@timber-js/app 0.2.0-alpha.2 → 0.2.0-alpha.200

package/dist/dev-tools/dev-page-shell.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Shared scaffold for dev-mode HTML pages (dev error page, dev 404 page).
+ *
+ * Both pages are self-contained HTML documents served when the normal
+ * render pipeline can't produce a page. They share:
+ * - The document scaffold (head, container, footer)
+ * - Base CSS (layout, light/dark variables, common components)
+ * - The HMR auto-reload script that watches Vite's WebSocket and reloads
+ *   when the developer fixes the error / adds the missing route
+ *
+ * Dev-only: this module is only imported by dev-mode code paths. It is
+ * never included in production builds.
+ *
+ * Design doc: 21-dev-server.md §"Error Overlay", §"Dev 404 Page"
+ */
+/**
+ * HMR connection options for the dev page auto-reload WebSocket.
+ * Derived from Vite's resolved server config so the page can connect
+ * to the correct HMR endpoint (TIM-789).
+ */
+export interface DevErrorHmrOptions {
+    protocol?: string;
+    host?: string;
+    port?: number;
+    path?: string;
+    token?: string;
+}
+/**
+ * Extract HMR connection options from a Vite resolved config.
+ * Used by the dev server to pass HMR config to the dev page generators
+ * so the auto-reload WebSocket connects to the correct endpoint.
+ */
+export declare function extractHmrOptions(config: {
+    server?: {
+        hmr?: {
+            protocol?: string;
+            host?: string;
+            port?: number;
+            clientPort?: number;
+            path?: string;
+        } | boolean;
+    };
+    webSocketToken?: string;
+}): DevErrorHmrOptions | undefined;
+/**
+ * Build the inline auto-reload script for dev pages.
+ *
+ * The page is static HTML, not a Vite-managed module, so the normal HMR
+ * update flow can't reach it. Instead we connect to Vite's HMR WebSocket
+ * directly and reload on any update event.
+ *
+ * URL construction mirrors Vite's own client.mjs: explicitly configured
+ * values win, and the browser's location fills any gaps at runtime. This
+ * matters because Vite 8 requires a `?token=` on browser WS upgrades in
+ * every config — a config with only a token still needs the host and port
+ * from `location` (TIM-1067).
+ */
+export declare function buildReloadScript(hmrOptions?: DevErrorHmrOptions): string;
+export interface DevPageShellOptions {
+    /** Page title — escaped by the shell. */
+    title: string;
+    /** Page-specific CSS appended after the shared base (badge colors, etc.). */
+    extraCss?: string;
+    /** Inner HTML of the container — must already be escaped by the caller. */
+    bodyHtml: string;
+    /** Hint text shown next to the timber logo in the footer. */
+    footerHint: string;
+    /** Additional inline script placed before the auto-reload script. */
+    extraScript?: string;
+    /** HMR connection options for the auto-reload WebSocket. */
+    hmrOptions?: DevErrorHmrOptions;
+}
+/**
+ * Render a self-contained dev page: scaffold + shared CSS + footer +
+ * HMR auto-reload script.
+ */
+export declare function renderDevPageShell(opts: DevPageShellOptions): string;
+//# sourceMappingURL=dev-page-shell.d.ts.map

package/dist/dev-tools/dev-page-shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-page-shell.d.ts","sourceRoot":"","sources":["../../src/dev-tools/dev-page-shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,MAAM,CAAC,EAAE;QACP,GAAG,CAAC,EACA;YAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,UAAU,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,GACvF,OAAO,CAAC;KACb,CAAC;IACF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,kBAAkB,GAAG,SAAS,CAkBjC;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAuBzE;AAID,MAAM,WAAW,mBAAmB;IAClC,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACjC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CA0BpE"}

package/dist/dev-tools/error-page.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Dev error page — self-contained HTML error page for dev server 500s.
+ *
+ * Generates a styled, self-contained HTML page when the RSC pipeline fails
+ * and the Vite error overlay can't fire (e.g., first page load before HMR
+ * WebSocket connects, RSC entry module crash, early pipeline errors).
+ *
+ * This is NOT a replacement for Vite's error overlay — it's the fallback
+ * for when the overlay's transport (WebSocket) isn't available yet.
+ *
+ * Dev-only: this module is only imported by dev-server.ts (apply: 'serve')
+ * and via dynamic import from fallback-error.ts in dev mode. It is never
+ * included in production builds.
+ *
+ * Design doc: 21-dev-server.md §"Error Overlay"
+ */
+import { type ErrorPhase } from './overlay.ts';
+import { type DevErrorHmrOptions } from './dev-page-shell.ts';
+/**
+ * Generate a self-contained HTML error page for dev server 500 responses.
+ *
+ * The page includes:
+ * - Error message and phase label
+ * - Source code context around the first app frame (if readable)
+ * - Component stack (for React render errors)
+ * - Classified stack trace (app frames highlighted, internals collapsed)
+ * - Copy button for the full error
+ * - Dark/light mode via prefers-color-scheme
+ * - Auto-reconnect script that watches for Vite HMR and reloads
+ */
+export declare function generateDevErrorPage(error: Error, phase: ErrorPhase, projectRoot: string, hmrOptions?: DevErrorHmrOptions): string;
+//# sourceMappingURL=error-page.d.ts.map

package/dist/dev-tools/error-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-page.d.ts","sourceRoot":"","sources":["../../src/dev-tools/error-page.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAA6C,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAG1F,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAiFlF;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,kBAAkB,GAC9B,MAAM,CAsGR"}

package/dist/dev-tools/holding-server.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Dev holding server — serves a loading page while Vite initializes.
+ *
+ * When `timber dev` (or `vite dev`) starts, Vite takes several seconds
+ * to initialize all plugins, scan routes, and boot the RSC environment.
+ * During this window, the port is unbound and browsers get
+ * ERR_CONNECTION_REFUSED.
+ *
+ * This module creates a lightweight HTTP server that binds the port
+ * immediately and serves a branded holding page with auto-refresh.
+ * Once Vite is ready, the holding server is closed and Vite's server
+ * takes over the port.
+ *
+ * The holding server is started in rootSync's config() hook (the
+ * earliest Vite plugin lifecycle point where we know the port) and
+ * closed directly in timber-dev-server's configureServer() hook
+ * (the last plugin, awaited). configureServer runs during
+ * createServer(), well before Vite's port probe and bind, so the
+ * port is free by the time httpServerStart() runs. (TIM-1419)
+ *
+ * Browser requests (Accept: text/html) get the HTML holding page.
+ * API requests (Accept: application/json) get a 503 JSON response.
+ * All responses include Retry-After: 1.
+ *
+ * See design/21-dev-server.md, TIM-665.
+ */
+export interface HoldingServer {
+    /**
+     * Start listening on the given port and host.
+     * The host must match Vite's resolved `server.host` so the probe
+     * faithfully detects conflicts on the same address Vite will bind.
+     * Returns the actual bound port (useful when port is 0 for OS assignment).
+     */
+    listen(port: number, host?: string): Promise<number>;
+    /** Gracefully close the server and stop accepting connections. */
+    close(): Promise<void>;
+}
+/**
+ * Create a holding HTTP server that serves a loading page during startup.
+ *
+ * The config hook attempts one bind on the requested port. If it fails,
+ * startup continues without the holding page; Vite owns port selection.
+ * The last configureServer hook awaits close() before Vite probes/binds.
+ */
+export declare function createHoldingServer(): HoldingServer;
+//# sourceMappingURL=holding-server.d.ts.map

package/dist/dev-tools/holding-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"holding-server.d.ts","sourceRoot":"","sources":["../../src/dev-tools/holding-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAErD,kEAAkE;IAClE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AA8ED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CAyDnD"}

package/dist/dev-tools/hydration-overlay.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Hydration mismatch diff overlay — dev-only.
+ *
+ * Parses React 19's structured diff from hydration error messages and
+ * renders a color-coded + Client / - Server diff in a dismissible overlay.
+ *
+ * See design/21-dev-server.md §"Error Overlay"
+ */
+export declare function isHydrationError(error: unknown): boolean;
+export declare function showHydrationError(error: unknown): void;
+//# sourceMappingURL=hydration-overlay.d.ts.map

package/dist/dev-tools/hydration-overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hydration-overlay.d.ts","sourceRoot":"","sources":["../../src/dev-tools/hydration-overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAaH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKxD;AA6HD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAOvD"}

package/dist/dev-tools/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Dev tools barrel — re-exports all dev-only modules.
+ *
+ * Organized by concern, not by Vite plugin vs server module:
+ * - stack-classifier: frame classification for error display
+ * - overlay: Vite browser error overlay integration
+ * - error-page: self-contained HTML 500 page
+ * - 404-page: self-contained HTML 404 page
+ * - terminal: boxed terminal error output
+ * - logger: structured request tree logger
+ * - browser-logs: forward browser console to server
+ * - logs: forward server console to browser
+ * - holding-server: startup holding server
+ * - instrumentation: fetch tracing + OTEL span processor
+ *
+ * Dev-only: all modules in this subtree are only active during `vite dev`.
+ * They are never included in production builds.
+ */
+export { classifyFrame, classifyStack, type FrameType, type ClassifiedFrame, } from './stack-classifier.ts';
+export { sendErrorToOverlay, fixErrorStacktrace, classifyErrorPhase, extractComponentStack, parseFirstAppFrame, calculateModuleRunnerOffset, formatRscDebugContext, formatTerminalError, PHASE_LABELS, type ErrorPhase, type RscDebugComponentInfo, } from './overlay.ts';
+export { generateDevErrorPage } from './error-page.ts';
+export { extractHmrOptions, renderDevPageShell, buildReloadScript, type DevErrorHmrOptions, } from './dev-page-shell.ts';
+export { generateDev404Page, collectRoutes, findSimilarRoutes } from './404-page.ts';
+export { formatTerminalError as formatTerminalErrorDirect } from './terminal.ts';
+export { formatSpanTree, formatSpanSummary, formatJson, resolveLogMode, type DevLogMode, type DevLoggerConfig, } from './logger.ts';
+export { resolveForwardConsole, type BrowserLogLevel, type DevBrowserLogsConfig, } from './browser-logs.ts';
+export { timberDevLogs } from './logs.ts';
+export { createHoldingServer, type HoldingServer } from './holding-server.ts';
+export { instrumentDevFetch, DevSpanProcessor, type DevFetchCleanup } from './instrumentation.ts';
+export { isHydrationError, showHydrationError } from './hydration-overlay.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/dev-tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dev-tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EACL,aAAa,EACb,aAAa,EACb,KAAK,SAAS,EACd,KAAK,eAAe,GACrB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,2BAA2B,EAC3B,qBAAqB,EACrB,mBAAmB,EACnB,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,qBAAqB,GAC3B,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,KAAK,kBAAkB,GACxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAGrF,OAAO,EAAE,mBAAmB,IAAI,yBAAyB,EAAE,MAAM,eAAe,CAAC;AAGjF,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,KAAK,UAAU,EACf,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,oBAAoB,GAC1B,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG1C,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAG9E,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAGlG,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/dev-tools/instrumentation.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Dev-mode OTEL instrumentation — fetch tracing and span processing.
+ *
+ * Combines two concerns:
+ * 1. Fetch instrumentation: patches globalThis.fetch to create OTEL spans
+ *    for every fetch call, giving visibility into async data fetching in
+ *    the dev request log tree.
+ * 2. Span processing: collects completed spans per-request and drives
+ *    dev log output when the root span ends.
+ *
+ * Only activated in dev mode — zero overhead in production.
+ *
+ * Design ref: 17-logging.md §"Dev Logging", 21-dev-server.md §"Dev Logging"
+ */
+import type { SpanProcessor, ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import type { Span, Context } from '@opentelemetry/api';
+import { type DevLoggerConfig } from './logger.ts';
+export type DevFetchCleanup = () => void;
+/**
+ * Patch globalThis.fetch to wrap every call in an OTEL span.
+ *
+ * Returns a cleanup function that restores the original fetch.
+ * Idempotent: a repeated call restores the previous patch before
+ * re-patching, so wrappers never stack. Only call this in dev mode.
+ */
+export declare function instrumentDevFetch(): DevFetchCleanup;
+/**
+ * DevSpanProcessor — Custom OTEL SpanProcessor that drives dev log output.
+ *
+ * Collects completed spans per-request (correlated by trace ID). When the
+ * root span (http.server.request) ends, all child spans are already collected
+ * (child spans end before parent in OTEL). The processor formats the span
+ * tree and writes it to stderr.
+ *
+ * This replaces the old DevLogEmitter/DevLogEvents system. OTEL spans are
+ * now the single source of truth for dev logging — no more parallel event
+ * systems that can drift.
+ */
+export declare class DevSpanProcessor implements SpanProcessor {
+    /**
+     * Max traces retained while waiting for their root span. Traces are only
+     * deleted when an `http.server.request` root ends — orphan fetches (no
+     * active request) and spans ending after their root would otherwise
+     * accumulate for the dev-server lifetime. Beyond the cap, the
+     * oldest-inserted trace is evicted (Map preserves insertion order).
+     * See TIM-1067, B49.
+     */
+    private static readonly MAX_PENDING_TRACES;
+    private spansByTrace;
+    private mode;
+    private config;
+    constructor(config: DevLoggerConfig);
+    onStart(_span: Span, _context: Context): void;
+    onEnd(span: ReadableSpan): void;
+    private format;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}
+//# sourceMappingURL=instrumentation.d.ts.map

package/dist/dev-tools/instrumentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation.d.ts","sourceRoot":"","sources":["../../src/dev-tools/instrumentation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AACjF,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAKL,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAIrB,MAAM,MAAM,eAAe,GAAG,MAAM,IAAI,CAAC;AAazC;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAwDpD;AA4BD;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAiB,YAAW,aAAa;IACpD;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAO;IAEjD,OAAO,CAAC,YAAY,CAAqC;IACzD,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,MAAM,CAAkB;IAEhC,YAAY,MAAM,EAAE,eAAe,EAGlC;IAED,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI,CAE5C;IAED,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAyB9B;IAED,OAAO,CAAC,MAAM;IAUR,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAE9B;IAEK,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAEhC;CACF"}

package/dist/{server/dev-logger.d.ts → dev-tools/logger.d.ts}

@@ -41,4 +41,4 @@ export declare function formatSpanSummary(spans: ReadableSpan[], _config?: DevLo
  * to jq or feeding into external trace analysis tools.
  */
 export declare function formatJson(spans: ReadableSpan[]): string;
-//# sourceMappingURL=dev-logger.d.ts.map
+//# sourceMappingURL=logger.d.ts.map

package/dist/dev-tools/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/dev-tools/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAIlE,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3E,MAAM,WAAW,eAAe;IAC9B,qCAAqC;IACrC,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA8LD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,UAAU,CAMnE;AAID;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,EAAE,EAAE,MAAM,CAAC,EAAE,eAAe,GAAG,MAAM,CAgDtF;AAwGD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,EAAE,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,MAAM,CAc1F;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,MAAM,CA6BxD"}

package/dist/{plugins/dev-logs.d.ts → dev-tools/logs.d.ts}

@@ -11,8 +11,22 @@
  *
  * Design docs: 18-build-system.md §"Dev Server", 02-rendering-pipeline.md
  */
-import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
+import type { Plugin, Logger } from 'vite';
+import type { PluginContext } from '../plugin-context.ts';
+/**
+ * Snapshot of the original console methods, captured at module load time
+ * (before any patching). Used as Vite's `customLogger` console so that
+ * forwardConsole output bypasses our patch entirely — eliminating the
+ * server→browser→server forwarding loop without string matching.
+ */
+export declare const originalConsole: Pick<Console, 'log' | 'warn' | 'error' | 'debug' | 'info'>;
+/**
+ * Wrap a Vite Logger so its output methods route through `originalConsole`
+ * instead of the global (potentially patched) console. This prevents the
+ * server→browser→server forwarding loop even when the user supplies their
+ * own `customLogger` that internally calls console methods.
+ */
+export declare function wrapLoggerWithOriginalConsole(logger: Logger): Logger;
 /** Log levels that are patched and forwarded. */
 export type ServerLogLevel = 'log' | 'warn' | 'error' | 'debug' | 'info';
 /** Payload sent over Vite's HMR WebSocket. */
@@ -43,4 +57,4 @@ export declare function isFrameworkInternalCaller(): boolean;
  * when the server closes. Only active during `vite dev`.
  */
 export declare function timberDevLogs(_ctx: PluginContext): Plugin;
-//# sourceMappingURL=dev-logs.d.ts.map
+//# sourceMappingURL=logs.d.ts.map

package/dist/dev-tools/logs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logs.d.ts","sourceRoot":"","sources":["../../src/dev-tools/logs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,EAAE,MAAM,MAAM,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAMtF,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAqDpE;AAID,iDAAiD;AACjD,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;AAIzE,8CAA8C;AAC9C,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,cAAc,CAAC;IACtB,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;CACnB;AA2ID;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,IAAI,OAAO,CAsBnD;AAuED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAiBzD"}

package/dist/dev-tools/overlay.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Dev error overlay — formats and sends errors to Vite's browser overlay and stderr.
+ *
+ * Integrates with Vite's built-in error overlay (`server.hot.send`) rather
+ * than implementing a custom overlay.
+ *
+ * Stack trace source-mapping uses the correct Vite environment module graph:
+ * RSC errors use `server.environments.rsc.moduleGraph`, SSR/other errors use
+ * `server.environments.ssr.moduleGraph`. `server.ssrFixStacktrace()` is NOT
+ * used because it hardcodes the SSR module graph, which doesn't contain
+ * source maps for RSC modules (separate Vite environment with its own
+ * module graph). This caused RSC errors to show transpiled line numbers
+ * instead of original source positions.
+ *
+ * Design doc: 21-dev-server.md §"Error Overlay"
+ */
+import type { ViteDevServer } from 'vite';
+/** The phase of the pipeline where the error occurred. */
+export type ErrorPhase = 'module-transform' | 'proxy' | 'middleware' | 'access' | 'render' | 'handler';
+/** Labels for terminal output. */
+export declare const PHASE_LABELS: Record<ErrorPhase, string>;
+export { classifyFrame, classifyStack, type FrameType, type ClassifiedFrame, } from './stack-classifier.ts';
+/**
+ * Extract the React component stack from an error, if present.
+ * React attaches this as `componentStack` during renderToReadableStream errors.
+ */
+export declare function extractComponentStack(error: unknown): string | null;
+interface SourceLocation {
+    file: string;
+    line: number;
+    column: number;
+}
+/**
+ * Parse the first application frame from a stack trace.
+ * Returns file/line/column for the overlay's `loc` field.
+ */
+export declare function parseFirstAppFrame(stack: string, projectRoot: string): SourceLocation | null;
+/**
+ * Classify the error phase by inspecting the error's stack trace.
+ * Falls back to 'render' if no specific phase can be determined.
+ */
+export declare function classifyErrorPhase(error: Error, projectRoot: string): ErrorPhase;
+import { formatTerminalError as _formatTerminalError } from './terminal.ts';
+export declare const formatTerminalError: typeof _formatTerminalError;
+/**
+ * Component info extracted from the RSC debug channel.
+ * Contains only names, environments, and stack frames — never source code.
+ */
+export interface RscDebugComponentInfo {
+    name: string;
+    env: string | null;
+    stack: unknown[] | null;
+}
+/**
+ * Format RSC debug component info into a readable string for the overlay.
+ *
+ * Renders the server component tree that was active when an error occurred,
+ * including component names and source locations from stack frames. This
+ * gives developers visibility into which server components were rendering
+ * without exposing source code.
+ *
+ * Returns an empty string if no components are provided.
+ */
+export declare function formatRscDebugContext(components: RscDebugComponentInfo[]): string;
+export declare function calculateModuleRunnerOffset(): number;
+/**
+ * Source-map an error's stack trace using the Vite dev server's module graph.
+ *
+ * Exported so that the fallback error renderer (fallback-error.ts) can
+ * source-map errors before rendering the dev error page. Without this,
+ * the dev error page shows transpiled positions (e.g. page.tsx:1:1 instead
+ * of page.tsx:4:9).
+ *
+ * See TIM-811.
+ */
+export declare function fixErrorStacktrace(server: ViteDevServer, error: Error, phase?: ErrorPhase): void;
+/**
+ * Send an error to Vite's browser overlay and log it to stderr.
+ *
+ * Uses `server.ssrFixStacktrace()` to map stack traces back to source,
+ * then sends the error via `server.hot.send()` for the browser overlay.
+ *
+ * When `rscDebugComponents` is provided (dev mode only), the server
+ * component tree context is appended to the error message. This helps
+ * developers identify which server component caused the error without
+ * exposing source code.
+ *
+ * The dev server remains running — errors are handled, not fatal.
+ */
+export declare function sendErrorToOverlay(server: ViteDevServer, error: Error, phase: ErrorPhase, projectRoot: string, rscDebugComponents?: RscDebugComponentInfo[]): void;
+//# sourceMappingURL=overlay.d.ts.map

package/dist/dev-tools/overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../../src/dev-tools/overlay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAkB,MAAM,MAAM,CAAC;AAqC1D,0DAA0D;AAC1D,MAAM,MAAM,UAAU,GAClB,kBAAkB,GAClB,OAAO,GACP,YAAY,GACZ,QAAQ,GACR,QAAQ,GACR,SAAS,CAAC;AAEd,kCAAkC;AAClC,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAOnD,CAAC;AAIF,OAAO,EACL,aAAa,EACb,aAAa,EACb,KAAK,SAAS,EACd,KAAK,eAAe,GACrB,MAAM,uBAAuB,CAAC;AAI/B;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAUnE;AAID,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAqB5F;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,GAAG,UAAU,CAehF;AAOD,OAAO,EAAE,mBAAmB,IAAI,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC5E,eAAO,MAAM,mBAAmB,6BAAuB,CAAC;AAIxD;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,qBAAqB,EAAE,GAAG,MAAM,CAiCjF;AAkBD,wBAAgB,2BAA2B,IAAI,MAAM,CA6BpD;AAuHD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,IAAI,CAMhG;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,MAAM,EACnB,kBAAkB,CAAC,EAAE,qBAAqB,EAAE,GAC3C,IAAI,CA0CN"}

package/dist/dev-tools/stack-classifier.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Stack trace frame classifier — categorizes stack frames by origin.
+ *
+ * Provides `classifyFrame` (single frame) and `classifyStack` (full stack
+ * string) as the shared primitives used by the error page, terminal
+ * formatter, and overlay.
+ *
+ * Dev-only: this module is only imported by other dev-tools modules.
+ */
+export type FrameType = 'app' | 'framework' | 'internal';
+export interface ClassifiedFrame {
+    raw: string;
+    type: FrameType;
+    file?: string;
+    line?: number;
+    col?: number;
+}
+/**
+ * Classify a single stack frame line by origin.
+ *
+ * - 'app': user application code (in project root, not node_modules)
+ * - 'framework': timber-app internal code
+ * - 'internal': node_modules, Node.js internals
+ */
+export declare function classifyFrame(frameLine: string, projectRoot: string): FrameType;
+/**
+ * Classify all frames in a full stack trace string.
+ *
+ * Parses the stack, skips the first line (error message), filters to
+ * lines starting with "at ", and returns classified frames with optional
+ * file/line/col metadata.
+ */
+export declare function classifyStack(stack: string, projectRoot: string): ClassifiedFrame[];
+//# sourceMappingURL=stack-classifier.d.ts.map

package/dist/dev-tools/stack-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-classifier.d.ts","sourceRoot":"","sources":["../../src/dev-tools/stack-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,WAAW,GAAG,UAAU,CAAC;AAEzD,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAmBD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,SAAS,CAS/E;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,eAAe,EAAE,CAUnF"}

package/dist/dev-tools/terminal.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Terminal error formatting — boxed, color-coded error output for dev mode.
+ *
+ * Produces a visually scannable error block with:
+ * - Unicode box-drawing border around the error
+ * - Phase badge and error message
+ * - First app frame highlighted as the primary action item
+ * - OSC 8 clickable file:line links (VSCode terminal, iTerm2, etc.)
+ * - Internal/framework frames collapsed with a count
+ * - Component stack (for React render errors)
+ *
+ * Dev-only: this module is only imported by dev-error-overlay.ts.
+ *
+ * Design doc: 21-dev-server.md §"Error Overlay"
+ */
+import { type ErrorPhase } from './overlay.ts';
+/**
+ * Format an error for terminal output with a boxed layout.
+ *
+ * The output is designed to be scannable at a glance:
+ * 1. Red box with phase badge and error message
+ * 2. First app frame as a clickable link (the primary action item)
+ * 3. App frames listed normally
+ * 4. Internal/framework frames collapsed with count
+ * 5. Component stack (if present)
+ */
+export declare function formatTerminalError(error: Error, phase: ErrorPhase, projectRoot: string): string;
+//# sourceMappingURL=terminal.d.ts.map

package/dist/dev-tools/terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../../src/dev-tools/terminal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAIL,KAAK,UAAU,EAChB,MAAM,cAAc,CAAC;AAyEtB;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAkEhG"}

package/dist/fonts/ast-walk.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Generic AST node types and recursive walkers for font static analysis.
+ *
+ * `ast.ts` owns parsing, config extraction, and call-site discovery; this
+ * module owns the recursive walks that police where font bindings may be
+ * used (dynamic configs, nested scopes, unconsumed references). Split out
+ * to keep `ast.ts` under the 500-code-line limit (design/18-build-system.md).
+ *
+ * Design doc: 24-fonts.md §"Step 1: Static Analysis"
+ */
+export interface AstNode {
+    type: string;
+    [key: string]: unknown;
+}
+export interface IdentifierNode extends AstNode {
+    type: 'Identifier';
+    name: string;
+}
+export interface PositionedNode extends AstNode {
+    start: number;
+    end: number;
+}
+/** A flagged reference/usage for build-error reporting. */
+export interface FlaggedUsage {
+    name: string;
+    line: number;
+    column: number;
+}
+/** Convert a 0-based byte offset into a 1-based line and 0-based column. */
+export declare function offsetToLineColumn(source: string, offset: number): {
+    line: number;
+    column: number;
+};
+/**
+ * Invoke `visit` on every direct child AST node of `node` (array elements
+ * and object-valued properties with a `type` field).
+ */
+export declare function walkChildNodes(node: AstNode, visit: (child: AstNode) => void): void;
+/**
+ * Recursively walk the AST looking for CallExpression nodes where
+ * the callee is one of the imported font names and the first argument
+ * is not an ObjectExpression (i.e. it's dynamic).
+ */
+export declare function walkForDynamicCalls(node: AstNode, names: ReadonlySet<string>, source: string): string | null;
+/**
+ * Recursively walk an AST node looking for font CallExpressions in nested
+ * scopes (function bodies, if-blocks, loops, etc.). Font calls must be
+ * module-level; nested calls are collected as errors.
+ *
+ * `isNested` tracks whether we've descended past the top-level statement.
+ * Top-level VariableDeclarations and ExpressionStatements are already
+ * handled by the main loop in `findFontCallSites`, so we only flag calls
+ * found deeper.
+ */
+export declare function walkForNestedFontCalls(node: AstNode, bindingNames: ReadonlyMap<string, unknown>, source: string, out: FlaggedUsage[], isNested: boolean): void;
+/**
+ * Recursively walk an AST node looking for references to font bindings
+ * that were not consumed by a recognized call site.
+ *
+ * Skips:
+ * - recognized CallExpressions (the transform rewrites them wholesale)
+ * - TS type-position nodes (erased at runtime)
+ * - non-computed member properties (`obj.Inter` doesn't reference the binding)
+ * - non-computed object keys (`{ Inter: 1 }` doesn't reference the binding)
+ * - export aliases (`export { inter as Inter }` — only `local` is a reference)
+ */
+export declare function walkForUnconsumedReferences(node: AstNode, bindingNames: ReadonlyMap<string, unknown>, consumedCallStarts: ReadonlySet<number>, source: string, out: FlaggedUsage[]): void;
+//# sourceMappingURL=ast-walk.d.ts.map

package/dist/fonts/ast-walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast-walk.d.ts","sourceRoot":"","sources":["../../src/fonts/ast-walk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,cAAe,SAAQ,OAAO;IAC7C,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAe,SAAQ,OAAO;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAUlC;AAID;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAcnF;AAID;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,EAC1B,MAAM,EAAE,MAAM,GACb,MAAM,GAAG,IAAI,CAuBf;AAwBD;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,OAAO,EACb,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1C,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,YAAY,EAAE,EACnB,QAAQ,EAAE,OAAO,GAChB,IAAI,CAoBN;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,OAAO,EACb,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1C,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAC,EACvC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,YAAY,EAAE,GAClB,IAAI,CA8CN"}