smoodly 0.0.4 → 0.0.6

package/dist/next/page-renderer.d.ts

@@ -1,36 +1,44 @@
 import type { ComponentType, ReactElement } from "react";
 import type { Metadata } from "next";
-import type { CollectionSchema } from "../collections.ts";
-import type { EntryStore } from "../entry-store.ts";
 import type { Descriptor } from "../fields.ts";
 import { type PairedPage } from "../render.tsx";
-import type { PageStore } from "../store.ts";
-/** A registered section, as both the renderer and the ref resolver need it. */
+import { type SmoodlySite } from "../site.ts";
+/** A registered section, as renderPage's registry needs it. */
 type SectionEntry = ComponentType<any> & {
     schema: {
         name: string;
         fields: Record<string, Descriptor>;
     };
 };
-export type PageRendererOptions = {
-    /** Lazy so `next build` never needs env vars at import time. */
-    stores: () => {
-        pages: PageStore;
-        entries: EntryStore;
+/** A page shape or an entry page — anything in `config.registry.pages`. */
+export type PageRegistration = ((props: any) => ReactElement) & {
+    schema: {
+        kind: string;
+        name: string;
+        collection?: string;
     };
+};
+export type PageRendererOptions = {
+    site: SmoodlySite;
     sections: SectionEntry[];
-    collections: CollectionSchema<any>[];
-    /** Cache tag per slug; must match what publish revalidates. */
-    tag?: (slug: string) => string;
+    pages: ReadonlyArray<PageRegistration>;
+    /** Locale-relative CMS path → site URL. Default: the path itself. With
+     *  next-intl: `(path, locale) => getPathname({ locale, href: path })`. */
+    href?: (path: string, locale: string) => string;
 };
-export type RenderOptions = {
-    slug?: string;
+export type PathRenderOptions = {
+    locale?: string;
     searchParams?: Promise<Record<string, string | string[] | undefined>>;
 };
 export declare function createPageRenderer(options: PageRendererOptions): {
-    renderSmoodlyPage<Z extends Record<string, unknown>>(Page: PairedPage<Z>, opts?: RenderOptions): Promise<ReactElement>;
-    smoodlyMetadata<Z extends Record<string, unknown>>(Page: PairedPage<Z>, opts?: {
-        slug?: string;
-    }): Promise<Metadata>;
+    renderSmoodlyPath: (segments: string[], opts?: PathRenderOptions) => Promise<ReactElement<unknown, string | import("react").JSXElementConstructor<any>>>;
+    smoodlyMetadata: (segments: string[], opts?: {
+        locale?: string;
+    }) => Promise<Metadata>;
+    /** A fixed registration rendered from the developer's own route file. */
+    renderSmoodlyPage: <Z extends Record<string, unknown>>(Page: PairedPage<Z>, opts?: PathRenderOptions) => Promise<ReactElement<unknown, string | import("react").JSXElementConstructor<any>>>;
+    smoodlyPageMetadata: <Z extends Record<string, unknown>>(Page: PairedPage<Z>, opts?: {
+        locale?: string;
+    }) => Promise<Metadata>;
 };
 export {};

package/dist/next/page-renderer.js

@@ -4,66 +4,89 @@ import { draftMode } from "next/headers";
 import { notFound } from "next/navigation";
 import { connection } from "next/server";
 import { EditorBridge } from "../admin/next/bridge.js";
+import { fixedPathFor } from "../localize.js";
+import { joinPath } from "../paths.js";
 import { renderPage } from "../render.js";
-import { resolveTree } from "../resolve.js";
-import { metadataFrom, pageSlugFor } from "./meta.js";
+import { entryTag, pageTag } from "../revalidate.js";
+import { pageContextOf } from "../site.js";
+import { metadataFrom } from "./meta.js";
 export function createPageRenderer(options) {
-    const tag = options.tag ?? ((slug) => `page:${slug}`);
-    const resolved = (tree, o) => resolveTree(tree, {
-        sections: options.sections,
-        collections: options.collections,
-        fetch: (collection, ids) => options.stores().entries.getMany(collection, ids, o),
-    });
-    // The cached unit is the RESOLVED tree: entry data is frozen with the
-    // page, so an entry edit only appears once the revalidation fan-out
-    // fires revalidateTag("page:<slug>").
-    const cachedPublished = (slug) => unstable_cache(async () => {
-        const { pages } = options.stores();
-        const record = await pages.getPage(slug);
-        const tree = record?.publishedVersionId ? await pages.getPublishedTree(slug) : null;
-        return record && tree
-            ? { template: record.template, tree: await resolved(tree, { status: "published" }) }
-            : null;
-    }, 
-    // Prefixed so it never collides with the surviving catch-all's own
-    // ["resolved-page", slug] cache in the same app.
-    ["smoodly-resolved-page", slug], { tags: [tag(slug)] })();
-    async function load(slug, draft) {
-        if (!draft)
-            return cachedPublished(slug);
-        const { pages } = options.stores();
-        const record = await pages.getPage(slug);
-        const tree = record ? await pages.getDraftTree(slug) : null;
-        return record && tree ? { template: record.template, tree: await resolved(tree) } : null;
+    const { site } = options;
+    const href = options.href ?? ((path) => path);
+    const shapes = new Map(options.pages.filter((p) => p.schema.kind === "page").map((p) => [p.schema.name, p]));
+    const entryPages = new Map(options.pages.filter((p) => p.schema.kind === "entryPage" && p.schema.collection).map((p) => [p.schema.collection, p]));
+    /** locate (uncached: the id it returns IS the cache tag) then load —
+     *  cached per (locale, path) outside draft mode. */
+    async function load(locale, path, draft) {
+        const target = await site.locate(locale, path);
+        if (!target)
+            return null;
+        if (draft)
+            return site.load(target, locale, path, { draft: true });
+        return unstable_cache(() => site.load(target, locale, path), ["smoodly-site", locale, path], {
+            tags: [target.kind === "page" ? pageTag(target.id) : entryTag(target.id)],
+        })();
     }
-    /** A record that exists but belongs to another registration is a 404
-     * for THIS route — otherwise the open [slug] route would render a fixed
-     * page's record through its own view at a duplicate URL. */
-    function forRegistration(loaded, name) {
-        return loaded && loaded.template === name ? loaded.tree : null;
+    function render(hit, editor, locale) {
+        if (hit.kind === "page") {
+            const Page = shapes.get(hit.template);
+            if (!Page) {
+                console.warn(`smoodly: no page registration named "${hit.template}" — the record at ${hit.path} is a 404.`);
+                notFound();
+            }
+            const page = pageContextOf(hit, (path) => href(path, locale));
+            return renderPage(Page, hit.tree, { sections: options.sections }, { editor, page });
+        }
+        const View = entryPages.get(hit.collection);
+        if (!View) {
+            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 });
+    }
+    function alternates(hit) {
+        if (site.locales.supported.length < 2)
+            return {};
+        const languages = Object.fromEntries(Object.entries(hit.paths).map(([locale, path]) => [locale, href(path, locale)]));
+        return { alternates: { languages } };
+    }
+    async function page(pathFor, opts, accept) {
+        // A CMS route is request-rendered by construction: without this a
+        // route with no dynamic segment would be prerendered against the
+        // database at build time (DESIGN.md §3, OQ #19).
+        await connection();
+        const locale = opts?.locale ?? site.locales.default;
+        const path = pathFor(locale);
+        const { isEnabled: draft } = await draftMode();
+        const hit = await load(locale, path, draft);
+        if (!hit || !accept(hit))
+            notFound();
+        const editor = draft && (await opts?.searchParams)?.["smoodly-editor"] === "1";
+        return (_jsxs(_Fragment, { children: [editor ? _jsx(EditorBridge, {}) : null, render(hit, editor, locale)] }));
     }
+    async function metadata(pathFor, opts, accept) {
+        // generateMetadata runs alongside the page render, so it gates too.
+        await connection();
+        const locale = opts?.locale ?? site.locales.default;
+        const path = pathFor(locale);
+        const { isEnabled: draft } = await draftMode();
+        const hit = await load(locale, path, draft);
+        if (!hit || !accept(hit))
+            return {};
+        return { ...(hit.kind === "page" ? metadataFrom(hit.tree.meta) : {}), ...alternates(hit) };
+    }
+    const any = () => true;
+    /** The escape hatch may only render ITS OWN registration's record. */
+    const only = (Page) => (hit) => hit.kind === "page" && hit.template === Page.schema.name;
+    /** Resolved AFTER connection(), inside page()/metadata(), so a wiring
+     *  error surfaces as a rejected promise like every other failure. */
+    const fixedPath = (Page) => (locale) => fixedPathFor(Page.schema, locale, site.locales, site.homePageSlug);
+    const literal = (segments) => () => joinPath(segments);
     return {
-        async renderSmoodlyPage(Page, opts) {
-            // A CMS route is request-rendered by construction: without this a
-            // fixed-slug route file has nothing dynamic in it, so `next build`
-            // would prerender it against the database (DESIGN.md §3, OQ #19).
-            await connection();
-            const slug = pageSlugFor(Page.schema, opts?.slug);
-            const { isEnabled: draft } = await draftMode();
-            const tree = forRegistration(await load(slug, draft), Page.schema.name);
-            if (!tree)
-                notFound();
-            const editor = draft && (await opts?.searchParams)?.["smoodly-editor"] === "1";
-            return (_jsxs(_Fragment, { children: [editor ? _jsx(EditorBridge, {}) : null, renderPage(Page, tree, { sections: options.sections }, { editor })] }));
-        },
-        async smoodlyMetadata(Page, opts) {
-            // generateMetadata runs alongside the page render, so it must gate
-            // on the request too or a build could still reach the database here.
-            await connection();
-            const slug = pageSlugFor(Page.schema, opts?.slug);
-            const { isEnabled: draft } = await draftMode();
-            const tree = forRegistration(await load(slug, draft), Page.schema.name);
-            return metadataFrom(tree?.meta);
-        },
+        renderSmoodlyPath: (segments, opts) => page(literal(segments), opts, any),
+        smoodlyMetadata: (segments, opts) => metadata(literal(segments), opts, any),
+        /** A fixed registration rendered from the developer's own route file. */
+        renderSmoodlyPage: (Page, opts) => page(fixedPath(Page), opts, only(Page)),
+        smoodlyPageMetadata: (Page, opts) => metadata(fixedPath(Page), opts, only(Page)),
     };
 }

package/dist/page.d.ts

@@ -6,8 +6,10 @@ export type PageSchema<Zones extends Record<string, unknown> = Record<string, un
     /** Fixed: this registration owns exactly ONE page record, at this slug,
      * served by one route file. Absent = open: editors create many.
      * The route file serving "/" must declare the config's `homePageSlug`
-     * (default "home") — that is how the admin maps its record to "/". */
-    slug?: string;
+     * (default "home") — that is how the admin maps its record to "/".
+     * A per-locale object lets each locale carry its own translated
+     * 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>;
     /** phantom: zone names for Props inference */
@@ -16,7 +18,12 @@ export type PageSchema<Zones extends Record<string, unknown> = Record<string, un
 export declare function pageSchema<Zones extends Record<string, object>>(input: {
     name: string;
     title: string;
-    slug?: string;
+    slug?: string | Record<string, string>;
     zones: Zones;
     meta?: Record<string, unknown>;
 }): PageSchema<Zones>;
+/** 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: {
+    slug?: string | Record<string, string>;
+}, defaultLocale: string): string | undefined;

package/dist/page.js

@@ -21,8 +21,11 @@ export function pageSchema(input) {
     // 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.
-    if (input.slug !== undefined && (typeof input.slug !== "string" || input.slug.trim() === "")) {
-        throw new Error(`smoodly: page "${input.name}" declares an invalid slug — a fixed slug must be a non-empty string.`);
+    if (input.slug !== undefined) {
+        const values = typeof input.slug === "string" ? [input.slug] : Object.values(input.slug);
+        if (values.length === 0 || values.some((v) => typeof v !== "string" || v.trim() === "")) {
+            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.`);
+        }
     }
     return {
         kind: "page",
@@ -33,3 +36,10 @@ export function pageSchema(input) {
         meta: input.meta ?? {},
     };
 }
+/** The default-locale segment of a fixed slug — what the admin lists and
+ *  what today's root-level lookups use. */
+export function fixedSlug(schema, defaultLocale) {
+    if (schema.slug === undefined)
+        return undefined;
+    return typeof schema.slug === "string" ? schema.slug : schema.slug[defaultLocale];
+}

package/dist/pairing.d.ts

@@ -1,16 +1,17 @@
 import type { ComponentType, ReactElement } from "react";
 import type { BuilderMap, ElementSchema, NamespaceValues, SectionSchema } from "./schema.ts";
-import type { ZoneContent } from "./render.tsx";
-/** What the view receives. A page view gets its zones; a section/element
- * view gets field values flat and styles complete (defaults filled).
- * The page branch keys on `kind` — an optional-only check would match
- * section schemas too, since a type lacking `__zones` still extends
- * `{ __zones?: X }`. */
+import type { PageContext, ZoneContent } from "./render.tsx";
+/** What the view receives. A page view gets its zones and where it sits
+ * in the tree; a section/element view gets field values flat and styles
+ * complete (defaults filled). The page branch keys on `kind` — an
+ * optional-only check would match section schemas too, since a type
+ * lacking `__zones` still extends `{ __zones?: X }`. */
 export type Props<S> = S extends {
     kind: "page";
     __zones?: infer Z extends Record<string, unknown>;
 } ? {
     zones: Record<keyof Z & string, ZoneContent>;
+    page: PageContext;
 } : S extends {
     __f?: infer F extends BuilderMap;
     __s?: infer St extends BuilderMap;

package/dist/path-index.d.ts

@@ -0,0 +1,16 @@
+import type { PathRow, PathTarget } from "./paths.ts";
+export type { PathRow, PathTarget } from "./paths.ts";
+export interface PathIndex {
+    rewrite(targets: PathTarget[], rows: PathRow[]): Promise<void>;
+    remove(targets: PathTarget[]): Promise<void>;
+    resolve(locale: string, path: string): Promise<PathTarget | null>;
+    pathsOf(target: PathTarget): Promise<Record<string, string>>;
+}
+export declare const pathTakenError: (locale: string, path: string) => Error;
+export declare class MemoryPathIndex implements PathIndex {
+    private rows;
+    rewrite(targets: PathTarget[], rows: PathRow[]): Promise<void>;
+    remove(targets: PathTarget[]): Promise<void>;
+    resolve(locale: string, path: string): Promise<PathTarget | null>;
+    pathsOf(target: PathTarget): Promise<Record<string, string>>;
+}

package/dist/path-index.js

@@ -0,0 +1,33 @@
+const sameTarget = (a, b) => a.kind === b.kind && a.id === b.id;
+const key = (locale, path) => `${locale} ${path}`;
+export const pathTakenError = (locale, path) => new Error(`smoodly: the path "${path}" (${locale}) is already taken.`);
+export class MemoryPathIndex {
+    constructor() {
+        this.rows = [];
+    }
+    async rewrite(targets, rows) {
+        const kept = this.rows.filter((r) => !targets.some((t) => sameTarget(t, r)));
+        const taken = new Set(kept.map((r) => key(r.locale, r.path)));
+        for (const row of rows) {
+            const k = key(row.locale, row.path);
+            if (taken.has(k))
+                throw pathTakenError(row.locale, row.path);
+            taken.add(k);
+        }
+        this.rows = [...kept, ...rows.map((r) => ({ ...r }))];
+    }
+    async remove(targets) {
+        this.rows = this.rows.filter((r) => !targets.some((t) => sameTarget(t, r)));
+    }
+    async resolve(locale, path) {
+        const row = this.rows.find((r) => r.locale === locale && r.path === path);
+        return row ? { kind: row.kind, id: row.id } : null;
+    }
+    async pathsOf(target) {
+        const out = {};
+        for (const r of this.rows)
+            if (sameTarget(r, target))
+                out[r.locale] = r.path;
+        return out;
+    }
+}

package/dist/paths.d.ts

@@ -0,0 +1,80 @@
+export declare const SEGMENT_RE: RegExp;
+export declare const isSegment: (s: string) => boolean;
+export declare function assertSegment(s: string, what: string): void;
+export type LocaleSet = {
+    default: string;
+    supported: string[];
+};
+/** A per-locale segment map: a string applies to every supported locale; an object is copied as declared. */
+export declare function perLocaleSegments(value: string | Record<string, string>, supported: string[]): Record<string, string>;
+export type PathTarget = {
+    kind: "page" | "entry";
+    id: string;
+};
+export type PathRow = PathTarget & {
+    locale: string;
+    path: string;
+};
+export declare const joinPath: (segments: string[]) => string;
+export declare const splitPath: (path: string) => string[];
+type SlugI18n = Record<string, {
+    slug?: string;
+}> | null | undefined;
+/** The locale's own segment, or the default locale's (per-field fallback). */
+export declare function segmentFor(node: {
+    slug: string;
+    i18n?: SlugI18n;
+}, locale: string, set: LocaleSet): string;
+/** null = every supported locale; otherwise the intersection. */
+export declare function localesOf(node: {
+    locales?: string[] | null;
+}, set: LocaleSet): string[];
+export declare function chainOf<T extends {
+    id: string;
+    parentId: string | null;
+}>(node: T, byId: (id: string) => T | undefined): T[];
+export declare function assertDepth(depth: number, max: number, what: string): void;
+export type PageLike = {
+    id: string;
+    parentId: string | null;
+    slug: string;
+    i18n: Record<string, {
+        slug?: string;
+        title?: string;
+    }> | null;
+    locales: string[] | null;
+};
+export type PagePathOptions = {
+    locales: LocaleSet;
+    homePageSlug: string;
+};
+/** The node's path in one locale: `/` for the home node, else the
+ *  localized ancestor chain joined. THE derivation — pagePathRows,
+ *  buildPageTree and the site layer all call this. */
+export declare function pagePath(node: PageLike, byId: (id: string) => PageLike | undefined, locale: string, opts: PagePathOptions): string;
+export declare function pagePathRows(targets: PageLike[], byId: (id: string) => PageLike | undefined, opts: PagePathOptions): PathRow[];
+export type EntryLike = {
+    id: string;
+    parentId: string | null;
+    fields: Record<string, unknown>;
+    i18n: Record<string, Record<string, unknown>> | null;
+    locales: string[] | null;
+};
+export declare function collectionSegment(path: string | Record<string, string> | undefined, locale: string, set: LocaleSet): string | null;
+/** The "claims a URL" predicate (§1): a slug is only a real segment when
+ * it is a non-empty string — absent, null, or `""` all mean "no URL".
+ * The sibling index predicate in sql.ts (`entries_sibling_slug_key`)
+ * mirrors this rule exactly, so Postgres and memory agree on which
+ * entries can collide. */
+export declare const slugOf: (fields: Record<string, unknown>) => string | null;
+export declare function entrySegment(entry: EntryLike, locale: string, set: LocaleSet): string | null;
+export declare function entryPathRows(targets: EntryLike[], byId: (id: string) => EntryLike | undefined, collection: {
+    path?: string | Record<string, string>;
+}, set: LocaleSet): PathRow[];
+export type PageTreeNode<T extends PageLike> = {
+    record: T;
+    path: string;
+    children: PageTreeNode<T>[];
+};
+export declare function buildPageTree<T extends PageLike>(records: T[], locale: string, opts: PagePathOptions): PageTreeNode<T>[];
+export {};

package/dist/paths.js

@@ -0,0 +1,110 @@
+// The one place a URL is derived (spec 2026-09-05 §1, §4). Pure and
+// framework-free: both store adapters and the tree query call these, so
+// the `paths` index and every derived `path` value agree by construction.
+export const SEGMENT_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export const isSegment = (s) => SEGMENT_RE.test(s);
+export function assertSegment(s, what) {
+    if (typeof s !== "string" || !isSegment(s)) {
+        throw new Error(`smoodly: ${what} "${s}" is not a valid slug — use lowercase letters, digits and single hyphens.`);
+    }
+}
+/** A per-locale segment map: a string applies to every supported locale; an object is copied as declared. */
+export function perLocaleSegments(value, supported) {
+    return typeof value === "string" ? Object.fromEntries(supported.map((l) => [l, value])) : { ...value };
+}
+export const joinPath = (segments) => (segments.length === 0 ? "/" : "/" + segments.join("/"));
+export const splitPath = (path) => path.split("/").filter((s) => s.length > 0);
+/** The locale's own segment, or the default locale's (per-field fallback). */
+export function segmentFor(node, locale, set) {
+    if (locale === set.default)
+        return node.slug;
+    const own = node.i18n?.[locale]?.slug;
+    return typeof own === "string" && own.length > 0 ? own : node.slug;
+}
+/** null = every supported locale; otherwise the intersection. */
+export function localesOf(node, set) {
+    if (!node.locales)
+        return [...set.supported];
+    return set.supported.filter((l) => node.locales.includes(l));
+}
+export function chainOf(node, byId) {
+    const chain = [node];
+    let current = node;
+    while (current.parentId !== null) {
+        const parent = byId(current.parentId);
+        if (!parent)
+            throw new Error(`smoodly: broken parent chain at "${node.id}".`);
+        chain.unshift(parent);
+        current = parent;
+    }
+    return chain;
+}
+export function assertDepth(depth, max, what) {
+    if (depth > max)
+        throw new Error(`smoodly: ${what} would exceed the tree depth (${max}).`);
+}
+const isHome = (node, homePageSlug) => node.parentId === null && node.slug === homePageSlug;
+/** The node's path in one locale: `/` for the home node, else the
+ *  localized ancestor chain joined. THE derivation — pagePathRows,
+ *  buildPageTree and the site layer all call this. */
+export function pagePath(node, byId, locale, opts) {
+    return isHome(node, opts.homePageSlug)
+        ? "/"
+        : joinPath(chainOf(node, byId).map((n) => segmentFor(n, locale, opts.locales)));
+}
+export function pagePathRows(targets, byId, opts) {
+    const rows = [];
+    for (const target of targets) {
+        for (const locale of localesOf(target, opts.locales)) {
+            rows.push({ kind: "page", id: target.id, locale, path: pagePath(target, byId, locale, opts) });
+        }
+    }
+    return rows;
+}
+export function collectionSegment(path, locale, set) {
+    if (path === undefined)
+        return null;
+    if (typeof path === "string")
+        return path;
+    return path[locale] ?? path[set.default] ?? null;
+}
+/** The "claims a URL" predicate (§1): a slug is only a real segment when
+ * it is a non-empty string — absent, null, or `""` all mean "no URL".
+ * The sibling index predicate in sql.ts (`entries_sibling_slug_key`)
+ * mirrors this rule exactly, so Postgres and memory agree on which
+ * entries can collide. */
+export const slugOf = (fields) => {
+    const slug = fields.slug;
+    return typeof slug === "string" && slug.length > 0 ? slug : null;
+};
+export function entrySegment(entry, locale, set) {
+    const own = locale === set.default ? undefined : entry.i18n?.[locale]?.slug;
+    return typeof own === "string" && own.length > 0 ? own : slugOf(entry.fields);
+}
+export function entryPathRows(targets, byId, collection, set) {
+    const rows = [];
+    for (const target of targets) {
+        const chain = chainOf(target, byId);
+        for (const locale of localesOf(target, set)) {
+            const base = collectionSegment(collection.path, locale, set);
+            if (base === null)
+                continue;
+            const segments = chain.map((e) => entrySegment(e, locale, set));
+            if (segments.some((s) => s === null))
+                continue;
+            rows.push({ kind: "entry", id: target.id, locale, path: joinPath([base, ...segments]) });
+        }
+    }
+    return rows;
+}
+export function buildPageTree(records, locale, opts) {
+    const byId = (id) => records.find((r) => r.id === id);
+    const build = (parentId) => records
+        .filter((r) => r.parentId === parentId)
+        .map((r) => ({
+        record: r,
+        path: pagePath(r, byId, locale, opts),
+        children: build(r.id),
+    }));
+    return build(null);
+}

package/dist/render.d.ts

@@ -16,6 +16,34 @@ export type PageTree = {
     zones: Record<string, TreeNode[]>;
     meta?: 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. */
+export type PageLink = {
+    title: string;
+    path: string;
+    hasPage: boolean;
+};
+export type PageContextLink = PageLink & {
+    url: string;
+};
+export type PageContext = {
+    id: string;
+    title: string;
+    path: string;
+    url: string;
+    /** Root first, parent last. */
+    ancestors: ReadonlyArray<PageContextLink>;
+    children: ReadonlyArray<PageContextLink>;
+};
+/** The `page` prop of a view rendered outside the site (a test, a preview
+ *  of a shape): a real object, so a view never guards an optional prop, but
+ *  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 declare const EMPTY_PAGE_CONTEXT: PageContext;
 type AnyPaired = ComponentType<any> & {
     schema: {
         name: string;
@@ -30,19 +58,20 @@ export type ZoneContent = {
 export declare function Zone({ of: content }: {
     of: ZoneContent;
 }): import("react").JSX.Element | null;
-export type PairedPage<Zones extends Record<string, unknown>> = ((props: {
+export type PageViewProps<Zones extends Record<string, unknown>> = {
     zones: Record<keyof Zones & string, ZoneContent>;
-}) => ReactElement) & {
+    page: PageContext;
+};
+export type PairedPage<Zones extends Record<string, unknown>> = ((props: PageViewProps<Zones>) => ReactElement) & {
     schema: PageSchema<Zones>;
 };
-export declare function page<Zones extends Record<string, unknown>>(schema: PageSchema<Zones>, View: ComponentType<{
-    zones: Record<keyof Zones & string, ZoneContent>;
-}>): PairedPage<Zones>;
+export declare function page<Zones extends Record<string, unknown>>(schema: PageSchema<Zones>, View: ComponentType<PageViewProps<Zones>>): PairedPage<Zones>;
 export type Registry = {
     sections?: AnyPaired[];
     elements?: AnyPaired[];
 };
 export declare function renderPage<Zones extends Record<string, unknown>>(Page: PairedPage<Zones>, tree: PageTree, registry: Registry, options?: {
     editor?: boolean;
+    page?: PageContext;
 }): ReactElement;
 export {};

package/dist/render.js

@@ -1,4 +1,11 @@
 import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+/** The `page` prop of a view rendered outside the site (a test, a preview
+ *  of a shape): a real object, so a view never guards an optional prop, but
+ *  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([]),
+});
 export function Zone({ of: content }) {
     // A malformed tree (bad data, a client that skipped isPageTree) must not
     // crash the render — treat a non-array nodes as empty rather than throw.
@@ -23,7 +30,7 @@ export function Zone({ of: content }) {
 export function page(schema, View) {
     const Component = ((props) => {
         const V = View;
-        return _jsx(V, { zones: props.zones });
+        return _jsx(V, { zones: props.zones, page: props.page });
     });
     Component.schema = schema;
     return Component;
@@ -37,5 +44,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 });
+    return _jsx(Page, { zones: zones, page: options?.page ?? EMPTY_PAGE_CONTEXT });
 }

package/dist/resolve.d.ts

@@ -19,4 +19,12 @@ type ResolveOptions = {
     maxDepth?: number;
 };
 export declare function resolveTree(tree: PageTree, options: ResolveOptions): Promise<PageTree>;
+export type ResolveFieldsOptions = {
+    collections: CollectionSchema<any>[];
+    fetch: EntryFetcher;
+    maxDepth?: number;
+};
+/** 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>>;
 export {};