@ozsarman/clarityjs 0.6.0

package/src/router.js

@@ -0,0 +1,732 @@
+/**
+ * Clarity.js Router — v0.4 (History API)
+ *
+ * pushState-based client-side router. Clean URLs (/about, /users/42).
+ * SSR-compatible: works on the server with an injected initial path.
+ *
+ * ─── Features ────────────────────────────────────────────────────────────────
+ *  • History API        pushState / replaceState / popstate
+ *  • Named params       /users/:id → { id: '42' }
+ *  • Wildcard           /docs/*
+ *  • Nested routes      <Route> inside layout components
+ *  • <Outlet>           placeholder for active child route
+ *  • Guards             beforeEnter(pattern, fn) — sync or async, can redirect
+ *  • Scroll restoration automatic scroll-to-top on navigation (configurable)
+ *  • SSR mode           renderRouter(path) → renders component tree for given path
+ *  • back() / forward() programmatic browser history
+ *  • View Transition API  document.startViewTransition() on navigation
+ *
+ * ─── API ─────────────────────────────────────────────────────────────────────
+ *  navigate(path, opts?)    — push to history (runs guards)
+ *  navigateReplace(path)    — replace current entry (runs guards)
+ *  back()                   — history.back()
+ *  forward()                — history.forward()
+ *  currentPath()            — reactive current pathname signal
+ *  routeParams()            — reactive params from last matched route
+ *  matchRoute(pattern, path)— returns params object or null
+ *  beforeEnter(pattern, fn) — register navigation guard
+ *  removeGuard(id)          — deregister guard
+ *  createRouter(opts)       — configure router-wide options
+ *  setServerPath(path)      — SSR: set initial path from request
+ *  useViewTransition()      — { isTransitioning, startTransition }
+ *  Route(pattern, fn, _e, opts)
+ *  Link({ to, children, activeClass, exact, viewTransition })
+ *  Switch(routes, fallback, _e)
+ *  Outlet({ routes, fallback })
+ *
+ * ─── Guard signature ─────────────────────────────────────────────────────────
+ *  (to: { path, params, query }) => boolean | string | Promise<boolean|string>
+ *    true / undefined → allow
+ *    false            → cancel
+ *    '/other'         → redirect
+ *
+ * Author: Claude (Anthropic) + Özdemir Sarman
+ */
+
+import { signal, effect } from './runtime.js';
+
+// ─── Router configuration ─────────────────────────────────────────────────────
+
+const _config = {
+  scrollBehavior:  'top',    // 'top' | 'restore' | 'none'
+  base:            '',       // base URL prefix (e.g. '/app')
+  trailingSlash:   false,    // normalize trailing slashes
+  viewTransition:  false,    // use document.startViewTransition() on navigate
+};
+
+/**
+ * Configure global router options.
+ * Call once at app startup before mounting.
+ *
+ * @param {object} opts
+ * @param {'top'|'restore'|'none'} [opts.scrollBehavior='top']  — scroll behaviour on navigation
+ * @param {string}  [opts.base='']          — base URL prefix (e.g. '/app')
+ * @param {boolean} [opts.trailingSlash]    — normalize trailing slashes
+ */
+export function createRouter(opts = {}) {
+  Object.assign(_config, opts);
+}
+
+// ─── Internal state ───────────────────────────────────────────────────────────
+
+// Reactive signal: current pathname (e.g. '/about')
+const _path   = signal(_getPathname());
+// Reactive signal: params from last matched route
+const _params = signal({});
+// Query string signal: e.g. { q: 'hello' }
+const _query  = signal(_parseQuery(typeof window !== 'undefined' ? window.location.search : ''));
+
+// Guards registry
+let   _guardId = 0;
+const _guards  = new Map();
+
+// View Transition state
+const _transitioning = signal(false);
+
+// Scroll position cache for 'restore' behaviour
+const _scrollCache = new Map();
+
+// ─── Initial event listeners (browser only) ───────────────────────────────────
+
+if (typeof window !== 'undefined') {
+  window.addEventListener('popstate', () => {
+    _path.set(_getPathname());
+    _query.set(_parseQuery(window.location.search));
+  });
+
+  // Intercept all <a href="/..."> clicks that aren't external/special.
+  document.addEventListener('click', (e) => {
+    // If a more specific handler (e.g. the <Link> component) already handled
+    // this click, do nothing — avoids double navigation.
+    if (e.defaultPrevented) return;
+
+    const a = e.target.closest('a[href]');
+    if (!a) return;
+
+    const href = a.getAttribute('href');
+    if (!href) return;
+
+    // Let browser handle external links, mailto:, tel:, pure #anchors,
+    // target=_blank, downloads, and modifier-clicks.
+    if (href.startsWith('http') || href.startsWith('//') ||
+        href.startsWith('mailto:') || href.startsWith('tel:') ||
+        href.startsWith('#') ||
+        a.target === '_blank' || a.hasAttribute('download') ||
+        e.ctrlKey || e.metaKey || e.shiftKey || e.altKey) {
+      return;
+    }
+
+    // Handle in-app links
+    const url = new URL(href, window.location.origin);
+    if (url.origin !== window.location.origin) return;
+
+    e.preventDefault();
+    // Navigate by pathname + search only — a hash is an in-page anchor, not a
+    // route, and must never become part of the matched path.
+    navigate(url.pathname + url.search);
+  });
+}
+
+// ─── Path helpers ─────────────────────────────────────────────────────────────
+
+function _getPathname() {
+  if (typeof window === 'undefined') return '/';
+  let p = window.location.pathname;
+  // Strip base prefix
+  if (_config.base && p.startsWith(_config.base)) {
+    p = p.slice(_config.base.length) || '/';
+  }
+  return _normalizePath(p);
+}
+
+function _normalizePath(p) {
+  if (!p || p === '') return '/';
+  if (!p.startsWith('/')) p = '/' + p;
+  if (_config.trailingSlash === false && p !== '/' && p.endsWith('/')) {
+    p = p.slice(0, -1);
+  }
+  return p;
+}
+
+function _parseQuery(search) {
+  if (!search) return {};
+  const q = {};
+  for (const [k, v] of new URLSearchParams(search)) q[k] = v;
+  return q;
+}
+
+function _buildHref(path) {
+  return _config.base + path;
+}
+
+// ─── Guard helpers ────────────────────────────────────────────────────────────
+
+async function _runGuards(to, params = {}) {
+  let resolved = to;
+  for (const [, guard] of _guards) {
+    if (guard.pattern && matchRoute(guard.pattern, resolved) === null) continue;
+    let result;
+    try {
+      const toParams = guard.pattern ? (matchRoute(guard.pattern, resolved) ?? params) : params;
+      result = await guard.fn({ path: resolved, params: toParams, query: _parseQuery(window?.location?.search ?? '') });
+    } catch (err) {
+      console.error('[Clarity Router] guard threw:', err);
+      return null;
+    }
+    if (result === false) return null;
+    if (typeof result === 'string') resolved = result;
+  }
+  return resolved;
+}
+
+// ─── Public navigation API ────────────────────────────────────────────────────
+
+/**
+ * Navigate to `path` using pushState. Runs guards before committing.
+ *
+ * @param {string} path   — e.g. '/users/42?tab=profile'
+ * @param {object} [opts]
+ * @param {object} [opts.state]       — arbitrary state stored in history entry
+ * @param {boolean}[opts.scroll=true] — whether to apply scrollBehavior
+ * @returns {Promise<boolean>}  false if navigation was cancelled by a guard
+ */
+export async function navigate(path, { state = null, scroll = true, viewTransition } = {}) {
+  const normalized = _normalizePath(path.split('?')[0]) +
+    (path.includes('?') ? '?' + path.split('?')[1] : '');
+
+  const params  = matchRoute('/*', normalized.split('?')[0]) ?? {};
+  const resolved = await _runGuards(normalized.split('?')[0], params);
+  if (resolved === null) return false;
+
+  const finalPath = resolved + (normalized.includes('?') && !resolved.includes('?')
+    ? '?' + normalized.split('?')[1]
+    : '');
+
+  // Determine whether to use View Transition API
+  const useVT = (viewTransition ?? _config.viewTransition) &&
+    typeof document !== 'undefined' &&
+    typeof document.startViewTransition === 'function';
+
+  const commit = () => {
+    if (typeof window !== 'undefined') {
+      // Save scroll position for the page we're leaving (restore mode)
+      if (_config.scrollBehavior === 'restore') {
+        _scrollCache.set(window.location.pathname, { x: window.scrollX, y: window.scrollY });
+      }
+      window.history.pushState(state, '', _buildHref(finalPath));
+    }
+
+    _path.set(_normalizePath(finalPath.split('?')[0]));
+    _query.set(_parseQuery(finalPath.includes('?') ? finalPath.split('?')[1] : ''));
+
+    if (scroll && typeof window !== 'undefined') _applyScroll(resolved);
+  };
+
+  if (useVT) {
+    _transitioning.set(true);
+    const transition = document.startViewTransition(commit);
+    transition.finished.finally(() => _transitioning.set(false));
+  } else {
+    commit();
+  }
+
+  return true;
+}
+
+/**
+ * Replace the current history entry. Same guard/scroll logic as navigate().
+ * @param {string} path
+ * @param {object} [opts]
+ * @param {boolean} [opts.viewTransition]  — override global viewTransition setting
+ */
+export async function navigateReplace(path, { viewTransition } = {}) {
+  const resolved = await _runGuards(_normalizePath(path.split('?')[0]));
+  if (resolved === null) return false;
+
+  const useVT = (viewTransition ?? _config.viewTransition) &&
+    typeof document !== 'undefined' &&
+    typeof document.startViewTransition === 'function';
+
+  const commit = () => {
+    if (typeof window !== 'undefined') {
+      window.history.replaceState(null, '', _buildHref(resolved));
+    }
+    _path.set(_normalizePath(resolved.split('?')[0]));
+    _query.set(_parseQuery(resolved.includes('?') ? resolved.split('?')[1] : ''));
+  };
+
+  if (useVT) {
+    _transitioning.set(true);
+    const transition = document.startViewTransition(commit);
+    transition.finished.finally(() => _transitioning.set(false));
+  } else {
+    commit();
+  }
+
+  return true;
+}
+
+/** Go back one step in history. */
+export function back() {
+  if (typeof window !== 'undefined') window.history.back();
+}
+
+/** Go forward one step in history. */
+export function forward() {
+  if (typeof window !== 'undefined') window.history.forward();
+}
+
+/**
+ * SSR: inject the request path so server-rendered components see the right route.
+ * Call before rendering the component tree on the server.
+ *
+ * @param {string} path  — from req.url or req.path
+ */
+export function setServerPath(path) {
+  _path.set(_normalizePath(path.split('?')[0]));
+  _query.set(_parseQuery(path.includes('?') ? path.split('?')[1] : ''));
+}
+
+// ─── Scroll behaviour ─────────────────────────────────────────────────────────
+
+function _applyScroll(path) {
+  if (_config.scrollBehavior === 'none') return;
+
+  if (_config.scrollBehavior === 'restore') {
+    const saved = _scrollCache.get(path);
+    if (saved) { window.scrollTo(saved.x, saved.y); return; }
+  }
+
+  // Default: scroll to top
+  window.scrollTo({ top: 0, left: 0, behavior: 'instant' });
+}
+
+// ─── Guards ───────────────────────────────────────────────────────────────────
+
+/**
+ * Register a navigation guard.
+ *
+ * @param {string|null} pattern  — pattern to guard (null = global)
+ * @param {Function}    guardFn  — ({ path, params, query }) => bool | string | Promise<…>
+ * @returns {number} guard id
+ */
+export function beforeEnter(pattern, guardFn) {
+  if (typeof pattern === 'function') { guardFn = pattern; pattern = null; }
+  const id = ++_guardId;
+  _guards.set(id, { pattern, fn: guardFn });
+  return id;
+}
+
+/** Remove a guard by id. */
+export function removeGuard(id) { _guards.delete(id); }
+
+// ─── Reactive signals (public) ────────────────────────────────────────────────
+
+/**
+ * Reactive current pathname. Use .get() in effects or call as function.
+ * @returns {string}
+ */
+export const currentPath = Object.assign(() => _path.get(), _path);
+
+/**
+ * Reactive query params object.  { q: 'hello', page: '2' }
+ */
+export const currentQuery = Object.assign(() => _query.get(), _query);
+
+/**
+ * Reactive params from the last matched route.
+ */
+export const routeParams = Object.assign(() => _params.get(), _params);
+
+/**
+ * View Transition API hook.
+ *
+ * Returns a reactive `isTransitioning` flag and a `startTransition` helper
+ * that wraps any callback in `document.startViewTransition()` when supported.
+ *
+ * @example
+ *   const { isTransitioning, startTransition } = useViewTransition();
+ *   effect(() => { if (isTransitioning.get()) body.classList.add('transitioning'); });
+ *
+ * @returns {{ isTransitioning: Signal<boolean>, startTransition: (cb: Function) => void }}
+ */
+export function useViewTransition() {
+  function startTransition(callback) {
+    if (typeof document !== 'undefined' && typeof document.startViewTransition === 'function') {
+      _transitioning.set(true);
+      const t = document.startViewTransition(callback);
+      t.finished.finally(() => _transitioning.set(false));
+    } else {
+      callback();
+    }
+  }
+
+  return { isTransitioning: _transitioning, startTransition };
+}
+
+// ─── matchRoute ───────────────────────────────────────────────────────────────
+
+/**
+ * Match a route pattern against a concrete path.
+ *
+ * Supports:
+ *   /users/:id          named params
+ *   /docs/*             wildcard suffix
+ *   /a/:b/c/:d          multiple params
+ *
+ * @param {string} pattern
+ * @param {string} path
+ * @returns {Record<string,string> | null}
+ */
+export function matchRoute(pattern, path) {
+  // Normalize
+  pattern = _normalizePath(pattern);
+  path    = _normalizePath(path.split('?')[0]);
+
+  if (pattern === '/*') return {};   // catch-all
+
+  const pp = pattern.split('/').filter(Boolean);
+  const ap = path.split('/').filter(Boolean);
+
+  // Wildcard at end: /docs/* matches /docs/a/b/c
+  const hasWildcard = pp[pp.length - 1] === '*';
+  if (hasWildcard) {
+    if (ap.length < pp.length - 1) return null;
+  } else {
+    if (pp.length !== ap.length) return null;
+  }
+
+  const params = {};
+  for (let i = 0; i < pp.length; i++) {
+    if (pp[i] === '*') { params['*'] = ap.slice(i).join('/'); break; }
+    if (pp[i].startsWith(':')) {
+      params[pp[i].slice(1)] = decodeURIComponent(ap[i] ?? '');
+    } else if (pp[i] !== ap[i]) {
+      return null;
+    }
+  }
+  return params;
+}
+
+// ─── Route component ──────────────────────────────────────────────────────────
+
+/**
+ * Renders children reactively when the current path matches `pattern`.
+ * This is the runtime target for `<Route path="…">` in .clarity files.
+ *
+ * @param {string}   pattern
+ * @param {Function} renderChildren  — (params) => Node | Node[]
+ * @param {Function} [_e]            — effect dispose collector
+ * @param {object}   [opts]
+ * @param {boolean}  [opts.exact]    — exact match only (default: prefix-ok for /dash matching /dash/sub)
+ * @param {Function} [opts.guard]    — inline sync guard
+ * @returns {Comment}
+ */
+export function Route(pattern, renderChildren, _e, opts = {}) {
+  const { guard, exact = true } = opts;
+  const anchor = document.createComment(`clarity:route(${pattern})`);
+  let currentNodes = [];
+
+  const dispose = effect(() => {
+    const path   = _path.get();
+    const params = exact
+      ? matchRoute(pattern, path)
+      : _matchPrefix(pattern, path);
+
+    // Remove previous nodes
+    currentNodes.forEach(n => n.parentNode?.removeChild(n));
+    currentNodes = [];
+
+    if (params === null) return;
+
+    // Inline sync guard
+    if (typeof guard === 'function') {
+      const r = guard({ path, params, query: _query.peek() });
+      if (r === false) return;
+      if (typeof r === 'string') { navigate(r); return; }
+    }
+
+    // Update global params
+    _params.set(params);
+
+    // Render
+    const nodes = [renderChildren(params)].flat(Infinity);
+    const parent = anchor.parentNode;
+    if (!parent) return;
+
+    nodes.forEach(n => {
+      if (n && typeof n === 'object' && (n instanceof Node || n.nodeType)) {
+        parent.insertBefore(n, anchor.nextSibling);
+        currentNodes.push(n);
+      }
+    });
+  });
+
+  if (_e) _e(dispose);
+  return anchor;
+}
+
+/** Prefix match: /dashboard matches /dashboard/stats when exact=false */
+function _matchPrefix(pattern, path) {
+  // Try exact first
+  const exact = matchRoute(pattern, path);
+  if (exact !== null) return exact;
+
+  // Try prefix: path starts with pattern segments
+  const pp = pattern.split('/').filter(Boolean);
+  const ap = path.split('/').filter(Boolean);
+  if (ap.length < pp.length) return null;
+
+  const params = {};
+  for (let i = 0; i < pp.length; i++) {
+    if (pp[i].startsWith(':')) params[pp[i].slice(1)] = ap[i];
+    else if (pp[i] !== ap[i]) return null;
+  }
+  return params;
+}
+
+// ─── Switch component ─────────────────────────────────────────────────────────
+
+/**
+ * Renders the FIRST matching route from an array of { pattern, render } entries.
+ * Equivalent to React Router's <Switch> / <Routes>.
+ *
+ * @param {Array<{pattern:string, render:Function}>} routes
+ * @param {Function} [fallback]  — rendered when nothing matches (404 UI)
+ * @param {Function} [_e]
+ * @returns {Comment}
+ */
+export function Switch(routes, fallback, _e) {
+  const anchor = document.createComment('clarity:switch');
+  let   currentNodes = [];
+
+  const dispose = effect(() => {
+    const path = _path.get();
+
+    currentNodes.forEach(n => n.parentNode?.removeChild(n));
+    currentNodes = [];
+
+    let matched = false;
+    for (const { pattern, render } of routes) {
+      const params = matchRoute(pattern, path);
+      if (params !== null) {
+        _params.set(params);
+        [render(params)].flat(Infinity).forEach(n => {
+          if (n instanceof Node) {
+            anchor.parentNode?.insertBefore(n, anchor.nextSibling);
+            currentNodes.push(n);
+          }
+        });
+        matched = true;
+        break;
+      }
+    }
+
+    if (!matched && typeof fallback === 'function') {
+      [fallback()].flat(Infinity).forEach(n => {
+        if (n instanceof Node) {
+          anchor.parentNode?.insertBefore(n, anchor.nextSibling);
+          currentNodes.push(n);
+        }
+      });
+    }
+  });
+
+  if (_e) _e(dispose);
+  return anchor;
+}
+
+// ─── Outlet component ─────────────────────────────────────────────────────────
+
+/**
+ * Slot for nested routes inside a layout component.
+ * Advanced mode: pass routes array explicitly for programmatic control.
+ *
+ * @param {object}    [props]
+ * @param {Array}     [props.routes]   — explicit route list (advanced)
+ * @param {Function}  [props.fallback]
+ * @returns {Comment}
+ */
+export function Outlet({ routes = [], fallback = null } = {}) {
+  if (routes.length === 0 && !fallback) {
+    return document.createComment('clarity:outlet');
+  }
+  return Switch(routes, fallback ?? undefined, null);
+}
+
+// ─── Link component ───────────────────────────────────────────────────────────
+
+/**
+ * Renders an `<a>` that uses navigate() (pushState) instead of full page reload.
+ *
+ * Props:
+ *   to          — target path
+ *   children    — child nodes or label string
+ *   activeClass — class when active (default: 'clarity-link-active')
+ *   exact       — exact path match for active state (default: false)
+ *   replace     — use replaceState instead of pushState
+ *
+ * @param {object} props
+ * @returns {HTMLAnchorElement}
+ */
+export function Link({
+  to,
+  label,
+  children,
+  className       = undefined, // base CSS class(es) for the <a>
+  'class': klass  = undefined, // allow `class="..."` from .clarity JSX
+  activeClass     = 'clarity-link-active',
+  exact           = false,
+  replace         = false,
+  prefetch        = true,   // hover-prefetch the route chunk (requires code splitting)
+  viewTransition  = undefined, // override global viewTransition setting per-link
+} = {}) {
+  const a = document.createElement('a');
+  a.href = _buildHref(to);
+
+  // Forward an author-supplied class so links can be styled (active class is
+  // toggled separately in the effect below).
+  const _baseClass = className ?? klass;
+  if (_baseClass) a.className = _baseClass;
+
+  if (Array.isArray(children)) {
+    children.forEach(c => {
+      if (c instanceof Node) a.appendChild(c);
+      else a.appendChild(document.createTextNode(String(c)));
+    });
+  } else if (label) {
+    a.textContent = label;
+  }
+
+  // Use navigate() so pushState fires instead of a page reload
+  a.addEventListener('click', (e) => {
+    // Let browser handle modifier-clicks naturally
+    if (e.ctrlKey || e.metaKey || e.shiftKey || e.altKey) return;
+    e.preventDefault();
+    if (replace) {
+      navigateReplace(to, { viewTransition });
+    } else {
+      navigate(to, { viewTransition });
+    }
+  });
+
+  // Hover prefetch: start loading the route chunk before the user clicks.
+  // Only fires once per link element (idempotent).
+  if (prefetch) {
+    let _prefetched = false;
+    a.addEventListener('mouseenter', () => {
+      if (_prefetched) return;
+      _prefetched = true;
+      prefetchRoute(to).catch(() => {});
+    }, { passive: true });
+  }
+
+  // Reactive active class
+  effect(() => {
+    const current = _path.get();
+    const active  = exact
+      ? current === _normalizePath(to)
+      : (current === _normalizePath(to) || current.startsWith(_normalizePath(to) + '/'));
+    a.classList.toggle(activeClass, active);
+    a.setAttribute('aria-current', active ? 'page' : 'false');
+  });
+
+  return a;
+}
+
+// ─── SSR helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Render the component tree for a specific server-side path.
+ * Call before renderToString/renderToDocument on the server.
+ *
+ * @param {string}   path         — e.g. '/users/42'
+ * @param {Function} componentFn  — root component function
+ * @param {object}   [props]      — additional props
+ * @returns {Node}
+ */
+export function renderWithPath(path, componentFn, props = {}) {
+  setServerPath(path);
+  return componentFn(props);
+}
+
+/**
+ * Express / Fastify middleware factory.
+ * Injects the request path into the Clarity router before SSR rendering.
+ *
+ * @returns {Function}  Express middleware (req, res, next) => void
+ */
+export function createSSRMiddleware() {
+  return function clarityRouterMiddleware(req, res, next) {
+    setServerPath(req.path ?? req.url ?? '/');
+    next();
+  };
+}
+
+// ─── Code-splitting prefetch ──────────────────────────────────────────────────
+
+/**
+ * Route chunk registry — populated by the app when using code splitting.
+ * Maps route path patterns to dynamic import functions.
+ *
+ *   registerRouteChunk('/about', () => import('./pages/about.js'));
+ *   registerRouteChunk('/users/:id', () => import('./pages/users/[id].js'));
+ */
+const _routeRegistry = new Map(); // pattern → importFn
+
+export function registerRouteChunk(pattern, importFn) {
+  _routeRegistry.set(pattern, importFn);
+}
+
+/**
+ * Prefetch the JavaScript chunk for a route.
+ * Uses <link rel="modulepreload"> if the chunk URL is known from the manifest,
+ * otherwise calls import() to start fetching.
+ *
+ * @param {string} path  — route path to prefetch (e.g. '/about')
+ */
+export async function prefetchRoute(path) {
+  const normalized = _normalizePath(path.split('?')[0]);
+
+  // Try manifest-based modulepreload first (injected by Vite plugin at build time)
+  const manifest = globalThis.__clarityRouteManifest__;
+  if (manifest) {
+    for (const [pattern, entry] of Object.entries(manifest)) {
+      if (matchRoute(pattern, normalized)) {
+        _injectModulepreload(entry.chunk);
+        for (const dep of entry.imports ?? []) _injectModulepreload(dep);
+        return;
+      }
+    }
+  }
+
+  // Fallback: trigger dynamic import() for the matching registered chunk
+  for (const [pattern, importFn] of _routeRegistry) {
+    if (matchRoute(pattern, normalized)) {
+      try { await importFn(); } catch (_) {}
+      return;
+    }
+  }
+}
+
+function _injectModulepreload(src) {
+  if (!src || typeof document === 'undefined') return;
+  const abs = src.startsWith('/') ? src : '/' + src;
+  if (document.querySelector(`link[rel="modulepreload"][href="${abs}"]`)) return;
+  const link = document.createElement('link');
+  link.rel  = 'modulepreload';
+  link.href = abs;
+  document.head.appendChild(link);
+}
+
+/**
+ * Inject <link rel="modulepreload"> tags for the current route.
+ * Call this after the app mounts to preload the current page's chunk
+ * and trigger prefetching of likely-next pages.
+ *
+ * @param {string} [path]  — defaults to currentPath().get()
+ */
+export function injectModulepreloads(path) {
+  const p = path ?? _path.get();
+  prefetchRoute(p); // fire and forget
+}