@reactra/router 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akhil Shastri and the Reactra contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @reactra/router
+
+> Reactra router runtime — file-based routing, params/query, navigation, and middleware.
+
+**Alpha** — published under the npm dist-tag `alpha`. APIs may change before 1.0.
+
+```bash
+npm install @reactra/router@alpha
+```
+
+Part of [Reactra](https://github.com/akhilshastri/reactra) — a compiler-first,
+React-19-compatible framework. See the [documentation](https://reactra-docs.vercel.app) to get
+started.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,508 @@
+import type { CSSProperties, ComponentType, LazyExoticComponent, ReactNode } from "react";
+import type { MiddlewareDef } from "./middleware.ts";
+import type { ScrollRestorationMode } from "./scrollManager.ts";
+/**
+ * Routing bindings the compiler registers for a page component with
+ * argumented `use storeX(...)`. The router looks these up by NAME on enter /
+ * exit (see {@link RouterRegistryImpl.registerRouteBindings}).
+ *
+ * Day 16 (`#18b`): name-keyed registration replaced the prior
+ * `Object.assign(component, { routeBindings })` wrap. The wrap broke React
+ * Fast Refresh's export-compatibility check, forcing a full reload on every
+ * edit to a mixed page+route-store file. With name-keyed registration, the
+ * page export is a plain arrow Fast Refresh accepts, and the
+ * `RouterRegistry.registerRouteBindings("Foo", { … })` module-level call
+ * overwrites the bindings entry under the same name when the module
+ * re-evaluates after HMR.
+ */
+/** Route-entry coordinates handed to onEnter/onExit; keys preserved-state slots (§8.4). */
+export interface RouteLifecycleCtx {
+    pathname: string;
+    params: Record<string, string>;
+    query: Record<string, string | string[]>;
+}
+export interface RouteBindings {
+    onEnter: (ctx: RouteLifecycleCtx) => void;
+    onExit: (fromCtx: RouteLifecycleCtx, toCtx?: RouteLifecycleCtx | null) => void;
+    /**
+     * Stage E (Resource v1 §8.3 / §8.5) — compiler-emitted prefetch warmer.
+     * `PrefetchRuntime.warm(to, params, query)` calls this with the parsed
+     * lifecycle ctx + a per-key AbortController signal so destination route
+     * stores' `warm(inputs, signal)` companions can pre-fill the resource
+     * cache ahead of real navigation. Bindings that own no route stores
+     * with resources omit this; PrefetchRuntime treats absence as a no-op.
+     * Best-effort: returned promise resolves silently on any failure (matches
+     * the warmResource contract — RES015 deliberately not minted).
+     */
+    warm?: (ctx: RouteLifecycleCtx, signal: AbortSignal) => Promise<void>;
+}
+/**
+ * A page component is a plain React function component, or — once routes are
+ * code-split (§5.2) — the `lazy()`-wrapped exotic component the generated
+ * manifest emits (`component: lazy(() => import("./pages/..."))`). Day-16 `#18b`
+ * dropped the `routeBindings?` field — bindings are stored in the registry by
+ * name, not on the component identity itself.
+ */
+export type PageComponent = ComponentType | LazyExoticComponent<ComponentType>;
+/**
+ * Route registration shape. The user passes these to `configureRouter` —
+ * one entry per page. `path` is a pattern with `:name` placeholders matching
+ * URL segments. `bindingsName` is set by the walker for pages with
+ * argumented `use storeX(...)` so the router can look up the
+ * compiler-registered route bindings on enter / exit.
+ */
+/**
+ * Prefetch trigger for a route / `RouteLink` (Router §5.5). `none` disables it.
+ * `visible` uses an IntersectionObserver; `hover` fires on pointer-enter/focus;
+ * `mount` warms as soon as a link to the route renders.
+ */
+export type PrefetchTrigger = "hover" | "visible" | "mount" | "none";
+export interface RouteConfig {
+    id: string;
+    path: string;
+    component: PageComponent;
+    /**
+     * §5.2/§5.5 — warms this route's code-split chunk: the SAME dynamic import the
+     * `component` `lazy()` wraps, exposed as a bare thunk the walker emits so
+     * {@link PrefetchRuntime} can trigger the fetch ahead of navigation. Rollup
+     * dedups — `lazy(() => import(X))` and `() => import(X)` share one chunk.
+     */
+    preload?: () => Promise<unknown>;
+    /**
+     * §5.5 — the page's declared `prefetch on <trigger>` policy. Reserved: the
+     * walker does not emit it yet (the page-keyword→manifest hop is a follow-up),
+     * so in Phase 1 the `RouteLink` `prefetch` prop is the driver.
+     */
+    prefetch?: {
+        trigger: PrefetchTrigger;
+    };
+    /**
+     * §2.3 `_loading.tsx` — the nearest-ancestor loading component the walker
+     * resolved for this route (file convention). `RouteRenderer` uses it as the
+     * Suspense fallback in place of the global `configureRouter({ loadingFallback })`.
+     * Eagerly imported in the manifest so it renders synchronously when the
+     * route's lazy chunk suspends.
+     */
+    loading?: ComponentType;
+    /**
+     * §2.3 `_error.tsx` — the nearest-ancestor error boundary component the walker
+     * resolved for this route. `RouteRenderer` wraps the route in a
+     * {@link RouteErrorBoundary} that renders this component with `{ error, reset }`
+     * props on a render-time throw. Eagerly imported so it renders synchronously
+     * (a lazy error UI that itself suspends would surface as a confusing loading
+     * state while the error is in flight).
+     */
+    errorBoundary?: ComponentType<{
+        error: unknown;
+        reset: () => void;
+    }>;
+    /**
+     * §2.3 `_layout.tsx` — the full ancestor chain (outermost-first) wrapping the
+     * page. Each layout receives `children` (the next inner layout, or the
+     * page-with-Suspense at the bottom of the chain). Eagerly imported so layouts
+     * persist around a (suspending) page below — only the page area shows the
+     * route's loading fallback.
+     */
+    layouts?: ReadonlyArray<ComponentType<{
+        children?: ReactNode;
+    }>>;
+    bindingsName?: string;
+}
+/**
+ * What `useRoute()` returns. `route` is the matched config (or `null` if
+ * the current pathname doesn't match any route — the renderer shows nothing).
+ */
+export interface RouteState {
+    pathname: string;
+    params: Record<string, string>;
+    /** Repeated keys (`?tag=x&tag=y`) arrive as arrays — backs `query foo: string[]`. */
+    query: Record<string, string | string[]>;
+    route: RouteConfig | null;
+}
+/**
+ * The transition shape handed to the optional replay route tap (Replay §5).
+ * Carries everything the receiver needs to fold a `Route#1` state_snapshot and
+ * reconstruct the navigable `path` (`pathname` + raw query string), without the
+ * receiver re-serializing the query.
+ */
+export interface ReplayRouteState {
+    pathname: string;
+    /** Raw query string WITHOUT a leading `?` (the router's `currentQuery`). */
+    search: string;
+    params: Record<string, string>;
+    query: Record<string, string | string[]>;
+}
+/**
+ * Opt-in replay route tap (Replay §5). The router calls this — when installed —
+ * on every committed transition, so `@reactra/behaviours/replayable` can record a
+ * `Route#1` snapshot WITHOUT the router depending on the replay runtime. Mirrors
+ * the `__REACTRA_TEST__` neutral-global pattern; a no-op `?.` until the replay
+ * receiver installs it (`configureReplay`).
+ */
+declare global {
+    var __REACTRA_REPLAY_ROUTE__: ((route: ReplayRouteState) => void) | undefined;
+}
+/**
+ * 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 declare const matchRoute: (pattern: string, pathname: string) => Record<string, string> | null;
+/**
+ * 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 declare const buildPath: (pattern: string, params?: Record<string, string>, query?: Record<string, string | number | boolean | ReadonlyArray<string | number | boolean>>) => string;
+/**
+ * How a `query` field should be coerced from its raw URL string, per the
+ * page's declared type (Router §3.1 coercion table). A `readonly string[]`
+ * is a string-literal-union (enum) whose members are the allowed raw values
+ * (e.g. `["active", "archived"]`). `"string"` is passthrough.
+ */
+export type QueryCoercion = "string" | "number" | "boolean" | "string[]" | readonly string[];
+/**
+ * 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 declare const coerceQuery: (raw: string | readonly string[] | undefined, kind: QueryCoercion, fallback?: unknown) => unknown;
+declare class RouterRegistryImpl {
+    private routes;
+    private listeners;
+    private currentPathname;
+    private currentQuery;
+    private currentSnapshot;
+    private previousRoute;
+    private routeBindings;
+    private currentEntered;
+    private middlewareChains;
+    /** Register a route. Idempotent on `id` — re-registering replaces. */
+    register: (route: RouteConfig) => void;
+    /**
+     * 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: readonly RouteConfig[]) => void;
+    /**
+     * 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: string, bindings: RouteBindings) => void;
+    /** Read access for tests + setLocation lifecycle. */
+    lookupRouteBindings: (name: string) => RouteBindings | undefined;
+    /**
+     * 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: string) => RouteConfig | undefined;
+    /**
+     * 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: string, query: string) => void;
+    /** Subscribe to route changes. useSyncExternalStore feeds React this. */
+    subscribe: (onChange: () => void) => (() => void);
+    /**
+     * 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: (name: string) => unknown) => void;
+    /** Current route snapshot — stable reference until the next transition. */
+    getSnapshot: () => RouteState;
+    /** Read-only access for tests + the browser-sync helper. */
+    getCurrentPathname: () => string;
+    getCurrentQuery: () => string;
+    /**
+     * 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: ReadonlyMap<string, ReadonlyArray<MiddlewareDef>> | Readonly<Record<string, ReadonlyArray<MiddlewareDef>>>) => void;
+    /**
+     * 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: string) => ReadonlyArray<MiddlewareDef> | undefined;
+    /** All registered routes — used by `navigate` to match before running the chain. */
+    getRoutes: () => readonly RouteConfig[];
+}
+/**
+ * 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 declare const RouterRegistry: RouterRegistryImpl;
+declare class PrefetchRuntimeImpl {
+    private inflight;
+    private warmControllers;
+    /**
+     * 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: string, params?: Record<string, unknown>, query?: Record<string, unknown>) => void;
+    /**
+     * 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: string, params?: Record<string, unknown>, query?: Record<string, unknown>) => void;
+}
+/** Process-wide prefetch singleton (Router §8.5). */
+export declare const PrefetchRuntime: PrefetchRuntimeImpl;
+export declare const __getRouterMode: () => "hash" | "history";
+/**
+ * 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 declare const configureRouter: (config: {
+    routes: RouteConfig[];
+    mode?: "hash" | "history";
+    /** Suspense fallback while a code-split route chunk loads (§5.2). Default null. */
+    loadingFallback?: ReactNode;
+    /**
+     * Wave 3, Stage 3 — per-route middleware chains. Typically the
+     * `middlewareChains` export of the walker-generated
+     * `router-middleware.generated.ts`. Omitting it leaves no chains
+     * registered (the same effect as the empty-map case from a fresh-clone
+     * project with no `_middleware.ts` files).
+     */
+    middlewareChains?: ReadonlyMap<string, ReadonlyArray<MiddlewareDef>> | Readonly<Record<string, ReadonlyArray<MiddlewareDef>>>;
+    /**
+     * Wave 3, §2b — app-wide scroll restoration policy. Spec §3.5 + §13.1.
+     * `defaultMode` applies to every route until the per-page meta classifier
+     * lands (then `meta { scrollRestoration: "manual" }` overrides per page).
+     *   - `auto` (recommended): scroll-to-top on push, restore saved on pop.
+     *   - `top`:                always scroll-to-top.
+     *   - `manual`:             the app controls scroll explicitly.
+     * `scrollKey` is the sessionStorage namespace (default `"reactra:scroll"`).
+     * Omitting the whole field leaves scroll management unmanaged (browser
+     * default — historical Phase-1 behaviour).
+     */
+    scrollRestoration?: {
+        defaultMode?: ScrollRestorationMode;
+        scrollKey?: string;
+    };
+}) => void;
+/**
+ * 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 declare const navigate: (to: string, replace?: boolean) => void;
+/**
+ * React hook returning the active route state. Subscribes via
+ * `useSyncExternalStore` so a component re-renders when the route changes.
+ */
+export declare const useRoute: () => RouteState;
+/**
+ * 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 declare const mergeQuery: (current: Record<string, string | string[]>, updates: Record<string, string | number | boolean | ReadonlyArray<string | number | boolean> | undefined>) => Record<string, string | string[]>;
+/**
+ * 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 declare const useRouteMatch: (pattern: string) => Record<string, string> | null;
+/**
+ * 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 declare const useQueryUpdater: () => ((updates: Record<string, string | number | boolean | undefined>, options?: {
+    replace?: boolean;
+}) => void);
+/**
+ * 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 declare const RouteRenderer: () => ReactNode;
+/**
+ * Shape of the bits of a click event `RouteLink` needs to decide whether to
+ * intercept. Kept structural (not React's `MouseEvent`) so the decision is a
+ * pure, DOM-free, unit-testable function.
+ */
+export interface ClickLike {
+    button: number;
+    metaKey: boolean;
+    ctrlKey: boolean;
+    shiftKey: boolean;
+    altKey: boolean;
+    defaultPrevented: boolean;
+}
+/**
+ * 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 declare const shouldInterceptClick: (e: ClickLike, target?: string) => boolean;
+/**
+ * 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 declare const isRouteActive: (currentPath: string, linkPath: string, exactMatch?: boolean) => boolean;
+/**
+ * Props for the runtime {@link RouteLink}. `to` is a route pattern (e.g.
+ * `/customers/:id`); `params` fills its `:name` segments and `query` becomes
+ * the query string — both via {@link buildPath}. The generated manifest
+ * re-exports a typed wrapper whose `to`/`params`/`query` are checked against
+ * `RouteId`/`RouteParams`/`RouteQuery` (Router §3.3, `#5c-typed`).
+ */
+export interface RouteLinkProps {
+    to: string;
+    params?: Record<string, string>;
+    query?: Record<string, string | number | boolean>;
+    replace?: boolean;
+    /** Class applied (in addition to `className`) when this link's route is active. */
+    activeClass?: string;
+    /** Active only on an exact pathname match (default: also active for descendants). */
+    exactMatch?: boolean;
+    className?: string;
+    style?: CSSProperties;
+    target?: string;
+    children?: ReactNode;
+    /**
+     * §5.5 — warm the destination route's code-split chunk ahead of click:
+     * `"hover"` (pointer-enter/focus), `"visible"` (IntersectionObserver),
+     * `"mount"` (on render), or `"none"`/omitted (no prefetch). Phase 1 warms the
+     * chunk only; data warming lands with Resource v1.
+     */
+    prefetch?: PrefetchTrigger;
+}
+/**
+ * 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 declare const RouteLink: (props: RouteLinkProps) => ReactNode;
+export { Portal } from "./portal.ts";
+export type { PortalProps } from "./portal.ts";
+export { buildContextCommands, compose, defineMiddleware, isAbortCommand, isRedirectCommand, runAfterLeaveChain, runBeforeEnterChain, } from "./middleware.ts";
+export type { MiddlewareContext, MiddlewareDef, MiddlewareFn, MiddlewareRouteCoord, NavigationCommand, RouteMetaResolved, } from "./middleware.ts";
+export { createScrollManager, generateHistoryKey } from "./scrollManager.ts";
+export type { NavigationKind, ScrollManager, ScrollManagerConfig, ScrollPosition, ScrollRestorationMode, } from "./scrollManager.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}