smoodly 0.0.24 → 0.0.25

package/dist/admin/validate.d.ts

@@ -22,6 +22,10 @@ export type ElementDescs = Record<string, {
     fields: Record<string, Desc>;
     settings?: Record<string, Desc>;
 }>;
+/** The errors of `previous` that a fresh validation still reports, with the
+ *  fresh message: a form's refusal list shrinks as its fields are fixed and
+ *  never grows from typing (2026-09-25) — only a publish adds. */
+export declare function stillFailing(previous: Record<string, string>, fresh: FieldError[]): Record<string, string>;
 /** Validate one value map. Without `scope.fields` the values ARE the fields (an entry, a page, an object global). */
 export declare function validateFields(values: Record<string, unknown>, descriptors: Record<string, Desc>, elements?: ElementDescs, scope?: ValidationScope): FieldError[];
 /** A tree node (or a visual global, in node shape) against its schema: fields, settings (prefixed), css (spec 2026-09-14 §3, §4). */

package/dist/admin/validate.js

@@ -12,14 +12,21 @@ import { normalizeTag, sameTag } from "../tags.js";
 import { hasContent } from "./richtext-doc.js";
 import { ELEMENT_NODE, richtextBlocks } from "../richtext-walk.js";
 import { rowsProblems } from "../custom/rows.js";
+import { isCalendarDay, isInstant } from "./forms/date-picker.js";
 const subfields = (d) => d.fields && typeof d.fields === "object" ? d.fields : {};
 const itemOf = (d) => d.item && typeof d.item === "object" ? d.item : undefined;
 const isEmpty = (v) => v === undefined || v === null || v === "" || (Array.isArray(v) && v.length === 0);
+/** An object holding nothing but empty values, at any depth — `{}`, `{ label: "" }`. */
+const isBlankObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v) &&
+    Object.values(v).every((x) => isEmpty(x) || isBlankObject(x));
 /** An object whose every subfield is optional — or is itself an object that
  *  may be absent — may be absent altogether. */
 const mayBeAbsent = (d) => d.optional === true || d.type === "boolean" || (d.type === "object" && Object.values(subfields(d)).every(mayBeAbsent));
 const plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
 function validateValue(path, value, d, errors, elements, scope) {
+    // An optional object with nothing filled in is absent (drafts inserted before 2026-09-26 carry `{}`).
+    if (d.type === "object" && d.optional === true && isBlankObject(value))
+        return;
     if (isEmpty(value)) {
         if (!mayBeAbsent(d))
             errors.push({ field: path, message: "Required." });
@@ -49,6 +56,17 @@ function validateValue(path, value, d, errors, elements, scope) {
         }
         return;
     }
+    // Dates (spec 2026-09-25 date pickers §2): the stored formats exactly, and a day the calendar has.
+    if (d.type === "date") {
+        if (typeof value !== "string" || !isCalendarDay(value))
+            errors.push({ field: path, message: "Not a date (2026-09-02)." });
+        return;
+    }
+    if (d.type === "datetime") {
+        if (typeof value !== "string" || !isInstant(value))
+            errors.push({ field: path, message: "Not a date and time." });
+        return;
+    }
     if (d.type === "image" || d.type === "video" || d.type === "file") {
         if (typeof value !== "object" || Array.isArray(value) || typeof value.asset !== "string") {
             errors.push({ field: path, message: "Must be an uploaded file." });
@@ -151,6 +169,16 @@ function validateMap(prefix, values, descriptors, errors, elements, scope) {
         validateValue(prefix === "" ? key : `${prefix}.${key}`, values[key], d, errors, elements, scope);
     }
 }
+/** The errors of `previous` that a fresh validation still reports, with the
+ *  fresh message: a form's refusal list shrinks as its fields are fixed and
+ *  never grows from typing (2026-09-25) — only a publish adds. */
+export function stillFailing(previous, fresh) {
+    const out = {};
+    for (const e of fresh)
+        if (e.field in previous)
+            out[e.field] = e.message;
+    return out;
+}
 /** Validate one value map. Without `scope.fields` the values ARE the fields (an entry, a page, an object global). */
 export function validateFields(values, descriptors, elements = {}, scope = {}) {
     const errors = [];

package/dist/cli/load-collections.d.ts

@@ -0,0 +1,2 @@
+import type { CollectionSchema } from "../collections.ts";
+export declare function loadCollections(file: string, cwd: string): Promise<CollectionSchema<any>[]>;

package/dist/cli/load-collections.js

@@ -0,0 +1,26 @@
+// packages/smoodly/src/cli/load-collections.ts
+// Loads the app's `smoodly/collections.ts` — TypeScript, through tsx's
+// import API, under the app's own tsconfig so its `@/` alias resolves.
+// The barrel and not `smoodly/config.ts`: the config imports the page
+// shapes and with them React and Next, which a command line has no use
+// for; the barrel is what the config registers in both starters.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { tsImport } from "tsx/esm/api";
+export async function loadCollections(file, cwd) {
+    if (!existsSync(file)) {
+        throw new Error(`smoodly: ${file} does not exist — pass --collections <file> for the module that exports \`collections\`.`);
+    }
+    const tsconfig = join(cwd, "tsconfig.json");
+    const mod = (await tsImport(pathToFileURL(file).href, {
+        parentURL: import.meta.url,
+        ...(existsSync(tsconfig) ? { tsconfig } : {}),
+    }));
+    const list = mod.collections;
+    const isCollection = (c) => typeof c === "object" && c !== null && typeof c.name === "string";
+    if (!Array.isArray(list) || !list.every(isCollection)) {
+        throw new Error(`smoodly: ${file} must export \`collections\`, the list of smoodly.collection() definitions the config registers.`);
+    }
+    return list;
+}

package/dist/cli/main.d.ts

@@ -0,0 +1,13 @@
+import { type MigrateArgs } from "./migrate.ts";
+export declare const USAGE = "usage: smoodly migrate [--check] [--collections <file>] [--migrations <dir>]\n\n  Copies the core schema files this package ships that supabase/migrations/\n  lacks, and writes one views file for the collections whose view is new or\n  changed. Prints the push or reset command; never runs it.\n\n  --check              write nothing; exit 1 when anything is pending\n  --collections <file> the module exporting `collections` (default smoodly/collections.ts)\n  --migrations <dir>   the app's migration folder (default supabase/migrations)";
+export type Parsed = {
+    command: "migrate";
+    args: MigrateArgs;
+} | {
+    command: "help";
+} | {
+    command: "error";
+    message: string;
+};
+export declare function parseArgs(argv: string[]): Parsed;
+export declare function main(argv: string[], out?: (line: string) => void): Promise<number>;

package/dist/cli/main.js

@@ -0,0 +1,62 @@
+// packages/smoodly/src/cli/main.ts
+// `smoodly` — the package's command line (spec 2026-09-26 §2). One
+// subcommand for now; `check`, `export` and the drift report land here
+// later. Exit codes: 0 done or nothing to do, 1 pending (--check) or a
+// refused file, 2 usage.
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runMigrate } from "./migrate.js";
+export const USAGE = `usage: smoodly migrate [--check] [--collections <file>] [--migrations <dir>]
+
+  Copies the core schema files this package ships that supabase/migrations/
+  lacks, and writes one views file for the collections whose view is new or
+  changed. Prints the push or reset command; never runs it.
+
+  --check              write nothing; exit 1 when anything is pending
+  --collections <file> the module exporting \`collections\` (default smoodly/collections.ts)
+  --migrations <dir>   the app's migration folder (default supabase/migrations)`;
+export function parseArgs(argv) {
+    const [command, ...rest] = argv;
+    if (!command || command === "--help" || command === "-h" || command === "help")
+        return { command: "help" };
+    if (command !== "migrate")
+        return { command: "error", message: `unknown command "${command}"` };
+    const args = { check: false, collections: "smoodly/collections.ts", migrations: "supabase/migrations" };
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        if (a === "--check")
+            args.check = true;
+        else if (a === "--collections" && rest[i + 1] !== undefined)
+            args.collections = rest[++i];
+        else if (a === "--migrations" && rest[i + 1] !== undefined)
+            args.migrations = rest[++i];
+        else
+            return { command: "error", message: `unexpected argument "${a}"` };
+    }
+    return { command: "migrate", args };
+}
+export async function main(argv, out = console.log) {
+    const parsed = parseArgs(argv);
+    if (parsed.command === "help") {
+        out(USAGE);
+        return 0;
+    }
+    if (parsed.command === "error") {
+        out(`smoodly: ${parsed.message}\n\n${USAGE}`);
+        return 2;
+    }
+    try {
+        return await runMigrate(parsed.args, out);
+    }
+    catch (e) {
+        out(e instanceof Error ? e.message : String(e));
+        return 1;
+    }
+}
+// Run when this file is the entry (`tsx src/cli/main.ts …`, the repo's
+// `npm run db:migrate`); the published bin imports `main` and runs it itself.
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(new URL(import.meta.url))) {
+    void main(process.argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    });
+}

package/dist/cli/migrate.d.ts

@@ -0,0 +1,23 @@
+import type { CollectionSchema } from "../collections.ts";
+import { type MigrationFile, type MigratePlan } from "../migrations.ts";
+export type MigrateArgs = {
+    check: boolean;
+    collections: string;
+    migrations: string;
+};
+/** The folder shipped in the package: `../../migrations/` from dist/cli/ and from src/cli/ alike. */
+export declare const PACKAGE_MIGRATIONS_DIR: string;
+export declare const NO_FOLDER = "No supabase/migrations folder here \u2014 nothing to do. (Smoodly Cloud keeps the schema current; a self-host app gets the folder from `supabase init`.)";
+export declare const NEXT_STEP = "Next: apply it \u2014 `supabase db push` (hosted) or `supabase db reset` (local).";
+export declare const upToDate: (version: number, n: number) => string;
+export declare const modifiedMessage: (name: string) => string;
+export declare function readSqlFiles(dir: string): Promise<MigrationFile[]>;
+/** One line per thing the plan does; "Pending" wording under --check. */
+export declare function describePlan(plan: MigratePlan, check: boolean): string[];
+export type MigrateDeps = {
+    cwd?: string;
+    /** Test seam: replaces the tsx loader. */
+    load?: (file: string, cwd: string) => Promise<CollectionSchema<any>[]>;
+    now?: () => Date;
+};
+export declare function runMigrate(args: MigrateArgs, out: (line: string) => void, deps?: MigrateDeps): Promise<number>;

package/dist/cli/migrate.js

@@ -0,0 +1,64 @@
+// packages/smoodly/src/cli/migrate.ts
+// The filesystem half of `smoodly migrate` (spec 2026-09-26 §2): reads
+// the package's migrations/ and the app's supabase/migrations/, loads the
+// app's collections, asks the pure planner (../migrations.ts) what to
+// write, writes it. The message strings are what the docs quote.
+import { existsSync } from "node:fs";
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { collectionSQL } from "../sql.js";
+import { coreFileVersion, SCHEMA_VERSION } from "../schema-version.js";
+import { planIsEmpty, planMigrate } from "../migrations.js";
+import { loadCollections } from "./load-collections.js";
+/** The folder shipped in the package: `../../migrations/` from dist/cli/ and from src/cli/ alike. */
+export const PACKAGE_MIGRATIONS_DIR = fileURLToPath(new URL("../../migrations/", import.meta.url));
+export const NO_FOLDER = "No supabase/migrations folder here — nothing to do. (Smoodly Cloud keeps the schema current; a self-host app gets the folder from `supabase init`.)";
+export const NEXT_STEP = "Next: apply it — `supabase db push` (hosted) or `supabase db reset` (local).";
+export const upToDate = (version, n) => `Up to date: core schema v${version}, every collection's view is current (${n} ${n === 1 ? "collection" : "collections"}).`;
+export const modifiedMessage = (name) => `Refusing: ${name} differs from the package's copy. A published migration is never edited — restore it from the package, or move your change to a new file.`;
+export async function readSqlFiles(dir) {
+    const names = (await readdir(dir)).filter((n) => n.endsWith(".sql")).sort();
+    return Promise.all(names.map(async (name) => ({ name, text: await readFile(join(dir, name), "utf8") })));
+}
+/** One line per thing the plan does; "Pending" wording under --check. */
+export function describePlan(plan, check) {
+    const lines = [];
+    for (const name of plan.modified)
+        lines.push(modifiedMessage(name));
+    for (const f of plan.copy)
+        lines.push(`${check ? "Pending" : "Copied"} ${f.name} (core schema v${coreFileVersion(f.name)}).`);
+    if (plan.views) {
+        const names = [...plan.views.text.matchAll(/^-- smoodly:collection (\S+)/gm)].map((m) => m[1]);
+        lines.push(`${check ? "Pending" : "Wrote"} ${plan.views.name} (views: ${names.join(", ")}).`);
+    }
+    return lines;
+}
+export async function runMigrate(args, out, deps = {}) {
+    const cwd = deps.cwd ?? process.cwd();
+    const appDir = resolve(cwd, args.migrations);
+    if (!existsSync(appDir)) {
+        out(NO_FOLDER);
+        return 0;
+    }
+    const collections = await (deps.load ?? loadCollections)(resolve(cwd, args.collections), cwd);
+    const plan = planMigrate({
+        packageFiles: await readSqlFiles(PACKAGE_MIGRATIONS_DIR),
+        appFiles: await readSqlFiles(appDir),
+        collections: collections.map((c) => ({ name: c.name, sql: collectionSQL(c) })),
+    }, (deps.now ?? (() => new Date()))());
+    for (const line of describePlan(plan, args.check))
+        out(line);
+    if (plan.modified.length > 0)
+        return 1;
+    if (planIsEmpty(plan)) {
+        out(upToDate(SCHEMA_VERSION, collections.length));
+        return 0;
+    }
+    if (args.check)
+        return 1;
+    for (const f of [...plan.copy, ...(plan.views ? [plan.views] : [])])
+        await writeFile(join(appDir, f.name), f.text, "utf8");
+    out(NEXT_STEP);
+    return 0;
+}

package/dist/config.d.ts

@@ -32,6 +32,10 @@ export type SmoodlyConfig = {
         default: string;
         supported: string[];
     };
+    /** The site's time zone, an IANA name such as "Europe/Helsinki" (spec
+     *  2026-09-25 date pickers §5): editors pick datetimes in it, views
+     *  format with it. Absent = the editor's browser zone. */
+    timeZone?: string;
     /** `tree.depth` — how deep editors may nest pages. Absent = flat. */
     pages?: {
         tree?: {

package/dist/config.js

@@ -3,6 +3,7 @@ import { DEFAULT_MEDIA } from "./media.js";
 import { DEFAULT_ADMIN_PATH, assertAdminPath, isAdminSlug } from "./admin-path.js";
 import { resolveStyleValues, styleDescriptors } from "./styles.js";
 import { resolveCustom } from "./custom/index.js";
+import { isValidZone } from "./time-zone.js";
 /** `global`: the placement node type and an admin route; `asset`: the refs
  *  target of every media edge; `media`: the admin's Media screen route. */
 export const RESERVED_NAMES = ["global", "asset", "media"];
@@ -135,6 +136,13 @@ function assertLocales(config) {
     if (!supported.includes(def))
         throw new Error(`smoodly: the default locale "${def}" is not in the supported list.`);
 }
+function assertTimeZone(config) {
+    if (config.timeZone === undefined)
+        return;
+    if (!isValidZone(config.timeZone)) {
+        throw new Error(`smoodly: timeZone "${config.timeZone}" is not a time zone this runtime knows — use an IANA name such as "Europe/Helsinki".`);
+    }
+}
 /** Every element name a richtext toolset embeds, walking objects and lists. */
 function toolsetElementNames(descriptors, out) {
     for (const d of Object.values(descriptors ?? {})) {
@@ -174,6 +182,7 @@ function assertToolsetElements(config) {
 }
 export function defineConfig(config) {
     assertLocales(config);
+    assertTimeZone(config);
     assertUniqueNames(config);
     assertGlobalSections(config);
     assertToolsetElements(config);

package/dist/fields.d.ts

@@ -74,6 +74,8 @@ export declare const f: {
         from?: string;
     }) => FieldBuilder<string, {}>;
     date: () => FieldBuilder<string, {}>;
+    /** A UTC instant to the minute, "2026-09-02T14:30:00Z" (spec 2026-09-25 date pickers §1). */
+    datetime: () => FieldBuilder<string, {}>;
     number: () => FieldBuilder<number, {}>;
     /** `aspect`: one `"w:h"` or several the crop tool may lock to — a per-use
      *  constraint, so the component knows its box before the image loads. */

package/dist/fields.js

@@ -81,6 +81,8 @@ export const f = {
     link: () => builder({ type: "link" }),
     slug: (opts) => builder({ type: "slug", ...(opts?.from ? { from: opts.from } : {}) }),
     date: () => builder({ type: "date" }),
+    /** A UTC instant to the minute, "2026-09-02T14:30:00Z" (spec 2026-09-25 date pickers §1). */
+    datetime: () => builder({ type: "datetime" }),
     number: () => builder({ type: "number" }),
     /** `aspect`: one `"w:h"` or several the crop tool may lock to — a per-use
      *  constraint, so the component knows its box before the image loads. */

package/dist/index.d.ts

@@ -27,6 +27,7 @@ export type { Crop, Hotspot, AssetKind, ImageValue, VideoValue, FileValue, Asset
 export { z } from "./zones.ts";
 export { defineConfig } from "./config.ts";
 export { collectionSQL, coreTablesSQL } from "./sql.ts";
+export { SCHEMA_VERSION, SCHEMA_VERSION_KEY, schemaVersionSQL, coreFileVersion, schemaBehind, schemaBehindMessage } from "./schema-version.ts";
 export { MemoryPageStore } from "./store.ts";
 export { MemoryAssetStore, assetErrors, kindOf, extensionFor, objectPath, withDownload, PAGE_SIZE as ASSET_PAGE_SIZE } from "./asset-store.ts";
 export type { AssetStore, UploadTicket, FinishInput, AssetQuery, AssetPage, BeginUploadInput, CreateAssetInput } from "./asset-store.ts";
@@ -150,7 +151,7 @@ export declare const smoodly: {
     Section: typeof Section;
     marks: typeof marks;
 };
-export { NODE_ATTR, ZONE_ATTR, EMPTY_ATTR, FIELD_ATTR, ITEM_ATTR, EDITOR_ATTR, resolveMarkPath } from "./marks.ts";
+export { NODE_ATTR, ZONE_ATTR, EMPTY_ATTR, BLANK_ATTR, FIELD_ATTR, ITEM_ATTR, EDITOR_ATTR, resolveMarkPath } from "./marks.ts";
 export type { MarkNode, MarkPath, Marks, Scope } from "./marks.ts";
 export { resolveSmoodlyEnv, smoodlyEnv } from "./env.ts";
 export type { SmoodlyEnv } from "./env.ts";

package/dist/index.js

@@ -21,6 +21,7 @@ export { ASSET_COLLECTION, DEFAULT_MEDIA, MEDIA_TYPES, FULL_CROP, CENTER_HOTSPOT
 export { z } from "./zones.js";
 export { defineConfig } from "./config.js";
 export { collectionSQL, coreTablesSQL } from "./sql.js";
+export { SCHEMA_VERSION, SCHEMA_VERSION_KEY, schemaVersionSQL, coreFileVersion, schemaBehind, schemaBehindMessage } from "./schema-version.js";
 export { MemoryPageStore } from "./store.js";
 export { MemoryAssetStore, assetErrors, kindOf, extensionFor, objectPath, withDownload, PAGE_SIZE as ASSET_PAGE_SIZE } from "./asset-store.js";
 export { imageDimensions } from "./image-dimensions.js";
@@ -61,7 +62,7 @@ export const smoodly = {
     Section,
     marks,
 };
-export { NODE_ATTR, ZONE_ATTR, EMPTY_ATTR, FIELD_ATTR, ITEM_ATTR, EDITOR_ATTR, resolveMarkPath } from "./marks.js";
+export { NODE_ATTR, ZONE_ATTR, EMPTY_ATTR, BLANK_ATTR, FIELD_ATTR, ITEM_ATTR, EDITOR_ATTR, resolveMarkPath } from "./marks.js";
 export { resolveSmoodlyEnv, smoodlyEnv } from "./env.js";
 export { clientOptions, createSmoodlyClient } from "./client.js";
 export { createSmoodlySite, pageContextOf } from "./site.js";

package/dist/marks.d.ts

@@ -4,6 +4,9 @@ export declare const NODE_ATTR = "data-smd-node";
 /** An empty zone's placeholder box, from `<Zone>` in editor mode. */
 export declare const ZONE_ATTR = "data-smd-zone";
 export declare const EMPTY_ATTR = "data-smd-empty";
+/** A section that renders no text and no media, stamped by the bridge in
+ *  editor mode so the canvas can give it a height to see and select. */
+export declare const BLANK_ATTR = "data-smd-blank";
 /** The element that renders a field's value verbatim. */
 export declare const FIELD_ATTR = "data-smd-field";
 /** A list item's or object field's root: scopes the field names inside it. */

package/dist/marks.js

@@ -3,6 +3,9 @@ export const NODE_ATTR = "data-smd-node";
 /** An empty zone's placeholder box, from `<Zone>` in editor mode. */
 export const ZONE_ATTR = "data-smd-zone";
 export const EMPTY_ATTR = "data-smd-empty";
+/** A section that renders no text and no media, stamped by the bridge in
+ *  editor mode so the canvas can give it a height to see and select. */
+export const BLANK_ATTR = "data-smd-blank";
 /** The element that renders a field's value verbatim. */
 export const FIELD_ATTR = "data-smd-field";
 /** A list item's or object field's root: scopes the field names inside it. */

package/dist/migrations.d.ts

@@ -0,0 +1,37 @@
+export type MigrationFile = {
+    name: string;
+    text: string;
+};
+export type CollectionSQL = {
+    name: string;
+    sql: string;
+};
+export declare const MARKER_PREFIX = "-- smoodly:collection ";
+/** The first 16 hex chars of sha256 over the exact emitted SQL. */
+export declare const collectionHash: (sql: string) => string;
+export declare const collectionMarker: (c: CollectionSQL) => string;
+/** name → hash, the LAST marker per collection across the files in name order. */
+export declare function parseMarkers(files: MigrationFile[]): Map<string, string>;
+/** UTC yyyyMMddHHmmss — the Supabase CLI's file-name prefix. */
+export declare const stamp: (at: Date) => string;
+/** A views file must sort after every core file it may depend on and
+ *  after any earlier views file it supersedes: the later of `now` and the
+ *  newest own stamp plus a minute. */
+export declare function viewsStamp(names: string[], now: Date): Date;
+/** One file with a block per new or changed collection; null when none changed. */
+export declare function viewsFile(collections: CollectionSQL[], existing: Map<string, string>, at: Date): MigrationFile | null;
+export type CorePending = {
+    copy: MigrationFile[];
+    modified: string[];
+};
+/** Package files the app lacks (copy) and same-named files whose text differs (modified — never overwritten). */
+export declare function pendingCoreFiles(packageFiles: MigrationFile[], appFiles: MigrationFile[]): CorePending;
+export type MigratePlan = CorePending & {
+    views: MigrationFile | null;
+};
+export declare function planMigrate(input: {
+    packageFiles: MigrationFile[];
+    appFiles: MigrationFile[];
+    collections: CollectionSQL[];
+}, now: Date): MigratePlan;
+export declare const planIsEmpty: (plan: MigratePlan) => boolean;

package/dist/migrations.js

@@ -0,0 +1,73 @@
+// packages/smoodly/src/migrations.ts
+// What `npx smoodly migrate` decides, as pure functions over file lists
+// (spec 2026-09-26 §2–§3): which package files the app lacks, which
+// collections need a fresh view block, and the one views file to write.
+// Node-only (crypto): exposed at `smoodly/migrations`, never from the
+// root index, which the client bundle reaches through the config.
+import { createHash } from "node:crypto";
+export const MARKER_PREFIX = "-- smoodly:collection ";
+const MARKER_RE = /^-- smoodly:collection (\S+) sha256:([0-9a-f]+)\s*$/gm;
+const OWN_FILE_RE = /^(\d{14})_smoodly_(v\d+|views)\.sql$/;
+/** The first 16 hex chars of sha256 over the exact emitted SQL. */
+export const collectionHash = (sql) => createHash("sha256").update(sql).digest("hex").slice(0, 16);
+export const collectionMarker = (c) => `${MARKER_PREFIX}${c.name} sha256:${collectionHash(c.sql)}`;
+/** name → hash, the LAST marker per collection across the files in name order. */
+export function parseMarkers(files) {
+    const out = new Map();
+    for (const file of [...files].sort((a, b) => a.name.localeCompare(b.name))) {
+        for (const m of file.text.matchAll(MARKER_RE))
+            out.set(m[1], m[2]);
+    }
+    return out;
+}
+/** UTC yyyyMMddHHmmss — the Supabase CLI's file-name prefix. */
+export const stamp = (at) => at.toISOString().replace(/\D/g, "").slice(0, 14);
+const stampDate = (s) => new Date(Date.UTC(+s.slice(0, 4), +s.slice(4, 6) - 1, +s.slice(6, 8), +s.slice(8, 10), +s.slice(10, 12), +s.slice(12, 14)));
+/** A views file must sort after every core file it may depend on and
+ *  after any earlier views file it supersedes: the later of `now` and the
+ *  newest own stamp plus a minute. */
+export function viewsStamp(names, now) {
+    let at = now;
+    for (const name of names) {
+        const m = OWN_FILE_RE.exec(name);
+        if (!m)
+            continue;
+        const after = new Date(stampDate(m[1]).getTime() + 60000);
+        if (after > at)
+            at = after;
+    }
+    return at;
+}
+/** One file with a block per new or changed collection; null when none changed. */
+export function viewsFile(collections, existing, at) {
+    const changed = collections.filter((c) => existing.get(c.name) !== collectionHash(c.sql));
+    if (changed.length === 0)
+        return null;
+    const text = "-- Smoodly: read views and order indexes for this app's collections, written by `npx smoodly migrate`\n" +
+        `-- (${at.toISOString()}). One block per collection; the marker's hash is the block's SQL, compared on the next run.\n` +
+        "-- Never edit a written file: change the collection and run migrate again.\n\n" +
+        changed.map((c) => `${collectionMarker(c)}\n${c.sql.trim()}`).join("\n\n") +
+        "\n";
+    return { name: `${stamp(at)}_smoodly_views.sql`, text };
+}
+/** Package files the app lacks (copy) and same-named files whose text differs (modified — never overwritten). */
+export function pendingCoreFiles(packageFiles, appFiles) {
+    const app = new Map(appFiles.map((f) => [f.name, f.text]));
+    const copy = [];
+    const modified = [];
+    for (const file of [...packageFiles].sort((a, b) => a.name.localeCompare(b.name))) {
+        const have = app.get(file.name);
+        if (have === undefined)
+            copy.push(file);
+        else if (have !== file.text)
+            modified.push(file.name);
+    }
+    return { copy, modified };
+}
+export function planMigrate(input, now) {
+    const core = pendingCoreFiles(input.packageFiles, input.appFiles);
+    const names = [...input.packageFiles, ...input.appFiles].map((f) => f.name);
+    const views = viewsFile(input.collections, parseMarkers(input.appFiles), viewsStamp(names, now));
+    return { ...core, views };
+}
+export const planIsEmpty = (plan) => plan.copy.length === 0 && plan.modified.length === 0 && plan.views === null;

package/dist/schema-version.d.ts

@@ -0,0 +1,17 @@
+/** The minimum schema version the package needs. Moves ONLY in a release
+ *  that adds a table, column, function or policy the package reads; a
+ *  unit test holds it equal to the highest file in `migrations/`. */
+export declare const SCHEMA_VERSION = 1;
+export declare const SCHEMA_VERSION_KEY = "schema_version";
+export declare const CORE_FILE_RE: RegExp;
+export declare const VIEWS_FILE_RE: RegExp;
+/** The version a core file leaves behind, from its name; null for anything else. */
+export declare function coreFileVersion(name: string): number | null;
+/** The last statement of every core file. */
+export declare function schemaVersionSQL(version: number): string;
+/** Behind blocks the admin and warns on the site (§5). Null = no
+ *  `smoodly_meta` table, a database older than version 1. Ahead is the
+ *  normal state of a cloud app between our migration and its package
+ *  bump, and is fine. */
+export declare const schemaBehind: (database: number | null, required?: number) => boolean;
+export declare function schemaBehindMessage(database: number | null, required?: number): string;

package/dist/schema-version.js

@@ -0,0 +1,32 @@
+// packages/smoodly/src/schema-version.ts
+// The schema version this package needs (spec 2026-09-26 §1) and the two
+// things every side agrees on: the `smoodly_meta` row that records a
+// database's version, and the names of the files the package ships. Pure
+// and framework-free — the SQL emitters, the CLI, the stores, the admin
+// op and the shell all read it from here.
+/** The minimum schema version the package needs. Moves ONLY in a release
+ *  that adds a table, column, function or policy the package reads; a
+ *  unit test holds it equal to the highest file in `migrations/`. */
+export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION_KEY = "schema_version";
+export const CORE_FILE_RE = /^(\d{14})_smoodly_v(\d+)\.sql$/;
+export const VIEWS_FILE_RE = /^(\d{14})_smoodly_views\.sql$/;
+/** The version a core file leaves behind, from its name; null for anything else. */
+export function coreFileVersion(name) {
+    const m = CORE_FILE_RE.exec(name);
+    return m ? Number(m[2]) : null;
+}
+/** The last statement of every core file. */
+export function schemaVersionSQL(version) {
+    return (`insert into "smoodly_meta" ("key", "value") values ('${SCHEMA_VERSION_KEY}', '${version}')\n` +
+        `  on conflict ("key") do update set "value" = excluded."value";`);
+}
+/** Behind blocks the admin and warns on the site (§5). Null = no
+ *  `smoodly_meta` table, a database older than version 1. Ahead is the
+ *  normal state of a cloud app between our migration and its package
+ *  bump, and is fine. */
+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).");
+}

package/dist/sql-space.js

@@ -193,6 +193,12 @@ $$;`.trim());
     statements.push(`drop policy if exists "smoodly_read" on "spaces";\n` +
         `create policy "smoodly_read" on "spaces" for select\n` +
         `  using (${write});`);
+    // The package reads its schema version with the write key (the
+    // service role bypasses anyway); nothing else sees the table. No
+    // space_id: the schema is one per database (spec 2026-09-26 §1).
+    statements.push(`drop policy if exists "smoodly_read" on "smoodly_meta";\n` +
+        `create policy "smoodly_read" on "smoodly_meta" for select\n` +
+        `  using ((select "smoodly_key_kind"()) = 'write' and not (select "smoodly_space_key_revoked"()));`);
     statements.push(storageSQL());
     return statements.join("\n\n");
 }

package/dist/sql.js

@@ -286,6 +286,15 @@ $$;
 -- to anything but a write key. The generated per-collection views
 -- (collectionSQL) run with security_invoker = true, so they are subject
 -- to this same smoodly_read policy rather than their owner's privileges.
+-- smoodly_meta: which version of this schema the database holds (spec
+-- 2026-09-26 §1). One row per database, not per space; every core
+-- migration file upserts the version row as its last statement, and the
+-- package compares it with SCHEMA_VERSION (behind blocks the admin).
+create table if not exists "smoodly_meta" (
+  "key" text primary key,
+  "value" text not null
+);
+
 alter table "pages" enable row level security;
 alter table "page_locales" enable row level security;
 alter table "page_versions" enable row level security;
@@ -295,6 +304,7 @@ alter table "entry_versions" enable row level security;
 alter table "refs" enable row level security;
 alter table "paths" enable row level security;
 alter table "assets" enable row level security;
+alter table "smoodly_meta" enable row level security;
 `.trim(),
         spaceLayerSQL(),
     ].join("\n\n");

package/dist/store.d.ts

@@ -54,6 +54,8 @@ export interface PageStore {
     getPage(id: string): Promise<PageRecord | null>;
     listPages(): Promise<PageRecord[]>;
     resolvePath(locale: string, path: string): Promise<PathTarget | null>;
+    /** The database's schema version from `smoodly_meta`; null when the table is missing (older than v1). Memory: always current (spec 2026-09-26 §5). */
+    schemaVersion(): Promise<number | null>;
     /** locale → path, for the locales the page exists in. */
     pathsOf(id: string): Promise<Record<string, string>>;
     /** Refused when the page already has the locale or its parent lacks it (the parent rule). */
@@ -194,6 +196,7 @@ export declare class MemoryPageStore implements PageStore {
     getPage(id: string): Promise<PageRecord | null>;
     listPages(): Promise<PageRecord[]>;
     resolvePath(locale: string, path: string): Promise<PathTarget | null>;
+    schemaVersion(): Promise<number>;
     pathsOf(id: string): Promise<Record<string, string>>;
     addLocale(id: string, locale: string, options: AddLocaleOptions, by?: string): Promise<PageRecord>;
     removeLocale(id: string, locale: string): Promise<PageRecord>;

package/dist/store.js

@@ -13,6 +13,7 @@ import { ASSET_COLLECTION } from "./media.js";
 import { collectTreeRefs } from "./refs.js";
 import { customToolset, withCustomSchema } from "./custom/index.js";
 import { MemoryPathIndex } from "./path-index.js";
+import { SCHEMA_VERSION } from "./schema-version.js";
 import { assertDepth, assertSegment, assertSupportedLocale, chainOf, isHomeNode, pagePathRows, unsupportedLocale, } from "./paths.js";
 export const DEFAULT_LOCALES = { default: "en", supported: ["en"] };
 /** The section list every adapter walks refs with: the registered ones plus the custom section's schema (spec 2026-09-14 §6). */
@@ -266,6 +267,9 @@ export class MemoryPageStore {
     resolvePath(locale, path) {
         return this.paths.resolve(locale, path);
     }
+    schemaVersion() {
+        return Promise.resolve(SCHEMA_VERSION);
+    }
     pathsOf(id) {
         return this.paths.pathsOf({ kind: "page", id });
     }

package/dist/supabase-store.d.ts

@@ -48,7 +48,10 @@ export declare class SupabasePageStore implements PageStore {
     createPage(input: CreatePageInput, by?: string): Promise<PageRecord>;
     getPage(id: string): Promise<PageRecord | null>;
     listPages(): Promise<PageRecord[]>;
+    /** The site's one warning per process (spec 2026-09-26 §5): fired by the first locate, never blocking. */
+    private schemaChecked;
     resolvePath(locale: string, path: string): Promise<PathTarget | null>;
+    schemaVersion(): Promise<number | null>;
     pathsOf(id: string): Promise<{}>;
     addLocale(id: string, locale: string, options: AddLocaleOptions, by?: string): Promise<PageRecord>;
     removeLocale(id: string, locale: string): Promise<PageRecord>;