@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/src/browser/history-state.ts

@@ -61,6 +61,27 @@ export function buildHistoryState(
   return Object.keys(result).length > 0 ? result : null;
 }
 
+/**
+ * Stamp an `idx` on the next history entry's state and call push/replaceState.
+ * Push increments the current idx; replace keeps it. Initial entry idx is 0.
+ * Used by useRouter().back() to detect "first entry in this session" without
+ * relying on the Navigation API.
+ */
+export function pushHistoryWithIdx(
+  state: Record<string, unknown> | null,
+  url: string,
+  replace: boolean,
+): void {
+  const oldIdx = (window.history.state as { idx?: number } | null)?.idx ?? 0;
+  const newIdx = replace ? oldIdx : oldIdx + 1;
+  const finalState = { ...(state ?? {}), idx: newIdx };
+  if (replace) {
+    window.history.replaceState(finalState, "", url);
+  } else {
+    window.history.pushState(finalState, "", url);
+  }
+}
+
 /**
  * Merge server-set location state into the current history entry.
  * Replaces the current history state and dispatches notification event

package/src/browser/index.ts

@@ -1,9 +1,9 @@
 // ============================================================================
-// Browser Module - Browser entry point for RSC Router
+// Browser Module - Browser entry point for Rango
 // ============================================================================
 //
 // Usage:
-//   import { initBrowserApp, RSCRouter } from "rsc-router/browser";
+//   import { initBrowserApp, Rango } from "rsc-router/browser";
 //
 // For React components (Link, useNavigation, etc.):
 //   import { Link, useNavigation, useAction, href } from "rsc-router/client";
@@ -13,6 +13,6 @@
 // Browser app initialization
 export {
   initBrowserApp,
-  RSCRouter,
+  Rango,
   type InitBrowserAppOptions,
 } from "./rsc-router.js";

package/src/browser/invalidate-client-cache.ts

@@ -0,0 +1,52 @@
+/**
+ * Client seat of `invalidateClientCache()` (the `default` export condition).
+ *
+ * Makes the current client behave as if a server action had just completed:
+ * the history cache is marked stale (SWR), the prefetch map is flushed, the
+ * state rotates, and sibling tabs are broadcast to — the same
+ * `markCacheAsStaleAndBroadcast()` path the server-action bridge uses. This is
+ * the gentler mark-stale (not hard-clear) behavior, so Back renders the cached
+ * entry instantly and revalidates.
+ */
+
+import { getRegisteredStore } from "./navigation-store-handle.js";
+import { clearPrefetchCache } from "./prefetch/cache.js";
+
+export function invalidateClientCache(): void {
+  if (typeof document === "undefined") {
+    // SSR pass of a client component also resolves the default condition. A
+    // render-time call must not take down the page; no-op with a dev warning.
+    if (process.env.NODE_ENV !== "production") {
+      console.warn(
+        "[rango] invalidateClientCache() was called during a server render; " +
+          "it is a no-op outside the browser.",
+      );
+    }
+    return;
+  }
+
+  const store = getRegisteredStore();
+  if (store) {
+    store.markCacheAsStaleAndBroadcast();
+    return;
+  }
+
+  // Pre-boot: no store registered yet. clearPrefetchCache() (which rotates the
+  // state) is complete at this point — there is no history cache to mark and no
+  // sibling state worth broadcasting.
+  clearPrefetchCache();
+}
+
+/**
+ * Client no-op for `keepClientCache()`. It is a server action directive (the
+ * `react-server` condition sets a response header the action bridge reads);
+ * there is nothing to suppress from the client side.
+ */
+export function keepClientCache(): void {
+  if (process.env.NODE_ENV !== "production") {
+    console.warn(
+      "[rango] keepClientCache() has no effect on the client; it is a server " +
+        "action directive. Call it from inside a server action.",
+    );
+  }
+}

package/src/browser/link-interceptor.ts

@@ -1,18 +1,164 @@
 import type { LinkInterceptorOptions, NavigateOptions } from "./types.js";
+import {
+  subscribeToLocationChange,
+  type EventController,
+} from "./event-controller.js";
+import {
+  getDefaultPrefetchStrategy,
+  resolveAdaptiveStrategy,
+  subscribeToAdaptiveStrategyChange,
+} from "./prefetch/default-strategy.js";
+import { observeForPrefetch } from "./prefetch/observer.js";
+import { subscribeToPrefetchCacheInvalidation } from "./prefetch/invalidation.js";
+import { notifyListeners } from "./notify-listeners.js";
+import type { PrefetchStrategy } from "../router/prefetch-default.js";
+
+const ELIGIBILITY_ATTRIBUTES = {
+  href: "href",
+  target: "target",
+  download: "download",
+  noIntercept: "data-no-intercept",
+  linkComponent: "data-link-component",
+  external: "data-external",
+  prefetch: "data-prefetch",
+  prefetchScope: "data-prefetch-scope",
+} as const;
+
+const ELIGIBILITY_ATTRIBUTE_FILTER = Object.values(ELIGIBILITY_ATTRIBUTES);
+const ANCHOR_SELECTOR = "a";
+const ELIGIBLE_ANCHOR_SELECTOR = `a[${ELIGIBILITY_ATTRIBUTES.href}]`;
+const LINK_COMPONENT_SELECTOR = `a[${ELIGIBILITY_ATTRIBUTES.linkComponent}]`;
+const HTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
+const PREFETCH_OPT_OUT_VALUES = new Set(["false", "none"]);
+const PREFETCH_SCOPE_OPT_OUT_SELECTOR =
+  `[${ELIGIBILITY_ATTRIBUTES.prefetchScope}="false"],` +
+  `[${ELIGIBILITY_ATTRIBUTES.prefetchScope}="none"]`;
+const STATIC_RESOURCE_EXTENSION =
+  /\.(?:7z|avif|bmp|bz2|cjs|css|csv|docx?|eot|gif|gz|ico|jpe?g|js|json|m4a|map|mjs|mov|mp3|mp4|ogg|ogv|otf|pdf|png|pptx?|rar|svg|tar|tgz|tiff?|ttf|txt|wasm|wav|webm|webp|woff2?|xlsx?|xml|zip)$/i;
+
+function isElementNode(value: unknown): value is Element {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as Node).nodeType === 1 &&
+    typeof (value as Element).matches === "function"
+  );
+}
+
+function isNode(value: unknown): value is Node {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as Node).nodeType === "number"
+  );
+}
+
+type PrefetchScopeChangeListener = () => void;
+
+interface PrefetchScopeObserverState {
+  observer: MutationObserver;
+  subscriptions: Map<Element, Set<PrefetchScopeChangeListener>>;
+}
+
+const prefetchScopeObservers = new WeakMap<
+  Document,
+  PrefetchScopeObserverState
+>();
+
+function createPrefetchScopeObserverState(
+  ownerDocument: Document,
+): PrefetchScopeObserverState | undefined {
+  if (
+    typeof MutationObserver === "undefined" ||
+    !ownerDocument.documentElement
+  ) {
+    return undefined;
+  }
+
+  const subscriptions = new Map<Element, Set<PrefetchScopeChangeListener>>();
+  const observer = new MutationObserver((mutations) => {
+    const affected = new Set<PrefetchScopeChangeListener>();
+    const collect = (element: Element) => {
+      subscriptions.get(element)?.forEach((listener) => affected.add(listener));
+    };
+
+    for (const mutation of mutations) {
+      if (!isElementNode(mutation.target)) continue;
+      collect(mutation.target);
+      mutation.target
+        .querySelectorAll(LINK_COMPONENT_SELECTOR)
+        .forEach(collect);
+    }
+    notifyListeners(affected, (listener) => listener());
+  });
+  observer.observe(ownerDocument.documentElement, {
+    subtree: true,
+    attributes: true,
+    attributeFilter: [ELIGIBILITY_ATTRIBUTES.prefetchScope],
+  });
+  return { observer, subscriptions };
+}
+
+export function subscribeToPrefetchScopeChange(
+  element: HTMLAnchorElement,
+  listener: PrefetchScopeChangeListener,
+): () => void {
+  const ownerDocument = element.ownerDocument;
+  let state = prefetchScopeObservers.get(ownerDocument);
+  if (!state) {
+    state = createPrefetchScopeObserverState(ownerDocument);
+    if (!state) return () => {};
+    prefetchScopeObservers.set(ownerDocument, state);
+  }
+
+  let listeners = state.subscriptions.get(element);
+  if (!listeners) {
+    listeners = new Set();
+    state.subscriptions.set(element, listeners);
+  }
+  listeners.add(listener);
+
+  let active = true;
+  return () => {
+    if (!active) return;
+    active = false;
+    listeners.delete(listener);
+    if (
+      listeners.size === 0 &&
+      state.subscriptions.get(element) === listeners
+    ) {
+      state.subscriptions.delete(element);
+    }
+    if (
+      state.subscriptions.size === 0 &&
+      prefetchScopeObservers.get(ownerDocument) === state
+    ) {
+      state.observer.disconnect();
+      prefetchScopeObservers.delete(ownerDocument);
+    }
+  };
+}
 
 /**
  * Check if an anchor points to the same page with only a hash change.
  * Used by both Link component and link-interceptor to let the browser
  * handle anchor scrolling natively.
  */
-export function isHashOnlyNavigation(anchor: HTMLAnchorElement): boolean {
+function isHashOnlyNavigationToPath(
+  anchor: HTMLAnchorElement,
+  pathname: string,
+): boolean {
   return (
-    anchor.pathname === window.location.pathname &&
+    pathname === window.location.pathname &&
     anchor.search === window.location.search &&
     !!anchor.hash
   );
 }
 
+export function isHashOnlyNavigation(anchor: HTMLAnchorElement): boolean {
+  return isHashOnlyNavigationToPath(anchor, anchor.pathname);
+}
+
 /**
  * Default link interception predicate
  *
@@ -27,50 +173,119 @@ export function isHashOnlyNavigation(anchor: HTMLAnchorElement): boolean {
  * @returns true if the link should be intercepted
  */
 export function defaultShouldIntercept(link: HTMLAnchorElement): boolean {
-  // Only intercept same-origin links
-  if (link.origin !== window.location.origin) {
+  if (!isEligiblePlainAnchor(link)) return false;
+
+  // Don't intercept hash-only navigation (same path, only fragment changes).
+  // Let the browser handle anchor scrolling natively.
+  return !isHashOnlyNavigation(link);
+}
+
+function isEligiblePlainAnchor(link: HTMLAnchorElement): boolean {
+  // Namespace identity survives adoptNode/importNode across realms; instanceof
+  // does not. Structural test doubles omit namespaceURI and retain the legacy
+  // property-based behavior.
+  if (link.namespaceURI && link.namespaceURI !== HTML_NAMESPACE) {
     return false;
   }
 
-  // Don't intercept if it has download attribute
-  if (link.hasAttribute("download")) {
+  // Only handle same-origin links
+  if (link.origin !== window.location.origin) {
     return false;
   }
 
-  // Don't intercept if target is set to something other than _self
-  if (link.target && link.target !== "_self") {
+  // Skip links with a download attribute
+  if (link.hasAttribute(ELIGIBILITY_ATTRIBUTES.download)) {
     return false;
   }
 
-  // Don't intercept if explicitly disabled
-  if (link.getAttribute("data-no-intercept") === "true") {
+  // Skip links targeting another browsing context
+  const target = link.getAttribute(ELIGIBILITY_ATTRIBUTES.target);
+  if (target && target !== "_self") {
     return false;
   }
 
-  // Don't intercept Link component anchors - they handle their own navigation
-  if (link.hasAttribute("data-link-component")) {
+  // Skip links explicitly excluded from delegated handling
+  if (link.getAttribute(ELIGIBILITY_ATTRIBUTES.noIntercept) === "true") {
     return false;
   }
 
-  // Don't intercept external links
-  if (link.hasAttribute("data-external")) {
+  // Link components handle their own navigation and prefetch
+  if (link.hasAttribute(ELIGIBILITY_ATTRIBUTES.linkComponent)) {
     return false;
   }
 
-  // Don't intercept hash-only navigation (same path, only fragment changes).
-  // Let the browser handle anchor scrolling natively.
-  if (isHashOnlyNavigation(link)) {
+  // Skip links explicitly marked external
+  if (link.hasAttribute(ELIGIBILITY_ATTRIBUTES.external)) {
     return false;
   }
 
   return true;
 }
 
+function normalizePathname(pathname: string): string {
+  return pathname
+    .replace(/%[0-9a-f]{2}/gi, (escape) => escape.toUpperCase())
+    .replace(/\/+$/, "");
+}
+
+function canonicalizeBasenamePathname(basename?: string): string | undefined {
+  if (!basename) return undefined;
+  return normalizePathname(new URL(basename, window.location.origin).pathname);
+}
+
+export function isPrefetchScopeDisabled(element: Element): boolean {
+  return (
+    typeof element.closest === "function" &&
+    element.closest(PREFETCH_SCOPE_OPT_OUT_SELECTOR) !== null
+  );
+}
+
+type PrefetchEligibility = "eligible" | "location-dependent" | "ineligible";
+
+function defaultPrefetchEligibilityInBasename(
+  link: HTMLAnchorElement,
+  basename?: string,
+): PrefetchEligibility {
+  if (!isEligiblePlainAnchor(link)) return "ineligible";
+  if (isPrefetchScopeDisabled(link)) return "ineligible";
+
+  const prefetch = link.getAttribute(ELIGIBILITY_ATTRIBUTES.prefetch);
+  if (prefetch && PREFETCH_OPT_OUT_VALUES.has(prefetch)) return "ineligible";
+
+  const rawPathname = link.pathname;
+  if (isHashOnlyNavigationToPath(link, rawPathname)) {
+    return "location-dependent";
+  }
+  const pathname = normalizePathname(rawPathname);
+  if (
+    basename !== undefined &&
+    pathname !== basename &&
+    !pathname.startsWith(`${basename}/`)
+  ) {
+    return "ineligible";
+  }
+
+  if (prefetch === "true") return "eligible";
+
+  // Scope is decided on canonical encoded path segments. Decode only for
+  // resource classification so malformed escapes cannot expand router scope.
+  let resourcePathname: string;
+  try {
+    resourcePathname = decodeURIComponent(pathname);
+  } catch {
+    return "ineligible";
+  }
+  if (STATIC_RESOURCE_EXTENSION.test(resourcePathname)) {
+    return "ineligible";
+  }
+  return "eligible";
+}
+
 /**
  * Set up link interception for SPA navigation
  *
- * Attaches a global click handler to intercept clicks on anchor elements
- * and call the onNavigate callback instead of performing a full page load.
+ * Attaches a global click handler to intercept clicks on anchor elements and
+ * call the onNavigate callback instead of performing a full page load.
  *
  * @param onNavigate - Callback when a link should navigate via SPA
  * @param options - Configuration options
@@ -99,7 +314,8 @@ export function setupLinkInterception(
       return;
     }
 
-    const target = event.target as HTMLElement;
+    if (!isElementNode(event.target)) return;
+    const target = event.target;
     const link = target.closest("a");
 
     if (!link || !shouldIntercept(link)) {
@@ -139,3 +355,236 @@ export function setupLinkInterception(
     document.removeEventListener("click", handleClick);
   };
 }
+
+export type DelegatedPrefetchCallback = (
+  url: string,
+  priority: "direct" | "queued",
+) => void | (() => void);
+
+export interface DelegatedPrefetchOptions {
+  eventController: Pick<EventController, "getState" | "subscribe">;
+  shouldPrefetch?: (link: HTMLAnchorElement) => boolean;
+  defaultPrefetch?: PrefetchStrategy;
+  root?: HTMLElement;
+  basename?: string;
+}
+
+interface DelegatedPrefetchState {
+  stopObserving?: () => void;
+  cancelPending?: () => void;
+}
+
+export function setupDelegatedLinkPrefetch(
+  onPrefetch: DelegatedPrefetchCallback,
+  options: DelegatedPrefetchOptions,
+): () => void {
+  const defaultStrategy =
+    options.defaultPrefetch ?? getDefaultPrefetchStrategy();
+  if (defaultStrategy === "none") return () => {};
+
+  const basename = canonicalizeBasenamePathname(options.basename);
+  const customShouldPrefetch = options.shouldPrefetch;
+  const getEligibility = customShouldPrefetch
+    ? (link: HTMLAnchorElement): PrefetchEligibility => {
+        if (isPrefetchScopeDisabled(link)) return "ineligible";
+        return customShouldPrefetch(link) ? "eligible" : "ineligible";
+      }
+    : (link: HTMLAnchorElement) =>
+        defaultPrefetchEligibilityInBasename(link, basename);
+  const states = new Map<HTMLAnchorElement, DelegatedPrefetchState>();
+  const parked = new Set<HTMLAnchorElement>();
+  let strategy = resolveAdaptiveStrategy(defaultStrategy);
+
+  const disarm = (link: HTMLAnchorElement) => {
+    const state = states.get(link);
+    state?.stopObserving?.();
+    state?.cancelPending?.();
+    states.delete(link);
+    if (strategy === "hover") syncMutationObserver();
+  };
+
+  const evaluateEligibility = (link: HTMLAnchorElement): PrefetchEligibility =>
+    link.hasAttribute(ELIGIBILITY_ATTRIBUTES.href)
+      ? getEligibility(link)
+      : "ineligible";
+
+  const updateParked = (
+    link: HTMLAnchorElement,
+    eligibility: PrefetchEligibility,
+  ) => {
+    if (eligibility === "location-dependent" && strategy !== "hover") {
+      parked.add(link);
+    } else parked.delete(link);
+  };
+
+  const forget = (link: HTMLAnchorElement) => {
+    disarm(link);
+    parked.delete(link);
+  };
+
+  const trigger = (link: HTMLAnchorElement, priority: "direct" | "queued") => {
+    const eligibility = evaluateEligibility(link);
+    updateParked(link, eligibility);
+    if (eligibility !== "eligible") {
+      disarm(link);
+      return;
+    }
+
+    let state = states.get(link);
+    if (!state) {
+      state = {};
+      states.set(link, state);
+    }
+    state.cancelPending?.();
+    state.cancelPending = undefined;
+    try {
+      state.cancelPending = onPrefetch(link.href, priority) ?? undefined;
+    } finally {
+      if (strategy === "hover" && !state.cancelPending) states.delete(link);
+      syncMutationObserver();
+    }
+  };
+
+  const register = (link: HTMLAnchorElement) => {
+    disarm(link);
+    const eligibility = evaluateEligibility(link);
+    updateParked(link, eligibility);
+    if (eligibility !== "eligible") return;
+    if (strategy === "hover") return;
+
+    const state: DelegatedPrefetchState = {};
+    states.set(link, state);
+
+    if (strategy === "render") {
+      trigger(link, "queued");
+    } else if (strategy === "viewport") {
+      state.stopObserving = observeForPrefetch(link, () => {
+        state.stopObserving = undefined;
+        trigger(link, "queued");
+      });
+    }
+  };
+
+  const visitAnchors = (
+    node: Node,
+    visit: (link: HTMLAnchorElement) => void,
+  ) => {
+    if (!isElementNode(node)) return;
+    if (node.matches(ANCHOR_SELECTOR)) {
+      visit(node as HTMLAnchorElement);
+    }
+    node
+      .querySelectorAll<HTMLAnchorElement>(ANCHOR_SELECTOR)
+      .forEach((link) => visit(link));
+  };
+
+  const root = options.root ?? document.documentElement;
+  let mutationObserver: MutationObserver | undefined;
+  function syncMutationObserver(): void {
+    const shouldObserve =
+      strategy === "viewport" || strategy === "render" || states.size > 0;
+    if (!shouldObserve) {
+      mutationObserver?.disconnect();
+      mutationObserver = undefined;
+      return;
+    }
+    if (mutationObserver || typeof MutationObserver === "undefined" || !root) {
+      return;
+    }
+
+    mutationObserver = new MutationObserver((mutations) => {
+      const affected = new Set<HTMLAnchorElement>();
+      const markAffected = (link: HTMLAnchorElement) => affected.add(link);
+      for (const mutation of mutations) {
+        if (mutation.type === "attributes") {
+          if (mutation.attributeName === ELIGIBILITY_ATTRIBUTES.prefetchScope) {
+            visitAnchors(mutation.target, markAffected);
+          } else if (
+            isElementNode(mutation.target) &&
+            mutation.target.matches(ANCHOR_SELECTOR)
+          ) {
+            affected.add(mutation.target as HTMLAnchorElement);
+          }
+          continue;
+        }
+        mutation.removedNodes.forEach((node) =>
+          visitAnchors(node, markAffected),
+        );
+        mutation.addedNodes.forEach((node) => visitAnchors(node, markAffected));
+      }
+      for (const link of affected) {
+        if (link.isConnected && root.contains(link)) register(link);
+        else forget(link);
+      }
+    });
+    mutationObserver.observe(root, {
+      subtree: true,
+      childList: true,
+      attributes: true,
+      attributeFilter: ELIGIBILITY_ATTRIBUTE_FILTER,
+    });
+  }
+
+  const rescan = () => {
+    for (const link of [...states.keys()]) disarm(link);
+    parked.clear();
+    strategy = resolveAdaptiveStrategy(defaultStrategy);
+    syncMutationObserver();
+    if ((strategy === "viewport" || strategy === "render") && root) {
+      visitAnchors(root, register);
+    }
+  };
+
+  rescan();
+
+  const handleMouseOver = (event: MouseEvent) => {
+    if (!isElementNode(event.target)) return;
+
+    const link = event.target.closest<HTMLAnchorElement>(
+      ELIGIBLE_ANCHOR_SELECTOR,
+    );
+    if (!link || !root.contains(link)) return;
+    if (isNode(event.relatedTarget) && link.contains(event.relatedTarget)) {
+      return;
+    }
+    trigger(link, "direct");
+  };
+
+  if (strategy === "hover" || strategy === "viewport") {
+    root.addEventListener("mouseover", handleMouseOver);
+  }
+
+  const unsubscribeLocation =
+    defaultStrategy === "viewport" ||
+    defaultStrategy === "render" ||
+    defaultStrategy === "adaptive"
+      ? subscribeToLocationChange(options.eventController, () => {
+          if (strategy !== "viewport" && strategy !== "render") return;
+          for (const link of [...parked]) {
+            if (link.isConnected && root.contains(link)) register(link);
+            else forget(link);
+          }
+        })
+      : undefined;
+  const unsubscribeAdaptive =
+    defaultStrategy === "adaptive"
+      ? subscribeToAdaptiveStrategyChange(rescan)
+      : undefined;
+  const unsubscribeInvalidation = subscribeToPrefetchCacheInvalidation(() => {
+    if (strategy !== "viewport" && strategy !== "render") return;
+    for (const link of [...states.keys()]) {
+      if (link.isConnected && root.contains(link)) register(link);
+      else forget(link);
+    }
+  });
+
+  return () => {
+    mutationObserver?.disconnect();
+    root.removeEventListener("mouseover", handleMouseOver);
+    unsubscribeLocation?.();
+    unsubscribeAdaptive?.();
+    unsubscribeInvalidation();
+    for (const link of [...states.keys()]) disarm(link);
+    parked.clear();
+  };
+}

package/src/browser/logging.ts

@@ -1,5 +1,15 @@
 import { INTERNAL_RANGO_DEBUG } from "../internal-debug.js";
 
+/**
+ * Module-level debug flag for guarding call sites whose debug arguments do
+ * non-trivial work (joins, maps, spreads, object literals). Because the Vite
+ * transform folds INTERNAL_RANGO_DEBUG to a literal, an `if (IS_BROWSER_DEBUG)`
+ * guard is minifier-DCE-able — the whole block drops from the production bundle.
+ * Prefer this over isBrowserDebugEnabled() at hot call sites: a const guard folds
+ * where a function call may not.
+ */
+export const IS_BROWSER_DEBUG: boolean = INTERNAL_RANGO_DEBUG;
+
 interface BrowserLogContext {
   requestId: string;
   txId: string;
@@ -53,3 +63,21 @@ export function debugLog(msg: string, ...args: unknown[]): void {
     console.log(msg, ...args);
   }
 }
+
+/**
+ * Boot-sequence debug log: one line per initial-document step (flight decode,
+ * handle stream, bridge wiring, initial tree build, hydration commit), each
+ * stamped with performance.now() so the gap BEFORE hydrateRoot is visible.
+ * The initial document path was otherwise silent — FE debug only started
+ * talking at the first soft navigation, so a boot stall (e.g. an await that
+ * holds initBrowserApp, and with it hydrateRoot) was invisible.
+ */
+export function bootLog(step: string, details?: Record<string, unknown>): void {
+  if (!INTERNAL_RANGO_DEBUG) return;
+  const prefix = `[Browser][boot] ${step} @ ${Math.round(performance.now())}ms`;
+  if (details) {
+    console.log(prefix, details);
+    return;
+  }
+  console.log(prefix);
+}