@iterant/site-runtime 3.8.1 → 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.1._
+_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.8.2._
 
 **Toolchain** (this package owns the version; do NOT declare these):
 
@@ -749,6 +749,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.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/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