@timber-js/app 0.2.0-alpha.147 → 0.2.0-alpha.149

package/src/cli-schema-sync.ts

@@ -36,16 +36,113 @@ function walkSegments(node: SegmentNode, segments: Set<string>): void {
   }
 }
 
+/**
+ * Replace comment bodies (and optionally string contents) with spaces,
+ * preserving length and newlines so every index maps 1:1 to the original.
+ * Lets the structural scanning below ignore `segmentParams` mentions and
+ * braces inside comments/strings without a TS parser (fine pre-alpha,
+ * see TIM-1066).
+ *
+ * With `maskStrings`, string contents are blanked too — except literal
+ * 'segmentParams' strings, kept so a quoted property key stays findable.
+ */
+function maskSource(content: string, maskStrings: boolean): string {
+  const out = content.split('');
+  const n = content.length;
+  let i = 0;
+
+  const blank = (from: number, to: number): void => {
+    for (let j = from; j < to; j++) {
+      if (content[j] !== '\n') out[j] = ' ';
+    }
+  };
+
+  while (i < n) {
+    const ch = content[i];
+    const next = content[i + 1];
+    if (ch === '/' && next === '/') {
+      const start = i;
+      while (i < n && content[i] !== '\n') i++;
+      blank(start, i);
+    } else if (ch === '/' && next === '*') {
+      const start = i;
+      i += 2;
+      while (i < n && !(content[i] === '*' && content[i + 1] === '/')) i++;
+      i = Math.min(i + 2, n);
+      blank(start, i);
+    } else if (ch === '"' || ch === "'" || ch === '`') {
+      const start = i;
+      i++;
+      while (i < n && content[i] !== ch) {
+        if (content[i] === '\\') i++;
+        i++;
+      }
+      const end = i; // at closing quote (or n if unterminated)
+      if (maskStrings && content.slice(start + 1, end) !== 'segmentParams') {
+        blank(start + 1, end);
+      }
+      i++;
+    } else {
+      i++;
+    }
+  }
+  return out.join('');
+}
+
+/**
+ * Locate the `segmentParams: { ... }` block in a schema file.
+ * Returns the indices of the opening and matching closing brace, or null
+ * if no segmentParams property is found. Comments and strings are masked
+ * first, so a JSDoc example mentioning `segmentParams: { ... }` above the
+ * real defineSchema call is not mistaken for the block, and braces inside
+ * comments/strings don't skew the depth count. The search is anchored to
+ * the `defineSchema(` call when present, so helper objects with their own
+ * segmentParams property earlier in the file are skipped.
+ */
+export function findSegmentParamsBlock(
+  content: string
+): { openBrace: number; closeBrace: number } | null {
+  const masked = maskSource(content, true);
+
+  const defineCall = /\bdefineSchema\s*\(/.exec(masked);
+  const keyRe = /(['"]?)segmentParams\1\s*:\s*\{/g;
+  keyRe.lastIndex = defineCall ? defineCall.index + defineCall[0].length : 0;
+  const keyMatch = keyRe.exec(masked);
+  if (!keyMatch) return null;
+
+  const openBrace = keyMatch.index + keyMatch[0].length - 1;
+  let depth = 1;
+  let i = openBrace + 1;
+  while (i < masked.length && depth > 0) {
+    if (masked[i] === '{') depth++;
+    else if (masked[i] === '}') depth--;
+    i++;
+  }
+  if (depth > 0) return null;
+  // i now points to just after the closing brace
+  return { openBrace, closeBrace: i - 1 };
+}
+
 /**
  * Parse existing bracket keys from an app/schema.ts file.
- * Uses regex to find keys in segmentParams: { '[key]': ... } blocks.
+ * Scoped to the segmentParams: { ... } block — bracket keys elsewhere in
+ * the file (unrelated objects, comments above defineSchema) are ignored.
+ * Comments inside the block are masked, so a commented-out entry does not
+ * count as registered.
+ *
+ * The key charset matches the route classifier (segment-classify.ts):
+ * any character except `]`, so hyphenated params like '[my-param]' parse.
  */
 export function parseExistingSchemaKeys(content: string): string[] {
+  const block = findSegmentParamsBlock(content);
+  if (!block) return [];
+
+  const blockContent = maskSource(content, false).slice(block.openBrace, block.closeBrace);
   const keys: string[] = [];
   // Match quoted bracket keys like '[artistSlug]', '[...slug]', '[[...topic]]'
-  const re = /['"](\[{1,2}(?:\.{3})?\w+\]{1,2})['"]\s*:/g;
+  const re = /['"](\[{1,2}(?:\.{3})?[^\]]+\]{1,2})['"]\s*:/g;
   let m: RegExpExecArray | null;
-  while ((m = re.exec(content)) !== null) {
+  while ((m = re.exec(blockContent)) !== null) {
     keys.push(m[1]);
   }
   return keys;
@@ -121,31 +218,14 @@ function ensureCodecImport(content: string): string {
 function appendToSchema(content: string, newSegments: string[]): string {
   content = ensureCodecImport(content);
 
-  // Find "segmentParams" key position
-  const spIndex = content.indexOf('segmentParams');
-  if (spIndex === -1) {
+  const block = findSegmentParamsBlock(content);
+  if (!block) {
     throw new Error(
       '[timber] Could not find segmentParams in schema file. ' +
         'Expected a defineSchema({ segmentParams: { ... } }) call.'
     );
   }
-
-  // Find the opening brace after segmentParams
-  const openBrace = content.indexOf('{', spIndex + 'segmentParams'.length);
-  if (openBrace === -1) {
-    throw new Error('[timber] Could not find opening brace for segmentParams.');
-  }
-
-  // Count braces to find the matching close
-  let depth = 1;
-  let i = openBrace + 1;
-  while (i < content.length && depth > 0) {
-    if (content[i] === '{') depth++;
-    else if (content[i] === '}') depth--;
-    i++;
-  }
-  // i now points to just after the closing brace
-  const closeBrace = i - 1;
+  const { openBrace, closeBrace } = block;
 
   // Detect indentation from existing entries
   const existingLine = content.slice(openBrace, closeBrace).match(/^(\s+)['"]\[/m);
@@ -168,21 +248,32 @@ function appendToSchema(content: string, newSegments: string[]): string {
 
 /**
  * Remove entries from the segmentParams block whose keys match `staleSegments`.
- * Removes the entire line including trailing comma/whitespace.
+ * Removes the entire entry including trailing comma/whitespace. Scoped to
+ * the segmentParams block — identical keys in unrelated objects elsewhere
+ * in the file are left untouched.
  */
 function removeFromSchema(content: string, staleSegments: string[]): string {
+  const block = findSegmentParamsBlock(content);
+  if (!block) return content;
+
+  let blockContent = content.slice(block.openBrace, block.closeBrace);
+  // Key matching and the entry walk run on a comment-masked copy (same
+  // length, indices align) so commented-out entries are never removed.
+  // Both copies are spliced in sync to keep indices valid.
+  let blockMasked = maskSource(blockContent, false);
+
   for (const seg of staleSegments) {
     const escaped = seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     const keyRe = new RegExp(`^[ \t]*['"]${escaped}['"][ \t]*:`, 'gm');
     let m: RegExpExecArray | null;
-    while ((m = keyRe.exec(content)) !== null) {
+    while ((m = keyRe.exec(blockMasked)) !== null) {
       const start = m.index;
       let i = m.index + m[0].length;
       let depth = 0;
       let inString: string | null = null;
 
-      while (i < content.length) {
-        const ch = content[i];
+      while (i < blockMasked.length) {
+        const ch = blockMasked[i];
         if (inString) {
           if (ch === '\\') {
             i++;
@@ -205,13 +296,15 @@ function removeFromSchema(content: string, staleSegments: string[]): string {
       }
 
       // Consume trailing newline
-      if (i < content.length && content[i] === '\n') i++;
+      if (i < blockMasked.length && blockMasked[i] === '\n') i++;
 
-      content = content.slice(0, start) + content.slice(i);
+      blockContent = blockContent.slice(0, start) + blockContent.slice(i);
+      blockMasked = blockMasked.slice(0, start) + blockMasked.slice(i);
       keyRe.lastIndex = start;
     }
   }
-  return content;
+
+  return content.slice(0, block.openBrace) + blockContent + content.slice(block.closeBrace);
 }
 
 export interface SchemaSyncResult {

package/src/cli.ts

@@ -17,6 +17,8 @@ type Command = (typeof COMMANDS)[number];
 export interface ParsedArgs {
   command: Command;
   config: string | undefined;
+  /** Positional arguments after the command (used by `timber schema sync`). */
+  rest: string[];
 }
 
 export interface CommandOptions {
@@ -26,6 +28,11 @@ export interface CommandOptions {
 /**
  * Parse CLI arguments into a structured command + options.
  * Accepts: timber <command> [--config|-c <path>]
+ *
+ * Unknown flags are an error, not silently ignored — `timber dev --port 4000`
+ * starting on the default port would contradict fail-loudly. The CLI surface
+ * is intentionally --config-only (design/11-platform.md §CLI); port selection
+ * goes through the PORT env var or server.port in vite.config.ts.
  */
 export function parseArgs(args: string[]): ParsedArgs {
   if (args.length === 0) {
@@ -40,16 +47,31 @@ export function parseArgs(args: string[]): ParsedArgs {
   }
 
   let config: string | undefined;
+  const rest: string[] = [];
   for (let i = 1; i < args.length; i++) {
-    if (args[i] === '--config' || args[i] === '-c') {
+    const arg = args[i];
+    if (arg === '--config' || arg === '-c') {
       config = args[++i];
       if (!config) {
         throw new Error('--config requires a path argument');
       }
+    } else if (arg.startsWith('-')) {
+      const portHint =
+        arg === '--port' || arg === '-p'
+          ? ' To change the port, set the PORT environment variable (PORT=4000 timber dev) ' +
+            'or server.port in vite.config.ts.'
+          : '';
+      throw new Error(
+        `Unknown option: ${arg}. The timber CLI only accepts --config <path>.${portHint}`
+      );
+    } else if (command === 'schema') {
+      rest.push(arg);
+    } else {
+      throw new Error(`Unexpected argument: ${arg}. Usage: timber ${command} [--config <path>]`);
     }
   }
 
-  return { command: command as Command, config };
+  return { command: command as Command, config, rest };
 }
 
 // ─── Command Implementations ─────────────────────────────────────────────────
@@ -105,51 +127,25 @@ export function resolvePreviewStrategy(
   return 'vite';
 }
 
-/**
- * Load timber.config.ts from the project root.
- * Returns the config object with adapter, output, etc.
- * Returns null if no config file is found.
- */
-async function loadTimberConfig(root: string): Promise<{
-  adapter?: import('./adapters/types').TimberPlatformAdapter;
-  output?: string;
-  buildDir?: string;
-} | null> {
-  const { existsSync } = await import('node:fs');
-  const { join } = await import('node:path');
-  const { pathToFileURL } = await import('node:url');
-
-  const configNames = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];
-
-  for (const name of configNames) {
-    const configPath = join(root, name);
-    if (existsSync(configPath)) {
-      // Use Vite's built-in config loading to handle TypeScript
-      const mod = await import(pathToFileURL(configPath).href);
-      return mod.default ?? mod;
-    }
-  }
-  return null;
-}
-
 /**
  * Serve the production build for local testing.
  * If the adapter provides a preview() method, it takes priority.
  * Otherwise falls back to Vite's built-in preview server.
+ *
+ * Uses the same loadTimberConfigFile loader as dev/build — one loader,
+ * one set of module semantics. A config file that exists but fails to
+ * load throws (naming the file) instead of silently degrading to plain
+ * Vite preview. See TIM-1066.
  */
 export async function runPreview(options: CommandOptions, _deps?: ViteDeps): Promise<void> {
-  const { join, resolve } = await import('node:path');
+  const { loadTimberConfigFile, resolveBuildDir } = await import('./plugin-context.js');
 
-  // Try to load timber config for adapter-specific preview
   const root = process.cwd();
-  const config = await loadTimberConfig(root).catch(() => null);
+  const config = loadTimberConfigFile(root);
   const adapter = config?.adapter as import('./adapters/types').TimberPlatformAdapter | undefined;
 
   if (resolvePreviewStrategy(adapter) === 'adapter') {
-    // Resolve build directory: timber config > default .timber/dist
-    const buildDir = config?.buildDir
-      ? resolve(root, config.buildDir)
-      : join(root, '.timber', 'dist');
+    const buildDir = resolveBuildDir(root, config?.buildDir);
     const timberConfig = { output: (config?.output ?? 'server') as 'server' | 'static' };
     await adapter!.preview!(timberConfig, buildDir);
     return;
@@ -259,7 +255,7 @@ async function main(): Promise<void> {
       await runCheck(options);
       break;
     case 'schema':
-      await runSchema(process.argv.slice(3));
+      await runSchema(parsed.rest);
       break;
   }
 }

package/src/client/browser-entry/hmr.ts

@@ -57,17 +57,6 @@ export function setupHmr(router: RouterInstance): void {
     });
   });
 
-  // Listen for dev warnings forwarded from the server via WebSocket.
-  // See dev-warnings.ts — emitOnce() sends these via server.hot.send().
-  hot.on('timber:dev-warning', (data: unknown) => {
-    const warning = data as { level: string; message: string };
-    if (warning.level === 'error') {
-      console.error(warning.message);
-    } else {
-      console.warn(warning.message);
-    }
-  });
-
   // Listen for server console logs forwarded via WebSocket.
   // Replays them in the browser console with a [SERVER] prefix
   // so developers can see server output without switching to the terminal.

package/src/client/browser-entry/hydrate.ts

@@ -33,6 +33,44 @@ import type { TopLoaderConfig } from '../top-loader.js';
 
 import type { RscStreamResult } from './rsc-stream.js';
 
+let showHydrationError: ((error: unknown) => void) | null = null;
+let isHydrationError: ((error: unknown) => boolean) | null = null;
+let pendingHydrationErrors: unknown[] = [];
+
+// React 19 emits attribute-only hydration mismatches via console.error
+// with format substitution: console.error(fmt, link, diff). We must
+// intercept before hydrateRoot() to catch errors during initial hydration.
+const ATTR_MISMATCH_RE =
+  /A tree hydrated but some attributes of the server rendered HTML didn't match/;
+if (process.env.NODE_ENV !== 'production') {
+  const origConsoleError = console.error;
+  console.error = (...args: unknown[]) => {
+    origConsoleError.apply(console, args);
+    if (typeof args[0] === 'string' && ATTR_MISMATCH_RE.test(args[0])) {
+      const message = args
+        .slice(1)
+        .reduce<string>((s, arg) => s.replace('%s', String(arg)), args[0] as string);
+      queueOrShowHydrationError(new Error(message));
+    }
+  };
+  import('../../dev-tools/hydration-overlay.js').then((m) => {
+    showHydrationError = m.showHydrationError;
+    isHydrationError = m.isHydrationError;
+    for (const err of pendingHydrationErrors) {
+      if (m.isHydrationError(err)) m.showHydrationError(err);
+    }
+    pendingHydrationErrors = [];
+  });
+}
+
+function queueOrShowHydrationError(error: unknown): void {
+  if (showHydrationError && isHydrationError) {
+    if (isHydrationError(error)) showHydrationError(error);
+  } else {
+    pendingHydrationErrors.push(error);
+  }
+}
+
 interface HydrateOptions {
   /** RSC stream result (null if no inlined payload) */
   rscResult: RscStreamResult | null;
@@ -116,13 +154,9 @@ export function hydrateApp({ rscResult, config }: HydrateOptions): void {
       // the shell is flushed). React replays the error during hydration
       // but the server HTML is already correct — no recovery needed.
       onRecoverableError(error: unknown) {
-        // Suppress errors during page unload (refresh/navigate away).
-        // The aborted stream causes incomplete HTML which React flags
-        // as a recoverable error — but the page is being replaced.
         if (isPageUnloading()) return;
-        // Only log in dev — in production these are expected for
-        // deny() inside Suspense and streaming error boundaries.
         if (process.env.NODE_ENV === 'development') {
+          queueOrShowHydrationError(error);
           console.debug('[timber] Hydration recoverable error:', error);
         }
       },

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

@@ -11,9 +11,8 @@
  * See design/19-client-navigation.md §"History Stack"
  */
 
-import { setCurrentParams } from '#client-internal';
 import type { RouterInstance } from '#client-internal';
-import { setNavigationState } from '../navigation-context.js';
+import { getNavigationState } from '../navigation-context.js';
 import type { NavigationApiController } from '../navigation-api.js';
 import { getScrollY } from './scroll.js';
 
@@ -35,9 +34,14 @@ export function setupPostHydration({
   // Store the initial page in the history stack so back-button works
   // after the first navigation. We store the decoded RSC element so
   // back navigation can replay it instantly without a server fetch.
+  // Params were captured from the server-embedded __timber_params by
+  // runPreHydration() — without them on the entry, the cached replay on
+  // back-navigation would normalize params to {} and wipe every
+  // 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,
   });
 
   // Initialize scroll state for the initial entry.
@@ -58,19 +62,6 @@ export function setupPostHydration({
     delete (self as unknown as Record<string, unknown>).__timber_segments;
   }
 
-  // If the hydration path was skipped (no RSC payload), populate the
-  // fallback params from server embed here.
-  const lateTimberParams = (self as unknown as Record<string, unknown>).__timber_params;
-  if (lateTimberParams && typeof lateTimberParams === 'object') {
-    setCurrentParams(lateTimberParams as Record<string, string | string[]>);
-    setNavigationState({
-      params: lateTimberParams as Record<string, string | string[]>,
-      pathname: window.location.pathname,
-      search: window.location.search,
-    });
-    delete (self as unknown as Record<string, unknown>).__timber_params;
-  }
-
   // Register popstate handler for back/forward navigation.
   // When Navigation API is active, the navigate event covers traversals —
   // popstate is a no-op. When unavailable, popstate handles back/forward.

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

@@ -14,7 +14,11 @@ 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 } from '../navigation-context.js';
+import {
+  NavigationProvider,
+  getNavigationState,
+  setNavigationState,
+} from '../navigation-context.js';
 import { transitionRender, navigateTransition } from '../navigation-root.js';
 import { SegmentUpdateContext, EMPTY_SEGMENT_UPDATES } from '../segment-update-context.js';
 import {
@@ -54,10 +58,96 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
   // very first client navigation (before any wrapPayload call).
   let currentPayload: unknown = options?.initialElement ?? null;
 
+  // ─── History API Patch ──────────────────────────────────────────
+  // Patch pushState/replaceState to detect external URL changes (nuqs
+  // shallow updates, replaceUrl, third-party libraries). When the router
+  // itself calls pushState/replaceState, it sets a flag so the patch
+  // skips the sync — the router already updates NavigationContext.
+  //
+  // On Navigation API browsers, the navigate event catches most URL
+  // changes. The patch is defense-in-depth and the primary mechanism
+  // for History API-only browsers (older Safari/Firefox).
+  const ROUTER_HISTORY_FLAG = Symbol.for('__timber_router_history_update');
+  const gFlags = globalThis as Record<symbol, boolean>;
+
+  const originalPushState = window.history.pushState.bind(window.history);
+  const originalReplaceState = window.history.replaceState.bind(window.history);
+
+  /**
+   * Sync NavigationContext.search after a shallow URL update. Called by
+   * the Navigation API shallow handler and the History API patch.
+   *
+   * @param search — the new search string. The Navigation API path passes
+   *   this from event.destination.url (window.location hasn't committed
+   *   yet when the navigate listener fires). The History API patch omits
+   *   it, reading window.location.search (already committed by the time
+   *   the patched pushState/replaceState returns).
+   *
+   * Bails when search is unchanged (scroll saves, no-ops, dual-fire).
+   * Re-wraps currentPayload with updated NavigationProvider and commits
+   * via transitionRender (startTransition — non-blocking).
+   */
+  function syncShallowSearch(search?: string): void {
+    const currentSearch = search ?? window.location.search;
+    const navState = getNavigationState();
+    if (currentSearch === navState.search) return;
+    if (!currentPayload) return;
+
+    const newNavState: NavigationState = {
+      params: navState.params,
+      pathname: navState.pathname,
+      search: currentSearch,
+    };
+    setNavigationState(newNavState);
+
+    const withNav = createElement(
+      NavigationProvider,
+      { value: newNavState },
+      currentPayload as React.ReactNode
+    );
+    const withUpdates = createElement(
+      SegmentUpdateContext.Provider,
+      { value: EMPTY_SEGMENT_UPDATES },
+      withNav
+    );
+    const wrapped = createElement(TimberNuqsAdapter, null, withUpdates);
+    transitionRender(wrapped);
+  }
+
+  window.history.pushState = function (
+    data: unknown,
+    unused: string,
+    url?: string | URL | null
+  ): void {
+    originalPushState(data, unused, url);
+    if (!gFlags[ROUTER_HISTORY_FLAG]) {
+      syncShallowSearch();
+    }
+  };
+
+  window.history.replaceState = function (
+    data: unknown,
+    unused: string,
+    url?: string | URL | null
+  ): void {
+    originalReplaceState(data, unused, url);
+    if (!gFlags[ROUTER_HISTORY_FLAG]) {
+      syncShallowSearch();
+    }
+  };
+
   const deps: RouterDeps = {
     fetch: (url, init) => window.fetch(url, init),
-    pushState: (data, unused, url) => window.history.pushState(data, unused, url),
-    replaceState: (data, unused, url) => window.history.replaceState(data, unused, url),
+    pushState: (data, unused, url) => {
+      gFlags[ROUTER_HISTORY_FLAG] = true;
+      window.history.pushState(data, unused, url);
+      gFlags[ROUTER_HISTORY_FLAG] = false;
+    },
+    replaceState: (data, unused, url) => {
+      gFlags[ROUTER_HISTORY_FLAG] = true;
+      window.history.replaceState(data, unused, url);
+      gFlags[ROUTER_HISTORY_FLAG] = false;
+    },
     navigationApiActive: useNavApi,
     scrollTo: (x, y) => {
       // Scroll the document viewport.
@@ -94,6 +184,7 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
     // navState is passed explicitly by the router — no temporal coupling
     // with getNavigationState().
     renderRoot: (element: unknown, navState: NavigationState) => {
+      currentPayload = element;
       const withNav = createElement(
         NavigationProvider,
         { value: navState },
@@ -183,6 +274,10 @@ export function createTimberRouter(options?: RouterInitOptions): RouterInitResul
         // Back/forward — delegate to the router's popstate handler.
         await router.handlePopState(url, scrollY, signal);
       },
+      onShallowNavigate: (destinationUrl: string) => {
+        const search = new URL(destinationUrl).search;
+        syncShallowSearch(search);
+      },
     });
 
     // Wire the router-navigating flag into RouterDeps.

package/src/client/history.ts

@@ -10,7 +10,12 @@ export interface HistoryEntry {
   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 useParams). Null for SSR'd initial page. */
+  /**
+   * Route params for this page (for useSegmentParams). Every entry that can
+   * be replayed must carry them — the initial SSR entry gets them from the
+   * server-embedded __timber_params, navigation entries from X-Timber-Params,
+   * and revalidation overwrites preserve the current state (TIM-1037).
+   */
   params?: Record<string, string | string[]> | null;
 }
 
@@ -23,13 +28,8 @@ export interface HistoryEntry {
  * On forward navigation, the new page's payload is pushed onto the stack.
  * On popstate, the cached payload is replayed instantly.
  *
- * Supports two keying modes:
- * - **URL-keyed** (default): entries keyed by pathname + search.
- *   Used with the History API fallback.
- * - **Entry-key + URL**: when the Navigation API is available,
- *   entries can also be stored by Navigation entry key for
- *   disambiguation of duplicate URLs in the history stack.
- *   Falls back to URL lookup when entry key is not found.
+ * Entries are keyed by pathname + search. Used with the History API
+ * fallback and the Navigation API.
  *
  * Scroll positions are stored in history.state or Navigation API entry
  * state, not in this stack — see design/19-client-navigation.md §Scroll Restoration.
@@ -39,26 +39,12 @@ export interface HistoryEntry {
  */
 export class HistoryStack {
   private entries = new Map<string, HistoryEntry>();
-  /** Entries keyed by Navigation API entry key for duplicate URL disambiguation. */
-  private entryKeyMap = new Map<string, HistoryEntry>();
 
-  push(url: string, entry: HistoryEntry, entryKey?: string): void {
+  push(url: string, entry: HistoryEntry): void {
     this.entries.set(url, entry);
-    if (entryKey) {
-      this.entryKeyMap.set(entryKey, entry);
-    }
   }
 
-  /**
-   * Get an entry. When an entry key is provided (Navigation API),
-   * tries the entry-key map first for accurate disambiguation of
-   * duplicate URLs, then falls back to URL lookup.
-   */
-  get(url: string, entryKey?: string): HistoryEntry | undefined {
-    if (entryKey) {
-      const byKey = this.entryKeyMap.get(entryKey);
-      if (byKey) return byKey;
-    }
+  get(url: string): HistoryEntry | undefined {
     return this.entries.get(url);
   }