@velastack/cms 0.3.1 → 0.5.0

package/README.md

@@ -201,13 +201,18 @@ If `endpoint` is omitted (e.g. when using `mockAdapter` for tests/demos), the pl
 
 ## CMS components
 
-All four included CMS components share the same prop shape:
+Every CMS component shares the same prop shape:
 
-| Prop       | Type               | Notes                                                                    |
-| ---------- | ------------------ | ------------------------------------------------------------------------ |
-| `name`     | `string`           | Field path inside this scope. Must be a static string at v1.             |
-| `fallback` | varies             | Rendered when no value is stored. `string` for text, HTML for rich text. |
-| `value`    | `unknown` (opt-in) | Per-item override used inside `<CmsRepeater/>`; bypasses scope lookup.   |
+| Prop       | Type               | Notes                                                                                                                                           |
+| ---------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `name`     | `string`           | Field path inside this scope. Must be a static string at v1.                                                                                    |
+| `scope`    | `'root' \| string` | Read and write a value that lives in the root layout scope (`'root'`, i.e. `layout:/`) or another param-less layout scope (`layout:/(public)`). |
+| `fallback` | varies             | Rendered when **nothing** is stored. `string` for text, HTML for rich text, `{ url, alt }` or a URL for images.                                 |
+| `value`    | `unknown` (opt-in) | Per-item override; bypasses scope lookup and disables editing.                                                                                  |
+
+Two stored states are distinct: `undefined` (nothing stored) renders the fallback, `null` (the editor cleared the field) renders empty. Editables write `null` on clear, never drop the key, so a cleared field can't fall back to the template's demo copy after publish.
+
+`scope="root"` is how site-wide content — hours, contact, navigation, branding — is edited where it renders: put the component in the root `+layout.svelte` and reference the same `name` from any page with `scope="root"`. The payload already carries every enclosing layout tree, so no extra fetch happens.
 
 ### `<CmsText />`
 
@@ -248,7 +253,55 @@ Renders an `<img>`. Edit mode shows the current image plus a URL input.
 </CmsRepeater>
 ```
 
-Iterates an array stored at `name`. Inside the snippet, pass per-item values via `value=` to bypass scope lookup. Edit mode renders the same snippet for each item plus add/remove controls and per-key inputs.
+Iterates an array stored at `name`. Inside the snippet, pass per-item values via `value=` to bypass scope lookup. Edit mode renders the same snippet for each item plus add/remove controls and per-key inputs. `CmsRepeater` is the placeholder for the structured list components; new templates should build on `defineStructured` below.
+
+## Structured components
+
+Hours, team, testimonials and the like are one value with a fixed shape, edited in a slot-anchored popover and rendered by the template through a snippet. The package ships the pieces a structured component is made of; the components themselves come with the editor-components release.
+
+```ts
+// hours.ts — the value's rules
+import { defineStructured, registerStructured, asItems, asString } from '@velastack/cms';
+
+export const hours = registerStructured(
+	defineStructured<Hours>({
+		component: 'CmsHours', // canonical export name, recorded in the manifest
+		version: 1, // written as `v` on every value
+		translatable: ['note'], // root fields that translate
+		items: { key: 'days', translatable: ['label'] }, // the list and its translatable fields
+		normalize: (raw) => ({ v: 1, note: asString(raw?.note), days: asItems(raw?.days, …) }),
+		empty: () => ({ v: 1, note: '', days: [] })
+	})
+);
+```
+
+```svelte
+<!-- cms-hours.svelte — the display component -->
+<script lang="ts">
+	import { useCmsField } from '@velastack/cms';
+	let { name, scope, fallback, children } = $props();
+	const field = useCmsField(
+		() => ({ name, scope }),
+		(raw) => hours.read(raw, fallback)
+	);
+</script>
+
+{#if field.editable}
+	{#await import('./cms-hours-editable.svelte') then { default: Editable }}
+		<Editable {field} {children} />
+	{/await}
+{:else}
+	{@render children(field.current)}
+{/if}
+```
+
+The editable sibling wraps `StructuredEditorPopover` from `@velastack/cms/editor` (also `FieldInput`, `ReorderButtons`, the Popover / Tabs / Switch / Checkbox / Sheet primitives and `CmsMediaPicker`), passes a `preview` snippet and an `editor` snippet over a local draft, and the popover commits on **Done**. Edit mode is page-wide; the bar's Save flushes the draft.
+
+Rules every structured value follows (`core/structured.ts`):
+
+- **Whole-object writes, explicit `null` clears.** Components never patch a leaf; they write the full `{ v, … }` object. Cleared fields are `null`.
+- **List items carry a stable `id`** (`newItemId()`); reorder and delete work because arrays replace wholesale on merge.
+- **Localisation is a string overlay.** The default locale stores the full value at `<name>`; every other locale stores only strings at `<name>.$t.<id>.<field>` (`_` is the id for root fields). `read()` folds the overlay in, structure never forks between languages, and the popover's locale tabs write only the overlay. The Locales panel counts translatable strings per locale for every structured usage on the current route.
 
 ### `<CmsEntries />`
 
@@ -296,7 +349,7 @@ A component is treated as a CMS component if **any** of the following hold:
 
 2. **It's a named export from your local `src/lib/components/cms/index.{ts,js}` barrel.** Re-export your component there if you prefer a single import path..
 
-3. **It's imported from the `@velastack/cms` package itself.** The four built-ins (`CmsText`, `CmsRichText`, `CmsImage`, `CmsRepeater`) work this way: any import resolving inside the installed `@velastack/cms` package is auto-classified.
+3. **It's imported from the `@velastack/cms` package itself.** Every named import from `@velastack/cms` is a CMS component, whether or not the bundler resolved the package.
 
 ### Third-party packs (opt-in)
 
@@ -332,13 +385,12 @@ String patterns match `source === pattern || source.startsWith(pattern + '/')`.
 
 A CMS component should:
 
-- Accept `{ name: string; fallback?: string; value?: unknown }` props (and any extras you need).
-- Call `getCmsScope()` from `cms` to find its scope.
-- Read drafts via `cmsStore.hasDraft(scopeKey, name)` / `cmsStore.getValue(scopeKey, name)` when `cmsStore.isEditing` is true; fall back to `page.data.cms.docs[scopeKey][name]` otherwise.
-- Skip scope lookup when `value !== undefined` — that prop is the per-item override used inside `<CmsRepeater/>`.
-- Optionally provide an editable sibling that's dynamically `import()`'d when `cmsStore.isEditing` flips on, so editing code doesn't ship to public visitors.
+- Accept `{ name: string; scope?: string; fallback?: …; value?: unknown }` props (and any extras you need).
+- Call `useCmsField(() => ({ name, scope, value }), read)` once at init. It resolves the scope (context, `'root'`, or an explicit id), reads the merged value, reports `editable`, and exposes `set` / `clear`.
+- Treat `undefined` as "render the fallback" and `null` as "render empty" in `read`.
+- Optionally provide an editable sibling that's dynamically `import()`'d when `field.editable` flips on, so editing code doesn't ship to public visitors.
 
-The four built-ins are reference implementations; copy `src/lib/components/cms/cms-text.svelte` (or one of the other built-ins with a paired `*-editable.svelte` sibling) as a starting point.
+The built-ins are reference implementations; copy `src/lib/components/cms/cms-text.svelte` (or one of the others with a paired `*-editable.svelte` sibling) as a starting point.
 
 ## Architecture
 
@@ -399,7 +451,7 @@ Display components prefer drafts over published values when `isEditing` is true.
 
 ### Page metadata
 
-Page scopes carry an editable metadata field list (default: `title`, `description`, `canonical`, `robots`). Resolution order, per design:
+Every page scope carries the full metadata set by default — `title`, `description`, `ogTitle`, `ogDescription`, `ogImage`, `twitterCard`, `canonical`, `noindex` — and a route's `page.cms.ts` `metadata` schema adds to or overrides it. The SEO panel previews the search snippet and the share card; blank share fields reuse the search fields. Resolution order, per design:
 
 ```
 editable page metadata (cms.metadata)
@@ -407,7 +459,19 @@ editable page metadata (cms.metadata)
   → static site defaults (defineBaseMetaTags)
 ```
 
-Hand `cms.metadata` directly to `definePageMetaTags(...)` from `svelte-meta-tags` and you're done.
+`toMetaTags(cms.metadata, { siteName })` turns the branch into `svelte-meta-tags` props, with the title template and Open Graph site name from the root layout's `branding.name`:
+
+```svelte
+<script lang="ts">
+	import { cms, toMetaTags } from '@velastack/cms';
+	const siteName = $derived(cms.docs['layout:/']?.branding?.name as string | undefined);
+	const metaTags = $derived(deepMerge(data.baseMetaTags, toMetaTags(cms.metadata, { siteName })));
+</script>
+```
+
+### Site options
+
+`createCms({ site })` declares the **Site Options** panel: project-wide values that never render on the page — the schema.org type (`enum`), the default share image (`image`), which locales are enabled (`boolean`). Field types are `text`, `markdown`, `number`, `datetime`, `url`, `color`, `image`, `enum` (with `values`) and `boolean`. Anything a visitor sees belongs in the root layout scope, edited in place with `scope="root"`; the site tree is one non-localised tree per project.
 
 ## Adapters
 
@@ -578,6 +642,24 @@ cms.locale; // 'es'
 cms.locales; // ['en', 'es', 'fr']
 ```
 
+## Seeding a project
+
+A fresh project should open with content, not a blank site. The backend accepts a project's whole published state as one object and returns it in the same shape:
+
+```ts
+type CmsSeed = {
+	layouts?: Record<locale, Record<routeId, Tree>>;
+	pages?: Record<locale, Record<routeId, Tree | PageEntry[]>>; // a bare tree is a static page
+	site?: Tree;
+};
+```
+
+- `POST /seed` with a `CmsSeed` (plus `force?: true`) writes the published rows directly, outside the release flow. It answers `409 { ok: false, reason: 'already-seeded' }` when the project already has published rows unless `force` is set, so it can never silently overwrite edits. Image values are seeded as URLs; nothing is uploaded.
+- `GET /export` returns the published rows as a `CmsSeed` (tombstoned pages omitted).
+- In-process: `backend.store.seed(projectId, seed, { force })` and `backend.store.exportPublished(projectId)`.
+
+Both routes require an editor session. A host that creates projects (velastack.dev's `/setup`) reads the template's published `content/` and calls `store.seed` right after creating the project, in the locales the owner enabled.
+
 ## Redirects & tombstones
 
 Pages can be deleted with three different outcomes:
@@ -611,17 +693,24 @@ cms({
 	endpoint: 'https://cms.example.com/v1/projects/p1/cms',
 	locales: ['en'], // mirror createCms({ locales })
 	mediaDir: 'static/cms-media', // download target (default)
-	mediaPrefix: '/cms-media' // URL prefix in rewritten content (default)
+	mediaPrefix: '/cms-media', // URL prefix in rewritten content (default)
+
+	// Content manifest: `content/<locale>.json` keyed by scope id. When the
+	// default locale's file exists its values are injected as `fallback`
+	// props into every walked .svelte file, so components stay name-only.
+	content: 'content' // default; `false` disables
 });
 ```
 
+Build tooling that needs the same parser — a `pack` step inlining fallbacks into a tarball, a `verify` step checking usages against a content manifest — imports it from `@velastack/cms/build`: `scanUsages(source)`, `injectFallbacks(source, treeOrResolver)` / `inlineFallbacks`, `buildManifest(...)` and `fallbackResolverFor(result, file, content)`. The manifest records each usage's component type (`scope.usages`), and the walk reports dynamic `name`s and out-of-chain `scope=` attributes as warnings instead of dropping them silently.
+
 The plugin also exposes `virtual:vela-cms/manifest` (typed via the package's ambient declaration). You almost never need to import it directly — `loadCms` does that internally — but it's there if you want to introspect the manifest at build time.
 
 ## Constraints (v1)
 
 Static analysis is conservative on purpose:
 
-- `name=` props must be string literals or `name={'literal'}`. Computed names are not extracted.
+- `name=` props must be string literals or `name={'literal'}`. Computed names are not extracted; the plugin warns about each one.
 - Only static `import` of `.svelte` files is followed when walking the component graph. Bare specifiers (npm packages) are skipped unless they're the @velastack/cms package itself, are listed under `components`, or match a `traverse` pattern.
 - `<svelte:component this={…} />` and dynamic component selection are not traced.
 - Layout reset segments (`+page@layout.svelte`) are not yet supported.

package/dist/backend/index.d.ts

@@ -49,6 +49,6 @@ export type { CmsStore } from './store/queries.js';
 export type { SqliteDb, SqliteStatement } from './store/sqlite.js';
 export type { Migration } from './store/migrations/index.js';
 export { MIGRATIONS } from './store/migrations/index.js';
-export type { DocsResponse, MediaItem, OpenRelease, PageMapEntry, PageMapRoute, PagesResponse, PagesRoute, PublishedRelease, ReleaseItem, SiteResponse } from '../core/wire.js';
+export type { CmsSeed, DocsResponse, MediaItem, OpenRelease, PageMapEntry, PageMapRoute, PagesResponse, PagesRoute, PublishedRelease, ReleaseItem, ReleasePublisher, SeedRequest, SeedResponse, SeedSummary, SiteResponse } from '../core/wire.js';
 export type { PageDeleteOutcome, PageEntry } from '../core/page-entry.js';
 export type { Tree } from '../core/path.js';

package/dist/backend/routes/release.js

@@ -101,7 +101,7 @@ export const postReleasePublish = async (ctx) => {
             name = body.name;
         }
     }
-    const published = ctx.store.publishRelease(ctx.projectId, user.id, name);
+    const published = ctx.store.publishRelease(ctx.projectId, user, name);
     if (!published)
         return new Response('no open release to publish', { status: 404 });
     return Response.json({ release: published });
@@ -130,7 +130,7 @@ export const postReleaseRevert = (ctx) => {
     const id = ctx.params.id;
     if (!id)
         return badRequest('id required');
-    const reverted = ctx.store.revertRelease(ctx.projectId, id, user.id);
+    const reverted = ctx.store.revertRelease(ctx.projectId, id, user);
     if (!reverted)
         return new Response('release not found', { status: 404 });
     return Response.json({ release: reverted });

package/dist/backend/routes/seed.d.ts

@@ -0,0 +1,6 @@
+import type { CmsSeed } from '../../core/wire.js';
+import { type RouteCtx } from './context.js';
+/** Validate a request body into a {@link CmsSeed}, or explain why not. */
+export declare const parseSeed: (body: unknown) => CmsSeed | string;
+export declare const postSeed: (ctx: RouteCtx) => Promise<Response>;
+export declare const getExport: (ctx: RouteCtx) => Response;

package/dist/backend/routes/seed.js

@@ -0,0 +1,96 @@
+import { badRequest, isObjectRecord, isStringRecord, readJson } from './context.js';
+const parseEntries = (raw) => {
+    const out = [];
+    for (const e of raw) {
+        if (!isObjectRecord(e))
+            return 'page entries must be objects';
+        if (!isStringRecord(e.params))
+            return 'page entry params must be a string-keyed object';
+        if (!isObjectRecord(e.published))
+            return 'page entry published must be an object';
+        const entry = { params: e.params, published: e.published };
+        const t = e.tombstone;
+        if (isObjectRecord(t)) {
+            if (t.kind === 'gone')
+                entry.tombstone = { kind: 'gone' };
+            else if (t.kind === 'redirect' && typeof t.to === 'string') {
+                entry.tombstone = { kind: 'redirect', to: t.to };
+            }
+            else
+                return 'page entry tombstone must be gone or redirect';
+        }
+        out.push(entry);
+    }
+    return out;
+};
+/** Validate a request body into a {@link CmsSeed}, or explain why not. */
+export const parseSeed = (body) => {
+    if (!isObjectRecord(body))
+        return 'object body required';
+    const seed = {};
+    if (body.layouts !== undefined) {
+        if (!isObjectRecord(body.layouts))
+            return 'layouts must be keyed by locale';
+        seed.layouts = {};
+        for (const [locale, byRoute] of Object.entries(body.layouts)) {
+            if (!isObjectRecord(byRoute))
+                return `layouts.${locale} must be keyed by route id`;
+            const bucket = {};
+            for (const [routeId, tree] of Object.entries(byRoute)) {
+                if (!routeId.startsWith('/'))
+                    return `layouts.${locale}: "${routeId}" is not a route id`;
+                if (!isObjectRecord(tree))
+                    return `layouts.${locale}.${routeId} must be an object`;
+                bucket[routeId] = tree;
+            }
+            seed.layouts[locale] = bucket;
+        }
+    }
+    if (body.pages !== undefined) {
+        if (!isObjectRecord(body.pages))
+            return 'pages must be keyed by locale';
+        seed.pages = {};
+        for (const [locale, byRoute] of Object.entries(body.pages)) {
+            if (!isObjectRecord(byRoute))
+                return `pages.${locale} must be keyed by route id`;
+            const bucket = {};
+            for (const [routeId, value] of Object.entries(byRoute)) {
+                if (!routeId.startsWith('/'))
+                    return `pages.${locale}: "${routeId}" is not a route id`;
+                if (Array.isArray(value)) {
+                    const entries = parseEntries(value);
+                    if (typeof entries === 'string')
+                        return `pages.${locale}.${routeId}: ${entries}`;
+                    bucket[routeId] = entries;
+                }
+                else if (isObjectRecord(value)) {
+                    bucket[routeId] = value;
+                }
+                else
+                    return `pages.${locale}.${routeId} must be an object or an entry list`;
+            }
+            seed.pages[locale] = bucket;
+        }
+    }
+    if (body.site !== undefined) {
+        if (!isObjectRecord(body.site))
+            return 'site must be an object';
+        seed.site = body.site;
+    }
+    return seed;
+};
+export const postSeed = async (ctx) => {
+    const body = await readJson(ctx.event);
+    if (body === undefined)
+        return badRequest('invalid json');
+    const seed = parseSeed(body);
+    if (typeof seed === 'string')
+        return badRequest(seed);
+    const force = isObjectRecord(body) && body.force === true;
+    const result = ctx.store.seed(ctx.projectId, seed, { force });
+    if (!result.ok)
+        return Response.json(result, { status: 409 });
+    ctx.cache.clear();
+    return Response.json(result);
+};
+export const getExport = (ctx) => Response.json(ctx.store.exportPublished(ctx.projectId));

package/dist/backend/routes/table.js

@@ -6,6 +6,7 @@ import { getLogin, getLoginSuccess, postLogin } from './login.js';
 import { deleteReleaseItems, getRelease, getReleaseHistory, postReleaseDiscard, postReleaseHistoryPreviewKey, postReleaseItems, postReleasePreviewKey, postReleasePublish, postReleaseRevert } from './release.js';
 import { deleteMediaItem, getMedia, getUpload, postMedia } from './media.js';
 import { getDeploy, postDeploy } from './deploy.js';
+import { getExport, postSeed } from './seed.js';
 import { postTestReset } from './test-reset.js';
 export const ROUTES = [
     { method: 'GET', segments: ['docs'], auth: 'public', handler: getDocs },
@@ -65,6 +66,8 @@ export const ROUTES = [
     },
     { method: 'GET', segments: ['deploy'], auth: 'required', handler: getDeploy },
     { method: 'POST', segments: ['deploy'], auth: 'required', handler: postDeploy },
+    { method: 'POST', segments: ['seed'], auth: 'required', handler: postSeed },
+    { method: 'GET', segments: ['export'], auth: 'required', handler: getExport },
     { method: 'GET', segments: ['media'], auth: 'required', handler: getMedia },
     { method: 'POST', segments: ['media'], auth: 'required', handler: postMedia },
     { method: 'DELETE', segments: ['media', ':id'], auth: 'required', handler: deleteMediaItem },

package/dist/backend/store/migrations/0004-release-publisher.d.ts

@@ -0,0 +1 @@
+export declare const sql = "\nALTER TABLE releases ADD COLUMN published_by_email TEXT;\nALTER TABLE releases ADD COLUMN published_by_name TEXT;\nUPDATE releases SET\n  published_by_email = (SELECT e.email FROM cms_editors e WHERE e.id = releases.published_by),\n  published_by_name  = (SELECT e.name  FROM cms_editors e WHERE e.id = releases.published_by);\n";

package/dist/backend/store/migrations/0004-release-publisher.js

@@ -0,0 +1,15 @@
+// Who published a release, as they were at the time.
+//
+// `published_by` is an opaque editor id, which is all the auth adapter
+// promises to keep stable — and all the admin bar could show. The publisher's
+// email and name are now captured on the row at publish time, so history reads
+// the same under any adapter and survives the account being renamed or
+// removed. Existing rows are filled from `cms_editors` where the id still
+// resolves; the rest stay null and readers fall back to the id.
+export const sql = `
+ALTER TABLE releases ADD COLUMN published_by_email TEXT;
+ALTER TABLE releases ADD COLUMN published_by_name TEXT;
+UPDATE releases SET
+  published_by_email = (SELECT e.email FROM cms_editors e WHERE e.id = releases.published_by),
+  published_by_name  = (SELECT e.name  FROM cms_editors e WHERE e.id = releases.published_by);
+`;

package/dist/backend/store/migrations/index.js

@@ -1,6 +1,7 @@
 import { sql as init } from './0001-init.js';
 import { sql as site } from './0002-site.js';
 import { sql as editors } from './0003-editors.js';
+import { sql as releasePublisher } from './0004-release-publisher.js';
 /**
  * Every migration, in apply order.
  *
@@ -14,5 +15,6 @@ import { sql as editors } from './0003-editors.js';
 export const MIGRATIONS = [
     { name: '0001_init.sql', sql: init },
     { name: '0002_site.sql', sql: site },
-    { name: '0003_editors.sql', sql: editors }
+    { name: '0003_editors.sql', sql: editors },
+    { name: '0004_release_publisher.sql', sql: releasePublisher }
 ];

package/dist/backend/store/queries.d.ts

@@ -1,7 +1,8 @@
 import { type PageEntry, type PageDeleteOutcome } from '../../core/page-entry.js';
 import { type Tree } from '../../core/path.js';
-import type { AddReleaseItemInput, CreatePageResult, DiscardItemTarget, ListMediaOptions, ListMediaResult, MediaItem, OpenRelease, PageMapRoute, PublishedRelease, ReleaseItem, RenamePageResult, StagePageDeleteResult } from '../../core/wire.js';
+import type { AddReleaseItemInput, CmsSeed, CreatePageResult, DiscardItemTarget, ListMediaOptions, ListMediaResult, MediaItem, OpenRelease, PageMapRoute, PublishedRelease, ReleaseItem, RenamePageResult, SeedResponse, StagePageDeleteResult } from '../../core/wire.js';
 import type { SqliteDb } from './sqlite.js';
+import type { CmsEditor } from '../types.js';
 /** The locale a request falls back to when it names none. */
 export declare const DEFAULT_LOCALE = "en";
 /** An opaque, unguessable key for a release's preview URL. */
@@ -32,6 +33,7 @@ export declare const createStore: (db: SqliteDb) => {
     createPage: (projectId: string, userId: string, routeId: string, locale: string, params: Record<string, string>, metadata?: Record<string, unknown>) => CreatePageResult;
     deleteMediaItem: (projectId: string, id: string) => MediaItem | null;
     discardOpenRelease: (projectId: string, userId: string) => boolean;
+    exportPublished: (projectId: string) => CmsSeed;
     discardReleaseItem: (projectId: string, userId: string, target: DiscardItemTarget) => boolean;
     findMediaItem: (projectId: string, id: string) => MediaItem | null;
     findOpenReleaseByPreviewKey: (projectId: string, key: string) => OpenRelease | null;
@@ -43,6 +45,7 @@ export declare const createStore: (db: SqliteDb) => {
     getPublishedPageEntry: (projectId: string, locale: string, routeId: string, params: Record<string, string>) => PageEntry | null;
     getPublishedSiteTree: (projectId: string) => Tree;
     getReleaseHistory: (projectId: string) => PublishedRelease[];
+    hasPublishedContent: (projectId: string) => boolean;
     listAllPages: (projectId: string, userId: string, locale: string) => PageMapRoute[];
     listMediaItems: (projectId: string, { offset, limit }?: ListMediaOptions) => ListMediaResult;
     listPageParamValues: (projectId: string, routeId: string, param: string) => string[];
@@ -50,7 +53,7 @@ export declare const createStore: (db: SqliteDb) => {
         id: string;
         items: ReleaseItem[];
     } | null;
-    publishRelease: (projectId: string, userId: string, name?: string) => PublishedRelease | null;
+    publishRelease: (projectId: string, user: CmsEditor, name?: string) => PublishedRelease | null;
     regeneratePreviewKey: (projectId: string, userId: string) => string | null;
     regeneratePublishedPreviewKey: (projectId: string, releaseId: string) => string | null;
     renamePage: (projectId: string, userId: string, args: {
@@ -60,7 +63,10 @@ export declare const createStore: (db: SqliteDb) => {
         toParams: Record<string, string>;
         toUrl: string;
     }) => RenamePageResult;
-    revertRelease: (projectId: string, releaseId: string, userId: string) => PublishedRelease | null;
+    revertRelease: (projectId: string, releaseId: string, user: CmsEditor) => PublishedRelease | null;
+    seed: (projectId: string, input: CmsSeed, opts?: {
+        force?: boolean;
+    }) => SeedResponse;
     seedPublishedDocs: (projectId: string, layouts: Record<string, Record<string, Tree>>, pages: Record<string, Record<string, PageEntry[]>>) => void;
     stagePageDelete: (projectId: string, userId: string, routeId: string, locale: string, params: Record<string, string>, outcome?: PageDeleteOutcome) => StagePageDeleteResult;
 };

package/dist/backend/store/queries.js

@@ -517,7 +517,7 @@ export const createStore = (db) => {
 			   updated_by_release = excluded.updated_by_release`);
     const updatePublishedPageTombstoneStmt = () => db.prepare('UPDATE published_pages SET tombstone = ?, updated_at = ?, updated_by_release = ? WHERE project_id = ? AND locale = ? AND route_id = ? AND params_hash = ?');
     const deletePublishedPageStmt = () => db.prepare('DELETE FROM published_pages WHERE project_id = ? AND locale = ? AND route_id = ? AND params_hash = ?');
-    const insertReleaseStmt = () => db.prepare('INSERT INTO releases (id, project_id, seq, name, published_by, published_at, preview_key) VALUES (?, ?, ?, ?, ?, ?, ?)');
+    const insertReleaseStmt = () => db.prepare('INSERT INTO releases (id, project_id, seq, name, published_by, published_by_email, published_by_name, published_at, preview_key) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)');
     const insertReleaseItemStmt = () => db.prepare('INSERT INTO release_items (release_id, project_id, seq, kind, route_id, locale, params_hash, params, tree, prior_tree, outcome, prior_tombstone, added_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)');
     const deleteOpenItemsForUserStmt = () => db.prepare('DELETE FROM open_release_items WHERE project_id = ? AND user_id = ?');
     /**
@@ -527,7 +527,8 @@ export const createStore = (db) => {
      * open release. Returns the new `PublishedRelease`, or null if there's nothing
      * to publish.
      */
-    const publishRelease = (projectId, userId, name) => {
+    const publishRelease = (projectId, user, name) => {
+        const userId = user.id;
         const tx = db.transaction(() => {
             ensureProjectState(projectId);
             const releaseRow = getOpenReleaseStmt().get(projectId, userId);
@@ -546,7 +547,7 @@ export const createStore = (db) => {
             // resolves on every per-item insert below. We delete the header at the
             // end if the body turned out to be empty.
             const finalName = name ?? releaseRow.name ?? null;
-            insertReleaseStmt().run(releaseId, projectId, seq, finalName, userId, publishedAt, previewKey);
+            insertReleaseStmt().run(releaseId, projectId, seq, finalName, user.id, user.email, user.name, publishedAt, previewKey);
             for (const item of items) {
                 if (item.kind === 'site') {
                     const target = getPublishedSiteTree(projectId);
@@ -635,7 +636,7 @@ export const createStore = (db) => {
             deleteOpenReleaseStmt().run(projectId, userId);
             const result = {
                 id: releaseId,
-                publishedBy: userId,
+                publishedBy: { id: user.id, email: user.email, name: user.name },
                 publishedAt,
                 preview_key: previewKey,
                 items: publishedItems
@@ -646,9 +647,9 @@ export const createStore = (db) => {
         });
         return tx();
     };
-    const listReleaseHistoryStmt = () => db.prepare('SELECT id, name, published_by, published_at, preview_key, reverted_at FROM releases WHERE project_id = ? ORDER BY seq ASC');
-    const findReleaseByPreviewKeyStmt = () => db.prepare('SELECT id, name, published_by, published_at, preview_key, reverted_at, seq FROM releases WHERE project_id = ? AND preview_key = ?');
-    const getReleaseByIdStmt = () => db.prepare('SELECT id, name, published_by, published_at, preview_key, reverted_at, seq FROM releases WHERE project_id = ? AND id = ?');
+    const listReleaseHistoryStmt = () => db.prepare('SELECT id, name, published_by, published_by_email, published_by_name, published_at, preview_key, reverted_at FROM releases WHERE project_id = ? ORDER BY seq ASC');
+    const findReleaseByPreviewKeyStmt = () => db.prepare('SELECT id, name, published_by, published_by_email, published_by_name, published_at, preview_key, reverted_at, seq FROM releases WHERE project_id = ? AND preview_key = ?');
+    const getReleaseByIdStmt = () => db.prepare('SELECT id, name, published_by, published_by_email, published_by_name, published_at, preview_key, reverted_at, seq FROM releases WHERE project_id = ? AND id = ?');
     const listReleaseItemsByReleaseIdStmt = () => db.prepare('SELECT kind, route_id, locale, params, tree, prior_tree, outcome, prior_tombstone FROM release_items WHERE release_id = ? ORDER BY id');
     const listReleaseItemsAfterSeqStmt = () => db.prepare('SELECT seq, kind, route_id, locale, params, tree, prior_tree, outcome, prior_tombstone FROM release_items WHERE project_id = ? AND seq > ? ORDER BY seq DESC, id DESC');
     const updateReleasePreviewKeyStmt = () => db.prepare('UPDATE releases SET preview_key = ? WHERE id = ?');
@@ -702,7 +703,11 @@ export const createStore = (db) => {
         const items = listReleaseItemsByReleaseIdStmt().all(row.id).map(rowToPublishedItem);
         const r = {
             id: row.id,
-            publishedBy: row.published_by,
+            publishedBy: {
+                id: row.published_by,
+                email: row.published_by_email,
+                name: row.published_by_name
+            },
             publishedAt: row.published_at,
             preview_key: row.preview_key,
             items
@@ -822,7 +827,7 @@ export const createStore = (db) => {
     // ---------------------------------------------------------------------------
     // Revert
     // ---------------------------------------------------------------------------
-    const revertRelease = (projectId, releaseId, userId) => {
+    const revertRelease = (projectId, releaseId, user) => {
         const tx = db.transaction(() => {
             ensureProjectState(projectId);
             const sourceRow = getReleaseByIdStmt().get(projectId, releaseId);
@@ -839,7 +844,7 @@ export const createStore = (db) => {
             const inverseName = sourceRow.name
                 ? `Revert "${sourceRow.name}"`
                 : `Revert ${sourceRow.id.slice(0, 8)}`;
-            insertReleaseStmt().run(inverseId, projectId, seq, inverseName, userId, publishedAt, previewKey);
+            insertReleaseStmt().run(inverseId, projectId, seq, inverseName, user.id, user.email, user.name, publishedAt, previewKey);
             for (const item of sourceItems) {
                 if (item.kind === 'site') {
                     const restoreTree = item.priorTree ?? {};
@@ -962,7 +967,7 @@ export const createStore = (db) => {
             return {
                 id: inverseId,
                 name: inverseName,
-                publishedBy: userId,
+                publishedBy: { id: user.id, email: user.email, name: user.name },
                 publishedAt,
                 preview_key: previewKey,
                 items: inverseItems
@@ -1172,6 +1177,92 @@ export const createStore = (db) => {
         });
         tx();
     };
+    // ---------------------------------------------------------------------------
+    // Seed / export
+    // ---------------------------------------------------------------------------
+    const countPublishedStmt = () => db.prepare(`SELECT (SELECT COUNT(*) FROM published_pages WHERE project_id = ?)
+			      + (SELECT COUNT(*) FROM published_layouts WHERE project_id = ?)
+			      + (SELECT COUNT(*) FROM published_site WHERE project_id = ?) AS n`);
+    /** Whether the project holds any published page, layout or site row. */
+    const hasPublishedContent = (projectId) => (countPublishedStmt().get(projectId, projectId, projectId)?.n ?? 0) > 0;
+    /**
+     * Seed a project's published content from a {@link CmsSeed} — a template's
+     * `content/` at project creation, or an export of another project. Writes
+     * the published rows directly, outside the release flow: there is no editor
+     * and nothing to revert to. Refuses when the project already has published
+     * rows unless `force`, so a second run cannot silently overwrite edits.
+     * Rows a forced seed does not name are left alone. Bumps `cms_version` so
+     * cached public reads are invalidated.
+     */
+    const seed = (projectId, input, opts = {}) => {
+        const tx = db.transaction(() => {
+            if (!opts.force && hasPublishedContent(projectId)) {
+                return { ok: false, reason: 'already-seeded' };
+            }
+            ensureProjectState(projectId);
+            const seedReleaseId = `seed-${projectId}`;
+            const at = nowIso();
+            const locales = new Set();
+            let layouts = 0;
+            let pages = 0;
+            for (const [locale, byRoute] of Object.entries(input.layouts ?? {})) {
+                for (const [routeId, tree] of Object.entries(byRoute)) {
+                    locales.add(locale);
+                    layouts += 1;
+                    upsertPublishedLayoutStmt().run(projectId, locale, routeId, JSON.stringify(tree), at, seedReleaseId);
+                }
+            }
+            for (const [locale, byRoute] of Object.entries(input.pages ?? {})) {
+                for (const [routeId, value] of Object.entries(byRoute)) {
+                    const entries = Array.isArray(value)
+                        ? value
+                        : [{ params: {}, published: value }];
+                    for (const entry of entries) {
+                        locales.add(locale);
+                        pages += 1;
+                        upsertPublishedPageStmt().run(projectId, locale, routeId, paramsHash(entry.params), JSON.stringify(entry.params), JSON.stringify(entry.published), entry.tombstone ? JSON.stringify(entry.tombstone) : null, at, seedReleaseId);
+                    }
+                }
+            }
+            const site = !!input.site;
+            if (input.site) {
+                upsertPublishedSiteStmt().run(projectId, JSON.stringify(input.site), at, seedReleaseId);
+            }
+            bumpProjectVersionStmt().run(projectId);
+            return { ok: true, seeded: { locales: [...locales].sort(), layouts, pages, site } };
+        });
+        return tx();
+    };
+    /**
+     * Every published row, in the shape {@link seed} accepts. Tombstoned pages
+     * are omitted: a seed describes content, not deletions.
+     */
+    const exportPublished = (projectId) => {
+        const out = { layouts: {}, pages: {} };
+        for (const { locale } of allLocalesForProjectStmt().all(projectId, projectId)) {
+            const layouts = {};
+            for (const r of allLayoutsByLocaleStmt().all(projectId, locale)) {
+                layouts[r.route_id] = parseTree(r.tree) ?? {};
+            }
+            if (Object.keys(layouts).length > 0)
+                out.layouts[locale] = layouts;
+            const pages = {};
+            for (const r of allPagesByLocaleStmt().all(projectId, locale)) {
+                if (parseOutcome(r.tombstone))
+                    continue;
+                (pages[r.route_id] ??= []).push({
+                    params: parseParams(r.params),
+                    published: parseTree(r.tree) ?? {}
+                });
+            }
+            if (Object.keys(pages).length > 0)
+                out.pages[locale] = pages;
+        }
+        const site = getPublishedSiteTree(projectId);
+        if (Object.keys(site).length > 0)
+            out.site = site;
+        return out;
+    };
     return {
         __resetProjectForTests,
         addReleaseItems,
@@ -1181,6 +1272,7 @@ export const createStore = (db) => {
         createPage,
         deleteMediaItem,
         discardOpenRelease,
+        exportPublished,
         discardReleaseItem,
         findMediaItem,
         findOpenReleaseByPreviewKey,
@@ -1192,6 +1284,7 @@ export const createStore = (db) => {
         getPublishedPageEntry,
         getPublishedSiteTree,
         getReleaseHistory,
+        hasPublishedContent,
         listAllPages,
         listMediaItems,
         listPageParamValues,
@@ -1201,6 +1294,7 @@ export const createStore = (db) => {
         regeneratePublishedPreviewKey,
         renamePage,
         revertRelease,
+        seed,
         seedPublishedDocs,
         stagePageDelete
     };