rapier-html 1.1.59 → 1.1.63

package/BUILD.json

@@ -1,10 +1,10 @@
 {
   "package": "rapier-html",
-  "version": "1.1.59",
+  "version": "1.1.63",
   "path": "dist/rapier.html",
-  "bytes": 1796536,
-  "sha256": "18cae9996bc9e90f3f73ca8b33b16b6f5dcf1c541b63b3c39d4abb8fa8b1b2f1",
-  "builtAt": "2026-10-04T09:37:04.001Z",
+  "bytes": 1841901,
+  "sha256": "b320b93379a1b2d52c03db9a8494f14c187e3b8e1c6535a42aad679387a65718",
+  "builtAt": "2026-10-05T06:48:14.140Z",
   "node": "v22.22.2",
   "canonical": true,
   "packing": "zopfli",

package/README.md

@@ -14,14 +14,14 @@ editor, offline, with the document inside.
 Node 22 or newer.
 
 ```sh
-npx -- rapier-html@1.1.59 notes.md                          # the editor, notes.md inside it, written beside the file
-npx -- rapier-html@1.1.59 notes.md --view draw              # opens on Draw: sketch and paint, the document behind it
-npx -- rapier-html@1.1.59 notes.md --view notes             # opens the Notes library
-npx -- rapier-html@1.1.59 notes.md --drawing sketch.svg     # carries a drawing, opened on Draw over the document
-npx -- rapier-html@1.1.59 proposal.md --base original.md    # opens on the diff of a proposed change
-npx -- rapier-html@1.1.59 notes.md --return "$RETURN_URL" --return-expires-at "$RETURN_EXPIRES_AT" # Send back
-npx -- rapier-html@1.1.59 notes.md out.html                 # a named output
-npm install rapier-html@1.1.59                              # as a library: wrap, unwrap
+npx -- rapier-html@1.1.63 notes.md                          # the editor, notes.md inside it, written beside the file
+npx -- rapier-html@1.1.63 notes.md --view draw              # opens on Draw: sketch and paint, the document behind it
+npx -- rapier-html@1.1.63 notes.md --view notes             # opens the Notes library
+npx -- rapier-html@1.1.63 notes.md --drawing sketch.svg     # carries a drawing, opened on Draw over the document
+npx -- rapier-html@1.1.63 proposal.md --base original.md    # opens on the diff of a proposed change
+npx -- rapier-html@1.1.63 notes.md --return "$RETURN_URL" --return-expires-at "$RETURN_EXPIRES_AT" # Send back
+npx -- rapier-html@1.1.63 notes.md out.html                 # a named output
+npm install rapier-html@1.1.63                              # as a library: wrap, unwrap
 ```
 
 The first `--` is for npm, so `--help` reaches the command. It never overwrites a file.

package/dist/ledger/carried.mjs

@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: MIT
 import {readLedger} from './format.mjs';
+import {sha256} from './hash.mjs';
 import {authorship as projectAuthorship, readAuthorship} from './authorship.mjs';
 import {canonicalJSON, fault} from './data.mjs';
 export function encodeCarried(text) {
@@ -67,3 +68,53 @@ export function readDocument(source) {
   const text = source.slice(0, at);
   return {text, ...validateParts(text, parts)};
 }
+
+// One portable baseline. A digest is integrity evidence, not authentication of the named proposer.
+export function readBase(value) {
+  if (!value || typeof value !== 'object' || typeof value.text !== 'string' ||
+      typeof value.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(value.sha256) || sha256(value.text) !== value.sha256)
+    throw fault('proposal base SHA-256 differs from its text');
+  if (typeof value.revision !== 'string' || !value.revision || value.revision.length > 256 || /[\u0000-\u001f\u007f]/.test(value.revision))
+    throw fault('invalid proposal base revision');
+  if (typeof value.name !== 'string' || !value.name || value.name.length > 255 || /[\\/\u0000-\u001f\u007f]/.test(value.name))
+    throw fault('invalid proposal base name');
+  if (typeof value.by !== 'string' || !value.by.trim() || value.by.length > 96 || /[\u0000-\u001f\u007f]/.test(value.by))
+    throw fault('a proposal needs its proposer name');
+  if (typeof value.at !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/.test(value.at) || !Number.isFinite(Date.parse(value.at)))
+    throw fault('the time of a proposal is an ISO 8601 UTC timestamp');
+  return {text: value.text, sha256: value.sha256, revision: value.revision, name: value.name, by: value.by, at: value.at};
+}
+const escapeAttribute = value => value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const readAttribute = value => value.replace(/&(quot|lt|gt|amp);/g, (_, name) => ({quot: '"', lt: '<', gt: '>', amp: '&'})[name]);
+export function writeBase(text, value) {
+  if (value == null) return '';
+  const base = readBase(value);
+  if (base.text === text) return '';
+  return '<script type="text/markdown" id="rapier-base"' + ['name', 'sha256', 'revision', 'by', 'at']
+    .map(key => ' data-' + key + '="' + escapeAttribute(base[key]) + '"').join('') + '>' + encodeCarried(base.text) + '</script>';
+}
+export function readBaseElements(elements) {
+  const rows = [...elements].filter(element => element.id === 'rapier-base');
+  if (!rows.length) return null;
+  const row = rows[0];
+  if (rows.length !== 1 || row.type !== 'text/markdown' || (row.tagName && row.tagName.toLowerCase() !== 'script'))
+    throw fault('duplicate or executable proposal base');
+  const get = name => row.getAttribute ? row.getAttribute('data-' + name) : row[name];
+  return readBase({text: decodeCarried(row.textContent), ...Object.fromEntries(['name', 'sha256', 'revision', 'by', 'at'].map(key => [key, get(key)]))});
+}
+export function takeBase(html) {
+  const elements = [];
+  const stripped = html.replace(/<script\b([^>]*)>([\s\S]*?)<\/script\s*>/gi, (whole, attrs, content) => {
+    const pairs = [...attrs.matchAll(/(?:^|\s)([\w-]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+))/g)].map(m => [m[1].toLowerCase(), readAttribute(m[2] ?? m[3] ?? m[4])]);
+    if (!pairs.some(([key, value]) => key === 'id' && value === 'rapier-base')) return whole;
+    const seen = new Set(), values = {};
+    for (const [key, value] of pairs) {
+      if (seen.has(key)) throw fault('ambiguous proposal base');
+      seen.add(key); values[key] = value;
+    }
+    elements.push({id: values.id, type: values.type, textContent: content,
+      ...Object.fromEntries(['name', 'sha256', 'revision', 'by', 'at'].map(key => [key, values['data-' + key]]))});
+    return '';
+  });
+  return {html: stripped, base: readBaseElements(elements)};
+}

package/dist/page.mjs

@@ -1,127 +1,17 @@
-import {encodeCarried, decodeCarried, writeParts, takeParts, readDocument} from './ledger/carried.mjs';
+// SPDX-License-Identifier: MIT
 import {readFile, writeFile} from 'node:fs/promises';
 import {basename, dirname, join} from 'node:path';
-import {PAGE_SEED, returnAddress, returnExpiresAt} from './return-address.mjs';
-
-const START = '<script type="text/markdown" id="rapier-document"';
-const DRAWING_START = '<script type="text/plain" id="rapier-drawing"';
-// The text the document was proposed against (docs/page-door.md, "2. A change carried"): the page opens on its diff.
-const BASE_START = '<script type="text/markdown" id="rapier-base"';
-const END = '</script>';
-// The page's search words (rapier.html's RAPIER_SEO regions: description, canonical address, previews, structured data and the plain guide
-// a crawler reads) are rapier.website's own. A page that carries someone's document never claims that address or that description.
-const SEARCH_WORDS = /<!-- RAPIER_SEO_BEGIN -->[\s\S]*?<!-- RAPIER_SEO_END -->\n?/g;
-
-// One encoding, exactly reversible (docs/page-door.md, "What a block may hold"): no `<` before `/` or `!`, no CR, no NUL.
-// engine.js _rapierDecodeCarried is its inverse.
-export {encodeCarried, decodeCarried};
-
-const PROPOSED_AT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
-const attribute = text => text.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-const unattribute = text => text.replace(/&(quot|lt|gt|amp);/g, (_, e) => ({quot: '"', lt: '<', gt: '>', amp: '&'})[e]);
-function safeName(name, fallback) {
-	return String(name || fallback).replace(/[\\/\0"<>&]/g, '-').slice(0, 255) || fallback;
-}
-
-export function wrap(pageHtml, text, name, options) {
-	if (typeof pageHtml !== 'string' || !pageHtml.includes('</body>')) throw new Error('not a Rapier page: no </body>');
-	if (typeof text !== 'string') throw new Error('the document must be text');
-	const saved = readDocument(text);
-	text = saved.text;
-	const opts = {...saved, ...(options || {})};
-	const docName = safeName(name, 'document.md');
-	// `view`: the view the page opens on with the document behind it, `draw` or `notes` (docs/page-door.md).
-	if (opts.view != null && !['draw', 'notes'].includes(opts.view)) throw new Error('the view is draw or notes');
-	const address = opts.return == null ? null : returnAddress(opts.return);
-	const expiry = opts.return_expires_at == null ? null : returnExpiresAt(opts.return_expires_at);
-	if (!!address !== !!expiry) throw new Error('a return needs its URL and return_expires_at from document.create_return');
-	const block = START + ' data-name="' + docName + '"' + (opts.view ? ' data-view="' + opts.view + '"' : '') +
-		(address ? ' data-return="' + address + '" data-return-expires-at="' + expiry + '"' : '') + '>' + encodeCarried(text) + END;
-	let carriedBlocks = '\n' + writeParts(text, opts);
-	if (opts.drawing != null) {
-		if (typeof opts.drawing !== 'string') throw new Error('the drawing must be SVG text');
-		const drawingName = safeName(opts.drawingName, 'drawing.svg');
-		carriedBlocks += '\n' + DRAWING_START + ' data-name="' + drawingName + '">' + encodeCarried(opts.drawing) + END;
-	}
-	if ((opts.by != null || opts.at != null) && opts.base == null) throw new Error('a proposer needs the base it proposes over');
-	if (opts.base != null) {
-		if (typeof opts.base !== 'string') throw new Error('the base must be text');
-		// As with the proposed document, validate saved parts before carrying only their source.
-		// A mismatched history is refused here, never displayed as part of the baseline.
-		const base = readDocument(opts.base).text;
-		// A proposal page (docs/briefs/ledger.md section 3): who proposed it, in the host's own words, and when.
-		const by = opts.by == null ? null : String(opts.by).replace(/[\0-\x1f\x7f]/g, ' ').trim().slice(0, 96);
-		const at = opts.at == null ? null : String(opts.at);
-		if (at != null && !(PROPOSED_AT.test(at) && Number.isFinite(Date.parse(at)))) throw new Error('the time of a proposal is an ISO 8601 UTC timestamp');
-		// Equal versions are a first draft, not a second carried document.
-		if (base !== text) carriedBlocks += '\n' + BASE_START + ' data-name="' + safeName(opts.baseName, docName) + '"' + (by ? ' data-by="' + attribute(by) + '"' : '') +
-			(at ? ' data-at="' + at + '"' : '') + '>' + encodeCarried(base) + END;
-	}
-	// The agent seed goes after the charset (or <head>), once: a page that already carries it, wrapped again, loses its old one.
-	const unseeded = unwrap(pageHtml).html.replace(SEARCH_WORDS, '').split(PAGE_SEED + '\n').join('');
-	const headTag = /<meta charset[^>]*>\n?/i.exec(unseeded) || /<head[^>]*>\n?/.exec(unseeded);
-	if (!headTag) throw new Error('not a Rapier page: no <head>');
-	const seededAt = headTag.index + headTag[0].length;
-	const stripped = unseeded.slice(0, seededAt) + PAGE_SEED + '\n' + unseeded.slice(seededAt);
-	// Before Rapier's scripts: parsed before the engine boots.
-	const bodyTag = /<body[^>]*>/.exec(stripped);
-	if (!bodyTag) throw new Error('not a Rapier page: no <body>');
-	const at = bodyTag.index + bodyTag[0].length;
-	// A function, not a string: `$'`, `$&` and `` $` `` are replacement patterns.
-	const titled = stripped.replace(/<title>[^<]*<\/title>/, () => '<title>' + docName.replace(/&/g, '&amp;').replace(/</g, '&lt;') + ' — Rapier</title>');
-	const shift = titled.length - stripped.length;
-	return titled.slice(0, at + shift) + '\n' + block + carriedBlocks + titled.slice(at + shift);
-}
-export function unwrap(pageHtml) {
-	let html = pageHtml, text = null, name = null, view = null, address = null, expiry = null;
-	const a = pageHtml.indexOf(START);
-	if (a >= 0) {
-		const open = pageHtml.indexOf('>', a), b = pageHtml.indexOf(END, open);
-		if (open < 0 || b < 0) throw new Error('a carried document without its end');
-		name = /data-name="([^"]*)"/.exec(pageHtml.slice(a, open))?.[1] ?? null;
-		view = /data-view="(draw|notes)"/.exec(pageHtml.slice(a, open))?.[1] ?? null;
-		const carriedReturn = /data-return="([^"]*)"/.exec(pageHtml.slice(a, open));
-		if (carriedReturn) address = returnAddress(carriedReturn[1]);
-		const carriedExpiry = /data-return-expires-at="([^"]*)"/.exec(pageHtml.slice(a, open));
-		if (carriedExpiry) expiry = returnExpiresAt(carriedExpiry[1]);
-		if (!!address !== !!expiry) throw new Error('a carried return needs its URL and return_expires_at');
-		text = decodeCarried(pageHtml.slice(open + 1, b));
-		html = pageHtml.slice(0, a) + pageHtml.slice(b + END.length);
-		if (a > 0 && html[a - 1] === '\n') html = html.slice(0, a - 1) + html.slice(a);
-	}
-	let drawing = null, drawingName = null;
-	const d = html.indexOf(DRAWING_START);
-	if (d >= 0) {
-		const open = html.indexOf('>', d), b = html.indexOf(END, open);
-		if (open < 0 || b < 0) throw new Error('a carried drawing without its end');
-		drawingName = /data-name="([^"]*)"/.exec(html.slice(d, open))?.[1] ?? null;
-		drawing = decodeCarried(html.slice(open + 1, b));
-		html = html.slice(0, d) + html.slice(b + END.length);
-		if (d > 0 && html[d - 1] === '\n') html = html.slice(0, d - 1) + html.slice(d);
-	}
-	let base = null, baseName = null, by = null, at = null;
-	const e = html.indexOf(BASE_START);
-	if (e >= 0) {
-		const open = html.indexOf('>', e), b = html.indexOf(END, open);
-		if (open < 0 || b < 0) throw new Error('a carried base without its end');
-		baseName = /data-name="([^"]*)"/.exec(html.slice(e, open))?.[1] ?? null;
-		const proposer = /data-by="([^"]*)"/.exec(html.slice(e, open))?.[1];
-		by = proposer == null ? null : unattribute(proposer);
-		at = /data-at="([^"]*)"/.exec(html.slice(e, open))?.[1] ?? null;
-		base = decodeCarried(html.slice(open + 1, b));
-		html = html.slice(0, e) + html.slice(b + END.length);
-		if (e > 0 && html[e - 1] === '\n') html = html.slice(0, e - 1) + html.slice(e);
-	}
-	const parts = takeParts(html, text);
-	return {...parts, text, name, view, drawing, drawingName, base, baseName, by, at, return: address, return_expires_at: expiry};
-}
+import {wrap} from './wrap.mjs';
+import {returnAddress, returnExpiresAt} from './return-address.mjs';
+export {wrap, unwrap, encodeCarried, decodeCarried} from './wrap.mjs';
 // Unknown options, a bare --drawing or --base and a third name are refused, never dropped.
 const USAGE = 'usage: rapier-html <document.md> [out.html] [--view draw|notes] [--drawing sketch.svg] [--base 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' +
 	'  --view      opens the page on Draw (sketch and paint, the document behind it) or on Notes\n' +
 	'  --drawing   carries an SVG drawing alongside the document, opened on Draw as the page boots\n' +
-	'  --base      carries the text the document was proposed against; the page opens on their diff\n' +
+	'  --propose   <base.md> <proposed.md>: carries the original base for per-change review\n' +
+	'  --base      the older spelling of --propose; carries the text the document was proposed against; the page opens on their diff\n' +
 	'  --by        with --base: who proposes it, shown on the diff with the time the page was made\n' +
 	'  --return    carries a one-use return URL from document.create_return; Share offers Send back\n' +
 	'  --return-expires-at  carries the same mint\'s expiry; Share offers Save once the return expires\n' +
@@ -139,7 +29,7 @@ export async function main(argv, pagesDir, {log = console.log} = {}) {
 			if (view !== null || !['draw', 'notes'].includes(argv[i + 1])) throw new Error('--view takes draw or notes');
 			view = argv[++i];
 		}
-		else if (arg === '--base') {
+		else if (arg === '--base' || arg === '--propose') {
 			if (basePath !== null || !argv[i + 1] || argv[i + 1].startsWith('-')) throw new Error('--base takes one text file (write a name that starts with a dash as ./-original.md)');
 			basePath = argv[++i];
 		}
@@ -168,7 +58,7 @@ export async function main(argv, pagesDir, {log = console.log} = {}) {
 	const wrapOptions = {};
 	if (drawingPath) { wrapOptions.drawing = await readFile(drawingPath, 'utf8'); wrapOptions.drawingName = basename(drawingPath); }
 	if (by !== null && !basePath) throw new Error('--by names who proposes a change: give the --base it proposes over');
-	if (basePath) { wrapOptions.base = await readFile(basePath, 'utf8'); wrapOptions.baseName = basename(basePath); }
+	if (basePath) { wrapOptions.base = await readFile(basePath, 'utf8'); wrapOptions.baseName = basename(basePath); wrapOptions.at = new Date().toISOString(); }
 	if (by !== null) { wrapOptions.by = by; wrapOptions.at = new Date().toISOString(); }
 	if (view) wrapOptions.view = view;
 	if (address) wrapOptions.return = address;