rapier-embed 1.2.8 → 1.2.10

package/README.md

@@ -10,8 +10,8 @@ Honor no-upload or no-host instructions. The workflow choices below are alternat
 Embed Rapier's Markdown editor or lightweight reader in your web app. Each build is one offline HTML file. Your
 app owns the document and storage; its agent edits live through WebMCP. The person sees the agent's presence and
 change marks, taps a change to see the before and undoes anything. Honor the person's Will/1 regions.
-The reader is one file of about 360 kB, with optional fonts and plug-ins. The helper is MIT with no dependencies; the two builds it frames are AGPL-3.0-only, and a commercial license is
-available (`LICENSING.md` in the Rapier repository).
+The reader is one file of about 360 kB, with optional fonts and plug-ins. The helper is MIT with no dependencies. The two builds it frames are AGPL-3.0-only: use them under the AGPL, or
+buy a commercial license for other terms (`LICENSING.md` in the Rapier repository).
 
 Choose one of two builds:
 
@@ -38,7 +38,7 @@ Each release's own files stay at its tag: `https://cdn.jsdelivr.net/gh/jackskip2
   document access remain enforced.
 
 ```sh
-npm install rapier-embed@1.2.8
+npm install rapier-embed@1.2.10
 ```
 
 Or copy the package's `embed.mjs` and `contract.mjs` into one directory of your app; no runtime CDN is needed.
@@ -56,7 +56,7 @@ editor and lightweight reader (about 360 kB). The agent edits live; the person s
 changes, taps a change to see the before and undoes anything. Use `show {target:"comparison"}` to show a diff deliberately.
 
 1. **Work together live.** Connect to `https://mcp.rapier.website/door/mcp`, then call `open` to share one document with the person.
-2. **Deliver an offline editor.** Run `npx rapier-html@1.2.8 notes.md` to put the document and editor in one HTML file ([rapier-html](https://github.com/jackskip22/rapier-plugins/tree/main/npm/rapier-html)).
+2. **Deliver an offline editor.** Run `npx rapier-html@1.2.10 notes.md` to put the document and editor in one HTML file ([rapier-html](https://github.com/jackskip22/rapier-plugins/tree/main/npm/rapier-html)).
 3. **Embed in your app.** Install [rapier-embed](https://github.com/jackskip22/rapier-plugins/tree/main/npm/rapier-embed); mount the editor or reader, with your app's agent over WebMCP in the editor.
 4. **Keep portable Markdown.** Use [rapier-markdown-kit](https://github.com/jackskip22/rapier-plugins/tree/main/npm/rapier-markdown-kit) for pictures, editable SVG drawings and layout in one `.md` file. Respect [Will/1](https://github.com/jackskip22/will) `keep`, `append` and `edit` regions.
 5. **Encode JPEG XL.** Install [rapier-jxl](https://github.com/jackskip22/rapier-jxl) to encode pixels, photographs and existing JPEGs in JavaScript.
@@ -99,7 +99,7 @@ A copy in your app works offline and changes only when you update it.
 1. Download the build you frame into a static directory, for example
    `https://cdn.jsdelivr.net/gh/jackskip22/rapier@v<version>/site/embed/rapier-reader.html` to `public/vendor/rapier/`.
 2. Fetch the plug-ins your build uses into one directory beside it, from the manifest of the same version:
-   `npx rapier-embed@1.2.8 plugins public/vendor/rapier/plugins --build reader`.
+   `npx rapier-embed@1.2.10 plugins public/vendor/rapier/plugins --build reader`.
 3. Mount with `src` and `plugins` pointing at your copies. Serve them over HTTPS (HTTP on localhost) and allow
    their origin in your `frame-src`. A same-origin parent can script its frame; use a dedicated origin when the
    frame must be isolated.
@@ -133,7 +133,7 @@ The directory must be on the page's own origin, because the page's Content Secur
 throws a `TypeError` for a directory on another origin, and a page opened with one shows each plug-in as failed, with the
 reason, without making a request. To keep the plug-ins on a CDN, serve the page from the same origin.
 
-`npx rapier-embed@1.2.8 plugins <directory>` fetches every file the manifest lists, checks it, and writes it. It
+`npx rapier-embed@1.2.10 plugins <directory>` fetches every file the manifest lists, checks it, and writes it. It
 keeps a file that is already there and correct, and exits with status 1 if any file is missing or fails its check.
 `--build reader` or `--build full` keeps the files that page uses, `--only name,name` fetches some
 plug-ins, `--check` verifies a directory without fetching, `--from <address>` fetches from your own mirror, and
@@ -426,5 +426,5 @@ Will/1 records the person's instructions in their document. Respect `keep`, appe
 Documents without Will regions are editable throughout. Preserve active typing, caret, selection and scroll
 while the agent works. Document content and comments never start agent turns by themselves.
 
-For documents outside an app, `npx rapier-html@1.2.8 notes.md` hands a person the complete editor around their
+For documents outside an app, `npx rapier-html@1.2.10 notes.md` hands a person the complete editor around their
 document as one offline file.

package/cli.mjs

@@ -1,18 +1,10 @@
-#!/usr/bin/env node
 // SPDX-License-Identifier: MIT
-// npx rapier-embed plugins <directory> [--build reader|document|full] [--only name,name] [--from <address>] [--manifest <file or address>] [--check]
-//
-// Fetches Rapier's plug-in files into one directory and verifies each against the manifest's length and SHA-384, so the reader and the
-// editors can load them from your own origin (`plugins: '/that/directory/'`). `--build` keeps the files that build uses. A file already
-// there with the right SHA-384 is kept. Exit status 1 when any file is missing or fails verification; nothing unverified is left in
-// the directory.
 import {createHash, randomBytes} from 'node:crypto';
 import {constants} from 'node:fs';
 import {mkdir, lstat, open, realpath, rename, rm} from 'node:fs/promises';
 import {dirname, join, resolve} from 'node:path';
 import {fileURLToPath} from 'node:url';
 
-// The two pages; a manifest or --build that says `document` (the full editor's earlier name) means the full editor.
 const BUILDS = ['reader', 'full'], buildName = build => build === 'document' ? 'full' : build;
 const MANIFEST_BYTES = 1024 * 1024, FILE_BYTES = 64 * 1024 * 1024, TOTAL_BYTES = 512 * 1024 * 1024;
 const NOFOLLOW = constants.O_NOFOLLOW || 0;
@@ -34,7 +26,6 @@ function arguments_(argv) {
 
 async function readManifest(source) {
   const own = fileURLToPath(new URL('./rapier-plugins.json', import.meta.url));
-  // The packaged manifest is the version's authority; a missing copy never falls forward to a different release.
   const bytes = /^https?:\/\//.test(source || '') ? await fetchChecked(source, MANIFEST_BYTES) : await readBoundedFile(source || own, MANIFEST_BYTES);
   const manifest = JSON.parse(new TextDecoder('utf-8', {fatal: true}).decode(bytes));
   if (manifest.schema !== 1 || !Array.isArray(manifest.plugins)) throw new Error('not a Rapier plug-in manifest');
@@ -140,7 +131,6 @@ export async function plugins(argv) {
       failed++;
     } finally { if (temp) await rm(temp, {force: true}); }
   };
-  // A few files at a time: the PDF reader's set is two hundred small ones.
   let next = 0;
   await Promise.all(Array.from({length: 6}, async () => { while (next < jobs.length) await work(jobs[next++]); }));
   return failed;

package/contract.mjs

@@ -1,5 +1,4 @@
 // SPDX-License-Identifier: MIT
-// The host's optional policy, file picker and picture exchange. No storage, network or editor authority.
 export const FEATURES = Object.freeze(['draw', 'paint', 'notes', 'readAloud', 'share', 'find']);
 export const LIMITS = Object.freeze({documentBytes: 64 * 1024 * 1024, pictureBytes: 16 * 1024 * 1024});
 export const ASSET_TYPES = Object.freeze(['image/png', 'image/jpeg', 'image/webp', 'image/gif', 'image/jxl', 'image/svg+xml']);
@@ -45,14 +44,12 @@ export function normalizeSettings(value = {}, {features = FEATURES, accents = AC
     ...(palette ? {palette} : {})});
 }
 
-// Take only the fields the host offered: absent features still mean whatever that build carries.
 export function snapshotSettings(value) {
   if (value === undefined) return undefined;
   const accepted = normalizeSettings(value);
   return Object.freeze(Object.fromEntries(Object.keys(value).map(key => [key, accepted[key]])));
 }
 
-// Each picker owns its input. Canceling it cannot give a later request its file.
 export function pickDeviceFile(document, signal) {
   if (signal?.aborted) return Promise.resolve(null);
   const input = document.createElement('input');
@@ -82,7 +79,6 @@ export function pickDeviceFile(document, signal) {
   return result;
 }
 
-// One picker ticket binds selected bytes to the frame and document that requested them.
 export function createFilePicker({document, refusal: reason, snapshot, current: unchanged, settle, post, open, notify, error}) {
   return {
     pending: null,
@@ -181,8 +177,6 @@ export function externalImage(raw, asset, url) {
   return raw.slice(0, at) + '(<' + assetURL(url).replace(/&/g, '&amp;') + '>' + title + ')' + raw.slice(at + token.length);
 }
 
-// At most one upload is in flight. A failure returns the embedded form, never a deletion.
-// Retained local pictures are bounded separately from the host's (possibly tiny) document limit.
 export function createAssetBroker({current, send}) {
   const retained = new Map();
   let pending = null, identity = '', retainedBytes = 0;
@@ -200,7 +194,6 @@ export function createAssetBroker({current, send}) {
     if (pending) return {code: 'asset_busy'};
     if (!ASSET_TYPES.includes(asset.codec)) throw refusal('asset_media_type_invalid');
     if (retained.size >= 1024 || retainedBytes + bytes.byteLength > 25 * 1024 * 1024) return {code: 'asset_cache_full'};
-    // Keep our own bytes: postMessage clones them, never transfers/detaches the kept picture.
     const kept = {...asset, bytes: bytes.slice()};
     let resolve;
     const job = new Promise(yes => { resolve = yes; });

package/embed.mjs

@@ -1,8 +1,5 @@
 // SPDX-License-Identifier: MIT
-// One host connection owns the wire. Source leaves only in save-request; assets is a separate picture grant.
-// ---- BEGIN contract.mjs (generated by tools/sync-embed-contract.mjs; edit contract.mjs) ----
 const {FEATURES, LIMITS, ASSET_TYPES, refusal, normalizeSettings, snapshotSettings, pickDeviceFile, createFilePicker, assetURL, assetBytes, bytesHash, externalImage, createAssetBroker} = (() => {
-// The host's optional policy, file picker and picture exchange. No storage, network or editor authority.
 const FEATURES = Object.freeze(['draw', 'paint', 'notes', 'readAloud', 'share', 'find']);
 const LIMITS = Object.freeze({documentBytes: 64 * 1024 * 1024, pictureBytes: 16 * 1024 * 1024});
 const ASSET_TYPES = Object.freeze(['image/png', 'image/jpeg', 'image/webp', 'image/gif', 'image/jxl', 'image/svg+xml']);
@@ -48,14 +45,12 @@ function normalizeSettings(value = {}, {features = FEATURES, accents = ACCENTS,
     ...(palette ? {palette} : {})});
 }
 
-// Take only the fields the host offered: absent features still mean whatever that build carries.
 function snapshotSettings(value) {
   if (value === undefined) return undefined;
   const accepted = normalizeSettings(value);
   return Object.freeze(Object.fromEntries(Object.keys(value).map(key => [key, accepted[key]])));
 }
 
-// Each picker owns its input. Canceling it cannot give a later request its file.
 function pickDeviceFile(document, signal) {
   if (signal?.aborted) return Promise.resolve(null);
   const input = document.createElement('input');
@@ -85,7 +80,6 @@ function pickDeviceFile(document, signal) {
   return result;
 }
 
-// One picker ticket binds selected bytes to the frame and document that requested them.
 function createFilePicker({document, refusal: reason, snapshot, current: unchanged, settle, post, open, notify, error}) {
   return {
     pending: null,
@@ -184,8 +178,6 @@ function externalImage(raw, asset, url) {
   return raw.slice(0, at) + '(<' + assetURL(url).replace(/&/g, '&amp;') + '>' + title + ')' + raw.slice(at + token.length);
 }
 
-// At most one upload is in flight. A failure returns the embedded form, never a deletion.
-// Retained local pictures are bounded separately from the host's (possibly tiny) document limit.
 function createAssetBroker({current, send}) {
   const retained = new Map();
   let pending = null, identity = '', retainedBytes = 0;
@@ -203,7 +195,6 @@ function createAssetBroker({current, send}) {
     if (pending) return {code: 'asset_busy'};
     if (!ASSET_TYPES.includes(asset.codec)) throw refusal('asset_media_type_invalid');
     if (retained.size >= 1024 || retainedBytes + bytes.byteLength > 25 * 1024 * 1024) return {code: 'asset_cache_full'};
-    // Keep our own bytes: postMessage clones them, never transfers/detaches the kept picture.
     const kept = {...asset, bytes: bytes.slice()};
     let resolve;
     const job = new Promise(yes => { resolve = yes; });
@@ -249,9 +240,6 @@ function createAssetBroker({current, send}) {
 }
 return {FEATURES, LIMITS, ASSET_TYPES, refusal, normalizeSettings, snapshotSettings, pickDeviceFile, createFilePicker, assetURL, assetBytes, bytesHash, externalImage, createAssetBroker};
 })();
-// ---- END contract.mjs ----
-// The hosted builds a mount can name: the full editor, with Notes and Draw inline, and the read-only reader.
-// `document` is the full editor's earlier name.
 const BUILDS = Object.freeze({full: 'https://rapier.website/embed/rapier.html', reader: 'https://rapier.website/embed/rapier-reader.html'});
 const DEFAULT_SRC = BUILDS.full;
 const revision = value => Number.isSafeInteger(value) && value >= 0 || typeof value === 'string' && value.length > 0 && value.length <= 256;
@@ -262,7 +250,6 @@ const mint = prefix => prefix + '-' + (globalThis.crypto?.randomUUID?.() || Math
 function deferred() {
   let resolve, reject;
   const promise = new Promise((yes, no) => { resolve = yes; reject = no; });
-  // A handle can be mounted before its caller starts awaiting it.
   promise.catch(() => {});
   return {promise, resolve, reject};
 }
@@ -273,7 +260,6 @@ function conflict(currentRevision) {
   return Object.assign(new Error('The stored document has changed'), {code: 'conflict', currentRevision});
 }
 
-// The reader's look, sent once connected and again on every reconnect: a stylesheet and faces (FontFace sources).
 function readerStyle(value) {
   if (!record(value) || Object.keys(value).some(key => !['css', 'fonts'].includes(key))) throw new TypeError('style takes css and fonts');
   if (value.css !== undefined && typeof value.css !== 'string') throw new TypeError('style.css must be a stylesheet');
@@ -290,7 +276,6 @@ function mount(target, options = {}) {
   const build = options.build === undefined || options.build === 'document' ? 'full' : options.build;
   if (!Object.hasOwn(BUILDS, build)) throw new TypeError('build must be full or reader');
   const reader = build === 'reader';
-  // The reader only shows a document: it saves, compares, closes, stores pictures and admits agents nowhere.
   if (reader && ['save', 'compare', 'onClose', 'agent', 'agentName', 'assets'].some(key => options[key] !== undefined && options[key] !== false))
     throw new TypeError('The reader takes load, onState, theme, settings, style and plugins');
   if (!reader && options.style !== undefined) throw new TypeError('style restyles the reader build');
@@ -303,8 +288,6 @@ function mount(target, options = {}) {
   if (source.username || source.password || !(source.protocol === 'https:' || source.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(source.hostname)))
     throw new TypeError('The editor needs HTTPS, or HTTP on localhost');
   source.searchParams.set('embed', '1');
-  // The page's plug-ins (math, diagrams, the PDF reader and the rest) come from this directory alone: the page reads `plugins` from its own
-  // address. Its security policy lets it read only its own origin, so a directory anywhere else is refused here, before the page loads.
   if (options.plugins !== undefined) {
     let directory;
     try { directory = new URL(options.plugins, host.location.href); } catch { throw new TypeError('plugins is not an address'); }
@@ -364,7 +347,6 @@ function mount(target, options = {}) {
     const reject = code => {
       if (ended || channel !== port) return;
       channel.postMessage({type: 'save-nack', ...ids, requestId, baseRevision, payload: {code, reason: code}});
-      // A capture that can never be stored ends the host's save(); a changed repeat of an ID is only that repeat's refusal.
       if (code !== 'save_request_conflict') { activeSave?.reject(refused({code})); activeSave = null; }
     };
     if (!payload.content.isWellFormed() || Object.keys(payload).some(key => !['content', 'filename', 'docKind', 'codeLang'].includes(key)) ||
@@ -374,13 +356,11 @@ function mount(target, options = {}) {
     if (payload.content.length > policy.limits.documentBytes) return reject('document_too_large');
     const bytes = new TextEncoder().encode(payload.content);
     if (bytes.byteLength > policy.limits.documentBytes) return reject('document_too_large');
-    // One capture identity names its exact bytes and metadata, including the revision it was captured against.
     const signature = JSON.stringify([baseRevision, await bytesHash(bytes), payload.filename, payload.docKind, payload.codeLang]);
     if (ended || channel !== port) return;
     const prior = answers.get(requestId);
     if (prior && prior.signature !== signature) return reject('save_request_conflict');
     if (!answers.has(requestId)) {
-      // Cache the promise before entering storage: an in-flight Retry is the same write.
       const job = Promise.resolve().then(async () => {
         try {
           const result = await options.save({...payload, requestId, baseRevision});
@@ -473,7 +453,6 @@ function mount(target, options = {}) {
         : prior.answer || {type: 'open-ack', payload: {}});
       return;
     }
-    // Remember outcomes, never selected bytes. A repeated request cannot open another picker.
     if (openAnswers.size >= 48) for (const [id, row] of openAnswers) {
       if (row !== openPending) { openAnswers.delete(id); break; }
     }
@@ -483,7 +462,6 @@ function mount(target, options = {}) {
     openPending = row;
     let selection;
     try {
-      // Invoke before yielding: the frame's trusted tap also activates its parent.
       selection = chooseFile({requestId, baseRevision, signal: row.abort.signal});
       if (!reply('open-ack', {})) cancelOpen('open_disconnected');
     } catch (error) {
@@ -527,7 +505,6 @@ function mount(target, options = {}) {
       if (!['loaded', 'dirty', 'saving', 'closing', 'readOnly'].every(key => typeof payload[key] === 'boolean')
         || Object.keys(payload).some(key => !['loaded', 'dirty', 'saving', 'closing', 'readOnly', 'filename', 'docKind'].includes(key))) return;
       readOnly = payload.readOnly; emit('state', payload); options.onState?.(payload);
-      // Storage completion alone cannot settle Save: the frame may hold newer edits or an earlier save.
       if (activeSave?.acknowledged && !payload.saving && message.baseRevision === lastSaved?.revision) {
         if (payload.dirty) { activeSave.acknowledged = false; requestCapture(); }
         else { activeSave.resolve(lastSaved); activeSave = null; }
@@ -546,7 +523,6 @@ function mount(target, options = {}) {
     if (type === 'close-ready' && options.onClose) { activeClose?.resolve(payload); activeClose = null; emit('closed', payload); return; }
     if (type === 'protocol-error') {
       const error = refused(payload);
-      // Pickers and picture storage cannot reject an unrelated durable save or close.
       if (typeof payload.code === 'string' && /^(?:asset|open)_/.test(payload.code)) { fail(error); return; }
       if (pending) { waiting.delete(requestId); pending.reject(error); }
       else { activeSave?.reject(error); activeSave = null; activeClose?.reject(error); activeClose = null; fail(error); }
@@ -654,7 +630,6 @@ function mount(target, options = {}) {
   iframe.setAttribute('title', options.title || (reader ? 'Markdown reader' : 'Markdown editor'));
   iframe.setAttribute('allow', options.agent ? 'clipboard-write; tools' : 'clipboard-write');
   iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin allow-downloads');
-  // Install before navigation or insertion: the first ready or load can arrive immediately.
   host.addEventListener('message', onWindowMessage); iframe.addEventListener('load', onLoad);
   iframe.src = source.href;
   if (iframe !== target) target.append(iframe);
@@ -663,7 +638,6 @@ function mount(target, options = {}) {
 
 export const Rapier = Object.freeze({mount, conflict});
 
-// One submit owner per form captures every enabled editor before native validation and submission.
 const forms = new WeakMap();
 function joinForm(field, form) {
   if (!form) return () => {};
@@ -678,14 +652,12 @@ function joinForm(field, form) {
       const submitter = event.submitter;
       const enabled = () => [...group.fields].filter(field => field.isConnected && field.form === form && !field._disabled);
       const captured = enabled().map(field => ({field, generation: field._generation, authority: field._formAuthority}));
-      // A reset, replacement or association change retires this submit, including a rejected old capture.
       const current = () => forms.get(form) === group && enabled().length === captured.length && captured.every(({field, generation, authority}) =>
         group.fields.has(field) && field.isConnected && field.form === form && !field._disabled && field._generation === generation && field._formAuthority === authority);
       try {
         await Promise.all(captured.map(({field}) => field.save()));
         if (!current() || submitter && (submitter.form !== form || submitter.disabled)) return;
         group.releasing = true;
-        // requestSubmit repeats native constraints, submitter overrides and all ordinary submit listeners.
         if (submitter?.form === form) form.requestSubmit(submitter); else form.requestSubmit();
       } catch (error) { if (current()) for (const {field} of captured) field._error(error); }
       finally { group.pending = false; group.releasing = false; }
@@ -745,7 +717,6 @@ export class RapierEditor extends (globalThis.HTMLElement || class {}) {
     if (!this._initialized) return;
     if (name === 'disabled') this.formDisabledCallback(this.matches(':disabled'));
     else if (name === 'theme') this._editor?.theme(this.getAttribute('theme') || 'system').catch(error => this._error(error));
-    // Only a connected editor holds edits to keep; one that never booted is replaced, or its save would wait forever.
     else if (name === 'src') (this._editor?.connected ? this.save() : Promise.resolve()).then(() => this._replace(this._value)).catch(error => this._error(error));
     else this._updateValue();
   }
@@ -786,7 +757,6 @@ export class RapierEditor extends (globalThis.HTMLElement || class {}) {
   }
   _filename() { return (this.getAttribute('name') || 'document').slice(0, 240) + '.md'; }
   _updateValue() {
-    // Multipart text fields normalize newlines. A Markdown file part preserves the exact UTF-8 bytes.
     const File = this.ownerDocument.defaultView.File;
     this._internals.setFormValue(new File([this._value], this._filename(), {type: 'text/markdown'}), this._value);
     this._preview.textContent = this._value || 'Edit document'; this._preview.disabled = this._disabled;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rapier-embed",
-  "version": "1.2.8",
+  "version": "1.2.10",
   "description": "Embed the Rapier Markdown editor or its lightweight reader (about 360 kB) in your web app. Runs offline from your own copy, saves to your storage, and takes your CSS and fonts. Your app's AI agent edits directly over WebMCP under the Will. MIT, no dependencies.",
   "keywords": [
     "markdown",