Skip to content

add(editor)!: an edit is retain, insert and delete ops, and an undo step keeps their inverse - #18

Merged
adammharris merged 2 commits into
mainfrom
cc/youthful-hamilton-hid5lb
Oct 26, 2026
Merged

adammharris merged 2 commits into
mainfrom
cc/youthful-hamilton-hid5lb

Conversation

@adammharris

@adammharris adammharris commented Oct 23, 2026 •

Copy link
Copy Markdown
Member

twig's half of leaf's draft proposal An edit format shared by leaf and the core (diaryx-org/leaf#23), tasks 6 and 7: ops applied with one reparse, and history that can be turned off. leaf takes it in diaryx-org/leaf#25.

What changes

One primitive: apply(ops). Splicer::apply takes Retain, Insert and Delete, read from the start of the source, and applies them with one reparse as one undo step. A failed reparse changes nothing, as before.

A gesture records the fewest ops. Gestures still build a replacement for a span. replace_at_span now records the fewest ops that turn the span's bytes into that replacement (ast::ops::diff: Myers over characters, so no op ends inside a UTF-8 sequence, with one splice as the fallback past 512 edits). So Cmd-B over word is two inserts with the word retained, not the word deleted and written again. That matters to a CRDT merge: a concurrent edit inside the word survives. edit_range, here and in the C ABI, records the span as the caller asked it. last_change still reports the span asked.

Public Editor and Op:

  • Op — Retain(usize), Insert(String), Delete(usize)
  • Editor::apply(&[Op]) -> Result<Change, Error> — several places in one edit; a position past the end or inside a character is InvalidArgument
  • Editor::last_ops() -> Result<Vec<Op>, Error> — what the last edit, undo or redo did, in one canonical spelling (no zero-length op, no two ops of one kind side by side, an insert before a delete at one place, no retain at the end)
  • Editor::set_history(bool) / keeps_history()
  • Op::diff(old, new), Op::apply(text, ops) and Op::compose(first, then), for a host that keeps text and ops of its own; leaf uses all three

History is inverse ops. An undo step holds its edit's inverse ops and its caret blob, not a copy of the whole source (200 copies of the page before). Coalescing composes two steps' ops. With history off, edits record no steps, for a host such as leaf that keeps its own history over last_ops.

Breaking

  • ast::splicer::HistoryEntry has ops: Vec<ast::ops::Op> in place of source: Vec<u8>.
  • ast::splicer::Error has a new OutOfRange variant.

This is a major version, as decision 5 of the leaf proposal expects. The first commit uses !, so the changelog files it under Breaking. One Behavioural-change: trailer: an undo or redo whose restored text the parser refuses now leaves its step on the stack, where it used to drop it.

Not in this PR

  • The C ABI and @diaryx/twig get no apply or last_ops yet. leaf calls twig from Rust, and the proposal leaves leaf-ffi and leaf-wasm on whole-text hosts for now.

Testing

  • cargo test --workspace: everything that passed before still passes, unchanged.
  • New tests:
    • ast/ops_test.rs: seeded randomized checks that diff applies back to the new text on character boundaries and is minimal against an LCS, that invert restores the source, and that compose equals one edit then the other.
    • Splicer tests: minimal gesture ops, apply as one step, coalescing, history off, and a refused undo keeping its step.
    • Public API tests in tests/binding.rs, including Op::diff, Op::apply and Op::compose, and the new signatures pinned in tests/api_surface.rs.
  • cargo test -p twig-doc --no-default-features passes.

…tep keeps their inverse

The splicer's one primitive is now apply(ops): Retain, Insert and Delete read from the start of the source, applied with one reparse and recorded as one undo step. A gesture still builds its replacement for a span, but replace_at_span records the fewest ops that turn the span's bytes into it (ast::ops::diff, Myers over characters, so no op ends inside a UTF-8 sequence, and one splice past 512 edits). Bold over a word is two inserts and the word retained, not the word deleted and written again, which is what a merge needs to keep a concurrent edit inside the word. edit_range, here and in the C ABI, records the span as asked. last_change keeps reporting the span asked.

Editor gains Op, apply (several places in one edit; a position past the end or inside a character is InvalidArgument), last_ops (what the last edit, undo or redo did, in one canonical spelling), and set_history / keeps_history. An undo step holds the edit's inverse ops and its caret blob instead of a copy of the whole source; coalescing composes two steps' ops. History off records no steps, for a host such as leaf that keeps its own over last_ops.

These are twig's tasks in leaf's draft proposal "An edit format shared by leaf and the core" (diaryx-org/leaf#23).

BREAKING CHANGE: ast::splicer::HistoryEntry holds `ops: Vec<ast::ops::Op>` where it held `source: Vec<u8>`, and ast::splicer::Error has an OutOfRange variant.

Behavioural-change: An undo or redo whose restored text the parser refuses
  now leaves its step on the stack, so it can be tried again. It used to drop
  the step.
@adammharris
adammharris force-pushed the cc/youthful-hamilton-hid5lb branch from 6a76fae to d81b0e6 Compare October 24, 2026 18:40
…ps text and ops of its own

Op::diff gives the fewest ops between two texts, cut between characters, as the gestures record theirs. Op::apply applies ops to a text with the checks Editor::apply makes. Op::compose folds a run of edits into one list, in the canonical spelling last_ops reads back. leaf composes each edit's last_ops into what it hands its host, and brings an open page to a changed file with a diff.
@adammharris
adammharris merged commit 25b2291 into main Oct 26, 2026
5 checks passed
@adammharris
adammharris deleted the cc/youthful-hamilton-hid5lb branch October 30, 2026 01:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant