smoodly 0.0.34 → 0.0.36

package/dist/next/preview-pill.js

@@ -0,0 +1,56 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+// The preview pill (spec 2026-09-29 pre-install fixes §2): while draft mode
+// is on, outside the editor's canvas, a floating pill says the page shows
+// unpublished changes and offers Exit preview. It is an inline script
+// defining a custom element with its styles in a Shadow DOM — no React,
+// no client module, never in the site's bundles (the live-page rule, §1).
+// The renderer emits it only in draft mode, so a live page's HTML is
+// unchanged. A strict Content-Security-Policy blocks the inline script;
+// the Next.js guide says so. The script is a constant: the route rides on
+// the element, so nothing is interpolated into code.
+import { createElement } from "react";
+const CSS = ":host{all:initial}:host([hidden]){display:none}" +
+    ".pill{position:fixed;bottom:16px;z-index:2147483647;display:flex;align-items:center;gap:8px;padding:6px 6px 6px 14px;" +
+    "border-radius:999px;background:#151727;color:#fff;font:500 13px/1.2 system-ui,-apple-system,sans-serif;" +
+    "box-shadow:0 4px 16px rgba(0,0,0,.25);cursor:grab;user-select:none;touch-action:none}" +
+    ".pill[data-pos=left]{left:16px}.pill[data-pos=center]{left:50%;transform:translateX(-50%)}.pill[data-pos=right]{right:16px}" +
+    ".pill.dragging{cursor:grabbing}" +
+    "a{color:#151727;background:#fff;border-radius:999px;padding:5px 10px;text-decoration:none;font-weight:600}" +
+    "button{all:unset;cursor:pointer;width:24px;height:24px;border-radius:999px;display:grid;place-items:center;color:#fff;opacity:.7}" +
+    "button:hover,button:focus-visible{opacity:1;outline:2px solid #fff}";
+const HTML = '<div class="pill" role="region" aria-label="Smoodly preview">' +
+    "<span>Preview \\u00b7 unpublished changes</span>" +
+    '<a href="#">Exit preview</a>' +
+    '<button type="button" aria-label="Hide until reload">\\u00d7</button>' +
+    "</div>";
+/** The pill's whole client side. `closed` lives in the closure, so a hidden
+ *  pill stays hidden across client navigations and returns on a reload. */
+export const PREVIEW_PILL_SCRIPT = "(function(){" +
+    'if(customElements.get("smoodly-preview-pill"))return;' +
+    'var KEY="smoodly-pill-position",closed=false;' +
+    'function load(){try{var v=localStorage.getItem(KEY);return v==="left"||v==="right"?v:"center"}catch(e){return"center"}}' +
+    "function save(v){try{localStorage.setItem(KEY,v)}catch(e){}}" +
+    "class Pill extends HTMLElement{connectedCallback(){" +
+    "if(closed){this.hidden=true;return}" +
+    "if(this.shadowRoot)return;" +
+    'var root=this.attachShadow({mode:"open"}),self=this;' +
+    `root.innerHTML="<style>${CSS}</style>${HTML.replace(/"/g, '\\"')}";` +
+    'var pill=root.querySelector(".pill"),link=root.querySelector("a"),close=root.querySelector("button");' +
+    'pill.setAttribute("data-pos",load());' +
+    'link.addEventListener("click",function(e){e.preventDefault();var route=self.getAttribute("data-route")||"/api/preview";' +
+    'location.href=route+(route.indexOf("?")<0?"?":"&")+"disable&path="+encodeURIComponent(location.pathname+location.search)});' +
+    'close.addEventListener("click",function(){closed=true;self.hidden=true});' +
+    "var start=null;" +
+    'pill.addEventListener("pointerdown",function(e){if(e.target.closest("a,button"))return;start=e.clientX;pill.setPointerCapture(e.pointerId);pill.classList.add("dragging")});' +
+    'pill.addEventListener("pointermove",function(e){if(start!==null)pill.style.translate=(e.clientX-start)+"px 0"});' +
+    'pill.addEventListener("pointerup",function(e){if(start===null)return;start=null;pill.classList.remove("dragging");pill.style.translate="";' +
+    'var x=e.clientX/innerWidth,pos=x<1/3?"left":x>2/3?"right":"center";pill.setAttribute("data-pos",pos);save(pos)});' +
+    'pill.addEventListener("pointercancel",function(){if(start===null)return;start=null;pill.classList.remove("dragging");pill.style.translate=""});' +
+    "}}" +
+    'customElements.define("smoodly-preview-pill",Pill);' +
+    "})();";
+/** The pill for a route that does not go through the renderer: render it
+ *  when `(await draftMode()).isEnabled`, never in the editor's canvas. */
+export function previewPill(opts) {
+    return (_jsxs(_Fragment, { children: [_jsx("script", { dangerouslySetInnerHTML: { __html: PREVIEW_PILL_SCRIPT } }), createElement("smoodly-preview-pill", { "data-route": opts?.route ?? "/api/preview" })] }));
+}

package/dist/next/preview-route.d.ts

@@ -0,0 +1 @@
+export declare function previewRoute(request: Request): Promise<Response>;

package/dist/next/preview-route.js

@@ -0,0 +1,30 @@
+// The draft-mode switch every starter mounts at app/api/preview/route.ts
+// (spec 2026-09-29 pre-install fixes §2). Turning drafts OFF is harmless,
+// so `?disable` needs no secret — the preview pill's Exit links here.
+// Turning them ON needs SMOODLY_PREVIEW_SECRET and fails closed when it is
+// unset. Either way it returns to a same-origin path.
+import { draftMode } from "next/headers";
+import { redirect } from "next/navigation";
+export async function previewRoute(request) {
+    const url = new URL(request.url);
+    const draft = await draftMode();
+    if (url.searchParams.has("disable")) {
+        draft.disable();
+    }
+    else {
+        const secret = process.env.SMOODLY_PREVIEW_SECRET;
+        if (!secret || url.searchParams.get("secret") !== secret)
+            return new Response("Invalid secret", { status: 401 });
+        draft.enable();
+    }
+    redirect(sameOriginPath(url.searchParams.get("path") ?? "/", url));
+}
+/** The path as this origin resolves it, or "/" when it would leave the site. A browser's URL parser strips
+ *  tab, CR and LF before it resolves a Location, so "/\t/evil.test" is "//evil.test" to it: resolve the
+ *  way it does and compare origins, and refuse control characters and backslashes outright. */
+function sameOriginPath(raw, base) {
+    if (!raw.startsWith("/") || /[\u0000-\u001f\u007f\\]/.test(raw))
+        return "/";
+    const to = new URL(raw, base);
+    return to.origin === base.origin ? to.pathname + to.search + to.hash : "/";
+}

package/dist/next/queries.d.ts

@@ -1,28 +1,27 @@
 import type { CollectionSchema } from "../collections.ts";
-import type { EntryRecord } from "../entry-store.ts";
 import type { GlobalSchema } from "../global.ts";
-import type { EntryQuery, PageTreeItem, SiteEntryItem, SitePage, SmoodlySite } from "../site.ts";
+import { type EntryItem, type PageItem } from "../read-shapes.ts";
+import type { Materialize } from "../schema.ts";
+import type { EntryQuery, PageTreeItem, SmoodlySite } from "../site.ts";
 export type QueryOptions = {
     locale?: string;
 };
-export type EntriesQuery = Omit<EntryQuery, "locale" | "draft"> & QueryOptions;
+export type EntriesQuery = Omit<EntryQuery, "locale" | "draft" | "ids"> & QueryOptions;
 type ByName<T, N> = Extract<T, {
     name: N;
 }>;
-/** Fields typed from the schema; a widened `CollectionSchema[]` array (names are `string`) falls back to the untyped record instead of `never`. */
-type EntryFields<C extends readonly CollectionSchema<any, string>[], N> = string extends C[number]["name"] ? Record<string, unknown> : NonNullable<ByName<C[number], N>["__entry"]>;
-/** A list item whose `entry.fields` are the collection's typed values. */
-export type TypedEntryItem<C extends readonly CollectionSchema<any, string>[], N> = Omit<SiteEntryItem, "entry"> & {
-    entry: Omit<EntryRecord, "fields"> & {
-        fields: EntryFields<C, N>;
-    };
+/** Fields typed from the schema, references materialized as `EntryRef`s; a widened `CollectionSchema[]` array (names are `string`) falls back to the untyped record instead of `never`. */
+type EntryFields<C extends readonly CollectionSchema<any, string>[], N> = string extends C[number]["name"] ? Record<string, unknown> : {
+    [K in keyof NonNullable<ByName<C[number], N>["__entry"]>]: Materialize<NonNullable<ByName<C[number], N>["__entry"]>[K]>;
 };
+/** A read item whose `fields` are the collection's typed values. */
+export type TypedEntryItem<C extends readonly CollectionSchema<any, string>[], N> = EntryItem<EntryFields<C, N>>;
 export type GlobalValue<S extends readonly GlobalSchema<any, string>[], N> = string extends S[number]["name"] ? Record<string, unknown> : NonNullable<ByName<S[number], N>["__value"]>;
 export type SmoodlyQueries<C extends readonly CollectionSchema<any, string>[], S extends readonly GlobalSchema<any, string>[]> = {
     /** The published page tree in a locale, every item with its page fields. */
     getPageTree(options?: QueryOptions): Promise<PageTreeItem[]>;
     /** A page by locale-relative path ("/company/about-us") or id. */
-    getPage(pathOrId: string, options?: QueryOptions): Promise<SitePage | null>;
+    getPage(pathOrId: string, options?: QueryOptions): Promise<PageItem | null>;
     /** Published entries of a collection: `where` (shared fields), `order`, `limit`, `parent` run in the store. */
     getEntries<N extends C[number]["name"]>(collection: N, options?: EntriesQuery): Promise<TypedEntryItem<C, N>[]>;
     getEntry<N extends C[number]["name"]>(collection: N, idOrPath: string, options?: QueryOptions): Promise<TypedEntryItem<C, N> | null>;

package/dist/next/queries.js

@@ -7,6 +7,7 @@ import { unstable_cache } from "next/cache";
 import { draftMode } from "next/headers";
 import { connection } from "next/server";
 import { collectionTag, entryTag, pageTag, pagesTreeTag, globalTag } from "../revalidate.js";
+import { referencedCollections } from "../read-shapes.js";
 /** JSON with object keys sorted at every level and `undefined` dropped, so two spellings of one query share a unit. */
 function stable(value) {
     if (Array.isArray(value))
@@ -26,6 +27,7 @@ function entriesKey(o) {
 }
 export function createSmoodlyQueries(options) {
     const { site } = options;
+    const collectionByName = new Map(options.collections.map((c) => [c.name, c]));
     const globalByName = new Map((options.globals ?? []).map((s) => [s.name, s]));
     const localeOf = (o) => o?.locale ?? site.locales.default;
     /** Every query gates on the request (never a build prerender), then reads live in draft mode or cached under `tags`. */
@@ -59,7 +61,10 @@ export function createSmoodlyQueries(options) {
         getEntries: (collection, o = {}) => {
             const locale = localeOf(o);
             const { locale: _locale, ...query } = o;
-            return run(["entries", collection, locale, entriesKey(o)], [collectionTag(collection)], (draft) => site.getEntries(collection, { ...query, locale, draft }));
+            // The unit also depends on every collection its references resolve into (spec 2026-09-29 content API contract §6).
+            const schema = collectionByName.get(collection);
+            const tags = [collection, ...(schema ? referencedCollections(schema, [...options.collections]) : [])];
+            return run(["entries", collection, locale, entriesKey(o)], [...new Set(tags)].map(collectionTag), (draft) => site.getEntries(collection, { ...query, locale, draft }));
         },
         async getEntry(collection, idOrPath, o) {
             const locale = localeOf(o);
@@ -70,7 +75,7 @@ export function createSmoodlyQueries(options) {
                 const hit = await site.getEntry(collection, idOrPath, { locale, draft });
                 // The site layer also answers a bare root slug, but the unit would sit under
                 // a tag no op ever fires — so a slug is refused here rather than cached stale.
-                if (hit && !idOrPath.startsWith("/") && hit.entry.id !== idOrPath) {
+                if (hit && !idOrPath.startsWith("/") && hit.id !== idOrPath) {
                     throw new Error(`smoodly: getEntry("${collection}", "${idOrPath}") takes an id or a path — for a slug, pass the entry's path.`);
                 }
                 return hit;

package/dist/page.d.ts

@@ -13,7 +13,8 @@ export type PageSchema<Zones extends Record<string, unknown> = Record<string, un
      * segment; the default locale's entry is required (see `fixedSlug`). */
     slug?: string | Record<string, string>;
     zones: Record<keyof Zones & string, ZonePolicy>;
-    meta: Record<string, unknown>;
+    /** The SEO & Social tab exists for this template; reads return `seo` and the route's metadata uses it (spec 2026-09-29 content API contract §7). */
+    seo?: true;
     /** The template's own page-level fields (spec 2026-09-10 page fields §1):
      *  stored in the tree per locale, typed on the view's `page.fields`. */
     fields: Record<string, Descriptor>;
@@ -27,7 +28,9 @@ export declare function pageSchema<Zones extends Record<string, object>, F exten
     title: string;
     slug?: string | Record<string, string>;
     zones: Zones;
-    meta?: Record<string, unknown>;
+    seo?: true;
+    /** Gone: `meta: { seo: true }` is `seo: true`. */
+    meta?: never;
     fields?: F;
 }): PageSchema<Zones, F>;
 /** The default-locale segment of a fixed slug — what the admin lists and

package/dist/page.js

@@ -44,6 +44,8 @@ function normalizePolicy(p) {
 export function pageSchema(input) {
     if (!input?.name)
         throw new Error("smoodly: a page requires a name.");
+    if (input.meta !== undefined)
+        throw new Error(`smoodly: page "${input.name}": meta: { seo: true } is now seo: true.`);
     // A fixed slug is decided by `slug !== undefined` at every other hop, but
     // the renderer's path lookup is truthiness-based: an empty string would read
     // as fixed to the admin and blow up in the route. Reject it at construction.
@@ -62,7 +64,7 @@ export function pageSchema(input) {
         title: input.title,
         ...(input.slug !== undefined ? { slug: input.slug } : {}),
         zones: Object.fromEntries(Object.entries(input.zones).map(([k, p]) => [k, normalizePolicy(p)])),
-        meta: input.meta ?? {},
+        ...(input.seo === true ? { seo: true } : {}),
         fields,
     };
 }

package/dist/pairing.d.ts

@@ -1,5 +1,5 @@
 import type { ComponentType, ReactElement } from "react";
-import type { BuilderMap, ElementSchema, NamespaceValues, SectionSchema } from "./schema.ts";
+import type { BuilderMap, ElementSchema, SectionSchema, Values } from "./schema.ts";
 import type { PageContext, ZoneContent } from "./render.tsx";
 import type { StyleProps } from "./styles.ts";
 /** What the view receives. A page view gets its zones and where it sits
@@ -14,28 +14,28 @@ export type Props<S> = S extends {
     __fields?: infer F extends BuilderMap;
 } ? {
     zones: Record<keyof Z & string, ZoneContent>;
-    page: PageContext<NamespaceValues<F>>;
+    page: PageContext<Values<F>>;
 } : S extends {
     __f?: infer F extends BuilderMap;
     __s?: infer St extends BuilderMap;
-} ? NamespaceValues<F> & {
-    settings: NamespaceValues<St>;
+} ? Values<F> & {
+    settings: Values<St>;
     styles: StyleProps;
 } : never;
 /** What hard-coded JSX may pass: fields flat, settings optional and partial, styles optional. */
-type ExternalProps<F extends BuilderMap, St extends BuilderMap> = NamespaceValues<F> & {
-    settings?: Partial<NamespaceValues<St>>;
+type ExternalProps<F extends BuilderMap, St extends BuilderMap> = Values<F> & {
+    settings?: Partial<Values<St>>;
     styles?: StyleProps;
 };
 export type PairedComponent<Schema, F extends BuilderMap, St extends BuilderMap> = ((props: ExternalProps<F, St>) => ReactElement) & {
     schema: Schema;
 };
-export declare function section<F extends BuilderMap, St extends BuilderMap>(schema: SectionSchema<F, St>, View: ComponentType<NamespaceValues<F> & {
-    settings: NamespaceValues<St>;
+export declare function section<F extends BuilderMap, St extends BuilderMap>(schema: SectionSchema<F, St>, View: ComponentType<Values<F> & {
+    settings: Values<St>;
     styles: StyleProps;
 }>): PairedComponent<SectionSchema<F, St>, F, St>;
-export declare function element<F extends BuilderMap, St extends BuilderMap>(schema: ElementSchema<F, St>, View: ComponentType<NamespaceValues<F> & {
-    settings: NamespaceValues<St>;
+export declare function element<F extends BuilderMap, St extends BuilderMap>(schema: ElementSchema<F, St>, View: ComponentType<Values<F> & {
+    settings: Values<St>;
     styles: StyleProps;
 }>): PairedComponent<ElementSchema<F, St>, F, St>;
 export {};

package/dist/path-index.d.ts

@@ -16,6 +16,8 @@ export interface PathIndex {
     resolve(locale: string, path: string): Promise<PathHit | null>;
     /** locale → the target's LIVE path. */
     pathsOf(target: PathTarget): Promise<Record<string, string>>;
+    /** id → the LIVE full path in one locale, for many targets at once (the resolver's EntryRef paths). */
+    livePathsIn(kind: "page" | "entry", ids: string[], locale: string): Promise<Record<string, string>>;
     /** The target's redirect rows. */
     redirectsOf(target: PathTarget): Promise<PathRow[]>;
     listLive(locale: string): Promise<PathRow[]>;
@@ -40,6 +42,7 @@ export declare class MemoryPathIndex implements PathIndex {
     private hit;
     resolve(locale: string, path: string): Promise<PathHit | null>;
     pathsOf(target: PathTarget): Promise<Record<string, string>>;
+    livePathsIn(kind: "page" | "entry", ids: string[], locale: string): Promise<Record<string, string>>;
     redirectsOf(target: PathTarget): Promise<PathRow[]>;
     /** Every live URL in the locale; an editor's row under a code address is left out, since visitors never reach it (spec §4). */
     listLive(locale: string): Promise<PathRow[]>;

package/dist/path-index.js

@@ -61,6 +61,13 @@ export class MemoryPathIndex {
             out[r.locale] = r.path;
         return out;
     }
+    async livePathsIn(kind, ids, locale) {
+        const wanted = new Set(ids);
+        const out = {};
+        for (const r of this.shownAll(this.rows.filter((r) => !r.redirect && r.kind === kind && r.locale === locale && wanted.has(r.id))))
+            out[r.id] = r.path;
+        return out;
+    }
     async redirectsOf(target) {
         return this.shownAll(this.rows.filter((r) => r.redirect && sameTarget(r, target)));
     }

package/dist/read-shapes.d.ts

@@ -0,0 +1,64 @@
+import type { CollectionSchema } from "./collections.ts";
+import type { EntryRecord } from "./entry-store.ts";
+import type { LocaleAlternate, PageAlternate } from "./paths.ts";
+import type { PageLink } from "./render.tsx";
+import type { ResolvedImage } from "./media.ts";
+import type { SitePage } from "./site.ts";
+import type { StyleProps } from "./styles.ts";
+/** A resolved reference: the target in the read's locale (§2). */
+export type EntryRef<F = Record<string, unknown>> = {
+    id: string;
+    path: string | null;
+    fields: F;
+};
+/** The effective SEO values: an editor's override where set, the fallback otherwise (§3, §7). */
+export type Seo = {
+    title?: string;
+    description?: string;
+    image?: ResolvedImage;
+    noindex?: boolean;
+};
+export type EntryItem<F = Record<string, unknown>> = {
+    id: string;
+    path: string | null;
+    locale: string;
+    locales: Record<string, LocaleAlternate | null>;
+    updatedAt: number;
+    fields: F;
+    seo?: Seo;
+};
+export type PageItem<F = Record<string, unknown>> = {
+    id: string;
+    title: string;
+    path: string;
+    locale: string;
+    locales: Record<string, PageAlternate | null>;
+    template: string;
+    fields: F;
+    seo?: Seo;
+    ancestors: PageLink[];
+    children: PageLink[];
+};
+export type GlobalItem<F = Record<string, unknown>, S = Record<string, unknown>> = {
+    locale: string;
+    fields: F;
+    settings?: S;
+    styles?: StyleProps;
+};
+/** A visual item's read: its settings and styles always present. */
+export type VisualGlobalItem<F = Record<string, unknown>, S = Record<string, unknown>> = GlobalItem<F, S> & {
+    settings: S;
+    styles: StyleProps;
+};
+/** One entry as a read returns it: Smoodly's keys, the content under `fields`; the record never leaves the site layer. */
+export declare function toEntryItem(record: EntryRecord, fields: Record<string, unknown>, o: {
+    path: string | null;
+    locale: string;
+    locales: Record<string, LocaleAlternate | null>;
+    seo?: Seo;
+}): EntryItem;
+/** One page as a read returns it: no record, no tree. */
+export declare function toPageItem(hit: SitePage): PageItem;
+/** Every collection a read of `schema` resolves into, by each ref field's own depth (the mirror of
+ *  runResolution's modes) — a list unit's extra tags (spec 2026-09-29 content API contract §6). */
+export declare function referencedCollections(schema: CollectionSchema<any>, all: CollectionSchema<any>[]): string[];

package/dist/read-shapes.js

@@ -0,0 +1,52 @@
+import { SEO_KEY } from "./seo.js";
+/** One entry as a read returns it: Smoodly's keys, the content under `fields`; the record never leaves the site layer. */
+export function toEntryItem(record, fields, o) {
+    // The reserved `$seo` values are Smoodly's: they leave as `seo`, never as a field.
+    const { [SEO_KEY]: _seo, ...rest } = fields;
+    return {
+        id: record.id, path: o.path, locale: o.locale, locales: o.locales,
+        updatedAt: record.locales[o.locale]?.updatedAt ?? record.updatedAt, fields: rest,
+        ...(o.seo ? { seo: o.seo } : {}),
+    };
+}
+/** One page as a read returns it: no record, no tree. */
+export function toPageItem(hit) {
+    return {
+        id: hit.record.id, title: hit.title, path: hit.path, locale: hit.locale, locales: hit.locales,
+        template: hit.template, fields: hit.fields, ...(hit.seo ? { seo: hit.seo } : {}),
+        ancestors: hit.ancestors, children: hit.children,
+    };
+}
+/** Every collection a read of `schema` resolves into, by each ref field's own depth (the mirror of
+ *  runResolution's modes) — a list unit's extra tags (spec 2026-09-29 content API contract §6). */
+export function referencedCollections(schema, all) {
+    const byName = new Map(all.map((c) => [c.name, c]));
+    const out = new Set();
+    const walk = (s, mode, seen) => {
+        for (const [key, raw] of Object.entries(s.fields)) {
+            const d = raw;
+            if (d.type !== "ref" && d.type !== "refList")
+                continue;
+            let next;
+            if (mode === "own")
+                next = d.resolve === "full" ? "full" : d.resolve !== null && typeof d.resolve === "object" ? d.resolve : "shallow";
+            else if (mode === "full")
+                next = "full";
+            else if (mode === "shallow")
+                continue;
+            else {
+                const on = mode[key];
+                if (!on)
+                    continue;
+                next = typeof on === "object" ? on : "shallow";
+            }
+            const name = d.target().name;
+            out.add(name);
+            const target = byName.get(name);
+            if (next !== "shallow" && target && !seen.has(name))
+                walk(target, next, new Set([...seen, name]));
+        }
+    };
+    walk(schema, "own", new Set([schema.name]));
+    return [...out];
+}

package/dist/render.d.ts

@@ -1,7 +1,7 @@
 import { type ComponentType, type ReactElement, type ReactNode } from "react";
 import type { PageAlternate } from "./paths.ts";
 import type { PageSchema } from "./page.ts";
-import type { BuilderMap, NamespaceValues } from "./schema.ts";
+import type { BuilderMap, Values } from "./schema.ts";
 import { type StyleValues } from "./styles.ts";
 import { type CustomOptions } from "./custom/index.ts";
 export type TreeNode = {
@@ -96,10 +96,10 @@ export type PageViewProps<Zones extends Record<string, unknown>, Fields = Record
     zones: Record<keyof Zones & string, ZoneContent>;
     page: PageContext<Fields>;
 };
-export type PairedPage<Zones extends Record<string, unknown>, F extends BuilderMap = BuilderMap> = ((props: PageViewProps<Zones, NamespaceValues<F>>) => ReactElement) & {
+export type PairedPage<Zones extends Record<string, unknown>, F extends BuilderMap = BuilderMap> = ((props: PageViewProps<Zones, Values<F>>) => ReactElement) & {
     schema: PageSchema<Zones, F>;
 };
-export declare function page<Zones extends Record<string, unknown>, F extends BuilderMap = {}>(schema: PageSchema<Zones, F>, View: ComponentType<PageViewProps<Zones, NamespaceValues<F>>>): PairedPage<Zones, F>;
+export declare function page<Zones extends Record<string, unknown>, F extends BuilderMap = {}>(schema: PageSchema<Zones, F>, View: ComponentType<PageViewProps<Zones, Values<F>>>): PairedPage<Zones, F>;
 export type Registry = {
     sections?: AnyPaired[];
     elements?: AnyPaired[];

package/dist/resolve.d.ts

@@ -7,6 +7,8 @@ import { type ElementSchemas } from "./richtext-walk.ts";
 import type { SectionLike } from "./refs.ts";
 import type { Toolset } from "./toolset.ts";
 export type EntryFetcher = (collection: string, ids: string[]) => Promise<Record<string, Record<string, unknown>>>;
+/** id → the entry's live full path in the read's locale; ids without one are absent. */
+export type PathLookup = (collection: string, ids: string[]) => Promise<Record<string, string>>;
 export type AssetFetcher = (ids: string[]) => Promise<Record<string, AssetRecord>>;
 type SchemaLike = {
     name: string;
@@ -25,6 +27,8 @@ type ResolveOptions = {
     })[];
     collections: CollectionSchema<any>[];
     fetch: EntryFetcher;
+    /** Each hydrated ref's address (spec 2026-09-29 content API contract §2). */
+    paths?: PathLookup;
     /** Media (spec 2026-09-08 §9): one batched asset fetch per page, values become resolved objects. */
     assets?: AssetFetcher;
     /** The registered global items a placement node may name (spec 2026-09-07 §4). */
@@ -52,6 +56,8 @@ export declare function resolveMediaSets(sets: MediaSet[], fetch: AssetFetcher,
 export type ResolveFieldsOptions = {
     collections: CollectionSchema<any>[];
     fetch: EntryFetcher;
+    /** Each hydrated ref's address (spec 2026-09-29 content API contract §2). */
+    paths?: PathLookup;
     assets?: AssetFetcher;
     /** Registered Elements a richtext document may embed (spec 2026-09-08 block nodes §2). */
     elements?: SectionLike[];
@@ -60,4 +66,10 @@ export type ResolveFieldsOptions = {
 /** One entry's fields, refs hydrated — the entry page's counterpart of
  *  resolveTree. Same rules, same batching, same cycle cut. */
 export declare function resolveFields(fields: Record<string, unknown>, descriptors: Record<string, Descriptor>, options: ResolveFieldsOptions): Promise<Record<string, unknown>>;
+/** Many value sets (a list's entries), one resolution: every ref batched per
+ *  collection across all sets, then one media round — all in place. */
+export declare function resolveFieldSets(sets: {
+    values: Record<string, unknown>;
+    descriptors: Record<string, Descriptor>;
+}[], options: ResolveFieldsOptions): Promise<void>;
 export {};

package/dist/resolve.js

@@ -1,6 +1,6 @@
 // The batched ref-resolution pass (DESIGN.md §3): one walk collects every
 // ref in the tree, fetches per collection in single batched calls, and
-// hands components hydrated entries. The ref site alone decides depth:
+// hands components hydrated entries as `{ id, path, fields }` (spec 2026-09-29 content API contract §2). The ref site alone decides depth:
 // bare refs hydrate one entry (refs stay ids), `.resolve("key")` follows
 // the named refs one level, and bare `.resolve()` follows the whole chain.
 // Cycles are cut per path — a ref back to an entry already on its own
@@ -9,6 +9,7 @@
 import { globalLink, GLOBAL_NODE_TYPE, SETTINGS_KEY, STYLES_KEY, CSS_KEY } from "./global.js";
 import { applyAssets, collectAssetIds } from "./media.js";
 import { elementSchemas } from "./richtext-walk.js";
+import { SEO_KEY } from "./seo.js";
 import { CUSTOM_NODE_TYPE, customSchema, customToolset } from "./custom/index.js";
 /** The built-in SEO set's one media value (spec 2026-09-10 page fields §2). */
 const META_DESCRIPTORS = { ogImage: { type: "image" } };
@@ -47,7 +48,7 @@ export async function resolveTree(tree, options) {
     }
     if (options.page && resolved.fields)
         collectTasks(resolved.fields, options.page.fields, tasks);
-    const hydrated = await runResolution(tasks, { collections: options.collections, fetch: options.fetch, maxDepth });
+    const hydrated = await runResolution(tasks, { collections: options.collections, fetch: options.fetch, paths: options.paths, maxDepth });
     if (options.assets) {
         const sets = [];
         for (const node of Object.values(resolved.zones ?? {}).flat()) {
@@ -150,6 +151,16 @@ export async function resolveFields(fields, descriptors, options) {
         await resolveMediaSets([{ values: resolved, descriptors }, ...hydrated], options.assets, elementSchemas(options.elements));
     return resolved;
 }
+/** Many value sets (a list's entries), one resolution: every ref batched per
+ *  collection across all sets, then one media round — all in place. */
+export async function resolveFieldSets(sets, options) {
+    const tasks = [];
+    for (const { values, descriptors } of sets)
+        collectTasks(values, descriptors, tasks);
+    const hydrated = await runResolution(tasks, { ...options, maxDepth: options.maxDepth ?? Infinity });
+    if (options.assets)
+        await resolveMediaSets([...sets, ...hydrated], options.assets, elementSchemas(options.elements));
+}
 /** Hydrates every task's refs in place and returns each hydrated entry
  *  copy with its collection's descriptors — the media pass walks those
  *  too, so a card reached through a ref carries its image URL. */
@@ -157,6 +168,7 @@ async function runResolution(seeds, options) {
     const collectionSchemas = new Map(options.collections.map((c) => [c.name, c]));
     // every entry is fetched once; cycle cuts reuse cached ancestors
     const cache = new Map();
+    const pathCache = new Map();
     const hydrated = [];
     let tasks = seeds;
     for (let round = 0; round < options.maxDepth && tasks.length > 0; round++) {
@@ -177,6 +189,14 @@ async function runResolution(seeds, options) {
             for (const [id, entry] of Object.entries(fetched))
                 table.set(id, entry);
             cache.set(collection, table);
+            // a collection with no path has no addresses: its refs carry path null
+            if (options.paths && collectionSchemas.get(collection)?.path !== undefined) {
+                const found = await options.paths(collection, [...ids]);
+                const paths = pathCache.get(collection) ?? new Map();
+                for (const [id, p] of Object.entries(found))
+                    paths.set(id, p);
+                pathCache.set(collection, paths);
+            }
         }));
         // apply results and queue follow-ups per the task's mode
         const next = [];
@@ -185,19 +205,21 @@ async function runResolution(seeds, options) {
                 const raw = cache.get(task.collection)?.get(id);
                 if (!raw)
                     return null;
-                const entry = structuredClone(raw);
+                // The SEO panel's values are the entry page's, never a reference's (and would cost a media fetch).
+                const { [SEO_KEY]: _seo, ...entry } = structuredClone(raw);
+                const ref = { id, path: pathCache.get(task.collection)?.get(id) ?? null, fields: entry };
                 const schema = collectionSchemas.get(task.collection);
                 if (schema)
                     hydrated.push({ values: entry, descriptors: schema.fields });
                 const pathKey = `${task.collection}:${id}`;
                 // cycle: this entry is its own ancestor — shallow copy, no recursion
                 if (task.ancestors.includes(pathKey))
-                    return entry;
+                    return ref;
                 if (task.mode === "shallow")
-                    return entry;
+                    return ref;
                 const targetSchema = collectionSchemas.get(task.collection);
                 if (!targetSchema)
-                    return entry;
+                    return ref;
                 const ancestors = [...task.ancestors, pathKey];
                 for (const [key, d] of Object.entries(targetSchema.fields)) {
                     if (d.type !== "ref" && d.type !== "refList")
@@ -225,7 +247,7 @@ async function runResolution(seeds, options) {
                         ancestors,
                     });
                 }
-                return entry;
+                return ref;
             };
             task.holder[task.key] = task.isList
                 ? task.id.map(hydrate)

package/dist/schema-version.d.ts

@@ -1,7 +1,7 @@
 /** The minimum schema version the package needs. Moves ONLY in a release
  *  that adds a table, column, function or policy the package reads; a
  *  unit test holds it equal to the highest file in `migrations/`. */
-export declare const SCHEMA_VERSION = 5;
+export declare const SCHEMA_VERSION = 7;
 export declare const SCHEMA_VERSION_KEY = "schema_version";
 export declare const CORE_FILE_RE: RegExp;
 export declare const VIEWS_FILE_RE: RegExp;

package/dist/schema-version.js

@@ -7,7 +7,7 @@
 /** The minimum schema version the package needs. Moves ONLY in a release
  *  that adds a table, column, function or policy the package reads; a
  *  unit test holds it equal to the highest file in `migrations/`. */
-export const SCHEMA_VERSION = 5;
+export const SCHEMA_VERSION = 7;
 export const SCHEMA_VERSION_KEY = "schema_version";
 export const CORE_FILE_RE = /^(\d{14})_smoodly_v(\d+)\.sql$/;
 export const VIEWS_FILE_RE = /^(\d{14})_smoodly_views\.sql$/;

package/dist/schema.d.ts

@@ -1,5 +1,7 @@
 import { type Descriptor, type FieldBuilder, type ValueOf } from "./fields.ts";
 import { pageSchema } from "./page.ts";
+import type { RefTo } from "./fields.ts";
+import type { EntryRef } from "./read-shapes.ts";
 export type BuilderMap = Record<string, FieldBuilder<any, any>>;
 export type SectionSchema<F extends BuilderMap = BuilderMap, S extends BuilderMap = BuilderMap> = {
     kind: "section";
@@ -37,6 +39,25 @@ export type NamespaceValues<M extends BuilderMap> = {
 } & {
     [K in OptionalKeys<M>]?: ValueOf<M[K]>;
 };
+/** The target's stored entry values (refs still as RefTo markers). */
+type EntryOf<T> = T extends {
+    __entry?: infer E;
+} ? NonNullable<E> : Record<string, unknown>;
+/** A target's fields as a ref site with mode M sees them (the ref site alone decides depth, DESIGN.md §3). */
+export type ShapeOf<T, M> = {
+    [K in keyof EntryOf<T>]: FieldAt<EntryOf<T>[K], M, K>;
+};
+type FieldAt<V, M, K> = V extends RefTo<infer U, any> ? M extends "full" ? EntryRef<ShapeOf<U, "full">> | null : K extends M ? EntryRef<ShapeOf<U, "shallow">> | null : string | null : V extends RefTo<infer U, any>[] ? M extends "full" ? (EntryRef<ShapeOf<U, "full">> | null)[] : K extends M ? (EntryRef<ShapeOf<U, "shallow">> | null)[] : string[] : V;
+/** One value as a read returns it: a ref becomes an EntryRef (or null), a refList a list of them. */
+export type Materialize<V> = V extends RefTo<infer T, infer M> ? EntryRef<ShapeOf<T, M>> | null : V extends RefTo<infer T, infer M>[] ? (EntryRef<ShapeOf<T, M>> | null)[] : V;
+/** What a view and a read receive (spec 2026-09-29 content API contract §4). */
+export type Values<M extends BuilderMap> = {
+    [K in keyof NamespaceValues<M>]: Materialize<NamespaceValues<M>[K]>;
+};
+/** A sample stores ids where a read shows references. */
+type Stored<M extends BuilderMap> = {
+    [K in keyof NamespaceValues<M>]: NamespaceValues<M>[K] extends RefTo<any, any> ? string : NamespaceValues<M>[K] extends RefTo<any, any>[] ? string[] : NamespaceValues<M>[K];
+};
 type SectionInput<F extends BuilderMap, S extends BuilderMap> = {
     name: string;
     title: string;
@@ -50,7 +71,7 @@ type SectionInput<F extends BuilderMap, S extends BuilderMap> = {
         omit: string[];
     };
     css?: false;
-    sample?: Partial<NamespaceValues<F> & NamespaceValues<S>>;
+    sample?: Partial<Stored<F> & Stored<S>>;
 };
 export declare const schema: {
     page: typeof pageSchema;