@iterant/site-runtime 3.0.2 → 3.1.2

package/docs/runtime-contract.md

@@ -29,6 +29,63 @@ 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.
 
+## Available libraries
+
+This package installs the toolchain and a curated kit, so a repo's own
+`package.json` is nearly empty and every entry in it reads as a deliberate
+divergence from a platform default.
+
+**Import kit libraries directly. Declare one in `package.json` ONLY to override
+the platform version.** `import { ArrowRight } from "lucide-react"` works with
+nothing added to the manifest; the copy comes from this package. Adding your own
+entry wins node resolution, which is exactly how an override is expressed, and it
+also means platform bumps stop moving that library: `site-runtime verify` reports
+every override it finds, and never fails on one.
+
+The toolchain is different in one way: it is NOT overridable. A repo that
+declares `astro`, `react` or `tailwindcss` installs a second copy, and then
+`astro build` runs one version while these gates check another. Verify fails on
+such a declaration. A repo that truly needs its own toolchain version ejects the
+runtime and says so.
+
+<!-- generated: available libraries -->
+
+_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.1.2._
+
+**Toolchain** (this package owns the version; do NOT declare these):
+
+| Package               | Version | What it is                                       |
+| --------------------- | ------- | ------------------------------------------------ |
+| `astro`               | 7.2.0   | the framework: routing, content collections, SSR |
+| `react`               | 19.2.8  | islands and bespoke page components              |
+| `react-dom`           | 19.2.8  | React's DOM renderer                             |
+| `tailwindcss`         | 4.3.3   | the utility CSS engine                           |
+| `@tailwindcss/vite`   | 4.3.3   | Tailwind's build integration                     |
+| `@astrojs/cloudflare` | 14.2.0  | the Workers adapter                              |
+| `@astrojs/react`      | 6.0.2   | the React renderer integration                   |
+| `@astrojs/sitemap`    | 3.7.3   | sitemap generation                               |
+| `@astrojs/check`      | 0.9.10  | the type checker `astro check` runs              |
+
+**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                    |
+
+<!-- /generated -->
+
+Anything else a page genuinely needs is a normal repo dependency, invisible to
+the platform: install it, declare it, own it.
+
 ## Content: copy lives in JSON, never in code
 
 No visible string is ever hardcoded in a component. Every heading, paragraph,
@@ -276,28 +333,55 @@ export default defineConfig({
 
 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
+tuning, the CSS browser floor, 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.
 
+### The browser floor
+
+The preset declares the browsers every brand site's CSS is compiled for, to
+Lightning CSS (Vite's minifier): **Safari 16.4, Chrome 111, Firefox 128**. That is
+Tailwind v4's own floor, and the floor the emitted stylesheet already has, since
+it ships `@property` declarations and `color-mix()` calls with no fallbacks. Stated
+rather than inherited, because with no targets the minifier leaves whatever syntax
+Tailwind emitted: breakpoints go out as `@media (width>=40rem)`, which older
+engines do not parse, so every breakpoint in the sheet silently stops applying on
+them.
+
+A repo must not set `build.cssTarget` itself. Wanting older browsers is a platform
+conversation: lowering the floor to Safari 15 does restore `min-width` breakpoints
+and costs 7.5K of fallbacks on the template's own sheet, for engines that still
+cannot render its `@property` and `color-mix()` values.
+
 ## 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
+1. **dependency tiers**: this repo declares no toolchain package, every toolchain
+   package RESOLVES the version this runtime declares (an `overrides` entry
+   declares nothing, so the installed manifests are what get read), and exactly
+   one astro resolves.
+2. **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
+3. **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
+4. **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
+5. **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.
+6. **prerendered pages**: every `.html` the build wrote is an HTML document. A
+   prerendered route renders inside workerd, and when that goes wrong the build
+   still exits 0 and the file holds whatever the failure stringified to. The usual
+   cause is a wrangler `compatibility_date` earlier than `2026-02-19`, which makes
+   every page render as the string `[object Object]`.
+7. **editor bytes**: a production build contains zero visual-editor bytes.
+8. **kit overrides**: advisory only, printed after everything passes.
 
 Other subcommands: `site-runtime scan-copy [files...]`,
 `site-runtime scan-island-imports [dir]`, `site-runtime scan-bespoke-siblings`.

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@iterant/site-runtime",
-  "version": "3.0.2",
+  "version": "3.1.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\"",
+    "kit-table": "node scripts/generate-kit-table.mjs",
     "lint": "eslint . --max-warnings 0",
     "lint:fix": "eslint --fix .",
+    "preversion": "node scripts/generate-kit-table.mjs",
     "test": "vitest run && node scripts/check-fixture.mjs",
     "test:fixture": "node scripts/check-fixture.mjs",
     "test:packed": "node scripts/check-packed.mjs",
@@ -27,6 +29,7 @@
     "!**/*.test.ts",
     "!scripts/check-fixture.mjs",
     "!scripts/check-packed.mjs",
+    "!scripts/generate-kit-table.mjs",
     "!src/lib/__fixtures__"
   ],
   "exports": {
@@ -49,32 +52,62 @@
     "./integrations/*": "./src/integrations/*.mjs",
     "./package.json": "./package.json"
   },
+  "iterant": {
+    "toolchain": [
+      "astro",
+      "react",
+      "react-dom",
+      "tailwindcss",
+      "@tailwindcss/vite",
+      "@astrojs/cloudflare",
+      "@astrojs/react",
+      "@astrojs/sitemap",
+      "@astrojs/check"
+    ],
+    "kit": [
+      "lucide-react",
+      "motion",
+      "radix-ui",
+      "@radix-ui/react-slot",
+      "embla-carousel-react",
+      "clsx",
+      "tailwind-merge",
+      "class-variance-authority",
+      "tw-animate-css",
+      "github-slugger"
+    ]
+  },
   "dependencies": {
-    "@astrojs/cloudflare": "^13.1.10",
-    "@astrojs/react": "^5.0.3",
-    "@astrojs/sitemap": "^3.7.2",
-    "schema-dts": "^2.0.0"
+    "@astrojs/check": "0.9.10",
+    "@astrojs/cloudflare": "14.2.0",
+    "@astrojs/react": "6.0.2",
+    "@astrojs/sitemap": "3.7.3",
+    "@radix-ui/react-slot": "1.3.3",
+    "@tailwindcss/vite": "4.3.3",
+    "astro": "7.2.0",
+    "class-variance-authority": "0.7.1",
+    "clsx": "2.1.1",
+    "embla-carousel-react": "8.6.0",
+    "github-slugger": "2.0.0",
+    "lucide-react": "1.31.0",
+    "motion": "13.0.0",
+    "radix-ui": "1.6.7",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "schema-dts": "2.0.0",
+    "tailwind-merge": "3.6.0",
+    "tailwindcss": "4.3.3",
+    "tw-animate-css": "1.4.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"
+    "typescript": "^5.6.0 || ^6.0.0"
   },
   "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"

package/scripts/dependency-tiers.mjs

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * The dependency-tier gates. Since 3.1.0 this package OWNS the toolchain and
+ * ships a curated kit, so who declares what is a checkable fact:
+ *
+ *   Tier 1, the toolchain (astro, react, react-dom, tailwind + its vite plugin,
+ *   the adapters, astro check). Package-versioned, exact, NOT overridable. A
+ *   repo that declares one of these installs a SECOND copy: `astro dev` then
+ *   resolves one version while the runtime's components were built and gated
+ *   against another, and two reacts in one page break hooks with no build
+ *   signal. So a declaration FAILS verify (`checkToolchainDeclarations`), and
+ *   exactly one astro has to resolve from the repo root (`checkAstroCopies`).
+ *
+ *   Tier 2, the curated kit (lucide-react, motion, radix, embla, clsx and
+ *   friends). The package's version is the platform DEFAULT and a repo
+ *   overrides it by simply declaring its own: node resolution puts the
+ *   top-level copy first, so no mechanism is needed and none is added. The
+ *   override is reported, never blocked (`reportKitOverrides`), which is the
+ *   guidance-over-gates posture applied to dependencies.
+ *
+ * Both tiers are read from this package's own package.json: the names from
+ * `iterant.toolchain` / `iterant.kit`, the versions from `dependencies`. That
+ * is the single place a library is added or moved between tiers, and it is the
+ * same source docs/runtime-contract.md's available-libraries table is generated
+ * from, so the table cannot drift from what installs.
+ *
+ * Imported by scripts/verify.mjs. Runs standalone for a quick read:
+ * `node scripts/dependency-tiers.mjs [repoDir]`.
+ */
+
+import { readdir, readFile, realpath } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
+
+/** @typedef {{ name: string; version: string }} Library */
+
+/** @param {string} path */
+async function readJson(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * This package's own manifest: the source of truth for both tiers.
+ *
+ * @returns {Promise<{ name: string; version: string; toolchain: Library[]; kit: Library[] }>}
+ */
+export async function readRuntimeTiers() {
+  const manifest = await readJson(join(PACKAGE_ROOT, "package.json"));
+  if (!manifest) {
+    throw new Error(
+      "dependency-tiers: @iterant/site-runtime's own package.json is unreadable",
+    );
+  }
+  const dependencies = manifest.dependencies ?? {};
+  /** @param {unknown} names */
+  const libraries = (names) =>
+    (Array.isArray(names) ? names : []).map((name) => ({
+      name: String(name),
+      version: String(dependencies[String(name)] ?? ""),
+    }));
+  return {
+    name: manifest.name,
+    version: manifest.version,
+    toolchain: libraries(manifest.iterant?.toolchain),
+    kit: libraries(manifest.iterant?.kit),
+  };
+}
+
+/** Every dependency map a repo can declare a package in. */
+const DECLARED_IN = [
+  "dependencies",
+  "devDependencies",
+  "optionalDependencies",
+  "peerDependencies",
+];
+
+/**
+ * @param {Record<string, unknown> | null} manifest
+ * @param {string} name
+ * @returns {{ field: string; range: string } | null}
+ */
+function declaration(manifest, name) {
+  if (!manifest) return null;
+  for (const field of DECLARED_IN) {
+    const map = manifest[field];
+    if (!map || typeof map !== "object") continue;
+    const range = /** @type {Record<string, unknown>} */ (map)[name];
+    if (typeof range === "string") return { field, range };
+  }
+  return null;
+}
+
+/**
+ * Tier-1 declaration gate. Returns one problem per declared toolchain package,
+ * each naming the eject path, plus a closing line with the whole list.
+ *
+ * @param {string} repoDir
+ * @returns {Promise<string[]>}
+ */
+export async function checkToolchainDeclarations(repoDir) {
+  const { toolchain, version } = await readRuntimeTiers();
+  const manifest = await readJson(join(repoDir, "package.json"));
+  const problems = [];
+  for (const { name, version: owned } of toolchain) {
+    const declared = declaration(manifest, name);
+    if (!declared) continue;
+    problems.push(
+      `package.json declares ${name}@${declared.range} in ${declared.field}, but @iterant/site-runtime ${version} owns it at ${owned}. ` +
+        `Remove the entry and reinstall: the runtime installs the toolchain, and \`astro dev\` / \`astro build\` resolve from that one hoisted copy.`,
+    );
+  }
+  if (problems.length > 0) {
+    problems.push(
+      `The toolchain is ${toolchain.map(({ name }) => name).join(", ")}. ` +
+        `A repo that genuinely needs different versions ejects the runtime: drop the @iterant/site-runtime dependency and paste the platform files back into src/, ` +
+        `the same marker convention a replaced shell.astro uses. Say so when you do, because an ejected repo stops receiving platform fixes.`,
+    );
+  }
+  return problems;
+}
+
+/**
+ * Tier-1 version gate: what is INSTALLED has to be what this runtime declares.
+ *
+ * The declaration gate reads the four dependency maps, which is where a repo
+ * declares a package, and that is exactly the hole: `overrides` (npm, bun) and
+ * `resolutions` (yarn) pin a version without appearing in any of them, so a repo
+ * could hold astro at 6.4.8 and pass every other check. The copy count does not
+ * see it either, since one copy of the wrong version is still one copy. Reading
+ * the installed manifests answers the question the other two only approximate,
+ * and it covers every tier-1 package rather than astro alone: react resolving a
+ * major behind is the same class of break and used to go unmentioned.
+ *
+ * A missing package is NOT reported here. That is either a repo the runtime was
+ * never installed in, which the astro-copy check states more usefully, or an
+ * optional-in-practice tool, and a gate that fires twice for one cause teaches
+ * people to skim it.
+ *
+ * @param {string} repoDir
+ * @returns {Promise<string[]>}
+ */
+export async function checkToolchainVersions(repoDir) {
+  const { toolchain, version } = await readRuntimeTiers();
+  /** @type {string[]} */
+  const problems = [];
+  for (const { name, version: owned } of toolchain) {
+    const installed = await readJson(
+      join(repoDir, "node_modules", name, "package.json"),
+    );
+    if (!installed?.version) continue;
+    if (String(installed.version) === owned) continue;
+    problems.push(
+      `${name} resolves ${installed.version}, but @iterant/site-runtime ${version} is built and gated against ${owned}. ` +
+        `Nothing in package.json's dependencies asks for that version, so it comes from an \`overrides\` / \`resolutions\` entry or a stale lockfile: ` +
+        `remove the pin and reinstall. A toolchain the runtime did not choose is a runtime nobody tested.`,
+    );
+  }
+  return problems;
+}
+
+/**
+ * Every astro copy reachable from the repo root: the hoisted one plus any
+ * nested under a top-level dependency. Deduplicated by real path, because the
+ * same install shows up as both a symlink and its target.
+ *
+ * @param {string} repoDir
+ * @returns {Promise<Array<{ path: string; version: string }>>}
+ */
+async function resolveAstroCopies(repoDir) {
+  const modules = join(repoDir, "node_modules");
+  /** @type {string[]} */
+  const candidates = [join(modules, "astro")];
+  /** @type {import("node:fs").Dirent[]} */
+  let entries = [];
+  try {
+    entries = await readdir(modules, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue;
+    // A scope directory holds packages, not a package: descend one more level.
+    if (entry.name.startsWith("@")) {
+      /** @type {import("node:fs").Dirent[]} */
+      let scoped = [];
+      try {
+        scoped = await readdir(join(modules, entry.name), {
+          withFileTypes: true,
+        });
+      } catch {
+        continue;
+      }
+      for (const inner of scoped) {
+        candidates.push(
+          join(modules, entry.name, inner.name, "node_modules", "astro"),
+        );
+      }
+      continue;
+    }
+    candidates.push(join(modules, entry.name, "node_modules", "astro"));
+  }
+
+  /** @type {Map<string, { path: string; version: string }>} */
+  const found = new Map();
+  for (const candidate of candidates) {
+    const manifest = await readJson(join(candidate, "package.json"));
+    if (!manifest?.version) continue;
+    const key = await realpath(candidate).catch(() => candidate);
+    if (found.has(key)) continue;
+    found.set(key, { path: candidate, version: String(manifest.version) });
+  }
+  return [...found.values()];
+}
+
+/**
+ * Single-copy invariant. Two astros mean the build and the gates can disagree
+ * about which one ran; none means the toolchain never installed.
+ *
+ * @param {string} repoDir
+ * @returns {Promise<string[]>}
+ */
+export async function checkAstroCopies(repoDir) {
+  const copies = await resolveAstroCopies(repoDir);
+  if (copies.length === 1) return [];
+  if (copies.length === 0) {
+    return [
+      "no astro resolves from this repo. The toolchain installs with @iterant/site-runtime, so this is an incomplete install: reinstall from the repo root.",
+    ];
+  }
+  return [
+    `${copies.length} copies of astro resolve from this repo, so the build and these gates can run different versions:\n` +
+      copies.map(({ path, version }) => `  ${version}  ${path}`).join("\n") +
+      "\nRemove the duplicate declaration and reinstall.",
+  ];
+}
+
+/**
+ * Tier-2 override report. Advisory: it never fails, it only names what the repo
+ * has taken over from the platform default and at which version it resolved.
+ *
+ * @param {string} repoDir
+ * @returns {Promise<string[]>}
+ */
+export async function reportKitOverrides(repoDir) {
+  const { kit } = await readRuntimeTiers();
+  const manifest = await readJson(join(repoDir, "package.json"));
+  const lines = [];
+  for (const { name, version: platformDefault } of kit) {
+    const declared = declaration(manifest, name);
+    if (!declared) continue;
+    const installed = await readJson(
+      join(repoDir, "node_modules", name, "package.json"),
+    );
+    const resolved = installed?.version
+      ? String(installed.version)
+      : "not installed";
+    lines.push(
+      `${name}: this repo declares ${declared.range} and resolved ${resolved}; the platform default is ${platformDefault}.`,
+    );
+  }
+  return lines;
+}
+
+/** The advisory's framing, printed only when there is an override to report. */
+export const KIT_OVERRIDE_PREAMBLE =
+  "kit override (advisory, verify passed): the platform ships these libraries and this repo pins its own versions, so platform bumps no longer move them.";
+
+// Standalone CLI: `node scripts/dependency-tiers.mjs [repoDir]`. Prints the
+// tier-1 problems to stderr and exits 1; prints the tier-2 advisory and stays
+// at 0.
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+) {
+  const repoDir = process.argv[2] ? resolve(process.argv[2]) : process.cwd();
+  const problems = [
+    ...(await checkToolchainDeclarations(repoDir)),
+    ...(await checkToolchainVersions(repoDir)),
+    ...(await checkAstroCopies(repoDir)),
+  ];
+  const overrides = await reportKitOverrides(repoDir);
+  if (overrides.length > 0) {
+    process.stdout.write(`${KIT_OVERRIDE_PREAMBLE}\n${overrides.join("\n")}\n`);
+  }
+  if (problems.length > 0) {
+    process.stderr.write(`toolchain check failed:\n${problems.join("\n")}\n`);
+    process.exit(1);
+  }
+}

package/scripts/prerendered-pages.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * Prerendered-page gate. A prerendered route is rendered inside workerd by the
+ * Cloudflare adapter and written to disk, and when that render goes wrong the
+ * build stays GREEN and the file gets whatever the failure stringified to.
+ *
+ * The live case (3.1.0, astro 7): a repo whose wrangler `compatibility_date`
+ * predates 2026-02-19 wrote the literal string "[object Object]" as its entire
+ * home page, with no warning in the build log, and the deployed worker served
+ * the same body for every SSR route. Nothing else looks at what the build
+ * actually produced, so a page that is not a page shipped.
+ *
+ * Every .html under dist/client has to start like a document. Run by
+ * `site-runtime verify` in a brand repo and by this package's own
+ * scripts/check-fixture.mjs against the fixture it just built, so the failure
+ * mode is covered by `pnpm test` and not only by a consumer's gate.
+ */
+
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/** The floor a Worker's compatibility_date must clear for the render to work. */
+export const WORKERD_COMPATIBILITY_FLOOR = "2026-02-19";
+
+const DOCUMENT_START = /^<(?:!doctype html|html[\s>])/i;
+
+/**
+ * @param {string} repoDir project root; dist/client is read beneath it
+ * @returns {Promise<string[]>} one problem per file that is not a document
+ */
+export async function checkPrerenderedPages(repoDir) {
+  /** @type {string[]} */
+  const problems = [];
+  const clientDir = join(repoDir, "dist", "client");
+
+  /** @param {string} dir */
+  async function walk(dir) {
+    /** @type {import("node:fs").Dirent[]} */
+    let entries = [];
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(path);
+        continue;
+      }
+      if (!entry.name.endsWith(".html")) continue;
+      const head = (await readFile(path, "utf8")).slice(0, 200).trimStart();
+      if (DOCUMENT_START.test(head)) continue;
+      problems.push(
+        `${relative(repoDir, path)} is not an HTML document. It begins: ${JSON.stringify(head.slice(0, 60))}. ` +
+          `A prerendered route rendered to something other than markup, which the build reports as success. ` +
+          `First thing to check is wrangler compatibility_date: the runtime's prerender and SSR need ${WORKERD_COMPATIBILITY_FLOOR} or later.`,
+      );
+    }
+  }
+
+  await walk(clientDir);
+  return problems;
+}
+
+// Standalone CLI: `node scripts/prerendered-pages.mjs [repoDir]`.
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+) {
+  const problems = await checkPrerenderedPages(
+    process.argv[2] ? resolve(process.argv[2]) : process.cwd(),
+  );
+  if (problems.length > 0) {
+    process.stderr.write(
+      `prerendered-page check failed:\n${problems.join("\n")}\n`,
+    );
+    process.exit(1);
+  }
+}

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

@@ -24,6 +24,11 @@
  *     exits with that step's exit code. Saves tokens in agent tool
  *     results and puts the useful output front-and-center.
  *
+ *     ONE exception, added with the curated kit in 3.1.0: a repo that pins
+ *     its own version of a kit library gets an advisory line about it after
+ *     everything passes. It cannot fail the run, and a repo that declares
+ *     none of them (every fresh repo) still prints nothing.
+ *
  * Run from the repo root via `bun run verify` / `npm run verify` (which map to
  * `site-runtime verify`). Every path below resolves against process.cwd(), the
  * repo being verified — the gates themselves live in node_modules.
@@ -172,6 +177,28 @@ async function checkFonts() {
   return problems;
 }
 
+// Dependency-tier gate, FIRST because it decides which toolchain the rest of
+// this run measures. The runtime owns the toolchain (3.1.0), so a repo that
+// declares astro or react installs a second copy and every step below silently
+// reports on the wrong one. Three questions, because each one has a hole the
+// others cover: who DECLARES a toolchain package, what version actually
+// RESOLVED (an overrides entry declares nothing), and how many copies of astro
+// there are. The checks and their messages live in dependency-tiers.mjs so its
+// tests can exercise them on fixtures.
+const { checkAstroCopies, checkToolchainDeclarations, checkToolchainVersions } =
+  await import("./dependency-tiers.mjs");
+const toolchainProblems = [
+  ...(await checkToolchainDeclarations(process.cwd())),
+  ...(await checkToolchainVersions(process.cwd())),
+  ...(await checkAstroCopies(process.cwd())),
+];
+if (toolchainProblems.length > 0) {
+  process.stderr.write(
+    `toolchain check failed:\n${toolchainProblems.join("\n")}\n`,
+  );
+  exit(1);
+}
+
 const fontProblems = await checkFonts();
 if (fontProblems.length > 0) {
   process.stderr.write(
@@ -180,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
@@ -222,6 +262,19 @@ for (const [cmd, args] of steps) {
   }
 }
 
+// Prerendered-page gate, against the dist/ the build just wrote. The check and
+// its message live in prerendered-pages.mjs so this package's own fixture check
+// runs the same assertion on the same kind of output: a broken prerender is
+// invisible to the build's exit code, so the only witness is the file.
+const { checkPrerenderedPages } = await import("./prerendered-pages.mjs");
+const prerenderProblems = await checkPrerenderedPages(process.cwd());
+if (prerenderProblems.length > 0) {
+  process.stderr.write(
+    `prerendered-page check failed:\n${prerenderProblems.join("\n")}\n`,
+  );
+  exit(1);
+}
+
 /**
  * Editor-bytes gate. The visual editor is dev-only — injected by
  * integrations/visual-editor-dev.mjs under `astro dev`, with the vendored
@@ -279,5 +332,18 @@ if (editorProblems.length > 0) {
   exit(1);
 }
 
+// The one thing a green verify prints: which curated-kit libraries this repo has
+// taken over from the platform default. It runs LAST so "verify passed, and here
+// is a note" cannot be misread as the cause of a failure, and it says nothing at
+// all for a repo that declares none of them, which is every fresh repo.
+const { KIT_OVERRIDE_PREAMBLE, reportKitOverrides } =
+  await import("./dependency-tiers.mjs");
+const kitOverrides = await reportKitOverrides(process.cwd());
+if (kitOverrides.length > 0) {
+  process.stderr.write(
+    `${KIT_OVERRIDE_PREAMBLE}\n${kitOverrides.join("\n")}\n`,
+  );
+}
+
 // Success: exit silently. Nothing to print.
 exit(0);

package/src/config/preset.ts

@@ -11,6 +11,32 @@ import newFileReload from "../integrations/new-file-reload.mjs";
 import previewErrorShell from "../integrations/preview-error-shell.mjs";
 import { sitemapWithCustomPages } from "../lib/sitemap";
 
+/**
+ * The browser floor every brand site's CSS is compiled for, stated rather than
+ * inherited. Esbuild-style target strings, because that is what Vite parses for
+ * both CSS minifiers.
+ *
+ * Vite 8 minifies CSS with Lightning CSS instead of esbuild, and its minify step
+ * takes targets from `build.cssTarget` alone: with that unset it passes `{}` and
+ * leaves modern syntax exactly as Tailwind emits it. Astro 6's output carried
+ * `@media(min-width:40rem)` and astro 7's carried `@media (width>=40rem)`, which
+ * older engines do not parse, so every breakpoint in the sheet would silently
+ * stop applying on them.
+ *
+ * The floor is Tailwind v4's own, which is also the floor these stylesheets
+ * already had: the same build emits 54 `@property` declarations and 52
+ * `color-mix()` calls with no fallbacks, in both the astro 6 and astro 7 output.
+ * Range media queries are supported at exactly that line (Safari 16.4,
+ * Chrome 104, Firefox 63), so declaring the floor keeps the modern syntax
+ * honestly rather than lowering one feature while the rest of the sheet needs the
+ * same engines. Lower these numbers and Lightning CSS lowers the syntax to match.
+ *
+ * NOT `css.lightningcss.targets`: the minify path overwrites that key with
+ * whatever `build.cssTarget` converts to, so setting it there looks right, passes
+ * every gate, and does nothing.
+ */
+const CSS_TARGET = ["safari16.4", "chrome111", "firefox128", "edge111"];
+
 // The Astro configuration every brand site runs on, as one spreadable fragment:
 //
 //   // astro.config.mjs
@@ -70,9 +96,12 @@ export function iterantStarter({
   pagesDir,
   overrides,
 }: IterantStarterOptions = {}) {
-  // The platform generates the wrangler config at deploy time; it isn't checked
-  // in. Only pass configPath to the Cloudflare adapter when one of the supported
-  // wrangler config files actually exists so local `astro dev` works without one.
+  // A repo's own wrangler config, when it has one. The template checks in a
+  // wrangler.jsonc and its compatibility_date decides how the adapter's workerd
+  // prerender behaves, so passing configPath is not a detail; the lookup stays
+  // conditional because a repo without any of these files still has to `astro
+  // dev`. The Worker the platform UPLOADS is configured separately, by the
+  // deploy path, and nothing writes a wrangler file into the repo.
   const wranglerConfig = ["wrangler.toml", "wrangler.jsonc", "wrangler.json"]
     .map((name) => join(process.cwd(), name))
     .find((path) => existsSync(path));
@@ -120,6 +149,12 @@ export function iterantStarter({
         },
       }),
     },
+    // The CSS floor (see CSS_TARGET). Vite's CSS minifier reads this and nothing
+    // else, and it is what stops the build emitting syntax the declared browsers
+    // cannot parse.
+    build: {
+      cssTarget: CSS_TARGET,
+    },
     optimizeDeps: {
       // Pre-bundle every client-side dep up front: discovering one
       // mid-session re-optimizes with a new ?v hash, and a stale
@@ -150,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,
     },
   };
 
@@ -166,6 +207,14 @@ export function iterantStarter({
       imageService: "compile",
       ...(wranglerConfig && { configPath: wranglerConfig }),
     }),
+    // HTML-aware compression, which was Astro's default until 7.0 changed it to
+    // "jsx". Set explicitly rather than inherited: under "jsx" a whitespace-only
+    // text node between two elements is dropped by JSX rules, so `<b>a</b>
+    // <i>b</i>` in a brand's own section renders as "ab". That is a rendered
+    // output change in brand-owned markup, which the semver contract does not
+    // allow a package MINOR to make; the runtime therefore keeps the old
+    // behavior and a later MAJOR can adopt "jsx" deliberately.
+    compressHTML: true,
     integrations,
     vite,
     // Port 4321 (Astro's default), NOT 3000: inside a Cloudflare Sandbox port

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/lib/sitemap/sitemap-with-custom-pages-plugin.ts

@@ -30,7 +30,11 @@ export function sitemapWithCustomPages(
       name: "capture-site-for-sitemap",
       hooks: {
         "astro:config:setup": ({ config, logger }) => {
-          const { paths, pagesDir: searched, entryCount } = getSitemapPaths({
+          const {
+            paths,
+            pagesDir: searched,
+            entryCount,
+          } = getSitemapPaths({
             pagesDir,
             root: root ?? fileURLToPath(config.root),
           });