rapier-html 1.2.7 → 1.2.9

package/BUILD.json

@@ -1,10 +1,10 @@
 {
   "package": "rapier-html",
-  "version": "1.2.7",
+  "version": "1.2.9",
   "path": "dist/rapier.html",
-  "bytes": 5886529,
-  "sha256": "1fda3f30b4140f90c74cef0ea3fce795e9a9672ed7c37a4d393d42dfcf1de8c1",
-  "builtAt": "2026-10-16T19:38:46.299Z",
+  "bytes": 6025685,
+  "sha256": "8ea5bfa5b5cbeba8312b6df5305162224ed00e38cdcf5e780e89839f9410a91c",
+  "builtAt": "2026-10-17T20:46:16.744Z",
   "node": "v22.23.3",
   "canonical": true,
   "packing": "zopfli",
@@ -14,15 +14,15 @@
       "delivery": "built-in",
       "kind": "script",
       "element": "rapier-plugin-math",
-      "bytes": 691650,
-      "packedBytes": 438088,
+      "bytes": 733943,
+      "packedBytes": 449582,
       "files": [
         {
           "id": "rapier-math",
-          "name": "rapier-math-2.4.0.js",
-          "version": "2.4.0",
-          "bytes": 691650,
-          "sri": "C92x26+pBI4q9FoWypMhBb8CqSGaaPLw8dpYigWiYNsYQRTcPVrFyPVjrhc/Tnwh"
+          "name": "rapier-math-2.6.1.js",
+          "version": "2.6.1",
+          "bytes": 733943,
+          "sri": "c6Y4kudfuc16Hkmvfgr0MpdQcJs1jU4qbsKu2tUSduVuQdwLQ/38rR0GmQMatLsS"
         }
       ]
     },

package/README.md

@@ -2,7 +2,7 @@
 
 Turn Markdown into one offline HTML file that contains the full Rapier editor. It opens in any browser, on a phone or
 computer, with no account. People read, edit, draw and paint; agents hand over documents, show what changed and get
-the edited copy back. Start with `npx rapier-html@1.2.7 notes.md`.
+the edited copy back. Start with `npx rapier-html@1.2.9 notes.md`.
 
 Use it for a plan to rearrange, a guide to annotate, a draft to keep writing, or a revision to review. The file works
 without any hosted workspace.
@@ -12,19 +12,19 @@ without any hosted workspace.
   (Math, Mermaid); `--include draw` adds drawing and painting. Notes never travel.
 - `--return` adds a one-use Send back address from the agent door.
 - `--view draw` opens on Draw. `--compare original.md` opens the edit with its diff; `--by <name>` attributes it.
-- `wrap` and `unwrap` move a document into a page and back out, exactly.
+- `writePage(text, name)` makes the page in one call; `unwrap` gives the document back, exactly.
 
 Needs Node 22 or newer.
 
 ```sh
-npx -- rapier-html@1.2.7 notes.md                          # the editor, notes.md inside it, written beside the file
-npx -- rapier-html@1.2.7 notes.md --view draw              # opens on Draw: sketch and paint, the document behind it
-npx -- rapier-html@1.2.7 notes.md --include draw,math     # carries Draw and Math (default: what the document needs)
-npx -- rapier-html@1.2.7 notes.md --drawing sketch.svg     # carries a drawing, opened on Draw over the document
-npx -- rapier-html@1.2.7 revised.md --compare original.md # opens showing what changed
-npx -- rapier-html@1.2.7 notes.md --return "$RETURN_URL" --return-expires-at "$RETURN_EXPIRES_AT" # Send back
-npx -- rapier-html@1.2.7 notes.md out.html                 # a named output
-npm install rapier-html@1.2.7                              # as a library: wrap, unwrap
+npx -- rapier-html@1.2.9 notes.md                          # the editor, notes.md inside it, written beside the file
+npx -- rapier-html@1.2.9 notes.md --view draw              # opens on Draw: sketch and paint, the document behind it
+npx -- rapier-html@1.2.9 notes.md --include draw,math     # carries Draw and Math (default: what the document needs)
+npx -- rapier-html@1.2.9 notes.md --drawing sketch.svg     # carries a drawing, opened on Draw over the document
+npx -- rapier-html@1.2.9 revised.md --compare original.md # opens showing what changed
+npx -- rapier-html@1.2.9 notes.md --return "$RETURN_URL" --return-expires-at "$RETURN_EXPIRES_AT" # Send back
+npx -- rapier-html@1.2.9 notes.md out.html                 # a named output
+npm install rapier-html@1.2.9                              # as a library: writePage, unwrap
 ```
 
 The first `--` is for npm, so `--help` reaches the command. It never overwrites a file.
@@ -60,20 +60,21 @@ current document. After expiry or a refusal, Share offers Save instead; bring th
 Save this as `example.mjs` in the folder you installed into, then run `node example.mjs`:
 
 ```js
-import {readFile, writeFile} from 'node:fs/promises';
-import {wrap, unwrap} from 'rapier-html';
+import {writeFile} from 'node:fs/promises';
+import {writePage, unwrap} from 'rapier-html';
 
-const rapier = await readFile(new URL('./rapier.html', import.meta.resolve('rapier-html')), 'utf8');
 const words = '# Hello\r\n\r\nA note about </script> and C:\\Users\\me.\n';
-const page = wrap(rapier, words, 'hello.md', {view: 'draw'});   // opens on Draw, the note behind it
+const page = await writePage(words, 'hello.md', {view: 'draw'});  // opens on Draw, the note behind it
 console.log('words back exactly:', unwrap(page).text === words);
 await writeFile('hello.rapier.html', page, {flag: 'wx'});        // 'wx': never over an existing file
 ```
 
-- `wrap(rapierHtml, text, name, {view, drawing, drawingName, base, baseName, by, at, return: returnURL, return_expires_at})`
+- `writePage(text, name, {include, view, drawing, drawingName, base, baseName, by, at, return: returnURL, return_expires_at})`
+  carries the editor with what the document displays with (`include` names the parts: `drawing`, `math`, `mermaid`).
+- `wrap(rapierHtml, text, name, options)` does the same into a page you supply; `carry(rapierHtml, parts)` cuts one.
 - `unwrap(pageHtml)` returns the same fields, plus the validated `comparisonBase` record, with `null` for anything the
   page doesn't carry.
-- Also exported: `encodeCarried`, `decodeCarried` and `main`.
+- Also exported: `portableNeeds`, `encodeCarried`, `decodeCarried` and `main`. TypeScript declarations ship in `dist/page.d.mts`.
 
 ## How the page carries the document
 

package/dist/cli.mjs

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
 import {dirname} from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {main} from './page.mjs';

package/dist/ledger/authored-origin.mjs

@@ -1,10 +1,7 @@
 // SPDX-License-Identifier: MIT
-// Immutable authored origins shared by causal transport and inverse projection.
 import {_rapierTransformSplices, _rapierValidAuthored} from './journal-records.mjs';
 import {sha256} from './hash.mjs';
 
-// The frontier names only causal maxima. Linear history needs one predecessor,
-// and concurrent predecessors remain separate until an act observes both.
 function authoredFrontier(records, visit = null) {
   const dependencies = new Map(), frontier = new Set();
   for (const record of records) {
@@ -38,8 +35,6 @@ export function authoredPlacements(base, records) {
   return origins;
 }
 
-// Immutable authored placement stays on its own act. Basis IDs refer only to this
-// canonical history; no source snapshot or duplicate history is stored.
 export function authoredPlacement(source, splices, basis) {
   const origin = {basis: basis.slice().sort(), source: sha256(source), splices: splices.map(row => ({...row}))};
   if (!_rapierValidAuthored(origin) || _rapierTransformSplices(source, splices) === null)

package/dist/ledger/authorship.mjs

@@ -17,7 +17,6 @@ export function authorship(input) {
   const {ledger, text} = readLedger(input), references = _rapierHistoryEffects(ledger.records).references, removed = new Map();
   let runs = ledger.start.text ? [[0, ledger.start.text.length, 'system', 'unattributed', 0]] : [];
   for (const record of ledger.records) {
-    // An Undo or Redo puts back text the act it references removed: that text keeps the runs it had.
     const tx = record.transaction, gone = [], kept = (references?.get(tx.id) || []).flatMap(id => removed.get(id) || []);
     for (const row of record.splices) {
       const cut = row.pos + row.removed.length, delta = row.inserted.length - row.removed.length, before = [], after = [], inside = [];
@@ -49,7 +48,6 @@ export function readAuthorship(input, text) {
   if (cursor !== text.length) throw fault('authorship does not cover the text');
   return value;
 }
-// Authorship-only imports become an incomplete insertion ledger. There is no mutable blame database.
 export function ledgerFromAuthorship(input, text, documentAuthority, metadata) {
   const value = readAuthorship(input, text), records = [];
   let current = '', root = textRoot('');

package/dist/ledger/carried.mjs

@@ -10,7 +10,6 @@ export function decodeCarried(text) {
   return String(text).replace(/\\([\\/!r0])/g, (_, c) => c === '\\' ? '\\' : c === 'r' ? '\r' : c === '0' ? '\0' : c === '/' ? '</' : '<!');
 }
 export function validateParts(text, {ledger = null, authorship = null, metadata} = {}) {
-  // A file's leading BOM is metadata, as in the editor's source intake.
   const canonical = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
   const history = ledger === null ? null : readLedger(ledger, canonical, metadata).ledger;
   const runs = authorship === null ? null : readAuthorship(authorship, canonical);
@@ -22,7 +21,6 @@ export function writeParts(text, options) {
   return Object.entries(parts).filter(([, value]) => value !== null).map(([name, value]) =>
     '<script type="application/json" id="rapier-' + name + '">' + encodeCarried(JSON.stringify(value)) + '</script>\n').join('');
 }
-// Pure adapter: the browser supplies inert script elements, Node supplies parsed script records.
 export function readParts(text, elements) {
   const parts = {ledger: null, authorship: null};
   for (const element of elements) {
@@ -35,7 +33,6 @@ export function readParts(text, elements) {
   }
   return validateParts(text, parts);
 }
-// The wrapper only removes whole script elements. Strings inside other scripts are not carriers.
 export function takeParts(html, text) {
   const elements = [];
   const stripped = html.replace(/<script\b([^>]*)>([\s\S]*?)<\/script\s*>/gi, (whole, attrs, content) => {
@@ -50,7 +47,6 @@ export function takeParts(html, text) {
   return {html: stripped, ...readParts(text ?? '', elements)};
 }
 const OPEN = '\n\n<!-- rapier-carried/1\n', CLOSE = '\n-->\n';
-// One optional HTML comment at EOF; every other Markdown reader ignores it. Source is never rewritten.
 export function writeDocument(text, options) {
   const parts = validateParts(text, options);
   if (!parts.ledger && !parts.authorship) return text;
@@ -58,9 +54,12 @@ export function writeDocument(text, options) {
   return text + OPEN + json + CLOSE;
 }
 export function readDocument(source) {
+  if (!source.endsWith(CLOSE)) {
+    if (source.includes(OPEN)) throw fault('unfinished document metadata');
+    return {text: source, ledger: null, authorship: null};
+  }
   const at = source.lastIndexOf(OPEN);
   if (at < 0) return {text: source, ledger: null, authorship: null};
-  if (!source.endsWith(CLOSE)) throw fault('unfinished document metadata');
   let parts;
   try { parts = JSON.parse(source.slice(at + OPEN.length, -CLOSE.length)); }
   catch (_) { throw fault('invalid document metadata'); }
@@ -69,10 +68,8 @@ export function readDocument(source) {
   return {text, ...validateParts(text, parts)};
 }
 
-// One portable baseline. A digest is integrity evidence, not authentication of the named author.
 export function readBase(value) {
   if (!value || typeof value !== 'object') throw fault('comparison base SHA-256 differs from its text');
-  // Capture each caller-owned field once; admission and serialization use these same scalars.
   const {text, sha256: digest, revision, name, by, at, fonts} = value;
   if (typeof text !== 'string' || typeof digest !== 'string' || !/^[a-f0-9]{64}$/.test(digest) || sha256(text) !== digest)
     throw fault('comparison base SHA-256 differs from its text');

package/dist/ledger/data.mjs

@@ -1,7 +1,5 @@
 // SPDX-License-Identifier: MIT
-// Only plain JSON data enters the public format. Accessors and toJSON are never executed.
 export function fault(message) { return Object.assign(new Error('Ledger: ' + message), {code: 'ledger_invalid'}); }
-// A plain object's prototype is null or Object's own. Both lookups read descriptors, so no getter runs.
 export const plainPrototype = proto => proto === null || Object.getPrototypeOf(proto) === null &&
   Object.getOwnPropertyDescriptor(Object.getOwnPropertyDescriptor(proto, 'constructor')?.value || {}, 'name')?.value === 'Object';
 export function fields(value, depth, active, sorted = true) {
@@ -22,8 +20,6 @@ export function scalar(value) {
   if (typeof value === 'string') { if (/[\uD800-\uDFFF]/u.test(value)) throw fault('unpaired surrogate'); return true; }
   return typeof value === 'number' && Number.isFinite(value) && !Object.is(value, -0);
 }
-// A canonical copy does not need a serialized document and a second parsed document.
-// Sorted insertion preserves the previous plainData result, including numeric-key ordering.
 export function plainData(value) {
   if (typeof value === 'string') value = JSON.parse(value);
   const active = new Set();
@@ -37,8 +33,6 @@ export function plainData(value) {
   };
   return copy(value, 0);
 }
-// Each yielded string is bounded, even when one value contains the whole document.
-// JSON.stringify still owns escaping; scalar boundaries keep its spelling exact.
 function* quoted(text, whole = true) {
   yield '"';
   for (let at = 0; at < text.length;) {
@@ -73,8 +67,6 @@ export function canonicalJSON(value, depth = 0, active = new Set()) { return Arr
 export function exactKeys(value, keys) {
   return value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
 }
-// TextEncoder's exact byte count, without allocating an encoded copy. Whole-character
-// admission is performed in this same pass when the document owner requests it.
 export function utf8Length(text, whole = false) {
   let bytes = 0;
   for (let at = 0; at < text.length; at++) {

package/dist/ledger/diff/concerns.mjs

@@ -1,10 +1,8 @@
 // SPDX-License-Identifier: MIT
 import {letter, within, prev, next} from './tokens.mjs';
 
-// Separator-only pieces join the edit beside them; adjacent blocks each carry their own line break.
 export function separate(c, endA = c.before.length, endB = c.after.length) {
   const {before, after, safe, raw, spend} = c;
-  // A separator-only piece beside another edit joins it; equal separators at its ends stay unchanged.
   if (!raw) for (let i = c.result.length - 1; i > 0; i--) {
     const p = c.result[i - 1], q = c.result[i], side = p[0][0] === p[0][1] ? 1 : p[1][0] === p[1][1] ? 0 : -1, text = side ? after : before;
     if (side >= 0 && !/\S/.test(text.slice(...p[side]))) {
@@ -16,15 +14,12 @@ export function separate(c, endA = c.before.length, endB = c.after.length) {
     if (p[2] || q[2] || p[0][1] !== q[0][0] || p[1][1] !== q[1][0] ||
       ![p, q].some(r => !/\S/.test(before.slice(...r[0]) + after.slice(...r[1])))) continue;
     const x = [p[0][0], q[0][1]], y = [p[1][0], q[1][1]], keep = /\S/.test(before.slice(...q[0]) + after.slice(...q[1])) ? q : p;
-    // CRLF steps as one separator.
     for (let k; x[0] < x[1] && y[0] < y[1] && /\s/.test(before[x[1] - 1]) && before[x[1] - 1] === after[y[1] - 1] &&
       (k = before.endsWith('\r\n', x[1]) && after.endsWith('\r\n', y[1]) ? 2 : 1) <= Math.min(x[1] - x[0], y[1] - y[0]) &&
       safe(before, x[1] - k) && safe(after, y[1] - k);) { x[1] -= k; y[1] -= k; }
     keep[3][0] = x[0] === x[1] ? 2 : y[0] === y[1] ? 0 : 1;
     c.result.splice(i - 1, 2, [x, y, false, keep[3]]);
   }
-  // Repeated closing lines can attach to the wrong block. Rotate an exact insertion/deletion to the
-  // next blank-line boundary, without crossing another edit or splitting a character.
   if (!raw) for (let i = 0; i < c.result.length; i++) {
     const p = c.result[i], q = c.result[i + 1], side = p[0][0] === p[0][1] ? 1 : p[1][0] === p[1][1] ? 0 : -1;
     if (side < 0 || p[2]) continue;
@@ -38,8 +33,6 @@ export function separate(c, endA = c.before.length, endB = c.after.length) {
     if (shift && p.slice(0, 2).every((span, k) => safe(k ? after : before, span[0] + shift) && safe(k ? after : before, span[1] + shift)))
       for (const span of p.slice(0, 2)) { span[0] += shift; span[1] += shift; }
   }
-  // Adjacent blocks deleted or inserted together: when the first carries the line break before it, each carries
-  // its own, so any one restores apart from its neighbors.
   if (!raw) for (let i = 1; i < c.result.length; i++) {
     const p = c.result[i - 1], q = c.result[i], kind = p[3][0], side = kind ? 1 : 0, text = side ? after : before;
     if (kind % 2 || q[3][0] !== kind || p[2] || q[2] || p[side][1] !== q[side][0] || p[1 - side][0] !== q[1 - side][0]) continue;
@@ -48,20 +41,16 @@ export function separate(c, endA = c.before.length, endB = c.after.length) {
   }
 }
 
-// Refine the outer walk and each move's inner walk before assigning transport ownership.
 export function phrases(c) {
   const {before, after, raw, code} = c;
-  // Whole-word replacements separated only by spaces read and restore as one phrase, and one number stays one number.
   if (!raw) for (let i = c.result.length - 1; i > 0; i--) {
     const p = c.result[i - 1], q = c.result[i], gap = before.slice(p[0][1], q[0][0]);
     if (p[3][0] !== 1 || q[3][0] !== 1 || p[3][3] || q[3][3] || p[2] || q[2] || gap !== after.slice(p[1][1], q[1][0])) continue;
-    // A time, a date, a version or a decimal is one number.
     const number = /^(?:[.,:/-]\d*)+$/.test(gap) && /\d/.test(before[p[0][1] - 1] + after[p[1][1] - 1]) && /\d/.test(before[q[0][0]] + after[q[1][0]]);
     if (!number && (code || !/^[^\S\r\n]+$/.test(gap) || within(before, p[0][0]) || within(after, p[1][0]) ||
       within(before, q[0][1]) || within(after, q[1][1]))) continue;
     p[0][1] = q[0][1]; p[1][1] = q[1][1]; c.result.splice(i, 1);
   }
-  // Paired inline markers added or removed around unchanged text on one line are one concern.
   if (!raw && !code) for (let i = 1; i < c.result.length; i++) {
     const p = c.result[i - 1], q = c.result[i], kind = p[3][0], side = kind ? 1 : 0, text = side ? after : before;
     if (kind % 2 || kind !== q[3][0] || p[2] || q[2] || p[3][3] || q[3][3]) continue;
@@ -72,12 +61,10 @@ export function phrases(c) {
   }
 }
 
-// Readable concerns: phrases, numbers and paired markers, then the public edits and changes with context.
 export function concerns(c) {
   phrases(c);
   const {before, after, spend, safe, budget, raw, code, evidence, structures, initial, options, pa, pb} = c, lb = c.lb;
   const overlaps = (a, b) => a[0] < b[1] && a[1] > b[0];
-  // Siblings are ordered and disjoint: the parts holding a range are found by descent, outermost first.
   const containing = (parts, from, to, out = []) => {
     let lo = 0, hi = parts.length;
     while (lo < hi) { const mid = lo + hi >>> 1; if (parts[mid].end < to) lo = mid + 1; else hi = mid; }
@@ -85,7 +72,6 @@ export function concerns(c) {
       if (parts[k].end >= to) { out.push(parts[k]); containing(parts[k].children, from, to, out); }
     return out;
   };
-  // Edits are ordered and disjoint on the after side.
   const touched = (edits, range) => {
     let lo = 0, hi = edits.length;
     while (lo < hi) { const mid = lo + hi >>> 1; if (edits[mid].after[1] <= range[0]) lo = mid + 1; else hi = mid; }
@@ -116,7 +102,6 @@ export function concerns(c) {
     if (!raw && !group[3]) group[3] = [[...item[0]], [...item[1]]];
     if (!group[4]) {
       const context = group[3];
-      // Context completes a word only where an edge falls inside it.
       if (!raw) for (const [text, span] of [[before, context[0]], [after, context[1]]]) {
         const start = within(text, span[0]), end = within(text, span[1]);
         for (let c; start && letter(c = prev(text, span[0])) && spend() && safe(text, span[0] - c.length);) span[0] -= c.length;
@@ -152,7 +137,6 @@ export function concerns(c) {
     }
   }
   if (options._stats) Object.assign(options._stats, {work: Math.max(0, initial - Math.max(0, budget.left)), coarse: edits.some(c => c.coarse)});
-  // Concern tuples: kind, unit, name, context, edits, affects, breaks. Wording inside a move shares its context.
   const moves = new Map(changes.map((change, i) => change[0] === 3 && [change[3], i + 1]).filter(Boolean));
   return {edits, changes: changes.map(([kind, unit, name, context, owned, affects, breaks], i) => ({
     id: i + 1, kind: ['delete', 'replace', 'insert', 'move', 'rename', 'format'][kind], unit, edits: owned,

package/dist/ledger/diff/diff.mjs

@@ -1,6 +1,4 @@
 // SPDX-License-Identifier: MIT
-// One comparison: observe structure, walk the source into exact records, find moves and renames, then read them as
-// concerns. Each stage lives in its own module and shares one comparison context.
 import {observe} from './structure.mjs';
 import {boundaries, tokenizer, wordSegmenter} from './tokens.mjs';
 import {matcher} from './matching.mjs';
@@ -12,10 +10,8 @@ export function diff(before, after, options = {}) {
   if (before === after) return {edits: [], changes: []};
   const budget = options._budget || {left: Number.isFinite(options.limit) ? Math.max(0, options.limit) : 1e7};
   const spend = (n = 1) => (budget.left -= n) >= 0, safe = boundaries(), raw = options._unit;
-  // Internal records: [before range, after range, coarse, concern, transported fragments].
   const c = {before, after, options, budget, spend, safe, raw, chars: options.unit === 'char', initial: budget.left,
     segmenter: wordSegmenter(), result: [], code: options.as === 'code'};
-  // A Markdown fence holds code inside prose; only code outside fences makes the text code.
   if (options.as !== 'prose' && options.as !== 'code') c.code = /(?:^|\n)\s*(?:[{}]|(?:function|class|const|let|var|import|export|def|fn|func|package)\s+\w[^]{0,80}[({=:;])/
     .test((before.slice(0, 4096) + '\n' + after.slice(0, 4096)).replace(/^ {0,3}(`{3,}|~{3,})[^]*?(?:^ {0,3}\1[`~]*[ \t]*$|(?![^]))/gm, ''));
   let fallback;
@@ -33,7 +29,6 @@ export function diff(before, after, options = {}) {
       }
       Object.assign(c, {structures, pa, pb, la: structures[0].links, lb: structures[1].links, aliases});
     } catch {
-      // A failed reader preserves an explicit prose choice and reports why structure was not used.
       const failed = structures?.find(value => !value || value.invalid);
       fallback = {structure: failed?.threw ? 'threw' : budget.left < 0 ? 'limit' : 'invalid', ...(failed?.threw ? {error: failed.error} : {})};
       c.code = options.as !== 'prose';
@@ -48,8 +43,6 @@ export function diff(before, after, options = {}) {
     structures?.[0]?.parts, structures?.[1]?.parts);
   separate(c);
   moves(c);
-  // A heading edit can re-record its children. Compare both walks after transport is known: unchanged moved
-  // fragments cost nothing, so a smaller plain walk cannot discard a move just by aligning some of its lines.
   if (structures && !evidence && !raw && c.result.some(r => r[0][0] === r[0][1]) && c.result.some(r => r[1][0] === r[1][1]) &&
     budget.left >= c.initial - budget.left) {
     const size = (rows, transport = false) => rows.reduce((n, r) => n + (!transport && r[3][0] === 3 ? 0 : r[0][1] - r[0][0] + r[1][1] - r[1][0]), 0);

package/dist/ledger/diff/index.mjs

@@ -1,5 +1,4 @@
 // SPDX-License-Identifier: MIT
-// The package entry: compare two texts, or merge two edits of one base.
 import {diff} from './diff.mjs';
 import {merge} from './merge.mjs';
 export {diff, merge};

package/dist/ledger/diff/matching.mjs

@@ -1,12 +1,7 @@
 // SPDX-License-Identifier: MIT
-// Subsequence search over token keys, bounded by a shared work budget.
 export function matcher(spend, budget) {
-  // Unique anchors and fallback equal pairs share one bounded subsequence search. Repetitive text, where equal pairs
-  // are too many to visit, anchors on runs of tokens found once on each side, then on positions, then on a shortest
-  // script; only a range none of them can afford within the work limit stays coarse.
   function matches(a, b) {
     const found = new Array(a.length), pending = [[0, a.length, 0, b.length]];
-    // Patience chain over candidate pairs in a order; unique anchors split the range into searched gaps.
     const chain = (pairs, a0, a1, b0, b1, split, near) => {
       const tails = [];
       for (const [i, j] of pairs) {
@@ -29,7 +24,6 @@ export function matcher(spend, budget) {
       while (a0 < a1 && b0 < b1 && a[a0] === b[b0]) found[a0++] = b0++;
       while (a0 < a1 && b0 < b1 && a[a1 - 1] === b[b1 - 1]) found[--a1] = --b1;
       if (a0 === a1 || b0 === b1 || !spend(a1 - a0 + b1 - b0)) continue;
-      // Between anchored runs the change is usually small; a token found once by chance must not misalign it.
       if (near && shortest(a, b, a0, a1, b0, b1, found, 4 * (a1 - a0 + b1 - b0))) continue;
       const positions = new Map();
       for (let j = b0; j < b1; j++) {
@@ -45,12 +39,10 @@ export function matcher(spend, budget) {
         if (list[0] === 1 && list.length === 2) unique++;
       }
       if (!count) continue;
-      // With no unique anchors, equal-length repeated runs prefer their witnessed positions to an arbitrary LIS.
       if (!unique && a1 - a0 === b1 - b0) {
         const anchors = diagonal(a, b, a0, a1, b0, b1);
         if (anchors) { chain(anchors, a0, a1, b0, b1, true, true); continue; }
       }
-      // Charge the chain before building it: one that cannot be afforded falls through to cheaper anchors.
       const chained = unique || count, cost = chained * Math.ceil(Math.log2(chained + 2));
       if (cost <= budget.left) {
         const pairs = [];
@@ -63,7 +55,6 @@ export function matcher(spend, budget) {
         chain(pairs, a0, a1, b0, b1, unique > 0);
         continue;
       }
-      // Few changes make a shortest script cheap (about n + d²); try that first at a bounded cost.
       if (shortest(a, b, a0, a1, b0, b1, found, a1 - a0 + b1 - b0)) continue;
       const anchors = runs(a, b, a0, a1, b0, b1) || diagonal(a, b, a0, a1, b0, b1);
       if (anchors) chain(anchors, a0, a1, b0, b1, true, true);
@@ -72,14 +63,11 @@ export function matcher(spend, budget) {
     return found;
   }
 
-  // Runs of k tokens found once on each side anchor text whose single tokens all repeat. Window hashes are checked
-  // token by token, so a collision costs work, never correctness.
   function runs(a, b, a0, a1, b0, b1) {
     const ids = new Map(), id = key => ids.get(key) ?? (ids.set(key, ids.size), ids.size - 1);
     const left = Int32Array.from({length: a1 - a0}, (_, k) => id(a[a0 + k])), right = Int32Array.from({length: b1 - b0}, (_, k) => id(b[b0 + k]));
     for (const k of [16, 4, 64]) {
       if (k > Math.min(left.length, right.length) || !spend(2 * (left.length + right.length))) return;
-      // A prime modulus below 2^31 and a base below 2^21 keep every product exact in a double.
       const P = 2147483647, B = 1000003;
       let power = 1;
       for (let n = 1; n < k; n++) power = power * B % P;
@@ -101,7 +89,6 @@ export function matcher(spend, budget) {
         while (n < k && left[i + n] === right[j + n]) n++;
         if (n === k) pairs.push([a0 + i, b0 + j]);
       }
-      // Overlapping windows add nothing a gap's equal-run trim does not find; keep one per k tokens.
       pairs.sort((p, q) => p[0] - q[0]);
       const spaced = [];
       for (const pair of pairs) if (!spaced.length || pair[0] >= spaced.at(-1)[0] + k) spaced.push(pair);
@@ -109,16 +96,12 @@ export function matcher(spend, budget) {
     }
   }
 
-  // Repeated lines align by position: tokens equal on the start diagonal before a split and on the end diagonal after
-  // it, at the split that keeps the most. Used only when they cover at least half of the shorter side.
   function diagonal(a, b, a0, a1, b0, b1) {
     const n = a1 - a0, m = b1 - b0, shift = m - n, size = Math.min(n, m);
     if (!spend(2 * (n + m))) return;
-    // head[s]: equal pairs on the start diagonal among the first s tokens; tail[s]: on the end diagonal from s on.
     const head = new Int32Array(n + 1), tail = new Int32Array(n + 2);
     for (let i = 0; i < n; i++) head[i + 1] = head[i] + (i < m && a[a0 + i] === b[b0 + i]);
     for (let i = n - 1; i >= 0; i--) tail[i] = tail[i + 1] + (i + shift >= 0 && a[a0 + i] === b[b0 + i + shift]);
-    // A deletion (shift < 0) skips -shift tokens of a between the diagonals.
     let best = -1, split = 0;
     for (let s = 0; s <= n; s++) {
       const rest = Math.min(n, s + Math.max(0, -shift)), kept = head[s] + tail[rest];
@@ -131,8 +114,6 @@ export function matcher(spend, budget) {
     return pairs;
   }
 
-  // Myers' greedy search: O((N + M) D) steps; each frontier is kept for the backward pass. An attempt can stop at
-  // its own share of the work and report no script.
   function shortest(a, b, a0, a1, b0, b1, found, share = Infinity) {
     const n = a1 - a0, m = b1 - b0, v = new Int32Array(2 * (n + m) + 3), o = n + m + 1, trace = [];
     const step = (k = 1) => (share -= k) >= 0 && spend(k);

package/dist/ledger/diff/merge.mjs

@@ -13,7 +13,6 @@ export function merge(base, mine, theirs, options = {}) {
   const check = n => { if (!spend(n)) throw null; };
   const safe = options.structure && boundaries();
   const trees = options.structure && !options._edits
-    // A reader that throws gives no structure: the texts merge by source coordinates.
     ? [base, mine, base, theirs].map(text => observe(text, options.structure, spend, safe, false, true)).map(tree => tree?.threw ? null : tree) : [];
   const repeatedBase = trees.splice(2, 1)[0];
   const equal = (a, b) => a.length === b.length && a.every((item, i) => item === b[i]);
@@ -71,13 +70,11 @@ export function merge(base, mine, theirs, options = {}) {
               check(list.length); map.set(name, null);
               return list.map(part => content(part, side));
             });
-            // Each occurrence keeps its base text on one side, or the whole list does.
             if (!equal(values[0], values[1]) && !equal(values[0], values[2]) && !(values.every(list => list.length === values[0].length) &&
               values[0].every((text, k) => text === values[1][k] || text === values[2][k]))) throw null;
           }
           return maps;
         };
-        // A part renamed on one side keeps its reader key and aligns with its base part.
         const keyed = new Map(rows[0].filter(part => part.nameAt && part.key != null).map(part => [part.key, part]));
         const own = new Set(rows[0].map(part => part.id)), renamed = new Map();
         for (const side of [1, 2]) {
@@ -89,7 +86,6 @@ export function merge(base, mine, theirs, options = {}) {
         }
         const id = part => renamed.get(part) ?? part.id;
         const maps = index(id), orders = rows.map(list => list.map(id));
-        // A vanished or added copy of a repeated name keeps the order; only a different order of shared names is a reorder.
         const within = (a, b) => { let k = 0; for (const name of b) if (name === a[k]) k++; return k === a.length; };
         const reordered = [1, 2].map(side => {
           const a = orders[0].filter(name => maps[side].has(name)), b = orders[side].filter(name => maps[0].has(name));
@@ -128,7 +124,6 @@ export function merge(base, mine, theirs, options = {}) {
           if (child) children.set(name, child);
         }
         if (frame < 0 && !children.size) return;
-        // A plan is a tree of range triples; a string is an already-admitted gap.
         const plan = [];
         if (frame >= 0) {
           let at = nodes[frame].start;
@@ -160,7 +155,6 @@ export function merge(base, mine, theirs, options = {}) {
       if ([...removed[0].keys()].some(name => removed[1].has(name)) &&
         (added[0].size !== added[1].size || [...added[0].keys()].some(name => !added[1].has(name)))) throw null;
       if (plan) {
-        // Project original ranges once. Nested moves never rebuild aligned documents.
         const chunks = [], conflicts = [];
         let length = 0;
         function project(item) {
@@ -183,8 +177,6 @@ export function merge(base, mine, theirs, options = {}) {
   const changes = options._edits || [mine, theirs].map((text, side) => diff(base, text,
     {...budget, structure: trees[0] && options.structure, _observed: trees[0] ? [trees[0], trees[side + 1]] : undefined}).edits);
   if (trees.some(Boolean) && budget._budget.left < 0) return complete();
-  // An edit reaches over the words it touches; edits whose reaches overlap form one group, so letters
-  // joined from both branches never form a word neither wrote.
   const spans = words(wordSegmenter(), base);
   const word = at => {
     let low = 0, high = spans.length;
@@ -210,7 +202,6 @@ export function merge(base, mine, theirs, options = {}) {
       row[1] = edit[1];
       if (index === edits.length) break;
       const [a, b, t, side2, from] = edits[index], peer = sides[1 - side2][2];
-      // One branch's insertion and replacement at the same base position are one contiguous edit.
       if (!(a < end || a === start || from < reach || edits[index - 1][0] === a && edits[index - 1][3] === side2 || peer &&
         (a === end && peer[0] === end || a === b && peer[0] < end &&
           a - end < t.length && (peer[2] + base.slice(end, a)).endsWith(t)))) break;

package/dist/ledger/diff/moves.mjs

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: MIT
 import {separate, phrases} from './concerns.mjs';
 
-// Moves bind equal transported fragments at both ends; renames group a binding's sites.
 export function moves(c) {
   const {before, after, spend, safe, budget, raw, code, tokens, matches, walk, structures, pa, pb, la, aliases} = c;
   const overlaps = (a, b) => a[0] < b[1] && a[1] > b[0];
@@ -9,7 +8,6 @@ export function moves(c) {
     c[side][0] >= range[0] && c[side][1] <= range[1]);
   try { if (!raw && budget.left >= 0) {
     const check = n => { if (!spend(n)) throw null; };
-    // Split transported text at wording boundaries; positions and words own distinct edits.
     const deleted = new Map();
     const moveKey = (item, side, text, parts = []) => {
       const [from, to] = item[side];
@@ -28,7 +26,6 @@ export function moves(c) {
     for (const item of c.result) if (item[3][0] === 2 && !item[2]) {
       const value = after.slice(...item[1]), key = moveKey(item, 1, after, pb);
       let old = deleted.get(key), score = 0;
-      // Edited wording still travels: plain text, or a prose part of the same kind.
       const text = value.trim(), prose = !structures || /^(paragraph|item|task|row|quote|section)$/.test(item[3][1]);
       if (!old && prose && text.length >= 24) for (const candidate of deleted.values()) {
         check(1);
@@ -41,7 +38,6 @@ export function moves(c) {
         if (n * 5 > Math.max(prior.length, text.length) * 3 && n >= score) { old = n === score ? null : candidate; score = n; }
       }
       if (!old || old[4]) continue;
-      // Separators that only one end carries stay outside the transported text.
       const x = [...old[0]], y = [...item[1]];
       for (const end of [0, 1]) {
         const pattern = end ? /\s*$/ : /^\s*/, left = before.slice(...x).match(pattern)[0], right = after.slice(...y).match(pattern)[0];
@@ -52,7 +48,6 @@ export function moves(c) {
       }
       const outer = c.result; c.result = [];
       walk(...x, ...y, 1);
-      // A changed heading can occupy a whole line while its marker still anchors the move.
       if (c.result.length && (c.result[0][0][0] === x[0] || c.result[0][1][0] === y[0] ||
         c.result.at(-1)[0][1] === x[1] || c.result.at(-1)[1][1] === y[1])) {
         c.result = []; walk(...x, ...y, 2);
@@ -60,7 +55,6 @@ export function moves(c) {
       separate(c, x[1], y[1]);
       phrases(c);
       const inner = c.result; c.result = outer;
-      // Equal boundary fragments make the exact extent recoverable without display context.
       if (inner.length && (inner[0][0][0] === x[0] || inner[0][1][0] === y[0] ||
         inner.at(-1)[0][1] === x[1] || inner.at(-1)[1][1] === y[1] || inner.some(c => c[2]))) continue;
       const move = [3, item[3][2] ? item[3][1] : code ? 'line' : 'block', item[3][2], [x, y]];
@@ -69,7 +63,6 @@ export function moves(c) {
         if (a0 < a1) old[4].push([[a0, a1], [old[1][0], old[1][0]], false, group]);
         if (b0 < b1) item[4].push([[item[0][0], item[0][0]], [b0, b1], false, group]);
       };
-      // Unmatched outer separators travel with the move, so restoring it alone keeps blocks apart.
       fragment(old[0][0], x[0], 0, 0, move); fragment(0, 0, item[1][0], y[0], move);
       let a = x[0], b = y[0], wording;
       for (const edit of inner) {

package/dist/ledger/diff/structure.mjs

@@ -1,5 +1,4 @@
 // SPDX-License-Identifier: MIT
-// Capture only the reader contract before another observation can reuse its objects.
 export function observe(text, reader, spend, safe, references = true, lenient = false) {
   let value;
   try { value = reader(text); } catch (error) { return {invalid: true, threw: true, error}; }
@@ -30,7 +29,6 @@ export function observe(text, reader, spend, safe, references = true, lenient =
         if (!usable && !lenient) throw null;
         const part = {start, end: stop, kind: scalar(kind), name: scalar(name), key: scalar(key, true)};
         if (nameAt != null) part.nameAt = span(nameAt, start, stop);
-        // Discard unsafe evidence only after validating its complete subtree.
         if (retained && usable) { parts.push(part); flat.push(part); }
         part.children = children == null ? [] : copy(children, start, stop, depth + 1, retained && usable);
       }

package/dist/ledger/diff/tokens.mjs

@@ -1,12 +1,10 @@
 // SPDX-License-Identifier: MIT
-// Space-free scripts (Thai, Lao, Myanmar, Khmer, kana, Han) have no word separator; the platform dictionary finds words.
 export const SPACELESS = /[\u0e00-\u0eff\u1000-\u109f\u1780-\u17ff\u3040-\u30ff\u3400-\u9fff\uf900-\ufaff]/;
 export const words = (segmenter, text) => [...text.matchAll(/[\p{L}\p{N}\p{M}_]+/gu)].flatMap(word => SPACELESS.test(word[0])
   ? [...segmenter().segment(word[0])].map(s => [word.index + s.index, word.index + s.index + s.segment.length])
   : [[word.index, word.index + word[0].length]]);
 export const wordSegmenter = () => { let segmenter; return () => segmenter ||= new Intl.Segmenter('en', {granularity: 'word'}); };
 
-// Segment only requested non-ASCII boundaries; observations never share a global document cache.
 export function boundaries() {
   const segments = Object.create(null);
   let segmenter, last = [];
@@ -15,7 +13,6 @@ export function boundaries() {
     const a = text.charCodeAt(at - 1), b = text.charCodeAt(at);
     if ((a & 0xfc00) === 0xd800 && (b & 0xfc00) === 0xdc00 || a === 13 && b === 10) return false;
     if (a < 0x300 && b < 0x300) return true;
-    // Retreats probe one long cluster many times; answer inside the last cluster without the segmenter.
     if (last[0] === text && at > last[1] && at < last[2]) return false;
     const found = (segments[text] ||= (segmenter ||= new Intl.Segmenter('en', {granularity: 'grapheme'})).segment(text)).containing(at);
     last = [text, found.index, found.index + found.segment.length];
@@ -23,16 +20,13 @@ export function boundaries() {
   }
 }
 
-// Letters are code points: an astral letter is one letter, never two lone surrogates.
 const pair = (text, at) => (text.charCodeAt(at - 1) & 0xfc00) === 0xd800 && (text.charCodeAt(at) & 0xfc00) === 0xdc00;
 export const prev = (text, at) => text.slice(Math.max(0, at - 1 - pair(text, at - 1)), at), next = (text, at) => text.slice(at, at + 1 + pair(text, at + 1));
 export const letter = c => c && /[\p{L}\p{M}\p{N}_]/u.test(c), within = (text, at) => letter(prev(text, at)) && letter(next(text, at));
 
-// Tokens at a level: 0 parts, 1 lines, 2 words, spaces and marks, 3 characters.
 export function tokenizer(c) {
   const {spend, safe, segmenter, raw, aliases} = c;
   return function tokens(text, start, end, level, parts) {
-    // Each source boundary is stored once, alongside comparison keys and optional owners.
     const keys = [], at = [start], owners = [];
     const out = [keys, at, owners];
     const add = (a, b, part, value) => {