@junejs/server 0.0.9 → 0.0.11

package/src/pipeline.ts

@@ -9,7 +9,7 @@
 // Bun.* — the dev-only and worker-only concerns (fs route discovery vs frozen
 // manifest) are injected as a RouteResolver, not branched on here.
 
-import React from "react";
+import React, { Suspense, use } from "react";
 // renderToReadableStream (NOT renderToStaticMarkup): it is the ONE render
 // function present in every react-dom/server build — node, browser, AND edge.
 // workerd resolves react-dom/server to server.edge (server.browser needs
@@ -18,6 +18,7 @@ import React from "react";
 import { renderToReadableStream } from "react-dom/server";
 
 import {
+  LoaderDataContext,
   type BrandedRoute,
   type Metadata,
   type RenderTarget,
@@ -33,12 +34,15 @@ import {
   sitemapXml,
 } from "@junejs/core/discovery";
 import { mcpHandler, mcpTools } from "@junejs/core/mcp";
+
+import { ensureScope, runInScope } from "@junejs/db";
 import type { AgentConfig } from "@junejs/core/config";
 import type { Resources } from "@junejs/core/resources";
 
 import { negotiate } from "./negotiate";
 
 export type LayoutComponent = React.ComponentType<{ children: React.ReactNode }>;
+export type LoadingComponent = React.ComponentType;
 
 // What a resolver returns for a matched pathname: the route definition, its
 // params, and the layout chain (root→leaf) that wraps it.
@@ -46,6 +50,10 @@ export type Resolved = {
   def: BrandedRoute;
   params: Record<string, string>;
   chain: LayoutComponent[];
+  // The nearest loading.tsx up the segment chain. Its presence opts a route
+  // into streaming Suspense: the shell + this fallback flush before load()
+  // resolves, then the view streams in.
+  loading?: React.ComponentType;
 };
 
 // The one thing dev and worker do differently: turn a clean pathname into a
@@ -93,6 +101,48 @@ function text(body: string, contentType: string, init?: ResponseInit) {
   return new Response(body, { ...init, headers });
 }
 
+// Make loader data available to the view's descendants via useLoaderData(). The
+// view itself receives data as PROPS (canonical); this provider is the escape
+// hatch for deep children and the Remix-style `const data = useLoaderData()`.
+function provideLoaderData(data: unknown, node: React.ReactNode): React.ReactNode {
+  return React.createElement(LoaderDataContext.Provider, { value: data }, node);
+}
+
+// The suspending leaf of a streaming route: use() the load promise, then render
+// the view. While the promise is pending the component suspends, so React emits
+// the surrounding Suspense fallback (loading.tsx) in the shell.
+function StreamedView({
+  loadPromise,
+  def,
+  ctx,
+}: {
+  loadPromise: Promise<unknown>;
+  def: BrandedRoute;
+  ctx: RouteContext;
+}): React.ReactNode {
+  const data = use(loadPromise);
+  return provideLoaderData(data, def.view ? def.view(data, ctx) : null);
+}
+
+// renderToReadableStream does not emit the doctype; prepend it without buffering
+// the React stream (streaming stays incremental).
+function withDoctype(source: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
+  const reader = source.getReader();
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(new TextEncoder().encode("<!doctype html>\n"));
+    },
+    async pull(controller) {
+      const { done, value } = await reader.read();
+      if (done) controller.close();
+      else controller.enqueue(value);
+    },
+    cancel(reason) {
+      void reader.cancel(reason);
+    },
+  });
+}
+
 // The default favicon: the site name's first character in a rounded square —
 // a plain SVG string, so it needs no fonts, no rasterizer, and works for CJK
 // names as readily as latin ones. Served at /favicon.svg AND /favicon.ico
@@ -133,19 +183,52 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
       (acc, L) => React.createElement(L, null, acc),
       node,
     );
-    // WebMCP: register the app's actions as browser tools. Computed per render
-    // from the live registry (stable after warmup), gated on agent.webmcp + mcp
-    // (execute proxies to /mcp). No actions → no script → page stays zero-JS.
-    const webmcpTools = agent.webmcp && agent.mcp ? mcpTools() : null;
-    const config: DocumentConfig = webmcpTools?.length ? { ...docConfig, webmcpTools } : docConfig;
     const stream = await renderToReadableStream(
-      React.createElement(Document, { config, metadata, children: wrapped }),
+      React.createElement(Document, { config: docConfigForRender(), metadata, children: wrapped }),
     );
     await stream.allReady; // fully resolved markup (no streamed Suspense fallbacks)
     const html = "<!doctype html>\n" + (await new Response(stream).text());
     return new Response(html, { status, headers: htmlHeaders() });
   }
 
+  // WebMCP: register the app's actions as browser tools. Computed per render
+  // from the live registry (stable after warmup), gated on agent.webmcp + mcp
+  // (execute proxies to /mcp). No actions → no script → page stays zero-JS.
+  function docConfigForRender(): DocumentConfig {
+    const webmcpTools = agent.webmcp && agent.mcp ? mcpTools() : null;
+    return webmcpTools?.length ? { ...docConfig, webmcpTools } : docConfig;
+  }
+
+  // Streaming Suspense: the shell (layout chain + the loading.tsx fallback)
+  // flushes immediately; <StreamedView> use()s the load promise, so React
+  // streams the resolved view in once load() settles. Gated by the caller on
+  // a present loading.tsx AND static metadata (a data-derived <title> can't
+  // stream — the <head> is outside the boundary).
+  async function renderStreamingDocument(
+    resolved: Resolved,
+    loadPromise: Promise<unknown>,
+    ctx: RouteContext,
+  ): Promise<Response> {
+    const { def, chain, loading: Loading } = resolved;
+    const leaf = React.createElement(StreamedView, { loadPromise, def, ctx });
+    const boundary = React.createElement(
+      Suspense,
+      { fallback: Loading ? React.createElement(Loading) : null },
+      leaf,
+    );
+    const wrapped = chain.reduceRight<React.ReactNode>(
+      (acc, L) => React.createElement(L, null, acc),
+      boundary,
+    );
+    const metadata = typeof def.metadata === "object" ? def.metadata : undefined;
+    const stream = await renderToReadableStream(
+      React.createElement(Document, { config: docConfigForRender(), metadata, children: wrapped }),
+      { onError: (e: unknown) => console.error("[june] streaming render error:", e) },
+    );
+    // NO allReady — return the live stream (shell first), doctype prepended.
+    return new Response(withDoctype(stream), { status: 200, headers: htmlHeaders() });
+  }
+
   function notFoundResponse(target: RenderTarget, pathname: string): Promise<Response> | Response {
     // Data clients get a JSON 404; humans get the rendered NotFound document.
     return target !== "view"
@@ -195,7 +278,7 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
       const payload = typeof def.json === "function" ? await def.json(data, ctx) : data;
       return Response.json(payload);
     }
-    const node = def.view ? def.view(data, ctx) : null;
+    const node = provideLoaderData(data, def.view ? def.view(data, ctx) : null);
     return renderDocument(node, resolveMeta(def, data, ctx), 200, chain);
   }
 
@@ -219,17 +302,16 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
     }
   }
 
-  return {
-    async fetch(request: Request): Promise<Response> {
+  async function handleRequest(request: Request): Promise<Response> {
       const url = new URL(request.url);
 
       // --- agent surface ---------------------------------------------------
       if (url.pathname === "/mcp") {
         if (!agent.mcp) return notFoundResponse("view", url.pathname);
-        // The agent's tool calls run through the same resources (and, once auth
-        // is wired, the same principal) the UI uses.
-        const res = cfg.resources ? await cfg.resources() : undefined;
-        return mcpHandler(request, { request, db: res?.db, kv: res?.kv, blob: res?.blob });
+        // The agent's tool calls run inside the same request scope, so an action's
+        // ambient `db` is the SAME resource the UI uses (and, once auth is wired,
+        // the same principal via ctx). ctx carries identity only — not resources.
+        return mcpHandler(request, { request });
       }
       if (request.method === "GET" && agent.discovery) {
         const d = await discovery(url);
@@ -258,17 +340,25 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
       const resolved = await cfg.resolve(pathname);
       if (!resolved) return notFoundResponse(target, pathname);
 
-      const res = cfg.resources ? await cfg.resources() : undefined;
+      // ctx is identity/request only; db/kv/blob are ambient (read from the
+      // request scope this whole handler runs inside — see runInScope below).
       const ctx: RouteContext = {
         request,
         url,
         params: resolved.params,
         target,
         speculative,
-        db: res?.db,
-        kv: res?.kv,
-        blob: res?.blob,
       };
+      // Streaming Suspense: a view request on a route with loading.tsx AND
+      // static metadata flushes the shell + fallback before load() resolves.
+      // (data-derived metadata can't stream — the <head> needs the title.)
+      if (target === "view" && resolved.loading && typeof resolved.def.metadata !== "function") {
+        const loadPromise = Promise.resolve(
+          resolved.def.load ? resolved.def.load(ctx) : undefined,
+        );
+        return renderStreamingDocument(resolved, loadPromise, ctx);
+      }
+
       let data: unknown;
       try {
         data = resolved.def.load ? await resolved.def.load(ctx) : undefined;
@@ -277,6 +367,17 @@ export function createPipeline(cfg: PipelineConfig): Pipeline {
         return notFoundResponse(target, pathname);
       }
       return renderProjection(resolved, target, data, ctx);
+  }
+
+  return {
+    async fetch(request: Request): Promise<Response> {
+      // Open the request's resources (memoized; env-bound on workerd) and run the
+      // ENTIRE request inside the scope, so ambient db/kv/blob resolve to them in
+      // loaders, views, and /mcp actions alike. ensureScope() lazily wires the
+      // async-context provider on first request (no static node:* import).
+      await ensureScope();
+      const resources = cfg.resources ? await cfg.resources() : {};
+      return runInScope({ resources }, () => handleRequest(request));
     },
   };
 }

package/src/resources.ts

@@ -5,8 +5,13 @@
 
 import type { ResourceConfig, Resources } from "@junejs/core/resources";
 
+// Import the EDGE-safe d1 adapter directly (not via ./db, which pulls host/
+// node:* — that would defeat keeping the worker graph host-free).
+import { d1, type D1Database } from "./d1";
+
 // Open every declared resource once. Returns a memoized provider so the same
 // long-lived handles are reused across requests (one SQLite connection, etc.).
+// Env-unaware — the dev/Node path, where resources are local processes.
 export function memoizeResources(
   config?: ResourceConfig,
 ): () => Promise<Resources> {
@@ -26,3 +31,45 @@ export function memoizeResources(
     return opened;
   };
 }
+
+// The deployed worker's env: the platform bindings the adapter declared in
+// wrangler. `DB` is the D1 binding name the workers() adapter emits for a
+// declared `db` resource (see adapter.ts ResourcePlan).
+export type WorkerEnv = { DB?: D1Database } & Record<string, unknown>;
+
+// Which resources the app declared — a pure descriptor the build bakes into the
+// generated worker entry. The worker resolves them from `env` bindings, NOT from
+// the user's config: importing the config would drag the host-only sqlite()/dev
+// server (node:child_process/http) into the workerd bundle. Local dev opens the
+// real factories instead, through memoizeResources() (see app.ts).
+export type ResourceFlags = { db?: boolean; kv?: boolean; blob?: boolean };
+
+// The PROD/worker provider. It binds declared resources to their EDGE handles
+// from env (env.DB → D1) — the prod half of "sqlite dev → D1 prod, one
+// declaration": the same `resources: { db: sqlite() }` runs on D1 at the edge,
+// because D1 *is* SQLite (same SQL, same Juno tables). No env binding → the
+// handle is absent and the route degrades (ctx.db undefined), never a crash.
+// Memoized per isolate (env is stable across requests in a workerd isolate).
+//
+// env is typed `unknown` (it arrives untyped from the runtime) and narrowed to
+// WorkerEnv — keeping the provider assignable to WorkerManifest.resources.
+export function bindWorkerResources(
+  flags: ResourceFlags,
+): (env?: unknown) => Promise<Resources> {
+  if (!flags.db && !flags.kv && !flags.blob) {
+    const empty: Resources = {};
+    return () => Promise.resolve(empty);
+  }
+  let opened: Promise<Resources> | null = null;
+  return (rawEnv) => {
+    const env = rawEnv as WorkerEnv | undefined;
+    if (!opened) {
+      opened = (async () => ({
+        db: flags.db && env?.DB ? await d1(env.DB).open() : undefined,
+        // kv/blob edge bindings (KV/R2) land with their adapters; a declared-but-
+        // unbound resource degrades to undefined, the same as db.
+      }))();
+    }
+    return opened;
+  };
+}

package/src/sqlite-driver.ts

@@ -0,0 +1,160 @@
+// Local SQLite driver selection — the ONE place that judges which built-in
+// sqlite the current runtime provides, decoupled from the host's server/spawn
+// concerns (host.ts). Both are zero-install: `bun:sqlite` under Bun, `node:sqlite`
+// under Node. This is dev/host-only (the deployed worker binds D1 from env via
+// src/d1.ts and never touches this module).
+//
+// Why a separate layer: the bun-vs-node *driver* choice and the bun-vs-node
+// *host* choice happen to share a signal (`typeof Bun`), but they answer
+// different questions — and the Node path has a real version cliff that deserves
+// one clear error, not a raw ERR_UNKNOWN_BUILTIN_MODULE leaking from a dynamic
+// import. Keeping the judgment here means host.ts just delegates.
+
+import type { JuneDb } from "@junejs/core/resources";
+
+// The shape bun:sqlite exposes directly and node:sqlite is adapted to: a
+// prepared statement with positional binding.
+type SyncStatement = {
+  all(...params: unknown[]): unknown[];
+  get(...params: unknown[]): unknown;
+  run(...params: unknown[]): { changes: number | bigint; lastInsertRowid?: number | bigint };
+};
+type SyncSqlite = {
+  query(sql: string): SyncStatement;
+  exec(sql: string): void;
+  close(): void;
+};
+
+// node:sqlite landed in v22.5.0 behind --experimental-sqlite, and lost the flag
+// in v22.13.0 (the 22 LTS line) and v23.4.0. We need the flag-free builtin, so
+// 22.13.0 is the practical floor on LTS; 23.4.0 on the odd line.
+export const NODE_SQLITE_MIN_LTS = "22.13.0";
+export const NODE_SQLITE_MIN_ODD = "23.4.0";
+
+// Wrap a synchronous SQLite handle as the async JuneDb. The driver work is
+// synchronous, but the SURFACE is async, so swapping in D1 later is invisible to
+// every caller. (Moved here from host.ts with the driver it serves.)
+function asyncSqlite(db: SyncSqlite): JuneDb {
+  const self: JuneDb = {
+    async query<T>(sql: string, params: unknown[] = []) {
+      return db.query(sql).all(...params) as T[];
+    },
+    async get<T>(sql: string, params: unknown[] = []) {
+      // Normalize "no row" to undefined — bun:sqlite returns null, node:sqlite
+      // returns undefined; the seam hides the difference.
+      return (db.query(sql).get(...params) ?? undefined) as T | undefined;
+    },
+    async run(sql: string, params: unknown[] = []) {
+      const r = db.query(sql).run(...params);
+      return { changes: Number(r.changes), lastInsertRowid: r.lastInsertRowid ?? 0 };
+    },
+    async exec(sql: string) {
+      db.exec(sql);
+    },
+    async transaction<T>(fn: (tx: JuneDb) => Promise<T>) {
+      db.exec("BEGIN");
+      try {
+        const out = await fn(self); // same connection — sqlite is single-writer
+        db.exec("COMMIT");
+        return out;
+      } catch (e) {
+        db.exec("ROLLBACK");
+        throw e;
+      }
+    },
+    async close() {
+      db.close();
+    },
+  };
+  return self;
+}
+
+// The actionable message when Node can't provide node:sqlite — the bad-first-run
+// path this layer exists to fix. Pure + exported so it is unit-testable without
+// an old Node. `nodeVersion` is process.versions.node (e.g. "20.11.0").
+export function nodeSqliteHelp(nodeVersion: string): string {
+  return [
+    `June's local database needs Node's built-in sqlite (node:sqlite), which this`,
+    `runtime can't load. You're on Node v${nodeVersion}.`,
+    ``,
+    `node:sqlite is available without a flag in Node >= ${NODE_SQLITE_MIN_LTS} (LTS) or`,
+    `>= ${NODE_SQLITE_MIN_ODD}. Node 22.5–22.12 / 23.0–23.3 have it behind`,
+    `--experimental-sqlite, and older Node doesn't ship it at all.`,
+    ``,
+    `Fix it one of two ways:`,
+    `  • Upgrade Node to ${NODE_SQLITE_MIN_LTS}+ (recommended), or`,
+    `  • Run June with Bun — bun:sqlite is built in, no flag, no version floor.`,
+  ].join("\n");
+}
+
+// --- silencing node:sqlite's one-time ExperimentalWarning -------------------
+// Node prints `ExperimentalWarning: SQLite is an experimental feature` the first
+// time node:sqlite loads. We guard the version, so we KNOW it works here — the
+// warning is just first-run noise. Silence ONLY that one line; every other
+// warning (deprecations, other experimentals) must still pass through.
+
+// True for exactly Node's node:sqlite ExperimentalWarning. Pure + exported so
+// the filter is unit-testable without triggering a real warning.
+export function isNodeSqliteExperimentalWarning(type: unknown, message: string): boolean {
+  return type === "ExperimentalWarning" && /sqlite/i.test(message);
+}
+
+type EmitWarning = (warning: string | Error, ...rest: unknown[]) => void;
+
+// Wrap an emitWarning impl so the node:sqlite experimental warning is dropped
+// and everything else is forwarded verbatim.
+export function makeWarningFilter(original: EmitWarning): EmitWarning {
+  return (warning, ...rest) => {
+    const message = typeof warning === "string" ? warning : (warning?.message ?? "");
+    // emitWarning(warning, type?) or emitWarning(warning, { type }) — read both.
+    const first = rest[0];
+    const type = typeof first === "string" ? first : (first as { type?: string } | undefined)?.type;
+    if (isNodeSqliteExperimentalWarning(type, message)) return;
+    original(warning, ...rest);
+  };
+}
+
+// bun-types declares the global `Bun`; on Node the binding doesn't exist at
+// runtime, which is exactly what the typeof guard checks.
+declare const Bun: unknown;
+
+// Open a LOCAL sqlite file (or ":memory:") on whichever runtime we're under.
+// The single seam host.openDb() delegates to.
+export async function openLocalSqlite(path: string): Promise<JuneDb> {
+  if (typeof Bun !== "undefined") {
+    // Non-literal specifier so a bundler can't FOLLOW bun:sqlite into a Node
+    // build (it only exists under Bun, and is only reached under Bun).
+    const specifier = "bun:sqlite";
+    const { Database } = (await import(specifier)) as {
+      Database: new (p: string, o?: { create?: boolean }) => SyncSqlite;
+    };
+    return asyncSqlite(new Database(path, { create: true }));
+  }
+
+  // Node: node:sqlite is a builtin, but only flag-free on a recent-enough
+  // version. A failed import here is the version cliff — translate it to guidance
+  // instead of letting ERR_UNKNOWN_BUILTIN_MODULE / "needs --experimental-sqlite"
+  // surface raw.
+  const specifier = "node:sqlite";
+  let mod: { DatabaseSync: new (p: string) => { prepare(sql: string): SyncStatement; exec(sql: string): void; close(): void } };
+  // Drop the SQLite ExperimentalWarning that fires during this import, restoring
+  // the original handler immediately after so no other warning is affected.
+  const originalEmitWarning = process.emitWarning;
+  process.emitWarning = makeWarningFilter(
+    originalEmitWarning.bind(process) as EmitWarning,
+  ) as typeof process.emitWarning;
+  try {
+    mod = (await import(specifier)) as typeof mod;
+  } catch (cause) {
+    throw new Error(nodeSqliteHelp(process.versions.node), { cause });
+  } finally {
+    process.emitWarning = originalEmitWarning;
+  }
+  const db = new mod.DatabaseSync(path);
+  // Adapt node:sqlite (prepare()) to the query()-shaped SyncSqlite surface.
+  return asyncSqlite({
+    query: (sql) => db.prepare(sql),
+    exec: (sql) => db.exec(sql),
+    close: () => db.close(),
+  });
+}

package/src/worker.ts

@@ -16,7 +16,7 @@ import type { AgentConfig } from "@junejs/core/config";
 import type { DocumentConfig } from "@junejs/core/document";
 import type { Resources } from "@junejs/core/resources";
 
-import { createPipeline, type ExtraHandler, type LayoutComponent, type Resolved } from "./pipeline";
+import { createPipeline, type ExtraHandler, type LayoutComponent, type LoadingComponent, type Resolved } from "./pipeline";
 
 export type WorkerManifest = {
   // Static paths → route definitions ("/", "/users", ...).
@@ -26,6 +26,8 @@ export type WorkerManifest = {
   // Layout chains (root→leaf) keyed by route path / dynamic pattern. The build
   // freezes the same chain the dev server loads from app/layout.* files.
   layoutChains?: Record<string, LayoutComponent[]>;
+  // Nearest loading.tsx per route path → streaming Suspense fallback.
+  loadings?: Record<string, LoadingComponent>;
   document: DocumentConfig;
   agent: AgentConfig;
   // Preload Link values (config earlyHints + auto font hints), frozen at build.
@@ -35,8 +37,9 @@ export type WorkerManifest = {
   // The app/_extra.* pre-route handler, imported by the generated entry.
   extra?: ExtraHandler;
   // Opened data resources (db/kv/blob) injected onto ctx. On workerd the D1/KV/R2
-  // bindings come from env per request, so the generated entry passes a provider.
-  resources?: () => Promise<Resources> | Resources;
+  // bindings come from env, so the generated entry passes an ENV-AWARE provider
+  // (bindWorkerResources) — the worker threads its env through on each fetch.
+  resources?: (env?: unknown) => Promise<Resources> | Resources;
 };
 
 type Compiled = { regex: RegExp; names: string[]; def: BrandedRoute; pattern: string };
@@ -82,7 +85,9 @@ function compilePattern(pattern: string): { regex: RegExp; names: string[] } {
   return { regex: new RegExp(allOptional ? `^(?:${source}|/)$` : `^${source}$`), names };
 }
 
-export function createWorker(manifest: WorkerManifest): { fetch(request: Request): Promise<Response> } {
+export function createWorker(
+  manifest: WorkerManifest,
+): { fetch(request: Request, env?: unknown): Promise<Response> } {
   const dynamic: Compiled[] = (manifest.dynamicRoutes ?? []).map((d) => ({
     ...compilePattern(d.pattern),
     def: d.def,
@@ -94,8 +99,15 @@ export function createWorker(manifest: WorkerManifest): { fetch(request: Request
   ].sort();
 
   const chainFor = (key: string): LayoutComponent[] => manifest.layoutChains?.[key] ?? [];
+  const loadingFor = (key: string): LoadingComponent | undefined => manifest.loadings?.[key];
 
-  return createPipeline({
+  // The worker's env (D1/KV/R2 bindings) arrives per fetch and is stable across
+  // requests in an isolate; we capture the latest and hand it to the env-aware
+  // provider, which memoizes the opened handles on first call.
+  let currentEnv: unknown;
+  const provider = manifest.resources;
+
+  const pipeline = createPipeline({
     docConfig: manifest.document,
     agent: manifest.agent,
     routeList: () => routeList,
@@ -103,10 +115,11 @@ export function createWorker(manifest: WorkerManifest): { fetch(request: Request
     htmlCacheControl: manifest.htmlCacheControl,
     notFoundComponent: manifest.notFound,
     extra: manifest.extra,
-    resources: manifest.resources,
+    resources: provider ? () => provider(currentEnv) : undefined,
     resolve: async (pathname): Promise<Resolved | null> => {
       const staticDef = manifest.routes[pathname];
-      if (staticDef) return { def: staticDef, params: {}, chain: chainFor(pathname) };
+      if (staticDef)
+        return { def: staticDef, params: {}, chain: chainFor(pathname), loading: loadingFor(pathname) };
       for (const d of dynamic) {
         const m = pathname.match(d.regex);
         if (m) {
@@ -118,12 +131,19 @@ export function createWorker(manifest: WorkerManifest): { fetch(request: Request
               return v === undefined ? [] : [[n, decodeURIComponent(v)]];
             }),
           );
-          return { def: d.def, params, chain: chainFor(d.pattern) };
+          return { def: d.def, params, chain: chainFor(d.pattern), loading: loadingFor(d.pattern) };
         }
       }
       return null;
     },
   });
+
+  return {
+    fetch(request, env) {
+      currentEnv = env;
+      return pipeline.fetch(request);
+    },
+  };
 }
 
 // --- the deployed worker's outermost layer (run_worker_first) ---------------
@@ -136,7 +156,7 @@ export function createWorker(manifest: WorkerManifest): { fetch(request: Request
 // dynamic routes reach the pipeline. With no ASSETS binding (no prerender), this
 // is a transparent pass-through to the pipeline.
 type AssetEnv = { ASSETS?: { fetch(request: Request): Promise<Response> } };
-type FetchPipeline = { fetch(request: Request): Promise<Response> };
+type FetchPipeline = { fetch(request: Request, env?: unknown): Promise<Response> };
 
 const estimateTokens = (s: string) => String(Math.ceil(s.length / 4));
 
@@ -168,14 +188,21 @@ export function withAssets(
         // no prerendered .md → fall through; a dynamic route renders it below.
       }
 
-      // 2. Static assets (prerendered HTML/.md/.json, /client.js) served direct.
+      // 2. Static assets (prerendered HTML/.md/.json, /client.js, hashed CSS)
+      //    served direct.
       if (assets) {
         const a = await assets.fetch(request);
         if (a.status !== 404) {
           const ct = a.headers.get("content-type") ?? "";
-          if (opts.link && ct.includes("text/html") && !a.headers.has("link")) {
+          const addLink = !!opts.link && ct.includes("text/html") && !a.headers.has("link");
+          // Content-hashed assets (e.g. /global.<hash>.css) are immutable — the
+          // URL changes when the bytes do, so the browser may cache forever and
+          // never revalidate (no 304 round-trip, no stale window).
+          const immutable = /\.[a-f0-9]{8,}\.(css|js)$/.test(url.pathname);
+          if (addLink || immutable) {
             const headers = new Headers(a.headers);
-            headers.set("link", opts.link);
+            if (addLink) headers.set("link", opts.link!);
+            if (immutable) headers.set("cache-control", "public, max-age=31536000, immutable");
             return new Response(a.body, { status: a.status, headers });
           }
           return a;
@@ -183,7 +210,8 @@ export function withAssets(
       }
 
       // 3. Dynamic routes → the render pipeline (already sets Link + negotiates).
-      return pipeline.fetch(request);
+      // Env flows through so the pipeline's resources get the D1/KV/R2 bindings.
+      return pipeline.fetch(request, env);
     },
   };
 }