smoodly 0.0.12 → 0.0.14

package/dist/admin/forms/useRichtextEditor.js

@@ -0,0 +1,281 @@
+"use client";
+// The richtext editor behind both mounts (widget spec 2026-09-08 §3;
+// inline editing spec 2026-09-10 §5): the TipTap instance over the full
+// schema with the toolset gating creation, the toolbar's active state,
+// the link popover, the "+" menu, the slash menu and the image picker.
+// The sidebar widget and the canvas editor render this state in their own
+// layouts. 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 and
+// re-seeds the editor. Block nodes render as cards, bound once through
+// setNodeViews.
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useEditor, useEditorState } from "@tiptap/react";
+import { Slice } from "@tiptap/pm/model";
+import { allowedOf } from "../../toolset.js";
+import { plainDoc } from "../richtext-doc.js";
+import { richtextExtensions } from "./richtext-extensions.js";
+import { gatePastedSlice } from "./richtext-paste.js";
+import { INACTIVE } from "./RichtextToolbar.js";
+import { elementNode, filterItems, imageNode, insertItems } from "./richtext-insert.js";
+import { insertBlock, setNodeViews } from "./richtext-nodes.js";
+import { RichtextImageCard } from "./RichtextImageCard.js";
+import { RichtextElementCard } from "./RichtextElementCard.js";
+import { useElements } from "./elements-context.js";
+import { useAssets } from "./assets-context.js";
+setNodeViews({ image: RichtextImageCard, element: RichtextElementCard });
+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 useRichtextEditor({ value, toolset, onChange, contentClass, onEscape }) {
+    const allowed = useMemo(() => allowedOf(toolset), [toolset]);
+    const elements = useElements();
+    const assets = useAssets();
+    const items = useMemo(() => insertItems(allowed, elements), [allowed, elements]);
+    // The parent's callbacks close over its render; the editor's handlers are
+    // created once, so read the latest through refs.
+    const onChangeRef = useRef(onChange);
+    onChangeRef.current = onChange;
+    const onEscapeRef = useRef(onEscape);
+    onEscapeRef.current = onEscape;
+    // The last document this editor 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(() => { });
+    // The "+" popover, the slash menu and the image picker.
+    const [menu, setMenu] = useState({ open: false, query: "", active: 0 });
+    const [slash, setSlash] = useState(null);
+    const [slashActive, setSlashActive] = useState(0);
+    const slashRef = useRef({ state: null, active: 0, dismissed: false });
+    const [picker, setPicker] = useState(false);
+    // The slash extension is created once; it reaches this render's insert through the ref.
+    const insertRef = useRef(() => { });
+    // Where the next insert goes: recorded when the "+" menu opens (the menu
+    // and the picker take focus), read back at pick time. Null = the caret.
+    const anchorRef = useRef(null);
+    const editor = useEditor({
+        immediatelyRender: false,
+        extensions: richtextExtensions(allowed, {
+            onLink: () => openLinkRef.current(),
+            slash: {
+                elements,
+                onState: (state) => {
+                    const r = slashRef.current;
+                    if (state === null) {
+                        r.dismissed = false;
+                        r.state = null;
+                        setSlash(null);
+                        return;
+                    }
+                    if (r.state === null) {
+                        r.dismissed = false;
+                        r.active = 0;
+                    }
+                    r.state = state;
+                    r.active = Math.min(r.active, Math.max(0, state.items.length - 1));
+                    setSlashActive(r.active);
+                    setSlash(r.dismissed ? null : state);
+                },
+                onKeyDown: (event) => {
+                    const r = slashRef.current;
+                    if (!r.state || r.dismissed)
+                        return false;
+                    const n = Math.max(1, r.state.items.length);
+                    if (event.key === "Escape") {
+                        r.dismissed = true;
+                        setSlash(null);
+                        return true;
+                    }
+                    if (event.key === "ArrowDown") {
+                        r.active = (r.active + 1) % n;
+                        setSlashActive(r.active);
+                        return true;
+                    }
+                    if (event.key === "ArrowUp") {
+                        r.active = (r.active - 1 + n) % n;
+                        setSlashActive(r.active);
+                        return true;
+                    }
+                    if (event.key === "Enter") {
+                        const item = r.state.items[r.active];
+                        if (item)
+                            r.state.pick(item);
+                        return true;
+                    }
+                    return false;
+                },
+                onPick: (item) => insertRef.current(item),
+            },
+        }),
+        content: isDoc(value) ? value : EMPTY,
+        editorProps: {
+            attributes: { class: contentClass },
+            transformPasted: (slice, view) => Slice.fromJSON(view.state.schema, gatePastedSlice(slice.toJSON(), allowed)),
+            // Direct editor props run before plugin props, so leave Escape to
+            // the slash plugin while its menu is up; otherwise the canvas editor
+            // ends its session on it.
+            handleKeyDown: (_view, event) => {
+                if (event.key !== "Escape" || !onEscapeRef.current)
+                    return false;
+                const r = slashRef.current;
+                if (r.state && !r.dismissed)
+                    return false;
+                onEscapeRef.current();
+                return true;
+            },
+        },
+        onUpdate: ({ editor }) => {
+            const doc = plainDoc(editor.getJSON());
+            emitted.current = doc;
+            onChangeRef.current(doc);
+        },
+    }, [allowed, elements]);
+    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,
+    });
+    /** One insert path for the "+" menu and the slash menu. An image needs the picker first. */
+    const insert = (item) => {
+        setMenu({ open: false, query: "", active: 0 });
+        if (!editor)
+            return;
+        // The "+" menu recorded its anchor; the slash command runs at the caret (its "/" just deleted).
+        const at = anchorRef.current ?? editor.state.selection.to;
+        if (item.kind === "image") {
+            anchorRef.current = at;
+            setPicker(true);
+            return;
+        }
+        anchorRef.current = null;
+        insertBlock(editor, elementNode(item.element), at);
+    };
+    insertRef.current = insert;
+    const pickImage = (record) => {
+        assets.remember(record);
+        setPicker(false);
+        const at = anchorRef.current ?? undefined;
+        anchorRef.current = null;
+        if (editor)
+            insertBlock(editor, imageNode(record.id), at);
+    };
+    const closePicker = () => {
+        setPicker(false);
+        const at = anchorRef.current ?? undefined;
+        anchorRef.current = null;
+        editor?.commands.focus(at);
+    };
+    // 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;
+        }
+        if (command === "insert") {
+            anchorRef.current = menu.open ? null : editor.state.selection.to;
+            setMenu((m) => ({ open: !m.open, query: "", active: 0 }));
+            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();
+    };
+    const menuItems = filterItems(items, menu.query);
+    const closeMenu = () => {
+        setMenu({ open: false, query: "", active: 0 });
+        const at = anchorRef.current ?? undefined;
+        anchorRef.current = null;
+        editor?.commands.focus(at);
+    };
+    // The menu floats over the content, so focus leaving it (a click
+    // anywhere else) closes it — without stealing focus back to the editor.
+    const dismissMenu = (e) => {
+        if (e.currentTarget.contains(e.relatedTarget))
+            return;
+        setMenu({ open: false, query: "", active: 0 });
+        anchorRef.current = null;
+    };
+    const onMenuKeyDown = (e) => {
+        const n = Math.max(1, menuItems.length);
+        if (e.key === "Escape") {
+            e.preventDefault();
+            e.stopPropagation();
+            closeMenu();
+        }
+        if (e.key === "ArrowDown") {
+            e.preventDefault();
+            setMenu((m) => ({ ...m, active: (m.active + 1) % n }));
+        }
+        if (e.key === "ArrowUp") {
+            e.preventDefault();
+            setMenu((m) => ({ ...m, active: (m.active - 1 + n) % n }));
+        }
+        if (e.key === "Enter") {
+            e.preventDefault();
+            const item = menuItems[menu.active];
+            if (item)
+                insert(item);
+        }
+    };
+    return {
+        editor, allowed, active: active ?? INACTIVE, canInsert: items.length > 0, run,
+        link: { open: link.open, href: link.href, setHref: (href) => setLink({ open: true, href }), apply: applyLink, remove: removeLink, close: closeLink },
+        menu: {
+            open: menu.open, query: menu.query, active: menu.active, items: menuItems,
+            setQuery: (query) => setMenu({ open: true, query, active: 0 }), onKeyDown: onMenuKeyDown,
+            pick: insert, close: closeMenu, dismiss: dismissMenu,
+        },
+        slash: slash ? { state: slash, active: slashActive } : null,
+        picker: { open: picker, pick: pickImage, close: closePicker },
+    };
+}

package/dist/admin/next/bridge.js

@@ -1,41 +1,72 @@
 "use client";
 // Runs INSIDE the draft-route iframe (glue adds it only when draft mode +
-// the editor param are on). Reports geometry, forwards select/hover,
-// executes refresh/scroll — the admin overlay draws all chrome. Rects are
-// in document coordinates: the iframe is sized to the full document height
-// by the editor, so client rects + scroll offsets map 1:1 onto the overlay.
+// the editor param are on). Reports geometry — section nodes, empty zones
+// and, since spec 2026-09-10, every marked field with its resolved path —
+// forwards select/hover with the field under the pointer, executes
+// refresh/scroll, and says when a render has committed. The admin overlay
+// draws all chrome. Rects are in document coordinates: the iframe is sized
+// to the full document height by the editor, so client rects + scroll
+// offsets map 1:1 onto the overlay.
 import { useEffect } from "react";
 import { useRouter } from "next/navigation";
+import { EDITOR_ATTR, FIELD_ATTR, NODE_ATTR, ZONE_ATTR, resolveMarkPath } from "../../marks.js";
+const post = (m) => window.parent.postMessage(m, "*");
 export function EditorBridge() {
     const router = useRouter();
+    // Every commit of this component — the mount, then each RSC refresh,
+    // which re-renders the route — tells the editor the new markup is in
+    // the DOM (spec 2026-09-10 §5: the inline richtext editor lets go of
+    // its container only then).
+    useEffect(() => { post({ source: "smoodly", kind: "rendered" }); });
     useEffect(() => {
-        const post = (m) => window.parent.postMessage(m, "*");
+        const docRect = (el) => {
+            const r = el.getBoundingClientRect();
+            return { x: r.left + window.scrollX, y: r.top + window.scrollY, w: r.width, h: r.height };
+        };
+        const all = (selector) => Array.from(document.querySelectorAll(selector));
+        const inEditor = (el) => Boolean(el?.closest?.(`[${EDITOR_ATTR}]`));
         const report = () => {
             // Array.from, not spread: the package's lib set is ES2020 + DOM
             // (no DOM.Iterable), so a NodeList isn't statically iterable here.
-            const nodes = Array.from(document.querySelectorAll("[data-smoodly-node]")).map((el) => {
-                const r = el.getBoundingClientRect();
-                return { id: el.dataset.smoodlyNode, x: r.left + window.scrollX, y: r.top + window.scrollY, w: r.width, h: r.height };
-            });
-            const emptyZones = Array.from(document.querySelectorAll("[data-smoodly-zone]")).map((el) => {
-                const r = el.getBoundingClientRect();
-                return { zone: el.dataset.smoodlyZone, x: r.left + window.scrollX, y: r.top + window.scrollY, w: r.width, h: r.height };
-            });
-            post({ source: "smoodly", kind: "rects", nodes, emptyZones, docH: document.documentElement.scrollHeight });
+            const nodes = all(`[${NODE_ATTR}]`).map((el) => ({ id: el.getAttribute(NODE_ATTR), ...docRect(el) }));
+            const emptyZones = all(`[${ZONE_ATTR}]`).map((el) => ({ zone: el.getAttribute(ZONE_ATTR), ...docRect(el) }));
+            const fields = [];
+            for (const el of all(`[${FIELD_ATTR}]`)) {
+                // A mark inside the admin's own editor root (a nested element card) is not the page's.
+                if (inEditor(el))
+                    continue;
+                const mark = resolveMarkPath(el);
+                if (mark)
+                    fields.push({ ...mark, ...docRect(el) });
+            }
+            post({ source: "smoodly", kind: "rects", nodes, emptyZones, fields, docH: document.documentElement.scrollHeight });
         };
         const raf = () => requestAnimationFrame(report);
         const ro = new ResizeObserver(raf);
         ro.observe(document.documentElement);
+        // characterData too: a text session edits a text node in place, and the outline must follow.
         const mo = new MutationObserver(raf);
-        mo.observe(document.body, { subtree: true, childList: true, attributes: true });
-        const nodeIdAt = (target) => target?.closest?.("[data-smoodly-node]")?.dataset.smoodlyNode ?? null;
+        mo.observe(document.body, { subtree: true, childList: true, attributes: true, characterData: true });
+        const elementOf = (target) => target;
+        const nodeIdAt = (target) => elementOf(target)?.closest?.(`[${NODE_ATTR}]`)?.getAttribute(NODE_ATTR) ?? null;
+        const pathAt = (target) => {
+            const el = elementOf(target)?.closest?.(`[${FIELD_ATTR}]`);
+            return el ? resolveMarkPath(el)?.path ?? null : null;
+        };
         const onClick = (e) => {
             // The canvas must never navigate away from under the editor.
-            if (e.target?.closest?.("a"))
+            if (elementOf(e.target)?.closest?.("a"))
                 e.preventDefault();
-            post({ source: "smoodly", kind: "select", id: nodeIdAt(e.target) });
+            // Inside its own editor root the admin owns every click.
+            if (inEditor(elementOf(e.target)))
+                return;
+            post({ source: "smoodly", kind: "select", id: nodeIdAt(e.target), path: pathAt(e.target), x: e.clientX, y: e.clientY });
+        };
+        const onMove = (e) => {
+            if (inEditor(elementOf(e.target)))
+                return;
+            post({ source: "smoodly", kind: "hover", id: nodeIdAt(e.target), path: pathAt(e.target) });
         };
-        const onMove = (e) => post({ source: "smoodly", kind: "hover", id: nodeIdAt(e.target) });
         const onMessage = (e) => {
             const m = e.data;
             if (m?.source !== "smoodly")
@@ -44,7 +75,7 @@ export function EditorBridge() {
                 router.refresh();
             if (m.kind === "scroll") {
                 document
-                    .querySelector(`[data-smoodly-node="${CSS.escape(m.id)}"]`)
+                    .querySelector(`[${NODE_ATTR}="${CSS.escape(m.id)}"]`)
                     ?.scrollIntoView({ behavior: "smooth", block: "center" });
             }
         };

package/dist/admin/ops-impl.js

@@ -1,10 +1,11 @@
 import { entryFieldsIn, entryTitleIn } from "../entry-store.js";
 import { ASSET_COLLECTION } from "../media.js";
 import { BASE } from "./shell/base.js";
-import { affectedTargets, entryTag, pageTag, sharedTag } from "../revalidate.js";
+import { affectedTargets, collectionTag, entryTag, pageTag, pagesTreeTag, sharedTag } from "../revalidate.js";
 import { ensureFixedNodes, fixedNodeOf } from "./fixed-nodes.js";
 import { ensureSharedItems } from "./shared-items.js";
 import { validateFields } from "./validate.js";
+import { elementSchemas } from "../richtext-walk.js";
 const ok = (data) => ({ ok: true, data });
 const err = (code, message, fields) => ({ ok: false, code, message, ...(fields ? { fields } : {}) });
 /** Own-property, non-array plain object — same shape guard the tree checks
@@ -88,6 +89,8 @@ export function createAdminOps(deps) {
     const { config, pages, entries, effects } = deps;
     const href = deps.href ?? ((path) => path);
     const collectionFields = (name) => config.registry.collections?.find((c) => c.name === name)?.fields ?? null;
+    // Element nodes inside richtext validate against these (spec 2026-09-08 block nodes §2).
+    const elementDescs = elementSchemas((config.registry.elements ?? []).map((e) => ({ name: e.schema.name, fields: e.schema.fields ?? {}, styles: e.schema.styles })));
     const sectionFields = (type) => config.registry.sections?.find((s) => s.schema.name === type)?.schema;
     const sharedItem = (name) => config.registry.shared?.find((s) => s.name === name) ?? null;
     /** One row per registration; null when materialization could not create it. */
@@ -119,6 +122,36 @@ export function createAdminOps(deps) {
                 effects.revalidate(sharedTag(item.name));
         }
     };
+    /** An asset's metadata (alt, title, caption, credit) is read wherever media
+     *  resolves (spec 2026-09-08 §9): the entry and page units that reference the
+     *  asset, directly or through an entry, the shared items among those rows,
+     *  and the list units of every referencing entry's collection. The walk is
+     *  the entry fan-out's, seeded with the asset's id — which is no entry, so
+     *  it gets no tag of its own. */
+    const expireAssetUsers = async (assetId) => {
+        if (!effects?.revalidate)
+            return;
+        const { pageIds, entryIds } = await affectedTargets({ pages, entries }, assetId);
+        const users = entryIds.filter((id) => id !== assetId);
+        for (const id of users)
+            effects.revalidate(entryTag(id));
+        for (const id of pageIds)
+            effects.revalidate(pageTag(id));
+        const touched = new Set(users);
+        for (const item of config.registry.shared ?? []) {
+            const row = (await entries.list(item.name))[0];
+            if (row && touched.has(row.id))
+                effects.revalidate(sharedTag(item.name));
+        }
+        for (const c of config.registry.collections ?? []) {
+            for (const id of users) {
+                if (await entries.get(c.name, id)) {
+                    effects.revalidate(collectionTag(c.name));
+                    break;
+                }
+            }
+        }
+    };
     /** Expire the cached units a tree change touched, in order, once each. */
     const expirePages = (ids) => {
         if (!effects?.revalidate)
@@ -126,6 +159,10 @@ export function createAdminOps(deps) {
         for (const id of new Set(ids.filter((x) => typeof x === "string")))
             effects.revalidate(pageTag(id));
     };
+    /** The tree listing's unit (spec 2026-09-11 §2): every page op that changes what it shows. */
+    const expireTree = () => effects?.revalidate?.(pagesTreeTag());
+    /** A collection's list units: every entry write, since a non-versioned collection's published read is its live row. */
+    const expireCollection = (name) => effects?.revalidate?.(collectionTag(name));
     /** A node and every descendant, node first, in listPages() order. */
     const subtreeIds = async (id) => {
         const all = await pages.listPages();
@@ -241,10 +278,12 @@ export function createAdminOps(deps) {
                     // A root create competes with the code-owned slugs: make sure they exist first.
                     await ensureFixedNodes(pages, config);
                 }
-                return ok(await pages.createPage({
+                const created = await pages.createPage({
                     locale: input.locale, slug: input.slug, template: input.template, parentId: input.parentId,
                     ...(input.title !== undefined ? { title: input.title } : {}),
-                }));
+                });
+                expireTree();
+                return ok(created);
             }),
             saveDraft: (id, locale, tree) => guard(async () => {
                 const unsupported = supportedLocale(locale);
@@ -278,17 +317,23 @@ export function createAdminOps(deps) {
                         const schema = sectionFields(node.type);
                         if (!schema?.fields)
                             continue;
-                        for (const fe of validateFields(node.fields ?? {}, schema.fields)) {
+                        for (const fe of validateFields(node.fields ?? {}, schema.fields, elementDescs)) {
                             fieldErrors.push({ field: `${node.id}.${fe.field}`, message: fe.message });
                         }
                     }
                 }
+                // The page's own fields (spec 2026-09-10 page fields §2); SEO meta is never validated.
+                const pageDescs = openTemplate(record.template)?.schema?.fields ?? {};
+                for (const fe of validateFields(draft.fields ?? {}, pageDescs, elementDescs)) {
+                    fieldErrors.push({ field: `page.fields.${fe.field}`, message: fe.message });
+                }
                 if (fieldErrors.length > 0) {
                     return err("validation", `smoodly: cannot publish "${row.slug}" — fix the listed fields first.`, fieldErrors);
                 }
                 const published = await pages.publish(id, locale);
                 // The parent's cached unit lists its published children.
                 expirePages([published.id, published.parentId]);
+                expireTree();
                 return ok(published);
             }),
             delete: (id) => guard(async () => {
@@ -304,6 +349,7 @@ export function createAdminOps(deps) {
                 // The cached unit is keyed by (locale, path) but tagged by the id
                 // found at the first miss; the parent's unit lists its children.
                 expirePages([id, record.parentId]);
+                expireTree();
                 return ok(null);
             }),
             rename: (id, patch) => guard(async () => {
@@ -322,17 +368,20 @@ export function createAdminOps(deps) {
                 // Every descendant's path changed with this segment; the parent
                 // lists this node's title and path.
                 expirePages([...(await subtreeIds(id)), record.parentId]);
+                expireTree();
                 return ok(renamed);
             }),
             move: (id, to) => guard(async () => {
                 const record = await pages.getPage(id);
                 if (!record)
                     return err("not_found", `smoodly: no page "${id}".`);
-                if (fixedNodeOf(record, config))
-                    return owned(record, "it stays at the root");
-                if (isHomeNode(record))
-                    return err("blocked", `smoodly: "${nameOf(record)}" is the site root — it stays at the root.`);
                 if (to.parentId !== null) {
+                    // Code owns a fixed node's URL, never the root's listing order:
+                    // reparenting is refused, reordering among the root siblings is not.
+                    if (fixedNodeOf(record, config))
+                        return owned(record, "it stays at the root");
+                    if (isHomeNode(record))
+                        return err("blocked", `smoodly: "${nameOf(record)}" is the site root — it stays at the root.`);
                     const parent = await pages.getPage(to.parentId);
                     if (!parent)
                         return err("not_found", `smoodly: no page "${to.parentId}".`);
@@ -342,6 +391,7 @@ export function createAdminOps(deps) {
                 }
                 const moved = await pages.move(id, to);
                 expirePages([...(await subtreeIds(id)), record.parentId, moved.parentId]);
+                expireTree();
                 return ok(moved);
             }),
             setTemplate: (id, template) => guard(async () => {
@@ -358,7 +408,9 @@ export function createAdminOps(deps) {
                 if (registration.schema.slug !== undefined) {
                     return err("validation", `smoodly: page template "${template}" is fixed — Smoodly creates that page for you.`);
                 }
-                return ok(await pages.setTemplate(id, template));
+                const withTemplate = await pages.setTemplate(id, template);
+                expireTree();
+                return ok(withTemplate);
             }),
             addLocale: (id, locale, options) => guard(async () => {
                 const unsupported = supportedLocale(locale) ?? supportedLocale(options?.from);
@@ -366,8 +418,10 @@ export function createAdminOps(deps) {
                     return unsupported;
                 if (!(await pages.getPage(id)))
                     return err("not_found", `smoodly: no page "${id}".`);
-                // A new locale is a draft: nothing public changes, nothing to expire.
-                return ok(await pages.addLocale(id, locale, { from: options.from }));
+                // A new locale is a draft: nothing public changes but the tree listing (spec 2026-09-11 §2).
+                const added = await pages.addLocale(id, locale, { from: options.from });
+                expireTree();
+                return ok(added);
             }),
             removeLocale: (id, locale) => guard(async () => {
                 const unsupported = supportedLocale(locale);
@@ -383,6 +437,7 @@ export function createAdminOps(deps) {
                 const removed = await pages.removeLocale(id, locale);
                 // The locale may have been published: its unit and the parent's listing go.
                 expirePages([id, record.parentId]);
+                expireTree();
                 return ok(removed);
             }),
         },
@@ -409,10 +464,12 @@ export function createAdminOps(deps) {
                 const descriptors = collectionFields(collection);
                 if (!descriptors)
                     return err("not_found", `smoodly: no collection named "${collection}".`);
-                const fieldErrors = validateFields(input.fields, descriptors);
+                const fieldErrors = validateFields(input.fields, descriptors, elementDescs);
                 if (fieldErrors.length > 0)
                     return err("validation", "Some fields need attention.", fieldErrors);
-                return ok(await entries.create(collection, input.fields, { locale: input.locale, parentId: input.parentId ?? null }));
+                const created = await entries.create(collection, input.fields, { locale: input.locale, parentId: input.parentId ?? null });
+                expireCollection(collection);
+                return ok(created);
             }),
             save: (collection, id, locale, fields) => guard(async () => {
                 const unsupported = supportedLocale(locale);
@@ -421,11 +478,12 @@ export function createAdminOps(deps) {
                 const descriptors = collectionFields(collection);
                 if (!descriptors)
                     return err("not_found", `smoodly: no collection named "${collection}".`);
-                const fieldErrors = validateFields(fields, descriptors);
+                const fieldErrors = validateFields(fields, descriptors, elementDescs);
                 if (fieldErrors.length > 0)
                     return err("validation", "Some fields need attention.", fieldErrors);
                 const entry = await entries.update(collection, id, locale, fields);
                 await fanOut(id);
+                expireCollection(collection);
                 return ok(entry);
             }),
             setStatus: (collection, id, locale, status) => guard(async () => {
@@ -434,24 +492,29 @@ export function createAdminOps(deps) {
                     return unsupported;
                 const entry = await entries.setStatus(collection, id, locale, status);
                 await fanOut(id);
+                expireCollection(collection);
                 return ok(entry);
             }),
             // The tag expires only after the delete succeeded; a blocked delete expires nothing.
-            delete: (collection, id) => guard(async () => (await entries.delete(collection, id), await fanOut(id), ok(null))),
+            delete: (collection, id) => guard(async () => (await entries.delete(collection, id), await fanOut(id), expireCollection(collection), ok(null))),
             move: (collection, id, to) => guard(async () => {
                 const moved = await entries.move(collection, id, to);
                 if (effects?.revalidate) {
                     for (const entryId of await entrySubtreeIds(collection, id))
                         effects.revalidate(entryTag(entryId));
                 }
+                expireCollection(collection);
                 return ok(moved);
             }),
-            // A new locale starts as a draft: nothing public changes, nothing to expire.
+            // A new locale starts as a draft: nothing public changes, but the collection's
+            // list units are expired anyway (spec 2026-09-11 §2) so they can never go stale.
             addLocale: (collection, id, locale, options) => guard(async () => {
                 const unsupported = supportedLocale(locale);
                 if (unsupported)
                     return unsupported;
-                return ok(await entries.addLocale(collection, id, locale, { from: options.from }));
+                const added = await entries.addLocale(collection, id, locale, { from: options.from });
+                expireCollection(collection);
+                return ok(added);
             }),
             removeLocale: (collection, id, locale) => guard(async () => {
                 const unsupported = supportedLocale(locale);
@@ -459,6 +522,7 @@ export function createAdminOps(deps) {
                     return unsupported;
                 const entry = await entries.removeLocale(collection, id, locale);
                 await fanOut(id);
+                expireCollection(collection);
                 return ok(entry);
             }),
         },
@@ -488,7 +552,7 @@ export function createAdminOps(deps) {
                 const item = sharedItem(name);
                 if (!item)
                     return err("not_found", `smoodly: no shared item named "${name}".`);
-                const fieldErrors = validateFields(fields, item.fields);
+                const fieldErrors = validateFields(fields, item.fields, elementDescs);
                 if (fieldErrors.length > 0)
                     return err("validation", "Some fields need attention.", fieldErrors);
                 const record = await sharedRecord(name);
@@ -555,7 +619,9 @@ export function createAdminOps(deps) {
                         return err("validation", `smoodly: ${key} must be text.`);
                     patch[key] = v;
                 }
-                return ok(await assets.update(id, patch));
+                const updated = await assets.update(id, patch);
+                await expireAssetUsers(id);
+                return ok(updated);
             }),
             delete: (id) => guard(async () => (assets ? (await assets.delete(id), ok(null)) : noMedia())),
             usage: (id) => guard(async () => {

package/dist/admin/richtext-doc.d.ts

@@ -1,5 +1,8 @@
 /** True when any text node in the tree has non-whitespace text. */
 export declare function hasText(doc: unknown): boolean;
+/** True when the document has text, or an image or element block (spec
+ *  2026-09-08 block nodes §2): a picture alone is content. */
+export declare function hasContent(doc: unknown): boolean;
 /** The document as plain JSON. ProseMirror builds node attrs with a null
  *  prototype, which React's server-action encoding refuses to serialize
  *  (it becomes a temporary reference and the server's structuredClone