@timber-js/app 0.1.24 → 0.1.26

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.24",
+  "version": "0.1.26",
   "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

@@ -213,9 +213,15 @@ export function nitro(options: NitroAdapterOptions = {}): TimberPlatformAdapter
     // local runtime — Vite's built-in preview is the fallback.
     preview: LOCALLY_PREVIEWABLE.has(preset)
       ? async (_config: TimberConfig, buildDir: string) => {
-          const cmd = generateNitroPreviewCommand(buildDir, preset);
-          if (!cmd) return;
-          await spawnNitroPreview(cmd.command, cmd.args, cmd.cwd);
+          // Generate a standalone preview server that uses Node's built-in
+          // HTTP server. The Nitro entry.ts can't be run directly because
+          // it imports h3 (a Nitro dependency not available at runtime).
+          const previewScript = generatePreviewScript(buildDir, preset);
+          const scriptPath = join(buildDir, 'nitro', '_preview-server.mjs');
+          await writeFile(scriptPath, previewScript);
+
+          const command = preset === 'bun' ? 'bun' : 'node';
+          await spawnNitroPreview(command, [scriptPath], join(buildDir, 'nitro'));
         }
       : undefined,
 
@@ -239,7 +245,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 +262,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 +276,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".
@@ -318,6 +326,175 @@ export default defineNitroConfig(${configJson})
 /** Presets that produce a locally-runnable server entry. */
 const LOCALLY_PREVIEWABLE = new Set<NitroPreset>(['node-server', 'bun']);
 
+/**
+ * Generate a standalone preview server script that uses Node's built-in
+ * HTTP server. This bypasses Nitro entirely — the Nitro entry.ts imports
+ * h3 which isn't available outside a Nitro build. For local preview we
+ * just need to serve static files and route requests to the RSC handler.
+ *
+ * @internal Exported for testing.
+ */
+export function generatePreviewScript(buildDir: string, preset: NitroPreset): string {
+  const rscEntryRelative = relative(join(buildDir, 'nitro'), join(buildDir, 'rsc', 'index.js'));
+  const rscEntry = rscEntryRelative.startsWith('.') ? rscEntryRelative : './' + rscEntryRelative;
+  const publicDir = './public';
+  const manifestInitPath = './_timber-manifest-init.js';
+  const runtimeName = PRESET_CONFIGS[preset].runtimeName;
+
+  return `// Generated by @timber-js/app — standalone preview server.
+// Uses Node's built-in HTTP server to serve static assets and route
+// dynamic requests through the RSC handler. No Nitro/h3 dependency.
+
+import { createServer } from 'node:http';
+import { readFile, stat } from 'node:fs/promises';
+import { join, extname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { existsSync } from 'node:fs';
+
+// Set runtime before importing the handler.
+process.env.TIMBER_RUNTIME = '${runtimeName}';
+
+// Load the build manifest if it exists.
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const manifestPath = join(__dirname, '${manifestInitPath}');
+if (existsSync(manifestPath)) {
+  await import('${manifestInitPath}');
+}
+
+// Import the RSC handler (default export is the fetch-like handler).
+const { default: handler, runWithEarlyHintsSender } = await import('${rscEntry}');
+
+const MIME_TYPES = {
+  '.html': 'text/html',
+  '.js': 'application/javascript',
+  '.mjs': 'application/javascript',
+  '.css': 'text/css',
+  '.json': 'application/json',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.webm': 'video/webm',
+  '.mp4': 'video/mp4',
+  '.txt': 'text/plain',
+  '.xml': 'application/xml',
+  '.wasm': 'application/wasm',
+};
+
+const publicDir = join(__dirname, '${publicDir}');
+const port = parseInt(process.env.PORT || '3000', 10);
+
+const server = createServer(async (req, res) => {
+  const url = new URL(req.url || '/', \`http://localhost:\${port}\`);
+
+  // Try serving static files from the public directory first.
+  const filePath = join(publicDir, url.pathname);
+  // Prevent path traversal.
+  if (filePath.startsWith(publicDir)) {
+    try {
+      const fileStat = await stat(filePath);
+      if (fileStat.isFile()) {
+        const ext = extname(filePath);
+        const contentType = MIME_TYPES[ext] || 'application/octet-stream';
+        const body = await readFile(filePath);
+        // Hashed assets get immutable cache, others get short cache.
+        const cacheControl = url.pathname.startsWith('/assets/')
+          ? 'public, max-age=31536000, immutable'
+          : 'public, max-age=3600, must-revalidate';
+        res.writeHead(200, {
+          'Content-Type': contentType,
+          'Content-Length': body.length,
+          'Cache-Control': cacheControl,
+        });
+        res.end(body);
+        return;
+      }
+    } catch {
+      // File not found — fall through to the RSC handler.
+    }
+  }
+
+  // Convert Node request to Web Request.
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (value) {
+      if (Array.isArray(value)) {
+        for (const v of value) headers.append(key, v);
+      } else {
+        headers.set(key, value);
+      }
+    }
+  }
+
+  let body = undefined;
+  if (req.method !== 'GET' && req.method !== 'HEAD') {
+    body = await new Promise((resolve) => {
+      const chunks = [];
+      req.on('data', (chunk) => chunks.push(chunk));
+      req.on('end', () => resolve(Buffer.concat(chunks)));
+    });
+  }
+
+  const webRequest = new Request(url.href, {
+    method: req.method,
+    headers,
+    body,
+    duplex: body ? 'half' : undefined,
+  });
+
+  try {
+    // Support 103 Early Hints when available.
+    const earlyHintsSender = (typeof res.writeEarlyHints === 'function')
+      ? (links) => { try { res.writeEarlyHints({ link: links }); } catch {} }
+      : undefined;
+
+    const webResponse = earlyHintsSender && runWithEarlyHintsSender
+      ? await runWithEarlyHintsSender(earlyHintsSender, () => handler(webRequest))
+      : await handler(webRequest);
+
+    // Write the response back to the Node response.
+    res.writeHead(webResponse.status, Object.fromEntries(webResponse.headers.entries()));
+
+    if (webResponse.body) {
+      const reader = webResponse.body.getReader();
+      const pump = async () => {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) { res.end(); return; }
+          res.write(value);
+        }
+      };
+      await pump();
+    } else {
+      res.end();
+    }
+  } catch (err) {
+    console.error('[timber preview] Request error:', err);
+    if (!res.headersSent) {
+      res.writeHead(500, { 'Content-Type': 'text/plain' });
+    }
+    res.end('Internal Server Error');
+  }
+});
+
+server.listen(port, () => {
+  console.log();
+  console.log('  ⚡ timber preview server running at:');
+  console.log();
+  console.log(\`    ➜  http://localhost:\${port}\`);
+  console.log();
+});
+`;
+}
+
 /** Command descriptor for Nitro preview — testable without spawning. */
 export interface NitroPreviewCommand {
   command: string;

package/src/cli.ts

@@ -132,7 +132,7 @@ export async function runPreview(options: CommandOptions): Promise<void> {
   const adapter = config?.adapter as import('./adapters/types').TimberPlatformAdapter | undefined;
 
   if (resolvePreviewStrategy(adapter) === 'adapter') {
-    const buildDir = join(root, '.timber', 'build');
+    const buildDir = join(root, 'dist');
     const timberConfig = { output: (config?.output ?? 'server') as 'server' | 'static' };
     await adapter!.preview!(timberConfig, buildDir);
     return;
@@ -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,
+    });
+  });
+}