@jundle/cloudflare 0.0.0-stage → 0.0.0

package/src/harness.js

@@ -0,0 +1,707 @@
+// Jundle workerd module-runner harness (SPEC §16.11).
+//
+// Static worker script, constructed ONCE per dev session by the
+// CF plugin's runner (Miniflare: this script + the unsafe-eval
+// binding + the wrangler-derived bindings). It contains NO app
+// code: app modules are fetched as text from the dev server
+// over HTTP and evaluated through the unsafe-eval binding as
+// CJS-converted code with a require hook — the workerd
+// counterpart of the Node runner's CJS evaluation
+// (packages/jundle/src/dev/runner.js), sharing its semantics:
+// same registry keys, same importer eviction (via the dev
+// server's version route), same loud failures for targets the
+// closure walk missed.
+//
+// This file is a TEMPLATE: the plugin reads it as text and
+// replaces the `// __JUNDLE_WRAPPERS__` line with generated
+// export wrappers (one per DO / Workflow / entrypoint class
+// export, discovered by static analysis on the dev server).
+// It must stay free of Node-only imports: everything here runs
+// in the worker (static node: imports + cloudflare:workers
+// only). It is dev-only machinery: the unsafe-eval binding is
+// a Miniflare option on this worker, never a wrangler binding,
+// never production, never in a prod bundle.
+import * as streamNs from "node:stream";
+import * as bufferNs from "node:buffer";
+import * as cryptoNs from "node:crypto";
+import * as eventsNs from "node:events";
+import * as pathNs from "node:path";
+import * as urlNs from "node:url";
+import * as utilNs from "node:util";
+import * as querystringNs from "node:querystring";
+import * as stringDecoderNs from "node:string_decoder";
+import * as asyncHooksNs from "node:async_hooks";
+import * as timersNs from "node:timers";
+import * as diagnosticsChannelNs from "node:diagnostics_channel";
+import * as cwNs from "cloudflare:workers";
+
+// Internal binding names. They are stripped from user `env`
+// before app code ever sees it (SPEC §16.11: user code receives
+// exactly its own bindings, identical in shape to production).
+const EVAL_NAME = "__jundle_runner_eval";
+const BASE_NAME = "__jundle_runner_base";
+const ENTRY_NAME = "__jundle_runner_entry";
+const INTERNAL = new Set([EVAL_NAME, BASE_NAME, ENTRY_NAME]);
+
+// Node builtins the require hook serves. Only builtins this
+// workerd's nodejs_compat actually provides are listed here
+// (verified by construction: node:os, for example, is NOT
+// provided and must stay out, or the worker fails to start).
+// Anything else fails loudly at require time, exactly like
+// the Node runner's un-pre-loaded error.
+const BUILTINS = {
+  "node:stream": streamNs,
+  "node:buffer": bufferNs,
+  "node:crypto": cryptoNs,
+  "node:events": eventsNs,
+  "node:path": pathNs,
+  "node:url": urlNs,
+  "node:util": utilNs,
+  "node:querystring": querystringNs,
+  "node:string_decoder": stringDecoderNs,
+  "node:async_hooks": asyncHooksNs,
+  "node:timers": timersNs,
+  "node:diagnostics_channel": diagnosticsChannelNs,
+};
+
+// No React Refresh globals are defined here, by design
+// (SPEC §16.6): server runtimes never evaluate a
+// Refresh-carrying module — client modules fetched for
+// SSR arrive as refresh-free SSR variants, and server
+// modules never get Refresh calls. A $RefreshReg$ call
+// evaluated here would throw a ReferenceError, which
+// indicates a variant-routing bug (a browser variant
+// fetched for SSR), not a missing runtime, and must
+// surface loudly rather than silently no-op.
+
+// process.env.NODE_ENV (dev parity with the dev server, which
+// fills NODE_ENV=development when unset). Workerd provides a
+// `process` global with an (empty) env; fill only when unset.
+try {
+  if (typeof process !== "undefined" && process && process.env && !process.env.NODE_ENV)
+    process.env.NODE_ENV = "development";
+} catch {}
+
+// ---- Runner state (per worker instance; lost on crash,
+// rebuilt lazily on next request — see SPEC §16.11) ----
+let evalBinding = null;
+let baseUrl = "";
+let entryUrl = "";
+let lastSeenVersion = 0;
+let manifestsCache = null;
+let lastGoodEntry = null;
+// Dev-module text cache: key `${env}\0${file}` -> {code, edges, filename, dirname}.
+const textCache = new Map();
+// Evaluated dev modules: key -> {exports, failed, error}.
+const evaluated = new Map();
+// Dep bundles: key (fileName, or `${entry}\0${rel}`) -> {code, modules, entryRel}.
+const depText = new Map();
+// Evaluated dep bundles: key -> {exports, failed, error}.
+const depEvaluated = new Map();
+// Parsed JSON values: key `${env}\0${file}` -> value.
+const jsonCache = new Map();
+// Prefetched asset values: key `${env}\0${file}\0${type}` ->
+// the namespace-shaped object the worker returns for that
+// file's asset-value URL ({ __esModule: true, default:
+// <value> }), mirroring NodeRunner's assetValueCache.
+// The key distinguishes type: one file as raw and as blob
+// are different values. One entry per file+env+type, so
+// every SSR importer in one env shares one value object.
+const assetValueCache = new Map();
+
+function devKey(url) {
+  const u = new URL(url, "http://dev");
+  return `${u.searchParams.get("env") || ""}\0${u.searchParams.get("file") || ""}`;
+}
+
+function devAssetKey(url) {
+  const u = new URL(url, "http://dev");
+  return `${u.searchParams.get("env") || ""}\0${u.searchParams.get("file") || ""}\0${u.searchParams.get("type") || ""}`;
+}
+
+function depKeyFromUrl(url) {
+  const u = new URL(url, "http://dev");
+  const rest = u.pathname.slice("/@jundle/deps/".length);
+  const slash = rest.indexOf("/");
+  if (slash === -1) return rest;
+  return `${rest.slice(0, slash)}\0${rest.slice(slash + 1)}`;
+}
+
+function stripEnv(env) {
+  const out = {};
+  for (const k of Object.keys(env)) {
+    if (!INTERNAL.has(k)) out[k] = env[k];
+  }
+  return out;
+}
+
+async function fetchJson(url) {
+  const res = await fetch(baseUrl + url);
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`ModuleRunner: fetch ${url} failed (${res.status}): ${body.slice(0, 500)}`);
+  }
+  return res.json();
+}
+
+// Pull-based invalidation (SPEC §16.11): one loopback fetch per
+// dispatch. Evicts invalidated dev-module keys (evaluated +
+// text) and JSON values for edited JSON files, then advances
+// the seen version. The dev server prunes acked batches.
+// After eviction, pushes fresh SSR-variant instances for the
+// browser-env subset (see pushSsrUpdates) before the entry
+// re-imports, so the entry's decode already sees them.
+async function syncVersion() {
+  const data = await fetchJson(`/@jundle/runner-version?since=${lastSeenVersion}`);
+  lastSeenVersion = data.version;
+  for (const key of data.invalidated || []) {
+    evaluated.delete(key);
+    textCache.delete(key);
+  }
+  for (const file of data.jsonFiles || []) {
+    for (const k of jsonCache.keys()) {
+      if (k.split("\0")[1] === file) jsonCache.delete(k);
+    }
+  }
+  for (const file of data.assetFiles || []) {
+    for (const k of assetValueCache.keys()) {
+      if (k.split("\0")[1] === file) assetValueCache.delete(k);
+    }
+  }
+  await pushSsrUpdates(data.clientInvalidated || []);
+}
+
+// Server-side updateModule push, runner path (SPEC §16.11):
+// after eviction, re-evaluate each evicted browser-env key
+// (server variant — ensureText fetches consumer=server)
+// and push the fresh exports into the dev shim's cache
+// under the stable dev URL, mirroring the browser HMR
+// client's update handler. React's Flight client skips
+// chunk loads on reload (its own module-level chunkCache),
+// so without the push a reloaded page keeps rendering the
+// first SSR instance. Failure keeps last-good silently:
+// the old shim entry stays (the push is skipped, never a
+// delete) and the failure is logged only, never surfaced
+// through the runner-error header. A browser module
+// failing worker evaluation is expected (DOM code has no
+// document in a worker), and surfacing it would trip the
+// hot client's first-update overlay rule and force a full
+// reload on the next update instead of HMR.
+async function pushSsrUpdates(clientKeys) {
+  for (const key of clientKeys) {
+    const [env, file] = key.split("\0");
+    const url = `/@jundle/module?env=${encodeURIComponent(env)}&file=${encodeURIComponent(file)}`;
+    try {
+      const rec = await ensureModuleByUrl(url);
+      globalThis.__jundleFlight?.updateModule?.(url, rec.exports);
+    } catch (e) {
+      console.error(`[jundle runner] SSR push ${url}: ${e && e.message ? e.message : String(e)}`);
+    }
+  }
+}
+
+// Closure walk (async, mirrors NodeRunner.ensureClosure): fetch
+// texts for the module and everything it reaches, so the sync
+// evaluation below never has to load anything. Dev edges,
+// client-ref edges, and server-action edges are all fetched
+// (client modules are transformed server-side by the fetch,
+// which is what populates the dev manifests, but never
+// evaluated — server code references them, it does not import
+// them). Dep edges fetch dep units; JSON edges fetch parsed
+// values; asset-value edges fetch values. CSS / host /
+// external edges fetch nothing.
+async function ensureText(url, visiting = new Set()) {
+  const key = devKey(url);
+  if (textCache.has(key) || visiting.has(key)) return;
+  visiting.add(key);
+  const u = new URL(url, "http://dev");
+  // Server consumer (SPEC §16.6): everything the harness
+  // fetches runs in the worker, so every module fetch
+  // asks for the SSR variant (refresh-free for client
+  // modules). Keys ignore the extra param (devKey reads
+  // env+file only), so registry/textCache identities and
+  // version-check eviction are unchanged.
+  u.searchParams.set("consumer", "server");
+  // Dev URL params are always sorted (SPEC §16.12), so the
+  // added consumer param must not land last out of order.
+  u.searchParams.sort();
+  const data = await fetchJson(`/@jundle/runner-module?${u.searchParams.toString()}`);
+  textCache.set(key, data);
+  for (const edge of data.edges || []) {
+    if (edge.kind === "dev" || edge.kind === "client-ref" || edge.kind === "server-action") {
+      await ensureText(edge.url, visiting);
+    } else if (edge.kind === "dep") {
+      await ensureDepText(edge.url, new Set());
+    } else if (edge.kind === "json") {
+      const jk = devKey(edge.url);
+      if (!jsonCache.has(jk)) {
+        const ju = new URL(edge.url, "http://dev");
+        jsonCache.set(jk, await fetchJson(`/@jundle/runner-json?${ju.searchParams.toString()}`));
+      }
+    } else if (edge.kind === "asset-value") {
+      // Asset-value edges (SPEC §16.12): the harness
+      // prefetches the value like a JSON value, then
+      // reconstructs the namespace the worker returns
+      // for the asset-value URL. Blob values arrive as
+      // base64 + MIME and are rebuilt here (Blob exists
+      // in workerd); raw and json values arrive as-is.
+      const ak = devAssetKey(edge.url);
+      if (!assetValueCache.has(ak)) {
+        const au = new URL(edge.url, "http://dev");
+        const data = await fetchJson(`/@jundle/runner-asset-value?${au.searchParams.toString()}`);
+        let value;
+        if (data.kind === "blob") {
+          value = new Blob([Uint8Array.from(atob(data.base64), (c) => c.charCodeAt(0))], {
+            type: data.mime,
+          });
+        } else {
+          value = data.value;
+        }
+        assetValueCache.set(ak, { __esModule: true, default: value });
+      }
+    }
+  }
+}
+
+// Dep-unit walk. Dep CJS text carries require literals, so
+// edges are derived from them (same literal-call shape the
+// CJS transform emits). A require that resolves to nothing
+// is skipped here — it fails loudly at eval time if actually
+// required, which is the correct (non-wedging) behavior for
+// both genuine misses and string-literal false positives.
+function extractRequires(code) {
+  const out = [];
+  const re = /require\("([^"]+)"\)/g;
+  let m;
+  while ((m = re.exec(code)) !== null) out.push(m[1]);
+  return out;
+}
+
+async function ensureDepText(depUrl, visiting = new Set()) {
+  const key = depKeyFromUrl(depUrl);
+  if (depText.has(key) || visiting.has(key)) return;
+  visiting.add(key);
+  const u = new URL(depUrl, "http://dev");
+  const data = await fetchJson(
+    `/@jundle/runner-dep${u.pathname.slice("/@jundle/deps".length)}${u.search}`,
+  );
+  depText.set(key, data);
+  for (const spec of extractRequires(data.code)) {
+    if (spec.startsWith("/@jundle/deps/")) {
+      await ensureDepText(spec, visiting);
+      continue;
+    }
+    if (spec.startsWith("./") || spec.startsWith("../")) {
+      const slash = key.indexOf("\0");
+      if (slash !== -1) {
+        const bundleEntry = key.slice(0, slash);
+        const rel = key.slice(slash + 1);
+        const normalized = pathNs.posix.normalize(
+          pathNs.posix.join(pathNs.posix.dirname(rel), spec),
+        );
+        if (data.modules && data.modules.includes(normalized)) {
+          await ensureDepText(`/@jundle/deps/${bundleEntry}/${normalized}`, visiting);
+        } else {
+          const base = normalized.split("/").pop();
+          await ensureDepText(`/@jundle/deps/${base}`, visiting).catch(() => {});
+        }
+      } else {
+        await ensureDepText(`/@jundle/deps/${spec.slice(2).split("?")[0]}`, visiting).catch(
+          () => {},
+        );
+      }
+    }
+  }
+}
+
+// Sync evaluation (mirrors NodeRunner.evaluate, including the
+// record-then-swap failure rule: circulars see partial
+// exports during evaluation; on failure the record becomes
+// FAILED (not half-populated), so the next request retries
+// instead of serving a partial module).
+function evaluateDev(key) {
+  const existing = evaluated.get(key);
+  if (existing && !existing.failed) return existing;
+  const text = textCache.get(key);
+  if (!text)
+    throw new Error(
+      `ModuleRunner: module '${key}' was not pre-fetched (the closure walk missed it); use a static, literal specifier so the walk pre-fetches it; dynamic specifiers are not pre-fetched.`,
+    );
+  const record = { exports: {}, failed: false };
+  evaluated.set(key, record);
+  const module = { exports: record.exports };
+  try {
+    if (!evalBinding)
+      throw new Error(
+        "ModuleRunner: unsafe-eval binding missing (Miniflare did not provide __jundle_runner_eval).",
+      );
+    const fn = evalBinding.eval(
+      "(function(require, module, exports, __filename, __dirname) {\n" +
+        text.code +
+        "\n})\n//# sourceURL=" +
+        (key.split("\0")[1] || key),
+    );
+    fn((spec) => requireHook(spec, key), module, module.exports, text.filename, text.dirname);
+  } catch (e) {
+    evaluated.set(key, { exports: {}, failed: true, error: e });
+    throw e;
+  }
+  record.exports = module.exports;
+  return record;
+}
+
+function evaluateDep(depUrl) {
+  const key = depKeyFromUrl(depUrl);
+  const existing = depEvaluated.get(key);
+  if (existing && !existing.failed) return existing;
+  const text = depText.get(key);
+  if (!text)
+    throw new Error(
+      `ModuleRunner: dep bundle '${key}' was not pre-fetched (the closure walk missed it).`,
+    );
+  // Bundle-dir entry redirect (NodeRunner parity: an entry
+  // with an entryRel evaluates through the bundle path).
+  if (!key.includes("\0") && text.entryRel)
+    return evaluateDep(`/@jundle/deps/${key}/${text.entryRel}`);
+  const record = { exports: {}, failed: false };
+  depEvaluated.set(key, record);
+  const module = { exports: record.exports };
+  const slash = key.indexOf("\0");
+  const rel = slash === -1 ? key : key.slice(slash + 1);
+  try {
+    if (!evalBinding)
+      throw new Error(
+        "ModuleRunner: unsafe-eval binding missing (Miniflare did not provide __jundle_runner_eval).",
+      );
+    const fn = evalBinding.eval(
+      "(function(require, module, exports, __filename, __dirname) {\n" +
+        text.code +
+        "\n})\n//# sourceURL=" +
+        rel,
+    );
+    fn((spec) => depRequireHook(spec, key, text), module, module.exports, rel, "");
+  } catch (e) {
+    depEvaluated.set(key, { exports: {}, failed: true, error: e });
+    throw e;
+  }
+  record.exports = module.exports;
+  return record;
+}
+
+function depRequireHook(spec, depKey, depTextRec) {
+  if (spec.startsWith("/@jundle/deps/")) return evaluateDep(spec).exports;
+  // Workerd provides node: builtins (via the harness's
+  // static imports) and cloudflare:workers to any code it
+  // runs, including dep bundles — so the dep hook serves
+  // them, exactly as the workerd bundle's static imports
+  // receive them. (NodeRunner's dep hook fails these; that
+  // is a Node-dev gap, not a runner gap.)
+  if (spec.startsWith("node:")) {
+    if (BUILTINS[spec]) return BUILTINS[spec];
+    throw new Error(
+      `ModuleRunner: dep bundle '${depKey}' requires unsupported Node builtin '${spec}'.`,
+    );
+  }
+  if (spec === "cloudflare:workers") return cwNs;
+  if (spec.startsWith("./") || spec.startsWith("../")) {
+    const slash = depKey.indexOf("\0");
+    if (slash !== -1) {
+      const bundleEntry = depKey.slice(0, slash);
+      const rel = depKey.slice(slash + 1);
+      const normalized = pathNs.posix.normalize(pathNs.posix.join(pathNs.posix.dirname(rel), spec));
+      if (depTextRec.modules && depTextRec.modules.includes(normalized))
+        return evaluateDep(`/@jundle/deps/${bundleEntry}/${normalized}`).exports;
+      const base = normalized.split("/").pop();
+      if (depText.has(base)) return evaluateDep(`/@jundle/deps/${base}`).exports;
+      throw new Error(
+        `ModuleRunner: dep bundle '${depKey}' requires unexpected specifier '${spec}' (dep bundles only import sibling dep files).`,
+      );
+    }
+    return evaluateDep(`/@jundle/deps/${spec.slice(2).split("?")[0]}`).exports;
+  }
+  throw new Error(
+    `ModuleRunner: dep bundle '${depKey}' requires unexpected specifier '${spec}' (dep bundles only import sibling dep files).`,
+  );
+}
+
+// Sync require hook for evaluated app modules (mirrors
+// NodeRunner.requireHook, minus the native-external path:
+// the worker has no native import, so bare non-node specs
+// fail loudly instead of loading natively).
+function requireHook(spec, importerKey) {
+  if (spec.startsWith("/@jundle/module?")) {
+    return evaluateDev(devKey(spec)).exports;
+  }
+  if (spec.startsWith("/@jundle/deps/")) {
+    return evaluateDep(spec).exports;
+  }
+  if (spec.startsWith("/@jundle/json?")) {
+    const key = devKey(spec);
+    if (!jsonCache.has(key))
+      throw new Error(`ModuleRunner: JSON module '${spec}' was not pre-fetched.`);
+    return { __esModule: true, default: jsonCache.get(key) };
+  }
+  if (spec.startsWith("/@jundle/asset-value?")) {
+    const key = devAssetKey(spec);
+    if (!assetValueCache.has(key))
+      throw new Error(`ModuleRunner: asset value '${spec}' was not pre-fetched.`);
+    return assetValueCache.get(key);
+  }
+  if (spec.startsWith("/@jundle/css?")) return {};
+  if (spec === "jundle:dev") return hostContext;
+  if (spec === "cloudflare:workers") return cwNs;
+  if (spec.startsWith("node:")) {
+    if (BUILTINS[spec]) return BUILTINS[spec];
+    throw new Error(
+      `ModuleRunner: Node builtin '${spec}' is not available in workerd dev (unsupported by this workerd's nodejs_compat).`,
+    );
+  }
+  // JSON requires via the importer's server-computed edges
+  // (literal require() calls resolving to JSON): the value
+  // directly, not the namespace (NodeRunner require-json
+  // parity).
+  const importerText = importerKey ? textCache.get(importerKey) : null;
+  if (importerText) {
+    for (const edge of importerText.edges || []) {
+      if (edge.kind === "json" && edge.spec === spec) {
+        const key = devKey(edge.url);
+        if (!jsonCache.has(key))
+          throw new Error(`ModuleRunner: JSON module '${spec}' was not pre-fetched.`);
+        return jsonCache.get(key);
+      }
+    }
+  }
+  // Relative JSON requires (NodeRunner parity for the common
+  // case): the server pre-fetches the value via the
+  // importer's requireJsonFiles edges, and the hook resolves
+  // the relative spec against the importer file. Both the
+  // exact name and the +.json form are tried (NodeRunner
+  // resolves "./data" to data.json the same way). Bare
+  // JSON requires are NOT resolved here (no resolver in
+  // the worker) — they fall through to the loud error
+  // below; use an import for those.
+  if (
+    importerKey &&
+    typeof spec === "string" &&
+    (spec.startsWith("./") || spec.startsWith("../")) &&
+    !spec.startsWith("/@jundle/")
+  ) {
+    const parts = importerKey.split("\0");
+    const importerFile = parts[1] || "";
+    const importerEnv = parts[0] || "";
+    const normalized = pathNs.posix.normalize(
+      pathNs.posix.join(pathNs.posix.dirname(importerFile), spec),
+    );
+    for (const candidate of [normalized, `${normalized}.json`]) {
+      const key = `${importerEnv}\0${candidate}`;
+      if (jsonCache.has(key)) return jsonCache.get(key);
+    }
+  }
+  throw new Error(
+    `ModuleRunner: '${spec}' was not pre-loaded (the closure walk missed it); use a static, literal specifier for this import so the walk pre-loads it; dynamic specifiers are not pre-loaded.`,
+  );
+}
+
+// Host context (the harness side of jundle:dev, mirroring
+// NodeRunner's hostContext: manifests are fetched per
+// dispatch (after import, so they are fresh); importModule
+// resolves through the dev server so absolute manifest file
+// paths map to canonical dev URLs; loadChunk parses the
+// dev-URL chunk id directly.
+const hostContext = {
+  getManifests: () => {
+    return (
+      manifestsCache || { clientManifest: {}, serverManifest: {}, clientEntry: [], clientCss: [] }
+    );
+  },
+  importModule: async (file, env) => {
+    const resolved = await fetchJson(
+      `/@jundle/runner-resolve?env=${encodeURIComponent(env)}&file=${encodeURIComponent(file)}`,
+    );
+    return (await ensureModuleByUrl(resolved.url)).exports;
+  },
+  loadChunk: async (chunkId) => {
+    const u = new URL(chunkId, "http://dev");
+    if (u.pathname !== "/@jundle/module")
+      throw new Error(`ModuleRunner: refusing to load chunk (not a dev module URL): ${chunkId}`);
+    const url = `/@jundle/module?env=${encodeURIComponent(u.searchParams.get("env") || "react-client")}&file=${encodeURIComponent(u.searchParams.get("file") || "")}`;
+    return (await ensureModuleByUrl(url)).exports;
+  },
+};
+
+async function ensureModuleByUrl(url) {
+  await ensureText(url, new Set());
+  return evaluateDev(devKey(url));
+}
+
+// Entry import for wrapper classes (DO / Workflow /
+// entrypoint methods run during dispatch, but an alarm can
+// fire outside any dispatch): always version-check first,
+// so a lazily-created real instance never uses a stale
+// class after an edit.
+async function __jundleImportEntry() {
+  await ensureEvalShims();
+  await syncVersion();
+  const rec = await ensureModuleByUrl(entryUrl);
+  return rec.exports;
+}
+
+// Eval-realm global shims (SPEC §16.11): this workerd
+// provides no WeakRef / FinalizationRegistry, but React's
+// Flight client constructs a WeakRef per response (and
+// other deps may use FinalizationRegistry). Install
+// dev-only shims in the EVAL realm (via the binding —
+// the eval realm may or may not share the worker's
+// global, so assigning from the harness is not enough)
+// before any module evaluates, and only when missing
+// (a future workerd with real WeakRef keeps its own).
+// WeakRef holds strongly: safe here, because React pairs
+// it with a strong `response` field it nulls when done,
+// and the shim reference itself is a collectable cycle.
+// The FinalizationRegistry shim never fires callbacks:
+// finalization is non-deterministic by spec, so dev code
+// must not depend on it firing.
+let evalShimsInstalled = false;
+async function ensureEvalShims() {
+  if (evalShimsInstalled || !evalBinding) return;
+  evalShimsInstalled = true;
+  const missing = evalBinding.eval(
+    "typeof WeakRef === 'undefined' || typeof FinalizationRegistry === 'undefined'",
+  );
+  if (!missing) return;
+  evalBinding.eval(
+    "if (typeof WeakRef === 'undefined') { globalThis.WeakRef = class WeakRef { constructor(t) { this._t = t; } deref() { return this._t; } }; }" +
+      "if (typeof FinalizationRegistry === 'undefined') { globalThis.FinalizationRegistry = class FinalizationRegistry { constructor() {} register() {} unregister() { return false; } }; }",
+  );
+}
+
+// Per-dispatch preamble, shared by fetch / scheduled /
+// queue: bind the internal bindings, pull invalidation,
+// (re-)import the entry, refresh manifests on success.
+// Entry failures keep the last-good entry for dispatch
+// (fetch only — scheduled/queue throw, they have no page
+// to serve stale); manifests stay at their previous
+// version on entry failure, so a stale entry never renders
+// against fresh manifests.
+async function prepareDispatch(env) {
+  evalBinding = env[EVAL_NAME];
+  baseUrl = env[BASE_NAME] || "";
+  entryUrl = env[ENTRY_NAME] || "";
+  if (!evalBinding)
+    throw new Error(
+      "ModuleRunner: unsafe-eval binding missing (Miniflare did not provide __jundle_runner_eval).",
+    );
+  // Dev-only global eval polyfill (SPEC §16.11): workerd bans
+  // codegen from strings at request time, so app code calling
+  // eval (notably React's dev Flight client, which warns and
+  // loses its stack-reconstruction features without it) would
+  // throw. The harness replaces the global eval with a
+  // binding-backed one before any app module evaluates: bare
+  // `eval` (including React's indirect `(0, eval)`) resolves
+  // to this, and the binding evaluates the string as a script
+  // in the worker's global scope — the same semantics as
+  // Node's indirect eval. Non-string arguments return as-is,
+  // per spec. Dev-only by construction: the binding never
+  // exists in production, so prod workerd still throws — and
+  // user code calling eval therefore works in runner dev but
+  // throws in production, a deliberate dev/prod gap stated
+  // in SPEC, not hidden.
+  // eslint-disable-next-line no-eval
+  globalThis.eval = (code) => (typeof code === "string" ? evalBinding.eval(code) : code);
+  if (!baseUrl)
+    throw new Error(`ModuleRunner: dev-server base URL missing (binding ${BASE_NAME} not set).`);
+  if (!entryUrl)
+    throw new Error(`ModuleRunner: entry URL missing (binding ${ENTRY_NAME} not set).`);
+  await ensureEvalShims();
+  await syncVersion();
+  let entryError = null;
+  let entry = null;
+  try {
+    const rec = await ensureModuleByUrl(entryUrl);
+    entry = rec.exports;
+    lastGoodEntry = entry;
+  } catch (e) {
+    entryError = e;
+    entry = lastGoodEntry;
+  }
+  if (entry && !entryError) {
+    manifestsCache = await fetchJson("/@jundle/runner-manifests");
+  }
+  return { entry, entryError };
+}
+
+function errorHeaderValue(e) {
+  return String((e && e.message) || e)
+    .replace(/[\r\n]+/g, " ")
+    .slice(0, 500);
+}
+
+function entryAppOf(entry) {
+  return entry ? entry.default || entry.app : null;
+}
+
+export default {
+  async fetch(request, env, ctx) {
+    try {
+      const { entry, entryError } = await prepareDispatch(env);
+      if (!entry)
+        // No last-good entry: surface the original import
+        // failure, not a generic message, so the overlay
+        // and the 500 body name the real cause.
+        throw (
+          entryError ||
+          new Error(
+            "ModuleRunner: no entry available (first import failed and no last-good entry exists).",
+          )
+        );
+      const app = entryAppOf(entry);
+      if (!app || typeof app.fetch !== "function")
+        throw new Error("ModuleRunner: entry's default export must be an app with a fetch method.");
+      const res = await app.fetch(request, stripEnv(env), ctx);
+      // Only entry errors set the runner-error header (the
+      // dev server broadcasts it to the overlay and strips
+      // it before returning). Push failures are silent
+      // keep-last-good (see pushSsrUpdates) and set no
+      // header: the entry itself is fine and the render
+      // keeps the last-good instance.
+      const headerError = entryError;
+      if (headerError) {
+        const headers = new Headers(res.headers);
+        headers.set("x-jundle-runner-error", errorHeaderValue(headerError));
+        return new Response(res.body, { status: res.status, headers });
+      }
+      return res;
+    } catch (e) {
+      return new Response(
+        "ModuleRunner: " +
+          (e && e.message ? e.message : String(e)) +
+          (e && e.stack ? "\n" + e.stack : ""),
+        {
+          status: 500,
+          headers: { "x-jundle-runner-error": errorHeaderValue(e), "content-type": "text/plain" },
+        },
+      );
+    }
+  },
+  async scheduled(controller, env, ctx) {
+    const { entry, entryError } = await prepareDispatch(env);
+    if (entryError) throw entryError;
+    if (!entry) throw new Error("ModuleRunner: no entry available.");
+    const app = entryAppOf(entry);
+    const handler = app && app.scheduled;
+    if (typeof handler !== "function")
+      throw new Error("ModuleRunner: entry has no scheduled handler.");
+    return handler(controller, stripEnv(env), ctx);
+  },
+  async queue(batch, env, ctx) {
+    const { entry, entryError } = await prepareDispatch(env);
+    if (entryError) throw entryError;
+    if (!entry) throw new Error("ModuleRunner: no entry available.");
+    const app = entryAppOf(entry);
+    const handler = app && app.queue;
+    if (typeof handler !== "function") throw new Error("ModuleRunner: entry has no queue handler.");
+    return handler(batch, stripEnv(env), ctx);
+  },
+};
+
+// __JUNDLE_WRAPPERS__