brustjs 0.1.50-alpha → 0.1.52-alpha

package/runtime/routes.ts

@@ -1,15 +1,8 @@
 import { createContext, createElement, useContext, type ComponentType, type ReactNode } from 'react'
-// React 19 split react-dom/server by runtime: under Bun the bare 'react-dom/server'
-// resolves to the web-streams build (server.bun.js), which only exports
-// renderToReadableStream. renderToPipeableStream (Node streams — what our Writable
-// sink + onAllReady/onShellReady path uses) lives in the .node build. Import it
-// explicitly so SSR works on the react@19 we declare as a peer (React 18 shipped
-// renderToPipeableStream in the bun build, which is why this was silently fine).
-import { renderToPipeableStream } from 'react-dom/server.node'
-import { Writable } from 'node:stream'
 import { Buffer } from 'node:buffer'
 import * as native from './index.js'
 import { renderBranchStreaming } from './render/stream.ts'
+import { renderToAwaitedString } from './render/fragment.ts'
 import { runInStoreContext, collectSnapshot } from './store/server-context.ts'
 import { buildStoreScripts } from './render/inject-store.ts'
 import { getCssHrefsForRoute } from './css.ts'
@@ -98,6 +91,31 @@ export interface BrustRequest {
    * unaborted shared sentinel; signal.aborted === false forever). Real
    * disconnect detection for render/action is a follow-up. */
   signal: AbortSignal
+  /** Matched route params (percent-decoded) — the SAME values the loader ctx
+   * receives. Populated by the TS dispatch layer (`prepReq`) BEFORE the
+   * middleware chain runs, so middleware can authorize against `{id}` without
+   * re-parsing the raw URL. Empty object for routes without params — and for
+   * SSE/WS requests (their envelope carries no params in v1). */
+  params: Record<string, string>
+  /** Request-scoped bag middleware writes and loaders/handlers read. The same
+   * object identity flows through the whole chain (middleware → loader →
+   * component/handler). Locals written before `next()` are visible downstream;
+   * writes AFTER `next()` returns happen after the loader already ran. Reset
+   * to a fresh `{}` per request. */
+  locals: Record<string, unknown>
+}
+
+/** Populate the TS-owned `BrustRequest` fields (`params`, `locals`) on a
+ * request that just arrived in the Rust envelope. Rust knows nothing of these
+ * fields, so every dispatch branch calls this ONCE, before composeChain /
+ * loaders run — the single population point. Mutates and returns `req`. */
+export function prepReq(
+  req: BrustRequest,
+  params: Record<string, string> | undefined,
+): BrustRequest {
+  req.params = params ?? {}
+  req.locals = {}
+  return req
 }
 
 /** Handler module shape — what `() => Promise<WsHandlers>` resolves to.
@@ -274,6 +292,76 @@ export function isNativeVerdict(x: unknown): x is NativeVerdict {
   )
 }
 
+const HTTP_ERROR: unique symbol = Symbol.for('brust.httpError')
+
+export interface HttpErrorOpts {
+  /** Override the Content-Type. Defaults: string body → `text/plain;
+   * charset=utf-8`, object body → `application/json; charset=utf-8`. */
+  contentType?: string
+  /** Extra response headers (e.g. `WWW-Authenticate`). */
+  headers?: Record<string, string>
+}
+
+/** The symbol-keyed value `httpError()` throws. Body/contentType are resolved
+ * at construction so every catch site emits the same wire shape. Mirrors the
+ * NativeVerdict / ActionError branding (Symbol.for survives the trigger being
+ * duplicated across bundles). */
+export interface HttpErrorTrigger {
+  readonly [HTTP_ERROR]: true
+  readonly status: number
+  readonly body: string
+  readonly contentType: string
+  readonly headers?: Record<string, string>
+}
+
+/** Throw from a route loader (React or native) to short-circuit the response
+ * with an arbitrary error status — the loader-side analogue of a middleware
+ * short-circuit:
+ *
+ * ```ts
+ * loader: async ({ req }) => {
+ *   if (!req.locals.user) throw httpError(403, 'no entry')
+ *   …
+ * }
+ * ```
+ *
+ * THROW-only (it never returns) — one usage form on both render paths, unlike
+ * `notFound()` which native loaders RETURN. `body`: string → text/plain (or
+ * `opts.contentType`), object → JSON, omitted → empty. Status must be an
+ * integer in 400-599: 3xx is `redirect()`'s job, a 404 that renders a page is
+ * `notFound()`'s. The response is a plain short-circuit — it never reaches the
+ * errorBoundary and never logs as a 500. */
+export function httpError(status: number, body?: string | object, opts?: HttpErrorOpts): never {
+  if (!Number.isInteger(status) || status < 400 || status > 599) {
+    throw new Error(
+      `httpError(status) must be an integer in 400-599, got ${status} — use redirect() for 3xx and notFound() for a rendered 404`,
+    )
+  }
+  let bodyStr: string
+  let contentType: string
+  if (body === undefined || typeof body === 'string') {
+    bodyStr = body ?? ''
+    contentType = opts?.contentType ?? 'text/plain; charset=utf-8'
+  } else {
+    bodyStr = JSON.stringify(body)
+    contentType = opts?.contentType ?? 'application/json; charset=utf-8'
+  }
+  const trigger: HttpErrorTrigger = {
+    [HTTP_ERROR]: true,
+    status,
+    body: bodyStr,
+    contentType,
+    headers: opts?.headers,
+  }
+  throw trigger
+}
+
+/** True when a thrown value is the `httpError()` trigger (symbol-keyed — a
+ * plain object with a `status` property is NOT mistaken for one). */
+export function isHttpErrorTrigger(x: unknown): x is HttpErrorTrigger {
+  return typeof x === 'object' && x !== null && (x as Record<symbol, unknown>)[HTTP_ERROR] === true
+}
+
 /** Framework default 404 body, served when a React `notFound()` fires but no
  * catch-all (`path: '*'`) is registered for the route's prefix — so the response
  * is still HTTP 404 with a body (never a 500, never a crash). */
@@ -320,10 +408,15 @@ export interface NativeLoaderCtx {
   req: BrustRequest
 }
 
-/** Result of running a native route's chain loaders top-down: either a merged
- * flat context object (all loader results shallow-merged, child keys win), or
- * the first verdict encountered (top-down) which short-circuits the chain. */
-export type NativeChainResult = { data: Record<string, unknown> } | { verdict: NativeVerdict }
+/** Result of running a native route's chain loaders top-down: a merged flat
+ * context object (all loader results shallow-merged, child keys win), the
+ * first verdict encountered (top-down) which short-circuits the chain, or an
+ * `httpError()` trigger THROWN by a loader (intercepted per-loader so it never
+ * reaches the caller's generic 500 catch). */
+export type NativeChainResult =
+  | { data: Record<string, unknown> }
+  | { verdict: NativeVerdict }
+  | { httpError: HttpErrorTrigger }
 
 /** Run a native route's `flat.chain` loaders top-down (parent → leaf) and merge
  * their results into ONE flat context object.
@@ -350,7 +443,16 @@ export async function runNativeChainLoaders(
     if (!node.loader) continue
     // `as never` bypasses per-route Params narrowing — NativeLoaderCtx is the
     // default-instantiated loader ctx shape ({ params, path, req }).
-    const result = await node.loader(ctx as never)
+    let result: unknown
+    try {
+      result = await node.loader(ctx as never)
+    } catch (err) {
+      // httpError() short-circuit — intercept PER-LOADER so the trigger never
+      // reaches the caller's generic loader catch (which logs + 500s). Any
+      // other throw keeps the existing 500 contract.
+      if (isHttpErrorTrigger(err)) return { httpError: err }
+      throw err
+    }
     if (isNativeVerdict(result)) {
       return { verdict: result }
     }
@@ -916,6 +1018,9 @@ export function makeRenderer(
       // have a per-conn AbortController. Middleware/loaders/components
       // can still read req.signal.aborted (always false).
       call.req.signal = NEVER_ABORTS
+      // Populate the TS-owned req fields (matched params + a fresh locals bag)
+      // BEFORE the middleware chain runs.
+      prepReq(call.req, call.params)
 
       // Run the middleware chain against a streaming-marker terminal.
       // Middleware that short-circuits (returns without calling next())
@@ -936,6 +1041,16 @@ export function makeRenderer(
       try {
         verdict = (await chain()) as StreamMarkerResponse
       } catch (err) {
+        // `throw httpError(...)` belongs in loaders, but a middleware that
+        // throws it still deserves the intended status, not a 500 + log dump.
+        if (isHttpErrorTrigger(err)) {
+          return packSingleChunkResponse(slotView, encoder, {
+            status: err.status,
+            contentType: err.contentType,
+            body: err.body,
+            headers: err.headers,
+          })
+        }
         console.error(`[brust] middleware/render uncaught:`, err)
         // FAST LANE: single-chunk error. Works for both React (big dispatch
         // reads the SAB via its fast-lane arm) and native routes (which take
@@ -1073,6 +1188,18 @@ export function makeRenderer(
             body: 'internal error',
           })
         }
+        if ('httpError' in chainResult) {
+          // A native loader threw httpError() — short-circuit with the
+          // trigger's response (same fast-lane mechanism as a middleware
+          // short-circuit, which already carries arbitrary statuses).
+          const he = chainResult.httpError
+          return packSingleChunkResponse(slotView, encoder, {
+            status: he.status,
+            contentType: he.contentType,
+            body: he.body,
+            headers: he.headers,
+          })
+        }
         let renderStatus: number | undefined
         if ('verdict' in chainResult) {
           // First verdict wins (top-down). Remaining loaders already skipped.
@@ -1245,6 +1372,24 @@ export function makeRenderer(
         try {
           element = await buildRenderElement(call, flat, opts.getWorkerId, shellMode)
         } catch (err) {
+          if (isHttpErrorTrigger(err)) {
+            // React loader threw httpError() — short-circuit with the trigger's
+            // response. NOT the errorBoundary, NOT the 500 path below: this is
+            // a deliberate response, like a middleware short-circuit.
+            return await emitSingleChunkResponse(
+              slotView,
+              napi,
+              workerId,
+              encoder,
+              {
+                status: err.status,
+                contentType: err.contentType,
+                body: err.body,
+                headers: err.headers,
+              },
+              slot,
+            )
+          }
           if (isNotFoundTrigger(err)) {
             // React `notFound()` trigger: abandon the matched route and render
             // the NEAREST catch-all (same selection as a Rust-unmatched path)
@@ -1395,41 +1540,8 @@ export function makeRenderer(
   }
 }
 
-/** Render a React element to a single HTML string, awaiting all Suspense
- * boundaries via onAllReady. Used by navigationBranch — renderToString
- * would only capture the shell + fallbacks, while renderBranchStreaming
- * is for the streaming render path. */
-function renderToAwaitedString(element: ReactNode): Promise<string> {
-  return new Promise<string>((resolve, reject) => {
-    const chunks: Buffer[] = []
-    const sink = new Writable({
-      write(chunk, _enc, cb) {
-        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))
-        cb()
-      },
-    })
-    sink.on('finish', () => resolve(Buffer.concat(chunks).toString('utf8')))
-    sink.on('error', reject)
-
-    let stream: ReturnType<typeof renderToPipeableStream>
-    stream = renderToPipeableStream(element, {
-      onAllReady() {
-        try {
-          stream.pipe(sink)
-        } catch (e) {
-          reject(e)
-        }
-      },
-      onShellError(err) {
-        reject(err)
-      },
-      onError(err) {
-        // Logged at the navigationBranch level; let onAllReady drive completion.
-        console.error('[brust] navigation render onError:', err)
-      },
-    })
-  })
-}
+// renderToAwaitedString moved to render/fragment.ts (shared with the public
+// renderFragment API) — imported above; navigationBranch behavior unchanged.
 
 async function navigationBranch(
   call: Extract<RouteCall, { kind: 'navigation' }>,
@@ -1484,6 +1596,10 @@ async function navigationBranch(
     _brustStream: NAV_MARKER,
   })
 
+  // Populate the TS-owned req fields (matched params + a fresh locals bag)
+  // BEFORE the middleware chain runs — mirrors the render branch.
+  prepReq(call.req, call.params)
+
   // navigationBranch receives a 'navigation' call, but composeChain only
   // needs req + middleware — cast to satisfy the type.
   const navChain = composeChain(
@@ -1496,6 +1612,17 @@ async function navigationBranch(
   try {
     navVerdict = (await navChain()) as NavMarkerResponse
   } catch (err) {
+    // Same guard as the render path: an httpError thrown from middleware gets
+    // its intended status (non-2xx nav → client full-reload contract).
+    if (isHttpErrorTrigger(err)) {
+      await emitSingleChunkResponse(view, napi, workerId, encoder, {
+        status: err.status,
+        contentType: err.contentType,
+        body: err.body,
+        headers: err.headers,
+      })
+      return
+    }
     console.error('[brust] navigation middleware threw:', err)
     await emitSingleChunkResponse(
       view,
@@ -1654,6 +1781,28 @@ async function navigationBranch(
       slot,
     )
   } catch (err) {
+    if (isHttpErrorTrigger(err)) {
+      // A loader threw httpError() on the SPA-nav path (React render or the
+      // native re-throw below). Mirror the existing non-2xx middleware
+      // short-circuit semantics: emit the trigger's response as-is — the
+      // client treats any non-2xx nav response as a fallback trigger (full
+      // reload), so the user lands on the authoritative document response.
+      // No new JSON error shape.
+      await emitSingleChunkResponse(
+        view,
+        napi,
+        workerId,
+        encoder,
+        {
+          status: err.status,
+          contentType: err.contentType,
+          body: err.body,
+          headers: err.headers,
+        },
+        slot,
+      )
+      return
+    }
     console.error('[brust] navigation render failed:', err)
     await emitSingleChunkResponse(
       view,
@@ -1703,6 +1852,12 @@ async function renderNativeRouteToHtml(
     }),
   )
 
+  if ('httpError' in chainResult) {
+    // Re-throw the trigger — navigationBranch's catch emits it as the nav
+    // response (non-2xx → client full-reload, mirroring a middleware
+    // short-circuit).
+    throw chainResult.httpError
+  }
   if ('verdict' in chainResult) {
     // SPA nav can't emit a redirect/404 in-place; force the client's full-reload
     // fallback so the document path produces the authoritative status.
@@ -2070,6 +2225,10 @@ export async function dispatchAction(
     }
   }
   call.req.signal = NEVER_ABORTS
+  // Populate the TS-owned req fields (matched params + a fresh locals bag)
+  // BEFORE the middleware chain runs. ctx.req === call.req, so handler locals
+  // reads see middleware writes with zero threading.
+  prepReq(call.req, call.params)
 
   // Body decode — dispatch by content-type (JSON / urlencoded / multipart).
   let rawBody: unknown
@@ -2158,6 +2317,15 @@ export async function dispatchAction(
     } catch (err) {
       if (isActionError(err)) {
         response = actionErrorResponse(err)
+      } else if (isHttpErrorTrigger(err)) {
+        // ActionError is the idiomatic action-status tool, but an httpError
+        // escaping a shared middleware/handler still gets its intended status.
+        response = {
+          status: err.status,
+          body: err.body,
+          contentType: err.contentType,
+          headers: err.headers,
+        }
       } else {
         console.error('[brust] action middleware uncaught:', err)
         response = {
@@ -2191,6 +2359,9 @@ async function mcpBranchToResponse(
   // reading req.signal.aborted always sees false; the SSE branch is where
   // real disconnect lives.
   call.req.signal = NEVER_ABORTS
+  // No params in the MCP envelope and no middleware chain — but the
+  // BrustRequest contract declares params/locals non-optional, so populate.
+  prepReq(call.req, undefined)
   const responseJson = await mcp.handleRequest(call.body_text, call.req)
   if (responseJson === '') {
     // Notification — no response body. Return 204 No Content.
@@ -2264,6 +2435,9 @@ async function sseBranch(
   // Inject NEVER_ABORTS into req for the middleware run. handleSseStream
   // will overwrite with a per-conn AbortController.signal afterward.
   call.req.signal = NEVER_ABORTS
+  // The SSE envelope carries NO params — middleware sees empty params in v1
+  // (widening the Rust envelope is a separate change). Fresh locals bag.
+  prepReq(call.req, undefined)
 
   // Run middleware chain with a 200 placeholder terminal. The terminal
   // does NOT invoke leaf.sse — handleSseStream does that after middleware
@@ -2370,6 +2544,9 @@ async function wsBranch(
   // lifecycle is via registered onMessage/onClose callbacks rather than
   // awaiting on a request signal.
   call.req.signal = NEVER_ABORTS
+  // The WS envelope carries NO params — middleware sees empty params in v1
+  // (same contract as SSE above). Fresh locals bag.
+  prepReq(call.req, undefined)
 
   // Run middleware chain with a 101 placeholder terminal that signals
   // "ready to upgrade". The terminal does NOT call route.websocket —

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;