@ripple-ui/svelte 0.0.0-stage → 0.9.0-next.0

package/dist/editor/core/inline-editor-tiptap.js

@@ -0,0 +1,192 @@
+/**
+ * @file editor/core/inline-editor-tiptap.ts
+ * @description L1 (PURE TS / DOM, zero Svelte/rune imports) the RICH-HTML
+ *   `InlineEditor` impl (EP-3) — the TipTap StarterKit path lifted VERBATIM out of
+ *   `RippleInlineEditor.svelte`. The ripple built-in rich editor (registered under
+ *   the 'tiptap' kind); used for `richtext`, whose content is structural HTML.
+ *
+ *   ASYNC MOUNT. `mount` returns its handle SYNCHRONOUSLY and dynamically imports
+ *   `@tiptap/core` + `@tiptap/starter-kit` in the background, so the bundle stays
+ *   lean and the host can tear down (`handle.destroy()`) mid-load. A `disposed`
+ *   flag guards the import against a teardown race (checked before clearing the
+ *   host HTML and again after constructing the editor).
+ *
+ *   COMMIT / CANCEL. Enter (no shift) and blur commit `editor.getHTML()`; Escape
+ *   cancels. Both are deferred to a microtask so the editor view is never destroyed
+ *   from inside its own keydown handler. A commit fires `onCommit(html)` ONLY when
+ *   the HTML changed from the seed. After TipTap is torn down the element is empty,
+ *   and Svelte's `is_controlled` `{@html}` only repaints on a CHANGED html string,
+ *   so every teardown path writes the current HTML back into the element directly
+ *   (covers the unchanged-value case AND the async gap before Svelte flushes). EVERY
+ *   teardown path also clears the host's `data-ripple-editing` attribute — the EP-1
+ *   stuck-outline fix (the rich commit branch used to leak the indigo outline).
+ *   All DOM / TipTap calls are guarded so the jsdom unit path never throws.
+ *
+ *   XSS POSTURE. The seed is SPEC content — LLM-authored and prompt-injectable —
+ *   and every teardown path writes it to `el.innerHTML` on a LIVE element, which
+ *   bypasses ProseMirror's schema completely. (The MOUNT path does not: ProseMirror
+ *   parses in an inert document and StarterKit has no image node, so a payload dies
+ *   there. Only the teardown restore was exploitable.) So the seed is sanitized on
+ *   intake, the `restoreRichHtml` sink sanitizes again defensively, and the COMMITTED
+ *   value is sanitized so the editor can never launder script-capable HTML back into
+ *   the spec for the next reader. Sanitizing the seed on intake (rather than at each
+ *   write) also keeps the `changed` comparison clean-vs-clean, so an unchanged commit
+ *   still emits no op. Structural StarterKit markup is untouched by the profile.
+ * @created 2026-06-30 (EP-3 — pluggable InlineEditor slot)
+ * @changes 2026-08-04 (security): closed the raw-`innerHTML` XSS sink — sanitize the
+ *   seed on intake, inside `restoreRichHtml`, and on the committed value.
+ */
+import { sanitizeHtml } from '../../utils/sanitize-html.js';
+import { registerInlineEditor } from './inline-editor.js';
+/** Best-effort destroy — jsdom / double-destroy must never throw the teardown path. */
+function safeDestroy(editor) {
+    try {
+        editor?.destroy?.();
+    }
+    catch {
+        /* jsdom / double-destroy — teardown must never throw */
+    }
+}
+/**
+ * Write model HTML into the element (Svelte won't repaint an unchanged {@html}).
+ * This is a RAW innerHTML write on a live, in-document element, so it sanitizes at
+ * the sink — the callers already pass sanitized strings, but hardening the write
+ * itself keeps any future call site safe by construction. Guarded for jsdom.
+ */
+function restoreRichHtml(el, html) {
+    try {
+        el.innerHTML = sanitizeHtml(html);
+    }
+    catch {
+        /* jsdom */
+    }
+}
+/** The rich-HTML editor backed by TipTap StarterKit — the ripple 'tiptap' built-in. */
+export const TipTapInlineEditor = {
+    mount(el, opts) {
+        // Sanitize the SPEC-controlled seed once, here: every teardown path writes it
+        // straight to innerHTML, and `changed` is measured against it (see header).
+        const seed = sanitizeHtml(opts.content);
+        let editor = null; // TipTap Editor once mounted (typed `any` at the call sites)
+        let disposed = false; // guards the async TipTap import against a teardown race
+        function commit() {
+            if (disposed)
+                return;
+            disposed = true;
+            let html = seed;
+            try {
+                html = editor?.getHTML?.() ?? seed;
+            }
+            catch {
+                html = seed;
+            }
+            // The value about to be written back into the SPEC — sanitize so a committed
+            // edit can never re-poison the node for every future reader of that spec.
+            html = sanitizeHtml(html);
+            safeDestroy(editor);
+            el.removeAttribute('data-ripple-editing'); // clear the editing outline (the EP-1 fix)
+            const changed = html !== seed;
+            if (changed)
+                opts.onCommit(html); // the host writes through adapter.applyEdit(setText)
+            restoreRichHtml(el, changed ? html : seed);
+        }
+        function cancel() {
+            if (disposed)
+                return;
+            disposed = true;
+            safeDestroy(editor);
+            el.removeAttribute('data-ripple-editing');
+            restoreRichHtml(el, seed);
+            opts.onCancel();
+        }
+        // Kick off the editor mount asynchronously; the handle below is returned now.
+        void (async () => {
+            try {
+                const [{ Editor }, { default: StarterKit }] = await Promise.all([
+                    import('@tiptap/core'),
+                    import('@tiptap/starter-kit')
+                ]);
+                if (disposed)
+                    return; // torn down mid-import
+                // Clear the host's {@html} render so TipTap (which APPENDS its view to the
+                // element) doesn't double-render. Safe: Svelte repaints {@html} on the next
+                // `html` change, and commit / cancel restore it explicitly.
+                try {
+                    el.innerHTML = '';
+                }
+                catch {
+                    /* jsdom */
+                }
+                const ed = new Editor({
+                    element: el,
+                    extensions: [StarterKit],
+                    content: seed || '',
+                    editorProps: {
+                        attributes: { class: 'prose prose-sm dark:prose-invert max-w-none focus:outline-none' },
+                        // Intercept commit / cancel keys BEFORE ProseMirror's default handling.
+                        // Defer to a microtask so the editor view is never destroyed from inside
+                        // its own keydown handler. Enter (no shift) commits — mirrors the text
+                        // path; Shift+Enter falls through to a hard break.
+                        handleKeyDown: (_view, event) => {
+                            if (event.key === 'Enter' && !event.shiftKey) {
+                                event.preventDefault();
+                                queueMicrotask(commit);
+                                return true;
+                            }
+                            if (event.key === 'Escape') {
+                                event.preventDefault();
+                                queueMicrotask(cancel);
+                                return true;
+                            }
+                            return false;
+                        }
+                    },
+                    // Blur commits (same intent as the text path). Deferred for the same
+                    // mid-handler-destroy safety reason as the keys above.
+                    onBlur: () => queueMicrotask(commit)
+                });
+                if (disposed) {
+                    // Torn down while constructing — drop the just-created editor.
+                    safeDestroy(ed);
+                    return;
+                }
+                editor = ed;
+                try {
+                    ed.commands.focus('end');
+                }
+                catch {
+                    /* jsdom — focus / selection is a nicety */
+                }
+            }
+            catch {
+                // Module load / mount failed — restore the rendered HTML and clear the slot.
+                if (!disposed) {
+                    disposed = true;
+                    el.removeAttribute('data-ripple-editing');
+                    restoreRichHtml(el, seed);
+                }
+            }
+        })();
+        return {
+            destroy() {
+                if (disposed)
+                    return; // already committed / cancelled / torn down (idempotent)
+                disposed = true;
+                safeDestroy(editor);
+                el.removeAttribute('data-ripple-editing');
+                restoreRichHtml(el, seed);
+            },
+            focus() {
+                try {
+                    editor?.commands?.focus?.('end');
+                }
+                catch {
+                    /* jsdom */
+                }
+            }
+        };
+    }
+};
+// Self-register the ripple built-in so `resolveInlineEditor('tiptap')` works for any
+// external caller; the controller also references the impl directly for the default.
+registerInlineEditor('tiptap', TipTapInlineEditor);

package/dist/editor/core/inline-editor.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @file editor/core/inline-editor.ts
+ * @description L1 (PURE TS, zero Svelte/rune imports) the pluggable INLINE-EDITOR
+ *   slot contract (EP-3) + a tiny kind -> editor registry. The visual-editor chrome
+ *   (`RippleInlineEditor`) no longer hard-codes TipTap / contenteditable: on
+ *   double-click it picks an `InlineEditor` and `mount`s it on the resolved element,
+ *   so a future lane (svelte source, html/css) can supply its own source-fidelity
+ *   editor by registering one under its `adapter.inlineEditor` kind — WITHOUT
+ *   touching the controller.
+ *
+ *   SLOT CONTRACT. The host (the controller) marks the element being edited with
+ *   `data-ripple-editing` (the editing outline) BEFORE it calls `mount`, and seeds
+ *   the editor via `opts.content` (html for a rich widget, text for a single-text
+ *   one). The InlineEditor then OWNS its full lifecycle:
+ *     • wires its own Enter / Escape / blur (commit / cancel / commit, matching the
+ *       ripple feel), focus + select-on-open, and teardown;
+ *     • calls `opts.onCommit(value)` ONLY when the content actually changed from
+ *       the seed (so an unchanged commit emits no op) — `value` is the edited
+ *       content (html or text); the host routes it to `adapter.applyEdit(ref,
+ *       { kind: 'setText', html: value })`;
+ *     • calls `opts.onCancel()` on Escape (the host applies no op);
+ *     • on EVERY teardown path (commit, cancel, and `handle.destroy()`) MUST clear
+ *       the host's `data-ripple-editing` attribute — this is the EP-1 stuck-outline
+ *       fix (the rich commit branch used to leak the indigo outline); keep it.
+ *   `handle.destroy()` is the SILENT teardown the host calls on re-entry (a fresh
+ *   edit on another node) and on unmount: tear down with NO `onCommit` / `onCancel`.
+ *   It must be idempotent and safe to call before an async editor has mounted.
+ *
+ *   THE PLAIN PATH IS FIXED. Single-text widgets (heading / text / button / badge)
+ *   always use `ContentEditableInlineEditor`; only the RICH slot is pluggable, keyed
+ *   by `adapter.inlineEditor` ('tiptap' is the ripple built-in; 'squire' / 'overlay'
+ *   are reserved for EP-4's source-fidelity lane, which calls `registerInlineEditor`
+ *   from its own module).
+ * @created 2026-06-30 (EP-3 — pluggable InlineEditor slot)
+ */
+/** What the host hands an `InlineEditor` when it opens an in-place edit. */
+export interface InlineEditorMountOpts {
+    /** Seed content for the editor: rich HTML for a rich widget, text for a plain one. */
+    content: string;
+    /** Called on a CHANGED commit (Enter / blur); `value` is the edited content. */
+    onCommit: (value: string) => void;
+    /** Called on cancel (Escape); the host applies no op. */
+    onCancel: () => void;
+}
+/** Live handle to a mounted `InlineEditor`. */
+export interface InlineEditorHandle {
+    /**
+     * Silent teardown — NO `onCommit` / `onCancel`. The host calls this on re-entry
+     * (a new edit elsewhere) and on unmount. Must be idempotent and safe to call
+     * before an async editor has finished mounting; must clear `data-ripple-editing`.
+     */
+    destroy(): void;
+    /** Optional: (re)focus the editor. The host relies on `mount` auto-focusing. */
+    focus?(): void;
+}
+/**
+ * A pluggable in-place editor. `mount` SYNCHRONOUSLY returns a handle even when the
+ * underlying editor loads asynchronously (e.g. TipTap's dynamic import), so the host
+ * can tear it down (`handle.destroy()`) during the load.
+ */
+export interface InlineEditor {
+    mount(el: HTMLElement, opts: InlineEditorMountOpts): InlineEditorHandle;
+}
+/**
+ * Register the rich/whole-content inline editor for a lane kind (the value a lane's
+ * `adapter.inlineEditor` returns). EP-4 calls this from the svelte lane's setup
+ * (`registerInlineEditor('squire', SquireInlineEditor)`) so the controller resolves
+ * it without changing. Re-registering a kind overwrites the previous impl.
+ */
+export declare function registerInlineEditor(kind: string, editor: InlineEditor): void;
+/** The rich editor registered for `kind`, or null when none is registered. */
+export declare function resolveInlineEditor(kind: string): InlineEditor | null;

package/dist/editor/core/inline-editor.js

@@ -0,0 +1,53 @@
+/**
+ * @file editor/core/inline-editor.ts
+ * @description L1 (PURE TS, zero Svelte/rune imports) the pluggable INLINE-EDITOR
+ *   slot contract (EP-3) + a tiny kind -> editor registry. The visual-editor chrome
+ *   (`RippleInlineEditor`) no longer hard-codes TipTap / contenteditable: on
+ *   double-click it picks an `InlineEditor` and `mount`s it on the resolved element,
+ *   so a future lane (svelte source, html/css) can supply its own source-fidelity
+ *   editor by registering one under its `adapter.inlineEditor` kind — WITHOUT
+ *   touching the controller.
+ *
+ *   SLOT CONTRACT. The host (the controller) marks the element being edited with
+ *   `data-ripple-editing` (the editing outline) BEFORE it calls `mount`, and seeds
+ *   the editor via `opts.content` (html for a rich widget, text for a single-text
+ *   one). The InlineEditor then OWNS its full lifecycle:
+ *     • wires its own Enter / Escape / blur (commit / cancel / commit, matching the
+ *       ripple feel), focus + select-on-open, and teardown;
+ *     • calls `opts.onCommit(value)` ONLY when the content actually changed from
+ *       the seed (so an unchanged commit emits no op) — `value` is the edited
+ *       content (html or text); the host routes it to `adapter.applyEdit(ref,
+ *       { kind: 'setText', html: value })`;
+ *     • calls `opts.onCancel()` on Escape (the host applies no op);
+ *     • on EVERY teardown path (commit, cancel, and `handle.destroy()`) MUST clear
+ *       the host's `data-ripple-editing` attribute — this is the EP-1 stuck-outline
+ *       fix (the rich commit branch used to leak the indigo outline); keep it.
+ *   `handle.destroy()` is the SILENT teardown the host calls on re-entry (a fresh
+ *   edit on another node) and on unmount: tear down with NO `onCommit` / `onCancel`.
+ *   It must be idempotent and safe to call before an async editor has mounted.
+ *
+ *   THE PLAIN PATH IS FIXED. Single-text widgets (heading / text / button / badge)
+ *   always use `ContentEditableInlineEditor`; only the RICH slot is pluggable, keyed
+ *   by `adapter.inlineEditor` ('tiptap' is the ripple built-in; 'squire' / 'overlay'
+ *   are reserved for EP-4's source-fidelity lane, which calls `registerInlineEditor`
+ *   from its own module).
+ * @created 2026-06-30 (EP-3 — pluggable InlineEditor slot)
+ */
+// --------------------------------------------------------------------------
+// RICH-editor registry — maps a lane's `adapter.inlineEditor` kind to its impl.
+// The plain single-text path is NOT in here (it always uses ContentEditable).
+// --------------------------------------------------------------------------
+const RICH_EDITORS = new Map();
+/**
+ * Register the rich/whole-content inline editor for a lane kind (the value a lane's
+ * `adapter.inlineEditor` returns). EP-4 calls this from the svelte lane's setup
+ * (`registerInlineEditor('squire', SquireInlineEditor)`) so the controller resolves
+ * it without changing. Re-registering a kind overwrites the previous impl.
+ */
+export function registerInlineEditor(kind, editor) {
+    RICH_EDITORS.set(kind, editor);
+}
+/** The rich editor registered for `kind`, or null when none is registered. */
+export function resolveInlineEditor(kind) {
+    return RICH_EDITORS.get(kind) ?? null;
+}

package/dist/editor/core/inspector-fields.d.ts

@@ -0,0 +1,49 @@
+import type { UINode } from '@ripple-ui/core';
+export type FieldKind = 'text' | 'textarea' | 'number' | 'boolean' | 'select' | 'readonly';
+export interface InspectorField {
+    /** Prop name on the node (also the op `prop`). */
+    prop: string;
+    /** Display label (the prop name; humanization is a view concern). */
+    label: string;
+    kind: FieldKind;
+    /** Current value (from `node.props[prop]`, falling back to the spec default). */
+    value: unknown;
+    /** Options for `kind === 'select'`. */
+    options?: string[];
+    /** True when a `select`'s options are numeric literals (coerce to Number on set). */
+    numeric?: boolean;
+    /** Spec description, surfaced as a field hint/title. */
+    description?: string;
+}
+/** Runtime shape of a manifest prop spec (a structural subset). */
+interface PropSpec {
+    type?: string;
+    required?: boolean;
+    description?: string;
+    default?: unknown;
+}
+interface EntryLike {
+    type: string;
+    props?: Record<string, PropSpec> | null;
+}
+/** Manifest entry for a widget type, or null when unknown. */
+export declare function inspectorCatalogEntry(type: string): EntryLike | null;
+/**
+ * Extract the option list from a union-literal manifest type string. Two forms:
+ *   - quoted-literal union  `"'sm' | 'md' | 'lg'"` or `'"a" | "b"'` → ['sm','md','lg']
+ *   - numeric-literal union `'1 | 2 | 3'`                           → ['1','2','3']
+ * Returns [] for anything that isn't a PURE literal union (so `number | string`,
+ * `string`, `Record<…>` are not mistaken for enums).
+ */
+export declare function parseEnumOptions(typeStr: string | undefined): string[];
+/** Classify a manifest prop `type` string into an editable field kind. */
+export declare function inferFieldKind(typeStr: string | undefined): FieldKind;
+/** Coerce a raw control value to the field's model type before it becomes a prop. */
+export declare function coerceFieldValue(kind: FieldKind, raw: unknown, numeric?: boolean): unknown;
+/**
+ * Derive the ordered, editable inspector fields for a node from its manifest
+ * entry. `readonly` props (collections/objects) are omitted. The value comes
+ * from the node when set, else the spec default, else an empty value for the kind.
+ */
+export declare function inferFields(node: UINode | null | undefined, entry?: EntryLike | null): InspectorField[];
+export {};

package/dist/editor/core/inspector-fields.js

@@ -0,0 +1,110 @@
+/**
+ * @file editor/core/inspector-fields.ts
+ * @changes 2026-09-17: coerceFieldValue's text fallback routes through asText
+ *   (objects → JSON, not "[object Object]") — oxlint no-base-to-string sweep.
+ * @description L1 (PURE TS, zero Svelte/DOM) manifest-driven field inference for
+ *   the Ripple visual editor's properties panel (`RippleInspector`). Given a
+ *   node, it reads the widget manifest's prop specs and derives a typed, editable
+ *   field per prop — `select` (from a union-literal type), `number`, `boolean`,
+ *   `textarea`, or `text` — so the inspector edits the FULL editable surface of a
+ *   widget (not just its text props), and auto-tracks the manifest: a new
+ *   widget/prop becomes editable the moment it lands. Props the inspector can't
+ *   safely edit inline (arrays/objects/functions like table `columns`) classify
+ *   as `readonly` and are omitted from the editable set.
+ *
+ *   Pure: the brain is here so it is unit-testable over synthetic specs; the
+ *   `.svelte` panel is a thin view that renders these fields and routes edits
+ *   back through the shared `EditorOps` seam (Decision 6 — L1 logic, L2 render).
+ * @created 2026-06-29 (editor chrome — properties panel)
+ */
+import { manifestEntries } from '../../manifest/index.js';
+import { asText } from '../../widgets/text-coerce.js';
+const CATALOG = new Map(manifestEntries.map((e) => [e.type, e]));
+/** Manifest entry for a widget type, or null when unknown. */
+export function inspectorCatalogEntry(type) {
+    return CATALOG.get(type) ?? null;
+}
+/** Prose props that read better as a multi-line textarea than a single-line input. */
+const TEXTAREA_PROPS = new Set(['description', 'content', 'body', 'markdown']);
+/**
+ * Extract the option list from a union-literal manifest type string. Two forms:
+ *   - quoted-literal union  `"'sm' | 'md' | 'lg'"` or `'"a" | "b"'` → ['sm','md','lg']
+ *   - numeric-literal union `'1 | 2 | 3'`                           → ['1','2','3']
+ * Returns [] for anything that isn't a PURE literal union (so `number | string`,
+ * `string`, `Record<…>` are not mistaken for enums).
+ */
+export function parseEnumOptions(typeStr) {
+    if (!typeStr)
+        return [];
+    const t = typeStr.trim();
+    const quoted = t.match(/(['"])(?:(?!\1).)*\1/g);
+    if (quoted) {
+        // Pure quoted union only: removing the literals + pipes must leave nothing.
+        const rest = t.replace(/(['"])(?:(?!\1).)*\1/g, '').replace(/\|/g, '').trim();
+        return rest === '' ? quoted.map((x) => x.slice(1, -1)) : [];
+    }
+    if (/^\d+(\s*\|\s*\d+)*$/.test(t))
+        return t.split('|').map((x) => x.trim());
+    return [];
+}
+/** True when every option is a bare integer literal (→ coerce the set value to Number). */
+function optionsAreNumeric(options) {
+    return options.length > 0 && options.every((o) => /^\d+$/.test(o));
+}
+/** Classify a manifest prop `type` string into an editable field kind. */
+export function inferFieldKind(typeStr) {
+    if (!typeStr)
+        return 'readonly';
+    const t = typeStr.trim();
+    if (parseEnumOptions(t).length >= 1)
+        return 'select';
+    if (/^number$/i.test(t))
+        return 'number';
+    if (/^boolean$/i.test(t))
+        return 'boolean';
+    // Plain string (incl. `string | number`), but not collections/callables/objects.
+    if (/string/i.test(t) && !/\[\]|Record|=>|[{}]/.test(t))
+        return 'text';
+    return 'readonly';
+}
+/** Coerce a raw control value to the field's model type before it becomes a prop. */
+export function coerceFieldValue(kind, raw, numeric = false) {
+    if (kind === 'number' || (kind === 'select' && numeric)) {
+        const n = Number(raw);
+        return Number.isFinite(n) ? n : 0;
+    }
+    if (kind === 'boolean')
+        return raw === true || raw === 'true' || raw === 'on';
+    return asText(raw);
+}
+/**
+ * Derive the ordered, editable inspector fields for a node from its manifest
+ * entry. `readonly` props (collections/objects) are omitted. The value comes
+ * from the node when set, else the spec default, else an empty value for the kind.
+ */
+export function inferFields(node, entry) {
+    if (!node)
+        return [];
+    const e = entry ?? inspectorCatalogEntry(node.type);
+    const specs = e?.props;
+    if (!specs)
+        return [];
+    const current = (node.props ?? {});
+    const fields = [];
+    for (const [prop, spec] of Object.entries(specs)) {
+        let kind = inferFieldKind(spec?.type);
+        if (kind === 'readonly')
+            continue;
+        if (kind === 'text' && TEXTAREA_PROPS.has(prop))
+            kind = 'textarea';
+        const fallback = spec?.default ?? (kind === 'boolean' ? false : kind === 'number' ? 0 : '');
+        const value = prop in current ? current[prop] : fallback;
+        const field = { prop, label: prop, kind, value, description: spec?.description };
+        if (kind === 'select') {
+            field.options = parseEnumOptions(spec?.type);
+            field.numeric = optionsAreNumeric(field.options);
+        }
+        fields.push(field);
+    }
+    return fields;
+}

package/dist/editor/core/lane-adapter.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @file editor/core/lane-adapter.ts
+ * @description L1 (PURE TS, zero Svelte/DOM) the lane-agnostic editor PORT (EP-1).
+ *   The visual-editor chrome (inspector today; overlay / inline / drag in later
+ *   slices) talks to a substrate ONLY through this interface, so the SAME chrome
+ *   can later drive other substrates (svelte source, html/css) by swapping the
+ *   adapter behind the port. The ripple substrate is the first implementation
+ *   (`RippleLaneAdapter`, over the spec-mutator path); nothing else may reach past
+ *   the port into spec-mutator / EditorOps / inferFields directly.
+ *
+ *   ADDRESSING. A `TargetRef` is the lane-scoped handle for one editable thing —
+ *   `{ uid, lane }`. `uid` is opaque to the chrome (a ripple node id today; a
+ *   source range or selector for a future lane). `lane` tags which adapter owns
+ *   it, so a multi-lane host never feeds a ref to the wrong adapter.
+ *
+ *   SYNC vs ASYNC. Every method returns SYNCHRONOUSLY. The ripple lane mutates an
+ *   in-memory `$state` tree through `spec-mutator` — there is no I/O, so a sync
+ *   contract keeps the chrome trivial (the inspector's `$derived(getFields(ref))`
+ *   needs no await / loading state, exactly as today's `$derived(inferFields)`).
+ *   Lanes that DO perform I/O (compile svelte source, round-trip remote html/css)
+ *   wrap this contract later — either an `AsyncLaneAdapter` variant or by widening
+ *   these returns to `T | Promise<T>` when the first async lane lands. Deferring
+ *   that until a real async lane exists avoids speculative Promise plumbing now.
+ * @created 2026-06-30 (EP-1 — LaneAdapter port + Ripple adapter)
+ * @changes 2026-06-30 (EP-1 review): add `readProp` — a symmetric single-field
+ *   read that mirrors the write routing (top-level / props / dotted), so the
+ *   chrome can read back a prop the adapter may store OUTSIDE `props`.
+ */
+import type { InspectorField } from './inspector-fields.js';
+/** Lane-scoped handle for one editable target. `uid` is opaque to the chrome. */
+export interface TargetRef {
+    /** Substrate-local id (a ripple node id today; opaque to the chrome). */
+    uid: string;
+    /** The adapter that owns this ref (e.g. `'ripple'`). */
+    lane: string;
+}
+/** A normalized, lane-agnostic view of one editable node. */
+export interface EditableNode {
+    /** Same value as the originating `TargetRef.uid`. */
+    uid: string;
+    /** Widget / element type (drives the field manifest). */
+    type: string;
+    /** Editable props (a shallow copy — mutate via `applyEdit`, never in place). */
+    props: Record<string, unknown>;
+    /** Current primary text / rich-HTML content, when the node has one. */
+    text?: string;
+    /** Child target uids in document order. */
+    childUids: string[];
+}
+/** A lane-agnostic edit intent. The adapter maps each to its substrate's ops. */
+export type EditOp = 
+/** Set prop `name` to `value`. `value` may be a RAW control value — the adapter
+ *  coerces it to the prop's model type (the chrome carries no coercion logic). */
+{
+    kind: 'setProp';
+    name: string;
+    value: unknown;
+}
+/** Replace the node's primary text / rich-HTML content with `html`. */
+ | {
+    kind: 'setText';
+    html: string;
+}
+/** Insert a new child of `childType` at `index` among the node's children. */
+ | {
+    kind: 'insertChild';
+    childType: string;
+    index: number;
+}
+/** Move an existing child (`childUid`) to `toIndex` among the node's children. */
+ | {
+    kind: 'moveChild';
+    childUid: string;
+    toIndex: number;
+}
+/** Remove an existing child (`childUid`). */
+ | {
+    kind: 'removeChild';
+    childUid: string;
+};
+/**
+ * The editor port. The chrome resolves a clicked element to a `TargetRef`, reads
+ * the node + its manifest fields, and applies `EditOp`s — all without knowing the
+ * substrate. Returns are synchronous for the ripple lane (see the file header).
+ */
+export interface LaneAdapter {
+    /** Stable lane id, stamped onto every `TargetRef` this adapter emits. */
+    readonly id: string;
+    /** Clicked / hovered element -> its target, or null when none resolves. */
+    resolveElement(el: Element): TargetRef | null;
+    /** Normalized view of the target node, or null when it no longer exists. */
+    readNode(ref: TargetRef): EditableNode | null;
+    /**
+     * Read ONE field's CURRENT value, mirroring `applyEdit`'s write routing so the
+     * value returned is exactly what the matching `setProp` stored. Use this — not
+     * `readNode().props[name]` — to read back a prop the adapter may route OUTSIDE
+     * `props` (top-level-colliding keys like `bind` / `class` / `style`, or a dotted
+     * path into `props`). Returns `undefined` when the node or field is absent.
+     */
+    readProp(ref: TargetRef, name: string): unknown;
+    /** The target's children as refs, in document order. */
+    listChildren(ref: TargetRef): TargetRef[];
+    /** Manifest fields (with current values) for the target — drives the inspector. */
+    getFields(ref: TargetRef): InspectorField[];
+    /** Apply one edit; returns whether it was recognized and applied. */
+    applyEdit(ref: TargetRef, op: EditOp): boolean;
+    /** Which inline-editing affordance the chrome should mount for this lane. */
+    inlineEditor?: 'tiptap' | 'squire' | 'overlay';
+}

package/dist/editor/core/lane-adapter.js

@@ -0,0 +1 @@
+export {};

package/dist/editor/core/memory-persistence-adapter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @file editor/core/memory-persistence-adapter.ts
+ * @description L1 (PURE TS, zero Svelte/DOM) in-memory `PersistenceAdapter` —
+ *   the standalone-lib reference stub (SP-1c-a). It proves the editor's
+ *   host-boundary (`ports.ts`) works with ZERO paw-os: a scope's working spec,
+ *   draft snapshots, and a published-revision log all live in a Map. The REAL
+ *   Branch-backed adapter implements the same interface host-side and drops in
+ *   without touching editor code.
+ *
+ *   Deep-clones on every read and write, so a stored draft/revision can never
+ *   alias the host's live ($state) tree (mutating the live spec must not
+ *   silently rewrite history).
+ * @created 2026-06-27 (SP-1c-a — branch spike/editor-domid-overlay)
+ */
+import { type UINode } from '@ripple-ui/core';
+import type { PersistenceAdapter, ScopeId, DraftRef, Revision } from './ports.js';
+import type { EditorOp } from './editor-ops.js';
+/**
+ * In-memory `PersistenceAdapter`. Default host adapter for the playground and
+ * tests; the canonical proof that the editor needs no backend to run.
+ */
+export declare class MemoryPersistenceAdapter implements PersistenceAdapter {
+    private scopes;
+    /** Seed a scope's initial working spec (host/test setup convenience). */
+    seed(scopeId: ScopeId, spec: UINode): void;
+    private store;
+    loadSpec(scopeId: ScopeId): Promise<UINode | null>;
+    applyOps(scopeId: ScopeId, ops: EditorOp[]): Promise<UINode>;
+    saveDraft(scopeId: ScopeId, spec: UINode): Promise<DraftRef>;
+    publish(scopeId: ScopeId, draft: DraftRef): Promise<Revision>;
+    listRevisions(scopeId: ScopeId): Promise<Revision[]>;
+    restore(scopeId: ScopeId, revisionId: string): Promise<UINode>;
+}