@ripple-ui/svelte 0.0.0-stage → 0.8.2

package/dist/editor/core/bounds-index.d.ts

@@ -0,0 +1,60 @@
+import { type Rect } from './geometry.js';
+/** Attribute the renderer stamps with `node.id` (NodeRenderer SP-0 stamp). */
+export declare const RIPPLE_NODE_ATTR = "data-ripple-node";
+/** Elements that may carry a node id: an explicit `id` or the dedicated attr. */
+export declare const NODE_ID_SELECTOR = "[id],[data-ripple-node]";
+export interface ResolveOptions {
+    /** Node ids known from the spec tree — the precise allow-list. */
+    knownIds?: Set<string> | null;
+    /**
+     * Override id recognition entirely. Default: membership in `knownIds` when
+     * provided, otherwise the ripple `n_xxxxxxxx` id format (`isValidNodeId`).
+     */
+    isNodeId?: (id: string) => boolean;
+    /**
+     * Stop the ancestor walk when this element is reached (EXCLUSIVE). Typically
+     * the render container, so the walk never escapes into the host/stage chrome.
+     */
+    boundary?: Element | null;
+}
+/**
+ * Read the node id carried by a SINGLE element. `data-ripple-node` is our own
+ * stamp (always a node id) and wins; otherwise an `id` the recognizer accepts.
+ * Returns null when the element carries no recognized node id.
+ */
+export declare function nodeIdOf(el: Element, opts?: ResolveOptions): string | null;
+/**
+ * Resolve a clicked/hovered element to its node id, walking up to the nearest
+ * id-bearing ancestor (SELECT-PARENT). Returns null if no node id is found
+ * before the boundary (exclusive) or the document root.
+ */
+export declare function resolveElementToNodeId(target: Element | null, opts?: ResolveOptions): string | null;
+/** id -> container-relative Rect, with an innermost-hit point resolver. */
+export declare class BoundsIndex {
+    #private;
+    constructor(map?: Map<string, Rect>);
+    get size(): number;
+    ids(): string[];
+    get(id: string): Rect | undefined;
+    has(id: string): boolean;
+    /** Innermost (smallest-area) node whose rect contains (x, y); null if none. */
+    resolvePoint(x: number, y: number): string | null;
+}
+/**
+ * THIN DOM BOUNDARY. Build an id -> container-relative Rect index by querying
+ * the container's id/attr-bearing descendants and measuring each. The FIRST
+ * match per id wins (document order = outermost), so a motion-wrapped node maps
+ * to its wrapper, not the inner widget that repeats the id.
+ *
+ * jsdom returns zero rects; the measurement is correct in a real browser. Tests
+ * assert the id SET, not positions (see the file header).
+ */
+export declare function buildBoundsIndex(container: HTMLElement, opts?: ResolveOptions): BoundsIndex;
+/**
+ * THIN DOM BOUNDARY. Find the FIRST element in `container` (document order =
+ * outermost) carrying node `id` — by the dedicated `data-ripple-node` stamp or a
+ * recognized DOM `id`. Used by the inline editor (SP-1b) to target the element
+ * to make contenteditable, and by SP-1c for drag handles. Returns null when no
+ * such element exists (e.g. a non-id-forwarding widget that only select-parents).
+ */
+export declare function findNodeElement(container: HTMLElement, id: string, opts?: ResolveOptions): HTMLElement | null;

package/dist/editor/core/bounds-index.js

@@ -0,0 +1,138 @@
+/**
+ * @file editor/core/bounds-index.ts
+ * @description L1 (PURE TS, zero Svelte/rune imports) DOM-id addressability for
+ *   the Ripple visual-editor overlay. Two layers, deliberately separated so the
+ *   logic is unit-testable without a real browser:
+ *
+ *   1. PURE resolution / math (testable with synthetic rects & jsdom elements):
+ *      - `BoundsIndex.resolvePoint`   point -> innermost node id over a Rect map.
+ *      - `resolveElementToNodeId`     clicked/hovered element -> node id, walking
+ *        UP to the nearest id-bearing ancestor. This is the SELECT-PARENT
+ *        fallback for the ~15% of widget roots that don't forward `id`
+ *        (badge / metric / table / chart / progress / research/*) — see
+ *        docs/design/sp0-spike-report.md.
+ *      - `nodeIdOf`                   read a single element's node id.
+ *
+ *   2. THIN DOM BOUNDARY (one function): `buildBoundsIndex(container)` queries
+ *      `[id],[data-ripple-node]`, reads getBoundingClientRect, and builds an
+ *      id -> container-relative Rect map. jsdom returns ZERO rects, so tests
+ *      assert the id SET this finds, not pixel positions — overlay box geometry
+ *      is deferred to browser confirmation.
+ *
+ *   Primary selector is the DOM `id` (SP-0 GO-WITH-FALLBACK, ~85% of widgets);
+ *   `data-ripple-node` is the dedicated-attribute path (motion wrappers today).
+ * @created 2026-06-27 (SP-1a — branch spike/editor-domid-overlay)
+ */
+import { isValidNodeId } from '@ripple-ui/core';
+import { pointInRect, rectArea, relativeRect } from './geometry.js';
+/** Attribute the renderer stamps with `node.id` (NodeRenderer SP-0 stamp). */
+export const RIPPLE_NODE_ATTR = 'data-ripple-node';
+/** Elements that may carry a node id: an explicit `id` or the dedicated attr. */
+export const NODE_ID_SELECTOR = `[id],[${RIPPLE_NODE_ATTR}]`;
+function recognizer(opts) {
+    if (opts?.isNodeId)
+        return opts.isNodeId;
+    const known = opts?.knownIds;
+    if (known)
+        return (id) => known.has(id);
+    return (id) => isValidNodeId(id);
+}
+/**
+ * Read the node id carried by a SINGLE element. `data-ripple-node` is our own
+ * stamp (always a node id) and wins; otherwise an `id` the recognizer accepts.
+ * Returns null when the element carries no recognized node id.
+ */
+export function nodeIdOf(el, opts) {
+    const stamped = el.getAttribute(RIPPLE_NODE_ATTR);
+    if (stamped)
+        return stamped;
+    const id = el.id;
+    if (id && recognizer(opts)(id))
+        return id;
+    return null;
+}
+/**
+ * Resolve a clicked/hovered element to its node id, walking up to the nearest
+ * id-bearing ancestor (SELECT-PARENT). Returns null if no node id is found
+ * before the boundary (exclusive) or the document root.
+ */
+export function resolveElementToNodeId(target, opts) {
+    const boundary = opts?.boundary ?? null;
+    let el = target;
+    while (el && el !== boundary) {
+        const id = nodeIdOf(el, opts);
+        if (id)
+            return id;
+        el = el.parentElement;
+    }
+    return null;
+}
+/** id -> container-relative Rect, with an innermost-hit point resolver. */
+export class BoundsIndex {
+    #map;
+    constructor(map) {
+        this.#map = map ?? new Map();
+    }
+    get size() {
+        return this.#map.size;
+    }
+    ids() {
+        return [...this.#map.keys()];
+    }
+    get(id) {
+        return this.#map.get(id);
+    }
+    has(id) {
+        return this.#map.has(id);
+    }
+    /** Innermost (smallest-area) node whose rect contains (x, y); null if none. */
+    resolvePoint(x, y) {
+        let bestId = null;
+        let bestArea = Infinity;
+        for (const [id, rect] of this.#map) {
+            if (!pointInRect(rect, x, y))
+                continue;
+            const area = rectArea(rect);
+            if (area < bestArea) {
+                bestArea = area;
+                bestId = id;
+            }
+        }
+        return bestId;
+    }
+}
+/**
+ * THIN DOM BOUNDARY. Build an id -> container-relative Rect index by querying
+ * the container's id/attr-bearing descendants and measuring each. The FIRST
+ * match per id wins (document order = outermost), so a motion-wrapped node maps
+ * to its wrapper, not the inner widget that repeats the id.
+ *
+ * jsdom returns zero rects; the measurement is correct in a real browser. Tests
+ * assert the id SET, not positions (see the file header).
+ */
+export function buildBoundsIndex(container, opts) {
+    const map = new Map();
+    const originRect = container.getBoundingClientRect();
+    const origin = { left: originRect.left, top: originRect.top };
+    for (const el of container.querySelectorAll(NODE_ID_SELECTOR)) {
+        const id = nodeIdOf(el, opts);
+        if (!id || map.has(id))
+            continue;
+        map.set(id, relativeRect(el.getBoundingClientRect(), origin));
+    }
+    return new BoundsIndex(map);
+}
+/**
+ * THIN DOM BOUNDARY. Find the FIRST element in `container` (document order =
+ * outermost) carrying node `id` — by the dedicated `data-ripple-node` stamp or a
+ * recognized DOM `id`. Used by the inline editor (SP-1b) to target the element
+ * to make contenteditable, and by SP-1c for drag handles. Returns null when no
+ * such element exists (e.g. a non-id-forwarding widget that only select-parents).
+ */
+export function findNodeElement(container, id, opts) {
+    for (const el of container.querySelectorAll(NODE_ID_SELECTOR)) {
+        if (nodeIdOf(el, opts) === id)
+            return el;
+    }
+    return null;
+}

package/dist/editor/core/drag-reorder.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @file editor/core/drag-reorder.ts
+ * @description L1 (PURE TS, zero Svelte/rune imports) drop-resolution for the
+ *   visual editor's drag-to-reorder (editor chrome PIECE 2). Given the overlay's
+ *   `BoundsIndex` (id -> container-relative Rect), a dragged node id, and a
+ *   container-relative pointer, it resolves WHICH SIBLING GAP the pointer is over
+ *   and returns the `node_moved` operands `{ new_parent_id, after_id }` (or null
+ *   for a no-op). Pure math + tree lookup, so it is unit-testable over synthetic
+ *   rects and a synthetic sibling accessor — no DOM, no browser.
+ *
+ *   SCOPE v1: SAME-PARENT reorder only. Siblings come from `resolveSiblings`,
+ *   which returns the dragged node's OWN parent, so `new_parent_id` is always the
+ *   current parent. Cross-parent drag (re-homing into a different container) is a
+ *   deliberate FOLLOW-UP — it needs a parent-hit-test the resolver doesn't do yet.
+ *
+ *   `after_id` is the sibling to insert AFTER (matching `spec-mutator`'s
+ *   `applyMoveNode`), or `''` to insert FIRST. It is always one of the OTHER
+ *   siblings (never the dragged node, which `applyMoveNode` removes before
+ *   re-inserting). The drop axis (row vs column) is auto-detected from the spread
+ *   of the sibling centers, so a vertical stack and a horizontal row both work.
+ * @created 2026-06-30 (editor chrome PIECE 2 — drag-to-reorder siblings)
+ */
+import { type UINode } from '@ripple-ui/core';
+import type { EditorOp } from './editor-ops.js';
+import type { BoundsIndex } from './bounds-index.js';
+/** The dragged node's parent id + its sibling ids in document order (incl. self). */
+export interface ParentAndSiblings {
+    parentId: string;
+    /** Sibling ids in document order, INCLUDING the dragged node itself. */
+    siblingIds: string[];
+}
+/** Resolve a node id to its parent + ordered siblings (or null if not found). */
+export type SiblingResolver = (id: string) => ParentAndSiblings | null;
+/** The `node_moved` operands a resolved drop produces. */
+export interface DropTarget {
+    new_parent_id: string;
+    /** Sibling id to insert AFTER, or '' to insert first. */
+    after_id: string;
+}
+/** Build a `SiblingResolver` from a live root accessor (uses `findParent`). */
+export declare function siblingResolverFromRoot(getRoot: () => UINode | null | undefined): SiblingResolver;
+/**
+ * Resolve a drag drop to `{ new_parent_id, after_id }`, or null for a no-op
+ * (pointer resolves to the dragged node's current slot — which includes dropping
+ * it on itself — or there is nothing to reorder against).
+ */
+export declare function resolveSiblingDrop(bounds: BoundsIndex, draggedId: string, pointer: {
+    x: number;
+    y: number;
+}, resolveSiblings: SiblingResolver): DropTarget | null;
+/** Build the wire-shaped `node_moved` op from a resolved drop target. */
+export declare function nodeMovedOp(node_id: string, target: DropTarget): EditorOp;

package/dist/editor/core/drag-reorder.js

@@ -0,0 +1,89 @@
+/**
+ * @file editor/core/drag-reorder.ts
+ * @description L1 (PURE TS, zero Svelte/rune imports) drop-resolution for the
+ *   visual editor's drag-to-reorder (editor chrome PIECE 2). Given the overlay's
+ *   `BoundsIndex` (id -> container-relative Rect), a dragged node id, and a
+ *   container-relative pointer, it resolves WHICH SIBLING GAP the pointer is over
+ *   and returns the `node_moved` operands `{ new_parent_id, after_id }` (or null
+ *   for a no-op). Pure math + tree lookup, so it is unit-testable over synthetic
+ *   rects and a synthetic sibling accessor — no DOM, no browser.
+ *
+ *   SCOPE v1: SAME-PARENT reorder only. Siblings come from `resolveSiblings`,
+ *   which returns the dragged node's OWN parent, so `new_parent_id` is always the
+ *   current parent. Cross-parent drag (re-homing into a different container) is a
+ *   deliberate FOLLOW-UP — it needs a parent-hit-test the resolver doesn't do yet.
+ *
+ *   `after_id` is the sibling to insert AFTER (matching `spec-mutator`'s
+ *   `applyMoveNode`), or `''` to insert FIRST. It is always one of the OTHER
+ *   siblings (never the dragged node, which `applyMoveNode` removes before
+ *   re-inserting). The drop axis (row vs column) is auto-detected from the spread
+ *   of the sibling centers, so a vertical stack and a horizontal row both work.
+ * @created 2026-06-30 (editor chrome PIECE 2 — drag-to-reorder siblings)
+ */
+import { findParent } from '@ripple-ui/core';
+/** Build a `SiblingResolver` from a live root accessor (uses `findParent`). */
+export function siblingResolverFromRoot(getRoot) {
+    return (id) => {
+        const root = getRoot();
+        if (!root)
+            return null;
+        const loc = findParent(root, id);
+        if (!loc || !loc.parent.id)
+            return null;
+        const kids = (loc.parent[loc.key] ?? []);
+        const siblingIds = kids.map((k) => k?.id).filter((x) => !!x);
+        return { parentId: loc.parent.id, siblingIds };
+    };
+}
+/**
+ * Resolve a drag drop to `{ new_parent_id, after_id }`, or null for a no-op
+ * (pointer resolves to the dragged node's current slot — which includes dropping
+ * it on itself — or there is nothing to reorder against).
+ */
+export function resolveSiblingDrop(bounds, draggedId, pointer, resolveSiblings) {
+    const ps = resolveSiblings(draggedId);
+    if (!ps || !ps.parentId)
+        return null;
+    const { parentId, siblingIds } = ps;
+    const d = siblingIds.indexOf(draggedId);
+    if (d === -1)
+        return null;
+    // The dragged node's CURRENT preceding sibling — the after_id that reproduces
+    // its present position. Resolving back to this is the no-op case.
+    const currentAfter = d <= 0 ? '' : siblingIds[d - 1];
+    // Candidates to place against: every OTHER sibling that has a measured rect.
+    // (after_id is always one of these — the dragged node is removed before the
+    // re-insert — or '' for first.)
+    const others = siblingIds.filter((id) => id !== draggedId && !!bounds.get(id));
+    if (others.length === 0)
+        return null;
+    const cells = others.map((id) => {
+        const r = bounds.get(id);
+        return { id, cx: r.left + r.width / 2, cy: r.top + r.height / 2 };
+    });
+    // Auto-detect the layout axis from the spread of sibling centers so a column
+    // (vary in y) and a row (vary in x) both resolve correctly.
+    const xs = cells.map((c) => c.cx);
+    const ys = cells.map((c) => c.cy);
+    const horizontal = Math.max(...xs) - Math.min(...xs) > Math.max(...ys) - Math.min(...ys);
+    const coord = horizontal ? pointer.x : pointer.y;
+    const centerOf = (c) => (horizontal ? c.cx : c.cy);
+    // Insertion index = number of sibling centers the pointer is past along the
+    // axis. after_id is the sibling just before that gap ('' when before the first).
+    let k = cells.findIndex((c) => coord < centerOf(c));
+    if (k === -1)
+        k = cells.length;
+    const afterId = k === 0 ? '' : cells[k - 1].id;
+    if (afterId === currentAfter)
+        return null; // no move (covers self-drop)
+    return { new_parent_id: parentId, after_id: afterId };
+}
+/** Build the wire-shaped `node_moved` op from a resolved drop target. */
+export function nodeMovedOp(node_id, target) {
+    return {
+        action: 'node_moved',
+        node_id,
+        new_parent_id: target.new_parent_id,
+        after_id: target.after_id
+    };
+}

package/dist/editor/core/editable.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Candidate text-prop names in priority order. For a given widget the FIRST
+ * candidate it actually declares (as a string-typed prop in the catalog) is its
+ * primary inline-editable prop. Ordered so the most "headline" text wins: a
+ * heading's `text`, a button's `label`, an alert's `title` beat secondary copy
+ * like `description`. `value` sits late and is only reached by widgets whose
+ * value is string-ish (stat / metric) — numeric-only `value` props are filtered
+ * out by the string-type check, so a slider never becomes "text editable".
+ */
+export declare const TEXT_PROP_PRIORITY: readonly ["text", "label", "title", "content", "heading", "value", "description"];
+/**
+ * Minimal shape this module needs from a catalog prop spec — a structural
+ * subset of the manifest's `WidgetPropSpec`, so a real manifest entry upcasts to
+ * `CatalogEntryLike` without a cast.
+ */
+export interface CatalogPropSpec {
+    /** Declared TS-ish type string, e.g. `"string"` or `'number | string'`. */
+    type?: string;
+}
+/** Minimal shape this module needs from a catalog entry (a manifest entry). */
+export interface CatalogEntryLike {
+    type: string;
+    props?: Record<string, CatalogPropSpec> | null;
+}
+/**
+ * The primary text prop to inline-edit for a catalog entry: the first
+ * `TEXT_PROP_PRIORITY` candidate the entry declares as a string-typed prop, or
+ * null when the widget has no editable text prop. Pure — unit-tested with
+ * synthetic entries, no manifest needed.
+ */
+export declare function resolvePrimaryTextProp(entry: CatalogEntryLike | null | undefined, priority?: readonly string[]): string | null;
+/**
+ * All editable text props for a catalog entry, in priority order (primary
+ * first). Drives the inspector, which renders one field per returned prop.
+ * Pure — same contract as `resolvePrimaryTextProp`.
+ */
+export declare function resolveEditableTextProps(entry: CatalogEntryLike | null | undefined, priority?: readonly string[]): string[];
+/** Catalog entry for a widget type, or null if the type is unknown. */
+export declare function catalogEntry(type: string): CatalogEntryLike | null;
+/** Primary inline-editable text prop for a widget type (catalog-derived). */
+export declare function primaryTextProp(type: string): string | null;
+/** Ordered editable text props for a widget type (catalog-derived). */
+export declare function editableTextProps(type: string): string[];
+/**
+ * Widgets whose rendered textContent equals their primary text prop, so the
+ * double-click contenteditable path can safely round-trip text -> prop. Kept
+ * deliberately small and explicit: every other widget edits via the inspector's
+ * per-prop fields (which never read textContent and so are safe for composites
+ * and multi-text widgets). Each entry is asserted to have a primary text prop in
+ * the catalog by `editable.test.ts`, so this set cannot silently drift from the
+ * manifest. SP-1c's widget codemod (id forwarding) can grow this set later.
+ */
+export declare const INLINE_TEXT_WIDGETS: ReadonlySet<string>;
+/**
+ * True when `type` may be inline-edited via the contenteditable path: it is in
+ * the single-text allow-list AND the catalog confirms it has a primary text
+ * prop. Belt-and-suspenders so a typo in the set can't enable an un-editable
+ * widget.
+ */
+export declare function isInlineTextWidget(type: string): boolean;
+/**
+ * Normalize text harvested from a contenteditable element before it becomes a
+ * prop value: collapse the non-breaking spaces (U+00A0) a browser injects, then
+ * trim. Pure and tiny so the commit path stays predictable; richer
+ * normalization (or a TipTap rich-text upgrade) is a future slice, not v1.
+ */
+export declare function normalizeInlineText(raw: string | null | undefined): string;
+/**
+ * The single prop a rich-text widget stores its authored HTML in. The inline
+ * editor seeds TipTap from `node.props.html` and commits `editor.getHTML()` back
+ * to the same prop. Kept as a named constant so the editor never hard-codes the
+ * magic string.
+ */
+export declare const RICH_TEXT_PROP: "html";
+/**
+ * Widgets edited via the TipTap RICH-HTML path rather than the plain
+ * contenteditable text path: their primary content is structural HTML (stored in
+ * `RICH_TEXT_PROP`), so double-click mounts a TipTap StarterKit editor in place
+ * and commits `getHTML()`. Deliberately separate from `INLINE_TEXT_WIDGETS`
+ * (which round-trips textContent) \u2014 a rich widget would lose its markup through
+ * the textContent path.
+ */
+export declare const RICH_TEXT_WIDGETS: ReadonlySet<string>;
+/**
+ * True when `type` should be edited through the TipTap rich-HTML path. Belt-and-
+ * suspenders mirror of `isInlineTextWidget`: membership in the rich allow-list.
+ */
+export declare function isRichTextWidget(type: string): boolean;

package/dist/editor/core/editable.js

@@ -0,0 +1,167 @@
+/**
+ * @file editor/core/editable.ts
+ * @description L1 (PURE TS, zero Svelte/rune imports) "which prop is editable"
+ *   policy for the Ripple visual editor (SP-1b). Two layers, deliberately split
+ *   so the LOGIC is testable with synthetic data while the catalog binding is
+ *   testable against ground truth:
+ *
+ *   1. PURE RESOLVER over a catalog-entry-like object (no manifest dependency):
+ *      - `resolvePrimaryTextProp(entry)`  -> the single prop to inline-edit.
+ *      - `resolveEditableTextProps(entry)` -> ordered list of string props for
+ *        the inspector (primary first).
+ *      Both walk `TEXT_PROP_PRIORITY` and return the first / all candidate
+ *      prop name(s) the entry DECLARES as a string-typed prop. Data-driven:
+ *      the mapping falls out of the catalog, it is not hand-guessed.
+ *
+ *   2. CATALOG BINDING (the only import — the pure-TS widget manifest):
+ *      - `primaryTextProp(type)` / `editableTextProps(type)` apply the resolver
+ *        to the real widget catalog, so `heading -> text`, `button -> label`,
+ *        `badge -> text`, `alert -> title`, etc. fall out automatically and a
+ *        new widget is picked up the moment it lands in the manifest.
+ *
+ *   Plus the INLINE-EDIT eligibility gate: `INLINE_TEXT_WIDGETS` /
+ *   `isInlineTextWidget(type)`. The double-click contenteditable path reads an
+ *   element's textContent, so it is only correct for SINGLE-TEXT widgets where
+ *   textContent === the primary prop (heading / text / badge / button). Every
+ *   other widget (cards, composites, multi-text widgets like alert/metric) is
+ *   edited via the inspector's per-prop fields, never via textContent.
+ *
+ *   The manifest is pure TS (verified: zero `svelte` imports), so importing it
+ *   here keeps this module grep-clean for runes/Svelte (Decision 6). If the
+ *   manifest's bundle weight ever matters for `@ripple-ui/svelte/editor`, swap
+ *   the import for a generated slim `type -> props` map — the resolver and every
+ *   caller stay unchanged.
+ * @created 2026-06-27 (SP-1b — branch spike/editor-domid-overlay)
+ */
+import { manifestEntries } from '../../manifest/index.js';
+/**
+ * Candidate text-prop names in priority order. For a given widget the FIRST
+ * candidate it actually declares (as a string-typed prop in the catalog) is its
+ * primary inline-editable prop. Ordered so the most "headline" text wins: a
+ * heading's `text`, a button's `label`, an alert's `title` beat secondary copy
+ * like `description`. `value` sits late and is only reached by widgets whose
+ * value is string-ish (stat / metric) — numeric-only `value` props are filtered
+ * out by the string-type check, so a slider never becomes "text editable".
+ */
+export const TEXT_PROP_PRIORITY = [
+    'text',
+    'label',
+    'title',
+    'content',
+    'heading',
+    'value',
+    'description',
+];
+/**
+ * A prop is "text-ish" if its declared catalog type mentions `string`. This
+ * keeps numeric-only props (`level: "1 | 2 | …"`, a numeric `value`) out of the
+ * editable set while still admitting `value: "number | string"`.
+ */
+function isStringProp(spec) {
+    return !!spec && typeof spec.type === 'string' && /string/i.test(spec.type);
+}
+/**
+ * The primary text prop to inline-edit for a catalog entry: the first
+ * `TEXT_PROP_PRIORITY` candidate the entry declares as a string-typed prop, or
+ * null when the widget has no editable text prop. Pure — unit-tested with
+ * synthetic entries, no manifest needed.
+ */
+export function resolvePrimaryTextProp(entry, priority = TEXT_PROP_PRIORITY) {
+    const props = entry?.props;
+    if (!props)
+        return null;
+    for (const cand of priority) {
+        if (isStringProp(props[cand]))
+            return cand;
+    }
+    return null;
+}
+/**
+ * All editable text props for a catalog entry, in priority order (primary
+ * first). Drives the inspector, which renders one field per returned prop.
+ * Pure — same contract as `resolvePrimaryTextProp`.
+ */
+export function resolveEditableTextProps(entry, priority = TEXT_PROP_PRIORITY) {
+    const props = entry?.props;
+    if (!props)
+        return [];
+    return priority.filter((cand) => isStringProp(props[cand]));
+}
+// --------------------------------------------------------------------------
+// Catalog binding — the manifest is the source of truth for type -> props.
+// --------------------------------------------------------------------------
+const CATALOG = new Map(manifestEntries.map((e) => [e.type, e]));
+/** Catalog entry for a widget type, or null if the type is unknown. */
+export function catalogEntry(type) {
+    return CATALOG.get(type) ?? null;
+}
+/** Primary inline-editable text prop for a widget type (catalog-derived). */
+export function primaryTextProp(type) {
+    return resolvePrimaryTextProp(CATALOG.get(type));
+}
+/** Ordered editable text props for a widget type (catalog-derived). */
+export function editableTextProps(type) {
+    return resolveEditableTextProps(CATALOG.get(type));
+}
+// --------------------------------------------------------------------------
+// Inline-edit eligibility — the contenteditable (textContent) path.
+// --------------------------------------------------------------------------
+/**
+ * Widgets whose rendered textContent equals their primary text prop, so the
+ * double-click contenteditable path can safely round-trip text -> prop. Kept
+ * deliberately small and explicit: every other widget edits via the inspector's
+ * per-prop fields (which never read textContent and so are safe for composites
+ * and multi-text widgets). Each entry is asserted to have a primary text prop in
+ * the catalog by `editable.test.ts`, so this set cannot silently drift from the
+ * manifest. SP-1c's widget codemod (id forwarding) can grow this set later.
+ */
+export const INLINE_TEXT_WIDGETS = new Set([
+    'heading',
+    'text',
+    'badge',
+    'button',
+]);
+/**
+ * True when `type` may be inline-edited via the contenteditable path: it is in
+ * the single-text allow-list AND the catalog confirms it has a primary text
+ * prop. Belt-and-suspenders so a typo in the set can't enable an un-editable
+ * widget.
+ */
+export function isInlineTextWidget(type) {
+    return INLINE_TEXT_WIDGETS.has(type) && primaryTextProp(type) !== null;
+}
+/**
+ * Normalize text harvested from a contenteditable element before it becomes a
+ * prop value: collapse the non-breaking spaces (U+00A0) a browser injects, then
+ * trim. Pure and tiny so the commit path stays predictable; richer
+ * normalization (or a TipTap rich-text upgrade) is a future slice, not v1.
+ */
+export function normalizeInlineText(raw) {
+    return (raw ?? '').replace(/\u00a0/g, ' ').trim();
+}
+// --------------------------------------------------------------------------
+// Rich-HTML edit eligibility \u2014 the TipTap path (editor chrome PIECE 1).
+// --------------------------------------------------------------------------
+/**
+ * The single prop a rich-text widget stores its authored HTML in. The inline
+ * editor seeds TipTap from `node.props.html` and commits `editor.getHTML()` back
+ * to the same prop. Kept as a named constant so the editor never hard-codes the
+ * magic string.
+ */
+export const RICH_TEXT_PROP = 'html';
+/**
+ * Widgets edited via the TipTap RICH-HTML path rather than the plain
+ * contenteditable text path: their primary content is structural HTML (stored in
+ * `RICH_TEXT_PROP`), so double-click mounts a TipTap StarterKit editor in place
+ * and commits `getHTML()`. Deliberately separate from `INLINE_TEXT_WIDGETS`
+ * (which round-trips textContent) \u2014 a rich widget would lose its markup through
+ * the textContent path.
+ */
+export const RICH_TEXT_WIDGETS = new Set(['richtext']);
+/**
+ * True when `type` should be edited through the TipTap rich-HTML path. Belt-and-
+ * suspenders mirror of `isInlineTextWidget`: membership in the rich allow-list.
+ */
+export function isRichTextWidget(type) {
+    return RICH_TEXT_WIDGETS.has(type);
+}

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

@@ -0,0 +1,58 @@
+/**
+ * @file editor/core/editor-ops.ts
+ * @description L1 (PURE TS, zero Svelte/rune imports) one-op apply SEAM for the
+ *   Ripple visual editor (SP-1b). This is the single choke point every editor
+ *   mutation flows through — inline text edit AND inspector prop edit both call
+ *   `setNodeProp`, which builds one wire-shaped `node_prop_set` payload and runs
+ *   it through `spec-mutator`'s `applyOp` against the host's live root.
+ *
+ *   The host owns the spec in Svelte `$state` (a deep proxy) and passes a
+ *   `getRoot` accessor; `applyOp` mutates that proxy IN PLACE, so the canvas
+ *   repaints reactively (SP-0 §3). After a successful op, `onApplied(op)` fires —
+ *   that is the documented interception point SP-1c (persistence / Branch) hangs
+ *   off to `saveDraft(root)` without any change to the call sites. Keeping the
+ *   op stream behind one function means undo/redo (a later slice) can also wrap
+ *   it (capture the inverse `applyOp` returns) in exactly one place.
+ *
+ *   Pure: no Svelte, no DOM. The only reactivity is in the host's `$state` root;
+ *   this module just routes payloads, so it is fully unit-testable over a plain
+ *   object tree.
+ * @created 2026-06-27 (SP-1b — branch spike/editor-domid-overlay)
+ */
+import { type UINode } from '@ripple-ui/core';
+/** A mutation payload as understood by `spec-mutator`'s `applyOp`. */
+export type EditorOp = Record<string, unknown>;
+/**
+ * Build a wire-shaped `node_prop_set` payload — the one op SP-1b emits. `prop`
+ * may be a top-level field (`text` is in `props`; `class`/`show`/… are top-level
+ * — `applySetNodeProp` routes them) or a dotted path into `props`.
+ */
+export declare function nodePropSet(node_id: string, prop: string, value: unknown): EditorOp;
+export interface EditorOpsOptions {
+    /**
+     * Accessor for the live root node. MUST return the same `$state` proxy the
+     * renderer reads, or mutations won't be reactive. Returning null/undefined
+     * makes `apply` a no-op (returns false) instead of throwing.
+     */
+    getRoot: () => UINode | null | undefined;
+    /**
+     * Called after an op is successfully applied, with the op that ran. SP-1c
+     * persistence hooks here (e.g. debounce a `saveDraft(getRoot())`); the host's
+     * lab wiring uses it to bump the overlay's re-measure `renderVersion`.
+     */
+    onApplied?: (op: EditorOp) => void;
+    /** Called when `applyOp` throws (bad node id, illegal move). Defaults to rethrow. */
+    onError?: (err: unknown, op: EditorOp) => void;
+}
+export interface EditorOps {
+    /** Apply one raw op; returns whether `applyOp` recognized + applied it. */
+    apply: (op: EditorOp) => boolean;
+    /** Convenience for the only op SP-1b emits — builds + applies `node_prop_set`. */
+    setNodeProp: (node_id: string, prop: string, value: unknown) => boolean;
+}
+/**
+ * Create the editor op seam bound to a host's live root accessor. Every editor
+ * entry point (inline edit, inspector) goes through the returned `apply` /
+ * `setNodeProp`, so `onApplied` is the one place to wire persistence/undo later.
+ */
+export declare function createEditorOps(opts: EditorOpsOptions): EditorOps;