@ripple-ui/svelte 0.0.0-stage → 0.8.2

package/dist/editor/core/memory-persistence-adapter.js

@@ -0,0 +1,90 @@
+/**
+ * @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 { applyOp } from '@ripple-ui/core';
+/**
+ * JSON round-trip clone (NOT structuredClone): structuredClone throws
+ * DataCloneError on a Svelte `$state` proxy. Callers currently pass
+ * `$state.snapshot()`-ed (plain) specs, but JSON keeps this proxy-safe whatever a
+ * caller hands in. Specs are plain JSON, so the round-trip is lossless.
+ */
+function clone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/**
+ * In-memory `PersistenceAdapter`. Default host adapter for the playground and
+ * tests; the canonical proof that the editor needs no backend to run.
+ */
+export class MemoryPersistenceAdapter {
+    scopes = new Map();
+    /** Seed a scope's initial working spec (host/test setup convenience). */
+    seed(scopeId, spec) {
+        this.store(scopeId).working = clone(spec);
+    }
+    store(scopeId) {
+        let s = this.scopes.get(scopeId);
+        if (!s) {
+            s = { working: null, drafts: new Map(), revisions: [], revisionSpecs: new Map(), seq: 0 };
+            this.scopes.set(scopeId, s);
+        }
+        return s;
+    }
+    async loadSpec(scopeId) {
+        const s = this.store(scopeId);
+        return s.working ? clone(s.working) : null;
+    }
+    async applyOps(scopeId, ops) {
+        const s = this.store(scopeId);
+        if (!s.working) {
+            throw new Error(`applyOps: no working spec for scope "${scopeId}" (seed or saveDraft first)`);
+        }
+        const root = clone(s.working);
+        for (const op of ops)
+            applyOp(root, op);
+        s.working = root;
+        return clone(root);
+    }
+    async saveDraft(scopeId, spec) {
+        const s = this.store(scopeId);
+        const draftId = `d${++s.seq}`;
+        s.drafts.set(draftId, clone(spec));
+        s.working = clone(spec);
+        return { scopeId, draftId };
+    }
+    async publish(scopeId, draft) {
+        const s = this.store(scopeId);
+        const draftSpec = s.drafts.get(draft.draftId);
+        if (!draftSpec) {
+            throw new Error(`publish: unknown draft "${draft.draftId}" for scope "${scopeId}"`);
+        }
+        const revisionId = `r${++s.seq}`;
+        const rev = { scopeId, revisionId };
+        s.revisions.push(rev);
+        s.revisionSpecs.set(revisionId, clone(draftSpec));
+        s.working = clone(draftSpec);
+        return rev;
+    }
+    async listRevisions(scopeId) {
+        return this.store(scopeId).revisions.map((r) => ({ ...r }));
+    }
+    async restore(scopeId, revisionId) {
+        const s = this.store(scopeId);
+        const spec = s.revisionSpecs.get(revisionId);
+        if (!spec) {
+            throw new Error(`restore: unknown revision "${revisionId}" for scope "${scopeId}"`);
+        }
+        s.working = clone(spec);
+        return clone(spec);
+    }
+}

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

@@ -0,0 +1,77 @@
+/**
+ * @file editor/core/ports.ts
+ * @description L1 (PURE TS, zero Svelte/DOM) host-boundary PORTS for the Ripple
+ *   visual editor (SP-1c-a). The editor talks to the outside world ONLY through
+ *   these interfaces — never a paw-os endpoint — which is exactly what keeps
+ *   `@ripple-ui/svelte` a standalone, framework-agnostic library: a host
+ *   (paw-os, or anyone) implements the ports against its own stack
+ *   (Branch / Fabric / S3 / agent, or their own), and the editor is unchanged.
+ *
+ *   Only `PersistenceAdapter` has an impl today (`MemoryPersistenceAdapter`,
+ *   the in-memory reference stub). The REAL Branch-backed adapter is a
+ *   host-side slice that drops in here unchanged. The sibling ports are
+ *   declared (types only) so the boundary contract is complete.
+ * @created 2026-06-27 (SP-1c-a — branch spike/editor-domid-overlay)
+ */
+import type { UINode } from '@ripple-ui/core';
+import type { EditorOp } from './editor-ops.js';
+/** Identifies the artifact being edited (pocket id, site id, …). */
+export type ScopeId = string;
+/** Handle to a saved (unpublished) draft snapshot. */
+export interface DraftRef {
+    scopeId: ScopeId;
+    draftId: string;
+}
+/** A published point in a scope's history. */
+export interface Revision {
+    scopeId: ScopeId;
+    revisionId: string;
+    label?: string;
+}
+/**
+ * How the editor loads, mutates, drafts, publishes, and restores a spec. The
+ * host owns the actual store; paw-os implements this over the Branch primitive
+ * (draft → review → publish + revert + history). The editor depends on this
+ * INTERFACE only — never a concrete host — per the standalone-lib boundary.
+ */
+export interface PersistenceAdapter {
+    /** Current (published) spec for a scope, or null if none yet. */
+    loadSpec(scopeId: ScopeId): Promise<UINode | null>;
+    /** Apply ops to the scope's working spec; returns the updated root. */
+    applyOps(scopeId: ScopeId, ops: EditorOp[]): Promise<UINode>;
+    /** Snapshot a spec as a draft (the editor's `onApplied` hook debounces this). */
+    saveDraft(scopeId: ScopeId, spec: UINode): Promise<DraftRef>;
+    /** Promote a draft to a published revision. */
+    publish(scopeId: ScopeId, draft: DraftRef): Promise<Revision>;
+    /** History for a scope, oldest first. */
+    listRevisions(scopeId: ScopeId): Promise<Revision[]>;
+    /** Restore a prior revision as the working spec; returns it. */
+    restore(scopeId: ScopeId, revisionId: string): Promise<UINode>;
+}
+/**
+ * Resolves live-data bindings for bound nodes (paw-os: Fabric / D1; anyone:
+ * their REST/GraphQL). Type-only for now — the editor's bound-node handling
+ * (a later slice) consumes this.
+ */
+export interface DataSourceAdapter {
+    resolveBinding(binding: unknown): Promise<unknown>;
+}
+/**
+ * Where exported artifacts (PDF / PPTX / MP4) land (paw-os: S3 / the per-tenant
+ * artifacts blob; anyone: their bucket). Type-only for now — Pillar 3 export
+ * consumes this.
+ */
+export interface ExportStorageAdapter {
+    put(file: Blob, meta: Record<string, unknown>): Promise<{
+        url: string;
+    }>;
+}
+/**
+ * Optional agent that emits the SAME ops the editor emits (paw-os: Claude /
+ * pocket_specialist; anyone: their agent, or none). Type-only for now —
+ * agent-assisted authoring is a later slice. This is why the editor is
+ * agent-agnostic: authoring is just an op stream.
+ */
+export interface AuthoringAgentAdapter {
+    proposeOps(prompt: string, context?: unknown): AsyncIterable<EditorOp[]>;
+}

package/dist/editor/core/ports.js

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

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

@@ -0,0 +1,80 @@
+/**
+ * @file editor/core/ripple-lane-adapter.ts
+ * @description L1 (PURE TS, zero Svelte/rune imports) the RIPPLE implementation of
+ *   the `LaneAdapter` port (EP-1). It adapts the existing editor primitives —
+ *   `resolveElementToNodeId` (DOM -> node id), `findById` (read), `inferFields`
+ *   (manifest fields), and the `EditorOps` one-op seam over `spec-mutator` (write)
+ *   — to the lane-agnostic `LaneAdapter` interface, so the chrome can drive the
+ *   ripple substrate without importing any of those directly.
+ *
+ *   COERCION lives HERE, not in the chrome. `applyEdit({kind:'setProp'})` accepts
+ *   a RAW control value and coerces it to the prop's model type by re-deriving the
+ *   field's kind/numeric from the manifest (`inferFields(node)`) and calling
+ *   `coerceFieldValue` — the exact (kind, numeric) the inspector used to read off
+ *   `inferFields` itself, so the write is byte-identical to the pre-port path. The
+ *   inspector is thereby freed of every coercion / manifest import.
+ *
+ *   WRITE PATH. All four mutating ops route through one internal `EditorOps`
+ *   (`createEditorOps({ getRoot, onApplied })`), so `onApplied` fires after each
+ *   successful apply exactly as before (the lab bumps `renderVersion` off it) and
+ *   a future undo/redo still wraps a single choke point. `applyEdit` never throws:
+ *   a bad ref / illegal move is swallowed and reported as `false` (the port
+ *   contract), so the chrome branches on a boolean, not a try/catch.
+ *
+ *   BOUNDARY. `resolveElement` needs the ancestor-walk boundary (the render
+ *   container) that the port signature can't carry, so the host supplies it via an
+ *   optional `getBoundary` accessor — the same stage element every other editor
+ *   piece already receives. When omitted, the walk runs to the document root,
+ *   which stays correct because `knownIds` is the precise allow-list (host chrome
+ *   can't carry a known node id).
+ * @created 2026-06-30 (EP-1 — LaneAdapter port + Ripple adapter)
+ * @changes 2026-06-30 (EP-1 review): add `readProp` (mirrors the write routing via
+ *   `getNodeProp` so a read returns what a write stored); the internal EditorOps
+ *   `onError` now `console.warn`s instead of swallowing silently, so genuinely bad
+ *   ops aren't invisible.
+ */
+import { type UINode } from '@ripple-ui/core';
+import { type InspectorField } from './inspector-fields.js';
+import { type EditorOp } from './editor-ops.js';
+import type { EditableNode, EditOp, LaneAdapter, TargetRef } from './lane-adapter.js';
+export interface RippleLaneAdapterOptions {
+    /**
+     * Accessor for the live root node. MUST return the same `$state` proxy the
+     * renderer reads, or writes won't be reactive (same contract as `EditorOps`).
+     */
+    getRoot: () => UINode | null | undefined;
+    /** Fired after each successful apply (the lab bumps its re-measure version). */
+    onApplied?: (op: EditorOp) => void;
+    /** Precise node-id allow-list for element resolution (author content can't pass). */
+    knownIds?: Set<string> | null;
+    /**
+     * Ancestor-walk boundary for `resolveElement` (EXCLUSIVE) — typically the render
+     * container. Omit to walk to the document root (safe under `knownIds`).
+     */
+    getBoundary?: () => Element | null;
+}
+/** The ripple substrate adapter (the first `LaneAdapter`). */
+export declare class RippleLaneAdapter implements LaneAdapter {
+    #private;
+    readonly id = "ripple";
+    readonly inlineEditor: "tiptap";
+    constructor(opts: RippleLaneAdapterOptions);
+    /** Clicked / hovered element -> its `TargetRef`, walking up to the nearest node. */
+    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 the write routing via `getNodeProp`:
+     * a top-level-colliding key (`bind`, `class`, `style`, …) reads off the node, a
+     * dotted path reads nested in `props`, everything else reads `props[name]`. This
+     * is the correct `onedit` readback — `readNode().props[name]` misses any prop the
+     * write routed OUTSIDE `props`. Returns `undefined` when the node/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;
+}

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

@@ -0,0 +1,197 @@
+/**
+ * @file editor/core/ripple-lane-adapter.ts
+ * @description L1 (PURE TS, zero Svelte/rune imports) the RIPPLE implementation of
+ *   the `LaneAdapter` port (EP-1). It adapts the existing editor primitives —
+ *   `resolveElementToNodeId` (DOM -> node id), `findById` (read), `inferFields`
+ *   (manifest fields), and the `EditorOps` one-op seam over `spec-mutator` (write)
+ *   — to the lane-agnostic `LaneAdapter` interface, so the chrome can drive the
+ *   ripple substrate without importing any of those directly.
+ *
+ *   COERCION lives HERE, not in the chrome. `applyEdit({kind:'setProp'})` accepts
+ *   a RAW control value and coerces it to the prop's model type by re-deriving the
+ *   field's kind/numeric from the manifest (`inferFields(node)`) and calling
+ *   `coerceFieldValue` — the exact (kind, numeric) the inspector used to read off
+ *   `inferFields` itself, so the write is byte-identical to the pre-port path. The
+ *   inspector is thereby freed of every coercion / manifest import.
+ *
+ *   WRITE PATH. All four mutating ops route through one internal `EditorOps`
+ *   (`createEditorOps({ getRoot, onApplied })`), so `onApplied` fires after each
+ *   successful apply exactly as before (the lab bumps `renderVersion` off it) and
+ *   a future undo/redo still wraps a single choke point. `applyEdit` never throws:
+ *   a bad ref / illegal move is swallowed and reported as `false` (the port
+ *   contract), so the chrome branches on a boolean, not a try/catch.
+ *
+ *   BOUNDARY. `resolveElement` needs the ancestor-walk boundary (the render
+ *   container) that the port signature can't carry, so the host supplies it via an
+ *   optional `getBoundary` accessor — the same stage element every other editor
+ *   piece already receives. When omitted, the walk runs to the document root,
+ *   which stays correct because `knownIds` is the precise allow-list (host chrome
+ *   can't carry a known node id).
+ * @created 2026-06-30 (EP-1 — LaneAdapter port + Ripple adapter)
+ * @changes 2026-06-30 (EP-1 review): add `readProp` (mirrors the write routing via
+ *   `getNodeProp` so a read returns what a write stored); the internal EditorOps
+ *   `onError` now `console.warn`s instead of swallowing silently, so genuinely bad
+ *   ops aren't invisible.
+ */
+import { findById, getNodeProp } from '@ripple-ui/core';
+import { resolveElementToNodeId } from './bounds-index.js';
+import { inferFields, coerceFieldValue } from './inspector-fields.js';
+import { primaryTextProp, isRichTextWidget, RICH_TEXT_PROP } from './editable.js';
+import { createEditorOps } from './editor-ops.js';
+/** The ripple substrate adapter (the first `LaneAdapter`). */
+export class RippleLaneAdapter {
+    id = 'ripple';
+    inlineEditor = 'tiptap';
+    #getRoot;
+    #knownIds;
+    #getBoundary;
+    /**
+     * This adapter's OWN write seam — every mutating op (setProp/setText/insert/
+     * move/remove) routes through it. NOTE: the lab also constructs a SECOND
+     * `EditorOps` (its `ops`, driving inline-edit / drag) over the SAME `$state`
+     * root. Two seams is benign today (each just calls `applyOp`), but the future
+     * undo/redo slice MUST unify them — `editor-ops.ts` intends ONE choke point so
+     * the inverse it returns is captured in a single place.
+     */
+    #ops;
+    constructor(opts) {
+        this.#getRoot = opts.getRoot;
+        this.#knownIds = opts.knownIds ?? null;
+        this.#getBoundary = opts.getBoundary;
+        // One internal seam for every write (see the #ops field note). `onError`
+        // keeps the port contract — applyEdit still returns `false` (never throws) and
+        // onApplied still fires on success — but no longer swallows SILENTLY: a bad op
+        // (bad node id / illegal move) is surfaced via console.warn so it isn't
+        // invisible. (import.meta.env isn't typed in this lib's tsconfig, so we can't
+        // dev-guard on it without a type error; a clear-prefixed warn is the fallback.)
+        this.#ops = createEditorOps({
+            getRoot: opts.getRoot,
+            onApplied: opts.onApplied,
+            onError: (err, op) => console.warn('[RippleLaneAdapter] op swallowed (applyEdit→false):', op, err)
+        });
+    }
+    /** Clicked / hovered element -> its `TargetRef`, walking up to the nearest node. */
+    resolveElement(el) {
+        const uid = resolveElementToNodeId(el, {
+            knownIds: this.#knownIds,
+            boundary: this.#getBoundary?.() ?? null
+        });
+        return uid ? { uid, lane: this.id } : null;
+    }
+    /** Normalized view of the target node, or null when it no longer exists. */
+    readNode(ref) {
+        const node = findById(this.#getRoot(), ref.uid);
+        if (!node?.id)
+            return null;
+        const props = (node.props ?? {});
+        const childUids = (node.children ?? [])
+            .map((c) => c?.id)
+            .filter((id) => !!id);
+        const node_ = { uid: node.id, type: node.type, props: { ...props }, childUids };
+        const text = readPrimaryText(node, props);
+        if (text !== undefined)
+            node_.text = text;
+        return node_;
+    }
+    /**
+     * Read one field's CURRENT value, mirroring the write routing via `getNodeProp`:
+     * a top-level-colliding key (`bind`, `class`, `style`, …) reads off the node, a
+     * dotted path reads nested in `props`, everything else reads `props[name]`. This
+     * is the correct `onedit` readback — `readNode().props[name]` misses any prop the
+     * write routed OUTSIDE `props`. Returns `undefined` when the node/field is absent.
+     */
+    readProp(ref, name) {
+        return getNodeProp(this.#getRoot(), ref.uid, name);
+    }
+    /** The target's children as refs, in document order. */
+    listChildren(ref) {
+        const node = findById(this.#getRoot(), ref.uid);
+        if (!node?.children)
+            return [];
+        return node.children
+            .filter((c) => !!c?.id)
+            .map((c) => ({ uid: c.id, lane: this.id }));
+    }
+    /** Manifest fields (with current values) for the target — drives the inspector. */
+    getFields(ref) {
+        return inferFields(findById(this.#getRoot(), ref.uid));
+    }
+    /** Apply one edit; returns whether it was recognized and applied. */
+    applyEdit(ref, op) {
+        switch (op.kind) {
+            case 'setProp':
+                return this.#ops.setNodeProp(ref.uid, op.name, this.#coerceProp(ref, op.name, op.value));
+            case 'setText': {
+                const prop = this.#textProp(ref);
+                return prop ? this.#ops.setNodeProp(ref.uid, prop, op.html) : false;
+            }
+            case 'insertChild':
+                return this.#ops.apply(insertChildOp(ref.uid, op, this.#getRoot()));
+            // moveChild/removeChild ASSUME `op.childUid` is an actual child of `ref`:
+            // moveChild computes `after_id` from `ref`'s children (so a non-child yields
+            // a meaningless position), and removeChild treats `ref` as the parent. True
+            // for the inspector slice (it never calls either); the future drag/overlay
+            // consumer MUST pass real children (a bad id throws → swallowed to `false`).
+            case 'moveChild':
+                return this.#ops.apply(moveChildOp(ref.uid, op, this.#getRoot()));
+            case 'removeChild':
+                return this.#ops.apply({ action: 'node_removed', node_id: op.childUid });
+            default:
+                return false;
+        }
+    }
+    /**
+     * Coerce a RAW prop value to its model type by re-deriving the field's
+     * kind/numeric from the manifest — the same (kind, numeric) the inspector read
+     * off `inferFields`, so the write is identical to the pre-port path. A prop with
+     * no inferred field (shouldn't happen on the inspector path) passes through.
+     */
+    #coerceProp(ref, name, raw) {
+        const field = this.getFields(ref).find((f) => f.prop === name);
+        return field ? coerceFieldValue(field.kind, raw, field.numeric) : raw;
+    }
+    /** The prop `setText` writes for this node: rich-HTML prop, else primary text prop. */
+    #textProp(ref) {
+        const node = findById(this.#getRoot(), ref.uid);
+        if (!node)
+            return null;
+        return isRichTextWidget(node.type) ? RICH_TEXT_PROP : primaryTextProp(node.type);
+    }
+}
+/** Current primary text / rich-HTML value of a node, when it has a string one. */
+function readPrimaryText(node, props) {
+    const prop = isRichTextWidget(node.type) ? RICH_TEXT_PROP : primaryTextProp(node.type);
+    if (!prop)
+        return undefined;
+    const value = props[prop];
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * Map `insertChild` -> a `node_added` payload. `after_id` is the id of the child
+ * currently before `index` (insert AFTER it); index 0 / empty parent fall through
+ * to an anchorless add. NOTE: `node_added` appends when anchorless, so inserting
+ * at index 0 of a NON-empty parent lands last — a `node_added` contract limit, not
+ * a bug here. The slice that actually wires insertChild handles strict-position-0
+ * (e.g. a follow-up move); the inspector slice never inserts.
+ */
+function insertChildOp(parentId, op, root) {
+    const kids = findById(root, parentId)?.children ?? [];
+    const after = op.index > 0 ? kids[op.index - 1]?.id ?? null : null;
+    return { action: 'node_added', parent_id: parentId, after_id: after, subtree: { type: op.childType } };
+}
+/**
+ * Map `moveChild` -> a `node_moved` payload. `toIndex` is the FINAL position among
+ * siblings; `after_id` is the sibling that should precede the moved child in the
+ * post-move list (computed over the siblings WITHOUT the moving child, since
+ * `applyMoveNode` removes it before re-inserting). Empty `after_id` inserts first.
+ * Assumes `childUid` is currently a child of `parentId` (the caller's `ref`) — the
+ * sibling math is over `parentId`'s children, so a non-child yields a nonsensical
+ * position. The inspector slice never calls this; the drag consumer must honor it.
+ */
+function moveChildOp(parentId, op, root) {
+    const kids = findById(root, parentId)?.children ?? [];
+    const rest = kids.map((c) => c?.id).filter((id) => !!id && id !== op.childUid);
+    const clamped = Math.min(Math.max(op.toIndex, 0), rest.length);
+    const after = clamped === 0 ? '' : rest[clamped - 1];
+    return { action: 'node_moved', node_id: op.childUid, new_parent_id: parentId, after_id: after };
+}

package/dist/editor/core/selection-model.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @file editor/core/selection-model.ts
+ * @description L1 (PURE TS, zero Svelte/rune imports) selection state for the
+ *   Ripple visual editor: which node id is SELECTED and which is HOVERED. This
+ *   is the framework-agnostic single source of truth for selection — the Svelte
+ *   L2 (`editor-selection.svelte.ts`) mirrors it reactively, and a future
+ *   React/Vue L2 would wrap it the same way (Decision 6). Mutators return
+ *   whether they changed anything (so a reactive wrapper only re-renders on real
+ *   changes) and notify subscribers. No DOM, no runes — fully unit-testable.
+ *   SP-1b (inline edit) and SP-1c (drag) attach to this same model.
+ * @created 2026-06-27 (SP-1a — branch spike/editor-domid-overlay)
+ */
+export interface SelectionState {
+    selectedId: string | null;
+    hoverId: string | null;
+}
+export type SelectionListener = (state: SelectionState) => void;
+export declare class SelectionModel {
+    #private;
+    constructor(initial?: Partial<SelectionState>);
+    get selectedId(): string | null;
+    get hoverId(): string | null;
+    getState(): SelectionState;
+    isSelected(id: string | null): boolean;
+    isHovered(id: string | null): boolean;
+    /** Set the selected node id (null clears). Returns true if it changed. */
+    select(id: string | null): boolean;
+    /** Set the hovered node id (null clears). Returns true if it changed. */
+    hover(id: string | null): boolean;
+    /** Select `id`, or clear selection if it is already the selected node. */
+    toggle(id: string): boolean;
+    /** Clear both selection and hover. Returns true if anything changed. */
+    clear(): boolean;
+    subscribe(fn: SelectionListener): () => void;
+}
+export declare function createSelectionModel(initial?: Partial<SelectionState>): SelectionModel;

package/dist/editor/core/selection-model.js

@@ -0,0 +1,79 @@
+/**
+ * @file editor/core/selection-model.ts
+ * @description L1 (PURE TS, zero Svelte/rune imports) selection state for the
+ *   Ripple visual editor: which node id is SELECTED and which is HOVERED. This
+ *   is the framework-agnostic single source of truth for selection — the Svelte
+ *   L2 (`editor-selection.svelte.ts`) mirrors it reactively, and a future
+ *   React/Vue L2 would wrap it the same way (Decision 6). Mutators return
+ *   whether they changed anything (so a reactive wrapper only re-renders on real
+ *   changes) and notify subscribers. No DOM, no runes — fully unit-testable.
+ *   SP-1b (inline edit) and SP-1c (drag) attach to this same model.
+ * @created 2026-06-27 (SP-1a — branch spike/editor-domid-overlay)
+ */
+export class SelectionModel {
+    #selectedId;
+    #hoverId;
+    #listeners = new Set();
+    constructor(initial) {
+        this.#selectedId = initial?.selectedId ?? null;
+        this.#hoverId = initial?.hoverId ?? null;
+    }
+    get selectedId() {
+        return this.#selectedId;
+    }
+    get hoverId() {
+        return this.#hoverId;
+    }
+    getState() {
+        return { selectedId: this.#selectedId, hoverId: this.#hoverId };
+    }
+    isSelected(id) {
+        return id != null && id === this.#selectedId;
+    }
+    isHovered(id) {
+        return id != null && id === this.#hoverId;
+    }
+    /** Set the selected node id (null clears). Returns true if it changed. */
+    select(id) {
+        if (this.#selectedId === id)
+            return false;
+        this.#selectedId = id;
+        this.#emit();
+        return true;
+    }
+    /** Set the hovered node id (null clears). Returns true if it changed. */
+    hover(id) {
+        if (this.#hoverId === id)
+            return false;
+        this.#hoverId = id;
+        this.#emit();
+        return true;
+    }
+    /** Select `id`, or clear selection if it is already the selected node. */
+    toggle(id) {
+        return this.select(this.#selectedId === id ? null : id);
+    }
+    /** Clear both selection and hover. Returns true if anything changed. */
+    clear() {
+        if (this.#selectedId === null && this.#hoverId === null)
+            return false;
+        this.#selectedId = null;
+        this.#hoverId = null;
+        this.#emit();
+        return true;
+    }
+    subscribe(fn) {
+        this.#listeners.add(fn);
+        return () => {
+            this.#listeners.delete(fn);
+        };
+    }
+    #emit() {
+        const snapshot = this.getState();
+        for (const fn of this.#listeners)
+            fn(snapshot);
+    }
+}
+export function createSelectionModel(initial) {
+    return new SelectionModel(initial);
+}

package/dist/editor/editor-selection.svelte.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @file editor/editor-selection.svelte.ts
+ * @description L2 (Svelte) reactive adapter over the L1 `SelectionModel`. Holds
+ *   a `$state` version counter bumped on every real selection/hover change, and
+ *   reads it inside each getter so Svelte tracks them as reactive dependencies —
+ *   the L1 model stays the single source of truth (and stays pure/unit-tested),
+ *   while the overlay re-renders when selection changes. A host can share ONE
+ *   instance across the overlay and the future inline-editor (SP-1b) so they
+ *   agree on the selected node. Mirrors the repo's pure-core + reactive-wrapper
+ *   idiom (state-mutator.ts <- StateManager).
+ * @created 2026-06-27 (SP-1a — branch spike/editor-domid-overlay)
+ */
+import { SelectionModel, type SelectionState } from './core/index.js';
+export declare class EditorSelection {
+    #private;
+    constructor(initial?: Partial<SelectionState>);
+    get selectedId(): string | null;
+    get hoverId(): string | null;
+    isSelected(id: string | null): boolean;
+    isHovered(id: string | null): boolean;
+    select(id: string | null): void;
+    hover(id: string | null): void;
+    toggle(id: string): void;
+    clear(): void;
+    /** Escape hatch to the underlying pure model (read-only / advanced use). */
+    get model(): SelectionModel;
+}
+export declare function createEditorSelection(initial?: Partial<SelectionState>): EditorSelection;

package/dist/editor/editor-selection.svelte.js

@@ -0,0 +1,61 @@
+/**
+ * @file editor/editor-selection.svelte.ts
+ * @description L2 (Svelte) reactive adapter over the L1 `SelectionModel`. Holds
+ *   a `$state` version counter bumped on every real selection/hover change, and
+ *   reads it inside each getter so Svelte tracks them as reactive dependencies —
+ *   the L1 model stays the single source of truth (and stays pure/unit-tested),
+ *   while the overlay re-renders when selection changes. A host can share ONE
+ *   instance across the overlay and the future inline-editor (SP-1b) so they
+ *   agree on the selected node. Mirrors the repo's pure-core + reactive-wrapper
+ *   idiom (state-mutator.ts <- StateManager).
+ * @created 2026-06-27 (SP-1a — branch spike/editor-domid-overlay)
+ */
+import { SelectionModel } from './core/index.js';
+export class EditorSelection {
+    #model;
+    // Bumped on every change the model reports; `void`-read inside getters so the
+    // Svelte compiler registers them as reactive reads.
+    #version = $state(0);
+    constructor(initial) {
+        this.#model = new SelectionModel(initial);
+    }
+    get selectedId() {
+        void this.#version;
+        return this.#model.selectedId;
+    }
+    get hoverId() {
+        void this.#version;
+        return this.#model.hoverId;
+    }
+    isSelected(id) {
+        void this.#version;
+        return this.#model.isSelected(id);
+    }
+    isHovered(id) {
+        void this.#version;
+        return this.#model.isHovered(id);
+    }
+    select(id) {
+        if (this.#model.select(id))
+            this.#version++;
+    }
+    hover(id) {
+        if (this.#model.hover(id))
+            this.#version++;
+    }
+    toggle(id) {
+        if (this.#model.toggle(id))
+            this.#version++;
+    }
+    clear() {
+        if (this.#model.clear())
+            this.#version++;
+    }
+    /** Escape hatch to the underlying pure model (read-only / advanced use). */
+    get model() {
+        return this.#model;
+    }
+}
+export function createEditorSelection(initial) {
+    return new EditorSelection(initial);
+}