tosijs-styled-editor 0.4.5 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,171 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-09-21
+
+### Added
+
+- **Drag selection is sticky at word boundaries.** The rule is one sentence:
+  snapping engages only once the drag LEAVES the word it began in — which in
+  practice means as soon as you cross a space, since offsets bracket the space
+  and there is no "crossed the gap but not yet arrived" position to wait in.
+  Inside that word you keep character precision, so pulling `fix` out of
+  `prefix` still works; cross into another word and both ends snap — including the anchor,
+  because a selection spanning words that starts mid-word is almost never what
+  was meant. Coming back inside the anchor word returns to precision.
+  Punctuation comes along only when the pointer reaches it: the segmenter
+  treats `,` as its own segment, so dragging past the comma in `hello,` takes
+  it and stopping inside `hello` does not. Whitespace is never dragged along,
+  so a selection cannot end in a trailing space you did not ask for.
+  Sticky only within a block, and only for plain drags — a double-click drag is
+  already word-granular, and a cross-block selection has larger units than
+  words.
+
+- **Tracked changes, and an LLM proofreading round-trip.** Insertions and
+  deletions are content (`<tosi-ins>` / `<tosi-del>` with author and timestamp),
+  not an operation log, so a tracked document still serializes and round-trips.
+  `reviseWith(fn, author)` sends each text node out as plain text, diffs the
+  response at word level, and applies the result as tracked changes;
+  `acceptChanges(id)` / `rejectChanges(id)` resolve them one at a time or all at
+  once.
+  The response is used as TEXT and never parsed as HTML, so a model returning
+  markup produces literal characters rather than elements — a stronger guarantee
+  than sanitizing, since there is no parse step to attack. Text already under
+  review is skipped, so a second pass cannot mark up the marks.
+  Change marks are styled in the core stylesheet on purpose: a `<tosi-del>`
+  without its strikethrough reads as the opposite of what the document means.
+- **Live edit tracking** (`editor.trackChanges = true`). Typing lands inside a
+  `<tosi-ins>`, and every deletion wraps in `<tosi-del>` — caret Backspace and
+  Delete, selection deletes, cut, inside lists, inside table cells. Deletions
+  that RESTRUCTURE rather than delete text are refused instead — block merges
+  (a cross-paragraph selection delete, Backspace at the start of a
+  paragraph, Delete at the end of one, Backspace out of a list item) and table Delete Row / Delete Column. A change mark wraps
+  content and structure is not content, so the honest answer until structural
+  tracking exists is to decline rather than restructure the document with
+  nothing in `changes` to show for it. A refusal fires a cancelable
+  `structural-edit-refused` event carrying `detail.reason`, so a host can
+  explain the dead keystroke or override it. A custom command deletes through
+  `ctx.removeNode(node)` and checks `ctx.tracksChanges()` before restructuring
+  — see EXTENSIBILITY.md.
+  One delete gesture is **one** change however many nodes and blocks it spans,
+  matching paste. The mechanism is one predicate —
+  is the caret already inside an insertion that is mine, this session? — so a
+  continuous run of typing is one change and there is no per-operation
+  bookkeeping. Session is part of the test, so reopening a document and typing
+  at the edge of your own earlier insertion opens a new change rather than
+  silently merging into one bearing the older timestamp. Un-typing your own
+  uncommitted text really removes it; re-deleting already-deleted text is a
+  no-op. Cut and paste are tracked as well — a paste is ONE change rather than
+  one per word, since a reviewer accepts or rejects the paste, not its
+  individual words.
+  Accepting or rejecting **evaporates the mark entirely**: no wrapper, no
+  `data-change`, no attribution residue, and the text is re-normalized. A
+  document does not accumulate its own history — undo and the version store
+  already do that, and a document carrying every resolved edit becomes
+  unreadable and awkward to share.
+
+- **Spell checking, which this editor otherwise has none of.** Browsers only
+  spell-check editing hosts (`textarea`, `input`, `contenteditable`), and nothing
+  here is one — so replacing `contentEditable` removed browser spell checking
+  entirely rather than leaving an unqueryable version of it. A contentEditable
+  editor has the opposite problem: checking it cannot query — no count, no list,
+  no way to block a submit on unresolved errors. This addresses both. Supply `editor.spellChecker` (a function from
+  words to the subset that is wrong) and the editor does tokenization
+  (`Intl.Segmenter`, so `don't` is one word and `l'objet` is two), marking,
+  and **form validity**: unresolved spelling sets `customError`, so a real form
+  submit is blocked rather than relying on the author to remember to check.
+  Resolution is `acceptWord(word, scope)` — `'document'` for a contract's
+  defined terms, `'dictionary'` for a firm's terms of art, exposed as
+  `documentWords` and `userDictionary`, with `handleWordAccepted(word, scope)`
+  to persist the latter. In a jargon-heavy domain the normal answer to an
+  unknown word is "that is a real word", not "I mistyped", so accepting has to
+  be as cheap as correcting. No dictionary ships — which words are real is a
+  localization question, and a hunspell dictionary is ~35x the size of this
+  editor.
+  Marks are view state: cleared on every check and stripped from `value`, so
+  they never reach the form value, an undo snapshot, or whatever the host
+  persists. Code, `kbd`, `samp`, `pre` and `spellcheck="false"` subtrees are
+  skipped.
+
+### Changed
+
+- **Footnote markers are saved as `<tosi-footnote>`, not `<sup>`.** The
+  superscript rule lives in the editor's shadow stylesheet, so in a downstream
+  renderer a marker will lay out as a full-size baseline digit unless you style
+  it. `.footnote-ref` is retained as the class, so **one rule repairs every
+  document**, including ones written before this change:
+  `tosi-footnote, .footnote-ref { vertical-align: super; font-size: 0.75em; }`
+- **`<tosi-del>` needs a strikethrough rule outside the editor too.** A tracked
+  document round-trips anywhere, which is the point — but an unstyled
+  `<tosi-del>` reads as ordinary prose, i.e. the _opposite_ of what the document
+  says. If you render `value` outside this component, ship
+  `tosi-del { text-decoration: line-through; opacity: 0.6; }` and
+  `tosi-ins { text-decoration: underline; }`. Beware a downstream sanitizer that
+  _unwraps_ unknown tags: that inverts a deletion silently. `acceptChanges()` is
+  how you hand a plain document to a consumer like that.
+- **`ignoreWord` is gone** — it was added and deprecated within this unreleased
+  span, so it never shipped and protects no callers. Use
+  `acceptWord(word, 'document')`.
+- **The build prints bundle sizes.** 0.5.0 measures 284.4 kB / **77.1 kB
+  gzipped** for the drop-in `dist/index.js`, and 143.8 kB / **29.2 kB gzipped**
+  for `dist/module.js` — three features for +3.4 kB gzipped over 0.4.5.
+
+### Fixed
+
+- **`editor.value` could throw and permanently destroy every spelling mark.**
+  Reading `value` unwraps the marks to keep them out of the serialization, then
+  restores them. Restoring ran in document order, so when one mark's anchor was
+  the _next_ mark — routine, since any `normalize()` collapses the empty text
+  node between them — `insertBefore` threw partway and every remaining mark
+  stayed unwrapped for good. `updateUndo()` reads `value` first thing on
+  keypress, so one keystroke in such a document also silently lost the undo
+  snapshot and the form value.
+- **Spell checking flagged correctly-spelled words, and the proofreader was sent
+  half-words.** Both walked text nodes directly, and the caret is a real element
+  that splits the node it sits in — so with the caret after `br` in
+  `the brown fox`, the checker was asked about `"br"` and reported it wrong,
+  blocking a form submit on a real word. Anything reading the document as
+  language now runs with the selection markers out of the text.
+- **Under `trackChanges`, most deletions were not tracked at all.** Only
+  selection deletes consulted the gate; caret Backspace and Delete — the
+  commonest gesture in the editor — along with list and table-cell deletions and
+  fully-selected blocks removed content outright, with no `<tosi-del>`, no entry
+  in `changes`, and nothing for `rejectChanges()` to restore. Every destructive
+  path is now tracked.
+- **A paste inside an existing insertion nested the marks**, so rejecting the
+  outer change silently discarded the inner one — including rejecting _another
+  author's_ change throwing away _your_ pasted text.
+- **Change ids could collide** when a deletion and its replacement were produced
+  in one keystroke (typing or pasting over a selection), so accepting the
+  deletion also accepted the replacement.
+- **Change marks arriving by paste are re-stamped.** `<tosi-ins>` is a safe
+  element, so pasted markup could carry any `data-author` and `data-time` it
+  liked and `editor.changes` reported it as fact — and a pasted `data-change`
+  could collide with a live one. Attribution is client-asserted document
+  content, not an authenticated identity; what is guaranteed is that a mark
+  records who put it in _this_ document.
+- **A spelling error could outlive the document it described.** Undo, redo,
+  `value =` and form reset all wipe the marks, and none of them touched form
+  validity — leaving the field invalid with a message naming an absent word,
+  anchored to a detached node.
+- **`reviseWith` no longer builds an unbounded diff table from a remote
+  response** (16k tokens measured at 1.7 s and +1.2 GB on the main thread), and
+  a proofreader that fails part-way no longer leaves the document half-revised
+  _outside_ the undo stack.
+- **`acceptChanges('')` / `rejectChanges('')` no longer resolve every change in
+  the document.** An empty string arrives from a `dataset` lookup that found
+  nothing; `undefined` still means all.
+- `src/spelling.ts` is exported from the package — `SpellChecker`,
+  `checkSpelling`, `wordsIn` and the rest were unnameable.
+
+- **Footnotes maintain themselves.** `renumberFootnotes` was always correct —
+  it removed orphans and derived numbers from document order — but only ever ran
+  at insertion time, so deleting a reference left its text orphaned in the list
+  and the survivors mis-numbered. `<tosi-footnote>` now calls it from
+  connected/disconnectedCallback, so a deletion, drag, paste or undo maintains
+  the list with no command run. Documents saved earlier, which used a plain
+  `<sup class="footnote-ref">`, still renumber correctly.
+
 ## [0.4.5] - 2026-09-17
 
 ### Added
@@ -37,12 +202,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `tosijs-kilpi` is a real dependency (this package's first — tosijs and
   tosijs-ui remain peers), at `^1.0.0`. kilpi went 1.0.0 for that reason alone:
   `^0.1.0` resolves to `>=0.1.0 <0.2.0`, so a 0.2.0 security fix would have
-  reached no installed consumer, and for a dependency that *is* the XSS defence
+  reached no installed consumer, and for a dependency that _is_ the XSS defence
   a range that blocks propagation is a defect in itself. It is external in `dist/module.js`, so a consumer who
   also depends on it directly gets one copy, and bundled into `dist/index.js`,
   which assumes no installs.
 
-
 ## [0.4.4] - 2026-09-16
 
 First release since 0.4.3 to reach npm. 0.4.4 and 0.4.5 were versioned in the
@@ -67,8 +231,8 @@ they are collected here rather than reconstructed inaccurately.
   Ordinary formatting and unregistered custom elements are preserved.
   `editor.sanitize` is a swappable hook if you would rather supply your own
   (DOMPurify drops in; see the README).
-  *This path was unreachable in 0.4.2–0.4.3 only because `insertionPoint()` was
-  broken; fixing that is what made it live again.*
+  _This path was unreachable in 0.4.2–0.4.3 only because `insertionPoint()` was
+  broken; fixing that is what made it live again._
 - **Ctrl/Cmd-clicking a link checks the URL scheme** and always opens a new
   context. `javascript:` executes in the embedding page's origin and `noopener`
   does not prevent it; `_self`/`_top` are resolved before `noopener` is
@@ -113,7 +277,6 @@ they are collected here rather than reconstructed inaccurately.
   subscription.
 - The drop-in `dist/index.js` build is minified: 83.5kB → 70.8kB gzipped.
 
-
 ### Added
 
 - **Drag and drop editing.** Selected text is a real draggable object, offering

package/README.md

@@ -182,6 +182,261 @@ preserves.
 [kilpi](https://github.com/tonioloewald/kilpi/issues) — that is where the code
 lives. Anything else, [this repository](https://github.com/tonioloewald/tosijs-editor/issues).
 
+## Spell checking
+
+This editor has **no browser spell checking at all**. Browsers only check editing
+hosts — `textarea`, `input`, `contenteditable` — and nothing here is one. That is
+a cost of replacing `contentEditable`, and worth knowing before you assume
+squiggles will appear on their own.
+
+In exchange you get the thing a `contentEditable` editor cannot have: an
+application that can _ask_.
+
+```javascript
+editor.spellChecker = (words) => new Set(words.filter((w) => !dictionary.has(w)))
+await editor.checkSpelling()
+
+editor.spellingErrors          // [{ word, element }, …] in document order
+editor.validity.customError    // true — a real form submit is blocked
+editor.clearSpelling()         // remove every mark, change no text
+```
+
+### Resolution is the workflow
+
+In a jargon-heavy domain — contracts, medicine, anything with terms of art — the
+usual answer to an unknown word is _"that is a real word"_, not _"I mistyped"_.
+So accepting has to be as cheap as correcting, and every flagged word has to end
+up resolved one way or the other.
+
+That is what the validity is for. **The field stays invalid until every flagged
+word is corrected or accepted**, so a real form submit is blocked rather than
+relying on anyone to remember to look.
+
+Accepting has two scopes, because they have different lifetimes:
+
+```javascript
+editor.acceptWord('indemnitor', 'document')    // this document only
+editor.acceptWord('lessor', 'dictionary')      // everywhere, for this user
+```
+
+- **`documentWords`** — a contract's defined terms and party names. Persist with
+  the document; it is part of the document's meaning, the same way a footnote is.
+- **`userDictionary`** — a firm's terms of art. Persist with the user, not the
+  document.
+
+Collapsing those into one list is what makes a spell checker unusable in these
+domains: either every later document inherits one contract's party names, or the
+user re-accepts the same terminology forever.
+
+The editor persists neither — it does not know where either store lives. It tells
+you what to write, and you decide where:
+
+```javascript
+editor.handleWordAccepted = (word, scope) => {
+  if (scope === 'dictionary') saveToUserDictionary(word)
+  else saveWithDocument(word)
+}
+```
+
+Load them back by assigning the sets before checking.
+
+Accepting jargon does not launder a real typo: with `indemnitor` and `lessor`
+accepted, `borwn` stays flagged and the field stays invalid.
+
+No dictionary ships with this component. Which words are real is a localization
+question with a different answer per document, and a hunspell dictionary is
+roughly forty times the size of the whole editor.
+
+### Wiring a real checker
+
+The checker is `(distinctWords) => the subset that is wrong`, sync or async, so
+any off-the-shelf engine fits behind it. With a hunspell-style library:
+
+```javascript
+import nspell from 'nspell'
+
+const spell = nspell(await loadAffix(), await loadDictionary())
+editor.spellChecker = (words) => new Set(words.filter((w) => !spell.correct(w)))
+```
+
+Or against a service, which is the case the batching exists for:
+
+```javascript
+editor.spellChecker = async (words) => {
+  const res = await fetch('/api/spell', {
+    method: 'POST',
+    body: JSON.stringify(words),
+  })
+  return new Set(await res.json())
+}
+```
+
+The editor asks about **distinct** words, once per check — so a 10,000-word
+document with a 2,000-word vocabulary is one call carrying 2,000 entries, not
+10,000 lookups and not one request per word.
+
+### What it does, and does not, do
+
+Tokenization uses `Intl.Segmenter` word segmentation, so `don't` is one word and
+`l'objet` is two — neither of which splitting on whitespace gives you. `code`,
+`kbd`, `samp`, `pre` and any `spellcheck="false"` subtree are skipped.
+
+Marks are **view state**: cleared on every check and stripped from `value`, so
+they never reach the form value, an undo snapshot, or whatever you persist. A
+document should not carry a record of which words some dictionary once disliked.
+
+Not implemented, and worth knowing before you build UI on this:
+
+- **no suggestions** — the checker reports _wrong_, not _did you mean_, and there
+  is no native right-click menu to inherit either
+- **no incremental check** — `checkSpelling()` re-walks the whole document, which
+  is right for a button and wrong for check-as-you-type on a long document
+- **persistence is yours** — the editor reports accepted words through
+  `handleWordAccepted` but stores nothing; reload the sets yourself
+
+## Tracked changes and LLM proofreading
+
+Insertions and deletions are **content** — `<tosi-ins>` and `<tosi-del>` elements
+carrying author and timestamp — not an operation log. A tracked document is still
+a document: it serializes, round-trips, and can be read by something that has
+never heard of this component.
+
+```javascript
+editor.changeAuthor = { id: 'alex', name: 'Alex' }
+
+await editor.reviseWith(async (text) => {
+  const res = await fetch('/api/proofread', { method: 'POST', body: text })
+  return (await res.json()).text
+}, { id: 'gpt-x', name: 'Proofreader' })
+
+editor.changes                    // [{ id, kind, author, authorName, time, text, element }]
+editor.acceptChanges(id)          // take this one
+editor.rejectChanges(id)          // keep the original
+editor.acceptChanges()            // all of them
+```
+
+Both readings stay in the document until someone decides. A reviewer can put the
+caret inside a proposed insertion and adjust it before accepting — the text
+inside a change mark is ordinary editable content.
+
+### What crosses the boundary
+
+**Out goes plain text**, one text node at a time. Formatting is deliberately not
+sent: a model asked to preserve markup will sometimes not, and a reviewer should
+be reviewing prose rather than diffing HTML. Marks _inside_ a block — a link, a
+bold run — survive because each text node is revised in place. What the model
+never sees, it cannot damage.
+
+**Back comes text, and only text.** The response is inserted as text nodes inside
+change marks and is never parsed as HTML, so a model that returns `<script>`
+produces those literal characters, visible for review. That is a stronger
+guarantee than sanitizing the response would be — there is no parse step to
+attack — which is why this path does not go through `editor.sanitize`.
+
+Text already under review is skipped, so a second pass cannot mark up the marks.
+
+### Why word-level
+
+The diff is word-level because the unit has to be something a reviewer can
+meaningfully accept or reject. A character diff turns `teh → the` into three
+separate changes, and a rewritten sentence into confetti.
+
+### Styling is correctness here
+
+`<tosi-ins>` and `<tosi-del>` are styled in the **core** stylesheet even though
+the behaviour is a plugin. An unloaded footnote plugin is benign — you see a
+stray marker. A `<tosi-del>` without its strikethrough renders deleted text as
+ordinary prose, which reads as the opposite of what the document means.
+
+### Tracking live edits
+
+```javascript
+editor.changeAuthor = { id: 'alex', name: 'Alex' }
+editor.trackChanges = true
+```
+
+Typing then lands inside a `<tosi-ins>`, and **every** deletion wraps in
+`<tosi-del>` instead of removing — caret Backspace and Delete, a selection
+delete, a cut, inside a list, inside a table cell. Nothing leaves the document
+without a mark and an entry in `changes`, which is the only property that makes
+`rejectChanges()` mean anything.
+
+The whole mechanism is **one predicate**, re-evaluated only when the insertion
+point might have moved: _is the caret already inside an insertion that is mine,
+from this session?_ If yes, typing appends to it. If no, a new one opens. There
+is no per-operation bookkeeping, because a continuous run of typing keeps the
+predicate true and it stops being true exactly when it should — a click
+elsewhere, an arrow key, a new line, a different author, a later session.
+
+**Session, not just author.** Reopening a document and typing at the edge of your
+own earlier tracked insertion opens a _new_ change. That edit happened at a
+different time and a reviewer may want to treat it separately; without this they
+would silently merge into one change bearing the older timestamp.
+
+**Cut and paste are tracked too.** A cut wraps in `<tosi-del>` like any other
+deletion. A paste is **one** change rather than one per word — you did not build
+it a keystroke at a time, and a reviewer wants to accept or reject the paste, not
+its individual words — so it gets its own mark even mid-typing-run. Pasted
+content is still sanitized before it is marked.
+
+Two deletions behave specially, because the pedantic version would be noise:
+
+- text inside **your own current insertion** is really removed — you are
+  un-typing something you just typed, not proposing to delete your own proposal
+- text already inside a `<tosi-del>` is left alone — it is deleted already
+
+### Not implemented
+
+- **no structural tracking.** A change mark wraps _content_, and structure is
+  not content. So while `trackChanges` is on, edits that restructure rather
+  than delete text are **refused** rather than performed:
+
+  - Backspace at the start of a paragraph, Delete at the end of one, and
+    Backspace out of a list item (each deletes a paragraph break)
+  - **Delete Row** and **Delete Column** on a table — a grid table has no row
+    elements, so row and column are derived from `cellIndex`, and a
+    `<tosi-del>` around a cell would itself become a grid item and shift every
+    later cell
+
+  Refusing is deliberate: the alternative is silently restructuring the
+  document with nothing in `changes` to show for it, which is the failure this
+  feature exists to prevent. Text deletion inside a block or a cell is
+  unaffected and fully tracked.
+
+  A refusal fires a cancelable **`structural-edit-refused`** event carrying
+  `detail.reason`, so the key is not simply dead — show a note, or call
+  `preventDefault()` on it to allow the edit:
+
+  ```javascript
+  editor.addEventListener('structural-edit-refused', (e) => {
+    toast(`Not tracked yet: ${e.detail.reason}. Turn off tracking to do this.`)
+  })
+  ```
+
+  `detail.reason` is one of `merge-blocks-backward`, `merge-blocks-forward`,
+  `merge-blocks-selection`, `remove-list-item`, `merge-list-items`,
+  `delete-table-row`, `delete-table-col`. **Calling `preventDefault()` performs the edit
+  untracked** — if tracking could have represented it, there would have been
+  nothing to refuse. A custom command refuses the same way, through
+  `ctx.refuseStructural(reason)`; see EXTENSIBILITY.md.
+
+- **no merge story.** Changes-as-content gets attribution, review and round-trip,
+  but not collaborative merge. That needs an operation log, which is a larger
+  decision — see
+  [EXTENSIBILITY.md](https://github.com/tonioloewald/tosijs-editor/blob/master/EXTENSIBILITY.md)
+  (a repo document; it is not in the npm tarball).
+
+### Resolved changes leave nothing behind
+
+Accepting or rejecting a change **evaporates the mark entirely** — no wrapper, no
+`data-change`, no attribution residue, and the text is re-normalized rather than
+left fragmented. A document does not accumulate its own history.
+
+That is deliberate. Undo, and whatever version store the document lives in,
+already record past states; a document that carries every resolved edit becomes
+unreadable, larger than its content, and awkward to share with anyone who was not
+part of the review.
+
 ## Keyboard Behavior
 
 ### General editing
@@ -205,7 +460,18 @@ lives. Anything else, [this repository](https://github.com/tonioloewald/tosijs-e
 | **Shift+Click**  | Extends selection to click position |
 | **Double-click** | Selects word                        |
 | **Triple-click** | Selects block                       |
-| **Click-drag**   | Selects character range             |
+| **Click-drag**   | Selects words, sticky at boundaries |
+
+**Click-drag is sticky at word boundaries.** Snapping engages only once the drag
+leaves the word it began in — in practice, as soon as you cross a space. Inside
+that first word you keep character precision, so pulling `fix` out of `prefix`
+still works; cross into another word and both ends snap, including the anchor,
+because a selection that spans words but starts mid-word is almost never what was
+meant. Punctuation comes along only when the pointer reaches it, and a selection
+never ends in a trailing space you did not ask for. Sticky within a block only —
+a double-click drag is already word-granular, and a cross-block selection has
+larger units than words. `stickySelectionBounds(text, anchor, head)` is exported
+if you want the rule without the editor.
 
 ### Inside a table cell
 
@@ -444,10 +710,43 @@ Custom widgets you add follow the same rules and get translated too.
 | `widgets`   | `'none' \| 'minimal' \| 'default'`                  | Attribute — built-in toolbar preset                                   |
 | `localized` | `boolean`                                           | Attribute — translate the built-in widgets and show a language picker |
 
-| Method           | Description              |
-| ---------------- | ------------------------ |
-| `doCommand(str)` | Execute a command string |
-| `focus()`        | Focus the caret          |
+### Change tracking
+
+| Member                        | Type                | Description                                                               |
+| ----------------------------- | ------------------- | ------------------------------------------------------------------------- |
+| `trackChanges`                | `boolean`           | Record live edits as tracked changes                                      |
+| `changeAuthor`                | `{ id, name? }`     | Who the next change is attributed to                                      |
+| `sessionId`                   | `string` (readonly) | Distinguishes this editing session from an earlier one by the same author |
+| `changes`                     | `TrackedChange[]`   | Every change in the document, in document order                           |
+| `acceptChanges(id?)`          | `void`              | Accept one change, or all of them with no argument                        |
+| `rejectChanges(id?)`          | `void`              | Reject one change, or all of them with no argument                        |
+| `reviseWith(revise, author?)` | `Promise<number>`   | Round-trip the prose through a proofreader; returns changes introduced    |
+
+### Spell checking
+
+| Member                             | Type                             | Description                                              |
+| ---------------------------------- | -------------------------------- | -------------------------------------------------------- |
+| `spellChecker`                     | `(words) => Set \| Promise<Set>` | Supply a checker; without one, nothing is checked        |
+| `checkSpelling()`                  | `Promise<SpellingError[]>`       | Check now and mark what comes back wrong                 |
+| `spellingErrors`                   | `SpellingError[]`                | The current errors — the query browsers refuse to answer |
+| `acceptWord(word, scope?)`         | `void`                           | `'document'` (default) or `'dictionary'`                 |
+| `documentWords` / `userDictionary` | `Set<string>`                    | The two accepted-word scopes, for persisting             |
+| `handleWordAccepted`               | `(word, scope) => void`          | Called when a word is accepted, so the host can persist  |
+| `clearSpelling()`                  | `void`                           | Drop every mark without changing the text                |
+
+### Other
+
+| Member           | Description                                                     |
+| ---------------- | --------------------------------------------------------------- |
+| `doCommand(str)` | Execute a command string                                        |
+| `focus()`        | Focus the caret                                                 |
+| `sanitize`       | `(root: Element) => void` applied to pasted and dropped content |
+
+Also exported from the package: `stickySelectionBounds`, `sanitizeInPlace` and
+`isSafeNavigationUrl` (re-exported from
+[tosijs-kilpi](https://www.npmjs.com/package/tosijs-kilpi)), `changeId`,
+`diffWords`, `acceptChange`/`rejectChange`, `checkSpelling`, `wordsIn`,
+`renumberFootnotes`, and the element classes behind the four content tags.
 
 ## License
 

package/dist/changes.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Tracked changes — insertions and deletions as CONTENT, with attribution.
+ *
+ * The alternative was an operation log alongside the undo snapshots.
+ * EXTENSIBILITY.md weighs both: an operation log is the only thing that gets you
+ * a merge story, and it is the most expensive decision in this codebase.
+ * Changes-as-content gets everything except merge, for a fraction of the work,
+ * and it fits the web-component substrate that footnotes and spelling already
+ * proved.
+ *
+ * WHAT THIS BUYS THAT AN OPERATION LOG DOES NOT: a tracked document is still a
+ * document. It serializes, round-trips, pastes into another editor, and can be
+ * read by something that has never heard of this component.
+ *
+ * ONE ASYMMETRY TO KNOW ABOUT. A footnote plugin that fails to load is benign —
+ * you see a stray marker. A `<tosi-del>` that fails to load renders deleted text
+ * as ordinary prose, which reads as the opposite of what the document means. So
+ * the strikethrough is load-bearing for CORRECTNESS, not decoration, and those
+ * styles belong in the core stylesheet even though the behaviour is a plugin.
+ */
+/** Who made a change, and when. */
+export interface ChangeAuthor {
+    /** Stable id — a user id, or a model name for an LLM pass. */
+    id: string;
+    /** What to show a reviewer. */
+    name?: string;
+}
+export interface TrackedChange {
+    id: string;
+    kind: 'insert' | 'delete';
+    author: string;
+    authorName: string;
+    time: string;
+    text: string;
+    element: HTMLElement;
+}
+export declare const INS_TAG = "tosi-ins";
+export declare const DEL_TAG = "tosi-del";
+/**
+ * A new change id.
+ *
+ * The sequence counter is not decoration. `Date.now()` alone collides whenever
+ * two marks are produced in one synchronous handler, which is the NORMAL case:
+ * typing over a selection and pasting over one both delete and then insert
+ * inside a single keydown. Measured at 29% collision without the counter — and
+ * a collision means `acceptChanges(deletionId)` silently also accepts the
+ * replacement insertion, so a reviewer cannot accept a deletion and reject
+ * what replaced it. Exported so there is ONE producer; there used to be three,
+ * and only this one had the guard.
+ */
+export declare const changeId: () => string;
+/**
+ * Insertion and deletion marks.
+ *
+ * Both are CONTAINERS — the text inside stays ordinary editable text, because a
+ * reviewer needs to be able to put the caret in a proposed sentence and adjust
+ * it before accepting. They hold no state beyond their attributes: what a change
+ * is, and who made it, is written in the document, not remembered by an
+ * instance that would not survive a round trip.
+ */
+export declare class TosiIns extends HTMLElement {
+}
+export declare class TosiDel extends HTMLElement {
+}
+export declare function defineChanges(): void;
+/** Every tracked change in a root, in document order. */
+export declare function changesIn(root: Element): TrackedChange[];
+/**
+ * Accept a change: the insertion becomes ordinary text, the deletion goes.
+ *
+ * Accept and reject are deliberately symmetric and deliberately *dumb* — each
+ * one resolves exactly one mark. Anything cleverer (accept all by this author,
+ * accept this paragraph) is a filter over `changesIn` plus a loop, which is the
+ * caller's policy rather than ours.
+ */
+export declare function acceptChange(el: Element): void;
+/** Reject a change: the insertion goes, the deletion becomes ordinary text. */
+export declare function rejectChange(el: Element): void;
+/**
+ * A word-level diff.
+ *
+ * Word-level, not character-level, because the unit has to be something a
+ * reviewer can meaningfully accept or reject. A character diff turns
+ * `teh -> the` into three separate changes and a rewritten sentence into
+ * confetti.
+ *
+ * Longest-common-subsequence over word tokens. Whitespace rides along with the
+ * word that follows it so that rejoining is lossless — the output of a diff with
+ * no changes is byte-identical to its input.
+ */
+export declare function tokenize(text: string): string[];
+export type DiffOp = {
+    op: 'same';
+    text: string;
+} | {
+    op: 'insert';
+    text: string;
+} | {
+    op: 'delete';
+    text: string;
+};
+/**
+ * Above this many tokens on either side, fall back to replace-the-whole-thing.
+ *
+ * The LCS table is (n+1)x(m+1) numbers, and one side of this diff is a REMOTE
+ * RESPONSE — whatever the proofreader returned. Measured: 8k tokens is 429 ms
+ * and +366 MB; 16k (a 78 kB text node) is 1.7 s and +1.2 GB, synchronously on
+ * the main thread. The asymmetric case is worse and cheaper to trigger: a
+ * 200-word paragraph against a 200k-word response is +226 MB PER TEXT NODE.
+ * 4000 tokens is a very long paragraph and costs about 128 MB worst case.
+ *
+ * Past the cap the change is still correct, just coarser: one deletion and one
+ * insertion rather than a word-level diff. Degrading the review experience
+ * beats freezing the tab.
+ */
+export declare const MAX_DIFF_TOKENS = 4000;
+export declare function diffWords(before: string, after: string): DiffOp[];
+/**
+ * Replace a text node's contents with the tracked result of revising it.
+ *
+ * Returns the number of changes introduced. Zero means the revision was
+ * identical and the document was not touched at all — which matters, because a
+ * proofreading pass that changes nothing should not dirty the document or
+ * produce an undo step.
+ */
+export declare function applyRevision(node: Text, revised: string, author: ChangeAuthor): number;