@velastack/cms 0.4.0 → 0.5.0

package/dist/components/cms/scope.d.ts

@@ -5,6 +5,16 @@ export type CmsScope = {
     routeId: string;
     params: Record<string, string>;
 };
+/**
+ * One CMS component usage as recorded by the Vite plugin: which value it
+ * reads and which component type reads it.
+ */
+export type CmsManifestUsage = {
+    name: string;
+    /** Canonical exported component name (`CmsText`, `CmsHours`, …). */
+    component: string;
+    preset?: string;
+};
 export type CmsScopeEntry = {
     scopeId: string;
     kind: 'layout' | 'page';
@@ -15,23 +25,31 @@ export type CmsScopeEntry = {
      * `metadata` branch shows up here too (e.g. `'metadata.title'`).
      */
     fields: string[];
+    /** The usages behind `fields`, with component types. Absent on hand-built manifests. */
+    usages?: CmsManifestUsage[];
 };
 /**
- * Schema for the project-wide site scope. Authored on `createCms({ site })`.
- * Top-level keys are sections rendered as groups in the Site Settings panel;
- * each section's `fields` keys become path segments in the stored tree
- * (`branding.name`, `social.twitter`).
+ * Schema for the project-wide site scope: the **Site Options** panel.
+ * Authored on `createCms({ site })`. Top-level keys are sections rendered as
+ * groups; each section's `fields` keys become path segments in the stored
+ * tree (`seo.schemaType`, `seo.shareImage`).
+ *
+ * Site options are for values that never render on the page — the schema.org
+ * type, the default share image, enabled locales. Anything a visitor sees
+ * belongs in the root layout scope, edited where it renders.
  *
  * `type` selects the input widget. Storage is unconstrained — the schema is
  * a UI hint, not an enforced type for the underlying tree (to keep the data
  * model uniform with pages/layouts and avoid destructive prunes when fields
  * are added/removed).
  */
-export type SiteFieldType = 'text' | 'markdown' | 'number' | 'datetime' | 'url' | 'color' | 'image';
+export type SiteFieldType = 'text' | 'markdown' | 'number' | 'datetime' | 'url' | 'color' | 'image' | 'enum' | 'boolean';
 export type SiteFieldSchema = {
     type: SiteFieldType;
     label: string;
     placeholder?: string;
+    /** Options for `enum` fields. */
+    values?: readonly string[];
 };
 export type SiteSectionSchema = {
     label: string;
@@ -104,6 +122,8 @@ export type CmsManifestScope = {
      * `metadata` branch shows up here too (e.g. `'metadata.title'`).
      */
     fields: string[];
+    /** The usages behind `fields`, with component types. Absent on hand-built manifests. */
+    usages?: CmsManifestUsage[];
 };
 export type CmsManifestRoute = {
     scopes: CmsManifestScope[];

package/dist/components/cms/structured-registry.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Which exported component reads which structured shape. Structured
+ * components register their schema at module load, so the Locales panel can
+ * count translatable strings for every usage the manifest recorded on the
+ * current route without importing the components themselves.
+ */
+import type { Structured } from '../../core/structured.js';
+import type { Tree } from '../../core/path.js';
+export declare const registerStructured: <T extends Tree>(schema: Structured<T>) => Structured<T>;
+export declare const getStructured: (component: string) => Structured<Tree> | undefined;

package/dist/components/cms/structured-registry.js

@@ -0,0 +1,6 @@
+const registry = new Map();
+export const registerStructured = (schema) => {
+    registry.set(schema.component, schema);
+    return schema;
+};
+export const getStructured = (component) => registry.get(component);

package/dist/components/cms/use-cms-field.svelte.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The one piece of plumbing every display component shares: find the scope,
+ * read the value, decide whether it is editable, write it back.
+ *
+ * Scope resolution (`scope` prop):
+ * - absent → the enclosing route scope from context, installed by the plugin
+ *   into every `+layout.svelte` / `+page.svelte`.
+ * - `'root'` → the root layout scope `layout:/`, so a page can read and write
+ *   a value that lives site-wide (hours, contact, navigation, branding). The
+ *   payload already carries every enclosing layout tree, and the root layout
+ *   encloses everything.
+ * - any other string → that scope id verbatim (`layout:/(public)`), for a
+ *   value owned by an intermediate layout. Only param-less scopes can be
+ *   addressed this way.
+ *
+ * Read rule (see `core/structured.ts`): `undefined` means nothing is stored
+ * and the component shows its fallback; `null` means the editor cleared the
+ * field, and the component shows it empty. Never conflate the two — that is
+ * the bug where a cleared field reverts to the template's demo copy.
+ */
+import { type CmsScope } from './scope.js';
+import { type CmsScopeRef } from './cms-store.svelte.js';
+export declare const ROOT_SCOPE_ID = "layout:/";
+export type CmsFieldInput = {
+    name: string;
+    scope?: string;
+    /** Per-item override: disables editing and scope lookup. */
+    value?: unknown;
+};
+export declare const resolveScopeRef: (scope: string | undefined, context: CmsScope | undefined) => CmsScopeRef | null;
+export type CmsField<T> = {
+    /** Resolved scope, or `null` outside any route scope. */
+    readonly ref: CmsScopeRef | null;
+    /** Raw stored value: `undefined` (nothing), `null` (cleared) or the value. */
+    readonly raw: unknown;
+    /** What to render, per the component's `read`. */
+    readonly current: T;
+    readonly editable: boolean;
+    readonly name: string;
+    /** Write the whole value into the draft. Pass `null` to clear. `locale`
+     * defaults to the locale being edited; structured editors pass the
+     * default locale for structure and another locale for its `$t` strings. */
+    set: (next: unknown, locale?: string) => void;
+    /** Write a value at a sub-path of this field, e.g. a `$t` string. */
+    setAt: (subPath: string, next: unknown, locale?: string) => void;
+    /** Read this field (or a sub-path of it) in a specific locale. */
+    getIn: (locale: string, subPath?: string) => unknown;
+    clear: () => void;
+};
+/**
+ * Call once at component init. `input` is an accessor so prop changes flow
+ * through; `read` turns the raw stored value into what the component renders.
+ */
+export declare const useCmsField: <T>(input: () => CmsFieldInput, read: (raw: unknown) => T) => CmsField<T>;

package/dist/components/cms/use-cms-field.svelte.js

@@ -0,0 +1,83 @@
+/**
+ * The one piece of plumbing every display component shares: find the scope,
+ * read the value, decide whether it is editable, write it back.
+ *
+ * Scope resolution (`scope` prop):
+ * - absent → the enclosing route scope from context, installed by the plugin
+ *   into every `+layout.svelte` / `+page.svelte`.
+ * - `'root'` → the root layout scope `layout:/`, so a page can read and write
+ *   a value that lives site-wide (hours, contact, navigation, branding). The
+ *   payload already carries every enclosing layout tree, and the root layout
+ *   encloses everything.
+ * - any other string → that scope id verbatim (`layout:/(public)`), for a
+ *   value owned by an intermediate layout. Only param-less scopes can be
+ *   addressed this way.
+ *
+ * Read rule (see `core/structured.ts`): `undefined` means nothing is stored
+ * and the component shows its fallback; `null` means the editor cleared the
+ * field, and the component shows it empty. Never conflate the two — that is
+ * the bug where a cleared field reverts to the template's demo copy.
+ */
+import { getCmsScope } from './scope.js';
+import { cmsStore } from './cms-store.svelte.js';
+export const ROOT_SCOPE_ID = 'layout:/';
+export const resolveScopeRef = (scope, context) => {
+    if (scope === 'root')
+        return { scopeId: ROOT_SCOPE_ID, routeId: '/', params: {} };
+    if (scope) {
+        const colon = scope.indexOf(':');
+        const routeId = colon === -1 ? scope : scope.slice(colon + 1);
+        return { scopeId: colon === -1 ? `layout:${scope}` : scope, routeId, params: {} };
+    }
+    if (!context)
+        return null;
+    return { scopeId: context.scopeId, routeId: context.routeId, params: context.params };
+};
+/**
+ * Call once at component init. `input` is an accessor so prop changes flow
+ * through; `read` turns the raw stored value into what the component renders.
+ */
+export const useCmsField = (input, read) => {
+    const context = getCmsScope();
+    const ref = $derived(resolveScopeRef(input().scope, context));
+    const raw = $derived.by(() => {
+        const { name, value } = input();
+        if (value !== undefined)
+            return value;
+        return ref ? cmsStore.getValue(ref, name) : undefined;
+    });
+    const current = $derived(read(raw));
+    const editable = $derived(cmsStore.isEditing && input().value === undefined && !!ref);
+    const set = (next, locale) => {
+        if (ref)
+            cmsStore.setValue(ref, input().name, next, locale);
+    };
+    const setAt = (subPath, next, locale) => {
+        if (ref)
+            cmsStore.setValue(ref, `${input().name}.${subPath}`, next, locale);
+    };
+    const getIn = (locale, subPath) => ref
+        ? cmsStore.getValue(ref, subPath ? `${input().name}.${subPath}` : input().name, locale)
+        : undefined;
+    return {
+        get ref() {
+            return ref;
+        },
+        get raw() {
+            return raw;
+        },
+        get current() {
+            return current;
+        },
+        get editable() {
+            return editable;
+        },
+        get name() {
+            return input().name;
+        },
+        set,
+        setAt,
+        getIn,
+        clear: () => set(null)
+    };
+};

package/dist/core/metadata.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Page metadata → `svelte-meta-tags` props.
+ *
+ * The page scope's `metadata` branch holds what the SEO panel edits (see
+ * `DEFAULT_METADATA_SCHEMA`). This maps it onto the object
+ * `definePageMetaTags` / `<MetaTags>` accept, so a template's root layout is
+ * one line: `deepMerge(baseMetaTags, toMetaTags(cms.metadata, { siteName }))`.
+ * Share fields fall back to the search fields, and the site name — read from
+ * the root layout's `branding.name` — supplies the title template and the
+ * Open Graph site name.
+ */
+export type MetaTagsInput = Record<string, unknown>;
+export type MetaTagsOptions = {
+    /** The root layout's `branding.name`; drives `titleTemplate` and `openGraph.siteName`. */
+    siteName?: string;
+    /** Title template when `siteName` is set. `%s` is the page title. Default `'%s · <siteName>'`. */
+    titleTemplate?: string;
+    /** Absolute URL of the page, for `openGraph.url` when no canonical is set. */
+    url?: string;
+};
+export type MetaTagsOutput = {
+    title?: string;
+    titleTemplate?: string;
+    description?: string;
+    canonical?: string;
+    robots?: string;
+    openGraph?: {
+        title?: string;
+        description?: string;
+        url?: string;
+        siteName?: string;
+        images?: Array<{
+            url: string;
+            alt?: string;
+        }>;
+    };
+    twitter?: {
+        cardType?: 'summary' | 'summary_large_image';
+        title?: string;
+        description?: string;
+        image?: string;
+    };
+};
+export declare const toMetaTags: (metadata: MetaTagsInput, options?: MetaTagsOptions) => MetaTagsOutput;

package/dist/core/metadata.js

@@ -0,0 +1,59 @@
+const str = (v) => (typeof v === 'string' && v !== '' ? v : undefined);
+const imageUrl = (v) => {
+    if (typeof v === 'string')
+        return v ? { url: v } : undefined;
+    if (v && typeof v === 'object' && !Array.isArray(v)) {
+        const r = v;
+        if (typeof r.url === 'string' && r.url) {
+            return typeof r.alt === 'string' && r.alt ? { url: r.url, alt: r.alt } : { url: r.url };
+        }
+    }
+    return undefined;
+};
+export const toMetaTags = (metadata, options = {}) => {
+    const title = str(metadata.title);
+    const description = str(metadata.description);
+    const ogTitle = str(metadata.ogTitle) ?? title;
+    const ogDescription = str(metadata.ogDescription) ?? description;
+    const image = imageUrl(metadata.ogImage);
+    const canonical = str(metadata.canonical);
+    const card = str(metadata.twitterCard);
+    const out = {};
+    if (title)
+        out.title = title;
+    if (options.siteName)
+        out.titleTemplate = options.titleTemplate ?? `%s · ${options.siteName}`;
+    if (description)
+        out.description = description;
+    if (canonical)
+        out.canonical = canonical;
+    if (metadata.noindex === true)
+        out.robots = 'noindex, nofollow';
+    const og = {};
+    if (ogTitle)
+        og.title = ogTitle;
+    if (ogDescription)
+        og.description = ogDescription;
+    if (canonical ?? options.url)
+        og.url = canonical ?? options.url;
+    if (options.siteName)
+        og.siteName = options.siteName;
+    if (image)
+        og.images = [image];
+    if (Object.keys(og).length > 0)
+        out.openGraph = og;
+    const tw = {};
+    if (card === 'summary' || card === 'summary_large_image')
+        tw.cardType = card;
+    else if (image)
+        tw.cardType = 'summary_large_image';
+    if (ogTitle)
+        tw.title = ogTitle;
+    if (ogDescription)
+        tw.description = ogDescription;
+    if (image)
+        tw.image = image.url;
+    if (Object.keys(tw).length > 0)
+        out.twitter = tw;
+    return out;
+};

package/dist/core/structured.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Structured values: the shapes behind the editor components (hours, team,
+ * testimonials, …) and the two rules every one of them follows.
+ *
+ * 1. **Versioned shapes, whole-object writes.** A structured value is a plain
+ *    object with a `v` version number. Components never patch a leaf inside
+ *    it; they read the whole value through the schema's `normalize`, change
+ *    it, and write the whole object back. A field the editor clears is
+ *    written as `null`, never dropped: the draft and release trees deep-merge
+ *    over the published tree, and a missing key merges to "unchanged" while
+ *    `null` merges to "cleared". That is what stops a cleared field from
+ *    reverting to the template's demo copy.
+ *
+ * 2. **Localisation is a string overlay, never a second structure.** The
+ *    default locale stores the full value at `<name>`. Every other locale
+ *    stores only strings, at `<name>.$t.<id>.<field>`, keyed by the stable
+ *    `id` of the list item they translate (the reserved id `_` addresses the
+ *    value's own root fields). Because objects deep-merge across locales,
+ *    reading `es` yields the default structure plus the `es` overlay, and
+ *    {@link applyTranslations} folds the strings in. Structure edits happen in
+ *    the default locale only, so the item list can never fork between
+ *    languages.
+ */
+import { type Tree } from './path.js';
+/** Branch under a structured value that holds a locale's string overlay. */
+export declare const TRANSLATIONS_KEY = "$t";
+/** Overlay id that addresses the structured value's root fields. */
+export declare const ROOT_ID = "_";
+/** `{ [itemId]: { [field]: string } }` — what a non-default locale stores. */
+export type TranslationOverlay = Record<string, Record<string, string>>;
+export type StructuredItem = {
+    id: string;
+} & Record<string, unknown>;
+export type StructuredSchema<T extends Tree> = {
+    /** Exported component name, e.g. `'CmsHours'`. Recorded in the manifest. */
+    component: string;
+    /** Current shape version, written as `v` on every value. */
+    version: number;
+    /** Root-level fields holding translatable strings, e.g. `['note']`. */
+    translatable: readonly string[];
+    /** The item list, when the value has one, and the item fields that translate. */
+    items?: {
+        key: string;
+        translatable: readonly string[];
+    };
+    /**
+     * Turn anything the store may hold — an older version, a hand-seeded
+     * partial object, garbage — into the current shape. Must never throw.
+     */
+    normalize: (raw: unknown) => T;
+    /** The cleared value: what an editor gets after "Clear". */
+    empty: () => T;
+};
+export type Structured<T extends Tree> = StructuredSchema<T> & {
+    /**
+     * Resolve a stored value the way a display component reads it:
+     * `undefined` (nothing stored) → the fallback; `null` (cleared) → empty;
+     * anything else → normalized, with the locale overlay applied.
+     */
+    read: (raw: unknown, fallback: T | undefined) => T;
+};
+export declare const isPlainObject: (v: unknown) => v is Tree;
+export declare const defineStructured: <T extends Tree>(schema: StructuredSchema<T>) => Structured<T>;
+/** Path of one translated string: `<name>.$t.<id>.<field>`. */
+export declare const translationPath: (name: string, id: string, field: string) => string;
+/** The `$t` branch of a stored value, when it is one. */
+export declare const extractTranslations: (raw: unknown) => TranslationOverlay | undefined;
+/** A copy of `raw` without its `$t` branch, so a whole-object write in the
+ * default locale never carries another locale's strings. */
+export declare const stripTranslations: (raw: unknown) => unknown;
+/**
+ * Fold a locale's string overlay into a normalized default-locale value.
+ * Root fields come from the `_` id; item fields from the item's own `id`.
+ * Only non-empty strings override, so an untranslated field shows the
+ * default-locale text rather than a blank.
+ */
+export declare const applyTranslations: <T extends Tree>(value: T, overlay: TranslationOverlay | undefined, schema: Pick<StructuredSchema<T>, "translatable" | "items">) => T;
+export type TranslatableField = {
+    /** Overlay id: an item id, or `_` for a root field. */
+    id: string;
+    field: string;
+    /** The default-locale string being translated. */
+    source: string;
+};
+/**
+ * Every translatable, non-empty string in a normalized default-locale value.
+ * Drives the popover's translation tab and the Locales panel's counts.
+ */
+export declare const translatableFields: <T extends Tree>(value: T, schema: Pick<StructuredSchema<T>, "translatable" | "items">) => TranslatableField[];
+/** How many translatable strings a locale's overlay still lacks. */
+export declare const countTranslations: <T extends Tree>(value: T, overlay: TranslationOverlay | undefined, schema: Pick<StructuredSchema<T>, "translatable" | "items">) => {
+    total: number;
+    missing: number;
+};
+export declare const asString: (v: unknown, fallback?: string) => string;
+export declare const asNumber: (v: unknown, fallback?: number | null) => number | null;
+export declare const asBoolean: (v: unknown, fallback?: boolean) => boolean;
+/**
+ * Normalize a list of items, guaranteeing every item carries a string `id`.
+ * An item without one (a hand-written seed, say) gets a deterministic
+ * `item-<index>` so reads stay stable until the editor next writes the list,
+ * at which point the ids are persisted.
+ */
+export declare const asItems: <I extends StructuredItem>(raw: unknown, normalizeItem: (item: Tree, index: number) => Omit<I, "id">) => I[];
+/** A short random id for a newly added item. Stable once written. */
+export declare const newItemId: () => string;
+/** Read a structured value's overlay for one locale out of a whole scope tree. */
+export declare const overlayAt: (tree: Tree | undefined, name: string) => TranslationOverlay | undefined;

package/dist/core/structured.js

@@ -0,0 +1,184 @@
+/**
+ * Structured values: the shapes behind the editor components (hours, team,
+ * testimonials, …) and the two rules every one of them follows.
+ *
+ * 1. **Versioned shapes, whole-object writes.** A structured value is a plain
+ *    object with a `v` version number. Components never patch a leaf inside
+ *    it; they read the whole value through the schema's `normalize`, change
+ *    it, and write the whole object back. A field the editor clears is
+ *    written as `null`, never dropped: the draft and release trees deep-merge
+ *    over the published tree, and a missing key merges to "unchanged" while
+ *    `null` merges to "cleared". That is what stops a cleared field from
+ *    reverting to the template's demo copy.
+ *
+ * 2. **Localisation is a string overlay, never a second structure.** The
+ *    default locale stores the full value at `<name>`. Every other locale
+ *    stores only strings, at `<name>.$t.<id>.<field>`, keyed by the stable
+ *    `id` of the list item they translate (the reserved id `_` addresses the
+ *    value's own root fields). Because objects deep-merge across locales,
+ *    reading `es` yields the default structure plus the `es` overlay, and
+ *    {@link applyTranslations} folds the strings in. Structure edits happen in
+ *    the default locale only, so the item list can never fork between
+ *    languages.
+ */
+import { get } from './path.js';
+/** Branch under a structured value that holds a locale's string overlay. */
+export const TRANSLATIONS_KEY = '$t';
+/** Overlay id that addresses the structured value's root fields. */
+export const ROOT_ID = '_';
+export const isPlainObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+export const defineStructured = (schema) => ({
+    ...schema,
+    read: (raw, fallback) => {
+        if (raw === undefined)
+            return fallback === undefined ? schema.empty() : fallback;
+        if (raw === null)
+            return schema.empty();
+        const overlay = extractTranslations(raw);
+        const value = schema.normalize(stripTranslations(raw));
+        return overlay ? applyTranslations(value, overlay, schema) : value;
+    }
+});
+/** Path of one translated string: `<name>.$t.<id>.<field>`. */
+export const translationPath = (name, id, field) => `${name}.${TRANSLATIONS_KEY}.${id}.${field}`;
+/** The `$t` branch of a stored value, when it is one. */
+export const extractTranslations = (raw) => {
+    if (!isPlainObject(raw))
+        return undefined;
+    const t = raw[TRANSLATIONS_KEY];
+    if (!isPlainObject(t))
+        return undefined;
+    const out = {};
+    for (const [id, fields] of Object.entries(t)) {
+        if (!isPlainObject(fields))
+            continue;
+        const strings = {};
+        for (const [field, v] of Object.entries(fields)) {
+            if (typeof v === 'string')
+                strings[field] = v;
+        }
+        out[id] = strings;
+    }
+    return out;
+};
+/** A copy of `raw` without its `$t` branch, so a whole-object write in the
+ * default locale never carries another locale's strings. */
+export const stripTranslations = (raw) => {
+    if (!isPlainObject(raw) || !(TRANSLATIONS_KEY in raw))
+        return raw;
+    const { [TRANSLATIONS_KEY]: _omit, ...rest } = raw;
+    return rest;
+};
+const overlayString = (overlay, id, field) => {
+    const v = overlay[id]?.[field];
+    return typeof v === 'string' && v !== '' ? v : undefined;
+};
+/**
+ * Fold a locale's string overlay into a normalized default-locale value.
+ * Root fields come from the `_` id; item fields from the item's own `id`.
+ * Only non-empty strings override, so an untranslated field shows the
+ * default-locale text rather than a blank.
+ */
+export const applyTranslations = (value, overlay, schema) => {
+    if (!overlay)
+        return value;
+    const out = { ...value };
+    for (const field of schema.translatable) {
+        const s = overlayString(overlay, ROOT_ID, field);
+        if (s !== undefined)
+            out[field] = s;
+    }
+    if (schema.items) {
+        const list = value[schema.items.key];
+        if (Array.isArray(list)) {
+            out[schema.items.key] = list.map((item) => {
+                if (!isPlainObject(item) || typeof item.id !== 'string')
+                    return item;
+                const next = { ...item };
+                for (const field of schema.items.translatable) {
+                    const s = overlayString(overlay, item.id, field);
+                    if (s !== undefined)
+                        next[field] = s;
+                }
+                return next;
+            });
+        }
+    }
+    return out;
+};
+/**
+ * Every translatable, non-empty string in a normalized default-locale value.
+ * Drives the popover's translation tab and the Locales panel's counts.
+ */
+export const translatableFields = (value, schema) => {
+    const out = [];
+    for (const field of schema.translatable) {
+        const s = value[field];
+        if (typeof s === 'string' && s !== '')
+            out.push({ id: ROOT_ID, field, source: s });
+    }
+    if (schema.items) {
+        const list = value[schema.items.key];
+        if (Array.isArray(list)) {
+            for (const item of list) {
+                if (!isPlainObject(item) || typeof item.id !== 'string')
+                    continue;
+                for (const field of schema.items.translatable) {
+                    const s = item[field];
+                    if (typeof s === 'string' && s !== '')
+                        out.push({ id: item.id, field, source: s });
+                }
+            }
+        }
+    }
+    return out;
+};
+/** How many translatable strings a locale's overlay still lacks. */
+export const countTranslations = (value, overlay, schema) => {
+    const fields = translatableFields(value, schema);
+    let missing = 0;
+    for (const f of fields) {
+        if (!overlay || overlayString(overlay, f.id, f.field) === undefined)
+            missing += 1;
+    }
+    return { total: fields.length, missing };
+};
+// ---------------------------------------------------------------------------
+// Normalizer building blocks
+// ---------------------------------------------------------------------------
+export const asString = (v, fallback = '') => typeof v === 'string' ? v : fallback;
+export const asNumber = (v, fallback = null) => typeof v === 'number' && Number.isFinite(v) ? v : fallback;
+export const asBoolean = (v, fallback = false) => typeof v === 'boolean' ? v : fallback;
+/**
+ * Normalize a list of items, guaranteeing every item carries a string `id`.
+ * An item without one (a hand-written seed, say) gets a deterministic
+ * `item-<index>` so reads stay stable until the editor next writes the list,
+ * at which point the ids are persisted.
+ */
+export const asItems = (raw, normalizeItem) => {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    raw.forEach((entry, index) => {
+        if (!isPlainObject(entry))
+            return;
+        const id = typeof entry.id === 'string' && entry.id !== '' ? entry.id : `item-${index}`;
+        out.push({ id, ...normalizeItem(entry, index) });
+    });
+    return out;
+};
+/** A short random id for a newly added item. Stable once written. */
+export const newItemId = () => {
+    const bytes = new Uint8Array(6);
+    if (typeof crypto !== 'undefined' && crypto.getRandomValues)
+        crypto.getRandomValues(bytes);
+    else
+        for (let i = 0; i < bytes.length; i++)
+            bytes[i] = Math.floor(Math.random() * 256);
+    let out = '';
+    for (const b of bytes)
+        out += b.toString(16).padStart(2, '0');
+    return out;
+};
+/** Read a structured value's overlay for one locale out of a whole scope tree. */
+export const overlayAt = (tree, name) => extractTranslations(get(tree, name));

package/dist/core/wire.d.ts

@@ -11,7 +11,7 @@
  * `published_at` stay snake_case because that is what the JSON carries.
  */
 import type { Tree } from './path.js';
-import type { PageDeleteOutcome } from './page-entry.js';
+import type { PageDeleteOutcome, PageEntry } from './page-entry.js';
 export type { PageDeleteOutcome };
 /** One pending change in a release, without the bookkeeping the store adds. */
 export type ReleaseItemCore = {
@@ -182,6 +182,36 @@ export type CmsDeployState = {
     };
     latest?: CmsDeployRun | null;
 };
+/**
+ * A project's published content in one object: `layouts` and `pages` keyed
+ * `[locale][routeId]`, plus the non-localised `site` tree. `POST /seed`
+ * accepts it and `GET /export` returns it, so a template's published
+ * `content/` can seed a fresh project and a project can be dumped back into
+ * the same shape. A page keyed by route id may be a bare tree (a static page,
+ * `params: {}`) or a full `PageEntry[]`.
+ */
+export type CmsSeed = {
+    layouts?: Record<string, Record<string, Tree>>;
+    pages?: Record<string, Record<string, Tree | PageEntry[]>>;
+    site?: Tree;
+};
+export type SeedRequest = CmsSeed & {
+    /** Overwrite a project that already has published rows. */
+    force?: boolean;
+};
+export type SeedSummary = {
+    locales: string[];
+    layouts: number;
+    pages: number;
+    site: boolean;
+};
+export type SeedResponse = {
+    ok: true;
+    seeded: SeedSummary;
+} | {
+    ok: false;
+    reason: 'already-seeded';
+};
 export type DocsResponse = {
     contents: Tree;
 } | PageDeleteOutcome;