brustjs 0.1.50-alpha → 0.1.52-alpha

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 {};