rapier-html 1.1.0

package/README.md

@@ -0,0 +1,87 @@
+# 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:
+
+```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
+```
+
+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`.
+
+## As a library
+
+Save this as `example.mjs` in the folder you installed into (`npm install rapier-html`) 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
+```
+
+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.
+
+## Licence
+
+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.
+
+## The page inside
+
+Its version is the version of the Rapier inside it. `BUILD.json` records the page's size, SHA-256, build time and Node version.

package/cli.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import {dirname} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {main} from './page.mjs';
+main(process.argv.slice(2), dirname(fileURLToPath(import.meta.url))).catch(error => { console.error(String(error?.message || error)); process.exit(1); });

package/package.json

@@ -0,0 +1,42 @@
+{
+  "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.",
+  "keywords": [
+    "markdown",
+    "editor",
+    "offline",
+    "single-file",
+    "html",
+    "agent",
+    "mcp",
+    "rapier"
+  ],
+  "author": "Jack Skipworth",
+  "license": "AGPL-3.0-only",
+  "homepage": "https://rapier.website",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jackskip22/rapier-plugins.git",
+    "directory": "npm/rapier-html"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "rapier-html": "cli.mjs"
+  },
+  "exports": {
+    ".": "./page.mjs"
+  },
+  "files": [
+    "cli.mjs",
+    "page.mjs",
+    "rapier.html",
+    "README.md",
+    "LICENSE",
+    "BUILD.json"
+  ],
+  "sideEffects": false
+}

package/page.mjs

@@ -0,0 +1,102 @@
+import {readFile, writeFile} from 'node:fs/promises';
+import {basename, dirname, join} from 'node:path';
+
+const START = '<script type="text/markdown" id="rapier-document"';
+const DRAWING_START = '<script type="text/plain" id="rapier-drawing"';
+const END = '</script>';
+
+// 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.
+function encodeCarried(text) {
+	return String(text).replace(/[\\\r\0]|<[/!]/g, m =>
+		m === '\\' ? '\\\\' : m === '\r' ? '\\r' : m === '\0' ? '\\0' : m === '</' ? '\\/' : '\\!');
+}
+function decodeCarried(text) {
+	return String(text).replace(/\\([\\/!r0])/g, (_, c) =>
+		c === '\\' ? '\\' : c === 'r' ? '\r' : c === '0' ? '\0' : c === '/' ? '</' : '<!');
+}
+export {encodeCarried, decodeCarried};
+
+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 opts = options || {};
+	const docName = safeName(name, 'document.md');
+	const block = START + ' data-name="' + docName + '">' + encodeCarried(text) + END;
+	let drawingBlock = '';
+	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;
+	}
+	const stripped = unwrap(pageHtml).html;
+	// 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 + drawingBlock + titled.slice(at + shift);
+}
+export function unwrap(pageHtml) {
+	let html = pageHtml, text = null, name = 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;
+		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);
+	}
+	return {html, text, name, drawing, drawingName};
+}
+// 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' +
+	'  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' +
+	'  --drawing   carries an SVG drawing alongside the document, opened on Draw as the page boots\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;
+	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 !== '--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];
+	}
+	if (names.length < 1 || names.length > 2) throw new Error(USAGE);
+	const [input, named] = names;
+	const text = await readFile(input, 'utf8');
+	const page = await readFile(join(pagesDir, 'rapier.html'), 'utf8');
+	const name = basename(input);
+	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); }
+	// 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' : '') + ')');
+	return out;
+}