rapier-embed 1.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jack Skipworth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# rapier-embed
+
+The Rapier editor inside your site. One call frames `rapier.html?embed=1`, connects at the frame's
+load, loads your document and answers its saves from your own storage. Your app keeps the document,
+its identity and its revisions; the frame never stores it.
+
+MIT. No dependencies. The contract it speaks is `docs/embed-contract.md` in the Rapier repository;
+the skill a coding agent reads is `skills/embed-rapier/SKILL.md` there.
+
+## Use it
+
+```html
+<iframe id="rapier" src="https://editor.example.com/rapier.html?embed=1"></iframe>
+```
+
+```js
+import {connectRapier, memoryStore} from 'rapier-embed';
+
+const store = memoryStore({revision: 1, content: '# Notes\n'});   // or your own: write(requestId, content, baseRevision)
+const rapier = connectRapier(document.querySelector('#rapier'), {
+  sessionId: 'session-1', documentId: 'doc-42',
+  capabilities: ['open', 'read'],            // add 'changes', 'compare', 'close', 'agent' as you use them
+  theme: 'dark',                             // 'light' | 'dark' | 'system'; the frame follows your app
+  store,
+  onConnected: () => rapier.load(store.content, {filename: 'notes.md', revision: store.revision}),
+});
+```
+
+That is the whole integration. The frame asks to save when the person presses Save; the helper
+calls `store.write(requestId, content, baseRevision)` once per request and answers the frame with
+the revision your store returns, or a conflict when your copy moved on. A repeated request (the
+person's Retry, a reconnect) gets the same answer and is never written twice.
+
+Your `store.write` returns `{revision}` after the bytes are durable, or `{conflict: true,
+currentRevision}` when `baseRevision` is not your current revision. Return only after the write is
+durable: the frame tells the person "saved to your.site" on your word.
+
+## The handle
+
+| Call | Needs | Does |
+|---|---|---|
+| `load(content, {filename, revision, readOnly, title})` | `open` | Opens your text in the frame at that revision. |
+| `save()` | `read` | Asks the frame to save now; the answer comes through `store.write`. |
+| `compare(content, {filename})` | `compare` | Opens your alternative text in the frame's Compare for the person to keep or drop. |
+| `close()` | `close` | Asks the frame to close; resolves with the frame's close-ready. |
+| `theme('light' \| 'dark' \| 'system')` | nothing | Changes the frame's theme live. |
+| `disconnect()` | nothing | Ends this connection and stops listening. |
+| `on(type, fn)` | | `connected`, `state` (with `changes`), `close-request`, `closed`, `error`. |
+
+`onState(state)` receives `{loaded, dirty, saving, closing, readOnly, filename, docKind}` whenever it
+changes, with `changes` granted. `onClose({dirty})` returns `'save'`, `'discard'` or `'cancel'` when the
+frame asks; without it a dirty document is saved and a clean one closes.
+
+## What the frame checks, and what you check
+
+The frame takes the connect only from its parent window, from an HTTPS origin (HTTP on localhost),
+and binds to that origin for the session. The helper checks every message it takes against the
+frame's window and origin. Without `read` the frame refuses to send the person's words anywhere;
+without `close` its Close control names the missing grant and sends you nothing. Grants are frozen
+for the connection: reload the frame to change them.
+
+Serve the frame from its own origin (`editor.example.com`), allow it in your `frame-src`, and let it
+keep a real origin if you sandbox it (`allow-scripts allow-same-origin`).

package/embed.mjs

@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: MIT
+// Host side of docs/embed-contract.md. The host keeps the document; this module stores nothing.
+// A repeated requestId gets the remembered answer, never a second write.
+
+const CAPABILITIES = ['open', 'read', 'changes', 'compare', 'close', 'agent'];
+
+export function connectRapier(iframe, options) {
+	const {sessionId, documentId, store, capabilities = ['open', 'read'], theme, onClose, onState, onError,
+		origin = new URL(iframe.src, globalThis.location?.href).origin, onConnected} = options;
+	if (typeof sessionId !== 'string' || !sessionId || typeof documentId !== 'string' || !documentId) throw new TypeError('sessionId and documentId are nonempty strings');
+	if (!Array.isArray(capabilities) || capabilities.some(name => !CAPABILITIES.includes(name))) throw new TypeError('capabilities is a list from ' + CAPABILITIES.join(', '));
+	if (capabilities.includes('read') && typeof store?.write !== 'function') throw new TypeError('read needs store.write(requestId, content, baseRevision) -> {revision} or {conflict: true, currentRevision}');
+	const ids = {sessionId, documentId};
+	const answered = new Map(), waiting = new Map();
+	let port = null, posted = false, connected = false, seq = 0;
+	const listeners = new Map();
+
+	const emit = (type, message) => { for (const fn of listeners.get(type) || []) fn(message); };
+	const fail = error => { emit('error', error); if (onError) onError(error); };
+	const sameFrame = event => event.source === iframe.contentWindow && event.origin === origin;
+
+	function send(type, payload, baseRevision) {
+		if (!port || !connected) return Promise.reject(new Error('not connected'));
+		const requestId = 'h' + (++seq) + '-' + Math.random().toString(36).slice(2, 10);
+		const message = {type, ...ids, requestId, ...(baseRevision !== undefined ? {baseRevision} : {}), ...(payload ? {payload} : {})};
+		return new Promise((resolve, reject) => {
+			waiting.set(requestId, {resolve, reject, type});
+			try { port.postMessage(message); } catch (error) { waiting.delete(requestId); reject(error); }
+		});
+	}
+
+	async function answerSave(message) {
+		const {requestId, baseRevision} = message;
+		// The answer is held from the moment storage starts: a Retry while it is pending shares the one write.
+		if (!answered.has(requestId)) answered.set(requestId, (async () => {
+			let reply;
+			try {
+				const outcome = await store.write(requestId, message.payload?.content ?? '', baseRevision, message.payload);
+				reply = outcome && outcome.conflict
+					? {type: 'save-nack', payload: {code: 'conflict', ...(outcome.currentRevision !== undefined ? {currentRevision: outcome.currentRevision} : {})}}
+					: {type: 'save-ack', payload: {revision: outcome.revision}};
+			} catch (error) {
+				reply = {type: 'save-nack', payload: {code: 'failed', reason: String(error?.message || error).slice(0, 500)}};
+			}
+			return {...ids, requestId, baseRevision, ...reply};
+		})());
+		port.postMessage(await answered.get(requestId));
+	}
+
+	function onPortMessage(event) {
+		const message = event.data;
+		if (!message || typeof message !== 'object' || message.sessionId !== sessionId || message.documentId !== documentId) return;
+		const pending = message.requestId ? waiting.get(message.requestId) : null;
+		switch (message.type) {
+			case 'connected':
+				connected = true;
+				emit('connected', message.payload);
+				if (onConnected) onConnected(message.payload);
+				return;
+			case 'save-request': answerSave(message).catch(fail); return;
+			case 'document-state': emit('state', message.payload); if (onState) onState(message.payload); return;
+			case 'close-request': {
+				const decide = decision => port.postMessage({type: 'close-decision', ...ids, requestId: message.requestId, baseRevision: message.baseRevision, payload: {decision}});
+				const dirty = !!message.payload?.dirty;
+				Promise.resolve(onClose ? onClose({dirty}) : (dirty ? 'save' : 'discard')).then(decide, fail);
+				emit('close-request', message.payload);
+				return;
+			}
+			case 'close-ready': emit('closed', message.payload); if (pending) { waiting.delete(message.requestId); pending.resolve(message.payload); } return;
+			case 'protocol-error':
+				if (pending) { waiting.delete(message.requestId); pending.reject(Object.assign(new Error(message.payload?.reason || message.payload?.code || 'refused'), {code: message.payload?.code, payload: message.payload})); }
+				else fail(Object.assign(new Error(message.payload?.reason || message.payload?.code || 'refused'), {code: message.payload?.code, payload: message.payload}));
+				return;
+			default:
+				if (pending) { waiting.delete(message.requestId); pending.resolve(message.payload); }
+				else emit(message.type, message.payload);
+		}
+	}
+
+	function connect() {
+		if (posted) return;
+		posted = true;
+		const channel = new MessageChannel();
+		port = channel.port1;
+		port.onmessage = onPortMessage;
+		iframe.contentWindow.postMessage({type: 'rapier-connect', ...ids, capabilities, ...(theme ? {theme} : {})}, origin, [channel.port2]);
+	}
+
+	function onWindowMessage(event) {
+		if (!sameFrame(event)) return;
+		const message = event.data;
+		if (message?.type === 'rapier-ready' && !posted) connect();
+		else if (message?.type === 'close-ready' && message.sessionId === sessionId && message.documentId === documentId) emit('closed', message.payload);
+	}
+
+	globalThis.addEventListener?.('message', onWindowMessage);
+	iframe.addEventListener('load', connect);
+
+	return Object.freeze({
+		get connected() { return connected; },
+		load: (content, {filename, revision = 1, readOnly, title} = {}) => send('load', {content, ...(filename ? {filename} : {}), revision, ...(readOnly !== undefined ? {readOnly} : {}), ...(title ? {title} : {})}, null),
+		save: () => send('save'),
+		compare: (content, {filename} = {}) => send('compare', {content, ...(filename ? {filename} : {})}),
+		close: () => send('close'),
+		theme: value => send('theme', {theme: value}),
+		disconnect() {
+			send('disconnect').catch(() => {});
+			globalThis.removeEventListener?.('message', onWindowMessage);
+			iframe.removeEventListener('load', connect);
+			try { port?.close(); } catch (_) {}
+			port = null; connected = false; posted = false;
+		},
+		on(type, fn) { if (!listeners.has(type)) listeners.set(type, new Set()); listeners.get(type).add(fn); return () => listeners.get(type).delete(fn); },
+	});
+}
+
+export function memoryStore(initial = {revision: 0, content: ''}) {
+	const state = {...initial};
+	return {
+		get revision() { return state.revision; },
+		get content() { return state.content; },
+		async write(requestId, content, baseRevision) {
+			if (baseRevision !== null && baseRevision !== undefined && baseRevision !== state.revision) return {conflict: true, currentRevision: state.revision};
+			state.content = content;
+			state.revision = (typeof state.revision === 'number' ? state.revision : 0) + 1;
+			return {revision: state.revision};
+		},
+	};
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "rapier-embed",
+  "version": "1.1.2",
+  "description": "Put the Rapier editor in your site: one call frames rapier.html?embed=1, connects, loads your document and answers its saves.",
+  "keywords": [
+    "markdown",
+    "editor",
+    "iframe",
+    "embed",
+    "offline",
+    "agent",
+    "rapier"
+  ],
+  "author": "Jack Skipworth",
+  "license": "MIT",
+  "homepage": "https://rapier.website",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jackskip22/rapier-plugins.git",
+    "directory": "npm/rapier-embed"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": "./embed.mjs"
+  },
+  "files": [
+    "embed.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false
+}