rapier-html 1.2.7 → 1.2.9

package/dist/ledger/journal-records.mjs

@@ -5,14 +5,10 @@ const _RAPIER_TRANSACTION_ACTOR_LIMIT = 160;
 const _RAPIER_TRANSACTION_OPERATION_LIMIT = 96;
 const _RAPIER_TRANSACTION_REQUEST_LIMIT = 160;
 
-/* Validate every row, not only the final string: a half-pair replacement can produce a whole
-	 character while leaving unencodable fragments in the ledger; two invalid rows can also repair
-	 each other. Refusal is atomic. Pre-existing damage elsewhere stays untouched and editable. */
 function _rapierTransformSplices(text, splices, inverse = false) {
 	try {
 		if (!Array.isArray(splices)) return null;
 		let value = String(text == null ? '' : text);
-		// In Unicode mode a complete pair is one scalar, outside the surrogate range.
 		const whole = text => typeof text === 'string' && !/[\uD800-\uDFFF]/u.test(text);
 		const splitsPair = at => at > 0 && at < value.length &&
 			(value.charCodeAt(at - 1) & 0xFC00) === 0xD800 &&
@@ -81,7 +77,6 @@ function _rapierTransformMetadata(value, effect, inverse = false) {
 	return next;
 }
 
-// An origin binds transported placement to exact authored rows and their causal basis.
 function _rapierValidAuthored(origin) {
 	if (!_rapierPlainLedgerData(origin) || !origin || Array.isArray(origin) ||
 		Object.keys(origin).length !== 3 || !Array.isArray(origin.basis) ||
@@ -95,9 +90,6 @@ function _rapierValidAuthored(origin) {
 		!/[\uD800-\uDFFF]/u.test(row.removed) && !/[\uD800-\uDFFF]/u.test(row.inserted));
 }
 
-// The lookup is an observation of one call's supplied records. Material rows keep
-// their existing borrowed-row API; an inverse owns fresh rows. Navigation only
-// follows strictly earlier revisions, including when an unadmitted list is unordered.
 function _rapierRecordIndex(records) {
 	const byId = new Map(), splices = new Map(), metadata = new Map();
 	for (const record of records) {
@@ -139,8 +131,6 @@ function _rapierRecordSplices(entry, ledger) {
 	} catch (_) { return null; }
 }
 
-// Source identifies a retained checkpoint even when host revision numbers differ.
-// The History Slider compares now → earlier: that answer is the earlier → now walk, inverted.
 function journalOperations(before, after, journal) {
 	if (typeof before !== 'string' || typeof after !== 'string' || !Array.isArray(journal)) return;
 	if (before === after) return [];
@@ -151,15 +141,34 @@ function journalOperations(before, after, journal) {
 
 function journalWalk(before, after, journal) {
 	try {
-		let text = after;
+		const pieces = [after];
 		const lookup = _rapierRecordIndex(journal), groups = [];
+		let length = after.length;
+		const locate = at => { let index = 0; for (; index < pieces.length - 1 && at >= pieces[index].length; index++) at -= pieces[index].length; return [index, at]; };
+		const codeAt = at => { const [index, offset] = locate(at); return pieces[index].charCodeAt(offset); };
+		const read = (from, to) => { let out = ''; for (let [index, offset] = locate(from); from < to && index < pieces.length; index++, offset = 0) { const part = pieces[index].slice(offset, offset + to - from); out += part; from += part.length; } return out; };
+		const cut = at => { const [index, offset] = locate(at); if (offset > 0 && offset < pieces[index].length) pieces.splice(index, 1, pieces[index].slice(0, offset), pieces[index].slice(offset)); };
+		const whole = text => typeof text === 'string' && !/[\uD800-\uDFFF]/u.test(text);
+		const splitsPair = at => at > 0 && at < length && (codeAt(at - 1) & 0xFC00) === 0xD800 && (codeAt(at) & 0xFC00) === 0xDC00;
 		for (let index = journal.length - 1; index >= 0; index--) {
 			const rows = lookup.splices(journal[index]);
-			const prior = _rapierTransformSplices(text, rows, true);
-			if (prior === null) return;
+			if (!Array.isArray(rows)) return;
+			for (const row of rows.slice().reverse()) {
+				if (!row || !Number.isSafeInteger(row.pos) || row.pos < 0 || Object.is(row.pos, -0)) return;
+				const pos = row.pos, removed = row.inserted, inserted = row.removed;
+				if (!whole(removed) || !whole(inserted) || pos > length || pos + removed.length > length ||
+						splitsPair(pos) || splitsPair(pos + removed.length) || read(pos, pos + removed.length) !== removed) return;
+				cut(pos); cut(pos + removed.length);
+				let [first] = locate(pos), count = 0;
+				if (pos === length) first = pieces.length;
+				else if (locate(pos)[1] !== 0) first++;
+				for (let left = removed.length; left > 0; count++) left -= pieces[first + count].length;
+				pieces.splice(first, count, ...(inserted ? [inserted] : []));
+				length += inserted.length - removed.length;
+				for (let at = pieces.length - 1; at >= 0; at--) if (!pieces[at] && pieces.length > 1) pieces.splice(at, 1);
+			}
 			groups.push(rows);
-			if (prior === before) return groups.reverse().flat().map(({pos, removed, inserted}) => ({pos, removed, inserted}));
-			text = prior;
+			if (length === before.length && pieces.join('') === before) return groups.reverse().flat().map(({pos, removed, inserted}) => ({pos, removed, inserted}));
 		}
 	} catch (_) { return; }
 }
@@ -167,14 +176,11 @@ function journalWalk(before, after, journal) {
 function _rapierRecordMetadata(entry, ledger) {
 	try {
 		if (Object.hasOwn(entry, 'metadata')) return _rapierValidMetadataEffect(entry.metadata) ? entry.metadata : undefined;
-		// An expanded record owns its complete effect; only compact navigation inherits one.
 		if (Array.isArray(entry.splices)) return null;
 		return _rapierRecordIndex(ledger || []).metadata(entry);
 	} catch (_) { return undefined; }
 }
 
-// A codec replacement owns only one inserted definition and its reference. Its
-// source act remains the picture's author; an arbitrary edit cannot claim upkeep.
 function _rapierPictureFinish(record, original, earlier, lookup) {
 	const tx = record?.transaction, rows = record?.splices;
 	if (tx?.operation !== 'document.finish-picture' || !tx.sourceTransactionId || tx.sourceTransactionIds ||
@@ -221,9 +227,6 @@ function _rapierPictureFinish(record, original, earlier, lookup) {
 	});
 }
 
-// Every active inverse keeps its original targets suppressed. Independent inverses
-// can share a target; withdrawing one restores it only after the last blocker leaves.
-// This includes assignments hidden by later choices. No second history is retained.
 function _rapierWalkHistoryEffects(records, lookup, visit = null, observe = null) {
 	try {
 		if (!Array.isArray(records)) return {ok: false};
@@ -238,9 +241,6 @@ function _rapierWalkHistoryEffects(records, lookup, visit = null, observe = null
 				if (was !== node.active) for (const ref of node.references) pending.push([ref, node.active ? 1 : -1]);
 			}
 		};
-		// Most admission needs only the final effect graph. A backwards pass proves it
-		// in linear work; prefix activity is asked only by native Redo, picture custody,
-		// or a metadata assignment. The explicit stack also bounds long inverse chains.
 		const activity = new Map();
 		const active = id => {
 			if (visit) return nodes.get(id).active;
@@ -258,8 +258,6 @@ function _rapierWalkHistoryEffects(records, lookup, visit = null, observe = null
 			return activity.get(id);
 		};
 		const lastUndo = new Map(), contexts = new Map(), order = [];
-		// Native Redo names an original act. Its inverse target is the last Undo
-		// in the author's proved causal view, not an unrelated later arrival.
 		const contextOf = origin => {
 			if (!origin) return null;
 			if (!_rapierValidAuthored(origin)) throw Error('origin');
@@ -338,8 +336,6 @@ function _rapierHistoryEffects(records, visit = null) {
 	return _rapierWalkHistoryEffects(records, null, visit);
 }
 
-// Every transition constrains the two initial metadata scalars. This proves each
-// inverse's result once, before the caller supplies the exact initial metadata.
 function _rapierMetadataProof(lookup) {
 	const values = {}, required = {}, assignments = {filename: [], docKind: []};
 	const requireInitial = (key, value) => {
@@ -355,7 +351,6 @@ function _rapierMetadataProof(lookup) {
 			values[key] = pair.after;
 			if (!refs.length) assignments[key].push({id: record.transaction.id, value: pair.after});
 		}
-		// Source-only rows cannot change a previously proved metadata assignment.
 		if (!effect && !refs.length) return;
 		for (const key of ['filename', 'docKind']) {
 			const expected = assignments[key].findLast(row => active(row.id));
@@ -385,7 +380,6 @@ function _rapierMetadataState(initial, records, effects = _rapierHistoryEffects(
 	} catch (_) { return null; }
 }
 
-// Prove each recorded transition and each inverse's semantic result, not only the final values.
 function _rapierReplayMetadata(initial, records) {
 	if (!_rapierValidMetadata(initial)) return null;
 	try {
@@ -405,16 +399,9 @@ function _rapierHasHistoryEffect(record, earlier = []) {
 	return _rapierHistoryEffects([...earlier, {...record, transaction: {...tx, id}}]).ok;
 }
 
-// A cached observation owns every byte-bearing record. Mutable graphs are compared
-// through descriptors on every call; only a proved, recursively frozen graph can
-// bypass that walk. Per-object weak entries keep one latest copy, not a revision log.
 const _rapierPrepareHistoryRecords = (() => {
 	const copies = new WeakMap();
-	// Repeated queries share the latest proved snapshot. A live but inactive input
-	// does not need to retain its record/effect indexes; immutable copies remain weak.
 	let prepared = new WeakMap();
-	// Object.freeze does not freeze Map/Set entries. Keep those collections inside
-	// the preparation and expose only immutable values through reading closures.
 	const view = collection => Object.freeze({size: collection.size, has: key => collection.has(key),
 		...(collection instanceof Map ? {get: key => collection.get(key)} : {}),
 		keys: () => collection.keys(), values: () => collection.values(), entries: () => collection.entries(),
@@ -456,8 +443,6 @@ const _rapierPrepareHistoryRecords = (() => {
 			frame.previous = previous?.copy;
 			frame.height = 0;
 			if (previous?.frozen) {
-				// A frozen shell fixes its descriptors, but every mutable child is still
-				// observed afresh. Fixed scalar fields need no second Unicode/data proof.
 				frame.frozen = frame.immutable = true;
 				frame.descriptors = previous.descriptors; frame.fields = previous.fields;
 				frame.out = null; frame.leaving = true; active.add(value); pending.push(frame);
@@ -467,8 +452,6 @@ const _rapierPrepareHistoryRecords = (() => {
 				}
 				continue;
 			}
-			// Check frozen-ness before capturing descriptors. A caller freezing a mutable
-			// input later cannot retroactively certify an earlier view of its properties.
 			frame.frozen = frame.immutable = Object.isFrozen(value);
 			const array = Array.isArray(value), proto = Object.getPrototypeOf(value);
 			if (!array && !plainPrototype(proto)) throw Error('history_data');
@@ -535,12 +518,6 @@ const _rapierPrepareHistoryRecords = (() => {
 	};
 })();
 
-// A ledger record as the journal and the Notes return validate it below: plain data, nothing
-// undefined anywhere in it. A live record could carry a row whose type or order is not yet known (a
-// block just inserted, before its first render: `type: undefined`), and the validator would refuse
-// the whole ledger for that one field -- silently at boot, where a refused ledger is cleared, and
-// as "Rapier could not be reopened: the document history could not be restored" on a return from
-// Notes. The copy is made once per record; records are frozen, so it never goes stale.
 const _rapierJournalRecord = (() => {
 	const copies = new WeakMap();
 	return record => {
@@ -551,10 +528,6 @@ const _rapierJournalRecord = (() => {
 })();
 
 function _rapierValidLedgerRecord(record, prior, earlier, documentAuthority, maxDocumentBytes, utf8Length, allowGap = false) {
-	// Recovery records are data, not executable objects. Inspect descriptors without invoking
-	// accessors, and use an ancestor set (not a global seen set) so shared acyclic data stays valid.
-	// Iterative traversal refuses cycles without exhausting the call stack. Proxies/counters that
-	// throw are refused by the same gate rather than escaping into document recovery.
 	try {
 		if (!_rapierPlainLedgerData(record) || !Array.isArray(earlier)) return false;
 		const own = Array.isArray(record?.splices), lookup = own ? null : _rapierRecordIndex(earlier);
@@ -566,8 +539,6 @@ function _rapierValidLedgerRecord(record, prior, earlier, documentAuthority, max
 	} catch (_) { return false; }
 }
 
-// Both callers proved plain data themselves: the public single-row validator above,
-// or the private owned-snapshot preparation. No caller-supplied trusted flag exists.
 function _rapierCheckLedgerRecord(record, prior, documentAuthority, maxDocumentBytes, utf8Length, allowGap,
 	{splices, metadata, semantic, duplicate}) {
 	try {
@@ -579,8 +550,6 @@ function _rapierCheckLedgerRecord(record, prior, documentAuthority, maxDocumentB
 		if ((!own && !navigation) || (own && record.splices.length > 64) ||
 			(record.transaction?.reverts && record.transaction?.reapplies)) return false;
 		const metadataChanged = Object.values(metadata || {}).some(pair => pair.before !== pair.after);
-		// An identical concurrent replacement keeps its authored rows and an empty
-		// physical splice. The origin proof, not this gate, shows the effect is already present.
 		const coincidentWitness = !splices?.length && record.beforeHash === record.afterHash &&
 			record.authored && _rapierValidAuthored(record.authored) && record.authored.splices.some(row => row.removed.length);
 		if (metadata === undefined || (!splices?.length && !metadataChanged && !semantic && !coincidentWitness) ||
@@ -597,7 +566,6 @@ function _rapierCheckLedgerRecord(record, prior, documentAuthority, maxDocumentB
 		const transaction = record.transaction;
 		const nullableText = (value, limit, empty = true) => value === null ||
 			(typeof value === 'string' && value.length <= limit && (empty || value.length > 0));
-		// Identity fields are bounded individually; durable history has no record-count limit.
 		const optional = (value, valid) => value === undefined || valid(value);
 		const identity = (value, limit) => typeof value === 'string' && value.length > 0 && value.length <= limit;
 		if (!transaction || typeof transaction.id !== 'string' || !transaction.id.length ||

package/dist/ledger/transport.mjs

@@ -1,5 +1,4 @@
 // SPDX-License-Identifier: MIT
-// Paired source placement, shared by live editing and canonical-history proof.
 import {_rapierTransformSplices, _rapierValidAuthored, _rapierHistoryEffects} from './journal-records.mjs';
 import {projectInverseSource} from './inverse-source.mjs';
 import {authoredBasis, authoredPlacement, authoredPlacements} from './authored-origin.mjs';
@@ -25,8 +24,6 @@ function emit(rows, at, remove, insert = '') {
   } else rows.push({at, remove, insert});
 }
 
-// Sweep original-source boundaries. Each counter names a coordinate in one input's
-// resulting document; concurrent insertions never enter the other input's removals.
 export function transformPair(left, right, leftFirst) {
   admitted(left); admitted(right);
   const points = [...new Set([0, ...left.flatMap(row => [row.at, row.at + row.remove]),
@@ -62,9 +59,6 @@ function applyBatch(text, rows) {
   return {text: after, splices: exact};
 }
 
-// Transport one sequential canonical act and every crossed record together. The
-// reciprocal path is checked against exact source, rather than only equal end text.
-// Canonical transport refuses deleting any authored unit already removed elsewhere.
 export function transposeRecord(base, splices, id, records) {
   if (typeof base !== 'string' || !Array.isArray(splices) || typeof id !== 'string' || !Array.isArray(records))
     throw new RangeError('canonical_transport_invalid');
@@ -75,10 +69,6 @@ export function transposeRecord(base, splices, id, records) {
     if (next === null) throw new RangeError('canonical_transport_invalid');
     current = next;
   }
-  // A concurrent act that already removed these same authored units and wrote the
-  // same replacement is one physical edit. This act stays in history with no second
-  // deletion. Pure insertions are never collapsed: each one is its own unit. An
-  // inverse of that act means the replacement is not still in force.
   const sameRows = (left, right) => left.length === right.length && left.every((row, index) =>
     row.pos === right[index].pos && row.removed === right[index].removed && row.inserted === right[index].inserted);
   const matched = crossed.filter(record => sameRows(record.splices, splices));
@@ -122,8 +112,6 @@ export function transposeRecord(base, splices, id, records) {
   return {splices: moved, sourceIndices, against: crossed, text: current};
 }
 
-// Hosted and editor callers already own a reciprocal transport log. Convert only
-// its admitted exact source to records, then prove canonical-unit preservation.
 export function transposeSource(base, splices, client, log) {
   let source = base;
   const records = log.map(entry => {
@@ -135,8 +123,6 @@ export function transposeSource(base, splices, client, log) {
 
 export {authoredBasis, authoredPlacement, authoredPlacements};
 
-// Reconstruct an authored view from the same records, then prove its exact physical
-// placement. Equality of resulting text alone cannot prove a repeated-text anchor.
 function authoredReplay(base, records, append = null) {
   const origins = new Map(), byId = new Map(), originalOrder = [], cache = new Map(), frontier = new Set();
   const effects = _rapierHistoryEffects(append ? [...records, append] : records);
@@ -156,8 +142,6 @@ function authoredReplay(base, records, append = null) {
     if (!result.ok) throw new RangeError('canonical_origin_invalid');
     return result;
   };
-  // Only immutable text digests are reused, within this one replay. Every
-  // authored-source comparison and physical placement proof still runs.
   const textHashes = new Map();
   const hashText = text => {
     if (typeof text !== 'string') return sha256(text);
@@ -166,7 +150,6 @@ function authoredReplay(base, records, append = null) {
     return digest;
   };
   const same = (a, b) => canonicalJSON(a) === canonicalJSON(b);
-  // Only owner-created ordered views of already admitted string IDs use this.
   const sameIds = (a, b) => {
     if (a.length !== b.length) return false;
     for (let index = 0; index < a.length; index++) if (a[index] !== b[index]) return false;
@@ -192,8 +175,6 @@ function authoredReplay(base, records, append = null) {
     })()))) throw new RangeError('canonical_origin_invalid');
     const refs = effects.references.get(id) || [];
     if (refs.some(id => !seen.has(id))) throw new RangeError('canonical_origin_invalid');
-    // An explicit origin can prove the same linear placement as an implicit one.
-    // Preserve the origin, but do not reconstruct every growing prefix to prove it again.
     if (linearPrefix === originalOrder.length && same(origin.basis, [...frontier].sort()) &&
         same(origin.splices, record.splices) && (!Object.hasOwn(record, 'authored') || origin.source === sha256(source)))
       linearPrefix++;
@@ -212,7 +193,6 @@ function authoredReplay(base, records, append = null) {
     const key = coverKey(origin);
     if (key) coverCounts.set(key, (coverCounts.get(key) || 0) + 1);
   }
-  // Two inverses can name different acts and still withdraw one physical replacement.
   const sharesCover = id => (effects.references.get(id) || []).some(ref => {
     const key = coverKey(origins.get(ref));
     return !!key && coverCounts.get(key) > 1;
@@ -250,14 +230,9 @@ function authoredReplay(base, records, append = null) {
     return closure;
   };
   const canonicalOrder = ordered(originalOrder);
-  // Only the three immediate fresh-spread call sites use this entry. Nothing
-  // retains allocation trust after an array has crossed an observable method.
   const literalKey = order => {
-    // An input iterator can supply arbitrary values. Preserve the whole-array
-    // depth/refusal path before any per-string encoding in that case.
     for (let index = 0; index < order.length; index++)
       if (typeof order[index] !== 'string') return canonicalJSON(order);
-    // Keep each canonical primitive encoder call and its serializer behavior.
     return '[' + Array.from({length: order.length}, (_, index) => canonicalJSON(order[index])).join(',') + ']';
   };
   const materialize = (order, rawSubmitted = false) => materializeKey(order, canonicalJSON(order), rawSubmitted);
@@ -266,14 +241,10 @@ function authoredReplay(base, records, append = null) {
     if (cache.has(key)) return cache.get(key);
     let prefixEnds = null;
     const prefixKey = length => {
-      // The original submitted array keeps its existing slice/species/data gate.
-      // Only this module's own order allocations use the validated key string.
       if (rawSubmitted) return canonicalJSON(order.slice(0, length));
       if (!prefixEnds) {
         prefixEnds = [1];
         let quoted = false, depth = 0;
-        // Scan canonical JSON only: an escaped code unit cannot end a string,
-        // and commas inside strings or nested values cannot split this array.
         for (let at = 1; at < key.length - 1; at++) {
           const code = key.charCodeAt(at);
           if (quoted) {
@@ -290,11 +261,7 @@ function authoredReplay(base, records, append = null) {
     };
     let placed = [], ids = new Set(), sourceIndices = new Map(), text = base;
     if (!order.length) { const empty = {text, records: [], sourceIndices}; cache.set(key, empty); return empty; }
-    // A proved linear prefix already is its authored view. Replay it once;
-    // reconstructing every growing prefix adds no evidence.
     let prefix = 0;
-    // Resume only an exact ordered prefix already proved in this replay. Copy its
-    // mutable containers before extending it; transported rows retain their placement.
     for (let length = order.length - 1; length > 0; length--) {
       const prior = cache.get(prefixKey(length));
       if (!prior) continue;
@@ -314,8 +281,6 @@ function authoredReplay(base, records, append = null) {
         throw new RangeError('canonical_origin_invalid');
       const closure = closureOf(origin.basis);
       if (closure.size === ids.size && [...closure].every(prior => ids.has(prior))) {
-        // The current view already is the complete authored context. There are no
-        // independent rows to cross, even when earlier acts were concurrent.
         if (hashText(text) !== origin.source) throw new RangeError('canonical_origin_invalid');
         const next = _rapierTransformSplices(text, origin.splices);
         if (next === null) throw new RangeError('canonical_origin_invalid');
@@ -326,8 +291,6 @@ function authoredReplay(base, records, append = null) {
       }
       const basisOrder = canonicalOrder.filter(prior => closure.has(prior)), basis = materialize(basisOrder);
       if (hashText(basis.text) !== origin.source) throw new RangeError('canonical_origin_invalid');
-      // Reconstruct causal context before crossing it. Physical gaps may already
-      // have collapsed under a deletion; they cannot choose concurrent ordering.
       const contextOrder = canonicalOrder.filter(prior => ids.has(prior)), context = sameIds(contextOrder, [...ids]) ? {text, records: placed} : materialize(contextOrder);
       if (context.text !== text) throw new RangeError('canonical_origin_invalid');
       const alignedOrder = [...basisOrder, ...contextOrder.filter(prior => !closure.has(prior))];
@@ -336,10 +299,6 @@ function authoredReplay(base, records, append = null) {
       const crossed = aligned.records.slice(basisOrder.length);
       let moved;
       if (effects.references.get(id)?.length && (sharedInverses || sharesCover(id))) {
-        // Each inverse retains its own targets. First prove the exact intention
-        // in its causal source, then place that choice in the accepted effect
-        // graph. Another inverse may already suppress the same original bytes,
-        // including when the two inverses name different authors of one replacement.
         const authored = projectInverse(basis.text, basis.records, id);
         if (!same(origin.splices, authored.splices) ||
             _rapierTransformSplices(basis.text, origin.splices) !== authored.after)
@@ -357,7 +316,6 @@ function authoredReplay(base, records, append = null) {
   const physicalOrder = append ? originalOrder.slice(0, -1) : originalOrder, physical = materialize(physicalOrder);
   if (physical.text !== source || physical.records.some((row, index) => !same(row.splices, records[index].splices)))
     throw new RangeError('canonical_origin_invalid');
-  // Raw submission is selected here by a private call site, never an input flag.
   return {source, origins, originalOrder, materialize, materializeLiteral,
     materializeSubmitted: order => materialize(order, true), ordered};
 }
@@ -365,14 +323,11 @@ function authoredReplay(base, records, append = null) {
 export function authoredHistory(base, records, selected = null) {
   const replay = authoredReplay(base, records);
   if (!selected) return {text: replay.source, records, origins: replay.origins};
-  // Targets follow independent work only in this transient Undo projection.
   const projected = replay.materialize(replay.ordered(replay.originalOrder, selected));
   if (projected.text !== replay.source) throw new RangeError('canonical_origin_invalid');
   return {...projected, origins: replay.origins};
 }
 
-// Semantic annotations use the original splice coordinates, even when an accepted
-// physical placement split those rows. The same replay proves the causal basis first.
 export function authoredSourceReader(base, records) {
   const replay = authoredReplay(base, records);
   return actId => {
@@ -390,8 +345,6 @@ export function authoredSourceReader(base, records) {
   };
 }
 
-// The original view and the accepted view are both reconstructed from the same
-// immutable acts. The reciprocal rows are an exact ACK, not another history.
 export function transposeAuthored(base, records, incoming, submitted) {
   if (!incoming.authored || !Array.isArray(submitted)) throw new RangeError('canonical_origin_invalid');
   const replay = authoredReplay(base, records, incoming), id = incoming.transaction.id;

package/dist/page.d.mts

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: MIT
+// rapier-html: Markdown to one offline HTML file that carries its exact source, and back.
+export type Part = 'drawing' | 'math' | 'mermaid';
+export type DocKind = 'markdown' | 'text' | 'code';
+export interface WrapOptions {
+  kind?: DocKind;
+  /** The view the page opens on, with the document behind it. */
+  view?: 'draw' | 'notes';
+  /** An SVG drawing carried beside the document, opened on Draw. */
+  drawing?: string;
+  drawingName?: string;
+  /** The original text (or a page carrying it); the page opens showing the diff. */
+  base?: string;
+  baseName?: string;
+  /** With base: the name and time shown on the diff. */
+  by?: string;
+  at?: string;
+  /** A one-use return URL and its expiry, both from the door's show {target: "return"}. */
+  return?: string;
+  return_expires_at?: string;
+  /** A rapier-ledger/2 history and its authorship projection, verified against the text. */
+  ledger?: unknown;
+  authorship?: unknown;
+}
+export interface Unwrapped {
+  /** The exact carried source, or null for a page without one. */
+  text: string | null;
+  name: string | null;
+  kind: DocKind | null;
+  view: 'draw' | 'notes' | null;
+  drawing: string | null;
+  drawingName: string | null;
+  base: string | null;
+  baseName: string | null;
+  baseSha256: string | null;
+  baseRevision: string | null;
+  by: string | null;
+  at: string | null;
+  return: string | null;
+  return_expires_at: string | null;
+  ledger: unknown;
+  authorship: unknown;
+  comparisonBase: unknown;
+  html: string;
+}
+/** Markdown to a page in one call: the editor this package carries, cut to what the document displays with. */
+export function writePage(text: string, name?: string, options?: WrapOptions & {include?: Part[]}): Promise<string>;
+/** Puts the document into a Rapier page you supply (for example a carry() of the packaged page). */
+export function wrap(pageHtml: string, text: string, name?: string, options?: WrapOptions): string;
+/** Reads the exact document back out of a page. */
+export function unwrap(pageHtml: string): Unwrapped;
+/** The page with only the named parts inline. */
+export function carry(pageHtml: string, include?: Part[]): string;
+/** The parts a document displays with: math, mermaid. */
+export function portableNeeds(text: string, options?: {base?: string; flowchart?: (source: string) => boolean}): Part[];
+export function encodeCarried(text: string): string;
+export function decodeCarried(text: string): string;
+/** The command line: rapier-html <document.md> [out.html] [options]. Resolves the written path, or null for --help. */
+export function main(argv: string[], pagesDir: string, options?: {log?: (line: string) => void}): Promise<string | null>;

package/dist/page.mjs

@@ -4,7 +4,13 @@ import {basename, dirname, join} from 'node:path';
 import {wrap, carry, portableNeeds} from './wrap.mjs';
 import {returnAddress, returnExpiresAt} from './return-address.mjs';
 export {wrap, unwrap, carry, portableNeeds, encodeCarried, decodeCarried} from './wrap.mjs';
-// Unknown options, a bare --drawing or --compare and a third name are refused.
+
+let carried = null;
+const carriedPage = () => carried ??= readFile(new URL('./rapier.html', import.meta.url), 'utf8');
+export async function writePage(text, name = 'document.md', {include, ...options} = {}) {
+	const carries = include ?? [...(options.view === 'draw' || options.drawing != null ? ['drawing'] : []), ...portableNeeds(String(text), {base: options.base})];
+	return wrap(carry(await carriedPage(), carries), text, name, options);
+}
 const USAGE = 'usage: rapier-html <document.md> [out.html] [--include draw,math,mermaid] [--view draw] [--drawing sketch.svg] [--compare original.md [--by <your name>]] [--return <url> --return-expires-at <timestamp>]\n' +
 	'  writes <document>.rapier.html beside the file: Rapier with the document inside it, one file, offline.\n' +
 	'  It never overwrites: an output that already exists, the document itself included, is refused.\n' +
@@ -18,7 +24,6 @@ const USAGE = 'usage: rapier-html <document.md> [out.html] [--include draw,math,
 	'  --return-expires-at  carries the same mint\'s expiry; Share offers Save once the return expires\n' +
 	'  --          everything after it is a filename, even one that starts with a dash\n' +
 	'  --help      this text';
-// Damaged UTF-8 is refused, never carried as U+FFFD; a BOM is carried.
 const text = async path => { try { return new TextDecoder('utf-8', {fatal: true, ignoreBOM: true}).decode(await readFile(path)); } catch (error) { throw error.code === 'ERR_ENCODING_INVALID_ENCODED_DATA' ? new Error(path + ' is not valid UTF-8') : error; } };
 
 export async function main(argv, pagesDir, {log = console.log} = {}) {
@@ -73,7 +78,6 @@ export async function main(argv, pagesDir, {log = console.log} = {}) {
 	if (view) wrapOptions.view = view;
 	if (address) wrapOptions.return = address;
 	if (expiry) wrapOptions.return_expires_at = expiry;
-	// Always a new file; 'wx' refuses any existing path, links included.
 	const carries = include || [...(view === 'draw' || drawingPath ? ['drawing'] : []), ...portableNeeds(source, {base: wrapOptions.base})];
 	const html = wrap(carry(page, carries), source, name, wrapOptions);
 	try { await writeFile(out, html, {flag: 'wx'}); }