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

package/src/cache/tag-aware-handler.ts

@@ -0,0 +1,233 @@
+/**
+ * TagAwareCacheHandler — wraps any CacheStore and adds tag-based invalidation.
+ *
+ * Three strategies, selected by store capabilities (best available wins):
+ *
+ * 1. **Native** (store has setWithTags + invalidateTag): Delegates entirely.
+ *    The store owns tag indexing. Used for Vercel Runtime Cache, DO-backed
+ *    stores, or any platform with first-class tag support.
+ *
+ * 2. **Eager** (store has sadd/smembers/srem/sdel): Maintains an inverted
+ *    index via atomic set operations. Invalidation enumerates the set and
+ *    deletes entries. Used for Redis.
+ *
+ * 3. **Lazy** (bare get/set/del only): Version-stamps entries with tag
+ *    counters. Invalidation bumps a counter (O(1)). Reads validate stored
+ *    versions against current. Race-free, correct under eventual consistency.
+ *    Used for Cloudflare KV.
+ *
+ * Implements the CacheHandler interface consumed by timber-cache.ts.
+ */
+
+import type { CacheHandler } from './index';
+import type { CacheStore } from './store';
+
+const DATA_PREFIX = 'd:';
+const TAG_SET_PREFIX = 'ts:';
+const TAG_VERSION_PREFIX = 'tv:';
+
+type Strategy = 'native' | 'eager' | 'lazy';
+
+/** Stored entry format for eager strategy. */
+interface EagerEntry {
+  value: unknown;
+  expiresAt: number;
+  tags: string[];
+}
+
+/** Stored entry format for lazy (version-stamp) strategy. */
+interface LazyEntry {
+  value: unknown;
+  expiresAt: number;
+  tags: string[];
+  tagVersions: Record<string, number>;
+}
+
+function detectStrategy(store: CacheStore): Strategy {
+  if (store.setWithTags && store.invalidateTag) return 'native';
+  if (store.sadd && store.smembers && store.srem && store.sdel) return 'eager';
+  return 'lazy';
+}
+
+export class TagAwareCacheHandler implements CacheHandler {
+  private store: CacheStore;
+  private prefix: string;
+  private strategy: Strategy;
+
+  constructor(store: CacheStore, opts?: { prefix?: string }) {
+    this.store = store;
+    this.prefix = opts?.prefix ?? 'timber:';
+    this.strategy = detectStrategy(store);
+  }
+
+  get consistency(): 'strong' | 'eventual' | 'local' {
+    return this.store.consistency;
+  }
+
+  private dataKey(key: string): string {
+    return `${this.prefix}${DATA_PREFIX}${key}`;
+  }
+
+  /** Namespace tags for native stores so prefix isolates shared stores. */
+  private prefixTags(tags: string[]): string[] {
+    return tags.map((t) => `${this.prefix}${t}`);
+  }
+
+  private tagSetKey(tag: string): string {
+    return `${this.prefix}${TAG_SET_PREFIX}${tag}`;
+  }
+
+  private tagVersionKey(tag: string): string {
+    return `${this.prefix}${TAG_VERSION_PREFIX}${tag}`;
+  }
+
+  async get(key: string): Promise<{ value: unknown; stale: boolean } | null> {
+    const raw = await this.store.get(this.dataKey(key));
+    if (raw === null) return null;
+
+    if (this.strategy === 'native' || this.strategy === 'eager') {
+      const entry = JSON.parse(raw) as EagerEntry;
+      const stale = Date.now() > entry.expiresAt;
+      return { value: entry.value, stale };
+    }
+
+    // Lazy: validate tag versions before returning
+    const entry = JSON.parse(raw) as LazyEntry;
+    if (entry.tags.length > 0) {
+      const currentVersions = await this.getTagVersions(entry.tags);
+      for (const tag of entry.tags) {
+        const stored = entry.tagVersions[tag] ?? 0;
+        const current = currentVersions[tag] ?? 0;
+        if (current > stored) return null;
+      }
+    }
+    const stale = Date.now() > entry.expiresAt;
+    return { value: entry.value, stale };
+  }
+
+  async set(key: string, value: unknown, opts: { ttl: number; tags: string[] }): Promise<void> {
+    const physicalTtl = Math.max(opts.ttl * 2 + 60, 120);
+
+    if (this.strategy === 'native') {
+      const entry: EagerEntry = {
+        value,
+        expiresAt: Date.now() + opts.ttl * 1000,
+        tags: opts.tags,
+      };
+      const payload = JSON.stringify(entry);
+      if (opts.tags.length > 0) {
+        await this.store.setWithTags!(
+          this.dataKey(key),
+          payload,
+          physicalTtl,
+          this.prefixTags(opts.tags)
+        );
+      } else {
+        await this.store.set(this.dataKey(key), payload, physicalTtl);
+      }
+      return;
+    }
+
+    if (this.strategy === 'eager') {
+      const entry: EagerEntry = {
+        value,
+        expiresAt: Date.now() + opts.ttl * 1000,
+        tags: opts.tags,
+      };
+      await this.store.set(this.dataKey(key), JSON.stringify(entry), physicalTtl);
+      if (opts.tags.length > 0) {
+        await Promise.all(
+          opts.tags.map((tag) => this.store.sadd!(this.tagSetKey(tag), [key], physicalTtl))
+        );
+      }
+      return;
+    }
+
+    // Lazy: snapshot current tag versions into the entry
+    const tagVersions = opts.tags.length > 0 ? await this.getTagVersions(opts.tags) : {};
+    const entry: LazyEntry = {
+      value,
+      expiresAt: Date.now() + opts.ttl * 1000,
+      tags: opts.tags,
+      tagVersions,
+    };
+    await this.store.set(this.dataKey(key), JSON.stringify(entry), physicalTtl);
+  }
+
+  async invalidate(opts: { key?: string; tag?: string }): Promise<void> {
+    if (opts.key) {
+      if (this.strategy === 'eager') {
+        const raw = await this.store.get(this.dataKey(opts.key));
+        if (raw !== null) {
+          const entry = JSON.parse(raw) as EagerEntry;
+          if (entry.tags.length > 0) {
+            await Promise.all(
+              entry.tags.map((tag) => this.store.srem!(this.tagSetKey(tag), [opts.key!]))
+            );
+          }
+        }
+      }
+      await this.store.del(this.dataKey(opts.key));
+    }
+
+    if (opts.tag) {
+      const tag = opts.tag;
+      if (this.strategy === 'native') {
+        await this.store.invalidateTag!(`${this.prefix}${tag}`);
+      } else if (this.strategy === 'eager') {
+        const members = await this.store.smembers!(this.tagSetKey(tag));
+        // Verify each member still carries the tag before deleting — the set
+        // can contain stale memberships from overwritten entries or LRU eviction.
+        // Remove only the snapshot members (via srem, not sdel) so concurrent
+        // writes that add new members between smembers() and cleanup are preserved.
+        await Promise.all(
+          members.map(async (k) => {
+            const raw = await this.store.get(this.dataKey(k));
+            if (raw === null) {
+              await this.store.srem!(this.tagSetKey(tag), [k]);
+              return;
+            }
+            const entry = JSON.parse(raw) as EagerEntry;
+            if (entry.tags.includes(tag)) {
+              await this.store.del(this.dataKey(k));
+              await this.store.srem!(this.tagSetKey(tag), [k]);
+            } else {
+              await this.store.srem!(this.tagSetKey(tag), [k]);
+            }
+          })
+        );
+      } else {
+        await this.bumpTagVersion(opts.tag);
+      }
+    }
+  }
+
+  // --- Lazy strategy helpers ---
+
+  private async getTagVersions(tags: string[]): Promise<Record<string, number>> {
+    const versions: Record<string, number> = {};
+    await Promise.all(
+      tags.map(async (tag) => {
+        const raw = await this.store.get(this.tagVersionKey(tag));
+        versions[tag] = raw !== null ? parseInt(raw, 10) : 0;
+      })
+    );
+    return versions;
+  }
+
+  private async bumpTagVersion(tag: string): Promise<void> {
+    const key = this.tagVersionKey(tag);
+    const raw = await this.store.get(key);
+    const stored = raw !== null ? parseInt(raw, 10) : 0;
+    // max(stored, now) + 1: strictly advancing even within the same
+    // millisecond (two bumps in 1ms produce N, N+1 not N, N). On
+    // eventually-consistent stores the read can be stale, but Date.now()
+    // provides a floor — regression only if BOTH the read is stale AND the
+    // clock is behind, bounded by the store's propagation window (~60s).
+    const version = Math.max(stored, Date.now()) + 1;
+    // Version keys must outlive all data entries stamped with them. Data
+    // entries use physical TTL of max(ttl*2+60, 120); 365 days exceeds any
+    // practical cache lifetime.
+    await this.store.set(key, String(version), 365 * 86400);
+  }
+}

package/src/cache/timber-cache.ts

@@ -160,14 +160,24 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
 
     /**
      * Run fn and store the result — exactly once per coalesced execution,
-     * inside the singleflight callback. The write is skipped when the key or
-     * any resolved tag was invalidated after fn started: storing would
-     * resurrect just-invalidated data as fresh for the full TTL.
+     * inside the singleflight callback. The write is skipped when:
+     * - the key/tags were invalidated after fn started (TIM-1028), or
+     * - the singleflight timed out (signal aborted) — the timed-out
+     *   flight's write could overwrite a newer value from a subsequent
+     *   flight (TIM-1092).
+     *
+     * Residual race: if fn() completes within the timeout but
+     * handler.set() is slow enough that the timeout fires during the
+     * set, the write lands with stale data. This window is narrow
+     * (requires set latency to straddle the timeout boundary) and
+     * self-healing (next cache miss triggers a fresh write). Fully
+     * closing it requires CAS/versioned writes on CacheHandler —
+     * tracked in TIM-1158.
      */
-    const executeAndStore = async (): Promise<Awaited<ReturnType<Fn>>> => {
+    const executeAndStore = async (signal: AbortSignal): Promise<Awaited<ReturnType<Fn>>> => {
       const startEpoch = currentInvalidationEpoch();
       const result = await fn(...args);
-      if (!wasInvalidatedSince(startEpoch, key, tags)) {
+      if (!signal.aborted && !wasInvalidatedSince(startEpoch, key, tags)) {
         await getHandler().set(key, result, { ttl: opts.ttl, tags });
       }
       return result;
@@ -182,9 +192,9 @@ export function createCache<Fn extends (...args: any[]) => Promise<any>>(
       });
       // Serve stale immediately, trigger background refetch
       const refetch = sf
-        .do(`swr:${flightKey}`, async () => {
+        .do(`swr:${flightKey}`, async (signal) => {
           try {
-            await executeAndStore();
+            await executeAndStore(signal);
           } catch (err) {
             // Failed refetch — stale entry continues to be served.
             logSwrRefetchFailed({ cacheKey: key, error: err });

package/src/cdn/cloudflare-purge.ts

@@ -0,0 +1,50 @@
+/**
+ * Cloudflare CDN purge handler — purges by cache tag via the Cloudflare API.
+ *
+ * Requires Cloudflare Enterprise for tag-based purging.
+ * See https://developers.cloudflare.com/cache/how-to/purge-cache/purge-by-tags/
+ */
+
+import type { CdnPurgeHandler } from './purge-store';
+
+export interface CloudflarePurgeOptions {
+  /** Cloudflare zone ID. */
+  zoneId: string;
+  /** API token with Cache Purge permission. */
+  apiToken: string;
+  /** Override fetch for testing. */
+  fetch?: typeof globalThis.fetch;
+}
+
+export class CloudflarePurge implements CdnPurgeHandler {
+  private readonly zoneId: string;
+  private readonly apiToken: string;
+  private readonly _fetch: typeof globalThis.fetch;
+
+  constructor(opts: CloudflarePurgeOptions) {
+    this.zoneId = opts.zoneId;
+    this.apiToken = opts.apiToken;
+    this._fetch = opts.fetch ?? globalThis.fetch;
+  }
+
+  async purgeTags(tags: string[]): Promise<void> {
+    if (tags.length === 0) return;
+
+    const res = await this._fetch(
+      `https://api.cloudflare.com/client/v4/zones/${this.zoneId}/purge_cache`,
+      {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${this.apiToken}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ tags }),
+      }
+    );
+
+    if (!res.ok) {
+      const body = await res.text();
+      throw new Error(`Cloudflare purge failed (${res.status}): ${body}`);
+    }
+  }
+}

package/src/cdn/fastly-purge.ts

@@ -0,0 +1,63 @@
+/**
+ * Fastly CDN purge handler — purges by surrogate key via the Fastly API.
+ *
+ * See https://www.fastly.com/documentation/reference/api/purging/
+ */
+
+import type { CdnPurgeHandler } from './purge-store';
+
+export interface FastlyPurgeOptions {
+  /** Fastly service ID. */
+  serviceId: string;
+  /** Fastly API token with purge permission. */
+  apiToken: string;
+  /** Use soft purge (marks as stale instead of immediate delete). Default: false. */
+  softPurge?: boolean;
+  /** Override fetch for testing. */
+  fetch?: typeof globalThis.fetch;
+}
+
+export class FastlyPurge implements CdnPurgeHandler {
+  private readonly serviceId: string;
+  private readonly apiToken: string;
+  private readonly softPurge: boolean;
+  private readonly _fetch: typeof globalThis.fetch;
+
+  constructor(opts: FastlyPurgeOptions) {
+    this.serviceId = opts.serviceId;
+    this.apiToken = opts.apiToken;
+    this.softPurge = opts.softPurge ?? false;
+    this._fetch = opts.fetch ?? globalThis.fetch;
+  }
+
+  async purgeTags(tags: string[]): Promise<void> {
+    if (tags.length === 0) return;
+
+    const results = await Promise.allSettled(
+      tags.map((tag) =>
+        this._fetch(
+          `https://api.fastly.com/service/${this.serviceId}/purge/${encodeURIComponent(tag)}`,
+          {
+            method: 'POST',
+            headers: {
+              'Fastly-Key': this.apiToken,
+              ...(this.softPurge ? { 'Fastly-Soft-Purge': '1' } : {}),
+            },
+          }
+        ).then(async (res) => {
+          if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`Fastly purge failed for tag "${tag}" (${res.status}): ${body}`);
+          }
+        })
+      )
+    );
+
+    const failures = results.filter((r): r is PromiseRejectedResult => r.status === 'rejected');
+    if (failures.length > 0) {
+      throw new Error(
+        `Fastly purge failed for ${failures.length}/${tags.length} tags: ${failures.map((f) => f.reason?.message).join('; ')}`
+      );
+    }
+  }
+}

package/src/cdn/headers.ts

@@ -0,0 +1,127 @@
+/**
+ * CDN header helpers — pure functions that build Cache-Control,
+ * CDN-Cache-Control, Surrogate-Control, and Surrogate-Key header values.
+ *
+ * These are developer-elected utilities for wiring CDN caching in
+ * proxy.ts / middleware.ts. The framework never sets these automatically.
+ * See design/25-production-deployments.md §Layer 2.
+ */
+
+export interface CacheControlOptions {
+  /** Mark the response as publicly cacheable (CDN, shared caches). */
+  public?: boolean;
+  /** Mark the response as private (browser cache only, not CDN). */
+  private?: boolean;
+  /** Max freshness in seconds for the browser/client. */
+  maxAge?: number;
+  /** Max freshness in seconds for shared caches (CDN, proxy). Overrides maxAge for CDNs. */
+  sMaxAge?: number;
+  /** Serve stale while revalidating in the background (seconds). */
+  staleWhileRevalidate?: number;
+  /** Serve stale on upstream error (seconds). */
+  staleIfError?: number;
+  /** Response must not be stored by any cache. */
+  noStore?: boolean;
+  /** Caches must revalidate before using a stored response. */
+  noCache?: boolean;
+  /** Caches must revalidate once stale — no serving stale without checking origin. */
+  mustRevalidate?: boolean;
+  /** Response will not change — allows aggressive caching. Pair with hashed URLs. */
+  immutable?: boolean;
+}
+
+/**
+ * Build a `Cache-Control` header value.
+ *
+ * ```ts
+ * ctx.headers.set('Cache-Control', cacheControl({
+ *   public: true,
+ *   maxAge: 300,
+ *   staleWhileRevalidate: 60,
+ * }));
+ * ```
+ */
+export function cacheControl(opts: CacheControlOptions): string {
+  if (opts.public && opts.private) {
+    throw new Error('cacheControl: public and private are mutually exclusive');
+  }
+  if (opts.noStore && opts.maxAge !== undefined) {
+    throw new Error('cacheControl: noStore makes maxAge meaningless — remove one');
+  }
+
+  const parts: string[] = [];
+
+  parts.push(opts.public ? 'public' : 'private');
+
+  if (opts.noStore) parts.push('no-store');
+  if (opts.noCache) parts.push('no-cache');
+  if (opts.maxAge !== undefined) parts.push(`max-age=${opts.maxAge}`);
+  if (opts.sMaxAge !== undefined) parts.push(`s-maxage=${opts.sMaxAge}`);
+  if (opts.staleWhileRevalidate !== undefined)
+    parts.push(`stale-while-revalidate=${opts.staleWhileRevalidate}`);
+  if (opts.staleIfError !== undefined) parts.push(`stale-if-error=${opts.staleIfError}`);
+  if (opts.mustRevalidate) parts.push('must-revalidate');
+  if (opts.immutable) parts.push('immutable');
+
+  return parts.join(', ');
+}
+
+export interface SurrogateControlOptions {
+  /** Max freshness in seconds for the surrogate (CDN). */
+  maxAge?: number;
+  /** Do not store in surrogate cache. */
+  noStore?: boolean;
+  /** Serve stale while revalidating (seconds). */
+  staleWhileRevalidate?: number;
+  /** Serve stale on error (seconds). */
+  staleIfError?: number;
+}
+
+/**
+ * Build a `Surrogate-Control` header value (Fastly, Akamai, Varnish).
+ *
+ * ```ts
+ * ctx.headers.set('Surrogate-Control', surrogateControl({ maxAge: 3600 }));
+ * ```
+ */
+export function surrogateControl(opts: SurrogateControlOptions): string {
+  const parts: string[] = [];
+  if (opts.noStore) parts.push('no-store');
+  if (opts.maxAge !== undefined) parts.push(`max-age=${opts.maxAge}`);
+  if (opts.staleWhileRevalidate !== undefined)
+    parts.push(`stale-while-revalidate=${opts.staleWhileRevalidate}`);
+  if (opts.staleIfError !== undefined) parts.push(`stale-if-error=${opts.staleIfError}`);
+  return parts.join(', ');
+}
+
+/**
+ * Build a `CDN-Cache-Control` header value (Cloudflare).
+ * Same directive syntax as Surrogate-Control but recognized by Cloudflare.
+ *
+ * ```ts
+ * ctx.headers.set('CDN-Cache-Control', cdnCacheControl({ maxAge: 3600 }));
+ * ```
+ */
+export function cdnCacheControl(opts: SurrogateControlOptions): string {
+  return surrogateControl(opts);
+}
+
+/**
+ * Build a `Surrogate-Key` header value — space-separated tags for CDN
+ * tag-based purging (Fastly, Cloudflare Enterprise, Akamai).
+ *
+ * Tags are deduplicated. Tags must not contain spaces or double quotes
+ * (these are separators/delimiters in the header format).
+ *
+ * ```ts
+ * ctx.headers.set('Surrogate-Key', surrogateKey(['products', `product:${id}`]));
+ * ```
+ */
+export function surrogateKey(tags: string[]): string {
+  for (const tag of tags) {
+    if (tag.includes(' ') || tag.includes('"')) {
+      throw new Error(`surrogateKey: tag "${tag}" must not contain spaces or double quotes`);
+    }
+  }
+  return [...new Set(tags)].join(' ');
+}

package/src/cdn/index.ts

@@ -0,0 +1,16 @@
+// @timber-js/app/cdn — CDN integration helpers
+//
+// Header utilities and purge handler for CDN caching. Developer-elected,
+// never automatic. See design/25-production-deployments.md §Layer 2.
+
+export { cacheControl, surrogateKey, surrogateControl, cdnCacheControl } from './headers';
+export type { CacheControlOptions, SurrogateControlOptions } from './headers';
+
+export { setCdnPurgeHandler, getCdnPurgeHandler } from './purge-store';
+export type { CdnPurgeHandler } from './purge-store';
+
+// Platform-specific purge handlers are at their own entry points:
+//   @timber-js/app/cdn/cloudflare → CloudflarePurge
+//   @timber-js/app/cdn/fastly     → FastlyPurge
+// Same pattern as @timber-js/app/cache/stores/* — keeps platform
+// dependencies out of the main CDN import.

package/src/cdn/purge-store.ts

@@ -0,0 +1,34 @@
+/**
+ * CDN purge handler singleton — same pattern as cache/handler-store.ts.
+ *
+ * Set via timber.config.ts or setCdnPurgeHandler() at boot. When set,
+ * cache.invalidate({ tag }) also triggers CDN purge for the invalidated
+ * tags, so revalidateTag() composes with CDN caching out of the box.
+ *
+ * See design/25-production-deployments.md §Layer 2.
+ */
+
+export interface CdnPurgeHandler {
+  /**
+   * Purge the given cache tags from the CDN.
+   * Called by cache.invalidate when a tag is invalidated.
+   */
+  purgeTags(tags: string[]): Promise<void>;
+}
+
+let handler: CdnPurgeHandler | undefined;
+
+/** Install a CDN purge handler. Called by the framework at boot from timber.config.ts. */
+export function setCdnPurgeHandler(h: CdnPurgeHandler): void {
+  handler = h;
+}
+
+/** Get the current CDN purge handler, if configured. */
+export function getCdnPurgeHandler(): CdnPurgeHandler | undefined {
+  return handler;
+}
+
+/** @internal — reset for tests only. */
+export function _resetCdnPurgeHandler(): void {
+  handler = undefined;
+}

package/src/client/browser-entry/action-dispatch.ts

@@ -18,9 +18,6 @@ import { setServerCallback, encodeReply, createFromFetch } from '../../rsc-runti
 import { getRouter, getRouterOrNull } from '#client-internal';
 import { setHardNavigating } from '../navigation-root.js';
 import { getClientDeploymentId, DEPLOYMENT_ID_HEADER, RELOAD_HEADER } from '../rsc-fetch.js';
-import { decodeHeadHeader, HEAD_HEADER } from '../../shared/head-header.js';
-import type { HeadElement } from '../head.js';
-
 export function setupServerActions(): void {
   setServerCallback(async (id: string, args: unknown[]) => {
     const body = await encodeReply(args);
@@ -30,7 +27,6 @@ export function setupServerActions(): void {
     // consumes the body stream.
     let hasRevalidation = false;
     let hasRedirect = false;
-    let headElementsJson: string | null = null;
 
     // Build action request headers. Include deployment ID for version
     // skew detection (TIM-446) — the server rejects stale actions gracefully.
@@ -56,7 +52,6 @@ export function setupServerActions(): void {
       }
       hasRevalidation = res.headers.get('X-Timber-Revalidation') === '1';
       hasRedirect = res.headers.get('X-Timber-Redirect') != null;
-      headElementsJson = res.headers.get(HEAD_HEADER);
       return res;
     });
 
@@ -104,11 +99,7 @@ export function setupServerActions(): void {
       const router = getRouterOrNull();
       if (router) {
         try {
-          // Percent-encoded JSON — same wire format as the navigation path.
-          // A malformed header decodes to null (head update skipped), it
-          // does not fail the revalidation. See TIM-1058.
-          const headElements = decodeHeadHeader(headElementsJson) as HeadElement[] | null;
-          router.applyRevalidation(wrapper._tree, headElements);
+          router.applyRevalidation(wrapper._tree);
         } catch (e) {
           console.error('[timber] applyRevalidation failed after server action', e);
         }

package/src/client/browser-entry/post-hydration.ts

@@ -40,7 +40,6 @@ export function setupPostHydration({
   // useSegmentParams() consumer on the initial page (TIM-1037).
   router.historyStack.push(window.location.pathname + window.location.search, {
     payload: initialElement,
-    headElements: null, // SSR already set the correct head
     params: getNavigationState().params,
   });
 

package/src/client/browser-entry/router-init.ts

@@ -12,7 +12,6 @@ import { createFromFetch } from '../../rsc-runtime/browser.js';
 import { createRouter, setGlobalRouter } from '#client-internal';
 import type { RouterDeps, RouterInstance } from '#client-internal';
 import type { NavigationState } from '#client-internal';
-import { applyHeadElements } from '../head.js';
 import { TimberNuqsAdapter } from '../nuqs-adapter.js';
 import {
   NavigationProvider,
@@ -243,10 +242,6 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
         requestAnimationFrame(callback);
       });
     },
-
-    // Apply resolved head elements (title, meta tags) to the DOM after
-    // SPA navigation. See design/16-metadata.md.
-    applyHead: applyHeadElements,
   };
 
   const router = createRouter(deps);

package/src/client/history.ts

@@ -1,15 +1,11 @@
 // History Stack — stores RSC payloads by URL for instant back/forward navigation
 // See design/19-client-navigation.md § History Stack
 
-import type { HeadElement } from './head';
-
 // ─── Types ───────────────────────────────────────────────────────
 
 export interface HistoryEntry {
   /** The complete segment tree payload at the time of navigation */
   payload: unknown;
-  /** Resolved head elements for this page (title, meta tags). Null for SSR'd initial page. */
-  headElements?: HeadElement[] | null;
   /**
    * Route params for this page (for useSegmentParams). Every entry that can
    * be replayed must carry them — the initial SSR entry gets them from the