smoodly 0.0.13 → 0.0.15

package/dist/next/queries.js

@@ -0,0 +1,87 @@
+// The in-app read API (spec 2026-09-11): five typed queries over the
+// framework-free site layer, each draft-aware inside the editor preview
+// and cached under a tag outside it — the pattern getSmoodlyShared set.
+// Lives in next/ because draftMode and unstable_cache are Next's; an
+// Astro glue wraps the same site reads over its own cache seam.
+import { unstable_cache } from "next/cache";
+import { draftMode } from "next/headers";
+import { connection } from "next/server";
+import { collectionTag, entryTag, pageTag, pagesTreeTag, sharedTag } 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));
+}
+export function createSmoodlyQueries(options) {
+    const { site } = options;
+    const sharedByName = new Map((options.shared ?? []).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`. */
+    async function run(key, tags, read) {
+        await connection();
+        const { isEnabled: draft } = await draftMode();
+        if (draft)
+            return read(true);
+        return unstable_cache(() => read(false), ["smoodly-q", ...key], { tags })();
+    }
+    /** The tag needs the id: a path is located first, uncached, as the renderer does. */
+    async function idOf(kind, locale, pathOrId) {
+        if (!pathOrId.startsWith("/"))
+            return pathOrId;
+        await connection();
+        const target = await site.locate(locale, pathOrId);
+        return target?.kind === kind ? target.id : null;
+    }
+    return {
+        getPageTree: (o) => {
+            const locale = localeOf(o);
+            return run(["pageTree", locale], [pagesTreeTag()], (draft) => site.getPagesTree({ locale, draft }));
+        },
+        async getPage(pathOrId, o) {
+            const locale = localeOf(o);
+            const id = await idOf("page", locale, pathOrId);
+            if (!id)
+                return null;
+            return run(["page", locale, pathOrId], [pageTag(id)], (draft) => site.getPage(pathOrId, { locale, draft }));
+        },
+        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 }));
+        },
+        async getEntry(collection, idOrPath, o) {
+            const locale = localeOf(o);
+            const id = await idOf("entry", locale, idOrPath);
+            if (!id)
+                return null;
+            return run(["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.entry.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 getShared(name, o) {
+            const locale = localeOf(o);
+            const item = sharedByName.get(name);
+            if (!item)
+                throw new Error(`smoodly: no shared item named "${name}".`);
+            return run(["shared", name, locale], [sharedTag(name)], (draft) => site.getShared(item, { locale, draft }));
+        },
+    };
+}

package/dist/page-tree.d.ts

@@ -0,0 +1,3 @@
+export declare function filterPageTree<T extends {
+    children: T[];
+}>(items: T[], keep: (item: T) => boolean): T[];

package/dist/page-tree.js

@@ -0,0 +1,6 @@
+// The one rule for pruning a navigation (spec 2026-09-11 §4): keep an
+// item when `keep` says so and recurse; a dropped parent drops its
+// subtree, since a nav cannot show orphans. Pure; the input is untouched.
+export function filterPageTree(items, keep) {
+    return items.filter(keep).map((item) => ({ ...item, children: filterPageTree(item.children, keep) }));
+}

package/dist/page.d.ts

@@ -1,5 +1,7 @@
 import type { ZonePolicy } from "./zones.ts";
-export type PageSchema<Zones extends Record<string, unknown> = Record<string, unknown>> = {
+import { type Descriptor } from "./fields.ts";
+import type { BuilderMap } from "./schema.ts";
+export type PageSchema<Zones extends Record<string, unknown> = Record<string, unknown>, F extends BuilderMap = BuilderMap> = {
     kind: "page";
     name: string;
     title: string;
@@ -12,16 +14,22 @@ export type PageSchema<Zones extends Record<string, unknown> = Record<string, un
     slug?: string | Record<string, string>;
     zones: Record<keyof Zones & string, ZonePolicy>;
     meta: Record<string, unknown>;
+    /** 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>;
     /** phantom: zone names for Props inference */
     readonly __zones?: Zones;
+    /** phantom: field builders for Props inference */
+    readonly __fields?: F;
 };
-export declare function pageSchema<Zones extends Record<string, object>>(input: {
+export declare function pageSchema<Zones extends Record<string, object>, F extends BuilderMap = {}>(input: {
     name: string;
     title: string;
     slug?: string | Record<string, string>;
     zones: Zones;
     meta?: Record<string, unknown>;
-}): PageSchema<Zones>;
+    fields?: F;
+}): PageSchema<Zones, F>;
 /** The default-locale segment of a fixed slug — what the admin lists and
  *  what today's root-level lookups use. */
 export declare function fixedSlug(schema: {

package/dist/page.js

@@ -1,3 +1,25 @@
+import { describePath, findMatch } from "./fields.js";
+/** What a page field may be: a settings form, never a ref, a list or a document (spec 2026-09-10 page fields §1). */
+const PAGE_FIELD_TYPES = new Set(["text", "link", "date", "number", "boolean", "select", "radio", "checkboxes", "image", "video", "file", "object"]);
+/** The descriptor at a dotted path below `d` (object subfields only — page fields hold no lists). */
+function descriptorAt(d, path) {
+    let cur = d;
+    for (const seg of path.split("."))
+        cur = cur.fields[seg];
+    return cur;
+}
+function assertPageField(page, key, d) {
+    const bad = findMatch(d, (sub) => !PAGE_FIELD_TYPES.has(sub.type), key);
+    if (bad !== null) {
+        const at = bad === key ? d : descriptorAt(d, bad.slice(key.length + 1));
+        const kind = at.type === "ref" || at.type === "refList" ? "refs" : at.type;
+        throw new Error(`smoodly: page "${page}": field ${describePath(bad)} — ${kind} cannot live in page fields.`);
+    }
+    const loc = findMatch(d, (sub) => sub.localized === true, key);
+    if (loc !== null) {
+        throw new Error(`smoodly: page "${page}": field ${describePath(loc)} uses .localized(), but page fields are per locale already.`);
+    }
+}
 /** Policies arrive as z.* results (possibly carrying builder methods) — store plain data only. */
 function normalizePolicy(p) {
     switch (p.kind) {
@@ -31,6 +53,9 @@ export function pageSchema(input) {
             throw new Error(`smoodly: page "${input.name}" declares an invalid slug — a fixed slug must be a non-empty string or a per-locale object of them.`);
         }
     }
+    const fields = Object.fromEntries(Object.entries(input.fields ?? {}).map(([k, b]) => [k, b.descriptor]));
+    for (const [key, d] of Object.entries(fields))
+        assertPageField(input.name, key, d);
     return {
         kind: "page",
         name: input.name,
@@ -38,6 +63,7 @@ export function pageSchema(input) {
         ...(input.slug !== undefined ? { slug: input.slug } : {}),
         zones: Object.fromEntries(Object.entries(input.zones).map(([k, p]) => [k, normalizePolicy(p)])),
         meta: input.meta ?? {},
+        fields,
     };
 }
 /** The default-locale segment of a fixed slug — what the admin lists and

package/dist/pairing.d.ts

@@ -9,9 +9,10 @@ import type { PageContext, ZoneContent } from "./render.tsx";
 export type Props<S> = S extends {
     kind: "page";
     __zones?: infer Z extends Record<string, unknown>;
+    __fields?: infer F extends BuilderMap;
 } ? {
     zones: Record<keyof Z & string, ZoneContent>;
-    page: PageContext;
+    page: PageContext<NamespaceValues<F>>;
 } : S extends {
     __f?: infer F extends BuilderMap;
     __s?: infer St extends BuilderMap;

package/dist/pairing.js

@@ -1,14 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-function styleDefaultsOf(styles) {
-    const out = {};
-    for (const [key, d] of Object.entries(styles)) {
-        if (d.default !== undefined)
-            out[key] = d.default;
-    }
-    return out;
-}
+import { defaultsOf } from "./field-defaults.js";
 function pair(schema, View) {
-    const defaults = styleDefaultsOf(schema.styles);
+    const defaults = defaultsOf(schema.styles);
     const Component = (props) => {
         const { styles: styleOverrides, ...fields } = props ?? {};
         const styles = { ...defaults, ...styleOverrides };

package/dist/render.d.ts

@@ -1,5 +1,6 @@
 import type { ComponentType, ReactElement } from "react";
 import type { PageSchema } from "./page.ts";
+import type { BuilderMap, NamespaceValues } from "./schema.ts";
 export type TreeNode = {
     id: string;
     type: string;
@@ -15,26 +16,32 @@ export type TreeNode = {
 export type PageTree = {
     zones: Record<string, TreeNode[]>;
     meta?: Record<string, unknown>;
+    fields?: Record<string, unknown>;
 };
 /** Where a rendered page sits in the tree — what a view needs for
  *  breadcrumbs and sub-navigation without a query (spec 2026-09-05 §5).
  *  `path` is the locale-relative CMS path (what the content API returns);
  *  `url` is that path through the app's `href` seam — `/fi/yritys` under
  *  next-intl, `/yritys` without it — so a page shape links the same way
- *  in both layouts. */
+ *  in both layouts. `fields` is the linked page's own page fields (spec
+ *  2026-09-10 page fields §3): the published tree's outside draft mode,
+ *  raw (no asset resolution), defaults applied, `{}` for a folder. */
 export type PageLink = {
     title: string;
     path: string;
     hasPage: boolean;
+    fields: Record<string, unknown>;
 };
 export type PageContextLink = PageLink & {
     url: string;
 };
-export type PageContext = {
+export type PageContext<Fields = Record<string, unknown>> = {
     id: string;
     title: string;
     path: string;
     url: string;
+    /** The page's own fields, typed from its schema on the view; resolved, defaults applied. */
+    fields: Fields;
     /** Root first, parent last. */
     ancestors: ReadonlyArray<PageContextLink>;
     children: ReadonlyArray<PageContextLink>;
@@ -58,14 +65,14 @@ export type ZoneContent = {
 export declare function Zone({ of: content }: {
     of: ZoneContent;
 }): import("react").JSX.Element | null;
-export type PageViewProps<Zones extends Record<string, unknown>> = {
+export type PageViewProps<Zones extends Record<string, unknown>, Fields = Record<string, unknown>> = {
     zones: Record<keyof Zones & string, ZoneContent>;
-    page: PageContext;
+    page: PageContext<Fields>;
 };
-export type PairedPage<Zones extends Record<string, unknown>> = ((props: PageViewProps<Zones>) => ReactElement) & {
-    schema: PageSchema<Zones>;
+export type PairedPage<Zones extends Record<string, unknown>, F extends BuilderMap = BuilderMap> = ((props: PageViewProps<Zones, NamespaceValues<F>>) => ReactElement) & {
+    schema: PageSchema<Zones, F>;
 };
-export declare function page<Zones extends Record<string, unknown>>(schema: PageSchema<Zones>, View: ComponentType<PageViewProps<Zones>>): PairedPage<Zones>;
+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 type Registry = {
     sections?: AnyPaired[];
     elements?: AnyPaired[];

package/dist/render.js

@@ -5,7 +5,7 @@ import { EMPTY_ATTR, ZONE_ATTR } from "./marks.js";
  *  no position in the tree. Frozen: one singleton shared by every such
  *  render, so a view that pushed onto it would leak into the next. */
 export const EMPTY_PAGE_CONTEXT = Object.freeze({
-    id: "", title: "", path: "/", url: "/", ancestors: Object.freeze([]), children: Object.freeze([]),
+    id: "", title: "", path: "/", url: "/", fields: Object.freeze({}), ancestors: Object.freeze([]), children: Object.freeze([]),
 });
 export function Zone({ of: content }) {
     // A malformed tree (bad data, a client that skipped isPageTree) must not
@@ -45,5 +45,5 @@ export function renderPage(Page, tree, registry, options) {
         zone,
         { name: zone, nodes: tree.zones?.[zone] ?? [], components, editor: options?.editor ?? false },
     ]));
-    return _jsx(Page, { zones: zones, page: options?.page ?? EMPTY_PAGE_CONTEXT });
+    return _jsx(Page, { zones: zones, page: (options?.page ?? EMPTY_PAGE_CONTEXT) });
 }

package/dist/resolve.d.ts

@@ -32,6 +32,10 @@ type ResolveOptions = {
     elements?: SectionLike[];
     /** Optional safety valve on chain length; unlimited by default. */
     maxDepth?: number;
+    /** The page's own field descriptors (spec 2026-09-10 page fields §3): `tree.fields` resolves like a node's fields, and `tree.meta.ogImage` as an image. */
+    page?: {
+        fields: Record<string, Descriptor>;
+    };
 };
 export declare function resolveTree(tree: PageTree, options: ResolveOptions): Promise<PageTree>;
 /** One value set's media, resolved in place. Exported for the site layer's shared-item styles. */

package/dist/resolve.js

@@ -9,6 +9,8 @@
 import { sharedLink, SHARED_NODE_TYPE, STYLES_KEY } from "./shared.js";
 import { applyAssets, collectAssetIds } from "./media.js";
 import { elementSchemas } from "./richtext-walk.js";
+/** The built-in SEO set's one media value (spec 2026-09-10 page fields §2). */
+const META_DESCRIPTORS = { ogImage: { type: "image" } };
 function targetOf(d) {
     const t = d.target?.();
     if (!t?.name)
@@ -40,6 +42,8 @@ export async function resolveTree(tree, options) {
             collectTasks(node.fields, schema.fields, tasks);
         }
     }
+    if (options.page && resolved.fields)
+        collectTasks(resolved.fields, options.page.fields, tasks);
     const hydrated = await runResolution(tasks, { collections: options.collections, fetch: options.fetch, maxDepth });
     if (options.assets) {
         const sets = [];
@@ -50,6 +54,10 @@ export async function resolveTree(tree, options) {
             sets.push({ values: node.fields, descriptors: schema.fields });
             sets.push({ values: node.styles, descriptors: schema.styles ?? {} });
         }
+        if (options.page && resolved.fields)
+            sets.push({ values: resolved.fields, descriptors: options.page.fields });
+        if (resolved.meta)
+            sets.push({ values: resolved.meta, descriptors: META_DESCRIPTORS });
         await resolveMediaSets([...sets, ...hydrated], options.assets, elementSchemas(options.elements));
     }
     return resolved;

package/dist/revalidate.d.ts

@@ -12,6 +12,12 @@ export declare const entryTag: (id: string) => string;
  *  locale, and code owns the name): the Next glue's getSmoodlyShared
  *  caches under it; ops.shared expires it. */
 export declare const sharedTag: (name: string) => string;
+/** The page-tree listing's cache unit (spec 2026-09-11 §2): one tree-wide
+ *  tag, fired by every page op that changes what the listing shows. */
+export declare const pagesTreeTag: () => string;
+/** A collection's list units: fired by every entry write in the
+ *  collection, since a non-versioned collection's published read is its live row. */
+export declare const collectionTag: (name: string) => string;
 export declare function affectedTargets(stores: {
     pages: PageStore;
     entries: EntryStore;

package/dist/revalidate.js

@@ -11,6 +11,12 @@ export const entryTag = (id) => `entry:${id}`;
  *  locale, and code owns the name): the Next glue's getSmoodlyShared
  *  caches under it; ops.shared expires it. */
 export const sharedTag = (name) => `shared:${name}`;
+/** The page-tree listing's cache unit (spec 2026-09-11 §2): one tree-wide
+ *  tag, fired by every page op that changes what the listing shows. */
+export const pagesTreeTag = () => "pages:tree";
+/** A collection's list units: fired by every entry write in the
+ *  collection, since a non-versioned collection's published read is its live row. */
+export const collectionTag = (name) => `entries:${name}`;
 export async function affectedTargets(stores, entryId, options = {}) {
     const maxDepth = options.maxDepth ?? Infinity;
     const seen = new Set([entryId]);

package/dist/shared.d.ts

@@ -6,7 +6,7 @@ import type { BuilderMap, NamespaceValues, SectionSchema } from "./schema.ts";
 export declare const SHARED_NODE_TYPE = "shared";
 /** The reserved key a visual item's styles live under in the node's shared JSONB. */
 export declare const STYLES_KEY = "$styles";
-export type SharedSchema<V = Record<string, unknown>> = CollectionSchema<any> & {
+export type SharedSchema<V = Record<string, unknown>, N extends string = string> = CollectionSchema<any, N> & {
     kind: "shared";
     /** The registered section a visual item renders through; absent = an object item. */
     section?: string;
@@ -28,19 +28,19 @@ export declare function sharedLink(node: {
     type: string;
     fields?: Record<string, unknown>;
 }): SharedLink | null;
-type SharedInput = {
-    name: string;
+type SharedInput<N extends string = string> = {
+    name: N;
     title: string;
     versions?: boolean;
 };
-export declare function shared<F extends BuilderMap>(input: SharedInput & {
+export declare function shared<F extends BuilderMap, const N extends string = string>(input: SharedInput<N> & {
     fields: F;
     section?: undefined;
-}): SharedSchema<NamespaceValues<F>>;
-export declare function shared<F extends BuilderMap, St extends BuilderMap>(input: SharedInput & {
+}): SharedSchema<NamespaceValues<F>, N>;
+export declare function shared<F extends BuilderMap, St extends BuilderMap, const N extends string = string>(input: SharedInput<N> & {
     section: PairedComponent<SectionSchema<F, St>, F, St>;
     fields?: undefined;
 }): SharedSchema<NamespaceValues<F> & {
     styles: NamespaceValues<St>;
-}>;
+}, N>;
 export {};

package/dist/site.d.ts

@@ -1,6 +1,7 @@
 import type { AssetStore } from "./asset-store.ts";
 import type { CollectionSchema, EntryOrder } from "./collections.ts";
-import { type EntryRecord, type EntryStore } from "./entry-store.ts";
+import type { Descriptor } from "./fields.ts";
+import { type EntryRecord, type EntryStore, type Where } from "./entry-store.ts";
 import { type LocaleSet, type PathTarget } from "./paths.ts";
 import type { SectionLike } from "./refs.ts";
 import type { PageContext, PageLink, PageTree } from "./render.tsx";
@@ -19,6 +20,16 @@ export type SiteOptions = {
     shared?: SharedSchema[];
     locales: LocaleSet;
     homePageSlug?: string;
+    /** Page shapes (entry pages are ignored): the source of each template's page-field descriptors (spec 2026-09-10 page fields §3). */
+    pages?: ReadonlyArray<SitePageSchema>;
+};
+/** A page registration as the site needs it: the template's page fields. */
+export type SitePageSchema = {
+    schema: {
+        kind: string;
+        name: string;
+        fields?: Record<string, Descriptor>;
+    };
 };
 export type SitePage = {
     kind: "page";
@@ -27,6 +38,8 @@ export type SitePage = {
     tree: PageTree;
     title: string;
     path: string;
+    /** The page's own fields (spec 2026-09-10 page fields §3): resolved, defaults applied. */
+    fields: Record<string, unknown>;
     ancestors: PageLink[];
     children: PageLink[];
     /** locale → path, for metadata alternates: the locales the page is
@@ -50,6 +63,7 @@ export type PageTreeItem = {
     title: string;
     path: string;
     hasPage: boolean;
+    fields: Record<string, unknown>;
     children: PageTreeItem[];
 };
 export type SiteEntryItem = {
@@ -59,10 +73,14 @@ export type SiteEntryItem = {
 export type EntryTreeItem = SiteEntryItem & {
     children: EntryTreeItem[];
 };
+/** `where`, `limit`, `parent` and `order` run in the store (spec 2026-09-11 §3); `draft` reads live rows inside the editor preview. */
 export type EntryQuery = {
     locale?: string;
     parent?: string | null;
     order?: EntryOrder;
+    where?: Where;
+    limit?: number;
+    draft?: boolean;
 };
 export type LoadOptions = {
     draft?: boolean;
@@ -77,16 +95,20 @@ export interface SmoodlySite {
     resolve(locale: string, path: string, options?: LoadOptions): Promise<SiteHit | null>;
     getPagesTree(options?: {
         locale?: string;
+        draft?: boolean;
     }): Promise<PageTreeItem[]>;
     getPage(pathOrId: string, options?: {
         locale?: string;
+        draft?: boolean;
     }): Promise<SitePage | null>;
     getEntries(collection: string, options?: EntryQuery): Promise<SiteEntryItem[]>;
     getEntry(collection: string, idOrPath: string, options?: {
         locale?: string;
+        draft?: boolean;
     }): Promise<SiteEntryItem | null>;
     getEntriesTree(collection: string, options?: {
         locale?: string;
+        draft?: boolean;
     }): Promise<EntryTreeItem[]>;
     /** A shared 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