brustjs 0.1.50-alpha → 0.1.52-alpha

package/types/routes.d.ts

@@ -0,0 +1,506 @@
+import { type ComponentType, type ReactNode } from 'react';
+import type { EndpointDef } from './define-actions.ts';
+export { mdNav, mdRoutes, mdUrlPath } from './md/routes.ts';
+export type { MdNavGroup, MdNavItem, MdRoute, MdRoutesOptions, MdRouteSource, } from './md/routes.ts';
+export { scanMdDir } from './md/scan.ts';
+export type { MdFile } from './md/scan.ts';
+export { slugifyHeading } from './md/slug.ts';
+export declare const NEVER_ABORTS: AbortSignal;
+/** 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;
+    /** Matched route params (percent-decoded) — the SAME values the loader ctx
+     * receives. Populated by the TS dispatch layer (`prepReq`) BEFORE the
+     * middleware chain runs, so middleware can authorize against `{id}` without
+     * re-parsing the raw URL. Empty object for routes without params — and for
+     * SSE/WS requests (their envelope carries no params in v1). */
+    params: Record<string, string>;
+    /** Request-scoped bag middleware writes and loaders/handlers read. The same
+     * object identity flows through the whole chain (middleware → loader →
+     * component/handler). Locals written before `next()` are visible downstream;
+     * writes AFTER `next()` returns happen after the loader already ran. Reset
+     * to a fresh `{}` per request. */
+    locals: Record<string, unknown>;
+}
+/** Populate the TS-owned `BrustRequest` fields (`params`, `locals`) on a
+ * request that just arrived in the Rust envelope. Rust knows nothing of these
+ * fields, so every dispatch branch calls this ONCE, before composeChain /
+ * loaders run — the single population point. Mutates and returns `req`. */
+export declare function prepReq(req: BrustRequest, params: Record<string, string> | undefined): BrustRequest;
+/** 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;
+}
+/** L2 programmatic cache-key result. The `key` function builds the COMPLETE
+ * cache key (you concat url + query + DB-derived data yourself). */
+export interface CacheKeyResult {
+    /** The COMPLETE L2 cache key. */
+    key: string;
+    /** Tag groups for `cache.invalidate({ tags })`. */
+    tags?: string[];
+    /** Seconds; overrides `key_ttl_seconds` / `ttl_seconds`. */
+    ttl?: number;
+}
+export interface RouteCacheConfig<Params = Record<string, string>> {
+    /** Base TTL in seconds (L1; L2 fallback). */
+    ttl_seconds: number;
+    /** L1 declarative key prefix expression (evaluated in Rust, zero-Bun on hit). */
+    prefix?: string;
+    /** Route to L2 when truthy: a key-expression (conditional) or `true` (always).
+     * Absent / `false` ⇒ L1 only. */
+    bypass?: string | boolean;
+    /** L2 programmatic key (runs in the worker). Returns the COMPLETE key. */
+    key?: (ctx: {
+        req: BrustRequest;
+        url: URL;
+        params: Params;
+    }) => CacheKeyResult | Promise<CacheKeyResult>;
+    /** Static L2 TTL (seconds); `CacheKeyResult.ttl` overrides per-entry. */
+    key_ttl_seconds?: number;
+    /** Static L1 invalidation tags. L1 entries cached for this route carry these
+     * tags so `cache.invalidate({ tags })` evicts them (L1 is no longer
+     * TTL-only). Route-level + static — not per-request. */
+    tags?: string[];
+}
+/** SSG config — read ONLY by `brust build --ssg`. Live server / dev ignore it.
+ * See docs/superpowers/specs/2026-06-12-ssg-dynamic-params-design.md. */
+export interface RouteSsgConfig {
+    /** generateStaticParams: concrete param records to prerender. Each record
+     * must cover every `{name}` in the route's full path with a non-empty
+     * string. Sync or async. Values are URL-encoded into the crawl path. */
+    params?: () => Array<Record<string, string>> | Promise<Array<Record<string, string>>>;
+    /** What non-prerendered paths do on a static host. 'none' (default) = skip
+     * → host 404 (today's behavior). 'client' = client-loader takeover
+     * (Phase B; requires `export const clientLoader` in the leaf component
+     * file, leaf must be a DEFAULT import in routes.tsx, React routes only). */
+    fallback?: 'none' | 'client';
+    /** Server-rendered loading UI baked into the fallback shell (Phase B).
+     * Renders in the leaf position with NO data. */
+    placeholder?: ComponentType;
+}
+/** 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;
+}
+declare const BRUST_VERDICT: unique symbol;
+/** Sentinel returned from a native (`native: true`) route loader to control the
+ * HTTP response. Build it with `notFound()` / `redirect()`, never by hand. */
+export interface NativeVerdict {
+    readonly [BRUST_VERDICT]: true;
+    readonly status: number;
+    readonly render: boolean;
+    readonly data?: unknown;
+    readonly headers?: Record<string, string>;
+}
+/** Signal "not found" from a route loader. ONE helper, two call shapes —
+ * matching how each render path consumes a loader result:
+ *
+ *  - NATIVE route loader: `return notFound(data?)`. The returned verdict is
+ *    inspected by `runNativeChainLoaders` and renders the route's OWN template
+ *    at HTTP 404 (`data` default `{}` becomes the template context).
+ *
+ *  - REACT route loader: `throw notFound()`. A React loader's RETURN value is
+ *    the component's `data` prop (never inspected as a verdict), so the only
+ *    way to signal not-found is to throw. The render dispatch discriminates the
+ *    thrown verdict (it is symbol-tagged — `isNativeVerdict`) BEFORE the generic
+ *    500/errorBoundary handler and renders the NEAREST catch-all (`path: '*'`)
+ *    for the route's prefix at HTTP 404 — NOT the route's own Component, NOT a
+ *    500. If no catch-all is registered for the prefix, a framework default 404
+ *    body is rendered. `data` is ignored on the React throw path (the catch-all
+ *    runs its own loader chain).
+ *
+ * Same value type (`NativeVerdict`) either way — native returns it, React
+ * throws it — so there is a single public `notFound()` API. */
+export declare function notFound(data?: unknown): NativeVerdict;
+/** Return from a native route loader to emit a redirect (no template render). */
+export declare function redirect(location: string, status?: 301 | 302 | 303 | 307 | 308): NativeVerdict;
+/** True if a loader return value is a NativeVerdict (symbol-keyed — a plain
+ * object with a `status` property is NOT mistaken for one). */
+export declare function isNativeVerdict(x: unknown): x is NativeVerdict;
+declare const HTTP_ERROR: unique symbol;
+export interface HttpErrorOpts {
+    /** Override the Content-Type. Defaults: string body → `text/plain;
+     * charset=utf-8`, object body → `application/json; charset=utf-8`. */
+    contentType?: string;
+    /** Extra response headers (e.g. `WWW-Authenticate`). */
+    headers?: Record<string, string>;
+}
+/** The symbol-keyed value `httpError()` throws. Body/contentType are resolved
+ * at construction so every catch site emits the same wire shape. Mirrors the
+ * NativeVerdict / ActionError branding (Symbol.for survives the trigger being
+ * duplicated across bundles). */
+export interface HttpErrorTrigger {
+    readonly [HTTP_ERROR]: true;
+    readonly status: number;
+    readonly body: string;
+    readonly contentType: string;
+    readonly headers?: Record<string, string>;
+}
+/** Throw from a route loader (React or native) to short-circuit the response
+ * with an arbitrary error status — the loader-side analogue of a middleware
+ * short-circuit:
+ *
+ * ```ts
+ * loader: async ({ req }) => {
+ *   if (!req.locals.user) throw httpError(403, 'no entry')
+ *   …
+ * }
+ * ```
+ *
+ * THROW-only (it never returns) — one usage form on both render paths, unlike
+ * `notFound()` which native loaders RETURN. `body`: string → text/plain (or
+ * `opts.contentType`), object → JSON, omitted → empty. Status must be an
+ * integer in 400-599: 3xx is `redirect()`'s job, a 404 that renders a page is
+ * `notFound()`'s. The response is a plain short-circuit — it never reaches the
+ * errorBoundary and never logs as a 500. */
+export declare function httpError(status: number, body?: string | object, opts?: HttpErrorOpts): never;
+/** True when a thrown value is the `httpError()` trigger (symbol-keyed — a
+ * plain object with a `status` property is NOT mistaken for one). */
+export declare function isHttpErrorTrigger(x: unknown): x is HttpErrorTrigger;
+/** Loader context passed to native chain loaders. */
+export interface NativeLoaderCtx {
+    params: Record<string, string>;
+    path: string;
+    req: BrustRequest;
+}
+/** Result of running a native route's chain loaders top-down: a merged flat
+ * context object (all loader results shallow-merged, child keys win), the
+ * first verdict encountered (top-down) which short-circuits the chain, or an
+ * `httpError()` trigger THROWN by a loader (intercepted per-loader so it never
+ * reaches the caller's generic 500 catch). */
+export type NativeChainResult = {
+    data: Record<string, unknown>;
+} | {
+    verdict: NativeVerdict;
+} | {
+    httpError: HttpErrorTrigger;
+};
+/** Run a native route's `flat.chain` loaders top-down (parent → leaf) and merge
+ * their results into ONE flat context object.
+ *
+ * Semantics (T3 — native <Outlet> loader chain):
+ *  - Each chain node may lack a loader → skip it.
+ *  - Results merge shallow: `merged = { ...merged, ...result }` — later (child)
+ *    keys win over earlier (parent) keys.
+ *  - First verdict wins: if any loader returns a `notFound()`/`redirect()`
+ *    verdict (top-down), STOP — remaining loaders are NOT run — and return it.
+ *  - `chain.length === 1` (or only the leaf has a loader) → behaves exactly as
+ *    the old leaf-only read (no regression).
+ *
+ * The caller is responsible for wrapping this in a SINGLE `runInStoreContext`
+ * (one Map per request) so parent loader store writes are visible to child
+ * loaders — mirroring the React path. This helper itself does NOT open a store
+ * scope. */
+export declare function runNativeChainLoaders(chain: Route[], ctx: NativeLoaderCtx): Promise<NativeChainResult>;
+/** 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. */
+    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;
+    /** Opt-in SSG behavior for dynamic-param routes (`/blog/{slug}`). Only
+     * consulted by `brust build --ssg`. */
+    ssg?: RouteSsgConfig;
+    /** 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;
+    /** Catch-all (`{ path: '*' }`) marker. When true this FlatRoute is a
+     * "not found" fallback: it stays in the array at its natural index (route_id
+     * stable) but install SKIPS the matchit insert for it — it only renders when
+     * matchit returns NoMatch under `notFoundPrefix`. NEVER remove a flagged
+     * entry from the flat array (that would shift every later route_id).
+     *
+     * A catch-all render is stamped HTTP 404 UNCONDITIONALLY (spec invariant 4:
+     * "never 200"). A `redirect()` from the catch-all's OWN loader still wins —
+     * redirect verdicts short-circuit and return before the 404 stamp on every
+     * path. A non-redirect verdict status, however, is overridden by 404 (a 404
+     * page is a 404, by definition). */
+    notFound?: boolean;
+    /** Parent layout's path prefix this catch-all covers. Root catch-all → `''`
+     * (matches everything as last resort). Longest segment-prefix wins at match
+     * time. Never contains `*` (it's the parent prefix, not the catch-all path). */
+    notFoundPrefix?: 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 declare function joinPath(base: string, rel: string): string;
+/** 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 (S3). */
+export declare function flattenRoutes(routes: Route[]): FlatRoute[];
+/** 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 declare const OutletContext: import("react").Context<ReactNode>;
+/** 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 declare function Outlet(): ReactNode;
+/** 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 declare function defineRoutes(routes: Route[]): FlatRoute[];
+/** 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;
+    /** Set by Rust when the route's `cache.bypass` matched — routes this
+     * request to the L2 programmatic cache (worker `cache.key`). */
+    bypassed?: boolean;
+} | {
+    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;
+    /** Path params extracted by the Rust router (e.g. {id} → "abc"). */
+    params?: Record<string, 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?: EndpointDef[];
+    /** MCP server instance — built once per worker at module top-level. */
+    mcp?: import('./mcp/server.ts').McpServer;
+    /** Render slots per worker. The `view` SAB is partitioned into this many
+     * disjoint sub-views; each render is dispatched with a `slot` index and
+     * operates on `view.subarray(slot*sub, slot*sub+sub)`. Default 1 (the whole
+     * view → byte-identical to the pre-multi-slot path). */
+    slots?: number;
+}
+export declare function makeRenderer(routes: FlatRoute[], view: Uint8Array, opts?: MakeRendererOptions): (envelopeJson: string, slot?: number) => Promise<number>;
+/** 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>;
+}
+export declare function dispatchAction(call: Extract<RouteCall, {
+    kind: 'action';
+}>, byId: Map<string, EndpointDef>): Promise<BranchResponse>;
+/** 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 declare function composeChain(req: BrustRequest, mws: Middleware[] | undefined, terminal: () => Promise<RouteResponse>): () => Promise<RouteResponse>;

package/types/sse/handler.d.ts

@@ -0,0 +1,22 @@
+import type { Route, RouteCall } from '../routes.ts';
+export type SseCall = Extract<RouteCall, {
+    kind: 'sse';
+}>;
+/** NAPI surface — Rust provides these. In tests, a mock satisfies the shape. */
+export interface SseNapi {
+    write(conn_id: bigint, bytes: Uint8Array): Promise<void>;
+    close(conn_id: bigint): void;
+    registerAbort(conn_id: bigint, cb: () => void): void;
+    signalOpen(conn_id: bigint, status: number, body: string, contentType: string): void;
+}
+/**
+ * Per-connection JS driver for SSE routes. Called once per client connection.
+ *
+ * Contract with the Rust napi shim:
+ *   - napi.registerAbort(conn_id, cb)  — Rust calls cb when client disconnects
+ *   - napi.signalOpen(conn_id, status, body, contentType)
+ *                                      — JS reports verdict; Rust waits before writing headers
+ *   - napi.write(conn_id, bytes)       — write a chunk; Promise resolves when TCP write completes (backpressure)
+ *   - napi.close(conn_id)             — JS tells Rust to tear down the per-conn task
+ */
+export declare function handleSseStream(call: SseCall, route: Route, napi: SseNapi): Promise<void>;

package/types/standard-schema.d.ts

@@ -0,0 +1,31 @@
+/** Minimal Standard Schema v1 surface — https://standardschema.dev */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
+    };
+}
+type StandardResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: ReadonlyArray<StandardIssue>;
+};
+export interface StandardIssue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | {
+        key: PropertyKey;
+    }>;
+}
+export type InferOutput<S> = S extends StandardSchemaV1<unknown, infer O> ? O : never;
+export type ValidateOk<T> = {
+    ok: true;
+    value: T;
+};
+export type ValidateErr = {
+    ok: false;
+    issues: ReadonlyArray<StandardIssue>;
+};
+export declare function validate<S extends StandardSchemaV1 | undefined>(schema: S, input: unknown): Promise<ValidateOk<S extends StandardSchemaV1 ? InferOutput<S> : unknown> | ValidateErr>;
+export {};

package/types/store/define-store.d.ts

@@ -0,0 +1,31 @@
+import { type Computed, type Signal } from './signal.ts';
+export interface StoreInstanceRecord {
+    instance: object;
+    subs: Set<() => void>;
+    version: {
+        n: number;
+    };
+    snap: {
+        value: Record<string, unknown>;
+        version: number;
+    } | null;
+    handle?: {
+        serialize(): Record<string, unknown>;
+    };
+}
+type ServerResolver = (name: string, create: () => StoreInstanceRecord) => StoreInstanceRecord;
+export declare function __setServerResolver(fn: ServerResolver): void;
+type StoreValue<X> = X extends Signal<infer T> ? T : X extends Computed<infer T> ? T : never;
+export type Snapshot<S> = {
+    [K in keyof S as [StoreValue<S[K]>] extends [never] ? S[K] extends (...a: never[]) => unknown ? never : K : K]: [StoreValue<S[K]>] extends [never] ? S[K] : StoreValue<S[K]>;
+};
+export interface StoreHandle<S extends object> {
+    (): S;
+    readonly name: string;
+    subscribe(cb: () => void): () => void;
+    snapshot(): Snapshot<S>;
+    serialize(): Record<string, unknown>;
+    hydrate(state: Record<string, unknown>): void;
+}
+export declare function defineStore<S extends object>(name: string, factory: () => S): StoreHandle<S> & S;
+export {};

package/types/store/index.d.ts

@@ -0,0 +1,5 @@
+export { signal, computed, effect, batch, isSignal, isComputed } from './signal.ts';
+export type { Signal, Computed } from './signal.ts';
+export { defineStore } from './define-store.ts';
+export type { StoreHandle, Snapshot } from './define-store.ts';
+export { toScriptJson, parseStoreScript, storeScriptTag } from './serialize.ts';

package/types/store/react.d.ts

@@ -0,0 +1,2 @@
+import type { Snapshot, StoreHandle } from './define-store.ts';
+export declare function useStore<S extends object>(store: StoreHandle<S> & S): Snapshot<S>;

package/types/store/serialize.d.ts

@@ -0,0 +1,5 @@
+export declare function toScriptJson(value: unknown): string;
+export declare function storeScriptTag(name: string, state: unknown): string;
+export declare function parseStoreScript(el: {
+    textContent: string | null;
+}): Record<string, unknown>;

package/types/store/server-context.d.ts

@@ -0,0 +1,4 @@
+import { type StoreInstanceRecord } from './define-store.ts';
+export declare function runInStoreContext<T>(fn: () => T): T;
+export declare function getServerInstance(name: string, create: () => StoreInstanceRecord): StoreInstanceRecord;
+export declare function collectSnapshot(): Record<string, Record<string, unknown>> | null;

package/types/store/signal.d.ts

@@ -0,0 +1,18 @@
+declare const SIGNAL: unique symbol;
+declare const COMPUTED: unique symbol;
+export interface Signal<T> {
+    (): T;
+    set(next: T | ((prev: T) => T)): void;
+    readonly [SIGNAL]: true;
+}
+export interface Computed<T> {
+    (): T;
+    readonly [COMPUTED]: true;
+}
+export declare function isSignal(v: unknown): v is Signal<unknown>;
+export declare function isComputed(v: unknown): v is Computed<unknown>;
+export declare function batch(fn: () => void): void;
+export declare function signal<T>(initial: T): Signal<T>;
+export declare function computed<T>(fn: () => T): Computed<T>;
+export declare function effect(fn: () => void | (() => void)): () => void;
+export {};

package/types/templates.d.ts

@@ -0,0 +1,18 @@
+export declare const templates: {
+    /** Register (or replace) a runtime template under `name`. Names are opaque
+     * keys (`shop/42/section/7@v3` is fine). Throws on jinja syntax errors
+     * (message includes line info). Replacement is atomic: concurrent renders
+     * see old or new, never missing. */
+    register(name: string, jinjaSource: string): void;
+    /** Remove a runtime-registered template. Returns whether it existed.
+     * Boot-tier templates (compiled from routes) are not removable. */
+    remove(name: string): boolean;
+    /** True when `name` resolves in either tier (dynamic first, then boot). */
+    has(name: string): boolean;
+    /** Names of runtime-registered templates (dynamic tier only). */
+    list(): string[];
+    /** Render a template (either tier) to an HTML string. Pure (name, data) →
+     * html — no request/store context. NOT the request fast lane; intended for
+     * handlers/loaders/tooling (draft canvases, section previews). */
+    render(name: string, data?: unknown): string;
+};