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

package/src/client/navigation-api.ts

@@ -17,7 +17,6 @@
  * See design/19-client-navigation.md
  */
 
-import type { NavigationApi, NavigateEvent } from './navigation-api-types.js';
 import { isHardNavigating } from './navigation-root.js';
 
 // ─── Feature Detection ───────────────────────────────────────────
@@ -27,20 +26,15 @@ import { isHardNavigating } from './navigation-root.js';
  * Feature-detected at runtime — no polyfill.
  */
 export function hasNavigationApi(): boolean {
-  return (
-    typeof window !== 'undefined' &&
-    'navigation' in window &&
-    (window as unknown as { navigation: unknown }).navigation != null
-  );
+  return typeof window !== 'undefined' && 'navigation' in window && window.navigation != null;
 }
 
 /**
  * Get the Navigation API instance. Returns null if unavailable.
- * Uses type assertion — we never import Navigation API types unconditionally.
  */
-export function getNavigationApi(): NavigationApi | null {
+export function getNavigationApi(): Navigation | null {
   if (!hasNavigationApi()) return null;
-  return (window as unknown as { navigation: NavigationApi }).navigation;
+  return window.navigation;
 }
 
 // ─── Navigation API Controller ───────────────────────────────────
@@ -285,7 +279,7 @@ export function setupNavigationApi(callbacks: NavigationApiCallbacks): Navigatio
     }
   }
 
-  nav.addEventListener('navigate', handleNavigate as EventListener);
+  nav.addEventListener('navigate', handleNavigate);
 
   return {
     setRouterNavigating(value: boolean): void {
@@ -341,7 +335,7 @@ export function setupNavigationApi(callbacks: NavigationApiCallbacks): Navigatio
     },
 
     cleanup(): void {
-      nav.removeEventListener('navigate', handleNavigate as EventListener);
+      nav.removeEventListener('navigate', handleNavigate);
     },
   };
 }

package/src/client/router.ts

@@ -4,7 +4,6 @@
 import { SegmentCache, PrefetchCache, buildSegmentTree } from './segment-cache';
 import type { SegmentInfo } from './segment-cache';
 import { HistoryStack } from './history';
-import type { HeadElement } from './head';
 import { setCurrentParams } from './use-segment-params.js';
 import {
   setNavigationState,
@@ -82,8 +81,6 @@ export interface RouterDeps {
    * In tests, this runs the callback synchronously.
    */
   afterPaint?: (callback: () => void) => void;
-  /** Apply resolved head elements (title, meta tags) to the DOM after navigation. */
-  applyHead?: (elements: HeadElement[]) => void;
   /**
    * Run a navigation inside a React transition with optimistic pending URL.
    * The pending URL shows immediately (useOptimistic urgent update) and
@@ -180,7 +177,7 @@ export interface RouterInstance {
    * Renders the element tree and updates head elements without a server fetch.
    * See design/08-forms-and-actions.md §"Single-Roundtrip Revalidation".
    */
-  applyRevalidation(element: unknown, headElements: HeadElement[] | null): void;
+  applyRevalidation(element: unknown): void;
   /**
    * Populate the segment cache from server-provided segment metadata.
    * Called on initial hydration with segment info embedded in the HTML.
@@ -364,27 +361,19 @@ export function createRouter(deps: RouterDeps): RouterInstance {
    * FetchResult plus the NavigationState (so it can be passed explicitly
    * to wrapPayload/renderRoot without temporal coupling).
    */
-  interface TransitionResult {
-    headElements: HeadElement[] | null;
-    decodePromise: Promise<void> | null;
-  }
-
   async function renderViaTransition(
     url: string,
     perform: () => Promise<FetchResult & { navState: NavigationState }>
-  ): Promise<TransitionResult> {
+  ): Promise<void> {
     if (deps.navigateTransition) {
-      let headElements: HeadElement[] | null = null;
       await deps.navigateTransition(url, async (wrapPayload) => {
         const result = await perform();
-        headElements = result.headElements;
 
         if (isPartialNavigation(result.skippedSegments)) {
           const segmentUpdates = buildSegmentUpdates(result);
 
           historyStack.push(url, {
             payload: null,
-            headElements: result.headElements,
             params: result.params,
           });
 
@@ -402,22 +391,18 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         // Full navigation — empty updates, render the new tree.
         historyStack.push(url, {
           payload: result.payload,
-          headElements: result.headElements,
           params: result.params,
         });
         const element = wrapPayload(result.payload, result.navState);
         return { element, decodePromise: result.decodePromise };
       });
-      // decodePromise is awaited inside the transition's startTransition
-      // callback (NavigationRoot), so we don't need it here.
-      return { headElements, decodePromise: null };
+      return;
     }
     // Fallback: no transition (tests, no React tree)
     const result = await perform();
     if (isPartialNavigation(result.skippedSegments)) {
       historyStack.push(url, {
         payload: null,
-        headElements: result.headElements,
         params: result.params,
       });
     } else {
@@ -430,19 +415,10 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           : result.payload;
       historyStack.push(url, {
         payload,
-        headElements: result.headElements,
         params: result.params,
       });
       renderPayload(payload, result.navState);
     }
-    return { headElements: result.headElements, decodePromise: result.decodePromise };
-  }
-
-  /** Apply head elements (title, meta tags) to the DOM if available. */
-  function applyHead(elements: HeadElement[] | null | undefined): void {
-    if (elements && deps.applyHead) {
-      deps.applyHead(elements);
-    }
   }
 
   /** Run a callback after the next paint (after React commit). */
@@ -495,7 +471,6 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       ? {
           payload: prefetched.payload,
           decodePromise: null,
-          headElements: prefetched.headElements,
           segmentInfo: prefetched.segmentInfo ?? null,
           params: prefetched.params ?? null,
           skippedSegments: prefetched.skippedSegments ?? null,
@@ -592,7 +567,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     setPending(true, url);
 
     try {
-      const { headElements } = await renderViaTransition(fetchUrl, () =>
+      await renderViaTransition(fetchUrl, () =>
         performNavigationFetch(fetchUrl, {
           replace,
           commitUrl: url,
@@ -601,9 +576,6 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         })
       );
 
-      // Update document.title and <meta> tags with the new page's metadata
-      applyHead(headElements);
-
       // Notify nuqs adapter (and any other listeners) that navigation completed.
       window.dispatchEvent(new Event('timber:navigation-end'));
 
@@ -685,7 +657,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
     setPending(true, currentUrl);
 
     try {
-      const { headElements } = await renderViaTransition(currentUrl, async () => {
+      await renderViaTransition(currentUrl, async () => {
         // No state tree sent — server renders the complete RSC payload
         const result = await fetchRscPayload(
           currentUrl,
@@ -699,8 +671,6 @@ export function createRouter(deps: RouterDeps): RouterInstance {
         const navState = updateNavigationState(result.params, currentUrl);
         return { ...result, navState };
       });
-
-      applyHead(headElements);
     } catch (error) {
       if (isAbortError(error)) return;
       throw error;
@@ -739,7 +709,6 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       setPending(false);
       const navState = updateNavigationState(entry.params, url);
       renderPayload(entry.payload, navState);
-      applyHead(entry.headElements);
       restoreScrollAfterPaint(scrollY);
     } else {
       // No cached payload — fetch from server.
@@ -749,7 +718,7 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       const navAbort = createNavAbort(externalSignal);
       setPending(true, url);
       try {
-        const { headElements } = await renderViaTransition(url, async () => {
+        await renderViaTransition(url, async () => {
           const stateTree = segmentCache.serializeStateTree();
           const result = await fetchRscPayload(url, deps, stateTree, undefined, navAbort.signal);
           updateSegmentCache(result.segmentInfo);
@@ -758,7 +727,6 @@ export function createRouter(deps: RouterDeps): RouterInstance {
           return { ...result, navState };
         });
 
-        applyHead(headElements);
         restoreScrollAfterPaint(scrollY);
       } catch (error) {
         if (isAbortError(error)) return;
@@ -811,10 +779,10 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       return () => pendingListeners.delete(listener);
     },
     prefetch,
-    applyRevalidation(element: unknown, headElements: HeadElement[] | null): void {
+    applyRevalidation(element: unknown): void {
       // Render the piggybacked element tree from a server action response.
-      // Updates the current history entry with the fresh payload and applies
-      // head elements — same as refresh() but without a server fetch.
+      // Updates the current history entry with the fresh payload —
+      // same as refresh() but without a server fetch.
       // Revalidation payloads are already resolved (no Flight thenable),
       // so no segment merging is needed — just cache and render.
       const currentUrl = deps.getCurrentUrl();
@@ -829,11 +797,9 @@ export function createRouter(deps: RouterDeps): RouterInstance {
       // to {} (TIM-1037).
       historyStack.push(currentUrl, {
         payload: element,
-        headElements,
         params: navState.params,
       });
       renderPayload(element, navState);
-      applyHead(headElements);
     },
     initSegmentCache: (segments: SegmentInfo[]) => updateSegmentCache(segments),
     segmentCache,

package/src/client/rsc-fetch.ts

@@ -12,13 +12,11 @@
  */
 
 import type { SegmentInfo } from './segment-cache';
-import type { HeadElement } from './head';
 import type { RouterDeps } from './router';
-import { decodeHeadHeader, HEAD_HEADER } from '../shared/head-header.js';
 
 // ─── Types ───────────────────────────────────────────────────────
 
-/** Result of fetching an RSC payload — includes head elements and segment metadata. */
+/** Result of fetching an RSC payload — includes segment metadata. */
 export interface FetchResult {
   payload: unknown;
   /**
@@ -29,7 +27,6 @@ export interface FetchResult {
    * become unhandled rejections.
    */
   decodePromise: Promise<void> | null;
-  headElements: HeadElement[] | null;
   /** Segment metadata from X-Timber-Segments header for populating the segment cache. */
   segmentInfo: SegmentInfo[] | null;
   /** Route params from X-Timber-Params header for populating useSegmentParams(). */
@@ -149,20 +146,6 @@ function warnMalformedHeader(headerName: string, raw: string): void {
   }
 }
 
-/**
- * Extract head elements from the X-Timber-Head response header.
- * Returns null if the header is missing or malformed.
- */
-export function extractHeadElements(response: Response): HeadElement[] | null {
-  const header = response.headers.get(HEAD_HEADER);
-  if (!header) return null;
-  const decoded = decodeHeadHeader(header);
-  if (decoded === null) {
-    warnMalformedHeader(HEAD_HEADER, header);
-  }
-  return decoded as HeadElement[] | null;
-}
-
 /**
  * Extract segment metadata from the X-Timber-Segments response header.
  * Returns null if the header is missing or malformed.
@@ -317,9 +300,6 @@ function trackStreamCompletion(body: ReadableStream<Uint8Array>): {
  * Fetch an RSC payload from the server. If a decodeRsc function is provided,
  * the response is decoded into a React element tree via createFromFetch.
  * Otherwise, the raw response text is returned (test mode).
- *
- * Also extracts head elements from the X-Timber-Head response header
- * so the client can update document.title and <meta> tags after navigation.
  */
 export async function fetchRscPayload(
   url: string,
@@ -335,10 +315,9 @@ export async function fetchRscPayload(
     // createFromFetch takes a Promise<Response> and progressively parses
     // the RSC Flight stream as chunks arrive.
     //
-    // Intercept the response to read X-Timber-Head before createFromFetch
+    // Intercept the response to read segment metadata before createFromFetch
     // consumes the body. Reading headers does NOT consume the body stream.
     const fetchPromise = deps.fetch(rscUrl, { headers, redirect: 'manual', signal });
-    let headElements: HeadElement[] | null = null;
     let segmentInfo: SegmentInfo[] | null = null;
     let params: Record<string, string | string[]> | null = null;
     let skippedSegments: string[] | null = null;
@@ -371,7 +350,8 @@ export async function fetchRscPayload(
       if (response.headers.get('X-Timber-Error') === '1') {
         throw new ServerErrorResponse(response.status, url);
       }
-      headElements = extractHeadElements(response);
+      // Metadata (<title>/<meta>/<link>) now rides the RSC Flight payload
+      // as React elements — React 19 Float handles them. See TIM-1151.
       segmentInfo = extractSegmentInfo(response);
       params = extractParams(response);
       skippedSegments = extractSkippedSegments(response);
@@ -391,7 +371,7 @@ export async function fetchRscPayload(
       }
       return response;
     });
-    // Await headers so headElements/segmentInfo/params are populated.
+    // Await headers so segmentInfo/params are populated.
     await wrappedPromise;
     // Start decoding but do NOT await — return the in-progress thenable.
     // React can render a Flight thenable directly: it suspends on unresolved
@@ -411,7 +391,6 @@ export async function fetchRscPayload(
     return {
       payload,
       decodePromise,
-      headElements,
       segmentInfo,
       params,
       skippedSegments,
@@ -429,7 +408,6 @@ export async function fetchRscPayload(
   return {
     payload: await response.text(),
     decodePromise: null,
-    headElements: extractHeadElements(response),
     segmentInfo: extractSegmentInfo(response),
     params: extractParams(response),
     skippedSegments: extractSkippedSegments(response),

package/src/client/segment-cache.ts

@@ -1,14 +1,11 @@
 // Segment Cache — stores the mounted segment tree and prefetched payloads
 // See design/19-client-navigation.md for architecture details.
 
-import type { HeadElement } from './head';
-
 // ─── Types ───────────────────────────────────────────────────────
 
-/** A prefetched RSC result with optional head elements and segment metadata. */
+/** A prefetched RSC result with optional segment metadata. */
 export interface PrefetchResult {
   payload: unknown;
-  headElements: HeadElement[] | null;
   /** Segment metadata from X-Timber-Segments header for populating the segment cache. */
   segmentInfo?: SegmentInfo[] | null;
   /** Route params from X-Timber-Params header for populating useSegmentParams(). */

package/src/client/use-cookie.ts

@@ -9,6 +9,7 @@
  */
 
 import { useSyncExternalStore } from 'react';
+import { parseCookie, stringifySetCookie } from 'cookie';
 import { getSsrData } from './ssr-data.js';
 import { assertValidCookieName } from '../cookies/validation.js';
 
@@ -41,24 +42,29 @@ const listeners = new Map<string, Set<Listener>>();
 /** Parse a cookie name from document.cookie. */
 export function getCookieValue(name: string): string | undefined {
   if (typeof document === 'undefined') return undefined;
-  const match = document.cookie.match(
-    new RegExp('(?:^|;\\s*)' + name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '\\s*=\\s*([^;]*)')
-  );
-  return match ? decodeURIComponent(match[1]) : undefined;
+  const cookies = parseCookie(document.cookie);
+  return cookies[name];
 }
 
 /** Serialize options into a cookie string suffix. */
 export function serializeOptions(options?: ClientCookieOptions): string {
   if (!options) return '; Path=/; SameSite=Lax';
-  const parts: string[] = [];
-  parts.push(`Path=${options.path ?? '/'}`);
-  if (options.domain) parts.push(`Domain=${options.domain}`);
-  if (options.maxAge !== undefined) parts.push(`Max-Age=${options.maxAge}`);
-  if (options.expires) parts.push(`Expires=${options.expires.toUTCString()}`);
   const sameSite = options.sameSite ?? 'lax';
-  parts.push(`SameSite=${sameSite.charAt(0).toUpperCase()}${sameSite.slice(1)}`);
-  if (options.secure) parts.push('Secure');
-  return '; ' + parts.join('; ');
+  // Build a Set-Cookie string via the cookie package, then strip the
+  // `__placeholder__=` name=value prefix to get just the attributes.
+  const full = stringifySetCookie({
+    name: '__placeholder__',
+    value: '',
+    path: options.path ?? '/',
+    domain: options.domain,
+    maxAge: options.maxAge,
+    expires: options.expires,
+    sameSite,
+    secure: options.secure,
+  });
+  // Strip everything up to and including the first "; "
+  const idx = full.indexOf('; ');
+  return idx >= 0 ? full.slice(idx) : '';
 }
 
 /** Notify all subscribers for a given cookie name. */

package/src/config-types.ts

@@ -47,6 +47,8 @@ export interface TimberUserConfig {
   clientJavascript?: boolean | ClientJavascriptConfig;
   adapter?: unknown;
   cacheHandler?: unknown;
+  /** CDN purge handler — called on revalidateTag/cache.invalidate to purge CDN-cached responses. */
+  cdnPurge?: unknown;
   allowedOrigins?: string[];
   csrf?: boolean;
   limits?: {
@@ -244,7 +246,7 @@ export interface TimberUserConfig {
    * Auto-generate sitemap.xml from the route tree.
    *
    * When enabled, timber walks the file-system route tree and produces a sitemap
-   * for all discoverable pages. Dynamic routes with `generateStaticParams()` are
+   * for all discoverable pages. Dynamic routes with `generateStaticSegmentParams()` are
    * enumerated. Routes protected by `access.ts` are excluded by default.
    *
    * If a user-authored `sitemap.ts` or `sitemap.xml` exists at the app root,

package/src/config-validation.ts

@@ -31,6 +31,7 @@ const KNOWN_CONFIG_KEYS = {
   clientJavascript: true,
   adapter: true,
   cacheHandler: true,
+  cdnPurge: true,
   allowedOrigins: true,
   csrf: true,
   limits: true,