@reactra/router 0.1.0-alpha.0

package/dist/index.js

@@ -0,0 +1,1049 @@
+// @reactra/router — Hash + History mode router + route-store lifecycle
+//
+// Owner: reactra-router-spec.md (Spec 3.2 / Discussion v4.3)
+//
+// `_middleware.ts` route-guard API (Wave 3, Stage 1) lives in ./middleware.ts
+// and is re-exported below.
+//
+// Phase 1 surface (Day 10a + Day 13):
+//   RouterRegistry  — pure core: routes map, pathname state, transitions
+//   configureRouter({ routes, mode })  — mode: "hash" (default) | "history"
+//   navigate(path)  — push a new pathname, fire onExit/onEnter bindings
+//   useRoute()      — React hook returning { pathname, params, query, route }
+//   RouteRenderer   — renders the active route's component
+//
+// Day 13 (item #5b) adds `mode: "history"`. In history mode, navigate()
+// uses `history.pushState` and the router listens for `popstate` to drive
+// re-renders on back/forward. Hash mode (the Day-10a default) is
+// unchanged. The pure core still works without a DOM — tests drive
+// `navigate` directly under Node.
+//
+// Deferred to subsequent days (still tracked in phase-1.md):
+//   meta / prefetch / transition codegen (#5c)
+//   RouteLink, useQueryUpdater, useRouteMatch (#5c)
+//   Typed query coercion (number / boolean / enum) (#5c)
+//   _middleware, route guards, scroll restoration (#5d)
+//   `for subtree` and keyed route stores (#5c)
+//   <a href> click interception → navigate() (#5c)
+import { Component, createElement, Suspense, useCallback, useEffect, useRef, useSyncExternalStore } from "react";
+import { __setMiddlewareServiceResolver, buildContextCommands, runAfterLeaveChain, runBeforeEnterChain, } from "./middleware.js";
+import { createScrollManager, ensureHistoryKey, pushStateWithKey, readHistoryKey, replaceStateWithKey, } from "./scrollManager.js";
+/**
+ * Match a pathname against a registered pattern. Returns the extracted
+ * params if it matches, `null` otherwise.
+ *
+ * Patterns use Express-style `:name` placeholders. Each segment is matched
+ * literally except for placeholders, which capture into `params[name]`.
+ * No catch-all (`*`) or optional segments in this MVP.
+ */
+/**
+ * Match a pathname against a route pattern, returning the extracted params
+ * if it matches or `null` otherwise. Exposed for {@link useRouteMatch} and
+ * for app code that wants to test an arbitrary pattern against the current
+ * (or any) pathname.
+ */
+export const matchRoute = (pattern, pathname) => {
+    const patSeg = pattern.split("/").filter(Boolean);
+    const pathSeg = pathname.split("/").filter(Boolean);
+    const params = {};
+    for (let i = 0; i < patSeg.length; i++) {
+        const p = patSeg[i];
+        // Catch-all (Wave 3 §2b) — `*name` consumes all REMAINING path
+        // segments (at least one — empty catch-alls don't match; the parent
+        // `/foo` route handles that case). Stored as a slash-joined string
+        // under the param name; consumers split on `/` for array semantics.
+        // (Spec §2.2 documents `{ slug: string[] }`; we keep the params type
+        // `Record<string, string>` for back-compat across the existing
+        // surface and revisit the proper widening in a later sweep.)
+        if (p.startsWith("*")) {
+            // Catch-all must be the last segment of the pattern.
+            if (i !== patSeg.length - 1)
+                return null;
+            const remaining = pathSeg.slice(i);
+            if (remaining.length === 0)
+                return null;
+            params[p.slice(1)] = remaining.map((s) => decodeURIComponent(s)).join("/");
+            return params;
+        }
+        if (i >= pathSeg.length)
+            return null;
+        const s = pathSeg[i];
+        if (p.startsWith(":")) {
+            params[p.slice(1)] = decodeURIComponent(s);
+        }
+        else if (p !== s) {
+            return null;
+        }
+    }
+    // No catch-all consumed the tail — the path must have exactly the
+    // pattern's segment count for a match.
+    if (patSeg.length !== pathSeg.length)
+        return null;
+    return params;
+};
+/**
+ * Parse a query string fragment ("?a=1&b=2" or "a=1&b=2") into a flat object.
+ * Repeated keys collapse to the last value — multi-value support and typed
+ * coercion are Day 10b.
+ */
+const parseQuery = (search) => {
+    const out = {};
+    const trimmed = search.startsWith("?") ? search.slice(1) : search;
+    if (!trimmed)
+        return out;
+    // A repeated key (`?tag=x&tag=y`) accumulates into an array (Router §3.1 —
+    // backs `query foo: string[]`); a single occurrence stays a string. The
+    // coercion layer collapses an unexpected array to its last value for a scalar
+    // `query` field, so a single-value field is unaffected by a stray repeat.
+    const put = (k, v) => {
+        const existing = out[k];
+        if (existing === undefined)
+            out[k] = v;
+        else if (Array.isArray(existing))
+            existing.push(v);
+        else
+            out[k] = [existing, v];
+    };
+    for (const pair of trimmed.split("&")) {
+        if (!pair)
+            continue;
+        const eq = pair.indexOf("=");
+        if (eq < 0)
+            put(decodeURIComponent(pair), "");
+        else
+            put(decodeURIComponent(pair.slice(0, eq)), decodeURIComponent(pair.slice(eq + 1)));
+    }
+    return out;
+};
+/**
+ * Split a fully-qualified URL fragment into its pathname + raw query parts.
+ * Used by `navigate` to peel apart the input string.
+ */
+const splitPathQuery = (input) => {
+    const q = input.indexOf("?");
+    if (q < 0)
+        return { pathname: input, query: "" };
+    return { pathname: input.slice(0, q), query: input.slice(q + 1) };
+};
+/**
+ * Build a concrete URL from a route PATTERN plus params + query — the
+ * runtime half of the typed-navigation surface (Router §5.3 / `#5c-typed`).
+ *
+ * The generated manifest's typed `navigate` (Router §5.1) delegates here:
+ * the compiler-derived `RouteId` / `RouteParams` types guarantee the
+ * caller passes the right param keys, and this function fills the
+ * `:name` placeholders with their (URL-encoded) values and appends a
+ * query string.
+ *
+ *   buildPath("/", )                                   → "/"
+ *   buildPath("/customers/:id", { id: "c 3" })         → "/customers/c%203"
+ *   buildPath("/customers/:id", { id: "c3" }, { tab: "notes" })
+ *                                                      → "/customers/c3?tab=notes"
+ *
+ * Throws (RO002-shaped) when a `:name` segment has no matching param —
+ * surfaced as a runtime guard behind the compile-time type check, so a
+ * JS caller bypassing the types still gets a clear error rather than a
+ * literal `/customers/:id` URL.
+ */
+export const buildPath = (pattern, params, query) => {
+    const filled = pattern
+        .split("/")
+        .map((seg) => {
+        if (!seg.startsWith(":"))
+            return seg;
+        const name = seg.slice(1);
+        const value = params?.[name];
+        if (value === undefined) {
+            throw new Error(`[@reactra/router] RO002: missing param "${name}" for route ` +
+                `pattern "${pattern}". Pass it via navigate("${pattern}", ` +
+                `{ params: { ${name}: … } }). (Router §5.3.)`);
+        }
+        return encodeURIComponent(value);
+    })
+        .join("/");
+    if (query === undefined)
+        return filled;
+    const search = new URLSearchParams();
+    for (const [k, v] of Object.entries(query)) {
+        if (v === undefined)
+            continue;
+        // An array value emits a repeated key (`?tag=x&tag=y`) so it round-trips
+        // back to a `query foo: string[]` read (Router §3.1).
+        if (Array.isArray(v))
+            for (const item of v)
+                search.append(k, String(item));
+        else
+            search.set(k, String(v));
+    }
+    const qs = search.toString();
+    return qs.length > 0 ? `${filled}?${qs}` : filled;
+};
+/**
+ * Coerce one raw query-string value to its declared type at read time
+ * (Router §3.1 / §5.3). The compiler emits one of these per `query foo: T`
+ * read, threading the declared kind + the `= default` expression as
+ * `fallback`. Coercion is lenient — a malformed value (non-numeric for
+ * `number`, off-enum for an enum) yields the `fallback` rather than throwing,
+ * since the URL is an external, user-editable source (the spec's RO024/RO025
+ * are navigation-time checks; reads degrade gracefully). An absent value
+ * (`undefined`) always yields `fallback`.
+ *
+ *   coerceQuery("42", "number")            → 42
+ *   coerceQuery("abc", "number", 1)        → 1
+ *   coerceQuery("true", "boolean")         → true
+ *   coerceQuery("x", ["a","b"], "a")       → "a"   (off-enum → fallback)
+ */
+export const coerceQuery = (raw, kind, fallback) => {
+    // `string[]` field: normalize to an array (a single value → one-element array;
+    // absent → the fallback, or [] when none). Repeated keys arrive here as arrays.
+    if (kind === "string[]") {
+        if (raw === undefined)
+            return fallback ?? [];
+        return Array.isArray(raw) ? [...raw] : [raw];
+    }
+    // Scalar field that received a repeated key → last-value-wins (the array form
+    // is only meaningful for a declared `string[]`). A `typeof` check (not
+    // Array.isArray) so TS reduces the union to `string | undefined` for the rest.
+    if (typeof raw !== "string" && raw !== undefined)
+        raw = raw[raw.length - 1];
+    if (raw === undefined)
+        return fallback;
+    if (kind === "string")
+        return raw;
+    if (kind === "number") {
+        const n = Number(raw);
+        return Number.isNaN(n) ? fallback : n;
+    }
+    if (kind === "boolean") {
+        if (raw === "true" || raw === "1" || raw === "")
+            return true;
+        if (raw === "false" || raw === "0")
+            return false;
+        return fallback;
+    }
+    // enum: kind is the array of allowed raw values.
+    return kind.includes(raw) ? raw : fallback;
+};
+class RouterRegistryImpl {
+    routes = [];
+    listeners = new Set();
+    currentPathname = "/";
+    currentQuery = "";
+    currentSnapshot = {
+        pathname: "/",
+        params: {},
+        query: {},
+        route: null,
+    };
+    previousRoute = null;
+    // Name-keyed bindings (Day 16 / #18b). Compiler-emitted modules call
+    // `registerRouteBindings("Foo", { onEnter, onExit })` at module-load /
+    // HMR-reload time; the lifecycle reads by name via the matched route's
+    // `bindingsName` field. After an HMR re-evaluation the new module
+    // overwrites the entry under the same name — so a route still
+    // matches its current onEnter/onExit even though the component
+    // identity may have changed.
+    routeBindings = new Map();
+    // True once the active route's `onEnter` has fired. With code-split routes
+    // (§5.2) the page chunk — and its sibling `registerRouteBindings(...)` call —
+    // loads AFTER `setLocation` runs, so `setLocation` can't fire `onEnter` yet
+    // (bindings absent). `registerRouteBindings` then fires a catch-up `onEnter`
+    // for the active route iff it hasn't been entered. The flag prevents a double
+    // enter: the eager path (setLocation fires it) and an HMR re-registration of an
+    // already-entered route must NOT re-instantiate the route store.
+    currentEntered = false;
+    // Wave 3, Stage 3 — `_middleware.ts` chains keyed by route path. Populated
+    // via `setMiddlewareChains` (called from `configureRouter` or directly).
+    // `Map` keeps the lookup O(1) and avoids accidental prototype-chain hits a
+    // plain object record would expose.
+    middlewareChains = new Map();
+    /** Register a route. Idempotent on `id` — re-registering replaces. */
+    register = (route) => {
+        const existing = this.routes.findIndex((r) => r.id === route.id);
+        if (existing >= 0)
+            this.routes[existing] = route;
+        else
+            this.routes.push(route);
+    };
+    /**
+     * Day 27 / `#5c-followup`: replace the entire routes array (typically
+     * with the freshly-evaluated `newMod.ROUTES` from a HMR-accept
+     * callback on the generated route manifest). Re-runs `setLocation`
+     * for the current pathname so a removed-mid-session route flips to
+     * the null-route state, a renamed route picks up its new shape, and
+     * an added route is matchable on the very next render — all without
+     * a page reload.
+     *
+     * The route's `onExit` (if any) fires for the previously-matched
+     * route inside `setLocation`, mirroring a normal navigation. The
+     * `previousRoute` snapshot is then updated to whatever matches now
+     * under the new set; the next genuine `navigate()` will exit it
+     * cleanly.
+     */
+    replaceRoutes = (newRoutes) => {
+        this.routes = [...newRoutes];
+        this.setLocation(this.currentPathname, this.currentQuery);
+    };
+    /**
+     * Register route lifecycle bindings under a stable name. Compiler-
+     * emitted in the same module that exports the page component (see
+     * Pass 9 codegen). Module-level call — runs once on first load AND
+     * again on every HMR re-evaluation, overwriting the prior entry.
+     * Safe to call before / after `register(route)`; lookup happens at
+     * route-enter time which is after both have been called.
+     */
+    registerRouteBindings = (name, bindings) => {
+        this.routeBindings.set(name, bindings);
+        // Catch-up for code-split routes (§5.2): if these bindings belong to the
+        // currently-active route and `setLocation` couldn't fire `onEnter` yet (the
+        // page chunk was still loading), fire it now with the active params/query.
+        // This runs during the lazy chunk's module-eval, BEFORE React renders the
+        // page body — so the route store is instantiated before `useReactraStore`.
+        // `!currentEntered` keeps the eager path and HMR re-registration from
+        // double-entering (an already-entered route's store is left intact).
+        if (!this.currentEntered && this.currentSnapshot.route?.bindingsName === name) {
+            bindings.onEnter({
+                pathname: this.currentSnapshot.pathname,
+                params: this.currentSnapshot.params,
+                query: this.currentSnapshot.query,
+            });
+            this.currentEntered = true;
+        }
+    };
+    /** Read access for tests + setLocation lifecycle. */
+    lookupRouteBindings = (name) => this.routeBindings.get(name);
+    /**
+     * Find a registered route by its path pattern (e.g. `/customers/:id`) — the
+     * value a `RouteLink`'s `to` carries. Used by {@link PrefetchRuntime} to reach
+     * a route's `preload` thunk. Returns the first match or `undefined`.
+     */
+    getRouteByPath = (path) => this.routes.find((r) => r.path === path);
+    /**
+     * Drive the registry to a new pathname + query. Fires the previous
+     * route's `onExit` (if any), updates the snapshot, fires the new
+     * route's `onEnter` (if any), then notifies React subscribers.
+     */
+    setLocation = (pathname, query) => {
+        this.currentPathname = pathname;
+        this.currentQuery = query;
+        const parsedQuery = parseQuery(query);
+        let matched = null;
+        let params = {};
+        for (const r of this.routes) {
+            const m = matchRoute(r.path, pathname);
+            if (m) {
+                matched = r;
+                params = m;
+                break;
+            }
+        }
+        // Lifecycle: dispose the prior route's stores before instantiating
+        // the new route's. If we re-enter the same route with different
+        // params, dispose + re-instantiate so the store sees the new inputs
+        // (RT-05). Bindings are looked up by name via the matched route's
+        // `bindingsName` field (Day 16 / #18b).
+        const prevBindings = this.previousRoute?.bindingsName != null
+            ? this.routeBindings.get(this.previousRoute.bindingsName)
+            : undefined;
+        // The leaving route's own coordinates (still in currentSnapshot until the
+        // reassignment below) key its preserved-state slot on exit (Store §6.4).
+        // Wave 3 §2b — also thread the route we're going TO (its coords, derived
+        // here BEFORE the snapshot is updated) so subtree-aware stores can decide
+        // whether to keep their instance alive. `null` when no matched route on
+        // the destination (404).
+        const toCtx = matched
+            ? { pathname, params, query: parsedQuery }
+            : null;
+        if (prevBindings) {
+            prevBindings.onExit({
+                pathname: this.currentSnapshot.pathname,
+                params: this.currentSnapshot.params,
+                query: this.currentSnapshot.query,
+            }, toCtx);
+        }
+        const nextBindings = matched?.bindingsName != null
+            ? this.routeBindings.get(matched.bindingsName)
+            : undefined;
+        // Snapshot must be set BEFORE the catch-up path can read it, and the
+        // current-entered flag reset for the newly-matched route.
+        this.previousRoute = matched;
+        this.currentSnapshot = { pathname, params, query: parsedQuery, route: matched };
+        if (nextBindings) {
+            nextBindings.onEnter({ pathname, params, query: parsedQuery });
+            this.currentEntered = true;
+        }
+        else {
+            // No bindings: either the route has no route store (nothing to enter), or
+            // its page chunk hasn't loaded yet (code-split, §5.2) — registerRouteBindings
+            // fires the catch-up onEnter once the chunk registers them.
+            this.currentEntered = false;
+        }
+        // Opt-in replay route tap (Replay §5) — a no-op `?.` until the replay
+        // receiver installs it. No router→replay dependency.
+        globalThis.__REACTRA_REPLAY_ROUTE__?.({
+            pathname,
+            search: this.currentQuery,
+            params,
+            query: parsedQuery,
+        });
+        for (const l of this.listeners)
+            l();
+    };
+    /** Subscribe to route changes. useSyncExternalStore feeds React this. */
+    subscribe = (onChange) => {
+        this.listeners.add(onChange);
+        return () => this.listeners.delete(onChange);
+    };
+    /**
+     * Install the middleware `ctx.service` resolver (Middleware spec v2 §3).
+     * Called by `@reactra/service`'s `bindScopedServicesToRouter` through the
+     * structural `RouterLike` contract — never by app code. Internal tier
+     * (Runtime v1 §1); delegates to the middleware module's slot.
+     */
+    __setMiddlewareServiceResolver = (resolver) => {
+        __setMiddlewareServiceResolver(resolver);
+    };
+    /** Current route snapshot — stable reference until the next transition. */
+    getSnapshot = () => this.currentSnapshot;
+    /** Read-only access for tests + the browser-sync helper. */
+    getCurrentPathname = () => this.currentPathname;
+    getCurrentQuery = () => this.currentQuery;
+    /**
+     * Register the per-route middleware chains emitted by the walker (Wave 3,
+     * Stage 2). Accepts either a `Map` or a plain record (the
+     * `router-middleware.generated.ts` shape). Overwrites the prior set — the
+     * generated file's HMR re-registration goes through here.
+     */
+    setMiddlewareChains = (chains) => {
+        this.middlewareChains.clear();
+        if (chains instanceof Map) {
+            for (const [k, v] of chains)
+                this.middlewareChains.set(k, v);
+        }
+        else {
+            for (const [k, v] of Object.entries(chains))
+                this.middlewareChains.set(k, v);
+        }
+    };
+    /**
+     * Read the registered chain for a route path, or `undefined` if none.
+     * Returning `undefined` (rather than `[]`) lets the caller short-circuit
+     * the async wrapper for the empty-chain fast path.
+     */
+    getMiddlewareChain = (routePath) => this.middlewareChains.get(routePath);
+    /** All registered routes — used by `navigate` to match before running the chain. */
+    getRoutes = () => this.routes;
+}
+/**
+ * The process-wide router singleton. The compiler emits imports of this
+ * (via `useRoute`) and the codegen-emitted `routeBindings` reference it
+ * indirectly through the page component's lifecycle hooks.
+ */
+export const RouterRegistry = new RouterRegistryImpl();
+// ---------------------------------------------------------------------------
+// PrefetchRuntime (Router §5.5 / §8.5) — chunk + data warming.
+//
+// `RouteLink` calls `warm(to, params, query)` on its trigger (hover / visible /
+// mount) to fetch the destination route's code-split chunk AND pre-fill its
+// route stores' resources (Resource v1 Stage E) ahead of navigation. `cancel`
+// aborts the per-key AbortController so the data warmers stop fetching.
+//
+// The `inflight` set dedups concurrent triggers for the same destination
+// (keyed by route + params + query, so two links to the same pattern with
+// different params don't share a slot). A per-key AbortController in
+// `warmControllers` is what `cancel` aborts to stop in-flight data warming
+// (chunk imports themselves aren't abortable — harmless, browser-cached).
+// ---------------------------------------------------------------------------
+const prefetchKey = (to, params, query) => `${to}|${JSON.stringify(params ?? {})}|${JSON.stringify(query ?? {})}`;
+class PrefetchRuntimeImpl {
+    inflight = new Set();
+    // Stage E (Resource v1 §8.5) — per-key AbortController. `cancel(...)` aborts
+    // it so destination `bindings.warm(ctx, signal)` data warmers stop fetching.
+    warmControllers = new Map();
+    /**
+     * Warm the destination route ahead of navigation. Fires the code-split
+     * chunk preload (if any) AND the compiler-emitted route-bindings warmer
+     * (Stage E) which pre-fills the resource cache via `warmResource`. No-op
+     * if the route is already warming this exact `(to, params, query)`. Both
+     * branches share the dedup key; both fire under a per-key AbortController
+     * that `cancel(...)` aborts on real navigation.
+     */
+    warm = (to, params = {}, query = {}) => {
+        const route = RouterRegistry.getRouteByPath(to);
+        const hasChunk = route?.preload !== undefined;
+        const bindings = route?.bindingsName != null
+            ? RouterRegistry.lookupRouteBindings(route.bindingsName)
+            : undefined;
+        const hasData = bindings?.warm !== undefined;
+        if (!hasChunk && !hasData)
+            return;
+        const key = prefetchKey(to, params, query);
+        if (this.inflight.has(key))
+            return;
+        this.inflight.add(key);
+        const ctrl = new AbortController();
+        this.warmControllers.set(key, ctrl);
+        const tasks = [];
+        if (hasChunk && route?.preload !== undefined) {
+            tasks.push(Promise.resolve(route.preload()).catch((e) => {
+                console.warn("[reactra:prefetch] chunk", to, e);
+            }));
+        }
+        if (hasData && bindings?.warm !== undefined) {
+            const ctx = {
+                pathname: to,
+                params: params,
+                query: query,
+            };
+            tasks.push(bindings.warm(ctx, ctrl.signal).catch(() => { }));
+        }
+        void Promise.allSettled(tasks).finally(() => {
+            this.inflight.delete(key);
+            this.warmControllers.delete(key);
+        });
+    };
+    /**
+     * Clear the dedup slot for a specific destination (params+query given) or
+     * for every in-flight warmup of a route (params+query omitted — used on real
+     * navigation). Aborts the per-key controller so any in-flight data warmer
+     * stops fetching (chunk imports stay running — harmless and browser-cached).
+     */
+    cancel = (to, params, query) => {
+        if (params === undefined && query === undefined) {
+            for (const key of [...this.inflight]) {
+                if (key.startsWith(`${to}|`)) {
+                    this.warmControllers.get(key)?.abort();
+                    this.warmControllers.delete(key);
+                    this.inflight.delete(key);
+                }
+            }
+            return;
+        }
+        const key = prefetchKey(to, params, query);
+        this.warmControllers.get(key)?.abort();
+        this.warmControllers.delete(key);
+        this.inflight.delete(key);
+    };
+}
+/** Process-wide prefetch singleton (Router §8.5). */
+export const PrefetchRuntime = new PrefetchRuntimeImpl();
+// Module-level mode set by configureRouter, read by navigate. Hash by
+// default — preserves the Day-10a contract for callers that don't pass
+// a `mode`. The `routerMode` getter exists for tests; production callers
+// should not need to read this.
+let routerMode = "hash";
+export const __getRouterMode = () => routerMode;
+// Suspense fallback shown while a code-split route chunk loads (§5.2). Default
+// null (blank during the brief chunk fetch). Per-route `_loading.tsx` boundaries
+// are Wave 3; set a single app-wide fallback via `configureRouter({ loadingFallback })`.
+let routerLoadingFallback = null;
+// Wave 3, §2b — scroll restoration. Configured via `configureRouter({
+// scrollRestoration })`; null until the app opts in. The navigate-
+// integration site short-circuits when null so apps that don't configure
+// it get the prior behaviour (no scroll management at all).
+let scrollManager = null;
+// Tracks the LEAVING entry's history key so the slow-path (post-middleware)
+// commit can save scroll for the correct entry — by the time the async
+// chain resolves, the browser may have moved on, so we snapshot at the
+// navigate() boundary.
+let lastKnownHistoryKey = null;
+/**
+ * Bootstrap call — invoked from `src/main.tsx` per Runtime v0 §5. Registers
+ * every route the app cares about, then attaches to the browser's location
+ * (hash or History API depending on `mode`) if `window` is available. Order
+ * rules: `configureStores` must precede `configureRouter` (route stores
+ * depend on the registry).
+ *
+ * `mode`:
+ *   - `"hash"` (default): URL fragment drives routing
+ *     (`#/customers/1`). No server config needed; works on static hosts.
+ *   - `"history"`: real paths (`/customers/1`) drive routing via the
+ *     History API. The dev server / production host MUST serve the SPA
+ *     fallback (index.html) for any non-asset path. Vite's default
+ *     `appType: "spa"` does this automatically.
+ */
+export const configureRouter = (config) => {
+    for (const r of config.routes)
+        RouterRegistry.register(r);
+    routerMode = config.mode ?? "hash";
+    if (config.loadingFallback !== undefined)
+        routerLoadingFallback = config.loadingFallback;
+    if (config.middlewareChains !== undefined) {
+        RouterRegistry.setMiddlewareChains(config.middlewareChains);
+    }
+    if (config.scrollRestoration !== undefined) {
+        scrollManager = createScrollManager({
+            defaultMode: config.scrollRestoration.defaultMode ?? "auto",
+            scrollKey: config.scrollRestoration.scrollKey ?? "reactra:scroll",
+        });
+        // Disable the browser's native scroll restoration so our manager owns
+        // it end-to-end. Without this the browser would also restore on
+        // popstate, racing our explicit `scrollTo` call.
+        if (typeof window !== "undefined" && "scrollRestoration" in window.history) {
+            try {
+                window.history.scrollRestoration = "manual";
+            }
+            catch {
+                // older Safari throws on assignment — non-fatal, browser default
+                // restoration still works.
+            }
+        }
+        // Ensure the initial entry carries a key so subsequent navigations can
+        // save+restore against a stable id.
+        lastKnownHistoryKey = ensureHistoryKey();
+    }
+    // Attach to the browser only if we're in one. In SSR / Node tests, the
+    // pure core (drive via navigate(...)) is the API.
+    if (typeof window === "undefined")
+        return;
+    if (routerMode === "hash") {
+        const sync = () => {
+            // Before driving setLocation: save the leaving entry's scroll so the
+            // user gets it back if they hit forward later, then drive the change.
+            if (scrollManager && lastKnownHistoryKey !== null) {
+                scrollManager.saveCurrent(lastKnownHistoryKey);
+            }
+            const raw = window.location.hash.slice(1) || "/";
+            const { pathname, query } = splitPathQuery(raw);
+            RouterRegistry.setLocation(pathname, query);
+            // hashchange events don't carry a stable per-entry key (the URL
+            // fragment is the only persisted bit). Use the pathname+query as a
+            // best-effort key — same URL revisit shares position. Adequate for
+            // hash mode; history mode below uses the proper history-state key.
+            if (scrollManager) {
+                const fakeKey = pathname + (query ? "?" + query : "");
+                scrollManager.applyForNavigation(fakeKey, "pop");
+                lastKnownHistoryKey = fakeKey;
+            }
+        };
+        window.addEventListener("hashchange", sync);
+        sync();
+    }
+    else {
+        // History mode: popstate fires on browser back/forward; pushState
+        // does NOT fire popstate, so navigate() drives setLocation directly
+        // (see below).
+        const sync = (isInitial) => {
+            if (scrollManager && lastKnownHistoryKey !== null) {
+                scrollManager.saveCurrent(lastKnownHistoryKey);
+            }
+            const pathname = window.location.pathname || "/";
+            const search = window.location.search;
+            const query = search.startsWith("?") ? search.slice(1) : search;
+            RouterRegistry.setLocation(pathname, query);
+            if (scrollManager) {
+                const key = readHistoryKey() ?? ensureHistoryKey();
+                // Initial mount is a synthetic "pop" (the user arrived at this URL
+                // directly, possibly with a back-forward cache); restore if we have
+                // a saved entry, otherwise scroll-to-top. Subsequent popstates
+                // (back / forward) also use "pop". Push events come through
+                // `commitNavigation`, not this listener.
+                scrollManager.applyForNavigation(key, isInitial ? "pop" : "pop");
+                lastKnownHistoryKey = key;
+            }
+        };
+        window.addEventListener("popstate", () => sync(false));
+        sync(true);
+    }
+};
+/**
+ * Commit a new pathname + query to the registry, including the browser-
+ * history bookkeeping appropriate to the configured mode. Extracted so
+ * both the empty-chain fast path AND the post-middleware slow path can
+ * share the same commit step.
+ */
+const commitNavigation = (to, replace, pathname, query) => {
+    if (typeof window === "undefined") {
+        RouterRegistry.setLocation(pathname, query);
+        return;
+    }
+    // Save the leaving entry's scroll position BEFORE the URL changes so the
+    // window.scrollX/Y readings reflect the right entry. No-op when
+    // scrollManager is null (app opted out of scroll restoration entirely).
+    if (scrollManager && lastKnownHistoryKey !== null) {
+        scrollManager.saveCurrent(lastKnownHistoryKey);
+    }
+    let newKey = null;
+    if (routerMode === "hash") {
+        // Hash mode: replaceState swaps the current entry; assigning
+        // location.hash always pushes. Honour `replace` by editing the
+        // existing entry's hash in place.
+        if (replace) {
+            if (scrollManager) {
+                newKey = replaceStateWithKey({}, `#${to}`);
+            }
+            else {
+                window.history.replaceState({}, "", `#${to}`);
+            }
+            RouterRegistry.setLocation(pathname, query);
+        }
+        else {
+            window.location.hash = to;
+            // The hashchange listener fires post-assignment; it handles
+            // setLocation + scroll. Skip the post-commit scroll branch below.
+            lastKnownHistoryKey = pathname + (query ? "?" + query : "");
+            return;
+        }
+    }
+    else {
+        if (replace) {
+            if (scrollManager) {
+                newKey = replaceStateWithKey({}, to);
+            }
+            else {
+                window.history.replaceState({}, "", to);
+            }
+        }
+        else {
+            if (scrollManager) {
+                newKey = pushStateWithKey({}, to);
+            }
+            else {
+                window.history.pushState({}, "", to);
+            }
+        }
+        RouterRegistry.setLocation(pathname, query);
+    }
+    // Apply mode-specific scroll behaviour after the registry commit. Push +
+    // replace both treat as "push" (no restore — the user just initiated a
+    // forward navigation). On `auto` mode this is scroll-to-top.
+    if (scrollManager) {
+        scrollManager.applyForNavigation(newKey, replace ? "replace" : "push");
+        lastKnownHistoryKey = newKey;
+    }
+};
+/**
+ * Build the {@link MiddlewareContext} for a navigation. The `to` coordinate
+ * is the resolved target; `from` snapshots the current route's coordinates
+ * (or `null` when there's no prior route — initial navigation).
+ */
+const buildMiddlewareContextFor = (toRoutePath, toPathname, toParams, toQuery) => {
+    const cur = RouterRegistry.getSnapshot();
+    const from = cur.route
+        ? {
+            pathname: cur.pathname,
+            params: cur.params,
+            query: cur.query,
+            meta: {},
+            routeId: cur.route.path,
+        }
+        : null;
+    return {
+        to: {
+            pathname: toPathname,
+            params: toParams,
+            query: toQuery,
+            meta: {},
+            routeId: toRoutePath,
+        },
+        from,
+        ...buildContextCommands(),
+    };
+};
+/**
+ * Navigate to a new path. Three flow shapes per Wave 3, Stage 3:
+ *
+ *   - **No matched route OR empty middleware chain (fast path).** Commit
+ *     synchronously — preserves the existing behaviour for every route
+ *     that doesn't have a `_middleware.ts` ancestor.
+ *
+ *   - **Non-empty middleware chain.** Fire-and-forget: build the
+ *     {@link MiddlewareContext}, run `runBeforeEnterChain` async, then:
+ *       - `redirect` command → recursive `navigate(cmd.path, cmd.replace)`.
+ *       - `abort` command    → return without commit (current route stays).
+ *       - allow              → commit, then run the PREVIOUS route's
+ *                              `afterLeave` chain in reverse.
+ *     The function returns `void` synchronously; tests should await an
+ *     `await Promise.resolve()` tick to see the post-chain state.
+ *
+ * Transport per mode:
+ *   - `hash`:    `window.location.hash = to` (fires `hashchange` →
+ *                `RouterRegistry.setLocation`).
+ *   - `history`: `history.pushState(...)` then drives `setLocation`
+ *                directly (pushState does NOT fire `popstate`).
+ *
+ * In pure Node (tests), `setLocation` is called regardless so the registry
+ * is observable without a DOM.
+ *
+ * **Limitation — popstate / hashchange (browser back/forward).** Those
+ * paths skip the middleware chain in this stage: by the time the event
+ * fires, the URL has already changed in the browser, and fighting that
+ * with a back-push is fragile. A follow-up will harden this by replacing
+ * the offending history entry on abort and chaining to the redirect
+ * target. The same applies to the initial-mount `sync()`.
+ */
+export const navigate = (to, replace = false) => {
+    const { pathname, query } = splitPathQuery(to);
+    // Match the target route synchronously to decide which flow to use.
+    let matched = null;
+    let params = {};
+    for (const r of RouterRegistry.getRoutes()) {
+        const m = matchRoute(r.path, pathname);
+        if (m) {
+            matched = r;
+            params = m;
+            break;
+        }
+    }
+    const chain = matched
+        ? RouterRegistry.getMiddlewareChain(matched.path)
+        : undefined;
+    if (!chain || chain.length === 0) {
+        // Fast path — preserves prior synchronous behaviour exactly.
+        commitNavigation(to, replace, pathname, query);
+        return;
+    }
+    // Slow path — async chain. Snapshot the LEAVING route's chain BEFORE the
+    // commit so afterLeave can run against it after the new route's onEnter.
+    const leavingRoute = RouterRegistry.getSnapshot().route;
+    const leavingChain = leavingRoute !== null
+        ? RouterRegistry.getMiddlewareChain(leavingRoute.path) ?? []
+        : [];
+    void (async () => {
+        const ctx = buildMiddlewareContextFor(matched.path, pathname, params, parseQuery(query));
+        const cmd = await runBeforeEnterChain(chain, ctx);
+        if (cmd?.type === "redirect") {
+            navigate(cmd.path, cmd.replace);
+            return;
+        }
+        if (cmd?.type === "abort") {
+            // No commit; current route stays. Spec §6.1 atomicity guarantee.
+            return;
+        }
+        // Allowed — commit, then run leaving route's afterLeave chain in reverse.
+        commitNavigation(to, replace, pathname, query);
+        if (leavingChain.length > 0) {
+            // The afterLeave ctx still describes the SAME transition (to/from
+            // mirror the beforeEnter ctx). Errors are swallowed at the
+            // navigation boundary — a noisy afterLeave shouldn't corrupt the
+            // already-committed navigation.
+            try {
+                await runAfterLeaveChain(leavingChain, ctx);
+            }
+            catch (err) {
+                if (typeof console !== "undefined") {
+                    console.error("[@reactra/router] afterLeave threw — swallowing post-commit", err);
+                }
+            }
+        }
+    })();
+};
+/**
+ * React hook returning the active route state. Subscribes via
+ * `useSyncExternalStore` so a component re-renders when the route changes.
+ */
+export const useRoute = () => {
+    const subscribe = useCallback((onChange) => RouterRegistry.subscribe(onChange), []);
+    const getSnapshot = useCallback(() => RouterRegistry.getSnapshot(), []);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+};
+/**
+ * Merge `updates` into a current query object, returning a fresh plain object.
+ * Values are coerced to strings (the query bag is string-valued); a key set to
+ * `undefined` is REMOVED. Pure — the testable core of {@link useQueryUpdater}.
+ */
+export const mergeQuery = (current, updates) => {
+    const out = { ...current };
+    for (const [k, v] of Object.entries(updates)) {
+        if (v === undefined)
+            delete out[k];
+        // Arrays carry through (a `string[]` query field round-trips via buildPath's
+        // repeated-key serialization); scalars stringify.
+        else if (Array.isArray(v))
+            out[k] = v.map(String);
+        else
+            out[k] = String(v);
+    }
+    return out;
+};
+/**
+ * React hook: does the current pathname match `pattern`? Returns the extracted
+ * params (`{}` for a param-less match) or `null` if it doesn't match. Useful
+ * for highlighting nav, conditional UI, or reading params for a pattern other
+ * than the active route. Subscribes to route changes via {@link useRoute}.
+ */
+export const useRouteMatch = (pattern) => {
+    const { pathname } = useRoute();
+    return matchRoute(pattern, pathname);
+};
+/**
+ * React hook returning a query-updater bound to the CURRENT route: call it with
+ * a partial `{ key: value }` to merge into the existing query and navigate to
+ * the same pathname with the new query string (a key set to `undefined` is
+ * removed). The URL stays the source of truth (Router §3.4 — query fields are
+ * read-only state sourced from the URL; to change one you navigate).
+ *
+ *   const setQuery = useQueryUpdater()
+ *   setQuery({ page: 2 })                 // /customers → /customers?page=2
+ *   setQuery({ page: undefined }, { replace: true })  // drop `page`, replace entry
+ */
+export const useQueryUpdater = () => {
+    const { pathname, query } = useRoute();
+    return useCallback((updates, options) => {
+        navigate(buildPath(pathname, undefined, mergeQuery(query, updates)), options?.replace ?? false);
+    }, [pathname, query]);
+};
+class RouteErrorBoundary extends Component {
+    state = { error: null };
+    static getDerivedStateFromError = (error) => ({ error });
+    reset = () => this.setState({ error: null });
+    render() {
+        if (this.state.error != null) {
+            return createElement(this.props.ErrorComp, { error: this.state.error, reset: this.reset });
+        }
+        return this.props.children;
+    }
+}
+/**
+ * Render the currently active route's component. Returns null when no route
+ * matches — Phase 1 demos can wrap with their own 404 layer. The route is
+ * composed (innermost → outermost) as:
+ *   page → Suspense(loading) → layouts(innermost→outermost) → ErrorBoundary
+ * Layouts sit OUTSIDE the Suspense so they persist while the page area shows
+ * the loading fallback; the error boundary is outermost so it catches throws
+ * from any layout, the Suspense fallback, or the page (Router §2.3).
+ */
+export const RouteRenderer = () => {
+    const { route } = useRoute();
+    if (!route)
+        return null;
+    // Per-route `_loading.tsx` (§2.3, walker-resolved) wins over the global
+    // `configureRouter({ loadingFallback })`; without one, fall back to the
+    // app-wide default. Routes are code-split (`lazy()` in the manifest, §5.2),
+    // so the Suspense boundary catches the chunk-load suspension.
+    const fallback = route.loading ? createElement(route.loading) : routerLoadingFallback;
+    let content = createElement(Suspense, { fallback }, createElement(route.component));
+    // §2.3 `_layout.tsx` chain (outermost-first in the array). Wrap innermost
+    // first so each layout's `children` is the next-inner wrapper, ending with
+    // the page-in-Suspense at the bottom. Layouts are eagerly imported, so they
+    // render synchronously around a (suspending) page → typical "layout persists,
+    // content streams" pattern; only the page area swaps to the loading fallback.
+    if (route.layouts && route.layouts.length > 0) {
+        for (let i = route.layouts.length - 1; i >= 0; i--) {
+            content = createElement(route.layouts[i], null, content);
+        }
+    }
+    // §2.3 `_error.tsx` — outermost wrap; catches render-time throws from any
+    // layout, the Suspense fallback, or the page. Renders the user's component
+    // with `{ error, reset }` on a throw.
+    if (route.errorBoundary) {
+        content = createElement(RouteErrorBoundary, { ErrorComp: route.errorBoundary }, content);
+    }
+    return content;
+};
+/**
+ * Should a `RouteLink` click be intercepted for SPA navigation, or left to
+ * the browser? Standard SPA-link rules (Router §3.3): only a plain primary
+ * (left) click with no modifier keys, not already prevented, and not aimed
+ * at another browsing context (`target` other than `_self`). A modifier or
+ * middle click — "open in new tab" — falls through to native navigation.
+ */
+export const shouldInterceptClick = (e, target) => {
+    if (e.defaultPrevented)
+        return false;
+    if (e.button !== 0)
+        return false;
+    if (e.metaKey || e.ctrlKey || e.shiftKey || e.altKey)
+        return false;
+    if (target !== undefined && target !== "" && target !== "_self")
+        return false;
+    return true;
+};
+/**
+ * Is `linkPath` the active route given the current pathname? Pure so it's
+ * unit-testable without the router. Exact match (or the root `/`, which would
+ * otherwise prefix-match everything) compares equality; otherwise a link is
+ * active for its own path and any descendant (`/customers` is active on
+ * `/customers/c1`).
+ */
+export const isRouteActive = (currentPath, linkPath, exactMatch = false) => {
+    if (exactMatch || linkPath === "/")
+        return currentPath === linkPath;
+    if (currentPath === linkPath)
+        return true;
+    const base = linkPath.endsWith("/") ? linkPath.slice(0, -1) : linkPath;
+    return currentPath.startsWith(base + "/");
+};
+/**
+ * A navigation anchor. Renders a real `<a href>` (so it is a normal,
+ * right-clickable, middle-clickable link with a visible URL) and intercepts
+ * plain left-clicks to drive SPA navigation via {@link navigate} instead of a
+ * full document load. Replaces the hand-rolled
+ * `<a onClick={e => { e.preventDefault(); navigate(...) }}>` pattern.
+ *
+ * `prefetch` (Router §5.5) warms the destination chunk ahead of click — on
+ * hover/focus, on viewport entry (IntersectionObserver), or on mount. Phase 1
+ * warms the code-split chunk only; resource/data warming lands with Resource v1.
+ */
+export const RouteLink = (props) => {
+    const href = buildPath(props.to, props.params, props.query);
+    const { pathname } = useRoute();
+    const linkPath = splitPathQuery(href).pathname;
+    const active = isRouteActive(pathname, linkPath, props.exactMatch ?? false);
+    const className = [props.className, active ? props.activeClass : undefined].filter(Boolean).join(" ") ||
+        undefined;
+    const anchorRef = useRef(null);
+    const { to, params, query } = props;
+    // Effective trigger: an explicit `prefetch` prop overrides; otherwise inherit
+    // the destination route's declared `prefetch on <trigger>` policy (§5.5). An
+    // explicit `prefetch="none"` opts out even if the page declares a trigger.
+    const prefetch = props.prefetch ?? RouterRegistry.getRouteByPath(to)?.prefetch?.trigger;
+    // `mount` + `visible` are effect-driven; `hover` is a handler (below). The
+    // serialized params/query in deps re-arm the observer when the destination
+    // changes. Cleanup cancels any pending warmup for this destination.
+    const paramsKey = JSON.stringify(params ?? {});
+    const queryKey = JSON.stringify(query ?? {});
+    useEffect(() => {
+        if (!prefetch || prefetch === "none" || prefetch === "hover")
+            return;
+        if (prefetch === "mount") {
+            PrefetchRuntime.warm(to, params, query);
+            return () => PrefetchRuntime.cancel(to, params, query);
+        }
+        // "visible": warm when the link scrolls into view, then stop observing.
+        const el = anchorRef.current;
+        if (!el || typeof IntersectionObserver === "undefined")
+            return;
+        const obs = new IntersectionObserver((entries) => {
+            for (const entry of entries) {
+                if (entry.isIntersecting) {
+                    PrefetchRuntime.warm(to, params, query);
+                    obs.disconnect();
+                    break;
+                }
+            }
+        });
+        obs.observe(el);
+        return () => {
+            obs.disconnect();
+            PrefetchRuntime.cancel(to, params, query);
+        };
+        // params/query are compared by their serialized form (objects are fresh each render).
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [to, prefetch, paramsKey, queryKey]);
+    const onHoverWarm = prefetch === "hover" ? () => PrefetchRuntime.warm(to, params, query) : undefined;
+    return createElement("a", {
+        href,
+        className,
+        style: props.style,
+        target: props.target,
+        ref: anchorRef,
+        onPointerEnter: onHoverWarm,
+        onFocus: onHoverWarm,
+        onClick: (e) => {
+            if (!shouldInterceptClick(e, props.target))
+                return;
+            e.preventDefault();
+            // Real navigation supersedes any in-flight warmup for this destination.
+            PrefetchRuntime.cancel(to, params, query);
+            navigate(href, props.replace ?? false);
+        },
+    }, props.children);
+};
+// ─── <Portal> — user-facing runtime component (createPortal wrapper) ────────
+export { Portal } from "./portal.js";
+// ─── `_middleware.ts` route-guard API — re-exports ─────────────────────────
+export { buildContextCommands, compose, defineMiddleware, isAbortCommand, isRedirectCommand, runAfterLeaveChain, runBeforeEnterChain, } from "./middleware.js";
+// ─── Scroll restoration — re-exports (Wave 3, §2b) ─────────────────────────
+export { createScrollManager, generateHistoryKey } from "./scrollManager.js";
+//# sourceMappingURL=index.js.map