rapier-html 1.1.1 → 1.1.2

package/BUILD.json

@@ -1,10 +1,10 @@
 {
   "package": "rapier-html",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "path": "rapier.html",
-  "bytes": 1736480,
-  "sha256": "e040386098ff5cbb2234780c6068ba0f3a1a5b3a8ac64e061ce9e52e15cc0504",
-  "builtAt": "2026-09-26T16:17:27.420Z",
+  "bytes": 1814968,
+  "sha256": "14f9723eb1d16fdeb39830aed5cbb0d4a71d304c7f859cbcc0662fbd7fafff3a",
+  "builtAt": "2026-09-27T17:48:31.488Z",
   "node": "v22.22.2",
   "canonical": true,
   "packing": "zopfli",

package/README.md

@@ -9,6 +9,7 @@ npx -- rapier-html notes.md --view draw              # opens on Draw: sketch and
 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
 ```
@@ -46,6 +47,32 @@ The first `--` is for npm, so `--help` reaches the command. It never overwrites
 **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
 
@@ -62,15 +89,16 @@ 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})` and `unwrap(pageHtml)`,
-which returns `{html, text, name, view, drawing, drawingName, base, baseName}` with `null` for what a
+`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`.
 
 ## 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 block holds no `<`
+`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.
@@ -78,10 +106,12 @@ fact of the file and written back on Save.
 ## Safety
 
 - 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 and a third filename are
-  refused too.
+  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, or the math, diagram and PDF-import helpers on first use.
+  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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rapier-html",
-  "version": "1.1.1",
+  "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",
@@ -33,6 +33,7 @@
   "files": [
     "cli.mjs",
     "page.mjs",
+    "return-address.mjs",
     "rapier.html",
     "README.md",
     "LICENSE",

package/page.mjs

@@ -1,5 +1,6 @@
 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"';
@@ -30,7 +31,11 @@ export function wrap(pageHtml, text, name, 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 block = START + ' data-name="' + docName + '"' + (opts.view ? ' data-view="' + opts.view + '"' : '') + '>' + encodeCarried(text) + END;
+	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');
@@ -52,13 +57,18 @@ export function wrap(pageHtml, text, name, options) {
 	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;
+	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);
@@ -83,20 +93,22 @@ export function unwrap(pageHtml) {
 		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 {html, text, name, view, drawing, drawingName, base, baseName, return: address, return_expires_at: expiry};
 }
 // 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]\n' +
+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, basePath = null, view = 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);
@@ -110,6 +122,14 @@ export async function main(argv, pagesDir, {log = console.log} = {}) {
 			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];
@@ -124,6 +144,8 @@ export async function main(argv, pagesDir, {log = console.log} = {}) {
 	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; }