@tideworthy/tidysites-platform 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.9.0
+
+- Editor: sections are an EmDash `blocks` field (`sections` by default), and the forms come from the seed's block type definitions (`slug`, `type`, `validation.options`, `subFields`) instead of Block Kit shapes. Fields render by EmDash type: string, text, url, number, integer, boolean, datetime, select, multiSelect, image (the media picker, storing EmDash's media value) and repeater; Portable Text and file fields say "edit in the admin". New blocks carry no `_version` so EmDash stamps the active one; a saved block keeps its `_type`, `_key` and `_version`, and fields the form read as empty are left out rather than written as null.
+- Editor: Publish reads the page's draft state from EmDash (`compare`), so a draft an agent staged over the API is publishable from the page; the count no longer depends on this browser's session.
+- `POST /_tidy/schema`: applies the template seed's block types, collections, fields and relations to a bootstrapped site (`onConflict: "update"`, no content, settings or menus). How a template schema change reaches a site provisioned before it. Refuses before bootstrap (409).
+
 ## 0.8.0
 
 - EmDash 1.0: the peer range is `>=1.0.0 <2.0.0` for `emdash` and `@emdash-cms/auth` (was 0.37 only). Nothing in the package changed: every export it depends on (`emdash/runtime` `getDb`, `emdash/seed` `loadSeed`, `emdash/middleware` `runScheduledTasks`, the repositories, `applySeed`, the auth token helpers) is still public in 1.0.1; only the `emdash/middleware/*` and `emdash/db/*-migrations` subpaths moved under `emdash/internal/*`, and this package never used them. Proven on a 0.37 database: the 1.0.1 runtime applied its 15 migrations on the first request (73 to 88), pages, sessions, editing, fill, maintenance and the content API all answered as before.

package/README.md

@@ -10,7 +10,7 @@ It is the only code in a Tidysites template that knows about the platform, and i
 npm install @tideworthy/tidysites-platform
 ```
 
-Peer dependencies: `astro` 7, `emdash` and `@emdash-cms/auth` 0.37.x, `kysely`. Published on npm as `@tideworthy/tidysites-platform`; GitHub tags `vX.Y.Z` match each version.
+Peer dependencies: `astro` 7, `emdash` and `@emdash-cms/auth` 1.x, `kysely`. Published on npm as `@tideworthy/tidysites-platform`; GitHub tags `vX.Y.Z` match each version.
 
 ## Wire it up
 
@@ -45,17 +45,17 @@ EmDash answers every page with `X-Frame-Options: SAMEORIGIN` unless a Content-Se
 
 ## The on-site editor
 
-EmDash's inline editor edits plain rich text; a Block Kit block inside a Portable Text field renders as an "edit in admin" placeholder. Templates built from blocks use the Tideworthy editor instead:
+A template built from sections (an EmDash `blocks` field) uses the Tideworthy editor on the site:
 
 ```astro
 ---
 import TidyEditor from "@tideworthy/tidysites-platform/editor";
-const editMode = Astro.cookies.get("emdash-edit-mode")?.value === "true";
+import seed from "../../seed/seed.json";
 ---
-{editMode && <TidyEditor collection="pages" id={page.data.id} blocks={blockSchema} value={content} />}
+<TidyEditor collection="pages" id={page.data.id} field="sections" blocks={seed.blockTypes} value={page.data.sections} records={[{ collection: "business", id, label: "Business details" }]} />
 ```
 
-The template renders the block list inside `<div data-tidy-blocks>` and each custom block inside `<div data-tidy-block={_key} data-tidy-type={_type}>`, and passes `PortableText` a copy of the array (`[...blocks]`) so EmDash's inline editor does not mount on it. `blocks` is the plugin definition's `portableTextBlocks`. Hovering a block shows a chip (Edit, move, add below, remove); Edit opens a panel built from the block's fields; Save writes a draft through EmDash's content API with the signed-in editor's session and reloads; Publish publishes every entry saved in the session. A text field whose id ends in `imageUrl` (or `photoUrl`, `logoUrl`) gets an image picker over the media library with upload. Records: wrap a region in `data-tidy-record="services" data-tidy-record-id="…" data-tidy-record-label="Service details"` and pass `records` to the component; the form comes from EmDash's manifest and saves publish at once. Pass the business record in `records` and it is always one click away in the pill. A section that lists records (a services grid) wraps each card in the same `data-tidy-record` attributes, so the card edits its record and the section's chip edits the section. On these pages EmDash's toolbar is hidden and its inline editing is off; article bodies keep EmDash's inline editor by passing the original array and not mounting this component.
+The template renders the sections inside `<div data-tidy-blocks>` and each one inside `<div data-tidy-block={_key} data-tidy-type={_type}>`. `blocks` is the seed's `blockTypes` (the same definitions EmDash's admin and MCP read); the form for a block comes from its retained version's fields. Hovering a block shows a chip (Edit, move, add below, remove); Edit opens the panel; Save writes the field through EmDash's content API with the signed-in editor's session, as a draft, and reloads. Publish appears when EmDash says the page has a draft (so a draft an agent staged over the API is publishable from the page) and publishes it. Image fields get a picker over the media library with upload and store EmDash's media value. Records: wrap a region in `data-tidy-record="services" data-tidy-record-id="…" data-tidy-record-label="Service details"` and pass `records` to the component; the form comes from EmDash's manifest and saves publish at once. Pass the business record in `records` and it is always one click away in the bar. A section that lists records (a services grid) wraps each card in the same `data-tidy-record` attributes, so the card edits its record and the section's chip edits the section. On these pages EmDash's toolbar is hidden and its inline editing is off; article bodies keep EmDash's inline editor by not passing a sections field.
 
 ## Bindings the routes read
 
@@ -125,6 +125,10 @@ Writes real content over the template's sample content on a bootstrapped site. S
 
 Entries are upserted by slug (`slug` defaults to `id`). An existing entry keeps every field the document does not name, so a fill can send only what it knows and the template's images and blocks stay underneath. `remove` deletes the named sample entries; slugs written by the same call are never removed, and unknown slugs are reported back in `missing`. Refuses with 409 before bootstrap. Returns `{ ok, settings, content: { created, updated, media }, removed, missing }`. Re-running the same document is safe.
 
+### `POST /_tidy/schema`
+
+Applies the template seed's structure to a site that is already set up: block types (new ones created, compatible versions amended), collections and their fields (existing ones updated to the template's definition, missing ones added, nothing deleted) and relations. Entries, settings, menus, taxonomies and sections are untouched. Refuses with 409 before bootstrap. Returns `{ ok, applied }` with EmDash's counts. This is how a template schema change reaches a site provisioned before it; the platform calls it before deploying the new template artifact.
+
 ### `POST /_tidy/maintenance?cron=…`
 
 Runs EmDash's scheduled work now (scheduled publishing, cleanup) and returns what it published. Workers in a dispatch namespace never receive cron triggers, so the platform's cron calls this on every site each minute.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tideworthy/tidysites-platform",
-	"version": "0.8.0",
+	"version": "0.9.0",
 	"description": "The Tidysites platform integration for EmDash sites: bootstrap, sessions, maintenance, health, and publish hooks under /_tidy/*.",
 	"license": "MIT",
 	"type": "module",
@@ -29,6 +29,7 @@
 		"./routes/health": "./src/routes/health.ts",
 		"./routes/rotate-token": "./src/routes/rotate-token.ts",
 		"./routes/fill": "./src/routes/fill.ts",
+		"./routes/schema": "./src/routes/schema.ts",
 		"./routes/maintenance": "./src/routes/maintenance.ts"
 	},
 	"scripts": {

package/src/editor/TidyEditor.astro

@@ -15,20 +15,22 @@
  * the bar is the one control. The bar sets `--tidy-bar` on <html> (its
  * height) so a template's sticky header can sit below it.
  */
-import type { Block, BlockSchema } from "./ops";
+import type { Block, BlockTypeSchema } from "./ops";
 
 interface Props {
 	collection?: string;
 	id?: string;
+	/** The entry's `blocks` field the sections live in; "sections" by default. */
 	field?: string;
-	blocks?: BlockSchema[];
+	/** The block types a section may be (the seed's `blockTypes`, filtered to what the field allows). */
+	blocks?: BlockTypeSchema[];
 	value?: Block[] | null;
 	/** Records reachable from the bar (the business) or from `[data-tidy-record]` regions on the page. */
 	records?: Array<{ collection: string; id: string; label: string }>;
 	/** What the bar calls this site; "Staging" by default. */
 	label?: string;
 }
-const { collection, id, field = "content", blocks, value, records = [], label = "Staging" } = Astro.props;
+const { collection, id, field = "sections", blocks, value, records = [], label = "Staging" } = Astro.props;
 const signedIn = Boolean(Astro.session ? await Astro.session.get("user") : null);
 const active = Astro.cookies.get("emdash-edit-mode")?.value === "true";
 const here = Astro.url.pathname + Astro.url.search;
@@ -96,9 +98,12 @@ const htmlClass = !signedIn ? "" : !active ? "tidy-has-bar tidy-idle" : editable
 	.tidy-form { display: grid; gap: 14px; }
 	.tidy-field { display: grid; gap: 6px; }
 	.tidy-field-label { font-weight: 600; font-size: 13px; }
-	.tidy-field input[type="text"], .tidy-field input[type="number"], .tidy-field textarea, .tidy-field select { width: 100%; box-sizing: border-box; border: 1px solid #c9d2cc; border-radius: 6px; padding: 8px 10px; font: inherit; background: #fff; color: inherit; }
+	.tidy-field input[type="text"], .tidy-field input[type="url"], .tidy-field input[type="number"], .tidy-field input[type="datetime-local"], .tidy-field textarea, .tidy-field select { width: 100%; box-sizing: border-box; border: 1px solid #c9d2cc; border-radius: 6px; padding: 8px 10px; font: inherit; background: #fff; color: inherit; }
 	.tidy-field textarea { resize: vertical; min-height: 88px; }
 	.tidy-field-toggle { display: flex; align-items: center; gap: 10px; }
+	.tidy-field-note { margin: 0; color: #4a5851; font-size: 13px; }
+	.tidy-multi { display: grid; gap: 6px; }
+	.tidy-multi-item { display: flex; align-items: center; gap: 8px; font-weight: 400; }
 	.tidy-repeater { border: 1px solid #d3dcd6; border-radius: 8px; padding: 12px; display: grid; gap: 12px; }
 	.tidy-repeater legend { font-weight: 600; padding: 0 6px; }
 	.tidy-repeater-item { display: grid; gap: 10px; padding: 12px; background: #f6f7f5; border-radius: 6px; }

package/src/editor/ops.ts

@@ -1,28 +1,48 @@
 /**
- * Pure operations on a page's block list (a Portable Text array whose custom
- * blocks carry `_type` and `_key`). The editor runtime calls these; the tests
- * cover them without a browser.
+ * Pure operations on a page's section list: an EmDash `blocks` field value,
+ * an array of typed blocks each carrying `_type`, `_version` and `_key`. The
+ * schemas are EmDash block type definitions (the seed's `blockTypes`), so the
+ * editor's forms, the admin's block editor and the MCP all read one contract.
+ * The editor runtime calls these; the tests cover them without a browser.
  */
-export type Block = { _type: string; _key?: string } & Record<string, unknown>;
+export type Block = { _type: string; _key?: string; _version?: number } & Record<string, unknown>;
+
+/** The field types a block definition may use (EmDash 1.0). */
+export type FieldType = "string" | "text" | "url" | "number" | "integer" | "boolean" | "datetime" | "select" | "multiSelect" | "portableText" | "image" | "file" | "repeater";
 
 export interface FieldSchema {
-	type: "text_input" | "number_input" | "toggle" | "select" | "repeater" | string;
-	action_id: string;
+	slug: string;
 	label: string;
-	multiline?: boolean;
-	options?: Array<{ label: string; value: string }>;
-	fields?: FieldSchema[];
-	item_label?: string;
-	min_items?: number;
-	max_items?: number;
+	type: FieldType | string;
+	required?: boolean;
+	defaultValue?: unknown;
+	description?: string;
+	validation?: {
+		options?: string[];
+		subFields?: FieldSchema[];
+		minItems?: number;
+		maxItems?: number;
+		[key: string]: unknown;
+	};
 }
 
-export interface BlockSchema {
-	type: string;
+/** One block type as the seed declares it. */
+export interface BlockTypeSchema {
+	slug: string;
 	label: string;
-	category?: string;
 	description?: string;
-	fields: FieldSchema[];
+	category?: string;
+	currentVersion: number;
+	versions: Array<{ version: number; fields: FieldSchema[] }>;
+}
+
+/** Field types the editor renders a control for; the rest are read-only here and edited in the admin. */
+export const EDITABLE_TYPES: ReadonlySet<string> = new Set(["string", "text", "url", "number", "integer", "boolean", "datetime", "select", "multiSelect", "image", "repeater"]);
+
+/** The fields of one retained version, or of the active version. */
+export function fieldsOf(type: BlockTypeSchema, version?: number): FieldSchema[] {
+	const v = version ?? type.currentVersion;
+	return type.versions.find((x) => x.version === v)?.fields ?? type.versions.find((x) => x.version === type.currentVersion)?.fields ?? [];
 }
 
 export function newKey(random: () => number = Math.random): string {
@@ -35,9 +55,9 @@ export function findBlock(blocks: Block[], key: string): Block | undefined {
 	return blocks.find((b) => b._key === key);
 }
 
-/** The block with `key` gets `data` merged over it; `_type` and `_key` never change. */
+/** The block with `key` gets `data` merged over it; `_type`, `_key` and `_version` never change. */
 export function updateBlock(blocks: Block[], key: string, data: Record<string, unknown>): Block[] {
-	return blocks.map((b) => (b._key === key ? { ...b, ...data, _type: b._type, _key: b._key } : b));
+	return blocks.map((b) => (b._key === key ? { ...b, ...data, _type: b._type, _key: b._key, ...(b._version !== undefined ? { _version: b._version } : {}) } : b));
 }
 
 export function moveBlock(blocks: Block[], key: string, direction: -1 | 1): Block[] {
@@ -55,7 +75,10 @@ export function removeBlock(blocks: Block[], key: string): Block[] {
 	return blocks.filter((b) => b._key !== key);
 }
 
-/** Insert a new block of `type` after the block with `afterKey` (or at the end). */
+/**
+ * Insert a new block of `type` after the block with `afterKey` (or at the end).
+ * No `_version`: EmDash stamps a new block with the type's active version.
+ */
 export function insertBlock(blocks: Block[], type: string, afterKey: string | null, data: Record<string, unknown>, key = newKey()): Block[] {
 	const block: Block = { ...data, _type: type, _key: key };
 	const i = afterKey ? blocks.findIndex((b) => b._key === afterKey) : -1;
@@ -63,32 +86,63 @@ export function insertBlock(blocks: Block[], type: string, afterKey: string | nu
 	return [...blocks.slice(0, i + 1), block, ...blocks.slice(i + 1)];
 }
 
-/** Empty values for every field in a schema, so a new block renders without holes. */
-export function defaultsFor(schema: BlockSchema): Record<string, unknown> {
+/**
+ * Starting values for a new block: the declared default where there is one,
+ * an empty string for text, false for a toggle, an empty list for a repeater,
+ * the first option for a select, and nothing at all for a number, image,
+ * file, date or rich text (EmDash accepts an absent optional field; it does
+ * not accept an empty string or null in a typed one).
+ */
+export function defaultsFor(type: BlockTypeSchema): Record<string, unknown> {
 	const out: Record<string, unknown> = {};
-	for (const f of schema.fields) {
-		if (f.type === "toggle") out[f.action_id] = false;
-		else if (f.type === "number_input") out[f.action_id] = null;
-		else if (f.type === "select") out[f.action_id] = f.options?.[0]?.value ?? "";
-		else if (f.type === "repeater") out[f.action_id] = [];
-		else out[f.action_id] = "";
+	for (const f of fieldsOf(type)) {
+		if (f.defaultValue !== undefined) out[f.slug] = structuredClone(f.defaultValue);
+		else if (f.type === "boolean") out[f.slug] = false;
+		else if (f.type === "repeater" || f.type === "multiSelect") out[f.slug] = [];
+		else if (f.type === "select") {
+			const first = f.validation?.options?.[0];
+			if (first !== undefined) out[f.slug] = first;
+		} else if (f.type === "string" || f.type === "text" || f.type === "url") out[f.slug] = "";
 	}
 	return out;
 }
 
-/** Coerce a raw form value into the field's stored type. */
+/**
+ * Coerce a raw form value into the field's stored type. Returns `undefined`
+ * for "no value" in a typed field so the key is left out of the saved block.
+ */
 export function coerce(field: FieldSchema, raw: unknown): unknown {
 	switch (field.type) {
-		case "toggle":
+		case "boolean":
 			return raw === true || raw === "on" || raw === "true";
-		case "number_input": {
-			if (raw === "" || raw === null || raw === undefined) return null;
+		case "number":
+		case "integer": {
+			if (raw === "" || raw === null || raw === undefined) return undefined;
 			const n = Number(raw);
-			return Number.isFinite(n) ? n : null;
+			if (!Number.isFinite(n)) return undefined;
+			return field.type === "integer" ? Math.trunc(n) : n;
 		}
+		case "select":
+			return typeof raw === "string" && raw !== "" ? raw : undefined;
+		case "multiSelect":
+			return Array.isArray(raw) ? raw.filter((x): x is string => typeof x === "string") : [];
 		case "repeater":
 			return Array.isArray(raw) ? raw : [];
+		case "image":
+		case "file":
+			return raw && typeof raw === "object" ? raw : undefined;
+		case "datetime":
+			return typeof raw === "string" && raw !== "" ? raw : undefined;
+		case "portableText":
+			return Array.isArray(raw) ? raw : undefined;
 		default:
 			return typeof raw === "string" ? raw : raw === null || raw === undefined ? "" : String(raw);
 	}
 }
+
+/** Drop keys whose value is `undefined` so an absent optional field stays absent. */
+export function compact(data: Record<string, unknown>): Record<string, unknown> {
+	const out: Record<string, unknown> = {};
+	for (const [k, v] of Object.entries(data)) if (v !== undefined) out[k] = v;
+	return out;
+}

package/src/editor/runtime.ts

@@ -3,21 +3,25 @@
 /**
  * The Tideworthy on-site editor. Runs on a page rendered in edit mode.
  *
- * Sections: every custom block sits in a frame (`[data-tidy-block]`, rendered
- * by the template); hovering shows a chip with Edit, Up, Down, Add and Remove,
- * and Edit opens a panel whose form comes from the block's field schema.
+ * Sections: every block of the page's `blocks` field sits in a frame
+ * (`[data-tidy-block]`, rendered by the template); hovering shows a chip with
+ * Edit, Up, Down, Add and Remove, and Edit opens a panel whose form comes from
+ * the block type's field definitions (the same ones EmDash's admin and MCP
+ * read).
  *
  * Records: a region wrapped in `[data-tidy-record]` (a service's header, say)
  * gets an "Edit … details" chip whose form comes from EmDash's manifest for
- * that collection; the business record is always reachable from the pill.
+ * that collection; the business record is always reachable from the bar.
  *
- * Images: a block field whose id names an image URL, or a record field of
- * kind image, gets a picker over the site's media library with upload.
+ * Images: an `image` field, in a block or a record, gets a picker over the
+ * site's media library with upload and stores EmDash's media value.
  *
- * Saves go through EmDash's content API with the editor's session, as drafts;
- * Publish publishes every entry touched in this browser session.
+ * Saves go through EmDash's content API with the editor's session, as drafts.
+ * Publish reads the entry's draft state from EmDash (so a draft an agent
+ * staged over the API is publishable from the page too) and publishes it,
+ * plus any record whose publish failed in this browser session.
  */
-import { coerce, defaultsFor, insertBlock, moveBlock, removeBlock, updateBlock, type Block, type BlockSchema, type FieldSchema } from "./ops";
+import { EDITABLE_TYPES, coerce, compact, defaultsFor, fieldsOf, insertBlock, moveBlock, removeBlock, updateBlock, type Block, type BlockTypeSchema, type FieldSchema } from "./ops";
 
 interface RecordRef {
 	collection: string;
@@ -29,7 +33,7 @@ interface Config {
 	collection: string;
 	id: string;
 	field: string;
-	blocks: BlockSchema[];
+	blocks: BlockTypeSchema[];
 	value: Block[];
 	records?: RecordRef[];
 	/** Where "Done" goes: /_tidy/edit switching editing off and returning here. */
@@ -56,9 +60,8 @@ interface MediaItem {
 const API = "/_emdash/api";
 const CSRF = { "X-EmDash-Request": "1" };
 const PENDING_KEY = "tidy-pending";
-const IMAGE_FIELD = /(image|photo|logo|picture)url$/i;
 /** Record fields the panel never shows: system, structural, or edited elsewhere. */
-const HIDDEN_RECORD_FIELDS = new Set(["content", "sort", "brand_primary", "brand_accent", "font_display", "font_body"]);
+const HIDDEN_RECORD_FIELDS = new Set(["content", "sections", "sort", "brand_primary", "brand_accent", "font_display", "font_body"]);
 
 function el<K extends keyof HTMLElementTagNameMap>(tag: K, attrs: Record<string, string> = {}, children: Array<Node | string> = []): HTMLElementTagNameMap[K] {
 	const e = document.createElement(tag);
@@ -75,18 +78,25 @@ function mediaUrl(m: MediaItem): string {
 	return m.url ?? `${API}/media/file/${m.storageKey}`;
 }
 
-/** The value an image record field stores: EmDash's media value for a library item. */
+/** The value an image field stores: EmDash's media value for a library item. */
 function mediaValue(m: MediaItem): Record<string, unknown> {
 	return { provider: "local", id: m.id, alt: m.alt ?? "", width: m.width ?? undefined, height: m.height ?? undefined, mimeType: m.mimeType, filename: m.filename, meta: { storageKey: m.storageKey } };
 }
 
+/** A URL to preview a stored image value, whatever shape it came in. */
+function imageSrc(v: unknown): string | null {
+	if (!v || typeof v !== "object") return typeof v === "string" && v ? v : null;
+	const o = v as { src?: string; url?: string; meta?: { storageKey?: string } };
+	return o.src ?? o.url ?? (o.meta?.storageKey ? `${API}/media/file/${o.meta.storageKey}` : null);
+}
+
 function api(path: string, init: RequestInit = {}): Promise<Response> {
 	return fetch(`${API}${path}`, { credentials: "same-origin", ...init, headers: { ...CSRF, ...(init.headers as Record<string, string> | undefined) } });
 }
 
 export function start(config: Config): void {
 	let value: Block[] = config.value;
-	const schemaOf = (type: string) => config.blocks.find((b) => b.type === type);
+	const schemaOf = (type: string) => config.blocks.find((b) => b.slug === type);
 	const frames = () => Array.from(document.querySelectorAll<HTMLElement>("[data-tidy-block]"));
 
 	// EmDash's inline editor is for prose pages; here the sections and records own their fields.
@@ -94,8 +104,10 @@ export function start(config: Config): void {
 	document.querySelectorAll("[data-emdash-ref]").forEach((n) => n.removeAttribute("data-emdash-ref"));
 
 	// --- pending publishes ---------------------------------------------------
+	// Records whose publish failed after a save; the page itself is read from EmDash.
 	const pending = new Set<string>(JSON.parse(sessionStorage.getItem(PENDING_KEY) ?? "[]") as string[]);
 	const persistPending = () => sessionStorage.setItem(PENDING_KEY, JSON.stringify([...pending]));
+	let pageHasDraft = false;
 
 	// --- the bar's controls --------------------------------------------------
 	const status = document.getElementById("tidy-bar-actions") ?? document.body.appendChild(el("div", { class: "tidy-bar-actions" }));
@@ -108,15 +120,29 @@ export function start(config: Config): void {
 	bizBtn.hidden = !business;
 	bizBtn.addEventListener("click", () => business && void openRecord(business));
 	function refreshStatus(text?: string) {
-		const n = pending.size;
+		const n = pending.size + (pageHasDraft ? 1 : 0);
 		statusText.textContent = text ?? (n === 0 ? "" : `${n} unpublished change${n === 1 ? "" : "s"}`);
 		publishBtn.hidden = n === 0 && !text?.startsWith("Publish failed");
 	}
 	refreshStatus();
+	/** Ask EmDash whether this page has a draft that differs from what is live. */
+	async function readDraftState(): Promise<void> {
+		try {
+			const r = await api(`/content/${encodeURIComponent(config.collection)}/${encodeURIComponent(config.id)}/compare`);
+			if (!r.ok) return;
+			const j = (await r.json().catch(() => ({}))) as { data?: { hasChanges?: boolean } };
+			pageHasDraft = j.data?.hasChanges === true;
+			refreshStatus();
+		} catch {
+			// the bar just shows no count
+		}
+	}
+	void readDraftState();
 	publishBtn.addEventListener("click", async () => {
 		publishBtn.disabled = true;
 		refreshStatus("Publishing");
-		const targets = pending.size ? [...pending] : [`${config.collection}/${config.id}`];
+		const targets = new Set<string>(pending);
+		if (pageHasDraft || targets.size === 0) targets.add(`${config.collection}/${config.id}`);
 		let failed = 0;
 		for (const t of targets) {
 			const [collection, id] = t.split("/") as [string, string];
@@ -133,16 +159,17 @@ export function start(config: Config): void {
 	});
 
 	/**
-	 * Page blocks save as a draft the page previews in edit mode; Publish makes
-	 * them live. Record details (the business, a service) are read by many
-	 * pages from their published version, so a draft would look like nothing
-	 * happened: they save and publish in one step.
+	 * Page sections save as a draft the page previews in edit mode; Publish
+	 * makes them live. Record details (the business, a service) are read by
+	 * many pages from their published version, so a draft would look like
+	 * nothing happened: they save and publish in one step.
 	 */
 	async function saveEntry(collection: string, id: string, data: Record<string, unknown>, publishNow = false): Promise<boolean> {
 		refreshStatus("Saving");
 		const r = await api(`/content/${encodeURIComponent(collection)}/${encodeURIComponent(id)}`, { method: "PUT", headers: { "content-type": "application/json" }, body: JSON.stringify({ data }) });
 		if (!r.ok) {
-			refreshStatus(`Save failed (${r.status})`);
+			const j = (await r.json().catch(() => ({}))) as { error?: { message?: string } };
+			refreshStatus(`Save failed (${j.error?.message ?? r.status})`);
 			return false;
 		}
 		if (publishNow) {
@@ -153,9 +180,6 @@ export function start(config: Config): void {
 				refreshStatus(`Saved; publish failed (${p.status})`);
 				return false;
 			}
-		} else {
-			pending.add(`${collection}/${id}`);
-			persistPending();
 		}
 		refreshStatus("Saved. Reloading");
 		location.reload();
@@ -301,7 +325,7 @@ export function start(config: Config): void {
 	});
 
 	// --- image picker -----------------------------------------------------------
-	/** An image control. `get` returns the stored value (URL string or media value); set through `onPick`. */
+	/** An image control: preview, choose from the library, upload, remove. `onPick` receives the library item or null. */
 	function imageControl(label: string, currentUrl: string | null, onPick: (item: MediaItem | null) => void): HTMLElement {
 		const wrap = el("div", { class: "tidy-field tidy-image" }, [el("span", { class: "tidy-field-label", text: label })]);
 		const preview = el("div", { class: "tidy-image-preview" });
@@ -366,93 +390,120 @@ export function start(config: Config): void {
 	}
 
 	// --- block forms ---------------------------------------------------------
-	function fieldInput(f: FieldSchema, v: unknown, name: string): HTMLElement {
-		const wrap = el("label", { class: "tidy-field" }, [el("span", { class: "tidy-field-label", text: f.label })]);
-		if (f.type === "toggle") {
-			const cb = el("input", { type: "checkbox", name });
+	type Reader = () => unknown;
+
+	/** One control for a block field (or a repeater row's sub-field). Returns the element and a reader of its coerced value. */
+	function fieldControl(f: FieldSchema, v: unknown): { node: HTMLElement; read: Reader } {
+		const label = f.label || f.slug;
+		if (f.type === "image") {
+			let picked: unknown = v && typeof v === "object" ? v : undefined;
+			const node = imageControl(label, imageSrc(v), (item) => {
+				picked = item ? mediaValue(item) : undefined;
+			});
+			return { node, read: () => picked };
+		}
+		const wrap = el("label", { class: "tidy-field" }, [el("span", { class: "tidy-field-label", text: label })]);
+		if (f.type === "boolean") {
+			const cb = el("input", { type: "checkbox" });
 			cb.checked = v === true;
 			wrap.className = "tidy-field tidy-field-toggle";
 			wrap.prepend(cb);
-		} else if (f.type === "select") {
-			const s = el("select", { name });
-			for (const o of f.options ?? []) {
-				const opt = el("option", { value: o.value, text: o.label });
-				if (o.value === v) opt.selected = true;
+			return { node: wrap, read: () => cb.checked };
+		}
+		if (f.type === "select") {
+			const s = el("select");
+			if (!f.required) s.append(el("option", { value: "", text: "" }));
+			for (const o of f.validation?.options ?? []) {
+				const opt = el("option", { value: o, text: o });
+				if (o === v) opt.selected = true;
 				s.append(opt);
 			}
 			wrap.append(s);
-		} else if (f.type === "number_input") {
-			const i = el("input", { type: "number", name });
+			return { node: wrap, read: () => coerce(f, s.value) };
+		}
+		if (f.type === "multiSelect") {
+			const box = el("div", { class: "tidy-multi" });
+			const chosen = new Set(Array.isArray(v) ? (v as string[]) : []);
+			const boxes: HTMLInputElement[] = [];
+			for (const o of f.validation?.options ?? []) {
+				const cb = el("input", { type: "checkbox", value: o });
+				cb.checked = chosen.has(o);
+				boxes.push(cb);
+				box.append(el("label", { class: "tidy-multi-item" }, [cb, o]));
+			}
+			wrap.append(box);
+			return { node: wrap, read: () => boxes.filter((b) => b.checked).map((b) => b.value) };
+		}
+		if (f.type === "number" || f.type === "integer") {
+			const i = el("input", { type: "number", ...(f.type === "integer" ? { step: "1" } : { step: "any" }) });
 			i.value = typeof v === "number" ? String(v) : "";
 			wrap.append(i);
-		} else if (f.multiline) {
-			const t = el("textarea", { name, rows: "4" });
+			return { node: wrap, read: () => coerce(f, i.value) };
+		}
+		if (f.type === "datetime") {
+			const i = el("input", { type: "datetime-local" });
+			i.value = typeof v === "string" ? v.slice(0, 16) : "";
+			wrap.append(i);
+			return { node: wrap, read: () => (i.value ? new Date(i.value).toISOString() : undefined) };
+		}
+		if (f.type === "text") {
+			const t = el("textarea", { rows: "4" });
 			t.value = typeof v === "string" ? v : "";
 			wrap.append(t);
-		} else {
-			const i = el("input", { type: "text", name });
-			i.value = typeof v === "string" ? v : v === null || v === undefined ? "" : String(v);
-			wrap.append(i);
+			return { node: wrap, read: () => t.value };
 		}
-		return wrap;
-	}
-
-	/** A text field that stores an image URL gets the picker; the hidden input keeps the URL for the reader. */
-	function blockField(f: FieldSchema, v: unknown, name: string): HTMLElement {
-		if (f.type !== "text_input" || !IMAGE_FIELD.test(f.action_id)) return fieldInput(f, v, name);
-		const hidden = el("input", { type: "hidden", name });
-		hidden.value = typeof v === "string" ? v : "";
-		const control = imageControl(f.label, hidden.value || null, (item) => {
-			hidden.value = item ? mediaUrl(item) : "";
-		});
-		control.append(hidden);
-		return control;
+		const i = el("input", { type: f.type === "url" ? "url" : "text" });
+		i.value = typeof v === "string" ? v : v === null || v === undefined ? "" : String(v);
+		wrap.append(i);
+		return { node: wrap, read: () => i.value };
 	}
 
-	function buildBlockForm(schema: BlockSchema, data: Record<string, unknown>): { form: HTMLFormElement; read: () => Record<string, unknown> } {
+	function buildBlockForm(type: BlockTypeSchema, block: Block): { form: HTMLFormElement; read: () => Record<string, unknown> } {
 		const form = el("form", { class: "tidy-form" });
-		const repeaters = new Map<string, { field: FieldSchema; items: HTMLElement }>();
-		for (const f of schema.fields) {
+		const readers: Array<[string, Reader]> = [];
+		for (const f of fieldsOf(type, block._version)) {
+			if (!EDITABLE_TYPES.has(f.type)) {
+				form.append(el("p", { class: "tidy-field-note", text: `${f.label || f.slug}: edit in the admin` }));
+				continue;
+			}
 			if (f.type === "repeater") {
-				const box = el("fieldset", { class: "tidy-repeater" }, [el("legend", { text: f.label })]);
+				const sub = f.validation?.subFields ?? [];
+				const box = el("fieldset", { class: "tidy-repeater" }, [el("legend", { text: f.label || f.slug })]);
 				const items = el("div", { class: "tidy-repeater-items" });
-				const rows = Array.isArray(data[f.action_id]) ? (data[f.action_id] as Record<string, unknown>[]) : [];
+				const rows = Array.isArray(block[f.slug]) ? (block[f.slug] as Record<string, unknown>[]) : [];
+				const rowReaders = new Map<HTMLElement, Array<[string, Reader]>>();
 				const addItem = (row: Record<string, unknown>) => {
 					const item = el("div", { class: "tidy-repeater-item" });
-					for (const sub of f.fields ?? []) item.append(blockField(sub, row[sub.action_id], sub.action_id));
-					const rm = el("button", { type: "button", class: "tidy-btn tidy-btn-danger tidy-btn-sm", text: `Remove ${f.item_label ?? "item"}` });
-					rm.addEventListener("click", () => item.remove());
+					const rs: Array<[string, Reader]> = [];
+					for (const s of sub) {
+						const c = fieldControl(s, row[s.slug]);
+						item.append(c.node);
+						rs.push([s.slug, c.read]);
+					}
+					const rm = el("button", { type: "button", class: "tidy-btn tidy-btn-danger tidy-btn-sm", text: "Remove" });
+					rm.addEventListener("click", () => {
+						rowReaders.delete(item);
+						item.remove();
+					});
 					item.append(rm);
 					items.append(item);
+					rowReaders.set(item, rs);
 				};
 				rows.forEach(addItem);
-				const add = el("button", { type: "button", class: "tidy-btn tidy-btn-sm", text: `Add ${f.item_label ?? "item"}` });
+				const add = el("button", { type: "button", class: "tidy-btn tidy-btn-sm", text: "Add" });
 				add.addEventListener("click", () => addItem({}));
 				box.append(items, add);
 				form.append(box);
-				repeaters.set(f.action_id, { field: f, items });
-			} else form.append(blockField(f, data[f.action_id], f.action_id));
-		}
-		const readScope = (scope: ParentNode, fields: FieldSchema[]): Record<string, unknown> => {
-			const out: Record<string, unknown> = {};
-			for (const f of fields) {
-				if (f.type === "repeater") continue;
-				const input = scope.querySelector<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>(`[name="${f.action_id}"]`);
-				out[f.action_id] = coerce(f, f.type === "toggle" ? (input as HTMLInputElement | null)?.checked : input?.value);
+				readers.push([f.slug, () => Array.from(items.children).map((item) => compact(Object.fromEntries((rowReaders.get(item as HTMLElement) ?? []).map(([k, r]) => [k, r()]))))]);
+				continue;
 			}
-			return out;
-		};
+			const c = fieldControl(f, block[f.slug]);
+			form.append(c.node);
+			readers.push([f.slug, c.read]);
+		}
 		const read = (): Record<string, unknown> => {
 			const out: Record<string, unknown> = {};
-			for (const f of schema.fields) {
-				if (f.type === "repeater") {
-					const rep = repeaters.get(f.action_id)!;
-					out[f.action_id] = Array.from(rep.items.children).map((item) => readScope(item, f.fields ?? []));
-					continue;
-				}
-				const input = Array.from(form.children).map((c) => c.querySelector<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>(`[name="${f.action_id}"]`)).find(Boolean) ?? null;
-				out[f.action_id] = coerce(f, f.type === "toggle" ? (input as HTMLInputElement | null)?.checked : input?.value);
-			}
+			for (const [k, r] of readers) out[k] = r();
 			return out;
 		};
 		return { form, read };
@@ -460,26 +511,29 @@ export function start(config: Config): void {
 
 	function openBlock(key: string) {
 		const block = value.find((b) => b._key === key);
-		const schema = block ? schemaOf(block._type) : undefined;
-		if (!block || !schema) return;
-		const { form, read } = buildBlockForm(schema, block);
+		const type = block ? schemaOf(block._type) : undefined;
+		if (!block || !type) return;
+		const { form, read } = buildBlockForm(type, block);
 		const saveBtn = el("button", { type: "submit", class: "tidy-btn tidy-btn-primary", text: "Save" });
 		const cancel = el("button", { type: "button", class: "tidy-btn", text: "Cancel" });
 		cancel.addEventListener("click", closePanel);
 		form.addEventListener("submit", (e) => {
 			e.preventDefault();
 			saveBtn.disabled = true;
-			void saveBlocks(updateBlock(value, key, read()));
+			// Fields the form read as "no value" are removed from the block, not written as null.
+			const data = read();
+			const next = updateBlock(value, key, data).map((b) => (b._key === key ? compact(b) : b)) as Block[];
+			void saveBlocks(next);
 		});
 		form.append(el("div", { class: "tidy-panel-actions" }, [saveBtn, cancel]));
-		openPanel(schema.label, schema.description, form);
+		openPanel(type.label, type.description, form);
 	}
 
 	function openAdd(afterKey: string | null) {
 		const listEl = el("div", { class: "tidy-add-list" });
-		for (const s of config.blocks.filter((b) => b.category !== "Inline")) {
+		for (const s of config.blocks) {
 			const b = el("button", { type: "button", class: "tidy-add-item" }, [el("strong", { text: s.label }), el("span", { text: s.description ?? "" })]);
-			b.addEventListener("click", () => void saveBlocks(insertBlock(value, s.type, afterKey, defaultsFor(s))));
+			b.addEventListener("click", () => void saveBlocks(insertBlock(value, s.slug, afterKey, defaultsFor(s))));
 			listEl.append(b);
 		}
 		const cancel = el("button", { type: "button", class: "tidy-btn", text: "Cancel" });
@@ -507,13 +561,12 @@ export function start(config: Config): void {
 		const values: Record<string, unknown> = {};
 		const readers: Array<() => void> = [];
 		for (const [name, f] of Object.entries(fields)) {
-			if (HIDDEN_RECORD_FIELDS.has(name) || ["portableText", "reference", "json", "datetime"].includes(f.kind)) continue;
+			if (HIDDEN_RECORD_FIELDS.has(name) || ["portableText", "reference", "json", "datetime", "blocks"].includes(f.kind)) continue;
 			const label = f.label ?? name;
 			const v = data[name];
 			if (f.kind === "image") {
-				const cur = v as { src?: string; meta?: { storageKey?: string } } | null | undefined;
 				values[name] = v ?? null;
-				form.append(imageControl(label, cur?.src ?? (cur?.meta?.storageKey ? `${API}/media/file/${cur.meta.storageKey}` : null), (item) => {
+				form.append(imageControl(label, imageSrc(v), (item) => {
 					values[name] = item ? mediaValue(item) : null;
 				}));
 				continue;

package/src/index.ts

@@ -29,6 +29,7 @@ export const PLATFORM_ROUTES = [
 	{ pattern: "/_tidy/health", entrypoint: `${PACKAGE}/routes/health` },
 	{ pattern: "/_tidy/rotate-token", entrypoint: `${PACKAGE}/routes/rotate-token` },
 	{ pattern: "/_tidy/fill", entrypoint: `${PACKAGE}/routes/fill` },
+	{ pattern: "/_tidy/schema", entrypoint: `${PACKAGE}/routes/schema` },
 	{ pattern: "/_tidy/maintenance", entrypoint: `${PACKAGE}/routes/maintenance` }
 ] as const;
 

package/src/lib/handlers.ts

@@ -12,6 +12,12 @@ export interface SeedOps {
 	load(): Promise<Record<string, unknown> & { settings?: Record<string, unknown> }>;
 	validate(seed: unknown): { valid: boolean; errors?: unknown };
 	apply(seed: Record<string, unknown>): Promise<{ collections?: unknown; content?: unknown }>;
+	/**
+	 * Apply only the structural parts of a seed (block types, collections and
+	 * their fields, relations) to a site that is already set up, updating what
+	 * exists and adding what is missing. Never touches entries, settings or menus.
+	 */
+	applyStructure(seed: Record<string, unknown>): Promise<Record<string, unknown>>;
 	/** Upsert content entries by slug (existing entries are updated), downloading `$media` URLs into the site's storage. */
 	upsertContent(content: Record<string, FillEntry[]>): Promise<{ created: number; updated: number; media: number }>;
 }
@@ -121,6 +127,36 @@ export async function bootstrap(input: BootstrapInput, deps: Deps, requestOrigin
 	return { ok: true, userId: user.id, token: t.raw, steps };
 }
 
+// ---------------------------------------------------------------------------
+// Schema: bring an existing site's structure up to the template's
+// ---------------------------------------------------------------------------
+
+export interface SchemaResult {
+	ok: true;
+	applied: Record<string, unknown>;
+}
+
+/** The seed keys that describe structure; everything else is left out before applying. */
+const STRUCTURE_KEYS = ["$schema", "version", "defaultLocale", "blockTypes", "collections", "relations"] as const;
+
+/**
+ * Apply the template seed's block types, collections, fields and relations to
+ * a bootstrapped site. Existing definitions are updated to the template's,
+ * missing ones are created, nothing is deleted, and entries, settings, menus,
+ * taxonomies and sections are untouched. This is how a template schema change
+ * reaches a site that was provisioned before it. Refuses before bootstrap.
+ */
+export async function applySchema(deps: Deps): Promise<SchemaResult> {
+	if ((await deps.store.getOption("emdash:setup_complete")) !== true) throw new HttpError(409, "site is not bootstrapped yet");
+	const full = await deps.seed.load();
+	const structure: Record<string, unknown> = {};
+	for (const k of STRUCTURE_KEYS) if (full[k] !== undefined) structure[k] = full[k];
+	const v = deps.seed.validate(structure);
+	if (!v.valid) throw new HttpError(500, "invalid seed", v.errors);
+	const applied = await deps.seed.applyStructure(structure);
+	return { ok: true, applied };
+}
+
 // ---------------------------------------------------------------------------
 // Fill: write real content over the template's sample content
 // ---------------------------------------------------------------------------

package/src/lib/runtime.ts

@@ -47,6 +47,15 @@ export async function buildDeps(): Promise<Deps> {
 			load: async () => (await loadSeed()) as unknown as Record<string, unknown> & { settings?: Record<string, unknown> },
 			validate: (seed) => validateSeed(seed),
 			apply: (seed) => applySeed(db, seed as unknown as Parameters<typeof applySeed>[1], { includeContent: true, onConflict: "skip", ...storageOpt }),
+			// Structure only: "update" rewrites an existing collection's definition
+			// and upserts its fields (never deletes one), adds missing block types
+			// and amends compatible block versions. The caller has already stripped
+			// content, settings and menus from the document.
+			applyStructure: async (seed) => {
+				const r = (await applySeed(db, seed as unknown as Parameters<typeof applySeed>[1], { includeContent: false, onConflict: "update" })) as unknown as Record<string, unknown>;
+				const pick = (k: string) => (r[k] !== undefined ? { [k]: r[k] } : {});
+				return { ...pick("blockTypes"), ...pick("collections"), ...pick("fields"), ...pick("relations") };
+			},
 			// A content-only seed document: no collections, menus, or settings, so
 			// applySeed touches nothing but entries. "update" makes it an upsert by
 			// slug. applySeed replaces an existing entry's data wholesale, so fields

package/src/routes/schema.ts

@@ -0,0 +1,10 @@
+/** POST /_tidy/schema: the template's block types, collections and fields onto an existing site. */
+import { applySchema } from "../lib/handlers";
+import { json } from "../lib/http";
+import { methodNotAllowed, platformRoute } from "./_shared";
+
+export const prerender = false;
+
+export const POST = platformRoute(async (_context, deps) => json(await applySchema(deps)));
+
+export const ALL = methodNotAllowed("POST");

package/src/version.ts

@@ -1,3 +1,3 @@
 /** Kept in step with package.json by the release checklist in MAINTAINING.md. */
-export const VERSION = "0.8.0";
+export const VERSION = "0.9.0";
 export const PLUGIN_ID = "tidy-platform";