brustjs 0.1.49-alpha → 0.1.51-alpha

package/types/css/manifest.d.ts

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

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

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

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

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

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

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

package/types/css.d.ts

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

package/types/define-actions.d.ts

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

package/types/dev/client.d.ts

@@ -0,0 +1,8 @@
+/** Browser dev client. Inlined into the SSR first chunk via a <script
+ * type="module">…</script> wrapper. Connects WS at /_brust/dev, handles
+ * reload / css-update / error / ok messages, manages a red overlay.
+ *
+ * Keep this string short — it ships in every dev-mode SSR response. */
+export declare const DEV_CLIENT_JS: string;
+/** Build the full <script> tag that gets spliced before </head>. */
+export declare function buildDevClientTag(): string;

package/types/dev/coordinator.d.ts

@@ -0,0 +1,33 @@
+import type { DevMessage } from './ws-channel.ts';
+import type { ChangeKind } from './watcher.ts';
+export interface CoordinatorDeps {
+    workers: {
+        terminateAll(): Promise<void>;
+        spawnAll(): Promise<void>;
+    };
+    buildCss: () => Promise<void>;
+    buildIslands: () => Promise<void>;
+    /** Recompile native-route `.jinja` templates from source and reload them into
+     * the minijinja env, so `native: true` routes pick up .tsx edits on reload. */
+    reEmitJinja: () => Promise<void>;
+    /** Clear the Rust-side island ISR cache. Called on every render-affecting
+     * reload (`ts`/`html`/`islands`) so a `.tsx` edit is reflected immediately —
+     * a frozen island render from before the edit must never survive a hot reload.
+     * Optional: a build without the island-cache addon export omits it. */
+    clearIslandCache?: () => void;
+    buildComponentCss?: () => Promise<void>;
+    snapshotComponentCss?: () => Promise<import('../css/manifest.ts').ComponentCssManifest | null>;
+    broadcast: (msg: DevMessage) => Promise<void> | void;
+    tui: {
+        appendEvent(line: string): void;
+    };
+}
+export declare class Coordinator {
+    private deps;
+    private state;
+    constructor(deps: CoordinatorDeps);
+    handleChange(ev: {
+        paths: string[];
+        kind: ChangeKind;
+    }): Promise<void>;
+}

package/types/dev/inject.d.ts

@@ -0,0 +1,6 @@
+/** Set the dev-client snippet (full `<script>…</script>` tag) the renderer
+ * should inject before `</head>`. Pass `null` to disable injection (the
+ * default in non-dev mode). */
+export declare function configureDevClientSnippet(s: string | null): void;
+/** Returns the configured snippet, or `null` when dev mode is off. */
+export declare function getDevClientSnippet(): string | null;

package/types/dev/jinja-reload.d.ts

@@ -0,0 +1,7 @@
+/** Called once by `brust dev` after the initial native-template emit. */
+export declare function registerJinjaReEmit(fn: () => Promise<void>): void;
+/** Called by the dev coordinator on a ts/html/islands hot reload. No-op when no
+ * callback is registered (e.g. unit tests, or an app with no native routes). */
+export declare function reEmitJinja(): Promise<void>;
+/** Test helper. */
+export declare function _resetForTests(): void;

package/types/dev/tui.d.ts

@@ -0,0 +1,35 @@
+interface Status {
+    port: number;
+    workers: number;
+    watching: string[];
+}
+export interface TuiOptions {
+    isTty: boolean;
+    write: (s: string) => void;
+    capacity?: number;
+}
+/** Astro-style dev output: a clean one-time banner on ready, then event lines
+ * that scroll naturally below it. Deliberately NOT a full-screen TUI — it never
+ * hides the cursor or clears the screen, so the terminal is left exactly as it
+ * was found when the dev server exits (no more vanished cursor on Ctrl-C). */
+export declare class Tui {
+    private opts;
+    private events;
+    private capacity;
+    private bannerShown;
+    constructor(opts: TuiOptions);
+    eventsForTests(): string[];
+    /** Print the ready banner. Idempotent — only the first call emits it. */
+    updateStatus(s: Status): void;
+    /** Append one event. Scrolls below the banner (TTY) or prints a plain line
+     * (non-TTY / CI). The in-memory ring buffer backs `eventsForTests`. */
+    appendEvent(line: string): void;
+    /** Called on shutdown. There is nothing to restore (we never altered the
+     * terminal mode); the reset is belt-and-braces so a half-written colored
+     * line can't bleed into the user's prompt. */
+    stop(): void;
+    /** Colorize an event line in TTY mode: a dim timestamp prefix, with ok/error
+     * markers tinted. The coordinator emits `  → ok (Nms)` and `  ✗ <msg>`. */
+    private format;
+}
+export {};

package/types/dev/watcher.d.ts

@@ -0,0 +1,34 @@
+export type ChangeKind = 'ts' | 'css' | 'component-css' | 'html' | 'islands' | 'md';
+/** Classify a changed path. Returns null when the path should be ignored.
+ * `root` is used to compute the relative path for ignore-segment matching.
+ * `hasMdRoutes` gates the `'md'` kind (S4): when the app has no md routes, a
+ * project `.md` edit (README.md, notes) must not trigger the full reload path
+ * (island rebuild + worker restart) — it classifies as null instead. Defaults
+ * to true for backward compatibility with callers that don't thread the flag. */
+export declare function classifyPath(absPath: string, root: string, hasMdRoutes?: boolean): ChangeKind | null;
+interface Coalesce {
+    add(path: string): void;
+    flush(): void;
+}
+/** Internal — exposed for unit tests. */
+export declare function _testCoalesce(debounceMs: number, flush: (paths: string[]) => void): Coalesce;
+export interface CreateWatcherOptions {
+    root: string;
+    debounceMs?: number;
+    /** Whether the app has md routes — gates `.md` classification (see
+     * classifyPath). Defaults to true (back-compat). */
+    hasMdRoutes?: boolean;
+    onChange: (ev: {
+        paths: string[];
+        kind: ChangeKind;
+    }) => void;
+}
+export interface Watcher {
+    close(): void;
+}
+/** Watch `root` recursively. Emits one `onChange` call per debounce window
+ * with paths classified by the dominant kind. Mixed-kind windows pick
+ * by priority: islands > ts > html > css (islands trigger a full restart
+ * that subsumes the others). */
+export declare function createWatcher(opts: CreateWatcherOptions): Watcher;
+export {};

package/types/dev/worker-registry.d.ts

@@ -0,0 +1,17 @@
+/** Called once by brust.serve() in dev mode AFTER it spawns the initial
+ * pool. Hands the references to the registry so the coordinator can
+ * churn them later. */
+export declare function registerInitialPool(workers: Worker[], entry: string, count: number, baseEnv: Record<string, string>): void;
+/** Terminate every Worker with a 2s per-worker grace. If termination
+ * doesn't return in time, abandon the reference and continue. */
+export declare function terminateAll(): Promise<void>;
+/** Spawn `count` fresh Workers using the entry + env captured at
+ * registerInitialPool time. Each worker gets BRUST_WORKER_ID=i.
+ * Resolves only after every fresh worker reports `brust-worker-ready`
+ * via postMessage — so the caller (coordinator) doesn't broadcast
+ * `reload` against workers whose message listeners aren't installed
+ * yet. Falls back after a 5s grace if a worker never signals. */
+export declare function spawnAll(): Promise<void>;
+/** Test helper. */
+export declare function _workersForTests(): Worker[];
+export declare function _resetForTests(): void;

package/types/dev/ws-channel.d.ts

@@ -0,0 +1,39 @@
+import type { Route } from '../routes.ts';
+/** Server-to-client protocol. Client never sends after open. */
+export type DevMessage = {
+    type: 'building';
+} | {
+    type: 'reload';
+} | {
+    type: 'css-update';
+    href: string;
+} | {
+    type: 'error';
+    message: string;
+    stack?: string;
+} | {
+    type: 'ok';
+};
+export declare function _clientCountForTests(): number;
+export declare function _resetForTests(): void;
+/** Build the synthetic /_brust/dev WS route. brust.run() prepends this
+ * to opts.routes in dev mode (both main + worker route arrays). */
+export declare function createDevWsRoute(): Route;
+/** Worker-side: install a message listener that receives `dev-broadcast`
+ * envelopes from the main process and forwards them to this worker's
+ * local clients. Idempotent. After install, posts `brust-worker-ready`
+ * back to the parent so spawnAll() knows the worker is ready to relay
+ * broadcasts (avoids a race where `reload` is dispatched before the
+ * fresh worker's listener is wired). */
+export declare function installWorkerBroadcastListener(): void;
+/** Main-side: push the message to every `/_brust/dev` client through the napi
+ * addon. The dev WS is a Rust-owned control channel (see the `/_brust/dev`
+ * branch in crates/brust/src/server.rs), so the frame is delivered straight
+ * through each connection's Rust-owned send_tx and SURVIVES a hot reload's
+ * worker restart.
+ *
+ * The previous implementation relayed main→worker→worker-local-clients, which
+ * lost the `reload` frame: the coordinator broadcasts it AFTER terminateAll(),
+ * by which point the connection's worker-side registration had died with the
+ * old worker. */
+export declare function broadcast(msg: DevMessage): Promise<void>;

package/types/generator.d.ts

@@ -0,0 +1,23 @@
+export interface GeneratorStrings {
+    /** Full meta tag, e.g. `<meta name="generator" content="brust 0.1.48-alpha"/>` */
+    meta: string;
+    /** X-Powered-By value, e.g. `brust/0.1.48-alpha` */
+    header: string;
+}
+/** Build the resolved strings. Version comes from the brustjs package.json
+ * (readVersion never throws — "unknown" degrades to name-only, never a crash).
+ * The version is sanitized to attr/header-safe bytes; semver chars only. */
+export declare function generatorStrings(versionOn: boolean): GeneratorStrings;
+/** Insert the generator meta immediately after the compiler-emitted viewport
+ * meta. Anchor missing (non-document template) → no-op, never an error.
+ * CALLER CONTRACT: pass fresh compiler output — this function does not check
+ * for an existing tag, so calling it twice on the same string duplicates.
+ * Every emit path recompiles from source each run, which keeps this safe. */
+export declare function insertGeneratorMeta(jinja: string, metaTag: string): string;
+/** Write the decision artifact into `dir` (a jinja out dir), creating it. */
+export declare function writeGeneratorArtifact(dir: string, strings: GeneratorStrings): void;
+/** Read the artifact; null on missing/malformed (caller decides the fallback). */
+export declare function readGeneratorArtifact(dir: string): GeneratorStrings | null;
+/** Artifact if present, else version-on defaults — the spec's fallback policy
+ * (an old dist with no artifact behaves as default = version on). */
+export declare function resolveGenerator(dir: string): GeneratorStrings;