brustjs 0.1.49-alpha → 0.1.51-alpha

package/types/md/emit.d.ts

@@ -0,0 +1,72 @@
+import { type MdRouteSource } from './routes.ts';
+/** The slice of a FlatRoute the md emit step reads. The chain holds the route
+ * NODES, so the md leaf's `__mdSource` (runtime/md/routes.ts) survives into it.
+ * `fullPath` is only read by the manifest derivation (emitMdArtifacts).
+ * `Component` admits plain `{ name }` carriers AND real component values
+ * (function/class — both expose `.name` via the Function prototype), so a
+ * `FlatRoute[]` passes without casts. */
+export interface FlatRouteLike {
+    fullPath?: string;
+    nativeTemplate?: string;
+    chain?: Array<{
+        Component?: {
+            name?: string;
+        } | ((...args: never[]) => unknown) | (abstract new (...args: never[]) => unknown);
+        __mdSource?: MdRouteSource;
+    }>;
+}
+export interface MdEmitOpts {
+    /** User's routes entry file (absolute path) — scanned for the default-import
+     * idents that resolve embedded component tags, and for app-wide directives. */
+    entryFile: string;
+    /** Flat routes; only chains whose LEAF carries `__mdSource` are emitted. */
+    flatRoutes: FlatRouteLike[];
+    /** Jinja output dir (same dir `emitNativeTemplates` writes to). */
+    outDir: string;
+    /** Bake the /_brust/dev WS client tag (parity with the native emit's
+     * BRUST_DEV injection — md pages render Rust-side and never pass through the
+     * React renderer's dev-client injection). */
+    withDevClient?: boolean;
+    /** What to do when a route's md file no longer exists on disk (deleted after
+     * the route table was built). emitMdTemplates serves BOTH `brust build` and
+     * the dev re-emit, and the two must diverge here:
+     *   - `'throw'` (build): a missing file is a HARD error — silently skipping
+     *     ships a dist with the route registered but its template absent.
+     *   - `'skip-warn'` (default; dev boot/re-emit): skip the route and warn
+     *     once that a restart is required — the dev route table is frozen at
+     *     boot, so a crash here would take down the whole hot-reload loop. */
+    onMissing?: 'throw' | 'skip-warn';
+}
+/** Test helper. */
+export declare function _resetMdRoutesChangedWarnForTests(): void;
+/** Emit one `.jinja` (+ `.islands.json` sidecar) per md route in `flatRoutes`.
+ * Returns the islands referenced from md content (`name → absolute source
+ * path`) so the build step can thread them into island-chunk discovery as
+ * `extraIslands` (task 2.8). Behaviors are NOT in the map — their chunks are
+ * built by `scanDirectiveComponents`, which already walks the routes-entry
+ * import graph the registry keeps alive. */
+export declare function emitMdTemplates(opts: MdEmitOpts): Promise<{
+    mdIslands: Map<string, string>;
+}>;
+export interface MdArtifactsOpts extends MdEmitOpts {
+    /** Dirs to write `md-manifest.json` into when the app has md routes (e.g.
+     * `<distDir>` and `<cwd>/.brust` — both "next to" their jinja dirs, where
+     * `loadPrebuiltMdManifest` / the staleness check look). Skipped entirely
+     * when there are no md routes (zero output difference for md-free apps). */
+    manifestDirs?: string[];
+}
+/** Task 2.8 build-integration seam: emit the md `.jinja` templates AND the
+ * frozen `md-manifest.json` (derived from the same flat route table — single
+ * source of truth) in one call. All build sites (`brust build`, `brust dev`
+ * boot/re-emit, runtime boot, dev HMR island rebuild) go through this so the
+ * template, manifest, and returned `mdIslands` chunk inputs can never diverge.
+ * Strict no-op for apps without md routes. */
+export declare function emitMdArtifacts(opts: MdArtifactsOpts): Promise<{
+    mdIslands: Map<string, string>;
+}>;
+/** Replace the slot element's inner content with the md HTML. The slot attr
+ * itself stays (hydration-neutral, useful for tests). Exactly one slot must
+ * exist and it must be empty — both are emit-pipeline invariants, so a
+ * violation is a hard error, not a soft skip. `name` is a generated template
+ * name (`[A-Za-z0-9_]` only), so interpolating it into the regex is safe. */
+export declare function spliceMdSlot(template: string, name: string, mdHtml: string): string;

package/types/md/render.d.ts

@@ -0,0 +1,80 @@
+export type MdHydrate = 'load' | 'idle' | 'visible' | 'interaction';
+/** One embedded-component use found in a markdown page (islands only). */
+export interface MdIslandUse {
+    name: string;
+    /** 0-based per page; the emit step offsets past the wrapper's own islands. */
+    instanceLocal: number;
+    props: Record<string, unknown>;
+    hydrate: MdHydrate;
+    csr: boolean;
+    /** 1-based line number within the md body (post-frontmatter). */
+    line: number;
+}
+/** One behavior-component (x-data) use found in a markdown page. */
+export interface MdBehaviorUse {
+    name: string;
+    directive: string;
+    /** 1-based line number within the md body (post-frontmatter). */
+    line: number;
+    /** Literal tag props (string/number only — validated at extract time). The
+     * emit step inline-substitutes them into the component's compiled body. */
+    props: Record<string, unknown>;
+    /** The EXACT placeholder host markup injected into the rendered HTML. The
+     * emit step (which owns compileJsx) substitutes the fully inlined component
+     * body over this exact string. It carries the per-render nonce, so user
+     * prose can never collide with it. */
+    marker: string;
+}
+export type MdComponentResolution = {
+    kind: 'island';
+    id: string;
+} | {
+    kind: 'behavior';
+    directive: string;
+};
+export interface RenderMdPageOptions {
+    /** Markdown source, frontmatter already stripped. */
+    body: string;
+    absPath: string;
+    /** `null` → unknown name → renderMdPage throws with `file:line`. */
+    resolve: (name: string, line: number) => MdComponentResolution | null;
+}
+interface ShikiLike {
+    codeToHtml(code: string, options: {
+        lang: string;
+        themes: {
+            light: string;
+            dark: string;
+        };
+    }): Promise<string>;
+}
+/** Test seam: replaces the dynamic `import('shiki')` and resets all cached state. */
+export declare function __setShikiImporterForTests(importer: (() => Promise<ShikiLike>) | null): void;
+/**
+ * Highlights a code fence via shiki (lazy-imported once, cached) with dual
+ * CSS-variables themes. shiki absent → escape-only `<pre><code>` fallback and
+ * ONE warning per build. Unknown language → silent escape-only fallback.
+ */
+export declare function highlightCode(code: string, lang: string): Promise<string>;
+/**
+ * Replaces every minijinja delimiter in md-origin HTML with a string-literal
+ * expression that renders back to the original text. Single pass — the
+ * replacements themselves are never re-matched. Component-host markup is
+ * injected AFTER this pass so its jinja stays live.
+ */
+export declare function neutralizeBraces(html: string): string;
+/**
+ * Renders one markdown page body to jinja-safe HTML.
+ *
+ * Order is load-bearing (locked by tests):
+ * 1. extract component-tag lines to opaque placeholders (marked never sees them)
+ * 2. render markdown (GFM, heading ids, shiki fences)
+ * 3. neutralize jinja braces over the rendered HTML
+ * 4. substitute placeholders with host markup — its jinja stays live
+ */
+export declare function renderMdPage(opts: RenderMdPageOptions): Promise<{
+    html: string;
+    islands: MdIslandUse[];
+    behaviors: MdBehaviorUse[];
+}>;
+export {};

package/types/md/routes.d.ts

@@ -0,0 +1,119 @@
+import type { ComponentType } from 'react';
+import type { Route } from '../routes.ts';
+import { type MdFile } from './scan.ts';
+/**
+ * Content-addressed jinja template name for an md page:
+ * `Md_<sanitized relPath>_<8hex(sha256 relPath)>`.
+ *
+ * Sanitizes `[^A-Za-z0-9_]` to `_`; the hash (same scheme as
+ * `islandChunkBasename` in runtime/islands/chunk-id.ts) keeps two relPaths
+ * that sanitize identically (e.g. `a-b.md` vs `a_b.md`) from colliding.
+ */
+export declare function mdTemplateName(relPath: string): string;
+/**
+ * Maps a content-relative md path to its URL under `prefix`.
+ * `index.md` maps to the prefix itself; `guide/index.md` maps to
+ * `<prefix>/guide`; `query/where.md` maps to `<prefix>/query/where`.
+ * Trailing slashes on `prefix` are normalized away (`/docs/` == `/docs`).
+ */
+export declare function mdUrlPath(relPath: string, prefix: string): string;
+/** Build-time source info attached to every md leaf route. Plain field on the
+ * Route node, so it survives `flattenRoutes` into `FlatRoute.chain` (the chain
+ * holds the node objects); the emit step filters chains whose leaf has it. */
+export interface MdRouteSource {
+    absPath: string;
+    relPath: string;
+    contentDir: string;
+    frontmatter: MdFile['frontmatter'];
+    components: Record<string, ComponentType<any>>;
+    layoutName?: string;
+}
+/** An md leaf route — an ordinary native Route plus the `__mdSource` marker. */
+export type MdRoute = Route & {
+    __mdSource: MdRouteSource;
+};
+export interface MdRoutesOptions {
+    /** URL prefix the pages mount under. Default `'/'`. */
+    prefix?: string;
+    /** Optional layout component — when set, mdRoutes returns ONE parent route
+     * `{ path: prefix, Component: layout, children: [...mdLeaves] }`. */
+    layout?: ComponentType<any>;
+    /** Component-tag registry for `<Name />` tags inside the md body. */
+    components?: Record<string, ComponentType<any>>;
+    /** Loader for the LAYOUT parent route — runs before each md leaf renders and
+     * its data merges into the leaf's context top-down (so it feeds the layout
+     * chrome: sidebar, pager, …). Only applies when `layout` is set. Return keys
+     * that DON'T collide with the leaf's `__md` head metadata, which must win.
+     * Without this, the layout loader had to be attached by mutating the returned
+     * route node (`tree.loader = …`) — undocumented surface (was FRAMEWORK-GAPS G2). */
+    loader?: Route['loader'];
+}
+/** One frozen-manifest entry (everything route construction needs per page).
+ * `contentDir` is only present when the entry belongs to a DIFFERENT content
+ * dir than the manifest's top-level `contentDir` (apps mounting two or more
+ * `mdRoutes()` dirs share ONE manifest file per dist) — additive, so version-1
+ * manifests without it stay readable. */
+export interface MdManifestEntry {
+    relPath: string;
+    templateName: string;
+    urlPath: string;
+    frontmatter: MdFile['frontmatter'];
+    contentDir?: string;
+}
+export interface MdManifest {
+    version: 1;
+    contentDir: string;
+    entries: MdManifestEntry[];
+}
+export declare const MD_MANIFEST_FILENAME = "md-manifest.json";
+/** Write the frozen md manifest as `<dir>/md-manifest.json` (creates `dir`).
+ * Returns the absolute file path written. */
+export declare function writeMdManifest(dir: string, entries: MdManifestEntry[], contentDir: string): string;
+/** Read + schema-check a frozen md manifest. Throws on a missing file, bad
+ * JSON, or an unsupported version (fail loudly — the manifest is build output). */
+export declare function readMdManifest(file: string): MdManifest;
+/** The slice of a FlatRoute the manifest derivation reads (structural — avoids
+ * a circular import with runtime/md/emit.ts's FlatRouteLike). `Component` is
+ * declared (as unknown — never read here) so the all-optional shape shares a
+ * property with Route and FlatRoute[] passes TS weak-type detection. */
+export interface MdManifestFlatRouteLike {
+    fullPath?: string;
+    nativeTemplate?: string;
+    chain?: Array<{
+        Component?: unknown;
+        __mdSource?: MdRouteSource;
+    }>;
+}
+/** Derive the frozen md manifest from the FLAT ROUTE TABLE (single source of
+ * truth — never re-scan the fs at manifest-write time). Returns `null` when the
+ * app has no md routes, so callers can skip ALL md output (the `brust build`
+ * byte-identical invariant for md-free apps). With multiple `mdRoutes()` dirs,
+ * the first dir seen is the manifest's top-level `contentDir`; entries from
+ * other dirs carry a per-entry `contentDir`. */
+export declare function mdManifestFromFlatRoutes(flatRoutes: MdManifestFlatRouteLike[]): {
+    contentDir: string;
+    entries: MdManifestEntry[];
+} | null;
+/** Turn a directory of `.md` files into native Route entries. Each file gets a
+ * synthetic named component (name = its jinja template name, satisfying
+ * `validateRoute`'s native checks) and a loader exposing the frontmatter as
+ * `{ __md: { title, description } }`. With `layout`, returns ONE parent route
+ * at `prefix` whose children carry prefix-relative paths; without, the leaves
+ * carry the full prefixed path. */
+export declare function mdRoutes(contentDir: string, opts?: MdRoutesOptions): Route[];
+export interface MdNavItem {
+    title: string;
+    path: string;
+    order?: number;
+}
+export interface MdNavGroup {
+    group: string | null;
+    items: MdNavItem[];
+}
+/** Navigation model for a content dir: items grouped by `frontmatter.nav.group`
+ * (ungrouped pages land in a `group: null` top-level bucket), sorted by
+ * `nav.order` (missing order sorts last) then title. Paths use the prefix the
+ * dir was mounted under by `mdRoutes` (frozen-manifest urlPaths in a prebuilt
+ * run; `'/'` if mdRoutes was never called for the dir). Group order follows
+ * the first appearance of each group in the sorted item sequence. */
+export declare function mdNav(contentDir: string): MdNavGroup[];

package/types/md/scan.d.ts

@@ -0,0 +1,34 @@
+export interface MdFile {
+    /** Posix-separated path relative to the content dir, e.g. 'query/where.md'. */
+    relPath: string;
+    absPath: string;
+    frontmatter: {
+        title?: string;
+        description?: string;
+        nav?: {
+            group?: string;
+            order?: number;
+        };
+        [k: string]: unknown;
+    };
+    /** Markdown source after the frontmatter block is stripped. */
+    body: string;
+}
+/**
+ * Recursively scans `contentDir` for `.md` files, sorted by `relPath`.
+ *
+ * Frontmatter is a leading `---` … `---` block parsed as a hand-rolled YAML
+ * subset (NO yaml dependency):
+ * - `key: value` lines; keys match `[A-Za-z0-9_-]+`
+ * - values: double-quoted strings (JSON escapes), single-quoted strings (no
+ *   escapes), bare strings, numbers, booleans
+ * - one-level nested maps via the INLINE-BRACES form only, e.g.
+ *   `nav: { group: "Getting Started", order: 1 }` — indented child keys are
+ *   NOT supported and throw
+ * - blank lines inside the block are ignored
+ *
+ * Files without a frontmatter block get `frontmatter: {}` and the whole file
+ * as `body`. Malformed frontmatter throws with `<absPath>:<line>`. CRLF line
+ * endings are tolerated.
+ */
+export declare function scanMdDir(contentDir: string): MdFile[];

package/types/md/slug.d.ts

@@ -0,0 +1 @@
+export declare function slugifyHeading(text: string): string;

package/types/native/build.d.ts

@@ -0,0 +1,30 @@
+/** The single island-vs-behavior classifier: a component source is a native
+ * behavior component iff it has `export const behavior`. Shared by
+ * `scanDirectiveComponents` and the md emit step (runtime/md/emit.ts) so the
+ * two paths can never diverge. */
+export declare function isBehaviorSource(src: string): boolean;
+/** Deterministic, app-unique directive name = camelCase(basename) + "_" + 8 hex of
+ *  sha256(cwd-relative path). The SINGLE name contract: chunk filename, runtime
+ *  registry key, and the compiler-emitted `x-data` all derive from this. */
+export declare function directiveName(absPath: string, projectRoot: string): string;
+/** BFS the local import graph from the routes entry; return directiveName →
+ * absolute sourcePath for every file that has `export const behavior`. Throws on
+ * two distinct files deriving the same directive name (path-hashed, collision-resistant). */
+export declare function scanDirectiveComponents(routesEntryFile: string): Map<string, string>;
+export interface BuildDirectivesResult {
+    outDir: string;
+    count: number;
+    /** All emitted filenames (basenames): `_directives.js` (the shared runtime) plus
+     * one `<name>.directive.js` per component. Callers mirror these into .brust/islands. */
+    files: string[];
+}
+/** Build the shared directive runtime (`_directives.js`, loaded on every native page)
+ * PLUS one `<name>.directive.js` chunk per component (loaded ON DEMAND by the runtime
+ * when an `x-data="<name>"` appears). Splitting behaviors into per-component chunks
+ * keeps a page from downloading the JS of components it never renders; the runtime
+ * dynamically `import()`s a chunk the first time its name is seen (initial or post
+ * SPA-nav). Each chunk self-registers via the global `register` handle (so it needs
+ * no runtime import). React must not leak into any chunk — asserted per file. */
+export declare function buildDirectives(components: Map<string, string>, options: {
+    outDir: string;
+}): Promise<BuildDirectivesResult>;

package/types/native/index.d.ts

@@ -0,0 +1,2 @@
+export { register, start } from './runtime.ts';
+export type { Behavior, BehaviorCtx, Instance } from './runtime.ts';

package/types/native/runtime.d.ts

@@ -0,0 +1,52 @@
+export type Instance = Record<string, unknown>;
+/** What a `behavior` receives. Beyond `el`/`props`, two lifecycle helpers whose
+ * teardown auto-joins the component's disposer set (run on unmount / SPA-nav swap):
+ *  - `effect(fn)`  — a reactive effect (React `useEffect` semantics: `fn` may return
+ *                    a cleanup that runs before each re-run and on unmount). Use it
+ *                    for side-effects on signal change (sync localStorage, the DOM
+ *                    outside the component, timers). Returns the disposer too.
+ *  - `onCleanup(fn)` — register a one-shot teardown for unmount (e.g. removeEventListener). */
+export interface BehaviorCtx {
+    el: HTMLElement;
+    props: unknown;
+    effect: (fn: () => void | (() => void)) => () => void;
+    onCleanup: (fn: () => void) => void;
+}
+export type Behavior = (ctx: BehaviorCtx) => Instance;
+/** Register a component behavior under `name`. Called by `<name>.directive.js` chunks
+ * via the global handle below (they do NOT import this module — keeps each chunk to
+ * just its behavior, with the runtime shared as the single `_directives.js` copy). */
+export declare function register(name: string, behavior: Behavior): void;
+/** Scan `root` (default: document) for [x-data], mount each, and (once) attach a
+ * MutationObserver for dynamic mount/dispose. Idempotent. NOTE: `root` scopes the
+ * INITIAL scan only; the observer always watches the global `document.body` (one
+ * observer per document handles every later mount/dispose, incl. SPA-nav swaps),
+ * plus one observer per discovered OPEN shadow root (a body observer cannot see
+ * mutations inside a shadow tree). */
+export declare function start(root?: ParentNode): void;
+export interface ForExpr {
+    itemName: string;
+    indexName?: string;
+    listPath: string;
+    keyPaths?: string[];
+}
+/** Parse an x-for expression. Grammar:
+ *   (item[, index]) in listPath [by keyPath, keyPath, ...]
+ * Returns null on malformed input (caller warns + skips). */
+export declare function parseFor(raw: string): ForExpr | null;
+/** Write `value` into the signal at `path`, unwrapping intermediate signal/computed
+ * hops like `read()` (resolveRaw does NOT unwrap intermediates and cannot be the base
+ * for multi-hop paths). The LEAF is never called: `isSignal(leaf)` → `.set(value)`,
+ * else warn once and skip. */
+export declare function writePath(scope: Instance, path: string, value: unknown): void;
+/** Apply a bound value to a DOM attr/property. class → className; boolean props →
+ * property (when present) + attribute presence; value → property; else attribute. */
+export declare function setBound(el: HTMLElement, attr: string, value: unknown): void;
+/** Walk a dotted member path against `scope`, unwrapping a signal/computed at EVERY
+ * hop (so an intermediate item-signal is tracked by `effect`); at the LEAF also call
+ * a plain function to obtain its value (this read is what `effect` tracks). */
+export declare function read(scope: Instance, path: string): unknown;
+/** Resolve a dotted path WITHOUT calling the leaf (for x-on handlers). */
+export declare function resolveRaw(scope: Instance, path: string): unknown;
+/** Resolve `path` on `scope` and, if a function, call it with the event. */
+export declare function callMethod(scope: Instance, path: string, event: Event): void;

package/types/navigation/active-nav.d.ts

@@ -0,0 +1,2 @@
+export declare function installActiveNav(): void;
+export declare function __resetActiveNavForTest(): void;

package/types/navigation/index.d.ts

@@ -0,0 +1,5 @@
+export type { NavPhase, NavState, NavStore } from './store.ts';
+export { nav, getNavState, subscribe, onBeforeNavigate, onNavigate, onNavigateError, } from './store.ts';
+export { installActiveNav } from './active-nav.ts';
+export { navigate, buildSearch } from './navigate.ts';
+export type { NavigateOptions, QueryInit, QueryValue } from './navigate.ts';

package/types/navigation/navigate.d.ts

@@ -0,0 +1,14 @@
+export type QueryValue = string | number | boolean;
+export type QueryInit = Record<string, QueryValue | null | undefined | ReadonlyArray<QueryValue>>;
+export interface NavigateOptions {
+    query?: QueryInit;
+    replace?: boolean;
+}
+/** Serialize a query object to a `?...` string (or '' when empty). Pure, DOM-free. */
+export declare function buildSearch(query: QueryInit): string;
+/** Programmatic SPA navigation. Resolves `path` against the current location,
+ * merges `options.query` over any query already in `path` (each key replaces all
+ * base occurrences; null/undefined deletes), then delegates to the registered
+ * navigator (full SPA swap + nav-state lifecycle). No navigator registered (no
+ * islands bootstrap) → full-document load so the call still navigates. */
+export declare function navigate(path: string, options?: NavigateOptions): Promise<void>;

package/types/navigation/react.d.ts

@@ -0,0 +1,15 @@
+import { type NavState } from './store.ts';
+/** Watch the navigation state from a React island.
+ *
+ * ```tsx
+ * import { useNav } from 'brustjs/client'
+ * function Crumb() {
+ *   const { path, phase } = useNav()
+ *   return <span>{phase === 'loading' ? 'Loading…' : path}</span>
+ * }
+ * ```
+ *
+ * The third arg (server snapshot) is the same getter — on the server the store
+ * holds its idle defaults (no `location`), so SSR renders the idle state and the
+ * client hydrates the real one on mount. */
+export declare function useNav(): NavState;

package/types/navigation/store.d.ts

@@ -0,0 +1,44 @@
+import { type Signal } from '../store/signal.ts';
+export type NavPhase = 'idle' | 'loading' | 'success' | 'error';
+export interface NavState {
+    path: string;
+    search: string;
+    phase: NavPhase;
+    error: Error | null;
+    from: string | null;
+    to: string | null;
+}
+export interface NavStore {
+    path: Signal<string>;
+    search: Signal<string>;
+    phase: Signal<NavPhase>;
+    error: Signal<Error | null>;
+    from: Signal<string | null>;
+    to: Signal<string | null>;
+}
+type BeforeCb = (e: {
+    from: string;
+    to: string;
+}) => void;
+type NavCb = (e: NavState) => void;
+type ErrorCb = (e: {
+    to: string;
+    error: Error;
+}) => void;
+export declare const nav: NavStore;
+export declare function getNavState(): NavState;
+export declare function subscribe(cb: NavCb): () => void;
+export declare function onBeforeNavigate(cb: BeforeCb): () => void;
+export declare function onNavigate(cb: NavCb): () => void;
+export declare function onNavigateError(cb: ErrorCb): () => void;
+export declare function __navInit(path: string, search: string): void;
+export declare function __navStart(toPath: string, _toSearch: string): void;
+export declare function __navCommit(toPath: string, toSearch: string): void;
+export declare function __navError(toPath: string, error: unknown): void;
+/** Register the SPA navigator implementation (bootstrap's swap). Last-write-wins;
+ * re-registration with the same closure (HMR / multiple chunks) is idempotent. */
+export declare function registerNavigator(fn: (url: URL, replace: boolean) => Promise<void>): void;
+/** @internal — the registered navigator, or null when no islands bootstrap loaded. */
+export declare function _getNavigator(): ((url: URL, replace: boolean) => Promise<void>) | null;
+export declare function __resetNavForTest(): void;
+export {};

package/types/render/fragment.d.ts

@@ -0,0 +1,20 @@
+import { type ComponentType, type ReactNode } from 'react';
+/** 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. */
+export declare function renderToAwaitedString(element: ReactNode): Promise<string>;
+export interface RenderFragmentOpts {
+    /** Request cookies visible to cookies()/session helpers inside the tree. */
+    cookies?: Record<string, string>;
+}
+/** Render a component to an HTML string with framework contexts scoped:
+ * request scope (cookies) ∘ request cache (cachedFetch/dedupe) ∘ store
+ * context (fresh per call — no cross-call leakage; concurrency-safe via
+ * AsyncLocalStorage). Suspense supported — the promise resolves when the
+ * whole tree is ready, never with fallbacks. Static HTML only: no island
+ * hydration markers/scripts (an `<Island>` inside the fragment SSRs its
+ * component but ships no hydration), no head/CSS collection, no streaming.
+ * Native/jinja fragments are served by `templates.render` instead.
+ * Errors reject with the component's error — no error-boundary semantics. */
+export declare function renderFragment<P extends object>(Component: ComponentType<P>, props: P, opts?: RenderFragmentOpts): Promise<string>;

package/types/render/inject-action-prefix.d.ts

@@ -0,0 +1,9 @@
+/** @internal — used by tests to reset the warn-once flag. */
+export declare function _resetWarnedForTests(): void;
+/** Splice `snippet` (a full `<script>…</script>`) into `body` immediately
+ * before the first `</head>` (case-insensitive on the four ASCII letters
+ * only). Returns the original body untouched if `snippet` is null/empty or if
+ * `</head>` is absent. */
+export declare function injectActionPrefix(body: Uint8Array, snippet: string | null): Uint8Array;
+export declare function configureActionPrefixSnippet(s: string | null): void;
+export declare function getActionPrefixSnippet(): string | null;

package/types/render/inject-css-link.d.ts

@@ -0,0 +1,8 @@
+/** @internal — used by the unit test suite to reset the warn-once flag. */
+export declare function _resetWarnedForTests(): void;
+/** Splice `<link rel="stylesheet" href="...">` tags into `body` immediately
+ * before the first occurrence of `</head>` (case-insensitive). Returns the
+ * original body untouched if `hrefs` is empty or if `</head>` is absent
+ * (warns once in the latter case). Renderer calls this on the first chunk
+ * only — see spec S"SSR <link> injection". */
+export declare function injectCssLink(body: Uint8Array, hrefs: readonly string[]): Uint8Array;

package/types/render/inject-dev-client.d.ts

@@ -0,0 +1,6 @@
+/** @internal — used by tests to reset the warn-once flag. */
+export declare function _resetWarnedForTests(): void;
+/** Splice `snippet` into `body` immediately before the first `</head>`
+ * (case-insensitive on the four ASCII letters only). Returns the original body
+ * untouched if `snippet` is null/empty or if `</head>` is absent. */
+export declare function injectDevClient(body: Uint8Array, snippet: string | null): Uint8Array;

package/types/render/inject-generator.d.ts

@@ -0,0 +1,7 @@
+/** Seed from generator.json at boot (main + worker). null → no injection. */
+export declare function configureGeneratorMeta(meta: string | null): void;
+export declare function getGeneratorMeta(): string | null;
+/** Splice `metaTag` immediately before the first `</head>` (case-insensitive).
+ * No </head> in the chunk, empty tag, or an existing generator meta → body
+ * returned untouched. Byte-level (no decode) — safe with multibyte content. */
+export declare function injectGeneratorMeta(body: Uint8Array, metaTag: string | null): Uint8Array;

package/types/render/inject-store.d.ts

@@ -0,0 +1,9 @@
+/** @internal — used by tests to reset the warn-once flag. */
+export declare function _resetWarnedForTests(): void;
+/** Build the combined `<script type="application/json">` blob for every touched
+ * store. Returns '' when the snapshot is null/empty. */
+export declare function buildStoreScripts(snap: Record<string, Record<string, unknown>> | null): string;
+/** Splice the store snapshot `<script>`(s) into `body` immediately before the
+ * first `</head>`. Returns the original body untouched if the snapshot is
+ * null/empty or if `</head>` is absent. */
+export declare function injectBrustStore(body: Uint8Array, snap: Record<string, Record<string, unknown>> | null): Uint8Array;

package/types/render/stream.d.ts

@@ -0,0 +1,45 @@
+import { type ReactNode, type ComponentType } from 'react';
+export interface RenderBranchStreamingArgs {
+    element: ReactNode;
+    /** The render's SAB sub-view (whole buffer at slots=1). All chunk encodes
+     * write at offset 0 of this view → automatically the slot's base. */
+    view: Uint8Array;
+    /** The render slot index, passed to every napi.renderChunk* call so Rust
+     * reads/writes the matching SAB sub-region. Default 0 (single-slot path). */
+    slot?: number;
+    workerId: bigint;
+    napi: {
+        renderChunk: (workerId: bigint, slot: number, len: number, sabBytes: Uint8Array) => Promise<void>;
+        renderChunkFinal: (workerId: bigint, slot: number, len: number, sabBytes: Uint8Array) => Promise<void>;
+    };
+    errorBoundary: ComponentType<{
+        error: Error;
+    }>;
+    /** Status for the successful (non-error) render. Default 200. Used by
+     * middleware-wrapped routes that want to set a non-200 status before
+     * the component runs (e.g. 201 from a server action redirect). */
+    status?: number;
+    /** Extra response headers injected by middleware (e.g. `x-render-ms`).
+     * Merged into the meta envelope's `headers` map. */
+    headers?: Record<string, string>;
+    /** The matched route's fullPath (e.g. '/' or '/blog/{slug}'). Used to
+     * combine global CSS hrefs with per-route CSS hrefs before injection. */
+    routePath?: string;
+    /** Per-request store snapshot collected after loaders run. Injected as a
+     * `<script data-brust-store="…">` blob before `</head>` (buffering) or into
+     * the streaming first-chunk prepend. Null/undefined → no injection. */
+    storeSnapshot?: Record<string, Record<string, unknown>> | null;
+    /** Inject the islands importmap + bootstrap even when no <Island> rendered.
+     * SSG fallback shells need the bootstrap (client takeover runtime) on pages
+     * that may have zero real islands. */
+    forceIslands?: boolean;
+}
+/** JSON.stringify the per-chunk meta. Defaults match the renderToString
+ * path so single-chunk responses keep their existing wire shape. */
+export declare function makeMeta(opts: {
+    status: number;
+    streaming: boolean;
+    contentType?: string;
+    headers?: Record<string, string>;
+}): string;
+export declare function renderBranchStreaming(args: RenderBranchStreamingArgs): Promise<void>;

package/types/request-context.d.ts

@@ -0,0 +1,16 @@
+interface RequestScope {
+    ctx: Map<string, unknown>;
+    reqCookies: Record<string, string>;
+    setCookies: string[];
+}
+/** Open a per-request scope. `reqCookies` is the parsed incoming Cookie header
+ * (BrustRequest.cookies). Staged Set-Cookie strings accumulate in `setCookies`
+ * and are flushed by routes.ts onto the response headers. */
+export declare function runInRequestScope<T>(reqCookies: Record<string, string>, fn: () => T): T;
+/** Per-request scratch Map for apps building request-scoped state on top of the
+ * module-global store. Throws when called outside a request scope. */
+export declare function getRequestContext(): Map<string, unknown>;
+/** Internal — the active scope (or undefined). Used by cookies.ts and the
+ * routes.ts flush. Not re-exported from the package entry. */
+export declare function __scope(): RequestScope | undefined;
+export {};