@iterant/site-runtime 3.0.2

package/README.md

@@ -0,0 +1,30 @@
+# @iterant/site-runtime
+
+The site runtime maintained by [Iterant](https://iterant.ai), used in every
+website we build and serve: the content grammar and collection schemas, the SEO
+head and JSON-LD graph, the layout core, the Astro config preset, the dev
+integrations, the platform route handlers, and the verify gates.
+
+Sites on the Iterant platform install this package and keep only their own
+content, components, and design in their repository; everything mechanical
+lives here and is upgraded by version bump. The contract between the package
+and a site is [`docs/runtime-contract.md`](./docs/runtime-contract.md), which
+ships inside the package so a site always reads the guidance for the exact
+version it is pinned to.
+
+## Published as readable source
+
+There is no compiled bundle in this package. What lands in
+`node_modules/@iterant/site-runtime/` are the same `.astro`, `.tsx` and `.ts`
+files we maintain, and a site's own Astro build compiles them together with
+its code. This is deliberate: when something breaks, the stack trace leads to
+a file anyone can open and read. If that file is inside this package, the
+problem is ours; if it is in the site's `src/`, it belongs to the site.
+
+## Intended use
+
+This package exists for websites built and operated on the Iterant platform.
+It is published publicly so those sites can install it without credentials,
+and so anyone can read the code their site runs. It is not a general-purpose
+framework, carries no public support commitment, and its API follows the needs
+of the Iterant platform. All rights reserved.

package/bin/site-runtime.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * The site-runtime CLI: the platform's build and content gates, run from a
+ * brand repo root.
+ *
+ *   site-runtime verify                    # the gate: fonts, islands, lint, check, tests, build, bespoke siblings, editor bytes
+ *   site-runtime scan-copy [files...]      # hardcoded visible copy in component code
+ *   site-runtime scan-island-imports [dir] # island-grade ui primitives imported by registered sections
+ *   site-runtime scan-bespoke-siblings     # bespoke locale-sibling hydration contract (after a build)
+ *
+ * Every gate resolves paths against process.cwd(), so it must be run from the
+ * repo root (`bun run verify`, `npm run verify`, or directly).
+ *
+ * Each subcommand delegates to the gate in ../scripts/. argv is rewritten so
+ * the gate sees exactly what it would see if it had been invoked directly,
+ * which is also how the gates stay runnable on their own inside the package.
+ */
+
+import { fileURLToPath } from "node:url";
+
+const GATES = {
+  verify: "../scripts/verify.mjs",
+  "scan-copy": "../scripts/scan-copy.mjs",
+  "scan-island-imports": "../scripts/scan-island-imports.mjs",
+  "scan-bespoke-siblings": "../scripts/scan-bespoke-siblings.mjs",
+};
+
+const [subcommand, ...args] = process.argv.slice(2);
+const gate =
+  subcommand && Object.hasOwn(GATES, subcommand)
+    ? GATES[/** @type {keyof typeof GATES} */ (subcommand)]
+    : undefined;
+
+if (!gate) {
+  process.stderr.write(
+    `site-runtime: unknown command ${subcommand ? `"${subcommand}"` : "(none given)"}\n` +
+      `usage: site-runtime <${Object.keys(GATES).join("|")}> [args...]\n`,
+  );
+  process.exit(2);
+}
+
+const gatePath = fileURLToPath(new URL(gate, import.meta.url));
+process.argv = [process.argv[0], gatePath, ...args];
+
+await import(gate);

package/docs/runtime-contract.md

@@ -0,0 +1,324 @@
+# The site runtime contract
+
+`@iterant/site-runtime` is the platform layer every Iterant brand site runs on.
+This document is the contract that layer guarantees: the content model, the head
+and structured data rules, the chrome and locale grammar, and the gates that
+enforce them. It ships inside the package, so a repo always reads the guidance
+for the version it is pinned to.
+
+A brand repo's own `AGENTS.md` keeps brand notes and points here.
+
+## Ownership: what to edit, what to read
+
+| Layer                                                                                | Owner    | Rule                    |
+| ------------------------------------------------------------------------------------ | -------- | ----------------------- |
+| `src/content/**` (page entries, chrome), sections, page components, `globals.css`    | brand    | edit freely             |
+| `site-config.ts`, `site-shell.ts`, `components/layout/shell.astro`, section registry | brand    | edit freely             |
+| head + SEO + JSON-LD, layout core, content grammar and collection schemas            | platform | read freely, edit never |
+| Astro config preset, dev integrations, verify gates, platform route handlers         | platform | read freely, edit never |
+
+Platform code sits at `node_modules/@iterant/site-runtime/` as plain source, so
+a stack trace points at a legible file and any tool that reads `src/lib/` reads
+this too. That is deliberate: reading is how you tell whose bug it is. A trace
+into `node_modules/@iterant/site-runtime` means a platform bug, so report it and
+pin or bump; a trace into `src/` means this repo's code.
+
+Editing platform code in place is what the package exists to stop. One patched
+Layout forks that brand forever and it stops receiving fixes. When a brand truly
+needs different behavior, eject the shim instead: paste the file back into the
+repo and mark it, the same convention a replaced `shell.astro` uses. When the
+defect is in the package, say so.
+
+## Content: copy lives in JSON, never in code
+
+No visible string is ever hardcoded in a component. Every heading, paragraph,
+link label, button label and image alt on every page lives in that page's JSON
+entry (`src/content/pages/<page>.json`); navbar and footer copy lives in
+`src/content/chrome.json`. Components receive content as typed props and render
+it. That is what makes every page editable in the visual editor and translatable
+without touching code.
+
+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":"color","value":"…"}`. Repeated content is
+  `{"type":"array","items":[{…}]}`.
+- 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.
+- An image wrapper may carry responsive `srcset` candidates, each a `src` plus a
+  width (`"400w"`) or density (`"2x"`) descriptor.
+- Every component has a stable kebab-case `id`, unique per entry, assigned once
+  and NEVER renamed: edits and translations are addressed through it.
+- 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
+  are wrapper-level (`props.heading`, `props.features.0.title`), never
+  leaf-level. Array containers carry `data-array-container="<field>"`, items
+  `data-array-item={index}`.
+- Rendering may transform copy for presentation (highlighting a word, splitting
+  on a separator) only with operands that come from the entry: add a field for
+  the term and use it. Never a literal in TSX, and never "correct" entry copy in
+  code: what looks like a typo may be brand voice or deliberate test data.
+- `site-runtime scan-copy` finds hardcoded copy in component code. Like every
+  gate, never edit or weaken it.
+
+### The collection schemas
+
+The repo's `src/content.config.ts` is a shim over `createCollections`, which
+takes the two brand-owned registries and returns the `pages` and `chrome`
+collections:
+
+```ts
+import { createCollections } from "@iterant/site-runtime/content";
+import { CHROME_COMPONENT_PROPS } from "@iterant/site-runtime/chrome-schemas";
+import { REGISTERED_SECTION_PROPS } from "./lib/section-schemas";
+
+export const collections = createCollections({
+  registeredSectionProps: REGISTERED_SECTION_PROPS,
+  chromeComponentProps: CHROME_COMPONENT_PROPS,
+});
+```
+
+WHICH section types exist is brand-owned. The grammar around them is not: entry
+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.
+
+## Pages: entry-driven vs bespoke
+
+Every page has a JSON entry holding its route, SEO meta and content. What
+differs is who renders it.
+
+**Entry-driven** (`"mode": "registry"`, the default): the catch-all
+`src/pages/[...slug].astro` resolves the request path against each entry's
+`route` at request time and renders its `components` through the repo's section
+registry. Cheap to create, cheap to edit, schema-validated. Use it for pages
+that are a linear stack of known section types.
+
+Registered sections are server-rendered, never hydrated: Astro cannot statically
+trace `client:*` directives through a registry map, so adding one renders
+nothing. Keep section components presentational. A section that needs client JS
+is a signal the page should be bespoke instead, and the island-import gate fails
+the build on an island-grade primitive imported under
+`src/components/sections/`.
+
+**Bespoke** (real code): set `"mode": "bespoke"` in the entry, create the React
+page at `src/components/pages/<page>/page.tsx`, and a thin Astro shell at
+`src/pages/<page>.astro` that loads the entry and threads it down. Static routes
+win over the catch-all automatically. The COPY still comes from the entry,
+always.
+
+Write in this order: entry JSON, then `page.tsx`, then the route shell LAST. The
+route goes live the moment the shell lands. While a route is broken mid-edit the
+dev server swaps the error page for `/under-construction`, which is a platform
+route: never delete, rename, or link to it.
+
+Two conventions make a bespoke page's locale siblings hydrate, and both break
+silently: the page component lives at `src/components/pages/<page>/page.tsx` as
+the module's default or sole function export, and the shell hydrates it with
+`client:load` importing from `@/components/pages/<page>/page`. That static import
+is what puts the component in the client bundle siblings hydrate from. The
+bespoke-sibling gate enforces both on every non-draft bespoke page, after the
+build.
+
+## Structured data is derived, never authored
+
+Every indexable page emits a schema.org graph (Organization, WebSite, the page
+node, BreadcrumbList, plus a Product node on product pages) built
+deterministically from the entry meta and the canonical URL. Your only job is to
+declare what the page IS:
+
+```json
+"meta": { "pageType": "article", "datePublished": "2026-08-09" }
+```
+
+Values: `article` (blog posts, guides, case studies; set `datePublished`, and
+touch `dateModified` on substantial updates), `product` (product and pricing
+pages), `about`, `contact`, or omit for a plain WebPage.
+
+The layout resolves the entry by route itself, so neither the catch-all nor a
+bespoke shell threads any of this. Do not hand-write JSON-LD for types this
+covers. For a genuinely custom schema (Service, Event, FAQ) pass a typed object
+through the layout's `jsonLd` prop or render `SeoJson` beside the visible content
+it describes; it merges into the graph and overrides any default node sharing its
+`@type`.
+
+## The layout
+
+`src/layouts/Layout.astro` in the repo is a shim over
+`@iterant/site-runtime/layout`. It injects the three brand-owned values and
+imports `globals.css`:
+
+```astro
+---
+import LayoutCore from "@iterant/site-runtime/layout";
+import "../styles/globals.css";
+import Shell from "@/components/layout/shell.astro";
+import { SITE_CONFIG } from "@/site-config";
+import { SITE_SHELL } from "@/site-shell";
+---
+
+<LayoutCore
+  {...Astro.props}
+  siteConfig={SITE_CONFIG}
+  siteShell={SITE_SHELL}
+  Shell={Shell}
+>
+  <slot name="head" slot="head" />
+  <slot />
+</LayoutCore>
+```
+
+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
+components: `shell.astro` mounts those, which is what keeps their `client:load`
+directive traceable.
+
+### The one `@source` line
+
+Tailwind v4 needs a `@source` line for anything outside the repo it should scan
+for class names. Point it at ONE file:
+
+```css
+@source "../../node_modules/@iterant/site-runtime/src/routes/UnderConstruction.astro";
+```
+
+That is the only shipped file with real utility classes, and the package's own
+suite fails if a second one appears. Do not point `@source` at the whole
+`src` tree: Tailwind's extractor cannot tell prose from markup, so every
+utility-shaped word in a comment or a validation message (`lowercase`,
+`sticky`, `transition`) becomes a real rule in every page's stylesheet.
+
+## Chrome (navbar and footer)
+
+Navbar and footer are structural, built once per brand, rendered on every page,
+but their copy lives in `src/content/chrome.json` under the same component
+grammar, one component per piece (`"id": "navbar"`, `"id": "footer"`). The layout
+mounts ONLY those two ids, resolved by id, so an absent component renders no
+chrome at all. Any other id in `chrome.json` is a hard schema error rather than a
+silent no-op: an announcement or utility bar belongs in a page section adjacent
+to the chrome. A component whose `type` does not match its `id` is also an error,
+because it validates the wrong props and renders nothing. Clone-emitted chrome is
+the one exception: `type: "replicated"` on a known id carries its copy in bespoke
+props.
+
+A locale-prefixed request mounts `chrome.<locale>.json` when that sibling exists
+and falls back to the base chrome otherwise, because pages translate before
+chrome does and a missing sibling must never strip the nav.
+
+## Locales
+
+A translated page is a first-class entry next to its base:
+`src/content/pages/<page>.<locale>.json`, with the lowercased locale as both the
+filename suffix and the route prefix (`/es/pricing`). The unsuffixed base stays
+the x-default. Chrome follows the same model.
+
+The shell emits `<html lang>` and the reciprocal hreflang set by threading
+`pageLocaleHead`. Every non-draft entry in a group contributes one alternate plus
+exactly one `x-default` pointing at the base; a page with no siblings emits
+nothing, and draft siblings are never advertised. A bespoke page's locale
+siblings need no per-page work: the catch-all renders them through the base's
+page component with the sibling's translated `components`.
+
+## Sitemap and platform routes
+
+`sitemap-index.xml` is generated at build by the preset's sitemap wiring.
+Prerendered pages are included automatically; SSR routes are invisible to
+`@astrojs/sitemap`, so their paths are read from the page entries on disk (each
+non-draft entry's `route`), resolved against Astro's own project root at
+`astro:config:setup`. A build driven from any directory therefore lists the same
+routes, and a page directory that reads empty is logged rather than silently
+dropped. The `site` value in `astro.config.mjs` is patched at deploy time by the
+platform and must remain a string literal, so the sitemap helper emits against a
+placeholder host and swaps it at emit time.
+
+Platform routes stay VISIBLE files in `src/pages/`, each a shim over a package
+handler. Nothing is injected: existence and addressing stay repo-owned so the
+`src/pages/` mental model holds, while the behavior rides the bump. A repo
+carries FOUR of them, all four unconditionally:
+
+| File                                   | Handler                     | `prerender` |
+| -------------------------------------- | --------------------------- | ----------- |
+| `src/pages/llms.txt.ts`                | `createLlmsTxtRoute`        | `true`      |
+| `src/pages/robots.txt.ts`              | `createRobotsTxtRoute`      | `true`      |
+| `src/pages/sitemap.xml.ts`             | `createSitemapRoute`        | `false`     |
+| `src/pages/proxied-sitemap-[i].xml.ts` | `createProxiedSitemapRoute` | `false`     |
+
+The two sitemap-proxy files are the ones easy to skip, and skipping them is how a
+brand loses its mirrored sitemap: they carry no logic of their own, so a repo
+cannot tell from its own tree that `sourceSitemapUrl` has nowhere to be served
+from. Both handlers answer 404 when no upstream is configured, which is what the
+routes did when they existed only for brands that had one. That 404 is a plain
+`text/plain` body from the handler rather than the branded 404 page a missing
+route would have rendered, the one intentional difference.
+
+`src/pages/under-construction.astro` is the fifth platform route, a three-line
+shim over the package's `UnderConstruction` component (see The layout).
+
+## The config preset
+
+`astro.config.mjs` keeps only per-site values and spreads the preset:
+
+```js
+export default defineConfig({
+  // Patched at deploy time by the platform: must remain a string literal.
+  site: "https://example.com",
+  ...iterantStarter(),
+});
+```
+
+The preset carries the adapter, the integrations (React, sitemap, and the
+dev-only plugin loader, preview error shell and new-file reload), the vite
+tuning, the dev server port and host, and the toolbar setting. A diverged repo
+extends rather than ejects: extra integrations and vite plugins append through
+`overrides`, and any other key it needs it writes in its own `defineConfig`
+object after the spread.
+
+## Verify: the gate
+
+`bun run verify` maps to `site-runtime verify` and is the gate. It is silent on
+success and prints the failing step's full output on failure. If it fails, the
+change is broken. In order:
+
+1. **font integrity**: every `public/fonts/*.woff2` is a real WOFF2 whose header
+   size matches the file, and every local `@font-face` URL resolves. Corrupt
+   fonts fail silently at runtime, with a green build.
+2. **island imports**: no island-grade ui primitive is imported under
+   `src/components/sections/`.
+3. **eslint**, then **astro check**, then the repo's own unit tests, then
+   **astro build**.
+4. **bespoke siblings**: every non-draft bespoke page satisfies the two
+   hydration conventions, checked against the fresh `dist/`, plus a pin on the
+   Astro runtime directive contract they rely on.
+5. **editor bytes**: a production build contains zero visual-editor bytes.
+
+Other subcommands: `site-runtime scan-copy [files...]`,
+`site-runtime scan-island-imports [dir]`, `site-runtime scan-bespoke-siblings`.
+All of them resolve paths against the current working directory, so run them
+from the repo root.
+
+New gates arrive advisory. A bump may land a check in warn mode and record the
+debt for the brand's next session rather than failing a fleet of builds at once;
+a gate is promoted to failing only in a later major.
+
+## Version identity
+
+The installed package version IS the site's runtime version. Every page emits
+`<meta name="it-site-runtime" content="<version>">`, read straight from the
+package, so there is nothing to re-stamp on a bump.
+`<meta name="it-astro-starter-version">` keeps emitting the same value for now,
+because the plugin loader and the platform's page indexer still read that name.
+
+One vestigial file rides along with it: a repo keeps `src/starter-version.ts`
+exporting the same version string (`"3.0.0"`) until the platform agent reads the
+package pin instead. The agent's capability resolution treats a MISSING
+`starter-version.ts` as the oldest possible starter and degrades accordingly, so
+deleting the file early costs a brand its newest capabilities. Nothing in the
+package reads it, and it goes away with that read.

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@iterant/site-runtime",
+  "version": "3.0.2",
+  "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": {
+    "clean": "git clean -xdf .cache .turbo node_modules fixtures",
+    "format": "prettier --check \"**/*.{js,cjs,mjs,ts,tsx,mdx}\" --ignore-path=\"../../.prettierignore\"",
+    "format:fix": "prettier --write \"**/*.{js,cjs,mjs,ts,tsx,mdx}\" --ignore-path=\"../../.prettierignore\"",
+    "lint": "eslint . --max-warnings 0",
+    "lint:fix": "eslint --fix .",
+    "test": "vitest run && node scripts/check-fixture.mjs",
+    "test:fixture": "node scripts/check-fixture.mjs",
+    "test:packed": "node scripts/check-packed.mjs",
+    "test:unit": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "bin": {
+    "site-runtime": "./bin/site-runtime.mjs"
+  },
+  "files": [
+    "bin",
+    "docs",
+    "scripts",
+    "src",
+    "!**/*.test.ts",
+    "!scripts/check-fixture.mjs",
+    "!scripts/check-packed.mjs",
+    "!src/lib/__fixtures__"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./content": "./src/content/collections.ts",
+    "./content/schema": "./src/content/schema.ts",
+    "./content-values": "./src/lib/content-values.ts",
+    "./locales": "./src/lib/locales.ts",
+    "./hreflang": "./src/lib/hreflang.ts",
+    "./chrome": "./src/lib/chrome.ts",
+    "./chrome-schemas": "./src/lib/chrome-schemas.ts",
+    "./bespoke-pages": "./src/lib/bespoke-pages.ts",
+    "./sitemap": "./src/lib/sitemap/index.ts",
+    "./seo": "./src/components/seo.tsx",
+    "./seo-json": "./src/components/seo-json.tsx",
+    "./layout": "./src/layouts/LayoutCore.astro",
+    "./under-construction": "./src/routes/UnderConstruction.astro",
+    "./routes": "./src/routes/index.ts",
+    "./config": "./src/config/preset.ts",
+    "./integrations/*": "./src/integrations/*.mjs",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@astrojs/cloudflare": "^13.1.10",
+    "@astrojs/react": "^5.0.3",
+    "@astrojs/sitemap": "^3.7.2",
+    "schema-dts": "^2.0.0"
+  },
+  "peerDependencies": {
+    "@tailwindcss/vite": "^4.1.18",
+    "astro": "^6.1.8",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "tailwindcss": "^4.1.18",
+    "typescript": ">=5.6"
+  },
+  "devDependencies": {
+    "@astrojs/check": "^0.9.8",
+    "@tailwindcss/vite": "4.2.2",
+    "@types/node": "24.3.1",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "@workspace/eslint-config": "workspace:*",
+    "@workspace/typescript-config": "workspace:*",
+    "astro": "^6.1.8",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
+    "tailwindcss": "4.2.2",
+    "typescript": "5.9.2",
+    "vitest": "^4.0.13",
+    "wrangler": "^4.107.0"
+  },
+  "license": "UNLICENSED",
+  "homepage": "https://iterant.ai"
+}

package/scripts/scan-bespoke-siblings.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * Bespoke-sibling hydration gate (starter 2.10.0 / PSI-B.5). Runs AFTER
+ * `astro build` (verify.mjs sequences it) against the fresh dist/.
+ *
+ * A bespoke page's locale siblings (`home.es.json`, route `/es`) render
+ * through the catch-all, which hydrates the base's page component by passing
+ * the shell's import specifier (`@/components/pages/<base>/page`) as
+ * `client:component-path`. Two conventions make that work, and BOTH break
+ * SILENTLY at runtime — an unhydrated sibling, or a base-renders/sibling-404s
+ * export mismatch — with zero build signal:
+ *
+ *   1. the shell hydrates the page component with `client:load` from
+ *      `@/components/pages/<base>/page`: that static import is what puts the
+ *      component in the client bundle, keyed by that exact specifier in the
+ *      built SSR manifest's entryModules;
+ *   2. `page.tsx` exposes the page as its default or sole function export —
+ *      the shape the catch-all's pickPageExport (src/lib/bespoke-pages.ts)
+ *      resolves.
+ *
+ * For every NON-DRAFT bespoke base entry, this asserts (1) against the built
+ * manifest and (2) by importing the built client entry itself. Draft bespoke
+ * pages are exempt: drafts never publish, their siblings are never advertised
+ * (hreflang/sitemap), and the stock `not-found` page is a draft that
+ * deliberately lives outside the `<base>/page.tsx` convention (404.astro
+ * renders it). Publishing a bespoke page puts it in scope on the next verify.
+ *
+ * It also pins the Astro runtime contract the catch-all relies on: the island
+ * renderer must keep accepting `client:component-path` /
+ * `client:component-export` as props (astro/dist/runtime/server/hydration.js
+ * `extractDirectives`). An Astro upgrade that changes directive handling
+ * turns this gate red instead of silently shipping unhydratable siblings.
+ *
+ * Silent on success; problems go to stderr with exit 1 (verify.mjs surfaces
+ * the buffer on failure). Like verify.mjs and scan-copy.mjs, never edit or
+ * weaken this script.
+ */
+
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { exit } from "node:process";
+
+const CONVENTIONS =
+  "bespoke pages must keep their page component at " +
+  "src/components/pages/<page>/page.tsx (default or sole function export) " +
+  "and their shell must render it with `client:load` importing from " +
+  '"@/components/pages/<page>/page" — see AGENTS.md "Pages: entry-driven vs bespoke"';
+
+/** @type {string[]} */
+const problems = [];
+
+// ---- SF-pin: the Astro runtime directive contract --------------------------
+
+const hydrationJs = join(
+  process.cwd(),
+  "node_modules/astro/dist/runtime/server/hydration.js",
+);
+const hydrationSrc = await readFile(hydrationJs, "utf8").catch(() => "");
+for (const directive of ["client:component-path", "client:component-export"]) {
+  if (!hydrationSrc.includes(`case "${directive}"`)) {
+    problems.push(
+      `astro runtime contract changed: ${hydrationJs} no longer handles ` +
+        `"${directive}" as a prop. Bespoke locale siblings hydrate through ` +
+        `exactly that escape hatch (src/pages/[...slug].astro) — re-verify ` +
+        `sibling hydration against this Astro version before shipping.`,
+    );
+  }
+}
+
+// ---- SF1+SF2: every non-draft bespoke base ---------------------------------
+
+/** Non-draft bespoke base entry ids (`home`), never locale siblings. */
+async function bespokeBases() {
+  const pagesDir = join(process.cwd(), "src/content/pages");
+  /** @type {string[]} */
+  const bases = [];
+  /** @type {string[]} */
+  let names = [];
+  try {
+    names = await readdir(pagesDir);
+  } catch {
+    return bases; // no pages dir — astro check owns that failure
+  }
+  for (const name of names.filter((n) => n.endsWith(".json")).sort()) {
+    const id = name.replace(/\.json$/, "");
+    if (id.includes(".")) continue; // locale sibling — guarded via its base
+    /** @type {{ mode?: string; draft?: boolean }} */
+    let entry;
+    try {
+      entry = JSON.parse(await readFile(join(pagesDir, name), "utf8"));
+    } catch {
+      continue; // unparseable JSON is astro check's failure, not ours
+    }
+    if (entry.mode === "bespoke" && entry.draft !== true) bases.push(id);
+  }
+  return bases;
+}
+
+/**
+ * The built SSR manifest's entryModules map (import specifier → client
+ * asset). Serialized inside one of the server chunks; values are plain
+ * strings, so the object literal is brace-free and parses as JSON.
+ * @returns {Promise<Record<string, string> | null>}
+ */
+async function builtEntryModules() {
+  const serverDir = join(process.cwd(), "dist/server");
+  /** @type {string[]} */
+  const stack = [serverDir];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    if (!dir) break;
+    /** @type {import("node:fs").Dirent[]} */
+    let entries = [];
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(path);
+        continue;
+      }
+      if (!entry.name.endsWith(".mjs")) continue;
+      const content = await readFile(path, "utf8");
+      const match = /"entryModules":(\{[^{}]*\})/.exec(content);
+      if (match) return JSON.parse(match[1]);
+    }
+  }
+  return null;
+}
+
+const bases = await bespokeBases();
+if (bases.length > 0 && problems.length === 0) {
+  const entryModules = await builtEntryModules();
+  if (!entryModules) {
+    problems.push(
+      "could not locate the entryModules manifest in dist/server — run this " +
+        "gate after `astro build` (verify.mjs does), and if the build layout " +
+        "changed, update scan-bespoke-siblings.mjs to match.",
+    );
+  } else {
+    for (const base of bases) {
+      const specifier = `@/components/pages/${base}/page`;
+      const asset = entryModules[specifier];
+      if (!asset) {
+        problems.push(
+          `bespoke page "${base}": "${specifier}" is not a client entry in ` +
+            `the built manifest, so its locale siblings would render ` +
+            `UNHYDRATED (dead buttons, no client JS) — ${CONVENTIONS}.`,
+        );
+        continue;
+      }
+      // Import the built client entry — the same module the sibling's island
+      // loads in the browser — and hold it to pickPageExport's shape.
+      const assetPath = join(process.cwd(), "dist/client", asset.split("?")[0]);
+      /** @type {Record<string, unknown>} */
+      let mod;
+      try {
+        mod = await import(pathToFileURL(assetPath).href);
+      } catch (err) {
+        problems.push(
+          `bespoke page "${base}": built client entry ${asset} failed to ` +
+            `import (${err instanceof Error ? err.message : err}) — its ` +
+            `locale siblings could not hydrate.`,
+        );
+        continue;
+      }
+      const fns = Object.values(mod).filter((v) => typeof v === "function");
+      if (typeof mod.default !== "function" && fns.length !== 1) {
+        problems.push(
+          `bespoke page "${base}": src/components/pages/${base}/page.tsx ` +
+            `exports ${fns.length} functions and no default — the catch-all ` +
+            `cannot pick the page component, so its locale siblings would ` +
+            `404 while the base page keeps working — ${CONVENTIONS}.`,
+        );
+      }
+    }
+  }
+}
+
+if (problems.length > 0) {
+  process.stderr.write(
+    `bespoke-sibling gate failed:\n${problems.join("\n")}\n`,
+  );
+  exit(1);
+}
+exit(0);