brustjs 0.1.0-alpha

package/runtime/routes.ts

@@ -0,0 +1,1406 @@
+import { createContext, createElement, useContext, type ComponentType, type ReactNode } from 'react'
+// React 19 split react-dom/server by runtime: under Bun the bare 'react-dom/server'
+// resolves to the web-streams build (server.bun.js), which only exports
+// renderToReadableStream. renderToPipeableStream (Node streams — what our Writable
+// sink + onAllReady/onShellReady path uses) lives in the .node build. Import it
+// explicitly so SSR works on the react@19 we declare as a peer (React 18 shipped
+// renderToPipeableStream in the bun build, which is why this was silently fine).
+import { renderToPipeableStream } from 'react-dom/server.node'
+import { Writable } from 'node:stream'
+import { Buffer } from 'node:buffer'
+// @ts-expect-error - index.js is generated by napi-rs at build time
+import * as native from './index.js'
+import { renderBranchStreaming } from './render/stream.ts'
+import { loadIslandManifest, resolveIslandContext } from './islands/native-render.ts'
+import type { ActionDef } from './actions.ts'
+
+// Permanently-unaborted AbortSignal sentinel for non-SSE routes.
+// The controller is held in module scope and never .abort()-ed, keeping
+// the signal alive in the unaborted state. Do NOT use AbortSignal.abort()
+// — that creates an already-aborted signal which would fire any
+// addEventListener('abort') listener synchronously and break defensive
+// cleanup code.
+const _neverAbortsController = new AbortController()
+export const NEVER_ABORTS: AbortSignal = _neverAbortsController.signal
+
+/** Structured view of the request, parsed once in Rust and shipped in the
+ * JSON envelope. Header names are lower-cased. Cookies are parsed from the
+ * Cookie header. `search` is the query string parsed as key→value (last
+ * occurrence wins on duplicates). */
+export interface BrustRequest {
+  method: string
+  /** Full request URL path including query string, e.g. `/foo?bar=1`. */
+  url: string
+  headers: Record<string, string>
+  cookies: Record<string, string>
+  search: Record<string, string>
+  /** AbortSignal that fires when the client disconnects mid-request.
+   * SSE-only in MVP — non-SSE routes receive NEVER_ABORTS (a permanently-
+   * unaborted shared sentinel; signal.aborted === false forever). Real
+   * disconnect detection for render/action is a follow-up. */
+  signal: AbortSignal
+}
+
+/** Handler module shape — what `() => Promise<WsHandlers>` resolves to.
+ *  open/message/close are all OPTIONAL — a no-op WebSocket (handshake
+ *  only, e.g. liveness probe) is a valid use case. */
+export interface WsHandlers {
+  /** Called once after the 101 handshake completes. Use this to record
+   * the socket in your in-memory map, send a hello frame, etc.
+   * Throwing here closes the conn with 1011 (Internal Error); on_close
+   * does NOT fire (we never reached steady state). */
+  open?: (
+    socket: WsSocket,
+    ctx: { req: BrustRequest; subprotocol: string | null },
+  ) => void | Promise<void>
+  /** Called per incoming message frame. data is string for Text frames,
+   * Uint8Array for Binary. Throwing here is logged but the conn stays
+   * open — one bad message shouldn't kill the conn; wrap in try/catch
+   * for strict-close semantics. */
+  message?: (socket: WsSocket, data: string | Uint8Array) => void | Promise<void>
+  /** Called exactly ONCE when the conn closes EXCEPT when the author
+   * called socket.close themselves. Code/reason from the RFC 6455
+   * close frame; 1006 for abnormal (RST), 1011 for pong timeout,
+   * 1001 for server shutdown. */
+  close?: (socket: WsSocket, code: number, reason: string) => void
+}
+
+/** The only handle the author touches inside a WsHandlers callback. */
+export interface WsSocket {
+  /** Send a frame. Text if data is string, Binary if Uint8Array. Returns
+   * a Promise that resolves when the TCP write completes (cooperative
+   * backpressure, same model as SSE napi.write). Rejects with a clear
+   * error if the conn is already closed. */
+  send(data: string | Uint8Array): Promise<void>
+  /** Initiate close with optional code (default 1000) and reason (default
+   * ''). Idempotent — second call is a no-op. on_close does NOT fire
+   * after this call. */
+  close(code?: number, reason?: string): void
+  /** Stable per-conn identifier. Useful as a Map key in author's
+   * in-memory connection registry. */
+  readonly id: bigint
+}
+
+export interface RouteContext<Params = Record<string, string>, Data = unknown> {
+  params: Params
+  path: string
+  /** Value returned by `route.loader`. Undefined if the route has no loader. */
+  data: Data
+  /** Bun Worker id rendering this request. null before the first registerRenderer
+   * return resolves (a brief window during boot). */
+  workerId: number | null
+  /** Structured request shape. Available to components for read-only inspection. */
+  req: BrustRequest
+}
+
+export interface ErrorBoundaryProps {
+  error: Error
+}
+
+export interface RouteCacheConfig {
+  /** Time-to-live in seconds. */
+  ttl_seconds: number
+  /** Request headers that affect content. Each becomes part of the cache key. */
+  vary?: string[]
+}
+
+/** Shape returned by a middleware or by the terminal `next()` (loader + render).
+ * Middleware can short-circuit by returning a RouteResponse without calling next,
+ * or call next() and mutate the returned response (status, headers). */
+export interface RouteResponse {
+  status: number
+  body: string
+  /** Extra response headers. Names are case-insensitive on the wire; Rust
+   * deduplicates by lower-casing internally. Skips collisions with the fixed
+   * Content-Type / Content-Length / Connection lines. */
+  headers?: Record<string, string>
+  /** Override the Content-Type emitted by Rust. Action returns set this to
+   * 'application/json; charset=utf-8'; middleware short-circuits with a
+   * raw string body can set 'text/plain'. Falls back to 'text/html' (render)
+   * or 'application/json' (action) when omitted. */
+  contentType?: string
+}
+
+/** Middleware contract — Express/Koa-style chain. Receives a structured
+ * request and a `next()` that runs the rest of the chain (eventually the
+ * loader + render). Return a `RouteResponse` to short-circuit, or call
+ * `await next()` and return its (possibly mutated) result. */
+export type Middleware = (
+  req: BrustRequest,
+  next: () => Promise<RouteResponse>,
+) => Promise<RouteResponse>
+
+export interface Route<Params = Record<string, string>, Data = unknown> {
+  /** Relative path segment (matchit syntax). Empty string `''` = layout-only
+   * (this node contributes nothing to the path; children attach to ancestors).
+   * Mutually exclusive with `index: true`. */
+  path?: string
+  /** Index route — matches the parent path exactly. Must be a leaf (no
+   * `children`, no `path`). Mutually exclusive with `path`. */
+  index?: boolean
+  /** TypeScript can't infer per-entry generics inside a `defineRoutes([...])`
+   * literal, so the array would force every Component to accept the default
+   * `RouteContext<Record<string, string>, unknown>` shape — components that
+   * narrow `Params` / `Data` would fail to type-check. Keep the field
+   * permissive here; each component self-declares its expected props. */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  Component?: ComponentType<any>
+  /** Optional async function that runs in the worker before rendering. Its
+   * return value becomes the component's `data` prop. Exceptions are caught
+   * by `errorBoundary` if declared (inherited from closest ancestor). */
+  loader?: (ctx: { params: Params; path: string; req: BrustRequest }) => Promise<Data>
+  /** Optional component invoked when Component or loader throws. Inherited
+   * by descendants when they don't define their own. */
+  errorBoundary?: ComponentType<ErrorBoundaryProps>
+  /** Opt-in cache. Cache config from the leaf only — parent's cache is
+   * ignored when the route is reached as part of a chain. */
+  cache?: RouteCacheConfig
+  /** Per-route middleware chain. Runs in declaration order; concatenated
+   * with parent middlewares (parent runs before child). Cache lookup
+   * still happens BEFORE any middleware (existing rule). */
+  middleware?: Middleware[]
+  /** Nested children. Each child's path is composed with this node's path
+   * via `joinPath` (see flattenRoutes). */
+  children?: Route[]
+  /** When set, this route streams a text/event-stream response. Cannot
+   * coexist with Component, loader, or children (validated at defineRoutes
+   * time). The framework auto-sends Content-Type, Cache-Control,
+   * X-Accel-Buffering, plus a `: ping\n\n` heartbeat every 15s (opt-out
+   * via sseOptions). The author returns ReadableStream<Uint8Array | string>;
+   * string chunks are UTF-8 encoded. Listen on req.signal for disconnect. */
+  sse?: (
+    req: BrustRequest,
+  ) => ReadableStream<Uint8Array | string> | Promise<ReadableStream<Uint8Array | string>>
+  sseOptions?: {
+    /** Auto-emit `: ping\n\n` every N ms. Default 15000. Set 0 to disable. */
+    heartbeatMs?: number
+  }
+  /** When set, this route accepts WebSocket upgrades. Cannot coexist
+   * with Component, loader, sse, or children (validated at defineRoutes
+   * time). The factory is invoked lazily by the WS dispatch path and
+   * cached per worker. The handler module may export `WsHandlers`
+   * directly OR as a `default` (the common `() => import('./ws-foo')`
+   * pattern returns a module namespace `{ default: WsHandlers }`);
+   * `handleWsConn` unwraps `.default` defensively at call time. */
+  websocket?: () => Promise<WsHandlers | { default: WsHandlers }>
+  wsOptions?: {
+    /** Server-initiated ping interval in ms. Default 30000. Set 0 to disable.
+     * Pong timeout = 2× pingMs; conn closes with code 1011 if no pong by then. */
+    pingMs?: number
+    /** Max message size in bytes. Default 1 048 576 (1 MB). Larger frames
+     * close the conn with 1009 (Message Too Big). */
+    maxMessageBytes?: number
+    /** Subprotocols the route supports (Sec-WebSocket-Protocol). Client's
+     * requested list is intersected with this; first match (in this declared
+     * order) wins and is reflected in Sec-WebSocket-Protocol response. */
+    subprotocols?: string[]
+  }
+  /** Sub-project J — render this route via the native (jinja) engine, not React.
+   * `Component` is REQUIRED (the JSX file is the source jsx-rustc compiles
+   * into `.brust/jinja/<Component.name>.jinja`). Loader-friendly: the loader's
+   * return value becomes the template context. */
+  native?: boolean
+}
+
+/** Internal post-flatten representation. Each FlatRoute is a single leaf or
+ * index route in the user's nested tree. Indexed by Rust's route_id (array
+ * position). Consumed by `makeRenderer` and structurally compatible with
+ * `brust.registerRoutes` (reads only `fullPath` and `cache`). */
+export interface FlatRoute {
+  /** Full path Rust matches against. Composed from the chain via joinPath. */
+  fullPath: string
+  /** Chain of Route nodes from root to leaf, inclusive. Renderer walks
+   * this top-down. */
+  chain: Route[]
+  /** Concatenated middleware from root → leaf. composeChain wraps right-to-left,
+   * so the first element here becomes the outermost wrap (runs first). */
+  middleware: Middleware[]
+  /** Closest errorBoundary in the chain (leaf wins; falls back up the chain). */
+  errorBoundary?: ComponentType<ErrorBoundaryProps>
+  /** Cache from the leaf only — no parent inheritance. */
+  cache?: RouteCacheConfig
+  /** Sub-project J — Component.name when leaf had `native: true`. Captured
+   * at flatten time (build-time AST identifier), so minifier-safe. */
+  nativeTemplate?: string
+}
+
+/** Compose a child's relative path onto a parent's base path.
+ *  - `rel === ''` (layout-only child) → returns `base` unchanged
+ *  - `rel` starts with `/` (absolute) → returns `rel` (only valid when base === '';
+ *    flattenRoutes rejects this case otherwise)
+ *  - otherwise → strip any trailing `/` from base, append `/${rel}` */
+export function joinPath(base: string, rel: string): string {
+  if (rel === '') return base
+  if (rel.startsWith('/')) return rel
+  const trimmedBase = base.endsWith('/') ? base.slice(0, -1) : base
+  return `${trimmedBase}/${rel}`
+}
+
+/** Validate a Route node's structural invariants in the context of its
+ * parent's basePath. Throws with a useful message at module top-level —
+ * route bugs fail loudly before brust.serve binds. */
+function validateRoute(r: Route, basePath: string): void {
+  if (r.index === true && r.path !== undefined) {
+    throw new Error(`route under "${basePath}": cannot set both index and path`)
+  }
+  if (r.index === true && r.children && r.children.length > 0) {
+    throw new Error(`route under "${basePath}": index route cannot have children`)
+  }
+  if (!r.index && r.path === undefined && !(r.children && r.children.length > 0)) {
+    throw new Error(`route under "${basePath}": must have path, index, or children`)
+  }
+  if (r.path?.startsWith('/') && basePath !== '') {
+    // Absolute children under a non-empty parent are a footgun (the child
+    // escapes the parent's URL space). Only allowed when the parent is
+    // layout-only (basePath === '').
+    throw new Error(
+      `route under "${basePath}": absolute child path "${r.path}" must be under a pathless ('') parent`,
+    )
+  }
+  if (r.native === true) {
+    const where = r.path ?? '(no path)'
+    if (r.Component === undefined) {
+      throw new Error(`Route ${where}: 'native: true' requires 'Component'`)
+    }
+    if (!r.Component.name || r.Component.name.length === 0) {
+      throw new Error(
+        `Route ${where}: 'native: true' Component must be a named function (got anonymous)`,
+      )
+    }
+    if (r.sse !== undefined) {
+      throw new Error(`Route ${where}: 'native: true' cannot coexist with 'sse'`)
+    }
+    if (r.websocket !== undefined) {
+      throw new Error(`Route ${where}: 'native: true' cannot coexist with 'websocket'`)
+    }
+    if (r.children !== undefined) {
+      throw new Error(`Route ${where}: 'native: true' cannot have nested children`)
+    }
+    if (r.cache !== undefined) {
+      throw new Error(`Route ${where}: 'native: true' cannot coexist with 'cache' (deferred)`)
+    }
+    // loader + middleware are EXPLICITLY allowed.
+  }
+  if (r.sse) {
+    const where = r.path ?? '(no path)'
+    if (r.Component !== undefined) {
+      throw new Error(`Route ${where}: 'sse' cannot coexist with 'Component'`)
+    }
+    if (r.loader !== undefined) {
+      throw new Error(`Route ${where}: 'sse' cannot coexist with 'loader'`)
+    }
+    if (r.children !== undefined) {
+      throw new Error(`Route ${where}: 'sse' cannot have nested children`)
+    }
+  }
+  if (r.websocket) {
+    const where = r.path ?? '(no path)'
+    if (r.Component !== undefined) {
+      throw new Error(`Route ${where}: 'websocket' cannot coexist with 'Component'`)
+    }
+    if (r.loader !== undefined) {
+      throw new Error(`Route ${where}: 'websocket' cannot coexist with 'loader'`)
+    }
+    if (r.sse !== undefined) {
+      throw new Error(`Route ${where}: 'websocket' cannot coexist with 'sse'`)
+    }
+    if (r.children !== undefined) {
+      throw new Error(`Route ${where}: 'websocket' cannot have nested children`)
+    }
+  }
+}
+
+/** Walk the nested route tree, emitting one FlatRoute per leaf or index node.
+ * Composes paths, middleware, errorBoundary, and cache per the rules in
+ * the design spec (§3). */
+export function flattenRoutes(routes: Route[]): FlatRoute[] {
+  const out: FlatRoute[] = []
+  walkRoutes(routes, [], '', out)
+  return out
+}
+
+function walkRoutes(
+  routes: Route[],
+  parentChain: Route[],
+  basePath: string,
+  out: FlatRoute[],
+): void {
+  for (const r of routes) {
+    validateRoute(r, basePath)
+    const chain = [...parentChain, r]
+
+    if (r.index === true) {
+      out.push(makeFlat(chain, basePath))
+      continue
+    }
+
+    const ownPath = r.path ?? ''
+    const myPath = joinPath(basePath, ownPath)
+
+    if (r.children && r.children.length > 0) {
+      walkRoutes(r.children, chain, myPath, out)
+    } else {
+      // Leaf with a path (validated above).
+      out.push(makeFlat(chain, myPath))
+    }
+  }
+}
+
+function makeFlat(chain: Route[], fullPath: string): FlatRoute {
+  const middleware: Middleware[] = []
+  for (const r of chain) {
+    if (r.middleware) middleware.push(...r.middleware)
+  }
+  let errorBoundary: ComponentType<ErrorBoundaryProps> | undefined
+  for (const r of chain) {
+    if (r.errorBoundary) errorBoundary = r.errorBoundary
+  }
+  const leaf = chain[chain.length - 1]
+  const cache = leaf.cache
+  const nativeTemplate = leaf.native === true && leaf.Component ? leaf.Component.name : undefined
+  return { fullPath, chain, middleware, errorBoundary, cache, nativeTemplate }
+}
+
+/** Internal React context that carries the next-deeper rendered element to
+ * the parent's <Outlet />. Default `null` means "no child to render" —
+ * `<Outlet />` from a leaf route or a flat route renders nothing. */
+export const OutletContext = createContext<ReactNode>(null)
+
+/** Renders the matched child route inside a parent layout. Read via
+ * React context; falls back to null at the leaf or in a flat (non-nested)
+ * route. Use inside a parent Component:
+ *
+ *     function AdminLayout() {
+ *       return <div><nav>…</nav><main><Outlet /></main></div>
+ *     }
+ */
+export function Outlet(): ReactNode {
+  return useContext(OutletContext)
+}
+
+/** Process the user's nested route tree into a flat array for the renderer
+ * and Rust route table. Each leaf/index node becomes one FlatRoute. Indices
+ * are stable across worker reloads (= array position), matching Rust's
+ * route_id semantics. */
+export function defineRoutes(routes: Route[]): FlatRoute[] {
+  return flattenRoutes(routes)
+}
+
+/** Wire-level shape of the JSON envelope produced by Rust. Discriminated
+ * union: render path (matched against a route) vs action path
+ * (POST /_brust/action/<id>). Keep these in sync with src/routes.rs
+ * RouteEnvelope / ActionEnvelope.
+ */
+export type RouteCall =
+  | {
+      kind: 'render'
+      route_id: number
+      path: string
+      params: Record<string, string>
+      req: BrustRequest
+    }
+  | {
+      kind: 'navigation'
+      route_id: number
+      path: string
+      params: Record<string, string>
+      req: BrustRequest
+    }
+  | {
+      kind: 'action'
+      action_id: string
+      /** Request's Content-Type, whitespace-trimmed (case preserved by Rust;
+       * the dispatch points below lowercase defensively). '' means the header
+       * was missing. */
+      content_type: string
+      /** UTF-8 text body — present for application/json and
+       * application/x-www-form-urlencoded. Mutually exclusive with body_b64. */
+      body_text?: string
+      /** Base64-encoded binary body — present for multipart/form-data.
+       * JS decodes via Buffer.from(s, 'base64') before parsing. */
+      body_b64?: string
+      req: BrustRequest
+    }
+  | {
+      kind: 'mcp'
+      body_text: string
+      req: BrustRequest
+    }
+  | {
+      kind: 'sse'
+      conn_id: bigint
+      req: BrustRequest
+    }
+  | {
+      kind: 'ws'
+      conn_id: bigint
+      client_subprotocols: string[]
+      req: BrustRequest
+    }
+
+/**
+ * Build a render callback for a given routes table. The returned function is
+ * what gets passed to `brust.registerRenderer(view, fn)` on the worker side.
+ *
+ * Wire format written to the SAB: [meta_len: u16 BE][meta JSON UTF-8][body bytes].
+ * meta = { status: number, headers?: Record<string, string> }.
+ */
+export interface MakeRendererOptions {
+  /** Lazy getter for the Bun Worker id. Called per-render so the value can be
+   * resolved after `registerRenderer` returns. Returns null before that. */
+  getWorkerId?: () => number | null
+  /** Action table the worker dispatches to when envelope.kind === 'action'.
+   * Both the main process and each worker call `brust.scanActions(...)` at
+   * module top-level and pass the resulting array here — the wire keys (ids)
+   * and the handler functions (fn) must agree across both ends. */
+  actions?: ActionDef[]
+  /** MCP server instance — built once per worker at module top-level. */
+  mcp?: import('./mcp/server.ts').McpServer
+}
+
+export function makeRenderer(
+  routes: FlatRoute[],
+  view: Uint8Array,
+  opts: MakeRendererOptions = {},
+): (envelopeJsonOrLen: number | string) => Promise<number> {
+  const encoder = new TextEncoder()
+  const decoder = new TextDecoder()
+  const byRouteId = new Map<number, FlatRoute>()
+  routes.forEach((r, i) => {
+    byRouteId.set(i, r)
+  })
+  const byActionId = new Map<string, ActionDef>()
+  for (const a of opts.actions ?? []) byActionId.set(a.id, a)
+
+  // napi shim for the chunk channel. The sabBytes arg is ignored by the
+  // native fn (Rust reads from the pre-registered BufPtr) — the call sites
+  // still pass it so renderBranchStreaming can be unit-tested against a
+  // mock that captures the bytes.
+  const napi = {
+    renderChunk: async (workerId: bigint, len: number, _sabBytes: Uint8Array): Promise<void> => {
+      await (native as any).napiRenderChunk(Number(workerId), len)
+    },
+    renderChunkFinal: async (
+      workerId: bigint,
+      len: number,
+      _sabBytes: Uint8Array,
+    ): Promise<void> => {
+      await (native as any).napiRenderChunkFinal(Number(workerId), len)
+    },
+  }
+
+  return async (envelopeJsonOrLen: number | string): Promise<number> => {
+    const envelopeJson =
+      typeof envelopeJsonOrLen === 'number'
+        ? decoder.decode(view.subarray(0, envelopeJsonOrLen))
+        : envelopeJsonOrLen
+    const call = JSON.parse(envelopeJson) as RouteCall
+    const wid = opts.getWorkerId?.() ?? 0
+    const workerId = BigInt(wid)
+
+    if (call.kind === 'render') {
+      const flat = byRouteId.get(call.route_id)
+      if (!flat) {
+        console.error(`[brust] unknown route_id=${call.route_id} for path=${call.path}`)
+        await emitSingleChunkResponse(view, napi, workerId, encoder, {
+          status: 404,
+          contentType: 'text/plain; charset=utf-8',
+          body: 'not found',
+        })
+        return 0
+      }
+      // Inject the permanently-unaborted signal — non-SSE routes don't
+      // have a per-conn AbortController. Middleware/loaders/components
+      // can still read req.signal.aborted (always false).
+      call.req.signal = NEVER_ABORTS
+
+      // Run the middleware chain against a streaming-marker terminal.
+      // Middleware that short-circuits (returns without calling next())
+      // wins as a plain single-chunk response. Middleware that calls next()
+      // gets the marker back and can wrap/mutate `headers` and `status`
+      // before we hand control to renderBranchStreaming.
+      const STREAM_MARKER: unique symbol = Symbol.for('brust.streamRender')
+      type StreamMarkerResponse = RouteResponse & { _brustStream?: typeof STREAM_MARKER }
+      const streamTerminal: () => Promise<StreamMarkerResponse> = async () => ({
+        status: 200,
+        body: '',
+        contentType: 'text/html; charset=utf-8',
+        _brustStream: STREAM_MARKER,
+      })
+      const chain = composeChain(call.req, flat.middleware, streamTerminal)
+
+      let verdict: StreamMarkerResponse
+      try {
+        verdict = (await chain()) as StreamMarkerResponse
+      } catch (err) {
+        console.error(`[brust] middleware/render uncaught:`, err)
+        // FAST LANE: single-chunk error. Works for both React (big dispatch
+        // reads the SAB via its fast-lane arm) and native routes (which take
+        // the channel-free dispatch_single_chunk).
+        return packSingleChunkResponse(view, encoder, {
+          status: 500,
+          contentType: 'text/html; charset=utf-8',
+          body: 'internal error',
+        })
+      }
+
+      if (verdict._brustStream !== STREAM_MARKER) {
+        // Middleware short-circuited with a concrete response. FAST LANE —
+        // single-chunk; same dual-dispatch safety as the error path above.
+        return packSingleChunkResponse(view, encoder, {
+          status: verdict.status,
+          contentType: verdict.contentType ?? 'text/html; charset=utf-8',
+          body: verdict.body,
+          headers: verdict.headers,
+        })
+      }
+
+      // Sub-project J — native: true branch. Runs the leaf's loader (if any),
+      // JSON-encodes the result into the SAB, then invokes napiRenderJinja
+      // which performs the minijinja render Rust-side and emits a 200 chunk
+      // through the same render-chunk channel as the React path.
+      //
+      // KNOWN LIMITATION: middleware can short-circuit by returning a
+      // RouteResponse without next() — that's the verdict._brustStream / status
+      // path above and works for native routes. But middleware that calls
+      // next() then mutates status/headers (e.g. adds Cache-Control) is NOT
+      // forwarded; napi_render_jinja hardcodes status: 200 and empty headers.
+      // Spec §4 doesn't define post-next() mutation semantics for native;
+      // deferred to v2.x. If your middleware needs to mutate, use a React
+      // route for now.
+      if (flat.nativeTemplate !== undefined) {
+        let data: unknown = {}
+        const leaf = flat.chain[flat.chain.length - 1]
+        if (leaf.loader) {
+          const ctx = { params: call.params, path: call.path, req: call.req }
+          try {
+            data = await leaf.loader(ctx as any)
+          } catch (err) {
+            console.error(`[brust] loader failed for native route ${flat.fullPath}:`, err)
+            // FAST LANE: native routes take dispatch_single_chunk (no chunk
+            // channel), so every native fallback MUST pack + return a length.
+            return packSingleChunkResponse(view, encoder, {
+              status: 500,
+              contentType: 'text/html; charset=utf-8',
+              body: 'internal error',
+            })
+          }
+        }
+        const json = JSON.stringify(data ?? {})
+        // Sub-project J — islands. If this template has an enriched islands
+        // manifest, merge per-island context vars (island_<id>_props, plus
+        // island_<id>_html for ssr entries) into the loader data before
+        // shipping it. resolveIslandContext is async (T9: it awaits the dynamic
+        // import + renderToString of each ssr island source).
+        const manifest = loadIslandManifest(flat.nativeTemplate)
+        if (manifest && manifest.length > 0) {
+          const rt = JSON.parse(json) // roundtrip ONCE; props read from rt
+          const extra = await resolveIslandContext(manifest, rt)
+          const ctx = { ...rt, ...extra }
+          const finalBytes = encoder.encode(JSON.stringify(ctx))
+          // The original size check guarded the pre-island bytes; the merged
+          // context (with island props) can be larger. Re-check on finalBytes.
+          if (finalBytes.length > view.length) {
+            return packSingleChunkResponse(view, encoder, {
+              status: 413,
+              contentType: 'text/plain; charset=utf-8',
+              body: 'loader data too large for SAB',
+            })
+          }
+          view.set(finalBytes, 0)
+          try {
+            return (native as any).napiRenderJinja(
+              Number(workerId),
+              finalBytes.length,
+              flat.nativeTemplate,
+            )
+          } catch (err) {
+            console.error(`[brust] napiRenderJinja failed for "${flat.nativeTemplate}":`, err)
+            return packSingleChunkResponse(view, encoder, {
+              status: 500,
+              contentType: 'text/html; charset=utf-8',
+              body: 'internal error',
+            })
+          }
+        }
+        const dataBytes = encoder.encode(json)
+        if (dataBytes.length > view.length) {
+          return packSingleChunkResponse(view, encoder, {
+            status: 413,
+            contentType: 'text/plain; charset=utf-8',
+            body: 'loader data too large for SAB',
+          })
+        }
+        view.set(dataBytes, 0)
+        try {
+          // FAST LANE: napiRenderJinja is a SYNC napi call — renders Rust-side,
+          // writes the framed response into the SAB, and returns its length
+          // directly (no Promise round-trip). Return it up to the tsfn; Rust's
+          // fast-lane arm reads the SAB directly (no chunk channel).
+          return (native as any).napiRenderJinja(
+            Number(workerId),
+            dataBytes.length,
+            flat.nativeTemplate,
+          )
+        } catch (err) {
+          console.error(`[brust] napiRenderJinja failed for "${flat.nativeTemplate}":`, err)
+          return packSingleChunkResponse(view, encoder, {
+            status: 500,
+            contentType: 'text/html; charset=utf-8',
+            body: 'internal error',
+          })
+        }
+      }
+
+      let element: ReactNode
+      let errorBoundary: ComponentType<{ error: Error }>
+      try {
+        element = await buildRenderElement(call, flat, opts.getWorkerId)
+        errorBoundary =
+          flat.errorBoundary ??
+          (({ error }) => createElement('div', null, `Internal Server Error: ${error.message}`))
+      } catch (err) {
+        // Setup failure BEFORE renderToPipeableStream — loader throw, params
+        // bind throw. Shape matches the legacy "internal error" path so
+        // existing integration tests stay green.
+        console.error(`[brust] render setup failed:`, err)
+        return await emitSingleChunkResponse(view, napi, workerId, encoder, {
+          status: 500,
+          contentType: 'text/html; charset=utf-8',
+          body: 'internal error',
+        })
+      }
+      await renderBranchStreaming({
+        element,
+        view,
+        workerId,
+        napi,
+        errorBoundary,
+        status: verdict.status,
+        headers: verdict.headers,
+        routePath: flat.fullPath,
+      })
+      // renderBranchStreaming wrote via the chunk channel.
+      return 0
+    }
+    if (call.kind === 'navigation') {
+      await navigationBranch(call, byRouteId, view, encoder, opts.getWorkerId)
+      return 0
+    }
+    if (call.kind === 'action') {
+      // FAST LANE: pack the framed response into the SAB and return its length.
+      // Rust reads it directly after the Promise settles — no chunk channel.
+      const resp = await actionBranchToResponse(call, byActionId)
+      return packSingleChunkResponse(view, encoder, resp)
+    }
+    if (call.kind === 'mcp') {
+      const resp = await mcpBranchToResponse(call, opts.mcp)
+      return await emitSingleChunkResponse(view, napi, workerId, encoder, resp)
+    }
+    if (call.kind === 'sse') {
+      try {
+        await sseBranch(call, view, encoder, routes)
+      } catch (err) {
+        // Setup-time errors only (BigInt coerce, dynamic import resolve,
+        // napi shim build). Once handleSseStream has started streaming,
+        // Rust already wrote 200 headers and frames — this 500 is irrelevant.
+        console.error('[brust] sseBranch uncaught:', err)
+      }
+      // SSE bypasses the chunk channel entirely — handleSseStream owns the
+      // socket via napiSse* fns. No renderChunk calls here.
+      return 0
+    }
+    if (call.kind === 'ws') {
+      try {
+        await wsBranch(call, view, encoder, routes)
+      } catch (err) {
+        // Setup-time errors only — same reasoning as sseBranch above.
+        console.error('[brust] wsBranch uncaught:', err)
+      }
+      // WS bypasses the chunk channel entirely — handleWsConn owns the
+      // socket via napiWs* fns. No renderChunk calls here.
+      return 0
+    }
+    // Unknown kind — log and 500. Shouldn't happen unless Rust ships
+    // something out of band.
+    console.error(`[brust] unknown envelope kind in worker:`, (call as { kind?: string }).kind)
+    return await emitSingleChunkResponse(view, napi, workerId, encoder, {
+      status: 500,
+      contentType: 'text/plain; charset=utf-8',
+      body: 'invalid envelope kind',
+    })
+  }
+}
+
+/** Render a React element to a single HTML string, awaiting all Suspense
+ * boundaries via onAllReady. Used by navigationBranch — renderToString
+ * would only capture the shell + fallbacks, while renderBranchStreaming
+ * is for the streaming render path. */
+function renderToAwaitedString(element: ReactNode): Promise<string> {
+  return new Promise<string>((resolve, reject) => {
+    const chunks: Buffer[] = []
+    const sink = new Writable({
+      write(chunk, _enc, cb) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))
+        cb()
+      },
+    })
+    sink.on('finish', () => resolve(Buffer.concat(chunks).toString('utf8')))
+    sink.on('error', reject)
+
+    let stream: ReturnType<typeof renderToPipeableStream>
+    stream = renderToPipeableStream(element, {
+      onAllReady() {
+        try {
+          stream.pipe(sink)
+        } catch (e) {
+          reject(e)
+        }
+      },
+      onShellError(err) {
+        reject(err)
+      },
+      onError(err) {
+        // Logged at the navigationBranch level; let onAllReady drive completion.
+        console.error('[brust] navigation render onError:', err)
+      },
+    })
+  })
+}
+
+async function navigationBranch(
+  call: Extract<RouteCall, { kind: 'navigation' }>,
+  byRouteId: Map<number, FlatRoute>,
+  view: Uint8Array,
+  encoder: TextEncoder,
+  getWorkerId: (() => number | null) | undefined,
+): Promise<void> {
+  const workerId = BigInt(getWorkerId?.() ?? 0)
+  const napi = {
+    renderChunk: async (wid: bigint, len: number, _view: Uint8Array): Promise<void> => {
+      await (native as any).napiRenderChunk(Number(wid), len)
+    },
+    renderChunkFinal: async (wid: bigint, len: number, _view: Uint8Array): Promise<void> => {
+      await (native as any).napiRenderChunkFinal(Number(wid), len)
+    },
+  }
+
+  const flat = byRouteId.get(call.route_id)
+  if (!flat) {
+    await emitSingleChunkResponse(view, napi, workerId, encoder, {
+      status: 404,
+      contentType: 'application/json; charset=utf-8',
+      body: '{"error":"not found"}',
+    })
+    return
+  }
+
+  // Run the middleware chain before rendering — mirrors the render branch's
+  // middleware pattern. A short-circuit verdict is emitted as the navigation
+  // response (client treats any non-2xx as a fallback trigger → full reload).
+  const NAV_MARKER: unique symbol = Symbol.for('brust.streamRender')
+  type NavMarkerResponse = RouteResponse & { _brustStream?: typeof NAV_MARKER }
+  const navTerminal: () => Promise<NavMarkerResponse> = async () => ({
+    status: 200,
+    body: '',
+    contentType: 'application/json; charset=utf-8',
+    _brustStream: NAV_MARKER,
+  })
+
+  // navigationBranch receives a 'navigation' call, but composeChain only
+  // needs req + middleware — cast to satisfy the type.
+  const navChain = composeChain(
+    (call as unknown as Extract<RouteCall, { kind: 'render' }>).req,
+    flat.middleware,
+    navTerminal,
+  )
+
+  let navVerdict: NavMarkerResponse
+  try {
+    navVerdict = (await navChain()) as NavMarkerResponse
+  } catch (err) {
+    console.error('[brust] navigation middleware threw:', err)
+    await emitSingleChunkResponse(view, napi, workerId, encoder, {
+      status: 500,
+      contentType: 'application/json; charset=utf-8',
+      body: '{"error":"middleware threw"}',
+    })
+    return
+  }
+
+  if (navVerdict._brustStream !== NAV_MARKER) {
+    // Middleware short-circuited — emit the verdict. Client's non-2xx check
+    // triggers the full-reload fallback so the user hits the real route and
+    // sees the middleware's challenge page.
+    await emitSingleChunkResponse(view, napi, workerId, encoder, {
+      status: navVerdict.status,
+      contentType: navVerdict.contentType ?? 'application/json; charset=utf-8',
+      body: navVerdict.body,
+      headers: navVerdict.headers,
+    })
+    return
+  }
+
+  try {
+    const element = await buildRenderElement(call as any, flat, getWorkerId)
+    if (!element) throw new Error('render setup failed')
+    // Use renderToPipeableStream + onAllReady so pages with <Suspense> emit
+    // their RESOLVED markup, not the fallback. renderToString would only
+    // capture the shell — navigating SPA-style to a Suspense-using route
+    // would otherwise ship "loading…" and never recover.
+    const fullHtml = await renderToAwaitedString(element)
+
+    // Extract <main> inner content. If the page didn't render a <main>,
+    // ship the full HTML — the client's no-main check will fire its
+    // full-reload fallback.
+    //
+    // Known limitation: the lazy regex truncates at the first </main>, so
+    // a page that renders nested <main> elements (invalid per the HTML
+    // spec but allowed by React) would lose content after the inner
+    // </main>. A future task can replace this with stack-counting
+    // extraction or DOMParser if real apps hit it.
+    const mainMatch = fullHtml.match(/<main[^>]*>([\s\S]*?)<\/main>/i)
+    const innerHtml = mainMatch ? mainMatch[1] : fullHtml
+
+    // Extract <title> text. React 18 inserts <!-- --> markers between
+    // adjacent text nodes inside <title>; strip those before serialising.
+    const titleMatch = fullHtml.match(/<title[^>]*>([\s\S]*?)<\/title>/i)
+    const title = titleMatch ? titleMatch[1].replace(/<!--.*?-->/g, '').trim() : ''
+
+    const body = JSON.stringify({ html: innerHtml, title })
+    await emitSingleChunkResponse(view, napi, workerId, encoder, {
+      status: 200,
+      contentType: 'application/json; charset=utf-8',
+      body,
+    })
+  } catch (err) {
+    console.error('[brust] navigation render failed:', err)
+    await emitSingleChunkResponse(view, napi, workerId, encoder, {
+      status: 500,
+      contentType: 'application/json; charset=utf-8',
+      body: '{"error":"render failed"}',
+    })
+  }
+}
+
+/** Build the React element for a render or navigation call: runs loaders
+ * top-down, builds the element bottom-up wrapping in OutletContext.Provider
+ * so nested routes receive the deeper element via <Outlet />. The caller
+ * (render branch or navigationBranch) is responsible for running the
+ * middleware chain BEFORE calling this — this helper assumes middleware
+ * has already passed.
+ *
+ * Throws on setup failure (loader throw, etc.). The caller synthesises a 500
+ * in that case.
+ */
+async function buildRenderElement(
+  call: Extract<RouteCall, { kind: 'render' }>,
+  flat: FlatRoute,
+  getWorkerId?: () => number | null,
+): Promise<ReactNode> {
+  call.req.signal = NEVER_ABORTS
+  const workerId = getWorkerId ? getWorkerId() : null
+  const chainNodes = flat.chain
+
+  // 1. Run loaders top-down (parent → leaf). Each Component receives ONLY
+  //    its own loader's data — no merge, no inheritance.
+  const datas: unknown[] = new Array(chainNodes.length)
+  for (let i = 0; i < chainNodes.length; i++) {
+    const r = chainNodes[i]
+    datas[i] = r.loader
+      ? await r.loader({ params: call.params, path: call.path, req: call.req })
+      : undefined
+  }
+
+  // 2. Build the React element bottom-up. Each level wraps the deeper level
+  //    via <OutletContext.Provider value={renderedChild}>; <Outlet /> in any
+  //    parent Component returns that value.
+  let element: ReactNode = null
+  for (let i = chainNodes.length - 1; i >= 0; i--) {
+    const r = chainNodes[i]
+    const node = createElement(r.Component!, {
+      params: call.params,
+      path: call.path,
+      data: datas[i],
+      workerId,
+      req: call.req,
+    })
+    element = createElement(OutletContext.Provider, { value: element }, node)
+  }
+  return element
+}
+
+/** Pack a framed single-chunk response `[meta_len: u16 BE][meta JSON][body]`
+ * into the SAB and return its total byte length — the FAST LANE. The worker
+ * resolves its render Promise with this length; Rust reads the framed bytes
+ * directly from the SAB after the Promise settles, bypassing the chunk channel
+ * (no napiRenderChunk call, no per-chunk ack round-trip). Returns the length so
+ * the caller can `return` it up to the tsfn.
+ *
+ * On SAB overflow, packs a small 500 instead and returns ITS length — the
+ * response always fits, so the client never hangs waiting for a body. */
+function packSingleChunkResponse(
+  view: Uint8Array,
+  encoder: TextEncoder,
+  resp: {
+    status: number
+    contentType: string
+    body: string | Uint8Array
+    headers?: Record<string, string>
+  },
+): number {
+  const bodyBytes = typeof resp.body === 'string' ? encoder.encode(resp.body) : resp.body
+  const meta = JSON.stringify({
+    status: resp.status,
+    contentType: resp.contentType,
+    headers: resp.headers ?? {},
+    streaming: false,
+  })
+  const metaBytes = encoder.encode(meta)
+  const total = 2 + metaBytes.length + bodyBytes.length
+  if (total > view.length) {
+    console.error(`[brust] fast-lane response ${total}b exceeds SAB ${view.length}b — emitting 500`)
+    const errBody = encoder.encode('response body too large')
+    const errMeta = JSON.stringify({
+      status: 500,
+      contentType: 'text/plain; charset=utf-8',
+      headers: {},
+      streaming: false,
+    })
+    const errMetaBytes = encoder.encode(errMeta)
+    const errTotal = 2 + errMetaBytes.length + errBody.length
+    view[0] = (errMetaBytes.length >> 8) & 0xff
+    view[1] = errMetaBytes.length & 0xff
+    view.set(errMetaBytes, 2)
+    view.set(errBody, 2 + errMetaBytes.length)
+    return errTotal
+  }
+  view[0] = (metaBytes.length >> 8) & 0xff
+  view[1] = metaBytes.length & 0xff
+  view.set(metaBytes, 2)
+  view.set(bodyBytes, 2 + metaBytes.length)
+  return total
+}
+
+/** Emit a single-chunk response through the chunk channel — wire shape
+ * matches what dispatch_to_worker_and_stream_chunks expects (one Bytes
+ * chunk with `[meta_len][meta][body]`, then Final). Used by mcp branch
+ * and by setup-failure fallbacks in the render branch. Returns 0 (the
+ * "used the chunk channel" sentinel) so callers can `return` it up to the
+ * tsfn. */
+async function emitSingleChunkResponse(
+  view: Uint8Array,
+  napi: {
+    renderChunk: (w: bigint, len: number, view: Uint8Array) => Promise<void>
+    renderChunkFinal: (w: bigint, len: number, view: Uint8Array) => Promise<void>
+  },
+  workerId: bigint,
+  encoder: TextEncoder,
+  resp: {
+    status: number
+    contentType: string
+    body: string | Uint8Array
+    headers?: Record<string, string>
+  },
+): Promise<number> {
+  const bodyBytes = typeof resp.body === 'string' ? encoder.encode(resp.body) : resp.body
+  const meta = JSON.stringify({
+    status: resp.status,
+    contentType: resp.contentType,
+    headers: resp.headers ?? {},
+    streaming: false,
+  })
+  const metaBytes = encoder.encode(meta)
+  const total = 2 + metaBytes.length + bodyBytes.length
+  if (total > view.length) {
+    console.error(
+      `[brust] single-chunk response ${total}b exceeds SAB ${view.length}b — emitting 500`,
+    )
+    // Emit a proper 500 plain-text response so the client doesn't hang on
+    // TCP timeout waiting for a body that never comes. The fallback body is
+    // small enough to always fit in the SAB.
+    const errBody = encoder.encode('response body too large')
+    const errMeta = JSON.stringify({
+      status: 500,
+      contentType: 'text/plain; charset=utf-8',
+      headers: {},
+      streaming: false,
+    })
+    const errMetaBytes = encoder.encode(errMeta)
+    const errTotal = 2 + errMetaBytes.length + errBody.length
+    view[0] = (errMetaBytes.length >> 8) & 0xff
+    view[1] = errMetaBytes.length & 0xff
+    view.set(errMetaBytes, 2)
+    view.set(errBody, 2 + errMetaBytes.length)
+    await napi.renderChunkFinal(workerId, errTotal, view)
+    return 0
+  }
+  view[0] = (metaBytes.length >> 8) & 0xff
+  view[1] = metaBytes.length & 0xff
+  view.set(metaBytes, 2)
+  view.set(bodyBytes, 2 + metaBytes.length)
+  await napi.renderChunkFinal(workerId, total, view)
+  return 0
+}
+
+/** Plain response object shape returned by action/mcp branches and consumed
+ * by `emitSingleChunkResponse`. The branches no longer write to the SAB
+ * directly — they hand back a JS-side response and the caller packs +
+ * dispatches it through the chunk channel. */
+interface BranchResponse {
+  status: number
+  contentType: string
+  body: string | Uint8Array
+  headers?: Record<string, string>
+}
+
+async function actionBranchToResponse(
+  call: Extract<RouteCall, { kind: 'action' }>,
+  byId: Map<string, ActionDef>,
+): Promise<BranchResponse> {
+  const def = byId.get(call.action_id)
+  if (!def) {
+    // Rust already 404s when the id isn't registered, but a race during
+    // hot-reload (or a desynced worker) could land here. Log and 404.
+    // Action clients always expect JSON, so ship a JSON envelope even
+    // when Rust would have 404'd first.
+    console.error(`[brust] unknown action_id=${call.action_id}`)
+    return {
+      status: 404,
+      body: '{"error":{"message":"unknown action"}}',
+      contentType: 'application/json; charset=utf-8',
+    }
+  }
+  // Populate req.signal with the permanently-unaborted sentinel. Action
+  // handlers reading req.signal.aborted always see false; the SSE branch
+  // is where real disconnect lives.
+  call.req.signal = NEVER_ABORTS
+
+  // Decode the body into the args array that will be spread into the handler.
+  // Three paths: multipart (body_b64), form-urlencoded (body_text), or JSON (body_text).
+  // Body decode happens BEFORE middleware so a malformed body 400s without running
+  // any user code.
+  let args: unknown[]
+  try {
+    if (call.body_b64 !== undefined) {
+      // Multipart path — base64 → bytes → Web Request.formData()
+      const bytes = Buffer.from(call.body_b64, 'base64')
+      const synthReq = new Request('http://x', {
+        method: 'POST',
+        headers: { 'Content-Type': call.content_type },
+        body: bytes,
+      })
+      const fd = await synthReq.formData()
+      args = [fd]
+    } else if (call.content_type.toLowerCase().startsWith('application/x-www-form-urlencoded')) {
+      // Form-urlencoded path — URLSearchParams → FormData
+      const params = new URLSearchParams(call.body_text ?? '')
+      const fd = new FormData()
+      for (const [k, v] of params) fd.append(k, v)
+      args = [fd]
+    } else {
+      // JSON path (default — empty or application/json content type).
+      const decoded = JSON.parse(call.body_text ?? '') as unknown
+      if (!Array.isArray(decoded)) {
+        return {
+          status: 400,
+          body: '{"error":{"message":"args must be a JSON array"}}',
+          contentType: 'application/json; charset=utf-8',
+        }
+      }
+      args = decoded
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    return {
+      status: 400,
+      body: JSON.stringify({ error: { message: `invalid request body: ${msg}` } }),
+      contentType: 'application/json; charset=utf-8',
+    }
+  }
+
+  const terminal = async (): Promise<RouteResponse> => {
+    try {
+      const result = await def.fn(call.req, ...args)
+      return {
+        status: 200,
+        body: result === undefined ? '' : JSON.stringify(result),
+        contentType: 'application/json; charset=utf-8',
+      }
+    } catch (err) {
+      console.error(`[brust] action ${def.id} threw:`, err)
+      const e = err instanceof Error ? err : new Error(String(err))
+      return {
+        status: 500,
+        body: JSON.stringify({ error: { message: e.message, name: e.name } }),
+        contentType: 'application/json; charset=utf-8',
+      }
+    }
+  }
+
+  const chain = composeChain(call.req, def.middleware, terminal)
+
+  let response: RouteResponse
+  try {
+    response = await chain()
+  } catch (err) {
+    console.error(`[brust] action middleware uncaught:`, err)
+    response = {
+      status: 500,
+      body: JSON.stringify({ error: { message: 'internal error' } }),
+      contentType: 'application/json; charset=utf-8',
+    }
+  }
+  return {
+    status: response.status,
+    body: response.body,
+    contentType: response.contentType ?? 'application/json; charset=utf-8',
+    headers: response.headers,
+  }
+}
+
+async function mcpBranchToResponse(
+  call: Extract<RouteCall, { kind: 'mcp' }>,
+  mcp: import('./mcp/server.ts').McpServer | undefined,
+): Promise<BranchResponse> {
+  if (!mcp) {
+    return {
+      status: 501,
+      body: '{"jsonrpc":"2.0","id":null,"error":{"code":-32603,"message":"mcp not configured"}}',
+      contentType: 'application/json; charset=utf-8',
+    }
+  }
+  // Populate req.signal with the permanently-unaborted sentinel. MCP handler
+  // reading req.signal.aborted always sees false; the SSE branch is where
+  // real disconnect lives.
+  call.req.signal = NEVER_ABORTS
+  const responseJson = await mcp.handleRequest(call.body_text, call.req)
+  if (responseJson === '') {
+    // Notification — no response body. Return 204 No Content.
+    return {
+      status: 204,
+      body: '',
+      contentType: 'application/json; charset=utf-8',
+    }
+  }
+  return {
+    status: 200,
+    body: responseJson,
+    contentType: 'application/json; charset=utf-8',
+  }
+}
+
+async function sseBranch(
+  call: Extract<RouteCall, { kind: 'sse' }>,
+  _view: Uint8Array,
+  encoder: TextEncoder,
+  routes: FlatRoute[],
+): Promise<void> {
+  // conn_id crosses the boundary as a JSON number (u64) but napiSse* fns
+  // require BigInt. Coerce once here; reassign on the call object so
+  // handleSseStream (which reads call.conn_id directly) also gets bigint.
+  ;(call as any).conn_id = BigInt((call as any).conn_id)
+
+  // Find matching FlatRoute by literal path (MVP — exact match; Rust's
+  // path_is_sse gates dispatch so we only see registered paths). Strip
+  // query string before matching.
+  // Rust's path_is_sse uses the same literal-match registration as this
+  // find — trailing-slash divergence (or any other normalization) fails
+  // in lockstep on both sides, never producing silent half-state.
+  const pathOnly = call.req.url.split('?')[0]
+  const flat = routes.find((r) => r.fullPath === pathOnly)
+  const leaf = flat?.chain[flat.chain.length - 1]
+
+  // Build napi shim around the four napiSse* native fns. signalOpen
+  // wraps the body string in a Buffer (the Rust side takes Buffer).
+  // Dynamic import is consistent with mcpBranch/actionBranch — defers
+  // loading the native binding until the dispatch path actually fires
+  // and avoids any circular-import risk during module init.
+  const native = await import('./index.js')
+  const napi = {
+    write: (conn_id: bigint, bytes: Uint8Array) =>
+      (native as any).napiSseWrite(
+        conn_id,
+        Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength),
+      ),
+    close: (conn_id: bigint) => (native as any).napiSseClose(conn_id),
+    registerAbort: (conn_id: bigint, cb: () => void) =>
+      (native as any).napiSseRegisterAbort(conn_id, cb),
+    signalOpen: (conn_id: bigint, status: number, body: string, ct: string) => {
+      const bodyBytes = encoder.encode(body)
+      ;(native as any).napiSseSignalOpen(
+        conn_id,
+        status,
+        Buffer.from(bodyBytes.buffer, bodyBytes.byteOffset, bodyBytes.byteLength),
+        ct,
+      )
+    },
+  }
+
+  if (!flat || !leaf?.sse) {
+    // Defensive — shouldn't reach here since Rust gates by path_is_sse.
+    napi.signalOpen(call.conn_id, 404, 'not found', 'text/plain; charset=utf-8')
+    napi.close(call.conn_id)
+    return
+  }
+
+  // Inject NEVER_ABORTS into req for the middleware run. handleSseStream
+  // will overwrite with a per-conn AbortController.signal afterward.
+  call.req.signal = NEVER_ABORTS
+
+  // Run middleware chain with a 200 placeholder terminal. The terminal
+  // does NOT invoke leaf.sse — handleSseStream does that after middleware
+  // approves. This keeps middleware semantics identical to action/render.
+  const placeholderTerminal: () => Promise<RouteResponse> = async () => ({
+    status: 200,
+    body: '',
+    contentType: 'text/event-stream',
+  })
+  const chain = composeChain(call.req, flat.middleware, placeholderTerminal)
+  const verdict = await chain()
+
+  if (verdict.status >= 400) {
+    napi.signalOpen(
+      call.conn_id,
+      verdict.status,
+      verdict.body,
+      verdict.contentType ?? 'text/plain; charset=utf-8',
+    )
+    napi.close(call.conn_id)
+    return
+  }
+
+  // Middleware OK — invoke handleSseStream which signals open 200 itself
+  // and runs the reader loop until done or aborted.
+  const { handleSseStream } = await import('./sse/handler.ts')
+  const routeShim: Route = {
+    path: flat.fullPath,
+    sse: leaf.sse,
+    sseOptions: leaf.sseOptions,
+  }
+  await handleSseStream(call, routeShim, napi)
+}
+
+async function wsBranch(
+  call: Extract<RouteCall, { kind: 'ws' }>,
+  _view: Uint8Array,
+  encoder: TextEncoder,
+  routes: FlatRoute[],
+): Promise<void> {
+  // Coerce conn_id from JSON.parse number → BigInt (same fix as sseBranch
+  // Task 12; native binding requires BigInt since conn_ids are u64).
+  ;(call as any).conn_id = BigInt(call.conn_id)
+
+  // Find matching FlatRoute by literal fullPath (Rust path_is_ws gates
+  // dispatch — same literal-match contract as SSE).
+  const pathOnly = call.req.url.split('?')[0]
+  const flat = routes.find((r) => r.fullPath === pathOnly)
+  const leaf = flat?.chain[flat.chain.length - 1]
+
+  // Build napi shim around the 4 napiWs* native fns. The registerHandlers
+  // shim adapts from struct-arg callbacks (WsMessageArg / WsCloseArg —
+  // Task 4 deviation: napi-rs rejected tuple Function args) to the
+  // positional-arg handleWsConn API.
+  const native = await import('./index.js')
+  const napi = {
+    send: (conn_id: bigint, bytes: Uint8Array, isBinary: boolean) =>
+      (native as any).napiWsSend(
+        conn_id,
+        Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength),
+        isBinary,
+      ),
+    close: (conn_id: bigint, code: number, reason: string) =>
+      (native as any).napiWsClose(conn_id, code, reason),
+    signalOpen: (
+      conn_id: bigint,
+      status: number,
+      body: string,
+      ct: string,
+      subprotocol: string,
+    ) => {
+      const bodyBytes = encoder.encode(body)
+      ;(native as any).napiWsSignalOpen(
+        conn_id,
+        status,
+        Buffer.from(bodyBytes.buffer, bodyBytes.byteOffset, bodyBytes.byteLength),
+        ct,
+        subprotocol,
+      )
+    },
+    registerHandlers: (
+      conn_id: bigint,
+      onMessage: (data: Uint8Array, isBinary: boolean) => void,
+      onClose: (code: number, reason: string) => void,
+    ) => {
+      // napi-rs delivers struct args (WsMessageArg / WsCloseArg) — adapt
+      // back to positional for handleWsConn's contract.
+      ;(native as any).napiWsRegisterHandlers(
+        conn_id,
+        (arg: { data: Uint8Array; isBinary: boolean }) => onMessage(arg.data, arg.isBinary),
+        (arg: { code: number; reason: string }) => onClose(arg.code, arg.reason),
+      )
+    },
+  }
+
+  if (!flat || !leaf?.websocket) {
+    // Defensive — Rust path_is_ws gates dispatch.
+    napi.signalOpen(call.conn_id, 404, 'not found', 'text/plain; charset=utf-8', '')
+    return
+  }
+
+  // Inject NEVER_ABORTS into req for middleware. There's no per-conn
+  // AbortController for WS — handleWsConn doesn't create one because
+  // lifecycle is via registered onMessage/onClose callbacks rather than
+  // awaiting on a request signal.
+  call.req.signal = NEVER_ABORTS
+
+  // Run middleware chain with a 101 placeholder terminal that signals
+  // "ready to upgrade". The terminal does NOT call route.websocket —
+  // handleWsConn does that after middleware approves.
+  const placeholderTerminal: () => Promise<RouteResponse> = async () => ({
+    status: 101,
+    body: '',
+    contentType: 'application/octet-stream',
+  })
+  const chain = composeChain(call.req, flat.middleware, placeholderTerminal)
+  const verdict = await chain()
+
+  if (verdict.status >= 400) {
+    napi.signalOpen(
+      call.conn_id,
+      verdict.status,
+      verdict.body,
+      verdict.contentType ?? 'text/plain; charset=utf-8',
+      '',
+    )
+    return
+  }
+
+  // Middleware OK — invoke handleWsConn. It signals open 101 itself
+  // (with the chosen subprotocol) and registers handlers.
+  const { handleWsConn } = await import('./ws/handler.ts')
+  const routeShim: Route = {
+    path: flat.fullPath,
+    websocket: leaf.websocket,
+    wsOptions: leaf.wsOptions,
+  }
+  await handleWsConn(call, routeShim, napi)
+}
+
+/** Right-to-left compose a middleware chain. Each middleware wraps the next;
+ * the terminal step ends up at the innermost call. Returning without calling
+ * next() short-circuits. Used identically by render + action branches. */
+export function composeChain(
+  req: BrustRequest,
+  mws: Middleware[] | undefined,
+  terminal: () => Promise<RouteResponse>,
+): () => Promise<RouteResponse> {
+  if (!mws || mws.length === 0) return terminal
+  let chain = terminal
+  for (let i = mws.length - 1; i >= 0; i--) {
+    const mw = mws[i]
+    const next = chain
+    chain = () => mw(req, next)
+  }
+  return chain
+}