smoodly 0.0.12 → 0.0.13

package/dist/marks.js

@@ -0,0 +1,43 @@
+/** A section's root, from `<smoodly.Section>` in editor mode. */
+export const NODE_ATTR = "data-smd-node";
+/** An empty zone's placeholder box, from `<Zone>` in editor mode. */
+export const ZONE_ATTR = "data-smd-zone";
+export const EMPTY_ATTR = "data-smd-empty";
+/** The element that renders a field's value verbatim. */
+export const FIELD_ATTR = "data-smd-field";
+/** A list item's or object field's root: scopes the field names inside it. */
+export const ITEM_ATTR = "data-smd-item";
+/** The root of an inline editing session inside the canvas; the bridge
+ *  forwards nothing from inside it, and reports no marks under it. */
+export const EDITOR_ATTR = "data-smd-editor";
+/** The section node and dotted field path of a marked element: its own
+ *  field name, prefixed by every item scope from the element itself up to
+ *  the section root. Null when the element carries no field mark or sits
+ *  outside a section node. */
+export function resolveMarkPath(el) {
+    const field = el.getAttribute(FIELD_ATTR);
+    if (!field)
+        return null;
+    const segments = [field];
+    for (let cur = el; cur; cur = cur.parentElement) {
+        const node = cur.getAttribute(NODE_ATTR);
+        if (node)
+            return { node, path: segments.join(".") };
+        const item = cur.getAttribute(ITEM_ATTR);
+        if (item)
+            segments.unshift(item);
+    }
+    return null;
+}
+function level() {
+    return {
+        field: (key) => ({ [FIELD_ATTR]: key }),
+        item: (key, index) => ({ ...level(), attrs: { [ITEM_ATTR]: `${key}.${index}` } }),
+        object: (key) => ({ ...level(), attrs: { [ITEM_ATTR]: key } }),
+    };
+}
+/** Typed marks for a section or element schema: `const m = smoodly.marks(heroSchema)`,
+ *  then `<h1 {...m.field("heading")}>`. The raw attributes stay the contract. */
+export function marks(_schema) {
+    return level();
+}

package/dist/media.d.ts

@@ -1,4 +1,5 @@
 import type { Descriptor } from "./fields.ts";
+import { type ElementSchemas } from "./richtext-walk.ts";
 export type Crop = {
     left: number;
     top: number;
@@ -102,7 +103,7 @@ export declare const isMediaValue: (v: unknown) => v is {
 };
 /** Every asset id a value set references, walking lists and objects —
  *  unlike refs, media may sit inside a container (spec §8). */
-export declare function collectAssetIds(values: Record<string, unknown> | undefined, descriptors: Record<string, Descriptor>, out: Set<string>): void;
+export declare function collectAssetIds(values: Record<string, unknown> | undefined, descriptors: Record<string, Descriptor>, out: Set<string>, elements?: ElementSchemas): void;
 /** Replace every media value in place with its resolved object — or delete
  *  it when the asset is missing or pending, so `image?.url` guards hold. */
-export declare function applyAssets(values: Record<string, unknown> | undefined, descriptors: Record<string, Descriptor>, assets: Map<string, AssetRecord>): void;
+export declare function applyAssets(values: Record<string, unknown> | undefined, descriptors: Record<string, Descriptor>, assets: Map<string, AssetRecord>, elements?: ElementSchemas): void;

package/dist/media.js

@@ -1,3 +1,4 @@
+import { ELEMENT_NODE, IMAGE_NODE, elementOf, elementSets, richtextBlocks } from "./richtext-walk.js";
 /** The refs target collection of every asset edge — a reserved registered name. */
 export const ASSET_COLLECTION = "asset";
 export const MEDIA_TYPES = new Set(["image", "video", "file"]);
@@ -30,7 +31,7 @@ export const cropAspect = (crop, imageAspect) => (crop.width * imageAspect) / cr
 export const isMediaValue = (v) => typeof v === "object" && v !== null && !Array.isArray(v) && typeof v.asset === "string";
 /** Every asset id a value set references, walking lists and objects —
  *  unlike refs, media may sit inside a container (spec §8). */
-export function collectAssetIds(values, descriptors, out) {
+export function collectAssetIds(values, descriptors, out, elements = {}) {
     if (!values)
         return;
     for (const [key, d] of Object.entries(descriptors)) {
@@ -41,8 +42,24 @@ export function collectAssetIds(values, descriptors, out) {
             if (isMediaValue(value))
                 out.add(value.asset);
         }
+        else if (d.type === "richtext") {
+            // Block nodes (spec 2026-09-08 block nodes §2): image nodes, and media inside a known element's fields and styles.
+            for (const node of richtextBlocks(value)) {
+                if (node.type === IMAGE_NODE) {
+                    const image = node.attrs.image;
+                    if (isMediaValue(image))
+                        out.add(image.asset);
+                }
+                else if (node.type === ELEMENT_NODE) {
+                    const schema = elementOf(node, elements);
+                    if (schema)
+                        for (const set of elementSets(node, schema))
+                            collectAssetIds(set.values, set.descriptors, out, elements);
+                }
+            }
+        }
         else if (d.type === "object" && typeof value === "object" && !Array.isArray(value)) {
-            collectAssetIds(value, d.fields, out);
+            collectAssetIds(value, d.fields, out, elements);
         }
         else if (d.type === "list" && Array.isArray(value)) {
             const item = d.item;
@@ -52,7 +69,10 @@ export function collectAssetIds(values, descriptors, out) {
                         out.add(v.asset);
                 }
                 else if (item.type === "object" && v && typeof v === "object") {
-                    collectAssetIds(v, item.fields, out);
+                    collectAssetIds(v, item.fields, out, elements);
+                }
+                else if (item.type === "richtext") {
+                    collectAssetIds({ v }, { v: item }, out, elements);
                 }
             }
         }
@@ -97,7 +117,7 @@ function resolveOne(value, d, assets) {
 }
 /** Replace every media value in place with its resolved object — or delete
  *  it when the asset is missing or pending, so `image?.url` guards hold. */
-export function applyAssets(values, descriptors, assets) {
+export function applyAssets(values, descriptors, assets, elements = {}) {
     if (!values)
         return;
     for (const [key, d] of Object.entries(descriptors)) {
@@ -111,8 +131,25 @@ export function applyAssets(values, descriptors, assets) {
             else
                 values[key] = resolved;
         }
+        else if (d.type === "richtext") {
+            for (const node of richtextBlocks(value)) {
+                if (node.type === IMAGE_NODE) {
+                    const resolved = resolveOne(node.attrs.image, { type: "image" }, assets);
+                    if (resolved === undefined)
+                        delete node.attrs.image;
+                    else
+                        node.attrs.image = resolved;
+                }
+                else if (node.type === ELEMENT_NODE) {
+                    const schema = elementOf(node, elements);
+                    if (schema)
+                        for (const set of elementSets(node, schema))
+                            applyAssets(set.values, set.descriptors, assets, elements);
+                }
+            }
+        }
         else if (d.type === "object" && typeof value === "object" && !Array.isArray(value)) {
-            applyAssets(value, d.fields, assets);
+            applyAssets(value, d.fields, assets, elements);
         }
         else if (d.type === "list" && Array.isArray(value)) {
             const item = d.item;
@@ -122,7 +159,12 @@ export function applyAssets(values, descriptors, assets) {
             else if (item.type === "object") {
                 for (const v of value)
                     if (v && typeof v === "object")
-                        applyAssets(v, item.fields, assets);
+                        applyAssets(v, item.fields, assets, elements);
+            }
+            else if (item.type === "richtext") {
+                // Resolves in place inside the document object `v`; the wrapper is throwaway.
+                for (const v of value)
+                    applyAssets({ v }, { v: item }, assets, elements);
             }
         }
     }

package/dist/refs.d.ts

@@ -6,7 +6,7 @@ export type RefEdge = {
     targetCollection: string;
     targetId: string;
 };
-export declare function collectEntryRefs(fields: Record<string, unknown>, schema: CollectionSchema<any>): RefEdge[];
+export declare function collectEntryRefs(fields: Record<string, unknown>, schema: CollectionSchema<any>, elements?: SectionLike[]): RefEdge[];
 /** A section schema, or anything carrying one (a paired component). */
 export type SectionLike = {
     name: string;
@@ -19,4 +19,4 @@ export type SectionLike = {
         styles?: Record<string, Descriptor>;
     };
 };
-export declare function collectTreeRefs(tree: PageTree, sections: SectionLike[]): RefEdge[];
+export declare function collectTreeRefs(tree: PageTree, sections: SectionLike[], elements?: SectionLike[]): RefEdge[];

package/dist/refs.js

@@ -6,32 +6,52 @@
 // this?) — forward resolution stays resolveTree's job.
 import { sharedLink } from "./shared.js";
 import { ASSET_COLLECTION, isMediaValue, MEDIA_TYPES } from "./media.js";
+import { ELEMENT_NODE, IMAGE_NODE, elementOf, elementSchemas, elementSets, richtextBlocks } from "./richtext-walk.js";
 function targetOf(d) {
     const t = d.target?.();
     if (!t?.name)
         throw new Error("smoodly: ref descriptor has no resolvable target.");
     return t.name;
 }
-/** Media edges walk into containers (spec 2026-09-08 media §8); `field`
- *  stays the top-level key so the edge is addressable like a ref. */
-function collectMedia(field, value, d, out) {
+/** Media edges walk into containers (spec 2026-09-08 media §8) and into
+ *  richtext documents (block nodes §2); `field` stays the top-level key
+ *  so the edge is addressable like a ref. */
+function collectMedia(field, value, d, out, elements) {
     if (value == null)
         return;
     if (MEDIA_TYPES.has(d.type)) {
         if (isMediaValue(value))
             out.push({ field, targetCollection: ASSET_COLLECTION, targetId: value.asset });
     }
+    else if (d.type === "richtext") {
+        for (const node of richtextBlocks(value)) {
+            if (node.type === IMAGE_NODE) {
+                const image = node.attrs.image;
+                if (isMediaValue(image))
+                    out.push({ field, targetCollection: ASSET_COLLECTION, targetId: image.asset });
+            }
+            else if (node.type === ELEMENT_NODE) {
+                const schema = elementOf(node, elements);
+                if (!schema)
+                    continue;
+                for (const set of elementSets(node, schema)) {
+                    for (const [k, sub] of Object.entries(set.descriptors))
+                        collectMedia(field, set.values[k], sub, out, elements);
+                }
+            }
+        }
+    }
     else if (d.type === "object" && typeof value === "object" && !Array.isArray(value)) {
         for (const [k, sub] of Object.entries(d.fields)) {
-            collectMedia(field, value[k], sub, out);
+            collectMedia(field, value[k], sub, out, elements);
         }
     }
     else if (d.type === "list" && Array.isArray(value)) {
         for (const v of value)
-            collectMedia(field, v, d.item, out);
+            collectMedia(field, v, d.item, out, elements);
     }
 }
-function collectFrom(values, descriptors, out) {
+function collectFrom(values, descriptors, out, elements) {
     for (const [field, d] of Object.entries(descriptors)) {
         const value = values[field];
         if (value == null)
@@ -47,16 +67,17 @@ function collectFrom(values, descriptors, out) {
         }
         else {
             // Refs are top-level only (f.list/f.object refuse them); media is not.
-            collectMedia(field, value, d, out);
+            collectMedia(field, value, d, out, elements);
         }
     }
 }
-export function collectEntryRefs(fields, schema) {
+export function collectEntryRefs(fields, schema, elements) {
     const out = [];
-    collectFrom(fields, schema.fields, out);
+    collectFrom(fields, schema.fields, out, elementSchemas(elements));
     return out;
 }
-export function collectTreeRefs(tree, sections) {
+export function collectTreeRefs(tree, sections, elements) {
+    const els = elementSchemas(elements);
     const byName = new Map(sections.map((s) => {
         const schema = "schema" in s ? s.schema : s;
         return [schema.name, schema];
@@ -74,9 +95,9 @@ export function collectTreeRefs(tree, sections) {
             const schema = byName.get(node.type);
             if (!schema)
                 continue; // fail-soft, same as renderPage
-            collectFrom(node.fields, schema.fields, out);
+            collectFrom(node.fields, schema.fields, out, els);
             if (schema.styles && node.styles)
-                collectFrom(node.styles, schema.styles, out);
+                collectFrom(node.styles, schema.styles, out, els);
         }
     }
     return out;

package/dist/render.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { EMPTY_ATTR, ZONE_ATTR } from "./marks.js";
 /** The `page` prop of a view rendered outside the site (a test, a preview
  *  of a shape): a real object, so a view never guards an optional prop, but
  *  no position in the tree. Frozen: one singleton shared by every such
@@ -13,7 +14,7 @@ export function Zone({ of: content }) {
     if (!nodes.length) {
         // In editor mode an empty zone still needs a measurable box for the
         // overlay's "+ add" affordance; in production it renders nothing.
-        return content?.editor ? (_jsx("div", { "data-smoodly-zone": content.name, "data-smoodly-empty": "", style: { minHeight: 48 } })) : null;
+        return content?.editor ? (_jsx("div", { [ZONE_ATTR]: content.name, [EMPTY_ATTR]: "", style: { minHeight: 48 } })) : null;
     }
     return (_jsx(_Fragment, { children: nodes.map((node) => {
             const Component = content.components.get(node.type);

package/dist/resolve.d.ts

@@ -3,6 +3,8 @@ import type { CollectionSchema } from "./collections.ts";
 import type { PageTree } from "./render.tsx";
 import { type SharedSchema } from "./shared.ts";
 import { type AssetRecord } from "./media.ts";
+import { type ElementSchemas } from "./richtext-walk.ts";
+import type { SectionLike } from "./refs.ts";
 export type EntryFetcher = (collection: string, ids: string[]) => Promise<Record<string, Record<string, unknown>>>;
 export type AssetFetcher = (ids: string[]) => Promise<Record<string, AssetRecord>>;
 type SchemaLike = {
@@ -26,20 +28,24 @@ type ResolveOptions = {
     assets?: AssetFetcher;
     /** The registered shared items a placement node may name (spec 2026-09-07 §4). */
     shared?: SharedSchema[];
+    /** Registered Elements a richtext document may embed (spec 2026-09-08 block nodes §2). */
+    elements?: SectionLike[];
     /** Optional safety valve on chain length; unlimited by default. */
     maxDepth?: number;
 };
 export declare function resolveTree(tree: PageTree, options: ResolveOptions): Promise<PageTree>;
 /** One value set's media, resolved in place. Exported for the site layer's shared-item styles. */
-export declare function resolveMedia(values: Record<string, unknown>, descriptors: Record<string, Descriptor>, fetch: AssetFetcher): Promise<void>;
+export declare function resolveMedia(values: Record<string, unknown>, descriptors: Record<string, Descriptor>, fetch: AssetFetcher, elements?: ElementSchemas): Promise<void>;
 /** Many value sets, one asset round (plus one for posters): the tree's
  *  nodes and every entry hydrated through a ref, or a list page's items.
  *  Exported for the site layer's content API. */
-export declare function resolveMediaSets(sets: MediaSet[], fetch: AssetFetcher): Promise<void>;
+export declare function resolveMediaSets(sets: MediaSet[], fetch: AssetFetcher, elements?: ElementSchemas): Promise<void>;
 export type ResolveFieldsOptions = {
     collections: CollectionSchema<any>[];
     fetch: EntryFetcher;
     assets?: AssetFetcher;
+    /** Registered Elements a richtext document may embed (spec 2026-09-08 block nodes §2). */
+    elements?: SectionLike[];
     maxDepth?: number;
 };
 /** One entry's fields, refs hydrated — the entry page's counterpart of

package/dist/resolve.js

@@ -8,6 +8,7 @@
 // construction and the output stays JSON-serializable.
 import { sharedLink, SHARED_NODE_TYPE, STYLES_KEY } from "./shared.js";
 import { applyAssets, collectAssetIds } from "./media.js";
+import { elementSchemas } from "./richtext-walk.js";
 function targetOf(d) {
     const t = d.target?.();
     if (!t?.name)
@@ -49,7 +50,7 @@ export async function resolveTree(tree, options) {
             sets.push({ values: node.fields, descriptors: schema.fields });
             sets.push({ values: node.styles, descriptors: schema.styles ?? {} });
         }
-        await resolveMediaSets([...sets, ...hydrated], options.assets);
+        await resolveMediaSets([...sets, ...hydrated], options.assets, elementSchemas(options.elements));
     }
     return resolved;
 }
@@ -70,19 +71,19 @@ async function fetchAssets(fetch, ids) {
     return out;
 }
 /** One value set's media, resolved in place. Exported for the site layer's shared-item styles. */
-export async function resolveMedia(values, descriptors, fetch) {
-    await resolveMediaSets([{ values, descriptors }], fetch);
+export async function resolveMedia(values, descriptors, fetch, elements = {}) {
+    await resolveMediaSets([{ values, descriptors }], fetch, elements);
 }
 /** Many value sets, one asset round (plus one for posters): the tree's
  *  nodes and every entry hydrated through a ref, or a list page's items.
  *  Exported for the site layer's content API. */
-export async function resolveMediaSets(sets, fetch) {
+export async function resolveMediaSets(sets, fetch, elements = {}) {
     const ids = new Set();
     for (const { values, descriptors } of sets)
-        collectAssetIds(values, descriptors, ids);
+        collectAssetIds(values, descriptors, ids, elements);
     const assets = await fetchAssets(fetch, ids);
     for (const { values, descriptors } of sets)
-        applyAssets(values, descriptors, assets);
+        applyAssets(values, descriptors, assets, elements);
 }
 /** Placements first (spec 2026-09-07 §4): fetch every linked item in one
  *  call per item, rewrite each node into the item's section node — the
@@ -128,7 +129,7 @@ export async function resolveFields(fields, descriptors, options) {
     collectTasks(resolved, descriptors, tasks);
     const hydrated = await runResolution(tasks, { ...options, maxDepth: options.maxDepth ?? Infinity });
     if (options.assets)
-        await resolveMediaSets([{ values: resolved, descriptors }, ...hydrated], options.assets);
+        await resolveMediaSets([{ values: resolved, descriptors }, ...hydrated], options.assets, elementSchemas(options.elements));
     return resolved;
 }
 /** Hydrates every task's refs in place and returns each hydrated entry

package/dist/richtext/index.d.ts

@@ -0,0 +1,12 @@
+import type { ReactElement } from "react";
+import { type RichTextElement } from "../richtext-render.tsx";
+export type CreateRichTextOptions = {
+    /** The registered Elements a body may embed. */
+    elements?: RichTextElement[];
+    /** next/image `sizes` for body images; the site's text column width. */
+    sizes?: string;
+};
+export declare function createRichText({ elements, sizes }?: CreateRichTextOptions): (props: {
+    doc: unknown;
+}) => ReactElement;
+export type { RichTextElement, RichTextImageProps, RichTextProps } from "../richtext-render.tsx";

package/dist/richtext/index.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { RichText } from "../richtext-render.js";
+import { SmoodlyImage } from "../image/SmoodlyImage.js";
+export function createRichText({ elements = [], sizes } = {}) {
+    const image = ({ image, caption }) => (_jsxs("figure", { children: [_jsx(SmoodlyImage, { image: image, sizes: sizes }), caption !== "" && _jsx("figcaption", { children: caption })] }));
+    return function BoundRichText({ doc }) {
+        return _jsx(RichText, { doc: doc, elements: elements, image: image });
+    };
+}

package/dist/richtext-render.d.ts

@@ -1,3 +1,23 @@
-export declare function RichText({ doc }: {
+import { type ReactElement, type ReactNode } from "react";
+import type { ResolvedImage } from "./media.ts";
+export type RichTextImageProps = {
+    image: ResolvedImage;
+    caption: string;
+};
+/** A paired element component: `smoodly.element(schema, View)`. */
+export type RichTextElement = {
+    schema: {
+        name: string;
+    };
+} & ((props: any) => ReactElement);
+export type RichTextProps = {
     doc: unknown;
-}): import("react").JSX.Element | null;
+    /** The registered Elements a document may embed, rendered by name. */
+    elements?: RichTextElement[];
+    /** How an image node renders; the default is a figure over a plain <img>. */
+    image?: (props: RichTextImageProps) => ReactNode;
+};
+/** Lazy by default: body images sit below the fold, and a lazy <img> is
+ *  the one React does not hoist a preload hint for on the server. */
+export declare function defaultRichTextImage({ image, caption }: RichTextImageProps): ReactNode;
+export declare function RichText({ doc, elements, image }: RichTextProps): import("react").JSX.Element | null;

package/dist/richtext-render.js

@@ -1,11 +1,15 @@
-import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
-// The site-side richtext renderer (spec 2026-09-07, list field §5):
-// TipTap JSON → React, a fragment with no wrapper so the developer owns
-// the surrounding element and its class. Pure React, no Node imports, so
-// it works in shared, server and client components alike. Unknown nodes
-// render their children — a document from a later, richer editor degrades
-// instead of crashing. Elements as node views are Phase 3.
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// The site-side richtext renderer (spec 2026-09-07 list field §5; block
+// nodes spec 2026-09-08): TipTap JSON → React, a fragment with no wrapper
+// so the developer owns the surrounding element and its class. Pure
+// React, no Node or Next imports, so it works in shared, server and
+// client components alike. Unknown nodes render their children — a
+// document from a later, richer editor degrades instead of crashing.
+// Block nodes: an `image` node renders through the `image` render prop
+// (default: a figure over a plain <img>); an `element` node renders the
+// paired component named in `elements`, nothing when unknown.
 import { Fragment, createElement } from "react";
+import { ELEMENT_NODE, IMAGE_NODE } from "./richtext-walk.js";
 /** Only schemes an editor's link may carry reach the page: http(s), mailto, tel,
  *  and site-relative targets. Anything else (javascript:, data:, an empty href,
  *  a protocol-relative `//host` or a backslash form `/\host` that a browser
@@ -18,19 +22,27 @@ function safeHref(raw) {
     const href = raw.replace(/[\t\n\r]/g, "").trim();
     return href !== "" && SAFE_HREF.test(href) ? href : null;
 }
-export function RichText({ doc }) {
+/** Lazy by default: body images sit below the fold, and a lazy <img> is
+ *  the one React does not hoist a preload hint for on the server. */
+export function defaultRichTextImage({ image, caption }) {
+    return (_jsxs("figure", { children: [_jsx("img", { src: image.url, width: image.width, height: image.height, alt: image.alt, loading: "lazy" }), caption !== "" && _jsx("figcaption", { children: caption })] }));
+}
+const isResolvedImage = (v) => typeof v === "object" && v !== null && typeof v.url === "string"
+    && typeof v.width === "number" && typeof v.height === "number";
+export function RichText({ doc, elements = [], image = defaultRichTextImage }) {
     const d = doc;
     if (!d || typeof d !== "object" || d.type !== "doc" || !Array.isArray(d.content))
         return null;
-    return _jsx(_Fragment, { children: renderNodes(d.content) });
+    const r = { elements: new Map(elements.map((e) => [e.schema.name, e])), image };
+    return _jsx(_Fragment, { children: renderNodes(d.content, r) });
 }
-function renderNodes(nodes) {
-    return nodes.map((n, i) => _jsx(Fragment, { children: renderNode(n) }, i));
+function renderNodes(nodes, r) {
+    return nodes.map((n, i) => _jsx(Fragment, { children: renderNode(n, r) }, i));
 }
-function renderNode(node) {
+function renderNode(node, r) {
     if (!node || typeof node !== "object")
         return null;
-    const children = Array.isArray(node.content) ? renderNodes(node.content) : null;
+    const children = Array.isArray(node.content) ? renderNodes(node.content, r) : null;
     switch (node.type) {
         case "text": return withMarks(node.text ?? "", node.marks ?? []);
         case "paragraph": return _jsx("p", { children: children });
@@ -43,6 +55,21 @@ function renderNode(node) {
         case "listItem": return _jsx("li", { children: children });
         case "blockquote": return _jsx("blockquote", { children: children });
         case "hardBreak": return _jsx("br", {});
+        case IMAGE_NODE: {
+            const a = (node.attrs ?? {});
+            if (!isResolvedImage(a.image))
+                return null;
+            return r.image({ image: a.image, caption: typeof a.caption === "string" ? a.caption : "" });
+        }
+        case ELEMENT_NODE: {
+            const a = (node.attrs ?? {});
+            const Component = typeof a.name === "string" ? r.elements.get(a.name) : undefined;
+            if (!Component)
+                return null;
+            const fields = a.fields && typeof a.fields === "object" ? a.fields : {};
+            const styles = a.styles && typeof a.styles === "object" ? a.styles : {};
+            return _jsx(Component, { ...fields, styles: styles });
+        }
         default: return children;
     }
 }

package/dist/richtext-walk.d.ts

@@ -0,0 +1,44 @@
+import type { Descriptor } from "./fields.ts";
+export declare const IMAGE_NODE = "image";
+export declare const ELEMENT_NODE = "element";
+export type ImageNodeAttrs = {
+    image?: unknown;
+    caption?: unknown;
+};
+export type ElementNodeAttrs = {
+    name?: unknown;
+    fields?: unknown;
+    styles?: unknown;
+};
+/** A block node as stored — `attrs` is the live object, so a walk may resolve in place. */
+export type BlockNode = {
+    type: string;
+    attrs: Record<string, unknown>;
+};
+/** Every image or element node in document order, at any depth. */
+export declare function richtextBlocks(doc: unknown): BlockNode[];
+/** An element's descriptors by name — what the walks read an element node against. */
+export type ElementSchemas = Record<string, {
+    fields: Record<string, Descriptor>;
+    styles: Record<string, Descriptor>;
+}>;
+type ElementLike = {
+    name: string;
+    fields: Record<string, Descriptor>;
+    styles?: Record<string, Descriptor>;
+} | {
+    schema: {
+        name: string;
+        fields: Record<string, Descriptor>;
+        styles?: Record<string, Descriptor>;
+    };
+};
+export declare function elementSchemas(list: ElementLike[] | undefined): ElementSchemas;
+/** The element schema an element node names, or null for an unknown one. */
+export declare function elementOf(node: BlockNode, elements: ElementSchemas): ElementSchemas[string] | null;
+/** An element node's field and style value sets, for a walk. */
+export declare function elementSets(node: BlockNode, schema: ElementSchemas[string]): {
+    values: Record<string, unknown>;
+    descriptors: Record<string, Descriptor>;
+}[];
+export {};

package/dist/richtext-walk.js

@@ -0,0 +1,46 @@
+export const IMAGE_NODE = "image";
+export const ELEMENT_NODE = "element";
+const isNode = (v) => typeof v === "object" && v !== null && typeof v.type === "string";
+/** Every image or element node in document order, at any depth. */
+export function richtextBlocks(doc) {
+    const out = [];
+    const walk = (n) => {
+        if (!isNode(n))
+            return;
+        if (n.type === IMAGE_NODE || n.type === ELEMENT_NODE) {
+            if (typeof n.attrs !== "object" || n.attrs === null)
+                n.attrs = {};
+            out.push(n);
+        }
+        if (Array.isArray(n.content))
+            for (const c of n.content)
+                walk(c);
+    };
+    walk(doc);
+    return out;
+}
+export function elementSchemas(list) {
+    const out = {};
+    for (const e of list ?? []) {
+        const s = "schema" in e ? e.schema : e;
+        if (!(s.name in out))
+            out[s.name] = { fields: s.fields, styles: s.styles ?? {} };
+    }
+    return out;
+}
+/** The element schema an element node names, or null for an unknown one. */
+export function elementOf(node, elements) {
+    const name = node.attrs.name;
+    return typeof name === "string" ? elements[name] ?? null : null;
+}
+const asRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v) ? v : undefined;
+/** An element node's field and style value sets, for a walk. */
+export function elementSets(node, schema) {
+    const a = node.attrs;
+    const fields = asRecord(a.fields);
+    const styles = asRecord(a.styles);
+    return [
+        ...(fields ? [{ values: fields, descriptors: schema.fields }] : []),
+        ...(styles ? [{ values: styles, descriptors: schema.styles }] : []),
+    ];
+}

package/dist/schema.d.ts

@@ -1,4 +1,4 @@
-import type { Descriptor, FieldBuilder, ValueOf } from "./fields.ts";
+import { type Descriptor, type FieldBuilder, type ValueOf } from "./fields.ts";
 import { pageSchema } from "./page.ts";
 export type BuilderMap = Record<string, FieldBuilder<any, any>>;
 export type SectionSchema<F extends BuilderMap = BuilderMap, S extends BuilderMap = BuilderMap> = {

package/dist/schema.js

@@ -1,3 +1,4 @@
+import { describePath, findMatch } from "./fields.js";
 import { pageSchema } from "./page.js";
 function toDescriptors(map) {
     return Object.fromEntries(Object.entries(map ?? {}).map(([k, b]) => [k, b.descriptor]));
@@ -35,6 +36,17 @@ export const schema = {
         return { kind: "section", ...baseSchema(input) };
     },
     element(input) {
-        return { kind: "element", contexts: input.contexts, ...baseSchema(input) };
+        const base = baseSchema(input);
+        // An element inside a document is unreachable to the refs index, which
+        // addresses refs by top-level key (spec 2026-09-08 block nodes §1).
+        if (input.contexts.includes("richtext")) {
+            for (const [key, d] of Object.entries(base.fields)) {
+                const hit = findMatch(d, (sub) => sub.type === "ref" || sub.type === "refList", key);
+                if (hit !== null) {
+                    throw new Error(`smoodly: element "${base.name}" cannot hold a ref (at ${describePath(hit)}) — refs cannot live inside richtext.`);
+                }
+            }
+        }
+        return { kind: "element", contexts: input.contexts, ...base };
     },
 };

package/dist/section-wrapper.js

@@ -1,4 +1,5 @@
 import { createElement } from "react";
+import { NODE_ATTR } from "./marks.js";
 // The root wrapper every section renders through. Owns the mechanical DOM
 // work on the real root element (no extra div): element choice via `as`,
 // string-valued styles emitted as kebab-cased data attributes. Built-in
@@ -10,7 +11,7 @@ export function Section({ as = "section", styles, className, style, children, })
     const { __smoodlyNode, ...rest } = (styles ?? {});
     const dataAttrs = {};
     if (typeof __smoodlyNode === "string")
-        dataAttrs["data-smoodly-node"] = __smoodlyNode;
+        dataAttrs[NODE_ATTR] = __smoodlyNode;
     for (const [key, value] of Object.entries(rest)) {
         if (typeof value === "string")
             dataAttrs[`data-${kebab(key)}`] = value;

package/dist/site.d.ts

@@ -14,6 +14,8 @@ export type SiteOptions = {
     };
     collections: CollectionSchema<any>[];
     sections: SectionLike[];
+    /** Registered Elements a richtext document may embed (spec 2026-09-08 block nodes §2). */
+    elements?: SectionLike[];
     shared?: SharedSchema[];
     locales: LocaleSet;
     homePageSlug?: string;