@getvitops/emdash 1.0.0 → 2.0.0-alpha.0

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { definePlugin, pluginResponse } from "emdash";
+import { definePlugin, getMenus, pluginResponse } from "emdash";
 import { iconMap } from "@getvitops/utils";
 import { designSystemPath, formatConfig, getAt, isConfig, mergePatch, resolveInput, setAt } from "@getvitops/generator/config";
 import { buildReverseIndex, patchToOverrideCss, validateColorContract } from "@getvitops/generator/tokens";
@@ -25,7 +25,165 @@ const SEMANTIC_ICON_OPTIONS = Object.keys(iconMap.fa7).sort().map((name) => ({
 	value: name
 }));
 
+// src/astro/blocks/tone.ts
+/**
+* The shared `tone` convention (UPSTREAM finding 21): every block that colours anything
+* takes one `tone` and, optionally, one `color`.
+*
+* - **`tone`** — a role name from the site's `colors.roles` (`brand-primary`, `danger`, a
+*   consumer-named surface role…), or a semantic name. Role first, then its semantic
+*   fallbacks, then `neutral`.
+* - **`color`** — the escape hatch: a palette hue (`amber`) or hue and step (`amber-300`).
+*   Wins over `tone` when set. Contrast is NOT checked for it — the generator's contrast
+*   contract covers roles, not arbitrary hue/step pairs — so it is for decoration.
+*
+* **Why CSS custom properties, not classes.** A class name built from a field value
+* (`bg-${tone}`) is invisible to Tailwind's scanner, so it generates nothing in that
+* format. The resolver instead returns an inline `style` of `--tone-*` properties that
+* the framework's `.tone` pattern (patterns/tone.css) reads. Each property is a `var()`
+* chain, so the fallback happens in CSS at render time and this module needs NO copy of
+* the site's config — a tone the site never defined degrades to `neutral`, not to
+* nothing.
+*
+* The inputs are editor-supplied strings that land inside a `style` attribute, so both are
+* validated against a closed identifier grammar before use; anything else is dropped.
+*/
+/** Semantic names every site is expected to define (`REQUIRED_ROLES`), plus common aliases. */
+const SEMANTIC_TONES = [
+	"neutral",
+	"info",
+	"success",
+	"warning",
+	"danger"
+];
+/**
+* When a role is absent, which others to try before `neutral`. Covers the framework's own
+* vocabulary (`ui-*`, `brand-*`) so a site that names only some of them still gets the
+* nearest relative rather than a grey block.
+*/
+const FALLBACKS = {
+	"brand-primary": ["ui-primary", "info"],
+	"brand-secondary": ["ui-secondary", "info"],
+	"ui-primary": ["info"],
+	"ui-secondary": ["info"],
+	"ui-accent": ["warning"],
+	surface: ["neutral"],
+	error: ["danger"],
+	notice: ["warning"],
+	note: ["info"],
+	it: ["ui-primary", "info"],
+	mk: ["ui-accent", "warning"]
+};
+const ROLE = /^[a-z][a-z0-9-]{0,40}$/;
+const HUE = /^([a-z][a-z0-9]*(?:-[a-z][a-z0-9]*)*?)(?:-(\d{2,3}))?$/;
+/** The role chain for a tone: itself, its relatives, then `neutral`. Pure and exported for tests. */
+function toneChain(tone) {
+	const name = typeof tone === "string" ? tone.trim().toLowerCase() : "";
+	if (!ROLE.test(name)) return ["neutral"];
+	return [.../* @__PURE__ */ new Set([
+		name,
+		...FALLBACKS[name] ?? [],
+		"neutral"
+	])];
+}
+/** `var(--a, var(--b, …))` over a chain of token names; the last link has no fallback. */
+function chain(tokens) {
+	return tokens.reduceRight((inner, token) => inner ? `var(${token}, ${inner})` : `var(${token})`, "");
+}
+/**
+* Resolve a block's `tone` / `color` fields.
+*
+* Returns an empty style when neither is set, so an unconfigured block carries no tone at
+* all (rather than a neutral one) and stays transparent.
+*/
+function resolveTone(tone, color) {
+	const hasTone = typeof tone === "string" && tone.trim() !== "";
+	const hue = typeof color === "string" ? HUE.exec(color.trim().toLowerCase()) : null;
+	if (hue) {
+		const [, name, step] = hue;
+		const at = (s) => `var(--color-${name}-${s})`;
+		return {
+			className: "tone",
+			style: [
+				`--tone-bg: ${at("100")}`,
+				`--tone-fg: ${at("900")}`,
+				`--tone-border: ${at("300")}`,
+				`--tone-solid: ${at(step ?? "600")}`,
+				`--tone-on-solid: #fff`
+			].join("; ")
+		};
+	}
+	if (!hasTone) return {
+		className: "tone",
+		style: ""
+	};
+	const roles = toneChain(tone);
+	const of = (prefix, suffix = "") => chain(roles.map((r) => `--color-${prefix}-${r}${suffix}`));
+	return {
+		className: "tone",
+		style: [
+			`--tone-bg: ${of("bg", "-muted")}`,
+			`--tone-fg: ${of("text")}`,
+			`--tone-border: ${of("border")}`,
+			`--tone-solid: ${chain([...roles.map((r) => `--color-bg-${r}-solid`), ...roles.map((r) => `--color-bg-${r}`)])}`,
+			`--tone-on-solid: ${chain(roles.map((r) => `--color-text-on-${r}`))}`
+		].join("; ")
+	};
+}
+
 // src/blocks.ts
+/** Route that fills every tone select with the site's own roles — see `index.ts`. */
+const TONES_ROUTE = "tones/list";
+/** Route that lists the site's EmDash menus for `vitops.nav`'s `menu` select — see `menus-route.ts`. */
+const MENUS_ROUTE = "menus/list";
+/**
+* The tone options an editor can always pick, before the site adds its own roles.
+* Static because Block Kit needs a non-empty `options` list even when `optionsRoute` is set
+* (it is the fallback if the route fails, and what non-block-editor renderers read).
+*/
+const STATIC_TONE_OPTIONS = [{
+	label: "None",
+	value: ""
+}, ...SEMANTIC_TONES.map((t) => ({
+	label: t[0].toUpperCase() + t.slice(1),
+	value: t
+}))];
+/**
+* The shared tone pair (UPSTREAM 21; resolution lives in `astro/blocks/tone.ts`): a `tone`
+* select that offers the site's roles, and a `color` escape hatch naming a palette hue.
+* Spread into any block that colours something.
+*/
+function toneFields() {
+	return [{
+		type: "select",
+		action_id: "tone",
+		label: "Tone (a colour role from the site)",
+		initial_value: "",
+		options: STATIC_TONE_OPTIONS,
+		optionsRoute: TONES_ROUTE
+	}, {
+		type: "text_input",
+		action_id: "color",
+		label: "Palette colour instead of a tone (e.g. amber or amber-300)"
+	}];
+}
+/** Heading level for a block's own heading; `h1` is reserved for the page title. */
+const levelField = (initial) => ({
+	type: "select",
+	action_id: "level",
+	label: "Heading level",
+	initial_value: initial,
+	options: [
+		"2",
+		"3",
+		"4",
+		"5",
+		"6"
+	].map((n) => ({
+		label: `h${n}`,
+		value: n
+	}))
+});
 const BLOCKS = [
 	{
 		/**
@@ -380,70 +538,104 @@ const BLOCKS = [
 		label: "Cards",
 		placeholder: "A grid of cards",
 		category: "Sections",
-		fields: [{
-			type: "repeater",
-			action_id: "cards",
-			label: "Cards",
-			item_label: "card",
-			min_items: 1,
-			fields: [
-				{
-					type: "text_input",
-					action_id: "title",
-					label: "Title"
-				},
-				{
-					type: "text_input",
-					action_id: "body",
-					label: "Text",
-					multiline: true
-				},
-				{
-					type: "text_input",
-					action_id: "image",
-					label: "Image URL"
-				},
-				{
-					type: "text_input",
-					action_id: "imageAlt",
-					label: "Image alt text"
-				},
-				{
-					type: "text_input",
-					action_id: "href",
-					label: "Link URL (makes the whole card clickable)"
-				},
-				{
-					type: "text_input",
-					action_id: "linkLabel",
-					label: "Link text",
-					initial_value: "Read more"
-				}
-			]
-		}, {
-			type: "select",
-			action_id: "columns",
-			label: "Columns",
-			initial_value: "3",
-			options: [
-				{
-					label: "1",
-					value: "1"
-				},
-				{
-					label: "2",
-					value: "2"
-				},
-				{
-					label: "3",
-					value: "3"
-				},
-				{
-					label: "4",
-					value: "4"
-				}
-			]
-		}]
+		fields: [
+			{
+				type: "repeater",
+				action_id: "cards",
+				label: "Cards",
+				item_label: "card",
+				min_items: 1,
+				fields: [
+					{
+						type: "text_input",
+						action_id: "title",
+						label: "Title"
+					},
+					{
+						type: "text_input",
+						action_id: "body",
+						label: "Text (write [link text](/url) for an inline link)",
+						multiline: true
+					},
+					{
+						type: "text_input",
+						action_id: "image",
+						label: "Image URL"
+					},
+					{
+						type: "text_input",
+						action_id: "imageAlt",
+						label: "Image alt text"
+					},
+					{
+						type: "text_input",
+						action_id: "href",
+						label: "Link URL (makes the whole card clickable)"
+					},
+					{
+						type: "text_input",
+						action_id: "linkLabel",
+						label: "Link text",
+						initial_value: "Read more"
+					},
+					{
+						type: "text_input",
+						action_id: "checklist",
+						label: "Checklist (panel style; one item per line)",
+						multiline: true
+					},
+					{
+						type: "text_input",
+						action_id: "ctaLabel",
+						label: "Button text (panel style)"
+					},
+					{
+						type: "text_input",
+						action_id: "ctaHref",
+						label: "Button URL (panel style)"
+					}
+				]
+			},
+			{
+				type: "select",
+				action_id: "variant",
+				label: "Style",
+				initial_value: "default",
+				options: [{
+					label: "Cards",
+					value: "default"
+				}, {
+					label: "Panels (tinted, with checklist and button)",
+					value: "panel"
+				}]
+			},
+			levelField("3"),
+			...toneFields(),
+			{
+				type: "select",
+				action_id: "columns",
+				label: "Columns",
+				initial_value: "3",
+				options: [
+					{
+						label: "1",
+						value: "1"
+					},
+					{
+						label: "2",
+						value: "2"
+					},
+					{
+						label: "3",
+						value: "3"
+					},
+					{
+						label: "4",
+						value: "4"
+					}
+				]
+			}
+		]
 	},
 	{
 		type: "vitops.accordion",
@@ -496,8 +688,9 @@ const BLOCKS = [
 			{
 				type: "text_input",
 				action_id: "heading",
-				label: "Heading"
+				label: "Heading (wrap words in *stars* to accent them)"
 			},
+			levelField("2"),
 			{
 				type: "text_input",
 				action_id: "body",
@@ -546,6 +739,37 @@ const BLOCKS = [
 					label: "Text and image side by side",
 					value: "split"
 				}]
+			},
+			...toneFields(),
+			{
+				type: "repeater",
+				action_id: "cards",
+				label: "Option cards under the buttons (optional)",
+				item_label: "card",
+				fields: [
+					{
+						type: "text_input",
+						action_id: "title",
+						label: "Title"
+					},
+					{
+						type: "text_input",
+						action_id: "body",
+						label: "Text (write [link text](/url) for an inline link)",
+						multiline: true
+					},
+					{
+						type: "text_input",
+						action_id: "href",
+						label: "Link URL (makes the card clickable)"
+					},
+					{
+						type: "text_input",
+						action_id: "linkLabel",
+						label: "Link text",
+						initial_value: "Learn more"
+					}
+				]
 			}
 		]
 	},
@@ -592,120 +816,904 @@ const BLOCKS = [
 				initial_value: false
 			}
 		]
-	}
-];
-/**
-* Resolve {@link BlockSelection} against {@link BLOCKS}.
-*
-* Pure so a misconfiguration fails at plugin construction, with the offending name in the
-* message, rather than as an editor menu that is quietly missing something.
-*/
-function selectBlocks(selection = {}) {
-	const known = new Set(BLOCKS.map((b) => b.type));
-	const check = (names, option) => {
-		for (const name of names ?? []) if (!known.has(name)) throw new Error(`[vitops] blocks.${option}: unknown block '${name}'. Known: ${[...known].join(", ")}.`);
-	};
-	check(selection.include, "include");
-	check(selection.exclude, "exclude");
-	const include = selection.include ? new Set(selection.include) : null;
-	const exclude = new Set(selection.exclude);
-	const base = BLOCKS.filter((b) => (!include || include.has(b.type)) && !exclude.has(b.type));
-	const extra = selection.extra ?? [];
-	const taken = new Set(BLOCKS.map((b) => b.type));
-	for (const block of extra) {
-		if (taken.has(block.type)) throw new Error(`[vitops] blocks.extra: type '${block.type}' is already defined.`);
-		taken.add(block.type);
-	}
-	return [...base, ...extra];
-}
-
-// src/design-system-route.ts
-/**
-* The `vitops.design-system` plugin route — what `<wc-theme-editor>` probes
-* and POSTs its patch to when mounted inside the EmDash admin (see this
-* package's README and AGENTS.md's "EmDash plugin as the design-system
-* editing surface" section). Mounted at
-* `/_emdash/api/plugins/vitops/design-system`.
-*
-* Two responsibilities, matching the dev-only `@getvitops/vite` endpoint's
-* contract byte-for-byte (`GET → { writable }`, `POST { patch } → { ok } |
-* { errors }`) so `<wc-theme-editor>` needs no branch for which one it's
-* talking to:
-*
-* 1. **Immediate**: persist the patch to `ctx.settings` — read back by the
-*    `page:fragments` hook in `index.ts`, which turns it into a site-wide
-*    `:root` override `<style>` on every public page. This is what makes an
-*    edit visible without a rebuild.
-* 2. **Canonical**: auto-commit the merged file to `site.deployment.branch`
-*    (default `dev`) via `@getvitops/utils/git`'s `commitFile()`, so the edit
-*    reaches the git-tracked `site.json` through this repo's own normal
-*    `dev → promote → main` review path — never a silent second source of
-*    truth. A commit failure (missing token, misconfigured repo, a transient
-*    GitHub error) is logged and surfaces as a warning, but never fails the
-*    save: the immediate override already works regardless.
-*
-* **Assumes `config` is a full site `Config`** (has `organization`/`site`),
-* not a bare `design-system.json` — true for any real EmDash site (it always
-* has a `site.json`), and the only case this plugin already handles anywhere
-* else (`vitopsHosting()`, `BLOCKS`).
-*
-* The GitHub token is read as `process.env.VITOPS_GITHUB_TOKEN` — matching
-* `hosting.ts`'s own `process.env.HOSTING` read in this same package, rather
-* than a `cloudflare:workers`-specific import: a native EmDash plugin runs
-* in-process with no isolation boundary (EmDash's own docs say plugins "can
-* access environment variables" directly), and this package already targets
-* both the Cloudflare and Node hosting targets through one `process.env`
-* convention (`nodejs_compat` on Workers maps bindings into `process.env`).
-*/
-const SETTINGS_KEY = "designSystemPatch";
-function json(status, body) {
-	return pluginResponse({
-		status,
-		headers: { "content-type": "application/json" },
-		body: {
-			kind: "text",
-			value: JSON.stringify(body)
-		}
-	});
-}
-/** Fetches the currently-stored patch, clearing it if the bundled `config`
-* (the last real build) already reflects every value in it — see the
-* module docblock's "self-clearing" note in AGENTS.md. */
-async function currentPatch(ctx, ds) {
-	const stored = await ctx.settings.get(SETTINGS_KEY);
-	if (!stored) return null;
-	const patchedColors = stored.patch["colors"];
-	if (patchedColors != null && JSON.stringify(mergePatch(ds.colors, patchedColors)) === JSON.stringify(ds.colors)) {
-		await ctx.settings.delete(SETTINGS_KEY);
-		return null;
-	}
-	return stored;
-}
-function createDesignSystemRoute(opts) {
-	const theme = opts.theme ?? "default";
-	return {
-		methods: ["GET", "POST"],
-		response: "raw",
-		permission: "plugins:manage",
-		handler: async (ctx) => {
-			const { designSystem: ds, config } = resolveInput(opts.config, {
-				theme,
-				siteEnv: "production"
-			});
-			if (ctx.request.method === "GET") {
-				await currentPatch(ctx, ds);
-				return json(200, { writable: true });
-			}
-			const patch = ctx.input?.patch;
-			if (patch == null || typeof patch !== "object" || Array.isArray(patch)) return json(400, { errors: ["body must be { patch: object }"] });
-			const mergedColors = mergePatch(ds.colors, patch["colors"] ?? {});
-			const contrastErrors = validateColorContract(mergedColors);
-			if (contrastErrors.length) return json(400, { errors: contrastErrors });
-			await ctx.settings.set(SETTINGS_KEY, {
-				patch,
-				at: Date.now()
-			});
-			const warnings = [];
+	},
+	{
+		type: "vitops.logos",
+		label: "Logos",
+		placeholder: "A still row of partner or client logos",
+		category: "Media",
+		fields: [
+			{
+				type: "text_input",
+				action_id: "label",
+				label: "Accessible name",
+				initial_value: "Partners"
+			},
+			{
+				type: "repeater",
+				action_id: "logos",
+				label: "Logos",
+				item_label: "logo",
+				min_items: 1,
+				fields: [
+					{
+						type: "text_input",
+						action_id: "image",
+						label: "Image URL"
+					},
+					{
+						type: "text_input",
+						action_id: "alt",
+						label: "Name (alt text)"
+					},
+					{
+						type: "text_input",
+						action_id: "href",
+						label: "Link URL (optional)"
+					}
+				]
+			},
+			{
+				type: "toggle",
+				action_id: "grayscale",
+				label: "Grey until hovered",
+				initial_value: false
+			},
+			{
+				type: "select",
+				action_id: "size",
+				label: "Logo height",
+				initial_value: "md",
+				options: [
+					{
+						label: "Small",
+						value: "sm"
+					},
+					{
+						label: "Medium",
+						value: "md"
+					},
+					{
+						label: "Large",
+						value: "lg"
+					}
+				]
+			}
+		]
+	},
+	{
+		type: "vitops.steps",
+		label: "Steps",
+		placeholder: "A numbered sequence joined by a connector line",
+		category: "Sections",
+		fields: [
+			{
+				type: "repeater",
+				action_id: "steps",
+				label: "Steps",
+				item_label: "step",
+				min_items: 1,
+				fields: [{
+					type: "text_input",
+					action_id: "title",
+					label: "Title"
+				}, {
+					type: "text_input",
+					action_id: "text",
+					label: "Text (write [link text](/url) for an inline link)",
+					multiline: true
+				}]
+			},
+			levelField("3"),
+			{
+				type: "select",
+				action_id: "layout",
+				label: "Layout",
+				initial_value: "column",
+				options: [{
+					label: "Stacked",
+					value: "column"
+				}, {
+					label: "Side by side when wide",
+					value: "row"
+				}]
+			},
+			...toneFields()
+		]
+	},
+	{
+		type: "vitops.stats",
+		label: "Stats",
+		placeholder: "Headline figures that count up, or labelled tiles",
+		category: "Sections",
+		fields: [
+			{
+				type: "repeater",
+				action_id: "stats",
+				label: "Figures",
+				item_label: "figure",
+				min_items: 1,
+				fields: [
+					{
+						type: "text_input",
+						action_id: "value",
+						label: "Figure (e.g. 82% or 11 hrs)"
+					},
+					{
+						type: "text_input",
+						action_id: "label",
+						label: "Label"
+					},
+					{
+						type: "text_input",
+						action_id: "group",
+						label: "Group (tiles style; small line above)"
+					},
+					{
+						type: "text_input",
+						action_id: "delta",
+						label: "Change (tiles style; e.g. +3 this week)"
+					},
+					{
+						type: "select",
+						action_id: "state",
+						label: "Change is",
+						initial_value: "",
+						options: [
+							{
+								label: "Neutral",
+								value: ""
+							},
+							{
+								label: "Good (up)",
+								value: "up"
+							},
+							{
+								label: "Bad (down)",
+								value: "down"
+							}
+						]
+					}
+				]
+			},
+			{
+				type: "select",
+				action_id: "variant",
+				label: "Style",
+				initial_value: "figures",
+				options: [{
+					label: "Figures",
+					value: "figures"
+				}, {
+					label: "Tiles",
+					value: "tiles"
+				}]
+			},
+			{
+				type: "toggle",
+				action_id: "animate",
+				label: "Count up when scrolled into view",
+				initial_value: true
+			},
+			...toneFields()
+		]
+	},
+	{
+		type: "vitops.callout",
+		label: "Callout",
+		placeholder: "A call-to-action band (not a dismissible banner)",
+		category: "Sections",
+		fields: [
+			{
+				type: "text_input",
+				action_id: "heading",
+				label: "Heading"
+			},
+			levelField("2"),
+			{
+				type: "text_input",
+				action_id: "body",
+				label: "Text (write [link text](/url) for an inline link)",
+				multiline: true
+			},
+			{
+				type: "text_input",
+				action_id: "primaryLabel",
+				label: "Main button text"
+			},
+			{
+				type: "text_input",
+				action_id: "primaryHref",
+				label: "Main button URL"
+			},
+			{
+				type: "text_input",
+				action_id: "secondaryLabel",
+				label: "Second link text"
+			},
+			{
+				type: "text_input",
+				action_id: "secondaryHref",
+				label: "Second link URL"
+			},
+			{
+				type: "select",
+				action_id: "align",
+				label: "Layout",
+				initial_value: "start",
+				options: [{
+					label: "Message left, buttons right",
+					value: "start"
+				}, {
+					label: "Centered",
+					value: "center"
+				}]
+			},
+			{
+				type: "toggle",
+				action_id: "solid",
+				label: "Fill with the solid colour",
+				initial_value: false
+			},
+			...toneFields()
+		]
+	},
+	{
+		type: "vitops.entries",
+		label: "Entries table",
+		placeholder: "Rows of term/value pairs: a stacked list that becomes a table when wide",
+		category: "Sections",
+		fields: [
+			{
+				type: "repeater",
+				action_id: "entries",
+				label: "Entries",
+				item_label: "entry",
+				min_items: 1,
+				fields: [{
+					type: "text_input",
+					action_id: "heading",
+					label: "Heading (row name)"
+				}, {
+					type: "text_input",
+					action_id: "pairs",
+					label: "Details (one per line: Term | Value)",
+					multiline: true
+				}]
+			},
+			levelField("3"),
+			{
+				type: "text_input",
+				action_id: "breakpoint",
+				label: "Becomes a table at this width",
+				initial_value: "40rem"
+			}
+		]
+	},
+	{
+		type: "vitops.pricing",
+		label: "Pricing",
+		placeholder: "Plan cards with aligned feature rows",
+		category: "Sections",
+		fields: [{
+			type: "repeater",
+			action_id: "plans",
+			label: "Plans",
+			item_label: "plan",
+			min_items: 1,
+			fields: [
+				{
+					type: "text_input",
+					action_id: "name",
+					label: "Plan name"
+				},
+				{
+					type: "text_input",
+					action_id: "price",
+					label: "Price (e.g. $49)"
+				},
+				{
+					type: "text_input",
+					action_id: "period",
+					label: "Period (e.g. per month)"
+				},
+				{
+					type: "text_input",
+					action_id: "features",
+					label: "Features (one per line)",
+					multiline: true
+				},
+				{
+					type: "text_input",
+					action_id: "ctaLabel",
+					label: "Button text"
+				},
+				{
+					type: "text_input",
+					action_id: "ctaHref",
+					label: "Button URL"
+				},
+				{
+					type: "toggle",
+					action_id: "featured",
+					label: "Highlight this plan",
+					initial_value: false
+				}
+			]
+		}, levelField("3")]
+	},
+	{
+		type: "vitops.embed",
+		label: "Embed (video or map)",
+		placeholder: "A video or map that loads only after the visitor allows it",
+		category: "Embeds",
+		fields: [
+			{
+				type: "select",
+				action_id: "provider",
+				label: "Provider",
+				initial_value: "youtube",
+				options: [
+					{
+						label: "YouTube",
+						value: "youtube"
+					},
+					{
+						label: "Vimeo",
+						value: "vimeo"
+					},
+					{
+						label: "Map (Google or OpenStreetMap embed address)",
+						value: "map"
+					},
+					{
+						label: "Other (https address)",
+						value: "custom"
+					}
+				]
+			},
+			{
+				type: "text_input",
+				action_id: "url",
+				label: "Address"
+			},
+			{
+				type: "text_input",
+				action_id: "title",
+				label: "Title (required: it names the frame for screen readers)"
+			},
+			{
+				type: "select",
+				action_id: "category",
+				label: "Consent category it waits on",
+				initial_value: "marketing",
+				options: [
+					{
+						label: "Marketing",
+						value: "marketing"
+					},
+					{
+						label: "Preferences",
+						value: "preferences"
+					},
+					{
+						label: "Analytics",
+						value: "analytics"
+					}
+				]
+			},
+			{
+				type: "text_input",
+				action_id: "ratio",
+				label: "Aspect ratio",
+				initial_value: "16 / 9"
+			}
+		]
+	},
+	{
+		type: "vitops.form",
+		label: "Contact form",
+		placeholder: "An enquiry form that emails you (and your CRM) and works without JavaScript",
+		category: "Forms",
+		fields: [
+			{
+				type: "text_input",
+				action_id: "heading",
+				label: "Heading"
+			},
+			levelField("2"),
+			{
+				type: "text_input",
+				action_id: "intro",
+				label: "Text above the form",
+				multiline: true
+			},
+			{
+				type: "repeater",
+				action_id: "fields",
+				label: "Fields",
+				item_label: "field",
+				min_items: 1,
+				fields: [
+					{
+						type: "text_input",
+						action_id: "label",
+						label: "Label (what the visitor sees)"
+					},
+					{
+						type: "text_input",
+						action_id: "name",
+						label: "Name in the message (optional: letters, digits, underscores)"
+					},
+					{
+						type: "select",
+						action_id: "type",
+						label: "Kind",
+						initial_value: "text",
+						options: [
+							{
+								label: "Short text",
+								value: "text"
+							},
+							{
+								label: "Email address",
+								value: "email"
+							},
+							{
+								label: "Phone number",
+								value: "tel"
+							},
+							{
+								label: "Long text",
+								value: "textarea"
+							},
+							{
+								label: "Choose one",
+								value: "select"
+							},
+							{
+								label: "Tick box",
+								value: "checkbox"
+							}
+						]
+					},
+					{
+						type: "toggle",
+						action_id: "required",
+						label: "Required",
+						initial_value: false
+					},
+					{
+						type: "text_input",
+						action_id: "placeholder",
+						label: "Example text"
+					},
+					{
+						type: "text_input",
+						action_id: "help",
+						label: "Help text under the field"
+					},
+					{
+						type: "text_input",
+						action_id: "options",
+						label: "Choices (one per line; for \"Choose one\" only)",
+						multiline: true
+					}
+				]
+			},
+			{
+				type: "text_input",
+				action_id: "submitLabel",
+				label: "Button text",
+				initial_value: "Send"
+			},
+			{
+				type: "text_input",
+				action_id: "successMessage",
+				label: "Message after sending",
+				initial_value: "Thanks. Your message has been sent."
+			},
+			{
+				type: "text_input",
+				action_id: "errorMessage",
+				label: "Message if sending fails"
+			},
+			{
+				type: "text_input",
+				action_id: "noJsMessage",
+				label: "Message when JavaScript is off (shown only if the site has a spam check)"
+			},
+			{
+				type: "text_input",
+				action_id: "action",
+				label: "Where the form posts (leave empty for /api/track)"
+			},
+			...toneFields()
+		]
+	},
+	{
+		/**
+		* Google reviews from the committed `.vitops/reviews.json` cache (`vitops reviews`).
+		*
+		* The data is a BUILD-TIME import (`virtual:getvitops/reviews`, from the `vitops()` Astro
+		* integration), never a filesystem read: the renderer runs in a Worker. So a new review
+		* appears after the next `vitops reviews` run is committed and the site rebuilt, not when
+		* an editor saves. Which reviews show is `selectReviews()` from `@getvitops/utils`, the
+		* one place that is decided — these fields are exactly its `ReviewLocationConfig`.
+		*/
+		type: "vitops.reviews",
+		label: "Google reviews",
+		icon: "star",
+		placeholder: "Customer reviews from the Google Business Profile cache",
+		category: "Sections",
+		fields: [
+			{
+				type: "text_input",
+				action_id: "label",
+				label: "Name for the group (read by screen readers)",
+				initial_value: "Customer reviews"
+			},
+			{
+				type: "text_input",
+				action_id: "location",
+				label: "Location key (organization.locations key; blank = every location in the cache)"
+			},
+			{
+				type: "select",
+				action_id: "layout",
+				label: "Layout",
+				initial_value: "grid",
+				options: [
+					{
+						label: "Grid",
+						value: "grid"
+					},
+					{
+						label: "Carousel",
+						value: "carousel"
+					},
+					{
+						label: "Marquee (scrolling row)",
+						value: "marquee"
+					}
+				]
+			},
+			{
+				type: "select",
+				action_id: "columns",
+				label: "Columns (grid only)",
+				initial_value: "3",
+				options: [
+					"1",
+					"2",
+					"3",
+					"4"
+				].map((n) => ({
+					label: n,
+					value: n
+				}))
+			},
+			{
+				type: "number_input",
+				action_id: "limit",
+				label: "Most reviews to show (0 = all)",
+				initial_value: 6
+			},
+			{
+				type: "select",
+				action_id: "minRating",
+				label: "Lowest rating to show",
+				initial_value: "4",
+				options: [
+					"1",
+					"2",
+					"3",
+					"4",
+					"5"
+				].map((n) => ({
+					label: n === "1" ? "Any" : `${n} stars and up`,
+					value: n
+				}))
+			},
+			{
+				type: "select",
+				action_id: "sort",
+				label: "Order",
+				initial_value: "recent",
+				options: [{
+					label: "Newest first",
+					value: "recent"
+				}, {
+					label: "Highest rated first",
+					value: "rating"
+				}]
+			},
+			{
+				type: "text_input",
+				action_id: "featured",
+				label: "Review ids to show first (comma-separated; they ignore the rating filter)"
+			},
+			{
+				type: "toggle",
+				action_id: "avatars",
+				label: "Show reviewers' Google photos (loads images from Google for every visitor)",
+				initial_value: false
+			},
+			...toneFields()
+		]
+	},
+	{
+		/**
+		* A named EmDash menu inside page content: a site map, a section's link list, a footer-style
+		* set of columns. NOT the header — that is `<SiteNav>` in the layout, which owns the drawer,
+		* dropdowns and breakpoints. `variant: sitenav` renders the same markup and pattern for the
+		* rare page that wants a real navbar in the body.
+		*
+		* The menu is chosen from `menus/list` (the site's own menus) with the conventional names as
+		* the static fallback, because a select needs a non-empty `options` list.
+		*/
+		type: "vitops.nav",
+		label: "Menu",
+		icon: "list",
+		placeholder: "An EmDash menu as a list of links",
+		category: "Navigation",
+		fields: [
+			{
+				type: "select",
+				action_id: "menu",
+				label: "Menu",
+				initial_value: "footer-sitemap",
+				options: [
+					{
+						label: "Footer site map",
+						value: "footer-sitemap"
+					},
+					{
+						label: "Footer legal",
+						value: "footer-legal"
+					},
+					{
+						label: "Primary",
+						value: "primary"
+					}
+				],
+				optionsRoute: MENUS_ROUTE
+			},
+			{
+				type: "text_input",
+				action_id: "label",
+				label: "Name for the navigation (read by screen readers; must differ from other menus)"
+			},
+			{
+				type: "text_input",
+				action_id: "heading",
+				label: "Visible heading (optional)"
+			},
+			levelField("2"),
+			{
+				type: "select",
+				action_id: "variant",
+				label: "Layout",
+				initial_value: "list",
+				options: [
+					{
+						label: "Vertical list",
+						value: "list"
+					},
+					{
+						label: "Inline row",
+						value: "inline"
+					},
+					{
+						label: "Columns (each top-level item with its sub-links)",
+						value: "columns"
+					},
+					{
+						label: "Navbar (the header pattern, in the page)",
+						value: "sitenav"
+					}
+				]
+			},
+			{
+				type: "select",
+				action_id: "depth",
+				label: "Levels to show",
+				initial_value: "1",
+				options: [
+					"1",
+					"2",
+					"3"
+				].map((n) => ({
+					label: n,
+					value: n
+				}))
+			},
+			...toneFields()
+		]
+	}
+];
+/**
+* Resolve {@link BlockSelection} against {@link BLOCKS}.
+*
+* Pure so a misconfiguration fails at plugin construction, with the offending name in the
+* message, rather than as an editor menu that is quietly missing something.
+*/
+function selectBlocks(selection = {}) {
+	const known = new Set(BLOCKS.map((b) => b.type));
+	const check = (names, option) => {
+		for (const name of names ?? []) if (!known.has(name)) throw new Error(`[vitops] blocks.${option}: unknown block '${name}'. Known: ${[...known].join(", ")}.`);
+	};
+	check(selection.include, "include");
+	check(selection.exclude, "exclude");
+	const include = selection.include ? new Set(selection.include) : null;
+	const exclude = new Set(selection.exclude);
+	const base = BLOCKS.filter((b) => (!include || include.has(b.type)) && !exclude.has(b.type));
+	const extra = selection.extra ?? [];
+	const taken = new Set(BLOCKS.map((b) => b.type));
+	for (const block of extra) {
+		if (taken.has(block.type)) throw new Error(`[vitops] blocks.extra: type '${block.type}' is already defined.`);
+		taken.add(block.type);
+	}
+	return [...base, ...extra];
+}
+
+// src/menus-route.ts
+/** The items the select shows: one per menu, valued by its `name` (what `getMenu()` takes). */
+function menuItems(menus) {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const { name, label } of menus) {
+		if (!name || seen.has(name)) continue;
+		seen.add(name);
+		out.push({
+			id: name,
+			name: label && label !== name ? `${label} (${name})` : name
+		});
+	}
+	return out;
+}
+function createMenusRoute(list) {
+	return {
+		permission: "content:read",
+		handler: async () => {
+			try {
+				return { items: menuItems(await list()) };
+			} catch {
+				return { items: [] };
+			}
+		}
+	};
+}
+
+// src/tones-route.ts
+/**
+* The `tones/list` plugin route: what fills every block's `tone` select with the site's own
+* colour roles (UPSTREAM 21 — "role names the admin never offered").
+*
+* EmDash's Block Kit `select` takes an `optionsRoute` for exactly this, and falls back to the
+* field's static options if the route fails or answers with no `items`, so a site that
+* configures nothing still gets the semantic names from `STATIC_TONE_OPTIONS`.
+*
+* **Where the roles come from.** Plugin code has no site config at runtime, so the site hands
+* it over: `tones: [...]` verbatim, or — if the design-system editor is already wired with the
+* site's `Config` — the `colors.roles` keys of that config, so there is nothing to keep in
+* step. A role is listed under its own name (`brand-primary`), because that is what
+* `resolveTone()` and the token names (`--color-bg-brand-primary-muted`) both use.
+*/
+/** Role names of a design system or full config, or `[]` if it cannot be resolved. */
+function rolesOf(config) {
+	if (!config || typeof config !== "object") return [];
+	try {
+		const { designSystem } = resolveInput(config, { siteEnv: "production" });
+		return Object.keys(designSystem.colors?.roles ?? {});
+	} catch {
+		return [];
+	}
+}
+/** The items the select shows: the site's roles first, then any semantic name it lacks. */
+function toneItems(roles) {
+	return [{
+		id: "",
+		name: "None"
+	}, ...[.../* @__PURE__ */ new Set([...roles, ...SEMANTIC_TONES])].map((id) => ({
+		id,
+		name: id.replace(/-/g, " ")
+	}))];
+}
+function createTonesRoute(roles) {
+	return {
+		permission: "content:read",
+		handler: async () => ({ items: toneItems(roles()) })
+	};
+}
+
+// src/design-system-route.ts
+/**
+* The `vitops.design-system` plugin route — what `<wc-theme-editor>` probes
+* and POSTs its patch to when mounted inside the EmDash admin (see this
+* package's README and AGENTS.md's "EmDash plugin as the design-system
+* editing surface" section). Mounted at
+* `/_emdash/api/plugins/vitops/design-system`.
+*
+* Two responsibilities, matching the dev-only `@getvitops/vite` endpoint's
+* contract byte-for-byte (`GET → { writable }`, `POST { patch } → { ok } |
+* { errors }`) so `<wc-theme-editor>` needs no branch for which one it's
+* talking to:
+*
+* 1. **Immediate**: persist the patch to `ctx.settings` — read back by the
+*    `page:fragments` hook in `index.ts`, which turns it into a site-wide
+*    `:root` override `<style>` on every public page. This is what makes an
+*    edit visible without a rebuild.
+* 2. **Canonical**: auto-commit the merged file to `site.deployment.branch`
+*    (default `dev`) via `@getvitops/utils/git`'s `commitFile()`, so the edit
+*    reaches the git-tracked `site.json` through this repo's own normal
+*    `dev → promote → main` review path — never a silent second source of
+*    truth. A commit failure (missing token, misconfigured repo, a transient
+*    GitHub error) is logged and surfaces as a warning, but never fails the
+*    save: the immediate override already works regardless.
+*
+* **Assumes `config` is a full site `Config`** (has `organization`/`site`),
+* not a bare `design-system.json` — true for any real EmDash site (it always
+* has a `site.json`), and the only case this plugin already handles anywhere
+* else (`vitopsHosting()`, `BLOCKS`).
+*
+* The GitHub token is read as `process.env.VITOPS_GITHUB_TOKEN` — matching
+* `hosting.ts`'s own `process.env.HOSTING` read in this same package, rather
+* than a `cloudflare:workers`-specific import: a native EmDash plugin runs
+* in-process with no isolation boundary (EmDash's own docs say plugins "can
+* access environment variables" directly), and this package already targets
+* both the Cloudflare and Node hosting targets through one `process.env`
+* convention (`nodejs_compat` on Workers maps bindings into `process.env`).
+*/
+const SETTINGS_KEY = "designSystemPatch";
+function json(status, body) {
+	return pluginResponse({
+		status,
+		headers: { "content-type": "application/json" },
+		body: {
+			kind: "text",
+			value: JSON.stringify(body)
+		}
+	});
+}
+/** Fetches the currently-stored patch, clearing it if the bundled `config`
+* (the last real build) already reflects every value in it — see the
+* module docblock's "self-clearing" note in AGENTS.md. */
+async function currentPatch(ctx, ds) {
+	const stored = await ctx.settings.get(SETTINGS_KEY);
+	if (!stored) return null;
+	const patchedColors = stored.patch["colors"];
+	if (patchedColors != null && JSON.stringify(mergePatch(ds.colors, patchedColors)) === JSON.stringify(ds.colors)) {
+		await ctx.settings.delete(SETTINGS_KEY);
+		return null;
+	}
+	return stored;
+}
+function createDesignSystemRoute(opts) {
+	const theme = opts.theme ?? "default";
+	return {
+		methods: ["GET", "POST"],
+		response: "raw",
+		permission: "plugins:manage",
+		handler: async (ctx) => {
+			const { designSystem: ds, config } = resolveInput(opts.config, {
+				theme,
+				siteEnv: "production"
+			});
+			if (ctx.request.method === "GET") {
+				await currentPatch(ctx, ds);
+				return json(200, { writable: true });
+			}
+			const patch = ctx.input?.patch;
+			if (patch == null || typeof patch !== "object" || Array.isArray(patch)) return json(400, { errors: ["body must be { patch: object }"] });
+			const mergedColors = mergePatch(ds.colors, patch["colors"] ?? {});
+			const contrastErrors = validateColorContract(mergedColors);
+			if (contrastErrors.length) return json(400, { errors: contrastErrors });
+			await ctx.settings.set(SETTINGS_KEY, {
+				patch,
+				at: Date.now()
+			});
+			const warnings = [];
 			const repoSpec = config?.site.deployment?.repo;
 			const token = process.env["VITOPS_GITHUB_TOKEN"];
 			if (!repoSpec || !token) warnings.push(!repoSpec ? "design-system sync skipped: site.deployment.repo is not set — the change is live but not yet synced to source." : "design-system sync skipped: no GitHub token configured — the change is live but not yet synced to source.");
@@ -760,6 +1768,94 @@ async function designSystemOverrideFragment(ctx, opts) {
 	};
 }
 
+// src/block-types.ts
+/** Block-type slugs may not contain a dot, so `vitops.section` is stored as `vitops_section`. */
+const SECTION_SLUG = "vitops_section";
+const select = (slug, label, options, defaultValue) => ({
+	slug,
+	label,
+	type: "select",
+	defaultValue,
+	validation: { options }
+});
+const SECTION_FIELDS = [
+	{
+		slug: "kicker",
+		label: "Kicker (small line above the heading)",
+		type: "string"
+	},
+	{
+		slug: "heading",
+		label: "Heading",
+		type: "string"
+	},
+	select("level", "Heading level", [
+		"2",
+		"3",
+		"4",
+		"5",
+		"6"
+	], "2"),
+	{
+		slug: "sub",
+		label: "Lead-in text under the heading",
+		type: "text"
+	},
+	{
+		slug: "body",
+		label: "Content (any blocks)",
+		type: "portableText"
+	},
+	select("layout", "Layout", [
+		"stack",
+		"center",
+		"split"
+	], "stack"),
+	select("width", "Width", [
+		"measure",
+		"breakout",
+		"spotlight",
+		"fullbleed"
+	], "measure"),
+	{
+		slug: "tone",
+		label: "Backdrop tone (a colour role from the site, e.g. surface or brand-primary)",
+		type: "string"
+	},
+	{
+		slug: "color",
+		label: "Palette colour instead of a tone (e.g. amber or amber-300)",
+		type: "string"
+	},
+	{
+		slug: "solid",
+		label: "Fill with the solid colour",
+		type: "boolean",
+		defaultValue: false
+	}
+];
+/** `vitops.section`: kicker, heading, lead-in, tone/backdrop, optional heading-left layout, and a body of blocks. */
+const SECTION_BLOCK_TYPE = {
+	slug: SECTION_SLUG,
+	label: "Section",
+	description: "A titled page section whose body can hold any other blocks.",
+	category: "Sections",
+	icon: "layout",
+	currentVersion: 1,
+	versions: [{
+		version: 1,
+		fields: SECTION_FIELDS
+	}]
+};
+/**
+* Every block type this plugin ships, in the shape `seed.json`'s `blockTypes` takes. Spread
+* it into the seed (and allow the slugs on the collection's `blocks` field), e.g.
+* `blockTypes: [...vitopsBlockTypes()]`.
+*/
+function vitopsBlockTypes() {
+	return [SECTION_BLOCK_TYPE];
+}
+
 // src/blocks-doc.ts
 const cell = (s) => (s ?? "").replace(/\|/g, "\\|").replace(/\n/g, " ");
 function describe(f) {
@@ -794,8 +1890,18 @@ function renderBlocksDoc(blocks = BLOCKS) {
 		"# EmDash blocks",
 		"",
 		"Each block is a Portable Text object: `{ \"_type\": \"vitops.cards\", \"_key\": \"<unique>\", ...fields }`.",
-		"Blocks are flat — a block cannot contain other blocks, and a repeater row holds scalar fields only.",
+		"Portable Text blocks are flat — they cannot contain other blocks, and a repeater row holds scalar fields only.",
+		"To put blocks inside something, use the section block TYPE (end of this page), whose body is Portable Text.",
 		"Give every block a unique `_key`; gallery and carousel derive their element id from it.",
+		"",
+		"## Colour: `tone` and `color`",
+		"",
+		"Every block that colours something takes the same two fields. `tone` is a colour role from the",
+		"site's `colors.roles` (or a semantic name); an unknown role falls back through its semantic",
+		"relatives to `neutral`. `color` is an escape hatch naming a palette hue (`amber`) or hue and step",
+		"(`amber-300`) and wins over `tone`; its contrast is not checked. Renderers emit `--tone-*` custom",
+		"properties, never a class built from the value. Multiline fields that accept links take",
+		"`[text](/url)`; hero headings accent words wrapped in `*stars*`.",
 		""
 	];
 	for (const b of blocks) {
@@ -803,6 +1909,19 @@ function renderBlocksDoc(blocks = BLOCKS) {
 		if (b.placeholder) out.push(`${b.placeholder}.`, "");
 		if (b.fields?.length) out.push("| Field | Type | Label | Notes |", "| --- | --- | --- | --- |", ...fieldRows(b.fields), "");
 	}
+	out.push("## `vitops.form` needs an endpoint", "", "The form posts to `/api/track` (the `action` field overrides it), which must be an on-demand route", "built with `createConversionRoute()` from `@getvitops/astro/routes`; the emdash template ships one.", "Field names are submitted as written, except that `phone` becomes `tel` and a few names the route", "reserves (`event`, `website`, `honeypot`, `_honeypot`, `cf-turnstile-response`) are renamed.", "It emails `site.notifications.email` and writes `site.crm` when set; with neither, the route refuses", "the post rather than accept a message nobody receives. Add the spam check with", "`vitops setup turnstile`: once `site.security.turnstile.siteKey` is set the block renders", "`<wc-turnstile>`, which loads Cloudflare Turnstile only when the visitor first uses the form", "(category `necessary`, so it is not behind the consent banner). The secret lives in the", "`VITOPS_TURNSTILE_SECRET` Worker secret, never in `site.json`. Use one form per page.", "", "## Block types (the `blocks` field)", "", "Schema-level block types, not Portable Text blocks: add them to the seed (`blockTypes: [...vitopsBlockTypes()]`),", "allow the slug on the collection's `blocks` field, and render with `blockTypeComponents` from `@getvitops/emdash/astro`.", "");
+	for (const t of vitopsBlockTypes()) {
+		out.push(`### \`${t.slug}\` — ${t.label}`, "", `${t.description ?? ""}`, "");
+		const fields = t.versions.find((v) => v.version === t.currentVersion)?.fields ?? [];
+		out.push("| Field | Type | Label | Notes |", "| --- | --- | --- | --- |", ...fields.map((f) => {
+			const notes = [
+				f.validation?.options ? `one of ${f.validation.options.join(", ")}` : "",
+				f.defaultValue !== void 0 ? `default \`${String(f.defaultValue)}\`` : "",
+				f.type === "portableText" ? "accepts every `vitops.*` block above" : ""
+			].filter(Boolean);
+			return `| \`${f.slug}\` | ${f.type} | ${cell(f.label)} | ${cell(notes.join("; "))} |`;
+		}), "");
+	}
 	return out.join("\n");
 }
 
@@ -867,7 +1986,7 @@ async function vitopsHosting(options = {}) {
 }
 
 // package.json
-var version = "1.0.0";
+var version = "2.0.0-alpha.0";
 
 // src/index.ts
 /**
@@ -929,6 +2048,7 @@ function createPlugin(options = {}) {
 	const wcBase = options.wcBase ?? "/vitops";
 	const editor = options.designSystemEditor || void 0;
 	const fragmentsEnabled = scripts === "fragments" || !!editor;
+	const roles = options.tones ?? rolesOf(editor?.config);
 	const pageFragments = async (_event, ctx) => {
 		const contributions = [];
 		if (scripts === "fragments") contributions.push({
@@ -966,9 +2086,13 @@ function createPlugin(options = {}) {
 				}]
 			} : {}
 		},
-		...editor ? { routes: { "design-system": createDesignSystemRoute(editor) } } : {}
+		routes: {
+			[TONES_ROUTE]: createTonesRoute(() => roles),
+			[MENUS_ROUTE]: createMenusRoute(() => getMenus()),
+			...editor ? { "design-system": createDesignSystemRoute(editor) } : {}
+		}
 	});
 }
 
-export { BLOCKS, createPlugin, createPlugin as default, renderBlocksDoc, selectBlocks, vitopsEmdash, vitopsHosting };
+export { BLOCKS, SECTION_BLOCK_TYPE, SECTION_SLUG, createPlugin, createPlugin as default, renderBlocksDoc, resolveTone, selectBlocks, toneChain, vitopsBlockTypes, vitopsEmdash, vitopsHosting };
 //# sourceMappingURL=index.mjs.map