smoodly 0.0.12 → 0.0.14

package/dist/admin/editor/inline-dom.js

@@ -0,0 +1,43 @@
+// The DOM rules of a session (spec 2026-09-10 §3–§5), pure over structural
+// types so they run under bare node: what a text session may edit, how a
+// value is written in place, and which layout the richtext editor root
+// copies from its container.
+/** A marked element the text session may edit: no child elements. A mark
+ *  on a container (an <a> inside a <p>) falls through to the inspector. */
+export const isPlainTextHost = (el) => el.childElementCount === 0;
+/** Write `value` in place: into the one existing text node when there is
+ *  one, so the site's React keeps pointing at the node it rendered and a
+ *  refresh reconciles into it; else as new text content. False when the
+ *  element is not a plain text host. */
+export function writeTextInto(el, value) {
+    if (!isPlainTextHost(el))
+        return false;
+    const first = el.firstChild;
+    if (first && first.nodeType === 3 && first.nextSibling === null) {
+        if (first.nodeValue !== value)
+            first.nodeValue = value;
+    }
+    else {
+        el.textContent = value;
+    }
+    return true;
+}
+/** The container's layout the richtext editor root copies (spec §5), so a
+ *  flex-column or grid container keeps its block spacing while its
+ *  children are hidden behind the editor. Kebab-cased, for setProperty. */
+export const LAYOUT_PROPS = [
+    "display", "flex-direction", "gap", "row-gap", "column-gap",
+    "grid-template-columns", "grid-auto-flow", "align-items", "justify-content",
+];
+export function layoutToCopy(computed) {
+    const display = computed.getPropertyValue("display");
+    if (display !== "flex" && display !== "grid")
+        return {};
+    const out = {};
+    for (const prop of LAYOUT_PROPS) {
+        const v = computed.getPropertyValue(prop);
+        if (v)
+            out[prop] = v;
+    }
+    return out;
+}

package/dist/admin/editor/inline-session.d.ts

@@ -0,0 +1,30 @@
+export type SessionKind = "text" | "richtext";
+export type Session = {
+    node: string;
+    path: string;
+    kind: SessionKind;
+};
+export type InlineState = {
+    session: Session | null;
+    pendingRefresh: boolean;
+};
+export type InlineEvent = {
+    type: "start";
+    session: Session;
+} | {
+    type: "end";
+}
+/** The autosave's save ack arrived. */
+ | {
+    type: "saved";
+}
+/** The iframe points at a new URL: nothing from the old canvas survives. */
+ | {
+    type: "canvas";
+};
+export declare const INITIAL_INLINE: InlineState;
+/** The next state, and whether to post a refresh to the bridge now. */
+export declare function reduceInline(state: InlineState, event: InlineEvent): {
+    state: InlineState;
+    refresh: boolean;
+};

package/dist/admin/editor/inline-session.js

@@ -0,0 +1,19 @@
+export const INITIAL_INLINE = { session: null, pendingRefresh: false };
+/** The next state, and whether to post a refresh to the bridge now. */
+export function reduceInline(state, event) {
+    switch (event.type) {
+        case "start":
+            // A pending refresh stays pending: it fires only once no session is active.
+            return { state: { session: event.session, pendingRefresh: state.pendingRefresh }, refresh: false };
+        case "end":
+            if (!state.session)
+                return { state, refresh: false };
+            return { state: INITIAL_INLINE, refresh: state.pendingRefresh };
+        case "saved":
+            return state.session
+                ? { state: { session: state.session, pendingRefresh: true }, refresh: false }
+                : { state, refresh: true };
+        case "canvas":
+            return { state: INITIAL_INLINE, refresh: false };
+    }
+}

package/dist/admin/editor/protocol.d.ts

@@ -12,20 +12,41 @@ export type ZoneRect = {
     w: number;
     h: number;
 };
+/** A marked element (spec 2026-09-10 §6): its section node and its resolved dotted path. */
+export type FieldRect = {
+    node: string;
+    path: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
 export type FromBridge = {
     source: "smoodly";
     kind: "rects";
     nodes: BridgeRect[];
     emptyZones: ZoneRect[];
+    fields: FieldRect[];
     docH: number;
-} | {
+}
+/** A click: the node under it, the marked field under it, and where (iframe client coordinates). */
+ | {
     source: "smoodly";
     kind: "select";
     id: string | null;
+    path: string | null;
+    x: number;
+    y: number;
 } | {
     source: "smoodly";
     kind: "hover";
     id: string | null;
+    path: string | null;
+}
+/** The bridge committed a render — after a refresh, the new markup is in the DOM. */
+ | {
+    source: "smoodly";
+    kind: "rendered";
 };
 export type ToBridge = {
     source: "smoodly";

package/dist/admin/editor/useCanvasBridge.d.ts

@@ -1,14 +1,18 @@
 import { type RefObject } from "react";
-import type { BridgeRect, ToBridge, ZoneRect } from "./protocol.ts";
+import type { BridgeRect, FieldRect, ToBridge, ZoneRect } from "./protocol.ts";
 export type Geometry = "waiting" | "ok" | "missing";
-export declare function useCanvasBridge({ iframeRef, iframeSrc, onSelect, onHover }: {
+export declare function useCanvasBridge({ iframeRef, iframeSrc, onSelect, onHover, onRendered }: {
     iframeRef: RefObject<HTMLIFrameElement | null>;
     iframeSrc: string | null;
-    onSelect(id: string | null): void;
-    onHover(id: string | null): void;
+    /** A click in the canvas: the node, the marked field under it (or null), and where in the iframe. */
+    onSelect(id: string | null, path: string | null, x: number, y: number): void;
+    onHover(id: string | null, path: string | null): void;
+    /** The bridge committed a render (the mount, then every refresh). */
+    onRendered(): void;
 }): {
     rects: BridgeRect[];
     emptyZones: ZoneRect[];
+    fields: FieldRect[];
     docH: number;
     geometry: Geometry;
     postToCanvas: (m: ToBridge) => void;

package/dist/admin/editor/useCanvasBridge.js

@@ -5,18 +5,19 @@
 // goes dark, the iframe and the outline keep working.
 import { useCallback, useEffect, useRef, useState } from "react";
 const GEOMETRY_TIMEOUT_MS = 4000;
-export function useCanvasBridge({ iframeRef, iframeSrc, onSelect, onHover }) {
+export function useCanvasBridge({ iframeRef, iframeSrc, onSelect, onHover, onRendered }) {
     const [rects, setRects] = useState([]);
     const [emptyZones, setEmptyZones] = useState([]);
+    const [fields, setFields] = useState([]);
     const [docH, setDocH] = useState(900);
     const [geometry, setGeometry] = useState("waiting");
     // The listener registers once; the handlers are read through refs.
-    const handlers = useRef({ onSelect, onHover });
-    handlers.current = { onSelect, onHover };
+    const handlers = useRef({ onSelect, onHover, onRendered });
+    handlers.current = { onSelect, onHover, onRendered };
     // A new canvas URL (a locale switch, a rename) means new geometry — the
     // previous page's rects are stale the instant the iframe starts loading
     // a different route, so clear them alongside resetting geometry.
-    useEffect(() => { setGeometry("waiting"); setRects([]); setEmptyZones([]); }, [iframeSrc]);
+    useEffect(() => { setGeometry("waiting"); setRects([]); setEmptyZones([]); setFields([]); }, [iframeSrc]);
     const postToCanvas = useCallback((m) => {
         iframeRef.current?.contentWindow?.postMessage(m, "*");
     }, [iframeRef]);
@@ -30,14 +31,18 @@ export function useCanvasBridge({ iframeRef, iframeSrc, onSelect, onHover }) {
             if (m.kind === "rects") {
                 setRects(m.nodes);
                 setEmptyZones(m.emptyZones);
+                setFields(m.fields);
                 setDocH(m.docH);
                 setGeometry("ok");
             }
             else if (m.kind === "select") {
-                handlers.current.onSelect(m.id);
+                handlers.current.onSelect(m.id, m.path, m.x, m.y);
             }
             else if (m.kind === "hover") {
-                handlers.current.onHover(m.id);
+                handlers.current.onHover(m.id, m.path);
+            }
+            else if (m.kind === "rendered") {
+                handlers.current.onRendered();
             }
         };
         window.addEventListener("message", onMessage);
@@ -49,5 +54,5 @@ export function useCanvasBridge({ iframeRef, iframeSrc, onSelect, onHover }) {
         const t = setTimeout(() => setGeometry((g) => (g === "waiting" ? "missing" : g)), GEOMETRY_TIMEOUT_MS);
         return () => clearTimeout(t);
     }, [iframeSrc, geometry]);
-    return { rects, emptyZones, docH, geometry, postToCanvas };
+    return { rects, emptyZones, fields, docH, geometry, postToCanvas };
 }

package/dist/admin/editor/useInlineSession.d.ts

@@ -0,0 +1,46 @@
+import { type RefObject } from "react";
+import { type Session } from "./inline-session.ts";
+import type { ToBridge } from "./protocol.ts";
+export type RichtextMount = {
+    session: Session;
+    /** The marked container; its rendered children are hidden while `root` is inside it. */
+    container: HTMLElement;
+    /** The editor root appended inside the container, in the iframe's document. It is
+     *  `display: contents`: the container's flex/grid layout goes on the element holding
+     *  the blocks (InlineRichtext puts `layout` on the ProseMirror root), so the page's
+     *  gap between paragraphs survives the session. */
+    root: HTMLElement;
+    /** The container's layout to copy onto the ProseMirror root (inline-dom `layoutToCopy`). */
+    layout: Record<string, string>;
+    /** Removes the document-level Escape listener; set by the mount, called by the release. */
+    unlisten?: () => void;
+    /** Where the click landed, iframe client coordinates — the caret goes there. */
+    at: {
+        x: number;
+        y: number;
+    } | null;
+    /** Ended with changes: read-only until the refresh has rendered (spec §5). */
+    closing: boolean;
+};
+type Point = {
+    x: number;
+    y: number;
+} | null;
+export declare function useInlineSession({ iframeRef, postToCanvas, patch }: {
+    iframeRef: RefObject<HTMLIFrameElement | null>;
+    postToCanvas(m: ToBridge): void;
+    /** Write a field value into the tree by node id and dotted path. */
+    patch(node: string, path: string, value: unknown): void;
+}): {
+    session: Session | null;
+    richtext: RichtextMount | null;
+    start: (session: Session, at: Point) => boolean;
+    end: () => void;
+    writeText: (node: string, path: string, value: string) => void;
+    markChanged: () => void;
+    onSaved: () => void;
+    onRendered: () => void;
+    onSelection: (id: string | null) => void;
+    onCanvasChange: () => void;
+};
+export {};

package/dist/admin/editor/useInlineSession.js

@@ -0,0 +1,244 @@
+"use client";
+// The inline editing session's DOM side (spec 2026-09-10 §3–§7). The
+// admin reaches the canvas iframe's document — same origin, the reason
+// the admin is embedded (DESIGN.md §2) — for exactly three things: a text
+// session (contentEditable on the real element), a richtext session (a
+// root appended inside the real container for InlineRichtext to portal
+// into, the rendered children hidden meanwhile) and the instant text
+// write. Everything mutates in place — the site's React keeps owning its
+// nodes, and a refresh reconciles into them. The decisions (one session,
+// the deferred refresh) are the pure reducer in ./inline-session.ts.
+import { useCallback, useEffect, useRef, useState } from "react";
+import { EDITOR_ATTR, FIELD_ATTR, resolveMarkPath } from "../../marks.js";
+import { ADMIN_CSS } from "../ui/theme.js";
+import { isPlainTextHost, layoutToCopy, writeTextInto } from "./inline-dom.js";
+import { INITIAL_INLINE, reduceInline } from "./inline-session.js";
+/** How long a closing richtext editor waits for the refresh's `rendered` before letting go anyway. */
+const CLOSE_FALLBACK_MS = 4000;
+/** On a hidden child: its inline display before the session, restored after. */
+const HIDDEN_ATTR = "data-smd-hidden";
+export function useInlineSession({ iframeRef, postToCanvas, patch }) {
+    const [state, setState] = useState(INITIAL_INLINE);
+    const stateRef = useRef(state);
+    const [richtext, setRichtext] = useState(null);
+    const richtextRef = useRef(null);
+    const changedRef = useRef(false);
+    const textRef = useRef(null);
+    const closeTimer = useRef(null);
+    const patchRef = useRef(patch);
+    patchRef.current = patch;
+    const dispatch = useCallback((event) => {
+        const { state: next, refresh } = reduceInline(stateRef.current, event);
+        stateRef.current = next;
+        setState(next);
+        if (refresh)
+            postToCanvas({ source: "smoodly", kind: "refresh" });
+    }, [postToCanvas]);
+    /** The page's elements marked for this node and path — never the admin's own editor DOM. */
+    const findMarked = useCallback((d, node, path) => Array.from(d.querySelectorAll(`[${FIELD_ATTR}]`)).filter((el) => {
+        if (el.closest(`[${EDITOR_ATTR}]`))
+            return false;
+        const m = resolveMarkPath(el);
+        return m !== null && m.node === node && m.path === path;
+    }), []);
+    // ── richtext: mount and release ────────────────────────────────────────
+    const release = useCallback((mount) => {
+        if (closeTimer.current) {
+            clearTimeout(closeTimer.current);
+            closeTimer.current = null;
+        }
+        mount.unlisten?.();
+        richtextRef.current = null;
+        setRichtext(null);
+        mount.root.remove();
+        for (const child of Array.from(mount.container.children)) {
+            const was = child.getAttribute(HIDDEN_ATTR);
+            if (was === null)
+                continue;
+            child.style.display = was;
+            child.removeAttribute(HIDDEN_ATTR);
+        }
+    }, []);
+    const endRef = useRef(() => { }); // `end`, declared below — both sessions end through it
+    const mountRichtext = useCallback((d, session, at) => {
+        const container = findMarked(d, session.node, session.path)[0];
+        if (!container)
+            return false;
+        ensureStyles(d);
+        const root = d.createElement("div");
+        root.setAttribute(EDITOR_ATTR, "");
+        root.style.display = "contents";
+        const view = d.defaultView;
+        const layout = view ? layoutToCopy(view.getComputedStyle(container)) : {};
+        for (const child of Array.from(container.children)) {
+            child.setAttribute(HIDDEN_ATTR, child.style.display);
+            child.style.display = "none";
+        }
+        container.appendChild(root);
+        // Escape with the focus outside the editor — a card's button took it — still ends the
+        // session; inside, the editor's own keymap runs first (useRichtextEditor's onEscape).
+        const onKey = (e) => {
+            // No `instanceof Node`: the target belongs to the iframe's realm, not the admin's.
+            if (e.key !== "Escape" || richtextRef.current?.closing || root.contains(e.target))
+                return;
+            e.preventDefault();
+            e.stopPropagation();
+            endRef.current();
+        };
+        d.addEventListener("keydown", onKey, true);
+        const mount = { session, container, root, at, closing: false, layout, unlisten: () => d.removeEventListener("keydown", onKey, true) };
+        richtextRef.current = mount;
+        setRichtext(mount);
+        changedRef.current = false;
+        return true;
+    }, [findMarked]);
+    // ── the text session ────────────────────────────────────────────────────
+    const mountText = useCallback((d, session, at) => {
+        const el = findMarked(d, session.node, session.path).find(isPlainTextHost);
+        if (!el)
+            return false;
+        el.setAttribute("contenteditable", "plaintext-only");
+        const onInput = () => patchRef.current(session.node, session.path, el.textContent ?? "");
+        const onKey = (e) => {
+            if (e.key === "Enter" || e.key === "Escape") {
+                e.preventDefault();
+                e.stopPropagation();
+                endRef.current();
+            }
+        };
+        const onBlur = () => endRef.current();
+        el.addEventListener("input", onInput);
+        el.addEventListener("keydown", onKey);
+        el.addEventListener("blur", onBlur);
+        textRef.current = {
+            el,
+            teardown: () => {
+                el.removeEventListener("input", onInput);
+                el.removeEventListener("keydown", onKey);
+                el.removeEventListener("blur", onBlur);
+                el.removeAttribute("contenteditable");
+                // Back to one text node holding the value — what the site's React rendered.
+                const single = el.childNodes.length === 1 && el.firstChild?.nodeType === 3;
+                if (!single)
+                    el.textContent = el.textContent ?? "";
+            },
+        };
+        el.focus({ preventScroll: true });
+        if (at)
+            placeCaret(d, at.x, at.y);
+        return true;
+    }, [findMarked]);
+    // ── start and end ───────────────────────────────────────────────────────
+    const end = useCallback(() => {
+        if (!stateRef.current.session)
+            return;
+        const text = textRef.current;
+        const mount = richtextRef.current;
+        const changed = changedRef.current;
+        // The reducer first: the blur that removing contenteditable fires re-enters here and must see no session.
+        dispatch({ type: "end" });
+        if (text) {
+            textRef.current = null;
+            text.teardown();
+        }
+        if (mount && !mount.closing) {
+            if (changed) {
+                // Stay mounted read-only until the refresh has rendered, so the old markup never flashes.
+                const closing = { ...mount, closing: true };
+                richtextRef.current = closing;
+                setRichtext(closing);
+                closeTimer.current = setTimeout(() => { if (richtextRef.current === closing)
+                    release(closing); }, CLOSE_FALLBACK_MS);
+            }
+            else {
+                release(mount);
+            }
+        }
+    }, [dispatch, release]);
+    endRef.current = end;
+    const start = useCallback((session, at) => {
+        const d = iframeRef.current?.contentDocument;
+        if (!d)
+            return false;
+        // A closing editor still holds its container: a new session on that field waits; any other releases it.
+        const mount = richtextRef.current;
+        if (mount?.closing) {
+            if (mount.session.node === session.node && mount.session.path === session.path)
+                return false;
+            release(mount);
+        }
+        end();
+        const ok = session.kind === "text" ? mountText(d, session, at) : mountRichtext(d, session, at);
+        if (ok)
+            dispatch({ type: "start", session });
+        return ok;
+    }, [iframeRef, dispatch, end, release, mountText, mountRichtext]);
+    // ── the instant write (spec §7) ─────────────────────────────────────────
+    const writeText = useCallback((node, path, value) => {
+        const d = iframeRef.current?.contentDocument;
+        if (!d)
+            return;
+        for (const el of findMarked(d, node, path)) {
+            if (textRef.current?.el === el)
+                continue; // the session's own element is the source
+            writeTextInto(el, value);
+        }
+    }, [iframeRef, findMarked]);
+    // ── signals from the editor ─────────────────────────────────────────────
+    const markChanged = useCallback(() => { changedRef.current = true; }, []);
+    const onSaved = useCallback(() => dispatch({ type: "saved" }), [dispatch]);
+    const onRendered = useCallback(() => {
+        const mount = richtextRef.current;
+        if (mount?.closing)
+            release(mount);
+    }, [release]);
+    const onSelection = useCallback((id) => {
+        const s = stateRef.current.session;
+        if (s && s.node !== id)
+            end();
+    }, [end]);
+    const onCanvasChange = useCallback(() => {
+        // The old document is gone: tear down without a refresh, tolerating detached nodes.
+        const text = textRef.current;
+        textRef.current = null;
+        if (text) {
+            try {
+                text.teardown();
+            }
+            catch { /* the element left with its document */ }
+        }
+        const mount = richtextRef.current;
+        if (mount)
+            release(mount);
+        dispatch({ type: "canvas" });
+    }, [dispatch, release]);
+    useEffect(() => () => { if (closeTimer.current)
+        clearTimeout(closeTimer.current); }, []);
+    return { session: state.session, richtext, start, end, writeText, markChanged, onSaved, onRendered, onSelection, onCanvasChange };
+}
+/** The admin stylesheet inside the iframe, once: the cards inside the canvas editor are admin UI. */
+function ensureStyles(d) {
+    if (d.querySelector("style[data-smoodly-admin-styles]"))
+        return;
+    const style = d.createElement("style");
+    style.setAttribute("data-smoodly-admin-styles", "");
+    style.textContent = ADMIN_CSS;
+    d.head.appendChild(style);
+}
+/** The caret at a point, for the text session (spec §4). */
+function placeCaret(d, x, y) {
+    const sel = d.getSelection();
+    if (!sel)
+        return;
+    const doc = d;
+    const pos = doc.caretPositionFromPoint?.(x, y);
+    if (pos) {
+        sel.collapse(pos.offsetNode, pos.offset);
+        return;
+    }
+    const range = doc.caretRangeFromPoint?.(x, y);
+    if (range) {
+        sel.removeAllRanges();
+        sel.addRange(range);
+    }
+}

package/dist/admin/field-paths.d.ts

@@ -0,0 +1,13 @@
+import type { AdminField } from "./serialize.ts";
+export declare const splitPath: (path: string) => string[];
+/** The descriptor at `path` in `section.fields`; null when the path is
+ *  not in the schema. A list without an item descriptor is a list of text
+ *  (the same default FieldWidget renders). */
+export declare function descriptorAt(section: {
+    fields: Record<string, AdminField>;
+}, path: string): AdminField | null;
+export declare function getAtPath(fields: Record<string, unknown> | undefined, path: string): unknown;
+/** `fields` with the value at `path` replaced. Copies only the spine —
+ *  siblings keep their identity — and keeps arrays arrays. Missing
+ *  objects along the way are created. */
+export declare function setAtPath(fields: Record<string, unknown> | undefined, path: string, value: unknown): Record<string, unknown>;

package/dist/admin/field-paths.js

@@ -0,0 +1,49 @@
+export const splitPath = (path) => path.split(".").filter((s) => s !== "");
+const isIndex = (s) => /^\d+$/.test(s);
+/** The descriptor at `path` in `section.fields`; null when the path is
+ *  not in the schema. A list without an item descriptor is a list of text
+ *  (the same default FieldWidget renders). */
+export function descriptorAt(section, path) {
+    const segments = splitPath(path);
+    if (segments.length === 0)
+        return null;
+    let d = section.fields[segments[0]];
+    for (const seg of segments.slice(1)) {
+        if (!d)
+            return null;
+        if (d.type === "list")
+            d = isIndex(seg) ? d.item ?? { type: "text" } : undefined;
+        else if (d.type === "object")
+            d = d.fields?.[seg];
+        else
+            return null;
+    }
+    return d ?? null;
+}
+export function getAtPath(fields, path) {
+    let v = fields;
+    for (const seg of splitPath(path)) {
+        if (v === null || typeof v !== "object")
+            return undefined;
+        v = v[seg];
+    }
+    return v;
+}
+/** `fields` with the value at `path` replaced. Copies only the spine —
+ *  siblings keep their identity — and keeps arrays arrays. Missing
+ *  objects along the way are created. */
+export function setAtPath(fields, path, value) {
+    const set = (obj, segments) => {
+        if (segments.length === 0)
+            return value;
+        const [head, ...rest] = segments;
+        if (Array.isArray(obj)) {
+            const copy = obj.slice();
+            copy[Number(head)] = set(obj[Number(head)], rest);
+            return copy;
+        }
+        const o = (obj !== null && typeof obj === "object" ? obj : {});
+        return { ...o, [head]: set(o[head], rest) };
+    };
+    return set(fields ?? {}, splitPath(path));
+}

package/dist/admin/forms/FieldWidget.d.ts

@@ -1,6 +1,6 @@
-import { type ReactElement } from "react";
+import type { ReactElement, ReactNode } from "react";
 import type { AdminField } from "../serialize.ts";
-export declare function FieldWidget({ descriptor: d, value, onChange, errors, path: pathProp, bare, refOptions, fieldKey, prefix, }: {
+export declare function FieldWidget({ descriptor: d, value: valueProp, onChange, errors, path: pathProp, bare, refOptions, fieldKey, prefix, mark, inlinePath, onEditHere, }: {
     descriptor: AdminField;
     value: unknown;
     onChange(value: unknown): void;
@@ -16,4 +16,9 @@ export declare function FieldWidget({ descriptor: d, value, onChange, errors, pa
     }[];
     fieldKey: string;
     prefix?: string;
+    /** A glyph after the label — the forms' "same in every language" mark. */
+    mark?: ReactNode;
+    /** The path of the field being edited in the canvas: its richtext widget yields to a note. */
+    inlinePath?: string;
+    onEditHere?(): void;
 }): ReactElement;