brustjs 0.1.50-alpha → 0.1.52-alpha

package/types/dev/client.d.ts

@@ -0,0 +1,8 @@
+/** Browser dev client. Inlined into the SSR first chunk via a <script
+ * type="module">…</script> wrapper. Connects WS at /_brust/dev, handles
+ * reload / css-update / error / ok messages, manages a red overlay.
+ *
+ * Keep this string short — it ships in every dev-mode SSR response. */
+export declare const DEV_CLIENT_JS: string;
+/** Build the full <script> tag that gets spliced before </head>. */
+export declare function buildDevClientTag(): string;

package/types/dev/coordinator.d.ts

@@ -0,0 +1,33 @@
+import type { DevMessage } from './ws-channel.ts';
+import type { ChangeKind } from './watcher.ts';
+export interface CoordinatorDeps {
+    workers: {
+        terminateAll(): Promise<void>;
+        spawnAll(): Promise<void>;
+    };
+    buildCss: () => Promise<void>;
+    buildIslands: () => Promise<void>;
+    /** Recompile native-route `.jinja` templates from source and reload them into
+     * the minijinja env, so `native: true` routes pick up .tsx edits on reload. */
+    reEmitJinja: () => Promise<void>;
+    /** Clear the Rust-side island ISR cache. Called on every render-affecting
+     * reload (`ts`/`html`/`islands`) so a `.tsx` edit is reflected immediately —
+     * a frozen island render from before the edit must never survive a hot reload.
+     * Optional: a build without the island-cache addon export omits it. */
+    clearIslandCache?: () => void;
+    buildComponentCss?: () => Promise<void>;
+    snapshotComponentCss?: () => Promise<import('../css/manifest.ts').ComponentCssManifest | null>;
+    broadcast: (msg: DevMessage) => Promise<void> | void;
+    tui: {
+        appendEvent(line: string): void;
+    };
+}
+export declare class Coordinator {
+    private deps;
+    private state;
+    constructor(deps: CoordinatorDeps);
+    handleChange(ev: {
+        paths: string[];
+        kind: ChangeKind;
+    }): Promise<void>;
+}

package/types/dev/inject.d.ts

@@ -0,0 +1,6 @@
+/** Set the dev-client snippet (full `<script>…</script>` tag) the renderer
+ * should inject before `</head>`. Pass `null` to disable injection (the
+ * default in non-dev mode). */
+export declare function configureDevClientSnippet(s: string | null): void;
+/** Returns the configured snippet, or `null` when dev mode is off. */
+export declare function getDevClientSnippet(): string | null;

package/types/dev/jinja-reload.d.ts

@@ -0,0 +1,7 @@
+/** Called once by `brust dev` after the initial native-template emit. */
+export declare function registerJinjaReEmit(fn: () => Promise<void>): void;
+/** Called by the dev coordinator on a ts/html/islands hot reload. No-op when no
+ * callback is registered (e.g. unit tests, or an app with no native routes). */
+export declare function reEmitJinja(): Promise<void>;
+/** Test helper. */
+export declare function _resetForTests(): void;

package/types/dev/tui.d.ts

@@ -0,0 +1,35 @@
+interface Status {
+    port: number;
+    workers: number;
+    watching: string[];
+}
+export interface TuiOptions {
+    isTty: boolean;
+    write: (s: string) => void;
+    capacity?: number;
+}
+/** Astro-style dev output: a clean one-time banner on ready, then event lines
+ * that scroll naturally below it. Deliberately NOT a full-screen TUI — it never
+ * hides the cursor or clears the screen, so the terminal is left exactly as it
+ * was found when the dev server exits (no more vanished cursor on Ctrl-C). */
+export declare class Tui {
+    private opts;
+    private events;
+    private capacity;
+    private bannerShown;
+    constructor(opts: TuiOptions);
+    eventsForTests(): string[];
+    /** Print the ready banner. Idempotent — only the first call emits it. */
+    updateStatus(s: Status): void;
+    /** Append one event. Scrolls below the banner (TTY) or prints a plain line
+     * (non-TTY / CI). The in-memory ring buffer backs `eventsForTests`. */
+    appendEvent(line: string): void;
+    /** Called on shutdown. There is nothing to restore (we never altered the
+     * terminal mode); the reset is belt-and-braces so a half-written colored
+     * line can't bleed into the user's prompt. */
+    stop(): void;
+    /** Colorize an event line in TTY mode: a dim timestamp prefix, with ok/error
+     * markers tinted. The coordinator emits `  → ok (Nms)` and `  ✗ <msg>`. */
+    private format;
+}
+export {};

package/types/dev/watcher.d.ts

@@ -0,0 +1,34 @@
+export type ChangeKind = 'ts' | 'css' | 'component-css' | 'html' | 'islands' | 'md';
+/** Classify a changed path. Returns null when the path should be ignored.
+ * `root` is used to compute the relative path for ignore-segment matching.
+ * `hasMdRoutes` gates the `'md'` kind (S4): when the app has no md routes, a
+ * project `.md` edit (README.md, notes) must not trigger the full reload path
+ * (island rebuild + worker restart) — it classifies as null instead. Defaults
+ * to true for backward compatibility with callers that don't thread the flag. */
+export declare function classifyPath(absPath: string, root: string, hasMdRoutes?: boolean): ChangeKind | null;
+interface Coalesce {
+    add(path: string): void;
+    flush(): void;
+}
+/** Internal — exposed for unit tests. */
+export declare function _testCoalesce(debounceMs: number, flush: (paths: string[]) => void): Coalesce;
+export interface CreateWatcherOptions {
+    root: string;
+    debounceMs?: number;
+    /** Whether the app has md routes — gates `.md` classification (see
+     * classifyPath). Defaults to true (back-compat). */
+    hasMdRoutes?: boolean;
+    onChange: (ev: {
+        paths: string[];
+        kind: ChangeKind;
+    }) => void;
+}
+export interface Watcher {
+    close(): void;
+}
+/** Watch `root` recursively. Emits one `onChange` call per debounce window
+ * with paths classified by the dominant kind. Mixed-kind windows pick
+ * by priority: islands > ts > html > css (islands trigger a full restart
+ * that subsumes the others). */
+export declare function createWatcher(opts: CreateWatcherOptions): Watcher;
+export {};

package/types/dev/worker-registry.d.ts

@@ -0,0 +1,17 @@
+/** Called once by brust.serve() in dev mode AFTER it spawns the initial
+ * pool. Hands the references to the registry so the coordinator can
+ * churn them later. */
+export declare function registerInitialPool(workers: Worker[], entry: string, count: number, baseEnv: Record<string, string>): void;
+/** Terminate every Worker with a 2s per-worker grace. If termination
+ * doesn't return in time, abandon the reference and continue. */
+export declare function terminateAll(): Promise<void>;
+/** Spawn `count` fresh Workers using the entry + env captured at
+ * registerInitialPool time. Each worker gets BRUST_WORKER_ID=i.
+ * Resolves only after every fresh worker reports `brust-worker-ready`
+ * via postMessage — so the caller (coordinator) doesn't broadcast
+ * `reload` against workers whose message listeners aren't installed
+ * yet. Falls back after a 5s grace if a worker never signals. */
+export declare function spawnAll(): Promise<void>;
+/** Test helper. */
+export declare function _workersForTests(): Worker[];
+export declare function _resetForTests(): void;

package/types/dev/ws-channel.d.ts

@@ -0,0 +1,39 @@
+import type { Route } from '../routes.ts';
+/** Server-to-client protocol. Client never sends after open. */
+export type DevMessage = {
+    type: 'building';
+} | {
+    type: 'reload';
+} | {
+    type: 'css-update';
+    href: string;
+} | {
+    type: 'error';
+    message: string;
+    stack?: string;
+} | {
+    type: 'ok';
+};
+export declare function _clientCountForTests(): number;
+export declare function _resetForTests(): void;
+/** Build the synthetic /_brust/dev WS route. brust.run() prepends this
+ * to opts.routes in dev mode (both main + worker route arrays). */
+export declare function createDevWsRoute(): Route;
+/** Worker-side: install a message listener that receives `dev-broadcast`
+ * envelopes from the main process and forwards them to this worker's
+ * local clients. Idempotent. After install, posts `brust-worker-ready`
+ * back to the parent so spawnAll() knows the worker is ready to relay
+ * broadcasts (avoids a race where `reload` is dispatched before the
+ * fresh worker's listener is wired). */
+export declare function installWorkerBroadcastListener(): void;
+/** Main-side: push the message to every `/_brust/dev` client through the napi
+ * addon. The dev WS is a Rust-owned control channel (see the `/_brust/dev`
+ * branch in crates/brust/src/server.rs), so the frame is delivered straight
+ * through each connection's Rust-owned send_tx and SURVIVES a hot reload's
+ * worker restart.
+ *
+ * The previous implementation relayed main→worker→worker-local-clients, which
+ * lost the `reload` frame: the coordinator broadcasts it AFTER terminateAll(),
+ * by which point the connection's worker-side registration had died with the
+ * old worker. */
+export declare function broadcast(msg: DevMessage): Promise<void>;

package/types/generator.d.ts

@@ -0,0 +1,23 @@
+export interface GeneratorStrings {
+    /** Full meta tag, e.g. `<meta name="generator" content="brust 0.1.48-alpha"/>` */
+    meta: string;
+    /** X-Powered-By value, e.g. `brust/0.1.48-alpha` */
+    header: string;
+}
+/** Build the resolved strings. Version comes from the brustjs package.json
+ * (readVersion never throws — "unknown" degrades to name-only, never a crash).
+ * The version is sanitized to attr/header-safe bytes; semver chars only. */
+export declare function generatorStrings(versionOn: boolean): GeneratorStrings;
+/** Insert the generator meta immediately after the compiler-emitted viewport
+ * meta. Anchor missing (non-document template) → no-op, never an error.
+ * CALLER CONTRACT: pass fresh compiler output — this function does not check
+ * for an existing tag, so calling it twice on the same string duplicates.
+ * Every emit path recompiles from source each run, which keeps this safe. */
+export declare function insertGeneratorMeta(jinja: string, metaTag: string): string;
+/** Write the decision artifact into `dir` (a jinja out dir), creating it. */
+export declare function writeGeneratorArtifact(dir: string, strings: GeneratorStrings): void;
+/** Read the artifact; null on missing/malformed (caller decides the fallback). */
+export declare function readGeneratorArtifact(dir: string): GeneratorStrings | null;
+/** Artifact if present, else version-on defaults — the spec's fallback policy
+ * (an old dist with no artifact behaves as default = version on). */
+export declare function resolveGenerator(dir: string): GeneratorStrings;

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 | null>;
+export declare function Island<P extends object>({ component: Component, props, hydrate, }: IslandProps<P>): ReactNode;