swift-rust 1.0.0 → 1.1.0

package/bin/dev-server.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { existsSync, statSync, readFileSync, readdirSync, watch as fsWatch } from "node:fs";
+import { existsSync, statSync, readFileSync, readdirSync, writeFileSync, unlinkSync, watch as fsWatch } from "node:fs";
 import { join, resolve, extname, relative, dirname, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import { performance } from "node:perf_hooks";
@@ -42,7 +42,14 @@ const PUBLIC_DIR = resolve(cwd, "public");
 const SWIFT_RUST_CONFIG = resolve(cwd, "swift-rust.config.json");
 
 const PAGE_EXTENSIONS = [".tsx", ".ts", ".jsx", ".js"];
-const SPECIAL_FILES = new Set(["layout", "loading", "error", "not-found", "template", "default", "route"]);
+const SPECIAL_FILES = new Set([
+  "layout", "loading", "error", "not-found", "template", "default", "route",
+  // RFC 0001 routing files
+  "guard", "loader", "action", "config", "schema", "proxy", "pending",
+  "revalidate", "shell", "fragment", "transition", "fallback", "prefetch",
+  "error-recovery", "i18n", "rpc", "stream", "edge", "worker", "query",
+  "state", "seo", "variant", "global-error",
+]);
 
 const moduleCache = new Map();
 const compileTimings = new Map();
@@ -148,22 +155,22 @@ function findFile(dir, basename) {
 function resolvePageRoute(segments) {
   if (segments.length === 0) {
     const file = findFile(APP_DIR, "page");
-    if (file) return { file, params: {}, segments: [] };
+    if (file) return { file, params: {}, segments: [], dirChain: [APP_DIR] };
     return null;
   }
-  return resolveRoute(APP_DIR, segments, 0, {});
+  return resolveRoute(APP_DIR, segments, 0, {}, [APP_DIR]);
 }
 
-function resolveRoute(dir, segments, idx, params) {
+function resolveRoute(dir, segments, idx, params, chain) {
   if (idx === segments.length) {
     const file = findFile(dir, "page");
-    if (file) return { file, params, segments: segments.slice(0, idx) };
+    if (file) return { file, params, segments: segments.slice(0, idx), dirChain: chain };
     return null;
   }
   const seg = segments[idx];
   const directDir = join(dir, seg);
   if (existsSync(directDir) && statSync(directDir).isDirectory()) {
-    const result = resolveRoute(directDir, segments, idx + 1, params);
+    const result = resolveRoute(directDir, segments, idx + 1, params, [...chain, directDir]);
     if (result) return result;
   }
   if (existsSync(dir) && statSync(dir).isDirectory()) {
@@ -175,7 +182,7 @@ function resolveRoute(dir, segments, idx, params) {
         if (paramName.startsWith("...")) continue;
         const paramDir = join(dir, e.name);
         const newParams = { ...params, [paramName]: seg };
-        const result = resolveRoute(paramDir, segments, idx + 1, newParams);
+        const result = resolveRoute(paramDir, segments, idx + 1, newParams, [...chain, paramDir]);
         if (result) return result;
       }
     }
@@ -183,6 +190,42 @@ function resolveRoute(dir, segments, idx, params) {
   return null;
 }
 
+/** Resolve the leaf directory for URL segments (incl. dynamic), even when the
+ *  segment has no page.tsx — used for stream.ts / rpc.ts handlers. */
+function resolveLeafDir(segments) {
+  return walkLeafDir(APP_DIR, segments, 0, {});
+}
+function walkLeafDir(dir, segments, idx, params) {
+  if (idx === segments.length) return { dir, params };
+  const seg = segments[idx];
+  const directDir = join(dir, seg);
+  if (existsSync(directDir) && statSync(directDir).isDirectory()) {
+    const r = walkLeafDir(directDir, segments, idx + 1, params);
+    if (r) return r;
+  }
+  if (existsSync(dir) && statSync(dir).isDirectory()) {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (e.isDirectory() && e.name.startsWith("[") && e.name.endsWith("]") && !e.name.includes("...")) {
+        const pn = e.name.slice(1, -1);
+        const r = walkLeafDir(join(dir, e.name), segments, idx + 1, { ...params, [pn]: seg });
+        if (r) return r;
+      }
+    }
+  }
+  return null;
+}
+
+/** Collect a routing file (guard/loader/action/config/schema/…) along the
+ *  matched directory chain, outermost → innermost. */
+function collectRouteFiles(dirChain, basename) {
+  const out = [];
+  for (const dir of dirChain || []) {
+    const f = findFile(dir, basename);
+    if (f) out.push({ file: f, dir });
+  }
+  return out;
+}
+
 function resolveApiRoute(segments) {
   if (segments.length === 0 || segments[0] !== "api") return null;
   const apiDir = join(APP_DIR, "api");
@@ -256,6 +299,16 @@ function findLoading(segments) {
   return findFile(APP_DIR, "loading");
 }
 
+/** Generic: find the nearest `<basename>` file walking the URL segments up. */
+function findRouteFileUp(segments, basename) {
+  for (let i = segments?.length ?? 0; i >= 0; i--) {
+    const dir = i === 0 ? APP_DIR : join(APP_DIR, ...segments.slice(0, i));
+    const file = findFile(dir, basename);
+    if (file) return file;
+  }
+  return findFile(APP_DIR, basename);
+}
+
 function findRouteSegmentsForDir(dir) {
   const rel = relative(APP_DIR, dir);
   if (rel === "" || rel === ".") return [];
@@ -271,6 +324,57 @@ function bustCache(file) {
   }
 }
 
+// Bumped on every file change. Used to invalidate the per-render SSR bundles
+// below so that edits to *transitively imported* modules (components/, lib/)
+// are picked up — Bun's module cache is path-keyed and ignores ?query busting,
+// so a plain re-import of the page would still serve stale child modules.
+let buildGeneration = 1;
+
+// Externalize everything that isn't the app's own source (relative imports and
+// the @/ alias). React and the framework stay shared/cached; only app code is
+// re-bundled, so every render reflects the latest component/lib edits.
+const externalizeDepsPlugin = {
+  name: "sr-externalize-deps",
+  setup(build) {
+    build.onResolve({ filter: /.*/ }, (args) => {
+      const p = args.path;
+      // App's own source (relative, absolute, or the @/ alias) → bundle fresh.
+      if (p.startsWith(".") || p.startsWith("/") || p.startsWith("@/")) return undefined;
+      // Everything else (react, swift-rust, node:*, @scope/*) → keep external.
+      return { path: p, external: true };
+    });
+  },
+};
+
+const ssrBundleCache = new Map(); // file -> { gen, mod }
+
+async function loadModuleFresh(filePath) {
+  if (typeof Bun === "undefined" || typeof Bun.build !== "function") {
+    return loadModule(filePath, { bust: true });
+  }
+  const cached = ssrBundleCache.get(filePath);
+  if (cached && cached.gen === buildGeneration) return cached.mod;
+
+  const result = await Bun.build({
+    entrypoints: [filePath],
+    target: "bun",
+    plugins: [externalizeDepsPlugin],
+  });
+  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`);
+  writeFileSync(tmp, code);
+  try {
+    const mod = await import(pathToFileURL(tmp).href);
+    ssrBundleCache.set(filePath, { gen: buildGeneration, mod });
+    return mod;
+  } finally {
+    try { unlinkSync(tmp); } catch {}
+  }
+}
+
 async function loadModule(filePath, { bust = false } = {}) {
   const baseUrl = pathToFileURL(filePath).href;
   const url = bust ? `${baseUrl}?t=${Date.now()}-${Math.random().toString(36).slice(2)}` : baseUrl;
@@ -605,7 +709,393 @@ async function renderToStringCompat(tree) {
   return renderToString(tree);
 }
 
-async function renderRoute(urlPath) {
+// ── Client islands: page-level "use client" hydration ──────────────────────
+// A page whose first meaningful line is `"use client"` is bundled for the
+// browser and hydrated, so interactive components (e.g. the Pdf viewer) run.
+// Static pages are untouched and ship zero JS.
+
+const islandBundleCache = new Map(); // pageFile -> { mtime, code }
+
+export function isClientPage(file) {
+  try {
+    for (const raw of readFileSync(file, "utf8").split("\n")) {
+      const t = raw.trim();
+      if (!t || t.startsWith("//") || t.startsWith("/*") || t.startsWith("*")) continue;
+      return /^["']use client["'];?$/.test(t);
+    }
+  } catch {}
+  return false;
+}
+
+async function buildIslandBundle(pageFile) {
+  if (typeof Bun === "undefined" || typeof Bun.build !== "function") {
+    throw new Error("client islands require the Bun runtime");
+  }
+  const cached = islandBundleCache.get(pageFile);
+  if (cached && cached.gen === buildGeneration) return cached.code;
+
+  // 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 entry = `import { createRoot } from "react-dom/client";
+import { createElement } from "react";
+import Page from ${JSON.stringify(pageFile)};
+const el = document.getElementById("__sr_island_root");
+if (el) {
+  let params = {};
+  try { params = JSON.parse(el.getAttribute("data-sr-params") || "{}"); } catch {}
+  // Client-render (not hydrate): "use client" pages contain client-only
+  // widgets (e.g. the pdf.js viewer) whose SSR output intentionally differs
+  // from the first client render, so hydration would mismatch.
+  el.innerHTML = "";
+  createRoot(el).render(createElement(Page, { params }));
+}
+`;
+  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();
+    islandBundleCache.set(pageFile, { gen: buildGeneration, code });
+    return code;
+  } finally {
+    try { unlinkSync(entryPath); } catch {}
+  }
+}
+
+// ── Routing-file error handling & convention validation ─────────────────────
+
+class RoutingFileError extends Error {
+  constructor(kind, file, cause) {
+    super(`Error in ${kind} (${relative(cwd, file)}): ${cause?.message ?? cause}`);
+    this.name = "RoutingFileError";
+    this.kind = kind;
+    this.file = file;
+    this.cause = cause;
+    if (cause?.stack) this.stack = cause.stack;
+  }
+}
+
+const warnedRouting = new Set();
+function warnRoutingFile(file, msg) {
+  const key = `${file}::${msg}`;
+  if (warnedRouting.has(key)) return;
+  warnedRouting.add(key);
+  process.stderr.write(`  ${paint("yellow", "⚠")} ${paint("dim", "[routing]")} ${msg}\n`);
+}
+
+/** Warn when routing files are placed where the router will never find them
+ *  (e.g. proxy.ts at the project root, or routing files in app/ when the app
+ *  uses an app/src/ directory). Helps catch a very common mistake early. */
+function validateRoutingConventions() {
+  const names = [...SPECIAL_FILES, "page"];
+  const appRel = relative(cwd, APP_DIR) || "app";
+  const usesSrc = APP_DIR.endsWith(`${sep}src`);
+  const scan = (dir, label) => {
+    if (!existsSync(dir) || resolve(dir) === resolve(APP_DIR)) return;
+    for (const name of names) {
+      const f = findFile(dir, name);
+      if (f) {
+        warnRoutingFile(
+          f,
+          `"${name}" found in ${label} — routing files belong under "${appRel}/". ` +
+            `Move ${relative(cwd, f)} into ${appRel}/ (the router only scans there).`,
+        );
+      }
+    }
+  };
+  scan(cwd, "the project root");
+  if (usesSrc) scan(dirname(APP_DIR), `"app/" (outside "src/")`);
+}
+
+// ── RFC 0001 route pipeline: config → schema → guard → loader/action ────────
+
+let routerRuntimePromise = null;
+function routerRuntime() {
+  if (!routerRuntimePromise) routerRuntimePromise = import("swift-rust/router").catch(() => null);
+  return routerRuntimePromise;
+}
+
+function parseCookieHeader(header) {
+  const map = new Map();
+  for (const part of (header || "").split(";")) {
+    const i = part.indexOf("=");
+    if (i < 0) continue;
+    const k = part.slice(0, i).trim();
+    if (k) map.set(k, decodeURIComponent(part.slice(i + 1).trim()));
+  }
+  return map;
+}
+function serializeCookie(name, value, opts = {}) {
+  let s = `${name}=${encodeURIComponent(value)}`;
+  if (opts.maxAge != null) s += `; Max-Age=${opts.maxAge}`;
+  if (opts.path) s += `; Path=${opts.path}`;
+  else s += "; Path=/";
+  if (opts.domain) s += `; Domain=${opts.domain}`;
+  if (opts.httpOnly) s += "; HttpOnly";
+  if (opts.secure) s += "; Secure";
+  if (opts.sameSite) s += `; SameSite=${opts.sameSite[0].toUpperCase()}${opts.sameSite.slice(1)}`;
+  return s;
+}
+
+function buildRouteCtx(req, url, params, searchParams) {
+  const cookieMap = parseCookieHeader(req?.headers?.get?.("cookie") || "");
+  const setCookies = [];
+  const cookies = {
+    get: (n) => cookieMap.get(n),
+    set: (n, v, o) => { cookieMap.set(n, v); setCookies.push(serializeCookie(n, v, o)); },
+    delete: (n, o) => { cookieMap.delete(n); setCookies.push(serializeCookie(n, "", { ...o, maxAge: 0 })); },
+    all: () => cookieMap,
+  };
+  const localsMap = new Map();
+  return {
+    url,
+    method: req?.method || "GET",
+    headers: req?.headers || new Headers(),
+    cookies,
+    params,
+    searchParams,
+    runtime: "node",
+    locals: { get: (k) => localsMap.get(k), set: (k, v) => localsMap.set(k, v) },
+    request: req,
+    __setCookies: setCookies,
+  };
+}
+
+// Turn a returned RouteControl object into a thrown control the catch handles.
+function applyControl(c) {
+  if (!c || typeof c !== "object" || !c.kind) return;
+  if (c.kind === "next") return;
+  const e = new Error(`route control: ${c.kind}`);
+  if (c.kind === "redirect") e.digest = `REDIRECT;${c.status || 307};${c.to}`;
+  else if (c.kind === "rewrite") e.digest = `REWRITE;${c.to}`;
+  else if (c.kind === "notFound") e.digest = "NOT_FOUND";
+  else if (c.kind === "response") e.__response = c.response;
+  else if (c.kind === "error") { throw c.error ?? new Error("route error"); }
+  throw e;
+}
+
+/** Merge config.ts along the chain (inner overrides outer). */
+async function readMergedConfig(chain) {
+  let config = {};
+  for (const { file } of collectRouteFiles(chain, "config")) {
+    const mod = await loadModuleFresh(file);
+    const c = mod.config ?? mod.default;
+    if (c && typeof c === "object") config = { ...config, ...c, headers: { ...config.headers, ...c.headers } };
+  }
+  // edge.ts / worker.ts force a runtime.
+  const edge = await collectFirst(chain, "edge");
+  if (edge && (edge.edge || edge.default)) config.runtime = "edge";
+  const worker = await collectFirst(chain, "worker");
+  if (worker && (worker.default || worker.bindings)) config.runtime = "worker";
+  return config;
+}
+
+async function runRoutePipeline(route, ctx) {
+  const chain = route.dirChain || [];
+
+  // proxy.ts — phase 1, outer → inner. Cheap, data-free interception
+  // (Next.js calls this "proxy"; "middleware" is accepted with a warning).
+  for (const { file } of collectRouteFiles(chain, "proxy")) {
+    const mod = await loadModuleFresh(file);
+    const fn = mod.default ?? mod.proxy;
+    if (typeof fn === "function") {
+      const matcher = mod.matcher;
+      const matched = !matcher || matchesMatcher(ctx.url.pathname, matcher);
+      if (matched) {
+        try {
+          applyControl(await fn(ctx));
+        } catch (e) {
+          if (e?.digest || e?.__response) throw e; // control flow, re-throw
+          throw new RoutingFileError("proxy", file, e);
+        }
+      }
+    }
+  }
+  // Back-compat: warn if the old name is used.
+  for (const { file } of collectRouteFiles(chain, "middleware")) {
+    warnRoutingFile(file, `"middleware.ts" was renamed to "proxy.ts" — rename ${relative(cwd, file)}.`);
+    const mod = await loadModuleFresh(file);
+    const fn = mod.default ?? mod.middleware;
+    if (typeof fn === "function") {
+      const matcher = mod.matcher;
+      if (!matcher || matchesMatcher(ctx.url.pathname, matcher)) applyControl(await fn(ctx));
+    }
+  }
+
+  // config.ts — merged, applied to the response by the caller.
+  const config = await readMergedConfig(chain);
+
+  // i18n.ts — resolve the active locale into locals (cookie/header/default).
+  const i18nMod = await collectFirst(chain, "i18n");
+  const i18nCfg = i18nMod?.i18n ?? i18nMod?.default;
+  if (i18nCfg && Array.isArray(i18nCfg.locales)) {
+    let locale = i18nCfg.defaultLocale ?? i18nCfg.locales[0];
+    if (typeof i18nCfg.resolve === "function") locale = (await i18nCfg.resolve(ctx)) || locale;
+    else if (i18nCfg.strategy === "cookie") locale = ctx.cookies.get("locale") || locale;
+    else if (i18nCfg.strategy === "header") {
+      const al = ctx.headers.get?.("accept-language")?.split(",")[0]?.split("-")[0];
+      if (al && i18nCfg.locales.includes(al)) locale = al;
+    }
+    ctx.locals.set("locale", locale);
+    ctx.__locale = locale;
+  }
+
+  // schema.ts — validate/brand params + searchParams (Standard-Schema/Zod-like)
+  for (const { file } of collectRouteFiles(chain, "schema")) {
+    const mod = await loadModuleFresh(file);
+    if (mod.params?.safeParse) {
+      const r = mod.params.safeParse(ctx.params);
+      if (!r.success) { const e = new Error("Invalid params"); e.__response = jsonResponse({ error: "Invalid params", issues: r.error?.issues ?? r.error }, 400); throw e; }
+      Object.assign(ctx.params, r.data);
+    }
+    const querySpec = (await collectFirst(chain, "query"))?.query;
+    const searchSchema = querySpec?.parse ?? mod.searchParams;
+    if (searchSchema?.safeParse) {
+      const r = searchSchema.safeParse(ctx.searchParams);
+      if (r.success) Object.assign(ctx.searchParams, r.data);
+    }
+  }
+
+  // guard.ts — outer → inner
+  for (const { file } of collectRouteFiles(chain, "guard")) {
+    const mod = await loadModuleFresh(file);
+    const fn = mod.default ?? mod.guard;
+    if (typeof fn === "function") {
+      try {
+        applyControl(await fn(ctx));
+      } catch (e) {
+        if (e?.digest || e?.__response) throw e;
+        throw new RoutingFileError("guard", file, e);
+      }
+    } else if (mod.default !== undefined || mod.guard !== undefined) {
+      warnRoutingFile(file, `guard.ts must export a function (default export). ${relative(cwd, file)}`);
+    }
+  }
+
+  let actionData;
+  // action.ts on mutating requests (leaf only)
+  if (ctx.method !== "GET" && ctx.method !== "HEAD") {
+    const actions = collectRouteFiles(chain, "action");
+    const leaf = actions[actions.length - 1];
+    if (leaf) {
+      const mod = await loadModuleFresh(leaf.file);
+      const fn = mod.default ?? mod.action;
+      if (typeof fn === "function") {
+        const actx = Object.assign({}, ctx, {
+          formData: () => ctx.request.formData(),
+          json: () => ctx.request.json(),
+        });
+        try {
+          const result = await fn(actx);
+          applyControl(result);
+          actionData = result;
+        } catch (e) {
+          if (e?.digest || e?.__response) throw e;
+          throw new RoutingFileError("action", leaf.file, e);
+        }
+      }
+    }
+  }
+
+  // loader.ts — run in parallel along the chain
+  const loaders = collectRouteFiles(chain, "loader");
+  const loaded = await Promise.all(
+    loaders.map(async ({ file, dir }) => {
+      const mod = await loadModuleFresh(file);
+      const fn = mod.default ?? mod.loader;
+      if (typeof fn !== "function") return [dir, undefined];
+      const lctx = Object.assign({}, ctx, { parent: () => undefined });
+      try {
+        return [dir, await fn(lctx)];
+      } catch (e) {
+        if (e?.digest || e?.__response) throw e;
+        throw new RoutingFileError("loader", file, e);
+      }
+    }),
+  );
+  const loadersMap = {};
+  for (const [dir, data] of loaded) loadersMap[relative(cwd, dir)] = data;
+  const loaderData = loaded.length ? loaded[loaded.length - 1][1] : undefined;
+
+  // state.ts — server-side state to hydrate a client store.
+  let serverState;
+  const stateMod = await collectFirst(chain, "state");
+  const stateFn = stateMod?.default ?? stateMod?.state;
+  if (typeof stateFn === "function") serverState = await stateFn(ctx);
+
+  // seo.tsx — structured data / head injection (has loader data).
+  let seoHead = "";
+  const seoMod = await collectFirst(chain, "seo");
+  const seoFn = seoMod?.default ?? seoMod?.seo;
+  if (typeof seoFn === "function") {
+    seoHead = buildSeoHead(await seoFn(Object.assign({}, ctx, { data: loaderData })));
+  }
+
+  // revalidate.ts — leaf decides cache TTL / tags.
+  let revalidatePlan = config.revalidate != null ? { ttl: config.revalidate } : undefined;
+  const rev = await collectFirst(chain, "revalidate");
+  const revFn = rev?.default ?? rev?.revalidate;
+  if (typeof revFn === "function") {
+    const plan = await revFn(Object.assign({}, ctx, { data: loaderData, afterAction: ctx.method !== "GET" }));
+    if (plan && typeof plan === "object") revalidatePlan = { ...revalidatePlan, ...plan };
+  }
+
+  return { actionData, loaderData, loaders: loadersMap, setCookies: ctx.__setCookies, config, revalidatePlan, serverState, seoHead };
+}
+
+function escAttr(s) {
+  return String(s).replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+}
+function buildSeoHead(r) {
+  if (!r || typeof r !== "object") return "";
+  const out = [];
+  if (r.title) out.push(`<title>${escAttr(r.title)}</title>`);
+  if (r.description) out.push(`<meta name="description" content="${escAttr(r.description)}" />`);
+  if (r.canonical) out.push(`<link rel="canonical" href="${escAttr(r.canonical)}" />`);
+  if (r.robots) out.push(`<meta name="robots" content="${escAttr(r.robots)}" />`);
+  for (const [k, v] of Object.entries(r.openGraph || {})) out.push(`<meta property="og:${escAttr(k)}" content="${escAttr(v)}" />`);
+  for (const a of r.alternates || []) out.push(`<link rel="alternate" hreflang="${escAttr(a.hreflang)}" href="${escAttr(a.href)}" />`);
+  const jsonLd = r.jsonLd ? (Array.isArray(r.jsonLd) ? r.jsonLd : [r.jsonLd]) : [];
+  for (const ld of jsonLd) out.push(`<script type="application/ld+json">${JSON.stringify(ld).replace(/</g, "\\u003c")}</script>`);
+  return out.join("\n");
+}
+
+async function collectFirst(chain, basename) {
+  const files = collectRouteFiles(chain, basename);
+  if (files.length === 0) return null;
+  return await loadModuleFresh(files[files.length - 1].file);
+}
+
+function matchesMatcher(pathname, matcher) {
+  const list = Array.isArray(matcher) ? matcher : [matcher];
+  return list.some((m) => {
+    if (typeof m !== "string") return false;
+    // simple glob: * → [^/]*, ** → .*
+    const re = new RegExp("^" + m.replace(/[.+?^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "::").replace(/\*/g, "[^/]*").replace(/::/g, ".*") + "$");
+    return re.test(pathname);
+  });
+}
+
+function jsonResponse(obj, status = 200) {
+  return new Response(JSON.stringify(obj), { status, headers: { "Content-Type": "application/json" } });
+}
+
+function cacheControlFromPlan(plan) {
+  if (!plan) return null;
+  if (plan.ttl === false) return "public, max-age=31536000, immutable";
+  if (plan.ttl === 0) return "no-store";
+  if (typeof plan.ttl === "number") return `public, max-age=0, s-maxage=${plan.ttl}, stale-while-revalidate`;
+  return null;
+}
+
+async function renderRoute(urlPath, req) {
   const segments = urlToRouteSegments(urlPath);
   const route = resolvePageRoute(segments);
   if (!route) {
@@ -618,8 +1108,48 @@ async function renderRoute(urlPath) {
 
   try {
     const React = await import("react");
-    const pageMod = await loadModule(route.file, { bust: true });
-    const Page = pageMod.default ?? pageMod.Page ?? pageMod.page;
+    const url = req ? new URL(req.url) : new URL(urlPath, "http://localhost");
+    const searchParams = Object.fromEntries(url.searchParams.entries());
+    const ctx = buildRouteCtx(req, url, { ...route.params }, searchParams);
+
+    // Run the RFC 0001 pipeline (config/schema/guard/loader/action).
+    const pipeline = await runRoutePipeline(route, ctx);
+    route.params = ctx.params; // validated/branded params flow to the page
+
+    const runtime = await routerRuntime();
+    if (runtime?.__setRouteContext) {
+      runtime.__setRouteContext({
+        request: ctx,
+        loaderData: pipeline.loaderData,
+        actionData: pipeline.actionData,
+        loaders: pipeline.loaders,
+      });
+    }
+
+    // variant.tsx — pick an A/B variant component (bucket from middleware/
+    // cookie/assign), else fall back to page.tsx.
+    let Page;
+    const leafDir = (route.dirChain || [])[(route.dirChain || []).length - 1];
+    const variantFile = leafDir && findFile(leafDir, "variant");
+    if (variantFile) {
+      const vmod = await loadModuleFresh(variantFile);
+      if (vmod.variants && typeof vmod.variants === "object") {
+        const bucket =
+          (typeof vmod.assign === "function" ? vmod.assign(ctx) : null) ||
+          ctx.locals.get("bucket") ||
+          ctx.cookies.get("bucket") ||
+          Object.keys(vmod.variants)[0];
+        const loader = vmod.variants[bucket];
+        if (typeof loader === "function") {
+          const m = await loader();
+          Page = m.default ?? m;
+        }
+      }
+    }
+    if (!Page) {
+      const pageMod = await loadModuleFresh(route.file);
+      Page = pageMod.default ?? pageMod.Page ?? pageMod.page;
+    }
     if (!Page) {
       return { status: 500, html: null, error: new Error(`page ${route.file} has no default export`) };
     }
@@ -628,19 +1158,44 @@ async function renderRoute(urlPath) {
       get: (t, k) => (k in t ? t[k] : dynamicParams.get(String(k))),
     });
 
+    const clientPage = isClientPage(route.file);
     let tree = React.createElement(Page, { params: paramsProxy });
+    if (clientPage) {
+      // Wrap in a hydration root so the client bundle can mount into it.
+      tree = React.createElement(
+        "div",
+        { id: "__sr_island_root", "data-sr-params": JSON.stringify(route.params || {}) },
+        tree,
+      );
+    }
     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);
     }
     const html = await renderToStringCompat(tree);
+    if (runtime?.__setRouteContext) runtime.__setRouteContext(null);
     const metadata = await resolveMetadata(layouts.map((l) => l.file), route.file, route.params, segments);
-    return { status: 200, html, metadata, error: null, pageFile: route.file, layoutFiles: layouts.map((l) => l.file), notFoundFile, errorFile, loadingFile, segments };
+    return { status: 200, html, metadata, error: null, clientPage, pageFile: route.file, layoutFiles: layouts.map((l) => l.file), notFoundFile, errorFile, loadingFile, segments, setCookies: pipeline.setCookies, actionData: pipeline.actionData, config: pipeline.config, revalidatePlan: pipeline.revalidatePlan, seoHead: pipeline.seoHead, serverState: pipeline.serverState };
   } catch (err) {
+    const rt = await routerRuntime();
+    if (rt?.__setRouteContext) rt.__setRouteContext(null);
+    if (err?.__response instanceof Response) {
+      return { status: err.__response.status, rawResponse: err.__response, html: null, error: null, segments };
+    }
     if (err?.digest === "NOT_FOUND" || err?.name === "NotFoundError") {
       return await renderNotFound(segments);
     }
+    if (err?.digest === "FORBIDDEN" || err?.name === "ForbiddenError") {
+      return { status: 403, html: null, error: null, segments, rawResponse: new Response("Forbidden", { status: 403, headers: { "Content-Type": "text/plain" } }) };
+    }
+    if (err?.digest === "UNAUTHORIZED" || err?.name === "UnauthorizedError") {
+      return { status: 401, html: null, error: null, segments, rawResponse: new Response("Unauthorized", { status: 401, headers: { "Content-Type": "text/plain" } }) };
+    }
+    if (err?.digest && String(err.digest).startsWith("REWRITE")) {
+      const to = String(err.digest).slice("REWRITE;".length);
+      return await renderRoute(to, req);
+    }
     if (err?.digest && String(err.digest).startsWith("REDIRECT")) {
       const [, statusStr, ...rest] = String(err.digest).split(";");
       return { status: parseInt(statusStr, 10) || 307, redirect: rest.join(";"), html: null, error: null, segments };
@@ -656,6 +1211,21 @@ async function renderRoute(urlPath) {
         }
       } catch {}
     }
+    // error-recovery.tsx — richer boundary with retry/reset (SSR: stub callbacks).
+    const recoveryFile = findRouteFileUp(segments, "error-recovery");
+    if (recoveryFile) {
+      try {
+        const React = await import("react");
+        const mod = await loadModule(recoveryFile, { bust: true });
+        const Recovery = mod.default ?? mod.ErrorRecovery;
+        if (Recovery) {
+          const html = await renderToStringCompat(
+            React.createElement(Recovery, { error: err, attempt: 1, retry: () => {}, reset: () => {} }),
+          );
+          return { status: 500, html, metadata: null, error: err, segments, pageFile: route.file };
+        }
+      } catch {}
+    }
     return { status: 500, html: null, error: err, segments, pageFile: route.file };
   }
 }
@@ -690,11 +1260,38 @@ function errorOverlayHTML(message, stack, extra) {
   return renderErrorOverlay({ message, stack, ...(extra || {}) });
 }
 
+// Metadata icon files looked up at the root of the app directory (app/ or
+// app/src/), Next.js App Router style. Found files are served from the site
+// root and auto-linked in <head>.
+const APP_ICON_FILES = ["favicon.ico", "favicon.svg", "icon.svg", "icon.png", "apple-icon.png"];
+
+function discoverAppIcons() {
+  const icons = [];
+  for (const name of APP_ICON_FILES) {
+    const file = join(APP_DIR, name);
+    if (existsSync(file) && statSync(file).isFile()) icons.push({ name, file });
+  }
+  return icons;
+}
+
+function buildAppIconsLinkTags() {
+  return discoverAppIcons()
+    .map(({ name }) => {
+      const ext = extname(name).toLowerCase();
+      if (name.startsWith("apple-icon")) return `<link rel="apple-touch-icon" href="/${name}" />`;
+      if (ext === ".ico") return `<link rel="icon" href="/${name}" sizes="any" />`;
+      if (ext === ".svg") return `<link rel="icon" href="/${name}" type="image/svg+xml" />`;
+      return `<link rel="icon" href="/${name}" />`;
+    })
+    .join("\n");
+}
+
 async function buildHead(head) {
   const css = await getProcessedGlobalsCss();
   const fontLink = buildGoogleFontsLinkTag();
   return [
     head || "",
+    buildAppIconsLinkTags(),
     fontLink,
     css ? `<style data-swift-rust-globals>${escapeForStyleTag(css)}</style>` : "",
   ].filter(Boolean).join("\n");
@@ -773,6 +1370,7 @@ function setupWatcher() {
             }
           } catch {}
           logEvent("change", full);
+          buildGeneration++;
           bustCache(full);
           if (full.includes(`${sep}globals.${"css"}`)) {
             globalsCssCache = { file: null, mtime: 0, css: "" };
@@ -796,6 +1394,12 @@ function setupWatcher() {
     }
   }
   walk(APP_DIR);
+  // Also watch sibling source dirs that pages/layouts import from — without
+  // this, edits to components/, lib/, etc. never trigger a reload.
+  for (const extra of ["components", "lib", "app"]) {
+    const p = resolve(cwd, extra);
+    if (existsSync(p)) walk(p);
+  }
 }
 
 const networkUrls = [];
@@ -954,6 +1558,22 @@ async function handleRequest(req, res) {
     return;
   }
 
+  // App-directory metadata icons (app/favicon.ico, app/icon.svg, …) served
+  // from the site root, Next.js style.
+  {
+    const iconName = pathname.replace(/^\/+/, "");
+    if (APP_ICON_FILES.includes(iconName)) {
+      const candidate = join(APP_DIR, iconName);
+      if (existsSync(candidate) && statSync(candidate).isFile()) {
+        const ext = extname(candidate).toLowerCase();
+        const mime = { ".ico": "image/x-icon", ".svg": "image/svg+xml", ".png": "image/png" }[ext] || "application/octet-stream";
+        res.writeHead(200, { "Content-Type": mime });
+        res.end(readFileSync(candidate));
+        return;
+      }
+    }
+  }
+
   if (existsSync(PUBLIC_DIR)) {
     const safe = pathname.replace(/\.\.+/g, "").replace(/^\/+/, "");
     const candidate = join(PUBLIC_DIR, safe);
@@ -1007,7 +1627,7 @@ async function handleRequest(req, res) {
   }
 
   const renderStart = performance.now();
-  const renderResult = await renderRoute(pathname);
+  const renderResult = await renderRoute(pathname, req);
   const renderMs = performance.now() - renderStart;
   const total = performance.now() - reqStart;
 
@@ -1122,10 +1742,48 @@ async function handleFetch(req) {
     return new Response("Image not found", { status: 404 });
   }
 
+  // Client-island hydration bundle for a "use client" page.
+  if (pathname === "/_swift-rust/island.js") {
+    const p = url.searchParams.get("p");
+    if (p && existsSync(p)) {
+      try {
+        const code = await buildIslandBundle(p);
+        return new Response(code, {
+          headers: { "Content-Type": "application/javascript; charset=utf-8", "Cache-Control": "no-cache" },
+        });
+      } catch (e) {
+        logError(e, `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" } });
+  }
+
   if (pathname.startsWith("/_swift-rust/")) {
     return new Response("Not found", { status: 404 });
   }
 
+  // App-directory metadata icons (app/favicon.ico, app/favicon.svg, …) served
+  // from the site root, Next.js style.
+  {
+    const iconName = pathname.replace(/^\/+/, "");
+    if (APP_ICON_FILES.includes(iconName)) {
+      const candidate = join(APP_DIR, iconName);
+      if (existsSync(candidate) && statSync(candidate).isFile()) {
+        const ext = extname(candidate).toLowerCase();
+        const mime =
+          { ".ico": "image/x-icon", ".svg": "image/svg+xml", ".png": "image/png" }[ext] ||
+          "application/octet-stream";
+        const file = Bun?.file ? Bun.file(candidate) : readFileSync(candidate);
+        logRequest({ method, url: pathname, status: 200, duration: performance.now() - reqStart, compileMs: 0 });
+        return new Response(file, { headers: { "Content-Type": mime } });
+      }
+    }
+  }
+
   if (existsSync(PUBLIC_DIR)) {
     const safe = pathname.replace(/\.\.+/g, "").replace(/^\/+/, "");
     const candidate = join(PUBLIC_DIR, safe);
@@ -1144,7 +1802,59 @@ async function handleFetch(req) {
     return await handleApiRoute(req, segments, method, reqStart);
   }
 
-  if (method !== "GET" && method !== "HEAD") {
+  // rpc.ts / stream.ts handlers (leaf, route.ts-like).
+  {
+    const leaf = resolveLeafDir(segments);
+    if (leaf) {
+      const sp = Object.fromEntries(url.searchParams.entries());
+      const baseCtx = buildRouteCtx(req, url, leaf.params, sp);
+      const rpcFile = findFile(leaf.dir, "rpc");
+      if (rpcFile) {
+        try {
+          const mod = await loadModuleFresh(rpcFile);
+          const procs = mod.procedures ?? mod.default;
+          if (procs && typeof procs === "object") {
+            if (method === "POST") {
+              const body = await req.json().catch(() => ({}));
+              const proc = procs[body.procedure];
+              if (!proc) return jsonResponse({ error: `Unknown procedure: ${body.procedure}` }, 404);
+              let input = body.input;
+              if (proc.input?.safeParse) {
+                const r = proc.input.safeParse(input);
+                if (!r.success) return jsonResponse({ error: "Invalid input", issues: r.error?.issues ?? r.error }, 400);
+                input = r.data;
+              }
+              return jsonResponse({ data: await proc.handler(input, baseCtx) });
+            }
+            if (method === "GET") return jsonResponse({ procedures: Object.keys(procs) });
+          }
+        } catch (e) {
+          return jsonResponse({ error: String(e?.message || e) }, 500);
+        }
+      }
+      const streamFile = findFile(leaf.dir, "stream");
+      if (streamFile && !findFile(leaf.dir, "page")) {
+        try {
+          const mod = await loadModuleFresh(streamFile);
+          const fn = mod.default ?? mod.stream;
+          if (typeof fn === "function") {
+            const result = await fn(baseCtx);
+            if (result instanceof Response) return result;
+            return new Response(result, {
+              headers: { "Content-Type": mod.contentType || "text/event-stream", "Cache-Control": "no-cache" },
+            });
+          }
+        } catch (e) {
+          return new Response(String(e?.message || e), { status: 500 });
+        }
+      }
+    }
+  }
+
+  // Non-GET requests are allowed to reach the page render so action.ts can run;
+  // pages without an action simply ignore the body.
+  const ALLOWED_METHODS = new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"]);
+  if (!ALLOWED_METHODS.has(method)) {
     return new Response("Method not allowed", { status: 405 });
   }
 
@@ -1189,7 +1899,7 @@ async function handleFetch(req) {
   }
 
   const renderStart = performance.now();
-  const renderResult = await renderRoute(pathname);
+  const renderResult = await renderRoute(pathname, req);
   const renderMs = performance.now() - renderStart;
   const total = performance.now() - reqStart;
 
@@ -1221,18 +1931,43 @@ async function handleFetch(req) {
 
   if (renderResult.redirect) {
     logRequest({ method, url: pathname, status: renderResult.status, duration: total, compileMs });
-    return new Response(null, {
-      status: renderResult.status,
-      headers: { Location: renderResult.redirect },
-    });
+    const rh = new Headers({ Location: renderResult.redirect });
+    for (const c of renderResult.setCookies || []) rh.append("Set-Cookie", c);
+    return new Response(null, { status: renderResult.status, headers: rh });
+  }
+
+  // Raw Response from a guard/action (RouteControl response, 401, 403, …).
+  if (renderResult.rawResponse instanceof Response) {
+    logRequest({ method, url: pathname, status: renderResult.rawResponse.status, duration: total, compileMs });
+    const r = renderResult.rawResponse;
+    for (const c of renderResult.setCookies || []) r.headers.append("Set-Cookie", c);
+    return r;
   }
 
   logRequest({ method, url: pathname, status: 200, duration: total, compileMs });
   await scanFontsFromLayouts();
-  return new Response(await wrapInDocumentAsync({ head: metadataToHead(renderResult.metadata), body: renderResult.html || "" }), {
-    status: 200,
-    headers: { "Content-Type": "text/html; charset=utf-8" },
-  });
+  // seo.tsx head + metadata head
+  const headExtra = [metadataToHead(renderResult.metadata), renderResult.seoHead || ""].filter(Boolean).join("\n");
+  let doc = await wrapInDocumentAsync({ head: headExtra, body: renderResult.html || "" });
+  // state.ts → window.__SR_STATE__ for client stores
+  if (renderResult.serverState !== undefined) {
+    const json = JSON.stringify(renderResult.serverState).replace(/</g, "\\u003c");
+    doc = doc.replace("</body>", `<script>window.__SR_STATE__=${json}</script>\n</body>`);
+  }
+  if (renderResult.clientPage && renderResult.pageFile) {
+    const src = `/_swift-rust/island.js?p=${encodeURIComponent(renderResult.pageFile)}`;
+    doc = doc.replace("</body>", `<script type="module" src="${src}"></script>\n</body>`);
+  }
+  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);
+  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(","));
+  return new Response(doc, { status: 200, headers });
 }
 
 async function handleApiRoute(req, segments, method, reqStart) {
@@ -1309,6 +2044,7 @@ const MIME = {
 };
 
 await checkAppDir();
+try { validateRoutingConventions(); } catch {}
 await detectNetworkUrls();
 logStartupBanner(`http://localhost:${port}`, networkUrls);
 logLine([` ${paint("dim", "› setupWatcher…")}`]);