@real-router/core 0.78.0 → 0.79.1

package/dist/esm/internals.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internals.d.mts","names":[],"sources":["../../src/internals.ts"],"mappings":";;;;;;;;;;;;UAyBiB,gBACf,UAAU,sBAAsB;WAEvB,YAAY,UAAU,SAAS,QACtC,cACA,SAAS,GACT,eACA,OAAO,eAAe,qCACnB,MAAM;WAEF,eAAe,UAAU,SAAS,QACzC,mBACA,aAAa,MACV,YAAY;WAER,qBACP,sBACA,gBAAgB,WACb;WAEI,YAAY,UAAU,SAAS,QACtC,cACA,UAAU,YACP,MAAM;WAEF,kBAAkB;WAElB,mBAAmB,UAAU,WACpC,WAAW,GACX,IAAI,OAAO,eAAe,QACvB;;;;;;;;WASI;aACE,OAAO,OAAO;aACd,YACP,UAAU,OAAO,8BACd;aACI;;;;;aAKA;;WAGF,YAAY,eAAe,SAAS;WAEpC,sBAAsB,OAAO;;;;;;;WAQ7B,wBACP,SAAS,OACT,WAAW,mBACX,OAAO;;;;;;;;WAUA,qBAAqB,iBAAiB;WAEtC,QAAQ,iBAAiB,QAAQ;;;;;;;WAQjC,kBACP,OAAO,OACP,UAAU,sBACP,QAAQ;WAGJ,cAAc,cAEnB,UAAU,wBAAwB;WAI7B,cAAc;WACd;WAEA,eAAe;WAEf;EAET,WAAW;WAQF,QAAQ;WAGR,4BAA4B,kBAAkB;WAM9C;IACP,SAAS;IACT,cAAc;IACd,iBAAiB,cAAc;IAK/B,cAAc;;WAIP,qBAAqB,YAAY;WAGjC;WACA;WACA;WACA,WAAW,OAAO;WAClB;IAAoB;;WACpB,qBAAqB;;;;;;;;;;EAW9B,gBAAgB;;iBAMF,aAAa,UAAU,qBACrC,QAAQ,OAAgB,KACvB,gBAAgB"}

package/dist/esm/namespaces/DependenciesNamespace/dependenciesStore.d.mts

@@ -0,0 +1,10 @@
+import { DefaultDependencies } from "../../types/router.mjs";
+import { Limits } from "../../types/internal.mjs";
+//#region src/namespaces/DependenciesNamespace/dependenciesStore.d.ts
+interface DependenciesStore<Dependencies extends DefaultDependencies = DefaultDependencies> {
+  dependencies: Partial<Dependencies>;
+  limits: Limits;
+}
+//#endregion
+export { DependenciesStore };
+//# sourceMappingURL=dependenciesStore.d.mts.map

package/dist/esm/namespaces/DependenciesNamespace/dependenciesStore.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependenciesStore.d.mts","names":[],"sources":["../../../../src/namespaces/DependenciesNamespace/dependenciesStore.ts"],"mappings":";;;UAKiB,kBACf,qBAAqB,sBAAsB;EAE3C,cAAc,QAAQ;EACtB,QAAQ"}

package/dist/esm/namespaces/RouteLifecycleNamespace/RouteLifecycleNamespace.d.mts

@@ -0,0 +1,174 @@
+import { State } from "../../types/base.mjs";
+import { DefaultDependencies, GuardFn, GuardFnFactory } from "../../types/router.mjs";
+import { RouteLifecycleDependencies } from "./types.mjs";
+//#region src/namespaces/RouteLifecycleNamespace/RouteLifecycleNamespace.d.ts
+/**
+ * Origin lane for a guard clear. Every `clearCanActivate` / `clearCanDeactivate`
+ * caller names its lane — there is no origin-blind default — so a new call site
+ * cannot silently wipe both the route-config and the external guard (#1171):
+ *
+ * - `"definition"` — clear only the route-config guard (`update(name, {…: null})`, #952).
+ * - `"external"` — clear only the external, component-managed guard
+ *   (`removeXGuard()` and post-leave auto-cleanup — the inverse of `addXGuard()`).
+ * - `"both"` — clear both (route removal / router teardown; the route is gone).
+ */
+type GuardClearScope = "definition" | "external" | "both";
+/**
+ * Source of truth for `canActivate` / `canDeactivate` guards.
+ *
+ * Storage is split by origin into four factory Maps (definition vs external,
+ * each ×activate/deactivate); a single compiled-function Map per kind backs
+ * navigation ("external wins" — when a route holds both a definition and an
+ * external guard, the compiled guard is the external one, regardless of
+ * registration order; #1174). `getFunctions()` returns a cached
+ * `[deactivate, activate]` tuple for the hot path (stable reference, no
+ * per-navigate allocation).
+ *
+ * All input validation is handled upstream by `getLifecycleApi` and
+ * `getRoutesApi` — this class has no static methods.
+ *
+ * **Ordering convention.** Every paired surface lists **deactivate before
+ * activate**: `getFunctions()` / `getFactories()` return `[deactivate,
+ * activate]`, `getFactoriesByOrigin()` returns that tuple per origin, and
+ * `canNavigateTo(toDeactivate, toActivate, …)` takes deactivate first. Keep
+ * any new paired surface consistent with this order.
+ */
+declare class RouteLifecycleNamespace<Dependencies extends DefaultDependencies = DefaultDependencies> {
+  #private;
+  setDependencies(deps: RouteLifecycleDependencies<Dependencies>): void;
+  getHandlerCount(type: "activate" | "deactivate"): number;
+  /**
+   * Pre-flights the #961 handler-limit `RangeError` into the route-CRUD PREPARE
+   * phase (#1046). `#registerHandler`'s per-slot limit check throws AFTER the
+   * tree/config swap, so `add`/`replace`/`update` tore post-commit when the
+   * validator was installed and the per-type count was at `maxLifecycleHandlers`.
+   * Running the same check here — before any store mutation — restores atomicity
+   * (#951/#956/#698): a batch that would exceed the limit aborts before a single
+   * write.
+   *
+   * Only NEW slots count (an overwrite leaves the union count unchanged, mirroring
+   * `#registerHandler`). For `replace` (`clearsDefinition = true`) the definition
+   * guards are about to be cleared, so the projection runs against the surviving
+   * EXTERNAL guards only — exactly the post-clear state the install loop sees.
+   * Plugin-gated: a no-op without the validator (the limit is opt-in).
+   *
+   * @param activateNames - route names a `canActivate` would be registered for
+   * @param deactivateNames - route names a `canDeactivate` would be registered for
+   * @param clearsDefinition - true for `replace` (definition guards cleared first)
+   */
+  preflightHandlerLimit(activateNames: Iterable<string>, deactivateNames: Iterable<string>, clearsDefinition: boolean): void;
+  /**
+   * Adds a canActivate guard for a route.
+   *
+   * @param name - Route name (input-validated by facade)
+   * @param handler - Guard function or boolean (input-validated by facade)
+   * @param isFromDefinition - True when guard comes from route definition
+   *   (lands in the definition Map; subject to `clearDefinitionGuards()`).
+   *   False (default) when added via `getLifecycleApi().addActivateGuard(...)`
+   *   (lands in the external Map; survives `replace()`).
+   *
+   * External wins at runtime (#1174): when a route holds both a definition and
+   * an external guard, the compiled function is the external one, regardless of
+   * registration order. Within one origin the most recent add overwrites. Origin
+   * determines which Map the factory is filed under (relevant for
+   * `clearDefinitionGuards()` and `cloneRouter` re-registration).
+   */
+  addCanActivate(name: string, handler: GuardFnFactory<Dependencies> | boolean, isFromDefinition?: boolean, precompiledFn?: GuardFn): void;
+  /**
+   * Adds a canDeactivate guard for a route.
+   *
+   * Symmetric counterpart to {@link addCanActivate}.
+   */
+  addCanDeactivate(name: string, handler: GuardFnFactory<Dependencies> | boolean, isFromDefinition?: boolean, precompiledFn?: GuardFn): void;
+  /**
+   * Removes a canActivate guard for a route. `scope` names the origin lane
+   * (see {@link GuardClearScope}) — there is no origin-blind default, so every
+   * caller commits to a lane and a new call site cannot silently clear both.
+   * Delegates to {@link #clearGuard} (mirrors the add side's `#registerHandler`).
+   *
+   * @param name - Route name (already validated by facade)
+   * @param scope - Which origin(s) to clear: `"definition"` / `"external"` / `"both"`
+   */
+  clearCanActivate(name: string, scope: GuardClearScope): void;
+  /**
+   * Removes a canDeactivate guard for a route. Symmetric counterpart to
+   * {@link clearCanActivate}.
+   *
+   * The `"external"` lane is what makes a route-config `canDeactivate` durable:
+   * post-leave auto-cleanup (`completeTransition`) and `removeDeactivateGuard()`
+   * unregister only the external, component-managed guard (router5 mount/unmount
+   * heritage), while a definition guard survives for re-entry — symmetric with
+   * definition `canActivate`, which lives as long as the route is in the tree
+   * (#1171). Clearing both by default made a config guard one-shot: the first
+   * permitted leave erased it, so re-entry was unguarded, `getRoutesApi().get()`
+   * lost the field, and a clone taken after the leave never received it
+   * (clone invariant #6).
+   *
+   * @param name - Route name (already validated by facade)
+   * @param scope - Which origin(s) to clear: `"definition"` / `"external"` / `"both"`
+   */
+  clearCanDeactivate(name: string, scope: GuardClearScope): void;
+  /**
+   * Clears all lifecycle handlers (canActivate and canDeactivate).
+   * Used by clearRoutes to reset all lifecycle state.
+   */
+  clearAll(): void;
+  /**
+   * Clears only lifecycle handlers that were registered from route definitions.
+   * Used by HMR `replace()` to remove definition-sourced guards without
+   * touching externally-added guards.
+   *
+   * For a slot where BOTH a definition and an external guard exist, the external
+   * factory survives — and the compiled function is RECOMPILED from it (#1192).
+   * Under external-wins (#1174) the compiled slot is already the external guard,
+   * so this recompile is idempotent — it re-derives the surviving external factory
+   * through the same choke point that keeps clearing correct (and stays robust if
+   * the compiled slot were ever out of sync). For a definition-only slot, the
+   * compiled function is dropped.
+   */
+  clearDefinitionGuards(): void;
+  /**
+   * Returns lifecycle factories as a flat `[deactivate, activate]` tuple of
+   * `Record<name, factory>` — the effective view where external wins over
+   * definition for the same slot. Used by `getRoutesApi` to enrich route
+   * objects with their current canActivate / canDeactivate factories and by
+   * the route-removal cleanup path.
+   *
+   * For cloneRouter (which needs to preserve origin on re-registration), use
+   * {@link getFactoriesByOrigin} instead.
+   */
+  getFactories(): [Record<string, GuardFnFactory<Dependencies>>, Record<string, GuardFnFactory<Dependencies>>];
+  /**
+   * Returns factories tagged by origin — definition and external as separate
+   * `[deactivate, activate]` tuples. Used by `cloneRouter` to re-register
+   * guards on the clone with their original origin flag preserved.
+   */
+  getFactoriesByOrigin(): {
+    definition: [Record<string, GuardFnFactory<Dependencies>>, Record<string, GuardFnFactory<Dependencies>>];
+    external: [Record<string, GuardFnFactory<Dependencies>>, Record<string, GuardFnFactory<Dependencies>>];
+  };
+  /**
+   * Returns compiled lifecycle functions for transition execution.
+   *
+   * @returns Tuple of [canDeactivateFunctions, canActivateFunctions] as Maps
+   */
+  getFunctions(): [Map<string, GuardFn>, Map<string, GuardFn>];
+  canNavigateTo(toDeactivate: string[], toActivate: string[], toState: State, fromState: State | undefined): boolean;
+  /**
+   * Compiles a guard factory to its `GuardFn` WITHOUT registering it — surfaces
+   * a throwing / non-function factory eagerly. The prepare-then-commit
+   * add/replace path (`adoptRouteArtifacts`) calls this for every pending guard
+   * BEFORE the store swap (#956), so a malformed factory aborts the mutation
+   * with the store untouched. The returned function is then installed via the
+   * `precompiledFn` argument of {@link addCanActivate} / {@link addCanDeactivate}
+   * — no re-compile, so a factory with compile-time side effects runs exactly
+   * once. Same boolean-shorthand handling + compile + non-function check as the
+   * inline `#registerHandler` path, so a route-config `canActivate: true`
+   * (boolean shorthand, runtime-reachable via the public route type) compiles to
+   * the cached `TRUE_GUARD`/`FALSE_GUARD` instead of throwing on a non-callable.
+   */
+  compileGuardFactory(handler: GuardFnFactory<Dependencies> | boolean, methodName: string): GuardFn;
+}
+//#endregion
+export { GuardClearScope, RouteLifecycleNamespace };
+//# sourceMappingURL=RouteLifecycleNamespace.d.mts.map

package/dist/esm/namespaces/RouteLifecycleNamespace/RouteLifecycleNamespace.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouteLifecycleNamespace.d.mts","names":[],"sources":["../../../../src/namespaces/RouteLifecycleNamespace/RouteLifecycleNamespace.ts"],"mappings":";;;;;;;;;;;;;;KAuCY;;;;;;;;;;;;;;;;;;;;;cAsBC,wBACX,qBAAqB,sBAAsB;;EAuC3C,gBAAgB,MAAM,2BAA2B;EAIjD,gBAAgB;;;;;;;;;;;;;;;;;;;;EA8ChB,sBACE,eAAe,kBACf,iBAAiB,kBACjB;;;;;;;;;;;;;;;;;EAuEF,eACE,cACA,SAAS,eAAe,yBACxB,4BACA,gBAAgB;;;;;;EAiBlB,iBACE,cACA,SAAS,eAAe,yBACxB,4BACA,gBAAgB;;;;;;;;;;EAqBlB,iBAAiB,cAAc,OAAO;;;;;;;;;;;;;;;;;;EAqBtC,mBAAmB,cAAc,OAAO;;;;;EAQxC;;;;;;;;;;;;;;EAsBA;;;;;;;;;;;EA+BA,iBACE,eAAe,eAAe,gBAC9B,eAAe,eAAe;;;;;;EA2BhC;IACE,aACE,eAAe,eAAe,gBAC9B,eAAe,eAAe;IAEhC,WACE,eAAe,eAAe,gBAC9B,eAAe,eAAe;;;;;;;EAgClC,iBAAiB,YAAY,UAAU,YAAY;EAInD,cACE,wBACA,sBACA,SAAS,OACT,WAAW;;;;;;;;;;;;;;EA8Cb,oBACE,SAAS,eAAe,yBACxB,qBACC"}

package/dist/esm/namespaces/RouteLifecycleNamespace/types.d.mts

@@ -0,0 +1,17 @@
+import { DefaultDependencies, GuardFn, GuardFnFactory, RouterLogger } from "../../types/router.mjs";
+import { RouterValidator } from "../../types/RouterValidator.mjs";
+//#region src/namespaces/RouteLifecycleNamespace/types.d.ts
+interface RouteLifecycleDependencies<Dependencies extends DefaultDependencies = DefaultDependencies> {
+  /** Per-router logger instance (from `getInternals(router).logger`) */
+  logger: RouterLogger;
+  compileFactory: (factory: GuardFnFactory<Dependencies>) => GuardFn;
+  /**
+   * Returns the opt-in DX validator, or `null` when no validation-plugin is
+   * installed. A plain deps field (#1331) — internals are registered before
+   * wiring, so `getInternals(router)` never throws and no try/catch is needed.
+   */
+  getValidator: () => RouterValidator | null;
+}
+//#endregion
+export { RouteLifecycleDependencies };
+//# sourceMappingURL=types.d.mts.map

package/dist/esm/namespaces/RouteLifecycleNamespace/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../src/namespaces/RouteLifecycleNamespace/types.ts"],"mappings":";;;UAUiB,2BACf,qBAAqB,sBAAsB;;EAG3C,QAAQ;EAER,iBAAiB,SAAS,eAAe,kBAAkB;;;;;;EAM3D,oBAAoB"}

package/dist/esm/namespaces/RoutesNamespace/forwardChain.d.mts

@@ -0,0 +1,5 @@
+//#region src/namespaces/RoutesNamespace/forwardChain.d.ts
+declare function resolveForwardChain(startRoute: string, forwardMap: Record<string, string>, maxDepth?: number): string;
+//#endregion
+export { resolveForwardChain };
+//# sourceMappingURL=forwardChain.d.mts.map

package/dist/esm/namespaces/RoutesNamespace/forwardChain.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forwardChain.d.mts","names":[],"sources":["../../../../src/namespaces/RoutesNamespace/forwardChain.ts"],"mappings":";iBAEgB,oBACd,oBACA,YAAY,wBACZ"}

package/dist/esm/namespaces/RoutesNamespace/routesStore.d.mts

@@ -0,0 +1,42 @@
+import { RouteDefinition, RouteTree } from "../../engine/builder/types.mjs";
+import { CreateMatcherOptions, Matcher } from "../../engine/createMatcher.mjs";
+import { DefaultDependencies, GuardFnFactory } from "../../types/router.mjs";
+import { RouteLifecycleNamespace } from "../RouteLifecycleNamespace/RouteLifecycleNamespace.mjs";
+import { RouteConfig, RoutesDependencies } from "./types.mjs";
+//#region src/namespaces/RoutesNamespace/routesStore.d.ts
+interface RoutesStore<Dependencies extends DefaultDependencies = DefaultDependencies> {
+  /**
+   * DERIVED VIEW, not stored state: reconstructed from `tree` on every access
+   * via `routeTreeToDefinitions` (the lossless inverse cloneRouter already
+   * relies on — the `~` absolute marker is restored, child order is the
+   * definition order). The tree is the single source of truth, so a third
+   * retained copy of the route table (~30 B/route) is not kept. Every reader
+   * is a cold CRUD/plugin-registration path; the derive is O(N).
+   *
+   * The returned array is a FRESH snapshot each time — mutating it never
+   * affects the store (pass an explicitly-mutated snapshot to
+   * `commitTreeChanges` instead, as `remove` does).
+   */
+  readonly definitions: RouteDefinition[];
+  readonly config: RouteConfig;
+  tree: RouteTree;
+  matcher: Matcher;
+  /**
+   * Per-route-name cache of URL (path) param names, derived from `matcher` and
+   * read by `RoutesNamespace.getUrlParams` (powers `areStatesEqual` /
+   * `isActiveRoute`). Cleared on every `matcher` rebuild so comparisons never
+   * stay frozen to a route's pre-mutation param shape (#723).
+   */
+  readonly urlParamsCache: Map<string, string[]>;
+  resolvedForwardMap: Record<string, string>;
+  routeCustomFields: Record<string, Record<string, unknown>>;
+  rootPath: string;
+  readonly matcherOptions: CreateMatcherOptions | undefined;
+  depsStore: RoutesDependencies<Dependencies> | undefined;
+  lifecycleNamespace: RouteLifecycleNamespace<Dependencies> | undefined;
+  readonly pendingCanActivate: Map<string, GuardFnFactory<Dependencies>>;
+  readonly pendingCanDeactivate: Map<string, GuardFnFactory<Dependencies>>;
+}
+//#endregion
+export { RoutesStore };
+//# sourceMappingURL=routesStore.d.mts.map

package/dist/esm/namespaces/RoutesNamespace/routesStore.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routesStore.d.mts","names":[],"sources":["../../../../src/namespaces/RoutesNamespace/routesStore.ts"],"mappings":";;;;;;UAsCiB,YACf,qBAAqB,sBAAsB;;;;;;;;;;;;;WAclC,aAAa;WACb,QAAQ;EACjB,MAAM;EACN,SAAS;;;;;;;WAOA,gBAAgB;EACzB,oBAAoB;EACpB,mBAAmB,eAAe;EAClC;WACS,gBAAgB;EACzB,WAAW,mBAAmB;EAC9B,oBAAoB,wBAAwB;WACnC,oBAAoB,YAAY,eAAe;WAC/C,sBAAsB,YAAY,eAAe"}

package/dist/esm/namespaces/RoutesNamespace/types.d.mts

@@ -0,0 +1,57 @@
+import { Params, SimpleState, State } from "../../types/base.mjs";
+import { DefaultDependencies, ForwardToCallback, GuardFn, GuardFnFactory, RouterLogger } from "../../types/router.mjs";
+//#region src/namespaces/RoutesNamespace/types.d.ts
+/**
+ * Dependencies injected into RoutesNamespace.
+ *
+ * These are function references from the Router facade,
+ * avoiding the need to pass the entire Router object.
+ */
+interface RoutesDependencies<Dependencies extends DefaultDependencies = DefaultDependencies> {
+  /** Per-router logger instance (from `getInternals(router).logger`) */
+  logger: RouterLogger;
+  /**
+   * Register a canActivate handler for a route. `precompiledFn` installs an
+   * already-compiled `GuardFn` (from {@link compileGuard}) without re-invoking
+   * the factory — used by the #956 prepare-then-commit path so guards compile
+   * once, before the store swap.
+   */
+  addActivateGuard: (name: string, handler: GuardFnFactory<Dependencies>, precompiledFn?: GuardFn) => void;
+  /** Register a canDeactivate handler for a route (see {@link addActivateGuard}). */
+  addDeactivateGuard: (name: string, handler: GuardFnFactory<Dependencies>, precompiledFn?: GuardFn) => void;
+  /**
+   * Compile a guard factory to its `GuardFn` WITHOUT registering it — surfaces a
+   * throwing / non-function factory eagerly so the add/replace commit can
+   * validate every guard before swapping the store (#956).
+   */
+  compileGuard: (handler: GuardFnFactory<Dependencies>, methodName: string) => GuardFn;
+  /** Create state object */
+  makeState: <P extends Params = Params>(name: string, params?: P, path?: string, meta?: Record<string, Record<string, "url" | "query">>) => State<P>;
+  /** Get current router state */
+  getState: () => State | undefined;
+  /** Compare two states for equality */
+  areStatesEqual: (state1: State | undefined, state2: State | undefined, ignoreQueryParams?: boolean) => boolean;
+  /** Get a dependency by name */
+  getDependency: <K extends keyof Dependencies>(name: K) => Dependencies[K];
+  /** Forward state through facade (allows plugin interception) */
+  forwardState: <P extends Params = Params>(name: string, params: P) => SimpleState<P>;
+}
+/**
+ * Configuration storage for routes.
+ * Stores decoders, encoders, default params, and forward mappings.
+ */
+interface RouteConfig {
+  /** Custom param decoders per route */
+  decoders: Record<string, (params: Params) => Params>;
+  /** Custom param encoders per route */
+  encoders: Record<string, (params: Params) => Params>;
+  /** Default params per route */
+  defaultParams: Record<string, Params>;
+  /** Forward mappings (source -> target) */
+  forwardMap: Record<string, string>;
+  /** Dynamic forward callbacks (source -> callback) */
+  forwardFnMap: Record<string, ForwardToCallback<any>>;
+}
+//#endregion
+export { RouteConfig, RoutesDependencies };
+//# sourceMappingURL=types.d.mts.map

package/dist/esm/namespaces/RoutesNamespace/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../src/namespaces/RoutesNamespace/types.ts"],"mappings":";;;;;;;;;UAmBiB,mBACf,qBAAqB,sBAAsB;;EAG3C,QAAQ;;;;;;;EAQR,mBACE,cACA,SAAS,eAAe,eACxB,gBAAgB;;EAIlB,qBACE,cACA,SAAS,eAAe,eACxB,gBAAgB;;;;;;EAQlB,eACE,SAAS,eAAe,eACxB,uBACG;;EAGL,YAAY,UAAU,SAAS,QAC7B,cACA,SAAS,GACT,eACA,OAAO,eAAe,qCACnB,MAAM;;EAGX,gBAAgB;;EAGhB,iBACE,QAAQ,mBACR,QAAQ,mBACR;;EAIF,gBAAgB,gBAAgB,cAAc,MAAM,MAAM,aAAa;;EAGvE,eAAe,UAAU,SAAS,QAChC,cACA,QAAQ,MACL,YAAY;;;;;;UAOF;;EAEf,UAAU,gBAAgB,QAAQ,WAAW;;EAG7C,UAAU,gBAAgB,QAAQ,WAAW;;EAG7C,eAAe,eAAe;;EAG9B,YAAY;;EAIZ,cAAc,eAAe"}

package/dist/esm/{RouterValidator-CZ8kPkrI.d.mts → types/RouterValidator.d.mts}

@@ -103,5 +103,5 @@ interface RouterValidator {
   };
 }
 //#endregion
-export { RouterValidator as t };
-//# sourceMappingURL=RouterValidator-CZ8kPkrI.d.mts.map
+export { RouterValidator };
+//# sourceMappingURL=RouterValidator.d.mts.map

package/dist/esm/types/RouterValidator.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouterValidator.d.mts","names":[],"sources":["../../../src/types/RouterValidator.ts"],"mappings":";;;;;;;;;;UAUiB;;;;EAIf;IACE,wBAAwB;IACxB,wBAAwB;IACxB,4BACE,eACA,iBACA,iBACA;IAEF,+BAA+B;IAC/B,2BACE,eACA,iBACA;IAEF,uBAAuB;IACvB,iBACE,mBACA,eACA;IAEF,0BAA0B;IAC1B,+BAA+B,eAAe;IAC9C,mCAAmC,cAAc;IACjD,sBACE,cACA,kBACA;IAEF,uBAAuB,iBAAiB;IACxC,oBAAoB,eAAe;IACnC,uBAAuB,eAAe;IACtC,8BAA8B,mBAAmB;IACjD,0BAA0B;IAC1B,sBAAsB;IACtB,wBAAwB;;;;;EAM1B;IACE,kBAAkB,kBAAkB;IACpC,+BAA+B,oBAAoB;;;;;EAMrD;IACE,yBAAyB,eAAe;IACxC,4BACE,eACA,gBACA;IAEF,6BAA6B,eAAe;IAC5C,2BAA2B,cAAc;IACzC,0BAA0B,gBAAgB;IAC1C,oBAAoB;IACpB,gBAAgB,cAAc;IAC9B,qBAAqB,gBAAgB;IACrC,wBAAwB;;;;;EAM1B;IACE,sBAAsB,eAAe;IACrC,6BACE,kBACA;IAEF,qBAAqB;IACrB,0BAA0B;IAC1B,sBAAsB;IACtB,uBAAuB;IACvB,uBAAuB;IACvB,6BAA6B,iBAAiB;;;;;EAMhD;IACE,kBAAkB,kBAAkB;IACpC,uBAAuB,eAAe;IACtC,0BAA0B,eAAe;IACzC,gBAAgB,cAAc,cAAc;IAC5C,qBAAqB,cAAc;;;;;EAMrC;IACE,uBAAuB;IACvB,gCAAgC;IAChC,8BAA8B;IAC9B,4BAA4B,kBAAkB;IAC9C,iBAAiB,iBAAiB;IAClC,oBAAoB;;;;;EAMtB;IACE,wBACE,eACA,iBACA;IAEF,6BACE,aACA,aACA;;;;;EAOJ;IACE,uBAAuB,eAAe;IACtC,0BACE,eACA,mBACA"}

package/dist/esm/types/api.d.mts

@@ -0,0 +1,184 @@
+import { RouteTreeState } from "./route-node-types.mjs";
+import { Params, SimpleState, State, StateMetaInput, Unsubscribe } from "./base.mjs";
+import { DefaultDependencies, GuardFnFactory, Options, Plugin, Route, RouteConfigUpdate } from "./router.mjs";
+import { EventMethodMap, EventName } from "./constants.mjs";
+import { TreeChangedEvent } from "./tree-changed.mjs";
+import { NavigationOptions, StateContext } from "../types.mjs";
+//#region src/types/api.d.ts
+/**
+ * Maps interceptable method names to their signatures.
+ * Used by {@link PluginApi.addInterceptor} to provide type-safe interceptor registration.
+ *
+ * To add a new interceptable method:
+ * 1. Add its signature here
+ * 2. Wrap it with `createInterceptable()` / `createBinaryInterceptable()` in
+ *    the `registerInternals` block of the Router constructor
+ *    (`packages/core/src/Router.ts`)
+ */
+interface InterceptableMethodMap {
+  start: (path?: string) => Promise<State>;
+  buildPath: (route: string, params?: Params) => string;
+  forwardState: (routeName: string, routeParams: Params) => SimpleState;
+}
+/**
+ * Type-safe interceptor callback.
+ * Receives `next` (the next function in the chain) followed by the method's original parameters.
+ */
+type InterceptorFn<M extends keyof InterceptableMethodMap> = (next: InterceptableMethodMap[M], ...args: Parameters<InterceptableMethodMap[M]>) => ReturnType<InterceptableMethodMap[M]>;
+/**
+ * Writer object returned by {@link PluginApi.claimContextNamespace}. Holds
+ * exclusive ownership of a single `state.context.<namespace>` key for the
+ * lifetime of the owning plugin.
+ *
+ * @description
+ * A plugin obtains a claim by calling `api.claimContextNamespace("ns")` at
+ * registration, then publishes per-navigation data via {@link write} from a
+ * lifecycle hook (typically `onTransitionSuccess`) or from an interceptor.
+ * The plugin must call {@link release} in its `teardown()` so another plugin
+ * can reclaim the same namespace.
+ *
+ * The core runtime enforces one invariant: a namespace can be held by at most
+ * one claim at a time. Double-claiming throws `CONTEXT_NAMESPACE_ALREADY_CLAIMED`.
+ *
+ * @example
+ * ```typescript
+ * const navigationPlugin: PluginFactory = (router) => {
+ *   const api = getPluginApi(router);
+ *   const claim = api.claimContextNamespace("navigation");
+ *
+ *   return {
+ *     onTransitionSuccess(toState, fromState) {
+ *       claim.write(toState, { direction: detectDirection(fromState, toState) });
+ *     },
+ *     teardown() {
+ *       claim.release();
+ *     },
+ *   };
+ * };
+ * ```
+ *
+ * @see {@link PluginApi.claimContextNamespace}
+ * @see {@link State.context}
+ */
+interface ContextNamespaceClaim<T = unknown> {
+  write: (state: State, value: T) => void;
+  release: () => void;
+}
+/**
+ * Plugin API — for plugins and infrastructure packages.
+ * Hides plugin-internal methods from public autocomplete.
+ */
+interface PluginApi {
+  makeState: <P extends Params = Params>(name: string, params?: P, path?: string, meta?: StateMetaInput) => State<P>;
+  buildState: (routeName: string, routeParams: Params) => RouteTreeState | undefined;
+  forwardState: <P extends Params = Params>(routeName: string, routeParams: P) => SimpleState<P>;
+  matchPath: <P extends Params = Params>(path: string) => State<P> | undefined;
+  /**
+   * Navigate to a fully-built `State`, skipping the redundant
+   * `forwardState`/`buildPath` round-trip in `buildNavigateState`.
+   *
+   * Plugin-only entry point for browser-initiated navigation: a plugin
+   * receives a URL event, resolves it via `api.matchPath(url)`, then commits
+   * the resulting `State` directly via `api.navigateToState(state, opts)`.
+   *
+   * Semantics vs `router.navigate(name, params, opts)`:
+   * - `forwardState` is NOT re-applied (matchPath already ran it).
+   * - `buildPath` is NOT re-run; `state.path` is used verbatim, preserving
+   *   `trailingSlash:"preserve"` source-URL output.
+   * - `forwardState`/`buildPath` interceptors do NOT run on this path; the
+   *   URL the user navigated to is the source of truth.
+   * - Pipeline: SAME_STATES check, FSM transition, guards, `subscribeLeave`,
+   *   `completeTransition`, plugin lifecycle hooks — all unchanged.
+   *
+   * Programmatic / userland navigation should keep using
+   * `router.navigate(name, params, opts)` so interceptors apply.
+   */
+  navigateToState: (state: State, options?: NavigationOptions) => Promise<State>;
+  setRootPath: (rootPath: string) => void;
+  getRootPath: () => string;
+  addEventListener: <E extends EventName>(eventName: E, cb: Plugin[EventMethodMap[E]]) => Unsubscribe;
+  buildNavigationState: (name: string, params?: Params) => State | undefined;
+  getOptions: () => Options;
+  getTree: () => unknown;
+  addInterceptor: <M extends keyof InterceptableMethodMap>(method: M, fn: InterceptorFn<M>) => Unsubscribe;
+  extendRouter: (extensions: Record<string, unknown>) => Unsubscribe;
+  /**
+   * Emits a `$$error` event without going through the navigation pipeline.
+   *
+   * Used by plugins that detect an error outside a running transition (e.g.,
+   * an unmatched URL on popstate in strict mode). The event reaches any
+   * `onTransitionError` plugin hook and any `$$error` listener so developers
+   * can observe errors raised by the plugin layer.
+   *
+   * The current router state is used as `fromState`; `toState` is `undefined`
+   * because no transition was attempted. Safe to call at any FSM state —
+   * delegates to `sendFailSafe` internally (direct emit when not READY).
+   */
+  emitTransitionError: (error: Error) => void;
+  claimContextNamespace: {
+    <K extends keyof StateContext & string>(namespace: K): ContextNamespaceClaim<StateContext[K]>;
+    (namespace: string): ContextNamespaceClaim;
+  };
+  getRouteConfig: (name: string) => Record<string, unknown> | undefined;
+}
+/**
+ * Routes API — for dynamic route mutation.
+ */
+interface RoutesApi<Dependencies extends DefaultDependencies = DefaultDependencies> {
+  add: (routes: Route<Dependencies>[] | Route<Dependencies>, options?: {
+    parent?: string;
+  }) => void;
+  remove: (name: string) => void;
+  /**
+   * Patch an existing route's configuration in place (no tree rebuild).
+   *
+   * Applies the structural/guard fields and any plugin-defined custom fields
+   * (lifecycle hooks, `preload`, `searchSchema`, …) from the patch. Fields are
+   * shallow-merged by key; `null` removes a field, `undefined` is a no-op.
+   * `name`/`path`/`children` are immutable — use `remove` + `add` to
+   * restructure. See {@link RouteConfigUpdate} for the full semantics and the
+   * plugin augmentation pattern.
+   */
+  update: (name: string, updates: RouteConfigUpdate<Dependencies>) => void;
+  clear: () => void;
+  replace: (routes: Route<Dependencies>[] | Route<Dependencies>) => void;
+  has: (name: string) => boolean;
+  get: (name: string) => Route<Dependencies> | undefined;
+  /**
+   * Subscribe to structural route-tree mutations (`add` / `remove` / `update`
+   * with structural fields / `replace` / `clear`). Fire-and-forget: the handler
+   * cannot cancel the mutation, runs after the atomic commit, and sees the
+   * post-mutation tree via `get()` / `has()`.
+   *
+   * Duplicate-registration semantics are **lenient** (mirrors
+   * `router.subscribe`): each call registers an independent listener and
+   * returns its own unsubscribe.
+   *
+   * @returns Unsubscribe function for this specific registration.
+   */
+  subscribeChanges: (handler: (event: TreeChangedEvent<Dependencies>) => void) => Unsubscribe;
+}
+/**
+ * Dependencies API — CRUD for dependency injection.
+ */
+interface DependenciesApi<Dependencies extends DefaultDependencies = DefaultDependencies> {
+  get: <K extends keyof Dependencies>(key: K) => Dependencies[K];
+  getAll: () => Partial<Dependencies>;
+  set: <K extends keyof Dependencies & string>(name: K, value: Dependencies[K]) => void;
+  setAll: (deps: Dependencies) => void;
+  remove: (name: keyof Dependencies) => void;
+  reset: () => void;
+  has: (name: keyof Dependencies) => boolean;
+}
+/**
+ * Lifecycle API — guard registration (addActivateGuard, addDeactivateGuard, etc.)
+ */
+interface LifecycleApi<Dependencies extends DefaultDependencies = DefaultDependencies> {
+  addActivateGuard: (name: string, canActivateHandler: GuardFnFactory<Dependencies> | boolean) => void;
+  addDeactivateGuard: (name: string, canDeactivateHandler: GuardFnFactory<Dependencies> | boolean) => void;
+  removeActivateGuard: (name: string) => void;
+  removeDeactivateGuard: (name: string) => void;
+}
+//#endregion
+export { ContextNamespaceClaim, DependenciesApi, InterceptableMethodMap, InterceptorFn, LifecycleApi, PluginApi, RoutesApi };
+//# sourceMappingURL=api.d.mts.map

package/dist/esm/types/api.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.mts","names":[],"sources":["../../../src/types/api.ts"],"mappings":";;;;;;;;;;;;;;;;;UAqCiB;EACf,QAAQ,kBAAkB,QAAQ;EAClC,YAAY,eAAe,SAAS;EACpC,eAAe,mBAAmB,aAAa,WAAW;;;;;;KAOhD,cAAc,gBAAgB,2BACxC,MAAM,uBAAuB,OAC1B,MAAM,WAAW,uBAAuB,QACxC,WAAW,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAqCtB,sBAAsB;EACrC,QAAQ,OAAO,OAAO,OAAO;EAC7B;;;;;;UAOe;EACf,YAAY,UAAU,SAAS,QAC7B,cACA,SAAS,GACT,eACA,OAAO,mBACJ,MAAM;EAEX,aACE,mBACA,aAAa,WACV;EAEL,eAAe,UAAU,SAAS,QAChC,mBACA,aAAa,MACV,YAAY;EAEjB,YAAY,UAAU,SAAS,QAAQ,iBAAiB,MAAM;;;;;;;;;;;;;;;;;;;;;EAsB9D,kBACE,OAAO,OACP,UAAU,sBACP,QAAQ;EAEb,cAAc;EACd;EAEA,mBAAmB,UAAU,WAC3B,WAAW,GACX,IAAI,OAAO,eAAe,QACvB;EAEL,uBAAuB,cAAc,SAAS,WAAW;EAEzD,kBAAkB;EAElB;EAEA,iBAAiB,gBAAgB,wBAC/B,QAAQ,GACR,IAAI,cAAc,OACf;EAEL,eAAe,YAAY,4BAA4B;;;;;;;;;;;;;EAcvD,sBAAsB,OAAO;EAE7B;KAEG,gBAAgB,uBACf,WAAW,IACV,sBAAsB,aAAa;KACrC,oBAAoB;;EAGvB,iBAAiB,iBAAiB;;;;;UAMnB,UACf,qBAAqB,sBAAsB;EAE3C,MACE,QAAQ,MAAM,kBAAkB,MAAM,eACtC;IAAY;;EAGd,SAAS;;;;;;;;;;;EAYT,SAAS,cAAc,SAAS,kBAAkB;EAElD;EAEA,UAAU,QAAQ,MAAM,kBAAkB,MAAM;EAEhD,MAAM;EAEN,MAAM,iBAAiB,MAAM;;;;;;;;;;;;;EAc7B,mBACE,UAAU,OAAO,iBAAiB,2BAC/B;;;;;UAMU,gBACf,qBAAqB,sBAAsB;EAE3C,MAAM,gBAAgB,cAAc,KAAK,MAAM,aAAa;EAC5D,cAAc,QAAQ;EACtB,MAAM,gBAAgB,uBACpB,MAAM,GACN,OAAO,aAAa;EAEtB,SAAS,MAAM;EACf,SAAS,YAAY;EACrB;EACA,MAAM,YAAY;;;;;UAMH,aACf,qBAAqB,sBAAsB;EAE3C,mBACE,cACA,oBAAoB,eAAe;EAErC,qBACE,cACA,sBAAsB,eAAe;EAEvC,sBAAsB;EACtB,wBAAwB"}

package/dist/esm/types/base.d.mts

@@ -0,0 +1,86 @@
+import { StateContext } from "../types.mjs";
+//#region src/types/base.d.ts
+/**
+ * Detach function returned by subscription APIs.
+ *
+ * @description
+ * Calling this function removes the associated listener. Returned by
+ * `router.subscribe()`, `router.addEventListener()`, `router.subscribeLeave()`,
+ * and plugin interceptors. Idempotent — calling more than once is safe and
+ * has no additional effect after the first call.
+ */
+type Unsubscribe = () => void;
+interface SimpleState<P extends Params = Params> {
+  name: string;
+  params: P;
+}
+type TransitionPhase = "deactivating" | "activating";
+type TransitionReason = "success" | "blocked" | "cancelled" | "error";
+interface TransitionMeta {
+  phase: TransitionPhase;
+  reason: TransitionReason;
+  reload?: boolean;
+  replace?: boolean;
+  redirected?: boolean;
+  from?: string;
+  blocker?: string;
+  segments: {
+    deactivated: string[];
+    activated: string[];
+    intersection: string;
+  };
+}
+interface State<P extends Params = Params> {
+  name: string;
+  params: P;
+  path: string;
+  transition: TransitionMeta;
+  /**
+   * Plugin-extensible per-route data, attached by plugins via
+   * `PluginApi.claimContextNamespace()` + `claim.write(state, value)`.
+   *
+   * @description
+   * Required field — always present as at least `{}` on every State created by
+   * the router (via `makeState`, `navigateToNotFound`, or `cloneRouter`).
+   *
+   * Typed extensions come from plugins augmenting {@link StateContext} through
+   * module augmentation. The intersection with `Record<string, unknown>` allows
+   * untyped namespaces (inline plugins, tests, or plugins that skip augmentation)
+   * to write without compile errors.
+   *
+   * The `context` object itself is **not frozen** — this is intentional, so
+   * plugins can attach data without cloning state. Core structural fields
+   * (`name`, `params`, `path`, `transition`) remain immutable via shallow
+   * `Object.freeze(state)`.
+   *
+   * @see {@link StateContext}
+   */
+  context: StateContext & Record<string, unknown>;
+}
+interface StateMetaInput<P extends Params = Params> {
+  params: P;
+}
+/**
+ * RouterError interface describing the public API of the RouterError class.
+ * The actual class implementation is in the real-router package.
+ * This interface enables structural typing compatibility between
+ * core-types and real-router packages.
+ */
+interface RouterError extends Error {
+  [key: string]: unknown;
+  readonly code: string;
+  readonly segment: string | undefined;
+  readonly path: string | undefined;
+  setCode: (code: string) => void;
+  setErrorInstance: (err: Error) => void;
+  setAdditionalFields: (fields: Record<string, unknown>) => void;
+  hasField: (key: string) => boolean;
+  getField: (key: string) => unknown;
+  toJSON: () => Record<string, unknown>;
+}
+interface Params {
+  [key: string]: string | string[] | number | number[] | boolean | boolean[] | Params | Params[] | Record<string, string | number | boolean> | null | undefined;
+}
+//#endregion
+export { Params, RouterError, SimpleState, State, StateMetaInput, TransitionMeta, TransitionPhase, TransitionReason, Unsubscribe };
+//# sourceMappingURL=base.d.mts.map

package/dist/esm/types/base.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.mts","names":[],"sources":["../../../src/types/base.ts"],"mappings":";;;;;;;;;;;KAmBY;UAEK,YAAY,UAAU,SAAS;EAC9C;EACA,QAAQ;;KAGE;KAEA;UAEK;EACf,OAAO;EACP,QAAQ;EACR;EACA;EACA;EACA;EACA;EACA;IACE;IACA;IACA;;;UAIa,MAAM,UAAU,SAAS;EACxC;EACA,QAAQ;EACR;EACA,YAAY;;;;;;;;;;;;;;;;;;;;;EAqBZ,SAAS,eAAe;;UAGT,eAAe,UAAU,SAAS;EACjD,QAAQ;;;;;;;;UASO,oBAAoB;GAClC;WACQ;WACA;WACA;EACT,UAAU;EACV,mBAAmB,KAAK;EACxB,sBAAsB,QAAQ;EAC9B,WAAW;EACX,WAAW;EACX,cAAc;;UAGC;GACd,4EAOG,SACA,WACA"}