rapier-html 1.2.6 → 1.2.8

package/BUILD.json

@@ -1,10 +1,10 @@
 {
   "package": "rapier-html",
-  "version": "1.2.6",
+  "version": "1.2.8",
   "path": "dist/rapier.html",
-  "bytes": 4952859,
-  "sha256": "48b694df7db506a77f5a98e01098f37d54e7f9a88d6e5647ca09ea43578c3927",
-  "builtAt": "2026-10-16T12:09:12.607Z",
+  "bytes": 5936307,
+  "sha256": "93e8ba922a0df18a75196a1a87971ac80d61b5a4a06630512abb25c94a23ff3f",
+  "builtAt": "2026-10-17T01:08:23.274Z",
   "node": "v22.23.3",
   "canonical": true,
   "packing": "zopfli",
@@ -14,15 +14,15 @@
       "delivery": "built-in",
       "kind": "script",
       "element": "rapier-plugin-math",
-      "bytes": 691650,
-      "packedBytes": 438088,
+      "bytes": 695410,
+      "packedBytes": 439180,
       "files": [
         {
           "id": "rapier-math",
-          "name": "rapier-math-2.4.0.js",
-          "version": "2.4.0",
-          "bytes": 691650,
-          "sri": "C92x26+pBI4q9FoWypMhBb8CqSGaaPLw8dpYigWiYNsYQRTcPVrFyPVjrhc/Tnwh"
+          "name": "rapier-math-2.5.0.js",
+          "version": "2.5.0",
+          "bytes": 695410,
+          "sri": "VDN0hcZbJ7LFS7fJjiUV/8THDfLxUWNfbGZQkggQptiaw4JaNAjZOmyK0kDRLNN3"
         }
       ]
     },

package/README.md

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

package/dist/cli.mjs

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

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

@@ -1,14 +1,26 @@
 // SPDX-License-Identifier: MIT
 import {readFile, writeFile} from 'node:fs/promises';
 import {basename, dirname, join} from 'node:path';
-import {wrap} from './wrap.mjs';
+import {wrap, carry, portableNeeds} from './wrap.mjs';
 import {returnAddress, returnExpiresAt} from './return-address.mjs';
-export {wrap, unwrap, encodeCarried, decodeCarried} from './wrap.mjs';
+export {wrap, unwrap, carry, portableNeeds, encodeCarried, decodeCarried} from './wrap.mjs';
+
+// The page this package carries, read once on first use.
+let carried = null;
+const carriedPage = () => carried ??= readFile(new URL('./rapier.html', import.meta.url), 'utf8');
+// One call from Markdown to a page: the carried editor, cut to what the document displays with (and Draw for
+// view 'draw' or a drawing), with the document inside. `include` names the parts instead: drawing, math, mermaid.
+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);
+}
 // Unknown options, a bare --drawing or --compare and a third name are refused.
-const USAGE = 'usage: rapier-html <document.md> [out.html] [--view draw|notes] [--drawing sketch.svg] [--compare original.md [--by <your name>]] [--return <url> --return-expires-at <timestamp>]\n' +
+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' +
-	'  --view      opens the page on Draw (sketch and paint, the document behind it) or on Notes\n' +
+	'  --include   what the file carries beyond the base editor: draw (drawing and painting), math, mermaid, or none;\n' +
+	'              by default, the plug-ins the document displays with, and Draw for --view draw or --drawing\n' +
+	'  --view      draw: opens the page on Draw (sketch and paint, the document behind it)\n' +
 	'  --drawing   carries an SVG drawing alongside the document, opened on Draw as the page boots\n' +
 	'  --compare   carries the original text; the page opens showing its diff from the current document\n' +
 	'  --by        with --compare: the name shown on the diff with the time the page was made\n' +
@@ -21,16 +33,22 @@ const text = async path => { try { return new TextDecoder('utf-8', {fatal: true,
 
 export async function main(argv, pagesDir, {log = console.log} = {}) {
 	const names = [];
-	let drawingPath = null, basePath = null, by = null, view = null, address = null, expiry = null, onlyNames = false;
+	let drawingPath = null, basePath = null, by = null, view = null, address = null, expiry = null, include = null, onlyNames = false;
 	for (let i = 0; i < argv.length; i++) {
 		const arg = argv[i];
 		if (onlyNames || !arg.startsWith('-')) names.push(arg);
 		else if (arg === '--') onlyNames = true;
 		else if (arg === '--help') { log(USAGE); return null; }
 		else if (arg === '--view') {
-			if (view !== null || !['draw', 'notes'].includes(argv[i + 1])) throw new Error('--view takes draw or notes');
+			if (view !== null || argv[i + 1] !== 'draw') throw new Error('--view takes draw');
 			view = argv[++i];
 		}
+		else if (arg === '--include') {
+			const listed = argv[i + 1] === 'none' ? [] : String(argv[i + 1] || '').split(',');
+			if (include !== null || listed.some(item => !['draw', 'math', 'mermaid'].includes(item))) throw new Error('--include takes draw, math and mermaid, comma-separated, or none');
+			include = listed.map(item => item === 'draw' ? 'drawing' : item);
+			i++;
+		}
 		else if (arg === '--compare') {
 			if (basePath !== null || !argv[i + 1] || argv[i + 1].startsWith('-')) throw new Error('--compare takes one text file (write a name that starts with a dash as ./-original.md)');
 			basePath = argv[++i];
@@ -66,9 +84,12 @@ export async function main(argv, pagesDir, {log = console.log} = {}) {
 	if (address) wrapOptions.return = address;
 	if (expiry) wrapOptions.return_expires_at = expiry;
 	// Always a new file; 'wx' refuses any existing path, links included.
-	try { await writeFile(out, wrap(page, source, name, wrapOptions), {flag: 'wx'}); }
+	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'}); }
 	catch (error) { throw error.code === 'EEXIST' ? new Error(out + ' already exists, and rapier-html never overwrites a file: name a new one') : error; }
-	log(out + ' (' + name + ', ' + Buffer.byteLength(source) + ' bytes of document' +
-		(view ? ', opens on ' + (view === 'draw' ? 'Draw' : 'Notes') : '') + (drawingPath ? ', ' + basename(drawingPath) + ' drawing' : '') + (basePath ? ', its diff from ' + basename(basePath) : '') + ')');
+	const labels = {drawing: 'Draw', math: 'Math', mermaid: 'Mermaid'};
+	log(out + ' (' + name + ', ' + Buffer.byteLength(source) + ' bytes of document, ' + Buffer.byteLength(html) + ' bytes in all, the base editor' +
+		[...new Set(carries)].map(id => ' + ' + labels[id]).join('') + (view ? ', opens on Draw' : '') + (drawingPath ? ', ' + basename(drawingPath) + ' drawing' : '') + (basePath ? ', its diff from ' + basename(basePath) : '') + ')');
 	return out;
 }