@junejs/server 0.0.28 → 0.0.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junejs/server",
-  "version": "0.0.28",
+  "version": "0.0.31",
   "description": "June host adapters + dev server. Host-coupled; depends on the pure @junejs/core contract layer.",
   "type": "module",
   "license": "MIT",
@@ -30,20 +30,24 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@junejs/core": "0.0.28",
+    "@junejs/core": "0.0.32",
     "@junejs/db": "0.0.28",
+    "lightningcss": "^1.27.0",
     "marked": "^18.0.5",
-    "rolldown": "^1.1.0",
-    "lightningcss": "^1.27.0"
+    "rolldown": "^1.1.0"
   },
   "peerDependencies": {
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
+    "react-server-dom-webpack": "19.2.7",
     "pg": "^8.0.0",
     "mysql2": "^3.0.0",
     "@libsql/client": "^0.14.0 || ^0.15.0 || ^0.16.0 || ^0.17.0"
   },
   "peerDependenciesMeta": {
+    "react-server-dom-webpack": {
+      "optional": true
+    },
     "pg": {
       "optional": true
     },
@@ -62,6 +66,7 @@
     "@libsql/client": "^0.17.3",
     "@types/pg": "^8.20.0",
     "mysql2": "^3.22.5",
-    "pg": "^8.21.0"
+    "pg": "^8.21.0",
+    "react-server-dom-webpack": "19.2.7"
   }
 }

package/src/app.ts

@@ -14,7 +14,12 @@ import { pathToFileURL } from "node:url";
 import type { ComponentType } from "react";
 
 import { routeFromModule } from "@junejs/core/route";
-import { resolveAgent, resolveSpeculationRules, type JuneConfig } from "@junejs/core/config";
+import {
+  resolveAgent,
+  resolveClientRouter,
+  resolveSpeculationRules,
+  type JuneConfig,
+} from "@junejs/core/config";
 import type { DocumentConfig } from "@junejs/core/document";
 import { runWithTrace, type RequestTrace } from "@junejs/core/instrumentation";
 
@@ -22,8 +27,14 @@ import { findMiddlewareFile, isResourceFile, listRoutes, matchRouteTree, resolve
 import { createPipeline, type ExtraHandler, type LayoutComponent, type Pipeline, type Resolved, type ResourceHandler } from "./pipeline";
 import { resolveBoundary } from "./segment";
 import { memoizeResources } from "./resources";
-import { findClientEntry, bundleClientToString, CLIENT_SCRIPT_URL } from "./client-bundle";
-import { findGlobalCss, processCssCached, STYLES_URL } from "./css";
+import {
+  findClientEntry,
+  bundleClientSplit,
+  CLIENT_SCRIPT_URL,
+  type ClientChunks,
+} from "./client-bundle";
+import { generateIslandRegistry } from "./island-registry";
+import { findGlobalCss, globalCssUsesTailwind, processCssCached, STYLES_URL } from "./css";
 import { buildModuleCss, registerCssModules, MODULE_STYLES_URL, type ModuleMaps } from "./css-modules";
 
 export type CreateAppOptions = {
@@ -107,7 +118,9 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
     speculationRules: resolveSpeculationRules(speculation ?? undefined),
     speculationDelivery: speculation ? speculation.delivery ?? "inline" : "inline",
     viewTransitions: config.viewTransitions ?? true,
-    clientRouter: config.clientRouter ?? false,
+    // Default the baseline reset OFF when the app uses Tailwind (its Preflight is the reset).
+    cssReset: config.cssReset ?? !globalCssUsesTailwind(appDir),
+    clientRouter: resolveClientRouter(config.clientRouter),
     clientScript: clientEntry ? CLIENT_SCRIPT_URL : null,
     styles: cssEntry ? STYLES_URL : null,
   };
@@ -117,13 +130,17 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
   let moduleCssPromise: Promise<{ maps: ModuleMaps; css: string | null }> | undefined;
   const getModuleCss = () => (moduleCssPromise ??= buildModuleCss(appDir, dirname(appDir)));
 
-  let clientBundle: Promise<string> | undefined;
-  const serveClient = (): Promise<string> =>
-    // cwd = the app ROOT (appDir's parent) so rolldown resolves node_modules
-    // from the project, exactly like the build does. Islands may import .module.css.
-    (clientBundle ??= getModuleCss().then(({ maps }) =>
-      bundleClientToString(clientEntry!, dirname(appDir), maps),
-    ));
+  // Split build: one chunk per island + a shared React chunk, all keyed by file
+  // name. The entry is "client.js"; island chunks load on demand. cwd = the app
+  // ROOT so rolldown resolves node_modules from the project, like the build does.
+  let clientBundle: Promise<ClientChunks> | undefined;
+  const serveClient = (): Promise<ClientChunks> =>
+    (clientBundle ??= getModuleCss().then(({ maps }) => {
+      // Regenerate app/_islands.gen.ts (the auto lazy registry) right before
+      // bundling, so a freshly added island() module is wired without a restart.
+      generateIslandRegistry(appDir);
+      return bundleClientSplit(clientEntry!, dirname(appDir), "development", maps);
+    }));
 
   const routePaths = () => listRoutes(appDir, { pageConvention: true });
 
@@ -226,15 +243,27 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
             new Response(css ?? "", { headers: { "content-type": "text/css; charset=utf-8" } }),
         );
       }
-      // Dev serves the islands runtime itself (build ships it as a static
-      // asset); bundled on first hit, memoized after.
-      if (clientEntry && new URL(request.url).pathname === CLIENT_SCRIPT_URL) {
-        return serveClient().then(
-          (code) =>
-            new Response(code, {
-              headers: { "content-type": "text/javascript; charset=utf-8" },
-            }),
-          (err: unknown) => {
+      // Dev serves the islands runtime itself (build ships it as static assets);
+      // bundled on first hit, memoized after. Split build → many chunks under
+      // /_june/: the entry is /_june/client.js, islands are /_june/<name>.js,
+      // loaded on demand by the lazy runtime.
+      {
+        const pathname = new URL(request.url).pathname;
+        if (clientEntry && pathname.startsWith("/_june/") && pathname.endsWith(".js")) {
+          const file = pathname.slice("/_june/".length);
+          return serveClient().then(
+            (chunks) => {
+              const code = chunks.get(file);
+              if (code === undefined)
+                return new Response(`unknown client chunk: ${file}\n`, {
+                  status: 404,
+                  headers: { "content-type": "text/plain; charset=utf-8" },
+                });
+              return new Response(code, {
+                headers: { "content-type": "text/javascript; charset=utf-8" },
+              });
+            },
+            (err: unknown) => {
             // A rejected bundle must answer, not hang the request (Bun.serve
             // times the handler out) — and must not be memoized, or the error
             // outlives its cause.
@@ -244,8 +273,9 @@ export function createApp({ appDir: appDirInput, config = {} }: CreateAppOptions
               status: 500,
               headers: { "content-type": "text/plain; charset=utf-8" },
             });
-          },
-        );
+            },
+          );
+        }
       }
       return runWithTrace(newTrace(), async () => (await getPipeline()).fetch(request));
     },

package/src/build.ts

@@ -24,7 +24,7 @@ import { basename, dirname, join, relative, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 
 import { loadJuneConfig } from "./config-loader";
-import { resolveAgent, resolveSpeculationRules } from "@junejs/core/config";
+import { resolveAgent, resolveClientRouter, resolveSpeculationRules } from "@junejs/core/config";
 import { buildLinkHeader } from "@junejs/core/discovery";
 import { routeFromModule, type BrandedRoute } from "@junejs/core/route";
 import { workers, type JuneAdapter, type ResourcePlan } from "./adapter";
@@ -35,7 +35,9 @@ import { findMiddlewareFile } from "./router";
 import { resolveBoundary } from "./segment";
 import type { ExtraHandler, LayoutComponent, LoadingComponent, ResourceHandler } from "./pipeline";
 import { findClientEntry, bundleClientToFile, CLIENT_SCRIPT_URL } from "./client-bundle";
-import { cssTargets, findGlobalCss, minifyCss, processCss, STYLES_URL } from "./css";
+import { generateIslandRegistry } from "./island-registry";
+import { buildRsc, findRscRoutes } from "./rsc-build";
+import { cssTargets, findGlobalCss, globalCssUsesTailwind, minifyCss, processCss, STYLES_URL } from "./css";
 import { buildModuleCss, rolldownCssModulesPlugin, registerCssModules } from "./css-modules";
 
 export type BuildResult = {
@@ -62,6 +64,12 @@ const ROUTE_EXTS = [".tsx", ".jsx", ".ts", ".js"];
 
 const isRouteGroup = (name: string) => /^\(.+\)$/.test(name);
 
+// Bun built-ins (`bun`, `bun:sqlite`, …) exist only at the Bun runtime and must never enter the
+// workerd graph. Marking them external keeps rolldown from constant-folding the `const x = "bun";
+// import(x)` runtime guard (in @junejs/core's cache.ts) and warning UNRESOLVED_IMPORT. Exported so
+// the build keeps externalizing them — see test/build-externals.test.ts.
+export const isBunSpecifier = (id: string): boolean => id === "bun" || id.startsWith("bun:");
+
 function segmentFile(dir: string, base: string): string | undefined {
   return ROUTE_EXTS.map((e) => join(dir, `${base}${e}`)).find(existsSync);
 }
@@ -142,7 +150,9 @@ export async function freezeConfig(appRoot: string): Promise<{
       speculationRules: resolveSpeculationRules(cfg.speculation ?? undefined),
       speculationDelivery: "inline",
       viewTransitions: cfg.viewTransitions ?? true,
-      clientRouter: cfg.clientRouter ?? false,
+      // Default the baseline reset OFF when the app uses Tailwind (its Preflight is the reset).
+      cssReset: cfg.cssReset ?? !globalCssUsesTailwind(join(appRoot, "app")),
+      clientRouter: resolveClientRouter(cfg.clientRouter),
       clientScript: hasClient ? CLIENT_SCRIPT_URL : null,
       styles: hasCss ? STYLES_URL : null,
     },
@@ -337,10 +347,19 @@ export async function juneBuild(
   const clientEntry = findClientEntry(appDir);
   let clientAsset: string | null = null;
   if (clientEntry) {
+    // Regenerate the auto lazy island registry before bundling (same as dev).
+    generateIslandRegistry(appDir);
     clientAsset = await bundleClientToFile(clientEntry, appRoot, assetsDir, cssModuleMaps);
     frozen.document.clientScript = `/${clientAsset}`;
   }
 
+  // Opt-in PER-ROUTE RSC build (page.rsc.tsx routes): emit the server + SSR-worker
+  // graphs under <outDir>/rsc/. Gated on RSC routes existing, so apps without any
+  // are byte-identical to before. Coexists with the SSR pipeline via a dispatcher.
+  if (findRscRoutes(appDir).length > 0) {
+    await buildRsc(appRoot, outDir, frozen.document);
+  }
+
   // 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
@@ -516,10 +535,8 @@ ${adapterEntry.wrap("pipeline")}
     transform: { define: { "process.env.NODE_ENV": JSON.stringify("production") } },
     plugins: [rolldownCssModulesPlugin(cssModuleMaps)], // .module.css → scoped class map
     external: (id: string) => {
-      // Bun built-ins (bun, bun:sqlite, …) exist only at Bun runtime, never in the workerd graph.
-      // Declaring them external silences rolldown's UNRESOLVED_IMPORT warning (it constant-folds the
-      // `const x = "bun"; import(x)` guard and tries to resolve "bun" before falling back to external).
-      if (id === "bun" || id.startsWith("bun:")) return true;
+      // Bun built-ins exist only at Bun runtime, never in the workerd graph (see isBunSpecifier).
+      if (isBunSpecifier(id)) return true;
       // 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;
       // config build.external: packages wrangler must bundle itself (its own

package/src/client-bundle.ts

@@ -18,7 +18,6 @@
 // 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, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
@@ -57,6 +56,33 @@ async function bundleClient(entryFile: string, cwd: string, mode: BundleMode, ma
   return bundle;
 }
 
+// PoC: split build. With a lazy registry (`{ name: () => import("./Island") }`)
+// the entry's dynamic imports make rolldown emit ONE chunk per island plus a
+// shared chunk for React — so a page downloads only the islands it actually
+// renders, not the whole app's union. Returns every chunk keyed by file name
+// (the entry is "client.js"); the dev server serves each under /_june/<name>.
+export type ClientChunks = Map<string, string>;
+
+export async function bundleClientSplit(
+  entryFile: string,
+  cwd: string,
+  mode: BundleMode,
+  maps: ModuleMaps = {},
+): Promise<ClientChunks> {
+  const bundle = await bundleClient(entryFile, cwd, mode, maps);
+  const { output } = await bundle.generate({
+    format: "esm",
+    entryFileNames: "client.js",
+    // [name] (no hash) in dev so the relative `import("./Counter.js")` baked into
+    // the entry resolves to a path the dev server can serve by name.
+    chunkFileNames: "[name].js",
+  });
+  await bundle.close();
+  const chunks: ClientChunks = new Map();
+  for (const o of output) if (o.type === "chunk") chunks.set(o.fileName, o.code);
+  return chunks;
+}
+
 // Build the client entry to a single `client.js` string (dev serves this live).
 export async function bundleClientToString(entryFile: string, cwd: string, maps: ModuleMaps = {}): Promise<string> {
   const bundle = await bundleClient(entryFile, cwd, "development", maps);
@@ -66,19 +92,39 @@ export async function bundleClientToString(entryFile: string, cwd: string, maps:
   return entry && entry.type === "chunk" ? entry.code : "";
 }
 
-// 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.
+// Build the client entry and write EVERY emitted chunk/asset under
+// `<destDir>/_june/`, each content-hashed by rolldown (immutable-cacheable). With
+// a lazy registry (`{ name: () => import("./Island") }`) rolldown code-splits one
+// chunk per island + a shared React chunk, and the entry's relative `import()`s
+// already point at the hashed siblings — so they must ALL ship, not just the
+// entry (writing only the entry leaves those imports 404ing in production).
+// Returns the ENTRY asset filename (`_june/client.<hash>.js`) for 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" });
+  // Hash entry + split chunks; all under _june/ so the entry's relative imports
+  // (`./Counter-<hash>.js`) resolve there when served from /_june/client.<hash>.js.
+  const { output } = await bundle.generate({
+    format: "esm",
+    // hex hashes keep the asset names in the historical `client.<8hex>.js` shape
+    // (lowercase hex) the document + parity tests expect, now that there can be
+    // sibling chunks too.
+    hashCharacters: "hex",
+    entryFileNames: "_june/client.[hash].js",
+    chunkFileNames: "_june/[name]-[hash].js",
+    assetFileNames: "_june/[name]-[hash][extname]",
+  });
   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;
+
+  let entryFileName = "";
+  for (const o of output) {
+    const dest = join(destDir, o.fileName);
+    await mkdir(dirname(dest), { recursive: true });
+    if (o.type === "chunk") {
+      await writeFile(dest, o.code);
+      if (o.isEntry) entryFileName = o.fileName;
+    } else {
+      await writeFile(dest, o.source);
+    }
+  }
+  return entryFileName;
 }

package/src/content.ts

@@ -79,7 +79,10 @@ function loadEntry(file: string, slug: string, locale?: string): ContentEntry {
 }
 
 const isMd = (f: string) => f.endsWith(".md") || f.endsWith(".mdx");
-const slugOf = (f: string) => f.replace(/\.(md|mdx)$/, "");
+// Strip the extension, then collapse a directory index file to the directory itself, so it owns the
+// folder's URL (Next.js / GitBook / Fumadocs convention): `a/b/index.md` → `a/b`, `a/b/README.md` →
+// `a/b`, and a root `index`/`README` → "". A folder with an index becomes a page (not a buried child).
+const slugOf = (f: string) => f.replace(/\.(md|mdx)$/, "").replace(/(^|\/)(index|README)$/i, "");
 const byDate = (a: ContentEntry, b: ContentEntry) =>
   String(b.data.date ?? "").localeCompare(String(a.data.date ?? "")) ||
   a.slug.localeCompare(b.slug);
@@ -104,25 +107,44 @@ function isLocaleDir(name: string, known?: readonly string[]): boolean {
   return known ? known.includes(name) : LOCALE_DIR.test(name);
 }
 
+// Recursively collect markdown under `root`; slug = the path relative to `root`, POSIX, no extension
+// (`guides/install.md` → `guides/install`) so routes and the sidebar can nest. `skipTopLocales` skips
+// locale buckets at the TOP level only (scanned separately) — so a top-level `ja-JP/` is a locale, but
+// a nested `guides/` (or `guides/ja-JP/`) is plain content.
+function collectMd(
+  root: string,
+  knownLocales: readonly string[] | undefined,
+  skipTopLocales: boolean,
+  sub = "",
+): { file: string; slug: string }[] {
+  const out: { file: string; slug: string }[] = [];
+  for (const ent of readdirSync(join(root, sub), { withFileTypes: true })) {
+    const rel = sub ? `${sub}/${ent.name}` : ent.name;
+    if (ent.isDirectory()) {
+      if (skipTopLocales && sub === "" && isLocaleDir(ent.name, knownLocales)) continue;
+      out.push(...collectMd(root, knownLocales, skipTopLocales, rel));
+    } else if (isMd(ent.name)) {
+      out.push({ file: join(root, rel), slug: slugOf(rel) });
+    }
+  }
+  return out;
+}
+
 export function scanCollection(dir: string, knownLocales?: readonly string[]): ScannedCollection {
-  const def: ContentEntry[] = [];
+  // Default-locale entries: every .md under `dir` except inside top-level locale buckets. Flat files
+  // keep flat slugs (zero migration); subdirs become slug paths.
+  const def = collectMd(dir, knownLocales, true)
+    .map(({ file, slug }) => loadEntry(file, slug))
+    .sort(byDate);
   const byLocale: Record<string, ContentEntry[]> = {};
   for (const ent of readdirSync(dir, { withFileTypes: true })) {
-    if (ent.isDirectory()) {
-      // Only a configured locale (or, without a list, a BCP-47-shaped name) is a
-      // locale bucket — a stray content/<col>/images/ is NOT a phantom "images".
-      if (!isLocaleDir(ent.name, knownLocales)) continue;
+    if (ent.isDirectory() && isLocaleDir(ent.name, knownLocales)) {
       const locale = ent.name;
-      const sub = join(dir, locale);
-      byLocale[locale] = readdirSync(sub)
-        .filter(isMd)
-        .map((f) => loadEntry(join(sub, f), slugOf(f), locale))
+      byLocale[locale] = collectMd(join(dir, locale), knownLocales, false)
+        .map(({ file, slug }) => loadEntry(file, slug, locale))
         .sort(byDate);
-    } else if (isMd(ent.name)) {
-      def.push(loadEntry(join(dir, ent.name), slugOf(ent.name)));
     }
   }
-  def.sort(byDate);
   return { default: def, byLocale };
 }
 
@@ -158,8 +180,9 @@ export function entry(
   locale?: string,
   opts?: { fallback?: boolean },
 ): ContentEntry | null {
-  // Guard the slug — it comes from the URL.
-  if (!/^[A-Za-z0-9._-]+$/.test(slug)) return null;
+  // Guard the slug — it comes from the URL. Allow "/" so nested content (`guides/install`) resolves,
+  // but reject path traversal and absolute/empty segments so the slug can't escape `dir`.
+  if (!/^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/.test(slug) || slug.includes("..")) return null;
   if (!locale) return probe(dir, slug);
   const variant = probe(join(dir, locale), slug, locale);
   if (variant) return variant;
@@ -207,6 +230,9 @@ export function generateContentModule(
     body += `export const ${CONST}: ContentEntry[] = ${JSON.stringify(def.map(strip), null, 2)};\n`;
     if (Object.keys(byLocale).length === 0) {
       body += `export const ${finder} = (slug: string): ContentEntry | null => ${CONST}.find((p) => p.slug === slug) ?? null;\n`;
+      // Always export the locale lister (a no-op for single-locale collections) so consumers can
+      // import `${d.name}` unconditionally — adding/removing locales never changes the module's shape.
+      body += `export const ${d.name} = (_locale?: string): ContentEntry[] => ${CONST};\n`;
     } else {
       anyLocale = true;
       const map: Record<string, Record<string, unknown>> = {};

package/src/css.ts

@@ -4,15 +4,16 @@
 // (served immutable). Only the asset HREF diverges dev↔built, never the rendered
 // structure — so dev/built parity (the agent surface) holds.
 //
-// Floor: plain CSS, zero deps. Blessed: if global.css opts into Tailwind
-// (`@import "tailwindcss"`), June compiles it via the app's own Tailwind v4
-// (resolved from the app, not bundled into June) — Tailwind auto-detects the
-// content it scans. CSS never touches the agent projections (.md/.json/mcp).
+// Floor: plain CSS, zero deps — Lightning CSS (the SAME Rust engine Tailwind v4 uses) handles
+// nesting/prefix/minify. Blessed: if global.css opts into Tailwind (`@import "tailwindcss"`), June
+// compiles it via the app's own Tailwind v4 ENGINE DIRECTLY — @tailwindcss/node + the @tailwindcss/oxide
+// Rust scanner (the first-party Vite-plugin path, not PostCSS) — resolved from the app, napi-portable
+// across Bun and Node. CSS never touches the agent projections (.md/.json/mcp).
 
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { createRequire } from "node:module";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 
 import type { Targets } from "lightningcss"; // type-only — never enters the graph
@@ -31,6 +32,18 @@ export function findGlobalCss(appDir: string): string | null {
 
 const usesTailwind = (css: string) => /@import\s+["']tailwindcss["']|@tailwind\b/.test(css);
 
+// True when app/global.css opts into Tailwind. Sync (build-time, tiny file) so the document config —
+// built synchronously in dev (app.ts) and the build (build.ts) — can default `cssReset` off when
+// Tailwind is present: its Preflight IS the reset, so June need not add its own baseline reset.
+export function globalCssUsesTailwind(appDir: string): boolean {
+  const p = join(appDir, GLOBAL_CSS);
+  try {
+    return existsSync(p) && usesTailwind(readFileSync(p, "utf8"));
+  } catch {
+    return false;
+  }
+}
+
 // Resolve a tool from the APP's node_modules (Tailwind/postcss are the app's
 // deps, not June's). Returns null when absent.
 function resolveFromApp(specifier: string, appDir: string): string | null {
@@ -67,23 +80,40 @@ export async function cssTargets(appDir: string): Promise<Targets> {
   return targets;
 }
 
+// Minimal type surface of the bits of Tailwind v4's engine we drive directly.
+type TwSource = { base: string; pattern: string; negated: boolean };
+type TwCompiler = { build(candidates: string[]): string; sources: TwSource[]; features: number };
+type TwNode = {
+  compile(css: string, opts: { base: string; onDependency: (p: string) => void }): Promise<TwCompiler>;
+  optimize(css: string, opts: { minify: boolean }): { code: string };
+  Features: { Utilities: number };
+};
+type TwOxide = { Scanner: new (o: { sources: TwSource[] }) => { scan(): string[] } };
+
+// Compile Tailwind v4 via its programmatic engine — @tailwindcss/node (compile + Lightning CSS optimize)
+// + @tailwindcss/oxide (the Rust content Scanner) — the SAME direct path the first-party Vite plugin
+// uses, NOT PostCSS. No postcss dependency or extra parse pass; the Oxide scanner (Rust) finds class
+// candidates and the compiler emits only those (tree-shaken). Engine resolved from the APP (its dep,
+// not June's); napi works identically on Bun and Node. Returns null when Tailwind isn't installed.
 async function compileTailwind(
   css: string,
   file: string,
   appDir: string,
   minify: boolean,
 ): Promise<string | null> {
-  const postcssPath = resolveFromApp("postcss", appDir);
-  const tailwindPath = resolveFromApp("@tailwindcss/postcss", appDir);
-  if (!postcssPath || !tailwindPath) return null;
-  const postcss = ((await import(postcssPath)) as { default: (p: unknown[]) => { process(css: string, opts: { from: string }): Promise<{ css: string }> } }).default;
-  const tailwind = ((await import(tailwindPath)) as { default: (opts?: unknown) => unknown }).default;
-  // Tailwind v4 only emits the classes the project actually uses (content
-  // detection = tree-shaking). For build we ALSO minify via its Lightning CSS
-  // optimizer; dev stays unminified for readability.
-  const plugin = minify ? tailwind({ optimize: { minify: true } }) : tailwind();
-  const result = await postcss([plugin]).process(css, { from: file });
-  return result.css;
+  const nodePath = resolveFromApp("@tailwindcss/node", appDir);
+  const oxidePath = resolveFromApp("@tailwindcss/oxide", appDir);
+  if (!nodePath || !oxidePath) return null;
+  const { compile, optimize, Features } = (await import(nodePath)) as TwNode;
+  const { Scanner } = (await import(oxidePath)) as TwOxide;
+  const base = dirname(file); // the CSS's dir — resolves @import / @source / auto-detection
+  const compiler = await compile(css, { base, onDependency: () => {} });
+  // Scan the project (app root) plus whatever the compiler declares; Oxide skips node_modules/.gitignore.
+  const sources: TwSource[] = [{ base: dirname(appDir), pattern: "**/*", negated: false }, ...compiler.sources];
+  const candidates = compiler.features & Features.Utilities ? new Scanner({ sources }).scan() : [];
+  const out = compiler.build(candidates);
+  // Lightning CSS optimize for build (minify + prefix/lower); dev stays readable.
+  return minify ? optimize(out, { minify: true }).code : out;
 }
 
 // Dev-only memo. The dev server re-fetches /global.css on EVERY navigation, but
@@ -138,7 +168,7 @@ export async function processCss(
     });
     if (compiled !== null) return compiled; // Tailwind already minified when asked
     console.warn(
-      "[june] global.css uses Tailwind but @tailwindcss/postcss isn't installed — serving raw CSS.",
+      "[june] global.css uses Tailwind but @tailwindcss/node + @tailwindcss/oxide aren't installed — serving raw CSS.",
     );
   }
   // Plain CSS (or the Tailwind fallback): minify + autoprefix/lower for the app's

package/src/dev-reload.ts

@@ -38,10 +38,13 @@ const RELOAD_JS = `// june dev live-reload: reconnect-after-drop → reload; "cs
     es.addEventListener("open", () => {
       if (dropped) {
         // push-HMR: morph the freshly-restarted page in place (state survives);
-        // hard-reload only if there's no morph hook or it can't apply.
+        // hard-reload only if there's no morph hook or it can't apply. On a
+        // successful morph also swap the stylesheet: a .tsx edit can change the
+        // class set, so the Tailwind-compiled /_june/global.css must refresh too
+        // (cache-busted) — otherwise new utility classes render unstyled.
         const hot = window.__juneLiveReload;
         (hot ? hot() : Promise.resolve(false)).then(
-          (ok) => { if (!ok) location.reload(); },
+          (ok) => { if (ok) swapCss(); else location.reload(); },
           () => location.reload(),
         );
       }

package/src/island-registry.ts

@@ -0,0 +1,95 @@
+// Auto-generate the island registry by scanning "use client" island() modules,
+// so the author never hand-writes the `{ name: () => import("./Island") }` map.
+//
+// Scans app/** for modules that (a) start with the "use client" directive AND
+// (b) use `island()` from @junejs/core/islands, and writes app/_islands.gen.ts:
+//
+//   export const ISLAND_LOADERS = {
+//     "Counter": () => import("./poc/Counter"),
+//     "Tabs":    () => import("./poc/Tabs"),
+//   };
+//
+// The KEY is the module's EXPORT name; importing the module runs its `island()`
+// call, which self-registers the component under its runtime name. Those must
+// agree — the marker the server stamps (the island's name) is what the client
+// looks up. So the convention is: an island's name == its export name (the React
+// default — `export const Counter = island(function Counter() {…})` satisfies it
+// for free; otherwise pass `island(C, { name })`).
+//
+// Over-inclusion is harmless: a loader whose name no marker references is never
+// called, so no chunk for an unused export is ever fetched.
+//
+// Host-coupled (node:fs), so it lives in @junejs/server, never the contract layer.
+import { readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+
+export const ISLAND_REGISTRY_FILE = "_islands.gen.ts";
+
+// Shared with rsc-manifest.ts (the RSC client-reference codegen).
+export function walk(dir: string): string[] {
+  return readdirSync(dir).flatMap((name) => {
+    const p = join(dir, name);
+    return statSync(p).isDirectory() ? walk(p) : [p];
+  });
+}
+
+// True iff the first real statement (skipping blanks + line comments) is the
+// directive — the same rule the bundler uses to treat a module as client.
+export function firstStatementIsDirective(src: string, directive: string): boolean {
+  for (const line of src.split("\n")) {
+    const t = line.trim();
+    if (!t || t.startsWith("//")) continue;
+    return t.startsWith(`"${directive}"`) || t.startsWith(`'${directive}'`);
+  }
+  return false;
+}
+
+// The named exports of a module (skipping `export default` and `export type`).
+export function exportNames(src: string): string[] {
+  const names: string[] = [];
+  for (const line of src.split("\n")) {
+    const t = line.trim();
+    const decl = t.match(/^export\s+(?:async\s+)?(?:function|const|let|var|class)\s+([A-Za-z0-9_$]+)/);
+    if (decl) names.push(decl[1]!);
+    const named = t.match(/^export\s*\{([^}]*)\}/); // `export type { … }` won't match (the `type` breaks it)
+    if (named) {
+      for (const part of named[1]!.split(",")) {
+        const e = part.split(" as ").pop()?.trim();
+        if (e) names.push(e);
+      }
+    }
+  }
+  return names;
+}
+
+// Write app/_islands.gen.ts. Returns the number of island loaders emitted.
+export function generateIslandRegistry(appDir: string): number {
+  const mods = walk(appDir)
+    .filter((f) => /\.(tsx|ts|jsx)$/.test(f) && !f.endsWith(ISLAND_REGISTRY_FILE))
+    .map((f) => ({ f, src: readFileSync(f, "utf8") }))
+    .filter(
+      ({ src }) =>
+        firstStatementIsDirective(src, "use client") &&
+        /@junejs\/core\/islands/.test(src) &&
+        /\bisland\s*\(/.test(src),
+    );
+
+  const entries: string[] = [];
+  for (const { f, src } of mods) {
+    const rel = "./" + relative(appDir, f).replace(/\.(tsx|ts|jsx)$/, "");
+    for (const name of exportNames(src)) {
+      if (name === "default") continue; // islands are named exports
+      entries.push(`  ${JSON.stringify(name)}: () => import(${JSON.stringify(rel)}),`);
+    }
+  }
+
+  const body = entries.length ? entries.join("\n") + "\n" : "";
+  const out =
+    "// AUTO-GENERATED by June — do not edit. Lazy loaders for island() modules.\n" +
+    "// Maps each island name to a lazy chunk loader; hydrateIslandsLazy consumes it.\n" +
+    "export const ISLAND_LOADERS: Record<string, () => Promise<unknown>> = {\n" +
+    body +
+    "};\n";
+  writeFileSync(join(appDir, ISLAND_REGISTRY_FILE), out);
+  return entries.length;
+}

package/src/rsc-build.ts

@@ -0,0 +1,121 @@
+// RSC build orchestrator — PER-ROUTE, opt-in via the `page.rsc.tsx` convention.
+// A route with a page.rsc.tsx is rendered through RSC (server graph → Flight →
+// <Document> → HTML); every other route stays on the existing SSR/island pipeline.
+// The two coexist behind a path dispatcher (createRscDispatch), so the SSR path is
+// byte-unchanged when no RSC route exists.
+//
+// "use client" 分流 (the dual-semantics resolution): the SAME directive is read
+// per ROUTE MODE. In an RSC route's server graph the client-references plugin turns
+// "use client" into a true client reference (React-spec boundary); in an SSR/island
+// route it stays an island scan marker. The two render paths are separate bundles,
+// so one component file can serve both with no conflict.
+import { existsSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+
+import type { DocumentConfig } from "@junejs/core/document";
+
+import { bundleServerGraph, bundleSsrGraph } from "./rsc-bundle";
+import { generateRscManifests, RSC_CLIENT_MANIFEST_FILE } from "./rsc-manifest";
+import { walk } from "./island-registry";
+
+const RSC_ROUTES_FILE = "_rsc-routes.gen.tsx";
+const RSC_PAGE_RE = /(?:^|\/)page\.rsc\.(tsx|jsx)$/;
+
+export type RscRoute = { path: string; file: string };
+
+// Scan app/** for page.rsc.tsx files → the RSC routes. Path is the route dir
+// relative to app/ (route groups "(name)" stripped), "/" for the app root.
+export function findRscRoutes(appDir: string): RscRoute[] {
+  if (!existsSync(appDir)) return [];
+  return walk(appDir)
+    .filter((f) => RSC_PAGE_RE.test(f))
+    .map((file) => {
+      const dir = dirname(relative(appDir, file));
+      const segs = dir === "." ? [] : dir.split("/").filter((s) => !/^\(.*\)$/.test(s));
+      return { path: "/" + segs.join("/"), file };
+    })
+    .map((r) => ({ ...r, path: r.path === "/" ? "/" : r.path.replace(/\/$/, "") }))
+    .sort((a, b) => a.path.localeCompare(b.path)); // deterministic
+}
+
+function runtimeEntry(name: string): string {
+  return join(dirname(new URL(import.meta.url).pathname), "rsc-runtime", name);
+}
+
+export type RscBuildResult = { worker: string; server: string; paths: string[] } | null;
+
+// Build all RSC routes for `appRoot` into `<outDir>/rsc/`. Returns the emitted
+// files + the owned paths (for the dispatcher), or null if no RSC route exists.
+export async function buildRsc(
+  appRoot: string,
+  outDir: string,
+  docConfig: DocumentConfig,
+): Promise<RscBuildResult> {
+  const appDir = join(appRoot, "app");
+  const routes = findRscRoutes(appDir);
+  if (routes.length === 0) return null;
+
+  // 1. Client-reference manifests from the "use client" modules.
+  generateRscManifests(appDir);
+
+  // 2. The route map the server graph renders against (path → view default export).
+  let routesGen = "// AUTO-GENERATED by June — do not edit. RSC route map.\n";
+  routesGen += 'import type React from "react";\n';
+  routes.forEach((r, i) => {
+    const rel = "./" + relative(appDir, r.file).replace(/\.(tsx|jsx)$/, "");
+    routesGen += `import V${i} from ${JSON.stringify(rel)};\n`;
+  });
+  routesGen += 'export { CLIENT_MANIFEST as clientManifest } from "./_rsc-server.gen";\n';
+  routesGen += "export const ROUTES: Record<string, React.ComponentType> = {\n";
+  routes.forEach((r, i) => (routesGen += `  ${JSON.stringify(r.path)}: V${i},\n`));
+  routesGen += "};\n";
+  await writeFile(join(appDir, RSC_ROUTES_FILE), routesGen);
+
+  // 3. The doc-config module the worker imports (aliased june:rsc-config).
+  const configFile = join(appDir, "_rsc-config.gen.ts");
+  await writeFile(
+    configFile,
+    "// AUTO-GENERATED by June — do not edit. RSC document config.\n" +
+      `export const DOC_CONFIG = ${JSON.stringify(docConfig)} as const;\n`,
+  );
+
+  const dest = join(outDir, "rsc");
+  await mkdir(dest, { recursive: true });
+
+  // 4. Server graph: route views → Flight (react-server condition + the
+  //    client-references plugin auto-wires "use client" islands).
+  const serverCode = await bundleServerGraph(
+    runtimeEntry("flight-render-routes.tsx"),
+    appRoot,
+    { "june:rsc-routes": join(appDir, RSC_ROUTES_FILE) },
+    appDir,
+  );
+  await writeFile(join(dest, "server.js"), serverCode);
+
+  // 5. SSR worker: Flight → <Document> → HTML (normal React), per request path.
+  const workerCode = await bundleSsrGraph(runtimeEntry("rsc-worker.tsx"), appRoot, {
+    "june:rsc-client": join(appDir, RSC_CLIENT_MANIFEST_FILE),
+    "june:rsc-config": configFile,
+  });
+  await writeFile(join(dest, "worker.js"), workerCode);
+
+  return { worker: "rsc/worker.js", server: "rsc/server.js", paths: routes.map((r) => r.path) };
+}
+
+type Fetcher = (request: Request) => Promise<Response>;
+
+// The 分流: route RSC-owned paths to the RSC worker, everything else to the SSR
+// pipeline. Exact-path match (RSC routes are explicit). This is what lets the two
+// render models coexist behind one fetch handler.
+export function createRscDispatch(
+  ssrFetch: Fetcher,
+  rscFetch: Fetcher,
+  rscPaths: Iterable<string>,
+): Fetcher {
+  const owned = new Set(rscPaths);
+  return (request: Request) => {
+    const path = new URL(request.url).pathname;
+    return owned.has(path) ? rscFetch(request) : ssrFetch(request);
+  };
+}

package/src/rsc-bundle.ts

@@ -0,0 +1,78 @@
+// RSC build pipeline — the dual React graph, bundled for STANDARD targets
+// (Cloudflare Workers / Vercel edge), with NO dependency on June's native runtime.
+//
+// The whole trick is resolve CONDITIONS:
+//   - server graph: ["react-server", "workerd", …] → `react` and
+//     `react-server-dom-webpack/server` resolve to their server-graph + edge
+//     (no node:*) builds. This graph renders components to a Flight stream.
+//   - ssr graph:    ["workerd", …] (NO react-server) → normal `react` +
+//     `react-server-dom-webpack/client` + `react-dom/server.edge`. This graph
+//     consumes a Flight stream and renders it to HTML.
+//
+// Both bundles are worker-safe (the edge builds avoid node:*), so the worker /
+// serverless function runs them directly. rolldown does the resolution — same
+// engine the client bundle already uses.
+import type { Plugin } from "rolldown";
+
+import { rscClientReferencesPlugin } from "./rsc-manifest";
+
+export type RscGraph = "server" | "ssr";
+
+// edge-first conditions shared by both graphs; the server graph prepends
+// "react-server" so React resolves to the server build.
+const EDGE_CONDITIONS = ["workerd", "edge-light", "import", "default"];
+
+// Generic-entry virtuals the build resolves to real app modules (so one runtime
+// entry serves any app): "june:app" (the app root), "june:rsc-client" (the
+// generated consumer manifest), "june:rsc-config" (the document config).
+export type RscAliases = Record<string, string>;
+
+async function bundleGraph(
+  entryFile: string,
+  cwd: string,
+  graph: RscGraph,
+  aliases: RscAliases = {},
+  plugins: Plugin[] = [],
+): Promise<string> {
+  const { rolldown } = await import("rolldown");
+  const conditionNames = graph === "server" ? ["react-server", ...EDGE_CONDITIONS] : EDGE_CONDITIONS;
+  const bundle = await rolldown({
+    input: entryFile,
+    cwd,
+    platform: "neutral",
+    plugins,
+    transform: { define: { "process.env.NODE_ENV": JSON.stringify("production") } },
+    resolve: {
+      conditionNames,
+      ...(Object.keys(aliases).length ? { alias: aliases } : {}),
+    },
+  });
+  const { output } = await bundle.generate({ format: "esm" });
+  await bundle.close();
+  const entry = output.find((o) => o.type === "chunk" && o.isEntry);
+  return entry && entry.type === "chunk" ? entry.code : "";
+}
+
+// Bundle the server (react-server) graph that renders an app to Flight. When
+// `appDir` is given, the client-references plugin rewrites that app's "use client"
+// modules into client references automatically (no hand-written registration).
+export function bundleServerGraph(
+  entryFile: string,
+  cwd: string,
+  aliases?: RscAliases,
+  appDir?: string,
+): Promise<string> {
+  const plugins = appDir ? [rscClientReferencesPlugin(appDir)] : [];
+  return bundleGraph(entryFile, cwd, "server", aliases, plugins);
+}
+
+// Bundle the SSR (normal-react) graph that turns a Flight stream into HTML.
+export function bundleSsrGraph(entryFile: string, cwd: string, aliases?: RscAliases): Promise<string> {
+  return bundleGraph(entryFile, cwd, "ssr", aliases);
+}
+
+// True iff bundled code references node:* — the worker-safety invariant. The RSC
+// edge builds must never pull node:* (Cloudflare/Vercel edge would reject it).
+export function referencesNodeBuiltins(code: string): boolean {
+  return /from\s*["']node:|require\(\s*["']node:/.test(code);
+}

package/src/rsc-manifest.ts

@@ -0,0 +1,111 @@
+// Auto-generate the RSC client-reference wiring by scanning "use client" modules,
+// so an app NEVER hand-writes registerClientReference / __webpack_require__ / the
+// module maps. Two halves, both keyed by the SAME id (`<relPath>#<export>`):
+//
+//  1. SERVER graph (Flight render): a rolldown plugin replaces each "use client"
+//     module's body with registerClientReference proxies — so `<Counter/>` in a
+//     server component serializes as a client REFERENCE, not its impl.
+//  2. SSR / BROWSER graphs (Flight consume): generated _rsc-client.gen.ts wires
+//     __webpack_require__ → the real modules + the moduleMap, and _rsc-server.gen.ts
+//     holds the render-side manifest (the webpackMap renderToReadableStream needs).
+//
+// Host-coupled (node:fs + rolldown types). Reuses the same "use client" scan as
+// the island registry.
+import { writeFileSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import type { Plugin } from "rolldown";
+
+import { walk, firstStatementIsDirective, exportNames } from "./island-registry";
+
+export const RSC_SERVER_MANIFEST_FILE = "_rsc-server.gen.ts";
+export const RSC_CLIENT_MANIFEST_FILE = "_rsc-client.gen.ts";
+
+// Stable, per-export reference id shared by every graph: "<relPath no ext>#<name>".
+function refId(appDir: string, absPath: string, name: string): string {
+  const rel = relative(appDir, absPath).replace(/\.(tsx|ts|jsx)$/, "");
+  return `${rel}#${name}`;
+}
+
+type ClientModule = { rel: string; abs: string; names: string[] };
+
+function clientModules(appDir: string): ClientModule[] {
+  return walk(appDir)
+    .filter(
+      (f) =>
+        /\.(tsx|ts|jsx)$/.test(f) &&
+        !f.endsWith(RSC_SERVER_MANIFEST_FILE) &&
+        !f.endsWith(RSC_CLIENT_MANIFEST_FILE),
+    )
+    .map((abs) => ({ abs, src: readFileSync(abs, "utf8") }))
+    .filter(({ src }) => firstStatementIsDirective(src, "use client"))
+    .map(({ abs, src }) => ({
+      abs,
+      rel: "./" + relative(appDir, abs).replace(/\.(tsx|ts|jsx)$/, ""),
+      names: exportNames(src).filter((n) => n !== "default"),
+    }))
+    .filter((m) => m.names.length > 0)
+    .sort((a, b) => a.rel.localeCompare(b.rel)); // deterministic output
+}
+
+// SERVER-graph plugin: rewrite every "use client" module under appDir into
+// registerClientReference proxies. Pass it ONLY to the server (react-server)
+// bundle — the SSR/browser graphs load the real modules.
+export function rscClientReferencesPlugin(appDir: string): Plugin {
+  return {
+    name: "june:rsc-client-references",
+    transform(code, id) {
+      if (!id.startsWith(appDir)) return null;
+      if (!firstStatementIsDirective(code, "use client")) return null;
+      const names = exportNames(code).filter((n) => n !== "default");
+      let out = `import { registerClientReference } from "react-server-dom-webpack/server";\n`;
+      for (const name of names) {
+        const rid = refId(appDir, id, name);
+        out += `export const ${name} = registerClientReference({}, ${JSON.stringify(rid)}, ${JSON.stringify(name)});\n`;
+      }
+      return { code: out, map: null };
+    },
+  };
+}
+
+// Write both manifest files. Returns the number of client modules wired.
+export function generateRscManifests(appDir: string): number {
+  const mods = clientModules(appDir);
+
+  // Render-side manifest (flat by id) — the webpackMap for renderToReadableStream.
+  let server = "// AUTO-GENERATED by June — do not edit. RSC render manifest.\n";
+  server += "export const CLIENT_MANIFEST: Record<string, { id: string; chunks: string[]; name: string }> = {\n";
+  for (const m of mods) {
+    for (const name of m.names) {
+      const rid = `${m.rel.slice(2)}#${name}`; // strip leading "./" → matches refId()
+      server += `  ${JSON.stringify(rid)}: { id: ${JSON.stringify(rid)}, chunks: [], name: ${JSON.stringify(name)} },\n`;
+    }
+  }
+  server += "};\n";
+  writeFileSync(join(appDir, RSC_SERVER_MANIFEST_FILE), server);
+
+  // Consumer side (SSR + browser): real modules + moduleMap, installs the webpack
+  // shim. moduleMap is NESTED by export name (what client.edge resolves against).
+  let client = "// AUTO-GENERATED by June — do not edit. RSC consumer manifest.\n";
+  mods.forEach((m, i) => (client += `import * as m${i} from ${JSON.stringify(m.rel)};\n`));
+  client += "\nconst CLIENT_MODULES: Record<string, unknown> = {\n";
+  mods.forEach((m, i) => {
+    for (const name of m.names) client += `  ${JSON.stringify(`${m.rel.slice(2)}#${name}`)}: m${i},\n`;
+  });
+  client += "};\n";
+  client += "export const MODULE_MAP: Record<string, Record<string, { id: string; chunks: string[]; name: string }>> = {\n";
+  for (const m of mods) {
+    for (const name of m.names) {
+      const rid = `${m.rel.slice(2)}#${name}`;
+      client += `  ${JSON.stringify(rid)}: { ${JSON.stringify(name)}: { id: ${JSON.stringify(rid)}, chunks: [], name: ${JSON.stringify(name)} } },\n`;
+    }
+  }
+  client += "};\n\n";
+  client +=
+    "const g = globalThis as Record<string, unknown>;\n" +
+    "g.__webpack_require__ = (id: string) => CLIENT_MODULES[id];\n" +
+    "g.__webpack_chunk_load__ = () => Promise.resolve();\n" +
+    "export { CLIENT_MODULES };\n";
+  writeFileSync(join(appDir, RSC_CLIENT_MANIFEST_FILE), client);
+
+  return mods.length;
+}

package/src/rsc-runtime/flight-render-routes.tsx

@@ -0,0 +1,33 @@
+// Server-graph entry for PER-ROUTE RSC: render the matched route's view to Flight.
+// The route map (path → server-component view) + client manifest are generated and
+// injected as "june:rsc-routes". Worker-safe (server.edge via the react-server
+// condition).
+import { renderToReadableStream } from "react-server-dom-webpack/server";
+
+import { ROUTES, clientManifest } from "june:rsc-routes";
+
+async function streamToString(stream: ReadableStream<Uint8Array>): Promise<string> {
+  const reader = stream.getReader();
+  const dec = new TextDecoder();
+  let out = "";
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    out += dec.decode(value, { stream: true });
+  }
+  out += dec.decode();
+  return out;
+}
+
+// Render the view registered for `path` to a Flight payload, or null if no RSC
+// route owns that path (the dispatcher then leaves it to the SSR pipeline).
+export async function renderFlight(path: string): Promise<string | null> {
+  const View = ROUTES[path];
+  if (!View) return null;
+  return streamToString(renderToReadableStream(<View />, clientManifest ?? {}));
+}
+
+// The paths this RSC bundle owns — the dispatcher routes these here.
+export function rscPaths(): string[] {
+  return Object.keys(ROUTES);
+}

package/src/rsc-runtime/flight-render.tsx

@@ -0,0 +1,27 @@
+// Server-graph entry (bundled with the react-server condition): render the app to
+// a React Flight stream. Worker-safe — uses server.edge under the hood. The app
+// is injected as "june:app" by the build's alias.
+import { renderToReadableStream } from "react-server-dom-webpack/server";
+
+import { App, clientManifest } from "june:app";
+
+async function streamToString(stream: ReadableStream<Uint8Array>): Promise<string> {
+  const reader = stream.getReader();
+  const dec = new TextDecoder();
+  let out = "";
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    out += dec.decode(value, { stream: true });
+  }
+  out += dec.decode();
+  return out;
+}
+
+// Render the app to a Flight payload string. (A real server would stream the
+// ReadableStream straight to the response; the string form is for tests + the
+// SSR step.)
+export async function renderFlight(): Promise<string> {
+  const stream = renderToReadableStream(<App />, clientManifest ?? {});
+  return streamToString(stream);
+}

package/src/rsc-runtime/flight-to-html.tsx

@@ -0,0 +1,45 @@
+// SSR-graph entry (bundled WITHOUT the react-server condition → normal React):
+// consume a Flight stream and render it to HTML. Worker-safe — react-dom's edge
+// server build + the client.edge Flight reader, no node:*. This is the first-load
+// step: the worker turns Flight into the HTML the browser paints.
+import { use } from "react";
+import { createFromReadableStream } from "react-server-dom-webpack/client";
+import { renderToReadableStream } from "react-dom/server.edge";
+
+// The Flight payload deserializes to a thenable React tree; `use` unwraps it
+// inside the render so react-dom can stream it to HTML.
+function Root({ tree }: { tree: Promise<React.ReactNode> }): React.ReactNode {
+  return use(tree);
+}
+
+async function streamToString(stream: ReadableStream<Uint8Array>): Promise<string> {
+  const reader = stream.getReader();
+  const dec = new TextDecoder();
+  let out = "";
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    out += dec.decode(value, { stream: true });
+  }
+  out += dec.decode();
+  return out;
+}
+
+// Turn a Flight payload string into an HTML string. `moduleMap` resolves client
+// references to their real components so islands SSR too; an empty map is fine for
+// server-only trees (client.edge still requires the manifest object to exist).
+export async function flightToHtml(
+  flight: string,
+  moduleMap: Record<string, unknown> = {},
+): Promise<string> {
+  const flightStream = new Response(flight).body as ReadableStream<Uint8Array>;
+  const tree = createFromReadableStream(flightStream, {
+    serverConsumerManifest: { moduleMap, serverModuleMap: null, moduleLoading: null },
+  }) as unknown as Promise<React.ReactNode>;
+  const html = await renderToReadableStream(<Root tree={tree} />);
+  // Non-streaming: wait for the whole document.
+  if (typeof (html as { allReady?: Promise<void> }).allReady?.then === "function") {
+    await (html as unknown as { allReady: Promise<void> }).allReady;
+  }
+  return streamToString(html as unknown as ReadableStream<Uint8Array>);
+}

package/src/rsc-runtime/rsc-worker.tsx

@@ -0,0 +1,70 @@
+// The RSC worker entry (SSR graph, normal React) — the fetch handler that serves
+// an RSC app on a STANDARD target (Cloudflare Workers / Vercel edge), no native
+// runtime. Per request it chains the two graphs:
+//   1. the server-graph bundle (react-server) renders the app → Flight,
+//   2. this graph deserializes the Flight + resolves client references to real
+//      modules (the generated consumer manifest) → a React tree,
+//   3. wraps it in June's <Document> and streams HTML.
+//
+// The server bundle is a SEPARATE file (its own react-server React); it is loaded
+// at runtime via a computed URL so this (normal-React) bundle never re-bundles it.
+import { use } from "react";
+import { createFromReadableStream } from "react-server-dom-webpack/client";
+import { renderToReadableStream } from "react-dom/server.edge";
+import { Document } from "@junejs/core/document";
+
+// Generated per app, aliased at build time:
+import { MODULE_MAP } from "june:rsc-client"; // installs __webpack_require__ (side effect) + the moduleMap
+import { DOC_CONFIG } from "june:rsc-config"; // the frozen DocumentConfig
+
+type ServerBundle = { renderFlight: (path: string) => Promise<string | null> };
+
+function Root({ tree }: { tree: Promise<React.ReactNode> }): React.ReactNode {
+  return use(tree);
+}
+
+async function streamToString(stream: ReadableStream<Uint8Array>): Promise<string> {
+  const reader = stream.getReader();
+  const dec = new TextDecoder();
+  let out = "";
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    out += dec.decode(value, { stream: true });
+  }
+  out += dec.decode();
+  return out;
+}
+
+async function renderDocument(path: string): Promise<string | null> {
+  // Non-literal specifier → rolldown leaves it as a runtime import, so the
+  // react-server server bundle is loaded (not re-bundled) from beside this file.
+  const serverUrl = new URL("./server.js", import.meta.url).href;
+  const server = (await import(serverUrl)) as ServerBundle;
+  const flight = await server.renderFlight(path);
+  if (flight === null) return null; // no RSC route here
+
+  const flightStream = new Response(flight).body as ReadableStream<Uint8Array>;
+  const tree = createFromReadableStream(flightStream, {
+    serverConsumerManifest: { moduleMap: MODULE_MAP, serverModuleMap: null, moduleLoading: null },
+  }) as unknown as Promise<React.ReactNode>;
+
+  const html = await renderToReadableStream(
+    <Document config={DOC_CONFIG}>
+      <Root tree={tree} />
+    </Document>,
+  );
+  if (typeof (html as { allReady?: Promise<void> }).allReady?.then === "function") {
+    await (html as unknown as { allReady: Promise<void> }).allReady;
+  }
+  return "<!DOCTYPE html>" + (await streamToString(html as unknown as ReadableStream<Uint8Array>));
+}
+
+export default {
+  async fetch(request: Request): Promise<Response> {
+    const path = new URL(request.url).pathname;
+    const body = await renderDocument(path);
+    if (body === null) return new Response("Not Found", { status: 404 });
+    return new Response(body, { headers: { "content-type": "text/html; charset=utf-8" } });
+  },
+};

package/src/rsc-runtime/rsdw-shims.d.ts

@@ -0,0 +1,53 @@
+// Ambient declarations for react-server-dom-webpack (it ships no .d.ts) and the
+// "june:app" virtual the RSC runtime entries import (aliased at bundle time).
+// Minimal — only the surface the runtime entries use.
+declare module "react-server-dom-webpack/server" {
+  export function renderToReadableStream(
+    model: unknown,
+    webpackMap?: unknown,
+    options?: unknown,
+  ): ReadableStream<Uint8Array>;
+  export function registerClientReference(
+    proxy: object,
+    id: string,
+    exportName: string,
+  ): unknown;
+  // "use server" — register a server function so it serializes as a server
+  // reference and can be invoked from a decoded client request.
+  export function registerServerReference<F>(fn: F, id: string, exportName: string): F;
+  export function decodeReply(body: string | FormData, serverManifest?: unknown, options?: unknown): Promise<unknown[]>;
+}
+
+declare module "react-server-dom-webpack/client" {
+  export function createFromReadableStream(
+    stream: ReadableStream<Uint8Array>,
+    options?: unknown,
+  ): Promise<React.ReactNode> & React.ReactNode;
+  // "use server" client half — encode args for a server-function POST.
+  export function encodeReply(value: unknown): Promise<string | FormData>;
+}
+
+// The app under render, injected by the build (resolve.alias "june:app" → app).
+declare module "june:app" {
+  import type React from "react";
+  export const App: React.ComponentType;
+  export const clientManifest: Record<string, unknown> | undefined;
+}
+
+// The generated per-route map (resolve.alias "june:rsc-routes" → _rsc-routes.gen.tsx).
+declare module "june:rsc-routes" {
+  import type React from "react";
+  export const ROUTES: Record<string, React.ComponentType>;
+  export const clientManifest: Record<string, unknown> | undefined;
+}
+
+// The generated consumer manifest (resolve.alias "june:rsc-client" → app/_rsc-client.gen.ts).
+declare module "june:rsc-client" {
+  export const MODULE_MAP: Record<string, Record<string, { id: string; chunks: string[]; name: string }>>;
+}
+
+// The frozen document config (resolve.alias "june:rsc-config" → generated).
+declare module "june:rsc-config" {
+  import type { DocumentConfig } from "@junejs/core/document";
+  export const DOC_CONFIG: DocumentConfig;
+}