brustjs 0.1.49-alpha → 0.1.51-alpha

package/types/index.d.ts

@@ -0,0 +1,222 @@
+import * as native from './index.js';
+/** Global CORS policy (one policy for the whole deployment — pages, actions,
+ * static assets alike; brust has no per-route CORS). Opt-in: omit to keep CORS
+ * disabled (byte-identical default — no `Access-Control-*` headers, OPTIONS
+ * still 405). Threaded into Rust, which answers preflights before the render
+ * pipeline and stamps actual responses at a single chokepoint. */
+export interface CorsOptions {
+    /** Allowed origins, exact scheme+host+port match (no wildcard subdomains).
+     * A list CONTAINING `'*'` is treated as wildcard: every origin allowed,
+     * echoed as the literal `*`. */
+    origins: string[];
+    /** Preflight `Access-Control-Allow-Methods`. Default: GET,POST,PUT,PATCH,DELETE,OPTIONS. */
+    methods?: string[];
+    /** Preflight `Access-Control-Allow-Headers`. Default: echo the request's
+     * `Access-Control-Request-Headers`. */
+    headers?: string[];
+    /** `Access-Control-Expose-Headers` on actual responses. Default: none. */
+    exposeHeaders?: string[];
+    /** Emit `Access-Control-Allow-Credentials: true`. INVALID combined with a
+     * wildcard origin — serve() throws at boot (browsers silently reject
+     * `Allow-Credentials` with `Allow-Origin: *`; we make it loud). */
+    credentials?: boolean;
+    /** Preflight `Access-Control-Max-Age` seconds. Default 600. */
+    maxAgeSeconds?: number;
+}
+/** Fail-fast CORS validation, mirroring Rust's `CorsConfig::validate` so a bad
+ * config throws in TS before the native call (clearer stack, same message
+ * shape). Exported for unit testing. */
+export declare function validateCorsOptions(cors: CorsOptions): void;
+export interface ServeOptions {
+    /** Host/address to bind on. A hostname (e.g. `localhost`, resolved Rust-side)
+     * or a literal IP such as `0.0.0.0` / `127.0.0.1`. */
+    host: string;
+    port: number;
+    workers: number;
+    entry: string;
+    bootTimeoutMs?: number;
+    /** Actions builder from `defineActions(...)`. When present, `serve`
+     * registers its endpoints (method/path, keyed by registration index)
+     * before the listener binds. Optional — omit if the app has no actions. */
+    actions?: import('./define-actions.ts').ActionsBuilder;
+    /** URL prefix the action router mounts under (e.g. `/_actions`). Threaded
+     * into Rust's ServeOptions.action_prefix. */
+    actionPrefix?: string;
+    /** Optional global CORS policy — see {@link CorsOptions}. Validated at boot
+     * (TS first, Rust mirrors): `origins` non-empty; `credentials` + wildcard
+     * origin throws. */
+    cors?: CorsOptions;
+    /** MCP support — pass a manifest built via brust.buildMcpManifest. brust.serve
+     * does NOT auto-wire MCP into workers; the worker branch of the entry file must
+     * call brust.loadMcpManifest() + makeMcpServer() itself and pass the McpServer
+     * to makeRenderer via `opts.mcp`. See example/pokedex/index.ts for the
+     * pattern. The field here is currently unused inside serve() and is reserved
+     * for future IPC-based propagation of the manifest. */
+    mcp?: {
+        manifest: import('./mcp/manifest.ts').McpManifest;
+    };
+    /** Performance tunables. All optional — omitting any field keeps the
+     * framework default, so the whole object is opt-in. `connWorkers` sets the
+     * Rust-side connection-handling concurrency (accept→parse→dispatch), which is
+     * INDEPENDENT of `workers` (the Bun render threads): I/O-bound paths like
+     * `/ping` scale with `connWorkers`, render-bound paths scale with `workers`.
+     * Setting `connWorkers > workers` is safe: a render dispatch that finds every
+     * worker busy QUEUES (awaits a free worker up to `claimTimeoutMs`) instead of
+     * 503-ing, so excess conn-workers just wait their turn rather than dropping
+     * requests. */
+    tuning?: {
+        /** Rust accept/dispatch concurrency. Default = `workers`. */
+        connWorkers?: number;
+        /** Max request bytes before header terminator. Default 16384 (16 KB). */
+        maxRequestBytes?: number;
+        /** Max action/RPC body size. Default 262144 (256 KB). */
+        maxActionBodyBytes?: number;
+        /** Accept-side queue depth (TCP backpressure point). Default 1024. */
+        connQueueCap?: number;
+        /** Initial per-connection read buffer capacity. Default 4096. */
+        readBufCap?: number;
+        /** Max ms a render waits for a free worker before 503 (AllBusy queues
+         * instead of failing fast). Default 10000. */
+        claimTimeoutMs?: number;
+        /** tokio I/O runtime worker-thread count for the hyper server. Runs inside
+         * Bun (which has its own threads + render workers), so this is NOT
+         * one-per-core. Default `min(availableParallelism, 4)` (fallback 2). */
+        workerThreads?: number;
+        /** Render slots per Bun worker — concurrent in-flight renders per isolate.
+         * Default `min(cores, 16)` (set `BRUST_RENDER_SLOTS` to go higher on >16-core
+         * hosts). Only speeds renders that `await` during render (e.g. Suspense with
+         * async data); CPU-bound/native/cache routes serialize on the one isolate and
+         * are unaffected. The count is propagated to each worker via the
+         * `BRUST_RENDER_SLOTS` env var and scales the per-worker SAB (one region per
+         * slot, so the cap bounds memory). slots > 1 is byte-identical to slots = 1. */
+        renderSlots?: number;
+    };
+}
+export type RenderFn = (envelopeJson: string, slot: number) => Promise<number>;
+export declare const isWorker: boolean;
+export declare function workerId(): number | null;
+export declare const brust: {
+    serve(opts: ServeOptions): Promise<void>;
+    /** Install the route table in Rust. MUST be called before `serve()`.
+     * Pass an array of FlatRoutes from `defineRoutes(...)` — each is JSON-encoded
+     * with its optional cache config. Rust matches against `fullPath`. */
+    registerRoutes(routes: import("./routes.ts").FlatRoute[]): number;
+    /** Register the list of literal route paths that should be dispatched as
+     * SSE (text/event-stream) instead of going through the render pipeline.
+     * Call from the main process after defineRoutes — the worker only needs
+     * the call if it also accepts SSE traffic, but in the current model the
+     * main accept loop owns dispatch so this is main-only. MVP supports only
+     * literal paths; parameterized routes (e.g. `/sse/{room}`) are a follow-up. */
+    registerSsePaths(paths: string[]): void;
+    /** Register the list of literal route paths that should be dispatched as
+     * WebSocket upgrades. Call from the main process after defineRoutes.
+     * MVP supports only literal paths — parameterized routes (e.g.
+     * `/ws/chat/{room}`) are a follow-up. */
+    registerWsPaths(paths: string[]): void;
+    /** Set the L1 response-cache and L2 page-cache capacities (entries).
+     * Default is 1000 each. Rust reconstructs both caches at the given
+     * capacities (moka fixes capacity at construction), so call this once at
+     * boot before serving begins. */
+    configureCache(opts: {
+        maxEntries: number;
+        pageMaxEntries: number;
+    }): void;
+    /** Tell Rust where to read `/_brust/islands/<file>` from. Called once at
+     * boot after buildIslands() emits chunks. Path must be absolute. */
+    configureIslandsDir(dir: string): void;
+    /** Tell Rust where to read `/_brust/css/<file>` from. Called from the
+     * main thread when CSS is configured. Path must be absolute. */
+    configureCssDir(dir: string): void;
+    /** Tell Rust where to read root-mapped static assets (`/favicon.ico`, …) from.
+     * Path must be absolute. */
+    configurePublicDir(dir: string): void;
+    /** Extract the MCP manifest from TypeScript source using the compiler API,
+     * write it to `.brust/mcp-manifest.json`, and return it. Call once in the
+     * main process after `brust.registerRoutes(routes)`. Workers must read the
+     * persisted manifest themselves via `brust.loadMcpManifest()` in the worker
+     * branch and pass an `McpServer` (built via `makeMcpServer`) to
+     * `makeRenderer` via `opts.mcp`. See example/pokedex/index.ts. */
+    buildMcpManifest(opts: {
+        actionsFile?: string;
+        routesFile: string;
+        sourceRoots: string[];
+        routes: import("./routes.ts").FlatRoute[];
+        cwd?: string;
+    }): Promise<import("./mcp/manifest.ts").McpManifest>;
+    /** Read the MCP manifest from `.brust/mcp-manifest.json`. Returns null if
+     * the file does not exist (i.e. the main process hasn't called
+     * `brust.buildMcpManifest` yet). Throws if the file is malformed. */
+    loadMcpManifest(cwd?: string): Promise<import("./mcp/manifest.ts").McpManifest | null>;
+    registerRenderer(buf: Uint8Array, slots: number, fn: RenderFn): number;
+    /**
+     * One-call lifecycle: scans actions, builds islands (if `routes.tsx` uses
+     * `<Island>`), registers routes + SSE/WS paths, builds the MCP manifest, then
+     * branches to `serve()` (main thread) or registers a renderer (worker
+     * thread). Replaces ~70 lines of boilerplate; the lower-level helpers
+     * (`scanActions`, `registerRoutes`, `makeRenderer`, etc.) are still exported
+     * for apps that need finer control.
+     *
+     * Conventions assumed (override via the corresponding option if your layout
+     * differs):
+     *   - `<scanRoot>/routes.tsx`       — scanned for `<Island>` usage (islands)
+     *                                     and referenced by the MCP manifest builder
+     *
+     * `scanRoot` defaults to the directory of `entry` so the typical caller
+     * passes only `{ routes, entry: import.meta.url }`.
+     */
+    run(opts: {
+        routes: import("./routes.ts").FlatRoute[];
+        entry: string;
+        scanRoot?: string;
+        /** Host/address to bind on. Default `localhost`. A `brust dev --port` /
+         * BRUST_PORT / BRUST_ADDR / brust.toml all override this app-level value
+         * (precedence: env > toml > this > framework default). */
+        address?: string;
+        /** TCP port to bind on. Default 1337. Overridable by env/toml — see
+         * `address`. */
+        port?: number;
+        /** Actions builder from `defineActions(...)`. Registered with Rust and
+         * threaded to each worker's renderer. Omit if the app has no actions. */
+        actions?: import("./define-actions.ts").ActionsBuilder;
+        /** URL prefix the action router mounts under. Threaded to serve(). */
+        actionPrefix?: string;
+        /** Optional global CORS policy — see {@link CorsOptions}. Threaded to
+         * serve() like `actionPrefix`. */
+        cors?: CorsOptions;
+        /** Overrides merged into the underlying `serve()` call (main thread). */
+        serve?: Partial<Omit<ServeOptions, "entry" | "actions" | "mcp">>;
+        /** Per-worker SAB size in bytes. Default 256 KB. */
+        sabBytes?: number;
+        /** When true, prepend the dev WS route, install file watcher, set the
+         * dev-client snippet, and start the TUI. Default false.
+         * Also activated by BRUST_DEV=1 environment variable. */
+        dev?: boolean;
+    }): Promise<void>;
+};
+export { defineRoutes, makeRenderer, Outlet, notFound, redirect, isNativeVerdict, httpError, isHttpErrorTrigger, } from './routes.ts';
+export type { Route, RouteCall, RouteContext, ErrorBoundaryProps, RouteCacheConfig, BrustRequest, RouteResponse, Middleware, NativeVerdict, HttpErrorOpts, HttpErrorTrigger, } from './routes.ts';
+export { defineActions, isValidEndpointPath } from './define-actions.ts';
+export type { EndpointDef, ActionContext, EndpointOptions, ActionsBuilder, } from './define-actions.ts';
+export { ActionError, isActionError } from './action-error.ts';
+export type { ActionErrorBody } from './action-error.ts';
+export { loadConfig, BrustConfigError } from './config.ts';
+export type { BrustConfig } from './config.ts';
+export { Island } from './islands/island.tsx';
+export type { IslandProps, HydrateTrigger } from './islands/island.tsx';
+import './islands/isr-jsx.ts';
+export type { IsrConfig } from './islands/isr-jsx.ts';
+export { BrustPage } from './islands/brust-page.tsx';
+export type { BrustPageProps, HeadEntry } from './islands/brust-page.tsx';
+export { defineStore, signal, computed, effect, batch } from './store/index.ts';
+export type { StoreHandle, Snapshot, Signal, Computed } from './store/index.ts';
+export { dedupe, cachedFetch } from './loader-cache.ts';
+export { renderFragment } from './render/fragment.ts';
+export type { RenderFragmentOpts } from './render/fragment.ts';
+export { buildIslands } from './islands/build.ts';
+export type { IslandsBuildResult, BuildIslandsOptions } from './islands/build.ts';
+export { cache } from './cache.ts';
+export type { InvalidateArgs } from './cache.ts';
+export { templates } from './templates.ts';
+export { getRequestContext } from './request-context.ts';
+export { cookies } from './cookies.ts';
+export type { CookieOptions } from './cookies.ts';

package/types/islands/brust-page.d.ts

@@ -0,0 +1,74 @@
+import { type ReactNode } from 'react';
+/** Props for the built-in `<BrustPage>` document shell.
+ *
+ * `<BrustPage>` is a NATIVE-route document component: in a `native: true` route
+ * the Rust JSX compiler intercepts the `BrustPage` tag and emits the whole
+ * `<html>/<head>/<body>` skeleton itself, auto-injecting the framework head tags
+ * (charset, viewport, the `/_brust/css/app.css` stylesheet link). The head is
+ * configured ENTIRELY through these props — you never write `<head>` markup, so
+ * brust keeps full ownership of `<head>` and can add more tags later (importmap,
+ * preloads) without colliding with hand-written head elements.
+ *
+ * On the native path each prop accepts a compile-time string literal OR a
+ * loader member-path (`title={data.title}`), interpolated into the Rust-rendered
+ * shell as `{{ path }}` (S8). Calls/arithmetic are still rejected. This React
+ * implementation mirrors the compiled output for the rare non-native use. */
+/** One extra `<head>` element for `<BrustPage head={[…]}>`. Discriminated by
+ * `tag`. On the native path, attribute values may be a string literal or a
+ * loader member-path (HTML-escaped); `text` (inner content of style/script/
+ * noscript) must be a static string literal (raw — never user input). */
+export type HeadEntry = {
+    tag: 'link';
+    rel: string;
+    href: string;
+    type?: string;
+    sizes?: string;
+    as?: string;
+    media?: string;
+    crossOrigin?: string;
+} | {
+    tag: 'meta';
+    name?: string;
+    property?: string;
+    httpEquiv?: string;
+    content: string;
+} | {
+    tag: 'base';
+    href?: string;
+    target?: string;
+} | {
+    tag: 'style';
+    text: string;
+    media?: string;
+} | {
+    tag: 'script';
+    src?: string;
+    text?: string;
+    type?: string;
+    defer?: boolean;
+    async?: boolean;
+    crossOrigin?: string;
+} | {
+    tag: 'noscript';
+    text: string;
+};
+export interface BrustPageProps {
+    /** `<html lang>` — defaults to `"en"`. */
+    lang?: string;
+    /** `<html class>` (e.g. `"dark"`). */
+    className?: string;
+    /** `<body class>`. */
+    bodyClassName?: string;
+    /** `<title>…</title>`. Omitted when absent. */
+    title?: string;
+    /** `<meta name="description" content="…">`. Omitted when absent. */
+    description?: string;
+    /** Extra `<head>` elements (link/meta/base/style/script/noscript). */
+    head?: HeadEntry[];
+    /** Page body — rendered inside `<body>`. */
+    children?: ReactNode;
+    /** Arbitrary `data-*` on `<html>` (e.g. `data-mode="dark"`). String literal
+     *  or loader member-path on the native path. */
+    [dataAttr: `data-${string}`]: string | undefined;
+}
+export declare function BrustPage({ lang, className, bodyClassName, title, description, head, children, ...rest }: BrustPageProps): ReactNode;

package/types/islands/build.d.ts

@@ -0,0 +1,49 @@
+import type { BunPlugin } from 'bun';
+export interface IslandsBuildResult {
+    /** Absolute path to the output directory passed to brust's Rust side. */
+    outDir: string;
+    /** Number of island chunks emitted (excludes runtime + bootstrap). */
+    islandCount: number;
+    /** id → content-addressed chunk URL (`/_brust/islands/<id>_<hash>.js`). Also
+     * written to `_islands.js` for the client bootstrap to resolve at runtime. */
+    chunks: Record<string, string>;
+}
+export interface BuildIslandsOptions {
+    /** Override the output directory. Default: `<cwd>/.brust/islands`. */
+    outDir?: string;
+    /** Build plugins passed straight to `Bun.build` for the per-island chunks.
+     * Needed for the component-CSS loader: global `Bun.plugin()` registrations do
+     * NOT apply to `Bun.build`, so an island that `import`s a `.module.css` must
+     * get the resolver here or Bun emits the CSS as a separate asset and collides
+     * on the output filename (X.module.css + X.tsx → both X.js). */
+    plugins?: BunPlugin[];
+}
+/** Scan a routes entry file for `<Island component={X} />` usage and derive the
+ * island chunk list (componentName → absolute source path). Replaces the old
+ * static config-file lookup — the chunk set is derived from source.
+ *
+ * 1. Resolve the entry's page imports via {@link scanImports}.
+ * 2. For each page, slice every `<Island … />` tag and capture its
+ *    `component={Ident}`. A tag with no `component` is a hard error (F3:
+ *    never silently skip an island).
+ * 3. Resolve each captured ident through that page's OWN imports.
+ * 4. Key by the content-addressed {@link islandChunkBasename} (`<Name>_<hash>`),
+ *    NOT the bare name — so two DIFFERENT files exporting a same-named component
+ *    produce two distinct chunks. Same name + same file dedups (same id). The
+ *    marker carries this same id (native: reconcileIslandManifest rewrite;
+ *    React: the Component→id registry seeded at worker boot), so there is no
+ *    app-unique-name requirement.
+ *
+ * `extraIslands` (task 2.8) merges additional islands the routes-graph scan
+ * cannot see — md-route islands resolved by `emitMdTemplates` (`name →
+ * absolute source path`, the bare-name map it returns). Each is keyed by the
+ * same content-addressed id, so same name + same path dedups against the scan
+ * result; same name + different path yields a distinct id (two chunks, the
+ * shipped same-name parity). A same-id-different-path collision is a hard
+ * error — never silently rebind a chunk id.
+ */
+export declare function scanIslandChunks(routesEntryFile: string, extraIslands?: Map<string, string>): Map<string, string>;
+/** Build the runtime chunks + all island chunks + bootstrap. Returns the
+ * absolute output directory; caller passes it to `brust.configureIslandsDir`. */
+export declare function buildIslands(islands: Map<string, string>, options?: BuildIslandsOptions): Promise<IslandsBuildResult>;
+export declare function buildOne(entrypoints: string[], outdir: string, naming: string, external: string[], plugins?: BunPlugin[]): Promise<void>;

package/types/islands/chunk-id.d.ts

@@ -0,0 +1,10 @@
+/** Content-addressed island id / chunk basename = `<Name>_<8hex(sha256
+ * cwd-relative source path)>`. The SINGLE name contract (mirrors the directive
+ * chunk scheme): the chunk filename, the `data-brust-island` marker (native
+ * rewrite in reconcileIslandManifest + the React island-id onLoad plugin), and
+ * the bootstrap import all derive from this — so two same-named components from
+ * different files get distinct ids and never collide.
+ *
+ * Lives in its own module (no `scanImports` dep) so both `islands/build.ts` and
+ * `cli/native-routes-emit.ts` can import it without a circular dependency. */
+export declare function islandChunkBasename(name: string, absSourcePath: string): string;

package/types/islands/importmap.d.ts

@@ -0,0 +1,2 @@
+export declare const ISLANDS_IMPORTMAP_AND_BOOTSTRAP: string;
+export declare const DIRECTIVES_BOOTSTRAP = "<script type=\"module\" src=\"/_brust/islands/_directives.js\" defer></script>";

package/types/islands/island.d.ts

@@ -0,0 +1,65 @@
+import { type ComponentType, type ReactNode } from 'react';
+import type { IsrConfig } from './isr-jsx.ts';
+/** Triggers that activate hydration of an island marker. */
+export type HydrateTrigger = 'load' | 'idle' | 'visible' | 'interaction';
+export interface IslandProps<P> {
+    /** Component rendered server-side INSIDE the marker. Same component
+     * the client chunk default-exports — SSR HTML must match the post-hydrate
+     * tree to avoid React reconciliation warnings. Its `Component.name` is the
+     * island id: it names the chunk (`<name>.js`) and the `data-brust-island`
+     * marker the client bootstrap reads, so it must be a stable, named
+     * component (no anonymous default export). */
+    component: ComponentType<P>;
+    /** Props passed to the component on both server and client. Must be
+     * JSON-serializable (no functions, classes, DOM nodes, etc.). Optional — a
+     * propless island (e.g. one that reads only global/client state) may omit it;
+     * it defaults to `{}`. On native routes, omitting `props` lowers to an empty
+     * props_path the renderer fills with `{}`. */
+    props?: P;
+    /** When to hydrate. Default 'load'. */
+    hydrate?: HydrateTrigger;
+    /** Native routes only: render this island server-side (renderToString during
+     * the loader crossing) so its markup ships in the HTML, then hydrate. Ignored
+     * on the React path (the whole tree already SSRs there). Default false. */
+    ssr?: boolean;
+    /**
+     * Optional ISR (incremental static regeneration) cache for an `ssr` island on
+     * a native-jinja route. When present, the island's `renderToString` runs ONCE
+     * per `key`; later requests serve the frozen markup from the Rust-side cache.
+     * Ignored unless `ssr` is set (caching a client-only island is meaningless).
+     *
+     * - `key` (required): unique string identifying this cache entry. A different
+     *   key is a different cached render. Compute it in the loader and pass it
+     *   through, e.g. `isr={{ key: data.cacheKey }}`.
+     * - `tags` (optional): groups for bulk invalidation —
+     *   `import { cache } from 'brustjs'; cache.invalidate({ tags: ['blog'] })`
+     *   evicts every entry carrying that tag. `cache.invalidate({ key })` evicts one.
+     * - `revalidate` (optional): TTL in **seconds** (integer). Omit to cache until
+     *   explicitly invalidated.
+     *
+     * Example: `isr={{ key: data.cacheKey, tags: ['blog'], revalidate: 60 }}`
+     */
+    isr?: IsrConfig;
+}
+/** Per-render box tracking whether any `<Island>` rendered. Created fresh per
+ * render and provided through {@link IslandUsedContext}; the renderer reads
+ * `box.used` once at the end to decide whether to prepend the importmap +
+ * bootstrap script.
+ *
+ * This is REQUEST-SCOPED (not a module-scope flag) so concurrent renders in one
+ * isolate (renderSlots>1) never cross-contaminate: React restores each render's
+ * context stack across Suspense resumption, so an interleaved peer setting its
+ * own box never flips ours. A module `let` could not give that guarantee. */
+export interface IslandUsedBox {
+    used: boolean;
+}
+/** Fresh per-render box. */
+export declare function createIslandUsedBox(): IslandUsedBox;
+/** Seed the Component→id registry (worker boot). */
+export declare function configureIslandIdRegistry(entries: Iterable<[unknown, string]>): void;
+/** Carries the per-render {@link IslandUsedBox} down to every `<Island>`. The
+ * renderer wraps the tree in a Provider with a fresh box; an `<Island>` rendered
+ * with no Provider (e.g. a standalone `renderToString` outside the React render
+ * path) reads `null` and is a no-op. */
+export declare const IslandUsedContext: import("react").Context<IslandUsedBox>;
+export declare function Island<P extends object>({ component: Component, props, hydrate, }: IslandProps<P>): ReactNode;

package/types/islands/isr-jsx.d.ts

@@ -0,0 +1,31 @@
+/** Shape of the `isr` attribute on an SSR component or `ssr` island on a
+ * native-jinja route. `renderToString` runs ONCE per `key`; later same-key
+ * requests serve the frozen markup from the Rust-side cache. */
+export interface IsrConfig {
+    /** Required unique cache key. A different key is a different cached render.
+     * Compute it in the loader and pass it through (e.g. `data.cacheKey`). */
+    key: string;
+    /** Optional groups for bulk invalidation —
+     * `import { cache } from 'brustjs'; cache.invalidate({ tags: ['blog'] })`
+     * evicts every entry carrying a tag. `cache.invalidate({ key })` evicts one. */
+    tags?: string[];
+    /** Optional TTL in SECONDS (integer). Omit to cache until invalidated. */
+    revalidate?: number;
+}
+declare module 'react' {
+    namespace JSX {
+        interface IntrinsicAttributes {
+            /** brust ISR cache directive — compiler-consumed (stripped before the
+             * component is called), valid on any SSR component or `ssr` island on a
+             * native route. See {@link IsrConfig}. */
+            isr?: IsrConfig;
+            /** brust `native` inline directive — compiler-consumed (stripped at lower
+             * time). On a native-jinja route, `<Comp native />` expands the component
+             * inline at compile time (no JS-worker render) when it is pure
+             * (props→JSX, no hooks/side-effects); otherwise it degrades to a normal
+             * SSR component with a build warning. Bare boolean, like `ssr` on an
+             * island. */
+            native?: boolean;
+        }
+    }
+}

package/types/islands/native-render.d.ts

@@ -0,0 +1,89 @@
+/** Set the directory the sidecar-manifest readers resolve against. Called once
+ * at boot from `index.ts`, mirroring `configureIslandsDir`/`configureCssDir`. */
+export declare function configureJinjaDir(dir: string): void;
+/** One entry of a `<template>.islands.json` manifest (enriched by T6). */
+export interface NativeIslandEntry {
+    component: string;
+    instance: number;
+    propsPath: string;
+    /** Literal props value baked at build time (md pages). When present
+     * (`!== undefined` — `null` and falsy literals are valid), it is used as the
+     * props value and `propsPath` is ignored (md entries carry `propsPath: ''`
+     * since the field is required). */
+    propsLiteral?: unknown;
+    ssr: boolean;
+    hydrate: string;
+    sourcePath: string;
+    /** Dotted path into loader data yielding the ISR cache key (string). */
+    keyPath?: string;
+    /** Dotted path into loader data yielding the ISR cache tags (string[]). */
+    tagsPath?: string;
+    /** Revalidate window in SECONDS; converted to ttlMs on cache.set. */
+    revalidate?: number;
+    /** Static ISR cache key (string literal in JSX). Takes precedence over keyPath. */
+    keyLiteral?: string;
+    /** Static ISR cache tags (array literal in JSX). Takes precedence over tagsPath. */
+    tagsLiteral?: string[];
+}
+/** Rust-side ISR cache, injected as a port for testability. A `get` hit
+ * returns a FROZEN {html,props} pair (the props are the entity-encoded attr
+ * string, identical to what was stored) so the served markup and the hydrated
+ * props stay byte-identical regardless of live loader-data mutation. */
+export interface IslandCache {
+    get(key: string): {
+        html: string;
+        props: string;
+    } | null;
+    set(key: string, tags: string[], ttlMs: number | undefined, html: string, props: string): void;
+}
+/** Walk a dotted path into `data`. Each segment must be an OWN enumerable
+ * property — inherited keys (`constructor`, `__proto__`, `toString`, …) yield
+ * `undefined` rather than traversing the prototype chain. This blocks both
+ * prototype-pollution-style reads AND the downstream crash where a resolved
+ * function (`Object`) makes `JSON.stringify` return `undefined`. A missing
+ * segment, a nullish/primitive cursor, or a non-own key all yield `undefined`.
+ * An empty path returns `data` itself. */
+export declare function pathInto(data: unknown, propsPath: string): unknown;
+/** HTML-entity-encode a string for a double-quoted attribute value. Order is
+ * load-bearing: `&` MUST be replaced first so the entities introduced by the
+ * later replacements aren't themselves double-encoded. Matches the compiler's
+ * `push_attr_escaped` charset (& < > ") so server-rendered markup and these
+ * props attrs stay consistent. */
+export declare function entityEncode(s: string): string;
+/** Read `<jinjaDir>/<templateName>.islands.json` and return the parsed entry
+ * array, or `null` if the file doesn't exist. `jinjaDir` defaults to the
+ * boot-configured jinja dir (`configureJinjaDir`), or `cwd/.brust/jinja` when
+ * unset; tests pass a temp dir. Both hits and misses are cached by absolute path. */
+export declare function loadIslandManifest(templateName: string, jinjaDir?: string): NativeIslandEntry[] | null;
+/** Build the per-island context additions for a manifest. Each entry
+ * contributes `island_<instance>_props` — the resolved props, JSON-stringified
+ * (undefined → null so it stays valid JSON) and entity-encoded. SSR entries
+ * (`ssr:true`) ALSO contribute `island_<instance>_html` — the island source
+ * component imported by absolute path and renderToString'd. The `instance` is a
+ * per-occurrence integer, so it's a safe key fragment. */
+export declare function resolveIslandContext(manifest: NativeIslandEntry[], data: unknown, cache?: IslandCache): Promise<Record<string, string>>;
+/** One entry in `<Name>.components.json` as enriched by `emitComponentArtifacts`. */
+export interface NativeComponentEntry {
+    component: string;
+    instance: number;
+    sourcePath: string;
+    /** Dotted path into loader data yielding the ISR cache key (string). */
+    keyPath?: string;
+    /** Dotted path into loader data yielding the ISR cache tags (string[]). */
+    tagsPath?: string;
+    /** Revalidate window in SECONDS; converted to ttlMs on cache.set. */
+    revalidate?: number;
+    /** Static ISR cache key (string literal in JSX). Takes precedence over keyPath. */
+    keyLiteral?: string;
+    /** Static ISR cache tags (array literal in JSX). Takes precedence over tagsPath. */
+    tagsLiteral?: string[];
+}
+/** Read `<jinjaDir>/<templateName>.components.json` and return the parsed entry
+ * array, or `null` if the file doesn't exist. Both hits and misses are cached
+ * by absolute path (same invariant as `loadIslandManifest`). */
+export declare function loadComponentManifest(templateName: string, jinjaDir?: string): NativeComponentEntry[] | null;
+/** Build the per-component context additions for a manifest. Each entry
+ * contributes `comp_<instance>_html` — the component rendered to HTML by
+ * the route's factory function. On `renderToString` failure: degrade to
+ * `comp_N_html = ""` and log, mirrors SSR island failure behaviour. */
+export declare function resolveComponentContext(manifest: NativeComponentEntry[], data: unknown, templateName: string, jinjaDir?: string, cache?: IslandCache): Promise<Record<string, string>>;

package/types/loader-cache.d.ts

@@ -0,0 +1,18 @@
+export declare function runInRequestCache<T>(fn: () => T): T;
+/** Request-scoped memoize: share the in-flight promise + cache result for the
+ * scope's lifetime. Outside a scope → passthrough. Reject → guarded delete
+ * (identity-checked) so a stale catch can't evict a newer entry.
+ *
+ * NOTE: the reject cleanup runs one microtask after rejection, so a caller that
+ * dedupes the SAME key within that gap receives the about-to-reject promise (and
+ * thus the rejection) — acceptable: the result is one shared failure, not a hang. */
+export declare function dedupe<T>(key: string, fn: () => Promise<T>): Promise<T>;
+/** Idempotent (GET/HEAD) fetch deduped per request; non-idempotent → bypass.
+ * Returns a fresh clone every call (the stored Response is never exposed).
+ *
+ * NOTE: the cache key is `method + url` ONLY — it does NOT include `init`
+ * headers/body. Two `cachedFetch(sameUrl, {headers:…})` calls with DIFFERENT
+ * headers in one request share the FIRST call's response. Intended for plain
+ * idempotent GETs (the common loader case); if a caller varies `init` per call
+ * on the same URL, use `fetch` directly. */
+export declare function cachedFetch(url: string, init?: RequestInit): Promise<Response>;

package/types/mcp/extractor.d.ts

@@ -0,0 +1,14 @@
+import type { FlatRoute } from '../routes.ts';
+import type { McpManifest } from './manifest.ts';
+export interface ExtractOptions {
+    /** Module exporting `defineActions(...)`. Convention `<scanRoot>/actions.ts`.
+     * Absent → zero tools (resources still extracted). */
+    actionsFile?: string;
+    /** The routes module file. */
+    routesFile: string;
+    /** User source roots. Reserved for future tsconfig resolution. */
+    sourceRoots: string[];
+    /** Result of `defineRoutes(...)`. */
+    routes: FlatRoute[];
+}
+export declare function extractMcpManifest(opts: ExtractOptions): Promise<McpManifest>;

package/types/mcp/manifest.d.ts

@@ -0,0 +1,23 @@
+import type { JsonSchema } from './schema.ts';
+export interface ToolSchema {
+    name: string;
+    description?: string;
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+    path: string;
+    inputSchema: JsonSchema;
+    outputSchema?: JsonSchema;
+}
+export interface ResourceSchema {
+    uriTemplate: string;
+    name: string;
+    description?: string;
+    outputSchema?: JsonSchema;
+    routeIndex: number;
+}
+export interface McpManifest {
+    version: 1;
+    tools: ToolSchema[];
+    resources: ResourceSchema[];
+}
+export declare function writeManifest(cwd: string, m: McpManifest): Promise<void>;
+export declare function readManifest(cwd: string): Promise<McpManifest | null>;

package/types/mcp/schema.d.ts

@@ -0,0 +1,19 @@
+import ts from 'typescript';
+export interface JsonSchema {
+    type?: string | string[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    prefixItems?: JsonSchema[];
+    minItems?: number;
+    maxItems?: number;
+    additionalProperties?: JsonSchema | boolean;
+    anyOf?: JsonSchema[];
+    enum?: unknown[];
+    format?: string;
+}
+export interface ToJsonSchemaOptions {
+    unwrapPromise?: boolean;
+    checker?: ts.TypeChecker;
+}
+export declare function tsTypeToJsonSchema(type: ts.Type, opts?: ToJsonSchemaOptions): JsonSchema | undefined;

package/types/mcp/server.d.ts

@@ -0,0 +1,15 @@
+import type { FlatRoute, BrustRequest } from '../routes.ts';
+import type { EndpointDef } from '../define-actions.ts';
+import type { McpManifest } from './manifest.ts';
+export interface McpServerOptions {
+    manifest: McpManifest;
+    endpoints: EndpointDef[];
+    routes: FlatRoute[];
+    packageVersion?: string;
+}
+export interface McpServer {
+    handleRequest(jsonRpcBody: string, req: BrustRequest): Promise<string>;
+}
+export declare function makeMcpServer(opts: McpServerOptions): McpServer;
+export declare function makeResult(id: number | string | null, result: unknown): string;
+export declare function makeError(id: number | string | null, code: number, message: string): string;