swift-rust 1.5.1 → 1.10.2

package/bin/dev-server.mjs

@@ -364,7 +364,303 @@ const externalizeDepsPlugin = {
   },
 };
 
+// ── Component-level "use client" islands ───────────────────────────────────
+// A `use client` *component* imported into a server-rendered page can't just be
+// SSR'd to static HTML — its useState/effects/handlers would never run. So when
+// the SSR bundle pulls in a client component, we wrap it: on the server it still
+// renders to HTML (good for SEO + no flash), but inside a marker element that
+// carries the component's source path, export name, and serialized props. A tiny
+// client runtime then hydrates each marker from a per-component browser bundle.
+//
+// Limitations (documented): props must be JSON-serializable; `children` and
+// function props don't cross the boundary, so islands should be self-contained
+// leaves (they manage their own children). Nested client components imported by
+// a client component are bundled into that island, not re-wrapped.
+
+const ISLAND_EXTS = [".tsx", ".ts", ".jsx", ".js", ".mjs"];
+
+// Resolve a relative / absolute / "@/"-aliased specifier to a real file path.
+function resolveIslandSpecifier(spec, importer) {
+  let base;
+  if (spec.startsWith("@/")) base = resolve(cwd, "src", spec.slice(2));
+  else if (spec.startsWith("/")) base = spec;
+  else if (spec.startsWith(".")) base = resolve(dirname(importer || cwd), spec);
+  else return null;
+  const candidates = [base, ...ISLAND_EXTS.map((e) => base + e), ...ISLAND_EXTS.map((e) => join(base, "index" + e))];
+  for (const c of candidates) {
+    try { if (statSync(c).isFile()) return c; } catch {}
+  }
+  return null;
+}
+
+// Extract export names from a module's source so we can re-export wrapped
+// versions. We only wrap Capitalized exports (React component convention) + the
+// default export; lowercase exports pass through untouched.
+function detectIslandExports(src) {
+  const named = new Set();
+  let hasDefault = false;
+  // strip block/line comments cheaply to avoid false matches
+  const code = src.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/[^\n]*/g, "$1");
+  if (/\bexport\s+default\b/.test(code)) hasDefault = true;
+  for (const m of code.matchAll(/\bexport\s+(?:async\s+)?(?:function|class|const|let|var)\s+([A-Za-z_$][\w$]*)/g)) {
+    named.add(m[1]);
+  }
+  for (const m of code.matchAll(/\bexport\s*\{([^}]*)\}/g)) {
+    for (const part of m[1].split(",")) {
+      const name = part.trim().split(/\s+as\s+/).pop()?.trim();
+      if (name && name !== "default") named.add(name);
+    }
+  }
+  return { hasDefault, named: [...named] };
+}
+
+// Build the source of an island wrapper module for a given client component
+// file. Temp sibling files hold verbatim copies of client components, so the
+// wrapper can import the *real* module under a distinct on-disk path (Bun
+// dedupes modules by resolved path, so a query-string alias would collapse the
+// real module into the wrapper). `temps` is per-build: a shared global list
+// let concurrent builds delete each other's temp files mid-build, which
+// surfaced as transient module-not-found errors on save.
+function islandWrapperSource(abs, temps) {
+  const src = readFileSync(abs, "utf8");
+  const { hasDefault, named } = detectIslandExports(src);
+  // Write the real component to a unique sibling so imports resolve identically.
+  const rawName = `.__sr_raw_${process.pid}_${Math.random().toString(36).slice(2)}__${basename(abs)}`;
+  const rawPath = join(dirname(abs), rawName);
+  writeFileSync(rawPath, src);
+  temps.push(rawPath);
+  const rawSpec = JSON.stringify(rawPath);
+  let out = `import { createElement as __h } from "react";
+import * as __real from ${rawSpec};
+const __src = ${JSON.stringify(abs)};
+function __ser(props){
+  var out = {};
+  for (var k in props){
+    if (k === "children") continue;
+    var v = props[k]; var t = typeof v;
+    if (v === null || t === "string" || t === "number" || t === "boolean" || (t === "object" && typeof v.$$typeof === "undefined")){
+      try { JSON.stringify(v); out[k] = v; } catch (e) {}
+    }
+  }
+  return JSON.stringify(out).replace(/</g, "\\\\u003c");
+}
+function __wrap(Comp, name){
+  if (typeof Comp !== "function") return Comp;
+  function SrIsland(props){
+    return __h("div", {
+      "data-sr-island": "",
+      "data-sr-island-src": __src,
+      "data-sr-island-export": name,
+      "data-sr-island-props": __ser(props),
+      style: { display: "contents" },
+    }, __h(Comp, props));
+  }
+  SrIsland.displayName = "Island(" + name + ")";
+  return SrIsland;
+}
+`;
+  if (hasDefault) out += `export default __wrap(__real.default, "default");\n`;
+  for (const n of named) {
+    if (/^[A-Z]/.test(n)) out += `export const ${n} = __wrap(__real[${JSON.stringify(n)}], ${JSON.stringify(n)});\n`;
+    else out += `export const ${n} = __real[${JSON.stringify(n)}];\n`;
+  }
+  return out;
+}
+
+// Which exported names of a 'use cache' module are *async functions* (the only
+// ones safe to wrap with cache(), since cache() always returns a Promise). We
+// pass everything else through untouched.
+function detectAsyncExports(src) {
+  const code = src.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/[^\n]*/g, "$1");
+  const asyncNamed = new Set();
+  const allNamed = new Set();
+  let defaultAsync = false;
+  let hasDefault = false;
+  if (/\bexport\s+default\b/.test(code)) {
+    hasDefault = true;
+    if (/\bexport\s+default\s+async\b/.test(code)) defaultAsync = true;
+  }
+  for (const m of code.matchAll(/\bexport\s+(async\s+)?function\s+([A-Za-z_$][\w$]*)/g)) {
+    allNamed.add(m[2]);
+    if (m[1]) asyncNamed.add(m[2]);
+  }
+  for (const m of code.matchAll(/\bexport\s+const\s+([A-Za-z_$][\w$]*)\s*=\s*(async\b)?/g)) {
+    allNamed.add(m[1]);
+    if (m[2]) asyncNamed.add(m[1]);
+  }
+  for (const m of code.matchAll(/\bexport\s*\{([^}]*)\}/g)) {
+    for (const part of m[1].split(",")) {
+      const name = part.trim().split(/\s+as\s+/).pop()?.trim();
+      if (name && name !== "default") allNamed.add(name);
+    }
+  }
+  return { asyncNamed: [...asyncNamed], allNamed: [...allNamed], defaultAsync, hasDefault };
+}
+
+// Source of a wrapper module that memoizes a 'use cache' module's async exports.
+function cacheWrapperSource(abs, temps) {
+  const src = readFileSync(abs, "utf8");
+  const { asyncNamed, allNamed, defaultAsync, hasDefault } = detectAsyncExports(src);
+  const rawName = `.__sr_raw_${process.pid}_${Math.random().toString(36).slice(2)}__${basename(abs)}`;
+  const rawPath = join(dirname(abs), rawName);
+  writeFileSync(rawPath, src);
+  temps.push(rawPath);
+  const tag = relative(cwd, abs);
+  let out = `import { cache as __cache } from "swift-rust/cache";
+import * as __real from ${JSON.stringify(rawPath)};
+const __opts = { tags: ${JSON.stringify([tag])} };
+`;
+  if (hasDefault) {
+    out += defaultAsync
+      ? `export default __cache(__real.default, __opts);\n`
+      : `export default __real.default;\n`;
+  }
+  for (const n of allNamed) {
+    out += asyncNamed.includes(n)
+      ? `export const ${n} = __cache(__real[${JSON.stringify(n)}], __opts);\n`
+      : `export const ${n} = __real[${JSON.stringify(n)}];\n`;
+  }
+  return out;
+}
+
+// Bun plugin: auto-memoize modules that declare a leading 'use cache' directive.
+// Built per-build so each build owns its temp-file list (see islandWrapperSource).
+function makeUseCachePlugin(temps) {
+  return {
+    name: "sr-use-cache",
+    setup(build) {
+      build.onResolve({ filter: /.*/ }, (args) => {
+        const p = args.path;
+        if (!(p.startsWith(".") || p.startsWith("/") || p.startsWith("@/"))) return undefined;
+        // Our own raw temp copy: resolve it explicitly into the file namespace.
+        // (Deferring to Bun's default resolver fails from a virtual namespace.)
+        if (/\.__sr_raw_/.test(p)) return { path: p, namespace: "file" };
+        if (args.importer && hasUseDirective(args.importer, "cache")) return undefined;
+        const abs = resolveIslandSpecifier(p, args.importer);
+        if (!abs || !hasUseDirective(abs, "cache")) return undefined;
+        return { path: abs, namespace: "sr-cache" };
+      });
+      build.onLoad({ filter: /.*/, namespace: "sr-cache" }, (args) => ({
+        contents: cacheWrapperSource(args.path, temps),
+        loader: "js",
+        resolveDir: dirname(args.path),
+      }));
+    },
+  };
+}
+
+// Bun plugin: wrap client components imported by *server* modules as islands.
+function makeClientIslandPlugin(temps) {
+  return {
+    name: "sr-client-islands",
+    setup(build) {
+      build.onResolve({ filter: /.*/ }, (args) => {
+        const p = args.path;
+        if (!(p.startsWith(".") || p.startsWith("/") || p.startsWith("@/"))) return undefined;
+        // Never wrap our own temp raw copies, and don't wrap when the importer is
+        // itself a client module — nested client components belong to that
+        // island's bundle, not a new boundary.
+        if (/\.__sr_raw_/.test(p)) return { path: p, namespace: "file" };
+        if (args.importer && hasUseDirective(args.importer, "client")) return undefined;
+        const abs = resolveIslandSpecifier(p, args.importer);
+        if (!abs || !hasUseDirective(abs, "client")) return undefined;
+        return { path: abs, namespace: "sr-island" };
+      });
+      build.onLoad({ filter: /.*/, namespace: "sr-island" }, (args) => ({
+        contents: islandWrapperSource(args.path, temps),
+        loader: "js",
+        resolveDir: dirname(args.path),
+      }));
+    },
+  };
+}
+
+// In-flight build dedup: concurrent requests for the same entry (every open tab
+// reloads at once on an HMR broadcast) await one build instead of racing.
+function withInflight(map, key, gen, factory) {
+  const cur = map.get(key);
+  if (cur && cur.gen === gen) return cur.promise;
+  const entry = { gen, promise: null };
+  entry.promise = (async () => {
+    try {
+      return await factory();
+    } finally {
+      if (map.get(key) === entry) map.delete(key);
+    }
+  })();
+  map.set(key, entry);
+  return entry.promise;
+}
+
+// Cache for per-component browser island bundles (src -> { gen, code }).
+// Each bundle is self-mounting: it imports the client component, finds every
+// marker on the page for this source, and hydrates it. React is bundled in, so a
+// single <script type="module"> per source needs no import map or shared runtime.
+const componentIslandCache = new Map();
+const componentIslandInflight = new Map();
+async function buildComponentIslandBundle(srcFile) {
+  if (typeof Bun === "undefined" || typeof Bun.build !== "function") {
+    throw new Error("client islands require the Bun runtime");
+  }
+  const cached = componentIslandCache.get(srcFile);
+  if (cached && cached.gen === buildGeneration) return cached.code;
+  return withInflight(componentIslandInflight, srcFile, buildGeneration, () =>
+    buildComponentIslandBundleNow(srcFile),
+  );
+}
+async function buildComponentIslandBundleNow(srcFile) {
+  const entryPath = join(
+    dirname(srcFile),
+    `.__sr_cisland_${process.pid}_${Date.now()}_${Math.random().toString(36).slice(2)}.js`,
+  );
+  const entry = `import { hydrateRoot, createRoot } from "react-dom/client";
+import { createElement } from "react";
+import * as __mod from ${JSON.stringify(srcFile)};
+var __src = ${JSON.stringify(srcFile)};
+var nodes = document.querySelectorAll('[data-sr-island]');
+for (var i = 0; i < nodes.length; i++) {
+  var el = nodes[i];
+  if (el.getAttribute("data-sr-island-src") !== __src || el.__srHydrated) continue;
+  el.__srHydrated = true;
+  var name = el.getAttribute("data-sr-island-export") || "default";
+  var Comp = __mod[name] || __mod.default;
+  if (typeof Comp !== "function") { console.warn("[swift-rust] island export missing:", name, __src); continue; }
+  var props = {};
+  try { props = JSON.parse(el.getAttribute("data-sr-island-props") || "{}"); } catch (e) {}
+  var element = createElement(Comp, props);
+  try { hydrateRoot(el, element); }
+  catch (err) { el.innerHTML = ""; createRoot(el).render(element); }
+}
+`;
+  writeFileSync(entryPath, entry);
+  try {
+    const result = await Bun.build({
+      entrypoints: [entryPath],
+      target: "browser",
+      minify: true,
+      define: { "process.env.NODE_ENV": '"production"' },
+    });
+    if (!result.success) throw new Error(result.logs.map((l) => l.message).join("\n"));
+    const code = await result.outputs[0].text();
+    componentIslandCache.set(srcFile, { gen: buildGeneration, code });
+    return code;
+  } finally {
+    try { unlinkSync(entryPath); } catch {}
+  }
+}
+
+// Collect unique client-island source files referenced in rendered HTML.
+function collectIslandSources(html) {
+  const srcs = new Set();
+  if (!html) return srcs;
+  for (const m of html.matchAll(/data-sr-island-src="([^"]+)"/g)) {
+    srcs.add(m[1].replace(/&amp;/g, "&").replace(/&quot;/g, '"'));
+  }
+  return srcs;
+}
+
 const ssrBundleCache = new Map(); // file -> { gen, mod }
+const ssrInflight = new Map(); // file -> { gen, promise }
 
 async function loadModuleFresh(filePath) {
   if (typeof Bun === "undefined" || typeof Bun.build !== "function") {
@@ -372,21 +668,32 @@ async function loadModuleFresh(filePath) {
   }
   const cached = ssrBundleCache.get(filePath);
   if (cached && cached.gen === buildGeneration) return cached.mod;
+  return withInflight(ssrInflight, filePath, buildGeneration, () =>
+    buildSsrModule(filePath, buildGeneration),
+  );
+}
 
-  const result = await Bun.build({
-    entrypoints: [filePath],
-    target: "bun",
-    plugins: [externalizeDepsPlugin],
-  });
+async function buildSsrModule(filePath, gen) {
+  const temps = [];
+  let result;
+  try {
+    result = await Bun.build({
+      entrypoints: [filePath],
+      target: "bun",
+      plugins: [makeUseCachePlugin(temps), makeClientIslandPlugin(temps), externalizeDepsPlugin],
+    });
+  } finally {
+    for (const t of temps) { try { unlinkSync(t); } catch {} }
+  }
   if (!result.success) {
     throw new Error(result.logs.map((l) => l.message).join("\n"));
   }
   const code = await result.outputs[0].text();
-  const tmp = join(dirname(filePath), `.__sr_ssr_${buildGeneration}_${Math.random().toString(36).slice(2)}.mjs`);
+  const tmp = join(dirname(filePath), `.__sr_ssr_${gen}_${Math.random().toString(36).slice(2)}.mjs`);
   writeFileSync(tmp, code);
   try {
     const mod = await import(pathToFileURL(tmp).href);
-    ssrBundleCache.set(filePath, { gen: buildGeneration, mod });
+    ssrBundleCache.set(filePath, { gen, mod });
     return mod;
   } finally {
     try { unlinkSync(tmp); } catch {}
@@ -424,11 +731,15 @@ async function compileRoute(urlPath) {
   }
 
   try {
-    await loadModule(route.file, { bust: true });
-    for (const layout of layouts) await loadModule(layout.file, { bust: true });
-    if (notFoundFile) await loadModule(notFoundFile, { bust: true });
-    if (errorFile) await loadModule(errorFile, { bust: true });
-    if (loadingFile) await loadModule(loadingFile, { bust: true });
+    // Generation-keyed bundles: a save bumps the generation (fresh build), an
+    // unchanged file is a cache hit. The old `?t=` bust-imports created new
+    // module instances on every request — they leaked (ESM registry entries
+    // are permanent) and, under Bun, didn't even pick up child-module edits.
+    await loadModuleFresh(route.file);
+    for (const layout of layouts) await loadModuleFresh(layout.file);
+    if (notFoundFile) await loadModuleFresh(notFoundFile);
+    if (errorFile) await loadModuleFresh(errorFile);
+    if (loadingFile) await loadModuleFresh(loadingFile);
   } catch (err) {
     compileTimings.set(urlPath, performance.now() - start);
     return { ok: false, reason: "compile_error", error: err, pageFile: route.file, layoutFile: layouts[0]?.file, params: route.params, segments };
@@ -452,14 +763,33 @@ function findAppGlobalsCss() {
   return null;
 }
 
+// A require() rooted at the user's project, so Node module resolution walks the
+// real node_modules tree (project → monorepo root → …) and finds packages
+// wherever the package manager hoisted them. Critical for production builds
+// (e.g. Vercel), where hard-coded ../../node_modules guesses miss the plugin
+// and Tailwind silently doesn't compile — shipping an unstyled site.
+let _projectRequire;
+function projectRequire() {
+  if (!_projectRequire) _projectRequire = createRequire(join(cwd, "package.json"));
+  return _projectRequire;
+}
+
 let postcssInstance = null;
 async function getPostcss() {
   if (postcssInstance !== null) return postcssInstance;
+  // 1) Resolve through the project's module graph.
+  try {
+    const entry = projectRequire().resolve("postcss");
+    const mod = await import(pathToFileURL(entry).href);
+    postcssInstance = { available: true, default: mod.default ?? mod, mod };
+    return postcssInstance;
+  } catch {}
+  // 2) Hard-coded fallbacks, then a bare import.
   try {
     const candidates = [
       join(cwd, "node_modules", "postcss"),
-      join(cwd, "node_modules", "postcss", "lib", "postcss.mjs"),
-      join(cwd, "node_modules", "postcss", "lib", "postcss.js"),
+      join(cwd, "..", "..", "node_modules", "postcss"),
+      join(cwd, "..", "..", "..", "node_modules", "postcss"),
     ];
     for (const candidate of candidates) {
       if (existsSync(candidate)) {
@@ -478,9 +808,19 @@ async function getPostcss() {
 }
 
 async function loadPostcssPluginByName(name) {
+  // 1) Node resolution from the project root — finds the plugin at any hoist level.
+  try {
+    const entryPath = projectRequire().resolve(name);
+    const mod = await import(pathToFileURL(entryPath).href);
+    const result = mod.default ?? mod;
+    logLine([` ${paint("dim", "css plugin loaded:")} ${paint("cyan", name)} ${paint("dim", "(resolved)")}`], 1);
+    return result;
+  } catch {}
+  // 2) Fallback: scan a few likely node_modules locations.
   const candidates = [
     join(cwd, "node_modules", name),
     join(cwd, "..", "..", "node_modules", name),
+    join(cwd, "..", "..", "..", "node_modules", name),
   ];
   for (const candidate of candidates) {
     const pkgJsonPath = join(candidate, "package.json");
@@ -503,7 +843,7 @@ async function loadPostcssPluginByName(name) {
       }
     }
   }
-  logLine([` ${paint("dim", "css plugin not found:")} ${paint("yellow", name)}`], 1);
+  logLine([` ${paint("dim", "css plugin not found:")} ${paint("yellow", name)} ${paint("dim", "— is it in dependencies?")}`], 1);
   return null;
 }
 
@@ -697,13 +1037,13 @@ async function resolveMetadata(layoutFiles, pageFile, params, segments) {
   const metas = [];
   for (const layoutFile of layoutFiles || []) {
     try {
-      const mod = await loadModule(layoutFile, { bust: true });
+      const mod = await loadModuleFresh(layoutFile);
       if (mod.metadata) metas.push(mod.metadata);
     } catch {}
   }
   if (pageFile) {
     try {
-      const mod = await loadModule(pageFile, { bust: true });
+      const mod = await loadModuleFresh(pageFile);
       if (mod.generateMetadata) {
         const m = await mod.generateMetadata({ params: params || {}, searchParams: {} });
         if (m) metas.push(m);
@@ -771,6 +1111,80 @@ export function isClientPage(file) {
   return false;
 }
 
+// True when a file's leading directive prologue contains `'use server'`.
+// (Component-level "use server" is NOT supported — swift-rust does classic SSR +
+// client islands, not React Server Components / Flight. The only legitimate home
+// for 'use server' is a route action.ts file, which is loaded by the router, not
+// imported into a page's render tree.)
+function hasServerDirective(file) {
+  try {
+    for (const raw of readFileSync(file, "utf8").split("\n")) {
+      const t = raw.trim();
+      if (!t || t.startsWith("//") || t.startsWith("/*") || t.startsWith("*")) continue;
+      if (/^["']use server["'];?$/.test(t)) return true;
+      if (/^["']use [a-z]+["'];?$/.test(t)) continue;
+      return false;
+    }
+  } catch {}
+  return false;
+}
+
+// Walk a page's transitive *relative* import graph looking for a module that
+// declares `'use server'`. Returns the offending file (or null). We only follow
+// ./ and ../ specifiers — that's where a developer's own components live, and it
+// keeps the scan cheap and free of node_modules false positives.
+const RELATIVE_EXTS = [".tsx", ".ts", ".jsx", ".js", ".mjs"];
+function findServerComponentInClientGraph(entryFile, seen = new Set()) {
+  const resolved = resolve(entryFile);
+  if (seen.has(resolved)) return null;
+  seen.add(resolved);
+  let src;
+  try {
+    src = readFileSync(resolved, "utf8");
+  } catch {
+    return null;
+  }
+  // The entry (the page) is allowed to be 'use client'; we only flag *imports*.
+  for (const m of src.matchAll(/\b(?:import|export)\b[^'"]*['"](\.[^'"]+)['"]/g)) {
+    const spec = m[1];
+    const base = resolve(dirname(resolved), spec);
+    let target = null;
+    const candidates = [base, ...RELATIVE_EXTS.map((e) => base + e), ...RELATIVE_EXTS.map((e) => join(base, "index" + e))];
+    for (const c of candidates) {
+      try {
+        if (statSync(c).isFile()) { target = c; break; }
+      } catch {}
+    }
+    if (!target) continue;
+    if (hasServerDirective(target)) return target;
+    const nested = findServerComponentInClientGraph(target, seen);
+    if (nested) return nested;
+  }
+  return null;
+}
+
+// Throw a clear, actionable error when a 'use client' page pulls a component
+// that declares 'use server'. Replaces the old silent no-op (the component used
+// to be imported but its directive ignored, so nothing ran and nothing warned).
+export function assertNoServerComponentInClientPage(pageFile) {
+  if (!isClientPage(pageFile)) return;
+  const offender = findServerComponentInClientGraph(pageFile);
+  if (offender) {
+    const rel = (f) => relative(cwd, f);
+    throw new Error(
+      `Unsupported: '${rel(offender)}' declares 'use server' but is imported into the ` +
+      `'use client' page '${rel(pageFile)}'.\n\n` +
+      `swift-rust uses classic SSR + client islands, not React Server Components, so a ` +
+      `'use server' component inside a client tree cannot run on the server — React forbids ` +
+      `importing a Server Component into a Client Component.\n\n` +
+      `Fix one of these:\n` +
+      `  • Remove the 'use server' directive — the component will render normally inside the client page.\n` +
+      `  • Move server-only work into a route loader (loader.ts) or action (action.ts) and pass the data down as props.\n` +
+      `  • Keep the page server-rendered (drop 'use client' on the page) and mark only the interactive leaf with 'use client'.`,
+    );
+  }
+}
+
 const VALID_RUNTIMES = new Set(["bun", "edge", "node", "worker"]);
 
 // Detect a `'use bun' | 'use edge' | 'use node'` directive among a file's
@@ -805,15 +1219,24 @@ export function hasUseDirective(file, name) {
   return false;
 }
 
+const islandBundleInflight = new Map();
 async function buildIslandBundle(pageFile) {
   if (typeof Bun === "undefined" || typeof Bun.build !== "function") {
     throw new Error("client islands require the Bun runtime");
   }
+  assertNoServerComponentInClientPage(pageFile);
   const cached = islandBundleCache.get(pageFile);
   if (cached && cached.gen === buildGeneration) return cached.code;
-
+  return withInflight(islandBundleInflight, pageFile, buildGeneration, () =>
+    buildIslandBundleNow(pageFile),
+  );
+}
+async function buildIslandBundleNow(pageFile) {
   // Temp hydration entry, written next to the page so module resolution works.
-  const entryPath = join(dirname(pageFile), `.__sr_island_${process.pid}_${Date.now()}.js`);
+  const entryPath = join(
+    dirname(pageFile),
+    `.__sr_island_${process.pid}_${Date.now()}_${Math.random().toString(36).slice(2)}.js`,
+  );
   const entry = `import { createRoot } from "react-dom/client";
 import { createElement } from "react";
 import Page from ${JSON.stringify(pageFile)};
@@ -1036,9 +1459,39 @@ async function readMergedConfig(chain, route) {
   // A route is "dynamic" (emitted as a request-time function) when it explicitly
   // opts into a runtime via a directive, config.ts/edge/worker, or config.dynamic.
   config.dynamic = Boolean(directive) || explicitRuntime || config.dynamic === true;
+
+  // `use static` (page directive) or config.static: a hard guarantee that the
+  // route is purely static — no request-time/dynamic behavior. We fail loudly on
+  // any conflict so the guarantee can't silently rot, then force the route static
+  // and tag it for aggressive caching. (The actual prerender happens in build;
+  // here we enforce + emit the cache contract.)
+  const wantsStatic =
+    (route?.file && hasUseDirective(route.file, "static")) ||
+    collectRouteFiles(chain, "config").some(({ file }) => hasUseDirective(file, "static")) ||
+    config.static === true;
+  if (wantsStatic) {
+    const reasons = [];
+    if (directive) reasons.push(`a 'use ${directive}' runtime directive (declares a request-time runtime)`);
+    else if (explicitRuntime) reasons.push("a runtime set by config.ts / edge.ts / worker.ts");
+    if (config.dynamic === true && !directive && !explicitRuntime) reasons.push("config.dynamic = true");
+    if (collectRouteFiles(chain, "action").length) reasons.push("an action.ts (mutations are dynamic)");
+    if (reasons.length) {
+      const rel = route?.file ? relative(cwd, route.file) : "(route)";
+      throw new Error(
+        `Route '${rel}' is marked 'use static' but is dynamic: it has ${reasons.join(", ")}.\n\n` +
+          `A 'use static' route is prerendered and CDN-cached, so it can't use request-time features. Fix one:\n` +
+          `  • Remove 'use static' if the route really needs to be dynamic.\n` +
+          `  • Drop the runtime directive / dynamic config / action.ts so the route can be fully static.\n` +
+          `  • For periodic refresh, keep 'use static' and add a revalidate.ts (ISR), which stays static + cached.`,
+      );
+    }
+    config.dynamic = false;
+    config.static = true;
+  }
   config.headers = {
     "x-swift-rust-runtime": runtime,
     ...(config.dynamic ? { "x-swift-rust-dynamic": "1" } : {}),
+    ...(config.static ? { "x-swift-rust-render": "static" } : {}),
     ...config.headers,
   };
   return config;
@@ -1416,6 +1869,11 @@ async function renderRoute(urlPath, req) {
     });
 
     const clientPage = isClientPage(route.file);
+    if (clientPage) {
+      // Loud failure (was a silent no-op): a 'use server' component imported into
+      // a 'use client' page can't run on the server in this SSR+islands model.
+      assertNoServerComponentInClientPage(route.file);
+    }
     let tree = React.createElement(Page, { params: paramsProxy });
     if (clientPage) {
       // Wrap in a hydration root so the client bundle can mount into it.
@@ -1493,7 +1951,7 @@ async function renderRoute(urlPath, req) {
     if (errorFile) {
       try {
         const React = await import("react");
-        const errorMod = await loadModule(errorFile, { bust: true });
+        const errorMod = await loadModuleFresh(errorFile);
         const ErrorBoundary = errorMod.default ?? errorMod.ErrorBoundary ?? errorMod.error;
         if (ErrorBoundary) {
           const html = await renderToStringCompat(React.createElement(ErrorBoundary, { error: err }));
@@ -1506,7 +1964,7 @@ async function renderRoute(urlPath, req) {
     if (recoveryFile) {
       try {
         const React = await import("react");
-        const mod = await loadModule(recoveryFile, { bust: true });
+        const mod = await loadModuleFresh(recoveryFile);
         const Recovery = mod.default ?? mod.ErrorRecovery;
         if (Recovery) {
           const html = await renderToStringCompat(
@@ -1523,7 +1981,7 @@ async function renderRoute(urlPath, req) {
     if (globalErrorFile) {
       try {
         const React = await import("react");
-        const mod = await loadModule(globalErrorFile, { bust: true });
+        const mod = await loadModuleFresh(globalErrorFile);
         const GlobalError = mod.default ?? mod.GlobalError;
         if (GlobalError) {
           const inner = await renderToStringCompat(
@@ -1611,14 +2069,14 @@ async function renderNotFound(segments) {
   try {
     const React = await import("react");
     const layouts = findLayoutsFor(segments || []);
-    const mod = await loadModule(notFoundFile, { bust: true });
+    const mod = await loadModuleFresh(notFoundFile);
     const NotFound = mod.default ?? mod.NotFound ?? mod.notFound;
     if (!NotFound) {
       return { status: 404, html: null, error: null, segments };
     }
     let tree = React.createElement(NotFound);
     for (let i = layouts.length - 1; i >= 0; i--) {
-      const layoutMod = await loadModule(layouts[i].file, { bust: true });
+      const layoutMod = await loadModuleFresh(layouts[i].file);
       const Layout = layoutMod.default ?? layoutMod.Layout ?? layoutMod.layout;
       if (Layout) tree = React.createElement(Layout, null, tree);
     }
@@ -1716,83 +2174,219 @@ function readNavigatorClient() {
   }
 }
 
-function shouldIgnoreFile(filename) {
-  if (!filename) return true;
-  const base = filename.split(sep).pop();
-  if (!base) return true;
-  if (base.startsWith(".")) return true;
+const WATCH_IGNORE_DIRS = new Set([
+  "node_modules",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+  "target",
+]);
+
+// Ignore anything inside a dep/build dir, any dot-prefixed path segment (which
+// also covers our own .__sr_* build temps and dirs like .git/.turbo/.next),
+// and editor scratch suffixes.
+function isIgnoredWatchPath(full) {
+  const rel = relative(cwd, full);
+  if (!rel || rel.startsWith("..")) return true;
+  const parts = rel.split(sep);
+  for (const p of parts) {
+    if (!p || p.startsWith(".")) return true;
+    if (WATCH_IGNORE_DIRS.has(p)) return true;
+  }
+  const base = parts[parts.length - 1];
   if (base.endsWith(".bak") || base.endsWith(".tmp") || base.endsWith("~")) return true;
-  if (base === "node_modules") return true;
   return false;
 }
 
+const SYNTAX_CHECK_LOADERS = { ".ts": "ts", ".tsx": "tsx", ".js": "js", ".jsx": "jsx", ".mjs": "js" };
+
+// Quick transpile of the changed sources before telling the browser to reload.
+// Editors save in stages (truncate+write, format-on-save), so the first FS
+// event often fires mid-write; compiling that state used to navigate every tab
+// into a dead 500 page. A failed check retries once after a beat (to skate
+// over partial writes); a persistent failure is a real syntax error.
+async function findSyntaxError(files) {
+  if (typeof Bun === "undefined" || typeof Bun.Transpiler !== "function") return null;
+  for (const file of files) {
+    const loader = SYNTAX_CHECK_LOADERS[extname(file)];
+    if (!loader) continue;
+    for (let attempt = 0; ; attempt++) {
+      let src;
+      try {
+        src = readFileSync(file, "utf8");
+      } catch {
+        break; // deleted — nothing to check
+      }
+      try {
+        new Bun.Transpiler({ loader }).transformSync(src);
+        break;
+      } catch (err) {
+        if (attempt >= 1) {
+          const msg = err?.message || String(err);
+          return `${relative(cwd, file)}: ${msg}`;
+        }
+        await new Promise((r) => setTimeout(r, 150));
+      }
+    }
+  }
+  return null;
+}
+
+function broadcastHmr(data) {
+  const payload = JSON.stringify({ event: "change", data });
+  for (const send of hmrClients) {
+    try {
+      send(payload);
+    } catch {}
+  }
+}
+
 function setupWatcher() {
   if (!existsSync(APP_DIR)) return;
   const watchers = new Map();
+  let recursiveMode = false;
 
-  const IGNORE_DIRS = new Set([
-    "node_modules",
-    "dist",
-    "build",
-    "out",
-    "coverage",
-    "target",
-    ".git",
-    ".vercel",
-    ".turbo",
-    ".swift-rust",
-    ".next",
-  ]);
+  // ── Debounced batch flush ──────────────────────────────────────────────────
+  // All events funnel into one pending set; a flush invalidates caches once,
+  // syntax-checks the batch, and broadcasts a single reload (or error).
+  const pendingFiles = new Set();
+  let pendingWildcard = false; // event with no usable filename → invalidate broadly
+  let flushTimer = null;
+  let flushing = false;
+  let lastFlushErrored = false;
+
+  function scheduleFlush() {
+    if (flushTimer) clearTimeout(flushTimer);
+    flushTimer = setTimeout(() => {
+      flushTimer = null;
+      void flush();
+    }, 80);
+  }
+
+  function noteChange(full) {
+    pendingFiles.add(full);
+    scheduleFlush();
+  }
+
+  function noteWildcard() {
+    pendingWildcard = true;
+    scheduleFlush();
+  }
+
+  async function flush() {
+    if (flushing) {
+      scheduleFlush();
+      return;
+    }
+    flushing = true;
+    try {
+      const files = [...pendingFiles];
+      pendingFiles.clear();
+      const wildcard = pendingWildcard;
+      pendingWildcard = false;
+      if (!files.length && !wildcard) return;
+
+      buildGeneration++;
+      for (const full of files) {
+        logEvent("change", full);
+        bustCache(full);
+        if (full.endsWith(`${sep}layout.tsx`) || full.endsWith(`${sep}layout.ts`)) {
+          fontsScannedFromLayout = false;
+          GOOGLE_FONT_FAMILIES.clear();
+        }
+      }
+      // Any source edit can introduce new utility classes (Tailwind scans the
+      // source tree), so re-run the CSS pipeline on every flush — not only when
+      // globals.css itself changes. mtime caching keeps subsequent requests hot.
+      globalsCssCache = { file: null, mtime: 0, css: "" };
+      if (wildcard) {
+        fontsScannedFromLayout = false;
+        GOOGLE_FONT_FAMILIES.clear();
+      }
+
+      const syntaxError = await findSyntaxError(files);
+      if (syntaxError) {
+        // Overlay on the live page instead of reloading into a dead 500 —
+        // page state survives, and the next clean save reloads normally.
+        lastFlushErrored = true;
+        logLine([` ${paint("red", "✗")} ${paint("red", syntaxError.split("\n")[0])}`]);
+        broadcastHmr({ type: "error", message: syntaxError });
+        return;
+      }
+      if (lastFlushErrored) {
+        lastFlushErrored = false;
+        broadcastHmr({ type: "ok" });
+      }
+      broadcastHmr({ type: "reload", file: relative(cwd, files[0] ?? cwd), at: Date.now() });
+      logHmr(files[0] ?? cwd);
+    } finally {
+      flushing = false;
+      if (pendingFiles.size || pendingWildcard) scheduleFlush();
+    }
+  }
+
+  function handleEvent(full) {
+    try {
+      if (statSync(full).isDirectory()) {
+        // New directory: in fallback mode start watching it. Files may have
+        // been created inside it before the watcher attached, so invalidate
+        // broadly instead of silently dropping the event (the old behavior —
+        // one dropped event meant stale renders until the server restarted).
+        if (!recursiveMode) walk(full);
+        noteWildcard();
+        return;
+      }
+    } catch {}
+    noteChange(full);
+  }
+
+  function onWatchEvent(baseDir) {
+    return (event, filename) => {
+      if (!filename) {
+        // macOS/FSEvents can coalesce events and drop the filename. Treat it
+        // as "something changed" rather than ignoring it.
+        noteWildcard();
+        return;
+      }
+      const full = join(baseDir, filename.toString());
+      if (isIgnoredWatchPath(full)) return;
+      handleEvent(full);
+    };
+  }
+
+  // Fallback: one watcher per directory (non-recursive platforms).
   function walk(dir) {
     if (watchers.has(dir)) return;
+    // A probe child path tells us whether the directory itself is ignored
+    // (cwd resolves to rel "x", which passes).
+    if (isIgnoredWatchPath(join(dir, "x"))) return;
     try {
       const entries = readdirSync(dir, { withFileTypes: true });
       for (const e of entries) {
-        if (e.isDirectory() && !e.name.startsWith(".") && !IGNORE_DIRS.has(e.name)) {
+        if (e.isDirectory() && !e.name.startsWith(".") && !WATCH_IGNORE_DIRS.has(e.name)) {
           walk(join(dir, e.name));
         }
       }
-      let debounce;
-      const w = fsWatch(dir, (event, filename) => {
-        if (shouldIgnoreFile(filename)) return;
-        const full = join(dir, filename.toString());
-        if (debounce) clearTimeout(debounce);
-        debounce = setTimeout(() => {
-          try {
-            const s = statSync(full);
-            if (s.isDirectory()) {
-              walk(full);
-              return;
-            }
-          } catch {}
-          logEvent("change", full);
-          buildGeneration++;
-          bustCache(full);
-          if (full.includes(`${sep}globals.${"css"}`)) {
-            globalsCssCache = { file: null, mtime: 0, css: "" };
-          }
-          if (full.endsWith(`${sep}layout.tsx`) || full.endsWith(`${sep}layout.ts`)) {
-            fontsScannedFromLayout = false;
-            GOOGLE_FONT_FAMILIES.clear();
-          }
-          const payload = { type: "reload", file: relative(cwd, full), at: Date.now() };
-          for (const send of hmrClients) {
-            try {
-              send(JSON.stringify({ event: "change", data: payload }));
-            } catch {}
-          }
-          logHmr(full);
-        }, 30);
-      });
+      const w = fsWatch(dir, onWatchEvent(dir));
       watchers.set(dir, w);
     } catch (err) {
       logLine([` ${paint("dim", "watch error:")} ${paint("red", err.message)}`], 1);
     }
   }
+
   // Watch the WHOLE project (minus dep/build dirs) so a change to *any* source
   // file — pages, components, lib, hooks, content, config, wherever — triggers
-  // a recompile + reload. No more "edit this folder and nothing happens".
-  walk(cwd);
+  // a recompile + reload. Prefer a single recursive watcher (macOS, Windows,
+  // Linux on Node 20+/Bun): hundreds of per-directory FSEvents watchers could
+  // hit OS limits and die silently, leaving saves unnoticed until a restart.
+  try {
+    const w = fsWatch(cwd, { recursive: true }, onWatchEvent(cwd));
+    watchers.set(cwd, w);
+    recursiveMode = true;
+  } catch {
+    walk(cwd);
+  }
 }
 
 const networkUrls = [];
@@ -2156,6 +2750,55 @@ async function handleFetch(req) {
     return new Response("// island not found", { status: 404, headers: { "Content-Type": "application/javascript" } });
   }
 
+  // Per-component client-island bundle (self-mounting; hydrates its markers).
+  if (pathname === "/_swift-rust/island-comp.js") {
+    const p = url.searchParams.get("p");
+    if (p && existsSync(p)) {
+      try {
+        const code = await buildComponentIslandBundle(p);
+        return new Response(code, {
+          headers: { "Content-Type": "application/javascript; charset=utf-8", "Cache-Control": "no-cache" },
+        });
+      } catch (e) {
+        logError(e, `component island bundle failed for ${p}`);
+        return new Response(`/* island build error: ${String(e?.message || e).replace(/\*\//g, "* /")} */`, {
+          status: 500,
+          headers: { "Content-Type": "application/javascript; charset=utf-8" },
+        });
+      }
+    }
+    return new Response("// island not found", { status: 404, headers: { "Content-Type": "application/javascript" } });
+  }
+
+  // On-demand revalidation: POST /_swift-rust/revalidate { tag?, path? }
+  // Purges the shared data cache (globalThis.__SR_CACHE__) by tag or path so
+  // webhooks / mutations can invalidate without a redeploy.
+  if (pathname === "/_swift-rust/revalidate") {
+    if (req.method !== "POST") {
+      return new Response(JSON.stringify({ error: "use POST" }), {
+        status: 405,
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+    let body = {};
+    try { body = await req.json(); } catch {}
+    const tag = body.tag ?? url.searchParams.get("tag");
+    const path = body.path ?? url.searchParams.get("path");
+    const store = globalThis.__SR_CACHE__;
+    let purged = 0;
+    if (store?.store) {
+      for (const [k, v] of store.store) {
+        if ((tag && v.tags?.includes(tag)) || (path && k.includes(path))) {
+          store.store.delete(k);
+          purged++;
+        }
+      }
+      if (tag) store.purged?.add(`tag:${tag}`);
+      if (path) store.purged?.add(`path:${path}`);
+    }
+    return Response.json({ revalidated: true, tag: tag ?? null, path: path ?? null, purged });
+  }
+
   if (pathname.startsWith("/_swift-rust/")) {
     return new Response("Not found", { status: 404 });
   }
@@ -2364,6 +3007,12 @@ async function handleFetch(req) {
     const src = `/_swift-rust/island.js?p=${encodeURIComponent(renderResult.pageFile)}`;
     doc = doc.replace("</body>", `<script type="module" src="${src}"></script>\n</body>`);
   }
+  // Component-level "use client" islands: one self-mounting module per unique
+  // source referenced by a marker in the rendered HTML.
+  for (const islandSrc of collectIslandSources(doc)) {
+    const s = `/_swift-rust/island-comp.js?p=${encodeURIComponent(islandSrc)}`;
+    doc = doc.replace("</body>", `<script type="module" src="${s}"></script>\n</body>`);
+  }
   // pending.tsx → hidden overlay the client navigator reveals while a
   // navigation is in flight (see runtime/navigator.js).
   const pendingOverlay = await renderPendingOverlay(renderResult.segments);
@@ -2380,12 +3029,28 @@ async function handleFetch(req) {
     const json = JSON.stringify(transitionCfg).replace(/</g, "\\u003c");
     doc = doc.replace("</body>", `<script>window.__SR_TRANSITION__=${json}</script>\n</body>`);
   }
+  // `use static` guarantee: a static route must not perform request-time work.
+  // Setting cookies during render is the one dynamic signal we can catch at
+  // runtime — fail loudly rather than silently shipping a wrong cache header.
+  if (renderResult.config?.static && (renderResult.setCookies || []).length) {
+    const e = new Error(
+      "A 'use static' route set a cookie during render, which is a dynamic action. " +
+        "Remove 'use static' or stop setting cookies on this route.",
+    );
+    logError(e, "use static violation");
+    return new Response(errorOverlayHTML(e.message, e.stack || ""), {
+      status: 500,
+      headers: { "Content-Type": "text/html; charset=utf-8" },
+    });
+  }
   const headers = new Headers({ "Content-Type": "text/html; charset=utf-8" });
   for (const c of renderResult.setCookies || []) headers.append("Set-Cookie", c);
   // config.ts headers
   for (const [k, v] of Object.entries(renderResult.config?.headers || {})) headers.set(k, String(v));
-  // revalidate.ts → Cache-Control + cache tags
-  const cc = cacheControlFromPlan(renderResult.revalidatePlan);
+  // revalidate.ts → Cache-Control + cache tags. A 'use static' route with no
+  // explicit revalidate plan gets a long-lived, revalidatable CDN cache.
+  let cc = cacheControlFromPlan(renderResult.revalidatePlan);
+  if (!cc && renderResult.config?.static) cc = "public, max-age=0, s-maxage=31536000, stale-while-revalidate";
   if (cc) headers.set("Cache-Control", cc);
   const tags = renderResult.revalidatePlan?.tags || renderResult.revalidatePlan?.invalidate;
   if (Array.isArray(tags) && tags.length) headers.set("x-vercel-cache-tags", tags.join(","));
@@ -2404,7 +3069,7 @@ async function handleApiRoute(req, segments, method, reqStart) {
   }
   const handlerName = method.toUpperCase();
   try {
-    const mod = await loadModule(route.file, { bust: true });
+    const mod = await loadModuleFresh(route.file);
     const handler = mod[handlerName] || mod[method.toLowerCase()];
     if (typeof handler !== "function") {
       const total = performance.now() - reqStart;