tosijs-styled-editor 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -5,7 +5,181 @@ All notable changes to this project are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.6.0] - 2026-10-07
+
+### Added
+
+- **Structural change tracking, BEHIND AN OFF-BY-DEFAULT FLAG**
+  (`editor.trackStructuralEdits`). Not reachable in 0.6.0, and not a supported
+  configuration for a document you care about — see the first note under
+  **Changed** for why. The rest of this entry describes what it does when
+  enabled, which is what 0.7.0 will ship.
+  Merging paragraphs is recorded the brute-force way — _these blocks out, these
+  blocks in_. A change mark wraps
+  content and a paragraph break is not content, so merging two paragraphs
+  strikes both originals (`data-block-delete`) and proposes a third
+  (`data-block-insert`); all three share one `data-change`, because one
+  keystroke is one change — the same rule paste already follows. Covers
+  Backspace at the start of a block, Delete at the end of one, and a selection
+  spanning blocks, where the proposed block reads as the deletion _would_ read
+  once accepted.
+  The cost is honest duplication: the text is present twice until someone
+  resolves it — and across a chain of merges, once per step, since each
+  superseded proposal is struck rather than removed. `value` carries all of it
+  until the chain is resolved.
+  **A merge is an ordinary edit.** It gets no veto and no special group: a
+  pending change in either paragraph, yours or anyone else's, neither blocks it
+  nor is absorbed into it. Every mark keeps its own id and stays independently
+  resolvable — privileging a structural edit over a textual one is not what
+  change tracking is for. The corollary is that contradictory choices are
+  possible and the editor honours them: reject an insertion, then accept a merge
+  whose proposal was taken from that paragraph, and those words are in the
+  result. Both are on screen when you choose; a review UI that wants to prevent
+  it should resolve a merge together with the edits inside it.
+  A chain of merges **strikes** each superseded proposal like any other block,
+  so an intermediate proposal stays in the document as
+  `<tosi-del data-change=… data-block-delete>` wrapping the earlier
+  `<tosi-ins data-block-insert>` — a shape a review UI has to render, and one
+  that stays resurrectable by rejecting the later merge. Dropping it instead
+  was tried and reversed: it was only safe while an earlier design absorbed the
+  earlier gesture into the later one, and without that it left a change id with
+  a delete half and no insert half, a state no gesture produces, from which
+  resolving per id lost text outright.
+  Lists and grid tables are the one refusal (`merge-blocks-not-mergeable`), and
+  it is about valid DOM rather than review policy: merging them produces loose
+  text as a direct child of a `<ul>`, or a mark that becomes a grid item and
+  shifts every `cellIndex`. That guard applies with tracking **off** as well.
+  `merge-blocks-backward`, `merge-blocks-forward` and `merge-blocks-selection`
+  no longer fire — those edits are recorded now.
+
+### Changed
+
+- **A cross-block merge is still refused while `trackChanges` is on, and the
+  refusal is no longer overridable.** The structural representation above is
+  complete and tested, but RESOLUTION has a confirmed defect: accepting a merge
+  whose outgoing block has nothing to strike — empty, holding only an empty
+  inline wrapper, or already fully struck — leaves that block standing and
+  anchors the replacement after it:
+
+  ```
+  <p>First</p><p></p><p>Third</p>  + Delete in the empty block
+    tracking off          → <p>First</p><p>Third</p>
+    tracking on, accepted → <p></p><p>First</p><p>Third</p>
+  ```
+
+  A flag about review deciding document structure is the one class this release
+  spent five correctness rounds eliminating, so the feature is gated off rather
+  than shipped reachable. `rejectChanges()` was correct throughout; accept was
+  the broken half. 0.7.0 finishes it.
+
+  0.5.x allowed `preventDefault()` on these refusals to perform the edit
+  untracked. That is gone, for the same reason it is gone for
+  `merge-blocks-not-mergeable`: an override that half-applies a gesture is the
+  shape three earlier remediation rounds kept producing.
+
+- **A mouse drag no longer snaps to word boundaries; a touch drag does.**
+  `stickySelection` is the knob — `'touch'` (the default), `'always'`, or
+  `'never'` — on both the component and `Selectable`, live and settable at any
+  time. **0.5.x snapped for every pointer**, so if you relied on that, set
+  `editor.stickySelection = 'always'`.
+  The reasoning is per-pointer: rounding a drag a mouse user aimed out to the
+  nearest words overrides a precise gesture, and double-click already means
+  "select this word". A fingertip has no precision to override. A hybrid device
+  (a Surface Pro) answers differently for its two pointers on the same document,
+  because the decision is per gesture. A stylus counts as a mouse: pen input
+  arrives as pointer plus compatibility mouse events, not touch events.
+- **Deleting across blocks now keeps the block at the START of the selection**,
+  with its type and its attributes. A selection delete used to keep the LAST
+  block while every other block merge kept the first, so dragging from a heading
+  into a paragraph and deleting left a `<p>` — and once tracked merges stopped
+  being refused, `trackChanges` silently decided which element type and which
+  `id` survived: the same gesture gave `<p class="a">Headgraph</p>` untracked and
+  `<h1 id="t">Headgraph</h1>` tracked. Same text, different wrapper, chosen by a
+  flag about review. One rule now, on every path.
+- **Word stickiness now applies to touch at all, including the affordance
+  handles.** It had been wired to the mouse only, which is backwards — and on a
+  phone the handles are how a selection is adjusted, so a touch user could not
+  reach it even after the two `Selectable` paths were fixed.
+
+### Removed
+
+- **Nothing was removed from the `structural-edit-refused` vocabulary.**
+  `merge-blocks-backward`, `merge-blocks-forward` and `merge-blocks-selection`
+  still fire with the default flags, so a 0.5.x listener keyed on them keeps
+  working. They stop firing only when `trackStructuralEdits` is enabled, which
+  0.6.0 does not do.
+- **`merge-blocks-not-mergeable` is no longer overridable.** 0.5.x documented
+  `preventDefault()` on `structural-edit-refused` as "performs the edit
+  untracked"; that stands for `remove-list-item`, `merge-list-items`,
+  `delete-table-row` and `delete-table-col`, and **not** for
+  `merge-blocks-not-mergeable`, which is about valid DOM rather than review
+  policy and fires with `trackChanges` off as well, where "untracked" means
+  nothing.
+  Before → after for a host doing
+  `if (e.detail.reason.startsWith('merge-blocks')) e.preventDefault()`: an
+  ordinary paragraph merge used to fire `merge-blocks-backward` and be performed
+  untracked; it now fires **no event** and is recorded as a tracked structural
+  change. Only a list or grid-table merge still refuses, and `preventDefault()`
+  on it has no effect — the document is left alone and the event is there to tell
+  the user why.
+
+### Fixed
+
+- **A partially struck block was skipped, and its text then appeared twice.**
+  The "already entirely deleted" guard tested element children, so
+  `<p>keep <tosi-del>cut</tosi-del></p>` looked fully deleted — a text node is
+  not an element child. Accepting a merge then left the surviving text in both
+  the original and the replacement.
+- **Rejecting a block-scoped insertion left an empty paragraph** where the
+  proposal had been, and took the caret with it — the mirror of a fix already
+  made on the accept side. The caret is now rescued out before the block goes.
+- **With `trackChanges: false` — the default — Backspace at the start of a block
+  and Delete at the end of one ATE A CHARACTER of the neighbouring block.**
+  `<p>one</p><p>two</p>` + Backspace at the start of `two` produced `"ontwo"`;
+  Delete at the end of `one` produced `"onewo"`. The character deletion ran and
+  then the blocks merged, where a gesture crossing a block boundary should delete
+  the paragraph break and nothing else. Present since at least 0.4.4 and
+  unaffected by tracking being off, so **every 0.5.x build loses a character on
+  every cross-paragraph Backspace.**
+- **A footnote reference duplicated in the document minted a second list item**
+  sharing one `data-footnote` and one `id`, carrying placeholder text, which
+  survived accept, reject and an explicit renumber and reached `value`. Reachable
+  in 0.5.x by pasting a reference. Footnote numbering is now per distinct note
+  rather than per reference, so repeated references to one note share its number
+  and its single list entry.
+- **Rejecting a chain of merges left one stray empty paragraph per intermediate
+  step**, in the document and in `value`.
+- **Delete in an empty block kept the block and pulled the NEXT block's content
+  into it**, leaving the caret at the start of what it had absorbed. An empty
+  block is residue — most often what a block-series delete just left behind — so
+  it now merges into the PREVIOUS block and the caret lands at its end, which is
+  what Backspace already did. The gesture's whole effect is that the block the
+  caret was in stops existing, so moving the caret forward made no sense. The
+  one exception is having no previous block, where the ordinary forward
+  behaviour stands.
+
+## [0.5.2] - 2026-09-26
+
+### Security
+
+- **0.5.1's fix was incomplete: `reviseWith()` could still emit live HTML.**
+  The guard that strips `<` and `>` from `changeAuthor` was applied at the four
+  write sites in the component and missed the fifth, `mark()` in
+  `src/changes.ts` — which is exactly what `reviseWith()` and the exported
+  `applyRevision()` go through. So the LLM-proofreading path, documented public
+  API, still broke a display name out of a raw-text element and put an
+  `<img onerror>` into `editor.value`. Reproduced end to end through the public
+  `value` setter and `reviseWith()`, with no host cooperation beyond wiring
+  `changeAuthor.name` to a profile name.
+
+  The guard now lives in `src/changes.ts` beside the only code that writes those
+  attributes, and every writer shares it. **A guard belongs at the layer every
+  writer shares, not at the addresses where the bug was first noticed** — which
+  is precisely the mistake 0.5.1 made.
+
+  **Upgrade from 0.5.1 as well as from 0.5.0** if you use `trackChanges` or
+  `reviseWith`. `SECURITY.md`'s statement in 0.5.1 was true of typing and
+  deletion and false of revision.
 
 ## [0.5.1] - 2026-09-26
 
@@ -48,7 +222,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### 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
+  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

package/README.md

@@ -355,6 +355,58 @@ editor.changeAuthor = { id: 'alex', name: 'Alex' }
 editor.trackChanges = true
 ```
 
+### Structural edits
+
+**Merging paragraphs is tracked too**, the brute-force way: _these blocks out,
+these blocks in_. A change mark wraps content and a paragraph break is not
+content, so merging two paragraphs strikes both originals and proposes a third:
+
+```xml
+<p><tosi-del data-change="c1" data-block-delete>Alpha.</tosi-del></p>
+<p><tosi-del data-change="c1" data-block-delete>Beta.</tosi-del></p>
+<p><tosi-ins data-change="c1" data-block-insert>Alpha. Beta.</tosi-ins></p>
+```
+
+All three share one `data-change`, because one keystroke is one change — the
+same rule paste already follows. Accepting removes the struck blocks and keeps
+the replacement; rejecting restores the originals and drops the proposal.
+Covers Backspace at the start of a block, Delete at the end of one, and a
+selection spanning blocks (where the proposal reads as the deletion _would_
+read once accepted).
+
+**The text is present twice until someone resolves it.** That is the cost of the
+brute-force representation, and it is worth knowing before you persist `value`
+on every keystroke: a document mid-merge serializes both the originals and the
+proposal.
+
+**`data-block-delete` / `data-block-insert` say a mark's scope is a whole
+block** rather than a run of text, and they are what tell `acceptChanges` to
+remove the struck block instead of leaving it empty. A downstream sanitizer that
+strips unknown `data-*` attributes turns a proposed merge back into three
+ordinary blocks.
+
+**A merge is an ordinary edit.** It has no veto and no special group: a pending
+change in either paragraph — yours or anyone's — does not block it, and it does
+not absorb that change or resolve it for you. Every mark keeps its own id and
+stays independently resolvable, because the point of tracking changes is that
+you see the old text and the new text and _you_ decide what stays.
+
+The corollary is that you can make contradictory choices, and the editor will do
+what you said. Reject an insertion inside a paragraph and then accept a merge
+whose proposed text was taken from that paragraph, and the inserted words are in
+the result — you rejected them in the old text and accepted a new paragraph that
+visibly contains them. Both are on screen when you choose. A review UI that
+wants to prevent this should resolve a merge and the edits inside it together;
+the editor does not decide that for you.
+
+Lists and grid tables are the one refusal (`merge-blocks-not-mergeable`), and it
+is about valid DOM rather than about review policy: merging them produces loose
+text as a direct child of a `<ul>`, or a mark that becomes a grid item and
+shifts every `cellIndex`. It is therefore **not overridable** — see
+`structural-edit-refused` below.
+
+### Everything else
+
 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
@@ -387,21 +439,13 @@ Two deletions behave specially, because the pedantic version would be noise:
 
 ### 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.
+- **lists and tables are still refused.** Backspace out of a list item, and
+  **Delete Row** / **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 beats silently restructuring with nothing in `changes` to show for
+  it. Text deletion inside a list item or a cell is unaffected and fully
+  tracked. (Paragraph merges ARE tracked — see Structural edits above.)
 
   A refusal fires a cancelable **`structural-edit-refused`** event carrying
   `detail.reason`, so the key is not simply dead — show a note, or call
@@ -414,11 +458,31 @@ Two deletions behave specially, because the pedantic version would be noise:
   ```
 
   `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.
+  `merge-blocks-selection`, `merge-blocks-not-mergeable`, `remove-list-item`,
+  `merge-list-items`, `delete-table-row`, `delete-table-col`.
+
+  The first three are a cross-block merge while `trackChanges` is on. They stop
+  firing if you enable `trackStructuralEdits`, which records those edits instead
+  — see the Component API table; it is off in 0.6.0 and not a supported
+  configuration yet.
+
+  **Calling `preventDefault()` performs the edit untracked** — if tracking could
+  have represented it, there would have been nothing to refuse — **except for
+  the four `merge-blocks-*` reasons, which are not overridable.** 0.5.x allowed
+  it; an override that half-applies a gesture is the shape several remediation
+  rounds kept producing, so the document is now left alone and the event is
+  there to tell the user why. That one is about
+  valid DOM rather than review policy, and it fires with `trackChanges` **off**
+  as well, where "perform it untracked" means nothing: merging a list or a grid
+  table produces loose text as a direct child of a `<ul>`, or a mark that
+  becomes a grid item and shifts every `cellIndex`. The refusal event still
+  fires, so you can tell the user why nothing happened; the document is left
+  alone. A cross-block selection delete that hits it still deletes the selected
+  TEXT, tracked, and simply does not merge the remnants — the words are
+  representable, the paragraph break is not.
+
+  A custom command refuses the same way, through `ctx.refuseStructural(reason)`,
+  and its result IS honoured; 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
@@ -460,18 +524,35 @@ part of the review.
 | **Shift+Click**  | Extends selection to click position |
 | **Double-click** | Selects word                        |
 | **Triple-click** | Selects block                       |
-| **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.
+| **Click-drag**   | Character precision; a FINGER snaps to words |
+
+**Word stickiness is per pointer, and since 0.6.0 a mouse drag does NOT snap.**
+A mouse user gets the platform's behaviour — character precision, and
+double-click when they want a word — because rounding a drag they aimed out to
+the nearest word boundaries overrides a precise gesture. A fingertip has no such
+precision to override, so a touch drag snaps, which is the only way a drag across
+a word ends up selecting that word.
+
+`editor.stickySelection` chooses: `'touch'` (the default), `'always'` — which
+restores the pre-0.6.0 behaviour for the mouse as well — or `'never'`. It is a
+live property, settable at any time, and it takes effect on the next drag.
+
+**When snapping does apply**, it 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.
+
+Whether the pointer has left the anchor word is asked **visually**, per line box,
+not by comparing logical offsets: inside a right-to-left run on a left-to-right
+line, x decreases as the logical index rises, so the two directions oppose and an
+offset comparison answers about the wrong one. `stickySelectionBounds(text,
+anchor, head, leftTheAnchorWord?)` is exported if you want the rule without the
+editor.
 
 ### Inside a table cell
 
@@ -596,6 +677,14 @@ inserting one in the middle renumbers the rest and reorders the list to match.
 Deleting a marker drops its entry on the next renumber, and deleting the last
 one removes the list. The stable identity is `data-footnote`, not the number.
 
+**Numbering is per NOTE, not per reference** (since 0.6.0): two references
+sharing a `data-footnote` are two pointers at one note, so they show the same
+number and share its single list entry. That matters because a reference can
+legitimately exist twice — copy one, or make a tracked edit that proposes a
+merged paragraph, and the same marker is in the document twice until the change
+is resolved. Numbering per reference minted a second list entry for the same
+note, sharing one `id`, carrying placeholder text.
+
 Inside the editor a link is text you are editing, so clicking it places the
 caret rather than navigating. Ctrl/Cmd-click follows it.
 
@@ -709,6 +798,8 @@ Custom widgets you add follow the same rules and get translated too.
 | `commands`  | `object`                                            | Command registry (extend to add custom commands)                      |
 | `widgets`   | `'none' \| 'minimal' \| 'default'`                  | Attribute — built-in toolbar preset                                   |
 | `localized` | `boolean`                                           | Attribute — translate the built-in widgets and show a language picker |
+| `stickySelection` | `'touch' \| 'always' \| 'never'`                 | When a drag snaps to word boundaries. Default `'touch'`: a finger snaps, a mouse keeps character precision. `'always'` restores pre-0.6.0 mouse behaviour |
+| `trackStructuralEdits` | `boolean` | Record cross-block merges as blocks-out/blocks-in instead of refusing them. **Off in 0.6.0 and not supported** — accepting such a merge resolves wrongly when an outgoing block has nothing to strike. 0.7.0 finishes it |
 
 ### Change tracking
 

package/SECURITY.md

@@ -38,7 +38,8 @@ and we will find a private channel.
 `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).
+seam (fully fixed in 0.5.2 — 0.5.0 is affected, and **0.5.1 is still affected
+through `reviseWith()`**, whose write site the first fix missed).
 
 They have to be stripped rather than escaped. HTML attribute serialization
 escapes `&` and `"` and **never `<`**, and `style`, `xmp`, `title`, `textarea`,

package/dist/changes.d.ts

@@ -36,6 +36,25 @@ export interface TrackedChange {
 }
 export declare const INS_TAG = "tosi-ins";
 export declare const DEL_TAG = "tosi-del";
+/**
+ * Marks whose scope is a whole BLOCK rather than a run of text.
+ *
+ * A structural edit is recorded the brute-force way — *these blocks out, these
+ * blocks in* — because a change mark wraps content and a paragraph break is not
+ * content. Merging two paragraphs therefore strikes both originals and proposes
+ * a third; splitting one strikes it and proposes two. Accepting removes the
+ * struck blocks entirely rather than leaving them empty, which is what these
+ * attributes tell `acceptChanges` to do, and the gesture shares one
+ * `data-change` because one keystroke is one change — the rule paste already
+ * follows, not a privilege granted to structural edits.
+ *
+ * The cost is honest duplication: the text appears twice until someone resolves
+ * it. The alternative — a sentinel marking the break itself — avoids that but
+ * means the pre-accept DOM does not represent the proposed document, so
+ * anything without the styling reads it wrongly.
+ */
+export declare const BLOCK_DELETE_ATTR = "data-block-delete";
+export declare const BLOCK_INSERT_ATTR = "data-block-insert";
 /**
  * A new change id.
  *
@@ -63,8 +82,56 @@ export declare class TosiIns extends HTMLElement {
 export declare class TosiDel extends HTMLElement {
 }
 export declare function defineChanges(): void;
+/**
+ * An attribute value that cannot break out of the element it is written into.
+ *
+ * HTML attribute serialization escapes `&` and `"` and **never `<`**. Inside a
+ * raw-text or RCDATA element — `style`, `xmp`, `title`, `textarea`, `noembed`,
+ * `noframes`, `plaintext` — the contents re-parse as text, so a `</style>` in
+ * an attribute value terminates the element and everything after it parses as
+ * markup, and `editor.value` then carries live HTML.
+ *
+ * This lives HERE, next to the only code that writes these attributes, because
+ * the first version of the fix lived in the component and covered four of the
+ * five write sites. The fifth was `mark()` below — on the public `reviseWith()`
+ * path — so 0.5.1 shipped as the fix for this and was still exploitable
+ * through it. A guard belongs at the layer every writer shares, not at the
+ * addresses where the bug was first noticed.
+ *
+ * Stripping, not escaping: no escape survives attribute serialization into a
+ * raw-text element.
+ */
+export declare function safeAttributeValue(value: string): string;
+/**
+ * Stamp a change mark with its attribution. **The only place that writes these
+ * attributes.**
+ *
+ * It exists because they were written at five addresses — four in the component
+ * (`openInsertion`, `trackDeletion`, `trackStructuralEdit`, `restampPastedChanges`)
+ * and `mark()` here — and the five drifted. `mark()` omitted `data-session`, so
+ * a `reviseWith()` mark attributed to the editor's own author carried no
+ * session, the "is this insertion MINE, from THIS session?" predicate could
+ * never answer true for it, and typing over your own revision nested a second
+ * change inside it instead of un-typing it.
+ *
+ * That is the shape this file already documents one screen above: the 0.5.1
+ * attribute-injection fix covered four of five write sites and shipped still
+ * exploitable through the fifth, and the conclusion recorded there was that a
+ * guard belongs at the layer every writer shares. The guard was moved and the
+ * five writers were not. (`reviews/0.6.0-dx-review.md`, M-3.)
+ *
+ * `id` is generated when not given, so a caller that needs one gesture to be
+ * one change passes the id it already minted.
+ */
+export declare function stampMark(el: Element, attribution: {
+    id?: string;
+    author: ChangeAuthor;
+    session: string;
+}): string;
 /** Every tracked change in a root, in document order. */
 export declare function changesIn(root: Element): TrackedChange[];
+/** Unwrap an element, leaving its children where it was. */
+export declare function unwrap(el: Element): void;
 /**
  * Accept a change: the insertion becomes ordinary text, the deletion goes.
  *
@@ -123,4 +190,4 @@ export declare function diffWords(before: string, after: string): DiffOp[];
  * 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;
+export declare function applyRevision(node: Text, revised: string, author: ChangeAuthor, session: string): number;

package/dist/commands.d.ts

@@ -74,13 +74,6 @@ export interface EditableContext {
 }
 /** Parse a "key value key value" argument list into a CSS object */
 export declare function makeCSS(args: string[]): Record<string, string> | null;
-/**
- * Renumber footnotes from DOCUMENT ORDER and reorder the list to match.
- *
- * Numbers are never stored — they are derived here — so inserting a footnote
- * in the middle renumbers everything after it, and deleting a marker drops its
- * entry. The stable identity is `data-footnote`, not the number.
- */
 export declare function renumberFootnotes(root: HTMLElement): void;
 /** Command definitions — extensible by adding new methods */
 export declare const commands: Record<string, Command>;