@the-smithy/create-hearth-site 0.19.0 → 0.20.0

package/package.json

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

package/template/AGENTS.md

@@ -2,3 +2,6 @@
 
 Read `CLAUDE.md` in this folder: it holds this project's instructions for every AI coding assistant, including
 the first steps to run in a new checkout (`pnpm hearth:check`, then `pnpm hearth:docs`).
+
+`pnpm hearth:docs` 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

@@ -13,12 +13,21 @@ Do these before writing code, and tell the developer what you found:
    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.
+   `node_modules/@the-smithy/hearth/llms.md` for the SDK. It also installs any skills Hearth offers this site in
+   `.claude/skills/` (see "Skills" below), so run it again when they're missing.
 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 build the design** in `src/app/globals.css` (tokens) and `src/components/blocks/` (one component per
    block type), checking with `pnpm dev` against the published pages.
 
+## Skills
+
+`pnpm hearth:docs` installs the skills Hearth offers this site in `.claude/skills/` (which ones depends on the
+site). Each `SKILL.md` says what it's for and when to use it. Claude Code loads them by itself; other assistants
+should read the ones that fit the task and follow them. Use them for that work, design work in particular, rather
+than starting from scratch. They aren't committed (`.claude/skills/.gitignore` lists them), so a fresh checkout gets
+them by running `pnpm hearth:docs`; never edit them, because the next run replaces them.
+
 ## Rules
 
 - **Content comes from Hearth.** Don't hard-code page text, menus, contact details or SEO tags. They're edited

package/template/README.md

@@ -42,7 +42,8 @@ The project comes with instructions for coding agents (`CLAUDE.md`, which Claude
 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). The agent's instructions already point it there.
+   committed), and installs any coding-assistant skills Hearth offers your site in `.claude/skills/`. The agent's
+   instructions already point it at both.
 3. **Then tell it what to build.** Prompts that work well:
 
    - *"Run the first steps in CLAUDE.md and tell me what's published and which blocks the site uses."*
@@ -73,6 +74,8 @@ Keep the API key out of chat: the agent never needs to see it, only `.env.local`
   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`.
   - 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.
   - Add both the bare domain and `www` to the site in Netlify, with the one Hearth uses as primary: Netlify then
     redirects the other to it.
 

package/template/package.json

@@ -14,6 +14,7 @@
   "dependencies": {
     "@the-smithy/ember": "^0.3.1",
     "@the-smithy/hearth": "workspace:^",
+    "maplibre-gl": "^6.16.0",
     "next": "16.3.8",
     "react": "19.2.8",
     "react-dom": "19.2.8",

package/template/scripts/hearth.mjs

@@ -1,7 +1,9 @@
 // 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:docs    saves Hearth's full API guide to hearth-api.md (not committed) for an AI assistant to read
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+//   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/
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
 import { createHearthClient, DEFAULT_BASE_URL, isHearthError } from "@the-smithy/hearth";
 
 const command = process.argv[2];
@@ -87,6 +89,40 @@ 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.");
+  await skills(env);
+}
+
+/**
+ * Installs the coding-assistant skills Hearth offers this site into .claude/skills/, replacing the ones it
+ * installed before. Their names are listed in .claude/skills/.gitignore, so they're never committed and the
+ * site's own skills there are left alone.
+ */
+async function skills(env) {
+  const res = await fetch(`${env.baseUrl}/admin/docs/skills.json`, { headers: { Authorization: `Bearer ${env.apiKey}` } });
+  if (!res.ok) return console.log(`  Hearth didn't return the coding-assistant skills (${res.status}); skipped them.`);
+  const { skills: offered = [] } = await res.json();
+  const dir = path.join(".claude", "skills");
+  const listFile = path.join(dir, ".gitignore");
+  const before = existsSync(listFile)
+    ? readFileSync(listFile, "utf8").split(/\r?\n/).map((l) => l.replace(/^\/|\/$/g, "")).filter((l) => l && !l.startsWith("#") && l !== ".gitignore")
+    : [];
+  const safe = (p) => /^[a-z0-9][a-z0-9-]*$/.test(p);
+  const names = offered.map((s) => s.name).filter(safe);
+  for (const name of before) if (safe(name) && !names.includes(name)) rmSync(path.join(dir, name), { recursive: true, force: true });
+  for (const skill of offered.filter((s) => safe(s.name))) {
+    rmSync(path.join(dir, skill.name), { recursive: true, force: true });
+    for (const file of skill.files) {
+      if (!file.path.split("/").every((part) => /^[A-Za-z0-9._-]+$/.test(part) && part !== "..")) continue;
+      const target = path.join(dir, skill.name, ...file.path.split("/"));
+      mkdirSync(path.dirname(target), { recursive: true });
+      writeFileSync(target, file.content);
+    }
+  }
+  if (names.length || before.length) {
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(listFile, ["# Installed by pnpm hearth:docs from Hearth; refreshed each run.", ".gitignore", ...names.map((n) => `/${n}/`)].join("\n") + "\n");
+  }
+  if (names.length) console.log(`✓ Installed ${names.length === 1 ? "a skill" : `${names.length} skills`} for your coding assistant in .claude/skills/: ${names.join(", ")}.`);
 }
 
 try {

package/template/src/app/actions.ts

@@ -41,3 +41,17 @@ export async function donate(prev: FormResult | null, formData: FormData): Promi
 export async function register(slug: string, prev: FormResult | null, formData: FormData): Promise<FormResult> {
   return hearthNext.registerAction(slug, { returnPath: "/registered" })(prev, formData);
 }
+
+/**
+ * Signs up to volunteer at an event that asks for volunteers. Sign-ups land under the event's Volunteers in Hearth,
+ * which also emails the site's alert addresses.
+ */
+export async function volunteer(slug: string, prev: VolunteerState | null, formData: FormData): Promise<VolunteerState> {
+  const result = await hearthNext.volunteerAction(slug)(prev, formData);
+  if (result.ok) return result;
+  // Hand back what they typed and chose, so the form keeps it after an error.
+  const values = Object.fromEntries([...formData.entries()].filter(([k, v]) => typeof v === "string" && !k.startsWith("$") && k !== "_gotcha" && k !== "shift")) as Record<string, string>;
+  return { ...result, values, shifts: formData.getAll("shift").map(String) };
+}
+
+export type VolunteerState = FormResult & { values?: Record<string, string>; shifts?: string[] };

package/template/src/app/fundraisers/[slug]/page.tsx

@@ -38,7 +38,7 @@ export default async function FundraiserPage({ params }: Props) {
             {f.summary ? <p className="text-lg opacity-85">{f.summary}</p> : null}
             <Progress fundraiser={f} large />
           </div>
-          {f.image ? <Img image={f.image} className="aspect-[4/3] w-full rounded-xl object-cover" /> : null}
+          {f.image ? <Img image={f.image} crop={4 / 3} className="aspect-[4/3] w-full rounded-xl object-cover" /> : null}
         </div>
       </section>
       <Blocks blocks={f.blocks} />

package/template/src/app/globals.css

@@ -8,7 +8,10 @@
   --color-bg: #fbfaf7;
   --color-ink: #1c1c1a;
   --color-muted-ink: #5b5b55;
+  /* Dividers and card edges: decorative, so they can be faint. */
   --color-line: #e3e0d8;
+  /* Form field and option borders: the border is how people see the field, so it needs 3:1 on surface, bg and muted. */
+  --color-field: #8a867e;
   --color-surface: #ffffff;
   --color-muted: #f1eee7;
   --color-inverse: #1c1c1a;

package/template/src/components/DonateForm.tsx

@@ -5,7 +5,7 @@ import { useFormStatus } from "react-dom";
 import type { FormResult } from "@the-smithy/hearth";
 import { donate } from "@/app/actions";
 
-const input = "block w-full rounded-lg border border-line bg-surface px-4 py-3 text-base text-ink focus:border-accent focus:outline-none";
+const input = "block w-full rounded-lg border border-field bg-surface px-4 py-3 text-base text-ink focus:border-accent focus:outline-none";
 const money = (cents: number) => (cents / 100).toLocaleString("en-US", { style: "currency", currency: "USD", maximumFractionDigits: cents % 100 ? 2 : 0 });
 
 function Submit({ label }: { label: string }) {
@@ -50,12 +50,12 @@ export function DonateForm({
         <legend className="mb-3 font-semibold">Amount</legend>
         <div className="flex flex-wrap gap-3">
           {presetsCents.map((cents) => (
-            <label key={cents} className="cursor-pointer rounded-lg px-5 py-3 font-semibold ring-1 ring-line has-checked:bg-accent has-checked:text-accent-ink has-checked:ring-accent">
+            <label key={cents} className="cursor-pointer rounded-lg px-5 py-3 font-semibold ring-1 ring-field has-checked:bg-accent has-checked:text-accent-ink has-checked:ring-accent">
               <input type="radio" name="amount" value={cents / 100} checked={amount === String(cents / 100)} onChange={(e) => setAmount(e.target.value)} className="sr-only" />
               {money(cents)}
             </label>
           ))}
-          <label className="cursor-pointer rounded-lg px-5 py-3 font-semibold ring-1 ring-line has-checked:bg-accent has-checked:text-accent-ink has-checked:ring-accent">
+          <label className="cursor-pointer rounded-lg px-5 py-3 font-semibold ring-1 ring-field has-checked:bg-accent has-checked:text-accent-ink has-checked:ring-accent">
             <input type="radio" name="amount" value="custom" checked={amount === "custom"} onChange={(e) => setAmount(e.target.value)} className="sr-only" />
             Other
           </label>

package/template/src/components/EventView.tsx

@@ -1,39 +1,86 @@
-import type { HearthEventDetail } from "@the-smithy/hearth";
+import type { BlockOf, HearthEventDetail } from "@the-smithy/hearth";
 import { JsonLd } from "@the-smithy/hearth/react";
 import { Blocks } from "@/components/blocks";
-import { formatEventDate } from "@/components/blocks/events";
+import { Hero } from "@/components/blocks/content";
+import { formatEventDate, volunteerAnchor } from "@/components/blocks/events";
 import { Registration } from "@/components/Registration";
 import { RegistrationForm } from "@/components/RegistrationForm";
+import { VolunteerForm } from "@/components/VolunteerForm";
 import { Img } from "@/components/ui";
 
-/** An event's page: header with date, place and registration, then its blocks. Used at /events/… and /<collection>/…. */
+/**
+ * An event's page: header with date, place and registration, then its blocks. Used at /events/… and /<collection>/….
+ * When the event's blocks start with a hero, the hero is the header (its heading is the page's only h1, the event's
+ * name its eyebrow, the event's image its picture if it has none) and the details sit in a band under it.
+ * Volunteer sign-up goes at the bottom, unless a Volunteer sign-up block for the event is placed on the page.
+ */
 export function EventView({ event }: { event: HearthEventDetail }) {
   const { location } = event;
+  const [first, ...rest] = event.blocks;
+  const hero = first?.type === "hero" ? (first as BlockOf<"hero">) : null;
+  // A Volunteer sign-up block for this event puts the form where the editor placed it, instead of at the bottom.
+  const volunteerBlock = event.blocks.some((b) => b.type === "volunteerSignup" && (b as BlockOf<"volunteerSignup">).data.event.slug === event.slug);
+
+  const cancelled = event.status === "cancelled" ? <p className="w-fit rounded bg-danger px-2 py-1 text-sm font-semibold text-white">This event is cancelled</p> : null;
+  const when = (
+    <p className="text-lg font-semibold text-highlight">
+      <time dateTime={event.startsAt}>{formatEventDate(event)}</time>
+    </p>
+  );
+  const where =
+    location.name || location.address ? (
+      <p>
+        {location.name ? <span className="block font-semibold">{location.name}</span> : null}
+        {location.address ? <span className="block opacity-80">{location.address}</span> : null}
+      </p>
+    ) : null;
+  const summary = event.summary ? <p className="text-lg opacity-85">{event.summary}</p> : null;
+  const actions = (
+    <div className="flex flex-wrap items-center gap-3">
+      <Registration event={event} />
+      {event.volunteering?.open ? (
+        <a href={volunteerBlock ? `#${volunteerAnchor(event.slug)}` : "#volunteer"} className="w-fit rounded-lg px-6 py-3.5 font-semibold ring-2 ring-current hover:opacity-80">
+          Volunteer
+        </a>
+      ) : null}
+    </div>
+  );
+
   return (
     <>
       <JsonLd data={event.meta.jsonLd} />
-      <section className="bg-muted">
-        <div className="mx-auto grid max-w-site items-center gap-10 px-4 py-16 sm:px-6 md:grid-cols-2">
-          <div className="flex flex-col gap-4">
-            {event.collection ? <p className="text-sm font-semibold uppercase tracking-[0.18em] opacity-75">{event.collection.name}</p> : null}
-            {event.status === "cancelled" ? <p className="w-fit rounded bg-danger px-2 py-1 text-sm font-semibold text-white">This event is cancelled</p> : null}
-            <h1 className="text-[clamp(32px,4.4vw,52px)] font-bold leading-tight tracking-tight">{event.title}</h1>
-            <p className="text-lg font-semibold text-highlight">
-              <time dateTime={event.startsAt}>{formatEventDate(event)}</time>
-            </p>
-            {location.name || location.address ? (
-              <p>
-                {location.name ? <span className="block font-semibold">{location.name}</span> : null}
-                {location.address ? <span className="block opacity-80">{location.address}</span> : null}
-              </p>
-            ) : null}
-            {event.summary ? <p className="text-lg opacity-85">{event.summary}</p> : null}
-            <Registration event={event} />
+      {hero ? (
+        <>
+          <Hero block={{ ...hero, data: { ...hero.data, eyebrow: hero.data.eyebrow ?? event.title, image: hero.data.image ?? event.image ?? undefined } }} />
+          <section className="bg-muted">
+            <div className="mx-auto flex max-w-site flex-wrap items-center justify-between gap-6 px-4 py-8 sm:px-6">
+              <div className="flex flex-col gap-2">
+                {cancelled}
+                {when}
+                {where}
+                {hero.data.body ? null : summary}
+              </div>
+              {actions}
+            </div>
+          </section>
+        </>
+      ) : (
+        <section className="bg-muted">
+          <div className="mx-auto grid max-w-site items-center gap-10 px-4 py-16 sm:px-6 md:grid-cols-2">
+            <div className="flex flex-col gap-4">
+              {event.collection ? <p className="text-sm font-semibold uppercase tracking-[0.18em] opacity-75">{event.collection.name}</p> : null}
+              {cancelled}
+              <h1 className="text-[clamp(32px,4.4vw,52px)] font-bold leading-tight tracking-tight">{event.title}</h1>
+              {when}
+              {where}
+              {summary}
+              {actions}
+            </div>
+            {event.image ? <Img image={event.image} crop={4 / 3} className="aspect-[4/3] w-full rounded-xl object-cover" /> : null}
           </div>
-          {event.image ? <Img image={event.image} className="aspect-[4/3] w-full rounded-xl object-cover" /> : null}
-        </div>
-      </section>
-      <Blocks blocks={event.blocks} />
+        </section>
+      )}
+      <Blocks blocks={hero ? rest : event.blocks} />
       {event.registration?.open ? (
         <section id="register" className="mx-auto max-w-site scroll-mt-8 px-4 py-16 sm:px-6">
           <div className="max-w-2xl">
@@ -43,6 +90,18 @@ export function EventView({ event }: { event: HearthEventDetail }) {
           </div>
         </section>
       ) : null}
+      {event.volunteering?.open && !volunteerBlock ? (
+        <section id="volunteer" className="mx-auto max-w-site scroll-mt-8 px-4 py-16 sm:px-6">
+          <div className="max-w-2xl">
+            <h2 className="mb-2 text-2xl font-bold">Volunteer</h2>
+            {event.volunteering.intro ? <p className="mb-2 whitespace-pre-line opacity-85">{event.volunteering.intro}</p> : null}
+            {event.volunteering.fundraiser ? <p className="mb-2 opacity-80">This event supports {event.volunteering.fundraiser.title}.</p> : null}
+            <div className="mt-6">
+              <VolunteerForm slug={event.slug} timezone={event.timezone} volunteering={event.volunteering} />
+            </div>
+          </div>
+        </section>
+      ) : null}
     </>
   );
 }

package/template/src/components/RegistrationForm.tsx

@@ -5,7 +5,7 @@ import { useFormStatus } from "react-dom";
 import type { EventTicket, FormResult } from "@the-smithy/hearth";
 import { register } from "@/app/actions";
 
-const input = "block w-full rounded-lg border border-line bg-surface px-4 py-3 text-base text-ink focus:border-accent focus:outline-none";
+const input = "block w-full rounded-lg border border-field bg-surface px-4 py-3 text-base text-ink focus:border-accent focus:outline-none";
 const price = (cents: number) => (cents ? (cents / 100).toLocaleString("en-US", { style: "currency", currency: "USD", maximumFractionDigits: cents % 100 ? 2 : 0 }) : "Free");
 
 function Submit({ paid }: { paid: boolean }) {

package/template/src/components/VolunteerForm.tsx

@@ -0,0 +1,143 @@
+"use client";
+
+import { useActionState } from "react";
+import { useFormStatus } from "react-dom";
+import type { EventVolunteering } from "@the-smithy/hearth";
+import { volunteer, type VolunteerState } from "@/app/actions";
+
+const input = "block w-full rounded-lg border border-field bg-surface px-4 py-3 text-base text-ink focus:border-accent focus:outline-none";
+
+/** A shift's day and time in the event's time zone: "Sat, Nov 14 · 8:00 AM – 11:00 AM". */
+function shiftTime(s: { startsAt: string; endsAt: string }, timeZone: string) {
+  const day = (d: string) => new Date(d).toLocaleDateString("en-US", { timeZone, weekday: "short", month: "short", day: "numeric" });
+  const time = (d: string) => new Date(d).toLocaleTimeString("en-US", { timeZone, hour: "numeric", minute: "2-digit" });
+  return day(s.startsAt) === day(s.endsAt) ? `${day(s.startsAt)} · ${time(s.startsAt)} – ${time(s.endsAt)}` : `${day(s.startsAt)} ${time(s.startsAt)} – ${day(s.endsAt)} ${time(s.endsAt)}`;
+}
+
+function Submit({ label }: { label: string }) {
+  const { pending } = useFormStatus();
+  return (
+    <button type="submit" disabled={pending} className="rounded-lg bg-accent px-6 py-3.5 font-semibold text-accent-ink hover:opacity-90 disabled:opacity-60">
+      {pending ? "Signing up…" : label}
+    </button>
+  );
+}
+
+/**
+ * Volunteer sign-up for an event: name and email, shifts to choose from (when the event lists them), then the
+ * event's own questions. Sign-ups land under the event's Volunteers in Hearth.
+ */
+export function VolunteerForm({ slug, timezone, volunteering }: { slug: string; timezone: string; volunteering: EventVolunteering }) {
+  const [state, action] = useActionState<VolunteerState | null, FormData>(volunteer.bind(null, slug), null);
+  const errors = state && !state.ok ? state.fieldErrors : {};
+  const values = (state && !state.ok ? state.values : undefined) ?? {};
+  const chosen = (state && !state.ok ? state.shifts : undefined) ?? [];
+  const many = volunteering.pickShifts === "many";
+
+  if (state?.ok) {
+    return (
+      <p role="status" className="rounded-xl bg-accent p-6 text-lg font-semibold text-accent-ink">
+        {state.message}
+      </p>
+    );
+  }
+
+  return (
+    <form action={action} className="space-y-6" noValidate>
+      {state && !state.ok ? (
+        <p role="alert" className="rounded-lg border border-danger/30 bg-danger/5 px-4 py-3 text-danger">
+          {state.message}
+        </p>
+      ) : null}
+      {/* Honeypot: hidden from people, filled in by bots. */}
+      <div aria-hidden className="absolute -left-[9999px]">
+        <label>
+          Leave this empty
+          <input name="_gotcha" tabIndex={-1} autoComplete="off" />
+        </label>
+      </div>
+      <div className="grid gap-5 sm:grid-cols-2">
+        <label className="block">
+          <span className="mb-1.5 block font-semibold">Name</span>
+          <input name="name" required autoComplete="name" defaultValue={values.name} aria-invalid={errors.name ? true : undefined} className={input} />
+          {errors.name ? <span className="mt-1 block text-danger">{errors.name}</span> : null}
+        </label>
+        <label className="block">
+          <span className="mb-1.5 block font-semibold">Email</span>
+          <input name="email" type="email" required autoComplete="email" defaultValue={values.email} aria-invalid={errors.email ? true : undefined} className={input} />
+          {errors.email ? <span className="mt-1 block text-danger">{errors.email}</span> : null}
+        </label>
+      </div>
+      {volunteering.pickShifts !== "none" ? (
+        <fieldset>
+          <legend className="mb-3 font-semibold">{many ? "Shifts you can do" : "Choose a shift"}</legend>
+          <div className="space-y-3">
+            {volunteering.shifts.map((s) => (
+              <label key={s.id} className={`flex cursor-pointer items-start gap-3 rounded-lg p-4 ring-1 ring-line has-checked:ring-2 has-checked:ring-accent ${s.full ? "cursor-not-allowed opacity-50" : ""}`}>
+                <input
+                  type={many ? "checkbox" : "radio"}
+                  name="shift"
+                  value={s.id}
+                  disabled={s.full}
+                  defaultChecked={chosen.includes(s.id)}
+                  className="mt-1 size-5 accent-accent"
+                />
+                <span className="flex-1">
+                  <span className="flex flex-wrap justify-between gap-2 font-semibold">
+                    <span>{s.name}</span>
+                    <span className="font-normal opacity-80">{s.full ? "Full" : s.remaining !== null && s.remaining <= 5 ? `${s.remaining} spot${s.remaining === 1 ? "" : "s"} left` : null}</span>
+                  </span>
+                  <span className="mt-0.5 block opacity-80">{shiftTime(s, timezone)}</span>
+                  {s.description ? <span className="mt-1 block opacity-80">{s.description}</span> : null}
+                </span>
+              </label>
+            ))}
+          </div>
+          {errors.shifts ? <p className="mt-2 text-danger">{errors.shifts}</p> : null}
+        </fieldset>
+      ) : null}
+      {volunteering.fields.map((f) => {
+        const id = `volunteer-${f.name}`;
+        const error = errors[f.name];
+        const common = { id, name: f.name, required: f.required, "aria-invalid": error ? true : undefined, "aria-describedby": error ? `${id}-error` : undefined };
+        return (
+          <div key={f.name}>
+            {f.type === "checkbox" ? (
+              <label className="flex items-center gap-3">
+                <input type="checkbox" {...common} defaultChecked={values[f.name] === "on"} className="size-5 accent-accent" />
+                {f.label}
+              </label>
+            ) : (
+              <>
+                <label htmlFor={id} className="mb-1.5 block font-semibold">
+                  {f.label}
+                  {f.required ? null : <span className="ml-1 font-normal opacity-70">(optional)</span>}
+                </label>
+                {f.type === "textarea" ? (
+                  <textarea {...common} rows={4} defaultValue={values[f.name]} placeholder={f.placeholder} className={input} />
+                ) : f.type === "select" ? (
+                  <select {...common} defaultValue={values[f.name] ?? ""} className={input}>
+                    <option value="" disabled>
+                      {f.placeholder || "Choose one…"}
+                    </option>
+                    {(f.options ?? []).map((o) => (
+                      <option key={o}>{o}</option>
+                    ))}
+                  </select>
+                ) : (
+                  <input {...common} type={f.type} defaultValue={values[f.name]} placeholder={f.placeholder} autoComplete={f.type === "tel" ? "tel" : undefined} className={input} />
+                )}
+              </>
+            )}
+            {error ? (
+              <p id={`${id}-error`} className="mt-1.5 text-sm text-danger">
+                {error}
+              </p>
+            ) : null}
+          </div>
+        );
+      })}
+      <Submit label={volunteering.submitLabel} />
+    </form>
+  );
+}

package/template/src/components/blocks/EmberFormBlock.tsx

@@ -23,7 +23,7 @@ export function EmberFormBlock({ formId, fallback }: { formId: string; fallback:
           muted: "var(--color-muted-ink)",
           error: "var(--color-danger)",
           inputBackground: "var(--color-surface)",
-          border: "var(--color-line)",
+          border: "var(--color-field)",
           successBackground: "var(--color-muted)",
           radius: "8px",
           maxWidth: "none",

package/template/src/components/blocks/Form.tsx

@@ -7,7 +7,7 @@ import { submitHearthForm, type FormState } from "@/app/actions";
 
 type FormData_ = BlockOf<"form">["data"];
 
-const input = "block w-full rounded-lg border border-line bg-surface px-4 py-3 text-base text-ink focus:border-accent focus:outline-none";
+const input = "block w-full rounded-lg border border-field bg-surface px-4 py-3 text-base text-ink focus:border-accent focus:outline-none";
 
 function Submit({ label }: { label: string }) {
   const { pending } = useFormStatus();

package/template/src/components/blocks/OpenMap.tsx

@@ -0,0 +1,102 @@
+"use client";
+
+import { directionsUrl, type Position } from "@the-smithy/hearth";
+import { useEffect, useRef, useState } from "react";
+import "maplibre-gl/dist/maplibre-gl.css";
+
+/** Free OpenStreetMap tiles from OpenFreeMap: no key, no account, no cookies. Swap for another MapLibre style to restyle. */
+const MAP_STYLE = "https://tiles.openfreemap.org/styles/liberty";
+
+export type MapPlace = { name: string; address: string; position: Position };
+
+/**
+ * A map with a pin for each place; a pin opens the place's name, address and directions. MapLibre loads only when the
+ * map is about to scroll into view, and scrolling the page never zooms it (two fingers, or Ctrl and scroll, do).
+ */
+export function OpenMap({ places, label, className = "" }: { places: MapPlace[]; label: string; className?: string }) {
+  const container = useRef<HTMLDivElement>(null);
+  const [failed, setFailed] = useState(false);
+  const key = JSON.stringify(places);
+
+  useEffect(() => {
+    const el = container.current;
+    if (!el) return;
+    let cancelled = false;
+    let remove = () => {};
+    const show = async () => {
+      const ml = await import("maplibre-gl");
+      // MapLibre looks for its worker beside its own script, which isn't where the bundler puts it.
+      ml.setWorkerUrl(new URL("maplibre-gl/dist/maplibre-gl-worker.mjs", import.meta.url).href);
+      if (cancelled) return;
+      const list: MapPlace[] = JSON.parse(key);
+      const map = new ml.Map({
+        container: el,
+        style: MAP_STYLE,
+        center: [list[0].position.lng, list[0].position.lat],
+        zoom: 15,
+        attributionControl: { compact: true },
+        cooperativeGestures: true,
+        // MapLibre makes the map a labelled region (the canvas): name it for this map.
+        locale: { "Map.Title": label },
+      });
+      remove = () => map.remove();
+      map.addControl(new ml.NavigationControl({ showCompass: false }));
+      let loaded = false;
+      map.once("load", () => (loaded = true));
+      map.on("error", () => !loaded && setFailed(true));
+
+      const bounds = new ml.LngLatBounds();
+      for (const place of list) {
+        const at: [number, number] = [place.position.lng, place.position.lat];
+        bounds.extend(at);
+        const pin = document.createElement("button");
+        pin.type = "button";
+        pin.className = "block size-6 rounded-full border-[3px] border-white bg-highlight shadow-md";
+        pin.setAttribute("aria-label", place.name);
+        new ml.Marker({ element: pin }).setLngLat(at).setPopup(new ml.Popup({ offset: 14, closeButton: true }).setDOMContent(popup(place))).addTo(map);
+      }
+      if (list.length > 1) map.fitBounds(bounds, { padding: { top: 48, right: 56, bottom: 72, left: 48 }, maxZoom: 15, duration: 0 });
+    };
+    // Wait until the map is near the screen: most visitors never scroll to it.
+    const observer = new IntersectionObserver(
+      ([entry]) => {
+        if (!entry.isIntersecting) return;
+        observer.disconnect();
+        show().catch(() => setFailed(true));
+      },
+      { rootMargin: "300px" },
+    );
+    observer.observe(el);
+    return () => {
+      cancelled = true;
+      observer.disconnect();
+      remove();
+    };
+  }, [key, label]);
+
+  return (
+    <div className={`relative overflow-hidden rounded-xl bg-muted [&_.maplibregl-map]:font-sans [&_.maplibregl-popup-close-button]:size-8 [&_.maplibregl-popup-close-button]:text-xl ${className}`}>
+      {/* Sized by the frame: MapLibre makes its container position: relative. */}
+      <div ref={container} className="size-full" />
+      {failed ? <p className="absolute inset-0 grid place-items-center p-6 text-center opacity-80">The map couldn&apos;t load.</p> : null}
+    </div>
+  );
+}
+
+/** A pin's popup, built as elements (never HTML strings) so names and addresses stay plain text. */
+function popup(place: MapPlace) {
+  const box = document.createElement("div");
+  box.className = "grid gap-1 pr-4 font-sans text-sm text-ink";
+  const name = document.createElement("strong");
+  name.textContent = place.name;
+  const address = document.createElement("span");
+  address.className = "whitespace-pre-line";
+  address.textContent = place.address;
+  const link = document.createElement("a");
+  link.href = directionsUrl(place);
+  link.rel = "noopener";
+  link.className = "font-semibold text-highlight underline underline-offset-4";
+  link.textContent = "Get directions";
+  box.append(name, address, link);
+  return box;
+}

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

@@ -8,7 +8,7 @@ const date = (iso: string | null) =>
 function Card({ entry }: { entry: CollectionEntry }) {
   return (
     <li className="relative flex flex-col overflow-hidden rounded-2xl bg-surface ring-1 ring-line">
-      {entry.image ? <Img image={entry.image} className="aspect-[16/10] w-full object-cover" /> : null}
+      {entry.image ? <Img image={entry.image} crop={16 / 10} className="aspect-[16/10] w-full object-cover" /> : null}
       <div className="flex flex-1 flex-col gap-2 p-6">
         {entry.date ? <p className="text-sm font-semibold text-highlight">{date(entry.date)}</p> : null}
         <h3 className="text-xl font-semibold">

package/template/src/components/blocks/content.tsx

@@ -5,7 +5,7 @@ export function Hero({ block }: { block: BlockOf<"hero"> }) {
   const d = block.data;
   return (
     <section className="relative overflow-hidden bg-inverse text-inverse-ink">
-      {d.image ? <Img image={d.image} priority className="absolute inset-0 size-full object-cover opacity-35" /> : null}
+      {d.image ? <Img image={d.image} crop priority className="absolute inset-0 size-full object-cover opacity-35" /> : null}
       <div className={`relative mx-auto max-w-site px-4 sm:px-6 ${d.size === "full" ? "py-28 sm:py-36" : "py-16 sm:py-20"}`}>
         {d.logo ? <Img image={d.logo} priority className="mb-6 h-20 w-auto sm:h-24" /> : null}
         {d.eyebrow ? <p className="mb-4 text-sm font-semibold uppercase tracking-[0.18em] opacity-80">{d.eyebrow}</p> : null}
@@ -46,7 +46,7 @@ export function MediaText({ block }: { block: BlockOf<"mediaText"> }) {
             </div>
           ) : null}
         </div>
-        {d.image ? <Img image={d.image} className={`w-full rounded-xl ${d.imageFit === "contain" ? "max-h-96 object-contain" : "aspect-[4/3] object-cover"}`} /> : null}
+        {d.image ? <Img image={d.image} crop={d.imageFit === "contain" ? undefined : 4 / 3} className={`w-full rounded-xl ${d.imageFit === "contain" ? "max-h-96 object-contain" : "aspect-[4/3] object-cover"}`} /> : null}
       </div>
     </Section>
   );
@@ -77,7 +77,7 @@ export function CardGrid({ block }: { block: BlockOf<"cardGrid"> }) {
       <ul className="grid gap-5 sm:grid-cols-2 lg:grid-cols-3">
         {d.items.map((c, i) => (
           <li key={i} className={`flex flex-col gap-3 rounded-2xl p-7 ${dark ? "bg-white/10" : "bg-surface ring-1 ring-line"}`}>
-            {c.image ? <Img image={c.image} className="mb-2 aspect-[16/10] w-full rounded-lg object-cover" /> : null}
+            {c.image ? <Img image={c.image} crop={16 / 10} className="mb-2 aspect-[16/10] w-full rounded-lg object-cover" /> : null}
             <h3 className="text-xl font-semibold">{c.title}</h3>
             {c.body ? <p className="leading-relaxed opacity-80">{c.body}</p> : null}
             {c.link ? (
@@ -112,6 +112,7 @@ export function Projects({ block }: { block: BlockOf<"projects"> }) {
             {p.image ? (
               <Img
                 image={p.image}
+                crop={16 / 10}
                 className={`aspect-[16/10] w-full rounded-xl object-cover object-top ${grid ? "mb-2" : i % 2 ? "md:order-2" : ""}`}
               />
             ) : null}
@@ -207,7 +208,7 @@ export function CallToAction({ block }: { block: BlockOf<"cta"> }) {
   if (!d.image) return <Section tone={d.tone}>{content(isDark(d.tone))}</Section>;
   return (
     <section className="relative overflow-hidden text-white">
-      <Img image={d.image} className="absolute inset-0 size-full object-cover" />
+      <Img image={d.image} crop className="absolute inset-0 size-full object-cover" />
       <div className="relative bg-black/55">
         <div className="mx-auto max-w-site px-4 py-20 sm:px-6 sm:py-24">{content(true)}</div>
       </div>
@@ -244,7 +245,7 @@ export function Quote({ block }: { block: BlockOf<"quote"> }) {
         <blockquote className="text-2xl font-semibold leading-snug sm:text-3xl">“{d.quote}”</blockquote>
         {d.name ? (
           <figcaption className="flex items-center gap-4">
-            {d.image ? <Img image={d.image} className="size-14 rounded-full object-cover" /> : null}
+            {d.image ? <Img image={d.image} crop={1} className="size-14 rounded-full object-cover" /> : null}
             <span>
               <span className="block font-semibold">{d.name}</span>
               {d.role ? <span className="block opacity-75">{d.role}</span> : null}

package/template/src/components/blocks/events.tsx

@@ -1,6 +1,7 @@
 import Link from "next/link";
 import type { BlockOf, HearthEvent } from "@the-smithy/hearth";
 import { Registration } from "@/components/Registration";
+import { VolunteerForm } from "@/components/VolunteerForm";
 import { Img, Section, SectionHeading } from "@/components/ui";
 
 /** "Sat, Oct 18 · 6:00 – 9:00 PM", in the event's own time zone. */
@@ -20,7 +21,7 @@ export function EventCard({ event }: { event: HearthEvent }) {
   const cancelled = event.status === "cancelled";
   return (
     <li className="flex flex-col overflow-hidden rounded-2xl bg-surface ring-1 ring-line">
-      {event.image ? <Img image={event.image} className="aspect-[16/9] w-full object-cover" /> : null}
+      {event.image ? <Img image={event.image} crop={16 / 9} className="aspect-[16/9] w-full object-cover" /> : null}
       <div className="flex flex-1 flex-col gap-2 p-6">
         <p className="text-sm font-semibold text-highlight">
           {cancelled ? <span className="mr-2 rounded bg-danger px-1.5 py-0.5 text-white">Cancelled</span> : null}
@@ -97,8 +98,41 @@ export function EventSpotlight({ block }: { block: BlockOf<"eventSpotlight"> })
             Event details
           </Link>
         </div>
-        {e.image ? <Img image={e.image} className="aspect-[4/3] w-full rounded-xl object-cover" /> : null}
+        {e.image ? <Img image={e.image} crop={4 / 3} className="aspect-[4/3] w-full rounded-xl object-cover" /> : null}
       </div>
     </Section>
   );
 }
+
+/**
+ * Volunteer sign-up for an event, wherever the block is placed. On another page it names the event and links to it;
+ * once sign-up closes it says so. The event's own page leaves out its built-in form when this block is on it.
+ */
+export function VolunteerSignup({ block }: { block: BlockOf<"volunteerSignup"> }) {
+  const e = block.data.event;
+  const v = e.volunteering;
+  const intro = block.data.intro || v.intro;
+  return (
+    <Section id={volunteerAnchor(e.slug)}>
+      <div className="max-w-2xl">
+        <h2 className="mb-2 text-2xl font-bold">{block.data.heading || "Volunteer"}</h2>
+        {block.data.eventSlug ? (
+          <p className="mb-2 font-semibold">
+            <Link href={e.path} className="underline underline-offset-4 hover:opacity-80">
+              {e.title}
+            </Link>
+            <span className="text-highlight"> · {formatEventDate(e)}</span>
+          </p>
+        ) : null}
+        {intro ? <p className="mb-2 whitespace-pre-line opacity-85">{intro}</p> : null}
+        {v.fundraiser ? <p className="mb-2 opacity-80">This event supports {v.fundraiser.title}.</p> : null}
+        <div className="mt-6">
+          {v.open ? <VolunteerForm slug={e.slug} timezone={e.timezone} volunteering={v} /> : <p className="opacity-80">Volunteer sign-up for this event has closed.</p>}
+        </div>
+      </div>
+    </Section>
+  );
+}
+
+/** Where an event's Volunteer sign-up block sits, for the event header's Volunteer button. */
+export const volunteerAnchor = (slug: string) => `volunteer-${slug}`;

package/template/src/components/blocks/giving.tsx

@@ -33,7 +33,7 @@ export function Progress({ fundraiser, large }: { fundraiser: Fundraiser; large?
 export function FundraiserCard({ fundraiser }: { fundraiser: Fundraiser }) {
   return (
     <li className="relative flex flex-col overflow-hidden rounded-2xl bg-surface ring-1 ring-line">
-      {fundraiser.image ? <Img image={fundraiser.image} className="aspect-[16/9] w-full object-cover" /> : null}
+      {fundraiser.image ? <Img image={fundraiser.image} crop={16 / 9} className="aspect-[16/9] w-full object-cover" /> : null}
       <div className="flex flex-1 flex-col gap-3 p-6">
         {fundraiser.status === "completed" ? <p className="w-fit rounded bg-muted px-2 py-0.5 text-sm font-semibold">Completed</p> : null}
         <h3 className="text-xl font-semibold">
@@ -100,7 +100,7 @@ export function FundraiserSpotlight({ block }: { block: BlockOf<"fundraiserSpotl
             </Link>
           </p>
         </div>
-        {f.image ? <Img image={f.image} className="aspect-[4/3] w-full rounded-xl object-cover" /> : null}
+        {f.image ? <Img image={f.image} crop={4 / 3} className="aspect-[4/3] w-full rounded-xl object-cover" /> : null}
       </div>
     </Section>
   );

package/template/src/components/blocks/index.tsx

@@ -3,12 +3,12 @@ import { HearthBlocks, type BlockComponents } from "@the-smithy/hearth/react";
 import { Section, SectionHeading } from "@/components/ui";
 import { CollectionList } from "./collections";
 import { CallToAction, CardGrid, Faq, Hero, MediaText, Pricing, Projects, Quote, RichText, Stats } from "./content";
-import { EventSpotlight, PastEvents, UpcomingEvents } from "./events";
+import { EventSpotlight, PastEvents, UpcomingEvents, VolunteerSignup } from "./events";
 import { CustomBlock } from "./custom";
 import { EmberFormBlock } from "./EmberFormBlock";
 import { HearthForm } from "./Form";
 import { Donate, FundraiserGrid, FundraiserSpotlight } from "./giving";
-import { Location, Schedule } from "./info";
+import { Location, Locations, Schedule } from "./info";
 import { Embed, Gallery, Logos, People, Video } from "./media";
 
 function FormBlock({ block }: { block: BlockOf<"form"> }) {
@@ -49,11 +49,13 @@ export const blocks: BlockComponents = {
   people: People,
   logos: Logos,
   location: Location,
+  locations: Locations,
   schedule: Schedule,
   form: FormBlock,
   upcomingEvents: UpcomingEvents,
   pastEvents: PastEvents,
   eventSpotlight: EventSpotlight,
+  volunteerSignup: VolunteerSignup,
   collectionList: CollectionList,
   fundraiserSpotlight: FundraiserSpotlight,
   fundraiserGrid: FundraiserGrid,

package/template/src/components/blocks/info.tsx

@@ -1,9 +1,11 @@
-import type { BlockOf } from "@the-smithy/hearth";
-import { Section, SectionHeading } from "@/components/ui";
+import { directionsUrl, pinned, type BlockOf } from "@the-smithy/hearth";
+import { Markdown, Section, SectionHeading, SmartLink } from "@/components/ui";
+import { OpenMap } from "./OpenMap";
+
+const linkStyle = "font-semibold text-highlight underline underline-offset-4";
 
 export function Location({ block }: { block: BlockOf<"location"> }) {
   const d = block.data;
-  const query = encodeURIComponent(`${d.name}, ${d.address}`);
   return (
     <Section>
       <SectionHeading eyebrow={d.eyebrow} heading={d.heading} />
@@ -12,20 +14,49 @@ export function Location({ block }: { block: BlockOf<"location"> }) {
           <h3 className="text-xl font-semibold">{d.name}</h3>
           <address className="whitespace-pre-line not-italic">{d.address}</address>
           {d.hours ? <p className="whitespace-pre-line">{d.hours}</p> : null}
-          {d.notes ? <p className="opacity-80">{d.notes}</p> : null}
-          <a href={`https://www.google.com/maps/dir/?api=1&destination=${query}`} rel="noopener" className="font-semibold text-highlight underline underline-offset-4">
+          {d.notes ? <Markdown className="opacity-80">{d.notes}</Markdown> : null}
+          <a href={directionsUrl(d)} rel="noopener" className={linkStyle}>
             Get directions
           </a>
         </div>
-        {d.showMap ? (
-          <iframe
-            title={`Map of ${d.name}`}
-            src={`https://www.google.com/maps?q=${query}&output=embed`}
-            loading="lazy"
-            referrerPolicy="no-referrer-when-downgrade"
-            className="aspect-[4/3] w-full rounded-xl border-0 bg-muted"
-          />
+        {/* Content from before map pins has none: it shows no map until the pin is set in Hearth. */}
+        {d.showMap && d.position ? <OpenMap places={[{ name: d.name, address: d.address, position: d.position }]} label={`Map of ${d.name}`} className="aspect-[4/3]" /> : null}
+      </div>
+    </Section>
+  );
+}
+
+/** Several places: one map with a pin for each (places without a pin are only listed), and the list beside it. */
+export function Locations({ block }: { block: BlockOf<"locations"> }) {
+  const d = block.data;
+  const onMap = d.showMap ? pinned(d.items) : [];
+  return (
+    <Section>
+      <SectionHeading eyebrow={d.eyebrow} heading={d.heading} intro={d.intro} />
+      <div className={`grid gap-10 ${onMap.length ? "md:grid-cols-[2fr_3fr]" : ""}`}>
+        {onMap.length ? (
+          <OpenMap places={onMap} label={d.heading ? `Map: ${d.heading}` : "Map of our locations"} className="aspect-[4/3] md:sticky md:top-24 md:order-2 md:aspect-auto md:h-[min(36rem,80vh)]" />
         ) : null}
+        <ul className={`divide-y divide-line border-y border-line ${onMap.length ? "" : "grid gap-x-10 sm:grid-cols-2 sm:divide-y-0 sm:border-y-0"}`}>
+          {d.items.map((place, i) => (
+            <li key={i} className="flex flex-col gap-2 py-6">
+              <h3 className="text-xl font-semibold">{place.name}</h3>
+              <address className="whitespace-pre-line not-italic">{place.address}</address>
+              {place.hours ? <p className="whitespace-pre-line">{place.hours}</p> : null}
+              {place.notes ? <p className="whitespace-pre-line opacity-80">{place.notes}</p> : null}
+              <p className="mt-1 flex flex-wrap gap-x-6 gap-y-2">
+                <a href={directionsUrl(place)} rel="noopener" className={linkStyle}>
+                  Get directions<span className="sr-only"> to {place.name}</span>
+                </a>
+                {place.link ? (
+                  <SmartLink href={place.link.href} className={linkStyle}>
+                    {place.link.label}
+                  </SmartLink>
+                ) : null}
+              </p>
+            </li>
+          ))}
+        </ul>
       </div>
     </Section>
   );

package/template/src/components/blocks/media.tsx

@@ -13,7 +13,7 @@ export function Gallery({ block }: { block: BlockOf<"gallery"> }) {
         {d.images.map((item, i) => (
           <li key={i}>
             <figure>
-              <Img image={item.image} className="aspect-[4/3] w-full rounded-xl object-cover" />
+              <Img image={item.image} crop={4 / 3} className="aspect-[4/3] w-full rounded-xl object-cover" />
               {item.caption ? <figcaption className="mt-2 text-sm opacity-75">{item.caption}</figcaption> : null}
             </figure>
           </li>
@@ -68,7 +68,7 @@ export function People({ block }: { block: BlockOf<"people"> }) {
       <ul className="grid gap-8 sm:grid-cols-2 lg:grid-cols-3">
         {d.people.map((p, i) => (
           <li key={i} className="flex flex-col gap-3">
-            {p.image ? <Img image={p.image} className="aspect-square w-full rounded-2xl object-cover" /> : null}
+            {p.image ? <Img image={p.image} crop={1} className="aspect-square w-full rounded-2xl object-cover" /> : null}
             <div>
               <h3 className="text-xl font-semibold">{p.name}</h3>
               {p.role ? <p className="opacity-75">{p.role}</p> : null}

package/template/src/components/ui.tsx

@@ -1,6 +1,7 @@
 import Link from "next/link";
 import { Fragment, type ReactNode } from "react";
 import ReactMarkdown from "react-markdown";
+import { focalPosition, type ImageRef } from "@the-smithy/hearth";
 
 type LinkRef = { label: string; href: string };
 export type Tone = "default" | "muted" | "inverse" | "accent";
@@ -15,9 +16,9 @@ const toneClass: Record<Tone, string> = {
 export const isDark = (tone?: Tone) => tone === "inverse" || tone === "accent";
 
 /** A full-width band with the site's content width inside. */
-export function Section({ tone = "default", className = "", children }: { tone?: Tone; className?: string; children: ReactNode }) {
+export function Section({ tone = "default", id, className = "", children }: { tone?: Tone; id?: string; className?: string; children: ReactNode }) {
   return (
-    <section className={toneClass[tone]}>
+    <section id={id} className={`${toneClass[tone]} ${id ? "scroll-mt-8" : ""}`}>
       <div className={`mx-auto max-w-site px-4 py-16 sm:px-6 sm:py-20 ${className}`}>{children}</div>
     </section>
   );
@@ -103,17 +104,24 @@ export function Button({ link, variant = "primary", dark }: { link?: LinkRef; va
  * An image from Hearth. Its width and height (from Hearth's media library) reserve its space, so the page doesn't jump
  * as it loads. `priority` loads it first: use it for the image at the top of the page (the hero), which is usually
  * the largest thing on screen; everything else loads as it scrolls into view.
+ *
+ * `crop` is for images cropped to fill a frame (`object-cover`): they keep the focal point set in Hearth's media
+ * library in view. Give the frame's aspect ratio (`crop={4 / 3}` for `aspect-[4/3]`) to centre the focal point, or
+ * `crop` alone for frames whose shape changes with the screen (a full-bleed hero). Leave it off for uncropped images.
  */
 /* eslint-disable @next/next/no-img-element -- Hearth serves media from its CDN at the uploaded size */
 export function Img({
   image,
   className = "",
   priority = false,
+  crop,
 }: {
-  image: { src: string; alt: string; width?: number; height?: number };
+  image: ImageRef;
   className?: string;
   priority?: boolean;
+  crop?: number | true;
 }) {
+  const objectPosition = crop ? focalPosition(image, crop === true ? undefined : crop) : undefined;
   return (
     <img
       src={image.src}
@@ -123,6 +131,7 @@ export function Img({
       fetchPriority={priority ? "high" : "auto"}
       decoding={priority ? "sync" : "async"}
       className={className}
+      style={objectPosition ? { objectPosition } : undefined}
     />
   );
 }