bsmnt 0.13.1 → 0.15.0

package/src/agent-skills/launch-ready/references/a11y.md

@@ -0,0 +1,74 @@
+# Accessibility
+
+Contrast, motion and target size are design decisions. Report failures; don't
+change brand colors or layout unasked.
+
+## A11Y-01 · Every page has an `h1`
+
+**Fix before launch**
+
+One `h1` that names the page. Screen reader users jump to it first.
+
+**Check:** `curl -s localhost:3000/<route> | grep -c '<h1'` prints at least `1`.
+
+## A11Y-02 · Everything works by keyboard
+
+**Fix before launch**
+
+Interactive elements are real controls (`<button>`, `<Link>`, inputs), reachable
+with Tab, with a visible focus style. A `<div onClick>` can't be reached
+without a mouse. Menus and modals close on Escape and return focus.
+
+**Check (browser):** Tab through the page. Every control is reachable, and
+you can always see where focus is.
+
+## A11Y-03 · Icon-only controls have a name
+
+**Fix before launch**
+
+An icon-only button or link carries an `aria-label` or visually hidden text.
+Otherwise a screen reader announces only "button".
+
+## A11Y-04 · Inputs have labels
+
+**Fix before launch**
+
+Each input has a `<label>`. A placeholder isn't one; it disappears as soon as
+someone types. Fields for personal data carry the matching `autocomplete`
+value (`email`, `name`, `tel`).
+
+## A11Y-05 · Text meets contrast
+
+**Fix before launch**
+
+Body text is at least 4.5:1 against its background, and large text (24px, or
+19px bold) at least 3:1. Logos, disabled controls and decorative text are
+exempt.
+
+**Check (browser):** Lighthouse's accessibility audit, or the axe DevTools
+extension.
+
+## A11Y-06 · Motion can be paused or reduced
+
+**Fix before launch**
+
+Anything that moves on its own for more than 5 seconds (autoplay video,
+marquees, carousels) has a pause control. Non-essential animation, smooth
+scrolling included, respects `prefers-reduced-motion`.
+
+## A11Y-07 · Targets are big enough; zoom stays on
+
+**Fix before launch**
+
+Tap targets are at least 24×24px, or have 24px of clearance. Links inside a
+sentence are exempt.
+
+Never set `maximumScale: 1` or `userScalable: false` in the viewport. If iOS
+zooms into a focused input, set the input's font size to at least 16px instead.
+
+## A11Y-08 · No horizontal scroll at 320px
+
+**Fix before launch**
+
+The page fits a 320px-wide viewport without horizontal scrolling. Maps, data
+tables and diagrams are exempt.

package/src/agent-skills/launch-ready/references/content.md

@@ -0,0 +1,65 @@
+# Content
+
+## CONTENT-01 · Indexed copy is in the server HTML
+
+**Must not ship** · only if indexed
+
+Text meant for search, link previews and AI is in the server HTML. Don't draw
+it only in a canvas, and don't load it only through `dynamic(..., { ssr: false })`.
+A WebGL scene can stay client-only; its headline and copy can't.
+
+**Check:** a sentence from the page's main copy appears in
+`curl -s localhost:3000/<route>`.
+
+## CONTENT-02 · No placeholder output
+
+**Must not ship**
+
+No `undefined`, `null`, `NaN`, `[object Object]` or lorem ipsum in rendered
+text. These usually appear after launch, when an editor leaves a CMS field
+empty, so render nothing for a missing field instead.
+
+**Check:**
+
+```bash
+curl -s localhost:3000/<route> | grep -noiE 'undefined|NaN|\[object Object\]|lorem ipsum'
+```
+
+A match is a lead, not proof: documentation can say "returns `undefined`" on
+purpose.
+
+## CONTENT-03 · Each fact has one source
+
+**Must not ship**
+
+A price, spec or limit shown in more than one place reads from one module or
+one CMS field. Two copies drift, and the site contradicts itself.
+
+**Check:** search the repo for the value. It appears once, where it's defined.
+
+## CONTENT-04 · No test pages, drafts or staging links
+
+**Must not ship**
+
+Test pages, unpublished drafts and links to staging or preview hosts aren't
+reachable in production or listed in the sitemap.
+
+**Check:** search the production HTML and `sitemap.xml` for `test`, `staging`,
+`preview` and `vercel.app`.
+
+## CONTENT-05 · No starter leftovers
+
+**Fix before launch**
+
+Replace basement's placeholders with the site's own, wherever they remain:
+
+- the `app/favicon.ico` every template ships
+- the `"Basement Starter"` title in `app/layout.tsx`
+- `siteName = "Basement"` in `lib/utils/metadata.ts`
+- the `"Basement Next Starter"` homepage heading
+
+**Check:**
+
+```bash
+grep -rn 'Basement Starter\|Basement Next Starter\|siteName = "Basement"' app lib components
+```

package/src/agent-skills/launch-ready/references/crawlers.md

@@ -0,0 +1,89 @@
+# Crawlers
+
+## CRAWL-01 · Indexing matches the decision
+
+**Must not ship** when production and the decision disagree
+
+`app/robots.ts` and each page's `noIndex` follow *Indexed by search engines*.
+Previews are never indexable.
+
+The starter indexes only the host of `NEXT_PUBLIC_BASE_URL`, and on Vercel
+only on a production deployment. Every other host, including `*.vercel.app`,
+gets `X-Robots-Tag: noindex` and a disallow-all `robots.txt`. Without
+`NEXT_PUBLIC_BASE_URL`, nothing is indexed.
+
+**Check:**
+
+```bash
+curl -s https://<production>/robots.txt
+curl -sI https://<production>/ | grep -i x-robots-tag
+curl -sI https://<preview>/ | grep -i x-robots-tag
+```
+
+Production matches the decision. The preview prints `noindex`.
+
+## CRAWL-02 · Canonicals point at the right page
+
+**Must not ship**
+
+A canonical is absolute and points at a page that returns 200 and is indexable.
+
+If `app/layout.tsx` sets `alternates.canonical: "/"`, every page that doesn't
+set its own canonical inherits it, which points the whole site at the
+homepage. Set it per page with `generatePageMetadata({ url })`, or remove it
+from the layout.
+
+If the layout declares an `en-US` alternate at `/en-US`, remove it unless a
+route serves that locale.
+
+**Check:**
+
+```bash
+curl -s localhost:3000/<route> | grep -o '<link rel="canonical"[^>]*>'
+```
+
+It names that route, not `/`.
+
+## CRAWL-03 · The sitemap lists every indexable page
+
+**Fix before launch** · only if indexed
+
+Build the sitemap from the same data as the routes: every static route, plus
+each CMS document with a public URL. The starter's `app/sitemap.xml/route.ts`
+lists only `/`; add each route to `getStaticEntries()`. When the sitemap reads
+a CMS, a new content type needs adding to its query.
+
+**Check:**
+
+```bash
+curl -s localhost:3000/sitemap.xml | grep -c '<loc>'
+```
+
+The count matches the number of public pages.
+
+## CRAWL-04 · The sitemap lists only live pages
+
+**Fix before launch** · only if indexed
+
+No sitemap URL redirects, 404s or is `noindex`, and each one uses the
+production host.
+
+**Check:**
+
+```bash
+curl -s localhost:3000/sitemap.xml | grep -o '<loc>[^<]*' | cut -c6- |
+  while read -r u; do printf '%s %s\n' "$(curl -so /dev/null -w '%{http_code}' "$u")" "$u"; done
+```
+
+Every line starts with `200`.
+
+## CRAWL-05 · AI crawler policy matches the decision
+
+**Fix before launch**
+
+- *AI crawlers: allowed* needs nothing.
+- *AI crawlers: blocked* adds a `disallow: "/"` rule in `robots.ts` for each
+  agent: `GPTBot`, `ClaudeBot`, `PerplexityBot`, `Google-Extended`, `CCBot`.
+- *llms.txt: yes* serves `/llms.txt`.
+
+**Check:** `curl -s https://<production>/robots.txt` matches the decision.

package/src/agent-skills/launch-ready/references/launch.md

@@ -0,0 +1,44 @@
+# On the real domain
+
+These only fail in production, so check them against the deployed URL.
+
+## LAUNCH-01 · Forms deliver on production
+
+**Must not ship** · only if the site has forms
+
+Submit each form on production and confirm the submission arrives. The usual
+failure: the form's API key is set for Preview but not for Production, so the
+form works on every preview and silently drops submissions after launch.
+
+## LAUNCH-02 · CMS publishing updates production
+
+**Must not ship** · only if the site uses a CMS
+
+Publish a small change in the CMS and confirm production shows it. The
+revalidation webhook points at the production URL and carries its secret.
+
+## LAUNCH-03 · One host
+
+**Fix before launch**
+
+Pick the apex domain or `www`. In Vercel's domain settings, the other
+redirects to it permanently.
+
+**Check:**
+
+```bash
+curl -sI https://<other-host>/ | grep -i '^location'
+```
+
+It points at the chosen host.
+
+## LAUNCH-04 · Old URLs redirect on a relaunch
+
+**Fix before launch** · only if *Replaces an existing site: yes*
+
+Every old URL with traffic or backlinks redirects to its new equivalent
+through `redirects()` in `next.config.ts`. Ask the user for the old site's URL
+list: its sitemap, or its top pages in analytics.
+
+**Check:** request a sample of old URLs. Each returns `308` to a page that
+returns `200`.

package/src/agent-skills/launch-ready/references/metadata.md

@@ -0,0 +1,83 @@
+# Metadata
+
+## META-01 · Every page has a real title
+
+**Must not ship**
+
+Each route exports `metadata` or `generateMetadata` with its own title. If
+`app/layout.tsx` still has the `"Basement Starter"` default and its
+`"%s - Basement Starter"` template, replace both with the site's name.
+
+**Check:**
+
+```bash
+curl -s localhost:3000/<route> | grep -o '<title>[^<]*'
+```
+
+## META-02 · Metadata is in the server HTML
+
+**Must not ship**
+
+Set titles, descriptions and share tags through the Metadata API, never with
+`document.title` or a client effect. Crawlers and link previews don't run
+JavaScript.
+
+**Check:** the tags appear in `curl -s localhost:3000/<route>`, not only in
+the browser's DOM.
+
+## META-03 · The share image loads
+
+**Must not ship**
+
+A declared `og:image` is absolute and returns an image.
+
+If the layout or `generatePageMetadata` defaults to `/opengraph-image.jpg`,
+add that file: no template ships it. Until `public/opengraph-image.jpg`
+exists, every share card is broken, and so is the Organization JSON-LD logo,
+which uses the same path.
+
+**Check:**
+
+```bash
+img=$(curl -s localhost:3000/ | grep -o 'property="og:image" content="[^"]*' | cut -d'"' -f4)
+curl -so /dev/null -w '%{http_code} %{content_type}\n' "$img"
+```
+
+Expect `200 image/...`.
+
+## META-04 · No `localhost` URLs in production
+
+**Must not ship**
+
+`metadataBase`, canonicals and share URLs read `NEXT_PUBLIC_BASE_URL`, then
+the Vercel deployment URL, and fall back to `http://localhost:3000` off Vercel.
+Set it for the Production environment.
+
+**Check:**
+
+```bash
+curl -s https://<production>/ | grep -c 'localhost:3000'
+```
+
+Expect `0`.
+
+## META-05 · Titles are unique
+
+**Fix before launch**
+
+Distinct pages have distinct titles. Variants that canonicalize to one page
+are exempt.
+
+## META-06 · Public pages have a description
+
+**Fix before launch**
+
+Slack, LinkedIn and iMessage show the description as the preview text. If the
+layout's default reads `package.json`'s `description`, write a real one there.
+
+## META-07 · `<html lang>` matches the content
+
+**Fix before launch**
+
+The starter sets `lang="en"`. Change it when the site isn't English, and set
+it per locale on a multilingual site.

package/src/agent-skills/launch-ready/references/performance.md

@@ -0,0 +1,36 @@
+# Performance
+
+## PERF-01 · The LCP image isn't lazy
+
+**Fix before launch**
+
+The largest image in the first screen (usually the hero) passes `priority` to
+`@/components/ui/image`. Everything below the fold stays lazy, which is the
+default.
+
+## PERF-02 · Image `sizes` match the layout
+
+**Fix before launch**
+
+`sizes` describes the width the image renders at. Without it, the image
+component falls back to `100vw` and the browser downloads the largest
+variant, which is only right for full-width images. Build `sizes` with
+`buildImageSizes` or `buildGridImageSizes` from `lib/utils/image-sizes.ts`.
+
+The `no-fill-without-sizes` lint rule catches `fill` with no `sizes`. It can't
+tell whether the value is correct.
+
+## PERF-03 · Responses are compressed
+
+**Fix before launch** · only when hosted outside Vercel
+
+Vercel compresses responses by default. Another host has to serve HTML, JS
+and CSS with gzip or brotli.
+
+**Check:**
+
+```bash
+curl -sI -H 'Accept-Encoding: gzip, br' https://<production>/ | grep -i content-encoding
+```
+
+Expect `gzip` or `br`.

package/src/agent-skills/launch-ready/references/routing.md

@@ -0,0 +1,47 @@
+# Routing
+
+## ROUTE-01 · Missing pages return 404
+
+**Must not ship**
+
+When a dynamic or CMS route has no data, call `notFound()` before any
+`<Suspense>`. Once a response starts streaming, its status is already 200.
+Next can't change it then, and injects a `noindex` tag instead.
+
+```tsx
+export default async function Page({ params }: PageProps<"/blog/[slug]">) {
+  const { slug } = await params
+  const post = await getPost(slug)
+  if (!post) notFound()
+  return <Post post={post} />
+}
+```
+
+**Check:**
+
+```bash
+curl -so /dev/null -w '%{http_code}\n' localhost:3000/does-not-exist
+```
+
+Expect `404`. Repeat under each dynamic segment, such as `/blog/does-not-exist`.
+
+**Not this:** redirecting unknown paths to `/`. That's still a missing page
+answering 200.
+
+## ROUTE-02 · No internal link is broken
+
+**Must not ship**
+
+Every internal link resolves to a page that returns 200. A control that only
+runs JavaScript is a `<button>`, not `<a href="#">`. An `#id` that exists on the
+page, or a "back to top" link, is fine.
+
+**Check:** list each route's links and request them.
+
+```bash
+curl -s localhost:3000/ | grep -o 'href="/[^"#]*"' | cut -d'"' -f2 | sort -u |
+  while read -r p; do printf '%s %s\n' "$(curl -so /dev/null -w '%{http_code}' "localhost:3000$p")" "$p"; done
+```
+
+Every line starts with `200`. A broken link in the nav or footer breaks on every
+page, so check those first.

package/src/agent-skills/launch-ready/references/security.md

@@ -0,0 +1,39 @@
+# Security and hygiene
+
+## SEC-01 · `NEXT_PUBLIC_` holds only public keys
+
+**Must not ship**
+
+Anything prefixed `NEXT_PUBLIC_` ships in the browser bundle, readable by
+anyone. Only keys designed to be public belong there: a Sanity project ID, a
+Stripe `pk_` key, an analytics site ID. Read every other secret on the server.
+
+**Check:**
+
+```bash
+grep -rhoE 'NEXT_PUBLIC_[A-Z0-9_]+' app components lib | sort -u
+```
+
+Confirm each name on the list is meant to be public.
+
+## SEC-02 · Tracking matches the consent decision
+
+**Fix before launch** · only if consent is required
+
+No analytics or ad script runs, and no tracking cookie is set, before the
+visitor answers the consent banner. The `ketch-consent-check` skill covers
+gating a script behind Ketch, when the project has it.
+
+**Check (browser):** in a fresh private window, before you answer the banner,
+DevTools → Application → Cookies lists no tracking cookies.
+
+## SEC-03 · No first-party console errors
+
+**Fix before launch**
+
+The console shows no errors from the site's own code on load, and no
+hydration mismatches. A mismatch means the server and the client rendered
+different content. Errors from third-party scripts are out of scope.
+
+**Check (browser):** load each route with DevTools open, then read the
+console.

package/src/agent-skills/page-builder-block/SKILL.md

@@ -13,21 +13,23 @@ description: >-
 
 # Page-builder block conventions
 
-Blocks are **documents** referenced from the `pageBuilder` array, drawn by
+Blocks are **inline objects** in the `pageBuilder` array — never documents, and
+never referenced. A placement belongs to exactly one page, so the block lives on
+that page and nothing is dereferenced at read time. They are drawn by
 `components/page-builder/renderer.tsx` through the registry in
 `components/page-builder/registry.tsx`. Read one existing block end to end
 before writing a new one — `hero` is the smallest complete example:
 
 - schema: `lib/integrations/sanity/schemas/components/reusable/hero.ts`
 - component: `components/page-builder/components/hero.tsx`
+- fixture: `components/page-builder/library.ts`
 - registration: `lib/integrations/sanity/schemas/components/index.ts`,
   `lib/integrations/sanity/schemas/index.ts`,
   `lib/integrations/sanity/page-builder-config.ts`,
-  `lib/integrations/sanity/structure.ts`,
   `components/page-builder/registry.tsx`
 
 A block exists in two halves — a schema and a component — and each half has one
-place that makes it a block rather than an ordinary document or a loose React
+place that makes it a block rather than an ordinary object type or a loose React
 component. Use them and the conventions below come for free; skip them and a
 typecheck fails.
 
@@ -35,8 +37,10 @@ typecheck fails.
 
 1. **Define the schema with `defineBlock`, never `defineType`.**
    `lib/integrations/sanity/schemas/shared/block.ts` implies
-   `type: "document"` and appends Anchor ID + Presentation Mode as the last two
-   fields:
+   `type: "object"` and appends Anchor ID + Presentation Mode as the last two
+   fields. The array member's type name is the block's `_type`, so the schema
+   name is also what the registry, the insert menu and the fixture library key
+   off:
 
    ```ts
    import { defineField } from "sanity"
@@ -123,7 +127,15 @@ typecheck fails.
    `SANITY_LAYOUT_TAGS` (`fetchers/layout.ts`, or `tags.ts` on the Cache
    Components variant), same as navbar and footer.
 
-5. **Regenerate types after a schema change:** `bun run sanity:typegen`. The
+5. **Ship a fixture in `components/page-builder/library.ts`.** One entry per
+   block: a stand-in value typed as the block's *query result* (so a schema or
+   projection change breaks the fixture at typecheck), a one-line note and a
+   stage background. That entry is the block's only preview — the live pane in
+   the insert menu, its row in Studio → Components and the `/components` route
+   all render it through the production renderer. Nothing needs adding to
+   `structure.ts`.
+
+6. **Regenerate types after a schema change:** `bun run sanity:typegen`. The
    page query spreads `...` for non-gated blocks, so new fields flow through
    automatically — except `gatedContent`, whose GROQ branch lists fields
    explicitly (`lib/integrations/sanity/queries.ts`). Add new fields there by
@@ -131,20 +143,21 @@ typecheck fails.
 
 ## Checklist for a new block
 
-- [ ] Schema in `schemas/components/reusable/<block>.ts` (or `singleton/` for a
-      one-instance block), built with `defineBlock` and carrying a `preview`.
+- [ ] Schema in `schemas/components/reusable/<block>.ts`, built with
+      `defineBlock` and carrying a `preview`.
 - [ ] Icon in `lib/integrations/sanity/icons.ts` (phosphor duotone).
 - [ ] Exported from `schemas/components/index.ts` and registered in
       `schemas/index.ts` (`schema.types`).
 - [ ] Member added to `page-builder-config.ts`: the `PageBuilderDocumentType`
-      union plus an entry in `reusablePageBuilderReferenceMembers` carrying
-      **both** axes — `pageTypes` (which page documents may host it) and
-      `category` (what the block is, one of `componentCategories`; `misc` only
-      when nothing fits).
-- [ ] Listed in `structure.ts` under the right folder.
+      union plus an entry in `pageBuilderBlockMembers` carrying **both** axes —
+      `pageTypes` (which page documents may host it) and `category` (what the
+      block is, one of `componentCategories`; `misc` only when nothing fits).
 - [ ] Component in `components/page-builder/components/<block>.tsx`, typed with
       `Extract<PageBuilderBlock, { _type: "<block>" }>`, no outer section, no
       vertical padding. Variants via `cva`/`cn` when the block has variants.
 - [ ] Entry in `components/page-builder/registry.tsx`, with `isEmpty` when the
       block can be left unfilled.
+- [ ] Fixture in `components/page-builder/library.ts`, typed as the block's
+      query result. It is the block's preview everywhere, so nothing needs
+      adding to `structure.ts`.
 - [ ] `bun run sanity:typegen && bun run typecheck && bun run lint && bun run build && bun run knip`.

package/src/modules/features/cms/sanity/files/app/layout.tsx

@@ -9,13 +9,13 @@ import { fontsVariable } from "@/lib/styles/fonts";
 import AppData from "@/package.json";
 import "@/lib/styles/css/index.css";
 import { cn } from "@/lib/styles/cn";
+import { getBaseUrl } from "@/lib/utils/url";
 
 const APP_NAME = AppData.name;
 const APP_DEFAULT_TITLE = "Basement Starter";
 const APP_TITLE_TEMPLATE = "%s - Basement Starter";
 const APP_DESCRIPTION = AppData.description;
-const APP_BASE_URL =
-	process.env.NEXT_PUBLIC_BASE_URL ?? "http://localhost:3000";
+const APP_BASE_URL = getBaseUrl();
 
 const geist = Geist({
 	subsets: ["latin"],

package/src/modules/features/cms/sanity/files/lib/utils/metadata.ts

@@ -1,4 +1,5 @@
 import type { Metadata } from "next";
+import { getBaseUrl } from "@/lib/utils/url";
 
 /**
  * Metadata Generation Utilities
@@ -26,8 +27,7 @@ interface GenerateMetadataOptions {
 	authors?: string[];
 }
 
-const APP_BASE_URL =
-	process.env.NEXT_PUBLIC_BASE_URL ?? "http://localhost:3000";
+const APP_BASE_URL = getBaseUrl();
 
 /**
  * Generate complete metadata object for pages

package/src/modules/features/cms/sanity/files/lib/utils/url.ts

@@ -3,15 +3,18 @@
  *
  * Priority:
  * 1. NEXT_PUBLIC_BASE_URL  - explicit override (custom domains)
- * 2. VERCEL_PROJECT_PRODUCTION_URL - auto-set by Vercel (production domain)
- * 3. VERCEL_URL - auto-set by Vercel (preview/branch deploys)
+ * 2. VERCEL_PROJECT_PRODUCTION_URL - auto-set by Vercel, on production deployments only
+ * 3. VERCEL_URL - the deployment's own URL, so previews never emit production URLs
  * 4. localhost fallback
  */
 export function getBaseUrl(): string {
 	if (process.env.NEXT_PUBLIC_BASE_URL) {
 		return process.env.NEXT_PUBLIC_BASE_URL;
 	}
-	if (process.env.VERCEL_PROJECT_PRODUCTION_URL) {
+	if (
+		process.env.VERCEL_ENV === "production" &&
+		process.env.VERCEL_PROJECT_PRODUCTION_URL
+	) {
 		return `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}`;
 	}
 	if (process.env.VERCEL_URL) return `https://${process.env.VERCEL_URL}`;

package/src/modules/features/cms/sanity-pagebuilder/files/app/api/revalidate/route.ts

@@ -8,7 +8,7 @@ import { parseBody } from "next-sanity/webhook";
 import { directClient } from "@/lib/integrations/sanity/client";
 import { SANITY_LAYOUT_TAGS } from "@/lib/integrations/sanity/fetchers/layout";
 import { SANITY_REDIRECTS_TAG } from "@/lib/integrations/sanity/fetchers/redirects";
-import { pageBuilderReferenceMembers as pbrm } from "@/lib/integrations/sanity/page-builder-config";
+import { pageBuilderBlockMembers } from "@/lib/integrations/sanity/page-builder-config";
 import {
 	FOLDER_PATH_QUERY,
 	P_REF_DOC_PAGES_QUERY,
@@ -63,7 +63,7 @@ type RevalidateWebhookBody = WebhookDocument & {
 };
 
 const referenceableTypes = new Set<string>([
-	...pbrm.map((m) => m.documentType),
+	...pageBuilderBlockMembers.map((member) => member.documentType),
 	...REFERENCEABLE_TYPES,
 ]);
 

package/src/modules/features/cms/sanity-pagebuilder/files/components/sanity/rich-text.tsx

@@ -4,7 +4,7 @@ import { SanityImage } from "@/components/ui/sanity-image";
 import {
 	getLinkAttributes,
 	urlForReference,
-} from "../../lib/integrations/sanity/utils/link";
+} from "@/lib/integrations/sanity/utils/link";
 
 interface RichTextProps {
 	content: PortableTextProps["value"];
@@ -80,7 +80,9 @@ export const RichText = ({ content }: RichTextProps) => {
 					externalLink: LinkMark,
 				},
 				block: {
-					h1: ({ children }) => <h1 className="h1">{children}</h1>,
+					// The h1 style is retired: the page owns its H1, so legacy content
+					// drops a level.
+					h1: ({ children }) => <h2 className="h2">{children}</h2>,
 					h2: ({ children }) => <h2 className="h2">{children}</h2>,
 					h3: ({ children }) => <h3 className="h3">{children}</h3>,
 					h4: ({ children }) => <h4 className="h4">{children}</h4>,