rapier-markdown-kit 1.2.7 → 1.2.9

package/README.md

@@ -24,6 +24,28 @@ deliberately show a diff. The kit supplies the portable source and history those
 npm install rapier-markdown-kit
 ```
 
+Render a document with [markdown-it](https://github.com/markdown-it/markdown-it), then style it with
+`rapier-markdown-kit/style.css` inside `<main class="md-render">`:
+
+```js
+import MarkdownIt from 'markdown-it';
+import {rapierMarkdown} from 'rapier-markdown-kit/markdown-it';
+
+const html = new MarkdownIt({html: true}).use(rapierMarkdown).render('# Plan\n\nShips **Friday**.\n');
+```
+
+Keep a document's history with authorship, and merge two offline copies:
+
+```js
+import {openLedger, replaceLedgerText, merge, authorship} from 'rapier-markdown-kit/rapier-ledger';
+
+const base = openLedger('Draft\n');
+const edited = replaceLedgerText(base, 'Draft, revised\n', {actor: {kind: 'human', id: 'ana'}});
+console.log(merge(edited, base).text, authorship(edited).runs);
+```
+
+TypeScript declarations ship for `markdown-it`, `will`, `rapier-ledger`, `ledger/carried` and `pdf`.
+
 ```js
 import {parseLayout} from 'rapier-markdown-kit/layout';   // the md-layout comment a picture carries
 import {typography, formatPageBreak} from 'rapier-markdown-kit/marks';   // inline typography and page breaks
@@ -46,6 +68,9 @@ as one HTML file on Android, Web and Windows.
 
 ## The shared renderer
 
+To render Markdown in your own app, use `rapier-markdown-kit/markdown-it` (above). The render factories below are the
+editor's own seam: each needs a `host` that supplies its DOM, Markdown, picture, style and font ports.
+
 `rapier-markdown-kit/render` exports `createRenderer`, `createMarkdownRenderer`,
 `createRenderStyles`, `createRenderSanitizer` and `createPrintRenderer`, plus the explicit font helpers
 `exportFontCss`, `requireDocumentFonts`, `fontRequests`, `waitForFonts` and `waitForFontRequests`. These are the
@@ -139,6 +164,7 @@ family name share the host's font namespace. Print retains its existing factory
 
 | Import | What it is |
 | --- | --- |
+| `rapier-markdown-kit/markdown-it` | `md.use(rapierMarkdown)`: the reference style's markup in markdown-it, in one line. |
 | `rapier-markdown-kit/layout` | The `md-layout:v1` comment a picture carries: parse it, validate it, write it back. |
 | `rapier-markdown-kit/marks` | Unified typography values, span writer and parser installer; preserved color/font comments, ink and page breaks. |
 | `rapier-markdown-kit/model` | Occupancy profiles and the line planner: the wrapping itself. |
@@ -146,7 +172,8 @@ family name share the host's font namespace. Print retains its existing factory
 | `rapier-markdown-kit/will` | The Will/1 grammar (a separate, optional standard): the markers around an agent's intent regions. |
 | `rapier-markdown-kit/assets` | The picture appendix: the reference definitions a document's pictures live in. It never decodes a picture. |
 | `rapier-markdown-kit/style.css` | The reference style: type, lists, tables, tasks, pictures and the document's other markup, scoped to `.md-render`. |
-| `rapier-markdown-kit/rapier-ledger` | The MIT edit-ledger format, replay, authorship projection and offline merge. |
+| `rapier-markdown-kit/rapier-ledger` | The MIT edit ledger: `openLedger`, replay, authorship, selective Undo, offline `merge`, three-way `mergeText`, and the carried parts. |
+| `rapier-markdown-kit/pdf` | `attachPdfSource`: attach the exact source to a PDF without rewriting its pages; `readPdfPageCount`. |
 | `rapier-markdown-kit/ledger/carried` | Checked optional parts for pages and saved Markdown. |
 | `rapier-markdown-kit` | Named exports from the layout, marks, model, typography, Will, assets and render modules, plus the `ledger` namespace. |
 
@@ -290,38 +317,13 @@ contract is [Reference style](https://github.com/jackskip22/rapier/blob/main/doc
 <!-- reference-style-example -->
 ```js
 import MarkdownIt from 'markdown-it';
-import {parseLayout, formatLayout, imageStyle} from 'rapier-markdown-kit/layout';
-import {TEXT_COLOR_NAMES, typography, formatColorRun, formatPageBreak, isPageBreakBlock} from 'rapier-markdown-kit/marks';
-import {installMarkdownImages} from 'rapier-markdown-kit/assets';
+import {rapierMarkdown} from 'rapier-markdown-kit/markdown-it';
+import {formatLayout} from 'rapier-markdown-kit/layout';
+import {TEXT_COLOR_NAMES, typography, formatColorRun, formatPageBreak} from 'rapier-markdown-kit/marks';
 import {readFile, writeFile} from 'node:fs/promises';
 import {pathToFileURL} from 'node:url';
 
-const md = typography.install(installMarkdownImages(new MarkdownIt({html: true, linkify: true})));
-md.renderer.rules.table_open = (tokens, index, options, env, renderer) =>
-  '<div class="table-scroll-wrap">\n' + renderer.renderToken(tokens, index, options);
-md.renderer.rules.table_close = (tokens, index, options, env, renderer) =>
-  renderer.renderToken(tokens, index, options) + '</div>\n';
-md.core.ruler.after('inline', 'reference-layout', state => {
-  for (let i = 1; i < state.tokens.length; i++) {
-    const inline = state.tokens[i], owner = state.tokens[i - 1];
-    if (inline.type !== 'inline' || !['paragraph_open', 'heading_open'].includes(owner.type)) continue;
-    const children = inline.children, marker = children.at(-1);
-    const layout = marker?.type === 'html_inline' ? parseLayout(marker.content) : null;
-    if (!layout) continue;
-    children.pop();
-    if (layout.align) owner.attrSet('data-md-align', layout.align);
-    const visible = children.filter(token => token.type !== 'text' || token.content.trim());
-    if (visible.length === 1 && visible[0].type === 'image' && layout.width) {
-      visible[0].attrSet('style', imageStyle(layout));
-      visible[0].attrSet('data-md-image-width', String(layout.width));
-    }
-  }
-});
-const htmlBlock = md.renderer.rules.html_block;
-md.renderer.rules.html_block = (tokens, index, options, env, renderer) =>
-  isPageBreakBlock(tokens[index].content)
-    ? '<div class="rapier-page-break" data-md-break="page" role="separator" aria-label="Page break"></div>\n'
-    : htmlBlock(tokens, index, options, env, renderer);
+const md = new MarkdownIt({html: true, linkify: true}).use(rapierMarkdown);
 
 export function renderReferenceDocument(source) {
   return md.render(source);

package/dist/agent/will.mjs

@@ -10,7 +10,7 @@ const _RAPIER_WILL_UNSPACED_OPENER = '<!--will/';
 const _RAPIER_WILL_UNSPACED_CLOSER = '<!--/will';
 
 function hasWillMarkers(text) {
-	return /^<!-- ?(?:will\/|\/will)/m.test(String(text == null ? '' : text));
+	return /(?:^|[\r\n])<!-- ?(?:will\/|\/will)/.test(String(text == null ? '' : text));
 }
 
 function _rapierWillMarkerOf(content) {
@@ -48,18 +48,14 @@ function _rapierWillMarkerOf(content) {
 		if (!intent.length || intent.indexOf('--') >= 0) return near('malformed_marker');
 		if ([...intent].length > _RAPIER_WILL_INTENT_LIMIT) return near('intent_over_bound');
 	}
-	// The words after the colon are document data, never permission; willGovern alone decides.
 	return { kind: 'open', law: word, intent, content: line };
 }
 
-// Scan CR, CRLF and LF lines directly into Will's reducer, including a trailing empty line.
-// Offsets remain authored UTF-16 coordinates; no editor helper or whole-document line tables.
 function _rapierWillParse(text) {
 	const source = String(text == null ? '' : text);
 	const will = {
 		present: false, fault: '', faults: [], blocks: [], markers: [], regions: [], text: source,
 	};
-	// A marker, well formed or near, opens its line with one of the four spellings hasWillMarkers looks for.
 	if (!hasWillMarkers(source)) return will;
 	let open = null;
 	for (let index = 0, start = 0; start <= source.length; index++) {
@@ -150,7 +146,6 @@ function _rapierWillIntentOf(will, start, end) {
 	const found = _rapierWillRegionsIn(will, start, end);
 	if (found.length !== 1) return '';
 	const region = found[0];
-	// Disclosed with the region's law, never in place of it: under keep and append the words widen nothing.
 	return region.intent && start >= region.start && end <= region.end ? region.intent : '';
 }
 

package/dist/images/gif.mjs

@@ -1,6 +1,4 @@
 // SPDX-License-Identifier: MIT
-// Container admission and a single-frame carrier, not a pixel/LZW decoder.
-// Original bytes remain the asset. Native ImageDecoder owns frame composition.
 export function inspectGIF(bytes) {
   const fail = message => {throw Object.assign(new Error(message), {code: 'GIF_ADMISSION'});};
   if (!(bytes instanceof Uint8Array) || bytes.length < 13 || bytes.length > 16 * 1024 * 1024 ||
@@ -39,7 +37,6 @@ export function inspectGIF(bytes) {
     at += 9; if (packed & 128) at += 3 * (2 << (packed & 7));
     need(1); if (bytes[at] < 2 || bytes[at] > 8) fail('Invalid GIF code size');
     at++; blocks(); frames++;
-    // A delay of 0 or 1 centisecond shows for 100 ms, as the browser draws it (images/playback.mjs times frames the same).
     const delay = control ? control[4] + control[5] * 256 : 0;
     duration += delay > 1 ? delay * 10 : 100;
     if (frames > 240 || width * height * frames > 96000000 || duration > 120000) fail('GIF animation exceeds the frame, work or duration budget');

package/dist/images/playback.mjs

@@ -1,9 +1,6 @@
 // SPDX-License-Identifier: MIT
-// Shared, self-contained playback for the host and its opaque HTML frames.
-// No source/history authority; at most one decoder and one returned frame per object.
 export function createMediaPlayback(win, inspectGIF) {
   const active = new Map(), encode = bytes => bytes.toBase64();
-  // Base64 decodes in 1 MiB slices with a task yield between them, so a large animation never holds the main thread.
   const bytes = async url => {
     const text = url.slice(url.indexOf(',') + 1), slice = 1 << 20;
     const out = new Uint8Array(text.length / 4 * 3 - (text.endsWith('==') ? 2 : text.endsWith('=') ? 1 : 0));
@@ -15,7 +12,6 @@ export function createMediaPlayback(win, inspectGIF) {
     return out;
   };
   function raster(url, canvas, changed = () => {}, dimensions = null) {
-    // setFromBase64 refuses any character outside base64 while decoding.
     if (url.length > 24 * 1024 * 1024 || !/^data:image\/(gif|jxl);base64,/i.test(url) || (url.length - url.indexOf(',') - 1) % 4) throw new Error('Unsupported animation source');
     const type = url.slice(5, url.indexOf(';')).toLowerCase();
     let data = null, info = null, size = null, decoder = null, timer = 0, closed = false, paused = true, ticket = 0, next = 0, loops = 0, duration = 0, single = false, held = false;
@@ -30,8 +26,6 @@ export function createMediaPlayback(win, inspectGIF) {
       if (!closed) changed(state);
     })();
     admitted.catch(error => {if (!closed) {state.status = 'admission-failed'; state.error = String(error.message).slice(0, 160); changed(state);}});
-    // A decoder closes only after its in-flight decode settles; Chrome 155's JPEG XL decoder fails when closed mid-decode.
-    // Its budget place goes with it: a poster or a finished loop holds no decoder.
     let inflight = null;
     const closeDecoder = () => {ticket++; win.clearTimeout(timer); timer = 0; active.delete(canvas); const old = decoder; decoder = null; if (old) inflight ? inflight.then(() => old.close()) : old.close();};
     const settle = async promise => {
@@ -73,8 +67,7 @@ export function createMediaPlayback(win, inspectGIF) {
           if (canvas.height !== h) canvas.height = h;
           const ctx = canvas.getContext('2d'); ctx.clearRect(0, 0, w, h); ctx.drawImage(frame, 0, 0);
           if (!state.first && next === 0) state.first = canvas.toDataURL('image/png');
-          // A frame of 10 ms or less shows for 100 ms, as the browser draws an <img> (images/gif.mjs counts the same).
-          const delay = frame.duration > 10000 ? Math.max(20, frame.duration / 1000) : 100;
+          const delay = type !== 'image/gif' ? Math.max(8, frame.duration / 1000) : frame.duration > 10000 ? Math.max(20, frame.duration / 1000) : 100;
           duration += delay; if (duration > 120000) throw new Error('Animation exceeds the duration budget');
           state.status = 'ready'; state.frame = next; changed(state);
           if (single) {paused = true; closeDecoder(); return;}
@@ -91,9 +84,7 @@ export function createMediaPlayback(win, inspectGIF) {
       }
     }
     return {state, play() {if (!closed && paused && !['decode-failed', 'admission-failed'].includes(state.status)) {paused = false; void step();}},
-      // A suspension that arrives during the one-frame decode (an offscreen host's first visibility report) waits for it.
       async first() {if (!state.first && !closed) {single = true; next = 0; paused = false; try {await step();} finally {single = false; paused = true; closeDecoder(); if (held) {held = false; this.suspend();}}} return state.first;},
-      // Pause keeps the decoder and its frame position; only suspension and removal release it.
       pause() {paused = true; ticket++; win.clearTimeout(timer); timer = 0;},
       suspend() {if (single) {held = true; return;} paused = true; closeDecoder(); canvas.width = canvas.height = 0; state.status = 'suspended'; changed(state);},
       close() {closed = true; paused = true; closeDecoder(); canvas.width = canvas.height = 0;},

package/dist/kit/assets.mjs

@@ -1,6 +1,5 @@
 // SPDX-License-Identifier: MIT
 // Re-export from ../spec/md-assets.mjs only: ../images/assets.mjs pulls AGPL decoders into the MIT graph (tools/check-kit.mjs).
-// The kit's names are listed: that module also exports what only Rapier's own parser consumers share.
 export {IMAGE_LIMITS, configureParser, normalizeLabel, assetTitle, installMarkdownImages, markdownParser, markdownBodyOffset,
   dataImage, parseAssets, documentAssets, packAssetIndex, restoreAssetIndex, projectImageDefinitions, blockwiseAssets,
   imageEnvironment, referenceOccurs, mayRetireImageDefinitions, retireDeletedImageDefinitions, assetOmissions, isAssetBlock,

package/dist/kit/conformance/run.mjs

@@ -1,6 +1,4 @@
-#!/usr/bin/env node
 // SPDX-License-Identifier: MIT
-// Usage: node run.mjs [--impl path/to/module.mjs] [--tolerance 2]
 import {resolve} from 'node:path';
 import {dirname} from 'node:path';
 import {fileURLToPath} from 'node:url';
@@ -32,11 +30,9 @@ function buildProfile(hint) {
 }
 
 const documents = loadDocuments(here);
-// Install once over merged data: Pretext memoizes its context (measurer.mjs).
 const measurer = installMeasurer(documents);
 const preparation = impl.createPreparationScope();
 
-// Preservation and presentation are separate claims; preservation is exact or a bug.
 const preservationRows = documents.map(expected => {
 	const comment = expected.picture?.layout;
 	if (!comment) return {document: expected.document, verdict: 'n/a', detail: "this fixture's picture carries no md-layout comment"};
@@ -61,7 +57,7 @@ const preservationRows = documents.map(expected => {
 console.log('Presentation (line boxes; hits/misses show how much of each row rests on the real trace vs. the character-sum fallback)\n');
 const rows = [];
 for (const expected of documents) {
-	const font = expected.measurer.font.replace(/\/[^ ]+ /, ' '); // canvas fonts take no line-height
+	const font = expected.measurer.font.replace(/\/[^ ]+ /, ' ');
 	const before = {hits: measurer.stats.hits, misses: measurer.stats.misses};
 	const flow = preparation.prepare(expected, [{text: expected.anchorText, font, letterSpacing: expected.measurer.letterSpacing || 0}]);
 	if (!flow) { rows.push({document: expected.document, verdict: 'ERROR', detail: 'rich preparation refused this font/text/letterSpacing'}); continue; }
@@ -80,14 +76,11 @@ for (const expected of documents) {
 	let maxLeftDelta = 0, maxRightDelta = 0, maxTopDelta = 0;
 	for (let i = 0; i < Math.min(plan.lines.length, expected.lines.length); i++) {
 		const got = plan.lines[i], want = expected.lines[i];
-		// Flowed lines are line boxes; an unflowed line's recorded top is its glyphs' own.
 		if (expected.anchorFlowed) maxTopDelta = Math.max(maxTopDelta, Math.abs(got.y - want.top));
-		// Flowed lines compare slot geometry (x+width); unflowed lines compare the measured tight extent.
 		const right = expected.anchorFlowed ? got.x + got.width : got.x + measurer.measure(font, got.fragments.map(f => f.text).join(''));
 		maxLeftDelta = Math.max(maxLeftDelta, Math.abs(got.x - want.left));
 		maxRightDelta = Math.max(maxRightDelta, Math.abs(right - want.right));
 	}
-	// A line that keeps its edges but lands on another row is a different layout.
 	const rowsAgree = maxTopDelta <= args.tolerance;
 	const withinTolerance = lineCountAgrees && rowsAgree && maxLeftDelta <= args.tolerance && maxRightDelta <= args.tolerance;
 	rows.push({

package/dist/kit/export-fonts.mjs

@@ -1,12 +1,10 @@
 // SPDX-License-Identifier: MIT
 import {documentFontUsage, CSS_GENERIC_FONT_FAMILIES} from '../spec/document-fonts.mjs';
 import {normalizeFontFamily} from '../spec/md-marks.mjs';
-// Collect document font data without a layout engine. Authored drawing resources keep their identities.
 const FONT_FIELDS = new Set(['font', 'font-family', 'font-weight', 'font-style', 'font-stretch', 'text-transform']);
 const FAMILY = "'Geist',system-ui,sans-serif";
 const MONO = "'Geist Mono',monospace";
 
-// Optional HTML enhancement: the font payload and its encoded stylesheet have separate limits.
 const FACTORY_FONT_BYTES = 8 * 1024, FACTORY_FONT_CSS_BYTES = 12 * 1024;
 const decodeCss = value => value.replace(/\\(?:([\da-f]{1,6})(?:\r\n|[ \t\n\r\f])?|([^\n\r\f]))/gi,
   (_, hex, character) => hex ? String.fromCodePoint(Math.max(1, Math.min(0x10ffff, parseInt(hex, 16)))) : character);
@@ -68,7 +66,6 @@ function rules(text, visit) {
 }
 
 function specificity(selector) {
-  // The reference sheet uses :where() for zero-specificity defaults.
   let value = selector.replace(/:where\((?:[^()]|\([^()]*\))*\)/g, '');
   const ids = (value.match(/#[\w-]+/g) || []).length;
   const classes = (value.match(/\.[\w-]+|\[[^\]]*\]|:(?!:)[\w-]+/g) || []).length;
@@ -291,14 +288,12 @@ export async function exportFontCss(root, {settings, css = '', fontCss = '', sub
     if (typeof subset !== 'function') throw new TypeError('The page font writer needs a subsetter.');
     let candidates = fontFaces(fontCss);
     if (portableFactory) {
-      // These candidates come from the factory resource host. Carried data owns a same-name family.
       const custom = new Set(fontFaces(customFontCss).map(face => face.family));
       candidates = candidates.filter(face => face.family === 'geist' && !custom.has(face.family));
     }
     const faces = fontRuns(root, {settings, css, faces: candidates}), output = [], prepared = new Map();
     let payloadBytes = 0;
     for (const face of faces) {
-      // Adjacent inline nodes retain shaping sequences; independent runs cannot compose together.
       const text = face.runs.join('\n');
       if (!prepared.has(face.source)) prepared.set(face.source, new Map());
       const variants = prepared.get(face.source);
@@ -310,7 +305,6 @@ export async function exportFontCss(root, {settings, css = '', fontCss = '', sub
           if (typeof validateFont !== 'function' || await validateFont(Uint8Array.from(bytes), {family: 'Geist'}) !== true) return '';
         } else if (bytes === null) { variants.set(text, null); continue; }
         if (!(bytes instanceof Uint8Array) || !bytes.length) throw new Error('The page font subset is empty.');
-        // Retain the encoded boundary value, not additional original or subset byte buffers.
         variants.set(text, {source: fontSource(bytes), length: bytes.length});
       }
       const saved = variants.get(text);
@@ -329,10 +323,8 @@ export async function exportFontCss(root, {settings, css = '', fontCss = '', sub
   }
 }
 
-// Validate the captured custom resources without rewriting their source or borrowing a live catalog.
 export async function requireDocumentFonts(source, {parser, index, root, settings, css = '', fontCss = '', validateFont}) {
   const candidates = fontFaces(fontCss), known = new Set(candidates.map(face => face.family));
-  // Missing named choices participate in the same cascade, but inert and generic runs need no data.
   for (const family of ['Geist', 'Geist Mono', ...documentFontUsage(source, parser).keys()]) {
     const name = family.toLowerCase();
     if (!known.has(name)) {
@@ -363,8 +355,6 @@ export async function requireDocumentFonts(source, {parser, index, root, setting
         throw Object.assign(new Error('Embedded font validation is unavailable: ' + asset.family), {code: 'export_font_unavailable'});
       if (await validateFont(bytes, {family: asset.family, format: asset.format}) !== true)
         throw Object.assign(new Error('The embedded font is invalid: ' + asset.family), {code: 'export_font_invalid'});
-      // The host validates the font; the viewing engine must also accept this exact container.
-      // Loading an uninstalled face checks bytes without changing this document's font set.
       if (typeof Font === 'function') try { await new Font('rapier-export-validation', bytes).load(); }
       catch (cause) { throw Object.assign(new Error('The embedded font could not be loaded: ' + asset.family, {cause}), {code: 'export_font_invalid'}); }
       checked.add(asset.url);
@@ -378,7 +368,6 @@ export function fontRequests(root, options = {}) {
     stretch: record.properties['font-stretch'] || '100%'}));
 }
 
-// This self-contained readiness step also runs in the isolated server print document.
 export async function waitForFontRequests(doc, requests) {
   if (!requests?.length) return;
   const family = value => String(value).trim().replace(/^(['"])([\s\S]*)\1$/, '$2').replace(/\\(?:([\da-f]{1,6})\s?|([^\r\n\f]))/gi,
@@ -395,9 +384,6 @@ export async function waitForFontRequests(doc, requests) {
   }
 }
 
-// CSS font loading can finish successfully while a required face is in the error state.
-// Load the exact embedded bytes before print takes its immutable page, and leave unrelated
-// local fallbacks and unused family styles outside this document's readiness decision.
 export async function waitForFonts(root, {settings, css = '', fontCss = '', install = true} = {}) {
   const required = fontRuns(root, {settings, css, fontCss});
   if (!required.length) return () => {};

package/dist/kit/index.mjs

@@ -6,4 +6,4 @@ export * from './typography.mjs';
 export * from './will.mjs';
 export * from './assets.mjs';
 export * from './render-entry.mjs';
-export * as ledger from './rapier-ledger.mjs';
+export * as ledger from './ledger.mjs';

package/dist/kit/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/kit/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/kit/ledger/carried.d.mts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+// The ledger and authorship carried inside the document: an optional HTML comment at the end of the file.
+import type {LedgerEnvelope, AuthorshipEnvelope, Metadata} from '../ledger.mjs';
+export interface DocumentParts { ledger?: LedgerEnvelope | null; authorship?: AuthorshipEnvelope | null; metadata?: Metadata; }
+export interface ReadParts { text: string; ledger: LedgerEnvelope | null; authorship: AuthorshipEnvelope | null; }
+/** The text with its parts appended as one EOF comment; the text alone when there are none. */
+export function writeDocument(text: string, parts?: DocumentParts): string;
+/** Splits a saved file into its exact text and verified parts; throws on a damaged or mismatched comment. */
+export function readDocument(source: string): ReadParts;
+export function writeParts(text: string, parts?: DocumentParts): string;
+export function readParts(text: string, elements: unknown): {ledger: LedgerEnvelope | null; authorship: AuthorshipEnvelope | null};
+export function validateParts(text: string, parts?: DocumentParts): {ledger: LedgerEnvelope | null; authorship: AuthorshipEnvelope | null};
+export function takeParts(html: string, text?: string): {html: string; ledger: LedgerEnvelope | null; authorship: AuthorshipEnvelope | null};
+export function encodeCarried(text: string): string;
+export function decodeCarried(text: string): string;
+export interface ComparisonBase { text: string; sha256: string; revision: string; name: string; by: string; at: string; }
+export function readBase(value: Partial<ComparisonBase>): ComparisonBase;
+export function writeBase(text: string, value: Partial<ComparisonBase>): string;
+export function readBaseElements(elements: unknown): ComparisonBase | null;
+export function takeBase(html: string): {html: string; base: ComparisonBase | null};

package/dist/kit/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/kit/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/kit/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;