@iterant/site-runtime 3.8.0 → 3.8.2

package/docs/runtime-contract.md

@@ -50,7 +50,7 @@ runtime and says so.
 
 <!-- generated: available libraries -->
 
-_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.8.0._
+_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.8.2._
 
 **Toolchain** (this package owns the version; do NOT declare these):
 
@@ -720,6 +720,58 @@ one reported, and calls `POST /__iterant/refresh` if the layer is behind. Every
 timestamp in these payloads, and in the signal lines, is an ISO 8601 string in
 UTC, never an epoch number.
 
+### Restarts and the error shell (3.8.1)
+
+An in-place restart answers whatever request was already running with a 500: the
+Cloudflare plugin's miniflare goes down under it. Until 3.8.0 `preview-error-shell`
+answered a 5xx by fetching `/under-construction` back through the same port while
+it held that failing response open, and in Docker that wedged the dev server for
+good. The self-fetch itself came back 200 in 271ms, and from then on every
+request that reached workerd rendered (the worker logged its own 200) and
+never reached the client, for the whole 120 second probe window, while Node's
+own middleware kept answering in 8ms. The same edit with the self-fetch gone
+recovered in 6 seconds.
+
+So the shell no longer fetches anything from inside a request. It caches the
+branded body and serves a 5xx from memory. The one fetch that fills the cache
+runs after a page this server has already ANSWERED, which is the only moment it
+is known to be able to render its own route; it is bounded by an abort timeout,
+holds no response open, gives up after three tries, and never runs while a
+restart is in flight (`dev-server-signals` opens that window at
+`restart`/`config` and closes it at `ready`). The cached body outlives the
+server that fetched it, so a restart keeps showing the branded shell, and the
+new server's own first page refetches it, which is what picks up an edited
+navbar. Before any page of a session has rendered there is nothing to cache and
+a break that early gets the static in-progress body.
+
+The preset also pre-bundles `astro/logger/json`, which the supervisor's
+`astro dev --json` imports on every boot. Discovered mid-session instead, it
+reloaded the program and split React in two inside workerd, and every island
+render then failed on `useRef`.
+
+### The worker's half of a content refresh (3.8.2)
+
+Astro syncs a changed page entry on the node side and then invalidates the data
+store module in the ssr module graph. Under the cloudflare adapter that graph
+entry is the only lever that reaches a render: the modules are evaluated inside
+workerd, and Astro cannot clear a runner it does not own. When the entry is
+missing at the moment the store is written (after a program reload, measured in
+the sandbox image), the node side logs `Reloaded data from home.json`, the store
+on disk is fresh, and `/` keeps serving the entry the worker evaluated last,
+until any SSR module changes. A first build showed two sections as "Coming up"
+placeholders for 95 seconds after their real rows had been written and
+committed.
+
+Since 3.8.2 the signals integration watches `.astro/data-store.json`, the file
+Astro itself writes on every sync, and hands it to every environment Astro
+cannot reach in process: the content virtual modules are invalidated in that
+environment's graph and the environment is sent a full reload, so the worker
+imports its entrypoints again against the new store. It prints
+`{"iterant":"dev-server","event":"content-reloaded","restart":...,"environments":["ssr"]}`.
+The reload is the same one an `.astro` edit causes and costs the same; a `.tsx`
+edit still hot-reloads, and the boot server is armed the same way as a restarted
+one, because the hole belongs to the adapter and not to the restart.
+
 ## Verify: the gate
 
 `bun run verify` maps to `site-runtime verify` and is the gate. It is silent on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iterant/site-runtime",
-  "version": "3.8.0",
+  "version": "3.8.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": {

package/src/config/preset.ts

@@ -283,6 +283,10 @@ export function iterantStarter({
         "tailwind-merge",
         "class-variance-authority",
         "@radix-ui/react-slot",
+        // The supervisor runs `astro dev --json`, so astro imports this one on
+        // every boot: left out, it is discovered mid-session and the reload
+        // that follows splits React in two inside workerd (the same crash).
+        "astro/logger/json",
       ],
     },
     server: {

package/src/content/schema.ts

@@ -164,6 +164,10 @@ export function createContentSchemas({
           // brand asset; alt is the accessible/og:image:alt text.
           ogImage: z
             .object({
+              // Every other image leaf in an entry is tagged type: "image",
+              // and the model reaches for the same tag here; the tag is
+              // accepted so a share image never refuses a whole page write.
+              type: z.literal("image").optional(),
               src: z.string().url(),
               assetId: z.string().optional(),
               alt: z.string().optional(),

package/src/integrations/dev-restart-state.mjs

@@ -0,0 +1,46 @@
+// @ts-check
+
+// Dev-only: is an in-place Astro restart in flight? (3.8.1)
+//
+// Astro replaces its Vite server in place when a watched file changes
+// (`src/site-config.ts`, `package.json`), and for that stretch the port still
+// accepts connections while the server behind it is being torn down and built
+// again. A request that was already running is answered 500 `fetch failed`:
+// the Cloudflare vite plugin's miniflare went down under it.
+//
+// preview-error-shell reads this flag before it fetches /under-construction
+// back through that same port for its cache. A fetch aimed into the gap buys
+// nothing (it can only fail or hang) and it reaches back into the plugin at
+// the moment it is least able to answer, which is how the 3.8.0 shell wedged
+// the dev server for a whole 120s probe window in Docker.
+//
+// The window opens in `dev-server-signals` at `astro:config:setup` on the
+// restarted server, the same moment it emits
+// `{"event":"restart","phase":"config"}`, and closes when that server's socket
+// starts listening, the moment of `{"event":"ready","restart":true}`.
+//
+// State, not a timer: nothing here schedules work or holds a handle, and the
+// two integrations share one module instance because the preset imports both
+// from this package. A restart that never lands would otherwise leave the flag
+// up for the rest of the session and strand the cache empty, so the flag is
+// read with a bound on how long a restart can plausibly be in flight rather
+// than trusted forever. A dev boot on a cold cache is around 11s.
+
+const RESTART_WINDOW_MS = 30_000;
+
+let startedAt = 0;
+
+/** The restarted server is being built. Called once per in-place restart. */
+export function beginRestart() {
+  startedAt = Date.now();
+}
+
+/** The restarted server is listening, so a self-fetch can be answered again. */
+export function endRestart() {
+  startedAt = 0;
+}
+
+/** @returns {boolean} */
+export function restartInFlight() {
+  return startedAt !== 0 && Date.now() - startedAt < RESTART_WINDOW_MS;
+}

package/src/integrations/dev-server-signals.mjs

@@ -4,6 +4,8 @@ import { readdirSync, readFileSync } from "node:fs";
 import { join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { beginRestart, endRestart } from "./dev-restart-state.mjs";
+
 // Dev-only restart signals, content re-arm and state probe (2026-09-11).
 //
 // Astro restarts its Vite server IN PLACE when a file in `settings.watchFiles`
@@ -64,6 +66,33 @@ import { fileURLToPath } from "node:url";
 // and it is why narrowing watcher #1 with `unwatch` was NOT done: it would buy
 // back six watched paths and cost the self-heal.
 //
+// THE WORKER'S HALF OF A CONTENT REFRESH. A synced store still has to reach the
+// environment that renders. Astro does that in
+// `content/vite-plugin-content-virtual-mod.js` (`invalidateDataStore`): it
+// invalidates the data store module in the ssr module graph and, for an
+// environment whose modules THIS process evaluates, drops the runner's copy as
+// well. `astro dev` with the cloudflare adapter has neither shape: the modules
+// live inside workerd, the plugin's environment is a plain DevEnvironment, and
+// the graph entry is the only lever Astro has left. A prune or a program reload
+// can leave that graph without the entry at the moment the store is written,
+// and then nothing reaches the render at all.
+//
+// Measured in the sandbox image on 2026-09-11, with the graph lever removed to
+// hold the state still: the node side logs `Reloaded data from home.json`, the
+// synced store on disk carries the new rows, `astro:content-changed` goes out
+// over the worker's channel, and / keeps serving the entry the worker evaluated
+// at the last program reload for as long as nothing else touches an SSR module.
+// A customer's first build showed two sections as "Coming up:" placeholders for
+// 95 s after their real rows had been written and committed.
+//
+// So the store write drives a reload of every environment Astro cannot reach in
+// process. The graph entries go first, so the re-import reads the new store
+// rather than a cached transform, and the full reload makes the worker clear its
+// evaluated modules and import its entrypoints again. This watches the same file
+// Astro's own plugin watches, so the store is on disk by the time the event
+// arrives, and it is armed on the BOOT server too: the hole belongs to the
+// adapter, not to the restart.
+//
 // STDOUT SIGNALS. One single-line JSON object per event, every one keyed
 // `iterant` so the preview supervisor (which already matches Astro's `ready in`
 // line) can filter them out of the dev log. Every `at`/timestamp field in this
@@ -76,6 +105,7 @@ import { fileURLToPath } from "node:url";
 //   {"iterant":"dev-server","event":"ready","restart":true}
 //   {"iterant":"dev-server","event":"content-synced","restart":true,"paths":[...]}
 //   {"iterant":"dev-server","event":"content-sync-failed","restart":true,"paths":[...],"error":"..."}
+//   {"iterant":"dev-server","event":"content-reloaded","restart":true,"environments":["ssr"]}
 //
 // `paths` are root-relative (`src/content/pages/home.json`), which is what a
 // writer wrote and the only key shape that survives a relocated tree. An empty
@@ -86,6 +116,11 @@ import { fileURLToPath } from "node:url";
 // which kind of server it got. Exactly one `ready` per server, boot or restart,
 // emitted when its httpServer starts listening.
 //
+// Those two moments are also the window preview-error-shell reads before it
+// goes and fetches /under-construction for its cache (`dev-restart-state`).
+// Nothing of ours may reach back through this port while the server behind it
+// is being replaced.
+//
 // HMR EVENTS, on this server's channel:
 //
 //   iterant:server-ready    { restart, at }   as each client connects
@@ -114,6 +149,10 @@ import { fileURLToPath } from "node:url";
 // `globalDataStore`), which an integration must not import.
 
 const REFRESH_DEBOUNCE_MS = 100;
+/** Astro's dev-time content store, under the project's own `.astro` dir. */
+const DATA_STORE_SEGMENTS = [".astro", "data-store.json"];
+/** The modules an SSR render reads a page entry through, by resolved id. */
+const CONTENT_VIRTUAL_IDS = ["\0astro:data-layer-content", "\0astro:content"];
 const STATE_PATH = "/__iterant/dev-state";
 const REFRESH_PATH = "/__iterant/refresh";
 const STATE_HEADER = "x-iterant-dev-state";
@@ -154,7 +193,13 @@ export default function devServerSignals({ pagesDir, chromeDir }) {
           [pagesDir, chromeDir].map((dir) => resolve(root, dir) + sep),
         );
         startedAt = new Date().toISOString();
-        if (isRestart) signal({ event: "restart", phase: "config" });
+        if (isRestart) {
+          // The same moment, shared with preview-error-shell: from here until
+          // this server listens, a fetch back through the port would be aimed
+          // at a server still being replaced (see dev-restart-state).
+          beginRestart();
+          signal({ event: "restart", phase: "config" });
+        }
       },
 
       "astro:server:setup": ({ server, refreshContent }) => {
@@ -228,6 +273,23 @@ export default function devServerSignals({ pagesDir, chromeDir }) {
           scheduleRefresh();
         }
 
+        // Whichever side synced it, a written store has to reach the render.
+        // Armed on both kinds of server: the environment that cannot be
+        // invalidated is the adapter's, and a boot server has the same one.
+        const dataStore = resolve(root, ...DATA_STORE_SEGMENTS);
+        server.watcher.on("all", (event, path) => {
+          if (event !== "add" && event !== "change") return;
+          if (path !== dataStore) return;
+          const reloaded = reloadRenderEnvironments(server);
+          if (reloaded.length > 0) {
+            signal({
+              event: "content-reloaded",
+              restart,
+              environments: reloaded,
+            });
+          }
+        });
+
         // An obsolete generation must not fire after its server is gone: Vite's
         // in-place restart calls close() on the old server (which closes this
         // httpServer) before the new one listens, and a timer still pending
@@ -281,9 +343,10 @@ export default function devServerSignals({ pagesDir, chromeDir }) {
         // waited for it would never announce itself; 'listening' is the moment
         // both paths share, and it is also the first moment the routes above
         // can actually be reached.
-        server.httpServer?.once("listening", () =>
-          signal({ event: "ready", restart }),
-        );
+        server.httpServer?.once("listening", () => {
+          endRestart();
+          signal({ event: "ready", restart });
+        });
 
         // The same news over HMR, as clients arrive. It cannot be sent from a
         // hook: an HMR payload with no client attached is dropped, and on a
@@ -303,6 +366,56 @@ export default function devServerSignals({ pagesDir, chromeDir }) {
   };
 }
 
+/**
+ * Hand the freshly written store to every environment Astro's own invalidation
+ * leaves behind: not the client, which Astro reloads itself, and not one this
+ * process evaluates, whose runner Astro already clears. What is left in this
+ * stack is the single workerd environment the cloudflare plugin creates, and it
+ * is the one that renders.
+ *
+ * The `runner` property is the test rather than vite's `isRunnableDevEnvironment`
+ * (which is `instanceof RunnableDevEnvironment`): that handle is what Astro's
+ * own content invalidation reaches for, and this file is loaded as source out of
+ * a brand's node_modules, where an import of vite to ask the question would be
+ * the only one any integration here has.
+ *
+ * @typedef {Parameters<
+ *   NonNullable<import("astro").AstroIntegration["hooks"]["astro:server:setup"]>
+ * >[0]["server"]} DevServer
+ */
+
+/**
+ * @param {DevServer} server
+ * @returns {string[]} The environments reloaded, for the signal line.
+ */
+function reloadRenderEnvironments(server) {
+  /** @type {string[]} */
+  const reloaded = [];
+  for (const environment of Object.values(server.environments)) {
+    if (environment.name === "client" || "runner" in environment) continue;
+    const timestamp = Date.now();
+    for (const id of CONTENT_VIRTUAL_IDS) {
+      const module = environment.moduleGraph.getModuleById(id);
+      // The graph entry first: a reload without it re-imports the cached
+      // transform, which is the store as it stood when that transform ran.
+      if (module) {
+        environment.moduleGraph.invalidateModule(
+          module,
+          undefined,
+          timestamp,
+          true,
+        );
+      }
+    }
+    // No `triggeredBy`: the runner then clears every evaluated module and
+    // imports each entrypoint again, rather than walking one file's importers
+    // to entrypoints the store module has no edge to.
+    environment.hot.send({ type: "full-reload", path: "*" });
+    reloaded.push(environment.name);
+  }
+  return reloaded;
+}
+
 /**
  * One signal line on stdout. Written directly rather than through Astro's
  * logger, which wraps and colorizes: a supervisor parses these, so they have to

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

@@ -1,4 +1,5 @@
 // @ts-check
+import { restartInFlight } from "./dev-restart-state.mjs";
 
 // 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
@@ -10,6 +11,33 @@
 // /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.
+//
+// NOTHING IS FETCHED FROM INSIDE A FAILING REQUEST (3.8.1). Until 3.8.0 the
+// 5xx path fetched /under-construction back through this same port while it
+// held the failing response open, and that wedged the dev server for good.
+// Measured in Docker, on the site-config edit that restarts the server in
+// place: an in-flight request resolves 500 `fetch failed` (the Cloudflare
+// plugin's miniflare goes down under it), the shell's self-fetch answers 200
+// in 271ms, and from then on every request that reaches workerd renders (the
+// worker logs its own 200) and never reaches the client, for the whole 120s
+// probe window. Node's own middleware still answers in 8ms, so what the
+// nested request leaves broken is the node-to-workerd path, inside
+// @cloudflare/vite-plugin. With the same self-fetch gone the same edit
+// recovered in 6s, and with the whole integration off, in 11s.
+//
+// So the branded body is CACHED instead, and a 5xx answers from memory with no
+// I/O at all. The one fetch that fills the cache runs after a request this
+// server has just ANSWERED, page and all: the only moment it is known to be
+// able to render its own route, and the furthest possible moment from a
+// restart. Nothing waits on that fetch, it carries an abort timeout, and it
+// does not run while `dev-server-signals` says a restart is in flight. One
+// server fetches once, and a restarted server fetches again off its own first
+// page, which is what picks up an edited navbar.
+//
+// The cached body outlives the server that fetched it, so a preview that has
+// shown the branded shell keeps showing it across a restart. Before the first
+// page of a session renders there is nothing to cache, and a break that early
+// gets the static shell below.
 
 // 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
@@ -20,9 +48,41 @@
  * >[0]["server"]} ViteDevServer
  */
 
+/**
+ * Whether THIS server has the branded body yet, whether a fetch for it is
+ * already out, and how many it has spent trying.
+ *
+ * @typedef {{ warmed: boolean, warming: boolean, attempts: number }} WarmState
+ */
+
 const FALLBACK_PATH = "/under-construction";
 
-// Served when /under-construction itself can't render (e.g. Layout broken).
+/**
+ * How long a warm fetch may take before it is abandoned. Nothing waits on it,
+ * so it can be patient: a cold server rendered this route in 5.3s under
+ * Docker. It is bounded all the same, because a fetch that never settles would
+ * hold `warming` up and leave the cache unfillable for the rest of the server.
+ */
+const WARM_TIMEOUT_MS = 10_000;
+
+/**
+ * The branded body, once some server has managed to fetch it. Module scope on
+ * purpose: an in-place restart builds a new server, and a preview that has
+ * been showing the branded shell should not drop back to the static one while
+ * the new server warms up.
+ */
+let cachedShell = "";
+
+/**
+ * How many times one server tries. A repo whose /under-construction route is
+ * gone answers 404 forever, and without a cap every page view would spend a
+ * fetch on it.
+ */
+const WARM_ATTEMPTS = 3;
+
+// Served until the branded body is cached, and after that only if the branded
+// fetch keeps failing: /under-construction not rendering (a broken Layout), or
+// a break before this session has rendered any page at all.
 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">
@@ -42,6 +102,14 @@ export default function previewErrorShell() {
               {
                 name: "preview-error-shell",
                 configureServer(server) {
+                  // Per server, so a restarted one warms again. The body it
+                  // fetches is shared; whether THIS server has fetched it is
+                  // not.
+                  const state = {
+                    warmed: false,
+                    warming: false,
+                    attempts: 0,
+                  };
                   server.middlewares.use((req, res, next) => {
                     const accept = String(req.headers.accept ?? "");
                     if (
@@ -51,7 +119,7 @@ export default function previewErrorShell() {
                     ) {
                       return next();
                     }
-                    intercept(server, res);
+                    intercept(server, state, res);
                     next();
                   });
                   // Astro's own dev handler registers earlier in the connect
@@ -72,13 +140,14 @@ export default function previewErrorShell() {
 
 /**
  * Buffer the response; replay it verbatim unless it resolves to a 5xx, in
- * which case serve the branded fallback body instead. Buffering trades dev
+ * which case serve the cached fallback body instead. Buffering trades dev
  * streaming for the swap — fine for a preview.
  *
  * @param {ViteDevServer} server
+ * @param {WarmState} state
  * @param {import("node:http").ServerResponse} res
  */
-function intercept(server, res) {
+function intercept(server, state, res) {
   /** @type {Array<string | Buffer>} */
   const chunks = [];
   /** @type {unknown[] | null} */
@@ -112,34 +181,45 @@ function intercept(server, res) {
         res.end = original.end;
         if (headArgs) original.writeHead(.../** @type {[number]} */ (headArgs));
         for (const c of chunks) original.write(c);
-        return original.end();
+        const answered = original.end();
+        // This server just proved it can render a page of its own. That is the
+        // moment, and the only one, to go and get the branded body.
+        if (!state.warmed) warm(server, state);
+        return answered;
       }
-      void serveFallback(server, original, status);
-      return res;
+      original.writeHead(status, {
+        "content-type": "text/html",
+        "x-preview-fallback": "1",
+      });
+      original.write(cachedShell || MINIMAL_FALLBACK);
+      return original.end();
     }
   );
 }
 
 /**
+ * Fetch the branded body into the cache. Fire and forget: nothing waits on it,
+ * no response is open on it, and a failure leaves the previous body in place.
+ *
  * @param {ViteDevServer} server
- * @param {{ writeHead: Function, write: Function, end: Function }} original
- * @param {number} status
+ * @param {WarmState} state
  */
-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" },
+function warm(server, state) {
+  if (state.warming || state.attempts >= WARM_ATTEMPTS) return;
+  if (restartInFlight()) return;
+  state.warming = true;
+  state.attempts += 1;
+  const port = server.config.server.port;
+  void fetch(`http://127.0.0.1:${port}${FALLBACK_PATH}`, {
+    headers: { accept: "text/html" },
+    signal: AbortSignal.timeout(WARM_TIMEOUT_MS),
+  })
+    .then((resp) => (resp.ok ? resp.text() : ""))
+    .catch(() => "")
+    .then((html) => {
+      state.warming = false;
+      if (!html) return;
+      state.warmed = true;
+      cachedShell = 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();
 }