@the-smithy/create-hearth-site 0.24.0 → 0.25.0

package/package.json

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

package/template/AGENTS.md

@@ -8,6 +8,10 @@ replaced by `pnpm hearth:update`, so never edit it. A site is styled in `src/the
 Tailwind classes of each element's slot in `index.ts` (every slot and its default is in
 `src/hearth/theme/defaults.ts`).
 
+At the start of every piece of work, run `pnpm hearth:check`: it says whether The Smithy has released anything newer
+than this site uses, and `pnpm hearth:update` brings Hearth's code up to date (see "Staying on the template and up to
+date" in `CLAUDE.md`).
+
 In a new checkout, run `pnpm hearth:check`, then `pnpm hearth:docs`. The latter also installs the skills Hearth
 offers this site in `.claude/skills/`. Read the `SKILL.md` of any that fits your task and follow it (see "Skills" in
 `CLAUDE.md`).

package/template/CLAUDE.md

@@ -51,29 +51,91 @@ Work in this order, and stop at the first step that gets the result:
      `data-highlight:`, `aria-invalid:`, `aria-[current=page]:`, `has-checked:`, `in-data-[…]:` and others; the top
      of `defaults.ts` lists them and each slot's comment says which apply.
    - Slots named `tone` pick a block's ground (default, muted, inverse or accent). `text` holds the words the code
-     shows ("Get directions", "Register"…). `map.style` is the map's MapLibre style; `emberForm` shapes Ember forms.
-   - Icons and marks drawn with CSS (`before:content-['✓']`, the FAQ's `+`, link arrows) live in slots too.
+     shows ("Get directions", "Register"…), with `{name}` for what the code fills in. `map.style` is the map's MapLibre
+     style; `emberForm` shapes Ember forms. A few slots in `page` are settings: `themeColor` (the browser's color around
+     the page), `externalLinks` ("new-tab"), `navMatch` ("exact" for menu links) and `dateStyle` ("long" for event dates).
+   - Icons and marks drawn with CSS (`before:content-['✓']`, the FAQ's `+`, link arrows) live in slots too. A card's
+     Icon in Hearth arrives as `data-icon="graduation-cap"`, for the site's CSS to draw.
 4. **Site CSS** under the tokens in `theme.css`: keyframes, background patterns, `@utility` classes your slots use,
-   and rules for Hearth's rich text (`.prose`) or a block (`[data-block="hero"]`).
-5. **Overrides**, last: `src/theme/overrides.tsx` can replace a whole block's component or draw the header's logo.
-   An override is the site's own code: updates don't reach it, so it falls behind Hearth. Use one only when slots,
-   tokens and CSS can't get there, build it from `src/hearth/ui.tsx` and the theme, and say why in `SITE.md`.
+   and rules for Hearth's rich text (`.prose`), a block (`[data-block="hero"]`), a page the code serves
+   (`[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
+   `src/hearth/ui.tsx` and the theme, and say why in `SITE.md`.
 
 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.
 
+### Pages at the code's addresses
+
+`/events`, `/fundraisers`, `/donate`, `/donate/thank-you`, `/registered` and the 404 are served by Hearth's code, with
+default words. A published page in Hearth at that address (`events`, `donate/thank-you`, `not-found` for the 404…)
+replaces those words: its blocks, its SEO and its structured data. **So a page's text never needs its own route or an
+override: make the page in Hearth.** `/events` and the fundraiser and donation addresses still need the site's Events
+or Giving feature. The site's `reserved_slugs` in Hearth mustn't list these, since that refuses the page.
+
+The thank-you pages and the 404 are never indexable and never in the sitemap or llms.txt. The 404 always answers 404,
+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:
+
+| Export | Replaces | 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 }` |
+| `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 |
+| `DonateForm` | The donation form | The amounts, `fundraiser`, `fundraisers` (active ones to choose from) and `submitLabel` |
+
+`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
+a fundraiser's page.
+
+`own` in the manifest (managed files `pnpm hearth:update` leaves alone) is for a site inside an app, with its own root
+layout, not for keeping a page: it stops that file getting fixes. Such a site imports `src/hearth/hearth.css` alone in
+its own CSS, and `src/hearth/base.css` if it wants Hearth's rich text and focus rings.
+
 **Custom blocks** (Settings → Custom blocks in Hearth) are the one place a site writes components: in
 `src/theme/custom-blocks.tsx`, built from `src/hearth/ui.tsx` so they take the theme.
 
+## Staying on the template and up to date
+
+Every site Hearth runs has the same code, so a fix or a new block reaches them all at once. That only holds while
+each site stays on the template and on current releases:
+
+- **Check for new releases from The Smithy at the start of every piece of work.** `pnpm hearth:check` lists every
+  `@the-smithy/*` package and Hearth's code in this site with a newer release on npm, even with no API key. Tell the
+  developer what it found.
+- **Update before you build on old code.** `pnpm hearth:update` brings Hearth's code and SDK to the latest release;
+  `pnpm add @the-smithy/<name>@latest` does any other Smithy package, such as the Ember SDK. Read the package's
+  `CHANGELOG.md`, run the checks below, look at the site, and commit the update on its own, with
+  `pnpm-workspace.yaml` if pnpm added the new versions to it.
+- **Don't drift.** A design change goes in `src/theme/`. Don't copy a component out of `src/hearth/`, replace a route
+  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.
+
 ## First steps in a new checkout
 
 Do these before writing code, and tell the developer what you found:
 
-1. **Check the setup:** `pnpm hearth:check`. It reads `.env.local`, connects to Hearth, lists the published
-   pages and the block types they use, and flags types with no component. It never prints the API key; you
-   shouldn't either, so don't open `.env.local` to read the key or echo 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.
+1. **Check the setup:** `pnpm hearth:check`. It reports any newer releases from The Smithy (see above), reads
+   `.env.local`, connects to Hearth, lists the published pages and the block types they use, and flags types with no
+   component. It never prints the API key; you shouldn't either, so don't open `.env.local` to read the key or echo
+   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
    `node_modules/@the-smithy/hearth/llms.md` for the SDK. It also installs any skills Hearth offers this site in

package/template/README.md

@@ -76,7 +76,10 @@ Keep the API key out of chat: the agent never needs to see it, only `.env.local`
   and the page's language all come from Hearth (`siteMetadata`, `generatePageMetadata`, `sitemapWith`, `robots`,
   `llmsTxtHandler`, `redirectOrNotFound`). Preview deploys
   and sites hidden in Hearth are kept out of search engines. What's still yours:
-  - Pages your own code serves (like `/events`) need their own `generateMetadata` and a place in `src/app/sitemap.ts`.
+  - `/events`, `/fundraisers`, `/donate`, `/donate/thank-you`, `/registered` and the 404 are served by Hearth's code. A page
+    in Hearth at that address (`not-found` for the 404) replaces their words, SEO and all, so make one there rather than
+    a page in code.
+  - Other pages your own code serves need their own `generateMetadata` and a place in `src/app/sitemap.ts`.
   - Use `<Img priority>` for the image at the top of a page, and keep one `<h1>` per page (the Hero block renders it).
   - Give `<Img>` the `crop` of an image that fills a frame (`crop={4 / 3}` for `aspect-[4/3] object-cover`) so it keeps
     the focal point set in Hearth's media library in view.
@@ -92,7 +95,7 @@ Keep the API key out of chat: the agent never needs to see it, only `.env.local`
 | `src/hearth/theme/defaults.ts` | Every slot and its default classes: read it to find the slot to change |
 | `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, or draw the logo |
+| `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 `CLAUDE.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,
@@ -107,7 +110,10 @@ export const theme = defineTheme({
 ```
 
 States are Tailwind variants inside the slot: `on-dark:` for blocks on an inverse or accent ground,
-`data-[size=full]:`, `aria-invalid:` and so on (listed at the top of `defaults.ts`).
+`data-[size=full]:`, `aria-invalid:` and so on (listed at the top of `defaults.ts`). Words the code shows are slots under
+`text`, and `page` holds some settings: `themeColor`, `externalLinks`, `navMatch` and `dateStyle`.
+
+Editors can name any block in Hearth ("Link to this block"), so a link such as `/#upcoming` jumps to it.
 
 ### Where things live
 
@@ -175,7 +181,15 @@ with a Markdown version to give an AI coding assistant. The SDK also ships `node
 
 ## Updating
 
+**Check for new releases whenever you start work on the site:** `pnpm hearth:check` lists anything from The Smithy
+with a newer release, and works without an API key.
+
 `pnpm hearth:update` updates Hearth's code in the site (`src/hearth/` and the other files `src/hearth/manifest.json`
 lists) to the latest release, with the packages it needs. Your `src/theme/` and your own files aren't touched. Then
 `pnpm install`, `pnpm typecheck`, `pnpm build`, and a look at the site. New blocks arrive styled by the defaults and
-your tokens; give them slots in the theme if the design needs it.
+your tokens; give them slots in the theme if the design needs it. Update other Smithy packages, such as the Ember SDK,
+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`.

package/template/package.json

@@ -13,13 +13,14 @@
     "hearth:update": "node scripts/hearth.mjs update"
   },
   "dependencies": {
-    "@the-smithy/ember": "^0.3.1",
+    "@the-smithy/ember": "^0.5.0",
     "@the-smithy/hearth": "workspace:^",
     "maplibre-gl": "^6.16.0",
     "next": "16.3.8",
     "react": "19.2.8",
     "react-dom": "19.2.8",
-    "react-markdown": "^10.1.0"
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4",

package/template/scripts/hearth.mjs

@@ -1,5 +1,6 @@
 // Setup helpers for this site, for you or your coding agent. Both read .env.local and never print the API key.
-//   pnpm hearth:check   checks .env.local and the connection to Hearth, then lists what's published
+//   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 in .claude/skills/
 //   pnpm hearth:update  updates Hearth's code in this site (src/hearth and the other files its manifest lists) to the
@@ -16,6 +17,11 @@ const fail = (message) => {
   throw new Stop(message);
 };
 
+const PACKAGE = "@the-smithy/create-hearth-site";
+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"];
+
 /** The SDK, loaded only by the commands that talk to Hearth (so hearth:update works before pnpm install). */
 const sdk = () => import("@the-smithy/hearth");
 
@@ -45,7 +51,49 @@ function designedBlocks() {
   return found.length ? new Set(found) : null;
 }
 
+/** The latest release of a package on npm, or null if npm can't be reached. */
+async function latestRelease(name) {
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${name.replace("/", "%2f")}`, { headers: { Accept: "application/vnd.npm.install-v1+json" } });
+    return res.ok ? (await res.json())["dist-tags"]?.latest ?? null : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Says which of The Smithy's packages have a newer release. Needs no API key, so it runs before anything else in hearth:check. */
+async function checkReleases() {
+  const pkg = JSON.parse(readFileSync("package.json", "utf8"));
+  const installed = (name, range) => {
+    const file = path.join("node_modules", ...name.split("/"), "package.json");
+    return existsSync(file) ? JSON.parse(readFileSync(file, "utf8")).version : range;
+  };
+  const used = Object.entries({ ...pkg.dependencies, ...pkg.devDependencies })
+    .filter(([name, range]) => name.startsWith("@the-smithy/") && !String(range).startsWith("workspace:"))
+    .map(([name, range]) => ({ name, have: installed(name, range) }));
+  if (existsSync(MANIFEST)) used.unshift({ name: PACKAGE, have: JSON.parse(readFileSync(MANIFEST, "utf8")).version });
+
+  const behind = [];
+  let unknown = 0;
+  await Promise.all(
+    used.map(async ({ name, have }) => {
+      const latest = await latestRelease(name);
+      if (!latest) unknown++;
+      else if (lower(have, latest)) behind.push({ name, have, latest });
+    }),
+  );
+  if (unknown) console.log(`! Couldn't check ${unknown} of The Smithy's packages on npm, so there may be newer releases than this lists.`);
+  if (!behind.length) return console.log(`✓ On the latest releases of The Smithy's packages (${used.map((u) => `${u.name.replace("@the-smithy/", "")} ${u.have}`).join(", ")})`);
+  console.log(`! The Smithy has released updates for this site:`);
+  for (const { name, have, latest } of behind) console.log(`  ${name} ${have} → ${latest}`);
+  const others = behind.filter((b) => !UPDATED_TOGETHER.includes(b.name)).map((b) => `${b.name}@latest`);
+  if (others.length < behind.length) console.log(`  Run pnpm hearth:update for Hearth's code and SDK.`);
+  if (others.length) console.log(`  Run pnpm add ${others.join(" ")} for the rest, and read their changelogs.`);
+}
+
 async function check() {
+  await checkReleases();
+  console.log();
   const env = await readEnv();
   const { createHearthClient, isHearthError } = await sdk();
   const hearth = createHearthClient(env);
@@ -135,8 +183,6 @@ async function skills(env) {
   if (names.length) console.log(`✓ Installed ${names.length === 1 ? "a skill" : `${names.length} skills`} for your coding assistant in .claude/skills/: ${names.join(", ")}.`);
 }
 
-const PACKAGE = "@the-smithy/create-hearth-site";
-const MANIFEST = "src/hearth/manifest.json";
 
 /** The files in an npm package tarball (.tgz), by their path inside it ("package/…"). */
 function untar(tgz) {
@@ -183,7 +229,8 @@ const lower = (a, b) => {
  * Updates the code Hearth manages in this site to the latest release (or --version x.y.z): replaces the managed files
  * listed in src/hearth/manifest.json, removes managed files the release dropped, adds seeded files that are new to
  * it (never overwriting the site's), and raises the packages the code needs. src/theme and the site's own files
- * aren't touched.
+ * aren't touched, nor are managed files the site's manifest lists under `own` (a site inside an app keeps its own root
+ * layout and route files, for example).
  */
 async function update() {
   const args = process.argv.slice(3);
@@ -192,9 +239,10 @@ async function update() {
   if (!wanted) fail("Give a version after --version, e.g. --version 0.21.0.");
   if (!existsSync(MANIFEST)) fail(`There's no ${MANIFEST}, so this site predates hearth:update. Move it onto the template's structure first (see CLAUDE.md).`);
   const old = JSON.parse(readFileSync(MANIFEST, "utf8"));
+  const own = old.own ?? [];
 
   // Managed files edited here would be lost: styling belongs in src/theme.
-  const git = spawnSync("git", ["status", "--porcelain", "--", ...old.managed], { encoding: "utf8" });
+  const git = spawnSync("git", ["status", "--porcelain", "--", ...old.managed.filter((entry) => !own.includes(entry))], { encoding: "utf8" });
   if (git.status === 0 && git.stdout.trim() && !force) {
     fail(`These managed files have uncommitted changes, which the update would replace:\n${git.stdout.trimEnd()}\nCommit them first (and move any styling into src/theme), or run with --force to replace them.`);
   }
@@ -225,12 +273,12 @@ async function update() {
   const changed = [];
   // Managed files the release no longer has.
   for (const file of old.managed.flatMap(localFiles)) {
-    if (files.has(file) || file === MANIFEST) continue;
+    if (files.has(file) || file === MANIFEST || listed(own, file)) continue;
     rmSync(file);
     changed.push(`- ${file}`);
   }
   for (const [file, body] of files) {
-    if (file === MANIFEST) continue;
+    if (file === MANIFEST || listed(own, file)) continue;
     const managed = listed(next.managed, file);
     // Seeded files are the site's own: add only ones that are new to this release's list, and never over a file.
     const newSeed = !managed && listed(next.seeded, file) && !listed(old.seeded ?? [], file) && !existsSync(file);
@@ -241,7 +289,7 @@ async function update() {
     writeFileSync(file, body);
     changed.push(`${existed ? "~" : "+"} ${file}`);
   }
-  writeFileSync(MANIFEST, JSON.stringify({ ...next, version }, null, 2) + "\n");
+  writeFileSync(MANIFEST, JSON.stringify({ ...next, version, ...(own.length ? { own } : {}) }, null, 2) + "\n");
 
   // 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"));

package/template/src/app/donate/thank-you/page.tsx

@@ -1,2 +1,2 @@
 // Managed by Hearth (pnpm hearth:update replaces it). Style it in src/theme; the page is src/hearth/pages/thank-you.tsx.
-export { default, metadata } from "@/hearth/pages/thank-you";
+export { default, generateMetadata } from "@/hearth/pages/thank-you";

package/template/src/app/globals.css

@@ -1,4 +1,5 @@
 /* Managed by Hearth (pnpm hearth:update replaces it). The site's tokens and CSS go in src/theme/theme.css. */
 @import "tailwindcss";
 @import "../hearth/hearth.css";
+@import "../hearth/base.css";
 @import "../theme/theme.css";

package/template/src/app/layout.tsx

@@ -1,4 +1,4 @@
 // Managed by Hearth (pnpm hearth:update replaces it): the layout is src/hearth/layout/RootLayout.tsx, styled in src/theme.
 import "./globals.css";
 
-export { default, generateMetadata } from "@/hearth/layout/RootLayout";
+export { default, generateMetadata, viewport } from "@/hearth/layout/RootLayout";

package/template/src/app/not-found.tsx

@@ -1,2 +1,2 @@
 // Managed by Hearth (pnpm hearth:update replaces it). Style it in src/theme; the page is src/hearth/pages/not-found.tsx.
-export { default } from "@/hearth/pages/not-found";
+export { default, generateMetadata } from "@/hearth/pages/not-found";

package/template/src/app/registered/page.tsx

@@ -1,2 +1,2 @@
 // Managed by Hearth (pnpm hearth:update replaces it). Style it in src/theme; the page is src/hearth/pages/registered.tsx.
-export { default, metadata } from "@/hearth/pages/registered";
+export { default, generateMetadata } from "@/hearth/pages/registered";

package/template/src/hearth/base.css

@@ -0,0 +1,66 @@
+/*
+ * Hearth's rich text and focus rings, shared by every site: src/app/globals.css loads it. Don't edit it in a site: the
+ * site's own CSS goes in src/theme/theme.css, which is loaded after this file and can override anything here.
+ */
+
+/* Markdown from Hearth (rich text, FAQ answers, media + text). Unlayered, so its line height beats text-* sizes. */
+.prose {
+  line-height: 1.7;
+}
+.prose > * + * {
+  margin-top: 1em;
+}
+.prose h2 {
+  font-size: 1.75rem;
+  font-weight: 700;
+  line-height: 1.25;
+  margin-top: 1.6em;
+}
+.prose h3 {
+  font-size: 1.35rem;
+  font-weight: 700;
+  margin-top: 1.4em;
+}
+.prose a {
+  text-decoration: underline;
+  text-underline-offset: 3px;
+}
+.prose ul {
+  list-style: disc;
+  padding-left: 1.4em;
+}
+.prose ol {
+  list-style: decimal;
+  padding-left: 1.4em;
+}
+.prose blockquote {
+  border-left: 3px solid var(--color-line);
+  padding-left: 1em;
+  font-style: italic;
+}
+.prose img {
+  border-radius: 0.75rem;
+}
+/* A wide table scrolls inside the text rather than widening the page. */
+.prose table {
+  display: block;
+  max-width: 100%;
+  overflow-x: auto;
+  border-collapse: collapse;
+}
+.prose th,
+.prose td {
+  border-bottom: 1px solid var(--color-line);
+  padding: 0.5em 1em 0.5em 0;
+  text-align: left;
+  vertical-align: top;
+}
+.prose th {
+  font-weight: 700;
+}
+
+/* Unlayered, so it beats utilities like focus:outline-none: keyboard focus always shows. */
+:focus-visible {
+  outline: 2px solid var(--color-accent);
+  outline-offset: 2px;
+}

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

@@ -6,17 +6,18 @@ import { fill, Img, Section, SectionHeading } from "../ui";
 
 const t = theme.collectionList;
 
-function Card({ entry }: { entry: CollectionEntry }) {
+function Card({ entry, heading }: { entry: CollectionEntry; heading?: string }) {
+  const Title = 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}
-        <h3 className={t.title}>
+        <Title className={t.title}>
           <Link href={entry.path} className={t.link}>
             {entry.title}
           </Link>
-        </h3>
+        </Title>
         {entry.summary ? <p className={t.summary}>{entry.summary}</p> : null}
         {entry.tags.length ? (
           <ul className={t.tags}>
@@ -36,7 +37,7 @@ function Card({ entry }: { entry: CollectionEntry }) {
 export function CollectionList({ block }: { block: BlockOf<"collectionList"> }) {
   const { entries, collection, layout } = block.data;
   return (
-    <Section block="collectionList">
+    <Section block="collectionList" id={block.anchor}>
       <SectionHeading eyebrow={block.data.eyebrow} heading={block.data.heading} intro={block.data.intro} />
       {!entries.length ? (
         <p className={t.empty}>{theme.text.noEntries}</p>
@@ -60,7 +61,7 @@ export function CollectionList({ block }: { block: BlockOf<"collectionList"> })
       ) : (
         <ul className={t.cards}>
           {entries.map((e) => (
-            <Card key={e.path} entry={e} />
+            <Card key={e.path} entry={e} heading={block.data.heading} />
           ))}
         </ul>
       )}