@nifrajs/web 2.14.1 → 3.2.0

package/dist/boundary.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Framework-neutral async boundaries. A boundary owns one named piece of UI data; the web core owns
+ * lifecycle, concurrency, and isolation while each adapter decides how its `render` result is mounted.
+ * The contract deliberately contains no React/Svelte/Vue/Preact types.
+ */
+/** Request-scoped inputs available to dynamic and intercepting boundaries. */
+export interface BoundaryRequestCtx {
+    readonly request: Request;
+    readonly params: Readonly<Record<string, string>>;
+    readonly api: unknown;
+    readonly env: unknown;
+    readonly draft: boolean;
+    readonly search: Readonly<Record<string, unknown>>;
+    readonly signal: AbortSignal;
+}
+/** Build-safe inputs available to a static boundary. It intentionally has no request/session/params API. */
+export interface StaticCtx {
+    readonly phase: "build";
+    readonly origin?: string;
+}
+export type BoundaryMode = "static" | "dynamic" | {
+    readonly intercept: string;
+};
+interface BoundaryBase<Data, UI> {
+    readonly name: string;
+    readonly render: (data: Data) => UI;
+    readonly fallback?: UI;
+    /** Adapter-provided error slot name. The neutral core never imports a UI component. */
+    readonly errorId?: string;
+}
+export type StaticBoundary<Data, UI> = BoundaryBase<Data, UI> & {
+    readonly mode: "static";
+    readonly load?: (ctx: StaticCtx) => Data | Promise<Data>;
+};
+export type DynamicBoundary<Data, UI> = BoundaryBase<Data, UI> & {
+    readonly mode: "dynamic";
+    readonly load?: (ctx: BoundaryRequestCtx) => Data | Promise<Data>;
+};
+export type InterceptBoundary<Data, UI> = BoundaryBase<Data, UI> & {
+    readonly mode: {
+        readonly intercept: string;
+    };
+    readonly load?: (ctx: BoundaryRequestCtx) => Data | Promise<Data>;
+};
+/** A discriminated union: the `mode` selects the context type accepted by `load`. */
+export type Boundary<Data, UI> = StaticBoundary<Data, UI> | DynamicBoundary<Data, UI> | InterceptBoundary<Data, UI>;
+/**
+ * Erased runtime registration shape used by a route/layout manifest. This is intentionally a
+ * structural union rather than `Boundary<never, unknown>`: a registration keeps its loader's
+ * concrete data type at the declaration site, and function-parameter variance must not turn that
+ * loader into `Promise<never>` when the manifest erases it.
+ */
+type ErasedBoundaryBase = {
+    readonly name: string;
+    readonly render: (data: never) => unknown;
+    readonly fallback?: unknown;
+    readonly errorId?: string;
+};
+export type BoundaryRegistration = (ErasedBoundaryBase & {
+    readonly mode: "static";
+    readonly load?: (ctx: StaticCtx) => unknown | Promise<unknown>;
+}) | (ErasedBoundaryBase & {
+    readonly mode: "dynamic";
+    readonly load?: (ctx: BoundaryRequestCtx) => unknown | Promise<unknown>;
+}) | (ErasedBoundaryBase & {
+    readonly mode: {
+        readonly intercept: string;
+    };
+    readonly load?: (ctx: BoundaryRequestCtx) => unknown | Promise<unknown>;
+});
+/** Neutral manifest descriptor: no framework component crosses the web core boundary. */
+export interface BoundaryDescriptor {
+    readonly name: string;
+    readonly mode: BoundaryMode;
+    readonly hasLoad: boolean;
+    readonly errorId?: string;
+}
+export type BoundaryStatus = "unresolved" | "pending" | "ready" | "error";
+export interface BoundaryError {
+    readonly name: string;
+    readonly message: string;
+}
+/** Serializable boundary state passed to the adapter's render seam. */
+export interface BoundaryState {
+    readonly name: string;
+    readonly mode: BoundaryMode;
+    readonly status: BoundaryStatus;
+    readonly data?: unknown;
+    readonly error?: BoundaryError;
+    readonly errorId?: string;
+}
+export type BoundaryStates = Readonly<Record<string, BoundaryState>>;
+/** A dynamic load that has started but is not part of the initial render barrier. */
+export interface PendingBoundary {
+    readonly name: string;
+    readonly mode: BoundaryMode;
+    readonly errorId?: string;
+    readonly promise: Promise<unknown>;
+}
+/** Runtime handles for a concurrent boundary batch. `initial` is renderable immediately. */
+export interface DynamicBoundaryBatch {
+    readonly initial: BoundaryStates;
+    readonly pending: ReadonlyArray<PendingBoundary>;
+    /** Resolves to final per-boundary states for non-streaming consumers and tests. */
+    readonly complete: Promise<BoundaryStates>;
+}
+/** Public in-memory reference cache for build-safe static boundary values. It holds no payload outside
+ * the process and is intentionally not a durable or tenant-aware cache implementation. */
+export interface StaticBoundaryCache {
+    get(boundary: BoundaryRegistration): Promise<unknown> | undefined;
+    set(boundary: BoundaryRegistration, value: Promise<unknown>): void;
+}
+export declare class MemoryStaticBoundaryCache implements StaticBoundaryCache {
+    #private;
+    get(boundary: BoundaryRegistration): Promise<unknown> | undefined;
+    set(boundary: BoundaryRegistration, value: Promise<unknown>): void;
+}
+export interface StaticBoundaryImportEdge {
+    readonly from: string;
+    readonly to: string;
+}
+export interface StaticBoundaryRoot {
+    readonly name: string;
+    readonly module: string;
+}
+/**
+ * Enforce the second half of the static-boundary safety boundary. A build adapter supplies the
+ * transitive module graph and the modules it has classified as request-scoped; a static root that
+ * reaches one fails before any shared shell is emitted. Keeping this check graph-shaped makes it
+ * usable by Bun/Vite without making the neutral web runtime depend on either bundler.
+ */
+export declare function assertStaticBoundaryImports(roots: readonly StaticBoundaryRoot[], edges: readonly StaticBoundaryImportEdge[], requestScopedModules: ReadonlySet<string>): void;
+/** Validate and serialize the neutral boundary manifest. Duplicate names fail closed at startup. */
+export declare function boundaryDescriptors(boundaries: readonly BoundaryRegistration[]): ReadonlyArray<BoundaryDescriptor>;
+/**
+ * Resolve all dynamic boundaries concurrently. Each receives a fresh frozen context object; one
+ * failure becomes that boundary's error state and never rejects a sibling or exposes sibling data.
+ * Static/intercepting modes remain `unresolved` until their phase-specific runtime owns them.
+ */
+export declare function resolveDynamicBoundaries(boundaries: readonly BoundaryRegistration[], context: BoundaryRequestCtx): Promise<BoundaryStates>;
+/**
+ * Start all dynamic boundary loads at once without making the page wait for the slowest sibling.
+ * The initial states contain `status: "pending"`; callers that support deferred values can attach
+ * each `pending.promise` to its own slot. `complete` still provides settled, isolated states to
+ * non-streaming callers, preserving the simple reference API.
+ */
+export declare function startDynamicBoundaries(boundaries: readonly BoundaryRegistration[], context: BoundaryRequestCtx): DynamicBoundaryBatch;
+/**
+ * Resolve only explicitly annotated static boundaries with a request-free build context. Dynamic
+ * and intercepting boundaries remain unresolved. Values are cached by boundary object identity in
+ * the supplied in-memory cache, so a worker instance does not repeat a build-safe computation per
+ * request. A rejected static load becomes that slot's error state; it never fabricates shared data.
+ */
+export declare function resolveStaticBoundaries(boundaries: readonly BoundaryRegistration[], context: StaticCtx, cache?: StaticBoundaryCache): Promise<BoundaryStates>;
+/** Stable mode label for adapter registries and diagnostics. */
+export declare function boundaryModeKey(mode: BoundaryMode): string;
+export {};
+//# sourceMappingURL=boundary.d.ts.map

package/dist/boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary.d.ts","sourceRoot":"","sources":["../src/boundary.ts"],"names":[],"mappings":"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"}

package/dist/boundary.js

@@ -0,0 +1,237 @@
+/**
+ * Framework-neutral async boundaries. A boundary owns one named piece of UI data; the web core owns
+ * lifecycle, concurrency, and isolation while each adapter decides how its `render` result is mounted.
+ * The contract deliberately contains no React/Svelte/Vue/Preact types.
+ */
+export class MemoryStaticBoundaryCache {
+    #values = new WeakMap();
+    get(boundary) {
+        return this.#values.get(boundary);
+    }
+    set(boundary, value) {
+        this.#values.set(boundary, value);
+    }
+}
+/**
+ * Enforce the second half of the static-boundary safety boundary. A build adapter supplies the
+ * transitive module graph and the modules it has classified as request-scoped; a static root that
+ * reaches one fails before any shared shell is emitted. Keeping this check graph-shaped makes it
+ * usable by Bun/Vite without making the neutral web runtime depend on either bundler.
+ */
+export function assertStaticBoundaryImports(roots, edges, requestScopedModules) {
+    const next = new Map();
+    for (const edge of edges) {
+        const children = next.get(edge.from);
+        if (children === undefined)
+            next.set(edge.from, [edge.to]);
+        else
+            children.push(edge.to);
+    }
+    for (const root of roots) {
+        const seen = new Set([root.module]);
+        const queue = [root.module];
+        for (let cursor = 0; cursor < queue.length; cursor++) {
+            const module = queue[cursor];
+            if (module === undefined)
+                continue;
+            if (requestScopedModules.has(module)) {
+                throw new TypeError(`[nifra/web] static boundary "${root.name}" reaches request-scoped module "${module}"`);
+            }
+            for (const child of next.get(module) ?? []) {
+                if (!seen.has(child)) {
+                    seen.add(child);
+                    queue.push(child);
+                }
+            }
+        }
+    }
+}
+const BOUNDARY_NAME = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+const MAX_INTERCEPT_PATH = 2048;
+const modeKey = (mode) => typeof mode === "string" ? mode : `intercept:${mode.intercept}`;
+const assertMode = (mode) => {
+    if (mode === "static" || mode === "dynamic")
+        return;
+    if (typeof mode !== "object" ||
+        mode === null ||
+        typeof mode.intercept !== "string" ||
+        mode.intercept.length === 0 ||
+        mode.intercept.length > MAX_INTERCEPT_PATH ||
+        !mode.intercept.startsWith("/") ||
+        mode.intercept.startsWith("//")) {
+        throw new TypeError("[nifra/web] boundary intercept must be a same-origin path");
+    }
+};
+/** Validate and serialize the neutral boundary manifest. Duplicate names fail closed at startup. */
+export function boundaryDescriptors(boundaries) {
+    const seen = new Set();
+    return boundaries.map((boundary) => {
+        if (!BOUNDARY_NAME.test(boundary.name) || seen.has(boundary.name)) {
+            throw new TypeError(`[nifra/web] invalid or duplicate boundary name "${boundary.name}"`);
+        }
+        assertMode(boundary.mode);
+        seen.add(boundary.name);
+        return {
+            name: boundary.name,
+            mode: boundary.mode,
+            hasLoad: boundary.load !== undefined,
+            ...(boundary.errorId !== undefined ? { errorId: boundary.errorId } : {}),
+        };
+    });
+}
+const scopedContext = (context) => Object.freeze({
+    request: context.request,
+    params: Object.freeze({ ...context.params }),
+    api: context.api,
+    env: context.env,
+    draft: context.draft,
+    search: Object.freeze({ ...context.search }),
+    signal: context.signal,
+});
+/**
+ * Redact a failed load into the client-visible slot. Boundary states are serialized into the document
+ * (`window.__NIFRA_BOUNDARIES__`), so the thrown error's own message never crosses: a driver or fetch
+ * failure carries hosts, credentials, and query text that a page is not allowed to publish. An `Error`
+ * subclass name is withheld for the same reason - it names the internal library. The real error goes to
+ * a generic server-console event, the same split `deferred.ts` uses for a rejected deferred value. The
+ * log deliberately carries only the failure kind: exception messages can contain credentials, query
+ * text, or user data and must not be copied into an operational sink by default.
+ *
+ * A boundary that wants to show the user something specific catches its own failure inside `load` and
+ * returns that as data; the framework never guesses which parts of an exception are publishable.
+ */
+const boundaryError = (error) => {
+    if (error !== undefined) {
+        console.error("[nifra/web] boundary load failed", {
+            kind: error instanceof Error ? "error" : typeof error,
+        });
+    }
+    return { name: "Error", message: "Boundary failed" };
+};
+/**
+ * Resolve all dynamic boundaries concurrently. Each receives a fresh frozen context object; one
+ * failure becomes that boundary's error state and never rejects a sibling or exposes sibling data.
+ * Static/intercepting modes remain `unresolved` until their phase-specific runtime owns them.
+ */
+export async function resolveDynamicBoundaries(boundaries, context) {
+    return startDynamicBoundaries(boundaries, context).complete;
+}
+/**
+ * Start all dynamic boundary loads at once without making the page wait for the slowest sibling.
+ * The initial states contain `status: "pending"`; callers that support deferred values can attach
+ * each `pending.promise` to its own slot. `complete` still provides settled, isolated states to
+ * non-streaming callers, preserving the simple reference API.
+ */
+export function startDynamicBoundaries(boundaries, context) {
+    // Validation only: a bad name, a duplicate, or a malformed intercept path throws here rather than
+    // producing a half-registered batch. It cannot return holes, so no slot below tests for one.
+    boundaryDescriptors(boundaries);
+    const initial = {};
+    const pending = [];
+    for (const boundary of boundaries) {
+        const base = {
+            name: boundary.name,
+            mode: boundary.mode,
+            ...(boundary.errorId !== undefined ? { errorId: boundary.errorId } : {}),
+        };
+        if (boundary.mode !== "dynamic") {
+            initial[boundary.name] = { ...base, status: "unresolved" };
+            continue;
+        }
+        if (boundary.load === undefined) {
+            initial[boundary.name] = { ...base, status: "ready" };
+            continue;
+        }
+        // Promise.resolve().then() converts a synchronous throw into this boundary's rejection, so it
+        // cannot abort siblings or escape before the caller attaches the deferred consumer.
+        const promise = Promise.resolve().then(() => boundary.load?.(scopedContext(context)));
+        pending.push({
+            name: boundary.name,
+            mode: boundary.mode,
+            ...(boundary.errorId !== undefined ? { errorId: boundary.errorId } : {}),
+            promise,
+        });
+        initial[boundary.name] = { ...base, status: "pending" };
+    }
+    const complete = Promise.all(boundaries.map(async (boundary) => {
+        const base = {
+            name: boundary.name,
+            mode: boundary.mode,
+            ...(boundary.errorId !== undefined ? { errorId: boundary.errorId } : {}),
+        };
+        if (boundary.mode !== "dynamic")
+            return { ...base, status: "unresolved" };
+        if (boundary.load === undefined)
+            return { ...base, status: "ready" };
+        const load = pending.find((entry) => entry.name === boundary.name);
+        if (load === undefined)
+            return { ...base, status: "error", error: boundaryError(undefined) };
+        try {
+            const data = await load.promise;
+            return { ...base, status: "ready", ...(data !== undefined ? { data } : {}) };
+        }
+        catch (error) {
+            return { ...base, status: "error", error: boundaryError(error) };
+        }
+    })).then((states) => Object.fromEntries(states.map((state) => [state.name, state])));
+    return { initial, pending, complete };
+}
+/**
+ * Resolve only explicitly annotated static boundaries with a request-free build context. Dynamic
+ * and intercepting boundaries remain unresolved. Values are cached by boundary object identity in
+ * the supplied in-memory cache, so a worker instance does not repeat a build-safe computation per
+ * request. A rejected static load becomes that slot's error state; it never fabricates shared data.
+ */
+export async function resolveStaticBoundaries(boundaries, context, cache = DEFAULT_STATIC_CACHE) {
+    // Validation only - see `startDynamicBoundaries`; the descriptor list has no holes to test for.
+    boundaryDescriptors(boundaries);
+    const states = await Promise.all(boundaries.map(async (boundary) => {
+        if (boundary.mode !== "static") {
+            return {
+                name: boundary.name,
+                mode: boundary.mode,
+                status: "unresolved",
+                ...(boundary.errorId !== undefined ? { errorId: boundary.errorId } : {}),
+            };
+        }
+        if (boundary.load === undefined) {
+            return {
+                name: boundary.name,
+                mode: boundary.mode,
+                status: "ready",
+                ...(boundary.errorId !== undefined ? { errorId: boundary.errorId } : {}),
+            };
+        }
+        let value = cache.get(boundary);
+        if (value === undefined) {
+            value = Promise.resolve().then(() => boundary.load?.(context));
+            cache.set(boundary, value);
+        }
+        try {
+            const data = await value;
+            return {
+                name: boundary.name,
+                mode: boundary.mode,
+                status: "ready",
+                ...(data !== undefined ? { data } : {}),
+                ...(boundary.errorId !== undefined ? { errorId: boundary.errorId } : {}),
+            };
+        }
+        catch (error) {
+            return {
+                name: boundary.name,
+                mode: boundary.mode,
+                status: "error",
+                error: boundaryError(error),
+                ...(boundary.errorId !== undefined ? { errorId: boundary.errorId } : {}),
+            };
+        }
+    }));
+    return Object.fromEntries(states.map((state) => [state.name, state]));
+}
+const DEFAULT_STATIC_CACHE = new MemoryStaticBoundaryCache();
+/** Stable mode label for adapter registries and diagnostics. */
+export function boundaryModeKey(mode) {
+    return modeKey(mode);
+}
+//# sourceMappingURL=boundary.js.map

package/dist/boundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary.js","sourceRoot":"","sources":["../src/boundary.ts"],"names":[],"mappings":"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"}

package/dist/build-plan.d.ts

@@ -0,0 +1,228 @@
+import type { ClientModuleGraph } from "./module-graph.js";
+export interface BuildManifest {
+    /** URL of the client entry module (content-hashed). */
+    readonly entry: string;
+    /** URLs of every emitted asset (entry + chunks) - for serving + preloading. */
+    readonly assets: readonly string[];
+    /** `routeId → [layout chunk URLs…, own chunk URL]` - the chunks a route needs, for `createWebApp`'s
+     * `routePreload` (`<link rel="modulepreload">` the matched route alongside the entry). Each route +
+     * layout is also a build entrypoint, so it gets a named chunk the bootstrap's lazy import dedupes to. */
+    readonly routes: Readonly<Record<string, readonly string[]>>;
+    /** URL paths copied from `publicDir`, sorted. Lets the server entry serve them without scanning a
+     * directory per request, and lets an adapter that needs a file list (CDN upload, platform static
+     * assets) consume one. Omitted when there is no `public/`. */
+    readonly publicFiles?: readonly string[];
+    /** The app's bundled, content-hashed stylesheet(s) - the bootstrap's **aggregate** CSS (every
+     * `import './x.css'` reachable from the app). The complete stylesheet regardless of which file
+     * imported the CSS; the always-safe fallback `createWebApp` links when a route has no per-route entry
+     * in {@link routeStyles}. Omitted when the app imports no CSS. */
+    readonly css?: readonly string[];
+    /** `routeId → [chain CSS URLs]` - only the stylesheets the matched route's layout chain + own file
+     * actually use (Bun emits a per-entrypoint CSS bundle per route/layout, with shared-component CSS
+     * inlined into each consumer). `createWebApp` links these instead of the aggregate, so a page ships
+     * only its own CSS. A route is omitted (→ aggregate fallback) when its `[name]` collides with another
+     * route's basename (ambiguous CSS↔route) or the build emitted orphan shared-chunk CSS - correctness
+     * over minimality. Absent entirely when the app imports no CSS. */
+    readonly routeStyles?: Readonly<Record<string, readonly string[]>>;
+}
+/** The built worker bundle - point your `wrangler.toml`'s `main` at `worker`. */
+export interface ServerBuild {
+    /** Path to the bundled, self-contained worker entry. */
+    readonly worker: string;
+    /** Paths of every emitted output (entry + any code-split chunks) - what to ship to the platform. */
+    readonly outputs: readonly string[];
+}
+/** A deploy target `nifra build --target <t>` can emit. `static` is pure SSG (no server). */
+export declare const BUILD_TARGETS: readonly ["bun", "node", "deno", "cf-pages", "vercel", "static"];
+export type BuildTarget = (typeof BUILD_TARGETS)[number];
+/** A type guard narrowing an arbitrary string to a {@link BuildTarget}. */
+export declare function isBuildTarget(value: string): value is BuildTarget;
+export type ServerBuildTarget = "browser" | "node" | "bun";
+export interface StaticBuildTargetPlan {
+    readonly target: "static";
+    readonly kind: "static";
+    readonly serverTarget: undefined;
+    readonly outputFile: undefined;
+    readonly run: string;
+}
+export interface ServerBuildTargetPlan {
+    readonly target: Exclude<BuildTarget, "static">;
+    readonly kind: "server";
+    readonly serverTarget: ServerBuildTarget;
+    /** The worker's final filename inside the assembled deploy directory. */
+    readonly outputFile: "_worker.js" | "index.js" | "server.js";
+    readonly run: string;
+}
+export type BuildTargetPlan = StaticBuildTargetPlan | ServerBuildTargetPlan;
+/**
+ * Resolve the target-specific deploy shape before any bundling starts. Keeping this decision pure
+ * means Bun and Vite strategies share the same output filename, server target, and hand-off text;
+ * the filesystem emitter only has to execute the plan.
+ */
+export declare function planBuildTarget(target: BuildTarget, outDir: string): BuildTargetPlan;
+/**
+ * A build-tool STRATEGY for {@link buildTargetWith} - the two bundling steps, and nothing else. Everything
+ * around them (server-entry codegen, deploy assembly, prerender, size report) is bundler-agnostic and
+ * lives in `buildTargetWith`, so a second bundler (Vite) is this interface, not a second orchestrator.
+ *
+ * Plugin lists are `readonly unknown[]` because a Bun plugin and a Vite plugin are different types; each
+ * strategy casts to its own. `buildTargetWith` only forwards them.
+ */
+export interface Bundler {
+    /** Build the client bundle → the shared {@link BuildManifest}. */
+    buildClient(input: {
+        readonly routesDir: string;
+        readonly outDir: string;
+        readonly clientModule: string;
+        readonly plugins?: readonly unknown[];
+        readonly conditions?: readonly string[];
+        readonly define?: Readonly<Record<string, string>>;
+        readonly publicDir?: string | false;
+        readonly publicEnvPrefix?: string;
+        /** Project root (Vite needs it; the Bun strategy ignores it). */
+        readonly root?: string;
+    }): Promise<BuildManifest>;
+    /** Build the server worker → the shared {@link ServerBuild}. */
+    buildServer(input: {
+        readonly routesDir: string;
+        readonly serverEntry: string;
+        readonly outDir: string;
+        readonly clientEntry: string;
+        readonly target: "browser" | "node" | "bun";
+        readonly plugins?: readonly unknown[];
+        readonly define?: Readonly<Record<string, string>>;
+        readonly root?: string;
+    }): Promise<ServerBuild>;
+}
+/** One `node:`-builtin-in-the-client finding: the offending builtin, the emitted chunk it landed in,
+ * and the shortest USER-module import chain that pulled it there (entry → … → builtin). */
+export interface NodeBuiltinFinding {
+    readonly builtin: string;
+    readonly chunk: string;
+    /** The shortest import path from a user entry to the builtin, as a list of display labels:
+     * `[entryFile, ...as-written specifiers along the way, builtin]`, e.g.
+     * `["routes/article/[slug].tsx", "../data.ts", "../db/client.ts", "postgres", "node:tls"]`. The
+     * entry is its graph key (the route file); each hop is the import's *as-written* specifier; the tail
+     * is the builtin. Empty only if the builtin module isn't reachable from any traced input (it always
+     * is when flagged). */
+    readonly chain: readonly string[];
+}
+/**
+ * Scan a build's metafile for any `node:` builtin that a USER module pulled into a CLIENT output
+ * chunk, returning a sorted, deduped list of {@link NodeBuiltinFinding}s. Three graph facts combine so
+ * the report is precise AND actionable:
+ *  1. **What the user wrote** - only builtins imported by a NON-`node:` input count, so Bun's own
+ *     polyfill chain (`node:crypto` → `node:buffer`/`node:stream`/…) doesn't bury the real cause.
+ *  2. **Where it landed** - the chunk is read from the per-output `inputs`, so the error names the
+ *     emitted file to look at.
+ *  3. **How it got there** - the shortest import chain from a user entry to the builtin
+ *     (`shortestBuiltinChain`), so the error points straight at the offending `import` line instead of
+ *     leaving the dev to grep the dependency tree (the DX gap this closes).
+ * Graph-based (never the emitted text), so it survives minification and can't be fooled by a string
+ * literal that merely contains `"node:crypto"`. Pure + exported for unit testing. Empty ⇒ clean.
+ */
+export declare function detectNodeBuiltinsInClient(graph: ClientModuleGraph): ReadonlyArray<NodeBuiltinFinding>;
+/** The marker specifier an author imports to opt a module into the client-leak guard. Matched on the
+ * import edge's *as-written* `original` first (the robust signal: it's exactly what the author typed,
+ * before Bun resolves it to `src/server-only.ts` / `dist/server-only.js`). */
+export declare const SERVER_ONLY_MARKER = "@nifrajs/web/server-only";
+/** One `server-only`-module-in-the-client finding: the offending module (the as-written marker-import
+ * chain's tail before the marker), the emitted chunk it landed in, and the shortest USER-module import
+ * chain that pulled it there (entry → … → the server-only module). */
+export interface ServerOnlyFinding {
+    /** The emitted client chunk the server-only module landed in (basename). */
+    readonly chunk: string;
+    /** The shortest import path from a user entry to the server-only module, as display labels:
+     * `[entryFile, ...as-written specifiers…, "<module> (marked server-only)"]`. Mirrors
+     * {@link NodeBuiltinFinding.chain}; the tail names the marked module so the message reads
+     * `routes/x.tsx → ../secrets.ts (marked server-only)`. */
+    readonly chain: readonly string[];
+}
+/**
+ * Scan a build's metafile for any module that opts into the `server-only` marker (a side-effect
+ * `import "@nifrajs/web/server-only"`) yet landed in a CLIENT output chunk, returning a sorted, deduped
+ * list of {@link ServerOnlyFinding}s. Mirrors {@link detectNodeBuiltinsInClient}: it reads the SAME
+ * graph facts - which inputs import the marker (the "marked" modules), which chunk each landed in (the
+ * per-output `inputs`), and the shortest import chain from a user entry to it. The marker module ITSELF
+ * (which imports nothing) is excluded - only the modules that *opt in* are flagged. Pure + exported for
+ * unit testing. Empty ⇒ clean.
+ */
+export declare function detectServerOnlyInClient(graph: ClientModuleGraph): ReadonlyArray<ServerOnlyFinding>;
+/** The build-failing message for `node:` builtins that reached the client bundle. `undefined` ⇒ clean. */
+export declare function formatNodeBuiltinLeak(findings: ReadonlyArray<NodeBuiltinFinding>): string | undefined;
+/** The build-failing message for `server-only`-marked modules that reached the client. `undefined` ⇒ clean. */
+export declare function formatServerOnlyLeak(findings: ReadonlyArray<ServerOnlyFinding>): string | undefined;
+/** One emitted chunk's measured size, in raw bytes + gzipped bytes (over-the-wire weight). */
+export interface ChunkSize {
+    /** The emitted file's basename (e.g. `index-abc123.js`). */
+    readonly name: string;
+    /** Raw byte length of the file. */
+    readonly bytes: number;
+    /** Gzipped byte length (what the client actually downloads, modulo brotli). */
+    readonly gzip: number;
+}
+/** A whole build's size report - every chunk (largest first) + the totals. */
+export interface SizeReport {
+    /** Per-chunk sizes, sorted biggest gzip first (the regression you want to see at the top). */
+    readonly chunks: readonly ChunkSize[];
+    /** Sum of every chunk's raw bytes. */
+    readonly totalBytes: number;
+    /** Sum of every chunk's gzip bytes. */
+    readonly totalGzip: number;
+}
+/**
+ * Aggregate a list of measured chunks into a {@link SizeReport}: sort biggest-gzip-first (ties broken
+ * by raw bytes, then name for stable output) and sum the totals. Pure - the measurement (reading the
+ * file + gzipping it) happens in the orchestrator; this is the deterministic, unit-testable core.
+ */
+export declare function aggregateSizeReport(chunks: readonly ChunkSize[]): SizeReport;
+/** Human-readable byte count: `B`/`KB`/`MB` with one decimal above 1 KB (e.g. `12.3 KB`). Pure. */
+export declare function formatBytes(bytes: number): string;
+/**
+ * Render a {@link SizeReport} as a terse aligned table (biggest first) with a totals row - the text
+ * `nifra build --report` prints. Pure (string in, string out) so the formatting is unit-testable.
+ */
+export declare function renderSizeReport(report: SizeReport): string;
+/** A drift finding between a committed server-manifest and the live `routes/` tree. */
+export interface ManifestDrift {
+    /** Route files present in `routes/` but ABSENT from the committed manifest (the manifest is stale -
+     * the new route won't be served by the worker). */
+    readonly missing: readonly string[];
+    /** Route files the committed manifest imports that no longer exist in `routes/` (a deleted/renamed
+     * route still wired into the worker - a build/runtime break). */
+    readonly extra: readonly string[];
+}
+/**
+ * Extract the route-relative file list a committed server-manifest declares, as the same
+ * `routes/`-relative keys `discoverRoutes` produces (e.g. `docs/index.tsx`). Reads the route map's KEYS,
+ * which carry the file extension and no directory prefix - exactly discovery's shape - so the result is
+ * independent of the specifier prefix the manifest happened to import with. The `@nifrajs/web` import and
+ * the baked `clientEntry`/`styles`/`routeStyles` lines carry no route-map entry and are ignored.
+ *
+ * `_routesPrefix` is accepted for call-site compatibility but no longer needed: the keys are already
+ * prefix-free. Pure - operates on source text.
+ */
+export declare function parseManifestRouteFiles(source: string, _routesPrefix?: string): string[];
+/** The baked `clientEntry` URL in a committed server-manifest, or `undefined` if absent. Pure. */
+export declare function parseManifestClientEntry(source: string): string | undefined;
+/** The baked top-level `styles` array in a committed server-manifest (empty if absent/unparseable). Pure. */
+export declare function parseManifestStyles(source: string): string[];
+/** The baked per-route `routeStyles` map in a committed server-manifest (empty if absent/unparseable). Pure. */
+export declare function parseManifestRouteStyles(source: string): Record<string, string[]>;
+/**
+ * Diff the route files a committed server-manifest imports against the files freshly discovered in
+ * `routes/`. Returns the `missing` (in routes/, not in manifest - stale manifest) and `extra` (in
+ * manifest, gone from routes/ - dangling import) sets. Empty arrays ⇒ in sync. Pure - the caller
+ * supplies both file lists (the committed source is parsed via {@link parseManifestRouteFiles}; the
+ * fresh list comes from `discoverRoutes`). Lists need not be pre-sorted; the result is sorted.
+ */
+export declare function diffManifestRoutes(manifestFiles: readonly string[], discoveredFiles: readonly string[]): ManifestDrift;
+/** True when a drift report is clean (no missing + no extra routes). */
+export declare function isManifestInSync(drift: ManifestDrift): boolean;
+/**
+ * Format a {@link ManifestDrift} as a named, actionable error message, or `undefined` when in sync.
+ * Names the exact missing/extra routes + the one fix (regenerate the manifest by re-running the build).
+ * `manifestPath` is shown for the dev to locate the stale file. Pure.
+ */
+export declare function formatManifestDrift(drift: ManifestDrift, manifestPath?: string): string | undefined;
+//# sourceMappingURL=build-plan.d.ts.map