@junejs/server 0.0.8 → 0.0.10

package/src/build.ts

@@ -17,6 +17,7 @@
 // content freeze (content/*.md → app/_content.ts) is what removes fs from the
 // dynamic route's graph; the worker reads frozen data, never the filesystem.
 
+import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
 import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative, sep } from "node:path";
@@ -24,13 +25,17 @@ import { pathToFileURL } from "node:url";
 
 import { loadJuneConfig } from "./config-loader";
 import { resolveAgent, resolveSpeculationRules } from "@junejs/core/config";
-import { isRouteDefinition, type BrandedRoute } from "@junejs/core/route";
+import { buildLinkHeader } from "@junejs/core/discovery";
+import { routeFromModule, type BrandedRoute } from "@junejs/core/route";
+import { workers, type JuneAdapter, type ResourcePlan } from "./adapter";
 import type { DocumentConfig } from "@junejs/core/document";
 import { collection } from "./content";
 import { createWorker, type WorkerManifest } from "./worker";
 import { findExtraFile } from "./router";
-import type { ExtraHandler, LayoutComponent } from "./pipeline";
+import type { ExtraHandler, LayoutComponent, LoadingComponent } from "./pipeline";
 import { findClientEntry, bundleClientToFile, CLIENT_SCRIPT_URL } from "./client-bundle";
+import { findGlobalCss, minifyCss, processCss, STYLES_URL } from "./css";
+import { buildModuleCss, rolldownCssModulesPlugin, registerCssModules } from "./css-modules";
 
 export type BuildResult = {
   outFile: string;
@@ -42,7 +47,13 @@ export type BuildResult = {
 
 // The segment layout CHAIN root→leaf: every directory level (route groups
 // included) may contribute a layout.* that wraps routes below it.
-type RouteEntry = { path: string; file: string; dynamic: boolean; layouts: string[] };
+type RouteEntry = {
+  path: string;
+  file: string;
+  dynamic: boolean;
+  layouts: string[];
+  loading?: string; // nearest loading.tsx up the tree → streaming Suspense fallback
+};
 
 const PAGE_BASENAMES = new Set(["page", "index"]);
 const ROUTE_EXTS = [".tsx", ".jsx", ".ts", ".js"];
@@ -61,15 +72,17 @@ export async function scanRoutes(
   dir = appDir,
   layouts: string[] = [],
   out: RouteEntry[] = [],
+  loading?: string,
 ): Promise<RouteEntry[]> {
   const ownLayout = segmentFile(dir, "layout");
   const chain = ownLayout ? [...layouts, ownLayout] : layouts;
+  const nearestLoading = segmentFile(dir, "loading") ?? loading;
   const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
   for (const e of entries) {
     if (e.name.startsWith("_") || e.name.startsWith(".")) continue;
     const full = join(dir, e.name);
     if (e.isDirectory()) {
-      await scanRoutes(appDir, full, chain, out);
+      await scanRoutes(appDir, full, chain, out, nearestLoading);
       continue;
     }
     const ext = e.name.match(/\.[^.]+$/)?.[0] ?? "";
@@ -78,7 +91,13 @@ export async function scanRoutes(
     const relDir = relative(appDir, dir);
     const segments = relDir === "" ? [] : relDir.split(sep).filter((s) => !isRouteGroup(s));
     const path = "/" + segments.join("/");
-    out.push({ path: path === "/" ? "/" : path, file: full, dynamic: /\[.+\]/.test(path), layouts: chain });
+    out.push({
+      path: path === "/" ? "/" : path,
+      file: full,
+      dynamic: /\[.+\]/.test(path),
+      layouts: chain,
+      loading: nearestLoading,
+    });
   }
   return out;
 }
@@ -128,13 +147,16 @@ export async function freezeConfig(appRoot: string): Promise<{
   // which re-freezes through buildManifest — sets the SAME clientScript, keeping
   // prerendered pages byte-equivalent to the live worker (parity).
   const hasClient = findClientEntry(join(appRoot, "app")) !== undefined;
+  const hasCss = findGlobalCss(join(appRoot, "app")) !== null;
   return {
     document: {
       site: cfg.site ?? {},
       speculationRules: resolveSpeculationRules(cfg.speculation ?? undefined),
       speculationDelivery: "inline",
       viewTransitions: cfg.viewTransitions ?? true,
+      clientRouter: cfg.clientRouter ?? false,
       clientScript: hasClient ? CLIENT_SCRIPT_URL : null,
+      styles: hasCss ? STYLES_URL : null,
     },
     agent: resolveAgent(cfg.agent),
     earlyHints: cfg.earlyHints ?? [],
@@ -166,21 +188,32 @@ export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
     return chain;
   };
 
+  const loadingCache = new Map<string, LoadingComponent | null>();
+  const loadingFor = async (file?: string): Promise<LoadingComponent | undefined> => {
+    if (!file) return undefined;
+    if (!loadingCache.has(file)) loadingCache.set(file, await importLayout(file) as LoadingComponent | null);
+    return loadingCache.get(file) ?? undefined;
+  };
+
   const routes: Record<string, BrandedRoute> = {};
   const dynamicRoutes: Array<{ pattern: string; def: BrandedRoute }> = [];
   const layoutChains: Record<string, LayoutComponent[]> = {};
+  const loadings: Record<string, LoadingComponent> = {};
 
   for (const r of scanned) {
-    const mod = (await import(pathToFileURL(r.file).href)) as { default?: unknown };
-    if (!isRouteDefinition(mod.default)) continue;
+    const mod = await import(pathToFileURL(r.file).href);
+    const def = routeFromModule(mod);
+    if (!def) continue;
     const chain = await componentsFor(r.layouts);
+    const loading = await loadingFor(r.loading);
     if (r.dynamic) {
-      dynamicRoutes.push({ pattern: r.path, def: mod.default });
+      dynamicRoutes.push({ pattern: r.path, def });
       layoutChains[r.path] = chain;
     } else {
-      routes[r.path] = mod.default;
+      routes[r.path] = def;
       layoutChains[r.path] = chain;
     }
+    if (loading) loadings[r.path] = loading;
   }
 
   let extra: ExtraHandler | undefined;
@@ -194,6 +227,7 @@ export async function buildManifest(appRoot: string): Promise<WorkerManifest> {
     routes,
     dynamicRoutes,
     layoutChains,
+    loadings,
     document: frozen.document,
     agent: frozen.agent,
     earlyHints: frozen.earlyHints,
@@ -222,9 +256,75 @@ export async function juneBuild(
   if (routes.length === 0) throw new Error(`no page.* routes found under ${appDir}`);
 
   const frozen = await freezeConfig(appRoot);
+  // The deploy adapter packages the portable build for its target (default:
+  // built-in workers()). It contributes the entry's export wrapper + emits the
+  // deploy config.
+  const fullConfig = await loadJuneConfig(appRoot);
+  const adapter = (fullConfig.deploy?.adapter as JuneAdapter | undefined) ?? workers();
+
+  // Fail fast on a config the target can't honor (e.g. Vercel has no D1) BEFORE
+  // the expensive bundle/prerender. The adapter only needs to know which
+  // resources are declared, so a presence-only plan suffices here.
+  adapter.validate?.({
+    plan: { db: fullConfig.resources?.db ? { binding: "DB", databaseName: "" } : undefined },
+    config: fullConfig,
+  });
+
+  // Compile the global stylesheet ONCE and content-hash it: the built worker and
+  // prerendered HTML link `/global.<hash>.css`, served immutable (cache forever,
+  // a content change ships a new URL → no revalidation, no stale window). Dev
+  // keeps the stable /global.css; only the asset HREF diverges dev↔built, never
+  // render semantics. freezeConfig + buildManifest both default styles to the
+  // stable URL — override both with the hashed one.
+  const cssOut = await processCss(appDir, { minify: true });
+  let cssAsset: string | null = null;
+  if (cssOut !== null) {
+    const hash = createHash("sha256").update(cssOut).digest("hex").slice(0, 8);
+    cssAsset = `_june/global.${hash}.css`; // under the reserved /_june/ prefix
+    frozen.document.styles = `/${cssAsset}`;
+  }
+
+  // CSS Modules: glob + transform app/**/*.module.css ONCE → the per-file class
+  // maps (the bundlers + dev loaders look these up) AND the collected stylesheet,
+  // which is content-hashed + emitted + linked just like global.css.
+  const { maps: cssModuleMaps, css: rawModuleCss } = await buildModuleCss(appDir, appRoot);
+  // Minify for build (dev serves it readable). Scoped class names are untouched,
+  // so the hashed sheet still matches the maps the bundlers/loaders hand out.
+  const moduleCss = rawModuleCss === null ? null : await minifyCss(rawModuleCss, "modules.css");
+  let moduleCssAsset: string | null = null;
+  if (moduleCss !== null) {
+    const hash = createHash("sha256").update(moduleCss).digest("hex").slice(0, 8);
+    moduleCssAsset = `_june/modules.${hash}.css`;
+    frozen.document.moduleStyles = `/${moduleCssAsset}`;
+  }
+
+  // Same for the client islands bundle: build + content-hash it NOW (before the
+  // entry codegen + prerender) so both freeze the hashed /_june/client.<hash>.js
+  // and it can be served immutable. The asset is written here. The client may
+  // import .module.css too, so it gets the same module maps.
+  const assetsDir = join(outDir, "assets");
+  const clientEntry = findClientEntry(appDir);
+  let clientAsset: string | null = null;
+  if (clientEntry) {
+    clientAsset = await bundleClientToFile(clientEntry, appRoot, assetsDir, cssModuleMaps);
+    frozen.document.clientScript = `/${clientAsset}`;
+  }
+
+  // Declared resources become two things: a build-time plan (→ platform bindings
+  // the adapter emits) and a runtime provider wired into the generated entry.
+  // A resource-less app imports no config and emits no bindings, so its output
+  // is byte-identical to before — the parity guarantee holds.
+  const resourcesCfg = fullConfig.resources;
+  const hasResources = !!(resourcesCfg?.db || resourcesCfg?.kv || resourcesCfg?.blob);
 
   // ---- generated entry -----------------------------------------------------
-  const imports: string[] = [`import { createWorker } from "@junejs/server/worker";`];
+  // Routes are namespace-imported and adapted with routeFromModule, so the
+  // multi-export page shape (default view + named loader/json/md) and the legacy
+  // route({}) default export both work.
+  const imports: string[] = [
+    `import { createWorker } from "@junejs/server/worker";`,
+    `import { routeFromModule } from "@junejs/core/route";`,
+  ];
   const statics: string[] = [];
   const dynamics: string[] = [];
   const layoutIds = new Map<string, string>();
@@ -237,12 +337,24 @@ export async function juneBuild(
     }
     return id;
   };
+  const loadingIds = new Map<string, string>();
+  const loadingId = (file: string) => {
+    let id = loadingIds.get(file);
+    if (!id) {
+      id = `Ld${loadingIds.size}`;
+      loadingIds.set(file, id);
+      imports.push(`import ${id} from ${JSON.stringify(importPath(genDir, file))};`);
+    }
+    return id;
+  };
   const chains: string[] = [];
+  const loadings: string[] = [];
   routes.forEach((r, i) => {
-    imports.push(`import r${i} from ${JSON.stringify(importPath(genDir, r.file))};`);
-    if (r.dynamic) dynamics.push(`    { pattern: ${JSON.stringify(r.path)}, def: r${i} },`);
-    else statics.push(`    ${JSON.stringify(r.path)}: r${i},`);
+    imports.push(`import * as r${i} from ${JSON.stringify(importPath(genDir, r.file))};`);
+    if (r.dynamic) dynamics.push(`    { pattern: ${JSON.stringify(r.path)}, def: routeFromModule(r${i}) },`);
+    else statics.push(`    ${JSON.stringify(r.path)}: routeFromModule(r${i}),`);
     chains.push(`    ${JSON.stringify(r.path)}: [${r.layouts.map(layoutId).join(", ")}],`);
+    if (r.loading) loadings.push(`    ${JSON.stringify(r.path)}: ${loadingId(r.loading)},`);
   });
 
   const builtExtraFile = findExtraFile(appDir);
@@ -250,10 +362,33 @@ export async function juneBuild(
     imports.push(`import extra from ${JSON.stringify(importPath(genDir, builtExtraFile))};`);
   }
 
+  // The Link header is frozen here from the same builder the pipeline uses, so
+  // the static and dynamic surfaces advertise identically. The adapter wraps the
+  // portable pipeline for its target (workers() → withAssets).
+  const linkHeader = buildLinkHeader(frozen.agent);
+  const adapterEntry = adapter.entry({ linkHeader });
+
+  // Resources (when declared) are bound from the worker's env (env.DB → D1) by
+  // an env-aware provider. We bake a pure FLAGS descriptor — never importing the
+  // user's config, which would drag the host-only sqlite()/dev server into the
+  // workerd bundle. Only emitted when something is declared, so resource-less
+  // bundles stay byte-identical (and host code never enters the graph).
+  const resourceFlags = {
+    db: !!resourcesCfg?.db,
+    kv: !!resourcesCfg?.kv,
+    blob: !!resourcesCfg?.blob,
+  };
+  if (hasResources) {
+    imports.push(`import { bindWorkerResources } from "@junejs/server/resources";`);
+  }
+  const resourcesField = hasResources
+    ? `\n  resources: bindWorkerResources(${JSON.stringify(resourceFlags)}),`
+    : "";
   const entry = `// AUTO-GENERATED by \`june build\` — do not edit. Regenerate: june build .
+${adapterEntry.imports.join("\n")}
 ${imports.join("\n")}
 
-export default createWorker({
+const pipeline = createWorker({
   routes: {
 ${statics.join("\n")}
   },
@@ -262,11 +397,16 @@ ${dynamics.join("\n")}
   ],
   layoutChains: {
 ${chains.join("\n")}
+  },
+  loadings: {
+${loadings.join("\n")}
   },
   document: ${JSON.stringify(frozen.document, null, 2).replace(/\n/g, "\n  ")},
   agent: ${JSON.stringify(frozen.agent)},
-  earlyHints: ${JSON.stringify(frozen.earlyHints)},${builtExtraFile ? "\n  extra," : ""}
+  earlyHints: ${JSON.stringify(frozen.earlyHints)},${builtExtraFile ? "\n  extra," : ""}${resourcesField}
 });
+
+${adapterEntry.wrap("pipeline")}
 `;
   const entryFile = join(genDir, "worker-entry.tsx");
   await writeFile(entryFile, entry);
@@ -277,6 +417,7 @@ ${chains.join("\n")}
     input: entryFile,
     cwd: appRoot,
     platform: "browser", // workerd's surface is web-standard; no node:* in the graph
+    plugins: [rolldownCssModulesPlugin(cssModuleMaps)], // .module.css → scoped class map
     external: (id: string) => {
       // Binary assets stay external — wrangler's CompiledWasm/Data rules own them.
       if (/\.(wasm|ttf|otf|woff2?|png|jpe?g|avif|webp)$/.test(id)) return true;
@@ -286,8 +427,9 @@ ${chains.join("\n")}
       return list.some((e) => id === e || id.startsWith(`${e}/`));
     },
     resolve: {
-      // Conditions BAKED at build (workerd has no runtime conditions, reminder #3).
-      conditionNames: ["workerd", "edge", "import", "default"],
+      // Conditions BAKED at build (the target has no runtime conditions, reminder
+      // #3). Adapter-owned: workers → workerd, vercel → edge-light.
+      conditionNames: adapter.conditions,
     },
   });
   const result = await bundle.write({ dir: outDir, format: "esm", entryFileNames: "worker.js" });
@@ -301,20 +443,29 @@ ${chains.join("\n")}
   // Same render path as the bundle (createWorker over the frozen manifest), so
   // what ships is what the parity test verified.
   const prerendered: string[] = [];
+  // Prerender imports route modules in-process, so the runtime CSS-Modules
+  // interceptor must be active for any route that imports a .module.css.
+  await registerCssModules(cssModuleMaps);
   const manifest = await buildManifest(appRoot);
+  if (cssAsset) manifest.document.styles = `/${cssAsset}`; // prerendered HTML links the hashed sheet
+  if (clientAsset) manifest.document.clientScript = `/${clientAsset}`;
+  if (moduleCssAsset) manifest.document.moduleStyles = `/${moduleCssAsset}`;
   const worker = createWorker(manifest);
-  const assetsDir = join(outDir, "assets");
   let hasAssets = false;
 
   for (const r of routes.filter((x) => !x.dynamic)) {
     const def = manifest.routes[r.path];
     if (!def || !def.prerender) continue;
     const stem = r.path === "/" ? "index" : r.path.slice(1);
-    const targets: Array<[string, string]> = [[r.path, `${stem}.html`]];
-    if (r.path !== "/") {
-      targets.push([`${r.path}.md`, `${stem}.md`]);
-      if (typeof def.json === "function") targets.push([`${r.path}.json`, `${stem}.json`]);
-    }
+    // The homepage's projection requests are `/.md` / `/.json` (negotiate strips
+    // the ext back to `/`); withAssets serves them for `Accept: text/markdown`.
+    const mdReq = r.path === "/" ? "/.md" : `${r.path}.md`;
+    const jsonReq = r.path === "/" ? "/.json" : `${r.path}.json`;
+    const targets: Array<[string, string]> = [
+      [r.path, `${stem}.html`],
+      [mdReq, `${stem}.md`],
+    ];
+    if (typeof def.json === "function") targets.push([jsonReq, `${stem}.json`]);
     for (const [reqPath, file] of targets) {
       const res = await worker.fetch(new Request(`https://prerender.june${reqPath}`));
       if (!res.ok) throw new Error(`prerender ${reqPath} → ${res.status}`);
@@ -326,43 +477,42 @@ ${chains.join("\n")}
     hasAssets = true;
   }
 
-  // ---- client islands bundle: app/_client.* → assets/client.js -------------
-  // Served at /client.js by the assets binding; the frozen document (freezeConfig)
-  // already points <script src> at it. No entry → no bundle, page ships zero JS.
-  const clientEntry = findClientEntry(appDir);
-  if (clientEntry) {
-    await bundleClientToFile(clientEntry, appRoot, assetsDir);
+  // ---- client islands bundle: built + content-hashed earlier (assets/_june/
+  //      client.<hash>.js, frozen into the document). No entry → page ships zero JS.
+  if (clientAsset) hasAssets = true;
+
+  // ---- global stylesheet: app/global.css → assets/global.css ---------------
+  // Served at /global.css; the frozen document already <link>s it. Compiled
+  // (Tailwind) or passed through (plain CSS). No file → no asset.
+  if (cssOut !== null && cssAsset) {
+    const dest = join(assetsDir, cssAsset);
+    await mkdir(dirname(dest), { recursive: true }); // cssAsset includes the _june/ subdir
+    await writeFile(dest, cssOut);
+    hasAssets = true;
+  }
+
+  // ---- collected CSS Modules: app/**/*.module.css → assets/_june/modules.<hash>.css
+  if (moduleCss !== null && moduleCssAsset) {
+    const dest = join(assetsDir, moduleCssAsset);
+    await mkdir(dirname(dest), { recursive: true });
+    await writeFile(dest, moduleCss);
     hasAssets = true;
   }
 
-  // ---- wrangler config (only when the app doesn't manage its own) ----------
-  if (!existsSync(join(appRoot, "wrangler.toml")) && !existsSync(join(appRoot, "wrangler.jsonc"))) {
-    const pkgPath = join(appRoot, "package.json");
-    const pkg = existsSync(pkgPath)
-      ? (JSON.parse(await Bun.file(pkgPath).text()) as { name?: string })
-      : {};
-    const deployCfg = (await loadJuneConfig(appRoot)).deploy;
-    await writeFile(
-      join(outDir, "wrangler.jsonc"),
-      JSON.stringify(
-        {
-          name:
-            deployCfg?.name ??
-            (pkg.name ?? basename(appRoot)).replace(/[^a-z0-9-]/gi, "-").toLowerCase(),
-          main: "./worker.js",
-          compatibility_date: "2025-01-01",
-          compatibility_flags: ["nodejs_compat"],
-          ...(hasAssets ? { assets: { directory: "./assets" } } : {}),
-          // config deploy.domain → a Workers custom domain; without it the
-          // generated file regenerating on every build would silently drop a
-          // hand-attached domain.
-          ...(deployCfg?.domain
-            ? { routes: [{ pattern: deployCfg.domain, custom_domain: true }] }
-            : {}),
-        },
-        null,
-        2,
-      ) + "\n",
+  // ---- deploy structure (adapter-owned: wrangler.jsonc for workers) --------
+  const pkgPath = join(appRoot, "package.json");
+  const pkgName = existsSync(pkgPath)
+    ? (JSON.parse(await Bun.file(pkgPath).text()) as { name?: string }).name
+    : undefined;
+  const defaultName = (pkgName ?? basename(appRoot)).replace(/[^a-z0-9-]/gi, "-").toLowerCase();
+  // A declared `db` → a D1 binding named DB (the name bindWorkerResources reads).
+  const plan: ResourcePlan = resourcesCfg?.db
+    ? { db: { binding: "DB", databaseName: `${defaultName}-db` } }
+    : {};
+  await adapter.emit({ appRoot, outDir, hasAssets, linkHeader, config: fullConfig, plan, defaultName });
+  if (plan.db) {
+    console.log(
+      `  ↳ d1 binding "${plan.db.binding}" emitted — set database_id in wrangler.jsonc (wrangler d1 create ${plan.db.databaseName})`,
     );
   }
 

package/src/client-bundle.ts

@@ -18,13 +18,16 @@
 // Host-coupled (node:fs + Rolldown), so it lives in @junejs/server, never the pure
 // contract layer.
 
+import { createHash } from "node:crypto";
 import { existsSync } from "node:fs";
-import { mkdir } from "node:fs/promises";
-import { join } from "node:path";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+import { rolldownCssModulesPlugin, type ModuleMaps } from "./css-modules";
 
 // The URL the document loads + the asset path the bundle is written to. Single
 // source of truth so build (freeze) and dev (live) agree.
-export const CLIENT_SCRIPT_URL = "/client.js";
+export const CLIENT_SCRIPT_URL = "/_june/client.js";
 const CLIENT_BASENAME = "_client";
 const CLIENT_EXTS = [".tsx", ".ts", ".jsx", ".js"];
 
@@ -39,7 +42,7 @@ export function findClientEntry(appDir: string): string | undefined {
 
 type BundleMode = "development" | "production";
 
-async function bundleClient(entryFile: string, cwd: string, mode: BundleMode) {
+async function bundleClient(entryFile: string, cwd: string, mode: BundleMode, maps: ModuleMaps = {}) {
   const { rolldown } = await import("rolldown");
   const bundle = await rolldown({
     input: entryFile,
@@ -47,6 +50,7 @@ async function bundleClient(entryFile: string, cwd: string, mode: BundleMode) {
     // The client graph is plain web — browser conditions, and React's dev/prod
     // branch resolved at build (no `process` in the browser to read it at runtime).
     platform: "browser",
+    plugins: [rolldownCssModulesPlugin(maps)], // islands may import .module.css
     transform: { define: { "process.env.NODE_ENV": JSON.stringify(mode) } },
     resolve: { conditionNames: ["browser", "import", "default"] },
   });
@@ -54,18 +58,27 @@ async function bundleClient(entryFile: string, cwd: string, mode: BundleMode) {
 }
 
 // Build the client entry to a single `client.js` string (dev serves this live).
-export async function bundleClientToString(entryFile: string, cwd: string): Promise<string> {
-  const bundle = await bundleClient(entryFile, cwd, "development");
+export async function bundleClientToString(entryFile: string, cwd: string, maps: ModuleMaps = {}): Promise<string> {
+  const bundle = await bundleClient(entryFile, cwd, "development", maps);
   const { output } = await bundle.generate({ format: "esm", entryFileNames: "client.js" });
   await bundle.close();
   const entry = output.find((o) => o.type === "chunk" && o.isEntry);
   return entry && entry.type === "chunk" ? entry.code : "";
 }
 
-// Build the client entry to `<destDir>/client.js` (build freezes it as an asset).
-export async function bundleClientToFile(entryFile: string, cwd: string, destDir: string): Promise<void> {
-  const bundle = await bundleClient(entryFile, cwd, "production");
-  await mkdir(destDir, { recursive: true });
-  await bundle.write({ dir: destDir, format: "esm", entryFileNames: "client.js" });
+// Build the client entry, content-hash it, and write `<destDir>/_june/client.<hash>.js`
+// (immutable-cacheable, like the hashed CSS). Returns the asset filename
+// (`_june/client.<hash>.js`) so the build can freeze its URL into the document.
+export async function bundleClientToFile(entryFile: string, cwd: string, destDir: string, maps: ModuleMaps = {}): Promise<string> {
+  const bundle = await bundleClient(entryFile, cwd, "production", maps);
+  const { output } = await bundle.generate({ format: "esm", entryFileNames: "client.js" });
   await bundle.close();
+  const entry = output.find((o) => o.type === "chunk" && o.isEntry);
+  const code = entry && entry.type === "chunk" ? entry.code : "";
+  const hash = createHash("sha256").update(code).digest("hex").slice(0, 8);
+  const fileName = `_june/client.${hash}.js`;
+  const dest = join(destDir, fileName);
+  await mkdir(dirname(dest), { recursive: true });
+  await writeFile(dest, code);
+  return fileName;
 }

package/src/css-modules-ambient.d.ts

@@ -0,0 +1,9 @@
+// Ambient types for CSS Modules: `import styles from "./X.module.css"` resolves
+// to a map of local class name → scoped name. June ships this so app code (and
+// these tests/fixtures) typecheck; the create-june template references an
+// equivalent june-env.d.ts. (No top-level import/export → this is a GLOBAL
+// declaration, so the ambient module applies everywhere.)
+declare module "*.module.css" {
+  const classes: Record<string, string>;
+  export default classes;
+}

package/src/css-modules-loader.d.mts

@@ -0,0 +1,7 @@
+// Types for the Node ESM CSS-Modules loader (a runtime hook, .mjs).
+export function initialize(data?: { maps?: Record<string, Record<string, string>> }): void;
+export function load(
+  url: string,
+  context: unknown,
+  next: (url: string, context: unknown) => unknown,
+): Promise<{ format: string; source: string; shortCircuit: boolean } | unknown>;

package/src/css-modules-loader.mjs

@@ -0,0 +1,20 @@
+// Node ESM loader for CSS Modules (dev). `module.register` runs this in its own
+// context, so it must be a plain, self-contained .mjs — it does NOT transform;
+// it just looks up the precomputed class map (handed in via init data) and
+// returns it as a JS module. The maps come from css-modules.ts's single glob
+// pass, so the served CSS and these maps agree by construction.
+import { fileURLToPath } from "node:url";
+
+let MAPS = {};
+
+export function initialize(data) {
+  MAPS = (data && data.maps) || {};
+}
+
+export async function load(url, context, next) {
+  if (url.endsWith(".module.css")) {
+    const map = MAPS[fileURLToPath(url)] || {};
+    return { format: "module", source: "export default " + JSON.stringify(map) + ";", shortCircuit: true };
+  }
+  return next(url, context);
+}