smoodly 0.0.45 → 0.0.47

package/dist/published.d.ts

@@ -0,0 +1,115 @@
+import type { EntryOrder } from "./collections.ts";
+import { type Where } from "./entry-store.ts";
+import type { SiteEntry, SitePage } from "./site.ts";
+/** A page's delivery row: a published page, or a folder present in the locale (document null, hasPage false). */
+export type PublishedPageRow = {
+    id: string;
+    locale: string;
+    parentId: string | null;
+    sort: number | null;
+    /** The served address; null when the tree hides the node (no path, or a code address wins). */
+    path: string | null;
+    title: string;
+    hasPage: boolean;
+    /** The page fields with defaults, raw (no asset resolution): what a tree item and a link show. */
+    linkFields: Record<string, unknown>;
+    document: SitePage | null;
+    tags: string[];
+    /** The document stamp that built the row (document-stamp.ts); the column name predates the name. */
+    model: string;
+    stale: boolean;
+    publishedAt: number;
+};
+/** An entry's or a global's delivery row. A global's `document` is the value `getGlobal` returns; its collection is the item's name. */
+export type PublishedEntryRow = {
+    id: string;
+    locale: string;
+    collection: string;
+    parentId: string | null;
+    sort: number | null;
+    slug: string | null;
+    path: string | null;
+    createdAt: number;
+    updatedAt: number;
+    /** The published snapshot, raw, slug included: what `where` and `order` read. */
+    fields: Record<string, unknown>;
+    document: SiteEntry | unknown;
+    tags: string[];
+    /** The document stamp that built the row (document-stamp.ts); the column name predates the name. */
+    model: string;
+    stale: boolean;
+    publishedAt: number;
+};
+/** `globals`: present when the lookup asked for global items by name — the locale's rows of those collections,
+ *  as `entries` returns them (document, model, stale; the raw fields may be empty), so a page is one call. */
+export type PublishedRoute = ({
+    kind: "page";
+    row: PublishedPageRow;
+} | {
+    kind: "entry";
+    row: PublishedEntryRow;
+}) & {
+    globals?: PublishedEntryRow[];
+};
+/** `model` and `stale` ride along so a tree read can rebuild what is behind before answering (spec 2026-10-07 §4). */
+export type PublishedTreeRow = Pick<PublishedPageRow, "id" | "parentId" | "sort" | "path" | "title" | "hasPage" | "linkFields" | "model" | "stale">;
+export type PublishedQuery = {
+    locale: string;
+    where?: Where;
+    order?: EntryOrder;
+    limit?: number;
+    parent?: string | null;
+    ids?: string[];
+};
+export type PublishedKey = {
+    kind: "page" | "entry";
+    id: string;
+    locale?: string;
+};
+export interface PublishedStore {
+    /** Upsert by (id, locale). */
+    putPages(rows: PublishedPageRow[]): Promise<void>;
+    putEntries(rows: PublishedEntryRow[]): Promise<void>;
+    /** Every locale of the id when `locale` is absent. */
+    remove(keys: PublishedKey[]): Promise<void>;
+    /** The one-call lookup: a reachable page or entry at the address, else null. With `globals` (collection names of
+     *  global items), the locale's rows of those collections come along on the route (schema v9), still one call. */
+    byAddress(locale: string, path: string, globals?: readonly string[]): Promise<PublishedRoute | null>;
+    page(id: string, locale: string): Promise<PublishedPageRow | null>;
+    entry(id: string, locale: string): Promise<PublishedEntryRow | null>;
+    /** Filtered, ordered and limited over `fields`, in the store (SQL or the memory matcher). */
+    entries(collection: string, q: PublishedQuery): Promise<PublishedEntryRow[]>;
+    /** The light columns of every row in the locale, with the model and stale flag, in tree order (sort asc nulls last, published, id). */
+    tree(locale: string): Promise<PublishedTreeRow[]>;
+    markStale(keys: PublishedKey[]): Promise<void>;
+    /** The document stamp this space recorded as current (DESIGN §3): what `rebuild` last wrote, or the first
+     *  writer's; null until then. Only a reader at this stamp rewrites rows. */
+    recordedModel(): Promise<string | null>;
+    /** Record `model` as the space's current stamp (upsert by space). */
+    recordModel(model: string): Promise<void>;
+    /** Rows of both tables, and how many of them carry a stamp other than `model`: what `migrate --check` and Content health show. */
+    countBehind(model: string): Promise<{
+        behind: number;
+        total: number;
+    }>;
+}
+export declare class MemoryPublishedStore implements PublishedStore {
+    private pages;
+    private entryRows;
+    private recorded;
+    recordedModel(): Promise<string | null>;
+    recordModel(model: string): Promise<void>;
+    countBehind(model: string): Promise<{
+        behind: number;
+        total: number;
+    }>;
+    putPages(rows: PublishedPageRow[]): Promise<void>;
+    putEntries(rows: PublishedEntryRow[]): Promise<void>;
+    remove(keys: PublishedKey[]): Promise<void>;
+    byAddress(locale: string, path: string, globals?: readonly string[]): Promise<PublishedRoute | null>;
+    page(id: string, locale: string): Promise<PublishedPageRow | null>;
+    entry(id: string, locale: string): Promise<PublishedEntryRow | null>;
+    entries(collection: string, q: PublishedQuery): Promise<PublishedEntryRow[]>;
+    tree(locale: string): Promise<PublishedTreeRow[]>;
+    markStale(keys: PublishedKey[]): Promise<void>;
+}

package/dist/published.js

@@ -0,0 +1,136 @@
+// The delivery model's store (spec 2026-10-07 delivery model §1, §5): the
+// finished documents Publish writes, one row per page, entry or global per
+// locale, read in one lookup. Derived from the editing tables and
+// rebuildable; the memory adapter is two maps with the matcher in code, the
+// Supabase one (supabase-published-store.ts) reads published_pages,
+// published_entries, the published_routes view and smoodly_list_published.
+import { matchesWhere } from "./entry-store.js";
+const keyOf = (id, locale) => `${id}:${locale}`;
+const asc = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/** smoodly_list_published's ORDER BY: manual by sort, else the built-in time or
+ *  the field, absent, null and empty last in both directions; ties by creation, then id. */
+function compareRows(order) {
+    return (a, b) => {
+        if (order === "manual") {
+            const d = (a.sort ?? Infinity) - (b.sort ?? Infinity);
+            if (d !== 0 && !Number.isNaN(d))
+                return d;
+        }
+        else if (order) {
+            const value = (r) => {
+                const v = order.by === "createdAt" ? r.createdAt : order.by === "updatedAt" ? r.updatedAt : r.fields[order.by];
+                return v === "" ? null : v;
+            };
+            const va = value(a), vb = value(b);
+            if (va == null && vb != null)
+                return 1;
+            if (vb == null && va != null)
+                return -1;
+            if (va != null && vb != null) {
+                const d = typeof va === "number" && typeof vb === "number" ? va - vb : String(va).localeCompare(String(vb));
+                if (d !== 0)
+                    return order.direction === "asc" ? d : -d;
+            }
+        }
+        return asc(a.createdAt, b.createdAt) || asc(a.id, b.id);
+    };
+}
+/** An address holds one row per table, as the SQL's unique (space, locale, path) index says: a row of another id
+ *  left at an incoming address (a stale row a capped rename did not reach) goes before the write. */
+function vacate(map, rows) {
+    const incoming = new Map(rows.filter((r) => r.path !== null).map((r) => [`${r.locale}\u0000${r.path}`, r.id]));
+    for (const [k, row] of map) {
+        const holder = row.path === null ? undefined : incoming.get(`${row.locale}\u0000${row.path}`);
+        if (holder !== undefined && holder !== row.id)
+            map.delete(k);
+    }
+}
+export class MemoryPublishedStore {
+    constructor() {
+        this.pages = new Map();
+        this.entryRows = new Map();
+        this.recorded = null;
+    }
+    async recordedModel() {
+        return this.recorded;
+    }
+    async recordModel(model) {
+        this.recorded = model;
+    }
+    async countBehind(model) {
+        const rows = [...this.pages.values(), ...this.entryRows.values()];
+        return { behind: rows.filter((r) => r.model !== model).length, total: rows.length };
+    }
+    async putPages(rows) {
+        vacate(this.pages, rows);
+        for (const row of rows)
+            this.pages.set(keyOf(row.id, row.locale), structuredClone(row));
+    }
+    async putEntries(rows) {
+        vacate(this.entryRows, rows);
+        for (const row of rows)
+            this.entryRows.set(keyOf(row.id, row.locale), structuredClone(row));
+    }
+    async remove(keys) {
+        for (const key of keys) {
+            const map = key.kind === "page" ? this.pages : this.entryRows;
+            for (const [k, row] of map)
+                if (row.id === key.id && (key.locale === undefined || row.locale === key.locale))
+                    map.delete(k);
+        }
+    }
+    async byAddress(locale, path, globals) {
+        const found = () => {
+            for (const row of this.pages.values()) {
+                if (row.locale === locale && row.path === path && row.hasPage)
+                    return { kind: "page", row: structuredClone(row) };
+            }
+            for (const row of this.entryRows.values()) {
+                if (row.locale === locale && row.path === path)
+                    return { kind: "entry", row: structuredClone(row) };
+            }
+            return null;
+        };
+        const route = found();
+        if (!route || !globals)
+            return route;
+        const wanted = new Set(globals);
+        route.globals = structuredClone([...this.entryRows.values()].filter((r) => r.locale === locale && wanted.has(r.collection)));
+        return route;
+    }
+    async page(id, locale) {
+        const row = this.pages.get(keyOf(id, locale));
+        return row ? structuredClone(row) : null;
+    }
+    async entry(id, locale) {
+        const row = this.entryRows.get(keyOf(id, locale));
+        return row ? structuredClone(row) : null;
+    }
+    async entries(collection, q) {
+        const wanted = q.ids ? new Set(q.ids) : null;
+        const rows = [...this.entryRows.values()].filter((r) => r.collection === collection &&
+            r.locale === q.locale &&
+            (q.parent === undefined || r.parentId === q.parent) &&
+            (!wanted || wanted.has(r.id)) &&
+            (!q.where || matchesWhere(r.fields, q.where)));
+        rows.sort(compareRows(q.order));
+        return structuredClone(typeof q.limit === "number" ? rows.slice(0, q.limit) : rows);
+    }
+    async tree(locale) {
+        return [...this.pages.values()]
+            .filter((r) => r.locale === locale)
+            .sort((a, b) => {
+            const d = (a.sort ?? Infinity) - (b.sort ?? Infinity);
+            return (d !== 0 && !Number.isNaN(d) ? d : 0) || asc(a.publishedAt, b.publishedAt) || asc(a.id, b.id);
+        })
+            .map(({ id, parentId, sort, path, title, hasPage, linkFields, model, stale }) => structuredClone({ id, parentId, sort, path, title, hasPage, linkFields, model, stale }));
+    }
+    async markStale(keys) {
+        for (const key of keys) {
+            const map = key.kind === "page" ? this.pages : this.entryRows;
+            for (const row of map.values())
+                if (row.id === key.id && (key.locale === undefined || row.locale === key.locale))
+                    row.stale = true;
+        }
+    }
+}

package/dist/react.d.ts

@@ -0,0 +1,61 @@
+import { element, section } from "./pairing.tsx";
+import { page } from "./render.tsx";
+import { entryPage } from "./entry-page.tsx";
+import { Section } from "./section-wrapper.tsx";
+export * from "./index.ts";
+export { element, entryPage, page, section, Section };
+export type { PairedComponent } from "./pairing.tsx";
+export { Zone, renderPage } from "./render.tsx";
+export type { PairedPage, PageViewProps, Registry } from "./render.tsx";
+export type { PairedEntryPage } from "./entry-page.tsx";
+export { RichText, defaultRichTextImage } from "./richtext-render.tsx";
+export type { RichTextProps, RichTextElement, RichTextImageProps } from "./richtext-render.tsx";
+export { defineViews } from "./views.ts";
+export type { Views, ViewsInput } from "./views.ts";
+export { createCustomSection } from "./custom/CustomSection.tsx";
+export type { CustomOptions, CustomSectionProps, CustomSectionComponent } from "./custom/CustomSection.tsx";
+/** The root's namespace plus the React pairing: `smoodly.section(schema, View)`, `<smoodly.Section>`. */
+export declare const smoodly: {
+    section: typeof section;
+    element: typeof element;
+    page: typeof page;
+    entryPage: typeof entryPage;
+    Section: typeof Section;
+    schema: {
+        page: typeof import("./page.ts").pageSchema;
+        section<F extends import("./schema.ts").BuilderMap = {}, S extends import("./schema.ts").BuilderMap = {}>(input: {
+            name: string;
+            title: string;
+            icon?: string;
+            description?: string;
+            fields?: F | undefined;
+            settings?: S | undefined;
+            meta?: never;
+            styles?: false | {
+                omit: string[];
+            };
+            css?: false;
+            sample?: Partial<import("./schema.ts").StoredValues<F> & import("./schema.ts").StoredValues<S>> | undefined;
+        }): import("./schema.ts").SectionSchema<F, S>;
+        element<F extends import("./schema.ts").BuilderMap = {}, S extends import("./schema.ts").BuilderMap = {}>(input: {
+            name: string;
+            title: string;
+            icon?: string;
+            description?: string;
+            fields?: F | undefined;
+            settings?: S | undefined;
+            meta?: never;
+            styles?: false | {
+                omit: string[];
+            };
+            css?: false;
+            sample?: Partial<import("./schema.ts").StoredValues<F> & import("./schema.ts").StoredValues<S>> | undefined;
+        } & {
+            contexts: ("richtext" | "column")[];
+        }): import("./schema.ts").ElementSchema<F, S>;
+    };
+    collection: typeof import("./collections.ts").collection;
+    toolset: typeof import("./toolset.ts").toolset;
+    global: typeof import("./global.ts").globalItem;
+    marks: typeof import("./marks.ts").marks;
+};

package/dist/react.js

@@ -0,0 +1,17 @@
+// smoodly/react: the React half of the package (spec 2026-10-02 astro cloud fit §8; plan 2026-10-06 astro
+// adapter 3, decision 1) — the pairing, the render layer and the view registry. A Next project's components
+// import from here; a `.schema.ts` file and the config import from "smoodly", which loads no React, so an
+// Astro project has none. Everything of the root is re-exported, so one import serves a component.
+import { smoodly as core } from "./index.js";
+import { element, section } from "./pairing.js";
+import { page } from "./render.js";
+import { entryPage } from "./entry-page.js";
+import { Section } from "./section-wrapper.js";
+export * from "./index.js";
+export { element, entryPage, page, section, Section };
+export { Zone, renderPage } from "./render.js";
+export { RichText, defaultRichTextImage } from "./richtext-render.js";
+export { defineViews } from "./views.js";
+export { createCustomSection } from "./custom/CustomSection.js";
+/** The root's namespace plus the React pairing: `smoodly.section(schema, View)`, `<smoodly.Section>`. */
+export const smoodly = { ...core, section, element, page, entryPage, Section };

package/dist/read-shapes.d.ts

@@ -1,7 +1,7 @@
 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 { PageLink } from "./page-context.ts";
 import type { ResolvedImage } from "./media.ts";
 import type { SitePage } from "./site.ts";
 import type { StyleProps } from "./styles.ts";

package/dist/reads.d.ts

@@ -0,0 +1,80 @@
+import type { CollectionSchema } from "./collections.ts";
+import type { GlobalSchema } from "./global.ts";
+import type { PathTarget } from "./paths.ts";
+import { type EntryItem, type PageItem } from "./read-shapes.ts";
+import type { Materialize } from "./schema.ts";
+import type { AddressWithGlobals, EntryQuery, PageTreeItem, SiteHit, SmoodlySite } from "./site.ts";
+/** One content read, as the framework's cache needs it. */
+export type ReadUnit<T> = {
+    /** What the published read holds: two calls with one key may share a cached `read(false)`. A draft read
+     *  has no key of its own — the draft and a stored version read under the same one — so it is never
+     *  cached by it. The site's model key rides in it. */
+    key: string[];
+    /** The tags the admin's operations expire it by (revalidate.ts). */
+    tags: string[];
+    /** Tags only the value knows (a read by address learns the id from the document it returns). An adapter
+     *  that tags a response after the read adds them; Next's cache needs its tags before the read and ignores this. */
+    tagsOf?(value: T): string[];
+    /** The read: the live draft, or the published value. */
+    read(draft: boolean): Promise<T>;
+};
+/** What a framework supplies. Every read of content passes through `run`, so an adapter that caches whole
+ *  responses hears the tags of everything a response rendered. A path lookup passes no unit: `locate`, a
+ *  redirect, and a path that leads nowhere (a null from `getPage` or `getEntry`, a 404) reach no `run`. */
+export type ReadAdapter = {
+    /** Resolves when there is a request to read for. Next: `connection()`, so a build prerenders nothing
+     *  against the database. Absent where a build may read (Astro's static mode). */
+    gate?(): Promise<void>;
+    /** Runs a unit: the adapter decides draft or published, where the value is cached, and who hears its tags. */
+    run<T>(unit: ReadUnit<T>): Promise<T>;
+};
+export type QueryOptions = {
+    locale?: string;
+};
+export type EntriesQuery = Omit<EntryQuery, "locale" | "draft" | "ids"> & QueryOptions;
+type ByName<T, N> = Extract<T, {
+    name: 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<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>;
+    getGlobal<N extends S[number]["name"]>(item: N, options?: QueryOptions): Promise<GlobalValue<S, N> | null>;
+};
+/** The route's read of a located target (locate is never a unit: the id it returns IS the tag). Keyed by
+ *  what the unit holds, not only where: an address that changes owner — a deploy handing it to a code
+ *  record, which fires no tag — can never serve the previous occupant (spec 2026-09-29 pre-install fixes
+ *  §5). `version` is History's stored version and counts inside draft mode only. */
+export declare function hitUnit(site: SmoodlySite, target: PathTarget, locale: string, path: string, version?: string): ReadUnit<SiteHit | null>;
+/** Astro's route read of an address: one lookup outside draft mode — the tags come with the document, so no
+ *  locate comes first; in draft mode, locate then load as the editing tables need (spec 2026-10-07 delivery
+ *  model §3). A redirect row answers as a redirect; a code-owned page answers where no record lives. */
+export declare function addressUnit(site: SmoodlySite, locale: string, path: string, version?: string): ReadUnit<SiteHit | {
+    kind: "redirect";
+    target: PathTarget;
+} | null>;
+/** Astro's route read with the layout's global items riding along (schema v9): the published read is one
+ *  `lookupWithGlobals`, and the shell seeds each value into the request scope under `globalUnit`'s key, so the
+ *  layout's loaders cost no call. The tags are the hit's; a global's tag joins when the layout reads it. A draft
+ *  read brings no globals: a preview reads live. */
+export declare function addressWithGlobalsUnit(site: SmoodlySite, locale: string, path: string, items: readonly GlobalSchema<any>[], version?: string): ReadUnit<AddressWithGlobals>;
+/** A global item's unit, by schema: the one `q.getGlobal` runs for the same item and locale. */
+export declare function globalUnit<V>(site: SmoodlySite, item: GlobalSchema<V>, locale: string): ReadUnit<V | null>;
+/** The typed queries over a site, run by the framework's adapter. */
+export declare function createQueries<const C extends readonly CollectionSchema<any, string>[], const S extends readonly GlobalSchema<any, string>[] = []>(options: {
+    site: SmoodlySite;
+    collections: C;
+    globals?: S;
+}, adapter: ReadAdapter): SmoodlyQueries<C, S>;
+export {};

package/dist/reads.js

@@ -0,0 +1,142 @@
+import { referencedCollections } from "./read-shapes.js";
+import { collectionTag, entryTag, globalTag, pageTag, pagesTreeTag } from "./revalidate.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))
+        return value.map(stable);
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : 1))
+            .map(([k, v]) => [k, stable(v)]));
+    }
+    return value;
+}
+/** A stable key for an entries query: only what was given, normalized. */
+function entriesKey(o) {
+    const { locale: _locale, ...rest } = o;
+    return JSON.stringify(stable(rest));
+}
+/** The route's read of a located target (locate is never a unit: the id it returns IS the tag). Keyed by
+ *  what the unit holds, not only where: an address that changes owner — a deploy handing it to a code
+ *  record, which fires no tag — can never serve the previous occupant (spec 2026-09-29 pre-install fixes
+ *  §5). `version` is History's stored version and counts inside draft mode only. */
+export function hitUnit(site, target, locale, path, version) {
+    return {
+        key: ["smoodly-site", site.cacheKey, locale, path, target.kind, target.id],
+        tags: [target.kind === "page" ? pageTag(target.id) : entryTag(target.id)],
+        read: (draft) => draft ? site.load(target, locale, path, { draft: true, ...(version !== undefined ? { version } : {}) }) : site.load(target, locale, path),
+    };
+}
+/** Astro's route read of an address: one lookup outside draft mode — the tags come with the document, so no
+ *  locate comes first; in draft mode, locate then load as the editing tables need (spec 2026-10-07 delivery
+ *  model §3). A redirect row answers as a redirect; a code-owned page answers where no record lives. */
+export function addressUnit(site, locale, path, version) {
+    return {
+        key: ["smoodly-site", site.cacheKey, locale, path],
+        tags: [],
+        tagsOf: tagsOfHit,
+        read: (draft) => (draft ? draftAddress(site, locale, path, version) : site.lookup(locale, path)),
+    };
+}
+/** The tags an address's value brings: the page's or the entry's; none for a miss, a redirect or a code-owned page. */
+function tagsOfHit(value) {
+    if (!value || value.kind === "redirect")
+        return [];
+    if (value.kind === "entry")
+        return [entryTag(value.entry.id)];
+    // A code-owned page has no row to expire it by.
+    return value.record.id.startsWith("code:") ? [] : [pageTag(value.record.id)];
+}
+/** The draft read of an address: locate, then load the draft, as the editing tables need. */
+async function draftAddress(site, locale, path, version) {
+    const target = await site.locate(locale, path);
+    if (!target)
+        return site.codePage(locale, path);
+    if (target.redirect)
+        return { kind: "redirect", target: { kind: target.kind, id: target.id } };
+    return site.load(target, locale, path, { draft: true, ...(version !== undefined ? { version } : {}) });
+}
+/** Astro's route read with the layout's global items riding along (schema v9): the published read is one
+ *  `lookupWithGlobals`, and the shell seeds each value into the request scope under `globalUnit`'s key, so the
+ *  layout's loaders cost no call. The tags are the hit's; a global's tag joins when the layout reads it. A draft
+ *  read brings no globals: a preview reads live. */
+export function addressWithGlobalsUnit(site, locale, path, items, version) {
+    return {
+        key: ["smoodly-site", site.cacheKey, locale, path, "+globals"],
+        tags: [],
+        tagsOf: (value) => tagsOfHit(value.hit),
+        read: async (draft) => (draft ? { hit: await draftAddress(site, locale, path, version), globals: new Map() } : site.lookupWithGlobals(locale, path, items)),
+    };
+}
+/** A global item's unit, by schema: the one `q.getGlobal` runs for the same item and locale. */
+export function globalUnit(site, item, locale) {
+    return {
+        key: ["smoodly-q", site.cacheKey, "global", item.name, locale],
+        tags: [globalTag(item.name)],
+        read: (draft) => site.getGlobal(item, { locale, draft }),
+    };
+}
+/** The typed queries over a site, run by the framework's adapter. */
+export function createQueries(options, adapter) {
+    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;
+    const gate = async () => { await adapter.gate?.(); };
+    const unit = (key, tags, read) => ({ key: ["smoodly-q", site.cacheKey, ...key], tags, read });
+    /** The tag needs the id: a path is located first, outside any unit, as the route does. */
+    async function idOf(kind, locale, pathOrId) {
+        if (!pathOrId.startsWith("/"))
+            return pathOrId;
+        const target = await site.locate(locale, pathOrId);
+        return target?.kind === kind ? target.id : null;
+    }
+    return {
+        async getPageTree(o) {
+            await gate();
+            const locale = localeOf(o);
+            return adapter.run(unit(["pageTree", locale], [pagesTreeTag()], (draft) => site.getPagesTree({ locale, draft })));
+        },
+        async getPage(pathOrId, o) {
+            await gate();
+            const locale = localeOf(o);
+            const id = await idOf("page", locale, pathOrId);
+            if (!id)
+                return null;
+            return adapter.run(unit(["page", locale, pathOrId], [pageTag(id)], (draft) => site.getPage(pathOrId, { locale, draft })));
+        },
+        async getEntries(collection, o = {}) {
+            await gate();
+            const locale = localeOf(o);
+            const { locale: _locale, ...query } = o;
+            // 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 adapter.run(unit(["entries", collection, locale, entriesKey(o)], [...new Set(tags)].map(collectionTag), (draft) => site.getEntries(collection, { ...query, locale, draft })));
+        },
+        async getEntry(collection, idOrPath, o) {
+            await gate();
+            const locale = localeOf(o);
+            const id = await idOf("entry", locale, idOrPath);
+            if (!id)
+                return null;
+            return adapter.run(unit(["entry", collection, locale, idOrPath], [entryTag(id)], async (draft) => {
+                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.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;
+            }));
+        },
+        async getGlobal(name, o) {
+            const item = globalByName.get(name);
+            if (!item)
+                throw new Error(`smoodly: no global item named "${name}".`);
+            await gate();
+            return adapter.run(globalUnit(site, item, localeOf(o)));
+        },
+    };
+}

package/dist/refs.d.ts

@@ -1,6 +1,6 @@
 import type { Descriptor } from "./fields.ts";
 import type { CollectionSchema } from "./collections.ts";
-import type { PageTree } from "./render.tsx";
+import type { PageTree } from "./page-context.ts";
 export type RefEdge = {
     field: string;
     targetCollection: string;

package/dist/registration.d.ts

@@ -0,0 +1,8 @@
+export type SchemaOr<S> = S | {
+    schema: S;
+};
+export declare function schemaOf<S extends object>(x: SchemaOr<S>): S;
+/** The schema a public builder was given, refusing a paired component (plan 2026-10-02 registration split). */
+export declare function schemaOnly<S extends {
+    name: string;
+}>(x: S): S;

package/dist/registration.js

@@ -0,0 +1,17 @@
+export function schemaOf(x) {
+    const carried = x.schema;
+    return carried !== null && typeof carried === "object" ? carried : x;
+}
+/** The schema a public builder was given, refusing a paired component (plan 2026-10-02 registration split). */
+export function schemaOnly(x) {
+    const carried = x.schema;
+    if (carried !== null && typeof carried === "object") {
+        if (carried.kind === "entryPage") {
+            const c = String(carried.collection);
+            throw new Error(`smoodly: an entry page is a view — list smoodly.entryPage(${c}, View) in defineViews({ pages }), not in registry.pages.`);
+        }
+        const name = String(carried.name);
+        throw new Error(`smoodly: pass the schema, not the component — "${name}" is registered by its schema (${name}Schema), and its component goes to defineViews.`);
+    }
+    return x;
+}