@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.210

package/dist/cookies/validation.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Cookie name and value validation per RFC 6265 §4.1.1.
+ *
+ * This module is pure — no server or client imports — so it can be loaded
+ * by both `server/request-context.ts` (which guards `getCookies().set()`)
+ * and `client/use-cookie.ts` (which guards `useCookie()`'s setter). The
+ * shared validator gives both sides identical encoding contracts:
+ * **the framework never silently encodes — callers emit `cookie-octet`
+ * bytes or get a developer-facing error.**
+ *
+ * Why this matters: see ONGOING_SECURITY.md H-3 (TIM-868) and
+ * design/29-cookies.md §"Cookie Name and Value Validation".
+ */
+/**
+ * Validate a cookie name against RFC 6265 §4.1.1 / RFC 7230 token rules.
+ * Throws a developer-facing error naming the offending byte and its index.
+ */
+export declare function assertValidCookieName(name: string): void;
+/**
+ * Validate cookie option attributes at runtime to prevent Set-Cookie
+ * header injection through unsanitized option values.
+ *
+ * TypeScript types enforce correct shapes at compile time, but at runtime
+ * (e.g. from untyped libraries or user-controlled config) invalid values
+ * could inject additional Set-Cookie attributes.
+ */
+export declare function assertValidCookieOptions(options: {
+    sameSite?: string;
+    path?: string;
+    domain?: string;
+    maxAge?: number;
+}): void;
+export declare function assertValidCookieValue(name: string, value: string): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/cookies/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/cookies/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA+BH;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAoBxD;AAmDD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,IAAI,CA+BP;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CA2BxE"}

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

@@ -0,0 +1,50 @@
+/**
+ * Dev 404 page — self-contained HTML page for dev-mode route misses.
+ *
+ * When no route matches and the user has no 404.tsx, this page shows:
+ * - The requested path
+ * - All registered routes in the app
+ * - "Did you mean?" suggestions based on string similarity
+ * - Setup instructions for new projects with no routes
+ *
+ * Dev-only: this module is only imported in dev mode. It is never
+ * included in production builds.
+ *
+ * Design doc: 21-dev-server.md, 07-routing.md
+ */
+import type { SegmentNode } from '../routing/types.ts';
+import { type DevErrorHmrOptions } from './dev-page-shell.ts';
+interface RouteInfo {
+    /** URL path pattern (e.g., "/dashboard/[id]") */
+    path: string;
+    /** Whether this is a page route or API route handler */
+    type: 'page' | 'route';
+}
+/**
+ * Collect all routable paths from a route tree (build-time scanner output
+ * or runtime route manifest).
+ *
+ * Wraps the shared `collectLeafRoutes` walker (TIM-848). Includes parallel
+ * slots so the dev 404 page can list slot pages too — they aren't
+ * separately addressable, but they're still useful to know about when
+ * debugging a missing route.
+ */
+export declare function collectRoutes<TFile>(root: SegmentNode<TFile>): RouteInfo[];
+/**
+ * Find routes similar to the requested path.
+ *
+ * Returns up to 3 suggestions, sorted by similarity.
+ * Only includes routes with distance ≤ 40% of the longer string.
+ */
+export declare function findSimilarRoutes(requestedPath: string, routes: RouteInfo[]): RouteInfo[];
+/**
+ * Generate a dev-mode 404 page with route listing and suggestions.
+ *
+ * Returns an HTML string for a self-contained error page. `hmrOptions`
+ * carries the resolved Vite HMR connection options (including the WS token
+ * Vite 8 requires on browser upgrades) so the auto-reload script can
+ * actually connect (TIM-1067, B33).
+ */
+export declare function generateDev404Page(requestedPath: string, routes: RouteInfo[], hmrOptions?: DevErrorHmrOptions): string;
+export {};
+//# sourceMappingURL=404-page.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"404-page.d.ts","sourceRoot":"","sources":["../../src/dev-tools/404-page.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGvD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAIlF,UAAU,SAAS;IACjB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAID;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,GAAG,SAAS,EAAE,CAQ1E;AAmCD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,SAAS,EAAE,CAezF;AAQD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,SAAS,EAAE,EACnB,UAAU,CAAC,EAAE,kBAAkB,GAC9B,MAAM,CAsDR"}

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

@@ -0,0 +1,40 @@
+/**
+ * Browser log forwarding — maps timber's devBrowserLogs config to Vite 8's
+ * server.forwardConsole option.
+ *
+ * Vite 8 ships built-in browser→terminal console forwarding via
+ * server.forwardConsole, which patches console methods in /@vite/client
+ * and prints forwarded output server-side. This replaces timber's custom
+ * client-side interception script and HMR WebSocket transport.
+ *
+ * Client error forwarding (overlay echo, digest filtering, componentStack)
+ * remains in browser-dev.ts — Vite's forwardConsole only logs to terminal
+ * and has no client-side filter hook. See TIM-1152.
+ *
+ * See design/21-dev-server.md §"Browser Log Forwarding"
+ */
+/** Log levels forwarded from the browser. */
+export type BrowserLogLevel = 'error' | 'warn' | 'info';
+/** Configuration value for devBrowserLogs in timber.config.ts. */
+export type DevBrowserLogsConfig = BrowserLogLevel | 'none' | undefined;
+/**
+ * Map timber's devBrowserLogs threshold to Vite 8's server.forwardConsole.
+ *
+ * Vite defaults forwardConsole OFF for non-agent dev; timber enables it
+ * based on the configured threshold (default: 'warn'). The threshold acts
+ * as a minimum severity — 'warn' forwards errors + warnings, 'info'
+ * forwards everything, 'error' forwards only errors, 'none' disables.
+ *
+ * Vite's unhandledErrors is explicitly disabled — timber's own
+ * setupClientErrorForwarding (browser-dev.ts) already catches window
+ * error/unhandledrejection, filters framework control-flow signals
+ * (redirect/deny digests) and page-unload aborts (TIM-838), and
+ * echoes errors to the Vite overlay. Enabling Vite's unhandledErrors
+ * would duplicate terminal output for normal errors and reintroduce
+ * unfiltered noise for framework signals.
+ */
+export declare function resolveForwardConsole(threshold: DevBrowserLogsConfig): boolean | {
+    unhandledErrors: boolean;
+    logLevels: string[];
+};
+//# sourceMappingURL=browser-logs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"browser-logs.d.ts","sourceRoot":"","sources":["../../src/dev-tools/browser-logs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,6CAA6C;AAC7C,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAExD,kEAAkE;AAClE,MAAM,MAAM,oBAAoB,GAAG,eAAe,GAAG,MAAM,GAAG,SAAS,CAAC;AAIxE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,oBAAoB,GAC9B,OAAO,GAAG;IAAE,eAAe,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,CAAA;CAAE,CAU7D"}

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

@@ -0,0 +1,95 @@
+/**
+ * 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;
+}
+/**
+ * Hooks the dev server hands the RSC environment, which cannot read the
+ * Vite server itself (separate module graph). The RSC entry exports
+ * `setDevHooks()`; the dev server calls it after importing the entry.
+ *
+ * Declared here, not in the RSC entry, so the dev-server plugin can name
+ * the type without pulling the RSC entry into its type graph.
+ */
+export interface DevHooks {
+    /** Forwards a pipeline error to the browser error overlay. */
+    onPipelineError?: (error: Error, phase: string) => void;
+    /**
+     * The resolved HMR endpoint for the auto-reload WebSocket on the dev 404
+     * page and the fallback error page (TIM-1067).
+     */
+    hmrOptions?: DevErrorHmrOptions;
+}
+/**
+ * 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;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACvB,8DAA8D;IAC9D,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxD;;;OAGG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACjC;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, classifyErrorPhase, extractComponentStack, parseFirstAppFrame, formatTerminalError, PHASE_LABELS, type ErrorPhase, } 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,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,YAAY,EACZ,KAAK,UAAU,GAChB,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,74 @@
+/**
+ * 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.
+ *
+ * Activated in dev, and in production only when TIMBER_DEBUG is set
+ * (design/13-security.md §"Debug Flag Security Boundary"); otherwise never
+ * loaded.
+ *
+ * Design ref: 17-logging.md §"Dev Logging", 21-dev-server.md §"Dev Logging"
+ */
+import { type SpanProcessor, type 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>;
+}
+/**
+ * Register a context manager and a tracer provider feeding DevSpanProcessor
+ * as the OTEL globals. Called once by initDevTracing().
+ *
+ * The SDK packages are imported statically here, and this module is the one
+ * initDevTracing() loads dynamically. A dynamic import of the CJS-only
+ * @opentelemetry/context-async-hooks bundles into a chunk whose namespace
+ * holds the exports on `default`, and loaders that rewrite such namespaces
+ * (tsx exposes the named exports and drops `default`) hand back no
+ * constructor at all (TIM-1554). A static import calls the bundled CJS
+ * factory directly and has no namespace to rewrite.
+ */
+export declare function registerDevTracing(config: DevLoggerConfig): 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;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,+BAA+B,CAAC;AACvC,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;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,CAyBhE"}

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/{plugins/dev-error-overlay.d.ts → dev-tools/overlay.d.ts}

@@ -1,23 +1,21 @@
 /**
  * Dev error overlay — formats and sends errors to Vite's browser overlay and stderr.
  *
- * Integrates with Vite's built-in error overlay (`server.ssrFixStacktrace` +
- * `server.hot.send`) rather than implementing a custom overlay.
+ * Integrates with Vite's built-in error overlay (`server.hot.send`) rather
+ * than implementing a custom overlay.
  *
- * Design doc: 21-dev-server.md §"Error Overlay"
+ * Stacks are shown as they arrive: Vite's module runner already reports
+ * source positions for the code it runs, and a second mapping pass moves
+ * them (TIM-1555).
+ *
+ * Design doc: 21-dev-server.md §"Error Overlay", §"RSC Source-Mapping"
  */
 import type { ViteDevServer } from 'vite';
 /** The phase of the pipeline where the error occurred. */
 export type ErrorPhase = 'module-transform' | 'proxy' | 'middleware' | 'access' | 'render' | 'handler';
-export type FrameType = 'app' | 'framework' | 'internal';
-/**
- * Classify a 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;
+/** 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.
@@ -38,23 +36,15 @@ export declare function parseFirstAppFrame(stack: string, projectRoot: string):
  * Falls back to 'render' if no specific phase can be determined.
  */
 export declare function classifyErrorPhase(error: Error, projectRoot: string): ErrorPhase;
-/**
- * Format an error for terminal output.
- *
- * - Red for the error message and phase label
- * - Dim for framework-internal frames
- * - Normal for application frames
- * - Separate section for component stack (if present)
- */
-export declare function formatTerminalError(error: Error, phase: ErrorPhase, projectRoot: string): string;
+import { formatTerminalError as _formatTerminalError } from './terminal.ts';
+export declare const formatTerminalError: typeof _formatTerminalError;
 /**
  * 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.
+ * Reads `error` and never writes it: the pipeline may render the same object
+ * on the fallback error page after reporting it here.
  *
  * The dev server remains running — errors are handled, not fatal.
  */
 export declare function sendErrorToOverlay(server: ViteDevServer, error: Error, phase: ErrorPhase, projectRoot: string): void;
-export {};
-//# sourceMappingURL=dev-error-overlay.d.ts.map
+//# 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;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,MAAM,CAAC;AAK1C,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;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,aAAa,EACrB,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,MAAM,GAClB,IAAI,CA6BN"}

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