brustjs 0.1.49-alpha → 0.1.51-alpha

package/runtime/templates.ts

@@ -0,0 +1,47 @@
+// R1 dynamic template registry — runtime registration of minijinja templates
+// (per-tenant sections etc.). Thin TS over NAPI; the Rust env is process-global
+// so registrations are visible to every worker isolate immediately.
+import * as native from './index.js'
+
+export const templates = {
+  /** Register (or replace) a runtime template under `name`. Names are opaque
+   * keys (`shop/42/section/7@v3` is fine). Throws on jinja syntax errors
+   * (message includes line info). Replacement is atomic: concurrent renders
+   * see old or new, never missing. */
+  register(name: string, jinjaSource: string): void {
+    // napi-rs v3 hands back the `Error` as the RETURN VALUE for sync
+    // fallible bindings under Bun instead of throwing (verified empirically
+    // for both `Result<()>` and `Result<String>`) — normalize to the
+    // documented throw.
+    const err = (native as any).napiRegisterTemplate(name, jinjaSource)
+    if (err instanceof Error) throw err
+  },
+  /** Remove a runtime-registered template. Returns whether it existed.
+   * Boot-tier templates (compiled from routes) are not removable. */
+  remove(name: string): boolean {
+    return (native as any).napiRemoveTemplate(name)
+  },
+  /** True when `name` resolves in either tier (dynamic first, then boot). */
+  has(name: string): boolean {
+    return (native as any).napiHasTemplate(name)
+  },
+  /** Names of runtime-registered templates (dynamic tier only). */
+  list(): string[] {
+    return (native as any).napiListDynamicTemplates() ?? []
+  },
+  /** Render a template (either tier) to an HTML string. Pure (name, data) →
+   * html — no request/store context. NOT the request fast lane; intended for
+   * handlers/loaders/tooling (draft canvases, section previews). */
+  render(name: string, data?: unknown): string {
+    // `data == null` (undefined OR explicit null) renders against an empty
+    // context — JSON.stringify(null) would hand minijinja a null root where
+    // every variable lookup goes Undefined.
+    const json = JSON.stringify(data == null ? {} : data)
+    // Same napi-rs v3 Bun quirk as register(): the Error comes back as the
+    // return value, not a throw — without this guard a consumer would
+    // interpolate "Error: ..." into HTML instead of catching.
+    const out = (native as any).napiRenderTemplate(name, json)
+    if (out instanceof Error) throw out
+    return out
+  },
+}

package/runtime/treaty.ts

@@ -11,6 +11,14 @@ export interface TreatyResponse<Data = unknown, Err = unknown> {
 }
 export interface ClientOptions {
   prefix?: string
+  /** Absolute origin of ANOTHER brust deployment to target, e.g.
+   * `https://api.example.com` (a path suffix like `/v2` composes by
+   * concatenation). Must match `^https?://`; a trailing slash is stripped.
+   * When set, the action prefix is `prefix ?? '/_brust/action'` — the global
+   * `__BRUST_ACTION_PREFIX__` belongs to the SERVING app and is never
+   * consulted. Cross-origin cookies: pass a `fetch` override that sets
+   * `credentials: 'include'` (and configure `cors.credentials` server-side). */
+  baseUrl?: string
   headers?: Record<string, string> | (() => Record<string, string>)
   fetch?: typeof fetch
 }
@@ -77,15 +85,30 @@ export type Treaty<App> =
 
 function resolvePrefix(opts?: ClientOptions): string {
   if (opts?.prefix) return opts.prefix
+  // The global __BRUST_ACTION_PREFIX__ is injected by the SERVING app's pages;
+  // it describes THIS origin's mount point, never a cross-origin target's.
+  if (opts?.baseUrl !== undefined) return '/_brust/action'
   const g = (globalThis as { __BRUST_ACTION_PREFIX__?: string }).__BRUST_ACTION_PREFIX__
   return g ?? '/_brust/action'
 }
 
+/** Validate + normalize `baseUrl`: absolute http(s) origin, trailing slash(es)
+ * stripped. Absent → '' (same-origin, byte-identical legacy behavior). */
+function resolveBaseUrl(opts?: ClientOptions): string {
+  const b = opts?.baseUrl
+  if (b === undefined) return ''
+  if (!/^https?:\/\//.test(b)) {
+    throw new Error(`treaty baseUrl must be an absolute http(s) origin (got ${JSON.stringify(b)})`)
+  }
+  return b.replace(/\/+$/, '')
+}
+
 /** Build a treaty proxy. Static segments accumulate as a path; a function call
  * with an object fills the next {param}(s) positionally (in insertion order); a
  * terminal method key (.get/.post/…) performs the request. URL is composed from
  * the literal accumulated segments — never from any inferred type. */
 export function client<App = unknown>(opts?: ClientOptions): Treaty<App> {
+  const baseUrl = resolveBaseUrl(opts)
   const prefix = resolvePrefix(opts)
   const doFetch = opts?.fetch ?? fetch
   function make(segments: string[]): any {
@@ -98,7 +121,7 @@ export function client<App = unknown>(opts?: ClientOptions): Treaty<App> {
               | { query?: Record<string, string>; headers?: Record<string, string> }
               | undefined
             const body = isBodyless ? undefined : arg1
-            let url = prefix + '/' + segments.join('/')
+            let url = baseUrl + prefix + '/' + segments.join('/')
             if (options?.query) {
               const qs = new URLSearchParams(options.query as Record<string, string>).toString()
               if (qs) url += '?' + qs

package/types/action-error.d.ts

@@ -0,0 +1,18 @@
+declare const ACTION_ERROR: unique symbol;
+export interface ActionErrorBody {
+    code: string;
+    message: string;
+    data?: unknown;
+}
+export declare class ActionError extends Error {
+    readonly [ACTION_ERROR]: true;
+    readonly status: number;
+    readonly code: string;
+    readonly data?: unknown;
+    constructor(status: number, code: string, opts?: {
+        message?: string;
+        data?: unknown;
+    });
+}
+export declare function isActionError(v: unknown): v is ActionError;
+export {};

package/types/cache-sync.d.ts

@@ -0,0 +1,42 @@
+import type { InvalidateArgs } from './cache.ts';
+/** Public wire contract (documented for external publishers like studio):
+ * `{ "v": 1, "sender": "<uuid>", "key": "...", "tags": ["..."],
+ *    "path": "...", "method": "GET" }` — all invalidation fields optional,
+ * `sender` may be omitted (never matches our token, always applied). */
+export interface CacheSyncMessage {
+    v: 1;
+    sender?: string;
+    key?: string;
+    tags?: string[];
+    path?: string;
+    method?: string;
+}
+export declare const CHANNEL_DEFAULT = "brust:cache:invalidate";
+/** Injectable publish seam so unit tests never construct a RedisClient. */
+export interface CacheSyncTransport {
+    publish(channel: string, message: string): Promise<unknown>;
+}
+export declare function __setTransportForTest(t: CacheSyncTransport | null): void;
+/** The redis URL may carry credentials (`redis://:pass@host:port/db`). Every
+ * log line that mentions the target MUST go through this — host:port only. */
+export declare function redactUrl(url: string): string;
+/** Apply a parsed peer message to the local NAPI caches. Direct fan-out —
+ * NEVER via cache.invalidate, so a received message can never re-publish
+ * (no loop, even across misconfigured channels). Exported for tests. */
+export declare function applyCacheSyncMessage(msg: CacheSyncMessage): void;
+/** Publish an invalidation to peers. No-op when sync is not configured
+ * (BRUST_CACHE_SYNC_URL absent). Fire-and-forget: synchronous from the
+ * caller's view, failures warn (throttled) and never propagate — local
+ * invalidation must never depend on redis state. */
+export declare function publishCacheSync(args: InvalidateArgs): void;
+/** Start the subscriber (main isolate only — run() guards; workers never call
+ * this). Idempotent; never throws. A down redis at boot logs a redacted warn
+ * and retries with capped exponential backoff — the server boots regardless. */
+export declare function startCacheSync(opts: {
+    url: string;
+    channel?: string;
+}): void;
+/** Shutdown/test hook: stop retries, close both clients, reset state so tests
+ * can restart. Wired into gracefulExit so backoff timers can't fire between
+ * drain and exit. */
+export declare function stopCacheSync(): void;

package/types/cache.d.ts

@@ -0,0 +1,20 @@
+import * as native from './index.js';
+export interface InvalidateArgs {
+    key?: string;
+    tags?: string[];
+    /** L1 response-cache: evict all entries for this request path (any prefix /
+     * query variant). Independent of `tags`. */
+    path?: string;
+    /** HTTP method for the `path` eviction (defaults to GET in Rust). */
+    method?: string;
+}
+export declare const cache: {
+    /** Evict across all three caches: islands, L2 page cache, and L1 response
+     * cache. `key`/`tags` hit islands + L2; the L1 response cache is reached by
+     * `tags` (the ROUTE must declare static `cache.tags` for its L1 entries to
+     * carry them) and by `path` (evicts every L1 entry for that request path,
+     * any prefix/query variant). All fields optional; `invalidate({})` is a
+     * deliberate no-op. The `?.` guards against a stale addon built before a
+     * given binding existed (degrades to no-op). */
+    invalidate(args: InvalidateArgs): void;
+};

package/types/cli/help.d.ts

@@ -0,0 +1,28 @@
+/** Read the brustjs package.json version. `help.ts` lives at
+ * <root>/runtime/cli/, so ../../package.json is <root>/package.json in both the
+ * source tree and an installed node_modules/brustjs layout. Never throws —
+ * returns "unknown" on any failure (version must not crash the CLI). */
+export declare function readVersion(): string;
+export declare const style: {
+    bold: (s: string) => string;
+    dim: (s: string) => string;
+    cyan: (s: string) => string;
+    green: (s: string) => string;
+    red: (s: string) => string;
+};
+interface CommandDef {
+    name: string;
+    summary: string;
+    usage: string;
+    flags: {
+        flag: string;
+        desc: string;
+    }[];
+    /** Free-form lines rendered after the Options block (one paragraph per entry). */
+    notes?: string[];
+}
+export declare const COMMANDS: CommandDef[];
+export declare function renderVersion(): string;
+export declare function renderRootHelp(): string;
+export declare function renderCommandHelp(name: string): string | null;
+export {};

package/types/cli/jinja-staleness.d.ts

@@ -0,0 +1,14 @@
+/** True when the emitted native templates in `jinjaDir` are missing or older
+ * than the authored `.tsx` sources under `scanRoot` — i.e. a boot-time
+ * recompile is warranted so `bun run <entry>` (source mode) doesn't require a
+ * prior `brust build`, and an edited page is picked up without a stale render.
+ *
+ * Staleness = the build marker (`_manifest.json`, written last by
+ * `emitNativeTemplates`) is absent, OR any source `.tsx` is newer than it.
+ *
+ * `manifestDir` is where `md-manifest.json` lives. It defaults to
+ * `dirname(jinjaDir)` — the layout contract is `jinjaDir == <x>/jinja` with
+ * the md manifest written next to it in `<x>` (both `emitMdArtifacts` callers
+ * pass `manifestDirs: [<x>]`). A caller that already holds the manifest dir
+ * should pass it explicitly instead of relying on that positional contract. */
+export declare function isJinjaStale(scanRoot: string, jinjaDir: string, manifestDir?: string): boolean;

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;