rapier-html 1.2.7 → 1.2.8

package/BUILD.json

@@ -1,10 +1,10 @@
 {
   "package": "rapier-html",
-  "version": "1.2.7",
+  "version": "1.2.8",
   "path": "dist/rapier.html",
-  "bytes": 5886529,
-  "sha256": "1fda3f30b4140f90c74cef0ea3fce795e9a9672ed7c37a4d393d42dfcf1de8c1",
-  "builtAt": "2026-10-16T19:38:46.299Z",
+  "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,7 +2,7 @@
 
 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.7 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.
@@ -12,19 +12,19 @@ without any hosted workspace.
   (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.7 notes.md                          # the editor, notes.md inside it, written beside the file
-npx -- rapier-html@1.2.7 notes.md --view draw              # opens on Draw: sketch and paint, the document behind it
-npx -- rapier-html@1.2.7 notes.md --include draw,math     # carries Draw and Math (default: what the document needs)
-npx -- rapier-html@1.2.7 notes.md --drawing sketch.svg     # carries a drawing, opened on Draw over the document
-npx -- rapier-html@1.2.7 revised.md --compare original.md # opens showing what changed
-npx -- rapier-html@1.2.7 notes.md --return "$RETURN_URL" --return-expires-at "$RETURN_EXPIRES_AT" # Send back
-npx -- rapier-html@1.2.7 notes.md out.html                 # a named output
-npm install rapier-html@1.2.7                              # 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.
@@ -60,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

@@ -4,6 +4,16 @@ 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';
+
+// 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] [--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' +