tosijs-styled-editor 0.4.4 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,206 @@ 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
+
+- **`SECURITY.md`**, with the one thing it needs to say: a sanitizer bypass
+  belongs to [`tosijs-kilpi`](https://github.com/tonioloewald/kilpi/issues),
+  because that is where the code lives. The README's security section now points
+  at kilpi's policy as authoritative rather than restating it — a copy of a
+  policy drifts from the policy, which is the same failure the extraction
+  removed from the code.
+- **`NOTICE`**, for the three Apache-2.0 works the drop-in `dist/index.js`
+  bundles.
+
+### Changed
+
+- **Sanitization moved to [`tosijs-kilpi`](https://github.com/tonioloewald/kilpi)**,
+  the same code extracted as a standalone library so it is not maintained in two
+  places. No API change: `sanitizeInPlace` and `isSafeNavigationUrl` are still
+  exported from this package, `editor.sanitize` still works the same way, and
+  behaviour is identical.
+
+  The reason it matters is not tidiness. When the sanitizer briefly existed
+  twice, a URL-normalization fix reached one copy and not the other — recorded
+  as M1 in the 0.4.4 review. Across two repositories that drift would not even
+  appear in a diff. kilpi carries DOMPurify's published 223-fixture corpus as a
+  hard publish gate, which this package could not run on its own.
+
+  `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
+  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
@@ -31,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
@@ -77,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/NOTICE

@@ -0,0 +1,16 @@
+tosijs-styled-editor
+Copyright 2026 Tonio Loewald
+
+The drop-in build (dist/index.js) bundles the following Apache-2.0 works:
+
+  tosijs          — Copyright 2026 Tonio Loewald
+  tosijs-ui       — Copyright 2026 Tonio Loewald
+  tosijs-kilpi    — Copyright 2026 Tonio Loewald
+                    https://github.com/tonioloewald/kilpi
+
+dist/module.js leaves all three external and bundles none of them.
+
+tosijs-kilpi's verification corpus is vendored from DOMPurify
+(Copyright (c) 2015 Mario Heiderich, MPL-2.0 OR Apache-2.0). That corpus is a
+test fixture in kilpi's repository and is not distributed in kilpi's package or
+in this one, so no DOMPurify material is redistributed here.

package/README.md

@@ -63,7 +63,13 @@ Live site and docs: <https://editor.tosijs.net>
 npm install tosijs-styled-editor
 ```
 
-Peer dependencies: `tosijs`, `tosijs-ui`
+**Peer dependencies** (you install these): `tosijs`, `tosijs-ui`
+
+**Runtime dependency** (installed automatically):
+[`tosijs-kilpi`](https://github.com/tonioloewald/kilpi) — the sanitizer applied
+to pasted and dropped content. It has no dependencies of its own and is about
+0.8 kB gzipped. The drop-in `dist/index.js` build bundles it; the ESM build
+leaves it external so you get one copy if you also depend on it directly.
 
 ## Usage
 
@@ -121,32 +127,39 @@ The caret is an `<input>` element, so mobile browsers show their keyboard automa
 
 ## Security: what is sanitized, and what is not
 
-Replacing `contentEditable` also means replacing the sanitization the browser
-was doing on your behalf. As of 0.4.4:
+Replacing `contentEditable` also means replacing the sanitization the browser was
+doing on your behalf.
 
 **Sanitized** — content arriving from outside the document, which is the path an
-attacker controls:
-
-- **paste** and **drop** (both go through one shared choke point)
-- inline event handlers (`onerror`, `onload`, …) are removed
-- `script`, `iframe`, `object`, `embed`, `link`, `meta`, `base`, `style`,
-  `form` and the SVG animation elements are removed — in **any** namespace, so
-  `<svg><script>` and `<svg><style>` are caught too
-- `href`/`src`/`xlink:href` are scheme-checked: `http(s)`, `mailto`, `tel` and
-  relative URLs are kept, `javascript:` is dropped, and `data:` is allowed only
-  for raster images (never for a link, never `data:image/svg+xml`)
-- ordinary formatting and **unregistered custom elements survive** — plugin
-  markup is content, not a threat
+attacker controls: **paste** and **drop**, both through one shared choke point.
+
+The filtering itself is [`tosijs-kilpi`](https://github.com/tonioloewald/kilpi),
+and **[its SECURITY.md is the authoritative policy](https://github.com/tonioloewald/kilpi/blob/main/SECURITY.md)** —
+read it before relying on this. It is deliberately not restated here, because a
+copy of a policy drifts from the policy. The one thing worth repeating, because
+it is a trade rather than a detail:
+
+> kilpi is a **denylist** for elements and attributes and an **allowlist** for URL
+> schemes. That is why unknown elements survive — your plugin markup round-trips
+> intact — and it is also why an element that becomes dangerous in a future
+> browser, and that kilpi has never heard of, would pass through. If protection
+> from the not-yet-known matters more to you than preserving unknown markup, use
+> DOMPurify instead (see the hook below).
 
 **NOT sanitized** — content you supply, which is inside your own trust boundary:
 
 - `editor.value = html`
 - initial light-DOM content
 
+**If you are upgrading from 0.4.3 or earlier:** documents your users created
+before 0.4.4 may already contain a payload that was pasted in, and this component
+cannot fix that for you — setting `value` does not filter. Sanitize your stored
+corpus as part of the upgrade.
+
 **Using a different sanitizer.** `editor.sanitize` is the hook — it receives a
 detached element and mutates it:
 
-```js
+```javascript
 editor.sanitize = (root) => {
   DOMPurify.sanitize(root, {
     IN_PLACE: true,
@@ -161,14 +174,268 @@ editor.sanitize = (root) => {
 
 It takes an element rather than an HTML string on purpose: a string signature
 would force a serialize-and-reparse round trip, and that round trip is where
-mutation XSS lives. Note the `CUSTOM_ELEMENT_HANDLING` block — DOMPurify
-unwraps unknown custom elements by default, which would discard plugin markup
-the built-in sanitizer preserves.
+mutation XSS lives. Note the `CUSTOM_ELEMENT_HANDLING` block — DOMPurify unwraps
+unknown custom elements by default, which would discard plugin markup kilpi
+preserves.
+
+**Reporting a vulnerability.** If it is in the sanitizer, file it against
+[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.
 
-**If you are upgrading from 0.4.3 or earlier, read this:** documents your users
-created before 0.4.4 may already contain a payload that was pasted in, and the
-component cannot fix that for you — setting `value` does not filter. Sanitize
-your stored corpus as part of the upgrade.
+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
 
@@ -193,7 +460,18 @@ your stored corpus as part of the upgrade.
 | **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
 
@@ -432,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