@timber-js/app 0.1.0

package/bin/timber.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+// Thin CLI wrapper — delegates to the compiled CLI entry.
+// This file is the bin entry point and never moves, regardless of build output changes.
+// See design/28-npm-packaging.md §"CLI Binary".
+import '../dist/cli.js';

package/dist/_chunks/error-boundary-dj-WO5uq.js

@@ -0,0 +1,121 @@
+import { Component, createElement } from "react";
+//#region src/client/error-boundary.tsx
+/**
+* Framework-injected React error boundary.
+*
+* Catches errors thrown by children and renders a fallback component
+* with the appropriate props based on error type:
+*   - DenySignal (4xx) → { status, dangerouslyPassData }
+*   - RenderError (5xx) → { error, digest, reset }
+*   - Unhandled error → { error, digest: null, reset }
+*
+* The `status` prop controls which errors this boundary catches:
+*   - Specific code (e.g. 403) → only that status
+*   - Category (400) → any 4xx
+*   - Category (500) → any 5xx
+*   - Omitted → catches everything (error.tsx behavior)
+*
+* See design/10-error-handling.md §"Status-Code Files"
+*/
+var _isUnloading = false;
+if (typeof window !== "undefined") {
+	window.addEventListener("beforeunload", () => {
+		_isUnloading = true;
+	});
+	window.addEventListener("pagehide", () => {
+		_isUnloading = true;
+	});
+}
+var TimberErrorBoundary = class extends Component {
+	constructor(props) {
+		super(props);
+		this.state = {
+			hasError: false,
+			error: null
+		};
+	}
+	static getDerivedStateFromError(error) {
+		if (_isUnloading) return {
+			hasError: false,
+			error: null
+		};
+		return {
+			hasError: true,
+			error
+		};
+	}
+	componentDidUpdate(prevProps) {
+		if (this.state.hasError && prevProps.children !== this.props.children) this.setState({
+			hasError: false,
+			error: null
+		});
+	}
+	/** Reset the error state so children re-render. */
+	reset = () => {
+		this.setState({
+			hasError: false,
+			error: null
+		});
+	};
+	render() {
+		if (!this.state.hasError || !this.state.error) return this.props.children;
+		const error = this.state.error;
+		const parsed = parseDigest(error);
+		if (parsed?.type === "redirect") throw error;
+		if (this.props.status != null) {
+			const errorStatus = getErrorStatus(parsed, error);
+			if (errorStatus == null || !statusMatches(this.props.status, errorStatus)) throw error;
+		}
+		if (parsed?.type === "deny") return createElement(this.props.fallbackComponent, {
+			status: parsed.status,
+			dangerouslyPassData: parsed.data
+		});
+		const digest = parsed?.type === "render-error" ? {
+			code: parsed.code,
+			data: parsed.data
+		} : null;
+		return createElement(this.props.fallbackComponent, {
+			error,
+			digest,
+			reset: this.reset
+		});
+	}
+};
+/**
+* Parse the structured digest from the error.
+* React sets `error.digest` from the string returned by RSC's onError.
+*/
+function parseDigest(error) {
+	const raw = error.digest;
+	if (typeof raw !== "string") return null;
+	try {
+		const parsed = JSON.parse(raw);
+		if (parsed && typeof parsed === "object" && typeof parsed.type === "string") return parsed;
+	} catch {}
+	return null;
+}
+/**
+* Extract the HTTP status code from a parsed digest or error message.
+* Falls back to message pattern matching for errors without a digest.
+*/
+function getErrorStatus(parsed, error) {
+	if (parsed?.type === "deny") return parsed.status;
+	if (parsed?.type === "render-error") return parsed.status;
+	if (parsed?.type === "redirect") return parsed.status;
+	const match = error.message.match(/^Access denied with status (\d+)$/);
+	if (match) return parseInt(match[1], 10);
+	return 500;
+}
+/**
+* Check whether an error's status matches the boundary's status filter.
+* Category markers (400, 500) match any status in that range.
+*/
+function statusMatches(boundaryStatus, errorStatus) {
+	if (boundaryStatus === 400) return errorStatus >= 400 && errorStatus <= 499;
+	if (boundaryStatus === 500) return errorStatus >= 500 && errorStatus <= 599;
+	return boundaryStatus === errorStatus;
+}
+//#endregion
+export { TimberErrorBoundary as t };
+
+//# sourceMappingURL=error-boundary-dj-WO5uq.js.map

package/dist/_chunks/error-boundary-dj-WO5uq.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-boundary-dj-WO5uq.js","names":[],"sources":["../../src/client/error-boundary.tsx"],"sourcesContent":["'use client';\n\n/**\n * Framework-injected React error boundary.\n *\n * Catches errors thrown by children and renders a fallback component\n * with the appropriate props based on error type:\n *   - DenySignal (4xx) → { status, dangerouslyPassData }\n *   - RenderError (5xx) → { error, digest, reset }\n *   - Unhandled error → { error, digest: null, reset }\n *\n * The `status` prop controls which errors this boundary catches:\n *   - Specific code (e.g. 403) → only that status\n *   - Category (400) → any 4xx\n *   - Category (500) → any 5xx\n *   - Omitted → catches everything (error.tsx behavior)\n *\n * See design/10-error-handling.md §\"Status-Code Files\"\n */\n\nimport { Component, createElement, type ReactNode } from 'react';\n\n// ─── Page Unload Detection ───────────────────────────────────────────────────\n// Track whether the page is being unloaded (user refreshed or navigated away).\n// When this is true, error boundaries suppress activation — the error is from\n// the aborted connection, not an application error.\nlet _isUnloading = false;\nif (typeof window !== 'undefined') {\n  window.addEventListener('beforeunload', () => {\n    _isUnloading = true;\n  });\n  window.addEventListener('pagehide', () => {\n    _isUnloading = true;\n  });\n}\n\n// ─── Digest Types ────────────────────────────────────────────────────────────\n\n/** Structured digest returned by RSC onError for DenySignal. */\ninterface DenyDigest {\n  type: 'deny';\n  status: number;\n  data: unknown;\n}\n\n/** Structured digest returned by RSC onError for RenderError. */\ninterface RenderErrorDigest {\n  type: 'render-error';\n  code: string;\n  data: unknown;\n  status: number;\n}\n\n/** Structured digest returned by RSC onError for RedirectSignal. */\ninterface RedirectDigest {\n  type: 'redirect';\n  location: string;\n  status: number;\n}\n\ntype ParsedDigest = DenyDigest | RenderErrorDigest | RedirectDigest;\n\n// ─── Props & State ───────────────────────────────────────────────────────────\n\nexport interface TimberErrorBoundaryProps {\n  /** The component to render when an error is caught. */\n  fallbackComponent: (...args: unknown[]) => ReactNode;\n  /**\n   * Status code filter. If set, only catches errors matching this status.\n   * 400 = any 4xx, 500 = any 5xx, specific number = exact match.\n   */\n  status?: number;\n  children: ReactNode;\n}\n\ninterface TimberErrorBoundaryState {\n  hasError: boolean;\n  error: Error | null;\n}\n\n// ─── Component ───────────────────────────────────────────────────────────────\n\nexport class TimberErrorBoundary extends Component<\n  TimberErrorBoundaryProps,\n  TimberErrorBoundaryState\n> {\n  constructor(props: TimberErrorBoundaryProps) {\n    super(props);\n    this.state = { hasError: false, error: null };\n  }\n\n  static getDerivedStateFromError(error: Error): TimberErrorBoundaryState {\n    // Suppress error boundaries during page unload (refresh/navigate away).\n    // The aborted connection causes React's streaming hydration to error,\n    // but the page is about to be replaced — showing an error boundary\n    // would be a jarring flash for the user.\n    if (_isUnloading) {\n      return { hasError: false, error: null };\n    }\n    return { hasError: true, error };\n  }\n\n  componentDidUpdate(prevProps: TimberErrorBoundaryProps): void {\n    // Reset error state when children change (e.g. client-side navigation).\n    // Without this, navigating from one error page to another keeps the\n    // stale error — getDerivedStateFromError doesn't re-fire for new children.\n    if (this.state.hasError && prevProps.children !== this.props.children) {\n      this.setState({ hasError: false, error: null });\n    }\n  }\n\n  /** Reset the error state so children re-render. */\n  private reset = () => {\n    this.setState({ hasError: false, error: null });\n  };\n\n  render(): ReactNode {\n    if (!this.state.hasError || !this.state.error) {\n      return this.props.children;\n    }\n\n    const error = this.state.error;\n    const parsed = parseDigest(error);\n\n    // RedirectSignal errors must propagate through all error boundaries\n    // so the SSR shell fails and the pipeline catch block can produce a\n    // proper HTTP redirect response. See design/04-authorization.md.\n    if (parsed?.type === 'redirect') {\n      throw error;\n    }\n\n    // If this boundary has a status filter, check whether the error matches.\n    // Non-matching errors re-throw so an outer boundary can catch them.\n    if (this.props.status != null) {\n      const errorStatus = getErrorStatus(parsed, error);\n      if (errorStatus == null || !statusMatches(this.props.status, errorStatus)) {\n        // Re-throw: this boundary doesn't handle this error.\n        throw error;\n      }\n    }\n\n    // Render the fallback component with the right props shape.\n    if (parsed?.type === 'deny') {\n      return createElement(this.props.fallbackComponent as never, {\n        status: parsed.status,\n        dangerouslyPassData: parsed.data,\n      });\n    }\n\n    // 5xx / RenderError / unhandled error\n    const digest =\n      parsed?.type === 'render-error' ? { code: parsed.code, data: parsed.data } : null;\n\n    return createElement(this.props.fallbackComponent as never, {\n      error,\n      digest,\n      reset: this.reset,\n    });\n  }\n}\n\n// ─── Helpers ─────────────────────────────────────────────────────────────────\n\n/**\n * Parse the structured digest from the error.\n * React sets `error.digest` from the string returned by RSC's onError.\n */\nfunction parseDigest(error: Error): ParsedDigest | null {\n  const raw = (error as { digest?: string }).digest;\n  if (typeof raw !== 'string') return null;\n  try {\n    const parsed = JSON.parse(raw);\n    if (parsed && typeof parsed === 'object' && typeof parsed.type === 'string') {\n      return parsed as ParsedDigest;\n    }\n  } catch {\n    // Not JSON — legacy or unknown digest format\n  }\n  return null;\n}\n\n/**\n * Extract the HTTP status code from a parsed digest or error message.\n * Falls back to message pattern matching for errors without a digest.\n */\nfunction getErrorStatus(parsed: ParsedDigest | null, error: Error): number | null {\n  if (parsed?.type === 'deny') return parsed.status;\n  if (parsed?.type === 'render-error') return parsed.status;\n  if (parsed?.type === 'redirect') return parsed.status;\n\n  // Fallback: parse DenySignal message pattern for errors that lost their digest\n  const match = error.message.match(/^Access denied with status (\\d+)$/);\n  if (match) return parseInt(match[1], 10);\n\n  // Unhandled errors are implicitly 500\n  return 500;\n}\n\n/**\n * Check whether an error's status matches the boundary's status filter.\n * Category markers (400, 500) match any status in that range.\n */\nfunction statusMatches(boundaryStatus: number, errorStatus: number): boolean {\n  // Category catch-all: 400 matches any 4xx, 500 matches any 5xx\n  if (boundaryStatus === 400) return errorStatus >= 400 && errorStatus <= 499;\n  if (boundaryStatus === 500) return errorStatus >= 500 && errorStatus <= 599;\n  // Exact match\n  return boundaryStatus === errorStatus;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA0BA,IAAI,eAAe;AACnB,IAAI,OAAO,WAAW,aAAa;AACjC,QAAO,iBAAiB,sBAAsB;AAC5C,iBAAe;GACf;AACF,QAAO,iBAAiB,kBAAkB;AACxC,iBAAe;GACf;;AAiDJ,IAAa,sBAAb,cAAyC,UAGvC;CACA,YAAY,OAAiC;AAC3C,QAAM,MAAM;AACZ,OAAK,QAAQ;GAAE,UAAU;GAAO,OAAO;GAAM;;CAG/C,OAAO,yBAAyB,OAAwC;AAKtE,MAAI,aACF,QAAO;GAAE,UAAU;GAAO,OAAO;GAAM;AAEzC,SAAO;GAAE,UAAU;GAAM;GAAO;;CAGlC,mBAAmB,WAA2C;AAI5D,MAAI,KAAK,MAAM,YAAY,UAAU,aAAa,KAAK,MAAM,SAC3D,MAAK,SAAS;GAAE,UAAU;GAAO,OAAO;GAAM,CAAC;;;CAKnD,cAAsB;AACpB,OAAK,SAAS;GAAE,UAAU;GAAO,OAAO;GAAM,CAAC;;CAGjD,SAAoB;AAClB,MAAI,CAAC,KAAK,MAAM,YAAY,CAAC,KAAK,MAAM,MACtC,QAAO,KAAK,MAAM;EAGpB,MAAM,QAAQ,KAAK,MAAM;EACzB,MAAM,SAAS,YAAY,MAAM;AAKjC,MAAI,QAAQ,SAAS,WACnB,OAAM;AAKR,MAAI,KAAK,MAAM,UAAU,MAAM;GAC7B,MAAM,cAAc,eAAe,QAAQ,MAAM;AACjD,OAAI,eAAe,QAAQ,CAAC,cAAc,KAAK,MAAM,QAAQ,YAAY,CAEvE,OAAM;;AAKV,MAAI,QAAQ,SAAS,OACnB,QAAO,cAAc,KAAK,MAAM,mBAA4B;GAC1D,QAAQ,OAAO;GACf,qBAAqB,OAAO;GAC7B,CAAC;EAIJ,MAAM,SACJ,QAAQ,SAAS,iBAAiB;GAAE,MAAM,OAAO;GAAM,MAAM,OAAO;GAAM,GAAG;AAE/E,SAAO,cAAc,KAAK,MAAM,mBAA4B;GAC1D;GACA;GACA,OAAO,KAAK;GACb,CAAC;;;;;;;AAUN,SAAS,YAAY,OAAmC;CACtD,MAAM,MAAO,MAA8B;AAC3C,KAAI,OAAO,QAAQ,SAAU,QAAO;AACpC,KAAI;EACF,MAAM,SAAS,KAAK,MAAM,IAAI;AAC9B,MAAI,UAAU,OAAO,WAAW,YAAY,OAAO,OAAO,SAAS,SACjE,QAAO;SAEH;AAGR,QAAO;;;;;;AAOT,SAAS,eAAe,QAA6B,OAA6B;AAChF,KAAI,QAAQ,SAAS,OAAQ,QAAO,OAAO;AAC3C,KAAI,QAAQ,SAAS,eAAgB,QAAO,OAAO;AACnD,KAAI,QAAQ,SAAS,WAAY,QAAO,OAAO;CAG/C,MAAM,QAAQ,MAAM,QAAQ,MAAM,oCAAoC;AACtE,KAAI,MAAO,QAAO,SAAS,MAAM,IAAI,GAAG;AAGxC,QAAO;;;;;;AAOT,SAAS,cAAc,gBAAwB,aAA8B;AAE3E,KAAI,mBAAmB,IAAK,QAAO,eAAe,OAAO,eAAe;AACxE,KAAI,mBAAmB,IAAK,QAAO,eAAe,OAAO,eAAe;AAExE,QAAO,mBAAmB"}

package/dist/_chunks/format-DNt20Kt8.js

@@ -0,0 +1,163 @@
+//#region src/server/dev-warnings.ts
+var WarningId = {
+	SUSPENSE_WRAPS_CHILDREN: "SUSPENSE_WRAPS_CHILDREN",
+	DENY_IN_SUSPENSE: "DENY_IN_SUSPENSE",
+	REDIRECT_IN_SUSPENSE: "REDIRECT_IN_SUSPENSE",
+	REDIRECT_IN_ACCESS: "REDIRECT_IN_ACCESS",
+	STATIC_REQUEST_API: "STATIC_REQUEST_API",
+	CACHE_REQUEST_PROPS: "CACHE_REQUEST_PROPS",
+	SLOW_SLOT_NO_SUSPENSE: "SLOW_SLOT_NO_SUSPENSE"
+};
+var _emitted = /* @__PURE__ */ new Set();
+/** Vite dev server for forwarding warnings to browser console. */
+var _viteServer = null;
+/**
+* Register the Vite dev server for browser console forwarding.
+* Called by timber-dev-server during configureServer.
+*/
+function setViteServer(server) {
+	_viteServer = server;
+}
+function isDev() {
+	return process.env.NODE_ENV !== "production";
+}
+/**
+* Emit a warning only once per dedup key.
+*
+* Writes to stderr and forwards to browser console via Vite WebSocket.
+* Returns true if emitted (not deduplicated).
+*/
+function emitOnce(warningId, location, level, message) {
+	if (!isDev()) return false;
+	const dedupKey = `${warningId}:${location}`;
+	if (_emitted.has(dedupKey)) return false;
+	_emitted.add(dedupKey);
+	const prefix = level === "error" ? "\x1B[31m[timber]\x1B[0m" : "\x1B[33m[timber]\x1B[0m";
+	process.stderr.write(`${prefix} ${message}\n`);
+	if (_viteServer?.hot) _viteServer.hot.send("timber:dev-warning", {
+		warningId,
+		level,
+		message: `[timber] ${message}`
+	});
+	return true;
+}
+/**
+* Warn when a layout wraps {children} in <Suspense>.
+*
+* This defers the page content — the primary resource — behind a fallback.
+* The page's data fetches won't affect the HTTP status code because they
+* resolve after onShellReady. If the page calls deny(404), the status code
+* is already committed as 200.
+*
+* @param layoutFile - Relative path to the layout file (e.g., "app/(dashboard)/layout.tsx")
+*/
+function warnSuspenseWrappingChildren(layoutFile) {
+	emitOnce(WarningId.SUSPENSE_WRAPS_CHILDREN, layoutFile, "warn", `Layout at ${layoutFile} wraps {children} in <Suspense>. This prevents child pages from setting HTTP status codes. Use useNavigationPending() for loading states instead.`);
+}
+/**
+* Warn when deny() is called inside a Suspense boundary.
+*
+* After the shell has flushed and the status code is committed, deny()
+* cannot change the HTTP response. The signal will be caught by the nearest
+* error boundary instead of producing a correct status code.
+*
+* @param file - Relative path to the file
+* @param line - Line number where deny() was called
+*/
+function warnDenyInSuspense(file, line) {
+	const location = line ? `${file}:${line}` : file;
+	emitOnce(WarningId.DENY_IN_SUSPENSE, location, "error", `deny() called inside <Suspense> at ${location}. The HTTP status is already committed — this will trigger an error boundary with a 200 status. Move deny() outside <Suspense> for correct HTTP semantics.`);
+}
+/**
+* Warn when redirect() is called inside a Suspense boundary.
+*
+* This will perform a client-side navigation instead of an HTTP redirect.
+*
+* @param file - Relative path to the file
+* @param line - Line number where redirect() was called
+*/
+function warnRedirectInSuspense(file, line) {
+	const location = line ? `${file}:${line}` : file;
+	emitOnce(WarningId.REDIRECT_IN_SUSPENSE, location, "error", `redirect() called inside <Suspense> at ${location}. This will perform a client-side navigation instead of an HTTP redirect.`);
+}
+/**
+* Warn when redirect() is called in a slot's access.ts.
+*
+* Slots use deny() for graceful degradation. Redirecting from a slot would
+* redirect the entire page, breaking the contract that slot failure is
+* isolated to the slot.
+*
+* @param accessFile - Relative path to the access.ts file
+* @param line - Line number where redirect() was called
+*/
+function warnRedirectInAccess(accessFile, line) {
+	const location = line ? `${accessFile}:${line}` : accessFile;
+	emitOnce(WarningId.REDIRECT_IN_ACCESS, location, "error", `redirect() called in access.ts at ${location}. Only deny() is valid in slot access checks. Use deny() to block access or move redirect() to middleware.ts.`);
+}
+/**
+* Warn when cookies() or headers() is called during a static build.
+*
+* In output: 'static' mode, there is no per-request context — these APIs
+* read build-time values only. This is almost always a mistake.
+*
+* @param api - The dynamic API name ("cookies" or "headers")
+* @param file - Relative path to the file calling the API
+*/
+function warnStaticRequestApi(api, file) {
+	emitOnce(WarningId.STATIC_REQUEST_API, `${api}:${file}`, "error", `${api}() called during static generation of ${file}. Dynamic request APIs are not available during prerendering.`);
+}
+/**
+* Warn when a "use cache" component receives request-specific props.
+*
+* Cached components should not depend on per-request data — a userId or
+* sessionId in the props means the cache will either be ineffective
+* (key per user) or dangerous (serve one user's data to another).
+*
+* @param componentName - Name of the cached component
+* @param propName - Name of the suspicious prop
+* @param file - Relative path to the component file
+* @param line - Line number
+*/
+function warnCacheRequestProps(componentName, propName, file, line) {
+	const location = line ? `${file}:${line}` : file;
+	emitOnce(WarningId.CACHE_REQUEST_PROPS, `${componentName}:${propName}:${location}`, "warn", `Cached component ${componentName} receives prop "${propName}" which appears request-specific. Cached components should not depend on per-request data.`);
+}
+/**
+* Warn when a parallel slot resolves slowly without a <Suspense> wrapper.
+*
+* A slow slot without Suspense blocks onShellReady — and therefore the
+* status code commit — for the entire page. Wrapping it in <Suspense>
+* lets the shell flush without waiting for the slot.
+*
+* @param slotName - The slot name (e.g., "@admin")
+* @param durationMs - How long the slot took to resolve
+*/
+function warnSlowSlotWithoutSuspense(slotName, durationMs) {
+	emitOnce(WarningId.SLOW_SLOT_NO_SUSPENSE, slotName, "warn", `Slot ${slotName} resolved in ${durationMs}ms and is not wrapped in <Suspense>. Consider wrapping to avoid blocking the flush.`);
+}
+/** @deprecated Use warnStaticRequestApi instead */
+var warnDynamicApiInStaticBuild = warnStaticRequestApi;
+/** @deprecated Use warnRedirectInAccess instead */
+function warnRedirectInSlotAccess(slotName) {
+	warnRedirectInAccess(`${slotName}/access.ts`);
+}
+/** @deprecated Use warnDenyInSuspense / warnRedirectInSuspense instead */
+function warnDenyAfterFlush(signal) {
+	if (signal === "deny") warnDenyInSuspense("unknown");
+	else warnRedirectInSuspense("unknown");
+}
+//#endregion
+//#region src/utils/format.ts
+/**
+* Shared formatting utilities.
+*/
+/** Format a byte count as a human-readable string (e.g. "1.50 kB"). */
+function formatSize(bytes) {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} kB`;
+	return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
+//#endregion
+export { warnDenyAfterFlush as a, warnRedirectInAccess as c, warnSlowSlotWithoutSuspense as d, warnStaticRequestApi as f, warnCacheRequestProps as i, warnRedirectInSlotAccess as l, WarningId as n, warnDenyInSuspense as o, warnSuspenseWrappingChildren as p, setViteServer as r, warnDynamicApiInStaticBuild as s, formatSize as t, warnRedirectInSuspense as u };
+
+//# sourceMappingURL=format-DNt20Kt8.js.map

package/dist/_chunks/format-DNt20Kt8.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-DNt20Kt8.js","names":[],"sources":["../../src/server/dev-warnings.ts","../../src/utils/format.ts"],"sourcesContent":["/**\n * Dev-mode warnings for common timber.js misuse patterns.\n *\n * These fire in development only and are stripped from production builds.\n * Each warning targets a specific misuse identified during design review.\n *\n * Warnings are deduplicated by warningId:filePath:line so the same warning\n * is only emitted once per dev session (per unique source location).\n *\n * Warnings are written to stderr and, when a Vite dev server is available,\n * forwarded to the browser console via Vite's WebSocket.\n *\n * See design/21-dev-server.md §\"Dev-Mode Warnings\"\n * See design/11-platform.md §\"Dev Mode\"\n */\n\nimport type { ViteDevServer } from 'vite';\n\n// ─── Warning IDs ───────────────────────────────────────────────────────────\n\nexport const WarningId = {\n  SUSPENSE_WRAPS_CHILDREN: 'SUSPENSE_WRAPS_CHILDREN',\n  DENY_IN_SUSPENSE: 'DENY_IN_SUSPENSE',\n  REDIRECT_IN_SUSPENSE: 'REDIRECT_IN_SUSPENSE',\n  REDIRECT_IN_ACCESS: 'REDIRECT_IN_ACCESS',\n  STATIC_REQUEST_API: 'STATIC_REQUEST_API',\n  CACHE_REQUEST_PROPS: 'CACHE_REQUEST_PROPS',\n  SLOW_SLOT_NO_SUSPENSE: 'SLOW_SLOT_NO_SUSPENSE',\n} as const;\n\nexport type WarningId = (typeof WarningId)[keyof typeof WarningId];\n\n// ─── Configuration ──────────────────────────────────────────────────────────\n\n/** Configuration for dev warning behavior. */\nexport interface DevWarningConfig {\n  /** Threshold in ms for \"slow slot\" warnings. Default: 200. */\n  slowSlotThresholdMs?: number;\n}\n\n// ─── Deduplication & Server ─────────────────────────────────────────────────\n\nconst _emitted = new Set<string>();\n\n/** Vite dev server for forwarding warnings to browser console. */\nlet _viteServer: ViteDevServer | null = null;\n\n/**\n * Register the Vite dev server for browser console forwarding.\n * Called by timber-dev-server during configureServer.\n */\nexport function setViteServer(server: ViteDevServer | null): void {\n  _viteServer = server;\n}\n\nfunction isDev(): boolean {\n  return process.env.NODE_ENV !== 'production';\n}\n\n/**\n * Emit a warning only once per dedup key.\n *\n * Writes to stderr and forwards to browser console via Vite WebSocket.\n * Returns true if emitted (not deduplicated).\n */\nfunction emitOnce(\n  warningId: WarningId,\n  location: string,\n  level: 'warn' | 'error',\n  message: string\n): boolean {\n  if (!isDev()) return false;\n\n  const dedupKey = `${warningId}:${location}`;\n  if (_emitted.has(dedupKey)) return false;\n  _emitted.add(dedupKey);\n\n  // Write to stderr\n  const prefix = level === 'error' ? '\\x1b[31m[timber]\\x1b[0m' : '\\x1b[33m[timber]\\x1b[0m';\n  process.stderr.write(`${prefix} ${message}\\n`);\n\n  // Forward to browser console via Vite WebSocket\n  if (_viteServer?.hot) {\n    _viteServer.hot.send('timber:dev-warning', {\n      warningId,\n      level,\n      message: `[timber] ${message}`,\n    });\n  }\n\n  return true;\n}\n\n// ─── Warning Functions ──────────────────────────────────────────────────────\n\n/**\n * Warn when a layout wraps {children} in <Suspense>.\n *\n * This defers the page content — the primary resource — behind a fallback.\n * The page's data fetches won't affect the HTTP status code because they\n * resolve after onShellReady. If the page calls deny(404), the status code\n * is already committed as 200.\n *\n * @param layoutFile - Relative path to the layout file (e.g., \"app/(dashboard)/layout.tsx\")\n */\nexport function warnSuspenseWrappingChildren(layoutFile: string): void {\n  emitOnce(\n    WarningId.SUSPENSE_WRAPS_CHILDREN,\n    layoutFile,\n    'warn',\n    `Layout at ${layoutFile} wraps {children} in <Suspense>. ` +\n      'This prevents child pages from setting HTTP status codes. ' +\n      'Use useNavigationPending() for loading states instead.'\n  );\n}\n\n/**\n * Warn when deny() is called inside a Suspense boundary.\n *\n * After the shell has flushed and the status code is committed, deny()\n * cannot change the HTTP response. The signal will be caught by the nearest\n * error boundary instead of producing a correct status code.\n *\n * @param file - Relative path to the file\n * @param line - Line number where deny() was called\n */\nexport function warnDenyInSuspense(file: string, line?: number): void {\n  const location = line ? `${file}:${line}` : file;\n  emitOnce(\n    WarningId.DENY_IN_SUSPENSE,\n    location,\n    'error',\n    `deny() called inside <Suspense> at ${location}. ` +\n      'The HTTP status is already committed — this will trigger an error boundary with a 200 status. ' +\n      'Move deny() outside <Suspense> for correct HTTP semantics.'\n  );\n}\n\n/**\n * Warn when redirect() is called inside a Suspense boundary.\n *\n * This will perform a client-side navigation instead of an HTTP redirect.\n *\n * @param file - Relative path to the file\n * @param line - Line number where redirect() was called\n */\nexport function warnRedirectInSuspense(file: string, line?: number): void {\n  const location = line ? `${file}:${line}` : file;\n  emitOnce(\n    WarningId.REDIRECT_IN_SUSPENSE,\n    location,\n    'error',\n    `redirect() called inside <Suspense> at ${location}. ` +\n      'This will perform a client-side navigation instead of an HTTP redirect.'\n  );\n}\n\n/**\n * Warn when redirect() is called in a slot's access.ts.\n *\n * Slots use deny() for graceful degradation. Redirecting from a slot would\n * redirect the entire page, breaking the contract that slot failure is\n * isolated to the slot.\n *\n * @param accessFile - Relative path to the access.ts file\n * @param line - Line number where redirect() was called\n */\nexport function warnRedirectInAccess(accessFile: string, line?: number): void {\n  const location = line ? `${accessFile}:${line}` : accessFile;\n  emitOnce(\n    WarningId.REDIRECT_IN_ACCESS,\n    location,\n    'error',\n    `redirect() called in access.ts at ${location}. ` +\n      'Only deny() is valid in slot access checks. ' +\n      'Use deny() to block access or move redirect() to middleware.ts.'\n  );\n}\n\n/**\n * Warn when cookies() or headers() is called during a static build.\n *\n * In output: 'static' mode, there is no per-request context — these APIs\n * read build-time values only. This is almost always a mistake.\n *\n * @param api - The dynamic API name (\"cookies\" or \"headers\")\n * @param file - Relative path to the file calling the API\n */\nexport function warnStaticRequestApi(api: 'cookies' | 'headers', file: string): void {\n  emitOnce(\n    WarningId.STATIC_REQUEST_API,\n    `${api}:${file}`,\n    'error',\n    `${api}() called during static generation of ${file}. ` +\n      'Dynamic request APIs are not available during prerendering.'\n  );\n}\n\n/**\n * Warn when a \"use cache\" component receives request-specific props.\n *\n * Cached components should not depend on per-request data — a userId or\n * sessionId in the props means the cache will either be ineffective\n * (key per user) or dangerous (serve one user's data to another).\n *\n * @param componentName - Name of the cached component\n * @param propName - Name of the suspicious prop\n * @param file - Relative path to the component file\n * @param line - Line number\n */\nexport function warnCacheRequestProps(\n  componentName: string,\n  propName: string,\n  file: string,\n  line?: number\n): void {\n  const location = line ? `${file}:${line}` : file;\n  emitOnce(\n    WarningId.CACHE_REQUEST_PROPS,\n    `${componentName}:${propName}:${location}`,\n    'warn',\n    `Cached component ${componentName} receives prop \"${propName}\" which appears request-specific. ` +\n      'Cached components should not depend on per-request data.'\n  );\n}\n\n/**\n * Warn when a parallel slot resolves slowly without a <Suspense> wrapper.\n *\n * A slow slot without Suspense blocks onShellReady — and therefore the\n * status code commit — for the entire page. Wrapping it in <Suspense>\n * lets the shell flush without waiting for the slot.\n *\n * @param slotName - The slot name (e.g., \"@admin\")\n * @param durationMs - How long the slot took to resolve\n */\nexport function warnSlowSlotWithoutSuspense(slotName: string, durationMs: number): void {\n  emitOnce(\n    WarningId.SLOW_SLOT_NO_SUSPENSE,\n    slotName,\n    'warn',\n    `Slot ${slotName} resolved in ${durationMs}ms and is not wrapped in <Suspense>. ` +\n      'Consider wrapping to avoid blocking the flush.'\n  );\n}\n\n// ─── Legacy aliases ─────────────────────────────────────────────────────────\n\n/** @deprecated Use warnStaticRequestApi instead */\nexport const warnDynamicApiInStaticBuild = warnStaticRequestApi;\n\n/** @deprecated Use warnRedirectInAccess instead */\nexport function warnRedirectInSlotAccess(slotName: string): void {\n  warnRedirectInAccess(`${slotName}/access.ts`);\n}\n\n/** @deprecated Use warnDenyInSuspense / warnRedirectInSuspense instead */\nexport function warnDenyAfterFlush(signal: 'deny' | 'redirect'): void {\n  if (signal === 'deny') {\n    warnDenyInSuspense('unknown');\n  } else {\n    warnRedirectInSuspense('unknown');\n  }\n}\n\n// ─── Testing ────────────────────────────────────────────────────────────────\n\n/**\n * Reset emitted warnings. For testing only.\n * @internal\n */\nexport function _resetWarnings(): void {\n  _emitted.clear();\n}\n\n/**\n * Get the set of emitted dedup keys. For testing only.\n * @internal\n */\nexport function _getEmitted(): ReadonlySet<string> {\n  return _emitted;\n}\n","/**\n * Shared formatting utilities.\n */\n\n/** Format a byte count as a human-readable string (e.g. \"1.50 kB\"). */\nexport function formatSize(bytes: number): string {\n  if (bytes < 1024) return `${bytes} B`;\n  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(2)} kB`;\n  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;\n}\n"],"mappings":";AAoBA,IAAa,YAAY;CACvB,yBAAyB;CACzB,kBAAkB;CAClB,sBAAsB;CACtB,oBAAoB;CACpB,oBAAoB;CACpB,qBAAqB;CACrB,uBAAuB;CACxB;AAcD,IAAM,2BAAW,IAAI,KAAa;;AAGlC,IAAI,cAAoC;;;;;AAMxC,SAAgB,cAAc,QAAoC;AAChE,eAAc;;AAGhB,SAAS,QAAiB;AACxB,QAAA,QAAA,IAAA,aAAgC;;;;;;;;AASlC,SAAS,SACP,WACA,UACA,OACA,SACS;AACT,KAAI,CAAC,OAAO,CAAE,QAAO;CAErB,MAAM,WAAW,GAAG,UAAU,GAAG;AACjC,KAAI,SAAS,IAAI,SAAS,CAAE,QAAO;AACnC,UAAS,IAAI,SAAS;CAGtB,MAAM,SAAS,UAAU,UAAU,4BAA4B;AAC/D,SAAQ,OAAO,MAAM,GAAG,OAAO,GAAG,QAAQ,IAAI;AAG9C,KAAI,aAAa,IACf,aAAY,IAAI,KAAK,sBAAsB;EACzC;EACA;EACA,SAAS,YAAY;EACtB,CAAC;AAGJ,QAAO;;;;;;;;;;;;AAeT,SAAgB,6BAA6B,YAA0B;AACrE,UACE,UAAU,yBACV,YACA,QACA,aAAa,WAAW,mJAGzB;;;;;;;;;;;;AAaH,SAAgB,mBAAmB,MAAc,MAAqB;CACpE,MAAM,WAAW,OAAO,GAAG,KAAK,GAAG,SAAS;AAC5C,UACE,UAAU,kBACV,UACA,SACA,sCAAsC,SAAS,4JAGhD;;;;;;;;;;AAWH,SAAgB,uBAAuB,MAAc,MAAqB;CACxE,MAAM,WAAW,OAAO,GAAG,KAAK,GAAG,SAAS;AAC5C,UACE,UAAU,sBACV,UACA,SACA,0CAA0C,SAAS,2EAEpD;;;;;;;;;;;;AAaH,SAAgB,qBAAqB,YAAoB,MAAqB;CAC5E,MAAM,WAAW,OAAO,GAAG,WAAW,GAAG,SAAS;AAClD,UACE,UAAU,oBACV,UACA,SACA,qCAAqC,SAAS,+GAG/C;;;;;;;;;;;AAYH,SAAgB,qBAAqB,KAA4B,MAAoB;AACnF,UACE,UAAU,oBACV,GAAG,IAAI,GAAG,QACV,SACA,GAAG,IAAI,wCAAwC,KAAK,+DAErD;;;;;;;;;;;;;;AAeH,SAAgB,sBACd,eACA,UACA,MACA,MACM;CACN,MAAM,WAAW,OAAO,GAAG,KAAK,GAAG,SAAS;AAC5C,UACE,UAAU,qBACV,GAAG,cAAc,GAAG,SAAS,GAAG,YAChC,QACA,oBAAoB,cAAc,kBAAkB,SAAS,4FAE9D;;;;;;;;;;;;AAaH,SAAgB,4BAA4B,UAAkB,YAA0B;AACtF,UACE,UAAU,uBACV,UACA,QACA,QAAQ,SAAS,eAAe,WAAW,qFAE5C;;;AAMH,IAAa,8BAA8B;;AAG3C,SAAgB,yBAAyB,UAAwB;AAC/D,sBAAqB,GAAG,SAAS,YAAY;;;AAI/C,SAAgB,mBAAmB,QAAmC;AACpE,KAAI,WAAW,OACb,oBAAmB,UAAU;KAE7B,wBAAuB,UAAU;;;;;;;;AChQrC,SAAgB,WAAW,OAAuB;AAChD,KAAI,QAAQ,KAAM,QAAO,GAAG,MAAM;AAClC,KAAI,QAAQ,OAAO,KAAM,QAAO,IAAI,QAAQ,MAAM,QAAQ,EAAE,CAAC;AAC7D,QAAO,IAAI,SAAS,OAAO,OAAO,QAAQ,EAAE,CAAC"}