@iterant/site-runtime 3.1.0 → 3.1.3

package/docs/runtime-contract.md

@@ -50,7 +50,7 @@ runtime and says so.
 
 <!-- generated: available libraries -->
 
-_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.1.0._
+_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.1.3._
 
 **Toolchain** (this package owns the version; do NOT declare these):
 
@@ -99,9 +99,13 @@ The grammar (`content-values.ts`, schema-enforced):
 
 - Copy is **wrapped**: `{"type":"text","value":"…"}`,
   `{"type":"link","text":"…","href":"…"}`,
-  `{"type":"image","src":"…","alt":"…"}`, `{"type":"svg","markup":"…"}`,
+  `{"type":"image","src":"…","alt":"…"}`,
+  `{"type":"video","src":"…","poster":"…"}`, `{"type":"svg","markup":"…"}`,
   `{"type":"color","value":"…"}`. Repeated content is
-  `{"type":"array","items":[{…}]}`.
+  `{"type":"array","items":[{…}]}`. A link's `text` is optional in bespoke
+  content (an anchor can wrap its label); authored sections and chrome
+  require it (`labelledLinkSchema`). Videos carry no copy and are never
+  translated.
 - Non-copy config stays bare: numbers, booleans, short lowercase tokens
   (`"zap"`, `"center"`, `"inverse"`). Bare strings with uppercase letters or
   spaces are rejected by the schema, so wrap them.
@@ -123,6 +127,37 @@ The grammar (`content-values.ts`, schema-enforced):
 - `site-runtime scan-copy` finds hardcoded copy in component code. Like every
   gate, never edit or weaken it.
 
+### Reading leaves in section code
+
+A section prop typed `ContentLeaf` is a union, and reading a variant field off
+the union (`leaf.value`, `leaf.href`) fails `astro check` even though it
+renders. Read leaves through the exported accessors, one per kind, and never
+hand-roll narrowing helpers:
+
+```tsx
+import {
+  readImage,
+  readItems,
+  readLink,
+  readText,
+} from "@iterant/site-runtime/content-values";
+
+<h2>{readText(data.heading)}</h2>;
+{
+  readItems(data.features).map((item, index) => (
+    <li key={index}>{readText(item.title)}</li>
+  ));
+}
+const cta = readLink(data.cta); // { text?, href, target? } | null
+const hero = readImage(data.hero); // { src, alt, srcset? } | null
+const reel = readVideo(data.reel); // { src, poster? } | null
+```
+
+They never throw and degrade to empty (`""`, `null`, `[]`) on the wrong kind,
+so a section renders with partial content instead of taking the route down.
+Type guards (`isTextContent`, `isLinkContent`, …) are exported for the rare
+case that needs manual narrowing.
+
 ### The collection schemas
 
 The repo's `src/content.config.ts` is a shim over `createCollections`, which

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iterant/site-runtime",
-  "version": "3.1.0",
+  "version": "3.1.3",
   "type": "module",
   "description": "The platform layer every Iterant brand site runs on: content grammar, collection schemas, SEO head and JSON-LD, layout core, Astro config preset, dev integrations and the verify gates.",
   "scripts": {
@@ -46,6 +46,8 @@
     "./seo": "./src/components/seo.tsx",
     "./seo-json": "./src/components/seo-json.tsx",
     "./layout": "./src/layouts/LayoutCore.astro",
+    "./layout-core": "./src/layouts/layout-core.ts",
+    "./layout-contract": "./src/layouts/layout-contract.ts",
     "./under-construction": "./src/routes/UnderConstruction.astro",
     "./routes": "./src/routes/index.ts",
     "./config": "./src/config/preset.ts",

package/scripts/scan-fetch-entrypoint.mjs

@@ -0,0 +1,73 @@
+// @ts-check
+/**
+ * Reserved-filename gate: `src/fetch.*`.
+ *
+ * Astro 7 resolves `srcDir + "fetch"` as the request-pipeline entrypoint
+ * (advanced routing): when the module resolves, its default export replaces
+ * the default fetch handler for EVERY request, in dev and in production
+ * builds alike, and a failure to resolve falls back silently. Resolution
+ * goes through Vite, so every resolvable extension counts and a `src/fetch/`
+ * directory resolves through its index file. A brand repo must never carry
+ * one: an innocently named helper would silently take over the whole request
+ * pipeline, and a broken one takes every route down with it. The platform
+ * reserves the name for a future runtime-owned shim; until that ships, the
+ * file's absence is the contract.
+ */
+
+import { readdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+// Vite's default resolve.extensions, which Astro does not override.
+const RESOLVABLE = /^fetch\.(mjs|js|mts|ts|jsx|tsx|json)$/;
+
+/**
+ * @param {string} rootDir
+ * @returns {Promise<string[]>}
+ */
+export async function checkFetchEntrypoint(rootDir) {
+  /** @type {import("node:fs").Dirent[]} */
+  let entries = [];
+  try {
+    entries = await readdir(join(rootDir, "src"), { withFileTypes: true });
+  } catch {
+    // No src/ at all is astro check's problem, not this gate's.
+    return [];
+  }
+  const problems = [];
+  for (const entry of entries) {
+    if (entry.isDirectory() && entry.name === "fetch") {
+      problems.push(
+        "src/fetch/ is a reserved name: Astro resolves it (through its index file) " +
+          "as the request-pipeline entrypoint for every route, dev and production. " +
+          "Rename the directory.",
+      );
+      continue;
+    }
+    if (entry.isFile() && RESOLVABLE.test(entry.name)) {
+      problems.push(
+        `src/${entry.name} is a reserved filename: Astro loads it as the ` +
+          "request-pipeline entrypoint for every route, dev and production, " +
+          "replacing the platform's default handler. Rename the file.",
+      );
+    }
+  }
+  return problems;
+}
+
+// Standalone CLI: `node scripts/scan-fetch-entrypoint.mjs [rootDir]`.
+// Prints problems to stderr and exits 1 when any are found.
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+) {
+  const problems = await checkFetchEntrypoint(
+    process.argv[2] ? resolve(process.argv[2]) : process.cwd(),
+  );
+  if (problems.length > 0) {
+    process.stderr.write(
+      `fetch-entrypoint check failed:\n${problems.join("\n")}\n`,
+    );
+    process.exit(1);
+  }
+}

package/scripts/verify.mjs

@@ -207,6 +207,19 @@ if (fontProblems.length > 0) {
   exit(1);
 }
 
+// Fetch-entrypoint gate — Astro loads src/fetch.* as the request-pipeline
+// entrypoint for EVERY route, dev and production, so an innocently named
+// helper silently takes over the whole pipeline. The check lives in
+// scan-fetch-entrypoint.mjs so its tests can exercise it on fixtures.
+const { checkFetchEntrypoint } = await import("./scan-fetch-entrypoint.mjs");
+const fetchProblems = await checkFetchEntrypoint(process.cwd());
+if (fetchProblems.length > 0) {
+  process.stderr.write(
+    `fetch-entrypoint check failed:\n${fetchProblems.join("\n")}\n`,
+  );
+  exit(1);
+}
+
 // Island-import gate — registered sections never hydrate, so an island-grade
 // ui primitive imported there ships a dead widget with zero build signal.
 // The check (direct + barrel + any-depth relative imports; type-only imports

package/src/config/preset.ts

@@ -185,6 +185,12 @@ export function iterantStarter({
       // Tunnel/preview hostnames are random per boot, so hostname
       // allow-listing is impossible; access control lives outside the dev server.
       allowedHosts,
+      // Vite 8 turns this on by itself when it sniffs an AI agent in the
+      // environment, and a forwarded browser console (any viewer with the
+      // preview open) would interleave into the process logs the platform
+      // parses for readiness and boot briefs. Pinned so a heuristic never
+      // decides the log shape; enabling it is a deliberate platform decision.
+      forwardConsole: false,
     },
   };
 

package/src/content/collections.ts

@@ -7,6 +7,7 @@ import {
   loaderBase,
 } from "../lib/content-paths";
 import { entryIdFromFile } from "../lib/locales";
+import { withDevQuarantine } from "./resilience";
 import { createContentSchemas, type ContentSchemaOptions } from "./schema";
 
 // The `pages` + `chrome` collections a brand site runs on. Astro requires the
@@ -53,7 +54,10 @@ export function createCollections({
       base: loaderBase(pagesDir),
       generateId: ({ entry }) => entryIdFromFile(entry),
     }),
-    schema: pageEntrySchema,
+    // Strict at build/verify; in dev an invalid entry is quarantined (logged
+    // in full, route degrades to an error stand-in) instead of taking the
+    // whole content sync — and with it every route of the preview — down.
+    schema: withDevQuarantine(pageEntrySchema),
   });
 
   const chrome = defineCollection({

package/src/content/resilience.ts

@@ -0,0 +1,106 @@
+import { z } from "astro/zod";
+
+// Dev-server resilience for the pages collection (3.1.1). Astro 7 treats one
+// invalid entry as fatal to the whole content sync, so a single half-finished
+// page took the ENTIRE preview down — every route, plus the save gate's boot.
+// In dev we quarantine instead: the strict schema still decides validity, the
+// violations are logged in full, and the broken entry is replaced by a
+// minimal valid stand-in (chromed page, no sections, error title) so its
+// route degrades while every other page keeps serving. Builds stay strict:
+// verify and publish reject the entry exactly as before, so nothing invalid
+// can ship.
+
+const ROUTE_PATTERN = /^\/[a-z0-9\-/]*$/;
+
+type AnyPageSchema = z.ZodTypeAny;
+
+export function isStrictContentEnv(env: NodeJS.ProcessEnv = process.env) {
+  // astro build sets NODE_ENV=production; astro dev sets development.
+  // SITE_RUNTIME_STRICT_CONTENT=1 forces build behavior in dev (escape hatch
+  // for debugging the strict path itself).
+  return (
+    env.NODE_ENV === "production" || env.SITE_RUNTIME_STRICT_CONTENT === "1"
+  );
+}
+
+// Render a ZodError as one line per violation with full paths. Zod 4 already
+// reports the informative branch of a union failure at its deep path (the
+// bare-string wrapper rule lands on e.g. components.1.props.columns.items.1
+// .key directly); genuinely ambiguous unions still collapse to one issue
+// carrying per-branch issue lists in `errors`, so those are walked.
+type UnionBranches = { errors?: z.ZodIssue[][] };
+
+function describeIssues(
+  issues: z.ZodIssue[],
+  base: PropertyKey[] = [],
+): string[] {
+  const lines: string[] = [];
+  for (const issue of issues) {
+    const path = [...base, ...issue.path];
+    const branches = (issue as UnionBranches).errors;
+    if (issue.code === "invalid_union" && Array.isArray(branches)) {
+      lines.push(...describeIssues(branches.flat(), path));
+      continue;
+    }
+    lines.push(`${path.map(String).join(".")}: ${issue.message}`);
+  }
+  return [...new Set(lines)];
+}
+
+/**
+ * Wrap the strict page-entry schema for collection use: pass-through when the
+ * entry is valid, quarantine when it is not (dev only). In a strict env
+ * (build/verify) and for an entry whose `route` field is itself unusable (it
+ * cannot be placed on a route), the original violations surface unchanged.
+ */
+export function withDevQuarantine<S extends AnyPageSchema>(
+  strict: S,
+  env: NodeJS.ProcessEnv = process.env,
+): z.ZodType<z.output<S>> {
+  const strictMode = isStrictContentEnv(env);
+  return z.unknown().transform((raw, ctx) => {
+    const parsed = strict.safeParse(raw);
+    if (parsed.success) return parsed.data as z.output<S>;
+
+    // Replay the strict schema's own issues through this pipeline — the cast
+    // bridges zod 4's public ZodIssue to addIssue's raw-issue input, which
+    // are the same objects under different declared types.
+    const surface = () => {
+      for (const issue of parsed.error.issues) {
+        ctx.addIssue(issue as never);
+      }
+      return z.NEVER;
+    };
+    if (strictMode) return surface();
+
+    const issues = describeIssues(parsed.error.issues);
+    const route =
+      raw !== null &&
+      typeof raw === "object" &&
+      "route" in raw &&
+      typeof raw.route === "string" &&
+      ROUTE_PATTERN.test(raw.route)
+        ? raw.route
+        : null;
+    if (route === null) return surface();
+
+    console.error(
+      [
+        `[site-runtime] QUARANTINED invalid page entry for route "${route}".`,
+        "The dev server keeps serving; this route renders an error stand-in",
+        "until the entry is fixed. Publish/verify still reject it. Violations:",
+        ...issues.map((line) => `  ${line}`),
+      ].join("\n"),
+    );
+
+    return strict.parse({
+      route,
+      title: "This page has a content error",
+      meta: {
+        title: "This page has a content error",
+        description: `Invalid entry quarantined in dev: ${issues.join("; ").slice(0, 400)}`,
+      },
+      components: [],
+    }) as z.output<S>;
+  });
+}

package/src/layouts/layout-contract.ts

@@ -0,0 +1,32 @@
+/** The layout surface GENERATORS write against, machine-readable (3.1.3).
+ *  Platform code that emits brand-repo routes imports this and tests its
+ *  emissions against it: a prop or slot an emission uses that is not listed
+ *  here is dropped silently at render, which is exactly how the locale-twin
+ *  incident escaped notice for two contract generations. The repo's Layout
+ *  shim injects the brand-context trio itself, so emitted routes never pass
+ *  those. The package's own contract test pins this list against
+ *  LayoutCore.astro, so the two cannot drift apart. */
+export const LAYOUT_CONTRACT = {
+  /** Props an emitted route may pass through the repo's Layout shim. */
+  props: [
+    "title",
+    "description",
+    "canonical",
+    "image",
+    "imageAlt",
+    "noindex",
+    "type",
+    "siteName",
+    "jsonLd",
+    "lang",
+    "hreflang",
+    "chrome",
+    "pageType",
+    "datePublished",
+    "dateModified",
+  ],
+  /** Injected by the repo's Layout shim; never passed by a route. */
+  shimInjected: ["siteConfig", "siteShell", "Shell"],
+  /** Named slots the layout renders. Anything else is dropped. */
+  slots: ["head"],
+} as const;

package/src/layouts/layout-core.ts

@@ -139,3 +139,5 @@ export function resolveStructuredData(
     dateModified: props.dateModified ?? entryMeta?.dateModified,
   };
 }
+
+export { LAYOUT_CONTRACT } from "./layout-contract";

package/src/lib/chrome-schemas.ts

@@ -4,7 +4,7 @@ import {
   arrayOf,
   configTokenSchema,
   contentLeafSchema,
-  linkContentSchema,
+  labelledLinkSchema,
   textContentSchema,
 } from "./content-values";
 
@@ -18,7 +18,7 @@ import {
 // repo passes this map into createCollections; the shapes are platform-owned.
 
 const text = textContentSchema;
-const link = linkContentSchema;
+const link = labelledLinkSchema;
 
 // A nav link is a link wrapper plus an optional trigger slug. When menuRef is
 // present the item opens a dropdown whose contents live in the top-level field
@@ -214,6 +214,14 @@ export const isChromeComponent = (type: string): type is ChromeComponentType =>
 // so it must be a loud error, not a silent no-op.
 export const KNOWN_CHROME_IDS = ["navbar", "footer"] as const;
 
+// …and site FURNITURE, which only a replicated shell mounts. A copyright strip
+// or a utility bar rides the frame rather than the navbar, so it renders on
+// every page and its copy belongs to the SITE rather than to any one page. The
+// id says who mounts it: this shell renders `frame-*` rows by id exactly as it
+// renders navbar and footer, and the starter's own shell never emits one, so a
+// `frame-*` row cannot appear in a repo with nothing to mount it.
+const FURNITURE_ID = /^frame-[a-z0-9][a-z0-9-]*$/;
+
 // A replicated chrome component (clone emit): the navbar/footer copy lives in
 // bespoke content-value props (validated by componentSchema like any bespoke
 // page component), not the prebuilt navbar/footer prop grammar. It still mounts
@@ -221,6 +229,22 @@ export const KNOWN_CHROME_IDS = ["navbar", "footer"] as const;
 // not "navbar"/"footer", and it is exempt from the CHROME_COMPONENT_PROPS shape.
 export const REPLICATED_CHROME_TYPE = "replicated";
 
+// …and a PER-PAGE chrome row (3.1.3): a known role with a scope suffix, e.g.
+// "navbar-pricing". A site can have more than one header, and which one a page
+// uses belongs to the page.
+//
+// It exists because a replicated page whose header differs from the site's had
+// only two outcomes, and both are wrong: the site's header wins and the page
+// loses its own, or the page's rides its own frame, is re-homed when that frame
+// is withheld, and renders BESIDE the site's — the same header twice. A row of
+// its own is the missing third.
+//
+// The role PREFIX is the mount contract, unchanged: the suffix says which
+// variant, and the prefix still says which mount can render it, so a row that
+// nothing could mount is still the loud error it has always been. A scoped row
+// is clone-emitted, so its type is "replicated" like the rest.
+const SCOPED_CHROME_ID = /^(?:navbar|footer)-[a-z0-9][a-z0-9-]*$/;
+
 // Validate a chrome.json components[] list's ids against the mount contract:
 // every id must be navbar|footer, and a known id's `type` must equal its `id`
 // (an {id:"navbar", type:"footer"} cross-wire validates the wrong props and
@@ -234,6 +258,13 @@ export function chromeIdIssues(
   const issues: { index: number; id: string; message: string }[] = [];
   const known = new Set<string>(KNOWN_CHROME_IDS);
   components.forEach((component, index) => {
+    if (
+      (FURNITURE_ID.test(component.id) ||
+        SCOPED_CHROME_ID.test(component.id)) &&
+      component.type === REPLICATED_CHROME_TYPE
+    ) {
+      return;
+    }
     if (!known.has(component.id)) {
       issues.push({
         index,

package/src/lib/content-values.ts

@@ -11,6 +11,7 @@ import { z } from "astro/zod";
 //   { "type": "text",  "value": "Visible prose" }
 //   { "type": "link",  "text": "Start free", "href": "/signup" }
 //   { "type": "image", "src": "/images/x.webp", "alt": "Description" }
+//   { "type": "video", "src": "/media/x.mp4", "poster": "/images/x.webp" }
 //   { "type": "svg",   "markup": "<svg…>", "label": "Accessible name" }
 //   { "type": "color", "value": "#0ea5e9" }
 //   { "type": "array", "items": [ { …wrapped fields per item… } ] }
@@ -27,7 +28,13 @@ export interface TextContent {
 
 export interface LinkContent {
   type: "link";
-  text: string;
+  /** The link's own label. Optional, because a link does not always have one:
+   *  an anchor wrapping an icon, a card, or several elements has its label in
+   *  the leaves beneath it, and those are separately addressable. A link with
+   *  no text of its own renders none, and its destination stays editable,
+   *  which is the point of the wrapper. Authored sections and chrome require
+   *  one anyway: see labelledLinkSchema. */
+  text?: string;
   href: string;
   target?: "_blank" | "_self";
 }
@@ -38,6 +45,12 @@ export interface ImageCandidate {
   src: string;
   assetId?: string;
   descriptor: string;
+  /** The <source> encoding this candidate composes ("image/webp"), absent for
+   *  the <img>'s own candidates. A <picture> is one image the browser fetches
+   *  in whichever format it supports, so its formats ride one wrapper: a swap
+   *  that clears the candidates drops every <source> at once and hands the
+   *  picture back to the img it just rewrote. */
+  type?: string;
 }
 
 export interface ImageContent {
@@ -50,6 +63,18 @@ export interface ImageContent {
   srcset?: ImageCandidate[];
 }
 
+/** A video the page plays. Like an image it is a resource the visitor sees and
+ *  an owner replaces, and unlike an image it carries no copy: there is nothing
+ *  in it to translate, which is why it has no text field and never appears in a
+ *  translation pass. `poster` is the still frame shown before playback. */
+export interface VideoContent {
+  type: "video";
+  src: string;
+  assetId?: string;
+  poster?: string;
+  posterAssetId?: string;
+}
+
 export interface SvgContent {
   type: "svg";
   markup: string;
@@ -70,6 +95,7 @@ export type ContentValue =
   | TextContent
   | LinkContent
   | ImageContent
+  | VideoContent
   | SvgContent
   | ColorContent
   | ArrayContent;
@@ -88,10 +114,20 @@ export const textContentSchema = z
     // would try to rewrite it and the editor would offer a text input for
     // a destination. Links live in link wrappers ({type:"link",text,href});
     // image sources in image wrappers.
+    //
+    // The tail is RFC 3986's path characters, not "any non-space" (3.1.3). A
+    // value the spec's own grammar cannot read as a url is not a destination,
+    // whatever it starts with: `/>` out of a syntax-highlighted code sample is
+    // visible copy, and refusing it left it baked into a component instead.
+    // Genuinely ambiguous cases stay refused: `/h` is both a price unit and a
+    // valid path, and no predicate over the STRING can tell them apart.
     value: z
       .string()
       .refine(
-        (value) => !/^(?:\/|#|https?:\/\/)\S*$/.test(value.trim()),
+        (value) =>
+          !/^(?:\/|#|https?:\/\/)[A-Za-z0-9\-._~%!$&'()*+,;=:@/?#[\]]*$/.test(
+            value.trim(),
+          ),
         'this looks like a URL or path — use {"type":"link","text":…,"href":…} (or image src), not a text wrapper',
       ),
   })
@@ -100,12 +136,21 @@ export const textContentSchema = z
 export const linkContentSchema = z
   .object({
     type: z.literal("link"),
-    text: z.string(),
+    text: z.string().optional(),
     href: z.string(),
     target: z.enum(["_blank", "_self"]).optional(),
   })
   .strict();
 
+/** A link that must carry a label: every one an AUTHOR writes. A hero CTA or a
+ *  nav item with no text is a button nobody can read, so the components that
+ *  render one from a fixed schema hold the stricter contract. The loose
+ *  wrapper above is for bespoke pages, where an anchor's label can live in the
+ *  markup beneath it. */
+export const labelledLinkSchema = linkContentSchema.extend({
+  text: z.string(),
+});
+
 // A srcset candidate descriptor is a width ("400w") or pixel density ("2x").
 const descriptorSchema = z
   .string()
@@ -119,6 +164,7 @@ export const imageCandidateSchema = z
     src: z.string(),
     assetId: z.string().optional(),
     descriptor: descriptorSchema,
+    type: z.string().optional(),
   })
   .strict();
 
@@ -134,6 +180,16 @@ export const imageContentSchema = z
   })
   .strict();
 
+export const videoContentSchema = z
+  .object({
+    type: z.literal("video"),
+    src: z.string(),
+    assetId: z.string().optional(),
+    poster: z.string().optional(),
+    posterAssetId: z.string().optional(),
+  })
+  .strict();
+
 export const svgContentSchema = z
   .object({
     type: z.literal("svg"),
@@ -170,6 +226,7 @@ export const contentLeafSchema: z.ZodType<ContentLeaf> = z.lazy(() =>
     textContentSchema,
     linkContentSchema,
     imageContentSchema,
+    videoContentSchema,
     svgContentSchema,
     colorContentSchema,
     arrayContentSchema,
@@ -199,3 +256,103 @@ export const arrayOf = <T extends z.ZodRawShape>(shape: T) =>
       items: z.array(z.object(shape).strict()),
     })
     .strict();
+
+// ---------------------------------------------------------------------------
+// Leaf accessors. Section code receives ContentLeaf, a seven-way union, and
+// the natural-but-wrong move is reading a variant's field off the union
+// (`leaf.value` renders fine and fails astro check). These are the one
+// documented way to read a leaf: narrow-and-extract, never throw, degrade to
+// empty so a section renders with partial content instead of taking the
+// route down. Use them instead of hand-rolled narrowing helpers.
+
+export function isTextContent(leaf: ContentLeaf): leaf is TextContent {
+  return typeof leaf === "object" && leaf !== null && leaf.type === "text";
+}
+
+export function isLinkContent(leaf: ContentLeaf): leaf is LinkContent {
+  return typeof leaf === "object" && leaf !== null && leaf.type === "link";
+}
+
+export function isImageContent(leaf: ContentLeaf): leaf is ImageContent {
+  return typeof leaf === "object" && leaf !== null && leaf.type === "image";
+}
+
+export function isVideoContent(leaf: ContentLeaf): leaf is VideoContent {
+  return typeof leaf === "object" && leaf !== null && leaf.type === "video";
+}
+
+export function isSvgContent(leaf: ContentLeaf): leaf is SvgContent {
+  return typeof leaf === "object" && leaf !== null && leaf.type === "svg";
+}
+
+export function isColorContent(leaf: ContentLeaf): leaf is ColorContent {
+  return typeof leaf === "object" && leaf !== null && leaf.type === "color";
+}
+
+export function isArrayContent(leaf: ContentLeaf): leaf is ArrayContent {
+  return typeof leaf === "object" && leaf !== null && leaf.type === "array";
+}
+
+/**
+ * The renderable text of a leaf: a text wrapper's value, or a bare config
+ * scalar stringified (a count or token an entry legitimately interpolates
+ * into copy). Structured wrappers (link, image, video, svg, color, array)
+ * have no text reading and come back empty — read them with their own
+ * accessor.
+ */
+export function readText(leaf: ContentLeaf | null | undefined): string {
+  if (leaf === null || leaf === undefined) return "";
+  if (isTextContent(leaf)) return leaf.value;
+  if (typeof leaf === "object") return "";
+  return String(leaf);
+}
+
+/** The link wrapper (text, href, optional target), or null. */
+export function readLink(
+  leaf: ContentLeaf | null | undefined,
+): LinkContent | null {
+  return leaf !== null && leaf !== undefined && isLinkContent(leaf)
+    ? leaf
+    : null;
+}
+
+/** The image wrapper (src, alt, optional srcset candidates), or null. */
+export function readImage(
+  leaf: ContentLeaf | null | undefined,
+): ImageContent | null {
+  return leaf !== null && leaf !== undefined && isImageContent(leaf)
+    ? leaf
+    : null;
+}
+
+/** The video wrapper (src, optional poster), or null. */
+export function readVideo(
+  leaf: ContentLeaf | null | undefined,
+): VideoContent | null {
+  return leaf !== null && leaf !== undefined && isVideoContent(leaf)
+    ? leaf
+    : null;
+}
+
+/** The svg wrapper (markup, optional label), or null. */
+export function readSvg(
+  leaf: ContentLeaf | null | undefined,
+): SvgContent | null {
+  return leaf !== null && leaf !== undefined && isSvgContent(leaf)
+    ? leaf
+    : null;
+}
+
+/** A color wrapper's CSS value, or null. */
+export function readColor(leaf: ContentLeaf | null | undefined): string | null {
+  return leaf !== null && leaf !== undefined && isColorContent(leaf)
+    ? leaf.value
+    : null;
+}
+
+/** An array wrapper's items, or an empty list. */
+export function readItems(leaf: ContentLeaf | null | undefined): ContentItem[] {
+  return leaf !== null && leaf !== undefined && isArrayContent(leaf)
+    ? leaf.items
+    : [];
+}