smoodly 0.0.35 → 0.0.37

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 = 6;
+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 = 6;
+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;

package/dist/seo.d.ts

@@ -0,0 +1,18 @@
+import type { Descriptor } from "./fields.ts";
+import type { Seo } from "./read-shapes.ts";
+/** The reserved key an entry's SEO values live under; a collection may not declare a field of this name. */
+export declare const SEO_KEY = "$seo";
+/** `seo: true` falls back on the title only; the object names the fields the description and the image fall back on. */
+export type CollectionSeo = true | {
+    description?: string;
+    image?: string;
+};
+export declare const SEO_DESCRIPTOR: Descriptor;
+export declare function validateCollectionSeo(name: string, seo: CollectionSeo, fields: Record<string, Descriptor>): void;
+/** An entry's effective SEO: the editor's `$seo` values where set, the fallbacks the collection names otherwise. */
+export declare function entrySeo(fields: Record<string, unknown>, schema: {
+    titleField?: string;
+    seo?: CollectionSeo;
+}): Seo;
+/** A page's effective SEO from its stored meta; the title falls back to the page title. */
+export declare function pageSeo(meta: Record<string, unknown> | undefined, title: string): Seo;

package/dist/seo.js

@@ -0,0 +1,53 @@
+/** The reserved key an entry's SEO values live under; a collection may not declare a field of this name. */
+export const SEO_KEY = "$seo";
+export const SEO_DESCRIPTOR = {
+    type: "object",
+    optional: true,
+    localized: true,
+    fields: {
+        title: { type: "text", optional: true },
+        description: { type: "text", optional: true },
+        ogImage: { type: "image", optional: true },
+        noindex: { type: "boolean", optional: true },
+    },
+};
+export function validateCollectionSeo(name, seo, fields) {
+    if (seo === true)
+        return;
+    for (const [role, key] of Object.entries(seo)) {
+        if (key === undefined)
+            continue;
+        const d = fields[key];
+        if (!d)
+            throw new Error(`smoodly: collection "${name}" seo.${role} names "${key}", which is not a field.`);
+        if (role === "description" && d.type !== "text")
+            throw new Error(`smoodly: collection "${name}" seo.description "${key}" must be a text field, not ${d.type}.`);
+        if (role === "image" && d.type !== "image")
+            throw new Error(`smoodly: collection "${name}" seo.image "${key}" must be an image field, not ${d.type}.`);
+    }
+}
+const str = (v) => (typeof v === "string" && v !== "" ? v : undefined);
+const image = (v) => v !== null && typeof v === "object" && typeof v.url === "string" ? v : undefined;
+const compact = (s) => Object.fromEntries(Object.entries(s).filter(([, v]) => v !== undefined));
+/** An entry's effective SEO: the editor's `$seo` values where set, the fallbacks the collection names otherwise. */
+export function entrySeo(fields, schema) {
+    const raw = fields[SEO_KEY];
+    const own = raw !== null && typeof raw === "object" ? raw : {};
+    const map = schema.seo === true || schema.seo === undefined ? {} : schema.seo;
+    return compact({
+        title: str(own.title) ?? (schema.titleField ? str(fields[schema.titleField]) : undefined),
+        description: str(own.description) ?? (map.description ? str(fields[map.description]) : undefined),
+        image: image(own.ogImage) ?? (map.image ? image(fields[map.image]) : undefined),
+        noindex: own.noindex === true ? true : undefined,
+    });
+}
+/** A page's effective SEO from its stored meta; the title falls back to the page title. */
+export function pageSeo(meta, title) {
+    const m = meta ?? {};
+    return compact({
+        title: str(m.title) ?? str(title),
+        description: str(m.description),
+        image: image(m.ogImage),
+        noindex: m.noindex === true ? true : undefined,
+    });
+}

package/dist/site.d.ts

@@ -10,6 +10,7 @@ import { type StyleValues, type StyleValuesInput } from "./styles.ts";
 import { type CustomConfigInput, type ResolvedCustom } from "./custom/index.ts";
 import type { PageRecord, PageStore } from "./store.ts";
 import type { PathHit } from "./path-index.ts";
+import { type EntryItem, type PageItem, type Seo } from "./read-shapes.ts";
 export type SiteOptions = {
     stores: () => {
         pages: PageStore;
@@ -40,6 +41,7 @@ export type SitePageSchema = {
         title?: string;
         slug?: string | Record<string, string>;
         fields?: Record<string, Descriptor>;
+        seo?: true;
     };
 };
 export type SitePage = {
@@ -58,6 +60,8 @@ export type SitePage = {
     /** One key per supported locale: the page's `{ slug, path }` there, or null where it is
      *  absent or, outside draft mode, unpublished (spec 2026-09-15 §1). */
     locales: Record<string, PageAlternate | null>;
+    /** The effective SEO values, for a template with `seo: true` (spec 2026-09-29 content API contract §7). */
+    seo?: Seo;
 };
 export type SiteEntry = {
     kind: "entry";
@@ -70,6 +74,8 @@ export type SiteEntry = {
     entry: EntryRecord;
     path: string;
     locales: Record<string, LocaleAlternate | null>;
+    /** The effective SEO values, for a collection with `seo` (§7). */
+    seo?: Seo;
 };
 export type SiteHit = SitePage | SiteEntry;
 export type PageTreeItem = {
@@ -80,13 +86,7 @@ export type PageTreeItem = {
     fields: Record<string, unknown>;
     children: PageTreeItem[];
 };
-export type SiteEntryItem = {
-    entry: EntryRecord;
-    path: string | null;
-    locale: string;
-    locales: Record<string, LocaleAlternate | null>;
-};
-export type EntryTreeItem = SiteEntryItem & {
+export type EntryTreeItem = EntryItem & {
     children: EntryTreeItem[];
 };
 /** `where`, `limit`, `parent` and `order` run in the store (spec 2026-09-11 §3); `draft` reads live rows inside the editor preview. */
@@ -97,6 +97,8 @@ export type EntryQuery = {
     where?: Where;
     limit?: number;
     draft?: boolean;
+    /** Only these entries (`getEntry` by id). */
+    ids?: string[];
 };
 /** `version`: a stored page version to render instead of the draft — History (spec 2026-09-13 §4), draft mode only. */
 export type LoadOptions = {
@@ -124,26 +126,23 @@ export interface SmoodlySite {
     getPage(pathOrId: string, options?: {
         locale?: string;
         draft?: boolean;
-    }): Promise<SitePage | null>;
-    getEntries(collection: string, options?: EntryQuery): Promise<SiteEntryItem[]>;
+    }): Promise<PageItem | null>;
+    getEntries(collection: string, options?: EntryQuery): Promise<EntryItem[]>;
     getEntry(collection: string, idOrPath: string, options?: {
         locale?: string;
         draft?: boolean;
-    }): Promise<SiteEntryItem | null>;
+    }): Promise<EntryItem | null>;
     getEntriesTree(collection: string, options?: {
         locale?: string;
         draft?: boolean;
     }): Promise<EntryTreeItem[]>;
-    /** A global item's content in a locale (spec 2026-09-07 §4): an object
-     *  item's merged fields, or a visual item's section props (fields plus
-     *  `settings`), refs hydrated; null when the item has no row there or is
-     *  unpublished (outside draft mode). */
+    /** A global item's content in a locale (spec 2026-09-07 §4): `{ locale, fields }`,
+     *  plus `settings` and `styles` for a visual item, refs hydrated; null when the
+     *  item has no row there or is unpublished (outside draft mode). */
     getGlobal<V>(item: GlobalSchema<V>, options?: {
         locale?: string;
         draft?: boolean;
     }): Promise<V | null>;
 }
-/** The `page` prop for a loaded page. `href` is the app's seam from a
- *  locale-relative path to a site URL; the default keeps CMS paths as URLs. */
 export declare function pageContextOf(hit: SitePage, href?: (path: string, locale: string) => string): PageContext;
 export declare function createSmoodlySite(options: SiteOptions): SmoodlySite;

package/dist/site.js

@@ -1,6 +1,6 @@
-import { ARRAY_FIELD_TYPES, entryFieldsIn, localizedKeys, schemaOf } from "./entry-store.js";
+import { ARRAY_FIELD_TYPES, entryFieldsIn, schemaOf } from "./entry-store.js";
 import { buildPageTree, chainOf, entryAlternates, entryPathRows, entrySegment, pageAlternates, pagePath, } from "./paths.js";
-import { resolveFields, resolveMedia, resolveMediaSets, resolveTree } from "./resolve.js";
+import { resolveFields, resolveFieldSets, resolveMedia, resolveTree } from "./resolve.js";
 import { elementSchemas } from "./richtext-walk.js";
 import { globalNodeId, SETTINGS_KEY, STYLES_KEY, CSS_KEY } from "./global.js";
 import { SMD_KEY } from "./section-wrapper.js";
@@ -9,8 +9,12 @@ import { resolveCustom } from "./custom/index.js";
 import { addressMap, codeAddresses } from "./addresses.js";
 import { fullPath, servedAnchor } from "./anchors.js";
 import { withDefaults } from "./field-defaults.js";
+import { toEntryItem, toPageItem } from "./read-shapes.js";
+import { entrySeo, pageSeo, SEO_KEY } from "./seo.js";
 /** The `page` prop for a loaded page. `href` is the app's seam from a
  *  locale-relative path to a site URL; the default keeps CMS paths as URLs. */
+/** Field types whose stored value is an object: not filterable (memory and SQL would disagree). */
+const OBJECT_FIELD_TYPES = new Set(["image", "video", "file", "richtext", "object"]);
 export function pageContextOf(hit, href = (p) => p) {
     const withUrl = (l) => ({ ...l, url: href(l.path, hit.locale) });
     return {
@@ -41,6 +45,8 @@ export function createSmoodlySite(options) {
      *  locale — published ones (a versioned collection's snapshot) on the
      *  public path, the live rows in draft mode. */
     const fetcher = (draft, locale) => (collection, ids) => options.stores().entries.getMany(collection, ids, locale, draft ? undefined : { status: "published" });
+    /** The resolver's path lookup, bound to a locale: each EntryRef's address (spec 2026-09-29 content API contract §2). */
+    const pathLookup = (locale) => (collection, ids) => options.stores().entries.pathsIn(collection, ids, locale);
     /** The media fetcher (spec 2026-09-08 §9) — absent when the site runs without an asset store. */
     const assetFetcher = () => {
         const assets = options.stores().assets;
@@ -123,7 +129,7 @@ export function createSmoodlySite(options) {
             collections: options.collections,
             globals: options.globals,
             elements: options.elements,
-            fetch: fetcher(draft, locale),
+            fetch: fetcher(draft, locale), paths: pathLookup(locale),
             assets: assetFetcher(),
             page: { fields: pageFields(record.template) },
             custom,
@@ -139,6 +145,7 @@ export function createSmoodlySite(options) {
         // Alternates advertise PUBLISHED locales only; the editor (draft) sees every present
         // one. Derived from the tree already listed — no index lookup (spec 2026-09-15 §2).
         const alternates = pageAlternates(record, byId, pathOpts, (l) => draft || record.locales[l]?.status === "published");
+        const withSeo = (options.pages ?? []).some((x) => x.schema.kind === "page" && x.schema.name === record.template && x.schema.seo === true);
         return {
             kind: "page",
             locale,
@@ -151,6 +158,7 @@ export function createSmoodlySite(options) {
             ancestors,
             children,
             locales: alternates,
+            ...(withSeo ? { seo: pageSeo(tree.meta, row.title) } : {}),
         };
     }
     async function loadEntry(id, locale, path, draft) {
@@ -170,51 +178,38 @@ export function createSmoodlySite(options) {
                 : (await entries.getMany(schema.name, [id], locale, { status: "published" }))[id];
             if (!raw)
                 return null;
-            const fields = await resolveFields(raw, schema.fields, { collections: options.collections, elements: options.elements, fetch: fetcher(draft, locale), assets: assetFetcher() });
+            const fields = await resolveFields(raw, schema.fields, { collections: options.collections, elements: options.elements, fetch: fetcher(draft, locale), paths: pathLookup(locale), assets: assetFetcher() });
             // Alternates advertise PUBLISHED locales only; the editor (draft) sees every present one.
             // One record is in memory (a nested entry's parents are not), so the `paths` index
             // supplies the paths — the same single lookup as before (spec 2026-09-15 §2).
             const known = await entries.pathsOf(schema.name, id);
             const alternates = entryAlternates(record, locales, (l) => draft || record.locales[l]?.status === "published", (l) => known[l] ?? null);
-            return { kind: "entry", locale, collection: schema.name, entry: { ...record, fields }, path, locales: alternates };
+            return {
+                kind: "entry", locale, collection: schema.name, entry: { ...record, fields }, path, locales: alternates,
+                ...(schema.seo ? { seo: entrySeo(fields, schema) } : {}),
+            };
         }
         return null;
     }
     const localeOf = (o) => o?.locale ?? locales.default;
-    /** One locale's published fields and path for entries of one collection;
-     *  `all` is the whole collection (a draft ancestor still contributes
-     *  its segment). `fieldsById` is the published read for the locale. */
-    function entryItems(schema, wanted, all, locale, draft, fieldsById) {
-        const index = new Map(all.map((e) => [e.id, e]));
-        const byId = (x) => index.get(x);
-        return wanted
-            .filter((record) => fieldsById[record.id] !== undefined)
-            .map((record) => {
-            const rows = entryPathRows([record], byId, schema.name);
-            const pathIn = (l) => {
-                const row = rows.find((r) => r.locale === l);
-                return row ? fullPath(anchors, row.anchor ?? "", row.path, l) : null;
-            };
-            return {
-                entry: { ...record, fields: fieldsById[record.id] },
-                path: pathIn(locale),
-                locale,
-                locales: entryAlternates(record, locales, (l) => draft || record.locales[l]?.status === "published", pathIn),
-            };
-        });
-    }
-    async function getEntries(collection, o = {}) {
+    async function readEntries(collection, o = {}) {
         const schema = schemaOf(options.collections, collection);
         const locale = localeOf(o);
         const draft = o.draft ?? false;
         const { entries } = options.stores();
         // A filter that silently matched nothing would be worse than an error (spec 2026-09-11 §3).
         for (const key of Object.keys(o.where ?? {})) {
-            if (key === "slug" || localizedKeys(schema).includes(key)) {
-                throw new Error(`smoodly: getEntries("${collection}"): "${key}" is localized — where filters shared fields only (spec 2026-09-11 §3).`);
+            if (key === "slug") {
+                throw new Error(`smoodly: getEntries("${collection}"): "slug" is not filterable — where filters fields; find an entry by its path instead.`);
             }
+            if (key === SEO_KEY)
+                throw new Error(`smoodly: getEntries("${collection}"): "${SEO_KEY}" is reserved — the SEO panel's values are not filterable.`);
             if (!(key in schema.fields))
                 throw new Error(`smoodly: getEntries("${collection}"): "${key}" is not a field of the collection.`);
+            // The memory adapter's `===` never matches an object while SQL's `@>` matches a subset, so the two would disagree.
+            if (OBJECT_FIELD_TYPES.has(schema.fields[key].type ?? "")) {
+                throw new Error(`smoodly: getEntries("${collection}"): "${key}" holds an object — filter on a scalar field instead.`);
+            }
             // Any-of reads the text form of the whole field (PostgREST's `->>`), which for
             // an array is its JSON — `["a"]` never matches "a" — so refuse rather than match nothing.
             if (Array.isArray(o.where[key]) && ARRAY_FIELD_TYPES.has(schema.fields[key].type ?? "")) {
@@ -224,26 +219,35 @@ export function createSmoodlySite(options) {
         if (o.limit !== undefined && (!Number.isInteger(o.limit) || o.limit < 0)) {
             throw new Error(`smoodly: getEntries("${collection}"): limit must be a non-negative integer.`);
         }
-        // The store filters, orders and limits (spec 2026-09-11 §3): the locale
-        // gate — presence in draft mode, published otherwise — is part of the
-        // query, so `limit` counts rows that are really there.
-        const inLocale = await entries.list(collection, {
-            order: o.order, where: o.where, limit: o.limit,
+        // The store filters, orders and limits over the snapshot shown (spec 2026-09-29 content API contract §5): the
+        // locale gate — presence in draft mode, published otherwise — is part of the query, so `limit` counts rows that are really there.
+        const rows = await entries.query(collection, {
+            locale, draft, where: o.where, order: o.order, limit: o.limit, ids: o.ids,
             ...(o.parent !== undefined ? { parent: o.parent } : {}),
-            ...(draft ? { locale } : { status: "published", locale }),
         });
         // Paths need every ancestor: a tree collection reads the whole collection for that, a flat one does not.
-        const all = schema.tree ? await entries.list(collection) : inLocale;
-        const fieldsById = draft
-            ? Object.fromEntries(inLocale.map((e) => [e.id, entryFieldsIn(e, locale)]))
-            : await entries.getMany(collection, inLocale.map((e) => e.id), locale, { status: "published" });
-        // Refs stay ids on the content API; media resolves (one asset round for
-        // the whole list), because a list page's cards need their image URLs.
-        const fetchAssets = assetFetcher();
-        if (fetchAssets)
-            await resolveMediaSets(Object.values(fieldsById).map((values) => ({ values, descriptors: schema.fields })), fetchAssets, elements);
-        return entryItems(schema, inLocale, all, locale, draft, fieldsById);
+        const all = schema.tree ? await entries.list(collection) : rows.map((r) => r.record);
+        // References and media resolve for the whole list in one pass (§2, §6).
+        const sets = rows.map((r) => ({ values: structuredClone(r.fields), descriptors: schema.fields }));
+        await resolveFieldSets(sets, { collections: options.collections, elements: options.elements, fetch: fetcher(draft, locale), paths: pathLookup(locale), assets: assetFetcher() });
+        const index = new Map(all.map((e) => [e.id, e]));
+        const byId = (x) => index.get(x);
+        return rows.map(({ record }, i) => {
+            const paths = entryPathRows([record], byId, schema.name);
+            const pathIn = (l) => {
+                const row = paths.find((r) => r.locale === l);
+                return row ? fullPath(anchors, row.anchor ?? "", row.path, l) : null;
+            };
+            const item = toEntryItem(record, sets[i].values, {
+                path: pathIn(locale),
+                locale,
+                locales: entryAlternates(record, locales, (l) => draft || record.locales[l]?.status === "published", pathIn),
+                ...(schema.seo ? { seo: entrySeo(sets[i].values, schema) } : {}),
+            });
+            return { record, item };
+        });
     }
+    const getEntries = async (collection, o = {}) => (await readEntries(collection, o)).map((r) => r.item);
     const api = {
         async getPagesTree(o) {
             const locale = localeOf(o);
@@ -273,28 +277,29 @@ export function createSmoodlySite(options) {
             if (!path)
                 return null;
             const hit = await site.resolve(locale, path, { draft: o?.draft ?? false });
-            return hit?.kind === "page" ? hit : null;
+            return hit?.kind === "page" ? toPageItem(hit) : null;
         },
         getEntries,
         async getEntry(collection, idOrPath, o) {
             schemaOf(options.collections, collection); // an unknown collection is a wiring error on every branch
             const locale = localeOf(o);
+            const draft = o?.draft ?? false;
             if (idOrPath.startsWith("/")) {
-                const hit = await site.resolve(locale, idOrPath, { draft: o?.draft ?? false });
-                return hit?.kind === "entry" && hit.collection === collection ? { entry: hit.entry, path: hit.path, locale: hit.locale, locales: hit.locales } : null;
+                const hit = await site.resolve(locale, idOrPath, { draft });
+                return hit?.kind === "entry" && hit.collection === collection ? toEntryItem(hit.entry, hit.entry.fields, hit) : null;
             }
-            const items = await getEntries(collection, { locale, draft: o?.draft ?? false });
-            const byId = items.find((i) => i.entry.id === idOrPath);
+            const [byId] = await readEntries(collection, { locale, draft, ids: [idOrPath] });
             if (byId)
-                return byId;
+                return byId.item;
             // A bare slug names a ROOT entry only (sibling-scoped slugs, spec §4):
             // match the localized slug directly (paths.ts owns slug derivation),
             // regardless of whether the collection even has a `path`.
-            return items.find((i) => i.entry.parentId === null && entrySegment(i.entry, locale) === idOrPath) ?? null;
+            const all = await readEntries(collection, { locale, draft });
+            return all.find((r) => r.record.parentId === null && entrySegment(r.record, locale) === idOrPath)?.item ?? null;
         },
         async getEntriesTree(collection, o) {
-            const items = await getEntries(collection, { locale: localeOf(o), draft: o?.draft ?? false });
-            const build = (parentId) => items.filter((i) => i.entry.parentId === parentId).map((i) => ({ ...i, children: build(i.entry.id) }));
+            const rows = await readEntries(collection, { locale: localeOf(o), draft: o?.draft ?? false });
+            const build = (parentId) => rows.filter((r) => r.record.parentId === parentId).map((r) => ({ ...r.item, children: build(r.record.id) }));
             return build(null);
         },
         async getGlobal(item, o) {
@@ -312,9 +317,9 @@ export function createSmoodlySite(options) {
                 : (await entries.getMany(item.name, [record.id], locale, { status: "published" }))[record.id];
             if (!raw)
                 return null;
-            const fields = await resolveFields(raw, item.fields, { collections: options.collections, elements: options.elements, fetch: fetcher(draft, locale), assets: assetFetcher() });
+            const fields = await resolveFields(raw, item.fields, { collections: options.collections, elements: options.elements, fetch: fetcher(draft, locale), paths: pathLookup(locale), assets: assetFetcher() });
             if (!item.section)
-                return fields;
+                return { locale, fields };
             const { [SETTINGS_KEY]: settings, [STYLES_KEY]: steps, [CSS_KEY]: css, ...rest } = fields;
             const fetch = assetFetcher();
             const own = settings !== null && typeof settings === "object" ? settings : {};
@@ -324,7 +329,8 @@ export function createSmoodlySite(options) {
             // the wrapper strips it and emits data-smd-node, so the canvas selects the item and the css reaches it.
             const stepsObject = steps !== null && typeof steps === "object" ? steps : {};
             return {
-                ...rest,
+                locale,
+                fields: rest,
                 settings: own,
                 styles: { ...stepsObject, [SMD_KEY]: { node: globalNodeId(item.name), css: typeof css === "string" ? css : undefined, values: styles } },
             };

package/dist/sql-space.d.ts

@@ -12,11 +12,12 @@ export declare function currentSpaceSQL(): string;
  *  reads go through the table's one SELECT policy. `table` is as SQL names
  *  it (`"pages"`, `storage.objects`). Drops the old `for all` policy first. */
 export declare function writePoliciesSQL(table: string, write: string, prefix: string): string;
-/** The content tables' and members' policies. A table with a public read
- *  has ONE select policy — its own space, not revoked, and a write key or
- *  the published condition — and split write policies. A table without
- *  one (refs, members) keeps its `for all` write policy, which is also its
- *  only select. */
+/** The content tables' and members' policies. Each content table has ONE
+ *  select policy — its own space, not revoked, and a write key (spec
+ *  2026-09-29 content API contract §8): no key but a write key reads
+ *  content; the publishable key serves sign-in and presence. Split write
+ *  policies beside it. `refs` and `members` keep their `for all` write
+ *  policy, which is also their only select. */
 export declare function contentPoliciesSQL(): string;
 export declare function spaceLayerSQL(): string;
 /** The media bucket and its object policies (spec 2026-09-08 media §3,