bsmnt 0.12.0 → 0.13.1

package/src/templates/next-default/lib/utils/image-sizes.ts

@@ -15,40 +15,55 @@ export type ByBreakpoint<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
 > = { base: T } & Partial<Record<Extract<keyof B, string>, T>>
 
+export type ImageSizesOptions<
+  B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
+> = { breakpoints?: B }
+
+export type GridImageSizesOptions<
+  B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
+> = ImageSizesOptions<B> & {
+  /** The grid container's `max-width` in px, past which columns stop growing. */
+  maxWidth?: number
+}
+
+type Condition<T> = { min: number; value: T }
+
 function columnWidth(columns: number): string {
   return `${Math.round(100 / columns)}vw`
 }
 
+function toConditions<T>(
+  overrides: Readonly<Record<string, T | undefined>>,
+  scale: BreakpointMap
+): Condition<T>[] {
+  return Object.entries(overrides).flatMap(([name, value]) => {
+    const min = scale[name]
+    return value !== undefined && min !== undefined ? [{ min, value }] : []
+  })
+}
+
 /**
  * Widest first, since `sizes` takes the first matching condition and the last
  * entry must be bare. `min-width` matches the Tailwind variant's boundary; a
  * `max-width: <next> - 1` one would leave a fractional-pixel gap.
  */
-function toSizes(
-  base: string,
-  overrides: Readonly<Record<string, string | undefined>>,
-  scale: BreakpointMap
-): string {
-  const conditions: string[] = []
-
-  for (const [name, min] of Object.entries(scale).sort(
-    ([, a], [, b]) => b - a
-  )) {
-    const value = overrides[name]
-    if (value !== undefined) {
-      conditions.push(`(min-width: ${min}px) ${value}`)
-    }
-  }
+function joinSizes(base: string, conditions: Condition<string>[]): string {
+  const sorted = [...conditions].sort((a, b) => b.min - a.min)
 
-  return [...conditions, base].join(", ")
+  return [
+    ...sorted.map(({ min, value }) => `(min-width: ${min}px) ${value}`),
+    base,
+  ].join(", ")
 }
 
 /** Builds `sizes` from the CSS length the image renders at per breakpoint. */
 export function buildImageSizes<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
->(widths: ByBreakpoint<string, B>, breakpoints?: B): string {
+>(widths: ByBreakpoint<string, B>, options: ImageSizesOptions<B> = {}): string {
   const { base, ...overrides } = widths
-  return toSizes(base, overrides, breakpoints ?? BASEMENT_BREAKPOINTS)
+  const scale = options.breakpoints ?? BASEMENT_BREAKPOINTS
+
+  return joinSizes(base, toConditions<string>(overrides, scale))
 }
 
 /**
@@ -58,15 +73,39 @@ export function buildImageSizes<
  */
 export function buildGridImageSizes<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
->(columns: ByBreakpoint<number, B>, breakpoints?: B): string {
+>(
+  columns: ByBreakpoint<number, B>,
+  options: GridImageSizesOptions<B> = {}
+): string {
+  const { maxWidth, breakpoints } = options
   const { base, ...overrides } = columns
-  const widths: Record<string, string> = {}
+  const steps = toConditions<number>(
+    overrides,
+    breakpoints ?? BASEMENT_BREAKPOINTS
+  )
+  const cap =
+    maxWidth !== undefined && Number.isFinite(maxWidth) && maxWidth > 0
+      ? maxWidth
+      : undefined
+
+  // The cap rarely lands on a breakpoint, so it needs its own condition.
+  if (cap !== undefined && !steps.some(({ min }) => min === cap)) {
+    const below = steps
+      .filter(({ min }) => min < cap)
+      .sort((a, b) => a.min - b.min)
+      .at(-1)
 
-  for (const [name, count] of Object.entries(overrides)) {
-    if (count !== undefined) {
-      widths[name] = columnWidth(count)
-    }
+    steps.push({ min: cap, value: below?.value ?? base })
   }
 
-  return toSizes(columnWidth(base), widths, breakpoints ?? BASEMENT_BREAKPOINTS)
+  return joinSizes(
+    columnWidth(base),
+    steps.map(({ min, value }) => ({
+      min,
+      value:
+        cap !== undefined && min >= cap
+          ? `${Math.round(cap / value)}px`
+          : columnWidth(value),
+    }))
+  )
 }

package/src/templates/next-experiments/lib/utils/README.md

@@ -45,6 +45,7 @@ export const metadata = generatePageMetadata({ title: 'About' })
 // next/image sizes — keys mirror the element's Tailwind variants
 buildImageSizes({ base: '100vw', desktop: '796px' })
 buildGridImageSizes({ base: 1, tablet: 2, desktop: 3 })
+buildGridImageSizes({ base: 1, tablet: 2, desktop: 3 }, { maxWidth: 1440 })
 
 // Refs — in a component, use the hook: an inline mergeRefs([...]) is a new
 // callback each render, so React detaches and reattaches every ref.

package/src/templates/next-experiments/lib/utils/image-sizes.ts

@@ -15,40 +15,55 @@ export type ByBreakpoint<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
 > = { base: T } & Partial<Record<Extract<keyof B, string>, T>>
 
+export type ImageSizesOptions<
+  B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
+> = { breakpoints?: B }
+
+export type GridImageSizesOptions<
+  B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
+> = ImageSizesOptions<B> & {
+  /** The grid container's `max-width` in px, past which columns stop growing. */
+  maxWidth?: number
+}
+
+type Condition<T> = { min: number; value: T }
+
 function columnWidth(columns: number): string {
   return `${Math.round(100 / columns)}vw`
 }
 
+function toConditions<T>(
+  overrides: Readonly<Record<string, T | undefined>>,
+  scale: BreakpointMap
+): Condition<T>[] {
+  return Object.entries(overrides).flatMap(([name, value]) => {
+    const min = scale[name]
+    return value !== undefined && min !== undefined ? [{ min, value }] : []
+  })
+}
+
 /**
  * Widest first, since `sizes` takes the first matching condition and the last
  * entry must be bare. `min-width` matches the Tailwind variant's boundary; a
  * `max-width: <next> - 1` one would leave a fractional-pixel gap.
  */
-function toSizes(
-  base: string,
-  overrides: Readonly<Record<string, string | undefined>>,
-  scale: BreakpointMap
-): string {
-  const conditions: string[] = []
-
-  for (const [name, min] of Object.entries(scale).sort(
-    ([, a], [, b]) => b - a
-  )) {
-    const value = overrides[name]
-    if (value !== undefined) {
-      conditions.push(`(min-width: ${min}px) ${value}`)
-    }
-  }
+function joinSizes(base: string, conditions: Condition<string>[]): string {
+  const sorted = [...conditions].sort((a, b) => b.min - a.min)
 
-  return [...conditions, base].join(", ")
+  return [
+    ...sorted.map(({ min, value }) => `(min-width: ${min}px) ${value}`),
+    base,
+  ].join(", ")
 }
 
 /** Builds `sizes` from the CSS length the image renders at per breakpoint. */
 export function buildImageSizes<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
->(widths: ByBreakpoint<string, B>, breakpoints?: B): string {
+>(widths: ByBreakpoint<string, B>, options: ImageSizesOptions<B> = {}): string {
   const { base, ...overrides } = widths
-  return toSizes(base, overrides, breakpoints ?? BASEMENT_BREAKPOINTS)
+  const scale = options.breakpoints ?? BASEMENT_BREAKPOINTS
+
+  return joinSizes(base, toConditions<string>(overrides, scale))
 }
 
 /**
@@ -58,15 +73,39 @@ export function buildImageSizes<
  */
 export function buildGridImageSizes<
   B extends BreakpointMap = typeof BASEMENT_BREAKPOINTS,
->(columns: ByBreakpoint<number, B>, breakpoints?: B): string {
+>(
+  columns: ByBreakpoint<number, B>,
+  options: GridImageSizesOptions<B> = {}
+): string {
+  const { maxWidth, breakpoints } = options
   const { base, ...overrides } = columns
-  const widths: Record<string, string> = {}
+  const steps = toConditions<number>(
+    overrides,
+    breakpoints ?? BASEMENT_BREAKPOINTS
+  )
+  const cap =
+    maxWidth !== undefined && Number.isFinite(maxWidth) && maxWidth > 0
+      ? maxWidth
+      : undefined
+
+  // The cap rarely lands on a breakpoint, so it needs its own condition.
+  if (cap !== undefined && !steps.some(({ min }) => min === cap)) {
+    const below = steps
+      .filter(({ min }) => min < cap)
+      .sort((a, b) => a.min - b.min)
+      .at(-1)
 
-  for (const [name, count] of Object.entries(overrides)) {
-    if (count !== undefined) {
-      widths[name] = columnWidth(count)
-    }
+    steps.push({ min: cap, value: below?.value ?? base })
   }
 
-  return toSizes(columnWidth(base), widths, breakpoints ?? BASEMENT_BREAKPOINTS)
+  return joinSizes(
+    columnWidth(base),
+    steps.map(({ min, value }) => ({
+      min,
+      value:
+        cap !== undefined && min >= cap
+          ? `${Math.round(cap / value)}px`
+          : columnWidth(value),
+    }))
+  )
 }

package/src/templates/next-pagebuilder/AGENTS.md

@@ -0,0 +1,129 @@
+# AGENTS.md
+
+Instructions for AI agents working in this repository. Human-facing setup,
+environment variables and the publish webhook live in the README — read it too.
+
+This is a **Next.js + Sanity page builder**: all URL structure is managed in
+Sanity, not in code, and a single catch-all route `[[...slug]]` renders every
+page.
+
+**Never add a page route under `app/`.** A new page is a `page` document in the
+Studio with a slug, not a directory. `app/(content)/[[...slug]]/page.tsx`
+resolves every one of them; a hand-written route shadows that resolver and
+becomes a URL no editor can see, move or delete. The only things that belong in
+`app/` are non-page endpoints — the Studio, API handlers, sitemap, feed.
+
+## Page-builder blocks
+
+**A block is `defineBlock` + a registry entry.** Define the schema with
+`defineBlock` (`lib/integrations/sanity/schemas/shared/block.ts`), never
+`defineType` — it implies `type: "document"` and appends **Anchor ID** and
+**Presentation Mode** for you. Register the component in
+`components/page-builder/registry.tsx`; the renderer is driven by that map, so
+there is no switch to extend.
+
+Both halves are enforced, not documented: the registry's key set is typed as
+exactly `PageBuilderDocumentType`, so a block registered in
+`page-builder-config.ts` without an entry there — or an entry there for a block
+that was never registered — is a typecheck error.
+
+**Every block declares two orthogonal axes** in `page-builder-config.ts`:
+`pageTypes` (which page documents may host it — drives validation) and
+`category` (what the block structurally is, one of `componentCategories` —
+drives the insert menu; `misc` only when nothing else fits). Never collapse them
+into one field: that is what made the menu a single flat list.
+
+**And a preview image.** The insert menu renders one tile per block from a
+`studioPreview` document (Components → Component Previews) keyed
+`block.<memberName>`. A block without one falls back to its schema icon, which
+is what made the old menu unreadable.
+
+**Never hardcode vertical padding in a block component.** The renderer wraps
+each block in `<Section>` (`components/page-builder/section.tsx`), which owns
+the `<section>` element, the anchor `id`, `scroll-mt` and the responsive padding
+top/bottom. A block component returns its content only — no outer `<section>`,
+no `py-*` / `pt-*` / `pb-*` on its root. Internal gaps between a block's own
+parts are fine.
+
+**Never hardcode px for section spacing either.** The scale lives in the Studio
+at **Layout → Spacing Scale**, where editors add or rename steps and mark one as
+the default, and it reaches the page as CSS custom properties. `Section` only
+references `var(--section-space-<key>, var(--section-space-default, 2.5rem))`.
+
+**An empty Anchor ID is generated from the block's title** (`headline` /
+`heading` / `teaserHeading` / `title` / `label` — never `internalTitle`, which is
+Studio-only) and de-duplicated per page. Name your block's headline field one of
+those and anchor links work for free.
+
+Declare `isEmpty` in the registry when a block can be left unfilled — the
+renderer then skips the block *and* its `<Section>`, so it leaves no padded gap
+and claims no anchor id. Don't early-return `null` from the component instead;
+the renderer has to know before it wraps anything.
+
+Full recipe and a checklist for a new block: the `page-builder-block` skill, or
+the "Page-builder blocks" section of the README.
+
+## Sanity
+
+- Everything Sanity lives in `lib/integrations/sanity/`.
+- Schemas use `defineType` / `defineField` / `defineArrayMember` (blocks use
+  `defineBlock`). GROQ queries are `SCREAMING_SNAKE_CASE` and wrapped in
+  `defineQuery`.
+- **Regenerate types after any schema or query change:** `bun sanity:typegen`,
+  and commit the result in the same PR. Never hand-edit `sanity.types.ts`.
+- The page query spreads `...` for non-gated blocks, so new block fields flow
+  through on their own — except `gatedContent`, whose GROQ branch lists fields
+  explicitly in `lib/integrations/sanity/queries.ts`. Add fields there by hand.
+- Read through `sanityFetch` / `fetchSanity`, not a bare client, so the
+  draft-mode perspective and cache tags are applied.
+- Publishing a document must invalidate what renders it. Layout singletons are
+  listed in `SANITY_LAYOUT_TAGS`; a new one that isn't there serves stale.
+- Add `data-sanity` attributes where visual editing should reach.
+- Nested layouts (e.g. `app/studio/layout.tsx`) must NOT render `<html>` or
+  `<body>` — the root layout already provides them.
+
+## React and Next.js
+
+- **React Compiler is on.** Do not write `useMemo`, `useCallback` or
+  `React.memo`. The one exception is `useRef` to instantiate an object once:
+
+  ```tsx
+  const instanceRef = useRef<SomeClass | null>(null)
+  if (!instanceRef.current) instanceRef.current = new SomeClass()
+  ```
+
+- React 19: refs are regular props, so no `forwardRef` (a lint rule enforces it).
+- **Never call `headers()`, `cookies()`, `draftMode()` or read `searchParams` in
+  a root layout** — it takes the whole page out of the prerender. Detect the
+  route with `useSelectedLayoutSegment()` in a `"use client"` wrapper, and put
+  draft-mode / visual-editing behaviour in a child component with its own
+  `<Suspense>` boundary.
+- Use `@/components/ui/image` rather than `next/image` directly, and
+  `@/components/ui/sanity-image` for Sanity assets.
+- Compose classNames with `cn` from `@/lib/styles/cn`.
+- Import with the `@/` alias; relative parent imports are a lint error.
+- Gate debug UI behind `process.env.NODE_ENV === "development"` — it is not
+  stripped in production otherwise.
+
+## House rules
+
+- **Bun only.** `bun install`, `bun run <script>`, `bunx`. Never npm, pnpm or
+  yarn — a second lockfile next to `bun.lock` is how the versions drift.
+- **Don't add a dependency without asking.** Check `bun info <package>` and the
+  current docs first.
+<!-- bsmnt:if dotenvx -->
+- **Secrets are encrypted at rest with dotenvx.** Never put a real secret in
+  plaintext in a committed env file — gitleaks blocks the commit. Use
+  `bun env:set KEY value` (`--plain` for trivial config and `NEXT_PUBLIC_*`).
+  The `manage-env` skill has the full procedure.
+<!-- bsmnt:endif -->
+- Don't leave commented-out code or `TODO`s behind; write the code so it reads
+  without them.
+- **Verify before claiming done:**
+
+  ```bash
+  bun sanity:typegen && bun typecheck && bun lint && bun run build && bun knip
+  ```
+
+  (`bun run build`, not `bun build` — the bare form is Bun's bundler.) Say what
+  you ran and what it printed; don't report success you haven't seen.

package/src/templates/next-pagebuilder/CLAUDE.md

@@ -0,0 +1,3 @@
+# CLAUDE.md
+
+@AGENTS.md

package/src/templates/next-pagebuilder/README.md

@@ -12,9 +12,79 @@ bun dev
 
 - Single catch-all route `[[...slug]]` handles all pages
 - Sanity page builder with composable content blocks
+- Editor-owned vertical spacing scale and per-block anchor links
 - Blog with categories, filtering, and pagination
 - Visual editing and live preview support
 
+## Page-builder blocks
+
+A block is two halves — a schema document and a React component — and each half
+has one place that makes it a block rather than an ordinary document or a loose
+component. Use them and Anchor ID, Presentation Mode and the spacing scale come
+for free.
+
+**Define the schema with `defineBlock`, never `defineType`**
+(`lib/integrations/sanity/schemas/shared/block.ts`). It implies
+`type: "document"` and appends two fields to every block:
+
+- **Anchor ID** — optional. Left empty, the anchor is generated from the block's
+  own title at render time (`headline` / `heading` / `teaserHeading` / `title` /
+  `label` — never `internalTitle`, which is Studio-only) and de-duplicated per
+  page, so two blocks with the same heading get `-2`. A value typed by hand
+  always wins, and the Studio shows the generated one as the placeholder. Link
+  to it as `/<page>#<anchor>`.
+- **Presentation Mode** — padding top and bottom, each picked from the shared
+  spacing scale. No free-form px. A block that never touches it follows whichever
+  step is marked as the default.
+
+Blocks that declare `groups` get a **Presentation** tab for both fields
+automatically — don't list it in `groups` yourself.
+
+**Register the component in `components/page-builder/registry.tsx`.** One entry
+per block, keyed by schema type; the renderer is driven by that map, so there is
+no switch to extend. `isEmpty` declares when a block has nothing to show — the
+renderer then skips the block *and* its `<Section>`, so an unfilled block leaves
+no padded gap behind and claims no anchor id. The registry's key set is typed as
+exactly `PageBuilderDocumentType`, so a block registered in one place and not the
+other is a typecheck error.
+
+**Never hardcode vertical padding in a block component.** The renderer wraps each
+block in `<Section>` (`components/page-builder/section.tsx`), which owns the
+`<section>` element, the anchor `id`, `scroll-mt` and the padding. A block
+component returns its content only — no outer `<section>`, no `py-*` / `pt-*` /
+`pb-*` on its root. Internal gaps between a block's own parts are fine.
+
+### The spacing scale is content, not code
+
+Editors own it at **Layout → Spacing Scale**: a list of steps, each with a name
+and px per breakpoint (mobile / tablet / desktop, empty reuses Desktop), one
+marked as the default. Ticking a second step as default unticks the previous, so
+there is always exactly one. Add a "Hero 120px" step and it shows up in every
+block's dropdown, no deploy.
+
+- Blocks store the step's `_key`, so renaming a step breaks nothing and a deleted
+  step degrades to the default instead of breaking the page.
+- The list arrives seeded with the built-in five (XS 16 · SM 24 · **MD 32,
+  default** · LG 48 · XL 80, from `schemas/shared/spacing.ts`), which also apply
+  as the fallback if you empty it. Hit **"Add the built-in steps"** in the field
+  to get them back as editable rows.
+- Values reach the page as CSS custom properties injected server-side by
+  `components/layout/spacing-scale/`, one `--section-space-<key>` per step plus
+  `--section-space-default`, re-declared inside the `768px` and `1440px` media
+  queries. `Section` only ever references
+  `var(--section-space-<key>, var(--section-space-default, 2.5rem))`, so an
+  unknown key degrades instead of breaking.
+- `spacingSettings` is a layout singleton, so publishing it busts the layout
+  cache the same way navbar and footer do.
+
+After a schema change run `bun sanity:typegen`. The page query spreads `...` for
+non-gated blocks, so new fields flow through on their own — except
+`gatedContent`, whose GROQ branch lists fields explicitly in
+`lib/integrations/sanity/queries.ts`.
+
+The bundled `page-builder-block` agent skill has the full recipe and a checklist
+for adding a new block.
+
 ## Commands
 
 - `bun dev` - Start dev server

package/src/templates/next-pagebuilder/app/(content)/layout.tsx

@@ -1,10 +1,12 @@
 import { JsonLd } from "@/components/layout/json-ld"
+import { SpacingScale } from "@/components/layout/spacing-scale"
 import { Wrapper } from "@/components/layout/wrapper"
 import { SanityVisualEditing } from "@/components/sanity/visual-editing"
 
 const Layout = ({ children }: { children: React.ReactNode }) => {
   return (
     <>
+      <SpacingScale />
       <JsonLd />
       <Wrapper>{children}</Wrapper>
       <SanityVisualEditing />

package/src/templates/next-pagebuilder/components/layout/spacing-scale/index.tsx

@@ -0,0 +1,18 @@
+import { getLayoutData } from "@/lib/integrations/sanity/fetchers/layout"
+import {
+  resolveSpacingSteps,
+  spacingScaleCss,
+} from "@/lib/integrations/sanity/schemas/shared/spacing"
+
+export const SpacingScale = async () => {
+  const { spacingSettings } = await getLayoutData()
+
+  return (
+    <style
+      // biome-ignore lint/security/noDangerouslySetInnerHtml: css custom properties from the spacing singleton
+      dangerouslySetInnerHTML={{
+        __html: spacingScaleCss(resolveSpacingSteps(spacingSettings?.steps)),
+      }}
+    />
+  )
+}

package/src/templates/next-pagebuilder/components/page-builder/components/article-content/index.tsx

@@ -7,7 +7,7 @@ import { RelatedPostItem } from "./related-post-item"
 export function ArticleContent({ block }: ArticleContentProps) {
   const { author, body, categories, date, relatedPosts, thumbnail } = block
   return (
-    <div className="py-8 md:py-12">
+    <div>
       <header className="mx-auto max-w-3xl space-y-6">
         {categories && categories.length > 0 ? (
           <div className="flex flex-wrap gap-2">

package/src/templates/next-pagebuilder/components/page-builder/components/content-collection/index.tsx

@@ -239,11 +239,11 @@ async function CollectionResults({
 // clickable before the grid resolves.
 export function ContentCollection(props: ContentCollectionProps) {
   return (
-    <section className="flex flex-col gap-8 py-8">
+    <div className="flex flex-col gap-8">
       <CollectionToolbar pinnedCategory={props.pinnedCategory} />
       <Suspense fallback={<CollectionResultsSkeleton />}>
         <CollectionResults {...props} />
       </Suspense>
-    </section>
+    </div>
   )
 }

package/src/templates/next-pagebuilder/components/page-builder/components/description.tsx

@@ -5,13 +5,9 @@ type DescriptionProps = {
 }
 
 export function Description({ block }: DescriptionProps) {
-  if (!block.description) return null
-
   return (
-    <section className="py-4">
-      <p className="max-w-[62ch] text-base/7 text-current/72 md:text-lg/8">
-        {block.description}
-      </p>
-    </section>
+    <p className="max-w-[62ch] text-base/7 text-current/72 md:text-lg/8">
+      {block.description}
+    </p>
   )
 }

package/src/templates/next-pagebuilder/components/page-builder/components/gated-content/index.tsx

@@ -64,7 +64,7 @@ export function GatedContent({ block }: GatedContentProps) {
   }
 
   return (
-    <section className="py-8 md:py-12">
+    <div>
       {block.teaserHeading ? (
         <h2 className="mb-4 font-semibold text-2xl tracking-tight md:text-4xl">
           {block.teaserHeading}
@@ -114,7 +114,7 @@ export function GatedContent({ block }: GatedContentProps) {
           </button>
         </form>
       )}
-    </section>
+    </div>
   )
 }
 

package/src/templates/next-pagebuilder/components/page-builder/components/hero.tsx

@@ -5,13 +5,9 @@ type HeroProps = {
 }
 
 export function Hero({ block }: HeroProps) {
-  if (!block.headline) return null
-
   return (
-    <section className="py-8 md:py-12">
-      <h1 className="max-w-4xl font-semibold text-4xl tracking-tight md:text-6xl">
-        {block.headline}
-      </h1>
-    </section>
+    <h1 className="max-w-4xl font-semibold text-4xl tracking-tight md:text-6xl">
+      {block.headline}
+    </h1>
   )
 }

package/src/templates/next-pagebuilder/components/page-builder/components/rich-text-block.tsx

@@ -1,16 +1,14 @@
-import { RichText } from "@/components/sanity/rich-text"
 import type { PageBuilderBlock } from "@/components/page-builder/types"
+import { RichText } from "@/components/sanity/rich-text"
 
 type RichTextBlockProps = {
   block: Extract<PageBuilderBlock, { _type: "richTextBlock" }>
 }
 
 export function RichTextBlock({ block }: RichTextBlockProps) {
-  if (!block.content) return null
-
   return (
-    <section className="prose max-w-none">
+    <div className="prose max-w-none">
       <RichText content={block.content} />
-    </section>
+    </div>
   )
 }

package/src/templates/next-pagebuilder/components/page-builder/registry.tsx

@@ -0,0 +1,70 @@
+import type { ReactNode } from "react"
+import type { PageBuilderDocumentType } from "@/lib/integrations/sanity/page-builder-config"
+import { ArticleContent } from "./components/article-content"
+import { ContentCollection } from "./components/content-collection"
+import type {
+  ContentCollectionSearchParams,
+  PinnedCollectionCategory,
+} from "./components/content-collection/types"
+import { Description } from "./components/description"
+import { GatedContent } from "./components/gated-content"
+import { Hero } from "./components/hero"
+import { RichTextBlock } from "./components/rich-text-block"
+import type { PageBuilderBlock } from "./types"
+
+export type BlockContext = {
+  searchParams: ContentCollectionSearchParams
+  pinnedCategory: PinnedCollectionCategory
+}
+
+type BlockOf<T extends PageBuilderDocumentType> = Extract<
+  PageBuilderBlock,
+  { _type: T }
+>
+
+type BlockEntry<T extends PageBuilderDocumentType> = {
+  render: (block: BlockOf<T>, context: BlockContext) => ReactNode
+  /** Skips the block *and* its `<Section>`, so no padded gap is left behind. */
+  isEmpty?: (block: BlockOf<T>) => boolean
+}
+
+const blockRegistry: {
+  [T in PageBuilderDocumentType]: BlockEntry<T>
+} = {
+  blogCollection: {
+    render: (block, { searchParams, pinnedCategory }) => (
+      <ContentCollection
+        block={block}
+        pinnedCategory={pinnedCategory}
+        searchParams={searchParams}
+      />
+    ),
+  },
+  blogContent: {
+    render: (block) => <ArticleContent block={block} />,
+  },
+  description: {
+    render: (block) => <Description block={block} />,
+    isEmpty: (block) => !block.description,
+  },
+  gatedContent: {
+    render: (block) => <GatedContent block={block} />,
+  },
+  hero: {
+    render: (block) => <Hero block={block} />,
+    isEmpty: (block) => !block.headline,
+  },
+  richTextBlock: {
+    render: (block) => <RichTextBlock block={block} />,
+    isEmpty: (block) => !block.content?.length,
+  },
+}
+
+/**
+ * Indexing the registry with the union collapses its per-key signatures into an
+ * intersection nothing satisfies, so the widening happens once, here.
+ */
+export const getBlockEntry = (
+  type: PageBuilderDocumentType
+): BlockEntry<PageBuilderDocumentType> | undefined =>
+  blockRegistry[type] as BlockEntry<PageBuilderDocumentType> | undefined