@iterant/site-runtime 3.1.2 → 3.3.0

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.2._
+_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.3.0._
 
 **Toolchain** (this package owns the version; do NOT declare these):
 
@@ -68,18 +68,19 @@ _Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.1.2._
 
 **Curated kit** (import directly; declare only to override):
 
-| Package                    | Version | What it is                                  |
-| -------------------------- | ------- | ------------------------------------------- |
-| `lucide-react`             | 1.31.0  | icons                                       |
-| `motion`                   | 13.0.0  | animation                                   |
-| `radix-ui`                 | 1.6.7   | unstyled accessible primitives              |
-| `@radix-ui/react-slot`     | 1.3.3   | prop forwarding for composable components   |
-| `embla-carousel-react`     | 8.6.0   | carousels                                   |
-| `clsx`                     | 2.1.1   | conditional class names                     |
-| `tailwind-merge`           | 3.6.0   | conflicting-utility resolution              |
-| `class-variance-authority` | 0.7.1   | component variants                          |
-| `tw-animate-css`           | 1.4.0   | the animation utilities Tailwind v4 dropped |
-| `github-slugger`           | 2.0.0   | heading and anchor slugs                    |
+| Package                    | Version | What it is                                            |
+| -------------------------- | ------- | ----------------------------------------------------- |
+| `lucide-react`             | 1.31.0  | icons                                                 |
+| `motion`                   | 13.0.0  | animation                                             |
+| `radix-ui`                 | 1.6.7   | unstyled accessible primitives                        |
+| `@radix-ui/react-slot`     | 1.3.3   | prop forwarding for composable components             |
+| `embla-carousel-react`     | 8.6.0   | carousels                                             |
+| `clsx`                     | 2.1.1   | conditional class names                               |
+| `tailwind-merge`           | 3.6.0   | conflicting-utility resolution                        |
+| `class-variance-authority` | 0.7.1   | component variants                                    |
+| `tw-animate-css`           | 1.4.0   | the animation utilities Tailwind v4 dropped           |
+| `github-slugger`           | 2.0.0   | heading and anchor slugs                              |
+| `micromark`                | 4.0.2   | the CommonMark compiler markdown wrappers render with |
 
 <!-- /generated -->
 
@@ -99,9 +100,15 @@ 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":[{…}]}`. Flowing body copy that needs inline
+  structure is `{"type":"markdown","value":"…"}` (3.3.0, see the markdown
+  section below). 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.
@@ -112,7 +119,8 @@ The grammar (`content-values.ts`, schema-enforced):
 - Components render bindings so tools can find the copy in the DOM:
   `data-component={id}` plus `data-component-type` on the section root;
   `data-editable="<field>"`, `data-path="props.<field>"` and
-  `data-edit-type="text|link|image|color"` on each copy-bearing element. Paths
+  `data-edit-type="text|link|image|color|markdown"` on each copy-bearing
+  element. Paths
   are wrapper-level (`props.heading`, `props.features.0.title`), never
   leaf-level. Array containers carry `data-array-container="<field>"`, items
   `data-array-item={index}`.
@@ -123,6 +131,75 @@ 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.
 
+### Markdown bodies (3.3.0)
+
+A `{"type":"text"}` value is an opaque string, so a link mid-sentence was
+inexpressible before this wrapper existed: a link was always its own leaf (a
+CTA, a nav item, a card). `{"type":"markdown","value":"…"}` holds flowing body
+copy with inline structure (links, emphasis, headings, lists, images) as
+CommonMark, stored as written.
+
+- **One wrapper is one body.** The whole value is a single edit and
+  translation target. Never split a body into per-paragraph wrappers to
+  imitate the old grammar; the point is that a sentence's link lives inside
+  the sentence that reads around it.
+- **Raw HTML is refused by the schema.** Write CommonMark. HTML that should
+  DISPLAY as copy (a technical article showing `<div>`) goes in a code span or
+  fence, which the schema skips. The compiler additionally renders with raw
+  HTML disabled, so anything that predates the schema displays as literal
+  text instead of becoming elements.
+- **Render with the runtime's compiler**, never your own:
+
+  ```tsx
+  import { renderMarkdown } from "@iterant/site-runtime/markdown";
+  import { readMarkdown } from "@iterant/site-runtime/content-values";
+
+  const body = readMarkdown(data.body); // raw CommonMark | null
+  <div
+    class="prose"
+    data-editable="body"
+    data-path="props.body"
+    data-edit-type="markdown"
+    set:html={body === null ? "" : renderMarkdown(body)}
+  />;
+  ```
+
+- **Headings start at `##`.** The body renders below the page's own h1; the
+  compiler does not demote levels for you.
+- Hrefs inside the value follow the same rules as link wrappers: root-relative
+  internal routes, absolute URLs for external targets.
+
+### 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
@@ -145,6 +222,67 @@ shape, id rules, uniqueness, the registry check on `mode: "registry"` pages, the
 chrome mount contract, locale entry ids and `_translation` all live in the
 package and change with a version bump.
 
+### The links manifest (3.3.0)
+
+`createCollections` also returns a third `links` collection reading the
+machine-owned `src/content/links.json`: the internal-links manifest the
+platform writes and nothing else may. Never hand-edit it, never let the agent
+edit it; link corrections happen upstream in the platform's link graph. The
+wire shape:
+
+```json
+{
+  "version": 1,
+  "routes": {
+    "/pricing": {
+      "label": "Related",
+      "links": [
+        { "href": "/guide", "text": "The guide", "placement": "related_aside" }
+      ]
+    }
+  }
+}
+```
+
+`LayoutCore` looks the current route up in `routes` and mounts the slice as a
+`<nav data-iterant-links>` inside the shell's slot, below the page content and
+above the shell-rendered footer. An absent file, an empty `routes` record, or
+a route with no slice all render zero bytes for the block, and nothing enters
+the shared CSS bundle, so apart from the two version metas the built pages
+match a repo pinned before 3.3.0: the file ships dark until the platform
+writes it. Each slice
+carries its own already-localized `label` (a locale sibling's route key is the
+full prefixed route, `/es/pricing`, with no fallback to the base route), so
+the package holds no copy and performs no localization. The schema tolerates
+unknown keys at every level (`placement` is written but unread), so an
+additive platform-side field can never fail an already-pinned repo's build.
+"The one `@source` line" below does not grow: the component ships no utility
+classes, only a scoped style block on the data attribute.
+
+### Choosing a shell (3.2.0)
+
+A repo may own more than one frame. A replicated site whose second page carried
+different chrome keeps that page's whole shell beside the site's, under a scope
+suffix (`shell-frame-pricing.tsx`), and `components/layout/shells.tsx` GLOBS
+them, so a frame registers by existing rather than by being listed.
+
+A page entry names the one it wants:
+
+```json
+{ "route": "/pricing", "shell": "pricing", "meta": { "title": "Pricing" } }
+```
+
+The layout reads it off the entry and threads it to `shell.astro` as `shellId`,
+so a route states it once in content instead of every `.astro` restating it. A
+route may still pass `shell` directly, and the prop wins over the entry, the
+same rule the structured-data props follow.
+
+Omit it and nothing changes: the seam falls back to the route's own scope and
+then to the site's frame, which is what every page written before 3.2.0 does.
+The name is not validated against the registry, because the shells a repo owns
+are a build-time glob that no schema can see; a name matching nothing renders
+the site's frame rather than failing the build.
+
 ## Pages: entry-driven vs bespoke
 
 Every page has a JSON entry holding its route, SEO meta and content. What
@@ -233,8 +371,8 @@ import { SITE_SHELL } from "@/site-shell";
 Every shell keeps importing `../layouts/Layout.astro` unchanged. The core owns
 the head (charset, viewport, favicon, generator, version meta, SEO, JSON-LD,
 hreflang, the `head` slot), resolves locale-aware chrome and the page entry, and
-renders the brand shell around the page slot with the `chrome`, `navbar` and
-`footer` props. It never imports a stylesheet and never imports chrome
+renders the brand shell around the page slot with the `chrome`, `navbar`,
+`footer` and `shellId` props. It never imports a stylesheet and never imports chrome
 components: `shell.astro` mounts those, which is what keeps their `client:load`
 directive traceable.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iterant/site-runtime",
-  "version": "3.1.2",
+  "version": "3.3.0",
   "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": {
@@ -10,6 +10,7 @@
     "kit-table": "node scripts/generate-kit-table.mjs",
     "lint": "eslint . --max-warnings 0",
     "lint:fix": "eslint --fix .",
+    "prepublishOnly": "node scripts/check-packed.mjs",
     "preversion": "node scripts/generate-kit-table.mjs",
     "test": "vitest run && node scripts/check-fixture.mjs",
     "test:fixture": "node scripts/check-fixture.mjs",
@@ -37,6 +38,7 @@
     "./content": "./src/content/collections.ts",
     "./content/schema": "./src/content/schema.ts",
     "./content-values": "./src/lib/content-values.ts",
+    "./markdown": "./src/lib/markdown.ts",
     "./locales": "./src/lib/locales.ts",
     "./hreflang": "./src/lib/hreflang.ts",
     "./chrome": "./src/lib/chrome.ts",
@@ -46,6 +48,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",
@@ -74,7 +78,8 @@
       "tailwind-merge",
       "class-variance-authority",
       "tw-animate-css",
-      "github-slugger"
+      "github-slugger",
+      "micromark"
     ]
   },
   "dependencies": {
@@ -90,6 +95,7 @@
     "embla-carousel-react": "8.6.0",
     "github-slugger": "2.0.0",
     "lucide-react": "1.31.0",
+    "micromark": "4.0.2",
     "motion": "13.0.0",
     "radix-ui": "1.6.7",
     "react": "19.2.8",

package/src/components/RelatedLinks.astro

@@ -0,0 +1,78 @@
+---
+// The machine-fed related-links block (ILV-6). Props are one route's slice of
+// the machine-owned src/content/links.json manifest; the manifest carries
+// every string, the heading included, so this file holds no copy of its own
+// and never re-sorts the array (ordering is the builder's contract).
+//
+// The wrapper is a <nav> ON PURPOSE: the canonical-corpus scrape excludes nav
+// and footer tags, which is what keeps machine-placed links from ever being
+// re-ingested as their own ranking evidence. The element choice is
+// load-bearing; related-links.test.ts pins it.
+//
+// No class attribute anywhere: tailwind-surface.test.ts pins exactly one
+// shipped file with utility classes, and this must not become a second.
+// Styling is an inline block INSIDE the conditional, every selector rooted at
+// the data attribute, colors from currentColor and custom-property fallbacks
+// only, so the block inherits each brand's own cascade. Inline on purpose: a
+// hoisted scoped style would enter the shared CSS bundle (and move its hash)
+// even on a brand with no manifest, breaking the absent-file byte-identity
+// that makes the renderer safe to ship ahead of any written manifest.
+
+interface Props {
+  links?: { href: string; text: string }[];
+  label?: string;
+}
+
+const { links, label } = Astro.props;
+
+// set:html, not a style-tag expression: Astro treats style content as raw
+// text, so an interpolation inside the tag would ship its braces literally.
+const RELATED_LINKS_CSS = `
+[data-iterant-links] {
+  margin: 3rem auto 0;
+  padding: 1.5rem 1rem 2rem;
+  max-width: var(--it-content-max-width, 72rem);
+}
+[data-iterant-links] h2 {
+  margin: 0 0 0.75rem;
+  font-size: 0.875rem;
+  font-weight: 600;
+  letter-spacing: 0.05em;
+  text-transform: uppercase;
+  opacity: 0.7;
+}
+[data-iterant-links] ul {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem 1.5rem;
+}
+[data-iterant-links] a {
+  color: currentColor;
+  text-decoration: underline;
+  text-underline-offset: 0.2em;
+  text-decoration-color: var(--it-link-underline, currentColor);
+}
+[data-iterant-links] a:hover {
+  opacity: 0.75;
+}
+`;
+---
+
+{
+  links && links.length > 0 && (
+    <nav data-iterant-links aria-label={label}>
+      {label && <h2>{label}</h2>}
+      <ul>
+        {links.map((link) => (
+          <li>
+            <a href={link.href}>{link.text}</a>
+          </li>
+        ))}
+      </ul>
+      <style is:inline set:html={RELATED_LINKS_CSS} />
+    </nav>
+  )
+}

package/src/content/collections.ts

@@ -8,7 +8,11 @@ import {
 } from "../lib/content-paths";
 import { entryIdFromFile } from "../lib/locales";
 import { withDevQuarantine } from "./resilience";
-import { createContentSchemas, type ContentSchemaOptions } from "./schema";
+import {
+  createContentSchemas,
+  linksManifestSchema,
+  type ContentSchemaOptions,
+} from "./schema";
 
 // The `pages` + `chrome` collections a brand site runs on. Astro requires the
 // collection definition to live in the repo's own src/content.config.ts, so
@@ -71,5 +75,20 @@ export function createCollections({
     schema: chromeEntrySchema,
   });
 
-  return { pages, chrome };
+  const links = defineCollection({
+    // The machine-owned links.json manifest (ILV-6), written only by the
+    // platform's sync channel. An absent file is a first-class valid state
+    // (the loader matches nothing and the layout renders nothing), the same
+    // ships-dark discipline chrome.json follows. NOT withDevQuarantine: the
+    // quarantine stand-in is page-shaped, and an invalid manifest is a
+    // platform bug that should fail verify loudly.
+    loader: glob({
+      pattern: "links.json",
+      base: loaderBase(chromeDir),
+      generateId: ({ entry }) => entryIdFromFile(entry),
+    }),
+    schema: linksManifestSchema,
+  });
+
+  return { pages, chrome, links };
 }

package/src/content/schema.ts

@@ -135,6 +135,26 @@ export function createContentSchemas({
       // design ships its own nav/footer (a full-design import) so the layout
       // mounts no chrome. Additive — existing entries omit it and keep chrome.
       chrome: z.boolean().default(true),
+      // Which SHELL this page renders in (site-runtime 3.2.0). A replicated
+      // site can carry more than one frame: a page whose chrome differed from
+      // the site's kept its own under a scope suffix, and the shell registry
+      // globs whatever sits beside it rather than listing them, so a shell
+      // registers by existing. Naming one here is how a page WRITTEN LATER
+      // picks from what the site already has; a replicated page needs no name,
+      // because its own shell is the one its route resolves to.
+      //
+      // Additive and unvalidated against the registry ON PURPOSE: the shells a
+      // repo owns are a glob resolved at build time, so a schema cannot know
+      // them, and a name that matches nothing falls back to the site's shell
+      // rather than failing a brand's build. Existing entries omit it and
+      // render exactly as they do today.
+      shell: z
+        .string()
+        .regex(
+          /^[a-z0-9]+(?:-[a-z0-9]+)*$/,
+          "shell must be a lowercase scope name (letters, digits, single hyphens)",
+        )
+        .optional(),
       meta: z
         .object({
           title: z.string(),
@@ -237,3 +257,44 @@ export function createContentSchemas({
 }
 
 export type ContentSchemas = ReturnType<typeof createContentSchemas>;
+
+// The machine-owned src/content/links.json manifest (ILV-6): the renderer-side
+// mirror of the platform's document contract (the Django builder is the
+// authority; a key rename happens in both places together or not at all).
+// Every object level is deliberately NON-strict: pins move brand by brand
+// while the platform writes one manifest shape fleet-wide, so an additive
+// field must be invisible to an older runtime, never a build failure delivered
+// through a content file. A breaking shape change still fails parse loudly.
+// `placement` is serialized by the builder but unread here, which is why it
+// does not appear below.
+export const linksManifestSchema = z.object({
+  version: z.number().int().positive(),
+  routes: z.record(
+    z.string(),
+    z.object({
+      // Always emitted by the builder, already locale-resolved per route; the
+      // renderer never localizes and holds no fallback copy.
+      label: z
+        .string()
+        .regex(/\S/, { message: "label cannot be blank" })
+        .optional(),
+      links: z.array(
+        z.object({
+          // Page targets are root-relative routes (Page.url_path); KB and
+          // trust targets keep their absolute crawled URL. The lookahead
+          // rejects protocol-relative //host hrefs, which would render an
+          // external link disguised as a same-site route.
+          href: z.string().regex(/^(\/(?!\/)|https?:\/\/)/i, {
+            message:
+              "expected a root-relative route or an absolute http(s) URL",
+          }),
+          text: z
+            .string()
+            .regex(/\S/, { message: "link text cannot be blank" }),
+        }),
+      ),
+    }),
+  ),
+});
+
+export type LinksManifest = z.infer<typeof linksManifestSchema>;

package/src/layouts/LayoutCore.astro

@@ -1,6 +1,7 @@
 ---
 import { getCollection, getEntry } from "astro:content";
 import type { AstroComponentFactory } from "astro/runtime/server/index.js";
+import RelatedLinks from "../components/RelatedLinks.astro";
 import { SEO, type PageType } from "../components/seo";
 import type { SeoJsonSchema } from "../components/seo-json";
 import type { HreflangAlternate } from "../lib/hreflang";
@@ -65,6 +66,12 @@ interface Props {
   pageType?: PageType;
   datePublished?: string;
   dateModified?: string;
+  // Which shell to render this page in (site-runtime 3.2.0). Read from the
+  // page entry's `shell` when a shell does not pass one, the same
+  // prop-wins-over-entry rule the structured-data props above follow. A
+  // replicated site can own several frames; this is what lets a page written
+  // later choose one instead of always taking the site's.
+  shell?: string;
 }
 
 const {
@@ -86,6 +93,7 @@ const {
   pageType,
   datePublished,
   dateModified,
+  shell,
 } = Astro.props;
 
 const site = Astro.site;
@@ -117,16 +125,32 @@ const { navbar, footer } = pickChromeComponents(chromeEntry?.data.components);
 // article dates reach the JSON-LD graph without every bespoke shell having
 // to thread them. Shells that pass the props explicitly still win. Routes
 // without an entry (404, under-construction) fall back to a plain WebPage.
-const pageEntry = findPageEntryByRoute(
-  await getCollection("pages"),
-  routePathFromPathname(Astro.url.pathname),
-  { includeDrafts: !import.meta.env.PROD },
-);
+const routePath = routePathFromPathname(Astro.url.pathname);
+const pageEntry = findPageEntryByRoute(await getCollection("pages"), routePath, {
+  includeDrafts: !import.meta.env.PROD,
+});
 const structuredData = resolveStructuredData(
   { pageType, datePublished, dateModified },
   pageEntry?.data.meta,
 );
 
+// The shell this page renders in, resolved from the same entry, so a page names
+// its shell once in content rather than every route restating it. Undefined
+// leaves the seam to fall back the way it already does: the route's own scope,
+// then the site's shell. A repo whose shell.astro predates this ignores the
+// prop, which is what makes the forward safe to ship ahead of any emit.
+const shellId = shell ?? pageEntry?.data.shell;
+
+// Machine-fed related links (ILV-6): the machine-owned src/content/links.json
+// manifest, resolved by this page's own route key. A locale sibling looks up
+// its full prefixed route; there is no fallback to the base route, because the
+// builder computes each sibling's slice from its own edges and drops
+// cross-language targets. The slice's label arrives already locale-resolved,
+// so the `locale` above is not consulted. Absent file, absent route, or an
+// empty slice all render nothing, the chrome.json ships-dark discipline.
+const linksEntry = await getEntry("links", "links");
+const linksSlice = linksEntry?.data.routes[routePath];
+
 // Version identity: the installed package version IS the site's runtime
 // version. `it-astro-starter-version` keeps emitting the same value while the
 // plugin loader and the platform's page indexer still read that name, and
@@ -175,8 +199,8 @@ const structuredData = resolveStructuredData(
     <slot name="head" />
   </head>
   <body class={siteShell.bodyClass} style={siteShell.bodyStyle}>
-    <Shell chrome={chrome} navbar={navbar} footer={footer}>
-      <slot />
+    <Shell chrome={chrome} navbar={navbar} footer={footer} shellId={shellId}>
+      <slot /><RelatedLinks links={linksSlice?.links} label={linksSlice?.label} />
     </Shell>
   </body>
 </html>

package/src/layouts/layout-contract.ts

@@ -0,0 +1,33 @@
+/** The layout surface GENERATORS write against, machine-readable (3.2.0).
+ *  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",
+    "shell",
+  ],
+  /** 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

@@ -9,8 +9,10 @@ import { z } from "astro/zod";
 // hrefs, srcs, ids, or config values.
 //
 //   { "type": "text",  "value": "Visible prose" }
+//   { "type": "markdown", "value": "Prose with [inline links](/pricing)." }
 //   { "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… } ] }
@@ -25,9 +27,27 @@ export interface TextContent {
   value: string;
 }
 
+/** Flowing body copy that needs inline structure a text wrapper cannot hold:
+ *  links mid-sentence, emphasis, headings, lists, images. The value is
+ *  CommonMark, stored as written; the renderer (lib/markdown.ts) compiles it
+ *  at build time with raw HTML disabled, so markup in the value displays as
+ *  literal text rather than becoming elements. One wrapper is one body: the
+ *  whole value is a single edit/translation target, which is what keeps a
+ *  sentence's link inside the sentence that reads around it. */
+export interface MarkdownContent {
+  type: "markdown";
+  value: string;
+}
+
 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 +58,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 +76,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;
@@ -68,8 +106,10 @@ export interface ArrayContent {
 
 export type ContentValue =
   | TextContent
+  | MarkdownContent
   | LinkContent
   | ImageContent
+  | VideoContent
   | SvgContent
   | ColorContent
   | ArrayContent;
@@ -88,24 +128,94 @@ 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',
       ),
   })
   .strict();
 
+// Raw HTML is refused at the schema level, not silently neutralized at render
+// time: an entry carrying `<script>` or `<div>` is a modeling error the author
+// should see at build, and the renderer's escaping is the backstop, not the
+// contract.
+//
+// The gate matches ELEMENT NAMES HTML actually defines, not every `<word>`.
+// CommonMark reads `<int>`, `Promise<T>` and `x<y and a>b` as raw html too,
+// and the safe renderer escapes each one back into exactly the words the
+// author typed, so refusing them rejected correct prose while claiming the
+// author had written markup. A name HTML does not define cannot be a mistaken
+// attempt to render an element, which is the only thing worth refusing.
+//
+// Code is stripped before the check, so markup shown AS copy stays legal,
+// which is what the error message promises: fenced (``` and ~~~), indented,
+// and inline spans, whose closing run must match the opening run (a ``-span
+// legitimately contains a lone backtick). Autolinks (`<https://…>`) never
+// match because a tag name cannot contain `:`.
+const _HTML_ELEMENTS = new Set(
+  `a abbr address area article aside audio b base bdi bdo blockquote body br
+   button canvas caption cite code col colgroup data datalist dd del details
+   dfn dialog div dl dt em embed fieldset figcaption figure footer form h1 h2
+   h3 h4 h5 h6 head header hgroup hr html i iframe img input ins kbd label
+   legend li link main map mark menu meta meter nav noscript object ol optgroup
+   option output p param picture pre progress q rp rt ruby s samp script search
+   section select slot small source span strong style sub summary sup table
+   tbody td template textarea tfoot th thead time title tr track u ul var video
+   wbr svg path circle rect g defs use`.split(/\s+/),
+);
+const _CODE = /(`+)[\s\S]*?\1|~~~[\s\S]*?~~~|(?:^|\n)(?: {4}|\t)[^\n]*/g;
+const _TAG = /<\/?([a-zA-Z][a-zA-Z0-9-]*)(?:[\s/>]|$)/g;
+
+export function carriesRawHtml(value: string): boolean {
+  const prose = value.replace(_CODE, " ");
+  for (const [, name] of prose.matchAll(_TAG)) {
+    if (_HTML_ELEMENTS.has(name.toLowerCase())) return true;
+  }
+  return false;
+}
+
+export const markdownContentSchema = z
+  .object({
+    type: z.literal("markdown"),
+    value: z
+      .string()
+      .refine(
+        (value) => !carriesRawHtml(value),
+        "raw HTML is not part of the markdown grammar: write CommonMark (links, emphasis, headings, lists, images); HTML to display as copy belongs in a code span",
+      ),
+  })
+  .strict();
+
 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 +229,7 @@ export const imageCandidateSchema = z
     src: z.string(),
     assetId: z.string().optional(),
     descriptor: descriptorSchema,
+    type: z.string().optional(),
   })
   .strict();
 
@@ -134,6 +245,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"),
@@ -168,8 +289,10 @@ const propKeySchema = z
 export const contentLeafSchema: z.ZodType<ContentLeaf> = z.lazy(() =>
   z.union([
     textContentSchema,
+    markdownContentSchema,
     linkContentSchema,
     imageContentSchema,
+    videoContentSchema,
     svgContentSchema,
     colorContentSchema,
     arrayContentSchema,
@@ -199,3 +322,120 @@ export const arrayOf = <T extends z.ZodRawShape>(shape: T) =>
       items: z.array(z.object(shape).strict()),
     })
     .strict();
+
+// ---------------------------------------------------------------------------
+// Leaf accessors. Section code receives ContentLeaf, an eight-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 isMarkdownContent(leaf: ContentLeaf): leaf is MarkdownContent {
+  return typeof leaf === "object" && leaf !== null && leaf.type === "markdown";
+}
+
+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 (markdown, 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 markdown wrapper's raw CommonMark source, or null. Rendering it is
+ *  lib/markdown.ts's `renderMarkdown`; the accessor hands back source so
+ *  non-rendering callers (search text, excerpts) are not forced through the
+ *  compiler. */
+export function readMarkdown(
+  leaf: ContentLeaf | null | undefined,
+): string | null {
+  return leaf !== null && leaf !== undefined && isMarkdownContent(leaf)
+    ? leaf.value
+    : null;
+}
+
+/** 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
+    : [];
+}

package/src/lib/markdown.ts

@@ -0,0 +1,17 @@
+import { micromark } from "micromark";
+
+// The one compiler for {type:"markdown"} content values (content-values.ts).
+// Runs at build time inside Astro's static render, so the browser ships HTML,
+// never a markdown runtime. micromark's default is the safety contract the
+// grammar depends on: raw HTML in the source is character-encoded into
+// visible text, not parsed into elements — the schema refuses element-like
+// tags up front, and this default is the backstop for anything that predates
+// or evades the schema. Do not pass allowDangerousHtml here, ever.
+//
+// Headings: a markdown body renders inside a section, below the page's own
+// h1, so authors start at `##`. The compiler does not rewrite heading levels;
+// a body that opens with `#` is an authoring error the review pass catches,
+// not something to silently demote.
+export function renderMarkdown(value: string): string {
+  return micromark(value);
+}