ferst-core 0.6.2 → 0.7.2

package/content/blocks.ts

@@ -1,719 +1,775 @@
-import { z } from 'zod';
-
-/**
- * The block palette — the heart of the Ferst page model (see
- * docs/BLOCK-ARCHITECTURE.md). A page is an ordered list of typed blocks stored
- * as JSON; a Zod **discriminated union** on `type` is the single contract the AI
- * composes against, the CMS validates, and the renderer's registry keys on.
- *
- * This is an original design of the *mechanism*, built from scratch. It starts
- * with **Level-1 primitives** only; recipes (Level 2) and
- * page templates (Level 3) layer on top later, and layout/container primitives
- * (Section/Grid/Stack, which nest child blocks) are a deliberate next slice.
- */
-
-/** Every block shares a `type` discriminant and an `enabled` flag (keep a block
- *  in the page data without rendering it). */
-export const headingBlock = z.object({
-  type: z.literal('heading'),
-  enabled: z.boolean().default(true),
-  text: z.string(),
-  level: z.number().int().min(1).max(6).default(2),
-  /** Explicit per-heading alignment. OMITTED ⇒ inherit the page/section
-   *  `--content-align` cascade; set it only to override for this one heading. */
-  align: z.enum(['start', 'center', 'end']).optional(),
-  /** Paint the text with a brand → accent-2 gradient (falls back to solid ink
-   *  where background-clip:text is unsupported). A per-block opt-in effect. */
-  gradient: z.boolean().default(false),
-});
-
-export const proseBlock = z.object({
-  type: z.literal('prose'),
-  enabled: z.boolean().default(true),
-  /** Plain text; blank lines separate paragraphs. Markdown rendering is a later
-   *  upgrade to this same block — the field stays `text`. */
-  text: z.string(),
-});
-
-export const imageBlock = z.object({
-  type: z.literal('image'),
-  enabled: z.boolean().default(true),
-  src: z.string(),
-  alt: z.string().default(''),
-  caption: z.string().optional(),
-  /** Canonical framing options — a small, clear set the AI or a client picks
-   *  from, rather than free-form CSS. Corners follow the site by default. */
-  radius: z.enum(['none', 'soft', 'round']).default('soft'),
-  shadow: z.boolean().default(false),
-  border: z.boolean().default(false),
-  ratio: z.enum(['auto', 'square', '4/3', '3/2', '16/9', '21/9']).default('auto'),
-  /** Opt in to a soft clip-path reveal as the image scrolls into view
-   *  (progressive: no motion under reduced-motion or unsupported browsers). */
-  reveal: z.boolean().default(false),
-});
-
-export const buttonBlock = z.object({
-  type: z.literal('button'),
-  enabled: z.boolean().default(true),
-  label: z.string(),
-  href: z.string(),
-  /** Role, not decoration: primary action, secondary action, filled CTA, or a
-   *  quiet ghost. Shape (radius) is a site-wide token, not a per-button choice. */
-  variant: z.enum(['primary', 'secondary', 'cta', 'ghost']).default('primary'),
-});
-
-export const quoteBlock = z.object({
-  type: z.literal('quote'),
-  enabled: z.boolean().default(true),
-  text: z.string(),
-  cite: z.string().optional(),
-});
-
-export const dividerBlock = z.object({
-  type: z.literal('divider'),
-  enabled: z.boolean().default(true),
-});
-
-export const spacerBlock = z.object({
-  type: z.literal('spacer'),
-  enabled: z.boolean().default(true),
-  size: z.enum(['sm', 'md', 'lg']).default('md'),
-});
-
-export const badgeBlock = z.object({
-  type: z.literal('badge'),
-  enabled: z.boolean().default(true),
-  text: z.string(),
-  tone: z.enum(['neutral', 'accent']).default('accent'),
-});
-
-export const statBlock = z.object({
-  type: z.literal('stat'),
-  enabled: z.boolean().default(true),
-  value: z.string(),
-  label: z.string(),
-});
-
-export const listBlock = z.object({
-  type: z.literal('list'),
-  enabled: z.boolean().default(true),
-  /** bullet (disc) · number (ordered) · check (ticked, uses the check icon). */
-  style: z.enum(['bullet', 'number', 'check']).default('bullet'),
-  items: z.array(z.string()).default([]),
-});
-
-/* ── Level 2 — Recipes (curated, opinionated compositions of primitives) ─────
- * A recipe is a first-class block in the same union, but it renders a *designed*
- * layout (composing primitives internally) rather than a bare element. Locked
- * components so quality can't drift (BLOCK-ARCHITECTURE §6). */
-export const heroBlock = z.object({
-  type: z.literal('hero'),
-  enabled: z.boolean().default(true),
-  eyebrow: z.string().optional(),
-  title: z.string(),
-  subtitle: z.string().optional(),
-  cta: z.object({ label: z.string(), href: z.string() }).optional(),
-  image: z.object({ src: z.string(), alt: z.string().default('') }).optional(),
-  /** Full-bleed background media for the `media` layout: an image and/or a
-   *  looping muted video (video wins when both are set). `overlay` (0–100) is
-   *  the darkening scrim so text stays legible; `poster` is the video's still. */
-  media: z
-    .object({
-      image: z.string().optional(),
-      video: z.string().optional(),
-      poster: z.string().optional(),
-      overlay: z.number().min(0).max(100).default(45),
-    })
-    .optional(),
-  layout: z.enum(['centered', 'split', 'media']).default('centered'),
-  /** Ambient background for centered/split heroes: `mesh` = a soft, slowly
-   *  drifting brand gradient behind the text (static under reduced-motion). */
-  background: z.enum(['none', 'mesh']).default('none'),
-});
-
-export const featureCardsBlock = z.object({
-  type: z.literal('featureCards'),
-  enabled: z.boolean().default(true),
-  title: z.string().optional(),
-  intro: z.string().optional(),
-  columns: z.union([z.literal(2), z.literal(3), z.literal(4)]).default(3),
-  cards: z
-    .array(
-      z.object({
-        icon: z.string().optional(),
-        title: z.string(),
-        text: z.string().optional(),
-        href: z.string().optional(),
-      })
-    )
-    .default([]),
-});
-
-export const ctaBlock = z.object({
-  type: z.literal('cta'),
-  enabled: z.boolean().default(true),
-  title: z.string(),
-  text: z.string().optional(),
-  cta: z.object({ label: z.string(), href: z.string() }),
-  background: z.enum(['muted', 'accent', 'mesh']).default('accent'),
-});
-
-export const faqBlock = z.object({
-  type: z.literal('faq'),
-  enabled: z.boolean().default(true),
-  title: z.string().optional(),
-  items: z.array(z.object({ question: z.string(), answer: z.string() })).default([]),
-});
-
-export const galleryBlock = z.object({
-  type: z.literal('gallery'),
-  enabled: z.boolean().default(true),
-  columns: z.union([z.literal(2), z.literal(3), z.literal(4)]).default(3),
-  images: z
-    .array(z.object({ src: z.string(), alt: z.string().default(''), caption: z.string().optional() }))
-    .default([]),
-});
-
-export const testimonialBlock = z.object({
-  type: z.literal('testimonial'),
-  enabled: z.boolean().default(true),
-  quote: z.string(),
-  author: z.string(),
-  role: z.string().optional(),
-  avatar: z.object({ src: z.string(), alt: z.string().default('') }).optional(),
-});
-
-/** A contact form recipe. `fields` is generic (any labelled input list) so the
- *  same recipe serves a contact page, an enquiry form, a sign-up, etc. `action`
- *  is optional: the core ships no backend, so with none it renders a standard
- *  semantic form a client later points at their own endpoint or a form service. */
-export const contactFormBlock = z.object({
-  type: z.literal('contactForm'),
-  enabled: z.boolean().default(true),
-  title: z.string().optional(),
-  intro: z.string().optional(),
-  /** Form target. Omit for a non-wired form (e.g. the showcase demo). */
-  action: z.string().optional(),
-  method: z.enum(['post', 'get']).default('post'),
-  submitLabel: z.string().default('Send message'),
-  /** Small print under the form (a privacy line, a demo notice, …). */
-  note: z.string().optional(),
-  fields: z
-    .array(
-      z.object({
-        name: z.string(),
-        label: z.string(),
-        type: z.enum(['text', 'email', 'tel', 'textarea']).default('text'),
-        required: z.boolean().default(false),
-        placeholder: z.string().optional(),
-      })
-    )
-    .default([
-      { name: 'name', label: 'Your name', type: 'text', required: true },
-      { name: 'email', label: 'Email', type: 'email', required: true },
-      { name: 'message', label: 'Message', type: 'textarea', required: true },
-    ]),
-});
-
-/** Accordion — a generic expand/collapse list (title + body). Domain-free
- *  sibling of `faq` (which carries question/answer semantics). */
-export const accordionBlock = z.object({
-  type: z.literal('accordion'),
-  enabled: z.boolean().default(true),
-  title: z.string().optional(),
-  items: z.array(z.object({ heading: z.string(), body: z.string() })).default([]),
-});
-
-/** Tiles — a curated card grid with five looks (outline / elevated / filled /
- *  gradient / image). The look is chosen per-block via `variant`; radius, stroke
- *  and elevation come from the global surface tokens, so tiles stay consistent
- *  with every other card on the page. Each tile can link (the whole tile is the
- *  target) and carry an icon, eyebrow, title, text and (for `image`) a photo. */
-export const tilesBlock = z.object({
-  type: z.literal('tiles'),
-  enabled: z.boolean().default(true),
-  title: z.string().optional(),
-  intro: z.string().optional(),
-  columns: z.union([z.literal(2), z.literal(3), z.literal(4)]).default(3),
-  variant: z.enum(['outline', 'elevated', 'filled', 'gradient', 'image']).default('elevated'),
-  /** Opt in to a pointer-following spotlight glow on hover (a small JS enhancement). */
-  spotlight: z.boolean().default(false),
-  tiles: z
-    .array(
-      z.object({
-        icon: z.string().optional(),
-        eyebrow: z.string().optional(),
-        title: z.string(),
-        text: z.string().optional(),
-        href: z.string().optional(),
-        image: z.object({ src: z.string(), alt: z.string().default('') }).optional(),
-      })
-    )
-    .default([]),
-});
-
-/** Banner — a full-bleed feature band: a fixed/parallax background image with a
- *  legibility scrim and a floating "shaded" content card (eyebrow + heading +
- *  text + optional CTA) drifting over it. `align` places the card; `parallax`
- *  pins the image so it slides under the content as you scroll (auto-disabled on
- *  touch and under reduced-motion). The showpiece "not-dull" effect. */
-export const bannerBlock = z.object({
-  type: z.literal('banner'),
-  enabled: z.boolean().default(true),
-  image: z.string(),
-  eyebrow: z.string().optional(),
-  title: z.string(),
-  text: z.string().optional(),
-  cta: z.object({ label: z.string(), href: z.string() }).optional(),
-  overlay: z.number().min(0).max(100).default(50),
-  align: z.enum(['start', 'center', 'end']).default('start'),
-  parallax: z.boolean().default(true),
-  /** Break the band out to the full viewport width (edge-to-edge, no rounded
-   *  corners); the card stays aligned to the page's content column. Great for a
-   *  homepage hero. Off by default (the band sits inside the content column). */
-  fullBleed: z.boolean().default(false),
-});
-
-/** Stats — a band of headline numbers (value + label + optional note), over an
- *  optional heading/intro and a chosen background. Composes the Stat primitive. */
-export const statsBlock = z.object({
-  type: z.literal('stats'),
-  enabled: z.boolean().default(true),
-  title: z.string().optional(),
-  intro: z.string().optional(),
-  background: z.enum(['none', 'muted', 'accent']).default('muted'),
-  columns: z.union([z.literal(2), z.literal(3), z.literal(4)]).default(3),
-  items: z.array(z.object({ value: z.string(), label: z.string(), description: z.string().optional() })).default([]),
-});
-
-/** Steps — a numbered process (how-it-works). `horizontal` shows connected cards
- *  in a row; `vertical` a stacked timeline. Each step: title + optional text/icon. */
-export const stepsBlock = z.object({
-  type: z.literal('steps'),
-  enabled: z.boolean().default(true),
-  title: z.string().optional(),
-  intro: z.string().optional(),
-  layout: z.enum(['horizontal', 'vertical']).default('horizontal'),
-  items: z.array(z.object({ title: z.string(), text: z.string().optional(), icon: z.string().optional() })).default([]),
-});
-
-/** Pricing — a row of plan cards (name, price, period, feature list, CTA). One
- *  plan may be `featured` (highlighted). */
-export const pricingBlock = z.object({
-  type: z.literal('pricing'),
-  enabled: z.boolean().default(true),
-  title: z.string().optional(),
-  intro: z.string().optional(),
-  plans: z
-    .array(
-      z.object({
-        name: z.string(),
-        price: z.string(),
-        period: z.string().optional(),
-        description: z.string().optional(),
-        features: z.array(z.string()).default([]),
-        cta: z.object({ label: z.string(), href: z.string() }).optional(),
-        featured: z.boolean().default(false),
-      })
-    )
-    .default([]),
-});
-
-/** Logos — a "trusted by" wall of images; muted by default, colour on hover. */
-export const logosBlock = z.object({
-  type: z.literal('logos'),
-  enabled: z.boolean().default(true),
-  title: z.string().optional(),
-  items: z.array(z.object({ src: z.string(), alt: z.string().default(''), href: z.string().optional() })).default([]),
-});
-
-/** Tabs — labelled panels; one open at a time. Progressive: the first panel is
- *  visible with no JS; a small script wires selection + ARIA. */
-export const tabsBlock = z.object({
-  type: z.literal('tabs'),
-  enabled: z.boolean().default(true),
-  title: z.string().optional(),
-  items: z
-    .array(z.object({ label: z.string(), heading: z.string().optional(), text: z.string().optional(), image: z.object({ src: z.string(), alt: z.string().default('') }).optional() }))
-    .default([]),
-});
-
-/** Announcement — a thin full-width bar (message + optional link), optionally
- *  dismissible. Dismissal is remembered per `id` in localStorage. */
-export const announcementBlock = z.object({
-  type: z.literal('announcement'),
-  enabled: z.boolean().default(true),
-  text: z.string(),
-  link: z.object({ label: z.string(), href: z.string() }).optional(),
-  tone: z.enum(['accent', 'neutral']).default('accent'),
-  dismissible: z.boolean().default(true),
-  /** localStorage key suffix so a dismissed bar stays dismissed. */
-  id: z.string().default('default'),
-});
-
-/** Bento — an asymmetric (mixed-span) grid of cards. Each item picks a `size`
- *  (sm / wide / tall / lg) and a `variant` look; the "living moodboard" layout. */
-export const bentoBlock = z.object({
-  type: z.literal('bento'),
-  enabled: z.boolean().default(true),
-  title: z.string().optional(),
-  intro: z.string().optional(),
-  items: z
-    .array(
-      z.object({
-        size: z.enum(['sm', 'wide', 'tall', 'lg']).default('sm'),
-        variant: z.enum(['surface', 'filled', 'gradient', 'image']).default('surface'),
-        icon: z.string().optional(),
-        eyebrow: z.string().optional(),
-        title: z.string(),
-        text: z.string().optional(),
-        href: z.string().optional(),
-        image: z.object({ src: z.string(), alt: z.string().default('') }).optional(),
-      })
-    )
-    .default([]),
-});
-
-/** Marquee — an infinite horizontal scroll of short phrases (a feature strip).
- *  Pure-CSS transform loop (GPU); pauses on hover; static wrap under
- *  reduced-motion. Decorative, so the moving track is aria-hidden. */
-export const marqueeBlock = z.object({
-  type: z.literal('marquee'),
-  enabled: z.boolean().default(true),
-  items: z.array(z.string()).default([]),
-  speed: z.enum(['slow', 'normal', 'fast']).default('normal'),
-});
-
-/** LatestPosts — a capability-backed recipe: the N most-recent published posts
- *  (optionally filtered to a `tag`) as a card grid or a compact list, with a
- *  "view all" link. Unlike other recipes it carries no content of its own — it
- *  queries the client's posts collection at build time — so it's the bridge from
- *  the posts capability into the page/block system (no per-client custom code). */
-export const latestPostsBlock = z.object({
-  type: z.literal('latestPosts'),
-  enabled: z.boolean().default(true),
-  title: z.string().optional(),
-  intro: z.string().optional(),
-  limit: z.number().int().min(1).max(12).default(3),
-  /** Filter to a single tag slug; omit for the main index (minus excluded tags). */
-  tag: z.string().optional(),
-  /** `grid` = full image cards; `list` = a compact miniature index (thumbnail +
-   *  category + date per row) that stays short even with many posts. */
-  layout: z.enum(['grid', 'list']).default('grid'),
-  /** In the `list` layout, badge the most-recent post as "New" when it was
-   *  published within this many days (0 disables it). Only the newest row is ever
-   *  flagged, so a frequently-posting site doesn't mark every row. Grid ignores it. */
-  newWithinDays: z.number().int().min(0).max(365).default(14),
-  /** "View all" target + label (the posts index by default). */
-  viewAllHref: z.string().default('/posts'),
-  viewAllLabel: z.string().default('All posts'),
-});
-
-/** MapEmbed — a consent-gated external map (e.g. Google Maps), the sibling of the
- *  calendar embed: nothing loads from the provider until the visitor opts in, so
- *  no third-party request fires on page load. `embedUrl` must be https; an unset
- *  or unsafe URL degrades to a friendly note + optional "open in Maps" link. */
-export const mapEmbedBlock = z.object({
-  type: z.literal('mapEmbed'),
-  enabled: z.boolean().default(true),
-  title: z.string().optional(),
-  intro: z.string().optional(),
-  /** The map iframe src (an https embed URL). Blank → a "not set up yet" note. */
-  embedUrl: z.string().default(''),
-  /** Link to open the location in the provider's app/site (a no-embed fallback). */
-  publicUrl: z.string().default(''),
-  height: z.number().int().min(150).max(1200).default(450),
-  /** Provider name shown in the consent notice ("shared with …"). */
-  provider: z.string().default('Google Maps'),
-});
-
-/** Table — a simple data table (header row + body rows) for structured data our
- *  other blocks can't carry cleanly (fees, opening hours, a cookies list). Scrolls
- *  horizontally on narrow screens so it never breaks the page width. */
-export const tableBlock = z.object({
-  type: z.literal('table'),
-  enabled: z.boolean().default(true),
-  title: z.string().optional(),
-  intro: z.string().optional(),
-  columns: z.array(z.string()).default([]),
-  rows: z.array(z.array(z.string())).default([]),
-});
-
-/** Notice — an inline highlighted info box (icon? + title? + body + link?) that
- *  sets a passage apart from prose ("reporting a concern", "please note"). Two
- *  tones (accent / neutral); the in-flow sibling of the corner StickyCallout. */
-export const noticeBlock = z.object({
-  type: z.literal('notice'),
-  enabled: z.boolean().default(true),
-  tone: z.enum(['accent', 'neutral']).default('accent'),
-  icon: z.string().optional(),
-  title: z.string().optional(),
-  text: z.string(),
-  link: z.object({ label: z.string(), href: z.string() }).optional(),
-});
-
-/** MediaCards — a grid of rich content cards with the IMAGE as a header on top
- *  (cover-cropped), then an optional icon badge, title, meta line, description and
- *  CTA. The image-HEADER pattern (distinct from `tiles`, which puts the image
- *  BEHIND the text) — for groups, team, services, events where the photo AND copy
- *  must both stay legible. Whole card links when a card has `href`. */
-export const mediaCardsBlock = z.object({
-  type: z.literal('mediaCards'),
-  enabled: z.boolean().default(true),
-  title: z.string().optional(),
-  intro: z.string().optional(),
-  columns: z.union([z.literal(2), z.literal(3)]).default(3),
-  cards: z
-    .array(
-      z.object({
-        image: z.object({ src: z.string(), alt: z.string().default('') }).optional(),
-        icon: z.string().optional(),
-        title: z.string(),
-        /** A short meta line shown as a pill (e.g. "Sundays 10:45 · Main hall"). */
-        meta: z.string().optional(),
-        text: z.string().optional(),
-        href: z.string().optional(),
-        /** CTA label when the card links (defaults to "Learn more"). */
-        linkLabel: z.string().optional(),
-      })
-    )
-    .default([]),
-});
-
-/** ContactCard — a branded "get in touch" band: display title + subtitle on the
- *  left, contact channels as tappable pills on the right, a note across the bottom. */
-export const contactCardBlock = z.object({
-  type: z.literal('contactCard'),
-  enabled: z.boolean().default(true),
-  eyebrow: z.string().optional(),
-  title: z.string(),
-  subtitle: z.string().optional(),
-  note: z.string().optional(),
-  items: z
-    .array(
-      z.object({
-        icon: z.string().optional(),
-        value: z.string(),
-        href: z.string().optional(),
-      })
-    )
-    .default([]),
-});
-
-/** Locations ("Where to find us") — location tiles, each a consent-gated map over
- *  a name / address / directions. https embed URLs only (isSafeEmbedUrl). */
-export const locationsBlock = z.object({
-  type: z.literal('locations'),
-  enabled: z.boolean().default(true),
-  title: z.string().optional(),
-  intro: z.string().optional(),
-  columns: z.union([z.literal(1), z.literal(2)]).default(2),
-  provider: z.string().default('Google Maps'),
-  items: z
-    .array(
-      z.object({
-        name: z.string(),
-        address: z.string().optional(),
-        embedUrl: z.string(),
-        directionsUrl: z.string().optional(),
-      })
-    )
-    .default([]),
-});
-
-export type RecipeBlock =
-  | z.infer<typeof heroBlock>
-  | z.infer<typeof featureCardsBlock>
-  | z.infer<typeof ctaBlock>
-  | z.infer<typeof faqBlock>
-  | z.infer<typeof galleryBlock>
-  | z.infer<typeof testimonialBlock>
-  | z.infer<typeof contactFormBlock>
-  | z.infer<typeof accordionBlock>
-  | z.infer<typeof tilesBlock>
-  | z.infer<typeof bannerBlock>
-  | z.infer<typeof statsBlock>
-  | z.infer<typeof stepsBlock>
-  | z.infer<typeof pricingBlock>
-  | z.infer<typeof logosBlock>
-  | z.infer<typeof tabsBlock>
-  | z.infer<typeof announcementBlock>
-  | z.infer<typeof bentoBlock>
-  | z.infer<typeof marqueeBlock>
-  | z.infer<typeof latestPostsBlock>
-  | z.infer<typeof mapEmbedBlock>
-  | z.infer<typeof tableBlock>
-  | z.infer<typeof noticeBlock>
-  | z.infer<typeof mediaCardsBlock>
-  | z.infer<typeof contactCardBlock>
-  | z.infer<typeof locationsBlock>;
-
-/* ── Level-1 layout / container primitives ─────────────────────────────────
- * These hold child blocks, so the schema is **recursive** (a container's
- * `blocks` field is the same block union). TypeScript can't infer a type through
- * `z.lazy`, so the recursive `Block` type is declared explicitly and the union
- * is cast to it. Containers are how primitives compose into layouts (and, later,
- * recipes). */
-export interface SectionBlock {
-  type: 'section';
-  enabled: boolean;
-  background: 'none' | 'muted' | 'accent';
-  width: 'normal' | 'wide' | 'full';
-  blocks: Block[];
-}
-export interface GridBlock {
-  type: 'grid';
-  enabled: boolean;
-  columns: 2 | 3 | 4;
-  gap: 'sm' | 'md' | 'lg';
-  blocks: Block[];
-}
-export interface StackBlock {
-  type: 'stack';
-  enabled: boolean;
-  gap: 'sm' | 'md' | 'lg';
-  blocks: Block[];
-}
-
-export type LeafBlock =
-  | z.infer<typeof headingBlock>
-  | z.infer<typeof proseBlock>
-  | z.infer<typeof imageBlock>
-  | z.infer<typeof buttonBlock>
-  | z.infer<typeof quoteBlock>
-  | z.infer<typeof dividerBlock>
-  | z.infer<typeof spacerBlock>
-  | z.infer<typeof badgeBlock>
-  | z.infer<typeof statBlock>
-  | z.infer<typeof listBlock>;
-
-/** The full recursive block type: leaf primitives + layout containers. */
-export type Block = LeafBlock | RecipeBlock | SectionBlock | GridBlock | StackBlock;
-export type BlockType = Block['type'];
-
-export const sectionBlock = z.object({
-  type: z.literal('section'),
-  enabled: z.boolean().default(true),
-  background: z.enum(['none', 'muted', 'accent']).default('none'),
-  width: z.enum(['normal', 'wide', 'full']).default('normal'),
-  /** Override the page's content alignment for this section's subtree. */
-  align: z.enum(['start', 'center', 'end']).optional(),
-  blocks: z.lazy(() => z.array(blockSchema)).default([]),
-});
-
-export const gridBlock = z.object({
-  type: z.literal('grid'),
-  enabled: z.boolean().default(true),
-  columns: z.union([z.literal(2), z.literal(3), z.literal(4)]).default(2),
-  gap: z.enum(['sm', 'md', 'lg']).default('md'),
-  blocks: z.lazy(() => z.array(blockSchema)).default([]),
-});
-
-export const stackBlock = z.object({
-  type: z.literal('stack'),
-  enabled: z.boolean().default(true),
-  gap: z.enum(['sm', 'md', 'lg']).default('md'),
-  blocks: z.lazy(() => z.array(blockSchema)).default([]),
-});
-
-/** The block palette: leaf primitives + layout containers. A discriminated union
- *  on `type` — the AI's + CMS's contract and the renderer's registry key. Adding
- *  a member without a matching BlockRenderer registry entry is a TypeScript error
- *  (the exhaustiveness guard against a silent-undefined render crash). Cast to
- *  the recursive `Block` type because `z.lazy` fields can't be inferred. */
-export const blockSchema = z.discriminatedUnion('type', [
-  headingBlock,
-  proseBlock,
-  imageBlock,
-  buttonBlock,
-  quoteBlock,
-  dividerBlock,
-  spacerBlock,
-  badgeBlock,
-  statBlock,
-  listBlock,
-  heroBlock,
-  featureCardsBlock,
-  ctaBlock,
-  faqBlock,
-  galleryBlock,
-  testimonialBlock,
-  contactFormBlock,
-  accordionBlock,
-  tilesBlock,
-  bannerBlock,
-  statsBlock,
-  stepsBlock,
-  pricingBlock,
-  logosBlock,
-  tabsBlock,
-  announcementBlock,
-  bentoBlock,
-  marqueeBlock,
-  latestPostsBlock,
-  mapEmbedBlock,
-  tableBlock,
-  noticeBlock,
-  mediaCardsBlock,
-  contactCardBlock,
-  locationsBlock,
-  sectionBlock,
-  gridBlock,
-  stackBlock,
-]) as unknown as z.ZodType<Block>;
-
-/** A page = metadata + an ordered list of blocks. Stored as JSON in the client
- *  repo; the AI composes it, a human verifies. This is also the schema of the
- *  `pages` collection that the client's `[...slug].astro` catch-all routes over,
- *  so one page = one JSON file (its filename is the URL slug). */
-export const pageSchema = z.object({
-  title: z.string(),
-  description: z.string().optional(),
-  /** Preloaded as the LCP image (passed to the layout) when set. */
-  heroImage: z.string().optional(),
-  /**
-   * Template-level content alignment — the default for text-bearing blocks on the
-   * page (headings, prose, quote). Cascades as `--content-align` so every recipe
-   * inherits one coherent alignment instead of each hard-coding its own. A
-   * `section` block can override it for its subtree; a `heading` can override per
-   * block. `start` (left) is the readable default for long-form; `center` suits
-   * short, hero-led pages.
-   */
-  align: z.enum(['start', 'center', 'end']).default('start'),
-  /**
-   * Provenance — the ferst-library template this page was instantiated from.
-   * The triangular model (docs/BLOCK-ARCHITECTURE.md §5): lego box → a template
-   * stored in the library → each client page links a `templateId`. The client
-   * repo never depends on the library; this is just a design-time back-reference
-   * so a template's lineage/variants stay traceable platform-side. Optional — a
-   * bespoke page may have none.
-   */
-  templateId: z.string().optional(),
-  /**
-   * Editor change-requests captured in the CMS — the seed of AI-driven editing
-   * ([[ferst_editing_ai_first_pdlc]]): rather than let editors edit block JSON
-   * directly (easy to break), they describe a desired change against the page and
-   * it's stored here for an agent to action later → PR → human verify. NEVER
-   * rendered; carried through the schema so a CMS save preserves it.
-   */
-  requests: z
-    .array(
-      z.object({
-        text: z.string(),
-        at: z.string().optional(),
-        by: z.string().optional(),
-        status: z.enum(['open', 'done']).default('open'),
-      }),
-    )
-    .default([]),
-  /** Keep the JSON in the repo but exclude it from the build. */
-  draft: z.boolean().default(false),
-  blocks: z.array(blockSchema).default([]),
-});
-export type Page = z.infer<typeof pageSchema>;
-
-/** Every block type id, derived from the union so it stays in sync — used for
- *  gallery coverage, CMS config generation, docs, etc. */
-export const blockTypes = (
-  blockSchema as unknown as { options: ReadonlyArray<{ shape: { type: { value: BlockType } } }> }
-).options.map((o) => o.shape.type.value);
+import { z } from 'zod';
+
+/**
+ * The block palette — the heart of the Ferst page model (see
+ * docs/BLOCK-ARCHITECTURE.md). A page is an ordered list of typed blocks stored
+ * as JSON; a Zod **discriminated union** on `type` is the single contract the AI
+ * composes against, the CMS validates, and the renderer's registry keys on.
+ *
+ * This is an original design of the *mechanism*, built from scratch. It starts
+ * with **Level-1 primitives** only; recipes (Level 2) and
+ * page templates (Level 3) layer on top later, and layout/container primitives
+ * (Section/Grid/Stack, which nest child blocks) are a deliberate next slice.
+ */
+
+/** Every block shares a `type` discriminant and an `enabled` flag (keep a block
+ *  in the page data without rendering it). */
+export const headingBlock = z.object({
+  type: z.literal('heading'),
+  enabled: z.boolean().default(true),
+  text: z.string(),
+  level: z.number().int().min(1).max(6).default(2),
+  /** Explicit per-heading alignment. OMITTED ⇒ inherit the page/section
+   *  `--content-align` cascade; set it only to override for this one heading. */
+  align: z.enum(['start', 'center', 'end']).optional(),
+  /** Paint the text with a brand → accent-2 gradient (falls back to solid ink
+   *  where background-clip:text is unsupported). A per-block opt-in effect. */
+  gradient: z.boolean().default(false),
+});
+
+export const proseBlock = z.object({
+  type: z.literal('prose'),
+  enabled: z.boolean().default(true),
+  /** Blank lines separate paragraphs; `- ` / `1. ` lines make lists; inline
+   *  `[links](href)` (incl. tel:/mailto:), `**bold**` and `*italic*` (lib/prose.ts). */
+  text: z.string(),
+});
+
+export const imageBlock = z.object({
+  type: z.literal('image'),
+  enabled: z.boolean().default(true),
+  src: z.string(),
+  alt: z.string().default(''),
+  caption: z.string().optional(),
+  /** Canonical framing options — a small, clear set the AI or a client picks
+   *  from, rather than free-form CSS. Corners follow the site by default. */
+  radius: z.enum(['none', 'soft', 'round']).default('soft'),
+  shadow: z.boolean().default(false),
+  border: z.boolean().default(false),
+  ratio: z.enum(['auto', 'square', '4/3', '3/2', '16/9', '21/9']).default('auto'),
+  /** Opt in to a soft clip-path reveal as the image scrolls into view
+   *  (progressive: no motion under reduced-motion or unsupported browsers). */
+  reveal: z.boolean().default(false),
+});
+
+export const buttonBlock = z.object({
+  type: z.literal('button'),
+  enabled: z.boolean().default(true),
+  label: z.string(),
+  href: z.string(),
+  /** Role, not decoration: primary action, secondary action, filled CTA, or a
+   *  quiet ghost. Shape (radius) is a site-wide token, not a per-button choice. */
+  variant: z.enum(['primary', 'secondary', 'cta', 'ghost']).default('primary'),
+});
+
+export const quoteBlock = z.object({
+  type: z.literal('quote'),
+  enabled: z.boolean().default(true),
+  text: z.string(),
+  cite: z.string().optional(),
+});
+
+export const dividerBlock = z.object({
+  type: z.literal('divider'),
+  enabled: z.boolean().default(true),
+});
+
+export const spacerBlock = z.object({
+  type: z.literal('spacer'),
+  enabled: z.boolean().default(true),
+  size: z.enum(['sm', 'md', 'lg']).default('md'),
+});
+
+export const badgeBlock = z.object({
+  type: z.literal('badge'),
+  enabled: z.boolean().default(true),
+  text: z.string(),
+  tone: z.enum(['neutral', 'accent']).default('accent'),
+});
+
+export const statBlock = z.object({
+  type: z.literal('stat'),
+  enabled: z.boolean().default(true),
+  value: z.string(),
+  label: z.string(),
+});
+
+export const listBlock = z.object({
+  type: z.literal('list'),
+  enabled: z.boolean().default(true),
+  /** bullet (disc) · number (ordered) · check (ticked, uses the check icon). */
+  style: z.enum(['bullet', 'number', 'check']).default('bullet'),
+  items: z.array(z.string()).default([]),
+});
+
+/* ── Level 2 — Recipes (curated, opinionated compositions of primitives) ─────
+ * A recipe is a first-class block in the same union, but it renders a *designed*
+ * layout (composing primitives internally) rather than a bare element. Locked
+ * components so quality can't drift (BLOCK-ARCHITECTURE §6). */
+export const heroBlock = z.object({
+  type: z.literal('hero'),
+  enabled: z.boolean().default(true),
+  eyebrow: z.string().optional(),
+  title: z.string(),
+  subtitle: z.string().optional(),
+  cta: z.object({ label: z.string(), href: z.string() }).optional(),
+  image: z.object({ src: z.string(), alt: z.string().default('') }).optional(),
+  /** Background media for the `media` layout, in order of precedence: a looping
+   *  muted `video` (a hosted file, or a YouTube / Vimeo link — embedded only after
+   *  cookie consent, showing `poster` until then), a slow crossfade through `images`
+   *  (2+), or one `image`.
+   *  `overlay` (0–100) is the darkening scrim so text stays legible; `poster` is
+   *  the video's still (and what reduced-motion visitors see). Moving backgrounds
+   *  get a pause button and stay still under prefers-reduced-motion. */
+  media: z
+    .object({
+      image: z.string().optional(),
+      images: z.array(z.string()).max(8).optional(),
+      video: z.string().optional(),
+      poster: z.string().optional(),
+      overlay: z.number().min(0).max(100).default(45),
+      /** Where the background leads: e.g. the full video on YouTube. The whole
+       *  background becomes a link (opens in a new tab — the app on phones), with
+       *  a visible "Watch the full video" cue; the text and CTA stay on top. */
+      link: z.string().optional(),
+      linkLabel: z.string().optional(),
+    })
+    .optional(),
+  layout: z.enum(['centered', 'split', 'media']).default('centered'),
+  /** How much of the screen a `media` hero takes: `standard` (a band), `tall`,
+   *  or `screen` — the full first screen, edge to edge (e.g. a video opener). */
+  size: z.enum(['standard', 'tall', 'screen']).default('standard'),
+  /** Ambient background for centered/split heroes: `mesh` = a soft, slowly
+   *  drifting brand gradient behind the text (static under reduced-motion). */
+  background: z.enum(['none', 'mesh']).default('none'),
+});
+
+export const featureCardsBlock = z.object({
+  type: z.literal('featureCards'),
+  enabled: z.boolean().default(true),
+  title: z.string().optional(),
+  intro: z.string().optional(),
+  columns: z.union([z.literal(2), z.literal(3), z.literal(4)]).default(3),
+  cards: z
+    .array(
+      z.object({
+        icon: z.string().optional(),
+        title: z.string(),
+        text: z.string().optional(),
+        href: z.string().optional(),
+      })
+    )
+    .default([]),
+});
+
+export const ctaBlock = z.object({
+  type: z.literal('cta'),
+  enabled: z.boolean().default(true),
+  title: z.string(),
+  text: z.string().optional(),
+  cta: z.object({ label: z.string(), href: z.string() }),
+  background: z.enum(['muted', 'accent', 'mesh']).default('accent'),
+});
+
+export const faqBlock = z.object({
+  type: z.literal('faq'),
+  enabled: z.boolean().default(true),
+  title: z.string().optional(),
+  items: z.array(z.object({ question: z.string(), answer: z.string() })).default([]),
+});
+
+export const galleryBlock = z.object({
+  type: z.literal('gallery'),
+  enabled: z.boolean().default(true),
+  columns: z.union([z.literal(2), z.literal(3), z.literal(4)]).default(3),
+  images: z
+    .array(z.object({ src: z.string(), alt: z.string().default(''), caption: z.string().optional() }))
+    .default([]),
+});
+
+export const testimonialBlock = z.object({
+  type: z.literal('testimonial'),
+  enabled: z.boolean().default(true),
+  quote: z.string(),
+  author: z.string(),
+  role: z.string().optional(),
+  avatar: z.object({ src: z.string(), alt: z.string().default('') }).optional(),
+});
+
+/** A contact form recipe. `fields` is generic (any labelled input list) so the
+ *  same recipe serves a contact page, an enquiry form, a sign-up, etc. `action`
+ *  is optional: the core ships no backend, so with none it renders a standard
+ *  semantic form a client later points at their own endpoint or a form service. */
+export const contactFormBlock = z.object({
+  type: z.literal('contactForm'),
+  enabled: z.boolean().default(true),
+  title: z.string().optional(),
+  intro: z.string().optional(),
+  /** Form target. Omit for a non-wired form (e.g. the showcase demo). */
+  action: z.string().optional(),
+  method: z.enum(['post', 'get']).default('post'),
+  submitLabel: z.string().default('Send message'),
+  /** Small print under the form (a privacy line, a demo notice, …). */
+  note: z.string().optional(),
+  fields: z
+    .array(
+      z.object({
+        name: z.string(),
+        label: z.string(),
+        type: z.enum(['text', 'email', 'tel', 'textarea']).default('text'),
+        required: z.boolean().default(false),
+        placeholder: z.string().optional(),
+      })
+    )
+    .default([
+      { name: 'name', label: 'Your name', type: 'text', required: true },
+      { name: 'email', label: 'Email', type: 'email', required: true },
+      { name: 'message', label: 'Message', type: 'textarea', required: true },
+    ]),
+});
+
+/** Accordion — a generic expand/collapse list (title + body). Domain-free
+ *  sibling of `faq` (which carries question/answer semantics). */
+export const accordionBlock = z.object({
+  type: z.literal('accordion'),
+  enabled: z.boolean().default(true),
+  title: z.string().optional(),
+  items: z.array(z.object({ heading: z.string(), body: z.string() })).default([]),
+});
+
+/** Tiles — a curated card grid with five looks (outline / elevated / filled /
+ *  gradient / image). The look is chosen per-block via `variant`; radius, stroke
+ *  and elevation come from the global surface tokens, so tiles stay consistent
+ *  with every other card on the page. Each tile can link (the whole tile is the
+ *  target) and carry an icon, eyebrow, title, text and (for `image`) a photo. */
+export const tilesBlock = z.object({
+  type: z.literal('tiles'),
+  enabled: z.boolean().default(true),
+  title: z.string().optional(),
+  intro: z.string().optional(),
+  columns: z.union([z.literal(2), z.literal(3), z.literal(4)]).default(3),
+  variant: z.enum(['outline', 'elevated', 'filled', 'gradient', 'image']).default('elevated'),
+  /** Opt in to a pointer-following spotlight glow on hover (a small JS enhancement). */
+  spotlight: z.boolean().default(false),
+  tiles: z
+    .array(
+      z
+        .object({
+          icon: z.string().optional(),
+          eyebrow: z.string().optional(),
+          /** Optional only for a picture tile: with an image and no text, the tile is
+           *  the picture alone (no scrim) — a linked poster/logo — named by its alt. */
+          title: z.string().optional(),
+          text: z.string().optional(),
+          href: z.string().optional(),
+          /** The link cue on a linking tile ("Learn more" by default). */
+          linkLabel: z.string().optional(),
+          image: z.object({ src: z.string(), alt: z.string().default('') }).optional(),
+        })
+        .refine((t) => !!t.title || !!t.image, { message: 'A tile needs a title or an image', path: ['title'] })
+    )
+    .default([]),
+});
+
+/** Banner — a full-bleed feature band: a fixed/parallax background image with a
+ *  legibility scrim and a floating "shaded" content card (eyebrow + heading +
+ *  text + optional CTA) drifting over it. `align` places the card; `parallax`
+ *  pins the image so it slides under the content as you scroll (auto-disabled on
+ *  touch and under reduced-motion). The showpiece "not-dull" effect. */
+export const bannerBlock = z.object({
+  type: z.literal('banner'),
+  enabled: z.boolean().default(true),
+  image: z.string(),
+  eyebrow: z.string().optional(),
+  title: z.string(),
+  text: z.string().optional(),
+  cta: z.object({ label: z.string(), href: z.string() }).optional(),
+  overlay: z.number().min(0).max(100).default(50),
+  align: z.enum(['start', 'center', 'end']).default('start'),
+  parallax: z.boolean().default(true),
+  /** Break the band out to the full viewport width (edge-to-edge, no rounded
+   *  corners); the card stays aligned to the page's content column. Great for a
+   *  homepage hero. Off by default (the band sits inside the content column). */
+  fullBleed: z.boolean().default(false),
+});
+
+/** Stats — a band of headline numbers (value + label + optional note), over an
+ *  optional heading/intro and a chosen background. Composes the Stat primitive. */
+export const statsBlock = z.object({
+  type: z.literal('stats'),
+  enabled: z.boolean().default(true),
+  title: z.string().optional(),
+  intro: z.string().optional(),
+  background: z.enum(['none', 'muted', 'accent']).default('muted'),
+  columns: z.union([z.literal(2), z.literal(3), z.literal(4)]).default(3),
+  items: z.array(z.object({ value: z.string(), label: z.string(), description: z.string().optional() })).default([]),
+});
+
+/** Steps — a numbered process (how-it-works). `horizontal` shows connected cards
+ *  in a row; `vertical` a stacked timeline. Each step: title + optional text/icon. */
+export const stepsBlock = z.object({
+  type: z.literal('steps'),
+  enabled: z.boolean().default(true),
+  title: z.string().optional(),
+  intro: z.string().optional(),
+  layout: z.enum(['horizontal', 'vertical']).default('horizontal'),
+  items: z.array(z.object({ title: z.string(), text: z.string().optional(), icon: z.string().optional() })).default([]),
+});
+
+/** Pricing — a row of plan cards (name, price, period, feature list, CTA). One
+ *  plan may be `featured` (highlighted). */
+export const pricingBlock = z.object({
+  type: z.literal('pricing'),
+  enabled: z.boolean().default(true),
+  title: z.string().optional(),
+  intro: z.string().optional(),
+  plans: z
+    .array(
+      z.object({
+        name: z.string(),
+        price: z.string(),
+        period: z.string().optional(),
+        description: z.string().optional(),
+        features: z.array(z.string()).default([]),
+        cta: z.object({ label: z.string(), href: z.string() }).optional(),
+        featured: z.boolean().default(false),
+      })
+    )
+    .default([]),
+});
+
+/** Logos — a "trusted by" wall of images; muted by default, colour on hover. */
+export const logosBlock = z.object({
+  type: z.literal('logos'),
+  enabled: z.boolean().default(true),
+  title: z.string().optional(),
+  items: z.array(z.object({ src: z.string(), alt: z.string().default(''), href: z.string().optional() })).default([]),
+});
+
+/** Tabs — labelled panels; one open at a time. Progressive: the first panel is
+ *  visible with no JS; a small script wires selection + ARIA. */
+export const tabsBlock = z.object({
+  type: z.literal('tabs'),
+  enabled: z.boolean().default(true),
+  title: z.string().optional(),
+  items: z
+    .array(z.object({ label: z.string(), heading: z.string().optional(), text: z.string().optional(), image: z.object({ src: z.string(), alt: z.string().default('') }).optional() }))
+    .default([]),
+});
+
+/** Announcement — a thin full-width bar (message + optional link), optionally
+ *  dismissible. Dismissal is remembered per `id` in localStorage. */
+export const announcementBlock = z.object({
+  type: z.literal('announcement'),
+  enabled: z.boolean().default(true),
+  text: z.string(),
+  link: z.object({ label: z.string(), href: z.string() }).optional(),
+  tone: z.enum(['accent', 'neutral']).default('accent'),
+  dismissible: z.boolean().default(true),
+  /** localStorage key suffix so a dismissed bar stays dismissed. */
+  id: z.string().default('default'),
+});
+
+/** Bento — an asymmetric (mixed-span) grid of cards. Each item picks a `size`
+ *  (sm / wide / tall / lg) and a `variant` look; the "living moodboard" layout. */
+export const bentoBlock = z.object({
+  type: z.literal('bento'),
+  enabled: z.boolean().default(true),
+  title: z.string().optional(),
+  intro: z.string().optional(),
+  items: z
+    .array(
+      z.object({
+        size: z.enum(['sm', 'wide', 'tall', 'lg']).default('sm'),
+        variant: z.enum(['surface', 'filled', 'gradient', 'image']).default('surface'),
+        icon: z.string().optional(),
+        eyebrow: z.string().optional(),
+        title: z.string(),
+        text: z.string().optional(),
+        href: z.string().optional(),
+        image: z.object({ src: z.string(), alt: z.string().default('') }).optional(),
+      })
+    )
+    .default([]),
+});
+
+/** Marquee — an infinite horizontal scroll of short phrases (a feature strip).
+ *  Pure-CSS transform loop (GPU); pauses on hover; static wrap under
+ *  reduced-motion. Decorative, so the moving track is aria-hidden. */
+export const marqueeBlock = z.object({
+  type: z.literal('marquee'),
+  enabled: z.boolean().default(true),
+  items: z.array(z.string()).default([]),
+  speed: z.enum(['slow', 'normal', 'fast']).default('normal'),
+});
+
+/** LatestPosts — a capability-backed recipe: the N most-recent published posts
+ *  (optionally filtered to a `tag`) as a card grid or a compact list, with a
+ *  "view all" link. Unlike other recipes it carries no content of its own — it
+ *  queries the client's posts collection at build time — so it's the bridge from
+ *  the posts capability into the page/block system (no per-client custom code). */
+export const latestPostsBlock = z.object({
+  type: z.literal('latestPosts'),
+  enabled: z.boolean().default(true),
+  title: z.string().optional(),
+  intro: z.string().optional(),
+  limit: z.number().int().min(1).max(12).default(3),
+  /** Filter to a single tag slug; omit for the main index (minus excluded tags). */
+  tag: z.string().optional(),
+  /** `grid` = full image cards; `list` = a compact miniature index (thumbnail +
+   *  category + date per row) that stays short even with many posts. */
+  layout: z.enum(['grid', 'list']).default('grid'),
+  /** In the `list` layout, badge the most-recent post as "New" when it was
+   *  published within this many days (0 disables it). Only the newest row is ever
+   *  flagged, so a frequently-posting site doesn't mark every row. Grid ignores it. */
+  newWithinDays: z.number().int().min(0).max(365).default(14),
+  /** "View all" target + label (the posts index by default). */
+  viewAllHref: z.string().default('/posts'),
+  viewAllLabel: z.string().default('All posts'),
+});
+
+/** MapEmbed — a consent-gated external map (e.g. Google Maps), the sibling of the
+ *  calendar embed: nothing loads from the provider until the visitor opts in, so
+ *  no third-party request fires on page load. `embedUrl` must be https; an unset
+ *  or unsafe URL degrades to a friendly note + optional "open in Maps" link. */
+export const mapEmbedBlock = z.object({
+  type: z.literal('mapEmbed'),
+  enabled: z.boolean().default(true),
+  title: z.string().optional(),
+  intro: z.string().optional(),
+  /** The map iframe src (an https embed URL). Blank → a "not set up yet" note. */
+  embedUrl: z.string().default(''),
+  /** Link to open the location in the provider's app/site (a no-embed fallback). */
+  publicUrl: z.string().default(''),
+  height: z.number().int().min(150).max(1200).default(450),
+  /** Provider name shown in the consent notice ("shared with …"). */
+  provider: z.string().default('Google Maps'),
+});
+
+/** Table — a simple data table (header row + body rows) for structured data our
+ *  other blocks can't carry cleanly (fees, opening hours, a cookies list). Scrolls
+ *  horizontally on narrow screens so it never breaks the page width. */
+export const tableBlock = z.object({
+  type: z.literal('table'),
+  enabled: z.boolean().default(true),
+  title: z.string().optional(),
+  intro: z.string().optional(),
+  columns: z.array(z.string()).default([]),
+  rows: z.array(z.array(z.string())).default([]),
+});
+
+/** Notice — an inline highlighted info box (icon? + title? + body + link?) that
+ *  sets a passage apart from prose ("reporting a concern", "please note"). Two
+ *  tones (accent / neutral); the in-flow sibling of the corner StickyCallout. */
+export const noticeBlock = z.object({
+  type: z.literal('notice'),
+  enabled: z.boolean().default(true),
+  tone: z.enum(['accent', 'neutral']).default('accent'),
+  icon: z.string().optional(),
+  title: z.string().optional(),
+  text: z.string(),
+  link: z.object({ label: z.string(), href: z.string() }).optional(),
+});
+
+/** MediaCards — a grid of rich content cards with the IMAGE as a header on top
+ *  (cover-cropped), then an optional icon badge, title, meta line, description and
+ *  CTA. The image-HEADER pattern (distinct from `tiles`, which puts the image
+ *  BEHIND the text) — for groups, team, services, events where the photo AND copy
+ *  must both stay legible. Whole card links when a card has `href`. */
+export const mediaCardsBlock = z.object({
+  type: z.literal('mediaCards'),
+  enabled: z.boolean().default(true),
+  title: z.string().optional(),
+  intro: z.string().optional(),
+  columns: z.union([z.literal(2), z.literal(3)]).default(3),
+  cards: z
+    .array(
+      z.object({
+        image: z.object({ src: z.string(), alt: z.string().default('') }).optional(),
+        icon: z.string().optional(),
+        title: z.string(),
+        /** A short meta line shown as a pill (e.g. "Sundays 10:45 · Main hall"). */
+        meta: z.string().optional(),
+        text: z.string().optional(),
+        href: z.string().optional(),
+        /** CTA label when the card links (defaults to "Learn more"). */
+        linkLabel: z.string().optional(),
+      })
+    )
+    .default([]),
+});
+
+/** ContactCard — a branded "get in touch" band: display title + subtitle on the
+ *  left, contact channels as tappable pills on the right, a note across the bottom. */
+export const contactCardBlock = z.object({
+  type: z.literal('contactCard'),
+  enabled: z.boolean().default(true),
+  eyebrow: z.string().optional(),
+  title: z.string(),
+  subtitle: z.string().optional(),
+  note: z.string().optional(),
+  items: z
+    .array(
+      z.object({
+        icon: z.string().optional(),
+        value: z.string(),
+        href: z.string().optional(),
+      })
+    )
+    .default([]),
+});
+
+/** Locations ("Where to find us") — location tiles, each a consent-gated map over
+ *  a name / address / directions. https embed URLs only (isSafeEmbedUrl). */
+export const locationsBlock = z.object({
+  type: z.literal('locations'),
+  enabled: z.boolean().default(true),
+  title: z.string().optional(),
+  intro: z.string().optional(),
+  columns: z.union([z.literal(1), z.literal(2)]).default(2),
+  provider: z.string().default('Google Maps'),
+  items: z
+    .array(
+      z.object({
+        name: z.string(),
+        address: z.string().optional(),
+        embedUrl: z.string(),
+        directionsUrl: z.string().optional(),
+      })
+    )
+    .default([]),
+});
+
+/** Video — a consent-gated YouTube / Vimeo player (incl. a channel's live stream).
+ *  `url` is the ordinary link an editor would paste; it becomes a privacy-friendly
+ *  embed (lib/video). An unrecognised link shows as a plain "watch" link. */
+export const videoBlock = z.object({
+  type: z.literal('video'),
+  enabled: z.boolean().default(true),
+  title: z.string().optional(),
+  caption: z.string().optional(),
+  url: z.string(),
+  ratio: z.enum(['16/9', '4/3', '1/1', '9/16']).default('16/9'),
+});
+
+/** Documents — a list of files (newsletters, minutes, policies, forms): type badge,
+ *  title, date and note per row, newest first, optionally grouped by year. `date`
+ *  is YYYY-MM-DD. Files open in the browser's own viewer, not an in-page one. */
+export const documentsBlock = z.object({
+  type: z.literal('documents'),
+  enabled: z.boolean().default(true),
+  title: z.string().optional(),
+  intro: z.string().optional(),
+  groupByYear: z.boolean().default(false),
+  items: z
+    .array(
+      z.object({
+        title: z.string(),
+        file: z.string(),
+        date: z.string().optional(),
+        note: z.string().optional(),
+      })
+    )
+    .default([]),
+});
+
+export type RecipeBlock =
+  | z.infer<typeof heroBlock>
+  | z.infer<typeof featureCardsBlock>
+  | z.infer<typeof ctaBlock>
+  | z.infer<typeof faqBlock>
+  | z.infer<typeof galleryBlock>
+  | z.infer<typeof testimonialBlock>
+  | z.infer<typeof contactFormBlock>
+  | z.infer<typeof accordionBlock>
+  | z.infer<typeof tilesBlock>
+  | z.infer<typeof bannerBlock>
+  | z.infer<typeof statsBlock>
+  | z.infer<typeof stepsBlock>
+  | z.infer<typeof pricingBlock>
+  | z.infer<typeof logosBlock>
+  | z.infer<typeof tabsBlock>
+  | z.infer<typeof announcementBlock>
+  | z.infer<typeof bentoBlock>
+  | z.infer<typeof marqueeBlock>
+  | z.infer<typeof latestPostsBlock>
+  | z.infer<typeof mapEmbedBlock>
+  | z.infer<typeof tableBlock>
+  | z.infer<typeof noticeBlock>
+  | z.infer<typeof mediaCardsBlock>
+  | z.infer<typeof contactCardBlock>
+  | z.infer<typeof locationsBlock>
+  | z.infer<typeof videoBlock>
+  | z.infer<typeof documentsBlock>;
+
+/* ── Level-1 layout / container primitives ─────────────────────────────────
+ * These hold child blocks, so the schema is **recursive** (a container's
+ * `blocks` field is the same block union). TypeScript can't infer a type through
+ * `z.lazy`, so the recursive `Block` type is declared explicitly and the union
+ * is cast to it. Containers are how primitives compose into layouts (and, later,
+ * recipes). */
+export interface SectionBlock {
+  type: 'section';
+  enabled: boolean;
+  background: 'none' | 'muted' | 'accent';
+  width: 'normal' | 'wide' | 'full';
+  blocks: Block[];
+}
+export interface GridBlock {
+  type: 'grid';
+  enabled: boolean;
+  columns: 2 | 3 | 4;
+  gap: 'sm' | 'md' | 'lg';
+  blocks: Block[];
+}
+export interface StackBlock {
+  type: 'stack';
+  enabled: boolean;
+  gap: 'sm' | 'md' | 'lg';
+  blocks: Block[];
+}
+
+export type LeafBlock =
+  | z.infer<typeof headingBlock>
+  | z.infer<typeof proseBlock>
+  | z.infer<typeof imageBlock>
+  | z.infer<typeof buttonBlock>
+  | z.infer<typeof quoteBlock>
+  | z.infer<typeof dividerBlock>
+  | z.infer<typeof spacerBlock>
+  | z.infer<typeof badgeBlock>
+  | z.infer<typeof statBlock>
+  | z.infer<typeof listBlock>;
+
+/** The full recursive block type: leaf primitives + layout containers. */
+export type Block = LeafBlock | RecipeBlock | SectionBlock | GridBlock | StackBlock;
+export type BlockType = Block['type'];
+
+export const sectionBlock = z.object({
+  type: z.literal('section'),
+  enabled: z.boolean().default(true),
+  background: z.enum(['none', 'muted', 'accent']).default('none'),
+  width: z.enum(['normal', 'wide', 'full']).default('normal'),
+  /** Override the page's content alignment for this section's subtree. */
+  align: z.enum(['start', 'center', 'end']).optional(),
+  blocks: z.lazy(() => z.array(blockSchema)).default([]),
+});
+
+export const gridBlock = z.object({
+  type: z.literal('grid'),
+  enabled: z.boolean().default(true),
+  columns: z.union([z.literal(2), z.literal(3), z.literal(4)]).default(2),
+  gap: z.enum(['sm', 'md', 'lg']).default('md'),
+  blocks: z.lazy(() => z.array(blockSchema)).default([]),
+});
+
+export const stackBlock = z.object({
+  type: z.literal('stack'),
+  enabled: z.boolean().default(true),
+  gap: z.enum(['sm', 'md', 'lg']).default('md'),
+  blocks: z.lazy(() => z.array(blockSchema)).default([]),
+});
+
+/** The block palette: leaf primitives + layout containers. A discriminated union
+ *  on `type` — the AI's + CMS's contract and the renderer's registry key. Adding
+ *  a member without a matching BlockRenderer registry entry is a TypeScript error
+ *  (the exhaustiveness guard against a silent-undefined render crash). Cast to
+ *  the recursive `Block` type because `z.lazy` fields can't be inferred. */
+export const blockSchema = z.discriminatedUnion('type', [
+  headingBlock,
+  proseBlock,
+  imageBlock,
+  buttonBlock,
+  quoteBlock,
+  dividerBlock,
+  spacerBlock,
+  badgeBlock,
+  statBlock,
+  listBlock,
+  heroBlock,
+  featureCardsBlock,
+  ctaBlock,
+  faqBlock,
+  galleryBlock,
+  testimonialBlock,
+  contactFormBlock,
+  accordionBlock,
+  tilesBlock,
+  bannerBlock,
+  statsBlock,
+  stepsBlock,
+  pricingBlock,
+  logosBlock,
+  tabsBlock,
+  announcementBlock,
+  bentoBlock,
+  marqueeBlock,
+  latestPostsBlock,
+  mapEmbedBlock,
+  tableBlock,
+  noticeBlock,
+  mediaCardsBlock,
+  contactCardBlock,
+  locationsBlock,
+  videoBlock,
+  documentsBlock,
+  sectionBlock,
+  gridBlock,
+  stackBlock,
+]) as unknown as z.ZodType<Block>;
+
+/** A page = metadata + an ordered list of blocks. Stored as JSON in the client
+ *  repo; the AI composes it, a human verifies. This is also the schema of the
+ *  `pages` collection that the client's `[...slug].astro` catch-all routes over,
+ *  so one page = one JSON file (its filename is the URL slug). */
+export const pageSchema = z.object({
+  title: z.string(),
+  description: z.string().optional(),
+  /** Preloaded as the LCP image (passed to the layout) when set. */
+  heroImage: z.string().optional(),
+  /**
+   * Template-level content alignment — the default for text-bearing blocks on the
+   * page (headings, prose, quote). Cascades as `--content-align` so every recipe
+   * inherits one coherent alignment instead of each hard-coding its own. A
+   * `section` block can override it for its subtree; a `heading` can override per
+   * block. `start` (left) is the readable default for long-form; `center` suits
+   * short, hero-led pages.
+   */
+  align: z.enum(['start', 'center', 'end']).default('start'),
+  /**
+   * Provenance — the ferst-library template this page was instantiated from.
+   * The triangular model (docs/BLOCK-ARCHITECTURE.md §5): lego box → a template
+   * stored in the library → each client page links a `templateId`. The client
+   * repo never depends on the library; this is just a design-time back-reference
+   * so a template's lineage/variants stay traceable platform-side. Optional — a
+   * bespoke page may have none.
+   */
+  templateId: z.string().optional(),
+  /**
+   * Editor change-requests captured in the CMS — the seed of AI-driven editing
+   * ([[ferst_editing_ai_first_pdlc]]): rather than let editors edit block JSON
+   * directly (easy to break), they describe a desired change against the page and
+   * it's stored here for an agent to action later → PR → human verify. NEVER
+   * rendered; carried through the schema so a CMS save preserves it.
+   */
+  requests: z
+    .array(
+      z.object({
+        text: z.string(),
+        at: z.string().optional(),
+        by: z.string().optional(),
+        status: z.enum(['open', 'done']).default('open'),
+      }),
+    )
+    .default([]),
+  /** Keep the JSON in the repo but exclude it from the build. */
+  draft: z.boolean().default(false),
+  blocks: z.array(blockSchema).default([]),
+});
+export type Page = z.infer<typeof pageSchema>;
+
+/** Every block type id, derived from the union so it stays in sync — used for
+ *  gallery coverage, CMS config generation, docs, etc. */
+export const blockTypes = (
+  blockSchema as unknown as { options: ReadonlyArray<{ shape: { type: { value: BlockType } } }> }
+).options.map((o) => o.shape.type.value);