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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-smithy/create-hearth-site",
-  "version": "0.27.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.27.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

@@ -86,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.

package/template/README.md

@@ -98,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`) |
@@ -170,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/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",