brustjs 0.1.50-alpha → 0.1.51-alpha

package/types/islands/isr-jsx.d.ts

@@ -0,0 +1,31 @@
+/** Shape of the `isr` attribute on an SSR component or `ssr` island on a
+ * native-jinja route. `renderToString` runs ONCE per `key`; later same-key
+ * requests serve the frozen markup from the Rust-side cache. */
+export interface IsrConfig {
+    /** Required unique cache key. A different key is a different cached render.
+     * Compute it in the loader and pass it through (e.g. `data.cacheKey`). */
+    key: string;
+    /** Optional groups for bulk invalidation —
+     * `import { cache } from 'brustjs'; cache.invalidate({ tags: ['blog'] })`
+     * evicts every entry carrying a tag. `cache.invalidate({ key })` evicts one. */
+    tags?: string[];
+    /** Optional TTL in SECONDS (integer). Omit to cache until invalidated. */
+    revalidate?: number;
+}
+declare module 'react' {
+    namespace JSX {
+        interface IntrinsicAttributes {
+            /** brust ISR cache directive — compiler-consumed (stripped before the
+             * component is called), valid on any SSR component or `ssr` island on a
+             * native route. See {@link IsrConfig}. */
+            isr?: IsrConfig;
+            /** brust `native` inline directive — compiler-consumed (stripped at lower
+             * time). On a native-jinja route, `<Comp native />` expands the component
+             * inline at compile time (no JS-worker render) when it is pure
+             * (props→JSX, no hooks/side-effects); otherwise it degrades to a normal
+             * SSR component with a build warning. Bare boolean, like `ssr` on an
+             * island. */
+            native?: boolean;
+        }
+    }
+}

package/types/islands/native-render.d.ts

@@ -0,0 +1,89 @@
+/** Set the directory the sidecar-manifest readers resolve against. Called once
+ * at boot from `index.ts`, mirroring `configureIslandsDir`/`configureCssDir`. */
+export declare function configureJinjaDir(dir: string): void;
+/** One entry of a `<template>.islands.json` manifest (enriched by T6). */
+export interface NativeIslandEntry {
+    component: string;
+    instance: number;
+    propsPath: string;
+    /** Literal props value baked at build time (md pages). When present
+     * (`!== undefined` — `null` and falsy literals are valid), it is used as the
+     * props value and `propsPath` is ignored (md entries carry `propsPath: ''`
+     * since the field is required). */
+    propsLiteral?: unknown;
+    ssr: boolean;
+    hydrate: string;
+    sourcePath: string;
+    /** Dotted path into loader data yielding the ISR cache key (string). */
+    keyPath?: string;
+    /** Dotted path into loader data yielding the ISR cache tags (string[]). */
+    tagsPath?: string;
+    /** Revalidate window in SECONDS; converted to ttlMs on cache.set. */
+    revalidate?: number;
+    /** Static ISR cache key (string literal in JSX). Takes precedence over keyPath. */
+    keyLiteral?: string;
+    /** Static ISR cache tags (array literal in JSX). Takes precedence over tagsPath. */
+    tagsLiteral?: string[];
+}
+/** Rust-side ISR cache, injected as a port for testability. A `get` hit
+ * returns a FROZEN {html,props} pair (the props are the entity-encoded attr
+ * string, identical to what was stored) so the served markup and the hydrated
+ * props stay byte-identical regardless of live loader-data mutation. */
+export interface IslandCache {
+    get(key: string): {
+        html: string;
+        props: string;
+    } | null;
+    set(key: string, tags: string[], ttlMs: number | undefined, html: string, props: string): void;
+}
+/** Walk a dotted path into `data`. Each segment must be an OWN enumerable
+ * property — inherited keys (`constructor`, `__proto__`, `toString`, …) yield
+ * `undefined` rather than traversing the prototype chain. This blocks both
+ * prototype-pollution-style reads AND the downstream crash where a resolved
+ * function (`Object`) makes `JSON.stringify` return `undefined`. A missing
+ * segment, a nullish/primitive cursor, or a non-own key all yield `undefined`.
+ * An empty path returns `data` itself. */
+export declare function pathInto(data: unknown, propsPath: string): unknown;
+/** HTML-entity-encode a string for a double-quoted attribute value. Order is
+ * load-bearing: `&` MUST be replaced first so the entities introduced by the
+ * later replacements aren't themselves double-encoded. Matches the compiler's
+ * `push_attr_escaped` charset (& < > ") so server-rendered markup and these
+ * props attrs stay consistent. */
+export declare function entityEncode(s: string): string;
+/** Read `<jinjaDir>/<templateName>.islands.json` and return the parsed entry
+ * array, or `null` if the file doesn't exist. `jinjaDir` defaults to the
+ * boot-configured jinja dir (`configureJinjaDir`), or `cwd/.brust/jinja` when
+ * unset; tests pass a temp dir. Both hits and misses are cached by absolute path. */
+export declare function loadIslandManifest(templateName: string, jinjaDir?: string): NativeIslandEntry[] | null;
+/** Build the per-island context additions for a manifest. Each entry
+ * contributes `island_<instance>_props` — the resolved props, JSON-stringified
+ * (undefined → null so it stays valid JSON) and entity-encoded. SSR entries
+ * (`ssr:true`) ALSO contribute `island_<instance>_html` — the island source
+ * component imported by absolute path and renderToString'd. The `instance` is a
+ * per-occurrence integer, so it's a safe key fragment. */
+export declare function resolveIslandContext(manifest: NativeIslandEntry[], data: unknown, cache?: IslandCache): Promise<Record<string, string>>;
+/** One entry in `<Name>.components.json` as enriched by `emitComponentArtifacts`. */
+export interface NativeComponentEntry {
+    component: string;
+    instance: number;
+    sourcePath: string;
+    /** Dotted path into loader data yielding the ISR cache key (string). */
+    keyPath?: string;
+    /** Dotted path into loader data yielding the ISR cache tags (string[]). */
+    tagsPath?: string;
+    /** Revalidate window in SECONDS; converted to ttlMs on cache.set. */
+    revalidate?: number;
+    /** Static ISR cache key (string literal in JSX). Takes precedence over keyPath. */
+    keyLiteral?: string;
+    /** Static ISR cache tags (array literal in JSX). Takes precedence over tagsPath. */
+    tagsLiteral?: string[];
+}
+/** Read `<jinjaDir>/<templateName>.components.json` and return the parsed entry
+ * array, or `null` if the file doesn't exist. Both hits and misses are cached
+ * by absolute path (same invariant as `loadIslandManifest`). */
+export declare function loadComponentManifest(templateName: string, jinjaDir?: string): NativeComponentEntry[] | null;
+/** Build the per-component context additions for a manifest. Each entry
+ * contributes `comp_<instance>_html` — the component rendered to HTML by
+ * the route's factory function. On `renderToString` failure: degrade to
+ * `comp_N_html = ""` and log, mirrors SSR island failure behaviour. */
+export declare function resolveComponentContext(manifest: NativeComponentEntry[], data: unknown, templateName: string, jinjaDir?: string, cache?: IslandCache): Promise<Record<string, string>>;

package/types/loader-cache.d.ts

@@ -0,0 +1,18 @@
+export declare function runInRequestCache<T>(fn: () => T): T;
+/** Request-scoped memoize: share the in-flight promise + cache result for the
+ * scope's lifetime. Outside a scope → passthrough. Reject → guarded delete
+ * (identity-checked) so a stale catch can't evict a newer entry.
+ *
+ * NOTE: the reject cleanup runs one microtask after rejection, so a caller that
+ * dedupes the SAME key within that gap receives the about-to-reject promise (and
+ * thus the rejection) — acceptable: the result is one shared failure, not a hang. */
+export declare function dedupe<T>(key: string, fn: () => Promise<T>): Promise<T>;
+/** Idempotent (GET/HEAD) fetch deduped per request; non-idempotent → bypass.
+ * Returns a fresh clone every call (the stored Response is never exposed).
+ *
+ * NOTE: the cache key is `method + url` ONLY — it does NOT include `init`
+ * headers/body. Two `cachedFetch(sameUrl, {headers:…})` calls with DIFFERENT
+ * headers in one request share the FIRST call's response. Intended for plain
+ * idempotent GETs (the common loader case); if a caller varies `init` per call
+ * on the same URL, use `fetch` directly. */
+export declare function cachedFetch(url: string, init?: RequestInit): Promise<Response>;

package/types/mcp/extractor.d.ts

@@ -0,0 +1,14 @@
+import type { FlatRoute } from '../routes.ts';
+import type { McpManifest } from './manifest.ts';
+export interface ExtractOptions {
+    /** Module exporting `defineActions(...)`. Convention `<scanRoot>/actions.ts`.
+     * Absent → zero tools (resources still extracted). */
+    actionsFile?: string;
+    /** The routes module file. */
+    routesFile: string;
+    /** User source roots. Reserved for future tsconfig resolution. */
+    sourceRoots: string[];
+    /** Result of `defineRoutes(...)`. */
+    routes: FlatRoute[];
+}
+export declare function extractMcpManifest(opts: ExtractOptions): Promise<McpManifest>;

package/types/mcp/manifest.d.ts

@@ -0,0 +1,23 @@
+import type { JsonSchema } from './schema.ts';
+export interface ToolSchema {
+    name: string;
+    description?: string;
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD';
+    path: string;
+    inputSchema: JsonSchema;
+    outputSchema?: JsonSchema;
+}
+export interface ResourceSchema {
+    uriTemplate: string;
+    name: string;
+    description?: string;
+    outputSchema?: JsonSchema;
+    routeIndex: number;
+}
+export interface McpManifest {
+    version: 1;
+    tools: ToolSchema[];
+    resources: ResourceSchema[];
+}
+export declare function writeManifest(cwd: string, m: McpManifest): Promise<void>;
+export declare function readManifest(cwd: string): Promise<McpManifest | null>;

package/types/mcp/schema.d.ts

@@ -0,0 +1,19 @@
+import ts from 'typescript';
+export interface JsonSchema {
+    type?: string | string[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    items?: JsonSchema;
+    prefixItems?: JsonSchema[];
+    minItems?: number;
+    maxItems?: number;
+    additionalProperties?: JsonSchema | boolean;
+    anyOf?: JsonSchema[];
+    enum?: unknown[];
+    format?: string;
+}
+export interface ToJsonSchemaOptions {
+    unwrapPromise?: boolean;
+    checker?: ts.TypeChecker;
+}
+export declare function tsTypeToJsonSchema(type: ts.Type, opts?: ToJsonSchemaOptions): JsonSchema | undefined;

package/types/mcp/server.d.ts

@@ -0,0 +1,15 @@
+import type { FlatRoute, BrustRequest } from '../routes.ts';
+import type { EndpointDef } from '../define-actions.ts';
+import type { McpManifest } from './manifest.ts';
+export interface McpServerOptions {
+    manifest: McpManifest;
+    endpoints: EndpointDef[];
+    routes: FlatRoute[];
+    packageVersion?: string;
+}
+export interface McpServer {
+    handleRequest(jsonRpcBody: string, req: BrustRequest): Promise<string>;
+}
+export declare function makeMcpServer(opts: McpServerOptions): McpServer;
+export declare function makeResult(id: number | string | null, result: unknown): string;
+export declare function makeError(id: number | string | null, code: number, message: string): string;

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