@timber-js/app 0.2.0-alpha.11 → 0.2.0-alpha.111

package/dist/cookies/validation.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 a cookie value against the RFC 6265 §4.1.1 `cookie-value`
+ * production:
+ *
+ *     cookie-value = *cookie-octet / ( DQUOTE *cookie-octet DQUOTE )
+ *     cookie-octet = %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E
+ *
+ * Both the bare `*cookie-octet` form and the DQUOTE-wrapped form are
+ * valid. The wrapped form is common in upstream `Set-Cookie` headers
+ * (e.g. `sid="abc"; Path=/`) and must be forwardable through
+ * `setFromHeaders` verbatim — stripping or rejecting the surrounding
+ * quotes would corrupt the on-the-wire bytes and break value semantics
+ * for the upstream service.
+ *
+ * Excluded bytes (in either form): CTL, whitespace (CR/LF/TAB/SP),
+ * interior DQUOTE, comma, semicolon, backslash, DEL, and anything
+ * non-ASCII. The smuggling primitive (`;`) is rejected regardless of
+ * wrapping.
+ *
+ * Throws a developer-facing error naming the offending byte and its
+ * index. Callers passing user-controlled data through the default
+ * `set()` path don't need to call this — `set()` auto-encodes via
+ * `encodeURIComponent`, whose output is always valid cookie-octet.
+ * This validator is for the `{ raw: true }` opt-out and for
+ * `setFromHeaders` forwarding.
+ */
+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;AAaD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CA2BxE"}

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

@@ -0,0 +1,46 @@
+/**
+ * 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.js';
+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.
+ */
+export declare function generateDev404Page(requestedPath: string, routes: RouteInfo[]): 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;AAMvD,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;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,CAiFrF"}

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

@@ -0,0 +1,84 @@
+/**
+ * timber-dev-browser-logs — Forwards browser console output to the server terminal.
+ *
+ * Injects a small inline script in dev mode that intercepts browser
+ * `console.error`, `console.warn`, and `console.info`, then forwards
+ * messages to the server via Vite's HMR WebSocket.
+ *
+ * The server-side listener formats and prints the messages with color-coded
+ * prefixes: [browser:error], [browser:warn], [browser:info].
+ *
+ * Dev-only: this plugin only runs during `vite dev`.
+ * No runtime overhead in production.
+ *
+ * See TIM-513 for design context.
+ * See design/18-build-system.md §"Dev Server" for sub-plugin architecture.
+ */
+import type { Plugin } from 'vite';
+import type { PluginContext } from '../plugin-context.js';
+/** 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;
+/**
+ * Payload sent from browser to server via Vite's HMR WebSocket.
+ * Kept small — truncated before sending.
+ */
+export interface BrowserLogPayload {
+    level: BrowserLogLevel;
+    /** Serialized message string. */
+    message: string;
+    /** Error stack trace, if the first argument was an Error. */
+    stack: string | null;
+    /** Source URL and line number, if available. */
+    source: string | null;
+    /** Timestamp in ms (Date.now()) from the browser. */
+    timestamp: number;
+}
+/**
+ * Format a browser log payload for server terminal output.
+ *
+ * Produces color-coded output like:
+ *   [browser:error] Uncaught TypeError: x is not a function
+ *     at App (app.tsx:10:5)
+ *   [browser:warn] Deprecation warning (app/page.tsx:42:12)
+ */
+export declare function formatBrowserLog(payload: BrowserLogPayload): string;
+/**
+ * Check if a log at `level` should be forwarded given the configured threshold.
+ *
+ * The threshold acts as a minimum severity:
+ * - 'error' → only errors
+ * - 'warn' → errors + warnings
+ * - 'info' → errors + warnings + info
+ * - 'none' → nothing
+ */
+export declare function shouldForwardLevel(level: BrowserLogLevel, threshold: BrowserLogLevel | 'none'): boolean;
+/**
+ * Truncate a message to `maxBytes` to avoid flooding the terminal.
+ * Appends a suffix indicating how many bytes were dropped.
+ */
+export declare function truncateMessage(message: string, maxBytes: number): string;
+/**
+ * Generate the inline script injected into the browser in dev mode.
+ *
+ * This script:
+ * 1. Saves references to the original console methods
+ * 2. Wraps `console.error`, `console.warn`, `console.info`
+ * 3. Calls the original first (browser devtools still work)
+ * 4. Serializes and forwards via `import.meta.hot.send()`
+ * 5. Truncates messages to MAX_MESSAGE_BYTES
+ *
+ * The script is minimal and self-contained — no imports, no dependencies.
+ */
+export declare function generateClientScript(threshold: BrowserLogLevel | 'none'): string;
+/**
+ * Create the timber-dev-browser-logs Vite plugin.
+ *
+ * - `configureServer`: Listens for HMR messages and prints them to the terminal
+ * - `transformIndexHtml`: Injects the client-side interception script
+ *
+ * Only active during `vite dev` (apply: 'serve').
+ */
+export declare function timberDevBrowserLogs(ctx: PluginContext): Plugin;
+//# 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;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,MAAM,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D,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;AAExE;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,eAAe,CAAC;IACvB,iCAAiC;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,gDAAgD;IAChD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;CACnB;AA6BD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAsBnE;AAID;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,eAAe,GAAG,MAAM,GAClC,OAAO,CAGT;AAID;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMzE;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,eAAe,GAAG,MAAM,GAAG,MAAM,CAgEhF;AAID;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAgE/D"}

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

@@ -0,0 +1,58 @@
+/**
+ * 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').
+ * It is never included in production builds.
+ *
+ * Design doc: 21-dev-server.md §"Error Overlay"
+ */
+import { type ErrorPhase } from './overlay.js';
+/**
+ * HMR connection options for the dev error page auto-reload WebSocket.
+ * Derived from Vite's resolved server config so the error 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 error page generator
+ * so the auto-reload WebSocket connects to the correct endpoint.
+ */
+export declare function extractHmrOptions(config: {
+    server?: {
+        hmr?: {
+            protocol?: string;
+            host?: string;
+            port?: number;
+            path?: string;
+        } | boolean;
+    };
+    webSocketToken?: string;
+}): DevErrorHmrOptions | undefined;
+/**
+ * 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;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAA6C,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AA+E1F;;;;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;QAAE,GAAG,CAAC,EAAE;YAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG,OAAO,CAAA;KAAE,CAAC;IAChG,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,kBAAkB,GAAG,SAAS,CAkBjC;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,MAAM,EACnB,UAAU,CAAC,EAAE,kBAAkB,GAC9B,MAAM,CAoIR"}

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

@@ -0,0 +1,54 @@
+/**
+ * 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 in timber-dev-server's configureServer() hook (the last
+ * plugin, right before Vite calls server.listen()).
+ *
+ * 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.
+     * Returns the actual bound port (useful when port is 0 for OS assignment).
+     */
+    listen(port: number): 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.
+ *
+ * Usage (inside Vite plugin):
+ * ```ts
+ * // In config() hook — earliest point where port is known.
+ * // Use bindWithBump() to honor the default-3000 + auto-bump policy
+ * // (see ../server/port-resolution.ts and TIM-842).
+ * const holding = createHoldingServer();
+ * await bindWithBump((p) => holding.listen(p), { startPort: 3000, autoBump: true });
+ *
+ * // In last plugin's configureServer() — wrap listen for seamless handoff
+ * const originalListen = server.listen.bind(server);
+ * server.listen = async (...args) => {
+ *   await holding.close();
+ *   return originalListen(...args);
+ * };
+ * ```
+ */
+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;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEtC,kEAAkE;IAClE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AA8ED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CAmDnD"}

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
+ * - warnings: dev-mode footgun warnings
+ * - 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.js';
+export { sendErrorToOverlay, fixErrorStacktrace, classifyErrorPhase, extractComponentStack, parseFirstAppFrame, calculateModuleRunnerOffset, formatRscDebugContext, formatTerminalError, PHASE_LABELS, type ErrorPhase, type RscDebugComponentInfo, } from './overlay.js';
+export { generateDevErrorPage, extractHmrOptions, type DevErrorHmrOptions } from './error-page.js';
+export { generateDev404Page, collectRoutes, findSimilarRoutes } from './404-page.js';
+export { formatTerminalError as formatTerminalErrorDirect } from './terminal.js';
+export { formatSpanTree, formatSpanSummary, formatJson, resolveLogMode, type DevLogMode, type DevLoggerConfig, } from './logger.js';
+export { warnSuspenseWrappingChildren, warnDenyInSuspense, warnRedirectInSuspense, warnRedirectInAccess, warnStaticRequestApi, warnSlowSlotWithoutSuspense, setViteServer, WarningId, type DevWarningConfig, _resetWarnings, _getEmitted, } from './warnings.js';
+export { timberDevBrowserLogs, type BrowserLogLevel, type DevBrowserLogsConfig, } from './browser-logs.js';
+export { timberDevLogs } from './logs.js';
+export { createHoldingServer, type HoldingServer } from './holding-server.js';
+export { instrumentDevFetch, DevSpanProcessor, type DevFetchCleanup } from './instrumentation.js';
+//# 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;;;;;;;;;;;;;;;;;;GAkBG;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,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACnG,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,4BAA4B,EAC5B,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,oBAAoB,EACpB,2BAA2B,EAC3B,aAAa,EACb,SAAS,EACT,KAAK,gBAAgB,EACrB,cAAc,EACd,WAAW,GACZ,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,oBAAoB,EACpB,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"}

package/dist/{server/dev-span-processor.d.ts → dev-tools/instrumentation.d.ts}

@@ -1,3 +1,28 @@
+/**
+ * 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.js';
+export type DevFetchCleanup = () => void;
+/**
+ * Patch globalThis.fetch to wrap every call in an OTEL span.
+ *
+ * Returns a cleanup function that restores the original fetch.
+ * Only call this in dev mode.
+ */
+export declare function instrumentDevFetch(): DevFetchCleanup;
 /**
  * DevSpanProcessor — Custom OTEL SpanProcessor that drives dev log output.
  *
@@ -9,12 +34,7 @@
  * 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.
- *
- * Design doc: 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 './dev-logger.js';
 export declare class DevSpanProcessor implements SpanProcessor {
     private spansByTrace;
     private mode;
@@ -26,4 +46,4 @@ export declare class DevSpanProcessor implements SpanProcessor {
     shutdown(): Promise<void>;
     forceFlush(): Promise<void>;
 }
-//# sourceMappingURL=dev-span-processor.d.ts.map
+//# 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;AAEzC;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CA+CpD;AA4BD;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAiB,YAAW,aAAa;IACpD,OAAO,CAAC,YAAY,CAAqC;IACzD,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,MAAM,CAAkB;gBAEpB,MAAM,EAAE,eAAe;IAKnC,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,GAAG,IAAI;IAI7C,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI;IAqB/B,OAAO,CAAC,MAAM;IAUR,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAIzB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAGlC"}

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;AAEH,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;AAmMD;;;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;AAyGD;;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}

@@ -12,7 +12,7 @@
  * 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 { PluginContext } from '../plugin-context.js';
 /** Log levels that are patched and forwarded. */
 export type ServerLogLevel = 'log' | 'warn' | 'error' | 'debug' | 'info';
 /** Payload sent over Vite's HMR WebSocket. */
@@ -43,4 +43,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,MAAM,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D,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;AAwDD;;;;;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.js';
+/**
+ * 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.js';
+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.js';
+/**
+ * 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;AAGH,OAAO,EAIL,KAAK,UAAU,EAChB,MAAM,cAAc,CAAC;AA4EtB;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAkEhG"}