react-bun-ssr 0.3.0 → 0.3.2

package/README.md

@@ -1,10 +1,17 @@
 # react-bun-ssr
 
+[![npm version](https://img.shields.io/npm/v/react-bun-ssr)](https://www.npmjs.com/package/react-bun-ssr)
+[![CI](https://github.com/react-formation/react-bun-ssr/actions/workflows/ci.yml/badge.svg)](https://github.com/react-formation/react-bun-ssr/actions/workflows/ci.yml)
+
 `react-bun-ssr` is a Bun-native SSR React framework with file-based routing, loaders, actions, middleware, streaming, soft navigation, and first-class markdown routes.
 
+> **Stability: Experimental (early alpha).**
+> Expect breaking changes across minor releases while core APIs and ergonomics are still being shaped.
+
 - Documentation: https://react-bun-ssr.dev/docs
 - API reference: https://react-bun-ssr.dev/docs/api/overview
 - Blog: https://react-bun-ssr.dev/blog
+- Changelog: [CHANGELOG.md](./CHANGELOG.md)
 - Repository: https://github.com/react-formation/react-bun-ssr
 
 ## Why react-bun-ssr?
@@ -31,6 +38,11 @@ Prerequisites:
 - Bun `>= 1.3.10`
 - `rbssr` available on PATH in the workflow you use to start a new app
 
+Try in browser:
+
+- StackBlitz (primary): https://stackblitz.com/github/react-formation/react-bun-ssr/tree/main/examples/sandbox-starter
+- CodeSandbox (fallback): https://codesandbox.io/s/github/react-formation/react-bun-ssr/tree/main/examples/sandbox-starter
+
 Minimal setup:
 
 ```bash
@@ -57,9 +69,15 @@ For the full setup walkthrough, read the installation guide:
 `rbssr init` scaffolds a small Bun-first SSR app:
 
 ```text
+package.json
+tsconfig.json
+.gitignore
 app/
   root.tsx
+  root.module.css
   middleware.ts
+  public/
+    favicon.svg
   routes/
     index.tsx
     api/
@@ -67,8 +85,13 @@ app/
 rbssr.config.ts
 ```
 
+- `package.json`: Bun scripts and framework/runtime dependencies
+- `tsconfig.json`: starter TypeScript config for Bun + JSX
+- `.gitignore`: minimal app-level ignore rules
 - `app/root.tsx`: document shell and top-level layout
+- `app/root.module.css`: starter CSS Module for layout and base presentation
 - `app/middleware.ts`: global request pipeline hook
+- `app/public/favicon.svg`: starter public asset
 - `app/routes/index.tsx`: first SSR page route
 - `app/routes/api/health.ts`: first API route
 - `rbssr.config.ts`: runtime configuration entrypoint
@@ -141,6 +164,7 @@ This repository contains both the framework and the official docs site built wit
 ```bash
 git clone git@github.com:react-formation/react-bun-ssr.git
 cd react-bun-ssr
+bun link
 bun install
 bun run docs:dev
 ```
@@ -178,20 +202,3 @@ Contributions should keep framework behavior, docs, tests, and generated artifac
 - The release workflow derives the published package version from the Git tag and rewrites `package.json` in the release job before publishing.
 - npm publishing uses trusted publishing with GitHub OIDC instead of an `NPM_TOKEN`.
 - npm package settings must have a trusted publisher configured for `react-formation / react-bun-ssr / release.yml`.
-
-## Deploying
-
-Fly.io deployment support is already documented and used by this project.
-
-Happy path:
-
-```bash
-fly auth login
-fly deploy
-```
-
-Full deployment docs:
-
-- https://react-bun-ssr.dev/docs/deployment/bun-deployment
-- https://react-bun-ssr.dev/docs/deployment/configuration
-- https://react-bun-ssr.dev/docs/deployment/troubleshooting

package/framework/cli/dev-runtime.ts

@@ -43,6 +43,10 @@ function toAbsoluteAppPath(appDir: string, relativePath: string): string {
   return path.join(appDir, relativePath);
 }
 
+function toNormalizedWatchPath(fileName?: string | Buffer | null): string {
+  return typeof fileName === "string" ? normalizeSlashes(fileName) : "";
+}
+
 interface DevHotData {
   bunServer?: Bun.Server<undefined>;
   reloadToken?: number;
@@ -88,9 +92,11 @@ export async function runHotDevChild(options: {
   let nextClientBuildReason: DevReloadReason | null = null;
   let stopping = false;
 
-  const watchers: FSWatcher[] = [];
   let structuralSyncTimer: ReturnType<typeof setTimeout> | undefined;
   let structuralSyncQueue: Promise<void> = Promise.resolve();
+  let routesWatcher: FSWatcher | null = null;
+  let appWatcher: FSWatcher | null = null;
+  let configWatcher: FSWatcher | null = null;
 
   const publishReload = (reason: DevReloadReason): void => {
     reloadToken += 1;
@@ -253,11 +259,7 @@ export async function runHotDevChild(options: {
     process.exit(RBSSR_DEV_RESTART_EXIT_CODE);
   };
 
-  const handleAppEvent = (eventType: string, fileName?: string | Buffer | null): void => {
-    const relativePath = typeof fileName === "string"
-      ? normalizeSlashes(fileName)
-      : "";
-
+  const handleAppEvent = (eventType: string, relativePath: string): void => {
     if (!relativePath) {
       scheduleStructuralSync();
       return;
@@ -289,12 +291,31 @@ export async function runHotDevChild(options: {
     });
   };
 
-  const addWatcher = (watcher: FSWatcher | null): void => {
-    if (watcher) {
-      watchers.push(watcher);
+  const ensureRoutesWatcher = async (): Promise<void> => {
+    if (routesWatcher || !(await existsPath(resolved.routesDir))) {
+      return;
+    }
+
+    try {
+      routesWatcher = watch(resolved.routesDir, { recursive: true }, (eventType, fileName) => {
+        const nestedPath = toNormalizedWatchPath(fileName);
+        const relativePath = nestedPath ? `routes/${nestedPath}` : "routes";
+        handleAppEvent(eventType, relativePath);
+      });
+    } catch {
+      log(`recursive route watching unavailable for ${resolved.routesDir}; route topology updates may require a restart`);
     }
   };
 
+  const refreshRoutesWatcher = async (): Promise<void> => {
+    if (routesWatcher) {
+      routesWatcher.close();
+      routesWatcher = null;
+    }
+
+    await ensureRoutesWatcher();
+  };
+
   const cleanup = async (options: {
     preserveServer: boolean;
   }): Promise<void> => {
@@ -303,9 +324,12 @@ export async function runHotDevChild(options: {
       structuralSyncTimer = undefined;
     }
 
-    for (const watcher of watchers.splice(0, watchers.length)) {
-      watcher.close();
-    }
+    routesWatcher?.close();
+    routesWatcher = null;
+    appWatcher?.close();
+    appWatcher = null;
+    configWatcher?.close();
+    configWatcher = null;
 
     if (clientWatch) {
       await clientWatch.stop();
@@ -318,31 +342,38 @@ export async function runHotDevChild(options: {
     }
   };
 
+  await refreshRoutesWatcher();
+
   try {
-    addWatcher(
-      watch(resolved.appDir, { recursive: true }, (eventType, fileName) => {
-        handleAppEvent(eventType, fileName);
-      }),
-    );
+    appWatcher = watch(resolved.appDir, (eventType, fileName) => {
+      const relativePath = toNormalizedWatchPath(fileName);
+      if (relativePath === "routes" && eventType === "rename") {
+        void refreshRoutesWatcher();
+      }
+
+      handleAppEvent(eventType, relativePath);
+    });
   } catch {
-    log(`recursive file watching unavailable for ${resolved.appDir}; dev route topology updates may require a restart`);
+    log(`top-level app watching unavailable for ${resolved.appDir}; route topology updates may require a restart`);
   }
 
   try {
-    addWatcher(
-      watch(options.cwd, (eventType, fileName) => {
-        if (typeof fileName !== "string" || !isConfigFileName(fileName)) {
-          return;
-        }
-        if (eventType === "rename" || eventType === "change") {
-          void restartForConfigChange();
-        }
-      }),
-    );
+    configWatcher = watch(options.cwd, (eventType, fileName) => {
+      const configFileName = toNormalizedWatchPath(fileName);
+      if (!configFileName || !isConfigFileName(configFileName)) {
+        return;
+      }
+      if (eventType === "rename" || eventType === "change") {
+        void restartForConfigChange();
+      }
+    });
   } catch {
     log(`config file watching unavailable for ${options.cwd}; config changes may require a manual restart`);
   }
 
+  await enqueueStructuralSync("bootstrap");
+  await refreshRoutesWatcher();
+
   if (import.meta.hot) {
     import.meta.hot.dispose(async (data: DevHotData) => {
       data.bunServer = bunServer;
@@ -352,8 +383,6 @@ export async function runHotDevChild(options: {
     });
   }
 
-  await enqueueStructuralSync("bootstrap");
-
   if (hotData.bunServer && bunServer) {
     publishReload("server-runtime");
   }

package/framework/cli/scaffold.ts

@@ -6,6 +6,23 @@ interface ScaffoldFile {
   content: string;
 }
 
+interface FrameworkPackageManifest {
+  version?: string;
+  devDependencies?: Record<string, string>;
+}
+
+const DEFAULT_FRAMEWORK_VERSION = "0.0.0";
+const DEFAULT_TYPESCRIPT_VERSION = "^5";
+const DEFAULT_BUN_TYPES_VERSION = "latest";
+const DEFAULT_REACT_TYPES_VERSION = "^19";
+const FAVICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96">
+  <rect width="96" height="96" rx="20" fill="#111827"/>
+  <path d="M25 28h20c13.807 0 25 11.193 25 25S58.807 78 45 78H25V28Zm18 40c8.837 0 16-7.163 16-16s-7.163-16-16-16h-8v32h8Z" fill="#f9fafb"/>
+</svg>
+`;
+
+let frameworkPackageManifestPromise: Promise<FrameworkPackageManifest> | null = null;
+
 async function writeIfMissing(filePath: string, content: string, force: boolean): Promise<void> {
   if (!force && await existsPath(filePath)) {
     return;
@@ -14,8 +31,115 @@ async function writeIfMissing(filePath: string, content: string, force: boolean)
   await writeText(filePath, content);
 }
 
-function templateFiles(cwd: string): ScaffoldFile[] {
+function getFrameworkPackageManifest(): Promise<FrameworkPackageManifest> {
+  if (!frameworkPackageManifestPromise) {
+    const packageJsonPath = path.resolve(import.meta.dir, "../../package.json");
+    frameworkPackageManifestPromise = Bun.file(packageJsonPath).json() as Promise<FrameworkPackageManifest>;
+  }
+
+  return frameworkPackageManifestPromise;
+}
+
+function normalizePackageName(cwd: string): string {
+  const baseName = path.basename(path.resolve(cwd));
+  const normalized = baseName
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/[._-]{2,}/g, "-")
+    .replace(/^[._-]+|[._-]+$/g, "");
+
+  return normalized || "rbssr-app";
+}
+
+function createPackageJsonContent(options: {
+  cwd: string;
+  frameworkVersion: string;
+  typescriptVersion: string;
+  bunTypesVersion: string;
+  reactTypesVersion: string;
+  reactDomTypesVersion: string;
+}): string {
+  const packageJson = {
+    name: normalizePackageName(options.cwd),
+    version: "0.0.0",
+    private: true,
+    type: "module",
+    scripts: {
+      dev: "rbssr dev",
+      build: "rbssr build",
+      start: "rbssr start",
+      typecheck: "bunx tsc --noEmit",
+    },
+    dependencies: {
+      "react-bun-ssr": options.frameworkVersion,
+      react: "^19",
+      "react-dom": "^19",
+    },
+    devDependencies: {
+      "@types/react": options.reactTypesVersion,
+      "@types/react-dom": options.reactDomTypesVersion,
+      "bun-types": options.bunTypesVersion,
+      typescript: options.typescriptVersion,
+    },
+  };
+
+  return `${JSON.stringify(packageJson, null, 2)}\n`;
+}
+
+function createTsconfigContent(): string {
+  const tsconfig = {
+    compilerOptions: {
+      target: "ESNext",
+      module: "Preserve",
+      moduleResolution: "Bundler",
+      jsx: "react-jsx",
+      strict: true,
+      types: ["bun-types"],
+    },
+    include: ["app", "rbssr.config.ts"],
+  };
+
+  return `${JSON.stringify(tsconfig, null, 2)}\n`;
+}
+
+function createGitignoreContent(): string {
+  return `node_modules
+dist
+.rbssr
+.env
+.env.local
+.DS_Store
+`;
+}
+
+async function templateFiles(cwd: string): Promise<ScaffoldFile[]> {
+  const frameworkPackage = await getFrameworkPackageManifest();
+  const frameworkVersion = frameworkPackage.version ?? DEFAULT_FRAMEWORK_VERSION;
+  const typescriptVersion = frameworkPackage.devDependencies?.typescript ?? DEFAULT_TYPESCRIPT_VERSION;
+  const bunTypesVersion = frameworkPackage.devDependencies?.["bun-types"] ?? DEFAULT_BUN_TYPES_VERSION;
+  const reactTypesVersion = frameworkPackage.devDependencies?.["@types/react"] ?? DEFAULT_REACT_TYPES_VERSION;
+  const reactDomTypesVersion = frameworkPackage.devDependencies?.["@types/react-dom"] ?? DEFAULT_REACT_TYPES_VERSION;
+
   return [
+    {
+      filePath: path.join(cwd, "package.json"),
+      content: createPackageJsonContent({
+        cwd,
+        frameworkVersion,
+        typescriptVersion,
+        bunTypesVersion,
+        reactTypesVersion,
+        reactDomTypesVersion,
+      }),
+    },
+    {
+      filePath: path.join(cwd, "tsconfig.json"),
+      content: createTsconfigContent(),
+    },
+    {
+      filePath: path.join(cwd, ".gitignore"),
+      content: createGitignoreContent(),
+    },
     {
       filePath: path.join(cwd, "rbssr.config.ts"),
       content: `import { defineConfig } from "react-bun-ssr";
@@ -29,14 +153,17 @@ export default defineConfig({
     {
       filePath: path.join(cwd, "app/root.tsx"),
       content: `import { Outlet } from "react-bun-ssr/route";
+import styles from "./root.module.css";
 
 export default function RootLayout() {
   return (
-    <main className="shell">
-      <header className="top">
+    <main className={styles.shell}>
+      <header className={styles.top}>
         <h1>react-bun-ssr</h1>
       </header>
-      <Outlet />
+      <section className={styles.content}>
+        <Outlet />
+      </section>
     </main>
   );
 }
@@ -44,6 +171,53 @@ export default function RootLayout() {
 export function head() {
   return <title>react-bun-ssr app</title>;
 }
+`,
+    },
+    {
+      filePath: path.join(cwd, "app/root.module.css"),
+      content: `:global(*) {
+  box-sizing: border-box;
+}
+
+:global(html) {
+  font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
+  background: linear-gradient(180deg, #f8fafc 0%, #e2e8f0 100%);
+  color: #0f172a;
+}
+
+:global(body) {
+  margin: 0;
+}
+
+.shell {
+  min-height: 100vh;
+  width: min(100%, 72rem);
+  margin: 0 auto;
+  padding: 3rem 1.5rem 4rem;
+}
+
+.top {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 2rem;
+}
+
+.top h1 {
+  margin: 0;
+  font-size: clamp(2rem, 5vw, 3.5rem);
+  line-height: 1;
+  letter-spacing: -0.04em;
+}
+
+.content {
+  padding: 1.5rem;
+  border: 1px solid rgba(15, 23, 42, 0.08);
+  border-radius: 1.5rem;
+  background: rgba(255, 255, 255, 0.84);
+  box-shadow: 0 24px 60px rgba(15, 23, 42, 0.12);
+  backdrop-filter: blur(18px);
+}
 `,
     },
     {
@@ -87,11 +261,15 @@ export const middleware: Middleware = async (ctx, next) => {
 };
 `,
     },
+    {
+      filePath: path.join(cwd, "app/public/favicon.svg"),
+      content: FAVICON_SVG,
+    },
   ];
 }
 
 export async function scaffoldApp(cwd: string, options: { force: boolean }): Promise<void> {
-  for (const file of templateFiles(cwd)) {
+  for (const file of await templateFiles(cwd)) {
     await writeIfMissing(file.filePath, file.content, options.force);
   }
 }

package/framework/runtime/client-runtime.tsx

@@ -17,11 +17,10 @@ import {
   type NavigationHistoryMode,
 } from "./navigation-api";
 import {
-  RBSSR_HEAD_MARKER_END_ATTR,
-  RBSSR_HEAD_MARKER_START_ATTR,
   RBSSR_PAYLOAD_SCRIPT_ID,
   RBSSR_ROUTER_SCRIPT_ID,
 } from "./runtime-constants";
+import { replaceManagedHead } from "./head-reconcile";
 import {
   createCatchAppTree,
   createErrorAppTree,
@@ -569,220 +568,6 @@ function createFallbackNotFoundRoute(rootModule: RouteModule): RouteModule {
   };
 }
 
-function nodeSignature(node: Node): string {
-  if (node.nodeType === Node.TEXT_NODE) {
-    return `text:${node.textContent ?? ""}`;
-  }
-
-  if (node.nodeType === Node.COMMENT_NODE) {
-    return `comment:${node.textContent ?? ""}`;
-  }
-
-  if (node.nodeType !== Node.ELEMENT_NODE) {
-    return `node:${node.nodeType}`;
-  }
-
-  const element = node as Element;
-  const attrs = Array.from(element.attributes)
-    .map(attribute => `${attribute.name}=${attribute.value}`)
-    .sort((a, b) => a.localeCompare(b))
-    .join("|");
-
-  return `element:${element.tagName.toLowerCase()}:${attrs}:${element.innerHTML}`;
-}
-
-function isIgnorableTextNode(node: Node): boolean {
-  return node.nodeType === Node.TEXT_NODE && (node.textContent ?? "").trim().length === 0;
-}
-
-function getManagedHeadNodes(startMarker: Element, endMarker: Element): Node[] {
-  const nodes: Node[] = [];
-  let cursor = startMarker.nextSibling;
-  while (cursor && cursor !== endMarker) {
-    nodes.push(cursor);
-    cursor = cursor.nextSibling;
-  }
-  return nodes;
-}
-
-function removeNode(node: Node): void {
-  if (node.parentNode) {
-    node.parentNode.removeChild(node);
-  }
-}
-
-function isStylesheetLinkNode(node: Node): node is HTMLLinkElement {
-  if (node.nodeType !== Node.ELEMENT_NODE) {
-    return false;
-  }
-
-  const element = node as Element;
-  return (
-    element.tagName.toLowerCase() === "link"
-    && (element.getAttribute("rel")?.toLowerCase() ?? "") === "stylesheet"
-    && Boolean(element.getAttribute("href"))
-  );
-}
-
-function toAbsoluteHref(href: string): string {
-  return new URL(href, document.baseURI).toString();
-}
-
-function waitForStylesheetLoad(link: HTMLLinkElement): Promise<void> {
-  const sheet = link.sheet;
-  if (sheet) {
-    return Promise.resolve();
-  }
-
-  return new Promise(resolve => {
-    const finish = () => {
-      link.removeEventListener("load", finish);
-      link.removeEventListener("error", finish);
-      resolve();
-    };
-
-    link.addEventListener("load", finish, { once: true });
-    link.addEventListener("error", finish, { once: true });
-  });
-}
-
-async function reconcileStylesheetLinks(options: {
-  head: HTMLHeadElement;
-  desiredStylesheetHrefs: string[];
-}): Promise<void> {
-  const desiredAbsoluteHrefs = options.desiredStylesheetHrefs.map(toAbsoluteHref);
-  const existingLinks = Array.from(
-    options.head.querySelectorAll('link[rel="stylesheet"][href]'),
-  ) as HTMLLinkElement[];
-
-  const existingByAbsoluteHref = new Map<string, HTMLLinkElement[]>();
-  for (const link of existingLinks) {
-    const href = link.getAttribute("href");
-    if (!href) {
-      continue;
-    }
-    const absoluteHref = toAbsoluteHref(href);
-    const list = existingByAbsoluteHref.get(absoluteHref) ?? [];
-    list.push(link);
-    existingByAbsoluteHref.set(absoluteHref, list);
-  }
-
-  const waitForLoads: Promise<void>[] = [];
-  for (let index = 0; index < options.desiredStylesheetHrefs.length; index += 1) {
-    const href = options.desiredStylesheetHrefs[index]!;
-    const absoluteHref = desiredAbsoluteHrefs[index]!;
-    const existing = existingByAbsoluteHref.get(absoluteHref)?.[0];
-    if (existing) {
-      waitForLoads.push(waitForStylesheetLoad(existing));
-      continue;
-    }
-
-    const link = document.createElement("link");
-    link.setAttribute("rel", "stylesheet");
-    link.setAttribute("href", href);
-    options.head.appendChild(link);
-    waitForLoads.push(waitForStylesheetLoad(link));
-  }
-
-  const seen = new Set<string>();
-  for (const link of Array.from(options.head.querySelectorAll('link[rel="stylesheet"][href]'))) {
-    const href = link.getAttribute("href");
-    if (!href) {
-      continue;
-    }
-
-    const absoluteHref = toAbsoluteHref(href);
-    if (seen.has(absoluteHref)) {
-      removeNode(link);
-      continue;
-    }
-
-    seen.add(absoluteHref);
-  }
-
-  await Promise.all(waitForLoads);
-}
-
-async function replaceManagedHead(headHtml: string): Promise<void> {
-  const head = document.head;
-  const startMarker = head.querySelector(`meta[${RBSSR_HEAD_MARKER_START_ATTR}]`);
-  const endMarker = head.querySelector(`meta[${RBSSR_HEAD_MARKER_END_ATTR}]`);
-
-  if (!startMarker || !endMarker || startMarker === endMarker) {
-    return;
-  }
-
-  const template = document.createElement("template");
-  template.innerHTML = headHtml;
-
-  const desiredStylesheetHrefs = Array.from(template.content.querySelectorAll('link[rel="stylesheet"][href]'))
-    .map(link => link.getAttribute("href"))
-    .filter((value): value is string => Boolean(value));
-  for (const styleNode of Array.from(template.content.querySelectorAll('link[rel="stylesheet"][href]'))) {
-    removeNode(styleNode);
-  }
-
-  const desiredNodes = Array.from(template.content.childNodes).filter(node => !isIgnorableTextNode(node));
-  const currentNodes = getManagedHeadNodes(startMarker, endMarker).filter(node => {
-    if (isIgnorableTextNode(node)) {
-      return false;
-    }
-
-    if (isStylesheetLinkNode(node)) {
-      return false;
-    }
-
-    return true;
-  });
-  const unusedCurrentNodes = new Set(currentNodes);
-
-  let cursor = startMarker.nextSibling;
-
-  for (const desiredNode of desiredNodes) {
-    while (cursor && cursor !== endMarker && isIgnorableTextNode(cursor)) {
-      const next = cursor.nextSibling;
-      removeNode(cursor);
-      cursor = next;
-    }
-
-    const desiredSignature = nodeSignature(desiredNode);
-
-    if (cursor && cursor !== endMarker && nodeSignature(cursor) === desiredSignature) {
-      unusedCurrentNodes.delete(cursor);
-      cursor = cursor.nextSibling;
-      continue;
-    }
-
-    let matchedNode: Node | null = null;
-    for (const currentNode of currentNodes) {
-      if (!unusedCurrentNodes.has(currentNode)) {
-        continue;
-      }
-      if (nodeSignature(currentNode) === desiredSignature) {
-        matchedNode = currentNode;
-        break;
-      }
-    }
-
-    if (matchedNode) {
-      unusedCurrentNodes.delete(matchedNode);
-      head.insertBefore(matchedNode, cursor ?? endMarker);
-      continue;
-    }
-
-    head.insertBefore(desiredNode.cloneNode(true), cursor ?? endMarker);
-  }
-
-  for (const leftover of unusedCurrentNodes) {
-    removeNode(leftover);
-  }
-
-  await reconcileStylesheetLinks({
-    head,
-    desiredStylesheetHrefs,
-  });
-}
-
 async function renderTransitionInitial(
   chunk: TransitionInitialChunk,
   toUrl: URL,

package/framework/runtime/doctype-stream.ts

@@ -0,0 +1,38 @@
+const DOCTYPE = new TextEncoder().encode("<!doctype html>");
+
+export function prependDoctypeStream(stream: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
+  let reader: ReadableStreamDefaultReader<Uint8Array> | null = null;
+
+  return new ReadableStream<Uint8Array>({
+    async start(controller) {
+      controller.enqueue(DOCTYPE);
+      reader = stream.getReader();
+
+      try {
+        while (true) {
+          const result = await reader.read();
+          if (result.done) {
+            break;
+          }
+          controller.enqueue(result.value);
+        }
+        controller.close();
+      } catch (error) {
+        controller.error(error);
+      } finally {
+        const activeReader = reader;
+        reader = null;
+        activeReader?.releaseLock();
+      }
+    },
+    async cancel(reason) {
+      const activeReader = reader;
+      if (activeReader) {
+        await activeReader.cancel(reason);
+        return;
+      }
+
+      await stream.cancel(reason);
+    },
+  });
+}

package/framework/runtime/head-reconcile.ts

@@ -0,0 +1,270 @@
+import {
+  RBSSR_HEAD_MARKER_END_ATTR,
+  RBSSR_HEAD_MARKER_START_ATTR,
+} from "./runtime-constants";
+
+const ELEMENT_NODE = 1;
+const TEXT_NODE = 3;
+const COMMENT_NODE = 8;
+
+export function isContentInsensitiveHeadTag(tagName: string): boolean {
+  const normalized = tagName.toLowerCase();
+  return normalized === "script" || normalized === "style" || normalized === "noscript";
+}
+
+function normalizeNodeText(value: string): string {
+  return value.replace(/\s+/g, " ").trim();
+}
+
+export function nodeSignature(node: Node): string {
+  if (node.nodeType === TEXT_NODE) {
+    return `text:${node.textContent ?? ""}`;
+  }
+
+  if (node.nodeType === COMMENT_NODE) {
+    return `comment:${node.textContent ?? ""}`;
+  }
+
+  if (node.nodeType !== ELEMENT_NODE) {
+    return `node:${node.nodeType}`;
+  }
+
+  const element = node as Element;
+  const tagName = element.tagName.toLowerCase();
+  const attrs = Array.from(element.attributes)
+    .map(attribute => `${attribute.name}=${attribute.value}`)
+    .sort((a, b) => a.localeCompare(b))
+    .join("|");
+
+  if (isContentInsensitiveHeadTag(tagName)) {
+    return `element:${tagName}:${attrs}`;
+  }
+
+  if (tagName === "title") {
+    return `element:${tagName}:${attrs}:${normalizeNodeText(element.textContent ?? "")}`;
+  }
+
+  // Keep generic element identity structural and cheap: no innerHTML serialization.
+  return `element:${tagName}:${attrs}:${normalizeNodeText(element.textContent ?? "")}:${element.childElementCount}`;
+}
+
+function isIgnorableTextNode(node: Node): boolean {
+  return node.nodeType === TEXT_NODE && (node.textContent ?? "").trim().length === 0;
+}
+
+function getManagedHeadNodes(startMarker: Element, endMarker: Element): Node[] {
+  const nodes: Node[] = [];
+  let cursor = startMarker.nextSibling;
+  while (cursor && cursor !== endMarker) {
+    nodes.push(cursor);
+    cursor = cursor.nextSibling;
+  }
+  return nodes;
+}
+
+function removeNode(node: Node): void {
+  if (node.parentNode) {
+    node.parentNode.removeChild(node);
+  }
+}
+
+function isStylesheetLinkNode(node: Node): node is HTMLLinkElement {
+  if (node.nodeType !== ELEMENT_NODE) {
+    return false;
+  }
+
+  const element = node as Element;
+  return (
+    element.tagName.toLowerCase() === "link"
+    && (element.getAttribute("rel")?.toLowerCase() ?? "") === "stylesheet"
+    && Boolean(element.getAttribute("href"))
+  );
+}
+
+function toAbsoluteHref(href: string, baseUri: string): string {
+  return new URL(href, baseUri).toString();
+}
+
+function resolveBaseUri(documentRef: Document): string {
+  const candidate = documentRef.baseURI;
+  if (typeof candidate === "string" && candidate.length > 0) {
+    try {
+      const parsed = new URL(candidate);
+      if (parsed.protocol !== "about:") {
+        return candidate;
+      }
+    } catch {
+      // fall back below
+    }
+  }
+
+  return "http://localhost/";
+}
+
+function waitForStylesheetLoad(link: HTMLLinkElement): Promise<void> {
+  if (!link.ownerDocument.defaultView || link.sheet) {
+    return Promise.resolve();
+  }
+
+  return new Promise(resolve => {
+    const finish = () => {
+      link.removeEventListener("load", finish);
+      link.removeEventListener("error", finish);
+      resolve();
+    };
+
+    link.addEventListener("load", finish, { once: true });
+    link.addEventListener("error", finish, { once: true });
+  });
+}
+
+async function reconcileStylesheetLinks(options: {
+  head: HTMLHeadElement;
+  desiredStylesheetHrefs: string[];
+  baseUri: string;
+}): Promise<void> {
+  const desiredAbsoluteHrefs = options.desiredStylesheetHrefs.map(href => toAbsoluteHref(href, options.baseUri));
+  const existingLinks = Array.from(
+    options.head.querySelectorAll('link[rel="stylesheet"][href]'),
+  ) as HTMLLinkElement[];
+
+  const existingByAbsoluteHref = new Map<string, HTMLLinkElement[]>();
+  for (const link of existingLinks) {
+    const href = link.getAttribute("href");
+    if (!href) {
+      continue;
+    }
+    const absoluteHref = toAbsoluteHref(href, options.baseUri);
+    const list = existingByAbsoluteHref.get(absoluteHref) ?? [];
+    list.push(link);
+    existingByAbsoluteHref.set(absoluteHref, list);
+  }
+
+  const waitForLoads: Promise<void>[] = [];
+  for (let index = 0; index < options.desiredStylesheetHrefs.length; index += 1) {
+    const href = options.desiredStylesheetHrefs[index]!;
+    const absoluteHref = desiredAbsoluteHrefs[index]!;
+    const existing = existingByAbsoluteHref.get(absoluteHref)?.[0];
+    if (existing) {
+      waitForLoads.push(waitForStylesheetLoad(existing));
+      continue;
+    }
+
+    const link = options.head.ownerDocument.createElement("link");
+    link.setAttribute("rel", "stylesheet");
+    link.setAttribute("href", href);
+    options.head.appendChild(link);
+    waitForLoads.push(waitForStylesheetLoad(link));
+  }
+
+  const seen = new Set<string>();
+  for (const link of Array.from(options.head.querySelectorAll('link[rel="stylesheet"][href]'))) {
+    const href = link.getAttribute("href");
+    if (!href) {
+      continue;
+    }
+
+    const absoluteHref = toAbsoluteHref(href, options.baseUri);
+    if (seen.has(absoluteHref)) {
+      removeNode(link);
+      continue;
+    }
+
+    seen.add(absoluteHref);
+  }
+
+  await Promise.all(waitForLoads);
+}
+
+export async function replaceManagedHead(
+  headHtml: string,
+  options: {
+    documentRef?: Document;
+    startMarkerAttr?: string;
+    endMarkerAttr?: string;
+  } = {},
+): Promise<void> {
+  const documentRef = options.documentRef ?? document;
+  const startMarkerAttr = options.startMarkerAttr ?? RBSSR_HEAD_MARKER_START_ATTR;
+  const endMarkerAttr = options.endMarkerAttr ?? RBSSR_HEAD_MARKER_END_ATTR;
+
+  const head = documentRef.head;
+  const startMarker = head.querySelector(`meta[${startMarkerAttr}]`);
+  const endMarker = head.querySelector(`meta[${endMarkerAttr}]`);
+
+  if (!startMarker || !endMarker || startMarker === endMarker) {
+    return;
+  }
+
+  const template = documentRef.createElement("template");
+  template.innerHTML = headHtml;
+
+  const desiredStylesheetHrefs = Array.from(template.content.querySelectorAll('link[rel="stylesheet"][href]'))
+    .map(link => link.getAttribute("href"))
+    .filter((value): value is string => Boolean(value));
+  for (const styleNode of Array.from(template.content.querySelectorAll('link[rel="stylesheet"][href]'))) {
+    removeNode(styleNode);
+  }
+
+  const desiredNodes = Array.from(template.content.childNodes).filter(node => !isIgnorableTextNode(node));
+  const currentNodes = getManagedHeadNodes(startMarker, endMarker).filter(node => {
+    if (isIgnorableTextNode(node)) {
+      return false;
+    }
+
+    if (isStylesheetLinkNode(node)) {
+      return false;
+    }
+
+    return true;
+  });
+  const unusedCurrentNodes = new Set(currentNodes);
+
+  let cursor = startMarker.nextSibling;
+
+  // Structural identity only: avoid subtree HTML serialization in signature checks.
+  for (const desiredNode of desiredNodes) {
+    while (cursor && cursor !== endMarker && isIgnorableTextNode(cursor)) {
+      const next = cursor.nextSibling;
+      removeNode(cursor);
+      cursor = next;
+    }
+
+    const desiredSignature = nodeSignature(desiredNode);
+
+    if (cursor && cursor !== endMarker && nodeSignature(cursor) === desiredSignature) {
+      unusedCurrentNodes.delete(cursor);
+      cursor = cursor.nextSibling;
+      continue;
+    }
+
+    let matchedNode: Node | null = null;
+    for (const currentNode of currentNodes) {
+      if (!unusedCurrentNodes.has(currentNode)) {
+        continue;
+      }
+      if (nodeSignature(currentNode) === desiredSignature) {
+        matchedNode = currentNode;
+        break;
+      }
+    }
+
+    if (matchedNode) {
+      unusedCurrentNodes.delete(matchedNode);
+      head.insertBefore(matchedNode, cursor ?? endMarker);
+      continue;
+    }
+
+    head.insertBefore(desiredNode.cloneNode(true), cursor ?? endMarker);
+  }
+
+  for (const leftover of unusedCurrentNodes) {
+    removeNode(leftover);
+  }
+
+  await reconcileStylesheetLinks({
+    head,
+    desiredStylesheetHrefs,
+    baseUri: resolveBaseUri(documentRef),
+  });
+}

package/framework/runtime/io.ts

@@ -80,7 +80,7 @@ export function sha256Short(input: HashInput): string {
 }
 
 export async function ensureDir(dirPath: string): Promise<void> {
-  runPosix(["mkdir", "-p", dirPath], `Failed to create directory: ${dirPath}`);
+  await runPosix(["mkdir", "-p", dirPath], `Failed to create directory: ${dirPath}`);
 }
 
 export async function ensureCleanDir(dirPath: string): Promise<void> {
@@ -89,7 +89,7 @@ export async function ensureCleanDir(dirPath: string): Promise<void> {
 }
 
 export async function removePath(targetPath: string): Promise<void> {
-  runPosix(["rm", "-rf", targetPath], `Failed to remove path: ${targetPath}`);
+  await runPosix(["rm", "-rf", targetPath], `Failed to remove path: ${targetPath}`);
 }
 
 export async function listEntries(dirPath: string): Promise<FileEntry[]> {
@@ -127,20 +127,23 @@ export async function makeTempDir(prefix: string): Promise<string> {
   return dirPath;
 }
 
-function runPosix(cmd: string[], context: string): void {
-  const result = Bun.spawnSync({
+async function runPosix(cmd: string[], context: string): Promise<void> {
+  const result = Bun.spawn({
     cmd,
     stdout: "pipe",
     stderr: "pipe",
   });
 
-  if (result.exitCode === 0) {
+  const exitCode = await result.exited;
+  if (exitCode === 0) {
     return;
   }
 
-  const decoder = new TextDecoder();
-  const stderr = result.stderr.length > 0 ? decoder.decode(result.stderr).trim() : "";
-  const stdout = result.stdout.length > 0 ? decoder.decode(result.stdout).trim() : "";
-  const details = stderr || stdout || `exit code ${result.exitCode}`;
+  const [stderr, stdout] = await Promise.all([
+    result.stderr ? new Response(result.stderr).text() : Promise.resolve(""),
+    result.stdout ? new Response(result.stdout).text() : Promise.resolve(""),
+  ]);
+
+  const details = stderr.trim() || stdout.trim() || `exit code ${exitCode}`;
   throw new Error(`[io] ${context} (${cmd.join(" ")}): ${details}`);
 }

package/framework/runtime/matcher.ts

@@ -6,8 +6,10 @@ import type {
   RouteSegment,
 } from "./types";
 
-// Bun FileSystemRouter is the runtime matcher used by the server.
-// This matcher is retained for lightweight unit coverage and internal utilities.
+// Bun FileSystemRouter is the runtime matcher used by the server for projected routes.
+// This matcher is used by server fallbacks and client transition matching.
+// It intentionally does first-match linear scanning and expects routes to be pre-ordered
+// by specificity (higher score first, then longer segment length, then routePath).
 function normalizePathname(pathname: string): string[] {
   if (!pathname || pathname === "/") {
     return [];

package/framework/runtime/render.tsx

@@ -10,6 +10,7 @@ import {
 } from "react";
 import { renderToReadableStream, renderToStaticMarkup, renderToString } from "react-dom/server";
 import type { DeferredSettleEntry } from "./deferred";
+import { prependDoctypeStream } from "./doctype-stream";
 import type {
   ClientRouterSnapshot,
   HydrationDocumentAssets,
@@ -361,36 +362,6 @@ function HtmlDocument(options: {
   );
 }
 
-function prependDoctype(stream: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
-  const encoder = new TextEncoder();
-  const doctype = encoder.encode("<!doctype html>");
-
-  return new ReadableStream<Uint8Array>({
-    async start(controller) {
-      controller.enqueue(doctype);
-      const reader = stream.getReader();
-
-      try {
-        while (true) {
-          const result = await reader.read();
-          if (result.done) {
-            break;
-          }
-          controller.enqueue(result.value);
-        }
-        controller.close();
-      } catch (error) {
-        controller.error(error);
-      } finally {
-        reader.releaseLock();
-      }
-    },
-    cancel(reason) {
-      void stream.cancel(reason);
-    },
-  });
-}
-
 export async function renderDocumentStream(options: {
   appTree: ReactElement;
   payload: RenderPayload;
@@ -410,7 +381,7 @@ export async function renderDocumentStream(options: {
     />,
   );
 
-  return prependDoctype(stream);
+  return prependDoctypeStream(stream);
 }
 
 export function renderDocument(options: {

package/framework/runtime/route-order.ts

@@ -0,0 +1,23 @@
+import type { RouteSegment } from "./types";
+
+export interface RouteSpecificityComparable {
+  score: number;
+  segments: RouteSegment[];
+  routePath: string;
+}
+
+export function sortRoutesBySpecificity<T extends RouteSpecificityComparable>(
+  routes: T[],
+): T[] {
+  return routes.sort((a, b) => {
+    if (a.score !== b.score) {
+      return b.score - a.score;
+    }
+
+    if (a.segments.length !== b.segments.length) {
+      return b.segments.length - a.segments.length;
+    }
+
+    return a.routePath.localeCompare(b.routePath);
+  });
+}

package/framework/runtime/route-scanner.ts

@@ -14,6 +14,7 @@ import {
   toRouteId,
   trimFileExtension,
 } from "./utils";
+import { sortRoutesBySpecificity } from "./route-order";
 
 const PAGE_FILE_RE = /\.(tsx|jsx|ts|js|md|mdx)$/;
 const LAYOUT_FILE_RE = /\.(tsx|jsx|ts|js)$/;
@@ -103,22 +104,6 @@ function getAncestorDirs(relativeDir: string): string[] {
   return result;
 }
 
-function sortRoutes<T extends { score: number; segments: RouteSegment[]; routePath: string }>(
-  routes: T[],
-): T[] {
-  return routes.sort((a, b) => {
-    if (a.score !== b.score) {
-      return b.score - a.score;
-    }
-
-    if (a.segments.length !== b.segments.length) {
-      return b.segments.length - a.segments.length;
-    }
-
-    return a.routePath.localeCompare(b.routePath);
-  });
-}
-
 export async function scanRoutes(
   routesDir: string,
   options: {
@@ -236,7 +221,7 @@ export async function scanRoutes(
   const pageRoutes = await Promise.all(pageRouteTasks);
 
   return {
-    pages: sortRoutes(pageRoutes),
-    api: sortRoutes(apiRoutes),
+    pages: sortRoutesBySpecificity(pageRoutes),
+    api: sortRoutesBySpecificity(apiRoutes),
   };
 }

package/framework/runtime/router.ts

@@ -17,6 +17,33 @@ export interface RouterNavigateInfo {
 
 export type RouterNavigateListener = (nextUrl: URL) => void;
 
+export interface RouterNavigateListenerStore {
+  clearRenderListeners(): void;
+  registerRenderListener(listener: RouterNavigateListener): void;
+  promoteRenderListenersToActive(): void;
+  getActiveListeners(): readonly RouterNavigateListener[];
+}
+
+export function createRouterNavigateListenerStore(): RouterNavigateListenerStore {
+  let renderListeners: RouterNavigateListener[] = [];
+  let activeListeners: RouterNavigateListener[] = [];
+
+  return {
+    clearRenderListeners() {
+      renderListeners = [];
+    },
+    registerRenderListener(listener) {
+      renderListeners.push(listener);
+    },
+    promoteRenderListenersToActive() {
+      activeListeners = renderListeners;
+    },
+    getActiveListeners() {
+      return activeListeners;
+    },
+  };
+}
+
 export function notifyRouterNavigateListeners(
   listeners: readonly RouterNavigateListener[],
   nextUrl: URL,
@@ -102,14 +129,22 @@ function createClientRouter(onNavigate: Router["onNavigate"]): Router {
 }
 
 export function useRouter(): Router {
-  const navigateListenersRef = useRef<RouterNavigateListener[]>([]);
+  const navigateListenerStoreRef = useRef<RouterNavigateListenerStore | null>(null);
+  if (navigateListenerStoreRef.current === null) {
+    navigateListenerStoreRef.current = createRouterNavigateListenerStore();
+  }
+  const navigateListenerStore = navigateListenerStoreRef.current;
   const didEmitInitialNavigationRef = useRef(false);
-  navigateListenersRef.current = [];
+  navigateListenerStore.clearRenderListeners();
 
   const onNavigate = useCallback<Router["onNavigate"]>((listener) => {
-    navigateListenersRef.current.push(listener);
+    navigateListenerStoreRef.current?.registerRenderListener(listener);
   }, []);
 
+  useEffect(() => {
+    navigateListenerStoreRef.current?.promoteRenderListenersToActive();
+  });
+
   useEffect(() => {
     if (typeof window === "undefined") {
       return;
@@ -118,7 +153,7 @@ export function useRouter(): Router {
     if (!didEmitInitialNavigationRef.current) {
       didEmitInitialNavigationRef.current = true;
       notifyRouterNavigateListeners(
-        navigateListenersRef.current,
+        navigateListenerStore.getActiveListeners(),
         new URL(window.location.href),
       );
     }
@@ -133,7 +168,10 @@ export function useRouter(): Router {
         }
 
         unsubscribe = runtime.subscribeToNavigation((info) => {
-          notifyRouterNavigateListeners(navigateListenersRef.current, info.nextUrl);
+          notifyRouterNavigateListeners(
+            navigateListenerStoreRef.current?.getActiveListeners() ?? [],
+            info.nextUrl,
+          );
         });
       })
       .catch(() => undefined);

package/framework/runtime/server.ts

@@ -68,6 +68,7 @@ import {
   sanitizeErrorMessage,
   stableHash,
 } from "./utils";
+import { sortRoutesBySpecificity } from "./route-order";
 
 type ResponseKind = "static" | "html" | "api" | "internal-dev" | "internal-transition";
 
@@ -374,8 +375,8 @@ function resolveAllRouteAssets(options: {
   return options.runtimeOptions.buildManifest?.routes ?? {};
 }
 
-function toClientRouteSnapshots(routes: PageRouteDefinition[]): ClientRouteSnapshot[] {
-  return routes.map(route => ({
+export function toClientRouteSnapshots(routes: PageRouteDefinition[]): ClientRouteSnapshot[] {
+  return sortRoutesBySpecificity([...routes]).map(route => ({
     id: route.id,
     routePath: route.routePath,
     segments: route.segments,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-bun-ssr",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -12,7 +12,23 @@
     "type": "git",
     "url": "git+https://github.com/react-formation/react-bun-ssr.git"
   },
-  "homepage": "https://github.com/react-formation/react-bun-ssr",
+  "description": "Bun-native SSR React framework with file-based routing, loaders, actions, streaming SSR. No Node adapter layer.",
+  "keywords": [
+    "bun",
+    "ssr",
+    "react",
+    "framework",
+    "file-based-routing",
+    "streaming",
+    "hydration",
+    "loaders",
+    "actions",
+    "markdown",
+    "rbssr",
+    "server-rendering",
+    "bun-native"
+  ],
+  "homepage": "https://react-bun-ssr.dev",
   "bugs": {
     "url": "https://github.com/react-formation/react-bun-ssr/issues"
   },
@@ -27,6 +43,7 @@
     "framework",
     "README.md"
   ],
+  "license": "MIT",
   "bin": {
     "rbssr": "bin/rbssr.ts"
   },
@@ -67,6 +84,7 @@
     "react-dom": "^19"
   },
   "devDependencies": {
+    "@happy-dom/global-registrator": "^20.8.3",
     "@playwright/test": "^1.54.2",
     "@types/react": "^19",
     "@types/react-dom": "^19",