tosijs-styled-editor 0.4.5 → 0.5.1

package/CHANGELOG.md

@@ -7,6 +7,215 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-09-26
+
+### Security
+
+- **An author's display name could break out of a raw-text element and become
+  live HTML.** HTML attribute serialization escapes `&` and `"` but **never
+  `<`**, and `style`, `xmp`, `title`, `textarea`, `noembed`, `noframes` and
+  `plaintext` re-parse their contents as raw text — so a `changeAuthor.name`
+  containing `</style><img src=x onerror=…>`, written into a change mark inside
+  one of those elements, terminated the element and the remainder parsed as
+  markup. `editor.value` then carried a real `<img onerror>`.
+
+  Nothing external triggers the re-parse: `value` is also the undo stack, so a
+  single undo does it in the same session, and `internals.setFormValue` hands it
+  to every other reader. Reachable without host cooperation — `tosijs-kilpi`
+  drops `style`/`script`/`iframe` but keeps `xmp`/`textarea`/`title`/`noembed`/
+  `noframes`/`plaintext`, so a collaborator can paste one — and the host need
+  only have wired `changeAuthor.name` to a profile name, which is what that
+  field is for.
+
+  `<` and `>` are now stripped from `changeAuthor.id` and `.name` at every write
+  site. Stripping rather than escaping: no escape survives attribute
+  serialization into a raw-text element. Affects 0.5.0 only, and only with
+  `trackChanges` enabled.
+
+  **Still true, and not a vulnerability:** tracked edits inside a raw-text
+  element are a bad idea regardless — a caret marker left in a `<style>` block
+  round-trips into literal CSS text with no attacker involved. Keeping the
+  editor's own marks out of those elements is tracked in `TODO.md`. See
+  `SECURITY.md`.
+
+### Changed
+
+- The build no longer passes `--incremental` to `tsc`, so no
+  `dist/tsconfig.tsbuildinfo` is produced. An incremental build into a wiped
+  `dist/` can emit nothing at all the second time, which disqualifies a build
+  that has to reproduce for the publish workflow.
+
+### Added
+
+- `.github/workflows/publish.yml` — OIDC trusted publishing with npm staged
+  publishing. CI can only *stage*; the maintainer's 2FA approval on npmjs.com is
+  what publishes, and it works from a phone.
+
+## [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 +246,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 +275,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 +321,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/SECURITY.md

@@ -30,3 +30,31 @@ and we will find a private channel.
   content are inside your trust boundary and are not filtered.
 - **documents stored before 0.4.4**, which may already contain a pasted payload.
   Setting `value` does not filter, so sanitize your corpus as part of upgrading.
+
+## `changeAuthor` is written into the document
+
+`editor.changeAuthor` (`id` and `name`) is serialized verbatim into
+`data-author` / `data-author-name` on every change mark, so it reaches
+`editor.value`, the form value and every undo snapshot. It is host-supplied and
+inside your trust boundary — but "the host wired it to a profile name" is the
+ordinary case, so the editor does not trust it: `<` and `>` are stripped at the
+seam (fixed in 0.5.1; 0.5.0 is affected).
+
+They have to be stripped rather than escaped. HTML attribute serialization
+escapes `&` and `"` and **never `<`**, and `style`, `xmp`, `title`, `textarea`,
+`noembed`, `noframes` and `plaintext` re-parse their contents as raw text — so a
+`</style>` inside an attribute value written into one of those terminates the
+element and everything after it parses as markup. Nothing external triggers the
+re-parse: `value` is also the undo stack, so a single undo does it in the same
+session.
+
+Two consequences worth knowing:
+
+- **A display name is not a place to put markup**, and it comes back with its
+  angle brackets removed rather than escaped. There is no escape that survives
+  attribute serialization into a raw-text element.
+- **Tracked edits inside a raw-text element remain a bad idea.** With no
+  attacker at all, a caret marker left inside a `<style>` block round-trips into
+  literal CSS text. Keeping the editor's own marks out of those elements is
+  tracked as an open item; until it lands, do not point this editor at documents
+  whose `<style>`/`<xmp>` content is meant to survive editing.