@timber-js/app 0.1.23 → 0.1.25

package/dist/server/metadata-platform.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Platform-specific metadata rendering — icons, Apple Web App, App Links, iTunes.
+ *
+ * Extracted from metadata-render.ts to keep files under 500 lines.
+ *
+ * See design/16-metadata.md
+ */
+import type { Metadata } from './types.js';
+import type { HeadElement } from './metadata.js';
+/**
+ * Render icon link elements (favicon, shortcut, apple-touch-icon, custom).
+ */
+export declare function renderIcons(icons: NonNullable<Metadata['icons']>, elements: HeadElement[]): void;
+/**
+ * Render alternate link elements (canonical, hreflang, media, types).
+ */
+export declare function renderAlternates(alternates: NonNullable<Metadata['alternates']>, elements: HeadElement[]): void;
+/**
+ * Render site verification meta tags (Google, Yahoo, Yandex, custom).
+ */
+export declare function renderVerification(verification: NonNullable<Metadata['verification']>, elements: HeadElement[]): void;
+/**
+ * Render Apple Web App meta tags and startup image links.
+ */
+export declare function renderAppleWebApp(appleWebApp: NonNullable<Metadata['appleWebApp']>, elements: HeadElement[]): void;
+/**
+ * Render App Links (al:*) meta tags for deep linking across platforms.
+ */
+export declare function renderAppLinks(appLinks: NonNullable<Metadata['appLinks']>, elements: HeadElement[]): void;
+/**
+ * Render Apple iTunes smart banner meta tag.
+ */
+export declare function renderItunes(itunes: NonNullable<Metadata['itunes']>, elements: HeadElement[]): void;
+//# sourceMappingURL=metadata-platform.d.ts.map

package/dist/server/metadata-platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-platform.d.ts","sourceRoot":"","sources":["../../src/server/metadata-platform.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI,CA6ChG;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,WAAW,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,EAC/C,QAAQ,EAAE,WAAW,EAAE,GACtB,IAAI,CA+BN;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,WAAW,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC,EACnD,QAAQ,EAAE,WAAW,EAAE,GACtB,IAAI,CAkBN;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,WAAW,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,EACjD,QAAQ,EAAE,WAAW,EAAE,GACtB,IAAI,CAmCN;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,WAAW,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,EAC3C,QAAQ,EAAE,WAAW,EAAE,GACtB,IAAI,CAwCN;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI,CAQnG"}

package/dist/server/metadata-render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadata-render.d.ts","sourceRoot":"","sources":["../../src/server/metadata-render.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAIjD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,GAAG,WAAW,EAAE,CAkI1E"}
+{"version":3,"file":"metadata-render.d.ts","sourceRoot":"","sources":["../../src/server/metadata-render.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAajD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,GAAG,WAAW,EAAE,CAkI1E"}

package/dist/server/metadata-social.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Social metadata rendering — Open Graph and Twitter Card meta tags.
+ *
+ * Extracted from metadata-render.ts to keep files under 500 lines.
+ *
+ * See design/16-metadata.md
+ */
+import type { Metadata } from './types.js';
+import type { HeadElement } from './metadata.js';
+/**
+ * Render Open Graph metadata into head element descriptors.
+ *
+ * Handles og:title, og:description, og:image (with dimensions/alt),
+ * og:video, og:audio, og:article:author, and other OG properties.
+ */
+export declare function renderOpenGraph(og: NonNullable<Metadata['openGraph']>, elements: HeadElement[]): void;
+/**
+ * Render Twitter Card metadata into head element descriptors.
+ *
+ * Handles twitter:card, twitter:site, twitter:title, twitter:image,
+ * twitter:player, and twitter:app (per-platform name/id/url).
+ */
+export declare function renderTwitter(tw: NonNullable<Metadata['twitter']>, elements: HeadElement[]): void;
+//# sourceMappingURL=metadata-social.d.ts.map

package/dist/server/metadata-social.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-social.d.ts","sourceRoot":"","sources":["../../src/server/metadata-social.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI,CAoErG;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,WAAW,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI,CA0FjG"}

package/dist/server/pipeline-interception.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Interception route matching for the request pipeline.
+ *
+ * Matches target URLs against interception rewrites to support the
+ * modal route pattern (soft navigation intercepts).
+ *
+ * Extracted from pipeline.ts to keep files under 500 lines.
+ *
+ * See design/07-routing.md §"Intercepting Routes"
+ */
+/** Result of a successful interception match. */
+export interface InterceptionMatchResult {
+    /** The pathname to re-match (the source/intercepting route's parent). */
+    sourcePathname: string;
+}
+/**
+ * Check if an intercepting route applies for this soft navigation.
+ *
+ * Matches the target pathname against interception rewrites, constrained
+ * by the source URL (X-Timber-URL header — where the user navigates FROM).
+ *
+ * Returns the source pathname to re-match if interception applies, or null.
+ */
+export declare function findInterceptionMatch(targetPathname: string, sourceUrl: string, rewrites: import('#/routing/interception.js').InterceptionRewrite[]): InterceptionMatchResult | null;
+/**
+ * Check if a pathname matches a URL pattern with dynamic segments.
+ *
+ * Supports [param] (single segment) and [...param] (one or more segments).
+ * Static segments must match exactly.
+ */
+export declare function pathnameMatchesPattern(pathname: string, pattern: string): boolean;
+//# sourceMappingURL=pipeline-interception.d.ts.map

package/dist/server/pipeline-interception.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-interception.d.ts","sourceRoot":"","sources":["../../src/server/pipeline-interception.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,iDAAiD;AACjD,MAAM,WAAW,uBAAuB;IACtC,yEAAyE;IACzE,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,OAAO,2BAA2B,EAAE,mBAAmB,EAAE,GAClE,uBAAuB,GAAG,IAAI,CAYhC;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CA0BjF"}

package/dist/server/pipeline-metadata.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Metadata route helpers for the request pipeline.
+ *
+ * Handles serving static metadata files and serializing sitemap responses.
+ * Extracted from pipeline.ts to keep files under 500 lines.
+ *
+ * See design/16-metadata.md §"Metadata Routes"
+ */
+/**
+ * Serve a static metadata file by reading it from disk.
+ *
+ * Static metadata route files (.xml, .txt, .json, .png, .ico, .svg, etc.)
+ * are served as-is with the appropriate Content-Type header.
+ * Text files include charset=utf-8; binary files do not.
+ *
+ * See design/16-metadata.md §"Metadata Routes"
+ */
+export declare function serveStaticMetadataFile(metaMatch: import('./route-matcher.js').MetadataRouteMatch): Promise<Response>;
+/**
+ * Serialize a sitemap array to XML.
+ * Follows the sitemap.org protocol: https://www.sitemaps.org/protocol.html
+ */
+export declare function serializeSitemap(entries: Array<{
+    url: string;
+    lastModified?: string | Date;
+    changeFrequency?: string;
+    priority?: number;
+}>): string;
+/** Escape special XML characters. */
+export declare function escapeXml(str: string): string;
+//# sourceMappingURL=pipeline-metadata.d.ts.map

package/dist/server/pipeline-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-metadata.d.ts","sourceRoot":"","sources":["../../src/server/pipeline-metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgBH;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAC3C,SAAS,EAAE,OAAO,oBAAoB,EAAE,kBAAkB,GACzD,OAAO,CAAC,QAAQ,CAAC,CAYnB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,KAAK,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC,GACD,MAAM,CAoBR;AAED,qCAAqC;AACrC,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO7C"}

package/dist/server/pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/server/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAY,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAkC1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAItD,sEAAsE;AACtE,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,uDAAuD;IACvD,UAAU,CAAC,EAAE,YAAY,CAAC;CAC3B;AAED,6DAA6D;AAC7D,MAAM,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,UAAU,GAAG,IAAI,CAAC;AAEnE,sEAAsE;AACtE,MAAM,MAAM,oBAAoB,GAAG,CACjC,QAAQ,EAAE,MAAM,KACb,OAAO,oBAAoB,EAAE,kBAAkB,GAAG,IAAI,CAAC;AAE5D,iEAAiE;AACjE,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,6DAA6D;AAC7D,MAAM,MAAM,aAAa,GAAG,CAC1B,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,oBAAoB,EAAE,OAAO,EAC7B,YAAY,CAAC,EAAE,mBAAmB,KAC/B,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAElC,+DAA+D;AAC/D,MAAM,MAAM,iBAAiB,GAAG,CAC9B,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,OAAO,EACZ,eAAe,EAAE,OAAO,KACrB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAI1B,MAAM,WAAW,cAAc;IAC7B,iFAAiF;IACjF,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;QAAE,OAAO,EAAE,WAAW,CAAA;KAAE,CAAC,CAAC;IACtD,qEAAqE;IACrE,UAAU,EAAE,YAAY,CAAC;IACzB,iGAAiG;IACjG,kBAAkB,CAAC,EAAE,oBAAoB,CAAC;IAC1C,kEAAkE;IAClE,MAAM,EAAE,aAAa,CAAC;IACtB,kEAAkE;IAClE,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,eAAe,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzF,kFAAkF;IAClF,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,gFAAgF;IAChF,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,yGAAyG;IACzG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,2BAA2B,EAAE,mBAAmB,EAAE,CAAC;IACjF;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxD;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,EAAE,CACpB,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,OAAO,EACZ,eAAe,EAAE,OAAO,KACrB,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACnC;AAID;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAuU1F"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/server/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAY,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAiB,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAoC1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAItD,sEAAsE;AACtE,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,uDAAuD;IACvD,UAAU,CAAC,EAAE,YAAY,CAAC;CAC3B;AAED,6DAA6D;AAC7D,MAAM,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,UAAU,GAAG,IAAI,CAAC;AAEnE,sEAAsE;AACtE,MAAM,MAAM,oBAAoB,GAAG,CACjC,QAAQ,EAAE,MAAM,KACb,OAAO,oBAAoB,EAAE,kBAAkB,GAAG,IAAI,CAAC;AAE5D,iEAAiE;AACjE,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,6DAA6D;AAC7D,MAAM,MAAM,aAAa,GAAG,CAC1B,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,eAAe,EAAE,OAAO,EACxB,oBAAoB,EAAE,OAAO,EAC7B,YAAY,CAAC,EAAE,mBAAmB,KAC/B,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAElC,+DAA+D;AAC/D,MAAM,MAAM,iBAAiB,GAAG,CAC9B,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,OAAO,EACZ,eAAe,EAAE,OAAO,KACrB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAI1B,MAAM,WAAW,cAAc;IAC7B,iFAAiF;IACjF,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC;QAAE,OAAO,EAAE,WAAW,CAAA;KAAE,CAAC,CAAC;IACtD,qEAAqE;IACrE,UAAU,EAAE,YAAY,CAAC;IACzB,iGAAiG;IACjG,kBAAkB,CAAC,EAAE,oBAAoB,CAAC;IAC1C,kEAAkE;IAClE,MAAM,EAAE,aAAa,CAAC;IACtB,kEAAkE;IAClE,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,eAAe,EAAE,OAAO,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzF,kFAAkF;IAClF,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,gFAAgF;IAChF,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,yGAAyG;IACzG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,2BAA2B,EAAE,mBAAmB,EAAE,CAAC;IACjF;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACxD;;;;;;;;;;OAUG;IACH,mBAAmB,CAAC,EAAE,CACpB,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,OAAO,EACZ,eAAe,EAAE,OAAO,KACrB,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACnC;AAID;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAuU1F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "Vite-native React framework for Cloudflare Workers — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",

package/src/adapters/nitro.ts

@@ -239,7 +239,13 @@ export function generateNitroEntry(
   preset: NitroPreset,
   hasManifestInit = false
 ): string {
-  const serverEntryRelative = relative(outDir, join(buildDir, 'server', 'entry.js'));
+  // The RSC entry is the main request handler — it exports the fetch handler as default.
+  // The Vite RSC plugin outputs it to rsc/index.js.
+  let serverEntryRelative = relative(outDir, join(buildDir, 'rsc', 'index.js'));
+  // Ensure the import path starts with ./ for ESM compatibility
+  if (!serverEntryRelative.startsWith('.')) {
+    serverEntryRelative = './' + serverEntryRelative;
+  }
   const runtimeName = PRESET_CONFIGS[preset].runtimeName;
   const earlyHints = PRESET_CONFIGS[preset].supportsEarlyHints;
 
@@ -250,10 +256,6 @@ export function generateNitroEntry(
   // On node-server and bun, wrap the handler with ALS so the pipeline
   // can send 103 Early Hints via res.writeEarlyHints(). Other presets
   // either don't support 103 or handle it at the CDN level.
-  const earlyHintsImport = earlyHints
-    ? `import { runWithEarlyHintsSender } from '${serverEntryRelative}'\n`
-    : '';
-
   const handlerCall = earlyHints
     ? `  const nodeRes = event.node?.res
   const earlyHintsSender = (typeof nodeRes?.writeEarlyHints === 'function')
@@ -268,8 +270,8 @@ export function generateNitroEntry(
   return `// Generated by @timber-js/app/adapters/nitro
 // Do not edit — this file is regenerated on each build.
 
-${manifestImport}${earlyHintsImport}import { defineEventHandler, toWebRequest, sendWebResponse } from 'h3'
-import { handler } from '${serverEntryRelative}'
+${manifestImport}import { defineEventHandler, toWebRequest, sendWebResponse } from 'h3'
+import handler, { runWithEarlyHintsSender } from '${serverEntryRelative}'
 
 // Set TIMBER_RUNTIME for instrumentation.ts conditional SDK initialization.
 // See design/25-production-deployments.md §"TIMBER_RUNTIME".

package/src/cli.ts

@@ -189,9 +189,16 @@ async function main(): Promise<void> {
   }
 }
 
-// Only run main when executed directly (not imported in tests)
+// Run main when executed as a CLI (not imported in tests).
+// The bin shim (bin/timber.mjs) does `import '../dist/cli.js'`, so
+// process.argv[1] points to the shim, not this file. We check both:
+// direct execution AND being imported by the timber bin shim.
 const isDirectExecution =
-  typeof process !== 'undefined' && process.argv[1] && import.meta.url.endsWith(process.argv[1]);
+  typeof process !== 'undefined' &&
+  process.argv[1] &&
+  (import.meta.url.endsWith(process.argv[1]) ||
+    process.argv[1].endsWith('bin/timber.mjs') ||
+    process.argv[1].endsWith('bin/timber'));
 
 if (isDirectExecution) {
   main().catch((err) => {

package/src/client/browser-dev.ts

@@ -0,0 +1,142 @@
+/**
+ * Dev-only browser helpers — server log replay and client error forwarding.
+ *
+ * These are only active when import.meta.hot is available (Vite dev mode).
+ * Extracted from browser-entry.ts to keep files under 500 lines.
+ *
+ * See design/21-dev-server.md §"HMR Wiring"
+ */
+
+import { isPageUnloading } from './unload-guard.js';
+
+// ─── HMR Hot Interface ──────────────────────────────────────────────
+
+/** Minimal interface for Vite's HMR channel. */
+export interface HotInterface {
+  on(event: string, cb: (...args: unknown[]) => void): void;
+  send(event: string, data: unknown): void;
+}
+
+// ─── Server Log Replay ──────────────────────────────────────────────
+
+/** Payload shape from plugins/dev-logs.ts */
+interface ServerLogPayload {
+  level: 'log' | 'warn' | 'error' | 'debug' | 'info';
+  args: unknown[];
+  location: string | null;
+  timestamp: number;
+}
+
+/**
+ * Deserialize a serialized arg back into a console-friendly value.
+ *
+ * Handles Error objects (serialized as { __type: 'Error', ... }),
+ * Maps, Sets, and passes everything else through.
+ */
+function deserializeArg(arg: unknown): unknown {
+  if (arg === '[undefined]') return undefined;
+  if (arg === null || typeof arg !== 'object') return arg;
+
+  const obj = arg as Record<string, unknown>;
+
+  if (obj.__type === 'Error') {
+    const err = new Error(obj.message as string);
+    err.name = obj.name as string;
+    if (obj.stack) err.stack = obj.stack as string;
+    return err;
+  }
+
+  if (obj.__type === 'Map') {
+    return new Map(
+      Object.entries(obj.entries as Record<string, unknown>).map(([k, v]) => [k, deserializeArg(v)])
+    );
+  }
+
+  if (obj.__type === 'Set') {
+    return new Set((obj.values as unknown[]).map(deserializeArg));
+  }
+
+  if (Array.isArray(arg)) {
+    return arg.map(deserializeArg);
+  }
+
+  // Plain object — recurse
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    result[key] = deserializeArg(value);
+  }
+  return result;
+}
+
+/**
+ * Set up the HMR listener that replays server console output in the browser.
+ *
+ * Each message arrives with a log level and serialized args. We prepend
+ * a styled "[SERVER]" badge and call the matching console method.
+ */
+export function setupServerLogReplay(hot: Pick<HotInterface, 'on'>): void {
+  /** CSS styles for the [SERVER] badge in browser console. */
+  const BADGE_STYLES: Record<string, string> = {
+    log: 'background: #0070f3; color: white; padding: 1px 5px; border-radius: 3px; font-weight: bold;',
+    info: 'background: #0070f3; color: white; padding: 1px 5px; border-radius: 3px; font-weight: bold;',
+    warn: 'background: #f5a623; color: white; padding: 1px 5px; border-radius: 3px; font-weight: bold;',
+    error:
+      'background: #e00; color: white; padding: 1px 5px; border-radius: 3px; font-weight: bold;',
+    debug:
+      'background: #666; color: white; padding: 1px 5px; border-radius: 3px; font-weight: bold;',
+  };
+
+  hot.on('timber:server-log', (data: unknown) => {
+    const payload = data as ServerLogPayload;
+    const level = payload.level;
+    const fn = console[level] ?? console.log;
+    const args = payload.args.map(deserializeArg);
+
+    const badge = `%cSERVER`;
+    const style = BADGE_STYLES[level] ?? BADGE_STYLES.log;
+    const locationSuffix = payload.location ? ` (${payload.location})` : '';
+
+    fn.call(console, badge, style, ...args, locationSuffix ? `\n  → ${payload.location}` : '');
+  });
+}
+
+// ─── Client Error Forwarding ────────────────────────────────────────
+
+/**
+ * Set up global error handlers that forward uncaught client-side
+ * errors to the dev server via Vite's HMR channel.
+ *
+ * The server receives 'timber:client-error' events, and echoes them
+ * back as Vite '{ type: "error" }' payloads to trigger the overlay.
+ */
+export function setupClientErrorForwarding(hot: Pick<HotInterface, 'send'>): void {
+  window.addEventListener('error', (event: ErrorEvent) => {
+    // Skip errors without useful information
+    if (!event.error && !event.message) return;
+    // Skip errors during page unload — these are abort-related, not application errors
+    if (isPageUnloading()) return;
+
+    const error = event.error;
+    hot.send('timber:client-error', {
+      message: error?.message ?? event.message,
+      stack: error?.stack ?? '',
+      componentStack: error?.componentStack ?? null,
+    });
+  });
+
+  window.addEventListener('unhandledrejection', (event: PromiseRejectionEvent) => {
+    const reason = event.reason;
+    if (!reason) return;
+    // Skip rejections during page unload — aborted fetches/streams cause these
+    if (isPageUnloading()) return;
+
+    const message = reason instanceof Error ? reason.message : String(reason);
+    const stack = reason instanceof Error ? (reason.stack ?? '') : '';
+
+    hot.send('timber:client-error', {
+      message,
+      stack,
+      componentStack: null,
+    });
+  });
+}