@the-smithy/create-hearth-site 0.26.0 → 0.28.0

package/README.md

@@ -40,7 +40,8 @@ cd acme-website
 
 Add an API key to `.env.local` (Hearth → the site → API & webhooks → API keys), and run `pnpm dev`. The
 new site's README walks through the first run, previews and troubleshooting. Its `HOSTING.md` covers deploying to
-Netlify or Vercel, and its `AGENTS.md` holds the instructions for coding agents.
+Netlify or Vercel, and its `AGENTS.md` holds the instructions for coding agents, who are set up to find code with
+[Drift](https://github.com/The-Smithy/drift).
 
 ## Documentation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-smithy/create-hearth-site",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Start a new client website powered by Hearth: pnpm create @the-smithy/hearth-site",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",
@@ -30,9 +30,10 @@
   ],
   "devDependencies": {
     "vitest": "^5.0.3",
-    "@the-smithy/hearth-schema": "^0.26.0"
+    "@the-smithy/hearth-schema": "^0.28.0"
   },
   "scripts": {
-    "test": "node --test \"test/**/*.test.js\" && vitest run test/blocks.test.ts test/overrides.test.ts"
+    "test": "node --test \"test/**/*.test.js\" && vitest run test/blocks.test.ts test/overrides.test.ts",
+    "blocks:reference": "vitest run --config reference/vitest.config.ts"
   }
 }

package/template/AGENTS.md

@@ -4,6 +4,26 @@ This is a client website whose content comes from Hearth, The Smithy's headless
 replaced by `pnpm hearth:update`: notes about this particular site go in `SITE.md`, which you should read too.
 `CLAUDE.md` and `GEMINI.md` only point here, for the assistants that look for those names.
 
+<!-- drift:start -->
+## Finding code: use Drift first
+
+Before grepping or reading whole files, use [Drift](https://github.com/The-Smithy/drift). It costs far fewer tokens.
+
+- `drift query <symbol>` or `drift find <words>`: where something is defined
+- `drift show <symbol>` or `drift sig <symbol>`: its source, or just its signature
+- `drift outline <file>`: a file's definitions and imports
+- `drift refs <symbol>`, `drift importers <file>`, `drift tests --for <file>`: what uses it
+- `drift context <symbol or file>`: all of the above before changing something
+- `drift map`: orientation in a new repo
+
+Never read `.drift-index.json`. Grep is still right for strings and comments. If `drift` isn't installed: `cargo install --git https://github.com/The-Smithy/drift`.
+<!-- drift:end -->
+
+Here, `pnpm hearth:drift` is the way to install or update Drift and its skill: it gets the latest release from GitHub,
+without Rust or an API key, and `pnpm hearth:docs` runs it too. Drift is only for working on the code. The build and
+deploy don't use it, so don't add it to `package.json` or the host's build, and if it can't be installed here, carry on
+with grep.
+
 ## How this site is built: Hearth's code, the site's styling
 
 Everything that works with Hearth is already here, and it's the same in every site Hearth runs: every block type,
@@ -66,6 +86,13 @@ Work in this order, and stop at the first step that gets the result:
    don't reach it, so it falls behind Hearth. Use one only when everything above can't get there, build it from
    `src/hearth/ui.tsx` and the theme, and say why in `SITE.md`.
 
+To style blocks without setting up pages for them, open `/hearth/blocks` while `pnpm dev` is running: every block with
+its options and states, in sample content, drawn with this site's theme, so a change in `src/theme` shows at once.
+`/hearth/blocks?block=hero` shows one block. Its **Unstyled** switch (`/hearth/blocks/unstyled`) shows them with no design
+and each element's slot name. Neither is served in production. Global blocks and the site's custom blocks aren't in it.
+Without a browser, the unstyled page is `node_modules/@the-smithy/hearth/block-reference.html`, but it's large: for slots,
+use `src/hearth/theme/defaults.ts`.
+
 Never copy a component out of `src/hearth/` to restyle it. If a design needs a slot or an option Hearth doesn't have,
 say so: it belongs in Hearth's template for every site (tell the developer to raise it with The Smithy), and an
 override can bridge the gap meanwhile.
@@ -139,8 +166,8 @@ Do these before writing code, and tell the developer what you found:
    fix `.env.local`; don't guess values.
 2. **Get the full reference:** `pnpm hearth:docs` saves Hearth's API guide (every block and its fields, events,
    forms, previews, SEO) to `hearth-api.md`. Read the parts you need from it, and from
-   `node_modules/@the-smithy/hearth/llms.md` for the SDK. It also installs any skills Hearth offers this site (see
-   "Skills" below), so run it again when they're missing. These aren't committed, so some assistants' search skips
+   `node_modules/@the-smithy/hearth/llms.md` for the SDK. It also installs Drift and any skills Hearth offers this site
+   (see "Skills" below), so run it again when they're missing. These aren't committed, so some assistants' search skips
    them: open them by their exact path, or from the terminal if your tool won't.
 3. **"Nothing is published"** means every page is a 404 until editors publish in Hearth. That's not a code
    problem: say so, and don't add placeholder content to work around it.
@@ -153,7 +180,7 @@ and, as the same copies, in `.claude/skills/`, since Claude Code only reads that
 for and when to use it. If your assistant doesn't load them by itself, read the ones that fit the task and follow them.
 Use them for that work, design work in particular, rather than starting from scratch. They aren't committed (a
 `.gitignore` in each folder lists them), so a fresh checkout gets them by running `pnpm hearth:docs`; never edit them,
-because the next run replaces them.
+because the next run replaces them. The `drift` skill works the same way, from `pnpm hearth:drift`.
 
 ## Hosting
 

package/template/README.md

@@ -42,12 +42,17 @@ without touching your styling. See "Styling the site" below.
 ## Working with an AI coding assistant
 
 The project comes with instructions for coding agents in `AGENTS.md`, which Codex, Cursor, Copilot and others read on
-their own. `CLAUDE.md` and `GEMINI.md` point Claude Code and Gemini CLI to it. Once your API key is in `.env.local`:
+their own. `CLAUDE.md` and `GEMINI.md` point Claude Code and Gemini CLI to it.
+
+Agents also use [Drift](https://github.com/The-Smithy/drift) to find code with far fewer tokens. `pnpm hearth:drift`
+installs or updates it and its skill from the latest release on GitHub. The site builds and deploys without it.
+
+Once your API key is in `.env.local`:
 
 1. **Check the connection yourself, or have the agent do it:** `pnpm hearth:check` confirms the key works and
    lists the published pages and the block types they use. It never prints the key.
 2. **Give the agent the full reference:** `pnpm hearth:docs` saves Hearth's API guide to `hearth-api.md` (not
-   committed), and installs any coding-assistant skills Hearth offers your site in `.agents/skills/` and
+   committed), and installs Drift and any coding-assistant skills Hearth offers your site in `.agents/skills/` and
    `.claude/skills/`. The agent's instructions already point it at both.
 3. **Then tell it what to build.** Prompts that work well:
 
@@ -93,6 +98,7 @@ Keep the API key out of chat: the agent never needs to see it, only `.env.local`
 | `src/theme/theme.css` | Brand tokens (colors, fonts, content width) and the site's own CSS. **Start here** |
 | `src/theme/index.ts` | The Tailwind classes of any part of any block, page, form, header or footer, by slot |
 | `src/hearth/theme/defaults.ts` | Every slot and its default classes: read it to find the slot to change |
+| `/hearth/blocks` | Not a file: while `pnpm dev` runs, this address shows every block on one page with your theme, without setting up pages for them. `?block=hero` shows one. Its **Unstyled** switch shows them with no design, and each element's slot name |
 | `src/theme/fonts.ts` | Web fonts (next/font) |
 | `src/theme/custom-blocks.tsx` | Components for the site's own block types (Settings → Custom blocks in Hearth) |
 | `src/theme/overrides.tsx` | Last resort: replace a whole block's component, the logo, the footer, the event or fundraiser page, their cards or the donation form (see `AGENTS.md`) |
@@ -165,6 +171,7 @@ packages are public on npm, so nothing else is needed to install them.
 
 The full reference (API, SDK, every block and its fields, previews, forms) is in Hearth under **API docs**,
 with a Markdown version to give an AI coding assistant. The SDK also ships `node_modules/@the-smithy/hearth/llms.md`.
+Every block is at `/hearth/blocks` while `pnpm dev` runs, with your theme or unstyled. Hearth has the unstyled page under **Block library**.
 
 ## Updating
 

package/template/_gitignore

@@ -13,3 +13,6 @@ next-env.d.ts
 
 # Hearth's API guide, downloaded by pnpm hearth:docs for AI assistants.
 hearth-api.md
+
+# Drift's code index, rebuilt as needed.
+.drift-index.json

package/template/package.json

@@ -10,6 +10,7 @@
     "typecheck": "tsc --noEmit",
     "hearth:check": "node scripts/hearth.mjs check",
     "hearth:docs": "node scripts/hearth.mjs docs",
+    "hearth:drift": "node scripts/hearth.mjs drift",
     "hearth:update": "node scripts/hearth.mjs update"
   },
   "dependencies": {

package/template/scripts/hearth.mjs

@@ -2,13 +2,16 @@
 //   pnpm hearth:check   says whether The Smithy has released anything newer than this site uses, checks .env.local and
 //                       the connection to Hearth, then lists what's published
 //   pnpm hearth:docs    saves Hearth's full API guide to hearth-api.md (not committed) for an AI assistant to read,
-//                       and installs any coding-assistant skills Hearth offers this site
+//                       and installs any coding-assistant skills Hearth offers this site, and Drift
+//   pnpm hearth:drift   installs or updates Drift, which finds code for coding agents, from its latest GitHub release
 //   pnpm hearth:update  updates Hearth's code in this site (src/hearth and the other files its manifest lists) to the
 //                       latest release, and the packages it needs; src/theme and your own files stay as they are
 import { spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import path from "node:path";
-import { gunzipSync } from "node:zlib";
+import { gunzipSync, inflateRawSync } from "node:zlib";
 
 const command = process.argv[2];
 /** Stops with a message. Thrown rather than process.exit(), which can crash Node on Windows mid-request. */
@@ -19,6 +22,13 @@ const fail = (message) => {
 
 const PACKAGE = "@the-smithy/create-hearth-site";
 const SKILL_DIRS = [".agents/skills", ".claude/skills"];
+/** Drift's release archive for each kind of machine it has a binary for. */
+const DRIFT_ARCHIVES = {
+  "win32-x64": "drift-x86_64-pc-windows-msvc.zip",
+  "linux-x64": "drift-x86_64-unknown-linux-musl.tar.gz",
+  "darwin-arm64": "drift-aarch64-apple-darwin.tar.gz",
+  "darwin-x64": "drift-x86_64-apple-darwin.tar.gz",
+};
 const MANIFEST = "src/hearth/manifest.json";
 /** The packages hearth:update raises; it leaves the site's other Smithy packages to it. */
 const UPDATED_TOGETHER = [PACKAGE, "@the-smithy/hearth", "@the-smithy/hearth-schema"];
@@ -149,6 +159,20 @@ async function docs() {
   writeFileSync("hearth-api.md", await res.text());
   console.log("✓ Saved Hearth's full API guide to hearth-api.md (not committed). Point your coding assistant at it.");
   await skills(env);
+  // Hearth's guide and skills are what this command is for, so Drift failing doesn't fail it.
+  await drift().catch((err) => console.log(`! Skipped Drift: ${err.message}`));
+}
+
+/** The skills a folder's .gitignore lists, which are the installed ones; anything else there is the site's own. */
+function listedSkills(dir) {
+  const listFile = path.join(dir, ".gitignore");
+  if (!existsSync(listFile)) return [];
+  return readFileSync(listFile, "utf8").split(/\r?\n/).map((l) => l.replace(/^\/|\/$/g, "")).filter((l) => l && !l.startsWith("#") && l !== ".gitignore" && l !== "drift");
+}
+
+function listSkills(dir, names) {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path.join(dir, ".gitignore"), ["# Installed by pnpm hearth:docs and hearth:drift; refreshed each run.", ".gitignore", "/drift/", ...names.map((n) => `/${n}/`)].join("\n") + "\n");
 }
 
 /**
@@ -164,10 +188,7 @@ async function skills(env) {
   const safe = (p) => /^[a-z0-9][a-z0-9-]*$/.test(p);
   const names = offered.map((s) => s.name).filter(safe);
   for (const dir of SKILL_DIRS) {
-    const listFile = path.join(dir, ".gitignore");
-    const before = existsSync(listFile)
-      ? readFileSync(listFile, "utf8").split(/\r?\n/).map((l) => l.replace(/^\/|\/$/g, "")).filter((l) => l && !l.startsWith("#") && l !== ".gitignore")
-      : [];
+    const before = listedSkills(dir);
     for (const name of before) if (safe(name) && !names.includes(name)) rmSync(path.join(dir, name), { recursive: true, force: true });
     for (const skill of offered.filter((s) => safe(s.name))) {
       rmSync(path.join(dir, skill.name), { recursive: true, force: true });
@@ -178,15 +199,74 @@ async function skills(env) {
         writeFileSync(target, file.content);
       }
     }
-    if (names.length || before.length) {
-      mkdirSync(dir, { recursive: true });
-      writeFileSync(listFile, ["# Installed by pnpm hearth:docs from Hearth; refreshed each run.", ".gitignore", ...names.map((n) => `/${n}/`)].join("\n") + "\n");
-    }
+    if (names.length || before.length) listSkills(dir, names);
   }
   if (names.length) console.log(`✓ Installed ${names.length === 1 ? "a skill" : `${names.length} skills`} for your coding assistant in ${SKILL_DIRS.map((d) => `${d}/`).join(" and ")}: ${names.join(", ")}.`);
 }
 
 
+/**
+ * Installs or updates Drift from its latest GitHub release, replacing the copy already on the PATH, then has it write
+ * its own skill, so both stay current without a new Hearth release. Only hearth:drift and hearth:docs run this, never
+ * an install or a build: a host doesn't need Drift, and shouldn't download and run a program on every deploy.
+ */
+async function drift() {
+  const releases = process.env.HEARTH_DRIFT_RELEASES ?? "https://github.com/The-Smithy/drift/releases";
+  const windows = process.platform === "win32";
+  const name = windows ? "drift.exe" : "drift";
+  const found = spawnSync(windows ? "where" : "which", ["drift"], { encoding: "utf8" });
+  const onPath = found.status === 0 ? found.stdout.split(/\r?\n/)[0].trim() : null;
+  const have = onPath && spawnSync(onPath, ["--version"], { encoding: "utf8" }).stdout?.trim().split(" ")[1];
+  const tag = (await fetch(`${releases}/latest`, { redirect: "manual" })).headers.get("location")?.match(/\/tag\/([^/]+)$/)?.[1];
+  if (!tag) fail("GitHub didn't say which release of Drift is the latest.");
+  const latest = tag.replace(/^v/, "");
+  const bin = onPath ?? path.join(windows ? path.join(process.env.LOCALAPPDATA ?? homedir(), "Programs", "drift") : path.join(homedir(), ".local", "bin"), name);
+
+  if (have && !lower(have, latest)) console.log(`✓ Drift ${have} is up to date.`);
+  else {
+    const archive = DRIFT_ARCHIVES[`${process.platform}-${process.arch}`];
+    if (!archive) fail(`Drift has no download for ${process.platform} ${process.arch}. Install it with: cargo install --git https://github.com/The-Smithy/drift`);
+    const download = async (file) => {
+      const res = await fetch(`${releases}/download/${tag}/${file}`);
+      if (!res.ok) fail(`Couldn't download ${file} from Drift's releases (${res.status}).`);
+      return Buffer.from(await res.arrayBuffer());
+    };
+    const [body, sums] = await Promise.all([download(archive), download("SHA256SUMS")]);
+    const sum = sums.toString("utf8").split(/\r?\n/).find((line) => line.endsWith(` ${archive}`))?.split(/\s+/)[0];
+    if (sum !== createHash("sha256").update(body).digest("hex")) fail(`${archive} doesn't match its checksum in Drift's release, so it wasn't installed.`);
+    const binary = (windows ? unzip : untar)(body).get(name);
+    if (!binary) fail(`${archive} has no ${name}.`);
+    mkdirSync(path.dirname(bin), { recursive: true });
+    writeFileSync(`${bin}.new`, binary);
+    chmodSync(`${bin}.new`, 0o755);
+    renameSync(`${bin}.new`, bin);
+    console.log(`✓ ${have ? `Updated Drift from ${have} to` : "Installed Drift"} ${latest} at ${bin}`);
+    if (!onPath) console.log(`  Add ${path.dirname(bin)} to your PATH so you and your coding assistant can run drift.`);
+  }
+
+  // Drift's skill follows its version, so like Hearth's skills it's installed rather than committed.
+  for (const dir of SKILL_DIRS) listSkills(dir, listedSkills(dir));
+  const install = spawnSync(bin, ["install", "."], { encoding: "utf8" });
+  if (install.status !== 0) fail(`Drift couldn't install its skill: ${install.stderr?.trim() || install.error?.message}`);
+  console.log(`✓ Installed Drift's skill in ${SKILL_DIRS.map((d) => `${d}/`).join(" and ")}.`);
+}
+
+/** The files in a zip archive, by name. */
+function unzip(zip) {
+  const files = new Map();
+  const end = zip.lastIndexOf(Buffer.from("PK\x05\x06", "latin1"));
+  let at = zip.readUInt32LE(end + 16);
+  for (let i = 0; i < zip.readUInt16LE(end + 10); i++) {
+    const nameLength = zip.readUInt16LE(at + 28);
+    const header = zip.readUInt32LE(at + 42);
+    const start = header + 30 + zip.readUInt16LE(header + 26) + zip.readUInt16LE(header + 28);
+    const body = zip.subarray(start, start + zip.readUInt32LE(at + 20));
+    files.set(zip.toString("utf8", at + 46, at + 46 + nameLength), zip.readUInt16LE(at + 10) === 8 ? inflateRawSync(body) : body);
+    at += 46 + nameLength + zip.readUInt16LE(at + 30) + zip.readUInt16LE(at + 32);
+  }
+  return files;
+}
+
 /** The files in an npm package tarball (.tgz), by their path inside it ("package/…"). */
 function untar(tgz) {
   const tar = gunzipSync(tgz);
@@ -323,7 +403,8 @@ try {
   if (command === "check") await check();
   else if (command === "docs") await docs();
   else if (command === "update") await update();
-  else fail("Usage: node scripts/hearth.mjs check | docs | update [--version x.y.z] [--force]");
+  else if (command === "drift") await drift().catch((err) => fail(err instanceof Stop ? err.message : `Couldn't install Drift: ${err.message}`));
+  else fail("Usage: node scripts/hearth.mjs check | docs | drift | update [--version x.y.z] [--force]");
 } catch (err) {
   if (!(err instanceof Stop)) throw err;
   console.error(`\n✗ ${err.message}\n`);

package/template/src/app/hearth/blocks/page.tsx

@@ -0,0 +1,2 @@
+// Managed by Hearth (pnpm hearth:update replaces it): every block with this site's theme, under pnpm dev only. See src/hearth/block-library/page.tsx.
+export { default, metadata } from "@/hearth/block-library/page";

package/template/src/app/hearth/blocks/unstyled/route.ts

@@ -0,0 +1,14 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+const SWITCH = `<span class="view-switch"><span class="view-current">Unstyled</span><a href="/hearth/blocks" onclick="this.href='/hearth/blocks'+location.hash">This site's theme</a></span>`;
+
+/**
+ * Every block unstyled, with its options, states and slot names, to build against while developing. Only under
+ * `pnpm dev`: the page comes from the SDK, so it matches this site's release, and visitors never see it.
+ */
+export function GET() {
+  if (process.env.NODE_ENV !== "development") return new Response("Not found", { status: 404 });
+  const page = readFileSync(path.join(process.cwd(), "node_modules/@the-smithy/hearth/block-reference.html"), "utf8");
+  return new Response(page.replace("<!-- hearth:view-switch -->", SWITCH), { headers: { "Content-Type": "text/html; charset=utf-8" } });
+}

package/template/src/hearth/block-library/controls.tsx

@@ -0,0 +1,45 @@
+"use client";
+
+import { Component, useEffect, type ReactNode } from "react";
+
+/** Nothing in a sample goes anywhere: its links don't navigate, and its forms never reach the site's real inbox in Hearth. */
+export function SampleGuard() {
+  useEffect(() => {
+    const stop = (e: Event) => {
+      const target = e.target as Element;
+      if (!target.closest?.("[data-library-sample]")) return;
+      if (e.type === "submit" || target.closest("a")) {
+        e.preventDefault();
+        e.stopPropagation();
+      }
+    };
+    // Before React's own handlers, which is where a form's server action and a next/link run.
+    document.addEventListener("click", stop, true);
+    document.addEventListener("submit", stop, true);
+    return () => {
+      document.removeEventListener("click", stop, true);
+      document.removeEventListener("submit", stop, true);
+    };
+  }, []);
+  return null;
+}
+
+/** A link to the block library's other view, staying on the same block. */
+export function ViewLink({ href, children }: { href: string; children: ReactNode }) {
+  return (
+    <a href={href} className="hearth-library-view" onClick={(e) => (e.currentTarget.href = href + window.location.hash)}>
+      {children}
+    </a>
+  );
+}
+
+/** One sample failing (a site without Giving has no fundraisers to offer) leaves the rest of the page working. */
+export class SampleBoundary extends Component<{ children: ReactNode }, { message?: string }> {
+  state: { message?: string } = {};
+  static getDerivedStateFromError(error: Error) {
+    return { message: error.message };
+  }
+  render() {
+    return this.state.message ? <p className="hearth-library-failed">This sample couldn&apos;t be drawn: {this.state.message}</p> : this.props.children;
+  }
+}

package/template/src/hearth/block-library/page.tsx

@@ -0,0 +1,116 @@
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import { Fragment, Suspense, type ReactNode } from "react";
+import { Blocks } from "../blocks";
+import { SampleBoundary, SampleGuard, ViewLink } from "./controls";
+import { FormStates, Ground, GROUND_NAMES } from "./pieces";
+import { blockSamples, libraryGroups } from "./samples";
+
+export const metadata: Metadata = { title: "Block library", robots: { index: false, follow: false } };
+
+const TONES = ["default", "muted", "inverse", "accent"] as const;
+
+// Its own plain styles, so that nothing in a site's theme changes the tools around the samples.
+const CSS = `
+.hearth-library-bar, .hearth-library-label, .hearth-library-failed { font: 14px/1.4 ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; color: #1a1a1a; }
+.hearth-library-bar { position: sticky; top: 0; z-index: 50; display: flex; flex-wrap: wrap; align-items: center; gap: 8px 16px; padding: 8px 16px; background: #fff; border-bottom: 1px solid #d8d8d4; }
+.hearth-library-bar b { font-weight: 700; }
+.hearth-library-switch { display: inline-flex; border: 1px solid #d8d8d4; border-radius: 6px; overflow: hidden; }
+.hearth-library-switch > * { padding: 4px 12px; }
+.hearth-library-switch > * + * { border-left: 1px solid #d8d8d4; }
+.hearth-library-current { background: #1f4fd8; color: #fff; }
+.hearth-library-jump { position: relative; }
+.hearth-library-jump summary { cursor: pointer; padding: 4px 12px; border: 1px solid #d8d8d4; border-radius: 6px; list-style: none; }
+.hearth-library-jump summary::after { content: " ▾"; }
+.hearth-library-jump nav { position: absolute; left: 0; top: calc(100% + 6px); width: min(260px, calc(100vw - 32px)); max-height: 70dvh; overflow-y: auto; padding: 8px; background: #fff; border: 1px solid #d8d8d4; border-radius: 6px; }
+.hearth-library-jump p { margin: 10px 8px 2px; font-size: 12px; font-weight: 600; color: #5c5c58; }
+.hearth-library-jump a { display: block; padding: 3px 8px; }
+.hearth-library-jump a:hover, .hearth-library-label a:hover { text-decoration: underline; }
+.hearth-library-note { color: #5c5c58; }
+.hearth-library-label { display: flex; flex-wrap: wrap; justify-content: space-between; gap: 2px 16px; padding: 6px 16px; background: #f4f4f2; border-block: 1px solid #d8d8d4; scroll-margin-top: 48px; }
+.hearth-library-label b { font-weight: 700; }
+.hearth-library-label a { color: #1f4fd8; }
+.hearth-library-failed { padding: 16px; }
+`;
+
+function Sample({ id, name, label, action, children }: { id?: string; name: string; label: string; action?: ReactNode; children: ReactNode }) {
+  return (
+    <>
+      <div id={id} className="hearth-library-label">
+        <span>
+          <b>{name}</b> · {label}
+        </span>
+        {action}
+      </div>
+      <div data-library-sample="">
+        <SampleBoundary>
+          <Suspense>{children}</Suspense>
+        </SampleBoundary>
+      </div>
+    </>
+  );
+}
+
+/**
+ * Every block on one page, drawn by the real components with this site's theme and overrides, so that a change in
+ * src/theme shows here at once. For `pnpm dev` only. Its samples stand in for a site's content, so nothing depends on
+ * which pages exist, and nothing here is saved. ?block=hero shows one block's samples.
+ */
+export default async function BlockLibrary({ searchParams }: { searchParams: Promise<{ block?: string | string[] }> }) {
+  if (process.env.NODE_ENV !== "development") notFound();
+  const { block } = await searchParams;
+  const samples = blockSamples(new Date());
+  const all = libraryGroups.flatMap((g) => g.blocks);
+  const only = all.find((b) => b.type === block);
+  const unstyled = `/hearth/blocks/unstyled${only ? `#block-${only.type}` : ""}`;
+  const showing = only ? [only] : all;
+  return (
+    <>
+      <style>{CSS}</style>
+      <SampleGuard />
+      <div className="hearth-library-bar">
+        <b>Block library</b>
+        <span className="hearth-library-switch">
+          <ViewLink href={unstyled}>Unstyled</ViewLink>
+          <span className="hearth-library-current">This site&apos;s theme</span>
+        </span>
+        <details className="hearth-library-jump">
+          <summary>{only ? only.label : "All blocks"}</summary>
+          <nav aria-label="Blocks">
+            <a href="/hearth/blocks">Every block on one page</a>
+            {libraryGroups.map((g) => (
+              <Fragment key={g.group}>
+                <p>{g.group}</p>
+                {g.blocks.map((b) => (
+                  <a key={b.type} href={`/hearth/blocks?block=${b.type}`}>
+                    {b.label}
+                  </a>
+                ))}
+              </Fragment>
+            ))}
+          </nav>
+        </details>
+        <span className="hearth-library-note">Sample content. Links and forms here do nothing.</span>
+      </div>
+      {only
+        ? null
+        : TONES.map((tone) => (
+            <Sample key={tone} id={tone === "default" ? "grounds" : undefined} name="Grounds" label={`${GROUND_NAMES[tone]} ground`}>
+              <Ground tone={tone} />
+            </Sample>
+          ))}
+      {only ? null : (
+        <Sample id="form-states" name="Form states" label="Errors, filled-in fields, options and the success message">
+          <FormStates />
+        </Sample>
+      )}
+      {showing.map((b) =>
+        samples[b.type].map((s, i) => (
+          <Sample key={s.block.id} id={i ? undefined : `block-${b.type}`} name={b.label} label={s.label} action={only ? <a href="/hearth/blocks">Show every block</a> : <a href={`/hearth/blocks?block=${b.type}`}>Only this block</a>}>
+            <Blocks blocks={[s.block]} />
+          </Sample>
+        )),
+      )}
+    </>
+  );
+}

package/template/src/hearth/block-library/pieces.tsx

@@ -0,0 +1,42 @@
+import { theme } from "@/theme";
+import { Alert, OptionCard, Question, Success } from "../forms/fields";
+import { Button, Section, SectionHeading, type Tone } from "../ui";
+
+/* What blocks share, for the block library: both its views draw these, the unstyled one and the site's own. */
+
+export const GROUND_NAMES: Record<Tone, string> = { default: "Standard", muted: "Subtle", inverse: "Dark", accent: "Brand color" };
+
+/** A heading and every button on one of the four grounds blocks sit on. */
+export function Ground({ tone }: { tone: Tone }) {
+  return (
+    <Section tone={tone} block="ground">
+      <SectionHeading eyebrow="Eyebrow" heading="A section heading with a *highlighted* phrase" intro="An intro under the heading, in a sentence or two." />
+      <div className={theme.hero.actions}>
+        <Button link={{ label: "Primary button", href: "#" }} />
+        <Button link={{ label: "Secondary button", href: "#" }} variant="secondary" />
+        <Button link={{ label: "Small", href: "#" }} size="small" />
+        <Button link={{ label: "Small", href: "#" }} variant="secondary" size="small" />
+      </div>
+    </Section>
+  );
+}
+
+/** What forms only show after someone submits, all together. */
+export function FormStates() {
+  return (
+    <Section block="form-states">
+      <div className={`${theme.formBlock.wrap} ${theme.form.root}`}>
+        <Alert>Please check the fields below and try again.</Alert>
+        <Question field={{ name: "email", label: "Email", type: "email", required: true }} idPrefix="states" error="Enter a valid email address." value="dana@" />
+        <Question field={{ name: "topic", label: "What is this about?", type: "select", required: true, options: ["Volunteering", "Donating"] }} idPrefix="states" error="Choose one." />
+        <Question field={{ name: "message", label: "Message", type: "textarea", required: true }} idPrefix="states" value="A message someone has already typed." />
+        <Question field={{ name: "updates", label: "Send me the monthly newsletter", type: "checkbox", required: false }} idPrefix="states" value="on" />
+        <OptionCard input={<input type="radio" name="states-option" defaultChecked className={theme.form.optionInput} />} title="A chosen option" meta="3 spots left">
+          <span className={theme.form.optionDetail}>Its details, under the title</span>
+        </OptionCard>
+        <OptionCard input={<input type="radio" name="states-option" disabled className={theme.form.optionInput} />} title="A full option" meta="Full" />
+        <Success>Thanks! We&apos;ll be in touch soon.</Success>
+      </div>
+    </Section>
+  );
+}

package/template/src/hearth/block-library/samples.ts

@@ -0,0 +1,342 @@
+/*
+ * What the block library shows: each block type with the options and states a design has to cover. The content is a
+ * made-up community kitchen, long enough to show how real copy sits. A new block type needs an entry here; Hearth's
+ * tests fail without one.
+ */
+import type { BlockOf, Fundraiser, HearthEvent, ImageRef } from "@the-smithy/hearth";
+import type { BlockComponents } from "@the-smithy/hearth/react";
+
+export type AnyType = keyof BlockComponents;
+type FormField = NonNullable<BlockOf<"form">["data"]["fields"]>[number];
+export type Sample = { label: string; block: BlockOf<AnyType> };
+
+let count = 0;
+function blockOf<T extends AnyType>(type: T, data: BlockOf<T>["data"]) {
+  return { id: `sample-${++count}`, type, data } as unknown as BlockOf<AnyType>;
+}
+
+/** A grey placeholder with its size written on it. */
+function image(width: number, height: number, alt = "Placeholder image"): ImageRef {
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}"><rect width="100%" height="100%" fill="#d9d9d9"/><path d="M0 0L${width} ${height}M${width} 0L0 ${height}" stroke="#bdbdbd" stroke-width="2"/></svg>`;
+  return { src: `data:image/svg+xml,${encodeURIComponent(svg)}`, alt, width, height } as ImageRef;
+}
+const photo = () => image(1200, 800);
+const portrait = (name: string) => image(600, 600, name);
+function logo(name: string): ImageRef {
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="160" height="40" viewBox="0 0 160 40"><rect width="160" height="40" fill="#d9d9d9"/><text x="80" y="25" font-family="sans-serif" font-size="14" fill="#595959" text-anchor="middle">${name}</text></svg>`;
+  return { src: `data:image/svg+xml,${encodeURIComponent(svg)}`, alt: name, width: 160, height: 40 } as ImageRef;
+}
+
+function fundraiser(slug: string, title: string, raisedCents: number, goalCents: number | null, donorCount: number, extra: Partial<Fundraiser> = {}): Fundraiser {
+  return {
+    slug,
+    path: `/fundraisers/${slug}`,
+    title,
+    summary: "Every gift goes toward equipment and ingredients for the meals we cook each week.",
+    image: photo(),
+    status: "active",
+    goalCents,
+    raisedCents,
+    donorCount,
+    startsAt: null,
+    endsAt: null,
+    categories: [],
+    ...extra,
+  };
+}
+const fundraisers = [
+  fundraiser("new-ovens", "New ovens for the kitchen", 1842500, 2500000, 214),
+  fundraiser("winter-meals", "Winter meals program", 640000, null, 57, { image: null }),
+  fundraiser("school-lunches", "School lunch fund", 1200000, 1200000, 132, { status: "completed" }),
+];
+
+const entry = (slug: string, title: string, date: string, tags: string[], hasImage = true) => ({
+  slug,
+  path: `/stories/${slug}`,
+  title,
+  date,
+  summary: "What we learned this month, from the volunteers who were there and the families they cooked for.",
+  image: hasImage ? photo() : null,
+  tags,
+  categories: [],
+  publishedAt: `${date}T12:00:00Z`,
+});
+const entries = [entry("first-year", "What a first year of shared meals taught us", "2026-09-14", ["Community", "Meals"]), entry("garden", "The garden that feeds forty families", "2026-08-02", ["Garden"]), entry("ovens", "Why we need new ovens", "2026-06-21", [], false)];
+const stories = { id: "c1", slug: "stories", name: "Stories", kind: "pages", description: null, path: "/stories", sort: "newest" } as const;
+
+const fields: FormField[] = [
+  { name: "name", label: "Your name", type: "text", required: true },
+  { name: "email", label: "Email", type: "email", required: true, placeholder: "you@example.org" },
+  { name: "phone", label: "Phone", type: "tel", required: false },
+  { name: "topic", label: "What is this about?", type: "select", required: true, options: ["Volunteering", "Donating", "Renting the kitchen"] },
+  { name: "message", label: "Message", type: "textarea", required: true },
+  { name: "updates", label: "Send me the monthly newsletter", type: "checkbox", required: false },
+];
+
+const markdown = `## Why we cook together
+
+Millbrook Community Kitchen opened in a church basement with two stoves. Today **more than three hundred neighbors** share a meal with us each week, and [anyone can join](/join).
+
+### What happens on a Tuesday
+
+1. Volunteers arrive at three and start prepping.
+2. Dinner goes out at six, with *no sign-up and no charge*.
+3. Whatever is left goes home with whoever wants it.
+
+Things to bring:
+
+- An appetite
+- A container for leftovers
+
+> The kitchen is the first place in this town where I knew everybody's name.
+
+| Day | Meal | Served |
+| --- | --- | --- |
+| Tuesday | Community dinner | 6:00 PM |
+| Saturday | Family breakfast | 9:00 AM |`;
+
+const people = [
+  { name: "Dana Whitfield", role: "Executive Director", image: portrait("Dana Whitfield"), bio: "Started the kitchen with two stoves and a borrowed van." },
+  { name: "Marco Reyes", role: "Head Cook", image: portrait("Marco Reyes"), bio: "Cooked in restaurants for twenty years before coming home to Millbrook." },
+  { name: "Priya Nair", role: "Volunteer Coordinator", image: portrait("Priya Nair"), bio: "Knows every volunteer by name, and what they're best at." },
+];
+
+const faqItems = [
+  { question: "Do I need to sign up for a meal?", answer: "No. Come any Tuesday at six. Everyone is welcome and every meal is free." },
+  { question: "Can I volunteer if I've never worked in a kitchen?", answer: "Yes. We'll pair you with someone experienced. **Most of our volunteers started that way.**" },
+  { question: "Can I rent the kitchen for my own event?", answer: "We rent to local groups on weekends. [Get in touch](/contact) for the rates." },
+];
+
+const plans = [
+  { name: "Neighbor", price: "$10", period: "per month", description: "For anyone who wants to help keep dinner free.", features: ["Monthly newsletter", "Member night invitations"], cta: { label: "Join", href: "/join" } },
+  { name: "Friend", price: "$25", period: "per month", description: "Covers a family's meals for a month.", features: ["Everything in Neighbor", "Name on the wall of friends", "Two guest passes"], cta: { label: "Join", href: "/join" }, highlight: "Most popular" },
+  { name: "Partner", price: "Let's talk", description: "For businesses that sponsor a program.", features: ["Everything in Friend", "Logo on the website"], cta: { label: "Contact us", href: "/contact" } },
+];
+
+const cards = [
+  { title: "Community dinners", body: "A free, hot meal every Tuesday, cooked by neighbors for neighbors.", image: photo(), link: { label: "See the menu", href: "/dinners" } },
+  { title: "Cooking classes", body: "Hands-on classes for every level, from knife skills to bread.", image: photo(), link: { label: "View classes", href: "/classes" } },
+  { title: "The kitchen garden", body: "Forty raised beds that supply a third of the produce we cook.", image: photo(), link: { label: "Visit the garden", href: "/garden" } },
+];
+
+const projects = [
+  { name: "Riverside Food Hub", description: "A shared cold store that lets six pantries buy together and **waste less**.", image: photo(), url: "https://example.org/hub", role: "Lead partner", status: "Live", stack: ["Cold storage", "Delivery van", "Shared ordering"] },
+  { name: "Lunch Box Library", description: "Reusable lunch boxes that families borrow and return at any school.", image: photo(), url: "https://example.org/lunch", role: "Program designer", status: "2024–2026", stack: ["Schools", "Volunteers"] },
+  { name: "Seed Exchange", description: "A yearly swap for seeds saved from the kitchen garden.", image: photo(), stack: [] },
+];
+
+const place = (name: string, address: string, lat: number, lng: number, hours: string) => ({ name, address, position: { lat, lng }, hours, notes: "Free parking behind the building. Step-free entrance on Mill Street.", link: { label: "About this kitchen", href: "/kitchens" } });
+const places = [place("Mill Street Kitchen", "410 Mill Street\nMillbrook, IL", 41.6, -88.5, "Mon–Fri · 9am–5pm"), place("Eastside Pantry", "22 Elm Avenue\nMillbrook, IL", 41.61, -88.47, "Tue & Thu · 2pm–6pm"), place("Riverside Hub", "9 Water Street\nMillbrook, IL", 41.59, -88.52, "Saturdays · 8am–noon")];
+
+/** The blocks in the order and groups Hearth's editor lists them (build.ts checks them against its registry). */
+export const libraryGroups: { group: string; blocks: { type: AnyType; label: string }[] }[] = [
+  { group: "Layout", blocks: [{ type: "hero", label: "Hero" }, { type: "cta", label: "Call to action" }] },
+  {
+    group: "Content",
+    blocks: [
+      { type: "richText", label: "Text" },
+      { type: "mediaText", label: "Image + text" },
+      { type: "stats", label: "Stats" },
+      { type: "cardGrid", label: "Cards" },
+      { type: "faq", label: "FAQ" },
+      { type: "pricing", label: "Pricing" },
+      { type: "projects", label: "Projects" },
+      { type: "quote", label: "Quote" },
+      { type: "people", label: "People" },
+      { type: "logos", label: "Logos" },
+      { type: "collectionList", label: "Collection list" },
+    ],
+  },
+  { group: "Media", blocks: [{ type: "gallery", label: "Photo gallery" }, { type: "video", label: "Video" }, { type: "embed", label: "Embed" }] },
+  {
+    group: "Places & events",
+    blocks: [
+      { type: "location", label: "Location" },
+      { type: "locations", label: "Locations" },
+      { type: "schedule", label: "Schedule" },
+      { type: "upcomingEvents", label: "Upcoming events" },
+      { type: "pastEvents", label: "Past events" },
+      { type: "eventSpotlight", label: "Event spotlight" },
+    ],
+  },
+  { group: "Forms", blocks: [{ type: "volunteerSignup", label: "Volunteer sign-up" }, { type: "form", label: "Form" }] },
+  { group: "Giving", blocks: [{ type: "fundraiserSpotlight", label: "Fundraiser spotlight" }, { type: "fundraiserGrid", label: "Fundraisers" }, { type: "donate", label: "Donation form" }] },
+];
+
+/** The active fundraisers a general donation form offers. */
+export const activeFundraisers = fundraisers.filter((f) => f.status === "active");
+
+/** Every block's samples. `today` sets their dates, so that upcoming events stay upcoming. */
+export function blockSamples(today: Date): Record<AnyType, Sample[]> {
+  const DAY = 86_400_000;
+  const at = (days: number, hour: number) => {
+    const d = new Date(today.getTime() + days * DAY);
+    d.setUTCHours(hour + 5, 0, 0, 0);
+    return d.toISOString();
+  };
+
+  function event(slug: string, title: string, days: number, extra: Partial<HearthEvent> = {}): HearthEvent {
+    return {
+      slug,
+      title,
+      status: "published",
+      summary: "An evening of cooking, sharing a table and meeting the neighbors who keep the kitchen running.",
+      startsAt: at(days, 18),
+      endsAt: at(days, 21),
+      allDay: false,
+      timezone: "America/Chicago",
+      location: { name: "Millbrook Community Kitchen", address: "410 Mill Street, Millbrook, IL" },
+      attendance: "in_person",
+      registrationUrl: "https://example.org/register",
+      image: photo(),
+      customFields: {},
+      path: `/events/${slug}`,
+      collection: null,
+      categories: [],
+      registration: null,
+      volunteering: null,
+      ...extra,
+    };
+  }
+
+  const events = [
+    event("harvest-supper", "Harvest Supper", 30),
+    event("knife-skills", "Knife Skills for Beginners", 44, { registrationUrl: null, registration: { open: false, closesAt: null, tickets: [{ soldOut: true }], fundraiser: null } as unknown as HearthEvent["registration"] }),
+    event("preserving", "Preserving the Season", 58, { status: "cancelled", image: null }),
+  ];
+  const pastEvents = [event("spring-table", "Spring Table", -60, { registrationUrl: null }), event("bread-day", "Community Bread Day", -95, { registrationUrl: null, image: null }), event("soup-swap", "Soup Swap", -130, { registrationUrl: null })];
+
+  const volunteering = {
+    open: true,
+    closesAt: null,
+    intro: "We need hands for setup, cooking and cleanup. No experience needed.",
+    fields: [{ name: "shirt", label: "Anything we should know?", type: "textarea", required: false }],
+    pickShifts: "many",
+    shifts: [
+      { id: "s1", name: "Setup", description: "Tables, chairs and signs.", startsAt: at(30, 15), endsAt: at(30, 17), remaining: null, full: false },
+      { id: "s2", name: "Cooking", description: null, startsAt: at(30, 16), endsAt: at(30, 19), remaining: 3, full: false },
+      { id: "s3", name: "Cleanup", description: null, startsAt: at(30, 21), endsAt: at(30, 23), remaining: 0, full: true },
+    ],
+    submitLabel: "Sign up",
+    successMessage: "Thanks for signing up.",
+    fundraiser: { slug: "new-ovens", title: "New ovens for the kitchen" },
+  } as const;
+
+  return {
+    hero: [
+      { label: "Full size, with image and both buttons", block: blockOf("hero", { eyebrow: "Millbrook Community Kitchen", heading: "A seat at the table for *everyone*", body: "Free meals, cooking classes and a garden that feeds forty families, all run by the neighbors who use them.", image: photo(), primaryCta: { label: "Come to dinner", href: "/dinners" }, secondaryCta: { label: "Volunteer", href: "/volunteer" }, size: "full" }) },
+      { label: "Compact, without an image (inner pages)", block: blockOf("hero", { heading: "About the kitchen", body: "How a church basement and two stoves became a meal for three hundred people a week.", size: "compact" }) },
+      { label: "With the site's logo", block: blockOf("hero", { heading: "A seat at the table for *everyone*", showLogo: true, logo: logo("Site logo"), primaryCta: { label: "Come to dinner", href: "/dinners" }, size: "compact" }) },
+      { label: "Background: Standard", block: blockOf("hero", { eyebrow: "Our story", heading: "Cooked by neighbors, for neighbors", body: "Every meal since 2011.", primaryCta: { label: "Read more", href: "/about" }, secondaryCta: { label: "Volunteer", href: "/volunteer" }, size: "compact", tone: "default" }) },
+      { label: "Background: Subtle", block: blockOf("hero", { eyebrow: "Our story", heading: "Cooked by neighbors, for neighbors", primaryCta: { label: "Read more", href: "/about" }, size: "compact", tone: "muted" }) },
+      { label: "Background: Brand color", block: blockOf("hero", { eyebrow: "Our story", heading: "Cooked by neighbors, for neighbors", primaryCta: { label: "Read more", href: "/about" }, size: "compact", tone: "accent" }) },
+    ],
+    richText: [
+      { label: "Narrow, with every kind of formatting", block: blockOf("richText", { markdown, width: "narrow" }) },
+      { label: "Wide", block: blockOf("richText", { markdown: "## A wider column of text\n\nWide text runs the full width of the site's content area. It suits short statements and text with tables more than long reading.", width: "wide" }) },
+    ],
+    mediaText: [
+      { label: "Image on the right, with a button", block: blockOf("mediaText", { eyebrow: "The garden", heading: "Forty beds, *one* big harvest", markdown: "Our garden supplies a third of the produce we cook. Families who tend a bed take home what they grow.\n\n- Open to everyone\n- Tools provided", image: photo(), imagePosition: "right", imageFit: "cover", cta: { label: "Visit the garden", href: "/garden" } }) },
+      { label: "Image on the left", block: blockOf("mediaText", { heading: "Classes for every level", markdown: "From knife skills to sourdough, our classes are hands-on and pay-what-you-can.", image: photo(), imagePosition: "left", imageFit: "cover" }) },
+      { label: "Image fit: whole image (logos, badges)", block: blockOf("mediaText", { heading: "Certified by the state food bank", markdown: "We meet every food safety standard, and we're inspected each year.", image: logo("Badge"), imagePosition: "right", imageFit: "contain" }) },
+    ],
+    stats: [
+      { label: "With a heading", block: blockOf("stats", { heading: "Last year at the kitchen", items: [{ value: "15,600", label: "Meals served" }, { value: "340", label: "Volunteers" }, { value: "40", label: "Garden beds" }, { value: "$0", label: "Charged for dinner" }] }) },
+      { label: "Without a heading, two numbers", block: blockOf("stats", { items: [{ value: "15+", label: "Years cooking together" }, { value: "6", label: "Partner pantries" }] }) },
+    ],
+    cardGrid: [
+      { label: "Images and links, Standard background", block: blockOf("cardGrid", { eyebrow: "What we do", heading: "Three ways to take part", intro: "Whichever you choose, there's a place for you.", items: cards, tone: "default" }) },
+      { label: "Text only, Subtle background", block: blockOf("cardGrid", { heading: "What to expect", items: cards.map(({ title, body }) => ({ title, body })), tone: "muted" }) },
+      { label: "Dark background", block: blockOf("cardGrid", { heading: "What to expect", items: cards.map(({ title, body, link }) => ({ title, body, link })), tone: "inverse" }) },
+      { label: "Brand color background, no heading", block: blockOf("cardGrid", { items: cards.map(({ title, body, link }) => ({ title, body, link })), tone: "accent" }) },
+    ],
+    faq: [
+      { label: "Answers open on click (the first is open here)", block: blockOf("faq", { heading: "Common questions", items: faqItems, display: "accordion" }) },
+      { label: "All answers showing", block: blockOf("faq", { heading: "Common questions", items: faqItems, display: "list" }) },
+    ],
+    pricing: [
+      { label: "Three plans, one highlighted", block: blockOf("pricing", { eyebrow: "Membership", heading: "Keep dinner free", intro: "Members cover the cost of what we cook.", plans, footnote: "Cancel any time. Donations are tax deductible. [See our finances](/finances).", tone: "default" }) },
+      { label: "Four plans, Subtle background", block: blockOf("pricing", { heading: "Membership", plans: [...plans, { name: "Patron", price: "$100", period: "per month", features: ["Everything in Friend", "An annual dinner with the cooks"], cta: { label: "Join", href: "/join" } }], tone: "muted" }) },
+      { label: "Dark background", block: blockOf("pricing", { heading: "Membership", plans, tone: "inverse" }) },
+    ],
+    projects: [
+      { label: "Showcase (large images, alternating sides)", block: blockOf("projects", { eyebrow: "Our work", heading: "What we've built together", intro: "Programs that started in the kitchen and grew.", items: projects, layout: "showcase", tone: "default" }) },
+      { label: "Grid (compact cards), Subtle background", block: blockOf("projects", { heading: "Our work", items: projects, layout: "grid", tone: "muted" }) },
+    ],
+    cta: [
+      { label: "Brand color", block: blockOf("cta", { heading: "Ready to *pull up a chair*?", body: "Dinner is every Tuesday at six. Everyone is welcome.", primary: { label: "Get directions", href: "/visit" }, secondary: { label: "Volunteer", href: "/volunteer" }, tone: "accent" }) },
+      { label: "Dark", block: blockOf("cta", { heading: "Ready to pull up a chair?", primary: { label: "Get directions", href: "/visit" }, secondary: { label: "Volunteer", href: "/volunteer" }, tone: "inverse" }) },
+      { label: "Subtle, with one button", block: blockOf("cta", { heading: "Ready to pull up a chair?", body: "Dinner is every Tuesday at six.", primary: { label: "Get directions", href: "/visit" }, tone: "muted" }) },
+      { label: "Standard, with one button", block: blockOf("cta", { heading: "Ready to pull up a chair?", primary: { label: "Get directions", href: "/visit" }, tone: "default" }) },
+      { label: "With a background photo", block: blockOf("cta", { heading: "Ready to pull up a chair?", body: "Dinner is every Tuesday at six.", primary: { label: "Get directions", href: "/visit" }, secondary: { label: "Volunteer", href: "/volunteer" }, tone: "default", image: photo() }) },
+    ],
+    quote: [
+      { label: "With photo, Standard background", block: blockOf("quote", { quote: "The kitchen is the first place in this town where I knew everybody's name.", name: "Rosa Delgado", role: "Volunteer since 2019", image: portrait("Rosa Delgado"), tone: "default" }) },
+      { label: "Name only, Subtle background", block: blockOf("quote", { quote: "My kids ask every week whether it's Tuesday yet.", name: "James Okafor", tone: "muted" }) },
+      { label: "Dark background", block: blockOf("quote", { quote: "Nobody asks why you came. They just hand you a plate.", name: "Rosa Delgado", role: "Volunteer since 2019", image: portrait("Rosa Delgado"), tone: "inverse" }) },
+      { label: "Brand color, no name", block: blockOf("quote", { quote: "Nobody asks why you came. They just hand you a plate.", tone: "accent" }) },
+    ],
+    people: [
+      { label: "Photos, roles and bios", block: blockOf("people", { eyebrow: "Who we are", heading: "Our team", intro: "A small staff and a lot of volunteers.", people }) },
+      { label: "Names and roles only", block: blockOf("people", { heading: "Our board", people: people.map(({ name, role }) => ({ name, role })) }) },
+    ],
+    logos: [
+      { label: "Logos, some linked", block: blockOf("logos", { heading: "Our partners", intro: "We couldn't do this without them.", logos: [{ name: "Food Bank", logo: logo("Food Bank"), url: "https://example.org" }, { name: "City Farm", logo: logo("City Farm") }, { name: "School District", logo: logo("School District"), url: "https://example.org" }, { name: "Rotary", logo: logo("Rotary") }, { name: "Library", logo: logo("Library") }] }) },
+      { label: "Names, when there's no logo", block: blockOf("logos", { logos: [{ name: "Millbrook Food Bank", url: "https://example.org" }, { name: "City Farm" }, { name: "Rotary Club" }] }) },
+    ],
+    gallery: [
+      { label: "3 across, with captions", block: blockOf("gallery", { heading: "Life in the kitchen", intro: "A few photos from this year.", images: [1, 2, 3, 4, 5, 6].map((n) => ({ image: photo(), caption: n % 2 ? "Tuesday dinner service" : undefined })), columns: "3" }) },
+      { label: "2 across (larger)", block: blockOf("gallery", { images: [1, 2].map(() => ({ image: photo() })), columns: "2" }) },
+      { label: "4 across (smaller)", block: blockOf("gallery", { images: [1, 2, 3, 4].map(() => ({ image: photo() })), columns: "4" }) },
+    ],
+    video: [{ label: "With heading and caption", block: blockOf("video", { heading: "A Tuesday at the kitchen", url: "https://www.youtube.com/watch?v=aqz-KE-bpKQ", title: "A Tuesday at the kitchen", caption: "Filmed by volunteers in the spring." }) }],
+    embed: [
+      { label: "Narrow", block: blockOf("embed", { html: "<p>Booking widget</p>", title: "Book a table", height: 300, width: "narrow", caption: "Bookings are handled by another service." }) },
+      { label: "Wide", block: blockOf("embed", { html: "<p>Booking widget</p>", title: "Book a table", height: 300, width: "wide" }) },
+      { label: "Full width", block: blockOf("embed", { html: "<p>Booking widget</p>", title: "Book a table", height: 300, width: "full" }) },
+    ],
+    location: [
+      { label: "With a map", block: blockOf("location", { eyebrow: "Visit us", heading: "Find the kitchen", name: "Mill Street Kitchen", address: "410 Mill Street\nMillbrook, IL 60541", hours: "Mon–Fri · 9am–5pm\nDinner Tuesdays at 6pm", notes: "Free parking behind the building. **Step-free entrance** on Mill Street.", position: { lat: 41.6, lng: -88.5 }, showMap: true }) },
+      { label: "Without a map or heading", block: blockOf("location", { name: "Mill Street Kitchen", address: "410 Mill Street\nMillbrook, IL 60541", showMap: false }) },
+    ],
+    locations: [
+      { label: "With a map", block: blockOf("locations", { eyebrow: "Find us", heading: "Our locations", intro: "Three places, all open to everyone.", items: places, showMap: true }) },
+      { label: "Without a map", block: blockOf("locations", { heading: "Our locations", items: places, showMap: false }) },
+    ],
+    schedule: [{ label: "With details on some items", block: blockOf("schedule", { eyebrow: "Saturday", heading: "Schedule", intro: "Doors open at eleven.", items: [{ time: "11:00 am", title: "Doors open", details: "Coffee and pastries in the hall." }, { time: "12:30 pm", title: "Lunch" }, { time: "2:00 pm", title: "Cooking demonstration", details: "Marco Reyes shows how to make stock from kitchen scraps." }, { time: "4:00 pm", title: "Close" }] }) }],
+    upcomingEvents: [
+      { label: "Register button, sold out, and cancelled without an image", block: blockOf("upcomingEvents", { eyebrow: "What's on", heading: "Upcoming events", intro: "Everyone is welcome.", limit: 3, events }) },
+      { label: "Registration coming soon, with a link to all of a collection's events", block: blockOf("upcomingEvents", { heading: "Talks", limit: 1, events: [event("talk", "Feeding a Town", 70, { registrationUrl: null })], collection: { ...stories, name: "Talks", path: "/talks", kind: "events" } }) },
+      { label: "When there are none", block: blockOf("upcomingEvents", { heading: "Upcoming events", limit: 3, events: [] }) },
+    ],
+    pastEvents: [
+      { label: "Past events (Subtle background by default)", block: blockOf("pastEvents", { heading: "Past events", intro: "Photos and recipes from earlier gatherings.", limit: 6, events: pastEvents }) },
+      { label: "When there are none", block: blockOf("pastEvents", { heading: "Past events", limit: 6, events: [], emptyText: "Nothing here yet. Our first gathering is coming up." }) },
+    ],
+    collectionList: [
+      { label: "Cards with images", block: blockOf("collectionList", { eyebrow: "From the kitchen", heading: "Latest stories", intro: "News and recipes from our volunteers.", collectionId: "c1", limit: 3, layout: "cards", collection: stories, entries }) },
+      { label: "Simple list", block: blockOf("collectionList", { heading: "Latest stories", collectionId: "c1", limit: 3, layout: "list", collection: stories, entries }) },
+      { label: "When there are none", block: blockOf("collectionList", { heading: "Latest stories", collectionId: "c1", limit: 3, layout: "cards", collection: stories, entries: [] }) },
+    ],
+    eventSpotlight: [{ label: "With a label and image", block: blockOf("eventSpotlight", { heading: "Featured event", event: { ...events[0], meta: {}, blocks: [] } as never }) }],
+    volunteerSignup: [
+      { label: "Open, with shifts (one is full)", block: blockOf("volunteerSignup", { eventSlug: "harvest-supper", heading: "Volunteer", event: { ...events[0], volunteering: volunteering } as never }) },
+      { label: "Closed", block: blockOf("volunteerSignup", { eventSlug: "harvest-supper", heading: "Volunteer", event: { ...events[0], volunteering: { ...volunteering, open: false } } as never }) },
+    ],
+    form: [{ label: "Every kind of field", block: blockOf("form", { heading: "Get in touch", intro: "We read everything and reply within two days.", formKey: "contact", fields: [...fields], submitLabel: "Send", successMessage: "Thanks! We'll be in touch soon." }) }],
+    fundraiserSpotlight: [
+      { label: "Active, with a goal", block: blockOf("fundraiserSpotlight", { heading: "Featured fundraiser", fundraiser: fundraisers[0] }) },
+      { label: "Completed (no Donate button)", block: blockOf("fundraiserSpotlight", { fundraiser: fundraisers[2] }) },
+    ],
+    fundraiserGrid: [
+      { label: "With a goal, without a goal or image, and completed", block: blockOf("fundraiserGrid", { eyebrow: "Giving", heading: "Current fundraisers", intro: "Choose what your gift supports.", status: "all", limit: 6, fundraisers }) },
+      { label: "When there are none", block: blockOf("fundraiserGrid", { heading: "Current fundraisers", status: "active", limit: 6, fundraisers: [] }) },
+    ],
+    donate: [
+      { label: "General, with a choice of fundraiser", block: blockOf("donate", { heading: "Make a gift", intro: "Your gift keeps dinner free.", submitLabel: "Donate", presetsCents: [2500, 5000, 10000, 25000], minCents: 500, maxCents: 2500000, fundraiser: null }) },
+      { label: "Giving to one fundraiser", block: blockOf("donate", { heading: "Make a gift", fundraiserSlug: "new-ovens", submitLabel: "Donate", presetsCents: [2500, 5000, 10000], minCents: 500, maxCents: 2500000, fundraiser: fundraisers[0] }) },
+    ],
+    // Each site designs its own, in its own code, so the template has nothing to show.
+    custom: [],
+  };
+}

package/template/src/hearth/manifest.json

@@ -17,6 +17,8 @@
     "src/app/robots.ts",
     "src/app/sitemap.ts",
     "src/app/llms.txt/route.ts",
+    "src/app/hearth/blocks/page.tsx",
+    "src/app/hearth/blocks/unstyled/route.ts",
     "src/app/api/preview/route.ts",
     "src/app/api/preview/exit/route.ts",
     "src/app/api/revalidate/route.ts",