smoodly 0.0.6 → 0.0.8

package/dist/collections.d.ts

@@ -9,7 +9,10 @@ export type EntryOrder = "manual" | {
 export declare const DEFAULT_ORDER: EntryOrder;
 export declare const BUILT_IN_ORDER_FIELDS: readonly ["createdAt", "updatedAt"];
 export type CollectionSchema<F extends BuilderMap = BuilderMap> = {
-    kind: "collection";
+    /** "shared" marks a code-declared singleton (spec 2026-09-07 decision
+     *  4): a shared item IS a collection with one entry, so both entry
+     *  stores accept it in the same list and branch on this. */
+    kind: "collection" | "shared";
     name: string;
     title: string;
     titleField?: string;
@@ -25,6 +28,11 @@ export type CollectionSchema<F extends BuilderMap = BuilderMap> = {
     admin?: {
         listColumns?: string[];
     };
+    /** Per-locale version history for this collection's entries (spec
+     *  2026-09-06 §7): every save becomes an `entry_versions` snapshot and
+     *  publish moves a pointer, as on pages. Off by default — a People list
+     *  does not want history; articles do. */
+    versions?: boolean;
     /** phantom: the entry value shape, used by f.ref target inference */
     readonly __entry?: NamespaceValues<F>;
 };
@@ -43,6 +51,7 @@ export declare function collection<F extends BuilderMap>(input: {
     admin?: {
         listColumns?: string[];
     };
+    versions?: boolean;
 }): CollectionSchema<F>;
 export type Toolset = {
     marks?: string[];

package/dist/collections.js

@@ -8,6 +8,15 @@ export function collection(input) {
     if (input.tree !== undefined && (!Number.isInteger(input.tree.depth) || input.tree.depth < 1)) {
         throw new Error(`smoodly: collection "${input.name}" declares an invalid tree depth.`);
     }
+    // `slug` is not a field on the node at all: splitFields drops it and the
+    // locale row owns it (spec 2026-09-06 §12), so ordering by it would be
+    // silently creation-ordered. Checked before the unknown-field check below
+    // so a collection with no declared `slug` field still gets this message,
+    // not "orders by an unknown field" — `slug` routes to the locale row
+    // whether or not it is declared.
+    if (input.order !== undefined && input.order !== "manual" && input.order.by === "slug") {
+        throw new Error(`smoodly: collection "${input.name}" orders by "slug", which is per locale — order fields are shared across locales.`);
+    }
     if (input.order !== undefined &&
         input.order !== "manual" &&
         !BUILT_IN_ORDER_FIELDS.includes(input.order.by) &&
@@ -17,6 +26,12 @@ export function collection(input) {
         !Object.prototype.hasOwnProperty.call(input.fields, input.order.by)) {
         throw new Error(`smoodly: collection "${input.name}" orders by an unknown field "${input.order.by}".`);
     }
+    if (input.order !== undefined &&
+        input.order !== "manual" &&
+        !BUILT_IN_ORDER_FIELDS.includes(input.order.by) &&
+        input.fields[input.order.by]?.descriptor.localized === true) {
+        throw new Error(`smoodly: collection "${input.name}" orders by "${input.order.by}", which is localized — order fields are shared across locales.`);
+    }
     return {
         kind: "collection",
         name: input.name,
@@ -26,6 +41,7 @@ export function collection(input) {
         ...(input.path !== undefined ? { path: input.path } : {}),
         ...(input.tree !== undefined ? { tree: input.tree } : {}),
         ...(input.order !== undefined ? { order: input.order } : {}),
+        ...(input.versions ? { versions: true } : {}),
         admin: input.admin,
     };
 }

package/dist/config.d.ts

@@ -1,5 +1,6 @@
 import type { Descriptor, FieldBuilder } from "./fields.ts";
 import type { CollectionSchema } from "./collections.ts";
+import type { SharedSchema } from "./shared.ts";
 type Registered = {
     schema: {
         kind: string;
@@ -19,6 +20,8 @@ export type SmoodlyConfig = {
         collections?: CollectionSchema<any>[];
         /** Page shapes and entry pages alike — everything that renders a URL. */
         pages?: Registered[];
+        /** Shared content: code-declared singletons (spec 2026-09-07). */
+        shared?: SharedSchema[];
     };
     locales: {
         default: string;

package/dist/config.js

@@ -1,17 +1,50 @@
-import { assertSegment, perLocaleSegments } from "./paths.js";
+import { assertSegment, fixedPageSegments, perLocaleSegments } from "./paths.js";
+const RESERVED_NAME = "shared"; // the placement node type and the admin route
 function assertUniqueNames(config) {
     const seen = new Set();
+    const sectionNameList = (config.registry.sections ?? []).map((s) => s.schema.name);
+    const sectionNames = new Set(sectionNameList);
     const all = [
-        ...(config.registry.sections ?? []).map((s) => s.schema.name),
+        ...sectionNameList,
         ...(config.registry.elements ?? []).map((e) => e.schema.name),
         ...(config.registry.collections ?? []).map((c) => c.name),
         ...(config.registry.pages ?? []).filter((p) => p.schema.kind !== "entryPage").map((p) => p.schema.name),
     ];
     for (const name of all) {
+        if (name === RESERVED_NAME)
+            throw new Error(`smoodly: "${RESERVED_NAME}" is a reserved name.`);
         if (seen.has(name))
             throw new Error(`smoodly: duplicate registered name "${name}".`);
         seen.add(name);
     }
+    // Shared items get their own pass, after every other kind is settled: a
+    // shared item's name must be unique among shared items, and must not
+    // collide with any collection/element/page/section name above — EXCEPT a
+    // visual item may reuse the name of the registered section it renders
+    // (spec 2026-09-07 §2's example pairs a "footer" section with a "footer"
+    // item). That exemption is narrow: it only excuses a match against the
+    // item's own, actually-registered section — never against a collection,
+    // element, or page that happens to share the string, and never against a
+    // second shared item of the same name.
+    const sharedSeen = new Set();
+    for (const item of config.registry.shared ?? []) {
+        const ownSection = item.name === item.section && sectionNames.has(item.name);
+        if (item.name === RESERVED_NAME)
+            throw new Error(`smoodly: "${RESERVED_NAME}" is a reserved name.`);
+        if (sharedSeen.has(item.name) || (seen.has(item.name) && !ownSection)) {
+            throw new Error(`smoodly: duplicate registered name "${item.name}".`);
+        }
+        sharedSeen.add(item.name);
+    }
+}
+/** A visual item renders through a registered section. */
+function assertSharedSections(config) {
+    const sections = new Set((config.registry.sections ?? []).map((s) => s.schema.name));
+    for (const item of config.registry.shared ?? []) {
+        if (item.section !== undefined && !sections.has(item.section)) {
+            throw new Error(`smoodly: shared item "${item.name}" renders section "${item.section}", which is not registered.`);
+        }
+    }
 }
 /** Every root-level segment a registration claims, per locale: fixed page
  *  slugs and collection paths. Two claims on one (locale, segment) are a
@@ -19,7 +52,11 @@ function assertUniqueNames(config) {
  *  EVERY locale of that path, which is the collection's index page. */
 function assertRootSegments(config) {
     const { default: def, supported } = config.locales;
+    // Mounts claim exactly the locales their path names; fixed pages fill an
+    // omitted locale from the default one, so the check must fill the same
+    // way the materializer does or the clash only shows up at materialization.
     const perLocale = (v) => perLocaleSegments(v, supported);
+    const pageSegments = (v) => fixedPageSegments(v, config.locales);
     const pages = (config.registry.pages ?? []).filter((p) => p.schema.kind === "page" && p.schema.slug !== undefined);
     const owners = new Map(); // "<locale> <segment>" → page name
     for (const p of pages) {
@@ -27,7 +64,7 @@ function assertRootSegments(config) {
         if (typeof slug !== "string" && slug[def] === undefined) {
             throw new Error(`smoodly: page "${p.schema.name}" declares a per-locale slug without the default locale "${def}".`);
         }
-        for (const [locale, segment] of Object.entries(perLocale(slug))) {
+        for (const [locale, segment] of Object.entries(pageSegments(slug))) {
             assertSegment(segment, `page "${p.schema.name}" fixed slug`);
             const owner = owners.get(`${locale} ${segment}`);
             if (owner) {
@@ -62,15 +99,32 @@ function assertRootSegments(config) {
             if (!pageName)
                 continue;
             const page = pages.find((p) => p.schema.name === pageName);
-            const everywhere = Object.entries(segments).every(([l, s]) => perLocale(page.schema.slug)[l] === s);
+            const everywhere = Object.entries(segments).every(([l, s]) => pageSegments(page.schema.slug)[l] === s);
             if (!everywhere) {
                 throw new Error(`smoodly: collection "${c.name}" and page registration "${pageName}" both claim the root segment "${segment}" (${locale}).`);
             }
         }
     }
 }
+/** A language subtag, optionally a script or region subtag (`en`, `fi`,
+ *  `en-US`, `zh-Hant`). Codes are otherwise opaque strings all the way
+ *  down — the paths key, the page_locales key — so the only place a
+ *  typo can be caught is here, at boot (spec 2026-09-06 §5). */
+const LOCALE_CODE_RE = /^[a-z]{2,3}(?:-[A-Za-z]{2,4})?$/;
+function assertLocales(config) {
+    const { default: def, supported } = config.locales;
+    for (const code of supported) {
+        if (!LOCALE_CODE_RE.test(code)) {
+            throw new Error(`smoodly: "${code}" is not a valid locale code — use a language tag like "en", "fi", "en-US" or "zh-Hant".`);
+        }
+    }
+    if (!supported.includes(def))
+        throw new Error(`smoodly: the default locale "${def}" is not in the supported list.`);
+}
 export function defineConfig(config) {
+    assertLocales(config);
     assertUniqueNames(config);
+    assertSharedSections(config);
     assertRootSegments(config);
     const depth = config.pages?.tree?.depth ?? 1;
     if (!Number.isInteger(depth) || depth < 1)

package/dist/entry-store.d.ts

@@ -1,19 +1,39 @@
 import type { CollectionSchema, EntryOrder } from "./collections.ts";
+import type { SharedSchema } from "./shared.ts";
+import { type RefEdge } from "./refs.ts";
 import { MemoryRefIndex } from "./ref-index.ts";
 import { type PathIndex } from "./path-index.ts";
 import { type LocaleSet, type PathTarget } from "./paths.ts";
+export type EntryLocale = {
+    /** The entry's segment in this locale; null claims no URL. */
+    slug: string | null;
+    status: "draft" | "published";
+    /** ONLY the .localized() fields, for this locale. */
+    fields: Record<string, unknown>;
+    draftVersionId: string | null;
+    publishedVersionId: string | null;
+    updatedAt: number;
+};
 export type EntryRecord = {
     id: string;
     collection: string;
     parentId: string | null;
+    /** The SHARED fields — every field without .localized(). */
     fields: Record<string, unknown>;
-    i18n: Record<string, Record<string, unknown>> | null;
-    status: "draft" | "published";
+    /** Only the locales present. Presence IS the row. */
+    locales: Record<string, EntryLocale>;
     sort: number | null;
-    locales: string[] | null;
     createdAt: number;
     updatedAt: number;
 };
+export type EntryVersion = {
+    id: string;
+    entryId: string;
+    locale: string;
+    /** The MERGED fields (shared + localized + slug) at that save. */
+    fields: Record<string, unknown>;
+    createdAt: number;
+};
 export type EntryUsage = {
     sourceKind: string;
     sourceId: string;
@@ -22,47 +42,66 @@ export type EntryUsage = {
 export type ListOptions = {
     /** Absent = the collection's configured order (config); `"manual"` sorts by `sort` asc. */
     order?: EntryOrder;
+    /** With `status`: the locale whose row is inspected; the default locale when omitted. */
+    locale?: string;
+    /** Only entries whose row in `locale` is published. */
     status?: "published";
     /**
      * `null` lists roots; a string id lists that parent's children; omitted
-     * (or explicitly `undefined`) applies no parent filter — everything in
-     * the collection, at every depth.
+     * (or explicitly `undefined`) applies no parent filter.
      */
     parent?: string | null;
 };
 export type CreateEntryOptions = {
+    locale: string;
     parentId?: string | null;
-    locales?: string[] | null;
+};
+export type AddEntryLocaleOptions = {
+    from: string;
 };
 export type EntryStoreOptions = {
     paths?: PathIndex;
     locales?: LocaleSet;
+    shared?: SharedSchema[];
 };
 export interface EntryStore {
-    create(collection: string, fields: Record<string, unknown>, options?: CreateEntryOptions): Promise<EntryRecord>;
+    /** Creates the node and ONE locale row from the merged `fields`: shared
+     * keys go to the node, .localized() keys and `slug` to the row. The
+     * parent (if any) must exist in that locale. */
+    create(collection: string, fields: Record<string, unknown>, options: CreateEntryOptions): Promise<EntryRecord>;
     get(collection: string, id: string): Promise<EntryRecord | null>;
     list(collection: string, options?: ListOptions): Promise<EntryRecord[]>;
-    /** Batched read for the resolver: fields keyed by id, missing ids omitted.
-     * The signature IS resolveTree's EntryFetcher. The published-route
-     * resolver passes { status: "published" } so an entry demoted to draft
-     * after a referencing page was published drops out on the next
-     * revalidation instead of hydrating draft fields (DESIGN.md OQ #16). */
-    getMany(collection: string, ids: string[], options?: {
+    /** Batched read for the resolver: the MERGED fields in `locale`, keyed
+     * by id. An id that is missing, absent in the locale, or (with
+     * `status`) unpublished there is omitted. With `{ status: "published" }`
+     * a versioned collection answers from the published snapshot, so a
+     * post-publish edit never leaks (DESIGN.md OQ #16). The signature,
+     * with the locale bound, IS resolveTree's EntryFetcher. */
+    getMany(collection: string, ids: string[], locale: string, options?: {
         status?: "published";
     }): Promise<Record<string, Record<string, unknown>>>;
-    update(collection: string, id: string, fields: Record<string, unknown>): Promise<EntryRecord>;
-    setStatus(collection: string, id: string, status: "draft" | "published"): Promise<EntryRecord>;
+    /** Replaces the merged fields for `locale`: shared keys on the node
+     * (every locale sees them), localized keys and the slug on the row. */
+    update(collection: string, id: string, locale: string, fields: Record<string, unknown>): Promise<EntryRecord>;
+    setStatus(collection: string, id: string, locale: string, status: "draft" | "published"): Promise<EntryRecord>;
+    /** Copies `from`'s localized fields and slug as the new row (shared
+     * fields need no copy); refused when the entry has the locale or its
+     * parent lacks it. */
+    addLocale(collection: string, id: string, locale: string, options: AddEntryLocaleOptions): Promise<EntryRecord>;
+    /** Deletes the row, its versions and its paths rows; refused for the
+     * last locale and while a child has it. */
+    removeLocale(collection: string, id: string, locale: string): Promise<EntryRecord>;
+    /** Newest first; empty for a collection without `versions`. */
+    listVersions(collection: string, id: string, locale: string): Promise<EntryVersion[]>;
     /** Blocked while anything references the entry (the safe-delete guard),
-     * and while it still has child entries. */
+     * and while it still has child entries. Removes every locale. */
     delete(collection: string, id: string): Promise<void>;
     /**
-     * Reparents `id` under `to.parentId`. `to.index` is the moved entry's
-     * final 0-based position among the destination siblings: the entry is
-     * removed from the sibling list first, then spliced back in at `index`.
-     * Omitted, it appends; out-of-range values clamp to [0, siblings.length].
-     * Destination siblings are renumbered 1..N afterward. Like `reorder`,
-     * `move` does NOT bump `updatedAt` — reparenting/resequencing is a
-     * structure change, not an edit to the entry's content.
+     * Reparents `id` under `to.parentId`, which must exist in every locale
+     * the entry has. `to.index` is the moved entry's final 0-based position
+     * among the destination siblings; omitted, it appends; out-of-range
+     * values clamp. Destination siblings are renumbered 1..N afterward.
+     * Like `reorder`, `move` does NOT bump `updatedAt`.
      */
     move(collection: string, id: string, to: {
         parentId: string | null;
@@ -72,8 +111,7 @@ export interface EntryStore {
     reorder(collection: string, orderedIds: string[]): Promise<void>;
     /** The refs index's reverse question: who points at this entry? */
     referencesTo(collection: string, id: string): Promise<EntryUsage[]>;
-    /** Reverse lookup by id alone (ids are globally unique) — what the
-     * fan-out walk queries, since it can't know a source's collection. */
+    /** Reverse lookup by id alone (ids are globally unique) — the fan-out walk. */
     incoming(targetId: string): Promise<{
         sourceKind: string;
         sourceId: string;
@@ -82,69 +120,117 @@ export interface EntryStore {
     pathsOf(collection: string, id: string): Promise<Record<string, string>>;
 }
 export declare function schemaOf(collections: CollectionSchema<any>[], name: string): CollectionSchema<any>;
+/** A shared item is a collection with exactly one entry (spec 2026-09-07). */
+export declare const isSharedSchema: (schema: CollectionSchema<any>) => boolean;
 export declare const DEFAULT_ENTRY_LOCALES: LocaleSet;
 export declare const entryErrors: {
     notFound: (collection: string, id: string) => Error;
     hasChildren: (collection: string, id: string) => Error;
     cycle: () => Error;
     foreignParent: () => Error;
-    /** Entry slugs are unique among SIBLINGS (DESIGN.md §3, decided
-     *  2026-09-05): the same rule pages have, since the URL is the tree.
-     *  ONE source for the text — the Supabase adapter maps its
-     *  entries_sibling_slug_key 23505 onto this same error. */
+    /** Entry slugs are unique among SIBLINGS per locale — the rule pages
+     *  have (spec 2026-09-06 §11): both adapters pre-check in code and the
+     *  paths primary key is the invariant. ONE source for the text. */
     slugTaken: (collection: string) => Error;
+    unsupportedLocale: (locale: string) => Error;
+    notInLocale: (id: string, locale: string) => Error;
+    alreadyInLocale: (id: string, locale: string) => Error;
+    parentNotInLocale: (locale: string) => Error;
+    lastLocale: (id: string) => Error;
+    localeInUse: (locale: string, titles: string[]) => Error;
+    moveLocales: (locale: string) => Error;
+    singleton: (name: string) => Error;
+    owned: (name: string, verb: string) => Error;
+    noSlug: (name: string) => Error;
+    everyLocale: (name: string) => Error;
+};
+/** The keys a locale row owns: every field with .localized(), except
+ *  `slug`, which is the row's own column (a segment is an address, per
+ *  locale by nature). */
+export declare function localizedKeys(schema: CollectionSchema<any>): string[];
+export type SplitFields = {
+    shared: Record<string, unknown>;
+    localized: Record<string, unknown>;
+    slug: string | null;
 };
+/** The merged form an editor submits, split the way the tables store it.
+ *  Every key that is neither localized nor `slug` is shared — declared or
+ *  not — so a stray key never disappears into a locale row. */
+export declare function splitFields(fields: Record<string, unknown>, schema: CollectionSchema<any>): SplitFields;
+export declare function entryLocaleRow(record: EntryRecord, locale: string): EntryLocale;
+/** The merged view of one locale: shared + that locale's fields + its
+ *  slug. A fresh object; throws for an absent locale. */
+export declare function entryFieldsIn(record: EntryRecord, locale: string): Record<string, unknown>;
+/** The refs index rows for an entry: the union over every live field set
+ *  — one per present locale, plus each published snapshot the draft has
+ *  moved past. Safe-delete must hold while ANY of them shows the target,
+ *  since the published site still renders it (DESIGN.md §3 "Page edges
+ *  in refs", the same stance). */
+export declare function entryRefEdges(fieldSets: Record<string, unknown>[], schema: CollectionSchema<any>): RefEdge[];
+/** What a message calls an entry: its title field in that locale, else its id. */
+export declare function entryTitleIn(record: EntryRecord, locale: string, schema: CollectionSchema<any>): string;
 /**
- * Sort comparator for one order rule; `seq` breaks ties by creation.
- *
- * Nulls sort last in BOTH directions (the Supabase adapter must use
- * `nullsFirst: false` to match). The creation tiebreak follows `direction`
- * for non-manual orders — two entries created in the same millisecond
- * must still land newest-first under the default order, not oldest-first
- * — while the manual branch's tiebreak stays ascending (creation order
- * is the natural fallback for otherwise-unordered `sort` values).
+ * Sort comparator for one order rule; `seq` breaks ties by creation. A
+ * declared order field is SHARED (collection() refuses a localized one),
+ * so `e.fields[order.by]` reads the node. Nulls sort last in BOTH
+ * directions (the Supabase adapter uses `nullsFirst: false` to match);
+ * the creation tiebreak follows `direction` for non-manual orders.
  * Declared fields compare numerically when both values are numbers,
- * otherwise as strings via `localeCompare`. The Supabase adapter orders
- * by the jsonb VALUE (`fields->x`, decided 2026-09-05), so the two agree
- * for a field holding numbers and for one holding strings (ISO dates
- * included). Two edges still differ: MIXED types in one field — Postgres
- * orders jsonb by type first (null < string < number < boolean < array <
- * object) rather than by `String(...)` — and an explicit JSON `null`
- * VALUE, which is a jsonb null and sorts FIRST in Postgres but last here
- * (a MISSING key is SQL NULL and does sort last, matching). See the
- * package README's follow-ups.
+ * otherwise as strings via `localeCompare` — the same order Postgres
+ * gives the jsonb VALUE (`fields->x`) for one type; see the README's
+ * follow-ups for the mixed-type and JSON-null edges.
  */
 export declare function compareEntries(order: EntryOrder, seq: (e: EntryRecord) => number): (a: EntryRecord, b: EntryRecord) => number;
 export declare class MemoryEntryStore implements EntryStore {
-    private collections;
     private refs;
     private entries;
+    private versions;
+    /** Insertion order per version — `createdAt` alone can tie within a millisecond. */
+    private versionSeq;
     private seq;
     private order;
     private paths;
     private locales;
+    private schemas;
     constructor(collections: CollectionSchema<any>[], refs?: MemoryRefIndex, options?: EntryStoreOptions);
+    private schema;
     private row;
     private must;
     private byId;
+    private snapshot;
     private subtree;
+    /** An edit bumps the node and the edited row; `move` and `reorder` never call this. */
+    private bump;
+    /** A versioned collection records every save as a merged snapshot and
+     *  points the locale's draft at it; others keep the row as the live content. */
+    private recordVersion;
+    private dropVersions;
+    /** Every field set the site can render for this entry: each present
+     *  locale's live view, plus a published snapshot the draft has moved
+     *  past (still rendered by the published site). */
+    private liveFieldSets;
     private writePaths;
     private writeRefs;
     private siblings;
-    /** The memory mirror of entries_sibling_slug_key: a string slug must be
-     *  unique among the entries sharing a parent. An absent, null or empty
-     *  slug claims no URL and never conflicts (the index's partial
-     *  predicate folds "" to null too via nullif). */
+    /** The friendly pre-check (spec 2026-09-06 §11): a string slug must be
+     *  unique among the siblings PRESENT in that locale; null never
+     *  conflicts. The paths primary key remains the invariant. */
     private assertSiblingSlug;
+    /** Same collection, within depth. Returns the parent (null at the root). */
     private assertParent;
-    create(collection: string, fields: Record<string, unknown>, options?: CreateEntryOptions): Promise<EntryRecord>;
+    /** The parent rule: a locale can only be added where the parent has it. */
+    private assertParentHasLocale;
+    create(collection: string, fields: Record<string, unknown>, options: CreateEntryOptions): Promise<EntryRecord>;
     get(collection: string, id: string): Promise<EntryRecord | null>;
     list(collection: string, options?: ListOptions): Promise<EntryRecord[]>;
-    getMany(collection: string, ids: string[], options?: {
+    getMany(collection: string, ids: string[], locale: string, options?: {
         status?: "published";
     }): Promise<Record<string, Record<string, unknown>>>;
-    update(collection: string, id: string, fields: Record<string, unknown>): Promise<EntryRecord>;
-    setStatus(collection: string, id: string, status: "draft" | "published"): Promise<EntryRecord>;
+    update(collection: string, id: string, locale: string, fields: Record<string, unknown>): Promise<EntryRecord>;
+    setStatus(collection: string, id: string, locale: string, status: "draft" | "published"): Promise<EntryRecord>;
+    addLocale(collection: string, id: string, locale: string, options: AddEntryLocaleOptions): Promise<EntryRecord>;
+    removeLocale(collection: string, id: string, locale: string): Promise<EntryRecord>;
+    listVersions(collection: string, id: string, locale: string): Promise<EntryVersion[]>;
     move(collection: string, id: string, to: {
         parentId: string | null;
         index?: number;