smoodly 0.0.35 → 0.0.37

package/dist/fields.d.ts

@@ -24,6 +24,14 @@ export declare function normalizeOptions<V extends string>(options: readonly Opt
 export declare function optionsOf(options: unknown): Option[];
 /** The values a stored choice may take. */
 export declare const optionValues: (options: unknown) => string[];
+/** A ref field's value at the type level: the target and how deep the ref site resolves it.
+ *  Never a runtime value — `Values<M>` turns it into what a read returns. */
+export type RefMode = "shallow" | "full" | (string & {});
+export type RefTo<T, M extends RefMode = "shallow"> = {
+    readonly __refTo: T;
+    readonly __mode: M;
+};
+type Rebase<V, M extends RefMode> = V extends RefTo<infer T, any> ? RefTo<T, M> : V extends RefTo<infer T, any>[] ? RefTo<T, M>[] : V;
 export type FieldBuilder<Value = unknown, Flags extends BuilderFlags = {}> = {
     readonly descriptor: Descriptor;
     optional(): FieldBuilder<Value, Flags & {
@@ -43,7 +51,9 @@ export type FieldBuilder<Value = unknown, Flags extends BuilderFlags = {}> = {
      *   the named refs, one level; object values nest deeper
      * - no call — hydrate the entry itself; its refs stay ids
      */
-    resolve(...projection: (string | Record<string, unknown>)[]): FieldBuilder<Value, Flags>;
+    resolve(): FieldBuilder<Rebase<Value, "full">, Flags>;
+    resolve<const K extends string>(...keys: K[]): FieldBuilder<Rebase<Value, K>, Flags>;
+    resolve<const P extends Record<string, unknown>>(projection: P): FieldBuilder<Rebase<Value, keyof P & string>, Flags>;
     /** Hide the field while the condition holds (spec 2026-09-14 §12): it leaves the form and validation skips it; the stored value is kept. */
     hidden(condition: Condition): FieldBuilder<Value, Flags>;
     /** phantom, type-level only */
@@ -105,14 +115,10 @@ export declare const f: {
      *  300px sidebar cannot show one legibly (spec 2026-09-07, list field §1).
      *  `.min`/`.max` count items. */
     list: <B extends FieldBuilder<any, any>>(item: B & NotLocalized<B>) => FieldBuilder<ValueOf<B>[], {}>;
-    ref: <T>(target: () => T) => FieldBuilder<Resolved<T>, {}>;
-    refList: <T>(target: () => T) => FieldBuilder<Resolved<T>[], {}>;
+    ref: <T>(target: () => T) => FieldBuilder<RefTo<T, "shallow">, {}>;
+    refList: <T>(target: () => T) => FieldBuilder<RefTo<T, "shallow">[], {}>;
 };
 export type ValueOf<B> = B extends FieldBuilder<infer V, infer Flags> ? Flags extends {
     optional: true;
 } ? V | undefined : V : never;
-/** Resolved entry for a ref target — refined when collections land. */
-export type Resolved<T> = T extends {
-    __entry?: infer E;
-} ? E : Record<string, unknown>;
 export {};

package/dist/fields.js

@@ -37,13 +37,13 @@ function builder(descriptor) {
         max: (n) => chain({ max: n }),
         min: (n) => chain({ min: n }),
         default: (v) => chain({ default: v }),
-        resolve: (...projection) => {
+        resolve: ((...projection) => {
             if (projection.length === 0)
                 return chain({ resolve: "full" });
             if (typeof projection[0] === "object")
                 return chain({ resolve: projection[0] });
             return chain({ resolve: Object.fromEntries(projection.map((k) => [k, true])) });
-        },
+        }),
         hidden: (condition) => chain({ hidden: condition }),
     };
 }

package/dist/global.d.ts

@@ -1,8 +1,8 @@
 import type { CollectionSchema } from "./collections.ts";
 import type { Descriptor } from "./fields.ts";
 import type { PairedComponent } from "./pairing.tsx";
-import type { BuilderMap, NamespaceValues, SectionSchema } from "./schema.ts";
-import type { StyleProps } from "./styles.ts";
+import type { BuilderMap, SectionSchema, Values } from "./schema.ts";
+import type { GlobalItem, VisualGlobalItem } from "./read-shapes.ts";
 /** The reserved tree node type of a placement. */
 export declare const GLOBAL_NODE_TYPE = "global";
 /** The reserved keys a visual item's settings, styles steps and css live under in its row (spec 2026-09-14 §8). */
@@ -46,12 +46,9 @@ type GlobalInput<N extends string = string> = {
 export declare function globalItem<F extends BuilderMap, const N extends string = string>(input: GlobalInput<N> & {
     fields: F;
     section?: undefined;
-}): GlobalSchema<NamespaceValues<F>, N>;
+}): GlobalSchema<GlobalItem<Values<F>>, N>;
 export declare function globalItem<F extends BuilderMap, St extends BuilderMap, const N extends string = string>(input: GlobalInput<N> & {
     section: PairedComponent<SectionSchema<F, St>, F, St>;
     fields?: undefined;
-}): GlobalSchema<NamespaceValues<F> & {
-    settings: NamespaceValues<St>;
-    styles: StyleProps;
-}, N>;
+}): GlobalSchema<VisualGlobalItem<Values<F>, Values<St>>, N>;
 export {};

package/dist/index.d.ts

@@ -51,7 +51,7 @@ export type { PathIndex } from "./path-index.ts";
 export { MemoryEntryStore } from "./entry-store.ts";
 export { SupabaseEntryStore } from "./supabase-entry-store.ts";
 export { SupabasePathIndex } from "./supabase-path-index.ts";
-export type { EntryStore, EntryRecord, EntryLocale, EntryVersion, EntryScan, EntryUsage, ListOptions, CreateEntryOptions, AddEntryLocaleOptions, EntryStoreOptions, Where, WhereValue, } from "./entry-store.ts";
+export type { EntryStore, EntryRecord, EntryLocale, EntryVersion, EntryScan, EntryUsage, ListOptions, CreateEntryOptions, AddEntryLocaleOptions, EntryStoreOptions, Where, WhereValue, SnapshotQuery, SnapshotRow, } from "./entry-store.ts";
 export { entryErrors, compareEntries, DEFAULT_ENTRY_LOCALES, localizedKeys, splitFields, entryLocaleRow, entryFieldsIn, entryRefEdges, entryTitleIn, matchesWhere, } from "./entry-store.ts";
 export { affectedTargets, pageTag, entryTag, globalTag, pagesTreeTag, collectionTag } from "./revalidate.ts";
 export type { AffectedTargets } from "./revalidate.ts";
@@ -66,7 +66,10 @@ export type { PageStore, PageRecord, PageLocale, PageVersion, PageScan, PageStor
 export { pathOptions, pageErrors, localeRow, pageRefEdges, DEFAULT_LOCALES } from "./store.ts";
 export type { SmoodlyConfig, ResolvedConfig } from "./config.ts";
 export type { FieldBuilder, Descriptor, ValueOf, Option, OptionInput, OptionValue } from "./fields.ts";
-export type { SectionSchema, ElementSchema, BuilderMap } from "./schema.ts";
+export type { SectionSchema, ElementSchema, BuilderMap, Values } from "./schema.ts";
+export type { CollectionSeo } from "./seo.ts";
+export type { EntryRef, EntryItem, PageItem, GlobalItem, VisualGlobalItem, Seo } from "./read-shapes.ts";
+export type { RefTo } from "./fields.ts";
 export type { Props, PairedComponent } from "./pairing.tsx";
 export type { CollectionSchema, EntryOrder } from "./collections.ts";
 export { DEFAULT_TOOLSET, type Toolset, type ToolsetMark, type ToolsetNode } from "./toolset.ts";
@@ -94,23 +97,7 @@ export declare const smoodly: {
                 omit: string[];
             };
             css?: false;
-            sample?: Partial<{ [K_1 in Exclude<keyof F, { [K in keyof F]: F[K] extends {
-                __flags?: infer Fl;
-            } ? Fl extends {
-                optional: true;
-            } ? K : never : never; }[keyof F]>]: import("./fields.ts").ValueOf<F[K_1]>; } & { [K_2 in { [K in keyof F]: F[K] extends {
-                __flags?: infer Fl;
-            } ? Fl extends {
-                optional: true;
-            } ? K : never : never; }[keyof F]]?: import("./fields.ts").ValueOf<F[K_2]> | undefined; } & { [K_4 in Exclude<keyof S, { [K_3 in keyof S]: S[K_3] extends {
-                __flags?: infer Fl;
-            } ? Fl extends {
-                optional: true;
-            } ? K_3 : never : never; }[keyof S]>]: import("./fields.ts").ValueOf<S[K_4]>; } & { [K_5 in { [K_3 in keyof S]: S[K_3] extends {
-                __flags?: infer Fl;
-            } ? Fl extends {
-                optional: true;
-            } ? K_3 : never : never; }[keyof S]]?: import("./fields.ts").ValueOf<S[K_5]> | undefined; }> | undefined;
+            sample?: Partial<{ [K in keyof import("./schema.ts").NamespaceValues<F>]: import("./schema.ts").NamespaceValues<F>[K] extends import("./fields.ts").RefTo<any, any> ? string : import("./schema.ts").NamespaceValues<F>[K] extends import("./fields.ts").RefTo<any, any>[] ? string[] : import("./schema.ts").NamespaceValues<F>[K]; } & { [K_1 in keyof import("./schema.ts").NamespaceValues<S>]: import("./schema.ts").NamespaceValues<S>[K_1] extends import("./fields.ts").RefTo<any, any> ? string : import("./schema.ts").NamespaceValues<S>[K_1] extends import("./fields.ts").RefTo<any, any>[] ? string[] : import("./schema.ts").NamespaceValues<S>[K_1]; }> | undefined;
         }): import("./schema.ts").SectionSchema<F, S>;
         element<F extends import("./schema.ts").BuilderMap = {}, S extends import("./schema.ts").BuilderMap = {}>(input: {
             name: string;
@@ -124,23 +111,7 @@ export declare const smoodly: {
                 omit: string[];
             };
             css?: false;
-            sample?: Partial<{ [K_1 in Exclude<keyof F, { [K in keyof F]: F[K] extends {
-                __flags?: infer Fl;
-            } ? Fl extends {
-                optional: true;
-            } ? K : never : never; }[keyof F]>]: import("./fields.ts").ValueOf<F[K_1]>; } & { [K_2 in { [K in keyof F]: F[K] extends {
-                __flags?: infer Fl;
-            } ? Fl extends {
-                optional: true;
-            } ? K : never : never; }[keyof F]]?: import("./fields.ts").ValueOf<F[K_2]> | undefined; } & { [K_4 in Exclude<keyof S, { [K_3 in keyof S]: S[K_3] extends {
-                __flags?: infer Fl;
-            } ? Fl extends {
-                optional: true;
-            } ? K_3 : never : never; }[keyof S]>]: import("./fields.ts").ValueOf<S[K_4]>; } & { [K_5 in { [K_3 in keyof S]: S[K_3] extends {
-                __flags?: infer Fl;
-            } ? Fl extends {
-                optional: true;
-            } ? K_3 : never : never; }[keyof S]]?: import("./fields.ts").ValueOf<S[K_5]> | undefined; }> | undefined;
+            sample?: Partial<{ [K in keyof import("./schema.ts").NamespaceValues<F>]: import("./schema.ts").NamespaceValues<F>[K] extends import("./fields.ts").RefTo<any, any> ? string : import("./schema.ts").NamespaceValues<F>[K] extends import("./fields.ts").RefTo<any, any>[] ? string[] : import("./schema.ts").NamespaceValues<F>[K]; } & { [K_1 in keyof import("./schema.ts").NamespaceValues<S>]: import("./schema.ts").NamespaceValues<S>[K_1] extends import("./fields.ts").RefTo<any, any> ? string : import("./schema.ts").NamespaceValues<S>[K_1] extends import("./fields.ts").RefTo<any, any>[] ? string[] : import("./schema.ts").NamespaceValues<S>[K_1]; }> | undefined;
         } & {
             contexts: ("richtext" | "column")[];
         }): import("./schema.ts").ElementSchema<F, S>;
@@ -157,8 +128,8 @@ export declare const smoodly: {
 };
 export { NODE_ATTR, ZONE_ATTR, EMPTY_ATTR, BLANK_ATTR, FIELD_ATTR, ITEM_ATTR, EDITOR_ATTR, resolveMarkPath } from "./marks.ts";
 export type { MarkNode, MarkPath, Marks, Scope } from "./marks.ts";
-export { resolveSmoodlyEnv, smoodlyEnv, publicContentConfig } from "./env.ts";
-export type { SmoodlyEnv, ContentConfig } from "./env.ts";
+export { resolveSmoodlyEnv, smoodlyEnv, presenceConfig } from "./env.ts";
+export type { SmoodlyEnv, PresenceConfig } from "./env.ts";
 export { clientOptions, createSmoodlyClient } from "./client.ts";
 export { createSmoodlySite, pageContextOf } from "./site.ts";
-export type { SiteOptions, SitePage, SitePageSchema, SiteEntry, SiteHit, SmoodlySite, LoadOptions, PageTreeItem, SiteEntryItem, EntryTreeItem, EntryQuery, } from "./site.ts";
+export type { SiteOptions, SitePageSchema, SmoodlySite, LoadOptions, PageTreeItem, EntryTreeItem, EntryQuery, } from "./site.ts";

package/dist/index.js

@@ -66,6 +66,6 @@ export const smoodly = {
     marks,
 };
 export { NODE_ATTR, ZONE_ATTR, EMPTY_ATTR, BLANK_ATTR, FIELD_ATTR, ITEM_ATTR, EDITOR_ATTR, resolveMarkPath } from "./marks.js";
-export { resolveSmoodlyEnv, smoodlyEnv, publicContentConfig } from "./env.js";
+export { resolveSmoodlyEnv, smoodlyEnv, presenceConfig } from "./env.js";
 export { clientOptions, createSmoodlyClient } from "./client.js";
 export { createSmoodlySite, pageContextOf } from "./site.js";

package/dist/migrations.js

@@ -43,7 +43,7 @@ export function viewsFile(collections, existing, at) {
     const changed = collections.filter((c) => existing.get(c.name) !== collectionHash(c.sql));
     if (changed.length === 0)
         return null;
-    const text = "-- Smoodly: read views and order indexes for this app's collections, written by `npx smoodly migrate`\n" +
+    const text = "-- Smoodly: read views for this app's collections, written by `npx smoodly migrate`\n" +
         `-- (${at.toISOString()}). One block per collection; the marker's hash is the block's SQL, compared on the next run.\n` +
         "-- Never edit a written file: change the collection and run migrate again.\n\n" +
         changed.map((c) => `${collectionMarker(c)}\n${c.sql.trim()}`).join("\n\n") +

package/dist/next/index.d.ts

@@ -1,6 +1,6 @@
 export { createPageRenderer } from "./page-renderer.tsx";
 export type { PageRendererOptions, PathRenderOptions, PageRegistration } from "./page-renderer.tsx";
-export { metadataFrom } from "./meta.ts";
+export { metadataFrom, metadataFromSeo } from "./meta.ts";
 export { createSmoodlyQueries } from "./queries.ts";
 export type { SmoodlyQueries, QueryOptions, EntriesQuery, TypedEntryItem, GlobalValue } from "./queries.ts";
 export { previewRoute } from "./preview-route.ts";

package/dist/next/index.js

@@ -1,5 +1,5 @@
 export { createPageRenderer } from "./page-renderer.js";
-export { metadataFrom } from "./meta.js";
+export { metadataFrom, metadataFromSeo } from "./meta.js";
 export { createSmoodlyQueries } from "./queries.js";
 export { previewRoute } from "./preview-route.js";
 export { previewPill } from "./preview-pill.js";

package/dist/next/meta.d.ts

@@ -1,8 +1,10 @@
 import type { Metadata } from "next";
-/** Maps the page tree's meta onto Next metadata (spec 2026-09-10 page
- * fields §4). The SEO title falls back to the page's own title so every
- * page carries one; absent meta and no title returns {} so the app's
- * layout.tsx defaults apply untouched. */
+import type { Seo } from "../read-shapes.ts";
+/** Maps the effective SEO values onto Next metadata (spec 2026-09-10 page
+ * fields §4, 2026-09-29 content API contract §7). Absent values leave the
+ * app's layout defaults untouched: no seo at all returns {}. */
+export declare function metadataFromSeo(seo: Seo | undefined): Metadata;
+/** A page tree's stored meta as Next metadata; the SEO title falls back to the page's own title. */
 export declare function metadataFrom(meta: unknown, page?: {
     title?: string;
 }): Metadata;

package/dist/next/meta.js

@@ -1,15 +1,10 @@
 import { imageUrl } from "../image/loaders.js";
-const isResolvedImage = (v) => typeof v === "object" && v !== null && typeof v.url === "string";
-/** Maps the page tree's meta onto Next metadata (spec 2026-09-10 page
- * fields §4). The SEO title falls back to the page's own title so every
- * page carries one; absent meta and no title returns {} so the app's
- * layout.tsx defaults apply untouched. */
-export function metadataFrom(meta, page) {
-    const m = typeof meta === "object" && meta !== null && !Array.isArray(meta) ? meta : {};
-    const str = (key) => (typeof m[key] === "string" && m[key] ? m[key] : undefined);
-    const title = str("title") ?? (page?.title ? page.title : undefined);
-    const description = str("description");
-    const ogImage = m.ogImage;
+import { pageSeo } from "../seo.js";
+/** Maps the effective SEO values onto Next metadata (spec 2026-09-10 page
+ * fields §4, 2026-09-29 content API contract §7). Absent values leave the
+ * app's layout defaults untouched: no seo at all returns {}. */
+export function metadataFromSeo(seo) {
+    const { title, description, image, noindex } = seo ?? {};
     const out = {};
     if (title)
         out.title = title;
@@ -20,16 +15,18 @@ export function metadataFrom(meta, page) {
         og.title = title;
     if (description)
         og.description = description;
-    if (isResolvedImage(ogImage)) {
+    if (image) {
         // The delivery seam decides the URL; the cloud's transform loader (OQ 28) can serve a real 1200-wide render.
-        og.images = [{ url: imageUrl(ogImage, { width: 1200 }), width: ogImage.width, height: ogImage.height, ...(ogImage.alt ? { alt: ogImage.alt } : {}) }];
-    }
-    else if (typeof ogImage === "string" && ogImage) {
-        og.images = [ogImage];
+        og.images = [{ url: imageUrl(image, { width: 1200 }), width: image.width, height: image.height, ...(image.alt ? { alt: image.alt } : {}) }];
     }
     if (Object.keys(og).length > 0)
         out.openGraph = og;
-    if (m.noindex === true)
+    if (noindex === true)
         out.robots = { index: false, follow: false };
     return out;
 }
+/** A page tree's stored meta as Next metadata; the SEO title falls back to the page's own title. */
+export function metadataFrom(meta, page) {
+    const m = typeof meta === "object" && meta !== null && !Array.isArray(meta) ? meta : {};
+    return metadataFromSeo(pageSeo(m, page?.title ?? ""));
+}

package/dist/next/page-renderer.js

@@ -16,8 +16,9 @@ import { fixedPathFor } from "../localize.js";
 import { decodeSegment, joinPath } from "../paths.js";
 import { renderPage } from "../render.js";
 import { entryTag, pageTag, globalTag } from "../revalidate.js";
+import { toEntryItem } from "../read-shapes.js";
 import { pageContextOf } from "../site.js";
-import { metadataFrom } from "./meta.js";
+import { metadataFromSeo } from "./meta.js";
 import { previewPill } from "./preview-pill.js";
 /** Logged once per renderer when Next's cacheComponents is on (spec 2026-09-27 cache components §2). */
 export const CACHE_COMPONENTS_WARNING = "smoodly: Next's cacheComponents is on, and Smoodly does not support it — a missing page answers 200 with noindex instead of 404, and a redirect answers 200 instead of 308. Turn cacheComponents off in next.config.ts; the Next.js guide's \"Cache Components\" section says why (https://smoodly.io/docs/frameworks/nextjs).";
@@ -73,7 +74,7 @@ export function createPageRenderer(options) {
             console.warn(`smoodly: no entry page for collection "${hit.collection}" — the entry at ${hit.path} is a 404.`);
             notFound();
         }
-        return _jsx(View, { entry: hit.entry, path: hit.path, locale: hit.locale, locales: hit.locales });
+        return _jsx(View, { entry: toEntryItem(hit.entry, hit.entry.fields, hit) });
     }
     /** hreflang from the SAME map a language switch reads (spec 2026-09-15 §3): the locales with a URL, through href. */
     function alternates(hit) {
@@ -133,7 +134,9 @@ export function createPageRenderer(options) {
         const hit = await load(target, locale, path, draft);
         if (!hit || !accept(hit))
             return {};
-        return { ...(hit.kind === "page" ? metadataFrom(hit.tree.meta, { title: hit.title }) : {}), ...alternates(hit) };
+        // A page type without seo: true still gets its page title as <title>; seo: true adds the panel's values on top.
+        const seo = hit.seo ?? (hit.kind === "page" ? { title: hit.title } : undefined);
+        return { ...metadataFromSeo(seo), ...alternates(hit) };
     }
     const any = () => true;
     /** The escape hatch may only render ITS OWN registration's record. */

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];
+}