@iterant/site-runtime 3.0.2

package/src/content/collections.ts

@@ -0,0 +1,71 @@
+import { defineCollection } from "astro:content";
+import { glob } from "astro/loaders";
+
+import {
+  DEFAULT_CHROME_DIR,
+  DEFAULT_PAGES_DIR,
+  loaderBase,
+} from "../lib/content-paths";
+import { entryIdFromFile } from "../lib/locales";
+import { createContentSchemas, 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
+// that file stays a shim over this factory:
+//
+//   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,
+//   });
+//
+// The grammar, the entry shape and the loader wiring are platform-owned; which
+// section and chrome types exist stays brand-owned.
+
+export interface CreateCollectionsOptions extends ContentSchemaOptions {
+  /** Page entry directory, relative to the project root. A repo that moves it
+   *  must pass the same value to `iterantStarter`, or the sitemap and the
+   *  collection read different directories. */
+  pagesDir?: string;
+  /** Directory holding chrome.json and its locale siblings. */
+  chromeDir?: string;
+}
+
+export function createCollections({
+  registeredSectionProps,
+  chromeComponentProps,
+  pagesDir = DEFAULT_PAGES_DIR,
+  chromeDir = DEFAULT_CHROME_DIR,
+}: CreateCollectionsOptions) {
+  const { pageEntrySchema, chromeEntrySchema } = createContentSchemas({
+    registeredSectionProps,
+    chromeComponentProps,
+  });
+
+  const pages = defineCollection({
+    // generateId preserves dots (the default slugifies `home.es` → `homees`),
+    // so locale sibling ids keep the platform's `<page>.<locale>` grammar.
+    loader: glob({
+      pattern: "**/*.json",
+      base: loaderBase(pagesDir),
+      generateId: ({ entry }) => entryIdFromFile(entry),
+    }),
+    schema: pageEntrySchema,
+  });
+
+  const chrome = defineCollection({
+    // The base chrome plus its locale siblings (chrome.es.json); LayoutCore
+    // resolves per request path with fallback to the base.
+    loader: glob({
+      pattern: ["chrome.json", "chrome.*.json"],
+      base: loaderBase(chromeDir),
+      generateId: ({ entry }) => entryIdFromFile(entry),
+    }),
+    schema: chromeEntrySchema,
+  });
+
+  return { pages, chrome };
+}

package/src/content/schema.ts

@@ -0,0 +1,239 @@
+import { z } from "astro/zod";
+
+import { chromeIdIssues } from "../lib/chrome-schemas";
+import { contentPropsSchema } from "../lib/content-values";
+import { translationProvenanceSchema } from "../lib/locales";
+
+// Page content lives HERE, as JSON — components render it, they never
+// contain it. One entry per page; `components` is the ordered list of
+// sections on the page. All visible copy sits in each component's `props`
+// in the content-value grammar (../lib/content-values.ts).
+//
+//   {
+//     "route": "/pricing",
+//     "meta": { "title": "Pricing — Brand", "description": "For SEO" },
+//     "components": [
+//       {
+//         "id": "pricing-hero",
+//         "type": "hero",
+//         "props": { "heading": { "type": "text", "value": "…" } }
+//       }
+//     ]
+//   }
+//
+// - `id` is a stable kebab-case anchor, unique per page. The visual editor
+//   and translation address content THROUGH it — never rename an id after
+//   creation.
+// - `mode` (default "registry"): registry pages render through
+//   src/pages/[...slug].astro + the brand's section registry, so every `type`
+//   must be registered. Bespoke pages set `"mode": "bespoke"` — their
+//   components are the page's own React components, and a bespoke .astro
+//   shell threads the entry into the page.
+// - `draft: true` renders in dev only.
+// - The sitemap picks `route` up automatically
+//   (../lib/sitemap/get-sitemap-paths.ts reads the pages directory from disk).
+//
+// WHICH section and chrome types exist is brand-owned: the repo passes its own
+// registries into these factories. The grammar around them is platform-owned.
+
+/**
+ * A brand-owned props registry: component type → the zod schema its `props`
+ * must satisfy. `REGISTERED_SECTION_PROPS` and `CHROME_COMPONENT_PROPS` in a
+ * brand repo are both this shape.
+ */
+export type PropsSchemaRegistry = Record<string, z.ZodTypeAny>;
+
+export interface ContentSchemaOptions {
+  /** The repo's `REGISTERED_SECTION_PROPS` (src/lib/section-schemas.ts). */
+  registeredSectionProps: PropsSchemaRegistry;
+  /** The repo's `CHROME_COMPONENT_PROPS` (re-exported from this package). */
+  chromeComponentProps: PropsSchemaRegistry;
+}
+
+const isoDateSchema = z
+  .string()
+  .regex(
+    /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2})?)?$/,
+    "expected an ISO date (2026-08-09) or ISO 8601 datetime",
+  );
+
+/**
+ * The page and chrome entry schemas for one brand's registries. Both
+ * collections share a single component schema, so a chrome entry is held to
+ * the same grammar as a page section and additionally to the chrome mount
+ * contract (chromeIdIssues + CHROME_COMPONENT_PROPS).
+ */
+export function createContentSchemas({
+  registeredSectionProps,
+  chromeComponentProps,
+}: ContentSchemaOptions) {
+  const isRegisteredSection = (type: string) => type in registeredSectionProps;
+  const isChromeComponent = (type: string) => type in chromeComponentProps;
+
+  const componentSchema = z
+    .object({
+      id: z
+        .string()
+        .regex(
+          /^[a-z0-9][a-z0-9-]*$/,
+          'component ids are stable kebab-case anchors, e.g. "pricing-hero"',
+        ),
+      type: z.string().min(1),
+      order: z.number().int().optional(), // defaults to array position
+      locked: z.boolean().optional(),
+      hidden: z.boolean().optional(),
+      // Non-rendering, platform-owned (figma provenance, warnings); never read by the renderer.
+      metadata: z.record(z.string(), z.unknown()).optional(),
+      props: contentPropsSchema,
+    })
+    .strict()
+    .superRefine((component, ctx) => {
+      if (isRegisteredSection(component.type)) {
+        const result = registeredSectionProps[component.type].safeParse(
+          component.props,
+        );
+        if (!result.success) {
+          for (const issue of result.error.issues) {
+            ctx.addIssue({ ...issue, path: ["props", ...issue.path] });
+          }
+        }
+      }
+    });
+
+  type Component = z.infer<typeof componentSchema>;
+
+  const componentListSchema = (
+    components: Component[],
+    ctx: z.RefinementCtx,
+  ) => {
+    const seen = new Set<string>();
+    components.forEach((component, index) => {
+      if (seen.has(component.id)) {
+        ctx.addIssue({
+          code: "custom",
+          path: [index, "id"],
+          message: `duplicate component id "${component.id}" — ids must be unique per entry`,
+        });
+      }
+      seen.add(component.id);
+    });
+  };
+
+  const pageEntrySchema = z
+    .object({
+      version: z.number().int().default(1),
+      schemaVersion: z.string().default("1.0"),
+      route: z
+        .string()
+        .regex(/^\/[a-z0-9\-/]*$/, "route must start with / and be lowercase"),
+      // Page display name (distinct from the SEO meta.title). Optional and
+      // additive; the head <title> falls back to it when meta.title is empty.
+      title: z.string().optional(),
+      mode: z.enum(["registry", "bespoke"]).default("registry"),
+      // Chrome opt-out (starter 2.13.0): default true renders the site-level
+      // navbar/footer from chrome.json as before. Set false on a page whose
+      // 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),
+      meta: z
+        .object({
+          title: z.string(),
+          description: z.string().optional(),
+          // Social/share image. src must be an absolute URL (crawlers 403 on
+          // signed S3 URLs — publish CDN URLs only). assetId links back to the
+          // brand asset; alt is the accessible/og:image:alt text.
+          ogImage: z
+            .object({
+              src: z.string().url(),
+              assetId: z.string().optional(),
+              alt: z.string().optional(),
+            })
+            .strict()
+            .optional(),
+          // What the page IS, for structured data (starter 2.17.0). The layout
+          // resolves the entry by route and emits the matching schema.org node
+          // deterministically (see ../components/seo.tsx) — never hand-author
+          // JSON-LD for types this covers. Absent means a plain WebPage.
+          pageType: z
+            .enum(["page", "article", "product", "about", "contact"])
+            .optional(),
+          // ISO dates (YYYY-MM-DD or full ISO 8601) for article-shaped pages;
+          // emitted as Article datePublished/dateModified. Set datePublished
+          // when the page first ships; touch dateModified on substantial
+          // content updates, not routine tweaks.
+          datePublished: isoDateSchema.optional(),
+          dateModified: isoDateSchema.optional(),
+        })
+        .strict(),
+      draft: z.boolean().default(false),
+      components: z.array(componentSchema).superRefine(componentListSchema),
+      // Locale siblings (<page>.<locale>.json, starter 2.8.0) carry per-leaf
+      // translation provenance. Platform-maintained, renderer-ignored — kept
+      // loose on purpose so agent-side evolution never fails a brand build.
+      _translation: translationProvenanceSchema.optional(),
+    })
+    .strict()
+    .superRefine((page, ctx) => {
+      if (page.mode !== "registry") return;
+      page.components.forEach((component, index) => {
+        if (!isRegisteredSection(component.type)) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["components", index, "type"],
+            message: `"${component.type}" is not a registered section type (registered: ${Object.keys(registeredSectionProps).join(", ")}). Bespoke components need "mode": "bespoke" plus a bespoke page shell.`,
+          });
+        }
+      });
+    });
+
+  // Site-level chrome copy (src/content/chrome.json): the navbar and footer
+  // are structural — built once per brand, rendered by the layout on every
+  // page — but their COPY (link labels, hrefs, footer text) is copy like any
+  // other, so it lives here in the same component grammar. Chrome components
+  // read their props via ../lib/chrome.ts.
+  // Validate a chrome component's props against its chrome-specific schema.
+  // Mirrors componentSchema's registered-section superRefine, but keyed off
+  // chromeComponentProps (navbar/footer) — NOT registeredSectionProps, so
+  // chrome types never become page-insertable registry sections. chrome.json
+  // renders ONLY navbar + footer (the layout mounts those two ids), so any
+  // other id or an id/type mismatch is a hard error (chromeIdIssues) — extra
+  // bands belong in page-adjacent sections, never here where nothing would
+  // mount them.
+  const chromeComponentListSchema = (
+    components: Component[],
+    ctx: z.RefinementCtx,
+  ) => {
+    componentListSchema(components, ctx);
+    for (const issue of chromeIdIssues(components)) {
+      ctx.addIssue({
+        code: "custom",
+        path: [issue.index, "id"],
+        message: issue.message,
+      });
+    }
+    components.forEach((component, index) => {
+      if (!isChromeComponent(component.type)) return;
+      const result = chromeComponentProps[component.type].safeParse(
+        component.props,
+      );
+      if (!result.success) {
+        for (const issue of result.error.issues) {
+          ctx.addIssue({ ...issue, path: [index, "props", ...issue.path] });
+        }
+      }
+    });
+  };
+
+  const chromeEntrySchema = z
+    .object({
+      components: z
+        .array(componentSchema)
+        .superRefine(chromeComponentListSchema),
+      _translation: translationProvenanceSchema.optional(),
+    })
+    .strict();
+
+  return { componentSchema, pageEntrySchema, chromeEntrySchema };
+}
+
+export type ContentSchemas = ReturnType<typeof createContentSchemas>;

package/src/index.ts

@@ -0,0 +1,22 @@
+// The package's pure surface: the content grammar, the collection schema
+// factories, locale/hreflang machinery, the chrome prop schemas, the bespoke
+// page helpers, the layout's data types, and the runtime version. Nothing here
+// imports an `astro:*` virtual module, so this entry is safe to import outside
+// an Astro build (the platform agent validates brand content through it).
+//
+// Astro-bound surfaces have their own entries: `/content` (collections),
+// `/layout`, `/seo`, `/routes`, `/sitemap`, `/config`, `/integrations/*`.
+export * from "./content/schema";
+export * from "./layouts/layout-core";
+export * from "./lib/bespoke-pages";
+export * from "./lib/chrome-schemas";
+export * from "./lib/content-paths";
+export * from "./lib/content-values";
+export * from "./lib/hreflang";
+export * from "./lib/locales";
+export * from "./version";
+export type {
+  BuildGraphArgs,
+  OrganizationInfo,
+  PageType,
+} from "./components/seo";

package/src/integrations/iterant-plugins.mjs

@@ -0,0 +1,83 @@
+// @ts-check
+
+// Central-plugin loader (starter ≥2.4.0) — the ONLY plugin code in brand
+// repos. Platform plugins (visual editor, dev-soft-reload, …) are served by
+// plugins.iterant.ai and CI/CD'd from the monorepo
+// (.github/workflows/plugins-deploy.yml): promoting a plugin there reaches
+// every brand's next preview load, with zero brand-repo commits. This file
+// replaces the vendored-IIFE mechanism (integrations/visual-editor-dev.mjs +
+// vendor/, retired in 2.4.0) and is deliberately too dumb to need changing.
+//
+// Dev-only. Two jobs:
+//
+// 1. Rebroadcast Vite HMR lifecycle as DOM events — remote plugins are not in
+//    the dev module graph, so they cannot touch import.meta.hot:
+//    - `vite:beforeFullReload` → cancelable `iterant:before-full-reload`.
+//      A plugin calling preventDefault() makes this loader throw inside the
+//      hot callback (vitejs/vite#6695), which cancels Vite's
+//      location.reload() — how dev-soft-reload morphs instead of flashing.
+//    - `vite:afterUpdate` → `vite:hmr-complete` (the visual-editor runtime's
+//      existing overlay-reapply contract).
+//
+// 2. Inject the plugin script tags: dev-soft-reload on every page;
+//    visual-editor only inside an iframe with ?editor=1 (and production
+//    builds contain zero plugin bytes — the loader is dev-command-gated and
+//    scripts/verify.mjs keeps enforcing the editor markers after every
+//    build).
+//
+// Fails soft by construction: plugin host unreachable → plain preview with
+// native reloads and no editor; the page itself never breaks.
+
+const BOOTSTRAP = `
+const HOST =
+  import.meta.env.PUBLIC_ITERANT_PLUGINS_HOST || "https://plugins.iterant.ai";
+const STARTER =
+  document.querySelector('meta[name="it-astro-starter-version"]')?.content ??
+  "";
+
+function loadPlugin(name, id) {
+  if (document.getElementById(id)) return;
+  const script = document.createElement("script");
+  script.id = id;
+  script.src =
+    HOST + "/" + name + "/stable/plugin.js?starter=" +
+    encodeURIComponent(STARTER);
+  document.head.appendChild(script);
+}
+
+loadPlugin("dev-soft-reload", "__iterant-dev-soft-reload");
+if (
+  window.parent !== window &&
+  new URLSearchParams(window.location.search).get("editor") === "1"
+) {
+  loadPlugin("visual-editor", "__visual-editor");
+}
+
+if (import.meta.hot) {
+  import.meta.hot.on("vite:beforeFullReload", () => {
+    const event = new CustomEvent("iterant:before-full-reload", {
+      cancelable: true,
+    });
+    window.dispatchEvent(event);
+    if (event.defaultPrevented) {
+      throw "[iterant-plugins] full reload handled by a plugin";
+    }
+  });
+  import.meta.hot.on("vite:afterUpdate", () => {
+    window.dispatchEvent(new CustomEvent("vite:hmr-complete"));
+  });
+}
+`;
+
+/** @returns {import("astro").AstroIntegration} */
+export default function iterantPlugins() {
+  return {
+    name: "iterant-plugins",
+    hooks: {
+      "astro:config:setup": ({ command, injectScript }) => {
+        if (command !== "dev") return;
+        injectScript("page", BOOTSTRAP);
+      },
+    },
+  };
+}

package/src/integrations/new-file-reload.mjs

@@ -0,0 +1,95 @@
+// @ts-check
+import { utimes } from "node:fs";
+
+// Dev-only new-file hot-reload (2026-07-23). Vite's HMR only reacts to files
+// already present in a module graph. A freshly CREATED component under src/
+// matches no module node — the import-analysis recovery that would pull it in
+// is client-graph-only (`if (ssr) return` in Vite's import-analysis path), so
+// the `add` event broadcasts nothing and the preview never refreshes until a
+// manual reload. Edits to existing modules are unaffected.
+//
+// This environment-API `hotUpdate` plugin catches any create/delete under src/
+// that resolved to zero modules and broadcasts a full-reload. The dev-soft-
+// reload preview plugin turns that into a soft morph instead of a flash, and a
+// route caught mid-build (5xx) self-heals on the next event.
+//
+// Broadcasts are coalesced on a short debounce so a bulk write storm (an
+// import scaffolding several files, a rename, a branch checkout) settles into
+// one reload rather than one per file. Assets that can't affect a rendered
+// module are skipped.
+//
+// The same blind spot starves Tailwind (2026-07-30): @tailwindcss/vite only
+// re-scans the filesystem when a CSS root's build dependencies change mtime,
+// so a component created mid-session contributes no new utility classes (its
+// novel arbitrary values render unstyled) until someone edits a stylesheet.
+// Before broadcasting, this plugin therefore bumps the mtime of every project
+// CSS module, driving the same invalidate-and-rescan path as a real edit.
+
+const RELOAD_DEBOUNCE_MS = 100;
+
+// Obvious binary/asset extensions that never resolve to a source module —
+// dropping an image or font under src/ shouldn't trigger a reload.
+const NON_SOURCE =
+  /\.(png|jpe?g|gif|svg|webp|avif|ico|woff2?|ttf|otf|eot|mp4|webm|mov|pdf|zip)$/i;
+
+/** @returns {import("astro").AstroIntegration} */
+export default function newFileReload() {
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  return {
+    name: "new-file-reload",
+    hooks: {
+      "astro:config:setup": ({ command, updateConfig }) => {
+        if (command !== "dev") return;
+        updateConfig({
+          vite: {
+            plugins: [
+              {
+                name: "iterant-new-file-reload",
+                hotUpdate({ type, file, modules, server }) {
+                  // A create/delete that resolved to a module is already
+                  // handled by the module-graph HMR path.
+                  if (type === "update" || modules.length > 0) return;
+                  // hotUpdate fires once per environment (client + ssr); act on
+                  // the client pass only so one event broadcasts one reload.
+                  if (this.environment.name !== "client") return;
+                  if (!file.includes("/src/")) return;
+                  if (NON_SOURCE.test(file)) return;
+                  // Coalesce a burst of qualifying events into a single reload:
+                  // reset the timer on each one and fire once the tree settles.
+                  clearTimeout(timer);
+                  timer = setTimeout(() => {
+                    // Tailwind v4 only re-scans the filesystem when a CSS
+                    // root's build dependencies change mtime (requiresBuild in
+                    // @tailwindcss/vite); a brand-new source file changes no
+                    // watched module, so its novel classes (arbitrary values
+                    // especially) stay missing from the generated CSS until
+                    // something touches the stylesheet. Bump the mtime of every
+                    // CSS module in the graph so the watcher runs the same
+                    // invalidate-and-rescan path as a real edit.
+                    const touched = new Set();
+                    for (const environment of Object.values(
+                      server.environments,
+                    )) {
+                      for (const mod of environment.moduleGraph.idToModuleMap.values()) {
+                        const cssFile = mod.file;
+                        if (!cssFile || !cssFile.endsWith(".css")) continue;
+                        if (cssFile.includes("/node_modules/")) continue;
+                        if (touched.has(cssFile)) continue;
+                        touched.add(cssFile);
+                        const now = new Date();
+                        utimes(cssFile, now, now, () => {});
+                      }
+                    }
+                    server.ws.send({ type: "full-reload", path: "*" });
+                  }, RELOAD_DEBOUNCE_MS);
+                  return [];
+                },
+              },
+            ],
+          },
+        });
+      },
+    },
+  };
+}

package/src/integrations/preview-error-shell.mjs

@@ -0,0 +1,145 @@
+// @ts-check
+
+// Dev-only branded fallback for broken routes (2026-07-06): mid-build there
+// is a window where a route exists but its page component doesn't (the shell
+// lands before page.tsx) or is mid-edit with a syntax error — and the Astro
+// dev server serves its raw stack-trace error page into the customer's
+// preview iframe. Astro middleware can't catch this class (the module fails
+// to load BEFORE middleware runs), so this intercepts at the HTTP layer:
+// buffer HTML responses and swap any 5xx body for the starter-owned
+// /under-construction shell (navbar + footer + "in progress"). The 5xx
+// status is preserved on purpose — verify probes and the save gate must
+// still see the failure; only the human-facing body changes.
+
+// vite is astro's dependency, not this package's, so the dev-server type is
+// derived from the hook astro hands it to. One vite in the type graph, whichever
+// version the installed astro ships.
+/**
+ * @typedef {Parameters<
+ *   NonNullable<import("astro").AstroIntegration["hooks"]["astro:server:setup"]>
+ * >[0]["server"]} ViteDevServer
+ */
+
+const FALLBACK_PATH = "/under-construction";
+
+// Served when /under-construction itself can't render (e.g. Layout broken).
+const MINIMAL_FALLBACK = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><title>Page in progress</title></head>
+<body style="display:flex;min-height:100vh;align-items:center;justify-content:center;font-family:system-ui,sans-serif">
+<p>This page is in progress — check back in a moment.</p>
+</body></html>`;
+
+/** @returns {import("astro").AstroIntegration} */
+export default function previewErrorShell() {
+  return {
+    name: "preview-error-shell",
+    hooks: {
+      "astro:config:setup": ({ command, updateConfig }) => {
+        if (command !== "dev") return;
+        updateConfig({
+          vite: {
+            plugins: [
+              {
+                name: "preview-error-shell",
+                configureServer(server) {
+                  server.middlewares.use((req, res, next) => {
+                    const accept = String(req.headers.accept ?? "");
+                    if (
+                      req.method !== "GET" ||
+                      !accept.includes("text/html") ||
+                      String(req.url ?? "").startsWith(FALLBACK_PATH)
+                    ) {
+                      return next();
+                    }
+                    intercept(server, res);
+                    next();
+                  });
+                  // Astro's own dev handler registers earlier in the connect
+                  // stack and ends the response before later layers run —
+                  // hoist this layer to the front so it wraps every HTML
+                  // response (the accept filter keeps it off asset requests).
+                  const layer = server.middlewares.stack.pop();
+                  if (layer) server.middlewares.stack.unshift(layer);
+                },
+              },
+            ],
+          },
+        });
+      },
+    },
+  };
+}
+
+/**
+ * Buffer the response; replay it verbatim unless it resolves to a 5xx, in
+ * which case serve the branded fallback body instead. Buffering trades dev
+ * streaming for the swap — fine for a preview.
+ *
+ * @param {ViteDevServer} server
+ * @param {import("node:http").ServerResponse} res
+ */
+function intercept(server, res) {
+  /** @type {Array<string | Buffer>} */
+  const chunks = [];
+  /** @type {unknown[] | null} */
+  let headArgs = null;
+  const original = {
+    writeHead: res.writeHead.bind(res),
+    write: res.write.bind(res),
+    end: res.end.bind(res),
+  };
+  res.writeHead = /** @type {any} */ (
+    (/** @type {unknown[]} */ ...args) => {
+      headArgs = args;
+      return res;
+    }
+  );
+  res.write = /** @type {any} */ (
+    (/** @type {any} */ chunk) => {
+      if (chunk) chunks.push(chunk);
+      return true;
+    }
+  );
+  res.end = /** @type {any} */ (
+    (/** @type {any} */ chunk) => {
+      if (chunk && typeof chunk !== "function") chunks.push(chunk);
+      const status = headArgs
+        ? Number(headArgs[0]) || res.statusCode
+        : res.statusCode;
+      if (status < 500) {
+        res.writeHead = original.writeHead;
+        res.write = original.write;
+        res.end = original.end;
+        if (headArgs) original.writeHead(.../** @type {[number]} */ (headArgs));
+        for (const c of chunks) original.write(c);
+        return original.end();
+      }
+      void serveFallback(server, original, status);
+      return res;
+    }
+  );
+}
+
+/**
+ * @param {ViteDevServer} server
+ * @param {{ writeHead: Function, write: Function, end: Function }} original
+ * @param {number} status
+ */
+async function serveFallback(server, original, status) {
+  let html = MINIMAL_FALLBACK;
+  try {
+    const port = server.config.server.port;
+    const resp = await fetch(`http://127.0.0.1:${port}${FALLBACK_PATH}`, {
+      headers: { accept: "text/html" },
+    });
+    if (resp.ok) html = await resp.text();
+  } catch {
+    // fall through to the minimal shell
+  }
+  original.writeHead(status, {
+    "content-type": "text/html",
+    "x-preview-fallback": "1",
+  });
+  original.write(html);
+  original.end();
+}