rapier-html 1.2.8 → 1.2.9

package/dist/ledger/diff/walk.mjs

@@ -1,17 +1,13 @@
 // SPDX-License-Identifier: MIT
 import {words, letter, within, prev, next} from './tokens.mjs';
 
-// Exact source records for a range: lines, then words, then characters, or structural parts when supplied.
 export function walker(c) {
   const {before, after, spend, safe, budget, raw, chars, code, segmenter, tokens, matches} = c;
   function record(a0, a1, b0, b1, unit, part, coarse = false) {
     if (a1 - a0 === b1 - b0 && before.slice(a0, a1) === after.slice(b0, b1)) return;
-    // Internal records: before, after, coarse, concern, transported fragments.
     c.result.push([[a0, a1], [b0, b1], coarse, [a0 === a1 ? 2 : b0 === b1 ? 0 : 1, part?.kind || unit, part?.name]]);
   }
 
-  // A line deletion or insertion holding whole named parts and only blank text besides is one record per part,
-  // cut at line starts, so each keeps its own name (and its callers' breaks).
   function name(from, ownersA, ownersB) {
     for (let r = from; r < c.result.length; r++) {
       const [[a0, a1], [b0, b1]] = c.result[r], side = a0 === a1 ? 1 : b0 === b1 ? 0 : -1;
@@ -34,7 +30,6 @@ export function walker(c) {
     }
   }
 
-  // A search step scans at most one fixed-size source chunk.
   function common(a, b, end, step) {
     let n = 0;
     while (n < end && spend()) {
@@ -95,7 +90,6 @@ export function walker(c) {
           }
         } else if (level < 2 && raw !== 'line') lines(x.slice(ai, i + 1), y.slice(bi, j + 1), context);
         else if (level === 2 && chars && !raw && i - ai <= 1 && j - bi <= 1 && x1 - x0 + y1 - y0 < 100) {
-          // A changed token is replaced whole unless the caller asks for the characters inside it.
           walk(x0, x1, y0, y1, 3, null, null, context);
         } else record(x0, x1, y0, y1, unit, context);
       }
@@ -108,12 +102,9 @@ export function walker(c) {
     }
   }
 
-  // Unequal lines pair in order by shared words. A line sharing under a quarter of its words with every candidate is
-  // replaced whole: an inserted line never borrows a neighbor's words, and a rewrite never reads as stray fragments.
   function lines(x, y, context) {
     const n = x.length - 1, m = y.length - 1;
     if (n * m > 4096 || !spend(n * m + x[n] - x[0] + y[m] - y[0])) return row(x[0], x[n], y[0], y[m], context);
-    // A renamed name's sites count as shared words.
     if (!c.renames) {
       c.renames = [[], []];
       for (const [p, old] of c.aliases || []) if (before.slice(...old.nameAt) !== after.slice(...p.nameAt)) {
@@ -141,7 +132,6 @@ export function walker(c) {
     }
     let k = 0, l = 0;
     for (const [p, q] of [...pairs, [n, m]]) {
-      // A merge compares one line against one line by character, whatever they share.
       if (raw === 'char' && p - k === 1 && q - l === 1) row(x[k], x[p], y[l], y[q], context);
       else if (k < p || l < q) record(x[k], x[p], y[l], y[q], 'line', context);
       if (p < n) row(x[p], x[p + 1], y[q], y[q + 1], context);
@@ -149,7 +139,6 @@ export function walker(c) {
     }
   }
 
-  // A table row with the same number of cells on both sides changes cell by cell; a character diff stays in its line.
   function row(a0, a1, b0, b1, context) {
     if (raw === 'char') return walk(a0, a1, b0, b1, 3, null, null, context);
     const cells = (text, a, b) => /^[ \t]*\|/.test(text.slice(a, b)) && [...text.slice(a, b).matchAll(/(?<!\\)\|/g)].map(m => a + m.index);
@@ -158,7 +147,6 @@ export function walker(c) {
     for (let k = 0; k <= p.length; k++) walk(k ? p[k - 1] + 1 : a0, p[k] ?? a1, k ? q[k - 1] + 1 : b0, q[k] ?? b1, 2, null, null, context);
   }
 
-  // Surviving source pieces keep the occurrence witnessed by the host.
   function operations(rows) {
     if (!Array.isArray(rows)) return null;
     const pieces = [[0, before.length]];

package/dist/ledger/format.mjs

@@ -8,8 +8,6 @@ import {canonicalJSON, canonicalParts, plainData, documentText, utf8Length, exac
 export {textRoot, rootAfter};
 const digest = value => sha256Parts(canonicalParts(value));
 const rootShape = value => typeof value === 'string' && /^\d+:[a-z0-9]+:[a-z0-9]+$/.test(value);
-// Structural/history admission is shared by the reader and the producer. The producer
-// proves source replay by reversing exact admitted splices; it need not replay its output.
 function* checkedRecords(ledger, prepared) {
   if (!prepared.ok || ledger.records.length !== prepared.records.length) throw fault('record chain differs');
   let root = ledger.start.root, revision = ledger.start.revision;
@@ -27,16 +25,9 @@ function* checkedRecords(ledger, prepared) {
   }
   if (ledger.head.revision !== revision || ledger.head.root !== root) throw fault('history does not describe this document');
 }
-// A ledger object read again is proved once: a boot reads one stored history through several records. The proof holds only
-// while that object still carries the exact proved data (its start text compared whole, the rest as canonical JSON), so a
-// changed byte is proved again, and refused. The proof lives as long as the object does.
 const proofs = new WeakMap();
 function readLedgerState(input, expectedText, expectedMetadata) {
   const ledger = plainData(input);
-  // The identifier rapier-ledger/2 is unchanged and is not backward compatible. This reader
-  // admits an empty physical splice whose authored rows name the same replacement. A reader
-  // from before that rule rejects the chain. Mixed-version sync throws notes_history_unavailable
-  // and leaves the older store unchanged; that refusal is not a held or caughtUp result.
   if (!exactKeys(ledger, ['format','documentAuthority','start','records','head','complete','sha256']) || ledger.format !== 'rapier-ledger/2' ||
       typeof ledger.documentAuthority !== 'string' || !ledger.documentAuthority || ledger.documentAuthority.length > 256 ||
       typeof ledger.complete !== 'boolean' || !Array.isArray(ledger.records) ||
@@ -81,7 +72,6 @@ function proveLedger(ledger) {
   if (ledger.head.revision !== revision || ledger.head.root !== root || ledger.head.sha256 !== sha256(text)) throw fault('history does not describe this document');
   return {text, metadata, root, revision, prepared, source};
 }
-// A stored copy may hold the head text alone. Its start is that text with every record reversed; readLedger proves it.
 export function ledgerWithStart(input, text) {
   let source = new HistorySource(documentText(text));
   for (let i = input.records.length - 1; i >= 0; i--) {
@@ -129,11 +119,8 @@ function* sourceFacts(text) {
 }
 function* produceLedger({text, metadata, records, documentAuthority, revision, root, complete = false, earlier = records} = {}) {
   if (!_rapierValidMetadata(metadata)) throw fault('document metadata required');
-  // Metadata has two admitted scalar fields. Keep its insertion order in the
-  // emitted envelope while capturing it before the first cooperative boundary.
   metadata = {...metadata};
   if (!Array.isArray(records) || !Array.isArray(earlier)) throw fault('records required');
-  // Inspect before touching properties: exporting must not call accessors on an alleged record.
   const prepared = _rapierPrepareHistoryRecords(records, earlier);
   if (!prepared.ok) throw fault('navigation target was not retained');
   const headFacts = yield* sourceFacts(text);
@@ -153,8 +140,6 @@ function* produceLedger({text, metadata, records, documentAuthority, revision, r
     startSource = startSource.apply(expanded[i].splices, true);
     startMetadata = _rapierTransformMetadata(startMetadata, expanded[i].metadata, true);
     if (startSource === null || !startMetadata) throw fault('history does not reverse from this document');
-    // Whole scalars and exact splice boundaries were just checked. Count the changed
-    // bytes, rather than re-encoding every reconstructed whole-document revision.
     for (const row of expanded[i].splices) bytes += utf8Length(row.removed) - utf8Length(row.inserted);
     if (bytes > 64 * 1024 * 1024) throw fault('document exceeds the editor text limit');
     yield;
@@ -174,8 +159,6 @@ function* produceLedger({text, metadata, records, documentAuthority, revision, r
   const payload = {format: 'rapier-ledger/2', documentAuthority,
     start: {text: startText, revision: startRevision, root: startRoot, sha256: startSHA, metadata: startMetadata},
     records: expanded, head: {revision, root, sha256: headSHA, metadata: {...metadata}}, complete: complete === true && startRevision === 0 && expanded.every((row, i) => !i || row.transaction.baseRevision === expanded[i - 1].transaction.revision)};
-  // Expanded rows are the exact canonical projection of this owned preparation.
-  // Keep its navigation/effect proof instead of admitting another copied graph.
   for (const _record of checkedRecords(payload, prepared)) yield;
   if (expanded.some(row => Object.hasOwn(row, 'authored'))) {
     try { authoredHistory(startText, expanded); } catch (_) { throw fault('authored origin differs'); }
@@ -191,7 +174,6 @@ function finish(producer) {
   return step.value;
 }
 export function exportLedger(input) { return finish(produceLedger(input)).ledger; }
-// Its returned facts were computed while admitting/hashing the exact head, never supplied.
 export async function prepareLedgerAsync(input, {yield: yieldWork, signal} = {}) {
   const producer = produceLedger(input);
   let step;
@@ -199,7 +181,6 @@ export async function prepareLedgerAsync(input, {yield: yieldWork, signal} = {})
     signal?.throwIfAborted();
     step = producer.next();
     if (!step.done && yieldWork) {
-      // The caller owns scheduling and its clock; ledger admission reads neither.
       const pending = yieldWork();
       if (pending) await pending;
     }
@@ -207,7 +188,6 @@ export async function prepareLedgerAsync(input, {yield: yieldWork, signal} = {})
   signal?.throwIfAborted();
   return step.value;
 }
-// Derived navigation, never a second history. A target older than start is intentionally unavailable.
 export function historyEnvelope(input, segmentIdentity = [], expectedText, expectedMetadata) {
   const {value: {ledger, text, metadata}, prepared, source} = readLedgerState(input, expectedText, expectedMetadata);
   const {byId, effects: {pictures}} = prepared;
@@ -235,8 +215,6 @@ export function historyEnvelope(input, segmentIdentity = [], expectedText, expec
   }
   if (ledger.complete) {
     if (ledger.records.length && !branch.length) throw fault('complete history lost its branch');
-    // Literal admitted splices are reversible. Proving the actual head back to
-    // the exact start also proves its forward active branch, without replaying it.
     if (traversed.length !== ledger.start.text.length || !traversed.matches(0, ledger.start.text) ||
         canonicalJSON(traversedMetadata) !== canonicalJSON(ledger.start.metadata)) throw fault('complete branch differs');
   }
@@ -246,8 +224,6 @@ export function historyEnvelope(input, segmentIdentity = [], expectedText, expec
     traversedMetadata = _rapierTransformMetadata(traversedMetadata, byId.get(branch[i]).metadata);
     if (traversed === null || !traversedMetadata) throw fault('redo branch does not replay');
   }
-  // Picture folding may relocate finished definitions while navigating. Keep its
-  // distinct forward proof; the literal-only case above needs no second traversal.
   if (ledger.complete && pictures.size) {
     let active = new HistorySource(ledger.start.text), activeMetadata = {...ledger.start.metadata};
     for (let i = 0; i < branch.length; i++) {
@@ -270,7 +246,6 @@ export function agentActorId(door, agent) {
   return door + '/' + agent.name;
 }
 
-// A writer changing representation records that change, rather than attaching an unrelated head.
 export function replaceLedgerText(input, text, {actor = {kind: 'system', id: 'rapier'}, operation = 'document.replace', at} = {}) {
   const current = readLedger(input); documentText(text);
   if (current.text === text) return current.ledger;

package/dist/ledger/hash.mjs

@@ -1,9 +1,7 @@
 // SPDX-License-Identifier: MIT
-// The editor's path-dependent root, plus synchronous SHA-256 for file readers (including offline wrappers).
 export function textRoot(text) {
   return textRootParts([text]);
 }
-// The same UTF-16 root over shared source pieces, without joining a historical body.
 export function textRootParts(parts) {
   let fnv = 0x811c9dc5, a = 1, b = 0, length = 0;
   for (const text of parts) {
@@ -30,7 +28,6 @@ const K = new Uint32Array([
   0x748f82ee,0x78a5636f,0x84c87814,0x8cc70208,0x90befffa,0xa4506ceb,0xbef9a3f7,0xc67178f2,
 ]);
 const rotate = (x, n) => (x >>> n) | (x << (32 - n));
-// One bounded SHA-256 compression state for file bytes and encoded source text.
 export function sha256State() {
   const h = new Uint32Array([0x6a09e667,0xbb67ae85,0x3c6ef372,0xa54ff53a,0x510e527f,0x9b05688c,0x1f83d9ab,0x5be0cd19]);
   const w = new Uint32Array(64), block = new Uint8Array(64);
@@ -82,14 +79,11 @@ export function sha256State() {
     get bytes() { return bytes; },
   };
 }
-// UTF-16 chunks share that byte state. Retain a trailing high surrogate so a
-// caller can split a character between updates without changing its UTF-8 digest.
 export function createSHA256() {
   const hash = sha256State(), encoded = new Uint8Array(65536), encoder = new TextEncoder();
   let high = '', finished = false;
   const write = text => {
     for (let at = 0; at < text.length;) {
-      // Bound both the substring and byte allocation; encodeInto never cuts a scalar.
       let end = Math.min(text.length, at + 32768);
       if (end < text.length && (text.charCodeAt(end - 1) & 0xfc00) === 0xd800 && (text.charCodeAt(end) & 0xfc00) === 0xdc00) end--;
       const part = encoder.encodeInto(text.slice(at, end), encoded);
@@ -117,4 +111,14 @@ export function sha256Parts(parts) {
   for (const part of parts) hash.update(part);
   return hash.digest();
 }
-export function sha256(text) { return createSHA256().update(text).digest(); }
+const LONG_TEXT = 65536, DIGESTS = new Map();
+export function sha256(text) {
+  if (typeof text !== 'string' || text.length < LONG_TEXT) return createSHA256().update(text).digest();
+  let digest = DIGESTS.get(text);
+  if (digest === undefined) {
+    digest = createSHA256().update(text).digest();
+    if (DIGESTS.size >= 4) DIGESTS.delete(DIGESTS.keys().next().value);
+  } else DIGESTS.delete(text);
+  DIGESTS.set(text, digest);
+  return digest;
+}

package/dist/ledger/history.mjs

@@ -1,5 +1,4 @@
 // SPDX-License-Identifier: MIT
-// Transient projections and selective inverses of the existing canonical journal.
 import {_rapierTransformSplices, _rapierValidMetadata, _rapierTransformMetadata, _rapierMetadataDelta, _rapierHistoryEffects, _rapierMetadataState, _rapierPrepareHistoryRecords} from './journal-records.mjs';
 import {projectInverseSource, HistorySource} from './inverse-source.mjs';
 import {textRootParts, rootAfter} from './hash.mjs';
@@ -41,16 +40,12 @@ export function groupHistoryActs(acts) {
 	return groups;
 }
 
-// A picture's codec replacement travels with its original navigation step.
-// Match every complete replacement exactly before moving any source bytes.
 export function pictureHistorySplices(input, target, redo) {
 	const {records} = input;
 	const id = target?.transaction?.id, at = records.indexOf(target);
 	if (!id || at < 0 || target.transaction.operation === 'document.finish-picture' || !Array.isArray(target.splices)) return null;
 	const later = records.slice(at + 1).filter(row => row?.transaction?.operation === 'document.finish-picture' && Array.isArray(row.splices) && row.splices.length);
 	if (!later.length) return null;
-	// A caller may hold a persistent source tree: request its text only when
-	// a later picture replacement can actually affect this navigation step.
 	const source = input.source;
 	const own = new Set(later.filter(row => row.transaction.sourceTransactionId === id));
 	const step = redo ? target.splices : target.splices.slice().reverse().map(row => ({pos: row.pos, removed: row.inserted, inserted: row.removed}));
@@ -78,9 +73,6 @@ export function pictureHistorySplices(input, target, redo) {
 	try { return plan(true); } catch (_) { return null; }
 }
 
-// Keep only the latest source observation. Inactive live documents must not retain
-// every revision's source tree. The weak key also lets the latest input be collected.
-// Mutable caller data is compared/captured before this cache can be consulted.
 let preparedHistories = new WeakMap();
 function prepareHistory(input) {
 	try {
@@ -123,7 +115,6 @@ function prepareHistory(input) {
 			row.beforeSource = initial; row.beforeMetadata = initialMetadata;
 		}
 		const earliestRevision = records[0]?.transaction.baseRevision ?? revision;
-		// The window's owner may name its root (the source store mints it once per text); otherwise hash the initial text.
 		let root = earliestRevision === 0 ? (typeof input.earliestRoot === 'string' && input.earliestRoot || textRootParts(initial.parts())) : null,
 			rootRevision = earliestRevision;
 		for (const {record, splices} of rows) {
@@ -131,8 +122,6 @@ function prepareHistory(input) {
 			if (hashed && (![record.beforeHash, record.afterHash].every(value =>
 				typeof value === 'string' && /^\d+:[a-z0-9]+:[a-z0-9]+$/.test(value)) ||
 				(splices.length ? record.beforeHash === record.afterHash : record.beforeHash !== record.afterHash))) return historyFailure('history_invalid');
-			// Revision gaps begin a new path root; a continuous revision-zero prefix
-			// still binds every untouched source byte through the initial text root.
 			if (record.transaction.baseRevision !== rootRevision) root = null;
 			if (hashed) {
 				if (root !== null && record.beforeHash !== root) return historyFailure('history_invalid');
@@ -155,12 +144,18 @@ function prepareHistory(input) {
 	} catch (_) { return historyFailure('history_invalid'); }
 }
 
+function settle(result, value) {
+	Object.defineProperty(result, 'initialSource', {value, writable: true, enumerable: true, configurable: true});
+	return value;
+}
+
 export function replayHistory(input) {
 	const prepared = prepareHistory(input);
 	if (!prepared.ok) return prepared;
-	const {source, initialSource, metadata, initialMetadata, revision, earliestRevision, complete, rows, effects} = prepared;
+	const {source, metadata, initialMetadata, revision, earliestRevision, complete, rows, effects} = prepared;
 	const acts = rows.filter(({record}) => !effects.pictures.has(record.transaction.id)).map(({record}) => historyAct(record, effects));
-	return {ok: true, source, initialSource, metadata: {...metadata}, initialMetadata: {...initialMetadata}, revision, earliestRevision, complete, acts,
+	return {ok: true, source, get initialSource() { return settle(this, prepared.initialSource); }, set initialSource(value) { settle(this, value); },
+		metadata: {...metadata}, initialMetadata: {...initialMetadata}, revision, earliestRevision, complete, acts,
 		effectiveActIds: effects.effectiveActIds.slice(), groups: groupHistoryActs(acts)};
 }
 
@@ -218,7 +213,6 @@ export function historyProjection(input, {from = 0, to = input?.source?.length,
 	return projectHistoryRange(prepared, from, to, actId);
 }
 
-// Several ranges share one proved source snapshot for this call.
 export function historyProjections(input, ranges) {
 	const prepared = prepareHistory(input);
 	if (!prepared.ok) return prepared;
@@ -227,8 +221,6 @@ export function historyProjections(input, ranges) {
 		projectHistoryRange(prepared, from, to, actId))};
 }
 
-// Block intervals stay ordered under reverse splices. A fixed balanced tree can
-// shift an untouched suffix lazily and visit only intervals crossing the edit.
 function historyBlockIndex(projected) {
 	const items = projected.map(block => ({block, range: {from: block.from, to: block.to}, shift: 0}))
 		.sort((a, b) => a.range.from - b.range.from);
@@ -278,8 +270,6 @@ export function historyPlaces(input, blocks) {
 		const {record, splices, beforeSource, afterSource} = prepared.rows[index], touched = new Map();
 		for (let at = splices.length - 1; at >= 0; at--) ranges.move(splices[at], node => {
 			if (touched.has(node) || prepared.effects.pictures.has(record.transaction.id)) return;
-			// Earlier splices in this reverse walk only shifted this interval. Recover
-			// its coordinates at the record's after-state before recording the first touch.
 			let after = {...node.range};
 			for (let prior = at + 1; prior < splices.length; prior++) {
 				const row = splices[prior];
@@ -290,37 +280,31 @@ export function historyPlaces(input, blocks) {
 			}
 			touched.set(node, after);
 		});
-		// Blocks one splice covers share its range (a whole-document delete maps every block to all it removed): slice each range once.
 		const slices = new Map(), cut = (source, side, from, to) => {
 			const key = side + from + ':' + to;
 			if (!slices.has(key)) slices.set(key, source.slice(from, to));
 			return slices.get(key);
 		};
-		// One record's act is read once; the blocks it touched share its fields (a whole-document delete touches every block).
 		let act = null;
 		for (const [node, afterRange] of touched) {
 			const beforeRange = ranges.range(node), previous = {...beforeRange, source: cut(beforeSource, 'b', beforeRange.from, beforeRange.to)},
 				after = {...afterRange, source: cut(afterSource, 'a', afterRange.from, afterRange.to)};
-			// A point (where words were deleted) has no words to compare: the act that touched it wrote there.
 			if (previous.source !== after.source || afterRange.from === afterRange.to) node.block.acts.push({...(act ||= historyAct(record)), before: previous, after});
 		}
 	}
 
 	const acts = prepared.rows.filter(({record}) => !prepared.effects.pictures.has(record.transaction.id)).map(({record}) => historyAct(record));
-	// Native Redo consumes its Undo as navigation while keeping that receipt in
-	// the reading history. All material withdrawals use the canonical blockers,
-	// including independent inverses holding the same original act suppressed.
 	const reversed = new Set();
 	for (const {record} of prepared.rows) if (prepared.effects.active.has(record.transaction.id) && !record.transaction.reapplies)
 		for (const id of prepared.effects.references.get(record.transaction.id) || []) reversed.add(id);
 
 	for (const block of projected) block.acts.reverse();
-	return {ok: true, source: prepared.source, initialSource: prepared.initialSource, revision: prepared.revision,
+	return {ok: true, source: prepared.source, get initialSource() { return settle(this, prepared.initialSource); },
+		set initialSource(value) { settle(this, value); }, revision: prepared.revision,
 		earliestRevision: prepared.earliestRevision, complete: prepared.complete, acts, blocks: projected,
 		reversed: acts.filter(act => reversed.has(act.id)).map(act => act.id)};
 }
 
-// Runs retain only exact replacement ancestry. A later replacement owns an ambiguous hunk whole.
 export function selectiveUndo(input, actIds, options = {}) {
 	const prepared = prepareHistory(input);
 	if (!prepared.ok) return prepared;
@@ -340,9 +324,6 @@ export function selectiveUndo(input, actIds, options = {}) {
 	const metadata = _rapierMetadataDelta(prepared.metadata, afterMetadata), effectChanged = selected.size > 0;
 	const sourceEffectChanged = records.some(record => record.splices.length && !prepared.effects.references.get(record.transaction.id)?.length &&
 		prepared.effects.active.has(record.transaction.id) !== projectedEffects.active.has(record.transaction.id));
-	// One shared replacement is visible while any of its authors is active. That
-	// includes an author stored with no second physical splice, and an inverse
-	// whose only effect is to make such an author active again.
 	let coverVisibilityChanged = false;
 	if (!sourceEffectChanged && selected.size) {
 		let origins = null;

package/dist/ledger/inverse-source.mjs

@@ -1,6 +1,4 @@
 // SPDX-License-Identifier: MIT
-// Exact source projection shared by canonical history and causal transport.
-// Callers admit and order the records first; this projection retains no state.
 import {_rapierTransformSplices, _rapierHistoryEffects} from './journal-records.mjs';
 import {authoredPlacements} from './authored-origin.mjs';
 import {canonicalJSON} from './data.mjs';
@@ -11,8 +9,6 @@ const historyBoundary = (source, at) => Number.isSafeInteger(at) && at >= 0 && !
 	!(at > 0 && at < source.length && (source.charCodeAt(at - 1) & 0xFC00) === 0xD800 &&
 	(source.charCodeAt(at) & 0xFC00) === 0xDC00);
 
-// Persistent AVL pieces retain original strings and coordinates. A revision costs
-// only the edited paths; reading a range visits its leaves, never earlier bodies.
 const sourceLeaf = (text, from = 0, to = text.length) => to > from
 	? {text, from, length: to - from, height: 1} : null;
 const sourceHeight = node => node?.height || 0;
@@ -101,8 +97,6 @@ export class HistorySource {
 		for (const text of parts) for (let at = 0; at < text.length;) {
 			if (!leaf) return false;
 			const length = Math.min(leaf.length - offset, text.length - at), from = leaf.from + offset;
-			// Untouched runs share their string and coordinates. Only changed fragments
-			// require a text comparison; no full-body join is needed to prove the plan.
 			if ((leaf.text !== text || from !== at) && leaf.text.slice(from, from + length) !== text.slice(at, at + length)) return false;
 			offset += length; at += length;
 			if (offset === leaf.length) { leaf = leaves.next().value; offset = 0; }
@@ -113,8 +107,6 @@ export class HistorySource {
 		const [left, rest] = sourceSplit(this.#root, pos), [, right] = sourceSplit(rest, length);
 		return new HistorySource('', sourceJoin(sourceJoin(left, sourceLeaf(text)), right));
 	}
-	// Undoing an admitted repair is observation: its after-state can join a scalar
-	// across the deleted run. Prove the forward boundaries on the reconstructed view.
 	before(splices) {
 		let source = this;
 		for (let index = splices.length - 1; index >= 0; index--) {
@@ -151,8 +143,6 @@ function minimalHistorySplice(before, after, pos = 0) {
 	return {pos: pos + first, removed: before.slice(first, a), inserted: after.slice(first, b)};
 }
 
-// Split recorded replacements only at exact unchanged word or line tokens.
-// Shared letters inside changed words do not establish surviving ownership.
 function historyHunks(row) {
 	if (row.removed === row.inserted) return [];
 	if (!row.removed || !row.inserted) return [{...row}];
@@ -166,8 +156,6 @@ function historyHunks(row) {
 }
 
 
-// Rows are already proved source placements, optionally carrying sourceIndices from
-// causal projection. Multiple inverse blockers can change history with no source edit.
 export function projectInverseSource(prepared, selected, projectedEffects, options = {}) {
 	const records = prepared.records || prepared.rows.map(({record, splices}) => record.splices === splices ? record : {...record, splices});
 	if (!records.some(record => !prepared.effects.references.get(record.transaction.id)?.length &&
@@ -179,8 +167,6 @@ export function projectInverseSource(prepared, selected, projectedEffects, optio
 		const recordsForCover = prepared.records || prepared.rows.map(({record, splices}) => record.splices === splices ? record : {...record, splices});
 		const coverGroups = new Map();
 		let coverOrigins = null;
-		// An empty document is a real causal source. Fresh notes start there, and a
-		// shared replacement authored against that source still has to stay covered.
 		if (typeof prepared.initialSource === 'string' && recordsForCover.some(record => record.authored?.splices?.some(row => row.removed.length))) {
 			try { coverOrigins = authoredPlacements(prepared.initialSource, recordsForCover); } catch { coverOrigins = null; }
 		}
@@ -254,9 +240,6 @@ export function projectInverseSource(prepared, selected, projectedEffects, optio
 			return next && effects.active.has(next.actId) && !prepared.effects.references.get(next.actId)?.length;
 		});
 		const reactivate = (actIds, effects) => {
-			// Any author of one shared removal or replacement restores that one physical
-			// hunk, including an author who stored no splice. A later independent act
-			// keeps the bytes it wrote until that act itself is withdrawn.
 			const wanted = new Set(actIds);
 			for (const id of actIds) for (const hunk of all) {
 				if (hunk.reversedHunk || hunk.derived || !hunk.coverIds?.includes(id) || wanted.has(hunk.actId)) continue;
@@ -269,8 +252,6 @@ export function projectInverseSource(prepared, selected, projectedEffects, optio
 					(!hunk.inserted && hunk.active)) continue;
 				const marker = pieces.indexOf(hunk.marker);
 				if (marker < 0) {
-					// A zero-row withdrawal can release source still carried by another
-					// inverse's marker. Its exact ancestry also preserves later inserted runs.
 					const inverse = all.findLast(prior => prior.reversedHunk === hunk.id && pieces.includes(prior.marker));
 					if (!inverse) throw Error('reactivation');
 					const runs = all.filter(prior => prior.actId === inverse.actId && prior.reversedHunk === hunk.id && pieces.includes(prior.marker));
@@ -302,8 +283,6 @@ export function projectInverseSource(prepared, selected, projectedEffects, optio
 			processed.push(record);
 			const picture = prepared.effects.pictures.get(tx.id);
 			if (picture) {
-				// The new codec bytes keep the exact inserted run's ownership. Do not
-				// cross a later edit, combine authors, or create another reversible act.
 				for (const row of splices) {
 					boundary(row.pos + row.removed.length);
 					const start = boundary(row.pos), end = boundary(row.pos + row.removed.length);
@@ -318,15 +297,11 @@ export function projectInverseSource(prepared, selected, projectedEffects, optio
 				continue;
 			}
 			if (references.size) {
-				// Exact inverse rows restore the previous run identities. Retain the inverse's
-				// own transient marker too, so reversing it restores that same ancestry again.
 				const invert = targets => {
 					const restored = pieces.slice(), inverses = [], priorSplices = options.keepHunk ? [] : null;
 					for (let index = targets.length - 1; index >= 0; index--) {
 						const target = targets[index], first = restored.indexOf(target.marker);
 						if (first < 0) return null;
-						// Each run of the target's own pieces inverts alone: a later author's pieces between
-						// its runs stay in place, outside every inverse, so reversing it cannot move them.
 						const runs = [];
 						for (let at = first; at < restored.length; at++) if (owns(restored[at], target))
 							if (runs.at(-1)?.[1] === at) runs.at(-1)[1]++; else runs.push([at, at + 1]);
@@ -346,8 +321,6 @@ export function projectInverseSource(prepared, selected, projectedEffects, optio
 								hunk.chosen = !keep;
 							}
 							hunk.kept = selected.has(tx.id) && !hunk.chosen;
-							// A semantic owner retaining this inverse also retains the exact ancestors
-							// it restored; effect reactivation must not change them behind that owner.
 							if (hunk.kept) for (let prior = target; prior; prior = byId.get(prior.reversedHunk)) keptInverseAncestors.add(prior.id);
 							hunk.marker = {mark: hunk};
 							const insertion = replacement.map(piece => piece.text ? {...piece,
@@ -359,10 +332,6 @@ export function projectInverseSource(prepared, selected, projectedEffects, optio
 					}
 					return replays(pieces, restored, splices) ? {restored, inverses} : null;
 				};
-				// An inverse taken while a later edit had replaced some of the act's hunks restored only
-				// the rest. Those replaced hunks survive it: no later projection treats them as undone.
-				// Recorded splices decide. An author who stored no splice still inverts the one
-				// shared hunk; an empty inverse does not match that text change and leaves it.
 				const direct = all.filter(hunk => hunk.active && references.has(hunk.actId));
 				const targets = direct.length ? direct : all.filter(hunk => hunk.active && !hunk.reversedHunk && !hunk.derived &&
 					hunk.coverIds?.some(id => references.has(id)));
@@ -399,16 +368,12 @@ export function projectInverseSource(prepared, selected, projectedEffects, optio
 			}
 			if (!references.size) coverIdsFor(tx.id);
 			const priorSplices = options.keepHunk ? [] : null;
-			// An admitted codec finish replaces the complete embedded definition/reference.
-			// Keep its inserted run whole, including byte-identical prefixes of a re-edit;
-			// the previous picture stays in `before` for Undo, not as mixed live ownership.
 			const hunks = row => pictureInsertions.get(tx.id)?.some(text => row.inserted.includes(text)) ? [{...row}] : historyHunks(row);
 			for (let rowIndex = 0; rowIndex < splices.length; rowIndex++) {
 				const original = splices[rowIndex];
 				let rows;
 				if (options.splitSplice) {
 					const beforeSource = textOf(pieces), parts = options.splitSplice({actId: tx.id, beforeSource, splice: original});
-					// Semantic boundaries only refine this act's exact bytes, never its history.
 					if (!Array.isArray(parts) || _rapierTransformSplices(beforeSource, parts) !== _rapierTransformSplices(beforeSource, [original]))
 						throw Error('hunk_projection');
 					rows = parts.flatMap(hunks);
@@ -421,14 +386,11 @@ export function projectInverseSource(prepared, selected, projectedEffects, optio
 					const start = boundary(row.pos), end = boundary(row.pos + row.removed.length);
 					let at = start.last, count = Math.max(0, end.first - at);
 					if (!row.removed.length) {
-						// A new insertion at a replacement's left boundary stays before that replacement.
 						const marker = pieces.slice(start.first, start.last).findIndex(item => item.mark?.inserted.length);
 						at = marker < 0 ? start.last : start.first + marker; count = 0;
 					}
 					const removed = pieces.slice(at, at + count);
 					if (textOf(removed) !== row.removed) throw Error('replay');
-					// A semantic owner may retain a drawing hunk while prose in that same act undoes.
-					// The predicate only selects transient hunks; every original row still replays.
 					if (chosen && options.keepHunk) {
 						const keep = options.keepHunk({actId: tx.id, spliceIndex: rowIndex, hunkIndex: index,
 							splice: {pos: row.pos, removed: row.removed, inserted: row.inserted}, beforeSource: textOf(pieces), actSource, priorSplices});
@@ -459,10 +421,6 @@ export function projectInverseSource(prepared, selected, projectedEffects, optio
 		let offset = 0;
 		for (const piece of pieces) if (piece.text) { origins.set(piece, offset); offset += piece.text.length; }
 		const superseded = [];
-		// Survival means an inverse left this hunk in place because a later independent
-		// edit still covered it. Once that edit is gone, deactivating its last owner through
-		// any inverse path withdraws every exposed hunk. Undoing only the later
-		// edit reveals the survived insertion and does not discard it.
 		for (const hunk of all) if (hunk.survived) {
 			const covered = [...hunk.supersededBy].some(id => {
 				const next = byId.get(id);
@@ -486,12 +444,8 @@ export function projectInverseSource(prepared, selected, projectedEffects, optio
 					reason: hunk.active ? 'later_edit' : 'already_undone'});
 				continue;
 			}
-			// Restoring an inverse can restore a deletion marker without any owned text.
 			restoreHunk(hunk);
 		}
-		// A hidden withdrawal can have no splice of its own. Reversing that withdrawal
-		// reactivates the shared hunk through the inverse that still carries it.
-		// Withdrawing a later act reveals that same hunk while any original author remains.
 		const reactivated = new Set(records.filter(record => !prepared.effects.active.has(record.transaction.id) &&
 			projectedEffects.active.has(record.transaction.id)).map(record => record.transaction.id));
 		for (const hunk of all) if (!hunk.reversedHunk && !hunk.derived && hunk.coverIds?.length > 1 &&