brustjs 0.1.50-alpha → 0.1.52-alpha

package/types/cli/native-routes-emit.d.ts

@@ -0,0 +1,217 @@
+/** Gather transitive component sources starting from a page source file.
+ *
+ * BFS/DFS over local imports reachable from `pageSourcePath`:
+ * - Reads each file's source text and adds it to `sources[ident]`.
+ * - Recursively follows local imports in each visited file.
+ * - Deduplicates by resolved path to handle cycles.
+ * - `mergedImports` is the union of every visited file's `scanImports`, with
+ *   the page's own imports taking precedence on a conflicting ident.
+ *
+ * Throws when the same ident resolves to two different absolute paths (across
+ * two different importing files) — that would be ambiguous for the Rust
+ * compiler. */
+export declare function gatherComponentSources(pageSourcePath: string): {
+    sources: Record<string, string>;
+    mergedImports: Map<string, ResolvedImport>;
+};
+/** T2 / B1 fix — gather component sources for an ENTIRE native chain.
+ *
+ * The leaf of a composed chain is a bare fragment that no longer imports its
+ * ancestors, so seeding `gatherComponentSources` from the leaf alone would
+ * leave every ancestor's source ABSENT — `<AppLayout native>` would then
+ * silently soft-fall to an SsrComponent (React render) and break native. This
+ * unions `gatherComponentSources` over EVERY chain component's resolved source
+ * file (resolved name→file via the entry's `importMap`), then injects each
+ * chain component's OWN source keyed by its ident.
+ *
+ * Returns the merged `sources` map and `mergedImports` (ident→absolute path).
+ * Post-condition: `sources` has a key for every chain component name. Throws if
+ * a chain component name can't be resolved to a source file via `importMap`. */
+export declare function gatherChainSources(chainNames: string[], importMap: Map<string, string>): {
+    sources: Record<string, string>;
+    mergedImports: Map<string, ResolvedImport>;
+};
+/** T2 — build the synthetic wrapper SOURCE STRING for a native route chain.
+ *
+ * Given the component identifiers parent→leaf (e.g. `['AppLayout', 'Leaf']`),
+ * emit a default-exported function whose body nests every component, leaf
+ * innermost, with the `native` attribute on EVERY tag:
+ *
+ *   export default function Leaf__chain() { return <AppLayout native><Leaf native/></AppLayout>; }
+ *
+ * Load-bearing details:
+ * - `export default function` is required — the Rust compiler's
+ *   `find_default_export` only matches that exact form.
+ * - `native` on every tag — without it a nested component lowers to an
+ *   SsrComponent (React render) instead of being inlined into the chain.
+ * - The leaf tag is self-closing; each ancestor wraps the next via `<Outlet/>`
+ *   inside the ancestor's own source (the compiler substitutes the children
+ *   slot for `<Outlet/>`).
+ *
+ * The wrapper function name is `${leafName}__chain` — purely cosmetic (the
+ * compiler keys off the default export, not the name). */
+export declare function buildChainWrapperSource(chainNames: string[]): string;
+/** Count opening `<main>` tags in a compiled template. SPA navigation extracts
+ * the FIRST `<main>…</main>` block (routes.ts), so a composed native template
+ * must contain exactly one `<main>` — the layout owns it and leaf fragments must
+ * not add their own. More than one silently truncates the SPA-nav payload. */
+export declare function countMainTags(template: string): number;
+/** Dev-only: splice the /_brust/dev WS client `<script>` into a compiled native
+ * template so `native: true` (jinja) routes auto-reload like React-SSR routes.
+ *
+ * Native routes render Rust-side on the fast lane, bypassing the React renderer
+ * that injects the dev client (runtime/render/stream.ts) — so without this the
+ * browser on a native page never opens the dev WS and can never auto-reload.
+ *
+ * Inserted before the first `</head>` when the page has one (a `<BrustPage>`
+ * shell); otherwise appended (bare-fragment pages like a plain `<div>`). The
+ * browser executes the module script in either position. Gated on `BRUST_DEV`
+ * so `brust build` never bakes it into production templates.
+ *
+ * Exported for the md emit step (runtime/md/emit.ts), which bakes the same tag
+ * under its `withDevClient` option — md pages render Rust-side too, so without
+ * it they never auto-reload in dev. */
+export declare function injectDevClientIntoTemplate(template: string): string;
+/** Bake the directive runtime loader into a native template iff it uses any
+ * x-data directive. Idempotent. Wrapped in {% raw %} for symmetry with the islands
+ * bootstrap bake (the tag has no {{ }} but the wrap is harmless + consistent). */
+export declare function bakeDirectivesIfUsed(template: string, force?: boolean): string;
+/** Sub-project J — build pass that turns user's `pages/<Name>.tsx` files into
+ * `.brust/jinja/<Name>.jinja` templates. Invoked from `brust build` and
+ * `brust dev` after the user's routes are flattened.
+ *
+ * Limitations (spec S7 + S13.10):
+ * - Regex-based import scanner — handles `import Name from './path'` only.
+ *   Full swc AST + re-export chain support deferred to v2.x.
+ * - Dev mode does NOT hot-reload templates on .tsx edit. Boot-only; restart
+ *   required. Deferred per spec S12.
+ */
+export interface NativeRouteEmitOpts {
+    /** User's routes entry file (absolute path). Scanned for ImportDeclarations
+     * to resolve each native: true route's Component to its source .tsx. */
+    entryFile: string;
+    /** Flat routes array; only entries with `nativeTemplate` are emitted. The
+     * runtime objects are full FlatRoutes — `chain` (parent→leaf route nodes,
+     * each carrying its `Component`) drives T2 native-chain composition. */
+    flatRoutes: {
+        nativeTemplate?: string;
+        /** Chain nodes parent→leaf. A leaf carrying `__mdSource` is a markdown
+         * page (runtime/md/routes.ts) — emitted by `emitMdTemplates`, NOT here. */
+        chain?: Array<{
+            Component?: {
+                name?: string;
+            };
+            __mdSource?: unknown;
+        }>;
+    }[];
+    /** `.brust/jinja` absolute output dir. Created if missing. */
+    outDir: string;
+    /** Repo root. Retained for call-site compatibility; native compilation now
+     * goes through the napi addon's `compileJsx`, not a target/ binary. */
+    repoRoot: string;
+    /** Dev-loop incremental compile (R14). When true, each route's resolved
+     * compileJsx inputs (route source + every transitively imported local source
+     * + the lucide/directive/component-source env) are content-hashed and memoized
+     * for the lifetime of the process; an unchanged route SKIPS compileJsx and the
+     * sidecar rewrites (the previous emit's outputs are already on disk) but still
+     * appears in the returned manifest. ANY error in hashing falls back to a full
+     * compile — correctness over speed. Set only by `brust dev`'s emit calls;
+     * `brust build` stays full-fidelity (default false → no memo read OR write,
+     * and any stale memo entry for the route is dropped). */
+    incremental?: boolean;
+    /** TEST SEAM — replaces the canonical-input hasher so tests can prove the
+     * hash-failure → compile-all fallback. Never set outside tests. */
+    hashInputsForTest?: (canonicalInputs: string) => string;
+}
+/** Per-route emit outcome counts for `emitNativeTemplates` — testability seam
+ * for the dev-loop incremental memo (R14). `compiled + skipped` = routes
+ * emitted (routes dropped for a missing import count in neither). */
+export interface NativeEmitStats {
+    compiled: number;
+    skipped: number;
+}
+/** Clear the incremental memo (test isolation). */
+export declare function resetNativeEmitMemo(): void;
+/** Write `<Name>.components.json` and `<Name>.factory.ts` for a native route
+ * that has SSR components. Also scans each SSR component's source for Island
+ * `component={X}` references and returns those identifiers so the build step
+ * can ensure their JS chunks are built.
+ *
+ * Both artifacts use PROJECT-RELATIVE paths, never the build machine's absolute
+ * path: `components.json` stores `sourcePath` relative to the project root
+ * (cwd); `.factory.ts` imports relative to its own location (`.brust/jinja/`).
+ * `enriched` keeps the ABSOLUTE path internally for the build-time island scan
+ * below (`readFileSync`).
+ *
+ * Exported for the md emit step (runtime/md/emit.ts), whose chained wrappers
+ * can carry layout SSR components and need the same sidecar emission. */
+export declare function emitComponentArtifacts(jinjaPath: string, componentsJsonStr: string, pageImports: Map<string, ResolvedImport>, routeName: string): {
+    islandIdsFromComponents: string[];
+};
+export declare function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<NativeEmitStats>;
+/** A resolved import reference, capturing the import FORM so the SSR factory can
+ * regenerate the correct `import` statement. Used only by the SSR-component path
+ * (`gatherComponentSources`/`gatherChainSources` → `emitComponentArtifacts` /
+ * `reconcileIslandManifest`), NOT by `scanImports` (which stays local-default
+ * string-valued for the two external callers in islands/native build). */
+export interface ResolvedImport {
+    /** Module specifier: an ABSOLUTE file path for local imports, or the verbatim
+     * bare specifier for package imports. */
+    spec: string;
+    /** true ⇒ `spec` is a package/bare specifier (keep verbatim; do not
+     * readFileSync/relativize/recurse). */
+    bare: boolean;
+    /** How the symbol was imported, so the factory regenerates the right import. */
+    kind: 'default' | 'named' | 'namespace';
+    /** For `named`, the exported name (may differ from the local alias). */
+    imported?: string;
+}
+/** Scan ALL import forms in `file` and resolve each local-name binding to a
+ * {@link ResolvedImport}. Unlike {@link scanImports} (default-local only, kept
+ * stable for external callers), this:
+ * - parses default / `* as ns` / `{ a, b as c }` / mixed `d, { a }` forms;
+ * - keeps package/bare specifiers verbatim (`bare:true`) instead of skipping
+ *   them — the SSR path needs them to regenerate `import` lines and to SSR
+ *   third-party components (e.g. lucide-react icons).
+ *
+ * Returns `Map<localName, ResolvedImport>` (localName = the in-source identifier
+ * used in JSX). Namespace imports are recorded parse-only (the Rust compiler
+ * rejects member-expression elements, so `<Ns.Member/>` isn't renderable yet). */
+export declare function scanImportRefs(file: string): Map<string, ResolvedImport>;
+/** Extract static SVG node data for every `lucide-react` icon imported by
+ * `file`, keyed by its in-source local name.
+ *
+ * For each lucide import (`entry.bare && entry.spec === 'lucide-react'`), the
+ * icon's exported name (`imported` for named/aliased, the local name for a
+ * default import) is kebab-cased to locate `lucide-react/dist/esm/icons/
+ * <kebab>.mjs`, whose `__iconNode` array is reshaped into the JSON the Rust
+ * compiler deserializes: `{ cls, node: [[tag, [[attr,val],…]], …] }`. The
+ * lucide-internal `key` attr is stripped and all attr values are coerced to
+ * strings. An unresolvable icon name is silently omitted. */
+export declare function extractLucideIcons(file: string): Promise<Record<string, string>>;
+/** Scan the entry file's `import Name from './path'` declarations and build a
+ * map of localName -> resolved absolute path (DEFAULT-LOCAL only — package
+ * specifiers skipped). Extension resolution tries `.tsx`, `.ts`, `/index.tsx`,
+ * `/index.ts` in order. Kept string-valued + default-local for the external
+ * callers in islands/build.ts + native/build.ts; the SSR-component path uses the
+ * richer {@link scanImportRefs} instead. */
+export declare function scanImports(entryFile: string): Map<string, string>;
+/** Reconcile the raw `<Name>.islands.json` jsx-rustc emitted against the page's
+ * own imports, then bake the importmap+bootstrap into the `.jinja`.
+ *
+ * Pure-ish & synchronous (fs only) so it unit-tests deterministically:
+ * 1. If `islandsJsonPath` is absent → no-op (the route has no islands; the
+ *    `.jinja` stays byte-identical).
+ * 2. Resolve every entry's `sourcePath` from the page's `import <component>
+ *    from "..."` (else throw).
+ * 3. Enrich each entry with that absolute `sourcePath` and rewrite the
+ *    `.islands.json`.
+ * 4. Append `{% raw %}…{% endraw %}`-wrapped bootstrap to the `.jinja`. The raw
+ *    block keeps the importmap's literal `}}`/`{{` inert through minijinja's
+ *    boot-time compile. The md emit step passes `bakeBootstrap: false` and bakes
+ *    once itself at the END of its pipeline (the append here has no `includes()`
+ *    guard, so a second pass over the same template would double-bake).
+ */
+export declare function reconcileIslandManifest(jinjaPath: string, islandsJsonPath: string, pageImports: Map<string, ResolvedImport>, routeName: string, options?: {
+    bakeBootstrap?: boolean;
+}): void;

package/types/cli/new.d.ts

@@ -0,0 +1,30 @@
+import { type EmittedFile, type TemplateDef } from './templates.ts';
+export interface ParsedNewArgs {
+    projectName: string;
+    targetDir: string;
+    template?: string;
+    yes: boolean;
+}
+export declare function parseArgs(args: string[]): ParsedNewArgs;
+export interface BrustRef {
+    kind: 'file' | 'version';
+    spec: string;
+}
+export declare function resolveBrustRef(startDir?: string): BrustRef;
+export interface CopyTemplateOpts {
+    templateDir: string;
+    targetDir: string;
+    substitutions: Record<string, string>;
+    exclude?: Set<string>;
+    extraFiles?: EmittedFile[];
+}
+export declare function copyTemplate(opts: CopyTemplateOpts): Promise<void>;
+export interface SelectTemplateOpts {
+    explicit?: string;
+    yes: boolean;
+    isTTY: boolean;
+    read?: (label: string) => string | null;
+    print?: (s: string) => void;
+}
+export declare function selectTemplate(opts: SelectTemplateOpts): TemplateDef;
+export declare function runNew(args: string[]): Promise<void>;

package/types/cli/templates.d.ts

@@ -0,0 +1,39 @@
+export interface ScaffoldCtx {
+    projectName: string;
+    /** Raw brust dep spec, e.g. "file:/abs/path" or "^0.1.16-alpha". */
+    brustSpec: string;
+}
+export interface EmittedFile {
+    /** POSIX-relative destination path under the project root. */
+    relPath: string;
+    content: string;
+}
+export interface TemplateDef {
+    name: string;
+    title: string;
+    description: string;
+    sourceDir: string;
+    /**
+     * POSIX-relative paths (from sourceDir) to skip when copying. Matching uses
+     * the SOURCE entry name (pre-`renameForEmit`), so to exclude an emitted
+     * `.gitignore` you list its source name `_gitignore`, not `.gitignore`.
+     */
+    exclude: Set<string>;
+    /** Files the source tree lacks, generated at scaffold time. */
+    extraFiles?: (ctx: ScaffoldCtx) => EmittedFile[];
+}
+export declare const DEFAULT_TEMPLATE = "minimal";
+/**
+ * Walk up from `startDir` to the directory of the nearest package.json whose
+ * `name === 'brustjs'`. Single source of truth for locating the brust package
+ * root (consumed by both `resolveBrustRef` and pokedex template resolution).
+ * Works in the source tree (repo root) and a published install
+ * (`node_modules/brustjs`). Throws if no such package.json is found.
+ */
+export declare function findBrustPackageRoot(startDir?: string): string;
+/**
+ * Build the template registry fresh per call so a missing/corrupt install
+ * surfaces as a thrown error at invocation time (not import time).
+ */
+export declare function listTemplates(): TemplateDef[];
+export declare function getTemplate(name: string): TemplateDef | undefined;

package/types/client/index.d.ts

@@ -0,0 +1,14 @@
+/** Browser-only client helpers. This module is loaded by hydrated island
+ * bundles. It intentionally does NOT import from runtime/routes.ts or
+ * runtime/index.ts — those pull in React and server-side surface that the
+ * client doesn't need.
+ */
+export declare class BrustActionError extends Error {
+    readonly status: number;
+    readonly payload: unknown;
+    constructor(message: string, status: number, payload: unknown);
+}
+export { client } from '../treaty.ts';
+export type { TreatyResponse, ClientOptions } from '../treaty.ts';
+export { useStore } from '../store/react.ts';
+export { useNav } from '../navigation/react.ts';

package/types/config.d.ts

@@ -0,0 +1,42 @@
+export interface BrustConfig {
+    /** Host/address to bind on. Default `localhost`. Accepts a hostname
+     * (resolved Rust-side) or a literal IP such as `0.0.0.0` / `127.0.0.1`. */
+    host: string;
+    /** TCP port to bind on. Default 1337. */
+    port: number;
+    /** Bun Worker count for render dispatch. Default `availableParallelism()`. */
+    workers: number;
+    /** L1 response-cache capacity (entries). Undefined → Rust default of 1000. */
+    cacheMaxEntries?: number;
+    /** L2 page-cache capacity (entries). Undefined → Rust default of 1000. */
+    cachePageMaxEntries?: number;
+    /** R9 cross-process cache invalidation: redis/dragonfly URL. Absent →
+     * feature disabled (current single-process behavior). */
+    cacheSyncUrl?: string;
+    /** Pub/sub channel for cache invalidation. Undefined → module default
+     * (`brust:cache:invalidate`). */
+    cacheSyncChannel?: string;
+}
+/** Caller-supplied fallbacks (e.g. `brust.run({ address, port })`) applied
+ * BELOW env + TOML but ABOVE the framework defaults. */
+export interface ConfigDefaults {
+    host?: string;
+    port?: number;
+}
+export declare class BrustConfigError extends Error {
+    readonly file: string | null;
+    constructor(message: string, file: string | null);
+}
+/**
+ * Resolve Brust configuration. Precedence (low → high):
+ * framework defaults < caller `defaults` < TOML < env.
+ *
+ * - Framework defaults: { host: 'localhost', port: 1337, workers: availableParallelism() }
+ * - Caller `defaults`: e.g. `brust.run({ address, port })` — app-level fallbacks
+ *   that fill in only when neither TOML nor env specify the value (so a
+ *   `brust dev --port` / BRUST_PORT still wins over code).
+ * - TOML: brust.toml at `cwd` (missing file is fine — only a present file with
+ *   wrong shape is an error). `[server] address` / `port`.
+ * - Env: BRUST_ADDR, BRUST_PORT, BRUST_WORKERS override either source.
+ */
+export declare function loadConfig(cwd?: string, defaults?: ConfigDefaults): Promise<BrustConfig>;

package/types/cookies.d.ts

@@ -0,0 +1,25 @@
+export interface CookieOptions {
+    maxAge?: number;
+    expires?: Date;
+    path?: string;
+    domain?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+/** Serialize a single Set-Cookie value. The value is URL-encoded; attributes
+ * are appended in a stable order. Mirrors the standard cookie attribute names.
+ *
+ * Hardening: the name is validated as an RFC 6265 token, and the final line is
+ * asserted CRLF-free — so a stray `\r\n` in a name/path/domain (which are NOT
+ * URL-encoded, unlike the value) can't smuggle an extra response header. */
+export declare function serializeCookie(name: string, value: string, opts?: CookieOptions): string;
+/** Per-request cookie helper. `get` reads the incoming request cookies; `set`
+ * and `delete` stage a Set-Cookie onto the active request scope, flushed onto
+ * the response by routes.ts. Outside a request scope, `set`/`delete` are no-ops
+ * (dev-warn under BRUST_DEV). */
+export declare const cookies: {
+    get(name: string): string | undefined;
+    set(name: string, value: string, opts?: CookieOptions): void;
+    delete(name: string, opts?: Pick<CookieOptions, "path" | "domain">): void;
+};

package/types/create.d.ts

@@ -0,0 +1 @@
+export { runNew } from './cli/new.ts';

package/types/css/build.d.ts

@@ -0,0 +1,11 @@
+export interface BuildCssOptions {
+    /** Absolute path to the entry CSS file (typically <scanRoot>/app.css). */
+    entry: string;
+    /** Absolute path to the output directory. Created if missing. */
+    outDir: string;
+}
+export interface CssBuildResult {
+    outDir: string;
+    files: string[];
+}
+export declare function buildCss(opts: BuildCssOptions): Promise<CssBuildResult>;

package/types/css/component-build.d.ts

@@ -0,0 +1,17 @@
+import { processCssFile } from './process-modules.ts';
+import { type RouteForCss } from './route-deps.ts';
+import { type ComponentCssManifest } from './manifest.ts';
+export interface BuildComponentCssOptions {
+    /** Absolute path to the user's app dir (where Home.tsx lives). */
+    scanRoot: string;
+    /** Absolute path under which chunk files + manifest are written. */
+    outDir: string;
+    /** Optional Tailwind compiler (for @apply resolution). */
+    tailwindCompile: Parameters<typeof processCssFile>[0]['tailwindCompile'];
+    /** Routes to map to CSS chunks. */
+    routes: RouteForCss[];
+}
+/** Run the full component CSS pipeline: scan → process → emit chunks +
+ * .d.ts + manifest. Returns the in-memory manifest for callers (brust.run)
+ * that need to register the Bun.plugin immediately. */
+export declare function buildComponentCss(opts: BuildComponentCssOptions): Promise<ComponentCssManifest>;

package/types/css/component-loader.d.ts

@@ -0,0 +1,8 @@
+import type { BunPlugin } from 'bun';
+import type { ComponentCssManifest } from './manifest.ts';
+/** Build a Bun.plugin that resolves component CSS imports.
+ *  - .module.css → `export default <name-map>` (JS, baked from manifest)
+ *  - .css        → empty JS (side-effect; real CSS already on disk)
+ *
+ * Register once per isolate (brust.run main + each worker). */
+export declare function cssLoaderPlugin(manifest: ComponentCssManifest): BunPlugin;

package/types/css/manifest.d.ts

@@ -0,0 +1,21 @@
+/** Per-CSS-file entry. Side-effect imports (.css) have exports:null;
+ * CSS Modules (.module.css) have a flat name→hashed-name map. */
+export interface ComponentCssModuleEntry {
+    /** Absolute URL path served by Rust (e.g. /_brust/css/components/<sha>.css). */
+    chunk: string;
+    /** Original class name → hashed class name. null for non-module .css. */
+    exports: Record<string, string> | null;
+}
+export interface ComponentCssManifest {
+    version: 1;
+    /** Absolute filesystem path of the source .css file → entry. */
+    modules: Record<string, ComponentCssModuleEntry>;
+    /** Route.fullPath → ordered, deduplicated chunk href list. */
+    routeChunks: Record<string, string[]>;
+}
+/** Read + validate. Returns null when the file doesn't exist (project has
+ * no component CSS — treated as a no-op everywhere). Throws on malformed
+ * JSON or version mismatch. */
+export declare function readComponentCssManifest(absolutePath: string): Promise<ComponentCssManifest | null>;
+/** Write to disk. Creates the parent directory if needed. */
+export declare function writeComponentCssManifest(absolutePath: string, manifest: ComponentCssManifest): Promise<void>;

package/types/css/process-modules.d.ts

@@ -0,0 +1,31 @@
+export interface ProcessCssOptions {
+    /** Absolute path; Lightning CSS uses this to derive [hash] in cssModules pattern. */
+    filename: string;
+    /** Source CSS text. */
+    source: string;
+    /** True iff this file is a .module.css. */
+    isModule: boolean;
+    /** Optional Tailwind compiler. When set, source is piped through it FIRST
+     * so @apply directives resolve before module class rewriting. Null when
+     * Tailwind isn't available. */
+    tailwindCompile: {
+        build(candidates: string[]): string;
+        sources: {
+            base: string;
+            pattern: string;
+            negated: boolean;
+        }[];
+    } | null;
+}
+export interface ProcessCssResult {
+    /** Compiled CSS bytes. */
+    code: Uint8Array;
+    /** null for non-module files; original→hashed name map for .module.css. */
+    exports: Record<string, string> | null;
+}
+/** Pipe a CSS file through Tailwind (if available) then Lightning CSS.
+ * For .module.css, class names are hashed via Lightning's default
+ * pattern `[local]_[hash]` where [hash] is file-derived (~6 chars).
+ * Two classes in the same file share the suffix; two files with the same
+ * class name get different hashes. */
+export declare function processCssFile(opts: ProcessCssOptions): Promise<ProcessCssResult>;

package/types/css/route-deps.d.ts

@@ -0,0 +1,20 @@
+import type { CssDep } from './scan-imports.ts';
+export interface RouteForCss {
+    /** Route.fullPath (e.g. '/' or '/blog/{slug}'). */
+    fullPath: string;
+    /** Absolute source files of the route's component CHAIN (root layout → leaf).
+     * computeRouteChunks walks the local import graph from each and unions the
+     * CSS deps it finds — so a layout's co-located `.module.css` links to every
+     * route under it, and a leaf's links only to that route. */
+    componentSources: string[];
+}
+/** Build the route → CSS chunk hrefs map.
+ *
+ * For each route, BFS the LOCAL import graph rooted at the route's component
+ * chain (via {@link scanImports}, same default-import walk islands use) and
+ * collect the CSS deps of every reachable file. This means a `.module.css`
+ * co-located with the component that imports it is enough — no need to also
+ * import it in routes.tsx. Chunks are deduplicated and sorted per route. */
+export declare function computeRouteChunks(routes: RouteForCss[], scan: Map<string, CssDep[]>, modules: Record<string, {
+    chunk: string;
+}>): Record<string, string[]>;

package/types/css/scan-imports.d.ts

@@ -0,0 +1,13 @@
+export interface CssDep {
+    /** Absolute path to the .css or .module.css file. */
+    path: string;
+    /** True iff the file ends with `.module.css`. */
+    isModule: boolean;
+    /** Default-import binding name (e.g. `styles` for `import styles from ...`).
+     * null for side-effect imports (`import './foo.css'`). */
+    importedName: string | null;
+}
+/** Walk `scanRoot` recursively, parse every TS/TSX file with the TypeScript
+ * compiler API, return a map of source file → CSS deps. Files outside
+ * scanRoot, inside ignored dirs, or test files are skipped. */
+export declare function scanCssImports(scanRoot: string): Promise<Map<string, CssDep[]>>;

package/types/css.d.ts

@@ -0,0 +1,16 @@
+/** Configure the list of stylesheet hrefs that the renderer should
+ * inject into the SSR HTML before </head>. Replaces any previous list.
+ * Called from brust.run() main and worker branches (both need to know
+ * so the per-worker renderer can inject). */
+export declare function configureCssEnabled(hrefs: readonly string[]): void;
+/** Returns the configured hrefs as a defensive copy. */
+export declare function getCssHrefs(): readonly string[];
+/** Set the CSS hrefs to inject for a specific route. Replaces any previous
+ * list for that route. Called from brust.run() main after the component
+ * manifest loads. Keys are route.fullPath strings (e.g. '/' or '/blog/{slug}'). */
+export declare function configureCssHrefsForRoute(routePath: string, hrefs: readonly string[]): void;
+/** Returns the CSS hrefs for a specific route, or [] when none configured.
+ * Defensive copy on the way out. */
+export declare function getCssHrefsForRoute(routePath: string): readonly string[];
+/** @internal — used by the unit test suite to wipe both global and per-route state. */
+export declare function _resetCssForTests(): void;

package/types/define-actions.d.ts

@@ -0,0 +1,133 @@
+import type { BrustRequest, Middleware } from './routes.ts';
+import type { StandardSchemaV1, InferOutput } from './standard-schema.ts';
+declare const RESPOND: unique symbol;
+export interface ActionResponseSentinel {
+    readonly [RESPOND]: true;
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+}
+export declare function isRespondSentinel(v: unknown): v is ActionResponseSentinel;
+export declare function makeRespond(): (body: unknown, init?: {
+    status?: number;
+    headers?: Record<string, string>;
+}) => ActionResponseSentinel;
+export interface ActionContext<Body = unknown, Params = Record<string, string>, Query = Record<string, string>> {
+    req: BrustRequest;
+    body: Body;
+    params: Params;
+    query: Query;
+    headers: Record<string, string>;
+    respond: (body: unknown, init?: {
+        status?: number;
+        headers?: Record<string, string>;
+    }) => ActionResponseSentinel;
+}
+type Handler<B, P, Q, R> = (ctx: ActionContext<B, P, Q>) => R | Promise<R>;
+export interface EndpointOptions {
+    body?: StandardSchemaV1;
+    query?: StandardSchemaV1;
+    middleware?: Middleware[];
+    /** Build-time MCP tool description (read by the manifest extractor). */
+    description?: string;
+    /** Declared domain errors, keyed by code. Each value is a StandardSchema for
+     * the error's `data` payload. TYPE-ONLY: flows into the treaty client's typed
+     * error union; the runtime ignores it (handlers throw `ActionError`). */
+    errors?: Record<string, StandardSchemaV1>;
+}
+export interface EndpointDef {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+    path: string;
+    handler: (ctx: ActionContext) => unknown;
+    body?: StandardSchemaV1;
+    query?: StandardSchemaV1;
+    middleware: Middleware[];
+}
+type ParamKeys<P extends string> = P extends `${string}{${infer K}}${infer Rest}` ? (K extends `*${infer C}` ? C : K) | ParamKeys<Rest> : never;
+type Params<P extends string> = [ParamKeys<P>] extends [never] ? Record<string, string> : {
+    [K in ParamKeys<P>]: string;
+};
+type BodyOf<O> = O extends {
+    body: infer S;
+} ? S extends StandardSchemaV1 ? InferOutput<S> : unknown : unknown;
+type QueryOf<O> = O extends {
+    query: infer S;
+} ? S extends StandardSchemaV1 ? InferOutput<S> : unknown : Record<string, string>;
+/** Discriminated error union derived from `opts.errors`. Each declared code maps
+ * to `{ code; message; data }` where `data` is the schema's inferred output. */
+type ErrorOf<O> = O extends {
+    errors: infer E;
+} ? {
+    [K in keyof E & string]: {
+        code: K;
+        message: string;
+        data: E[K] extends StandardSchemaV1 ? InferOutput<E[K]> : unknown;
+    };
+}[keyof E & string] : never;
+export type EndpointEntry = {
+    input: unknown;
+    output: unknown;
+    error: unknown;
+};
+export type EndpointMap = Record<string, Partial<Record<EndpointDef['method'], EndpointEntry>>>;
+export declare function isValidEndpointPath(p: string): boolean;
+export interface ActionsBuilder<Acc extends EndpointMap = {}> {
+    endpoints: EndpointDef[];
+    use(mw: Middleware): ActionsBuilder<Acc>;
+    get<P extends string, O extends EndpointOptions, R>(path: P, handler: Handler<BodyOf<O>, Params<P>, QueryOf<O>, R>, opts?: O): ActionsBuilder<Acc & {
+        [K in P]: {
+            GET: {
+                input: QueryOf<O>;
+                output: Awaited<R>;
+                error: ErrorOf<O>;
+            };
+        };
+    }>;
+    post<P extends string, O extends EndpointOptions, R>(path: P, handler: Handler<BodyOf<O>, Params<P>, QueryOf<O>, R>, opts?: O): ActionsBuilder<Acc & {
+        [K in P]: {
+            POST: {
+                input: BodyOf<O>;
+                output: Awaited<R>;
+                error: ErrorOf<O>;
+            };
+        };
+    }>;
+    put<P extends string, O extends EndpointOptions, R>(path: P, handler: Handler<BodyOf<O>, Params<P>, QueryOf<O>, R>, opts?: O): ActionsBuilder<Acc & {
+        [K in P]: {
+            PUT: {
+                input: BodyOf<O>;
+                output: Awaited<R>;
+                error: ErrorOf<O>;
+            };
+        };
+    }>;
+    patch<P extends string, O extends EndpointOptions, R>(path: P, handler: Handler<BodyOf<O>, Params<P>, QueryOf<O>, R>, opts?: O): ActionsBuilder<Acc & {
+        [K in P]: {
+            PATCH: {
+                input: BodyOf<O>;
+                output: Awaited<R>;
+                error: ErrorOf<O>;
+            };
+        };
+    }>;
+    delete<P extends string, O extends EndpointOptions, R>(path: P, handler: Handler<BodyOf<O>, Params<P>, QueryOf<O>, R>, opts?: O): ActionsBuilder<Acc & {
+        [K in P]: {
+            DELETE: {
+                input: BodyOf<O>;
+                output: Awaited<R>;
+                error: ErrorOf<O>;
+            };
+        };
+    }>;
+    head<P extends string, O extends EndpointOptions, R>(path: P, handler: Handler<BodyOf<O>, Params<P>, QueryOf<O>, R>, opts?: O): ActionsBuilder<Acc & {
+        [K in P]: {
+            HEAD: {
+                input: QueryOf<O>;
+                output: Awaited<R>;
+                error: ErrorOf<O>;
+            };
+        };
+    }>;
+}
+export declare function defineActions(): ActionsBuilder;
+export { RESPOND };