@ape-egg/vibe 2.1.21 → 2.3.0

package/runtime/component.js

@@ -1,4 +1,5 @@
 import { debugLog } from './debug.js';
+import { shouldCleanup } from './cleanup.js';
 import {
   PHASE_FETCH,
   PHASE_FETCH_CACHED,
@@ -71,6 +72,23 @@ const createScopedDollar = (componentId) => {
     get(target, prop, receiver) {
       if (prop === 'on') {
         return (event, callback) => {
+          // 'unmount' is scope-resolved: in a component script it means THIS
+          // component's unmount (conditional toggle, iteration removal,
+          // reactive src swap — and before an HMR re-run of the same id).
+          // The callback rides the same per-component cleanup registry the
+          // global-event unsubscribes below ride, so a component owns
+          // arbitrary side effects (intervals, listeners, sockets) without
+          // leaking them past its lifetime. At page level the root's `on`
+          // resolves the same event name to pagehide instead.
+          if (event === 'unmount') {
+            if (!window.__vibeComponentCleanups) window.__vibeComponentCleanups = {};
+            const slot = window.__vibeComponentCleanups[componentId] || (window.__vibeComponentCleanups[componentId] = []);
+            slot.push(callback);
+            return () => {
+              const i = slot.indexOf(callback);
+              if (i >= 0) slot.splice(i, 1);
+            };
+          }
           const unsub = target.on(event, callback);
           if (!window.__vibeComponentCleanups) window.__vibeComponentCleanups = {};
           const slot = window.__vibeComponentCleanups[componentId] || (window.__vibeComponentCleanups[componentId] = []);
@@ -261,6 +279,63 @@ export const abortComponentFetch = (element) => {
   }
 };
 
+// A fetched-component host: `<component>` or `<div class="component">`.
+export const isComponentWrapper = (el) =>
+  el.nodeName === 'COMPONENT' ||
+  (el.nodeName === 'DIV' && el.classList?.contains('component'));
+
+// The live element a reactive src binding acts on. The manifest tree keeps the
+// ORIGINAL element, but every (re)mount replaces the wrapper (finalize's
+// replaceWith), leaving a `_vibeReplacedBy` link behind. Follow the chain and
+// compress it so intermediate detached wrappers stay collectable.
+export const liveComponentWrapper = (element) => {
+  let live = element;
+  while (live._vibeReplacedBy) live = live._vibeReplacedBy;
+  if (live !== element) element._vibeReplacedBy = live;
+  return live;
+};
+
+// (Re)mount a component for a reactive src binding (`src="@[page.src]"`).
+// Three phases of a wrapper's life, one entry point:
+// - Unprocessed element (no fetch yet): write the resolved src — the pending
+//   boot/observer processComponent pass fetches it.
+// - Fetch in flight: abort it and fetch the new src.
+// - Mounted wrapper (src consumed by finalize): re-fetch and re-mount; the
+//   authored props + slot content re-apply via the remount context finalize
+//   stashed on the wrapper, and the outgoing component's state is evicted by
+//   the removal pass when replaceWith drops the old wrapper.
+export const remountComponent = (el, src, debug = false) => {
+  const wasFetching = pendingFetches.has(el);
+  const hadSrcAttr = el.hasAttribute('src');
+  // Compare against the LATEST requested src: with a fetch in flight the src
+  // attribute holds it (rapid navigation A→B→A must abort B, not no-op on A);
+  // mounted and idle, the finalize-stashed value does.
+  const current = wasFetching
+    ? el.getAttribute('src')
+    : (el._vibeMountedSrc ?? el.getAttribute('src'));
+  if (src === current) return;
+  abortComponentFetch(el);
+  el.setAttribute('src', src);
+  // Pre-fetch element awaiting its initial processing pass: that pass reads
+  // the new value — nothing to redo. A declaration-form wrapper (bound src
+  // that resolved to nothing, carried on data-vibe-src with no src
+  // attribute) was invisible to that pass, so hydration owns its first
+  // fetch too — the observer doesn't watch attributes.
+  if (el._vibeMountedSrc === undefined && !wasFetching && hadSrcAttr) return;
+  processSingle(el, debug);
+};
+
+// Key-change remount (`key="@[page.path]"`): mount the CURRENT src fresh even
+// though it is unchanged. Only a mounted, idle wrapper has anything to redo —
+// with a fetch pending the incoming mount is already fresh (a src change in
+// the same flush started it), and an unmounted wrapper's first mount is owned
+// by the normal processing pass.
+export const forceRemount = (el, debug = false) => {
+  if (pendingFetches.has(el) || el._vibeMountedSrc === undefined) return;
+  el.setAttribute('src', el._vibeMountedSrc);
+  processSingle(el, debug);
+};
+
 // Check if an element is nested inside another unprocessed component[src]
 const isNestedInUnprocessedComponent = (el, rootElement) => {
   let parent = el.parentElement;
@@ -473,16 +548,25 @@ const processSingle = (el, debug) => {
 
   const src = el.getAttribute('src');
 
-  // Use pre-hydration slot content if available (saved by index.js before hydration ran),
-  // otherwise fall back to current innerHTML (e.g. runtime-only usage without boot).
+  // Use pre-hydration slot content if available (saved by index.js before
+  // hydration ran, or re-stashed by finalize for reactive-src re-mounts),
+  // otherwise fall back to current innerHTML (e.g. runtime-only usage without
+  // boot). Kept on the element — a re-mount consumes the same authored slot.
   const children = (el._vibeSlotContent !== undefined ? el._vibeSlotContent : el.innerHTML).trim();
-  delete el._vibeSlotContent;
-  const props = {};
-  Array.from(el.attributes).forEach((attr) => {
-    if (attr.name !== 'src') {
-      props[attr.name] = attr.value;
-    }
-  });
+  // A re-mounted wrapper carries no prop attributes (finalize stripped them) —
+  // its authored props ride the remount context stashed at the previous mount.
+  let props = el._vibeRemountProps;
+  if (!props) {
+    props = {};
+    // `src` and `key` are the wrapper's own contract (what to mount / when to
+    // remount), and data-vibe-* attributes are runtime transport — none of
+    // them are authored props for the component.
+    Array.from(el.attributes).forEach((attr) => {
+      if (attr.name !== 'src' && attr.name !== 'key' && !attr.name.startsWith('data-vibe-')) {
+        props[attr.name] = attr.value;
+      }
+    });
+  }
 
   // Capture cache state before the fetch so the debug layer can tell a real
   // network fetch from a runtime-cache hit (the call below would make them
@@ -591,8 +675,10 @@ const processSingle = (el, debug) => {
         // Delegate prop substitution + slot inlining to shared helper.
         const transformedHtml = renderPropsAndSlot(temp, props, children);
 
-        // Clean up pending fetch tracker
-        pendingFetches.delete(el);
+        // Clean up pending fetch tracker — only if this fetch still owns the
+        // slot (a reactive-src re-mount may have aborted us and registered a
+        // newer controller for the same element).
+        if (pendingFetches.get(el) === controller) pendingFetches.delete(el);
 
         // Replace with clean component wrapper (no src, no props)
         // Check if element still has a parent (might have been removed during fetch)
@@ -615,6 +701,27 @@ const processSingle = (el, debug) => {
           // the plugin would have nothing to compare against). Vibe itself
           // never reads this; it's purely for the plugin spy.
           newWrapper._vibeRawSource = html;
+          // Remount context for reactive src bindings (src="@[page.src]"):
+          // the mounted src (no-op detection), the authored props, and the
+          // authored slot content. Each re-mount consumes these and finalize
+          // stashes them onto the next wrapper — self-sustaining across
+          // arbitrarily many navigations.
+          newWrapper._vibeMountedSrc = src;
+          newWrapper._vibeRemountProps = props;
+          newWrapper._vibeSlotContent = children;
+          // The authored binding travels ON the wrapper (data-vibe-src, same
+          // transport idea as data-vibe-namebind): the original tree node is
+          // pruned when this replaceWith's removal mutation is processed, and
+          // the replacement's reparse recaptures the binding from this
+          // attribute — the DOM alone carries the knowledge across swaps.
+          const srcBinding = el._vibeSrcBinding ?? el.getAttribute('data-vibe-src');
+          if (srcBinding) newWrapper.setAttribute('data-vibe-src', srcBinding);
+          // The key binding and its last resolved value ride along the same
+          // way, so a later key change still finds what to compare against
+          // on the replacement wrapper.
+          const keyBinding = el._vibeKeyBinding ?? el.getAttribute('data-vibe-key');
+          if (keyBinding) newWrapper.setAttribute('data-vibe-key', keyBinding);
+          if (el._vibeMountedKey !== undefined) newWrapper._vibeMountedKey = el._vibeMountedKey;
           // Transfer iteration-prop registry ownership from the soon-to-be-
           // detached `<component src>` to the new wrapper. The detached element
           // would otherwise trigger releaseOrphanedIterationProps and free the
@@ -650,13 +757,37 @@ const processSingle = (el, debug) => {
           // renderAllConditionals/Iterations populated runtime data) is what
           // iterate.js's update path uses to re-evaluate inlined bindings on
           // each row update.
+          // The observer hydrates the inserted subtree in its NEXT batch —
+          // until then, selectors keyed on hydrated attributes (a name-bound
+          // <page @[page.name]> → page[pvp] rules) don't match and the
+          // content paints unstyled. Cover the gap with the same fouc
+          // contract pages use: hidden at insertion, revealed by the batch
+          // that parsed and hydrated this subtree.
+          newWrapper.setAttribute('vibe-fouc', '');
           el._vibeReplacedBy = newWrapper;
           el.replaceWith(newWrapper);
           debugLog(fromCache ? PHASE_FETCH_CACHED : PHASE_FETCH, src, debug);
 
+          // Build-inlined child components (compiled SPA fragments) arrive
+          // with tagged wrapper ids and vibe-module scripts — the compiled-
+          // document form. A fetched mount is the fourth delivery mode after
+          // boot, conditional branches, and iteration rows: run those
+          // scripts now so each child's component({...}) state registers
+          // under its build-tagged id and the _cN bindings hydrate.
+          executeCompiledComponentScriptsIn([newWrapper]);
+
           // MutationObserver handles parsing and hydrating the new content.
           // Branch nodes are registered in the manifest by mountBranch,
           // so the observer can find parents even inside conditional branches.
+          // Hydration can span multiple batches (nested fetched components,
+          // async scripts) with paints in between — reveal only when the
+          // subtree has settled (same predicate the page-level ready uses).
+          // A wrapper unmounted mid-hydration releases the hook.
+          const unfouc = window.$.on('afterDomMutation', () => {
+            if (newWrapper.isConnected && !shouldCleanup(newWrapper)) return;
+            newWrapper.removeAttribute('vibe-fouc');
+            unfouc();
+          });
         } else {
           // Element was detached before finalize ran (conditional unmounted
           // during fetch, parent removed, etc). Release any state component()
@@ -676,10 +807,10 @@ const processSingle = (el, debug) => {
       finalize();
     })
     .catch((error) => {
-      // Clean up pending fetch tracker
-      pendingFetches.delete(el);
+      // Clean up pending fetch tracker — ownership-guarded (see finalize)
+      if (pendingFetches.get(el) === controller) pendingFetches.delete(el);
 
-      // If fetch was aborted (element removed), silently skip
+      // If fetch was aborted (element removed or re-mounted), silently skip
       if (error.name === 'AbortError') {
         return;
       }

package/runtime/hydrate.js

@@ -1,5 +1,6 @@
 import { updateIteration } from './iterate.js';
 import { updateConditional, managedNodes } from './conditionals.js';
+import { isComponentWrapper, liveComponentWrapper, remountComponent, forceRemount } from './component.js';
 import { VALUE_ATTRS, DOM_PROPERTIES, BINDING_REGEX, PURE_BINDING_REGEX } from './constants.js';
 import { evalInScope, resolveCaseInsensitivePath } from './utils.js';
 import { RawHtml } from './raw-html.js';
@@ -82,6 +83,51 @@ export default (affected, state, manifest = {}, oldState = {}) => {
     if (aff.type === 'attribute') {
       const { attrName, attrValue, element } = aff;
       try {
+        // Reactive component src (`<component src="@[page.src]">`): resolve
+        // the binding and (re)mount through component.js. The binding rides
+        // along so finalize can stamp it onto the replacement wrapper
+        // (data-vibe-src) — the tree node holding it is pruned when the
+        // wrapper swap's removal mutation lands, and the fresh wrapper's
+        // reparse rebuilds the knowledge from that attribute. A state change
+        // landing inside the swap window still resolves through the
+        // replacement chain.
+        // Keyed component (`<component src="@[page.src]" key="@[page.path]">`):
+        // a key change is a declared identity change — remount the mounted
+        // component even when the src is unchanged (param→param navigation on
+        // the same route). The first resolution just records the initial key;
+        // the mount itself is owned by the normal component pass.
+        if (attrName === 'key' && isComponentWrapper(element)) {
+          const live = liveComponentWrapper(element);
+          const newKey = attrValue.replace(BINDING_REGEX, (_, expr) =>
+            evalInScope(expr, effectiveState, live) ?? '',
+          );
+          live._vibeKeyBinding = attrValue;
+          const prevKey = live._vibeMountedKey;
+          live._vibeMountedKey = newKey;
+          if (prevKey !== undefined && newKey !== prevKey) forceRemount(live);
+          return;
+        }
+
+        if (attrName === 'src' && isComponentWrapper(element)) {
+          const live = liveComponentWrapper(element);
+          const newSrc = attrValue.replace(BINDING_REGEX, (_, expr) =>
+            evalInScope(expr, effectiveState, live) ?? '',
+          );
+          live._vibeSrcBinding = attrValue;
+          if (newSrc) {
+            remountComponent(live, newSrc);
+          } else if (live.hasAttribute('src')) {
+            // Unresolved src mounts nothing (a no-match deep link leaves
+            // $.page.src unset): move the binding onto data-vibe-src — the
+            // established transport parse.js already reads — and drop the
+            // fetchable src, so component processing and cleanup treat the
+            // outlet as settled instead of fetching a stringified binding.
+            live.setAttribute('data-vibe-src', attrValue);
+            live.removeAttribute('src');
+          }
+          return;
+        }
+
         // Check if this is a pure binding (e.g., value="@[inputValue]")
         const isPureBinding = attrValue.match(PURE_BINDING_REGEX);
         const isDomProperty = DOM_PROPERTIES.includes(attrName);

package/runtime/index.js

@@ -568,8 +568,26 @@ const main = (s, config = {}, stringSelector = '') => {
     afterUpdate: [],
     afterDomMutation: [],
     ready: [],
+    unmount: [],
   };
 
+  // The ready phase happens once. A listener registered after it fires
+  // immediately (parity with the late-safe $.ready promise) — late
+  // registration is the SPA norm, where fragment scripts run on mount,
+  // long after the shell booted.
+  let readyFired = false;
+
+  // Page-scope 'unmount': the visitor actually leaving — pagehide (navigation
+  // away, tab close). Deliberately NOT visibilitychange: a tab switch is not
+  // an unmount, the visitor comes back. Inside a component script the same
+  // event name resolves to that component's unmount instead (the scoped `$`
+  // proxy in component.js intercepts it before it reaches this hook).
+  if (typeof window !== 'undefined') {
+    window.addEventListener('pagehide', () => {
+      hooks.unmount.forEach((callback) => callback());
+    });
+  }
+
   // Extract plain values from proxy (removes proxy wrappers)
   // Optimized: indexed loops, Object.keys (no prototype walk), inline primitive check
   const extractPlainValue = (obj) => {
@@ -677,6 +695,14 @@ const main = (s, config = {}, stringSelector = '') => {
   // snapshots or Object.keys($).
   Object.defineProperty($, 'on', {
     value: (event, callback) => {
+      if (event === 'ready' && readyFired) {
+        try {
+          callback();
+        } catch (error) {
+          console.error('[vibe] Error in ready hook:', error);
+        }
+        return () => {};
+      }
       if (hooks[event]) {
         hooks[event].push(callback);
       }
@@ -1221,6 +1247,7 @@ const main = (s, config = {}, stringSelector = '') => {
       cleanupExecuted = true;
 
       // Fire ready hook after cleanup completes
+      readyFired = true;
       hooks.ready.forEach((callback) => {
         try {
           callback();

package/runtime/parse.js

@@ -21,16 +21,36 @@ const findComponentIdForElement = (element) => {
 // Single source of truth for reading attribute/name bindings off an element.
 // Called from both the root handler and recursive() so they can't drift. Any
 // element classified as a fetched component (`<component src>` or
-// `<div class="component" src>`) returns nulls — its attributes are props
-// owned by processComponent and must stay raw; hydrating them would coerce
-// objects to "[object Object]" or strip boolean-like attrs to empty.
+// `<div class="component" src>`) captures ONLY a bound src (`src="@[page.src]"`
+// — resolved by hydration before the fetch, re-mounted on change) and a bound
+// key (`key="@[page.path]"` — a key change remounts the same src); every other
+// attribute is a prop owned by processComponent and must stay raw — hydrating
+// them would coerce objects to "[object Object]" or strip boolean-like attrs
+// to empty. A mounted wrapper carries the authored bindings in data-vibe-src /
+// data-vibe-key (stamped by finalize — the src attribute was consumed by the
+// fetch), so the knowledge survives every wrapper replacement: reparsing the
+// live DOM alone rebuilds it.
 const captureAttributeBindings = (element, aliasSet) => {
   const nodeName = element.nodeName;
   const isFetchedComponent =
     (nodeName === 'COMPONENT' || (nodeName === 'DIV' && element.classList?.contains('component'))) &&
-    element.hasAttribute?.('src');
+    (element.hasAttribute?.('src') || element.hasAttribute?.('data-vibe-src'));
 
-  if (isFetchedComponent || !element.attributes || element.attributes.length === 0) {
+  if (isFetchedComponent) {
+    const src = element.getAttribute?.('data-vibe-src') ?? element.getAttribute?.('src');
+    const key = element.getAttribute?.('data-vibe-key') ?? element.getAttribute?.('key');
+    const attributes = {};
+    BINDING_REGEX.lastIndex = 0;
+    if (BINDING_REGEX.test(src)) attributes.src = src;
+    BINDING_REGEX.lastIndex = 0;
+    if (key && BINDING_REGEX.test(key)) attributes.key = key;
+    return {
+      attributes: Object.keys(attributes).length ? attributes : null,
+      nameBindings: null,
+    };
+  }
+
+  if (!element.attributes || element.attributes.length === 0) {
     return { attributes: null, nameBindings: null };
   }
 

package/runtime/pre-compiled-manifest.js

@@ -169,7 +169,24 @@ export const buildManifestCandidatePaths = (pathname, route) => {
   // sit mid-path, e.g. /a/:id/b) and try that manifest first — a direct hit, no
   // 404 probing. Skipped entirely when no route is declared.
   const routeSegments = route ? route.split("/").filter((s) => s) : null;
-  if (routeSegments && routeSegments.some((s) => s.startsWith(":"))) {
+  const isCatchAll =
+    routeSegments &&
+    routeSegments[routeSegments.length - 1]?.startsWith(":") &&
+    routeSegments[routeSegments.length - 1]?.endsWith("*");
+  if (isCatchAll) {
+    // A trailing `:name*` catch-all (pages/x/$$name.html) swallows every
+    // remaining URL segment — zero or more — so tokenizing by position is
+    // meaningless past the static prefix. The compiler collapses the whole
+    // `$$name.html` file to the same `$` token as a single `$param`, giving
+    // ONE manifest for every depth: <static-prefix>/$.html.manifest.js.
+    // Built from the raw pathname: with zero extra segments the .html
+    // normalization above has already mutated the prefix's last segment.
+    const rawSegments = pathname.split("/").filter((s) => s);
+    const prefix = rawSegments
+      .slice(0, routeSegments.length - 1)
+      .map((seg, i) => (routeSegments[i].startsWith(":") ? "$" : seg));
+    possiblePaths.push(`/vibe-hyperspeed/${[...prefix, "$"].join("/")}.html.manifest.js`);
+  } else if (routeSegments && routeSegments.some((s) => s.startsWith(":"))) {
     const tokenized = pathSegments.map((seg, i) => {
       if (!routeSegments[i]?.startsWith(":")) return seg;
       const dot = seg.indexOf(".");

package/spa.js

@@ -0,0 +1,143 @@
+// @ape-egg/vibe/spa
+//
+// Standalone SPA router — the tier between a handrolled router and compiler
+// SPA mode. Maintains one contract: $.page = { path, route, params, src,
+// name }, which a reactive component src (<component src="@[page.src]">)
+// turns into a route outlet.
+//
+// SOFT DEPENDENCY: nothing in Vibe's runtime imports this, it imports nothing
+// from Vibe, and deleting it leaves a working framework. The default
+// onNavigate writes to the runtime global window.$ at call time; pass a
+// custom onNavigate and the module is a pure router (parse/claim/history)
+// with no Vibe in sight.
+//
+// Route grammar (shared with the compiler's route table and route scanners):
+//   /static/path        literal segments
+//   /brawlers/:index    :param captures one segment
+//   /docs/:rest*        trailing :name* captures zero or more segments
+//   *                   declared no-match fallback — deep links and popstate
+//                       only, never claims a click
+// Tables are pre-sorted most-specific-first; first match wins.
+
+// Match one pathname against one route template. Returns the params object
+// (possibly empty) on match, null otherwise. Empty segments are dropped, so
+// trailing slashes resolve to the same route.
+const matchRoute = (path, route) => {
+  const routeSegments = route.split('/').filter(Boolean);
+  const pathSegments = path.split('/').filter(Boolean);
+  const params = {};
+  for (let i = 0; i < routeSegments.length; i++) {
+    const segment = routeSegments[i];
+    if (segment.startsWith(':') && segment.endsWith('*')) {
+      params[segment.slice(1, -1)] = pathSegments.slice(i).join('/');
+      return params;
+    }
+    if (pathSegments[i] === undefined) return null;
+    if (segment.startsWith(':')) params[segment.slice(1)] = pathSegments[i];
+    else if (segment !== pathSegments[i]) return null;
+  }
+  return pathSegments.length === routeSegments.length ? params : null;
+};
+
+// Route slug: segments joined with dashes, params flattened to their bare
+// name — '/' → 'home', '/pve/:id' → 'pve-id', '/docs/:rest*' → 'docs-rest'.
+// Stable across param values, so markup hangs page-scoped attributes and
+// active checks on it: <page @[page.name]>, page.name.startsWith('pve').
+const routeName = (route) =>
+  route
+    .replace(/^\/+|\/+$/g, '')
+    .replace(/:(\w+)\*?/g, '$1')
+    .replace(/\//g, '-') || 'home';
+
+// Resolve a location (anything with a .pathname, or a bare path string)
+// against a route table → { path, route, params, src, name, title? } | null.
+// Pure: the compiled shell seeds initial $.page with it, unit tests drive it
+// directly. '*' is skipped during matching and applied only when nothing
+// real matched — it is a declared fallback, not a positional route.
+export const resolve = (location, routes) => {
+  const path = location.pathname ?? location;
+  for (const entry of routes) {
+    if (entry.route === '*') continue;
+    const params = matchRoute(path, entry.route);
+    if (params)
+      return {
+        path,
+        route: entry.route,
+        params,
+        src: entry.src,
+        name: routeName(entry.route),
+        title: entry.title,
+      };
+  }
+  const fallback = routes.find((entry) => entry.route === '*');
+  return fallback
+    ? { path, route: '*', params: {}, src: fallback.src, name: '*', title: fallback.title }
+    : null;
+};
+
+// Wire the router: one document-level click listener + popstate. Claiming
+// rule: same-origin, unmodified, untargeted clicks whose pathname matches a
+// REAL route — '*' never claims, so unrouted paths navigate natively (which
+// is what makes mixed MPA/SPA output work). Returns { navigate, dispose }.
+export const setupSpa = ({ routes, onNavigate }) => {
+  // Default Vibe binding: one fresh-object assignment so bindings diff
+  // cleanly, reading window.$ at call time (page scripts boot vibe before
+  // setupSpa runs). A route-supplied title swaps document.title.
+  const apply = onNavigate ?? (({ path, route, params, src, name, title }) => {
+    window.$.page = { path, route, params, src, name };
+    if (title) document.title = title;
+  });
+
+  const claim = (target) => {
+    const resolved = resolve(target, routes);
+    return resolved && resolved.route !== '*' ? resolved : null;
+  };
+
+  const push = (url, resolved) => {
+    history.pushState({}, '', url);
+    apply(resolved);
+    scrollTo(0, 0);
+  };
+
+  const onClick = (event) => {
+    const anchor = event.target.closest('a[href]');
+    if (!anchor || anchor.origin !== location.origin) return;
+    if (anchor.target || anchor.hasAttribute('download')) return;
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey || event.button) return;
+    if (event.defaultPrevented) return;
+    // Same-page hash links keep the native anchor jump.
+    if (anchor.hash && anchor.pathname === location.pathname) return;
+    const resolved = claim(anchor);
+    if (!resolved) return;
+    event.preventDefault();
+    push(anchor.href, resolved);
+  };
+
+  // History traversal re-resolves WITH the '*' fallback — symmetric with
+  // deep-link entry, whose URL may itself be a '*' page. No scroll: the
+  // browser restores scroll position on popstate.
+  const onPopstate = () => {
+    const resolved = resolve(location, routes);
+    if (resolved) apply(resolved);
+  };
+
+  // Programmatic navigation, claiming like a link click: real route match →
+  // SPA navigation, anything else → native load (the server rewrite serves
+  // the shell, whose deep-link resolution may then mount '*').
+  const navigate = (path) => {
+    const url = new URL(path, location.origin);
+    const resolved = claim(url);
+    if (resolved) push(url, resolved);
+    else location.assign(url);
+  };
+
+  document.addEventListener('click', onClick);
+  addEventListener('popstate', onPopstate);
+
+  const dispose = () => {
+    document.removeEventListener('click', onClick);
+    removeEventListener('popstate', onPopstate);
+  };
+
+  return { navigate, dispose };
+};