rapier-html 1.1.0 → 1.1.2

package/BUILD.json

@@ -1,10 +1,10 @@
 {
   "package": "rapier-html",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "path": "rapier.html",
-  "bytes": 1733515,
-  "sha256": "b75dedcb78f9bd60ae04d896bbe3f4606b2127e6fa4275ada92c0b668c7e5694",
-  "builtAt": "2026-09-26T13:30:00.640Z",
+  "bytes": 1814968,
+  "sha256": "14f9723eb1d16fdeb39830aed5cbb0d4a71d304c7f859cbcc0662fbd7fafff3a",
+  "builtAt": "2026-09-27T17:48:31.488Z",
   "node": "v22.22.2",
   "canonical": true,
   "packing": "zopfli",

package/README.md

@@ -1,87 +1,120 @@
 # rapier-html
 
-Rapier with your document inside it. One command turns a Markdown file into a single HTML page
-that is the whole Rapier editor, carrying the document's exact text: it opens anywhere a browser
-is, offline, with no account. Read it, edit it, save it to the device, share it on. Agents hand
-people documents this way; people hand them back the same way.
-
-Nothing is fetched to open, edit or save the page, and nothing reports on its use. It goes to the
-network only when the document or the person asks: a picture or video the document links to on the
-web, or the math, diagram and PDF-import helpers, fetched once from a pinned CDN when first needed.
-
-## Use it
-
-Node 22 or newer:
+Rapier, the offline Markdown editor, as one HTML page with your document inside it. No account, no
+install, nothing fetched to open, edit or save. Node 22 or newer.
 
 ```sh
-npx -- rapier-html notes.md                       # writes notes.rapier.html beside it
-npx -- rapier-html notes.md out.html              # a named output
-npx -- rapier-html notes.md --drawing sketch.svg  # carries a drawing, opened on Draw as the page boots
-npx -- rapier-html --help
+npx -- rapier-html notes.md                          # the editor, notes.md inside it, written beside the file
+npx -- rapier-html notes.md --view draw              # opens on Draw: sketch and paint, the document behind it
+npx -- rapier-html notes.md --view notes             # opens on Notes: the document as cards
+npx -- rapier-html notes.md --drawing sketch.svg     # carries a drawing, opened on Draw over the document
+npx -- rapier-html proposal.md --base original.md    # opens on the diff of a proposed change
+npx -- rapier-html notes.md --return "$RETURN_URL" --return-expires-at "$RETURN_EXPIRES_AT" # Send back
+npx -- rapier-html notes.md out.html                 # a named output
+npm install rapier-html                              # as a library: wrap, unwrap
 ```
 
-The first `--` is for npm: without it `npx` keeps `--help`, and a later `--`, for itself.
-
-**It never overwrites a file.** An output that already exists -- the document itself included, or a
-link to it -- is refused and nothing is written; name a new one. An option it does not know, a
-`--drawing` with no file and a third filename are refused as well, so a typo cannot quietly make a
-different page. `--` makes everything after it a filename: `npx -- rapier-html -- --draft.md`.
+The first `--` is for npm, so `--help` reaches the command. It never overwrites a file.
+
+## What the page can do
+
+**Write**
+- Markdown the way it reads: headings, lists, checklists, tables, code, quotes, footnotes, pictures placed
+  around text.
+- Find and replace, Undo, a source view of the exact bytes.
+- Math and diagrams on demand, fetched once from a pinned address only when a document asks.
+
+**Draw and paint**
+- Shapes, lines, arrows, text on a canvas that goes into the document as a picture.
+- Paint with real brushes: pencil, pen, ink, watercolour that runs and dries, oil that mixes, a smudge
+  finger; dip the brush for more paint or more water.
+- Your own brush files, a dropper, paint laid over the drawing as a layer of its own.
+
+**Notes**
+- The document as cards: sections, drag to reorder, search across every note.
+- Voice recordings, reminders, a recycle bin that keeps seven days.
+- Import from Keep, Notion, Evernote, Joplin, Bear, Simplenote, OneNote, Obsidian and more.
+
+**Review a change**
+- Open on the diff of a proposal against the original; keep or drop each change; nothing applies until
+  the person says so.
+- Will markers in the Markdown say what an agent may change: `keep`, `append`, `edit`.
+
+**Keep it**
+- Save to the device, share the page on, open it again anywhere a browser is; offline throughout.
+- Export the document as Markdown or as a web page; print it.
+
+**For agents**
+- Hand a person a document, a sketch or a change as one file that opens with one click.
+- What they save comes back byte for byte through `unwrap`.
+- Add the return URL from `document.create_return`: the person edits the page and presses Send back;
+  `document.wait_for_user` wakes the agent, which reads the exact returned Markdown and continues.
+
+## Send an edited document back
+
+Call `document.create_return` on the Rapier agent door for the document's workspace. Pass its
+`return_url` and `return_expires_at` as `--return "$RETURN_URL" --return-expires-at "$RETURN_EXPIRES_AT"`
+or `wrap(..., {return: return_url, return_expires_at})`. Both values come from the same mint. Only the worker's
+HTTPS return route at `https://mcp.rapier.website/return/…` is accepted. The page shows Send back
+in Share; a page without an address has no such action.
+
+The person reads and edits offline, then presses Send back when ready. That press sends the current
+source and filename once, and shows acceptance or the worker's refusal. After acceptance, that page
+sends nothing again. Save to the device stays local. The return URL lasts up to one day, accepts one
+document up to 25 MiB, and grants no read or edit access to the agent's workspace.
+
+Once the carried expiry passes, Share offers Save in place of Send back: the work is safe on the page.
+A used or expired return refused by the worker offers the same Save. Saving keeps the current words,
+filename, byte-order mark and line endings through the normal local save path. Bring that file back to the
+assistant, which compares it against the workspace's current work and creates a fresh return for the next
+handoff; the old capability stays spent.
+
+The agent's `document.wait_for_user` returns a `returned` receipt with the `return_id`, name and time.
+`document.get_context` lists receipts even when no agent was waiting. Read the source with
+`document.read_context({return_id, start: 0})`, continuing at the returned `end` until `complete`.
+The returned copy stays separate from the workspace's current document, so newer work survives too.
 
 ## As a library
 
-Save this as `example.mjs` in the folder you installed into (`npm install rapier-html`) and run
-`node example.mjs`:
+Save this as `example.mjs` in the folder you installed into and run `node example.mjs`:
 
 ```js
 import {readFile, writeFile} from 'node:fs/promises';
 import {wrap, unwrap} from 'rapier-html';
 
-// The page inside the installed package.
 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');              // Rapier carrying the document
-// A drawing rides along, opened on Draw right after the document lands (Done places it in).
-const svg = '<svg xmlns="http://www.w3.org/2000/svg"><circle cx="8" cy="8" r="6"/></svg>';
-const both = wrap(rapier, words, 'hello.md', {drawing: svg, drawingName: 'sketch.svg'});
-
-console.log('words back exactly:', unwrap(page).text === words, '| drawing back exactly:', unwrap(both).drawing === svg);
-await writeFile('hello.rapier.html', page, {flag: 'wx'});   // 'wx': never over an existing file
+const page = wrap(rapier, 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
 ```
 
-It prints `words back exactly: true | drawing back exactly: true` and writes `hello.rapier.html`.
-The package exports `wrap`, `unwrap`, `encodeCarried`, `decodeCarried` and the command's `main`;
-`unwrap` returns `{html, text, name, drawing, drawingName}`, with `null` for what a page does not
-carry.
-
-## What the page carries
-
-The page carries the document as one `<script type="text/markdown" id="rapier-document">` block
-at the top of the body; the browser never executes it and Rapier reads it once at boot in place
-of the Welcome. A second, optional `<script type="text/plain" id="rapier-drawing">` block carries
-a drawing Rapier made (its SVG carries the drawing's recipe in its own metadata); Rapier opens Draw
-on that recipe once the document is up, the document behind it. Wrapping is a byte insertion, not
-a build: a second wrap replaces the blocks it is given.
-
-**Your words come back byte for byte, whatever is in them.** A script element's text is not inert
-to an HTML parser: `<!--` followed by `<script` puts it in a state where the block's own
-`</script>` stops closing it and the rest of the page is swallowed, CRLF and a lone carriage
-return are rewritten to a newline, and NUL becomes U+FFFD. A note *about* HTML is enough to hit
-the first. So a carried block holds no `<` before `/` or `!`, no carriage return and no NUL: a
-backslash is written `\\`, `</` is `\/`, `<!` is `\!`, a carriage return is `\r`, a NUL is
-`\0`, and nothing else changes. One pass each way, exactly reversible, and the same size as your
-words except where they already held a backslash. A byte-order mark is kept as a fact of the file
-and written back on Save, not folded into the text.
-
-`unwrap` reverses exactly what `wrap` wrote, and the editor inside the page reads by the same law,
-so a page always reads its own bytes correctly. The command reads the document as UTF-8 text.
+`wrap(rapierHtml, text, name, {view, drawing, drawingName, base, baseName, return: returnURL, return_expires_at})` and `unwrap(pageHtml)`,
+which returns `{html, text, name, view, drawing, drawingName, base, baseName, return: returnURL, return_expires_at}` with `null` for what a
+page does not carry. Also exported: `encodeCarried`, `decodeCarried`, `main`.
 
-## Licence
+## How the page carries the document
+
+One `<script type="text/markdown" id="rapier-document">` block at the top of the body, never executed,
+read once at boot. A drawing rides in `id="rapier-drawing"`, the text a change was proposed against in
+`id="rapier-base"`, the view to open on in the document block's `data-view`, the optional return URL
+in `data-return` and its exact expiry in `data-return-expires-at`. The block holds no `<`
+before `/` or `!`, no carriage return and no NUL: `\\`, `\/`, `\!`, `\r` and `\0` stand for them, one
+reversible pass each way, so a note about HTML is as safe as any other. A byte-order mark is kept as a
+fact of the file and written back on Save.
 
-AGPL-3.0-only, the full text in `LICENSE`: the page is the Rapier editor, with the notices of the
-libraries it carries. For the Markdown standard without the editor there is `rapier-markdown-kit`
-(MIT). Rapier is https://rapier.website.
+## Safety
 
-## The page inside
+- It never overwrites: an output that exists, the document itself included, is refused. Unknown options,
+  a `--view` that is not `draw` or `notes`, a `--drawing` or `--base` with no file, a missing or repeated
+  `--return` or `--return-expires-at`, a return without its expiry, an invalid expiry, an unsafe return URL and a third filename are refused too.
+- Nothing reports on the page's use. It reaches the network only when the document or the person asks:
+  a picture or video the document links to, the math, diagram and PDF-import helpers on first use,
+  or the person's Send back press. A return URL names only the worker's exact origin and return route;
+  credentials, query strings and fragments are refused by both the writer and carried-page boot.
+
+## Licence
 
-Its version is the version of the Rapier inside it. `BUILD.json` records the page's size, SHA-256, build time and Node version.
+AGPL-3.0-only (`LICENSE`): the page is the Rapier editor with the notices of the libraries it carries.
+The Markdown standard without the editor is `rapier-markdown-kit` (MIT). Rapier is https://rapier.website.
+`BUILD.json` records the page's size, SHA-256, build time and Node version.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rapier-html",
-  "version": "1.1.0",
-  "description": "Rapier with your document inside it: wrap a Markdown file into a single offline HTML page that is the whole Rapier editor, opened anywhere a browser is.",
+  "version": "1.1.2",
+  "description": "Rapier, the offline Markdown editor, as one HTML page with your document inside it: write, draw and paint, notes, the diff of a change; no account, nothing fetched.",
   "keywords": [
     "markdown",
     "editor",
@@ -33,6 +33,7 @@
   "files": [
     "cli.mjs",
     "page.mjs",
+    "return-address.mjs",
     "rapier.html",
     "README.md",
     "LICENSE",

package/page.mjs

@@ -1,8 +1,11 @@
 import {readFile, writeFile} from 'node:fs/promises';
 import {basename, dirname, join} from 'node:path';
+import {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>';
 
 // One encoding, exactly reversible (docs/page-door.md, "What a block may hold"): no `<` before `/` or `!`, no CR, no NUL.
@@ -26,12 +29,22 @@ export function wrap(pageHtml, text, name, options) {
 	if (typeof text !== 'string') throw new Error('the document must be text');
 	const opts = options || {};
 	const docName = safeName(name, 'document.md');
-	const block = START + ' data-name="' + docName + '">' + encodeCarried(text) + END;
-	let drawingBlock = '';
+	// `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 = '';
 	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');
-		drawingBlock = '\n' + DRAWING_START + ' data-name="' + drawingName + '">' + encodeCarried(opts.drawing) + END;
+		carriedBlocks = '\n' + DRAWING_START + ' data-name="' + drawingName + '">' + encodeCarried(opts.drawing) + END;
+	}
+	if (opts.base != null) {
+		if (typeof opts.base !== 'string') throw new Error('the base must be text');
+		carriedBlocks += '\n' + BASE_START + ' data-name="' + safeName(opts.baseName, docName) + '">' + encodeCarried(opts.base) + END;
 	}
 	const stripped = unwrap(pageHtml).html;
 	// Before Rapier's scripts: parsed before the engine boots.
@@ -41,15 +54,21 @@ export function wrap(pageHtml, text, name, options) {
 	// 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 + drawingBlock + titled.slice(at + shift);
+	return titled.slice(0, at + shift) + '\n' + block + carriedBlocks + titled.slice(at + shift);
 }
 export function unwrap(pageHtml) {
-	let html = pageHtml, text = null, name = null;
+	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);
@@ -64,23 +83,53 @@ export function unwrap(pageHtml) {
 		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);
 	}
-	return {html, text, name, drawing, drawingName};
+	let base = null, baseName = 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;
+		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);
+	}
+	return {html, text, name, view, drawing, drawingName, base, baseName, return: address, return_expires_at: expiry};
 }
-// Unknown options, a bare --drawing and a third name are refused, never dropped.
-const USAGE = 'usage: rapier-html <document.md> [out.html] [--drawing sketch.svg]\n' +
+// 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] [--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' +
+	'  --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' +
 	'  --          everything after it is a filename, even one that starts with a dash\n' +
 	'  --help      this text';
 export async function main(argv, pagesDir, {log = console.log} = {}) {
 	const names = [];
-	let drawingPath = null, onlyNames = false;
+	let drawingPath = null, basePath = null, view = null, address = null, expiry = 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');
+			view = argv[++i];
+		}
+		else if (arg === '--base') {
+			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];
+		}
+		else if (arg === '--return') {
+			if (address !== null || !argv[i + 1] || argv[i + 1].startsWith('-')) throw new Error('--return takes one HTTPS return URL');
+			address = returnAddress(argv[++i]);
+		}
+		else if (arg === '--return-expires-at') {
+			if (expiry !== null || !argv[i + 1] || argv[i + 1].startsWith('-')) throw new Error('--return-expires-at takes one ISO timestamp from document.create_return');
+			expiry = returnExpiresAt(argv[++i]);
+		}
 		else if (arg !== '--drawing') throw new Error('unknown option ' + arg + '\n' + USAGE);
 		else if (drawingPath !== null || !argv[i + 1] || argv[i + 1].startsWith('-')) throw new Error('--drawing takes one SVG file (write a name that starts with a dash as ./-sketch.svg)');
 		else drawingPath = argv[++i];
@@ -93,10 +142,14 @@ export async function main(argv, pagesDir, {log = console.log} = {}) {
 	const out = named || join(dirname(input), name.replace(/\.(md|markdown|txt)$/i, '') + '.rapier.html');
 	const wrapOptions = {};
 	if (drawingPath) { wrapOptions.drawing = await readFile(drawingPath, 'utf8'); wrapOptions.drawingName = basename(drawingPath); }
+	if (basePath) { wrapOptions.base = await readFile(basePath, 'utf8'); wrapOptions.baseName = basename(basePath); }
+	if (view) wrapOptions.view = view;
+	if (address) wrapOptions.return = address;
+	if (expiry) wrapOptions.return_expires_at = expiry;
 	// R85b: always a new file; 'wx' refuses any existing path, links included.
 	try { await writeFile(out, wrap(page, text, name, wrapOptions), {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(text) + ' bytes of document' +
-		(drawingPath ? ', ' + basename(drawingPath) + ' drawing' : '') + ')');
+		(view ? ', opens on ' + (view === 'draw' ? 'Draw' : 'Notes') : '') + (drawingPath ? ', ' + basename(drawingPath) + ' drawing' : '') + (basePath ? ', its diff from ' + basename(basePath) : '') + ')');
 	return out;
 }