@the-smithy/create-hearth-site 0.30.0 → 0.33.0

package/bin/create-hearth-site.js

@@ -21,7 +21,7 @@ const self = JSON.parse(await readFile(path.join(here, "..", "package.json"), "u
 // The template's lockfile is the Hearth workspace's (the SDK as a workspace link); a new site makes its own.
 const SKIP = new Set(["node_modules", ".next", ".netlify", ".vercel", ".env.local", "next-env.d.ts", "tsconfig.tsbuildinfo", "pnpm-lock.yaml"]);
 /** Dotfiles npm won't publish (or that would confuse the monorepo) are stored with a leading underscore. */
-const RENAMES = { _gitignore: ".gitignore", "_pnpm-workspace.yaml": "pnpm-workspace.yaml" };
+const RENAMES = { _gitignore: ".gitignore", _gitattributes: ".gitattributes", "_pnpm-workspace.yaml": "pnpm-workspace.yaml" };
 
 const usage = `Usage: pnpm create @the-smithy/hearth-site@latest <folder> --site <address> [--skip-install]
 

package/package.json

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

package/template/AGENTS.md

@@ -83,8 +83,9 @@ Work in this order, and stop at the first step that gets the result:
    (`[data-page="events"]`, so the same blocks elsewhere stay as they are) or one card (`[data-card="our-history"]`, from
    its title).
 5. **A page in Hearth** for words the code draws on its own pages: see "Pages at the code's addresses" below.
-6. **Overrides**, last: `src/theme/overrides.tsx` (see "Overrides" below). An override is the site's own code: updates
-   don't reach it, so it falls behind Hearth. Use one only when everything above can't get there, build it from
+6. **Overrides**, last: `src/theme/overrides.tsx` (see "Overrides" below). Use one only when everything above can't
+   get there, and the smallest that does: add to Hearth's component rather than replace it, and replace one part of a
+   block rather than the whole. What the site replaces is its own code, which updates don't reach. 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: each block with
@@ -94,9 +95,9 @@ It shows one block at a time: `/hearth/blocks?block=hero` goes to one, and `?blo
 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.
+Never copy a component out of `src/hearth/` to restyle or extend it: an override is given Hearth's own as `children`
+for that. 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.
 
 ### Pages at the code's addresses
 
@@ -112,19 +113,83 @@ never serves at `/not-found`, and redirects run before it.
 ### Overrides
 
 Everything is optional. A site's file only exports what it uses, and an update never replaces it. They can import
-Hearth's components, `Blocks` too. The types are in `src/hearth/overrides.ts`. They're used everywhere the template draws
-these things:
+Hearth's components, `Blocks` too. The types are in `src/hearth/overrides.ts`.
+
+**Each override is given Hearth's own version as `children`.** Keep it and add to it, and Hearth's stays up to date
+underneath the site's; leave it out, and the site's replaces it and falls behind. Reach for them in this order:
+
+1. **Add to a part**, keeping Hearth's: `({ children }) => <>{children}<Extra /></>`.
+2. **Replace a part**: the part's own markup, the rest of the block still Hearth's.
+3. **Add to a whole block**: something before or after it, inside its anchor.
+4. **Replace a whole block**, last.
+
+```tsx
+// src/theme/overrides.tsx
+import type { Overrides } from "@/hearth/overrides";
+import { theme } from "@/theme";
+
+export const parts: Overrides["parts"] = {
+  // A third link beside the hero's two, which stay Hearth's.
+  "hero.actions": ({ children }) => (
+    <>
+      {children}
+      <a href="tel:+15551234567" className={theme.button.secondary}>Call us</a>
+    </>
+  ),
+  // Each card as Hearth draws it, with a note under the ones without a link.
+  "cardGrid.item": ({ item, children }) => (
+    <>
+      {children}
+      {item.link ? null : <p className={theme.cardGrid.body}>Coming soon</p>}
+    </>
+  ),
+};
+
+export const blocks: Overrides["blocks"] = {
+  // Hearth's Stats block, with a source line under it.
+  stats: ({ children }) => (
+    <>
+      {children}
+      <p className={theme.section.inner}>Figures audited in 2026.</p>
+    </>
+  ),
+};
+```
+
+**Parts** (`parts`, by name; every one is in `PartProps` in `src/hearth/overrides.ts`, and `get_block_type` on Hearth's
+MCP server lists a block's). A part is what's inside its element, which stays Hearth's with its slot and attributes:
+
+| Part | Is | Blocks |
+| --- | --- | --- |
+| `<type>.heading` | The block's heading: eyebrow, heading and intro (the hero's and a CTA's: the text above the buttons) | Most blocks |
+| `<type>.item` | One item's contents, inside its `<li>` (a stat's `<div>`, a question's `<div>` or `<details>`). Given `item`, `index` and, for ones with a title, `heading` (`"h2"` or `"h3"`) | `stats`, `cardGrid`, `projects`, `pricing`, `faq`, `gallery`, `people`, `logos`, `locations`, `schedule`, `collectionList` |
+| `<type>.actions` | The links inside the button row. The row is drawn for the site's part even with no links in Hearth | `hero`, `mediaText`, `cta`, `eventSpotlight`, `fundraiserSpotlight` |
+| `<type>.media` | The image (children is null without one, and the part can still draw something) | `hero`, `mediaText`, `cta`, `eventSpotlight`, `fundraiserSpotlight` |
+| `location.details` | The name, address, hours and directions beside the map | `location` |
+
+Every part is given the `block` too.
+
+**The rest**, used everywhere the template draws them:
 
-| Export | Replaces | Given |
+| Export | Is | Given |
 | --- | --- | --- |
-| `blocks` | A whole block's component, by type | `{ block }`. An anchor from Hearth keeps working around it |
-| `Logo` | The logo in the header, and in the footer once the `footer.logo` slot has classes | `{ site, place }` |
+| `blocks` | A whole block, by type. An anchor from Hearth goes around it, so Hearth's in `children` has none | `{ block }` |
+| `Logo` | The logo in the header, and in the footer once the `footer.logo` slot has classes. Hearth's has no component, so no `children` | `{ site, place }` |
 | `Footer` | The footer | `{ site }` |
 | `EventPage` | An event's page, at `/events/…` and in collections, so a site needs no route of its own | `{ event }` |
 | `FundraiserPage` | A fundraiser's page | `{ fundraiser }` |
-| `EventCard`, `FundraiserCard` | The cards in lists; each draws an `<li>`, and may be async | `{ event }` or `{ fundraiser }`, and `heading`: `"h2"` or `"h3"`, for its title |
+| `EventCard`, `FundraiserCard` | The cards in lists; each draws an `<li>` (Hearth's in `children` is one too), and may be async | `{ event }` or `{ fundraiser }`, and `heading`: `"h2"` or `"h3"`, for its title |
 | `DonateForm` | The donation form | The amounts, `fundraiser`, `fundraisers` (active ones to choose from) and `submitLabel` |
 
+`children` works in client components too: it's Hearth's version already drawn, not a function. To draw Hearth's with
+different content, import its component and give it changed data:
+`import { Stats } from "@/hearth/blocks/content"`, then `<Stats block={{ ...block, data: { ...block.data, heading: "…" } }} />`.
+Not through `Blocks`, which would draw the site's override again.
+
+**After an update**, `pnpm hearth:update` lists what's overridden here whose Hearth version changed, and parts or
+blocks Hearth no longer has. `pnpm hearth:overrides` checks against the last commit any time (`--since <git ref>` for
+another). Look at each in `pnpm dev`.
+
 `EventPage` and `FundraiserPage` have their structured data drawn around them. To build on Hearth's: `EventContent`,
 `EventRegisterSection` and `EventVolunteerSection` from `components/EventView.tsx`, `FundraiserContent` from
 `components/FundraiserView.tsx`. A site's own routes are for pages Hearth has no address for, not for an event's or
@@ -153,8 +218,8 @@ each site stays on the template and on current releases:
   file, or write a site's own data layer, SEO or forms. A bug or a gap in Hearth's code gets fixed in Hearth's
   template and reaches the site by an update; say so to the developer, and if it can't wait, bridge it with an override
   and note it in `SITE.md`.
-- **After an update, look through `SITE.md`'s overrides** and compare each with the component it replaced in
-  `src/hearth/blocks`, since updates don't reach them. Delete any that the theme can now do.
+- **After an update, check the overrides** that `pnpm hearth:update` lists as changed in Hearth (`pnpm hearth:overrides`
+  any time), and look through `SITE.md`'s. Delete any that the theme or a smaller override can now do.
 
 ## First steps in a new checkout
 
@@ -166,10 +231,15 @@ Do these before writing code, and tell the developer what you found:
    it. If it fails, its message says what to fix (missing key, wrong `HEARTH_SITE`, revoked key). Ask the developer to
    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
+   forms, previews, SEO) to `hearth-api.md`, and its onboarding guide to `hearth-onboarding.md`: how to set up,
+   design and build a site, step by step, with code samples. Read the parts you need from them, and from
    `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.
+   Hearth's MCP server (`/api/mcp` on Hearth, read-only, with the site's API key) answers the same questions without
+   the files, if the developer has connected it: each block's fields, slots and starting classes, the tokens, and the
+   published content. For design work, its `get_design_workflow` tool is the way to carry a design from Figma, and
+   `read_onboarding_guide` reads the onboarding guide.
 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.
 4. **Then style the site** as above, checking with `pnpm dev` against the published pages, on a phone width too.

package/template/README.md

@@ -51,9 +51,10 @@ 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 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.
+2. **Give the agent the full reference:** `pnpm hearth:docs` saves Hearth's API guide to `hearth-api.md` and its
+   onboarding guide to `hearth-onboarding.md` (neither 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
+   them.
 3. **Then tell it what to build.** Prompts that work well:
 
    - *"Run the first steps in AGENTS.md and tell me what's published and which blocks the site uses."*
@@ -64,6 +65,11 @@ Once your API key is in `.env.local`:
    - *"The gallery looks plain. Make it a masonry grid using its slots in the theme, keeping it accessible."*
    - *"Run `pnpm hearth:update`, then check every published page still looks right."*
 
+**Without the code, or for design work:** Hearth also has an MCP server, so an agent can read the site's blocks, design
+system and published content from anywhere, read-only. Hearth's **API & webhooks** page shows how to connect it. Ask a
+connected agent to start with `get_design_workflow` to design the site in Figma and bring the design back into
+`src/theme/`.
+
 Keep the API key out of chat: the agent never needs to see it, only `.env.local` does. If it asks for content
 (page text, menus, contact details), the answer is to add or publish it in Hearth, not to write it into the code.
 
@@ -101,7 +107,7 @@ Keep the API key out of chat: the agent never needs to see it, only `.env.local`
 | `/hearth/blocks` | Not a file: while `pnpm dev` runs, this address shows each block with your theme, one at a time, without setting up pages for them. `?block=hero` goes to one, and `?block=all` shows the whole list. 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`) |
+| `src/theme/overrides.tsx` | Last resort: add to or replace a part of a block (its heading, items, buttons or image), a whole block, the logo, the footer, the event or fundraiser page, their cards or the donation form. Each is given Hearth's own as `children`, to keep and add to (see `AGENTS.md`) |
 | `SITE.md` | Notes about this site's design, for the next person or coding agent |
 
 A slot holds the classes of one element, e.g. `hero.title` or `cardGrid.card`. Set a string to replace the default,
@@ -169,6 +175,10 @@ packages are public on npm, so nothing else is needed to install them.
 
 ## Documentation
 
+**New to Hearth? Start with the onboarding guide**, in Hearth under **Onboarding guide** (`/admin/docs/onboarding`):
+setting up this site, designing it in code or in Figma, building on the SDK, and prompting coding agents at each stage,
+with sample prompts and the skills above. `pnpm hearth:docs` saves it as `hearth-onboarding.md` for your agent.
+
 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**.
@@ -186,4 +196,5 @@ with `pnpm add @the-smithy/<name>@latest`.
 
 Keep the site on the template: design goes in `src/theme/`, and bugs or gaps in `src/hearth/` get fixed in Hearth's
 template rather than here. If a site has to bridge a gap, its override goes in `src/theme/overrides.tsx` with a note
-in `SITE.md`.
+in `SITE.md`. `src/hearth/` is collapsed in pull requests (`.gitattributes`), and after an update `pnpm hearth:update`
+lists the overrides whose Hearth version changed (`pnpm hearth:overrides` any time).

package/template/SITE.md

@@ -11,7 +11,7 @@ site's and stays as it is.
 
 ## Overrides
 
-Components replaced in `src/theme/overrides.tsx`, and why slots, tokens and CSS couldn't do it. Check each against
-`src/hearth/blocks` after an update.
+What `src/theme/overrides.tsx` adds to or replaces, and why slots, tokens and CSS couldn't do it. After an update,
+check the ones `pnpm hearth:update` lists as changed in Hearth.
 
 - None.

package/template/_gitattributes

@@ -0,0 +1,2 @@
+# Hearth's code, which pnpm hearth:update replaces: collapsed in pull requests, where the site's own changes matter.
+src/hearth/** linguist-generated=true

package/template/_gitignore

@@ -11,8 +11,9 @@ next-env.d.ts
 .env*
 !.env.example
 
-# Hearth's API guide, downloaded by pnpm hearth:docs for AI assistants.
+# Hearth's API and onboarding guides, downloaded by pnpm hearth:docs for AI assistants.
 hearth-api.md
+hearth-onboarding.md
 
 # Drift's code index, rebuilt as needed.
 .drift-index.json

package/template/package.json

@@ -11,6 +11,7 @@
     "hearth:check": "node scripts/hearth.mjs check",
     "hearth:docs": "node scripts/hearth.mjs docs",
     "hearth:drift": "node scripts/hearth.mjs drift",
+    "hearth:overrides": "node scripts/hearth.mjs overrides",
     "hearth:update": "node scripts/hearth.mjs update"
   },
   "dependencies": {

package/template/scripts/hearth.mjs

@@ -1,11 +1,14 @@
 // Setup helpers for this site, for you or your coding agent. Both read .env.local and never print the API key.
 //   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 Drift
+//   pnpm hearth:docs    saves Hearth's full API guide to hearth-api.md and its onboarding guide to hearth-onboarding.md
+//                       (neither committed) for an AI assistant to read, 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
+//   pnpm hearth:overrides  lists what src/theme/overrides.tsx overrides whose Hearth version changed since the last
+//                       commit (or --since <git ref>), which hearth:update runs too
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
@@ -158,11 +161,25 @@ async function docs() {
   if (!res.ok) fail(`Hearth didn't return the API guide (${res.status}). Check the API key with pnpm hearth:check.`);
   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.");
+  const guide = await fetch(`${env.baseUrl}/admin/docs/onboarding.md`, { headers: { Authorization: `Bearer ${env.apiKey}` } });
+  if (guide.ok) {
+    writeFileSync("hearth-onboarding.md", await guide.text());
+    ignore("hearth-onboarding.md");
+    console.log("✓ Saved Hearth's onboarding guide to hearth-onboarding.md (not committed): setup, design, the SDK, prompts and skills.");
+  } else console.log(`  Hearth didn't return the onboarding guide (${guide.status}); skipped 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}`));
 }
 
+/** Adds a downloaded file to the site's .gitignore if it isn't there (sites made before it was downloaded lack it). */
+function ignore(file) {
+  const text = existsSync(".gitignore") ? readFileSync(".gitignore", "utf8") : "";
+  if (text.split(/\r?\n/).some((l) => l.trim().replace(/^\//, "") === file)) return;
+  const gap = text && !text.endsWith("\n") ? "\n\n" : text ? "\n" : "";
+  writeFileSync(".gitignore", `${text}${gap}# Downloaded by pnpm hearth:docs for AI assistants.\n${file}\n`);
+}
+
 /** 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");
@@ -374,6 +391,14 @@ async function update() {
   }
   writeFileSync(MANIFEST, JSON.stringify({ ...next, version, ...(own.length ? { own } : {}) }, null, 2) + "\n");
 
+  // Hearth's code collapsed in pull requests, as a new site has it; the rest of .gitattributes is the site's.
+  const attributes = existsSync(".gitattributes") ? readFileSync(".gitattributes", "utf8") : "";
+  if (!attributes.split(/\r?\n/).some((l) => l.startsWith("src/hearth/**"))) {
+    const gap = attributes && !attributes.endsWith("\n") ? "\n\n" : attributes ? "\n" : "";
+    writeFileSync(".gitattributes", `${attributes}${gap}${lf(files.get("_gitattributes")?.toString("utf8") ?? "src/hearth/** linguist-generated=true\n")}`);
+    changed.push(`${attributes ? "~" : "+"} .gitattributes: src/hearth/ collapsed in pull requests`);
+  }
+
   // The packages the code needs, at least at the release's versions, and its hearth:* scripts. The site's own stay.
   const pkg = JSON.parse(readFileSync("package.json", "utf8"));
   const theirs = JSON.parse(files.get("package.json").toString("utf8"));
@@ -395,16 +420,110 @@ async function update() {
   for (const line of changed) console.log(`  ${line}`);
   console.log(`\nNext: pnpm install, then pnpm typecheck and pnpm build, and check the site with pnpm dev.`);
   console.log(`  A type error in src/theme means a slot was renamed or removed: see src/hearth/theme/defaults.ts.`);
-  console.log(`  Components replaced in src/theme/overrides.tsx are the site's own: compare them with src/hearth/blocks.`);
-  console.log(`  What changed: CHANGELOG.md in ${PACKAGE}@${version}.`);
+  console.log(`  What changed: CHANGELOG.md in ${PACKAGE}@${version}.\n`);
+  // The managed files were committed before the update (it checks), so the last commit has the old ones.
+  overridesChanged("HEAD");
+}
+
+const OVERRIDES = "src/theme/overrides.tsx";
+/** Hearth's own version of each of the other overrides: its file and component. */
+const HEARTHS = {
+  Footer: ["src/hearth/layout/SiteFooter.tsx", "SiteFooter"],
+  EventPage: ["src/hearth/components/EventView.tsx", "EventContent"],
+  FundraiserPage: ["src/hearth/components/FundraiserView.tsx", "FundraiserContent"],
+  EventCard: ["src/hearth/blocks/events.tsx", "EventCard"],
+  FundraiserCard: ["src/hearth/blocks/giving.tsx", "FundraiserCard"],
+  DonateForm: ["src/hearth/forms/DonateForm.tsx", "DonateForm"],
+};
+
+const lf = (text) => text.replace(/\r\n/g, "\n");
+
+/** A file at a git ref, from where this site is in the repo (null if it wasn't there or there's no git). */
+function atRef(ref, file) {
+  const res = spawnSync("git", ["show", `${ref}:./${file}`], { encoding: "utf8" });
+  return res.status === 0 ? lf(res.stdout) : null;
+}
+
+/** A top-level function's source, to its closing brace at the start of a line. */
+function component(source, name) {
+  const start = source?.search(new RegExp(`^(?:export )?(?:async )?function ${name}\\b`, "m")) ?? -1;
+  if (start < 0) return null;
+  const end = source.indexOf("\n}\n", start);
+  return source.slice(start, end < 0 ? undefined : end + 3);
+}
+
+/** The keys of an exported object (`export const parts = { "hero.actions": …, stats, … }`): what's at its top level. */
+function exportedKeys(source, name) {
+  const at = source.search(new RegExp(`^export const ${name}\\b[^=]*=\\s*\\{`, "m"));
+  if (at < 0) return [];
+  let depth = 0;
+  let top = "";
+  for (let i = source.indexOf("{", source.indexOf("=", at)); i < source.length; i++) {
+    const c = source[i];
+    if ("([{".includes(c)) depth++;
+    else if (")]}".includes(c) && --depth === 0) break;
+    if (depth === 1 && c !== "{") top += c;
+    else if (depth === 2 && "([{".includes(c)) top += " ";
+  }
+  // A key starts a line or the object (`stats: …` or shorthand `stats,`), or follows a comma with a colon after it.
+  // That leaves out most words in JSX text, which sits at this level too.
+  return [...top.matchAll(/(?:(?:^|\n)\s*(?:"([\w.]+)"|'([\w.]+)'|([A-Za-z_]\w*))\s*(?=[:,]|$)|,\s*(?:"([\w.]+)"|'([\w.]+)'|([A-Za-z_]\w*))\s*(?=:))/g)].map(
+    (m) => m[1] ?? m[2] ?? m[3] ?? m[4] ?? m[5] ?? m[6],
+  );
+}
+
+/**
+ * What src/theme/overrides.tsx overrides whose Hearth version changed since a git ref: the site's code adds to it or
+ * replaces it, so check each still fits. Also names parts and blocks Hearth no longer has.
+ */
+function overridesChanged(ref) {
+  if (!existsSync(OVERRIDES)) return;
+  const source = lf(readFileSync(OVERRIDES, "utf8"));
+  const map = lf(readFileSync("src/hearth/blocks/index.tsx", "utf8"));
+  const typesOf = Object.fromEntries([...map.slice(map.indexOf("export const blocks")).matchAll(/^\s+(\w+): (\w+),$/gm)].map((m) => [m[1], m[2]]));
+  const partNames = new Set([...lf(readFileSync("src/hearth/overrides.ts", "utf8")).matchAll(/^\s+"(\w+\.\w+)":/gm)].map((m) => m[1]));
+  const blockFiles = readdirSync("src/hearth/blocks").map((f) => `src/hearth/blocks/${f}`);
+  const where = (name) => blockFiles.find((f) => component(lf(readFileSync(f, "utf8")), name)) ?? "src/hearth/blocks/index.tsx";
+
+  /** [what the site overrides, Hearth's file, Hearth's component] */
+  const checks = [];
+  const gone = [];
+  for (const type of exportedKeys(source, "blocks")) {
+    if (!typesOf[type]) gone.push(`blocks.${type}`);
+    else checks.push([`blocks.${type}`, where(typesOf[type]), typesOf[type]]);
+  }
+  for (const part of exportedKeys(source, "parts")) {
+    const name = typesOf[part.split(".")[0]];
+    if (!partNames.has(part) || !name) gone.push(`parts["${part}"]`);
+    else checks.push([`parts["${part}"]`, where(name), name]);
+  }
+  for (const [name, [file, hearths]] of Object.entries(HEARTHS)) {
+    const line = source.match(new RegExp(`^export (?:const|function|async function) ${name}\\b.*$`, "m"))?.[0];
+    if (line && !/=\s*null;$/.test(line)) checks.push([name, file, hearths]);
+  }
+  if (!checks.length && !gone.length) return console.log(`✓ ${OVERRIDES} overrides nothing of Hearth's.`);
+  if (spawnSync("git", ["rev-parse", "--verify", "--quiet", ref]).status !== 0) {
+    return console.log(`Couldn't read ${ref} from git, so compare what ${OVERRIDES} overrides with src/hearth yourself.`);
+  }
+
+  const changed = checks.filter(([, file, name]) => component(atRef(ref, file), name) !== component(lf(readFileSync(file, "utf8")), name));
+  if (gone.length) console.log(`✗ Hearth has none of these any more, so ${OVERRIDES} overrides nothing with them: ${gone.join(", ")}.`);
+  if (!changed.length) return console.log(`✓ Nothing ${OVERRIDES} overrides has changed in Hearth since ${ref}.`);
+  console.log(`Changed in Hearth since ${ref}, and overridden in ${OVERRIDES}. Check each still fits (pnpm dev):`);
+  for (const [what, file, name] of changed) console.log(`  ${what}: ${name} in ${file}`);
+  console.log(`  See the changes: git diff ${ref} -- ${[...new Set(changed.map(([, file]) => file))].join(" ")}`);
 }
 
 try {
   if (command === "check") await check();
   else if (command === "docs") await docs();
   else if (command === "update") await update();
+  else if (command === "overrides") {
+    const args = process.argv.slice(3);
+    overridesChanged(args.includes("--since") ? args[args.indexOf("--since") + 1] || fail("Give a git ref after --since, e.g. --since HEAD~1.") : "HEAD");
+  }
   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]");
+  else fail("Usage: node scripts/hearth.mjs check | docs | drift | update [--version x.y.z] [--force] | overrides [--since <git ref>]");
 } catch (err) {
   if (!(err instanceof Stop)) throw err;
   console.error(`\n✗ ${err.message}\n`);

package/template/src/hearth/blocks/collections.tsx

@@ -2,33 +2,36 @@ import Link from "next/link";
 import type { BlockOf, CollectionEntry } from "@the-smithy/hearth";
 import { theme } from "@/theme";
 import { formatEntryDate } from "../format";
+import { Part } from "../parts";
 import { fill, Img, Section, SectionHeading } from "../ui";
 
 const t = theme.collectionList;
 
-function Card({ entry, heading }: { entry: CollectionEntry; heading?: string }) {
-  const Title = heading ? "h3" : "h2";
+function Card({ block, entry, index }: { block: BlockOf<"collectionList">; entry: CollectionEntry; index: number }) {
+  const Title = block.data.heading ? "h3" : "h2";
   return (
     <li className={t.card}>
-      {entry.image ? <Img image={entry.image} crop={16 / 10} className={t.image} /> : null}
-      <div className={t.body}>
-        {entry.date ? <p className={t.date}>{formatEntryDate(entry.date)}</p> : null}
-        <Title className={t.title}>
-          <Link href={entry.path} className={t.link}>
-            {entry.title}
-          </Link>
-        </Title>
-        {entry.summary ? <p className={t.summary}>{entry.summary}</p> : null}
-        {entry.tags.length ? (
-          <ul className={t.tags}>
-            {entry.tags.map((tag) => (
-              <li key={tag} className={t.tag}>
-                {tag}
-              </li>
-            ))}
-          </ul>
-        ) : null}
-      </div>
+      <Part name="collectionList.item" props={{ block, item: entry, index, heading: Title }}>
+        {entry.image ? <Img image={entry.image} crop={16 / 10} className={t.image} /> : null}
+        <div className={t.body}>
+          {entry.date ? <p className={t.date}>{formatEntryDate(entry.date)}</p> : null}
+          <Title className={t.title}>
+            <Link href={entry.path} className={t.link}>
+              {entry.title}
+            </Link>
+          </Title>
+          {entry.summary ? <p className={t.summary}>{entry.summary}</p> : null}
+          {entry.tags.length ? (
+            <ul className={t.tags}>
+              {entry.tags.map((tag) => (
+                <li key={tag} className={t.tag}>
+                  {tag}
+                </li>
+              ))}
+            </ul>
+          ) : null}
+        </div>
+      </Part>
     </li>
   );
 }
@@ -38,30 +41,34 @@ export function CollectionList({ block }: { block: BlockOf<"collectionList"> })
   const { entries, collection, layout } = block.data;
   return (
     <Section block="collectionList" id={block.anchor}>
-      <SectionHeading eyebrow={block.data.eyebrow} heading={block.data.heading} intro={block.data.intro} />
+      <Part name="collectionList.heading" props={{ block }}>
+        <SectionHeading eyebrow={block.data.eyebrow} heading={block.data.heading} intro={block.data.intro} />
+      </Part>
       {!entries.length ? (
         <p className={t.empty}>{theme.text.noEntries}</p>
       ) : layout === "list" ? (
         <ul className={t.list}>
-          {entries.map((e) => (
+          {entries.map((e, i) => (
             <li key={e.path} className={t.listItem}>
-              <Link href={e.path} className={t.listLink}>
-                {e.title}
-              </Link>
-              {e.date || e.summary ? (
-                <p className={t.listMeta}>
-                  {e.date ? <span className={t.listDate}>{formatEntryDate(e.date)}</span> : null}
-                  {e.date && e.summary ? " · " : null}
-                  {e.summary}
-                </p>
-              ) : null}
+              <Part name="collectionList.item" props={{ block, item: e, index: i, heading: block.data.heading ? "h3" : "h2" }}>
+                <Link href={e.path} className={t.listLink}>
+                  {e.title}
+                </Link>
+                {e.date || e.summary ? (
+                  <p className={t.listMeta}>
+                    {e.date ? <span className={t.listDate}>{formatEntryDate(e.date)}</span> : null}
+                    {e.date && e.summary ? " · " : null}
+                    {e.summary}
+                  </p>
+                ) : null}
+              </Part>
             </li>
           ))}
         </ul>
       ) : (
         <ul className={t.cards}>
-          {entries.map((e) => (
-            <Card key={e.path} entry={e} heading={block.data.heading} />
+          {entries.map((e, i) => (
+            <Card key={e.path} block={block} entry={e} index={i} />
           ))}
         </ul>
       )}