smoodly 0.0.37 → 0.0.39

package/dist/content/content-api.js

@@ -0,0 +1,170 @@
+// The content API (spec 2026-09-30 tester findings §1): the admin's
+// operations with no signed-in editor, as a few verbs that throw. Scripts
+// and route handlers write content through this, never through the stores,
+// so validation, the code-owned address guards and publish checks apply.
+import { createAdminOps } from "../admin/ops-impl.js";
+import { imageDimensions } from "../image-dimensions.js";
+const MIME = {
+    jpg: "image/jpeg", jpeg: "image/jpeg", png: "image/png", webp: "image/webp", gif: "image/gif", avif: "image/avif",
+    svg: "image/svg+xml", mp4: "video/mp4", webm: "video/webm", pdf: "application/pdf",
+};
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+export class SmoodlyContentError extends Error {
+    constructor(error) {
+        const list = (error.fields ?? []).map((f) => `\n  ${f.field}: ${f.message}`).join("");
+        super(error.message + list);
+        this.name = "SmoodlyContentError";
+        this.code = error.code;
+        this.fields = error.fields ?? [];
+    }
+}
+async function must(result) {
+    const r = await result;
+    if (!r.ok)
+        throw new SmoodlyContentError(r);
+    return r.data;
+}
+/** With a password: the account is created (or an existing one kept) and made an admin. Without: an invite mail,
+ *  whose link goes to `redirectTo` or the Auth project's Site URL. Running it again changes nothing.
+ *  Its own function because `smoodly add-admin` has a member store and no config. */
+export async function addAdmin(members, email, options = {}) {
+    if (!members)
+        throw new SmoodlyContentError({ code: "internal", message: "smoodly: no member store — pass `members` to createSmoodlyContent." });
+    if (!EMAIL.test(email))
+        throw new SmoodlyContentError({ code: "validation", message: `smoodly: "${email}" is not an email address.` });
+    if (options.password !== undefined && options.password.length < 8) {
+        throw new SmoodlyContentError({ code: "validation", message: "smoodly: the password needs at least 8 characters." });
+    }
+    try {
+        // Where smoodly.io manages the members, nothing here writes them — as the admin's Members page refuses.
+        if ((await members.consoleUrl()) !== null) {
+            throw new SmoodlyContentError({ code: "blocked", message: "smoodly: this site's members are managed at smoodly.io." });
+        }
+        if (options.password !== undefined) {
+            await members.createAccount({ email, password: options.password, role: "admin" });
+            return { email, invited: false };
+        }
+        const { invited } = await members.invite({ email, role: "admin", redirectTo: options.redirectTo ?? "" });
+        return { email, invited };
+    }
+    catch (e) {
+        if (e instanceof SmoodlyContentError)
+            throw e;
+        throw new SmoodlyContentError({ code: "internal", message: e instanceof Error ? e.message : String(e) });
+    }
+}
+export function createSmoodlyContent(deps) {
+    const ops = createAdminOps(deps);
+    const def = deps.config.locales.default;
+    async function findPage(locale, path) {
+        const hit = await deps.pages.resolvePath(locale, path);
+        if (hit?.kind === "page" && !hit.redirect)
+            return deps.pages.getPage(hit.id);
+        return null;
+    }
+    async function updateEntry(collection, id, locale, fields) {
+        return must(ops.entries.save(collection, id, locale, fields));
+    }
+    /** The entries present in `locale` (the default language unless given) whose fields match every `where` key:
+     *  shared and that locale's fields and its slug, equal, or held by an array field (tags, refList). */
+    async function listEntries(collection, options = {}) {
+        if (!deps.config.registry.collections?.some((c) => c.name === collection)) {
+            throw new SmoodlyContentError({ code: "not_found", message: `smoodly: no collection named "${collection}".` });
+        }
+        const locale = options.locale ?? def;
+        const where = Object.entries(options.where ?? {});
+        return (await must(ops.entries.list(collection))).filter((e) => {
+            const row = e.locales[locale];
+            if (!row)
+                return false;
+            const fields = { ...e.fields, ...row.fields, slug: row.slug };
+            return where.every(([key, want]) => {
+                const value = fields[key];
+                return Array.isArray(value) ? value.includes(want) : value === want;
+            });
+        });
+    }
+    return {
+        pages: {
+            create: (input) => must(ops.pages.create(input)),
+            async setTree(id, locale, tree) {
+                await must(ops.pages.saveDraft(id, locale, tree));
+            },
+            /** The locale's draft tree — what `setTree` replaces; null for a folder or a locale the page lacks.
+             *  A seed reads it to tell a code-owned page nobody has filled yet. */
+            async getTree(id, locale) {
+                return (await must(ops.pages.get(id, locale))).draft;
+            },
+            async addLocale(id, locale, options) {
+                const added = await must(ops.pages.addLocale(id, locale, { from: options.from }));
+                if (options.slug === undefined && options.title === undefined)
+                    return added;
+                return must(ops.pages.rename(id, {
+                    locale,
+                    ...(options.slug !== undefined ? { slug: options.slug } : {}),
+                    ...(options.title !== undefined ? { title: options.title } : {}),
+                    redirect: false,
+                }));
+            },
+            publish: (id, locale) => must(ops.pages.publish(id, locale)),
+            /** A code-owned address with no record gets it created the way the admin's Pages list does (spec §2). */
+            async find(locale, path) {
+                const found = await findPage(locale, path);
+                if (found)
+                    return found;
+                await must(ops.pages.list());
+                return findPage(locale, path);
+            },
+        },
+        entries: {
+            create: (collection, input) => must(ops.entries.create(collection, input)),
+            update: updateEntry,
+            async addLocale(collection, id, locale, options) {
+                const added = await must(ops.entries.addLocale(collection, id, locale, { from: options.from }));
+                return options.fields ? updateEntry(collection, id, locale, options.fields) : added;
+            },
+            publish: (collection, id, locale) => must(ops.entries.setStatus(collection, id, locale, "published")),
+            list: listEntries,
+            async find(collection, match) {
+                return (await listEntries(collection, { where: { slug: match.slug }, locale: match.locale }))[0] ?? null;
+            },
+        },
+        globals: {
+            async set(name, locale, fields) {
+                await must(ops.globals.list()); // materializes the item (ensureGlobalItems), as opening Globals does
+                return must(ops.globals.save(name, locale, fields));
+            },
+            publish: (name, locale) => must(ops.globals.setStatus(name, locale, "published")),
+        },
+        media: {
+            /** A file path or bytes in, a ready asset and the value an image field stores out. */
+            async upload(file, meta = {}) {
+                if (!deps.assets)
+                    throw new SmoodlyContentError({ code: "internal", message: "smoodly: no media store — pass `assets` to createSmoodlyContent." });
+                // Loaded here, not at the top: this module is reachable from `smoodly/admin`, which a bundler may walk.
+                const bytes = typeof file === "string" ? new Uint8Array(await (await import("node:fs/promises")).readFile(file)) : file;
+                const filename = meta.filename ?? (typeof file === "string" ? file.split(/[\\/]/).pop() : "upload");
+                const mime = meta.mime ?? MIME[filename.split(".").pop().toLowerCase()] ?? "application/octet-stream";
+                // The media library's own rules, as the admin's upload applies them (config.media).
+                const { accept, maxSize } = deps.config.media;
+                if (!accept.includes(mime))
+                    throw new SmoodlyContentError({ code: "validation", message: `smoodly: "${filename}" is ${mime}, not an accepted file type.` });
+                if (bytes.byteLength > maxSize) {
+                    throw new SmoodlyContentError({ code: "validation", message: `smoodly: "${filename}" is larger than ${Math.round(maxSize / 1024 / 1024)} MB.` });
+                }
+                const { alt, title, caption, credit } = meta;
+                let asset;
+                try {
+                    asset = await deps.assets.create({ filename, mime, size: bytes.byteLength, bytes, alt, title, caption, credit, ...(imageDimensions(bytes) ?? {}) });
+                }
+                catch (e) {
+                    throw new SmoodlyContentError({ code: "internal", message: e instanceof Error ? e.message : String(e) });
+                }
+                return { asset: asset.id, ...(alt !== undefined ? { alt } : {}) };
+            },
+        },
+        members: {
+            addAdmin: (email, options = {}) => addAdmin(deps.members, email, options),
+        },
+    };
+}

package/dist/content/node.d.ts

@@ -0,0 +1,7 @@
+import type { BuilderMap, SectionSchema, StoredValues } from "../schema.ts";
+import type { PairedComponent } from "../pairing.tsx";
+import type { TreeNode } from "../render.tsx";
+export declare function node<F extends BuilderMap, St extends BuilderMap>(section: PairedComponent<SectionSchema<F, St>, F, St>, fields: Partial<StoredValues<F>>, options?: {
+    settings?: Partial<StoredValues<St>>;
+    id?: string;
+}): TreeNode;

package/dist/content/node.js

@@ -0,0 +1,10 @@
+import { newNodeId } from "../admin/tree-ops.js";
+export function node(section, fields, options = {}) {
+    const type = section.schema.name;
+    return {
+        id: options.id ?? newNodeId(type),
+        type,
+        fields: fields,
+        ...(options.settings ? { settings: options.settings } : {}),
+    };
+}

package/dist/env.d.ts

@@ -4,17 +4,20 @@ export type SmoodlyEnv = {
     url: string;
     /** Server-only: the service-role key (self-host) or the environment's write key (cloud). */
     secretKey: string;
-    /** What a browser may hold for the content project: anon/publishable key, or the cloud's per-environment key. It reads no content (sign-in and presence only). */
+    /** What a browser may hold for the content project: anon/publishable key, or the cloud's per-environment key. It reads no content (sign-in and presence only). "" on a live site that runs without the admin. */
     publishableKey: string;
     /** Where editors sign in. Defaults to `url`. */
     authUrl: string;
     /** That project's publishable key. Defaults to `publishableKey`. */
     authKey: string;
 };
-export declare function resolveSmoodlyEnv(env: Record<string, string | undefined>): SmoodlyEnv;
+/** The live site reads with the URL and the secret key; the admin and presence also need the
+ *  publishable key, so their callers pass "admin" (spec 2026-09-30 tester findings §4). A key
+ *  in the wrong variable or of no known form is named here, not by a failed read later. */
+export declare function resolveSmoodlyEnv(env: Record<string, string | undefined>, need?: "site" | "admin"): SmoodlyEnv;
 /** `resolveSmoodlyEnv(process.env)` — call lazily, never at module load,
  *  so `next build` without env still succeeds. */
-export declare const smoodlyEnv: () => SmoodlyEnv;
+export declare const smoodlyEnv: (need?: "site" | "admin") => SmoodlyEnv;
 /** What the browser needs to join the admin's presence channel: the content project's URL, publishable key and space, public values only — never for content reads (spec 2026-09-29 content API contract §8). */
 export type PresenceConfig = {
     url: string;

package/dist/env.js

@@ -1,27 +1,51 @@
 // The one config shape (spec 2026-09-04 §4/§6). Self-host sets three
-// names; the cloud sets five. The two defaults are what keep a single
+// names (the live site alone needs two); the cloud sets five. The two defaults are what keep a single
 // code path: a default for an absent value is not a mode branch.
 import { createSmoodlyClient } from "./client.js";
 import { readCurrentSpace } from "./current-space.js";
-const REQUIRED = ["SMOODLY_URL", "SMOODLY_SECRET_KEY", "SMOODLY_PUBLISHABLE_KEY"];
-export function resolveSmoodlyEnv(env) {
-    const missing = REQUIRED.filter((name) => !env[name]);
-    if (missing.length > 0) {
-        throw new Error(`smoodly: set ${missing.join(", ")} — see .env.local.example.`);
+const SITE_NEEDS = ["SMOODLY_URL", "SMOODLY_SECRET_KEY"];
+const ADMIN_NEEDS = [...SITE_NEEDS, "SMOODLY_PUBLISHABLE_KEY"];
+const DEPLOYING = "https://smoodly.io/docs/getting-started/deploying";
+const isJwt = (v) => v.split(".").length === 3;
+/** A legacy JWT key's role claim ("anon", "service_role"; "authenticated" for a cloud space key); null when it cannot be read. */
+function jwtRole(v) {
+    if (!isJwt(v))
+        return null;
+    try {
+        const role = JSON.parse(atob(v.split(".")[1].replace(/-/g, "+").replace(/_/g, "/"))).role;
+        return typeof role === "string" ? role : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The live site reads with the URL and the secret key; the admin and presence also need the
+ *  publishable key, so their callers pass "admin" (spec 2026-09-30 tester findings §4). A key
+ *  in the wrong variable or of no known form is named here, not by a failed read later. */
+export function resolveSmoodlyEnv(env, need = "site") {
+    const missing = (need === "admin" ? ADMIN_NEEDS : SITE_NEEDS).filter((name) => !env[name]);
+    if (missing.length > 0)
+        throw new Error(`smoodly: set ${missing.join(", ")} in .env.local (Deploying: ${DEPLOYING}).`);
+    const secretKey = env.SMOODLY_SECRET_KEY;
+    const publishableKey = env.SMOODLY_PUBLISHABLE_KEY ?? "";
+    if (secretKey.startsWith("sb_publishable_") || jwtRole(secretKey) === "anon") {
+        throw new Error("smoodly: SMOODLY_SECRET_KEY holds a publishable key — copy the secret (service-role) key from your Supabase project.");
+    }
+    if (!secretKey.startsWith("sb_secret_") && !isJwt(secretKey)) {
+        throw new Error("smoodly: SMOODLY_SECRET_KEY is neither an sb_secret_ key nor a JWT — copy the secret (service-role) key from your Supabase project.");
+    }
+    if (publishableKey.startsWith("sb_secret_") || jwtRole(publishableKey) === "service_role") {
+        throw new Error("smoodly: SMOODLY_PUBLISHABLE_KEY holds a secret key — it reaches the browser; copy the publishable (anon) key from your Supabase project.");
+    }
+    if (publishableKey && !publishableKey.startsWith("sb_publishable_") && !isJwt(publishableKey)) {
+        throw new Error("smoodly: SMOODLY_PUBLISHABLE_KEY is neither an sb_publishable_ key nor a JWT — copy the publishable (anon) key from your Supabase project.");
     }
     const url = env.SMOODLY_URL;
-    const publishableKey = env.SMOODLY_PUBLISHABLE_KEY;
-    return {
-        url,
-        secretKey: env.SMOODLY_SECRET_KEY,
-        publishableKey,
-        authUrl: env.SMOODLY_AUTH_URL || url,
-        authKey: env.SMOODLY_AUTH_KEY || publishableKey,
-    };
+    return { url, secretKey, publishableKey, authUrl: env.SMOODLY_AUTH_URL || url, authKey: env.SMOODLY_AUTH_KEY || publishableKey };
 }
 /** `resolveSmoodlyEnv(process.env)` — call lazily, never at module load,
  *  so `next build` without env still succeeds. */
-export const smoodlyEnv = () => resolveSmoodlyEnv(process.env);
+export const smoodlyEnv = (need = "site") => resolveSmoodlyEnv(process.env, need);
 /** One lookup per process per content project and key: the space never
  *  changes for a key. A failed lookup is not cached, so the next call retries. */
 const spaces = new Map();

package/dist/index.d.ts

@@ -66,7 +66,8 @@ 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, Values } from "./schema.ts";
+export type { SectionSchema, ElementSchema, BuilderMap, Values, StoredValues } from "./schema.ts";
+export { node } from "./content/node.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";
@@ -97,7 +98,7 @@ export declare const smoodly: {
                 omit: string[];
             };
             css?: false;
-            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;
+            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;
@@ -111,7 +112,7 @@ export declare const smoodly: {
                 omit: string[];
             };
             css?: false;
-            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;
+            sample?: Partial<import("./schema.ts").StoredValues<F> & import("./schema.ts").StoredValues<S>> | undefined;
         } & {
             contexts: ("richtext" | "column")[];
         }): import("./schema.ts").ElementSchema<F, S>;

package/dist/index.js

@@ -46,6 +46,7 @@ export { fixedPathFor } from "./localize.js";
 export { addressMap, assertAddress, codeAddresses, collectionKey, lastPart, ownerCollection, pageKey } from "./addresses.js";
 export { anchorUrl, anchorsFor, candidates, fullPath, pickHit } from "./anchors.js";
 export { pathOptions, pageErrors, localeRow, pageRefEdges, DEFAULT_LOCALES } from "./store.js";
+export { node } from "./content/node.js";
 export { DEFAULT_TOOLSET } from "./toolset.js";
 export { collectionOrder, collectionDepth, DEFAULT_ORDER } from "./collections.js";
 export { GLOBAL_NODE_TYPE, SETTINGS_KEY, STYLES_KEY, CSS_KEY, globalLink } from "./global.js";

package/dist/member-store.d.ts

@@ -21,6 +21,13 @@ export interface MemberStore {
     consoleUrl(): Promise<string | null>;
     /** Creates or finds the Auth user for the email, mails the invite when it created one, upserts the row (spec 2026-09-25 members management §3). */
     invite(input: InviteInput): Promise<InviteResult>;
+    /** Creates the Auth user with a password (confirmed, no mail) and upserts the row — the installer's first editor, `add-admin`.
+     *  An existing account keeps its password and only gains the membership. */
+    createAccount(input: {
+        email: string;
+        password: string;
+        role: MemberRole;
+    }): Promise<MemberRecord>;
     setRole(userId: string, role: MemberRole): Promise<MemberRecord>;
     /** Deletes the member row only; the Auth account stays. */
     remove(userId: string): Promise<void>;
@@ -44,6 +51,11 @@ export declare class MemoryMemberStore implements MemberStore {
     list(): Promise<MemberRecord[]>;
     consoleUrl(): Promise<string | null>;
     invite(input: InviteInput): Promise<InviteResult>;
+    createAccount(input: {
+        email: string;
+        password: string;
+        role: MemberRole;
+    }): Promise<MemberRecord>;
     setRole(userId: string, role: MemberRole): Promise<MemberRecord>;
     remove(userId: string): Promise<void>;
 }

package/dist/member-store.js

@@ -44,6 +44,14 @@ export class MemoryMemberStore {
         this.rows = [...this.rows.filter((r) => r.userId !== userId), member];
         return { member, invited };
     }
+    async createAccount(input) {
+        const key = input.email.toLowerCase();
+        const userId = this.accounts[key] ?? this.rows.find((r) => r.email?.toLowerCase() === key)?.userId ?? crypto.randomUUID();
+        this.accounts[key] = userId;
+        const member = { userId, email: input.email, role: input.role };
+        this.rows = [...this.rows.filter((r) => r.userId !== userId), member];
+        return member;
+    }
     async setRole(userId, role) {
         const row = this.rows.find((r) => r.userId === userId);
         if (!row)

package/dist/model-key.d.ts

@@ -0,0 +1 @@
+export declare function modelKey(model: unknown): string;

package/dist/model-key.js

@@ -0,0 +1,36 @@
+// A short, stable hash of the registered model (spec 2026-09-30 tester findings §3):
+// object keys sorted, functions dropped, cycles cut — two processes agree.
+// Plain arithmetic, no node:crypto: the root entry is imported by client sections too.
+function canonical(value, seen) {
+    if (typeof value === "function" || value === undefined)
+        return undefined;
+    if (value === null || typeof value !== "object")
+        return value;
+    if (seen.has(value))
+        return "[cycle]";
+    seen.add(value);
+    const out = Array.isArray(value)
+        ? value.map((v) => canonical(v, seen) ?? null)
+        : Object.fromEntries(Object.keys(value).sort().flatMap((k) => {
+            const v = canonical(value[k], seen);
+            return v === undefined ? [] : [[k, v]];
+        }));
+    seen.delete(value);
+    return out;
+}
+/** Two 32-bit FNV-1a style runs with different seeds (cyrb53's mixing): 64 bits, of which 48 are kept. */
+function hash(text) {
+    let h1 = 0xdeadbeef, h2 = 0x41c6ce57;
+    for (let i = 0; i < text.length; i++) {
+        const c = text.charCodeAt(i);
+        h1 = Math.imul(h1 ^ c, 2654435761);
+        h2 = Math.imul(h2 ^ c, 1597334677);
+    }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+    h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+    const hex = (n) => (n >>> 0).toString(16).padStart(8, "0");
+    return (hex(h2) + hex(h1)).slice(0, 12);
+}
+export function modelKey(model) {
+    return hash(JSON.stringify(canonical(model, new WeakSet())));
+}

package/dist/next/page-renderer.js

@@ -39,7 +39,7 @@ export function createPageRenderer(options) {
         // 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).
-        return unstable_cache(() => site.load(target, locale, path), ["smoodly-site", locale, path, target.kind, target.id], {
+        return unstable_cache(() => site.load(target, locale, path), ["smoodly-site", site.cacheKey, locale, path, target.kind, target.id], {
             tags: [target.kind === "page" ? pageTag(target.id) : entryTag(target.id)],
         })();
     }
@@ -114,7 +114,8 @@ export function createPageRenderer(options) {
         const target = await site.locate(locale, path);
         if (target?.redirect)
             await redirectTo(target, locale, params);
-        const hit = target ? await load(target, locale, path, draft, version) : null;
+        // A code-owned address with no record yet is served from code (spec 2026-09-30 tester findings §2).
+        const hit = target ? await load(target, locale, path, draft, version) : site.codePage(locale, path);
         if (!hit || !accept(hit))
             notFound();
         // The draft marker tells the page editor's canvas diagnosis that Smoodly
@@ -129,9 +130,9 @@ export function createPageRenderer(options) {
         const path = pathFor(locale);
         const { isEnabled: draft } = await draftMode();
         const target = await site.locate(locale, path);
-        if (!target || target.redirect)
+        if (target?.redirect)
             return {};
-        const hit = await load(target, locale, path, draft);
+        const hit = target ? await load(target, locale, path, draft) : site.codePage(locale, path);
         if (!hit || !accept(hit))
             return {};
         // A page type without seo: true still gets its page title as <title>; seo: true adds the panel's values on top.
@@ -153,7 +154,7 @@ export function createPageRenderer(options) {
         const { isEnabled: draft } = await draftMode();
         if (draft)
             return site.getGlobal(item, { locale, draft: true });
-        return unstable_cache(() => site.getGlobal(item, { locale }), ["smoodly-global", item.name, locale], {
+        return unstable_cache(() => site.getGlobal(item, { locale }), ["smoodly-global", site.cacheKey, item.name, locale], {
             tags: [globalTag(item.name)],
         })();
     }

package/dist/next/queries.js

@@ -36,7 +36,7 @@ export function createSmoodlyQueries(options) {
         const { isEnabled: draft } = await draftMode();
         if (draft)
             return read(true);
-        return unstable_cache(() => read(false), ["smoodly-q", ...key], { tags })();
+        return unstable_cache(() => read(false), ["smoodly-q", site.cacheKey, ...key], { tags })();
     }
     /** The tag needs the id: a path is located first, uncached, as the renderer does. */
     async function idOf(kind, locale, pathOrId) {

package/dist/schema-read.d.ts

@@ -0,0 +1,7 @@
+import type { SupabaseClient } from "@supabase/supabase-js";
+/** The policies show `smoodly_meta` to a write key only, so no visible row means the key is not a secret key (spec §5). */
+export declare function readSchemaVersion(db: SupabaseClient): Promise<{
+    version: number;
+} | {
+    missing: "key" | "schema";
+}>;

package/dist/schema-read.js

@@ -0,0 +1,15 @@
+import { SCHEMA_VERSION_KEY } from "./schema-version.js";
+/** The policies show `smoodly_meta` to a write key only, so no visible row means the key is not a secret key (spec §5). */
+export async function readSchemaVersion(db) {
+    const res = await db.from("smoodly_meta").select("value").eq("key", SCHEMA_VERSION_KEY).maybeSingle();
+    if (res.error) {
+        // PGRST205: not in PostgREST's schema cache; 42P01: undefined table; 42501: no grant.
+        if (res.error.code === "PGRST205" || res.error.code === "42P01")
+            return { missing: "schema" };
+        if (res.error.code === "42501")
+            return { missing: "key" };
+        throw new Error(`smoodly: reading the schema version: ${res.error.message}`);
+    }
+    const n = Number(res.data?.value);
+    return res.data && Number.isInteger(n) ? { version: n } : { missing: "key" };
+}

package/dist/schema-version.d.ts

@@ -15,3 +15,5 @@ export declare function schemaVersionSQL(version: number): string;
  *  bump, and is fine. */
 export declare const schemaBehind: (database: number | null, required?: number) => boolean;
 export declare function schemaBehindMessage(database: number | null, required?: number): string;
+/** The version row is hidden from anything but a secret key, so an invisible row means the wrong key, not an old schema. */
+export declare const secretKeyRefusedMessage = "smoodly: SMOODLY_SECRET_KEY cannot read the schema version \u2014 it is not the project's secret (service-role) key; the publishable key there is the usual mix-up.";

package/dist/schema-version.js

@@ -28,5 +28,7 @@ export function schemaVersionSQL(version) {
 export const schemaBehind = (database, required = SCHEMA_VERSION) => database === null || database < required;
 export function schemaBehindMessage(database, required = SCHEMA_VERSION) {
     return (`smoodly: the database schema is at version ${database ?? "none"}; this Smoodly needs version ${required}. ` +
-        "Run `npx smoodly migrate`, then `supabase db push` (hosted) or `supabase db reset` (local).");
+        "Run `npx smoodly migrate`, then apply it: `supabase db push` (hosted) or `supabase migration up` (local).");
 }
+/** The version row is hidden from anything but a secret key, so an invisible row means the wrong key, not an old schema. */
+export const secretKeyRefusedMessage = "smoodly: SMOODLY_SECRET_KEY cannot read the schema version — it is not the project's secret (service-role) key; the publishable key there is the usual mix-up.";

package/dist/schema.d.ts

@@ -2,6 +2,7 @@ import { type Descriptor, type FieldBuilder, type ValueOf } from "./fields.ts";
 import { pageSchema } from "./page.ts";
 import type { RefTo } from "./fields.ts";
 import type { EntryRef } from "./read-shapes.ts";
+import type { FileValue, ImageValue, ResolvedFile, ResolvedImage, ResolvedVideo, VideoValue } from "./media.ts";
 export type BuilderMap = Record<string, FieldBuilder<any, any>>;
 export type SectionSchema<F extends BuilderMap = BuilderMap, S extends BuilderMap = BuilderMap> = {
     kind: "section";
@@ -54,9 +55,14 @@ export type Materialize<V> = V extends RefTo<infer T, infer M> ? EntryRef<ShapeO
 export type Values<M extends BuilderMap> = {
     [K in keyof NamespaceValues<M>]: Materialize<NamespaceValues<M>[K]>;
 };
-/** A sample stores ids where a read shows references. */
-type Stored<M extends BuilderMap> = {
-    [K in keyof NamespaceValues<M>]: NamespaceValues<M>[K] extends RefTo<any, any> ? string : NamespaceValues<M>[K] extends RefTo<any, any>[] ? string[] : NamespaceValues<M>[K];
+/** One value as storage holds it: a ref is the entry's id, media is the `{ asset }` value, and lists and
+ *  objects hold the same inside. Richtext (`unknown`) and scalars pass through. */
+export type StoredOf<V> = unknown extends V ? V : V extends RefTo<any, any> ? string : V extends ResolvedImage ? ImageValue : V extends ResolvedVideo ? VideoValue : V extends ResolvedFile ? FileValue : V extends readonly (infer I)[] ? StoredOf<I>[] : V extends Record<string, unknown> ? {
+    [K in keyof V]: StoredOf<V[K]>;
+} : V;
+/** What storage holds for a field map (a sample, a node built from code). */
+export type StoredValues<M extends BuilderMap> = {
+    [K in keyof NamespaceValues<M>]: StoredOf<NamespaceValues<M>[K]>;
 };
 type SectionInput<F extends BuilderMap, S extends BuilderMap> = {
     name: string;
@@ -71,7 +77,7 @@ type SectionInput<F extends BuilderMap, S extends BuilderMap> = {
         omit: string[];
     };
     css?: false;
-    sample?: Partial<Stored<F> & Stored<S>>;
+    sample?: Partial<StoredValues<F> & StoredValues<S>>;
 };
 export declare const schema: {
     page: typeof pageSchema;

package/dist/site.d.ts

@@ -108,6 +108,9 @@ export type LoadOptions = {
 export interface SmoodlySite {
     readonly locales: LocaleSet;
     readonly homePageSlug: string;
+    /** The package version and a hash of the registered model: a part of every cache key, so an upgrade or a
+     *  model change never serves a unit cached in the old shape (spec 2026-09-30 tester findings §3). */
+    readonly cacheKey: string;
     /** The resolved styles values the renderer and `getGlobal` hand the wrapper. */
     readonly styles: StyleValues;
     /** The custom section's resolved options the renderer hands renderPage. */
@@ -119,6 +122,11 @@ export interface SmoodlySite {
     /** Everything the renderer needs for one target: null when it is a folder, unpublished (outside draft), or gone. */
     load(target: PathTarget, locale: string, path: string, options?: LoadOptions): Promise<SiteHit | null>;
     resolve(locale: string, path: string, options?: LoadOptions): Promise<SiteHit | null>;
+    /** A fixed page type (or a collection's index page) as code alone describes it, when `path` is its address in
+     *  `locale`: an empty tree, the page fields' defaults, the registration's title. The renderer serves it where
+     *  the index has no row — a page type added after install, a locale added to the config — until the admin
+     *  makes the record (spec 2026-09-30 tester findings §2). Not in `getPagesTree`: that lists records. */
+    codePage(locale: string, path: string): SitePage | null;
     getPagesTree(options?: {
         locale?: string;
         draft?: boolean;