@timber-js/app 0.2.0-alpha.158 → 0.2.0-alpha.159

package/src/server/route-element-builder.ts

@@ -15,7 +15,7 @@
  * See design/02-rendering-pipeline.md, design/04-authorization.md
  */
 
-import { createElement } from 'react';
+import { createElement, Fragment } from 'react';
 import { randomUUID } from 'node:crypto';
 
 import { withSpan } from './tracing.js';
@@ -48,6 +48,28 @@ import { SegmentOutlet } from '../client/segment-outlet.js';
 import { wrapSegmentWithErrorBoundaries } from './error-boundary-wrapper.js';
 import type { InterceptionContext } from './pipeline.js';
 import { shouldSkipSegment } from './state-tree-diff.js';
+import type { HeadElement } from './metadata.js';
+
+/**
+ * Convert HeadElement descriptors to React elements for Float hoisting.
+ *
+ * React 19 Float hoists <title>, <meta>, and <link> rendered anywhere in
+ * the tree into <head> during SSR, and manages them in document.head
+ * during client-side rendering. This replaces the X-Timber-Head header
+ * side-channel and the imperative client DOM applier.
+ */
+export function headElementsToReact(elements: HeadElement[]): React.ReactElement {
+  const children: React.ReactElement[] = [];
+  for (let i = 0; i < elements.length; i++) {
+    const el = elements[i];
+    if (el.tag === 'title' && el.content !== undefined) {
+      children.push(createElement('title', { key: `t${i}` }, el.content));
+    } else if (el.attrs) {
+      children.push(createElement(el.tag, { key: `h${i}`, ...el.attrs }));
+    }
+  }
+  return createElement(Fragment, null, ...children);
+}
 import { loadModule } from './safe-load.js';
 
 /**
@@ -119,13 +141,6 @@ export class ParamCoercionError extends Error {
 
 // ─── Types ────────────────────────────────────────────────────────────────
 
-/** Head element for client-side metadata updates. */
-export interface HeadElement {
-  tag: string;
-  content?: string;
-  attrs?: Record<string, string | null>;
-}
-
 /** Layout entry with component and segment. */
 export interface LayoutComponentEntry {
   component: (...args: unknown[]) => unknown;
@@ -136,8 +151,6 @@ export interface LayoutComponentEntry {
 export interface RouteElementResult {
   /** The React element tree (page wrapped in layouts, access gates, error boundaries). */
   element: React.ReactElement;
-  /** Resolved head elements for metadata. */
-  headElements: HeadElement[];
   /** Layout components loaded along the segment chain. */
   layoutComponents: LayoutComponentEntry[];
   /** Segments from the route match. */
@@ -358,7 +371,12 @@ export async function buildRouteElement(
     }
   }
 
-  // Resolve metadata
+  // Resolve metadata and convert to React elements that React 19 Float
+  // hoists into <head> during both SSR and client rendering. This replaces
+  // the previous HeadElement descriptor system (string splice for SSR,
+  // X-Timber-Head header for RSC nav, imperative DOM updates on client).
+  // React manages <title>/<meta>/<link> lifecycle across navigations.
+  // See design/16-metadata.md, TIM-1151.
   const resolvedMetadata = resolveMetadata(metadataEntries);
   const headElements = renderMetadataToElements(resolvedMetadata);
 
@@ -423,6 +441,11 @@ export async function buildRouteElement(
     }
   }
 
+  // Convert HeadElement descriptors to React elements for Float hoisting.
+  // Placed at the page segment level so they're always re-rendered on
+  // SPA navigation (sync layouts may be skipped by segment tree diffing).
+  const metadataElement = headElementsToReact(headElements);
+
   // Build element tree: page wrapped in layouts (innermost to outermost)
   const h = createElement as (...args: unknown[]) => React.ReactElement;
 
@@ -464,6 +487,12 @@ export async function buildRouteElement(
     element = h(TracedPage, {});
   }
 
+  // Wrap page + metadata in a Fragment so Float-hoisted elements are at
+  // the page segment level (always re-rendered, never skipped by segment
+  // tree diffing). React 19 Float hoists the <title>/<meta>/<link>
+  // children into <head> regardless of where they appear in the tree.
+  element = h(Fragment, null, metadataElement, element);
+
   // Build a lookup of layout components by segment for O(1) access.
   const layoutBySegment = new Map(
     layoutComponents.map(({ component, segment }) => [segment, component])
@@ -715,7 +744,6 @@ export async function buildRouteElement(
 
   return {
     element,
-    headElements: headElements as HeadElement[],
     layoutComponents,
     segments,
     deferSuspenseFor,

package/src/server/rsc-entry/helpers.ts

@@ -229,20 +229,3 @@ export { isAbortError } from '../render-utils.js';
 
 // escapeHtml is now imported from server/utils/escape-html.ts
 export { escapeHtml } from '../utils/escape-html.js';
-
-/**
- * Parse a Cookie header string into a name→value Map.
- * Used to populate NavContext.cookies for SSR hooks (useCookie).
- */
-export function parseCookiesFromHeader(header: string): Map<string, string> {
-  const map = new Map<string, string>();
-  if (!header) return map;
-  for (const pair of header.split(';')) {
-    const eqIndex = pair.indexOf('=');
-    if (eqIndex === -1) continue;
-    const name = pair.slice(0, eqIndex).trim();
-    const value = pair.slice(eqIndex + 1).trim();
-    if (name) map.set(name, value);
-  }
-  return map;
-}

package/src/server/rsc-entry/index.ts

@@ -30,6 +30,8 @@ import buildManifest from 'virtual:timber-build-manifest';
 import loadUserInstrumentation from 'virtual:timber-instrumentation';
 // @ts-expect-error — virtual module provided by timber-entries plugin
 import loadCacheHandler from 'virtual:timber-cache-handler';
+// @ts-expect-error — virtual module provided by timber-entries plugin
+import { loadCdnPurgeHandler } from 'virtual:timber-cache-handler';
 // @ts-expect-error — virtual module provided by timber-routing plugin
 import globalSchemaCodecs from 'virtual:timber-schema';
 
@@ -61,6 +63,9 @@ import { callSsr } from './ssr-bridge.js';
 import { isDebug, isDevMode, setDebugFromConfig } from '../debug.js';
 import { setSourceMapCallback } from '../dev-source-map.js';
 import { requestContextAls } from '../als-registry.js';
+import { capturePrebuiltPayloads } from '../prebuilt-builder.js';
+import { setPrebuiltPayloadSource } from '../prebuilt/payload-source.js';
+import { setRscFunctions, setComponentRefreshTimeout } from '../prebuilt-runtime.js';
 import { createAutoSitemapHandler } from '../sitemap-handler.js';
 
 /**
@@ -130,6 +135,13 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
     setCacheHandler(userCacheHandler as Parameters<typeof setCacheHandler>[0]);
   }
 
+  // Wire the CDN purge handler so revalidateTag triggers CDN purge (TIM-1166).
+  const userCdnPurge = await loadCdnPurgeHandler();
+  if (userCdnPurge) {
+    const { setCdnPurgeHandler } = await import('../../cdn/purge-store.js');
+    setCdnPurgeHandler(userCdnPurge as Parameters<typeof setCdnPurgeHandler>[0]);
+  }
+
   // Propagate renderTimeoutMs into the default singleflight so cache calls
   // without a per-call timeoutMs still get deadlock protection (TIM-1032).
   const renderTimeoutMs = (runtimeConfig as Record<string, unknown>).renderTimeoutMs as
@@ -138,8 +150,63 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
   if (renderTimeoutMs) {
     const { setDefaultSingleflightTimeout } = await import('../../cache/timber-cache.js');
     setDefaultSingleflightTimeout(renderTimeoutMs);
+    setComponentRefreshTimeout(renderTimeoutMs);
   }
 
+  // Wire the prebuilt payload source so cache.component wrappers can look
+  // up cached flight payloads at request time (TIM-1122). The source is
+  // platform-aware: Node/Nitro reads from disk; Cloudflare reads from
+  // static assets via globalThis.__TIMBER_PREBUILT_SOURCE__ (set by the
+  // generated _worker.js before this module loads).
+  // In dev mode there are no prebuilt artifacts — source stays null and
+  // all cache.component wrappers render dynamically.
+  if (!isDevMode()) {
+    const platformSource = (globalThis as Record<string, unknown>).__TIMBER_PREBUILT_SOURCE__ as
+      | import('../prebuilt/payload-source.js').PrebuiltPayloadSource
+      | undefined;
+    if (platformSource) {
+      setPrebuiltPayloadSource(platformSource);
+    } else {
+      // Default: Node/fs-based source — prebuilt/ is alongside rsc/ in the
+      // adapter output directory, so resolve relative to this entry.
+      try {
+        const { readFile: fsReadFile } = await import('node:fs/promises');
+        const { join: pathJoin, dirname } = await import('node:path');
+        const { fileURLToPath } = await import('node:url');
+        const entryDir = dirname(fileURLToPath(import.meta.url));
+        const prebuiltDir = pathJoin(entryDir, '..', 'prebuilt');
+        setPrebuiltPayloadSource({
+          async loadManifest() {
+            try {
+              const data = await fsReadFile(pathJoin(prebuiltDir, 'manifest.json'), 'utf-8');
+              return JSON.parse(data);
+            } catch {
+              return null;
+            }
+          },
+          async readPayload(file) {
+            try {
+              return await fsReadFile(pathJoin(prebuiltDir, file));
+            } catch {
+              return null;
+            }
+          },
+        });
+      } catch {
+        // node:fs not available (e.g. edge runtimes without the global
+        // override) — source stays null, wrappers render dynamically.
+      }
+    }
+  }
+
+  // Wire RSC flight functions so prebuilt-runtime can revive cached payloads
+  // and capture re-renders without a dynamic import (TIM-1165).
+  const rscMod = await import('../../rsc-runtime/rsc.js');
+  setRscFunctions({
+    createFromReadableStream: rscMod.createFromReadableStream,
+    renderToReadableStream: rscMod.renderToReadableStream,
+  });
+
   const matchRoute = createRouteMatcher(manifest);
   const matchMetadataRoute = createMetadataRouteMatcher(manifest);
 
@@ -161,6 +228,7 @@ async function createRequestHandler(manifest: typeof routeManifest, runtimeConfi
   const clientBootstrap = buildClientScripts({
     ...runtimeConfig,
     clientJavascript: clientJsConfig ?? { disabled: false, enableHMRInDev: false },
+    devBrowserLogs: (runtimeConfig as Record<string, unknown>).devBrowserLogs as string | undefined,
     buildManifest: buildManifest as BuildManifest,
   });
 
@@ -465,6 +533,21 @@ export { runWithEarlyHintsSender } from '../early-hints-sender.js';
 // waitUntil support via ALS. See design/11-platform.md §"waitUntil()".
 export { runWithWaitUntil } from '../waituntil-bridge.js';
 
+/**
+ * Post-build flight capture entry point (TIM-1119). The capture pass must
+ * run inside the built RSC bundle — the prebuilt component registry, the
+ * ALS instances, and the flight renderer are module instances in THIS
+ * bundle's graph; an outside import of the framework package would get
+ * fresh, empty copies. The timber-prebuilt plugin imports the built
+ * `rsc/index.js` after the 5-step build and calls this export.
+ * See design/44-render-at-build-time.md §Build Phase.
+ */
+export function __timber_capturePrebuilt(
+  options: import('../prebuilt-builder.js').CaptureOptions
+): Promise<import('../prebuilt-builder.js').CaptureSummary> {
+  return capturePrebuiltPayloads(routeManifest, options);
+}
+
 const { handler: _handler, pipelineConfig: _pipelineConfig } = await createRequestHandler(
   routeManifest,
   config

package/src/server/rsc-entry/render-route.ts

@@ -27,7 +27,6 @@ import {
   collectRouteFonts,
   collectRouteModulepreloads,
 } from '../build-manifest.js';
-import { isDevMode } from '../debug.js';
 import type { LayoutEntry } from '../deny-renderer.js';
 import { renderDenyPage, renderDenyPageAsRsc } from '../deny-renderer.js';
 import type { ClientBootstrapConfig } from '../html-injectors.js';
@@ -40,12 +39,7 @@ import { parseClientStateTree } from '../state-tree-diff.js';
 
 import { handleApiRoute } from './api-handler.js';
 import { renderErrorPage, renderNoMatchPage } from './error-renderer.js';
-import {
-  buildRedirectResponse,
-  createDebugChannelSink,
-  escapeHtml,
-  isRscPayloadRequest,
-} from './helpers.js';
+import { buildRedirectResponse, createDebugChannelSink, isRscPayloadRequest } from './helpers.js';
 import { buildRscPayloadResponse } from './rsc-payload.js';
 import { renderRscStream } from './rsc-stream.js';
 import { renderSsrResponse } from './ssr-renderer.js';
@@ -139,8 +133,7 @@ export async function renderRoute(
     desc: 'build element tree',
   });
 
-  const { element, headElements, layoutComponents, deferSuspenseFor, skippedSegments } =
-    routeResult;
+  const { element, layoutComponents, deferSuspenseFor, skippedSegments } = routeResult;
 
   // Build head HTML for injection into the SSR output.
   // Collects CSS, fonts, and modulepreload from the build manifest for matched segments.
@@ -186,29 +179,10 @@ export async function renderRoute(
     }
   }
 
-  for (const el of headElements) {
-    if (el.tag === 'title' && el.content) {
-      headHtml += `<title>${escapeHtml(el.content)}</title>`;
-    } else if (el.attrs) {
-      const attrs = Object.entries(el.attrs)
-        .filter(([, v]) => v != null)
-        .map(([k, v]) => `${k}="${escapeHtml(v as string)}"`)
-        .join(' ');
-      headHtml += `<${el.tag} ${attrs}>`;
-    }
-  }
-
-  // In dev mode, inject the browser log forwarding script so console
-  // errors/warnings from the browser appear in the server terminal.
-  // Set by timber-dev-browser-logs plugin via globalThis (TIM-575).
-  if (isDevMode()) {
-    const devLogScript = (globalThis as Record<string, unknown>).__timber_dev_browser_log_script as
-      | string
-      | undefined;
-    if (devLogScript) {
-      headHtml += devLogScript;
-    }
-  }
+  // Metadata tags (<title>, <meta>, <link>) are now rendered as React
+  // elements in the route element tree — React 19 Float hoists them into
+  // <head> during SSR and manages them during client rendering. No string
+  // splice needed. See TIM-1151.
 
   // Render to RSC Flight stream with signal tracking.
   const _rscStart = performance.now();
@@ -286,7 +260,6 @@ export async function renderRoute(
       signals,
       segments,
       layoutComponents,
-      headElements,
       match,
       responseHeaders,
       skippedSegments

package/src/server/rsc-entry/revalidate-renderer.ts

@@ -26,6 +26,8 @@
  * design/13-security.md §"Server actions silently bypass middleware".
  */
 
+import { stringifyCookie } from 'cookie';
+
 import type { BuildManifest } from '../build-manifest.js';
 import { canonicalize } from '../canonicalize.js';
 import { getCookiesForSsr, seedRequestCookies } from '../cookie-context.js';
@@ -116,18 +118,22 @@ export function validateRevalidatePath(path: unknown): PathValidation {
  * Serialize a cookie map into a `Cookie:` request header value
  * (`name1=value1; name2=value2`).
  *
- * Cookie values are RFC 6265 cookie-octet (no `;`, no `,`, no whitespace,
- * no `"` / `\`) by construction — `assertValidCookieValue()` rejects
- * anything else at write time. Names are validated similarly. Joining
- * with `; ` is therefore safe and cannot be used to smuggle additional
- * cookies via a malformed value.
+ * The RYW map holds decoded logical values (decodeURIComponent has
+ * already run), so we use the default encode (encodeURIComponent) to
+ * re-encode for the wire — mirroring getCookieJar().toString().
+ *
+ * Total — never throws. Malformed inbound cookie names (e.g. spaces)
+ * survive parseCookie but make stringifyCookie throw, so we fall back
+ * to a manual join to stay total over arbitrary request headers.
  */
 function serializeCookieMap(cookies: Map<string, string>): string {
-  const parts: string[] = [];
-  cookies.forEach((value, name) => {
-    parts.push(`${name}=${value}`);
-  });
-  return parts.join('; ');
+  try {
+    return stringifyCookie(Object.fromEntries(cookies));
+  } catch {
+    return Array.from(cookies.entries())
+      .map(([name, value]) => `${name}=${encodeURIComponent(value)}`)
+      .join('; ');
+  }
 }
 
 /** Dependencies for the revalidate renderer factory. */
@@ -337,7 +343,6 @@ export function createRevalidateRendererFactory(
       );
       return {
         element: routeResult.element,
-        headElements: routeResult.headElements,
       };
     };
   };

package/src/server/rsc-entry/rsc-payload.ts

@@ -5,16 +5,14 @@
  * returned directly without SSR HTML rendering. The client decodes it via
  * `createFromFetch` and renders into the hydrated React root.
  *
- * Design docs: 19-client-navigation.md §"RSC Payload Handling",
- *              16-metadata.md §"Head Elements"
+ * Design docs: 19-client-navigation.md §"RSC Payload Handling"
  */
 
 import type { LayoutEntry } from '../deny-renderer.js';
 import { renderDenyPageAsRsc } from '../deny-renderer.js';
 import type { RouteMatch } from '../pipeline.js';
-import { encodeHeadHeader, HEAD_HEADER } from '../../shared/head-header.js';
 import type { RedirectSignal } from '../primitives.js';
-import type { HeadElement, LayoutComponentEntry } from '../route-element-builder.js';
+import type { LayoutComponentEntry } from '../route-element-builder.js';
 import type { ManifestSegmentNode } from '../route-matcher.js';
 
 import {
@@ -40,7 +38,6 @@ export async function buildRscPayloadResponse(
   signals: RenderSignals,
   segments: ManifestSegmentNode[],
   layoutComponents: LayoutComponentEntry[],
-  headElements: HeadElement[],
   match: RouteMatch,
   responseHeaders: Headers,
   skippedSegments?: string[]
@@ -175,12 +172,9 @@ export async function buildRscPayloadResponse(
 
   responseHeaders.set('content-type', `${RSC_CONTENT_TYPE}; charset=utf-8`);
 
-  // Send resolved head elements so the client can update document.title
-  // and <meta> tags after SPA navigation. See design/16-metadata.md.
-  const encodedHead = encodeHeadHeader(headElements);
-  if (encodedHead !== null) {
-    responseHeaders.set(HEAD_HEADER, encodedHead);
-  }
+  // Metadata (<title>/<meta>/<link>) now rides the RSC Flight payload as
+  // React elements — React 19 Float manages them in document.head during
+  // client rendering. No X-Timber-Head header needed. See TIM-1151.
 
   // Send segment metadata so the client can populate its segment cache
   // for state tree diffing on subsequent navigations.

package/src/server/sitemap-generator.ts

@@ -6,7 +6,7 @@
  *
  * Features:
  * - Collects all static page routes automatically
- * - Calls `generateStaticParams()` on dynamic routes to enumerate URLs
+ * - Calls `generateStaticSegmentParams()` on dynamic routes to enumerate URLs
  * - Skips API routes (route.ts), layout-only segments, slots, intercepting routes
  * - Skips auth-protected routes (access.ts in segment chain) by default
  * - Automatic pagination: sitemap index when > 50,000 URLs
@@ -42,12 +42,12 @@ export interface SitemapEntry {
 
 /**
  * A route discovered during tree walk that may need async resolution
- * (dynamic routes with generateStaticParams).
+ * (dynamic routes with generateStaticSegmentParams).
  */
 export interface SitemapRoute {
   /** The URL path pattern (e.g., '/products/[id]'). */
   urlPath: string;
-  /** Whether this route has dynamic segments that need generateStaticParams. */
+  /** Whether this route has dynamic segments that need generateStaticSegmentParams. */
   isDynamic: boolean;
   /** Loader for the page module (from route manifest). */
   pageLoader?: { load: () => Promise<unknown>; filePath: string };
@@ -78,7 +78,7 @@ export const URLS_PER_SITEMAP = 50_000;
  * Walk the route tree and collect all routes eligible for the sitemap.
  *
  * Pure synchronous function — no module loading. Returns routes that may
- * need async resolution (dynamic routes with generateStaticParams).
+ * need async resolution (dynamic routes with generateStaticSegmentParams).
  *
  * @param root - The root segment node from the route tree
  * @param config - Sitemap configuration
@@ -159,7 +159,7 @@ export function hasDynamicSegments(urlPath: string): boolean {
  * Resolve sitemap routes into concrete URLs.
  *
  * For static routes, the URL is derived directly from the path.
- * For dynamic routes, calls `generateStaticParams()` from the page module.
+ * For dynamic routes, calls `generateStaticSegmentParams()` from the page module.
  *
  * @param routes - Routes collected by collectSitemapRoutes
  * @param config - Sitemap configuration
@@ -184,12 +184,18 @@ export async function resolveSitemapUrls(
         priority: config.defaultPriority,
       });
     } else if (loadModule && route.pageLoader) {
-      // Dynamic route — try to call generateStaticParams
+      // Dynamic route — try to call generateStaticSegmentParams
       try {
         const mod = await loadModule(route.pageLoader);
-        const generateFn = mod.generateStaticParams;
+        let generateFn = mod.generateStaticSegmentParams;
+        if (typeof generateFn !== 'function' && typeof mod.generateStaticParams === 'function') {
+          generateFn = mod.generateStaticParams;
+          console.warn(
+            `[timber] ${route.pageLoader.filePath}: generateStaticParams is deprecated — rename to generateStaticSegmentParams`
+          );
+        }
         if (typeof generateFn !== 'function') {
-          // No generateStaticParams export — skip this dynamic route
+          // No generateStaticSegmentParams export — skip this dynamic route
           continue;
         }
 
@@ -208,7 +214,7 @@ export async function resolveSitemapUrls(
         // Log and skip — don't fail the entire sitemap for one bad route
         const filePath = route.pageLoader.filePath;
         console.warn(
-          `[timber] sitemap: failed to call generateStaticParams for ${filePath}:`,
+          `[timber] sitemap: failed to call generateStaticSegmentParams for ${filePath}:`,
           error instanceof Error ? error.message : error
         );
       }
@@ -286,7 +292,7 @@ export function resolvePathWithParams(
  *
  * @param root - The root segment node from the route tree
  * @param config - Sitemap configuration
- * @param loadModule - Optional async function to load page modules (for generateStaticParams)
+ * @param loadModule - Optional async function to load page modules (for generateStaticSegmentParams)
  * @returns The sitemap result (single or index with pages)
  */
 export async function generateSitemap(

package/src/server/tracing.ts

@@ -163,6 +163,50 @@ export async function initDevTracing(
   globals[DEV_TRACING_INIT_KEY] = true;
 }
 
+// ─── Platform Tracer ─────────────────────────────────────────────────────
+
+/**
+ * A native platform span. Mirrors the subset of the Cloudflare Workers
+ * `Span` API that timber uses. See design/17-logging.md §"Cloudflare Native
+ * Spans" and TIM-1135.
+ */
+export interface PlatformSpan {
+  setAttribute(key: string, value: string | number | boolean): void;
+}
+
+/**
+ * Adapter-provided native tracer. Callback-scoped like Cloudflare's
+ * `tracing.enterSpan()` — the span starts when the callback is invoked and
+ * ends when it returns or its promise settles. Nesting follows the
+ * platform's async context.
+ *
+ * When registered, withSpan() wraps every framework span in a native span
+ * *in addition to* the OTEL emission — dual emission, so external OTEL
+ * collectors keep working alongside the platform's native trace view.
+ *
+ * Register via setPlatformTracer(), or by writing the
+ * Symbol.for('timber:platform-tracer') key on globalThis from
+ * adapter-generated entry code (what the Cloudflare _worker.js does).
+ */
+export interface PlatformTracer {
+  enterSpan<T>(name: string, fn: (span: PlatformSpan) => T): T;
+}
+
+// globalThis + Symbol.for so a tracer registered by adapter-generated entry
+// code (a separate module instance) is visible in both the RSC and SSR
+// environments — same pattern as the cf-bindings ALS.
+const PLATFORM_TRACER_KEY = Symbol.for('timber:platform-tracer');
+
+/** Register (or clear) the native platform tracer for this runtime. */
+export function setPlatformTracer(tracer: PlatformTracer | undefined): void {
+  (globalThis as Record<symbol, unknown>)[PLATFORM_TRACER_KEY] = tracer;
+}
+
+/** The registered native platform tracer, if any. */
+export function getPlatformTracer(): PlatformTracer | undefined {
+  return (globalThis as Record<symbol, unknown>)[PLATFORM_TRACER_KEY] as PlatformTracer | undefined;
+}
+
 // ─── OTEL Span Helpers ───────────────────────────────────────────────────
 
 /**
@@ -205,19 +249,54 @@ export async function getTracer(): Promise<import('@opentelemetry/api').Tracer |
 }
 
 /**
- * Run a function within an OTEL span. If OTEL is not available, runs the function
- * directly without any span overhead.
+ * Run a function within a framework span. Composes two emission channels:
+ *
+ * - **Native platform span** — when an adapter registered a PlatformTracer
+ *   (Cloudflare Workers), the fn is wrapped in platformTracer.enterSpan()
+ *   so it appears in the platform's native trace view.
+ * - **OTEL span** — when an OTEL SDK is active, the fn also runs inside an
+ *   OTEL span (dual emission). No SDK and no platform tracer = zero overhead.
  *
  * Automatically:
  * - Creates the span as a child of the current context
  * - Updates the ALS span ID for log–trace correlation
  * - Ends the span when the function completes
- * - Records exceptions on error
+ * - Records exceptions on error (OTEL channel)
  */
 export async function withSpan<T>(
   name: string,
   attributes: Record<string, string | number | boolean>,
   fn: () => T | Promise<T>
+): Promise<T> {
+  const platformTracer = getPlatformTracer();
+  if (!platformTracer) {
+    return runOtelSpan(name, attributes, fn);
+  }
+
+  // Native platform span wraps the OTEL emission (dual emission). The
+  // innermost platform span is tracked on the trace store so
+  // setSpanAttribute() can reach it after creation — the platform API has
+  // no getActiveSpan() equivalent.
+  return platformTracer.enterSpan(name, async (span) => {
+    for (const key of Object.keys(attributes)) {
+      span.setAttribute(key, attributes[key]);
+    }
+    const store = traceAls.getStore();
+    const prevPlatformSpan = store?.platformSpan;
+    if (store) store.platformSpan = span;
+    try {
+      return await runOtelSpan(name, attributes, fn);
+    } finally {
+      if (store) store.platformSpan = prevPlatformSpan;
+    }
+  });
+}
+
+/** The OTEL half of withSpan() — no-op passthrough when no SDK is active. */
+async function runOtelSpan<T>(
+  name: string,
+  attributes: Record<string, string | number | boolean>,
+  fn: () => T | Promise<T>
 ): Promise<T> {
   const tracer = await getTracer();
   if (!tracer) {
@@ -253,6 +332,12 @@ export async function setSpanAttribute(
   key: string,
   value: string | number | boolean
 ): Promise<void> {
+  // Forward to the innermost active native platform span, if any.
+  const platformSpan = traceAls.getStore()?.platformSpan;
+  if (platformSpan) {
+    platformSpan.setAttribute(key, value);
+  }
+
   const api = await getOtelApi();
   if (!api) return;