@iterant/site-runtime 3.8.1 → 3.9.0

package/docs/runtime-contract.md

@@ -50,7 +50,7 @@ runtime and says so.
 
 <!-- generated: available libraries -->
 
-_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.8.1._
+_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.9.0._
 
 **Toolchain** (this package owns the version; do NOT declare these):
 
@@ -617,13 +617,27 @@ The layout preloads the upright latin face of each named family and nothing
 else. Every face stays in the `@font-face` block, so the browser still fetches a
 slanted or extended-latin one the moment a glyph needs it.
 
-**`src/site-config.ts` is watched.** Astro restarts its dev server on its own
-config file, `package.json` and the tsconfig sources, and on nothing else, so a
-family added to `SITE_CONFIG.fonts` would be rendered by the layout while Astro
-had never resolved it. The preset adds the file to `settings.watchFiles`
-(`site-config-watch`), which makes the change restart the server and reach the
-font declarations. A repo that keeps its site config elsewhere passes
-`iterantStarter({ siteConfigPath })`.
+**`src/site-config.ts` is watched in list mode.** Astro restarts its dev server
+on its own config file, `package.json` and the tsconfig sources, and on nothing
+else, so a family added to `SITE_CONFIG.fonts` would be rendered by the layout
+while Astro had never resolved it. The preset adds the file to
+`settings.watchFiles` (`site-config-watch`), which makes the change restart the
+server and reach the font declarations. A repo that keeps its site config
+elsewhere passes `iterantStarter({ siteConfigPath })`.
+
+**Under `fonts: "catalog"` the preset registers no restart watch on it; Vite
+still watches it as a source module.** Every
+family is declared at boot, so a family written into `SITE_CONFIG.fonts` after
+that is one Astro already resolved, and the layout picks it up on the first
+render after the module's hot update has been processed. The site config is then outside the Astro
+config's import graph too, since the config no longer reads it, so no write of
+it restarts the server. That is the mode the platform's own starters run: the
+direction pick writes the file on every first build, and the restart it used to
+cause cost 11.7s of preview outage, ending in a re-attach the customer saw as
+the waking card (measured 2026-09-12). The boot pays 6.3s of font resolution
+instead of 1.2s on a cold tree, and nothing on a tree whose `.astro/fonts` cache
+came with it and whose metadata is under seven days old (Astro refreshes the
+metadata after that, through the cache's own files).
 
 ### The browser floor
 
@@ -749,6 +763,29 @@ The preset also pre-bundles `astro/logger/json`, which the supervisor's
 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.1",
+  "version": "3.9.0",
   "type": "module",
   "description": "The platform layer every Iterant brand site runs on: content grammar, collection schemas, SEO head and JSON-LD, layout core, Astro config preset, dev integrations and the verify gates.",
   "scripts": {

package/src/config/preset.ts

@@ -89,6 +89,11 @@ const FONT_SUBSETS: NonEmpty<string> = ["latin", "latin-ext"];
  * render a face Astro never resolved. `site-config-watch` makes that restart
  * happen, and these eleven make it unnecessary for the common pick.
  *
+ * `"catalog"` takes the other road: with every family declared, nothing the
+ * platform writes into SITE_CONFIG.fonts can name a face Astro did not resolve,
+ * so the site config leaves the dev server's restart list entirely and a
+ * direction pick reaches the page as a hot update instead of a reboot.
+ *
  * A name the catalog does not carry is skipped rather than declared: Astro's
  * `<Font>` throws on a CSS variable no family registered, and the layout reads
  * the same catalog to decide what to render.
@@ -163,9 +168,12 @@ export interface IterantStarterOptions {
    */
   fonts?: readonly string[] | "catalog";
   /**
-   * The repo's site config module, relative to the project root. Watched, so a
-   * change to `SITE_CONFIG.fonts` restarts the dev server and reaches the font
-   * declarations; the preset does not import the file, it only names it.
+   * The repo's site config module, relative to the project root. In list mode
+   * it is watched, so a change to `SITE_CONFIG.fonts` restarts the dev server
+   * and reaches the font declarations; the preset does not import the file, it
+   * only names it. Under `fonts: "catalog"` the preset registers no restart
+   * watch on it (Vite still watches it as a module), because every
+   * family is already declared.
    */
   siteConfigPath?: string;
   /**
@@ -226,8 +234,16 @@ export function iterantStarter({
     newFileReload(),
     // Dev-only: restart signals, the content re-arm, and the dev-state probe.
     devServerSignals({ pagesDir, chromeDir }),
-    // Restart the dev server when the site config the fonts come from changes.
-    siteConfigWatch(siteConfigPath),
+    // Restart the dev server when the site config the fonts come from changes,
+    // in list mode alone. The watch exists for one reason: the preset turns
+    // SITE_CONFIG.fonts into font declarations once, at server start, so a
+    // family added to that list after boot would render a face Astro never
+    // resolved. `"catalog"` declares every family up front, which answers the
+    // same question without a restart, and the restart is not free: every first
+    // build writes src/site-config.ts on the direction pick, and that cost 11.7s
+    // of preview outage, with a `preview.upstream-error` and a re-attach the
+    // customer sees as the waking card (measured 2026-09-12, run 10).
+    ...(fonts === "catalog" ? [] : [siteConfigWatch(siteConfigPath)]),
   ];
 
   const fontFamilies = catalogFontFamilies(fonts);

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-server-signals.mjs

@@ -66,6 +66,33 @@ import { beginRestart, endRestart } from "./dev-restart-state.mjs";
 // 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
@@ -78,6 +105,7 @@ import { beginRestart, endRestart } from "./dev-restart-state.mjs";
 //   {"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
@@ -121,6 +149,10 @@ import { beginRestart, endRestart } from "./dev-restart-state.mjs";
 // `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";
@@ -241,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
@@ -317,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