smoodly 0.0.12 → 0.0.13

package/dist/admin/forms/RichtextElementCard.js

@@ -0,0 +1,37 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// The element node view (spec 2026-09-08 block nodes §3): the node view IS
+// the form — a header (icon, title, collapse, delete) and the element's
+// fields then styles through FieldWidget, reading and writing attrs.
+// A richtext field inside mounts a nested RichtextWidget with its own
+// toolset. Errors come from the enclosing form under
+// `<path>.elements.<i>.<key>`, i being this node's index among the
+// document's element nodes. Collapse is component state only: a card
+// starts collapsed (2026-09-09) unless it holds nothing yet — a freshly
+// inserted element opens, so its fields can be filled straight away.
+import { useState } from "react";
+import { NodeViewWrapper } from "@tiptap/react";
+import { IconButton } from "../ui/primitives.js";
+import { FieldWidget } from "./FieldWidget.js";
+import { useElements } from "./elements-context.js";
+import { cardClass, useRichtextForm } from "./richtext-form-context.js";
+import { elementIndexAt } from "./richtext-insert.js";
+/** No field holds a value yet — the state right after an insert. */
+function isBlank(fields) {
+    return Object.values(fields).every((v) => v === undefined || v === null || v === "");
+}
+export function RichtextElementCard({ node, editor, getPos, updateAttributes, deleteNode, selected }) {
+    const elements = useElements();
+    const form = useRichtextForm();
+    const name = String(node.attrs.name ?? "");
+    const element = elements.find((e) => e.name === name);
+    const fields = (node.attrs.fields && typeof node.attrs.fields === "object" ? node.attrs.fields : {});
+    const styles = (node.attrs.styles && typeof node.attrs.styles === "object" ? node.attrs.styles : {});
+    const [open, setOpen] = useState(() => isBlank(fields));
+    const pos = getPos();
+    const index = typeof pos === "number" ? elementIndexAt(editor.state.doc, pos) : 0;
+    const base = `${form.path}.elements.${index}`;
+    const select = () => { if (typeof pos === "number")
+        editor.commands.setNodeSelection(pos); };
+    return (_jsxs(NodeViewWrapper, { className: cardClass(selected, form.canvas), "data-theme": form.canvas ? "light" : undefined, children: [_jsxs("div", { className: "sm-rtcard__head", "data-drag-handle": true, onClick: select, children: [_jsx("span", { className: "sm-rtcard__icon", "aria-hidden": "true", children: element?.icon ?? "▤" }), _jsx("span", { className: "sm-rtcard__title", children: element?.title ?? `Unknown element "${name}"` }), _jsx(IconButton, { label: open ? "Collapse" : "Expand", onClick: (e) => { e.stopPropagation(); setOpen((o) => !o); }, children: open ? "▾" : "▸" }), _jsx(IconButton, { label: "Delete element", onClick: (e) => { e.stopPropagation(); deleteNode(); }, children: "\u00D7" })] }), open && element && (_jsxs("div", { className: "sm-rtcard__body", contentEditable: false, children: [Object.entries(element.fields).map(([key, d]) => (_jsx(FieldWidget, { fieldKey: key, descriptor: d, value: fields[key], errors: form.errors, path: `${base}.${key}`, onChange: (v) => updateAttributes({ fields: { ...fields, [key]: v } }) }, key))), Object.entries(element.styles).map(([key, d]) => (_jsx(FieldWidget, { fieldKey: key, descriptor: d, value: styles[key], path: `${base}.styles.${key}`, onChange: (v) => updateAttributes({ styles: { ...styles, [key]: v } }) }, `style-${key}`)))] }))] }));
+}

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

@@ -0,0 +1,3 @@
+import { type ReactElement } from "react";
+import { type NodeViewProps } from "@tiptap/react";
+export declare function RichtextImageCard({ node, editor, getPos, updateAttributes, deleteNode, selected }: NodeViewProps): ReactElement;

package/dist/admin/forms/RichtextImageCard.js

@@ -0,0 +1,42 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// The image node view (spec 2026-09-08 block nodes §3): thumbnail,
+// filename, an alt input whose placeholder is the library's alt, a
+// caption input, Replace and Delete. Attribute edits go through
+// updateAttributes so the outer history sees them. Inputs stop keys from
+// reaching the editor (TipTap's node view stops events from form
+// controls), so Backspace in the caption never deletes the node.
+import { useEffect, useState } from "react";
+import { NodeViewWrapper } from "@tiptap/react";
+import { IconButton } from "../ui/primitives.js";
+import { useAssets } from "./assets-context.js";
+import { MediaPicker } from "./MediaPicker.js";
+import { cardClass, useRichtextForm } from "./richtext-form-context.js";
+export function RichtextImageCard({ node, editor, getPos, updateAttributes, deleteNode, selected }) {
+    const assets = useAssets();
+    const form = useRichtextForm();
+    const value = (node.attrs.image ?? {});
+    const caption = typeof node.attrs.caption === "string" ? node.attrs.caption : "";
+    const id = typeof value.asset === "string" ? value.asset : null;
+    const [asset, setAsset] = useState(null);
+    const [picker, setPicker] = useState(false);
+    useEffect(() => {
+        if (!id) {
+            setAsset(null);
+            return;
+        }
+        let live = true;
+        assets.get(id).then((r) => { if (live)
+            setAsset(r); });
+        return () => { live = false; };
+    }, [id, assets]);
+    const select = () => { const pos = getPos(); if (typeof pos === "number")
+        editor.commands.setNodeSelection(pos); };
+    const setAlt = (alt) => updateAttributes({ image: alt === "" ? { asset: id } : { asset: id, alt } });
+    const replace = (record) => {
+        assets.remember(record);
+        setPicker(false);
+        updateAttributes({ image: value.alt ? { asset: record.id, alt: value.alt } : { asset: record.id } });
+    };
+    return (_jsxs(NodeViewWrapper, { className: cardClass(selected, form.canvas), "data-theme": form.canvas ? "light" : undefined, "data-drag-handle": true, children: [_jsxs("div", { className: "sm-rtcard__head", onClick: select, children: [_jsx("span", { className: "sm-rtcard__icon", "aria-hidden": "true", children: "\u25A3" }), _jsx("span", { className: "sm-rtcard__title", children: "Image" }), _jsx(IconButton, { label: "Replace image", onClick: () => setPicker(true), children: "\u21BB" }), _jsx(IconButton, { label: "Delete image", onClick: () => deleteNode(), children: "\u00D7" })] }), _jsxs("div", { className: "sm-rtcard__body", contentEditable: false, children: [asset ? _jsx("img", { className: "sm-rtcard__thumb", src: asset.url, alt: "" }) : _jsx("div", { className: "sm-rtcard__thumb", style: { height: 80 } }), asset && _jsx("span", { className: "sm-rtcard__file", children: asset.filename }), _jsx("input", { className: "sm-input", "aria-label": "Alt text", placeholder: asset?.alt ?? "Alt text", value: value.alt ?? "", onChange: (e) => setAlt(e.target.value) }), _jsx("input", { className: "sm-input", "aria-label": "Caption", placeholder: "Caption", value: caption, onChange: (e) => updateAttributes({ caption: e.target.value }) })] }), picker && _jsx(MediaPicker, { kinds: ["image"], onPick: replace, onClose: () => setPicker(false) })] }));
+}

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

@@ -0,0 +1,6 @@
+import type { InsertItem } from "./richtext-insert.ts";
+export declare function RichtextInsertMenu({ items, active, onPick }: {
+    items: InsertItem[];
+    active: number;
+    onPick(item: InsertItem): void;
+}): import("react").JSX.Element;

package/dist/admin/forms/RichtextInsertMenu.js

@@ -0,0 +1,6 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const keepFocus = (e) => e.preventDefault();
+export function RichtextInsertMenu({ items, active, onPick }) {
+    return (_jsxs("div", { className: "sm-picker sm-richtext__insert", role: "listbox", "aria-label": "Insert", children: [items.length === 0 && _jsx("div", { className: "sm-richtext__insert-empty", children: "Nothing matches" }), items.map((item, i) => (_jsxs("button", { type: "button", role: "option", "aria-selected": i === active, className: i === active ? "sm-picker__item sm-picker__item--active" : "sm-picker__item", onMouseDown: keepFocus, onClick: () => onPick(item), children: [_jsx("span", { className: "sm-picker__icon", children: item.icon }), _jsx("span", { style: { fontWeight: 600 }, children: item.title })] }, `${item.kind}-${item.title}`)))] }));
+}

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

@@ -0,0 +1,7 @@
+import type { RichtextApi } from "./useRichtextEditor.ts";
+export declare function RichtextMenu({ menu }: {
+    menu: RichtextApi["menu"];
+}): import("react").JSX.Element;
+export declare function RichtextLinkRow({ link }: {
+    link: RichtextApi["link"];
+}): import("react").JSX.Element;

package/dist/admin/forms/RichtextPopovers.js

@@ -0,0 +1,25 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// The richtext editor's two popovers, shared by the sidebar widget and
+// the canvas toolbar (spec 2026-09-10 §5): the "+" insert menu with its
+// filter, and the link row. Presentational over the hook's state.
+import { Button } from "../ui/primitives.js";
+import { RichtextInsertMenu } from "./RichtextInsertMenu.js";
+export function RichtextMenu({ menu }) {
+    // Focus leaving the menu (a click anywhere else) closes it, without stealing focus back to the editor.
+    return (_jsxs("div", { className: "sm-richtext__menu", onBlur: menu.dismiss, children: [_jsx("input", { className: "sm-input", placeholder: "Filter\u2026", value: menu.query, autoFocus: true, "aria-label": "Insert filter", onChange: (e) => menu.setQuery(e.target.value), onKeyDown: menu.onKeyDown }), _jsx(RichtextInsertMenu, { items: menu.items, active: menu.active, onPick: menu.pick })] }));
+}
+export function RichtextLinkRow({ link }) {
+    return (_jsxs("div", { className: "sm-richtext__link", children: [_jsx("input", { className: "sm-input", placeholder: "https://\u2026 or /path", value: link.href, autoFocus: true, "aria-label": "Link URL", onChange: (e) => link.setHref(e.target.value), onKeyDown: (e) => {
+                    // Escape must not reach the editor's window handler, which clears the block selection.
+                    if (e.key === "Enter") {
+                        e.preventDefault();
+                        link.apply();
+                    }
+                    if (e.key === "Escape") {
+                        e.preventDefault();
+                        e.stopPropagation();
+                        link.close();
+                    }
+                } }), _jsx(Button, { onClick: link.apply, children: "Apply" }), _jsx(Button, { variant: "secondary", onClick: link.remove, children: "Remove" })] }));
+}

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

@@ -1,5 +1,5 @@
 import type { Allowed } from "../../toolset.ts";
-export type ToolbarCommand = "bold" | "italic" | "link" | "bulletList" | "orderedList" | "blockquote" | {
+export type ToolbarCommand = "bold" | "italic" | "link" | "bulletList" | "orderedList" | "blockquote" | "insert" | {
     heading: number;
 };
 export type ActiveState = {
@@ -13,8 +13,10 @@ export type ActiveState = {
     heading: number | null;
 };
 export declare const INACTIVE: ActiveState;
-export declare function RichtextToolbar({ allowed, active, onCommand }: {
+export declare function RichtextToolbar({ allowed, active, canInsert, onCommand }: {
     allowed: Allowed;
     active: ActiveState;
+    /** Whether the toolset allows an image or an element — the "+" button. */
+    canInsert: boolean;
     onCommand(command: ToolbarCommand): void;
 }): import("react").JSX.Element | null;

package/dist/admin/forms/RichtextToolbar.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Bold, Heading1, Heading2, Heading3, Heading4, Heading5, Heading6, Italic, Link, List, ListOrdered, Quote } from "lucide-react";
+import { Bold, Heading1, Heading2, Heading3, Heading4, Heading5, Heading6, Italic, Link, List, ListOrdered, Plus, Quote } from "lucide-react";
 import { IconButton } from "../ui/primitives.js";
 export const INACTIVE = {
     bold: false, italic: false, link: false, bulletList: false, orderedList: false, blockquote: false, heading: null,
@@ -9,7 +9,7 @@ const HEADING_ICONS = { 1: Heading1, 2: Heading2, 3: Heading3, 4: Heading4, 5: H
 const ICON = 14;
 /** Keep the editor's selection: a toolbar press must not blur the content. */
 const keepFocus = (e) => e.preventDefault();
-export function RichtextToolbar({ allowed, active, onCommand }) {
+export function RichtextToolbar({ allowed, active, canInsert, onCommand }) {
     const button = (label, pressed, command, Icon) => (_jsx(IconButton, { label: label, "aria-pressed": pressed, onMouseDown: keepFocus, onClick: () => onCommand(command), children: _jsx(Icon, { size: ICON, "aria-hidden": "true" }) }, label));
     const groups = [];
     const marks = [
@@ -31,6 +31,8 @@ export function RichtextToolbar({ allowed, active, onCommand }) {
     ].filter(Boolean);
     if (blocks.length > 0)
         groups.push(blocks);
+    if (canInsert)
+        groups.push([button("Insert", false, "insert", Plus)]);
     if (groups.length === 0)
         return null;
     return (_jsx("div", { className: "sm-richtext__bar", role: "toolbar", "aria-label": "Formatting", children: groups.map((group, i) => (_jsxs("span", { style: { display: "contents" }, children: [i > 0 && _jsx("span", { className: "sm-richtext__sep", "aria-hidden": "true" }), group] }, i))) }));

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

@@ -1,5 +1,8 @@
-export declare function RichtextWidget({ value, toolset, onChange }: {
+export declare function RichtextWidget({ value, toolset, onChange, errors, path }: {
     value: unknown;
     toolset: unknown;
     onChange(doc: unknown): void;
+    /** The enclosing form's errors and this field's dotted path, for the cards. */
+    errors?: Record<string, string>;
+    path?: string;
 }): import("react").JSX.Element;

package/dist/admin/forms/RichtextWidget.js

@@ -1,123 +1,26 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-// The richtext field widget (spec 2026-09-08 §3): a TipTap editor under a
-// fixed toolbar. The editor owns its document and emits TipTap JSON on
-// every change; the parent stores the emitted document by reference, so
-// a value that is not the last emitted document is a change from outside
-// (load, locale switch, a list row moving) and re-seeds the editor. The
-// schema is always full; `allowed` gates creation (extensions, paste,
-// toolbar). Only this file and richtext-extensions.ts import TipTap.
-import { useEffect, useMemo, useRef, useState } from "react";
-import { EditorContent, useEditor, useEditorState } from "@tiptap/react";
-import { Slice } from "@tiptap/pm/model";
-import { allowedOf } from "../../toolset.js";
-import { plainDoc } from "../richtext-doc.js";
-import { Button } from "../ui/primitives.js";
-import { richtextExtensions } from "./richtext-extensions.js";
-import { gatePastedSlice } from "./richtext-paste.js";
-import { INACTIVE, RichtextToolbar } from "./RichtextToolbar.js";
-const EMPTY = { type: "doc", content: [{ type: "paragraph" }] };
-const LEVELS = [1, 2, 3, 4, 5, 6];
-const isDoc = (v) => !!v && typeof v === "object" && v.type === "doc";
-export function RichtextWidget({ value, toolset, onChange }) {
-    const allowed = useMemo(() => allowedOf(toolset), [toolset]);
-    // The parent's onChange closes over its render; the editor's onUpdate is
-    // created once, so read the latest through a ref.
-    const onChangeRef = useRef(onChange);
-    onChangeRef.current = onChange;
-    // The last document this widget emitted — anything else arriving as
-    // `value` came from outside and re-seeds the editor.
-    const emitted = useRef(value);
-    const [link, setLink] = useState({ open: false, href: "" });
-    const openLinkRef = useRef(() => { });
-    const editor = useEditor({
-        immediatelyRender: false,
-        extensions: richtextExtensions(allowed, { onLink: () => openLinkRef.current() }),
-        content: isDoc(value) ? value : EMPTY,
-        editorProps: {
-            attributes: { class: "sm-richtext__content" },
-            transformPasted: (slice, view) => Slice.fromJSON(view.state.schema, gatePastedSlice(slice.toJSON(), allowed)),
-        },
-        onUpdate: ({ editor }) => {
-            const doc = plainDoc(editor.getJSON());
-            emitted.current = doc;
-            onChangeRef.current(doc);
-        },
-    }, [allowed]);
-    useEffect(() => {
-        if (!editor || value === emitted.current)
-            return;
-        emitted.current = value;
-        editor.commands.setContent(isDoc(value) ? value : EMPTY, { emitUpdate: false });
-    }, [editor, value]);
-    const active = useEditorState({
-        editor,
-        selector: ({ editor }) => editor
-            ? {
-                bold: editor.isActive("bold"),
-                italic: editor.isActive("italic"),
-                link: editor.isActive("link"),
-                bulletList: editor.isActive("bulletList"),
-                orderedList: editor.isActive("orderedList"),
-                blockquote: editor.isActive("blockquote"),
-                heading: LEVELS.find((level) => editor.isActive("heading", { level })) ?? null,
-            }
-            : INACTIVE,
-    });
-    // Read the caret's link from the editor at open time, not from the last
-    // render: a selection change and the press can land in the same tick.
-    const openLink = () => setLink({ open: true, href: editor?.getAttributes("link").href ?? "" });
-    openLinkRef.current = openLink;
-    const closeLink = () => {
-        setLink({ open: false, href: "" });
-        editor?.commands.focus();
-    };
-    const applyLink = () => {
-        if (!editor)
-            return;
-        const href = link.href.trim();
-        const chain = editor.chain().focus().extendMarkRange("link");
-        if (href === "")
-            chain.unsetLink().run();
-        else
-            chain.setLink({ href }).run();
-        setLink({ open: false, href: "" });
-    };
-    const removeLink = () => {
-        editor?.chain().focus().extendMarkRange("link").unsetLink().run();
-        setLink({ open: false, href: "" });
-    };
-    const run = (command) => {
-        if (!editor)
-            return;
-        if (command === "link") {
-            openLink();
-            return;
-        }
-        const chain = editor.chain().focus();
-        if (typeof command === "object")
-            chain.toggleHeading({ level: command.heading }).run();
-        else if (command === "bold")
-            chain.toggleBold().run();
-        else if (command === "italic")
-            chain.toggleItalic().run();
-        else if (command === "bulletList")
-            chain.toggleBulletList().run();
-        else if (command === "orderedList")
-            chain.toggleOrderedList().run();
-        else if (command === "blockquote")
-            chain.toggleBlockquote().run();
-    };
-    return (_jsxs("div", { className: "sm-richtext", children: [_jsx(RichtextToolbar, { allowed: allowed, active: active ?? INACTIVE, onCommand: run }), link.open && (_jsxs("div", { className: "sm-richtext__link", children: [_jsx("input", { className: "sm-input", placeholder: "https://\u2026 or /path", value: link.href, autoFocus: true, "aria-label": "Link URL", onChange: (e) => setLink({ open: true, href: e.target.value }), onKeyDown: (e) => {
-                            // Escape must not reach the editor's window handler, which clears the block selection.
-                            if (e.key === "Enter") {
-                                e.preventDefault();
-                                applyLink();
-                            }
-                            if (e.key === "Escape") {
-                                e.preventDefault();
-                                e.stopPropagation();
-                                closeLink();
-                            }
-                        } }), _jsx(Button, { onClick: applyLink, children: "Apply" }), _jsx(Button, { variant: "secondary", onClick: removeLink, children: "Remove" })] })), _jsx(EditorContent, { editor: editor })] }));
+// The richtext field widget (spec 2026-09-08 §3): the shared editor
+// (useRichtextEditor) under a fixed toolbar, the "+" menu floating under
+// the toolbar (never pushing the content), the slash menu under the
+// caret, the picker as a modal. Inside the canvas (spec 2026-09-10 §5) a
+// nested widget in an element card inherits the form context's `canvas`
+// flag, so its own cards stay admin-styled.
+import { useMemo } from "react";
+import { EditorContent } from "@tiptap/react";
+import { RichtextToolbar } from "./RichtextToolbar.js";
+import { RichtextInsertMenu } from "./RichtextInsertMenu.js";
+import { RichtextLinkRow, RichtextMenu } from "./RichtextPopovers.js";
+import { RichtextFormProvider, useRichtextForm } from "./richtext-form-context.js";
+import { MediaPicker } from "./MediaPicker.js";
+import { useRichtextEditor } from "./useRichtextEditor.js";
+export function RichtextWidget({ value, toolset, onChange, errors, path = "" }) {
+    const rt = useRichtextEditor({ value, toolset, onChange, contentClass: "sm-richtext__content" });
+    const parent = useRichtextForm();
+    const formInfo = useMemo(() => ({ errors, path, canvas: parent.canvas }), [errors, path, parent.canvas]);
+    return (_jsx(RichtextFormProvider, { value: formInfo, children: _jsxs("div", { className: "sm-richtext", children: [_jsxs("div", { className: "sm-richtext__head", children: [_jsx(RichtextToolbar, { allowed: rt.allowed, active: rt.active, canInsert: rt.canInsert, onCommand: rt.run }), rt.menu.open && _jsx(RichtextMenu, { menu: rt.menu })] }), rt.link.open && _jsx(RichtextLinkRow, { link: rt.link }), _jsxs("div", { className: "sm-richtext__body", children: [_jsx(EditorContent, { editor: rt.editor }), rt.slash && (_jsx("div", { className: "sm-richtext__slash", style: { top: rt.slash.state.rect ? rt.slash.state.rect.bottom - (editorTop(rt.editor) ?? 0) + 4 : 0 }, children: _jsx(RichtextInsertMenu, { items: rt.slash.state.items, active: rt.slash.active, onPick: (item) => rt.slash?.state.pick(item) }) }))] }), rt.picker.open && _jsx(MediaPicker, { kinds: ["image"], onPick: rt.picker.pick, onClose: rt.picker.close })] }) }));
+}
+/** The editor's top in viewport coordinates, to place the slash menu relative to the body wrapper. */
+function editorTop(editor) {
+    return editor?.view.dom.parentElement?.getBoundingClientRect().top;
 }

package/dist/admin/forms/elements-context.d.ts

@@ -0,0 +1,7 @@
+import { type ReactElement, type ReactNode } from "react";
+import type { AdminElement } from "../serialize.ts";
+export declare function ElementsProvider({ elements, children }: {
+    elements: AdminElement[];
+    children: ReactNode;
+}): ReactElement;
+export declare function useElements(): AdminElement[];

package/dist/admin/forms/elements-context.js

@@ -0,0 +1,13 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+// The serialized element descriptors, for the richtext widget's insert
+// menu and element cards. Defaults to none, so a form rendered without
+// the shell (tests, a bare page) still works.
+import { createContext, useContext } from "react";
+const Ctx = createContext([]);
+export function ElementsProvider({ elements, children }) {
+    return _jsx(Ctx.Provider, { value: elements, children: children });
+}
+export function useElements() {
+    return useContext(Ctx);
+}

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

@@ -0,0 +1,5 @@
+export declare const REVEAL_CLASS = "sm-field--reveal";
+export declare const PATH_ATTR = "data-sm-path";
+/** The path, then each enclosing path, outermost last. */
+export declare function ancestorsOf(path: string): string[];
+export declare function revealField(root: ParentNode, path: string): void;

package/dist/admin/forms/reveal.js

@@ -0,0 +1,47 @@
+// Revealing a field in the inspector from a canvas click (spec 2026-09-10
+// §8): scroll its widget into view, pulse it once, focus its first
+// control; a widget inside a collapsed list row is reached by expanding
+// the row first. The path grammar is FieldWidget's; the DOM hook is the
+// data-sm-path attribute Field and ListRow carry.
+export const REVEAL_CLASS = "sm-field--reveal";
+export const PATH_ATTR = "data-sm-path";
+/** The path, then each enclosing path, outermost last. */
+export function ancestorsOf(path) {
+    const segments = path.split(".").filter((s) => s !== "");
+    const out = [];
+    for (let n = segments.length; n >= 1; n--)
+        out.push(segments.slice(0, n).join("."));
+    return out;
+}
+export function revealField(root, path) {
+    const find = (p) => root.querySelector(`[${PATH_ATTR}="${CSS.escape(p)}"]`);
+    const target = find(path);
+    if (target) {
+        pulse(target);
+        return;
+    }
+    // Inside a collapsed row: expand the nearest rendered ancestor, then look again.
+    for (const p of ancestorsOf(path).slice(1)) {
+        const row = find(p);
+        if (!row)
+            continue;
+        const toggle = row.querySelector('[aria-expanded="false"]');
+        if (toggle) {
+            toggle.click();
+            requestAnimationFrame(() => revealField(root, path));
+        }
+        else
+            pulse(row);
+        return;
+    }
+}
+function pulse(el) {
+    el.scrollIntoView({ block: "center", behavior: "smooth" });
+    el.classList.remove(REVEAL_CLASS);
+    void el.offsetWidth; // restart the animation when the same field is revealed twice
+    el.classList.add(REVEAL_CLASS);
+    el.addEventListener("animationend", () => el.classList.remove(REVEAL_CLASS), { once: true });
+    // The value control first — an image's first control is its picker button, so Enter opens the library.
+    const control = el.querySelector("input,textarea,select,[contenteditable]") ?? el.querySelector("button");
+    control?.focus({ preventScroll: true });
+}

package/dist/admin/forms/richtext-extensions.d.ts

@@ -1,5 +1,13 @@
 import { type AnyExtension } from "@tiptap/core";
 import type { Allowed } from "../../toolset.ts";
+import type { AdminElement } from "../serialize.ts";
+import { type SlashOptions } from "./richtext-nodes.ts";
+/** The slash menu's wiring: the registry's elements (the toolset picks
+ *  from them) and the widget's state and key handlers. */
+export type SlashHooks = Omit<SlashOptions, "items"> & {
+    elements: AdminElement[];
+};
 export declare function richtextExtensions(allowed: Allowed, hooks: {
     onLink(): void;
+    slash?: SlashHooks;
 }): AnyExtension[];

package/dist/admin/forms/richtext-extensions.js

@@ -13,6 +13,8 @@ import Italic from "@tiptap/extension-italic";
 import Link from "@tiptap/extension-link";
 import Blockquote from "@tiptap/extension-blockquote";
 import { BulletList, OrderedList } from "@tiptap/extension-list";
+import { filterItems, insertItems } from "./richtext-insert.js";
+import { ElementNode, ImageNode, SlashMenu } from "./richtext-nodes.js";
 /** Keep the mark in the schema; add no way to create it when `on` is false. */
 function gateMarkConfig(on) {
     return {
@@ -32,6 +34,8 @@ const ALL_LEVELS = [1, 2, 3, 4, 5, 6];
 export function richtextExtensions(allowed, hooks) {
     const link = allowed.marks.has("link");
     const levels = allowed.headingLevels;
+    const items = hooks.slash ? insertItems(allowed, hooks.slash.elements) : [];
+    const slash = hooks.slash;
     return [
         StarterKit.configure({
             heading: false, bold: false, italic: false, link: false, blockquote: false,
@@ -70,5 +74,12 @@ export function richtextExtensions(allowed, hooks) {
                 return link ? { "Mod-k": () => { hooks.onLink(); return true; } } : {};
             },
         }),
+        // Block nodes (spec 2026-09-08 block nodes §2): always in the schema; the
+        // toolset gates the insert menu, the slash menu and paste.
+        ImageNode,
+        ElementNode,
+        ...(slash && items.length > 0
+            ? [SlashMenu.configure({ items: (q) => filterItems(items, q), onState: slash.onState, onKeyDown: slash.onKeyDown, onPick: slash.onPick })]
+            : []),
     ];
 }

package/dist/admin/forms/richtext-form-context.d.ts

@@ -0,0 +1,16 @@
+import { type ReactElement, type ReactNode } from "react";
+export type RichtextFormInfo = {
+    errors?: Record<string, string>;
+    path: string;
+    /** Mounted in the canvas: cards carry the admin's classes and the light theme (spec 2026-09-10 §5). */
+    canvas?: boolean;
+};
+export declare function RichtextFormProvider({ value, children }: {
+    value: RichtextFormInfo;
+    children: ReactNode;
+}): ReactElement;
+export declare function useRichtextForm(): RichtextFormInfo;
+/** A card's classes: inside the canvas it scopes the admin tokens to itself
+ *  (`sm-admin`, light — the page stays light) and opts out of Tailwind
+ *  typography (`not-prose`), which would otherwise style its internals. */
+export declare function cardClass(selected: boolean, canvas: boolean | undefined): string;

package/dist/admin/forms/richtext-form-context.js

@@ -0,0 +1,18 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+// What a card inside a richtext editor needs from the enclosing form: the
+// error map and its own dotted path, so an element card can show
+// `body.elements.2.heading` under the right input — and whether the
+// editor is mounted in the canvas, where a card is admin UI on the page.
+import { createContext, useContext } from "react";
+const Ctx = createContext({ path: "" });
+export function RichtextFormProvider({ value, children }) {
+    return _jsx(Ctx.Provider, { value: value, children: children });
+}
+export function useRichtextForm() { return useContext(Ctx); }
+/** A card's classes: inside the canvas it scopes the admin tokens to itself
+ *  (`sm-admin`, light — the page stays light) and opts out of Tailwind
+ *  typography (`not-prose`), which would otherwise style its internals. */
+export function cardClass(selected, canvas) {
+    return ["sm-rtcard", selected && "sm-rtcard--selected", canvas && "sm-admin not-prose"].filter(Boolean).join(" ");
+}

package/dist/admin/forms/richtext-insert.d.ts

@@ -0,0 +1,38 @@
+import type { Node as PmNode } from "@tiptap/pm/model";
+import type { Allowed } from "../../toolset.ts";
+import type { AdminElement } from "../serialize.ts";
+export type InsertItem = {
+    kind: "image";
+    title: "Image";
+    icon: string;
+} | {
+    kind: "element";
+    title: string;
+    icon: string;
+    element: AdminElement;
+};
+export declare function insertItems(allowed: Allowed, elements: AdminElement[]): InsertItem[];
+export declare function filterItems(items: InsertItem[], query: string): InsertItem[];
+export type ElementNodeJSON = {
+    type: "element";
+    attrs: {
+        name: string;
+        fields: Record<string, unknown>;
+        styles: Record<string, unknown>;
+    };
+};
+export type ImageNodeJSON = {
+    type: "image";
+    attrs: {
+        image: {
+            asset: string;
+            alt?: string;
+        };
+        caption: string;
+    };
+};
+/** A fresh element: sample first, then the empties, styles from their defaults — as a section insertion does. */
+export declare function elementNode(element: AdminElement): ElementNodeJSON;
+export declare function imageNode(assetId: string): ImageNodeJSON;
+/** How many element nodes precede `pos` — the validator's `elements.<i>` index. */
+export declare function elementIndexAt(doc: PmNode, pos: number): number;

package/dist/admin/forms/richtext-insert.js

@@ -0,0 +1,37 @@
+import { nodeFromSample } from "../tree-ops.js";
+export function insertItems(allowed, elements) {
+    const byName = new Map(elements.map((e) => [e.name, e]));
+    const out = [];
+    if (allowed.image)
+        out.push({ kind: "image", title: "Image", icon: "▣" });
+    for (const name of allowed.elements) {
+        const element = byName.get(name);
+        if (element)
+            out.push({ kind: "element", title: element.title, icon: element.icon ?? "▤", element });
+    }
+    return out;
+}
+export function filterItems(items, query) {
+    const q = query.trim().toLowerCase();
+    return q === "" ? items : items.filter((i) => i.title.toLowerCase().includes(q));
+}
+/** A fresh element: sample first, then the empties, styles from their defaults — as a section insertion does. */
+export function elementNode(element) {
+    const { fields, styles } = nodeFromSample(element, "");
+    return { type: "element", attrs: { name: element.name, fields, styles: styles ?? {} } };
+}
+export function imageNode(assetId) {
+    return { type: "image", attrs: { image: { asset: assetId }, caption: "" } };
+}
+/** How many element nodes precede `pos` — the validator's `elements.<i>` index. */
+export function elementIndexAt(doc, pos) {
+    let i = 0;
+    doc.descendants((n, p) => {
+        if (p >= pos)
+            return false;
+        if (n.type.name === "element")
+            i++;
+        return true;
+    });
+    return i;
+}

package/dist/admin/forms/richtext-nodes.d.ts

@@ -0,0 +1,37 @@
+import { Extension, Node, type Editor } from "@tiptap/core";
+import { type ReactNodeViewProps } from "@tiptap/react";
+import type { ComponentType } from "react";
+import type { InsertItem, ElementNodeJSON, ImageNodeJSON } from "./richtext-insert.ts";
+type Views = {
+    image: ComponentType<ReactNodeViewProps> | null;
+    element: ComponentType<ReactNodeViewProps> | null;
+};
+/** Bind the card components once, before the first editor mounts. */
+export declare function setNodeViews(next: Views): void;
+export declare const ImageNode: Node<any, any>;
+export declare const ElementNode: Node<any, any>;
+/** Insert a block at `at` (default: the selection's end — after a selected
+ *  card, never replacing it), followed by an empty paragraph so the caret
+ *  lands somewhere. The position is explicit because a menu or a picker
+ *  has taken focus in between, and a refocused contenteditable may place
+ *  its DOM caret at the first block before the editor's own selection is
+ *  restored; an empty paragraph at `at` is replaced, as TipTap does. */
+export declare function insertBlock(editor: Editor, node: ElementNodeJSON | ImageNodeJSON, at?: number): void;
+export type SlashState = {
+    items: InsertItem[];
+    rect: DOMRect | null;
+    pick(item: InsertItem): void;
+};
+export type SlashOptions = {
+    items(query: string): InsertItem[];
+    onState(state: SlashState | null): void;
+    /** Arrow, Enter and Escape while the menu is open; true when handled. */
+    onKeyDown(event: KeyboardEvent): boolean;
+    /** The pick: this editor's widget inserts (an image needs the picker first).
+     *  Per editor, never a shared slot — a nested richtext editor inside an
+     *  element card has its own widget and must not receive the outer pick. */
+    onPick(item: InsertItem): void;
+};
+/** `/` at the start of an empty paragraph opens the insert menu (spec §3). */
+export declare const SlashMenu: Extension<SlashOptions, any>;
+export {};