@real-router/core 0.80.0 → 0.82.0

package/dist/cjs/pipeline/port.d.ts

@@ -0,0 +1,147 @@
+import { Params, SearchParams } from "../types/base.js";
+//#region src/pipeline/port.d.ts
+/**
+ * The pipeline's read-model over the routes layer — a narrow port, not a new
+ * layer. The module stays pure and mock-testable; the router implements the
+ * port at wiring time (`wiring/wireNamespaces.ts`).
+ *
+ * ⚠ **Both ends are deliberately interceptable, and all four phases closed
+ * without changing that.** The signatures describe the pipeline's contract, not
+ * where the implementation goes:
+ *
+ * - `resolveForward` is wired to the `forwardState` SEAM (`Router.ts:259-324`),
+ *   i.e. the interceptable chain PLUS the centralized channel ASSERTION. It
+ *   used to be a channel-SEPARATION wrapper (stage ②) that repaired a
+ *   mis-channelled bag behind the producer's back; `ba0f6b18b` deleted the
+ *   stage outright, and the seam now REFUSES such a bag instead
+ *   (`assertChannelCorrect`, `src/channels/guard.ts`). Channel-correctness is
+ *   the producer's contract, not something the port quietly restores. Calling
+ *   the namespace primitive directly would switch off both the interceptors and
+ *   that check.
+ * - `buildPath` is wired to `ctx.buildPath`, the interceptable, because the
+ *   navigate path builds `state.path` through it (measured: one `navigate()`
+ *   runs BOTH the `forwardState` and the `buildPath` interceptor). Reaching for
+ *   the engine's `matcher.buildPath` here would silently stop running
+ *   `persistent-params`' `buildPath` interceptor on the navigate path — a
+ *   behaviour change, not a refactor. Phases 2 and 4 closed without un-wiring
+ *   it: ⑤a stays on the interceptable.
+ *
+ * Accessors arrived with their consumers, as designed — `queryNames` with the
+ * channel guard, `admitsUndeclaredQuery` with the mode gate (#1575),
+ * `pathNames` and the two sinks with the diagnostics (#1579 / #1584). One
+ * member the design (RFC §4.5) listed never arrived at all: `encode`. The route
+ * codecs stayed with the entry points that own their direction (`buildPath`
+ * calls `config.encoders`, `matchPath` calls `config.decoders`), so the port
+ * never grew a stage for them — which is the case for adding a member only
+ * together with its caller, since one added early is dead weight nothing
+ * detects (knip has no issue type for unused members of an interface).
+ */
+interface RouteResolver {
+  /**
+   * Stage ① — resolve the `forwardTo` chain (layering the hops' defaults) and
+   * hand back channel-correct bags. Channel-correct by REFUSAL, not by repair:
+   * the seam asserts and throws (see the header). `search` flows THROUGH the
+   * interceptor zone, not past it: `search-schema` validates the query channel
+   * here on the URL→State direction.
+   */
+  resolveForward: (name: string, params: Params, search?: SearchParams) => {
+    name: string;
+    params: Params;
+    search?: SearchParams | undefined;
+  };
+  /**
+   * Stage ③ input — the route's per-channel defaults. Split by field, never
+   * inferred: `defaultParams` owns the path channel, `defaultSearch` the query
+   * channel (RFC-4 M2 / #1548).
+   *
+   * Two accessors rather than one returning `{ params, search }`: `navigate` is
+   * the hot path, and the combined form allocated one throwaway object per
+   * navigation. That allocation is the deterministic reason; the bench arm it
+   * was measured on also carried a per-call `getInternals`, and the harness's
+   * own A/A spread is wider than the delta, so no percentage is attributable to
+   * this accessor alone.
+   */
+  defaultParams: (name: string) => Params | undefined;
+  defaultSearch: (name: string) => SearchParams | undefined;
+  /**
+   * Stage ⑤a executor — builds the URL from already-merged channels. Kept in
+   * raw-channel form (not `Canonical`) so the port never has to know about the
+   * brand and stays mockable on its own; `buildURL` is the primitive that
+   * accepts nothing but a `Canonical`.
+   */
+  buildPath: (name: string, params: Params, search: SearchParams) => string;
+  /**
+   * The route's declared `?query` names — the ONE registry that classifies and
+   * prints (#1556), so a key enters the query channel iff the build shows it.
+   * A name that also occupies a path slot (`/items/:id?id`) is absent here by
+   * construction: it is legitimately path-owned (#843 / #1549).
+   */
+  queryNames: (name: string) => readonly string[];
+  /**
+   * The mode gate (#1575) — `true` exactly for `queryParamsMode: "loose"`, the
+   * one mode whose build prints undeclared query keys. Read as a boolean rather
+   * than leaking the mode itself into the pipeline: the pipeline's question is
+   * "may an undeclared key be canonical here?", not "which mode is this?".
+   */
+  admitsUndeclaredQuery: () => boolean;
+  /**
+   * The mode gate's opt-in diagnostic sink (#1575) — `undefined` unless
+   * `validation-plugin` is installed, so bare core drops silently and the
+   * pipeline pays nothing. Resolved per call, not captured: the plugin
+   * registers after wiring.
+   *
+   * ⚠ Like its sibling below, the absence has to be REAL: the router implements
+   * this as a GETTER returning `undefined` while `validator === null`, not as a
+   * closure that forwards into an optional-chained validator. A closure is
+   * always truthy, so the pipeline's `?.` read as taken and bare core still paid
+   * the `pathNames` existence lookup (#1584) once per dropped key with nothing
+   * to feed. The `| undefined` in the type is what lets the getter say so under
+   * `exactOptionalPropertyTypes`.
+   *
+   * Optional on the interface so a MOCK port (the property tests) stays a
+   * four-liner: the pipeline's contract is the drop, not the report.
+   */
+  reportDroppedQueryKey?: ((routeName: string, key: string) => void) | undefined;
+  /**
+   * The route's PATH slot names, or `undefined` when there is NO SUCH ROUTE —
+   * the other half of "is this key declared?". Needed only by the undeclared-key
+   * diagnostic (#1579), which asks whether a key is declared ANYWHERE;
+   * `queryNames` alone cannot answer that.
+   *
+   * ⚠ The `undefined` arm is load-bearing, not defensive (#1584). An empty array
+   * is what an EXISTING route with no path slots returns, so `[]` cannot say
+   * "no such route" — and the diagnostic, reading `[]` for both, reported every
+   * key in the caller's bag as "declared nowhere on route X" for a route X that
+   * has no declarations only because it has no existence. That blames the params
+   * for a typo in the ROUTE name, which is the most misleading direction
+   * available. The matcher already knows the difference (`getSegmentsByName`
+   * answers `undefined`); this member used to discard it.
+   *
+   * `queryNames` is deliberately NOT given the same arm: its three consumers —
+   * the diagnostic, the default merge and the mode gate — all want `[]` for a
+   * missing route, and only this one asks a question that presupposes existence.
+   */
+  pathNames: (name: string) => readonly string[] | undefined;
+  /**
+   * Opt-in sink for a key the route declares NOWHERE (#1579 — the params half
+   * of #1553). Absent unless `validation-plugin` is installed, and the absence
+   * is what keeps the scan off the hot path: core checks one `undefined` and
+   * skips the walk entirely.
+   *
+   * ⚠ The absence has to be REAL — the router implements this member as a
+   * GETTER returning `undefined` while `validator === null`, not as a closure
+   * that forwards into an optional-chained validator. A closure is always
+   * truthy, so the gate would read as taken and bare core would walk the
+   * caller's bag on every commit; the `| undefined` in the type is what lets
+   * the getter say so under `exactOptionalPropertyTypes`.
+   *
+   * A diagnostic, never a gate — core keeps the key in `state.params` as
+   * app-level data (wiki `Route.md`). Dropping it was measured and rejected: it
+   * retires a shipped capability, and "declared nowhere" cannot tell a typo from
+   * `navigate("users", { id })` on a parent whose CHILD declares `:id`.
+   */
+  reportUndeclaredParamKey?: ((routeName: string, key: string) => void) | undefined;
+}
+//#endregion
+export { RouteResolver };
+//# sourceMappingURL=port.d.ts.map

package/dist/cjs/pipeline/port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.d.ts","names":[],"sources":["../../../src/pipeline/port.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAwCiB;;;;;;;;EAQf,iBACE,cACA,QAAQ,QACR,SAAS;IAET;IACA,QAAQ;IAIR,SAAS;;;;;;;;;;;;;;EAeX,gBAAgB,iBAAiB;EACjC,gBAAgB,iBAAiB;;;;;;;EAQjC,YAAY,cAAc,QAAQ,QAAQ,QAAQ;;;;;;;EAQlD,aAAa;;;;;;;EAQb;;;;;;;;;;;;;;;;;;EAmBA,0BACI,mBAAmB;;;;;;;;;;;;;;;;;;;;EAqBvB,YAAY;;;;;;;;;;;;;;;;;;;EAoBZ,6BACI,mBAAmB"}

package/dist/cjs/routerFSM.js

@@ -1,2 +1,2 @@
-const e=require("./foundation/fsm/fsm.js"),t={IDLE:`IDLE`,STARTING:`STARTING`,READY:`READY`,TRANSITION_STARTED:`TRANSITION_STARTED`,LEAVE_APPROVED:`LEAVE_APPROVED`,DISPOSED:`DISPOSED`},n={START:`START`,STARTED:`STARTED`,NAVIGATE:`NAVIGATE`,LEAVE_APPROVE:`LEAVE_APPROVE`,COMPLETE:`COMPLETE`,FAIL:`FAIL`,CANCEL:`CANCEL`,STOP:`STOP`,DISPOSE:`DISPOSE`},r={initial:t.IDLE,context:null,transitions:{[t.IDLE]:{[n.START]:t.STARTING,[n.DISPOSE]:t.DISPOSED},[t.STARTING]:{[n.STARTED]:t.READY,[n.FAIL]:t.IDLE,[n.STOP]:t.IDLE,[n.DISPOSE]:t.DISPOSED},[t.READY]:{[n.NAVIGATE]:t.TRANSITION_STARTED,[n.FAIL]:t.READY,[n.STOP]:t.IDLE,[n.DISPOSE]:t.DISPOSED},[t.TRANSITION_STARTED]:{[n.NAVIGATE]:t.TRANSITION_STARTED,[n.LEAVE_APPROVE]:t.LEAVE_APPROVED,[n.CANCEL]:t.READY,[n.FAIL]:t.READY,[n.DISPOSE]:t.DISPOSED},[t.LEAVE_APPROVED]:{[n.NAVIGATE]:t.TRANSITION_STARTED,[n.COMPLETE]:t.READY,[n.CANCEL]:t.READY,[n.FAIL]:t.READY,[n.DISPOSE]:t.DISPOSED},[t.DISPOSED]:{}}};function i(){return new e.FSM(r)}exports.createRouterFSM=i,exports.routerEvents=n,exports.routerStates=t;
+const e=require("./utils/fsm/fsm.js"),t={IDLE:`IDLE`,STARTING:`STARTING`,READY:`READY`,TRANSITION_STARTED:`TRANSITION_STARTED`,LEAVE_APPROVED:`LEAVE_APPROVED`,DISPOSED:`DISPOSED`},n={START:`START`,STARTED:`STARTED`,NAVIGATE:`NAVIGATE`,LEAVE_APPROVE:`LEAVE_APPROVE`,COMPLETE:`COMPLETE`,FAIL:`FAIL`,CANCEL:`CANCEL`,STOP:`STOP`,DISPOSE:`DISPOSE`},r={initial:t.IDLE,context:null,transitions:{[t.IDLE]:{[n.START]:t.STARTING,[n.DISPOSE]:t.DISPOSED},[t.STARTING]:{[n.STARTED]:t.READY,[n.FAIL]:t.IDLE,[n.STOP]:t.IDLE,[n.DISPOSE]:t.DISPOSED},[t.READY]:{[n.NAVIGATE]:t.TRANSITION_STARTED,[n.FAIL]:t.READY,[n.STOP]:t.IDLE,[n.DISPOSE]:t.DISPOSED},[t.TRANSITION_STARTED]:{[n.NAVIGATE]:t.TRANSITION_STARTED,[n.LEAVE_APPROVE]:t.LEAVE_APPROVED,[n.CANCEL]:t.READY,[n.FAIL]:t.READY,[n.DISPOSE]:t.DISPOSED},[t.LEAVE_APPROVED]:{[n.NAVIGATE]:t.TRANSITION_STARTED,[n.COMPLETE]:t.READY,[n.CANCEL]:t.READY,[n.FAIL]:t.READY,[n.DISPOSE]:t.DISPOSED},[t.DISPOSED]:{}}};function i(){return new e.FSM(r)}exports.createRouterFSM=i,exports.routerEvents=n,exports.routerStates=t;
 //# sourceMappingURL=routerFSM.js.map

package/dist/cjs/routerFSM.js.map

@@ -1 +1 @@
-{"version":3,"file":"routerFSM.js","names":["FSM"],"sources":["../../src/routerFSM.ts"],"sourcesContent":["// packages/core/src/routerFSM.ts\n\nimport { FSM } from \"./foundation/fsm\";\n\nimport type { FSMConfig } from \"./foundation/fsm\";\nimport type { NavigationOptions, State } from \"./types\";\n\n/**\n * Router FSM states.\n *\n * - IDLE: Router not started or stopped\n * - STARTING: Router is initializing\n * - READY: Router is ready for navigation\n * - TRANSITION_STARTED: Navigation in progress (before deactivation guards)\n * - LEAVE_APPROVED: Deactivation guards passed, activation guards pending\n * - DISPOSED: Router has been disposed (R2+)\n */\nexport const routerStates = {\n  IDLE: \"IDLE\",\n  STARTING: \"STARTING\",\n  READY: \"READY\",\n  TRANSITION_STARTED: \"TRANSITION_STARTED\",\n  LEAVE_APPROVED: \"LEAVE_APPROVED\",\n  DISPOSED: \"DISPOSED\",\n} as const;\n\nexport type RouterState = (typeof routerStates)[keyof typeof routerStates];\n\n/**\n * Router FSM events.\n *\n * - START: Begin router initialization\n * - STARTED: Router initialization complete\n * - NAVIGATE: Begin navigation\n * - COMPLETE: Navigation completed successfully\n * - FAIL: Navigation or initialization failed\n * - CANCEL: Navigation cancelled\n * - STOP: Stop router\n * - DISPOSE: Dispose router (R2+)\n */\nexport const routerEvents = {\n  START: \"START\",\n  STARTED: \"STARTED\",\n  NAVIGATE: \"NAVIGATE\",\n  LEAVE_APPROVE: \"LEAVE_APPROVE\",\n  COMPLETE: \"COMPLETE\",\n  FAIL: \"FAIL\",\n  CANCEL: \"CANCEL\",\n  STOP: \"STOP\",\n  DISPOSE: \"DISPOSE\",\n} as const;\n\nexport type RouterEvent = (typeof routerEvents)[keyof typeof routerEvents];\n\n/**\n * Per-event payloads for the router FSM (#1169 commit-gate). The three hot\n * navigation transitions carry their transition states so the FSM action\n * dispatched by `send()` emits the matching transition event — i.e. events are\n * literal consequences of FSM transitions (no `forceState` + manual emit). See\n * `EventBusNamespace.#setupFSMActions`.\n */\nexport interface RouterPayloads {\n  NAVIGATE: { toState: State; fromState?: State | undefined };\n  LEAVE_APPROVE: { toState: State; fromState?: State | undefined };\n  COMPLETE: {\n    toState: State;\n    fromState?: State | undefined;\n    opts?: NavigationOptions | undefined;\n  };\n}\n\n/**\n * Router FSM configuration.\n *\n * Transitions:\n * - IDLE → STARTING (START), DISPOSED (DISPOSE)\n * - STARTING → READY (STARTED), IDLE (FAIL, STOP), DISPOSED (DISPOSE)\n * - READY → TRANSITION_STARTED (NAVIGATE), READY (FAIL, self-loop for early validation errors), IDLE (STOP), DISPOSED (DISPOSE)\n * - TRANSITION_STARTED → LEAVE_APPROVED (LEAVE_APPROVE), TRANSITION_STARTED (NAVIGATE, self-loop), READY (CANCEL, FAIL), DISPOSED (DISPOSE)\n * - LEAVE_APPROVED → READY (COMPLETE, CANCEL, FAIL), TRANSITION_STARTED (NAVIGATE), DISPOSED (DISPOSE)\n * - DISPOSED → (no transitions)\n *\n * DISPOSE is wired from every non-DISPOSED state so `router.dispose()` always\n * settles the FSM at DISPOSED. The facade orchestrates cleanup through IDLE\n * for healthy flows; the direct transitions guarantee the FSM is not left\n * stuck if cleanup is skipped (e.g. dispose mid-STARTING when the start\n * pipeline threw before STARTED/FAIL).\n */\nconst routerFSMConfig: FSMConfig<RouterState, RouterEvent, null> = {\n  initial: routerStates.IDLE,\n  context: null,\n  transitions: {\n    [routerStates.IDLE]: {\n      [routerEvents.START]: routerStates.STARTING,\n      [routerEvents.DISPOSE]: routerStates.DISPOSED,\n    },\n    [routerStates.STARTING]: {\n      [routerEvents.STARTED]: routerStates.READY,\n      [routerEvents.FAIL]: routerStates.IDLE,\n      [routerEvents.STOP]: routerStates.IDLE,\n      [routerEvents.DISPOSE]: routerStates.DISPOSED,\n    },\n    [routerStates.READY]: {\n      [routerEvents.NAVIGATE]: routerStates.TRANSITION_STARTED,\n      [routerEvents.FAIL]: routerStates.READY,\n      [routerEvents.STOP]: routerStates.IDLE,\n      [routerEvents.DISPOSE]: routerStates.DISPOSED,\n    },\n    [routerStates.TRANSITION_STARTED]: {\n      [routerEvents.NAVIGATE]: routerStates.TRANSITION_STARTED,\n      [routerEvents.LEAVE_APPROVE]: routerStates.LEAVE_APPROVED,\n      [routerEvents.CANCEL]: routerStates.READY,\n      [routerEvents.FAIL]: routerStates.READY,\n      [routerEvents.DISPOSE]: routerStates.DISPOSED,\n    },\n    [routerStates.LEAVE_APPROVED]: {\n      [routerEvents.NAVIGATE]: routerStates.TRANSITION_STARTED,\n      [routerEvents.COMPLETE]: routerStates.READY,\n      [routerEvents.CANCEL]: routerStates.READY,\n      [routerEvents.FAIL]: routerStates.READY,\n      [routerEvents.DISPOSE]: routerStates.DISPOSED,\n    },\n    [routerStates.DISPOSED]: {},\n  },\n};\n\n/**\n * Factory function to create a router FSM instance.\n *\n * @returns FSM instance with initial state \"IDLE\"\n */\nexport function createRouterFSM(): FSM<\n  RouterState,\n  RouterEvent,\n  null,\n  RouterPayloads\n> {\n  return new FSM<RouterState, RouterEvent, null, RouterPayloads>(\n    routerFSMConfig,\n  );\n}\n"],"mappings":"2CAiBa,EAAe,CAC1B,KAAM,OACN,SAAU,WACV,MAAO,QACP,mBAAoB,qBACpB,eAAgB,iBAChB,SAAU,UACZ,EAgBa,EAAe,CAC1B,MAAO,QACP,QAAS,UACT,SAAU,WACV,cAAe,gBACf,SAAU,WACV,KAAM,OACN,OAAQ,SACR,KAAM,OACN,QAAS,SACX,EAsCM,EAA6D,CACjE,QAAS,EAAa,KACtB,QAAS,KACT,YAAa,EACV,EAAa,MAAO,EAClB,EAAa,OAAQ,EAAa,UAClC,EAAa,SAAU,EAAa,QACvC,GACC,EAAa,UAAW,EACtB,EAAa,SAAU,EAAa,OACpC,EAAa,MAAO,EAAa,MACjC,EAAa,MAAO,EAAa,MACjC,EAAa,SAAU,EAAa,QACvC,GACC,EAAa,OAAQ,EACnB,EAAa,UAAW,EAAa,oBACrC,EAAa,MAAO,EAAa,OACjC,EAAa,MAAO,EAAa,MACjC,EAAa,SAAU,EAAa,QACvC,GACC,EAAa,oBAAqB,EAChC,EAAa,UAAW,EAAa,oBACrC,EAAa,eAAgB,EAAa,gBAC1C,EAAa,QAAS,EAAa,OACnC,EAAa,MAAO,EAAa,OACjC,EAAa,SAAU,EAAa,QACvC,GACC,EAAa,gBAAiB,EAC5B,EAAa,UAAW,EAAa,oBACrC,EAAa,UAAW,EAAa,OACrC,EAAa,QAAS,EAAa,OACnC,EAAa,MAAO,EAAa,OACjC,EAAa,SAAU,EAAa,QACvC,GACC,EAAa,UAAW,CAAC,CAC5B,CACF,EAOA,SAAgB,GAKd,CACA,OAAO,IAAIA,EAAAA,IACT,CACF,CACF"}
+{"version":3,"file":"routerFSM.js","names":["FSM"],"sources":["../../src/routerFSM.ts"],"sourcesContent":["// packages/core/src/routerFSM.ts\n\nimport { FSM } from \"./utils/fsm\";\n\nimport type { NavigationOptions, State } from \"./types\";\nimport type { FSMConfig } from \"./utils/fsm\";\n\n/**\n * Router FSM states.\n *\n * - IDLE: Router not started or stopped\n * - STARTING: Router is initializing\n * - READY: Router is ready for navigation\n * - TRANSITION_STARTED: Navigation in progress (before deactivation guards)\n * - LEAVE_APPROVED: Deactivation guards passed, activation guards pending\n * - DISPOSED: Router has been disposed (R2+)\n */\nexport const routerStates = {\n  IDLE: \"IDLE\",\n  STARTING: \"STARTING\",\n  READY: \"READY\",\n  TRANSITION_STARTED: \"TRANSITION_STARTED\",\n  LEAVE_APPROVED: \"LEAVE_APPROVED\",\n  DISPOSED: \"DISPOSED\",\n} as const;\n\nexport type RouterState = (typeof routerStates)[keyof typeof routerStates];\n\n/**\n * Router FSM events.\n *\n * - START: Begin router initialization\n * - STARTED: Router initialization complete\n * - NAVIGATE: Begin navigation\n * - COMPLETE: Navigation completed successfully\n * - FAIL: Navigation or initialization failed\n * - CANCEL: Navigation cancelled\n * - STOP: Stop router\n * - DISPOSE: Dispose router (R2+)\n */\nexport const routerEvents = {\n  START: \"START\",\n  STARTED: \"STARTED\",\n  NAVIGATE: \"NAVIGATE\",\n  LEAVE_APPROVE: \"LEAVE_APPROVE\",\n  COMPLETE: \"COMPLETE\",\n  FAIL: \"FAIL\",\n  CANCEL: \"CANCEL\",\n  STOP: \"STOP\",\n  DISPOSE: \"DISPOSE\",\n} as const;\n\nexport type RouterEvent = (typeof routerEvents)[keyof typeof routerEvents];\n\n/**\n * Per-event payloads for the router FSM (#1169 commit-gate). The three hot\n * navigation transitions carry their transition states so the FSM action\n * dispatched by `send()` emits the matching transition event — i.e. events are\n * literal consequences of FSM transitions (no `forceState` + manual emit). See\n * `EventBusNamespace.#setupFSMActions`.\n */\nexport interface RouterPayloads {\n  NAVIGATE: { toState: State; fromState?: State | undefined };\n  LEAVE_APPROVE: { toState: State; fromState?: State | undefined };\n  COMPLETE: {\n    toState: State;\n    fromState?: State | undefined;\n    opts?: NavigationOptions | undefined;\n  };\n}\n\n/**\n * Router FSM configuration.\n *\n * Transitions:\n * - IDLE → STARTING (START), DISPOSED (DISPOSE)\n * - STARTING → READY (STARTED), IDLE (FAIL, STOP), DISPOSED (DISPOSE)\n * - READY → TRANSITION_STARTED (NAVIGATE), READY (FAIL, self-loop for early validation errors), IDLE (STOP), DISPOSED (DISPOSE)\n * - TRANSITION_STARTED → LEAVE_APPROVED (LEAVE_APPROVE), TRANSITION_STARTED (NAVIGATE, self-loop), READY (CANCEL, FAIL), DISPOSED (DISPOSE)\n * - LEAVE_APPROVED → READY (COMPLETE, CANCEL, FAIL), TRANSITION_STARTED (NAVIGATE), DISPOSED (DISPOSE)\n * - DISPOSED → (no transitions)\n *\n * DISPOSE is wired from every non-DISPOSED state so `router.dispose()` always\n * settles the FSM at DISPOSED. The facade orchestrates cleanup through IDLE\n * for healthy flows; the direct transitions guarantee the FSM is not left\n * stuck if cleanup is skipped (e.g. dispose mid-STARTING when the start\n * pipeline threw before STARTED/FAIL).\n */\nconst routerFSMConfig: FSMConfig<RouterState, RouterEvent, null> = {\n  initial: routerStates.IDLE,\n  context: null,\n  transitions: {\n    [routerStates.IDLE]: {\n      [routerEvents.START]: routerStates.STARTING,\n      [routerEvents.DISPOSE]: routerStates.DISPOSED,\n    },\n    [routerStates.STARTING]: {\n      [routerEvents.STARTED]: routerStates.READY,\n      [routerEvents.FAIL]: routerStates.IDLE,\n      [routerEvents.STOP]: routerStates.IDLE,\n      [routerEvents.DISPOSE]: routerStates.DISPOSED,\n    },\n    [routerStates.READY]: {\n      [routerEvents.NAVIGATE]: routerStates.TRANSITION_STARTED,\n      [routerEvents.FAIL]: routerStates.READY,\n      [routerEvents.STOP]: routerStates.IDLE,\n      [routerEvents.DISPOSE]: routerStates.DISPOSED,\n    },\n    [routerStates.TRANSITION_STARTED]: {\n      [routerEvents.NAVIGATE]: routerStates.TRANSITION_STARTED,\n      [routerEvents.LEAVE_APPROVE]: routerStates.LEAVE_APPROVED,\n      [routerEvents.CANCEL]: routerStates.READY,\n      [routerEvents.FAIL]: routerStates.READY,\n      [routerEvents.DISPOSE]: routerStates.DISPOSED,\n    },\n    [routerStates.LEAVE_APPROVED]: {\n      [routerEvents.NAVIGATE]: routerStates.TRANSITION_STARTED,\n      [routerEvents.COMPLETE]: routerStates.READY,\n      [routerEvents.CANCEL]: routerStates.READY,\n      [routerEvents.FAIL]: routerStates.READY,\n      [routerEvents.DISPOSE]: routerStates.DISPOSED,\n    },\n    [routerStates.DISPOSED]: {},\n  },\n};\n\n/**\n * Factory function to create a router FSM instance.\n *\n * @returns FSM instance with initial state \"IDLE\"\n */\nexport function createRouterFSM(): FSM<\n  RouterState,\n  RouterEvent,\n  null,\n  RouterPayloads\n> {\n  return new FSM<RouterState, RouterEvent, null, RouterPayloads>(\n    routerFSMConfig,\n  );\n}\n"],"mappings":"sCAiBa,EAAe,CAC1B,KAAM,OACN,SAAU,WACV,MAAO,QACP,mBAAoB,qBACpB,eAAgB,iBAChB,SAAU,UACZ,EAgBa,EAAe,CAC1B,MAAO,QACP,QAAS,UACT,SAAU,WACV,cAAe,gBACf,SAAU,WACV,KAAM,OACN,OAAQ,SACR,KAAM,OACN,QAAS,SACX,EAsCM,EAA6D,CACjE,QAAS,EAAa,KACtB,QAAS,KACT,YAAa,EACV,EAAa,MAAO,EAClB,EAAa,OAAQ,EAAa,UAClC,EAAa,SAAU,EAAa,QACvC,GACC,EAAa,UAAW,EACtB,EAAa,SAAU,EAAa,OACpC,EAAa,MAAO,EAAa,MACjC,EAAa,MAAO,EAAa,MACjC,EAAa,SAAU,EAAa,QACvC,GACC,EAAa,OAAQ,EACnB,EAAa,UAAW,EAAa,oBACrC,EAAa,MAAO,EAAa,OACjC,EAAa,MAAO,EAAa,MACjC,EAAa,SAAU,EAAa,QACvC,GACC,EAAa,oBAAqB,EAChC,EAAa,UAAW,EAAa,oBACrC,EAAa,eAAgB,EAAa,gBAC1C,EAAa,QAAS,EAAa,OACnC,EAAa,MAAO,EAAa,OACjC,EAAa,SAAU,EAAa,QACvC,GACC,EAAa,gBAAiB,EAC5B,EAAa,UAAW,EAAa,oBACrC,EAAa,UAAW,EAAa,OACrC,EAAa,QAAS,EAAa,OACnC,EAAa,MAAO,EAAa,OACjC,EAAa,SAAU,EAAa,QACvC,GACC,EAAa,UAAW,CAAC,CAC5B,CACF,EAOA,SAAgB,GAKd,CACA,OAAO,IAAIA,EAAAA,IACT,CACF,CACF"}

package/dist/cjs/transitionPath.js

@@ -1,2 +1,2 @@
-const e=require("./stateMetaStore.js"),t=[];Object.freeze(t);function n(e){let t=e.split(`.`),n=t.length,r=[t[0]],i=t[0].length;for(let a=1;a<n-1;a++)i+=1+t[a].length,r.push(e.slice(0,i));return r.push(e),r}const r=new Set([`string`,`number`,`boolean`]);function i(e){return r.has(typeof e)}function a(e,t,n,r){let a=t[e];if(!a||typeof a!=`object`)return!0;for(let e of Object.keys(a)){let t=n.params[e],a=r.params[e];if(i(t)&&i(a)&&String(t)!==String(a))return!1}return!0}function o(e,t,n,r,i,o){for(let s=0;s<o;s++){let o=r[s];if(o!==i[s]||!a(o,e,t,n))return s}return o}const s=new Map;function c(e){let t=s.get(e);if(t)return t;let n=l(e);return Object.freeze(n),s.set(e,n),n}function l(e){if(!e)return[``];let t=e.indexOf(`.`);if(t===-1)return[e];let r=e.indexOf(`.`,t+1);if(r===-1)return[e.slice(0,t),e];let i=e.indexOf(`.`,r+1);return i===-1?[e.slice(0,t),e.slice(0,r),e]:e.indexOf(`.`,i+1)===-1?[e.slice(0,t),e.slice(0,r),e.slice(0,i),e]:n(e)}let u,d,f=null,p,m,h=null;function g(n,r){if(!r)return{intersection:``,toActivate:c(n.name),toDeactivate:t};let i=e.getStateMetaParams(n),a=e.getStateMetaParams(r);if(!i&&!a)return{intersection:``,toActivate:c(n.name),toDeactivate:c(r.name)};let s=c(n.name),l=c(r.name),u=Math.min(l.length,s.length),d=o(i??a,n,r,s,l,u),f;if(d>=l.length)f=t;else if(d===0&&l.length===1)f=l;else{f=[];for(let e=l.length-1;e>=d;e--)f.push(l[e])}let p=d===0?s:s.slice(d);return{intersection:d>0?l[d-1]:``,toDeactivate:f,toActivate:p}}function _(e,t){if(f!==null&&e===u&&t===d)return f;if(h!==null&&e===p&&t===m)return h;let n=g(e,t);return p=u,m=d,h=f,u=e,d=t,f=n,n}exports.getTransitionPath=_,exports.nameToIDs=c;
+const e=[];Object.freeze(e);function t(e){let t=e.split(`.`),n=t.length,r=[t[0]],i=t[0].length;for(let a=1;a<n-1;a++)i+=1+t[a].length,r.push(e.slice(0,i));return r.push(e),r}const n=new Set([`string`,`number`,`boolean`]);function r(e){return n.has(typeof e)}function i(e,t,n,i){let a=t[e];if(!a||typeof a!=`object`)return!0;for(let e of Object.keys(a)){let t=n.params[e],a=i.params[e];if(r(t)&&r(a)&&String(t)!==String(a))return!1}return!0}function a(e,t,n,r,a,o){for(let s=0;s<o;s++){let o=r[s];if(o!==a[s]||!i(o,e,t,n))return s}return o}const o=new Map;function s(e){let t=o.get(e);if(t)return t;let n=c(e);return Object.freeze(n),o.set(e,n),n}function c(e){if(!e)return[``];let n=e.indexOf(`.`);if(n===-1)return[e];let r=e.indexOf(`.`,n+1);if(r===-1)return[e.slice(0,n),e];let i=e.indexOf(`.`,r+1);return i===-1?[e.slice(0,n),e.slice(0,r),e]:e.indexOf(`.`,i+1)===-1?[e.slice(0,n),e.slice(0,r),e.slice(0,i),e]:t(e)}let l,u,d=null,f,p,m=null;function h(t,n,r){if(!n)return{intersection:``,toActivate:s(t.name),toDeactivate:e};let i=r(t.name),o=r(n.name);if(!i&&!o)return{intersection:``,toActivate:s(t.name),toDeactivate:s(n.name)};let c=s(t.name),l=s(n.name),u=Math.min(l.length,c.length),d=a(i??o,t,n,c,l,u),f;if(d>=l.length)f=e;else if(d===0&&l.length===1)f=l;else{f=[];for(let e=l.length-1;e>=d;e--)f.push(l[e])}let p=d===0?c:c.slice(d);return{intersection:d>0?l[d-1]:``,toDeactivate:f,toActivate:p}}function g(e,t,n){if(d!==null&&e===l&&t===u)return d;if(m!==null&&e===f&&t===p)return m;let r=h(e,t,n);return f=l,p=u,m=d,l=e,u=t,d=r,r}exports.getTransitionPath=g,exports.nameToIDs=s;
 //# sourceMappingURL=transitionPath.js.map

package/dist/cjs/transitionPath.js.map

@@ -1 +1 @@
-{"version":3,"file":"transitionPath.js","names":["getStateMetaParams"],"sources":["../../src/transitionPath.ts"],"sourcesContent":["// packages/core/src/transitionPath.ts\n\nimport { getStateMetaParams } from \"./stateMetaStore\";\n\nimport type { State } from \"./types\";\n\n/**\n * Parameters extracted from a route segment.\n * Maps parameter names to their string values.\n */\ntype PrimitiveParam = string | number | boolean;\n\n/**\n * Represents a transition path between two router states.\n * Contains information about which route segments need to be activated/deactivated.\n */\nexport interface TransitionPath {\n  /** The common ancestor route segment where paths diverge */\n  intersection: string;\n  /** Route segments that need to be deactivated (in reverse order) */\n  toDeactivate: string[];\n  /** Route segments that need to be activated (in order) */\n  toActivate: string[];\n}\n\n// Constants for better maintainability\nconst ROUTE_SEGMENT_SEPARATOR = \".\";\nconst EMPTY_INTERSECTION = \"\";\nconst DEFAULT_ROUTE_NAME = \"\";\nconst FROZEN_EMPTY_ARRAY: string[] = [];\n\nObject.freeze(FROZEN_EMPTY_ARRAY);\n\n/**\n * Handles conversion of route names with many segments (5+).\n * Internal helper for nameToIDs function.\n *\n * Uses optimized hybrid approach: split to get segments, then slice original\n * string to build cumulative paths. This approach is 65-81% faster than\n * string concatenation for typical cases (5-10 segments).\n *\n * @param name - Route name with 5 or more segments\n * @returns Array of cumulative segment IDs\n * @throws {Error} If route depth exceeds maximum allowed\n * @internal\n */\nfunction nameToIDsGeneral(name: string): string[] {\n  // We know there are at least 5 segments at this point (after fast paths)\n  const segments = name.split(ROUTE_SEGMENT_SEPARATOR);\n  const segmentCount = segments.length;\n\n  // First segment is always just itself\n  const ids: string[] = [segments[0]];\n\n  // Calculate cumulative lengths and slice from original string\n  // This avoids repeated string concatenation (O(k²) → O(k))\n  let cumulativeLength = segments[0].length;\n\n  for (let i = 1; i < segmentCount - 1; i++) {\n    cumulativeLength += 1 + segments[i].length; // +1 for dot separator\n    ids.push(name.slice(0, cumulativeLength));\n  }\n\n  // Last segment is always the full route name\n  ids.push(name);\n\n  return ids;\n}\n\nconst PRIMITIVE_TYPES: ReadonlySet<string> = new Set([\n  \"string\",\n  \"number\",\n  \"boolean\",\n]);\n\nfunction isPrimitive(value: unknown): value is PrimitiveParam {\n  return PRIMITIVE_TYPES.has(typeof value);\n}\n\n/**\n * Compares segment parameters between two states without creating intermediate objects.\n * Returns true if all primitive params for the given segment are equal in both states.\n */\nfunction segmentParamsEqual(\n  name: string,\n  toMetaParams: Record<string, unknown>,\n  toState: State,\n  fromState: State,\n): boolean {\n  const keys = toMetaParams[name];\n\n  if (!keys || typeof keys !== \"object\") {\n    return true;\n  }\n\n  for (const key of Object.keys(keys)) {\n    const toVal = toState.params[key];\n    const fromVal = fromState.params[key];\n\n    if (\n      isPrimitive(toVal) &&\n      isPrimitive(fromVal) &&\n      String(toVal) !== String(fromVal)\n    ) {\n      return false;\n    }\n  }\n\n  return true;\n}\n\n/**\n * Finds the point where two state paths diverge based on segments and parameters.\n * Compares both segment names and their parameters to find the first difference.\n *\n * @param toMetaParams - Cached meta.params from toState (avoids per-segment WeakMap lookup)\n * @param toState - Target state\n * @param fromState - Source state\n * @param toStateIds - Segment IDs for target state\n * @param fromStateIds - Segment IDs for source state\n * @param maxI - Maximum index to check (minimum of both arrays)\n * @returns Index of first difference, or maxI if all checked segments match\n */\nfunction pointOfDifference(\n  toMetaParams: Record<string, unknown>,\n  toState: State,\n  fromState: State,\n  toStateIds: string[],\n  fromStateIds: string[],\n  maxI: number,\n): number {\n  for (let i = 0; i < maxI; i++) {\n    const toSegment = toStateIds[i];\n    const fromSegment = fromStateIds[i];\n\n    // Different segment names - immediate difference\n    if (toSegment !== fromSegment) {\n      return i;\n    }\n\n    if (!segmentParamsEqual(toSegment, toMetaParams, toState, fromState)) {\n      return i;\n    }\n  }\n\n  return maxI;\n}\n\n/**\n * Converts a route name to an array of hierarchical segment identifiers.\n * Each segment ID includes all parent segments in the path.\n *\n * @param name - Route name in dot notation (e.g., 'users.profile.edit')\n * @returns Array of cumulative segment IDs\n * @throws {Error} If route depth exceeds maximum allowed depth\n *\n * @example\n * // Simple route\n * nameToIDs('users');\n * // Returns: ['users']\n *\n * @example\n * // Nested route\n * nameToIDs('users.profile.edit');\n * // Returns: ['users', 'users.profile', 'users.profile.edit']\n *\n * @example\n * // Empty string (root route)\n * nameToIDs('');\n * // Returns: ['']\n *\n * @remarks\n * Input parameter is NOT validated in this function for performance reasons.\n * Validation significantly slows down nameToIDs execution.\n * The input should be validated by the function/method that calls nameToIDs.\n */\n// Module-global cache (shared across all router instances): bounded in practice by\n// the app's route-name vocabulary, which is stable across cloneRouter() requests, so\n// it does not grow per request. Intentionally NOT cleared on dispose() — it is not\n// per-router, so one router's teardown must not evict entries other routers rely on.\nconst nameToIDsCache = new Map<string, string[]>();\n\nexport function nameToIDs(name: string): string[] {\n  const cached = nameToIDsCache.get(name);\n\n  // Stryker disable next-line BlockStatement: equivalent — dropping the cache-hit early return recomputes the identical frozen id chain (the cache is a perf optimization, not a correctness gate).\n  if (cached) {\n    return cached;\n  }\n\n  const result = computeNameToIDs(name);\n\n  Object.freeze(result);\n  nameToIDsCache.set(name, result);\n\n  return result;\n}\n\nfunction computeNameToIDs(name: string): string[] {\n  if (!name) {\n    return [DEFAULT_ROUTE_NAME];\n  }\n\n  const firstDot = name.indexOf(ROUTE_SEGMENT_SEPARATOR);\n\n  if (firstDot === -1) {\n    return [name];\n  }\n\n  const secondDot = name.indexOf(ROUTE_SEGMENT_SEPARATOR, firstDot + 1);\n\n  if (secondDot === -1) {\n    return [name.slice(0, firstDot), name];\n  }\n\n  const thirdDot = name.indexOf(ROUTE_SEGMENT_SEPARATOR, secondDot + 1);\n\n  // Stryker disable next-line UnaryOperator,BlockStatement: equivalent — inverting/emptying the 3-segment fast path routes the name through nameToIDsGeneral (below), which yields the identical id chain (same rationale as the L242 ArithmeticOperator disable). The ConditionalExpression/EqualityOperator siblings stay live (→true and !== are killed).\n  if (thirdDot === -1) {\n    return [name.slice(0, firstDot), name.slice(0, secondDot), name];\n  }\n\n  // Stryker disable next-line ArithmeticOperator: equivalent — `thirdDot - 1` makes fourthDot non-(-1), routing 5+ segment names through nameToIDsGeneral, which yields the identical id chain.\n  const fourthDot = name.indexOf(ROUTE_SEGMENT_SEPARATOR, thirdDot + 1);\n\n  // Stryker disable next-line UnaryOperator,BlockStatement: equivalent — inverting/emptying the 4-segment fast path routes the name through nameToIDsGeneral (below), which yields the identical id chain (same rationale as the L242 ArithmeticOperator disable). The ConditionalExpression/EqualityOperator siblings stay live (→true and !== are killed).\n  if (fourthDot === -1) {\n    return [\n      name.slice(0, firstDot),\n      name.slice(0, secondDot),\n      name.slice(0, thirdDot),\n      name,\n    ];\n  }\n\n  return nameToIDsGeneral(name);\n}\n\n/**\n * Calculates the transition path between two router states.\n * Determines which route segments need to be deactivated and activated\n * to transition from one state to another.\n *\n * @param toState - Target state to transition to\n * @param fromState - Current state to transition from (optional)\n * @returns Transition path with intersection and segments to activate/deactivate\n *\n * @throws {TypeError} When toState is null or undefined\n * @throws {TypeError} When toState is not an object\n * @throws {TypeError} When toState.name is missing or not a string\n * @throws {TypeError} When toState.params is missing or not an object\n * @throws {TypeError} When toState.path is missing or not a string\n * @throws {TypeError} When toState.name contains invalid route format:\n *   - Contains only whitespace (e.g., \"   \")\n *   - Has consecutive dots (e.g., \"users..profile\")\n *   - Has leading/trailing dots (e.g., \".users\" or \"users.\")\n *   - Segments don't match pattern [a-zA-Z_][a-zA-Z0-9_-]* (e.g., \"users.123\")\n *   - Contains spaces or special characters (e.g., \"users profile\")\n *   - Exceeds maximum length (8192 characters)\n * @throws {TypeError} When fromState is provided and has any of the validation errors listed above for toState\n *\n * @example\n * // ✅ Valid calls\n * getTransitionPath({ name: 'users.profile', params: {}, path: '/users/profile' });\n * getTransitionPath(toState, fromState);\n * getTransitionPath({ name: '', params: {}, path: '/' }); // root route\n *\n * @example\n * // ❌ Invalid calls that throw TypeError\n * getTransitionPath(null);                                    // toState is null\n * getTransitionPath(undefined);                               // toState is undefined\n * getTransitionPath({});                                      // missing required fields\n * getTransitionPath({ name: 123, params: {}, path: '/' });    // name not a string\n * getTransitionPath({ name: 'home', path: '/' });             // missing params\n * getTransitionPath({ name: 'users..profile', params: {}, path: '/' }); // consecutive dots\n * getTransitionPath({ name: '.users', params: {}, path: '/' });         // leading dot\n * getTransitionPath({ name: 'users.', params: {}, path: '/' });         // trailing dot\n * getTransitionPath({ name: 'users profile', params: {}, path: '/' });  // contains space\n * getTransitionPath({ name: 'users.123', params: {}, path: '/' });      // segment starts with number\n * getTransitionPath(validToState, { name: 'invalid..route', params: {}, path: '/' }); // fromState invalid\n *\n * @example\n * // Full activation (no fromState)\n * getTransitionPath(makeState('users.profile'));\n * // Returns: {\n * //   intersection: '',\n * //   toActivate: ['users', 'users.profile'],\n * //   toDeactivate: []\n * // }\n *\n * @example\n * // Partial transition with common ancestor\n * getTransitionPath(\n *   makeState('users.profile'),\n *   makeState('users.list')\n * );\n * // Returns: {\n * //   intersection: 'users',\n * //   toActivate: ['users.profile'],\n * //   toDeactivate: ['users.list']\n * // }\n *\n * @example\n * // Complete route change\n * getTransitionPath(\n *   makeState('admin.dashboard'),\n *   makeState('users.profile')\n * );\n * // Returns: {\n * //   intersection: '',\n * //   toActivate: ['admin', 'admin.dashboard'],\n * //   toDeactivate: ['users.profile', 'users']\n * // }\n */\n// Single-entry cache: shouldUpdateNode calls getTransitionPath N times per\n// navigation with the same state objects (once per subscribed node).\n// Cache by reference eliminates N-1 redundant computations.\n// Module-global (≤2 State refs); not cleared on dispose — negligible, not per-router.\nlet cached1To: State | undefined;\nlet cached1From: State | undefined;\nlet cached1Result: TransitionPath | null = null;\n\nlet cached2To: State | undefined;\nlet cached2From: State | undefined;\nlet cached2Result: TransitionPath | null = null;\n\nfunction computeTransitionPath(\n  toState: State,\n  fromState?: State,\n): TransitionPath {\n  // ===== FAST PATH 1: Initial navigation (no fromState) =====\n  // This is the best performing case in benchmarks (5M ops/sec)\n  if (!fromState) {\n    return {\n      intersection: EMPTY_INTERSECTION,\n      toActivate: nameToIDs(toState.name),\n      toDeactivate: FROZEN_EMPTY_ARRAY,\n    };\n  }\n\n  // ===== FAST PATH 3: Missing meta requires full reload =====\n  // Single WeakMap lookup per state, reused in pointOfDifference/segmentParamsEqual\n  const toMetaParams = getStateMetaParams(toState);\n  const fromMetaParams = getStateMetaParams(fromState);\n\n  if (!toMetaParams && !fromMetaParams) {\n    // FAST PATH 3 (both states meta-less). Consumers that land here read the\n    // result order-INSENSITIVELY, so the from-chain is returned as-is\n    // (root→leaf, no reverse needed):\n    //   • `shouldUpdateNode` reads `toDeactivate` by MEMBERSHIP (`.includes`).\n    //   • Externally-supplied meta-less states (e.g. a plugin passing a raw\n    //     `{name, params, path}` to `navigateToState`) land here. Since #1170,\n    //     `navigateToState` carries the source's WeakMap meta across its writable\n    //     shell, so start()/popstate states are NOT meta-less. A `replace()`\n    //     survivor stays meta-less but is benign: the next transition's `toState`\n    //     always carries meta (buildNavigateState), so this both-meta-less path\n    //     is not reached from it.\n    // (`canNavigateTo` no longer reaches this path — since #970 it builds its\n    // toState WITH meta, mirroring buildNavigateState.)\n    // The navigate pipeline always carries meta (buildNavigateState) → STANDARD\n    // PATH below, which trims the shared ancestor and reverses correctly.\n    return {\n      intersection: EMPTY_INTERSECTION,\n      toActivate: nameToIDs(toState.name),\n      toDeactivate: nameToIDs(fromState.name),\n    };\n  }\n\n  // ===== STANDARD PATH: Routes with parameters =====\n  const toStateIds = nameToIDs(toState.name);\n  const fromStateIds = nameToIDs(fromState.name);\n  // Stryker disable next-line MethodExpression: equivalent — Math.max reads one index past the shorter id array; that slot is undefined, so the `toSegment !== fromSegment` check in pointOfDifference returns the same divergence index Math.min would stop at.\n  const maxI = Math.min(fromStateIds.length, toStateIds.length);\n\n  const i = pointOfDifference(\n    (toMetaParams ?? fromMetaParams) as Record<string, unknown>,\n    toState,\n    fromState,\n    toStateIds,\n    fromStateIds,\n    maxI,\n  );\n\n  // Optimization: Build deactivation list in reverse order directly\n  // instead of slice(i).toReversed() which creates 2 arrays\n  let toDeactivate: string[];\n\n  if (i >= fromStateIds.length) {\n    toDeactivate = FROZEN_EMPTY_ARRAY;\n  } else if (i === 0 && fromStateIds.length === 1) {\n    // Single-segment route: reversed = original, reuse cached frozen array\n    toDeactivate = fromStateIds;\n  } else {\n    toDeactivate = [];\n\n    for (let j = fromStateIds.length - 1; j >= i; j--) {\n      toDeactivate.push(fromStateIds[j]);\n    }\n  }\n\n  // Build activation list — reuse cached frozen array when using full list\n  const toActivate = i === 0 ? toStateIds : toStateIds.slice(i);\n\n  // Determine intersection point (common ancestor)\n  const intersection = i > 0 ? fromStateIds[i - 1] : EMPTY_INTERSECTION;\n\n  return {\n    intersection,\n    toDeactivate,\n    toActivate,\n  };\n}\n\nexport function getTransitionPath(\n  toState: State,\n  fromState?: State,\n): TransitionPath {\n  // Stryker disable BlockStatement: equivalent — both cache short-circuits below; emptying either early-return recomputes the identical TransitionPath (computeTransitionPath is deterministic for the same to/from states) and re-caches it. Restored right after.\n  if (\n    cached1Result !== null &&\n    toState === cached1To &&\n    fromState === cached1From\n  ) {\n    return cached1Result;\n  }\n\n  if (\n    cached2Result !== null &&\n    toState === cached2To &&\n    fromState === cached2From\n  ) {\n    return cached2Result;\n  }\n  // Stryker restore BlockStatement\n\n  const result = computeTransitionPath(toState, fromState);\n\n  cached2To = cached1To;\n  cached2From = cached1From;\n  cached2Result = cached1Result;\n\n  cached1To = toState;\n  cached1From = fromState;\n  cached1Result = result;\n\n  return result;\n}\n"],"mappings":"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"}
+{"version":3,"file":"transitionPath.js","names":[],"sources":["../../src/transitionPath.ts"],"sourcesContent":["// packages/core/src/transitionPath.ts\n\nimport type { State } from \"./types\";\n\n/**\n * Per-segment param-source map for a route name — `{ segment: { param: \"url\" |\n * \"query\" } }`. Resolved from the live matcher via `RoutesNamespace.getMetaForState`\n * (RFC-4 M2 / #1548: this replaced the removed `stateMetaStore` WeakMap — ownership\n * is now read by `state.name`, not carried per-State object). `undefined` when the\n * name is not in the tree (a CRUD-removed route → FAST PATH 3 fallback).\n */\nexport type RouteMetaLookup = (\n  name: string,\n) => Record<string, Record<string, \"url\" | \"query\">> | undefined;\n\n/**\n * Parameters extracted from a route segment.\n * Maps parameter names to their string values.\n */\ntype PrimitiveParam = string | number | boolean;\n\n/**\n * Represents a transition path between two router states.\n * Contains information about which route segments need to be activated/deactivated.\n */\nexport interface TransitionPath {\n  /** The common ancestor route segment where paths diverge */\n  intersection: string;\n  /** Route segments that need to be deactivated (in reverse order) */\n  toDeactivate: string[];\n  /** Route segments that need to be activated (in order) */\n  toActivate: string[];\n}\n\n// Constants for better maintainability\nconst ROUTE_SEGMENT_SEPARATOR = \".\";\nconst EMPTY_INTERSECTION = \"\";\nconst DEFAULT_ROUTE_NAME = \"\";\nconst FROZEN_EMPTY_ARRAY: string[] = [];\n\nObject.freeze(FROZEN_EMPTY_ARRAY);\n\n/**\n * Handles conversion of route names with many segments (5+).\n * Internal helper for nameToIDs function.\n *\n * Uses optimized hybrid approach: split to get segments, then slice original\n * string to build cumulative paths. This approach is 65-81% faster than\n * string concatenation for typical cases (5-10 segments).\n *\n * @param name - Route name with 5 or more segments\n * @returns Array of cumulative segment IDs\n * @throws {Error} If route depth exceeds maximum allowed\n * @internal\n */\nfunction nameToIDsGeneral(name: string): string[] {\n  // We know there are at least 5 segments at this point (after fast paths)\n  const segments = name.split(ROUTE_SEGMENT_SEPARATOR);\n  const segmentCount = segments.length;\n\n  // First segment is always just itself\n  const ids: string[] = [segments[0]];\n\n  // Calculate cumulative lengths and slice from original string\n  // This avoids repeated string concatenation (O(k²) → O(k))\n  let cumulativeLength = segments[0].length;\n\n  for (let i = 1; i < segmentCount - 1; i++) {\n    cumulativeLength += 1 + segments[i].length; // +1 for dot separator\n    ids.push(name.slice(0, cumulativeLength));\n  }\n\n  // Last segment is always the full route name\n  ids.push(name);\n\n  return ids;\n}\n\nconst PRIMITIVE_TYPES: ReadonlySet<string> = new Set([\n  \"string\",\n  \"number\",\n  \"boolean\",\n]);\n\nfunction isPrimitive(value: unknown): value is PrimitiveParam {\n  return PRIMITIVE_TYPES.has(typeof value);\n}\n\n/**\n * Compares segment parameters between two states without creating intermediate objects.\n * Returns true if all primitive params for the given segment are equal in both states.\n */\nfunction segmentParamsEqual(\n  name: string,\n  toMetaParams: Record<string, unknown>,\n  toState: State,\n  fromState: State,\n): boolean {\n  const keys = toMetaParams[name];\n\n  if (!keys || typeof keys !== \"object\") {\n    return true;\n  }\n\n  for (const key of Object.keys(keys)) {\n    const toVal = toState.params[key];\n    const fromVal = fromState.params[key];\n\n    if (\n      isPrimitive(toVal) &&\n      isPrimitive(fromVal) &&\n      String(toVal) !== String(fromVal)\n    ) {\n      return false;\n    }\n  }\n\n  return true;\n}\n\n/**\n * Finds the point where two state paths diverge based on segments and parameters.\n * Compares both segment names and their parameters to find the first difference.\n *\n * @param toMetaParams - Cached meta.params from toState (avoids per-segment WeakMap lookup)\n * @param toState - Target state\n * @param fromState - Source state\n * @param toStateIds - Segment IDs for target state\n * @param fromStateIds - Segment IDs for source state\n * @param maxI - Maximum index to check (minimum of both arrays)\n * @returns Index of first difference, or maxI if all checked segments match\n */\nfunction pointOfDifference(\n  toMetaParams: Record<string, unknown>,\n  toState: State,\n  fromState: State,\n  toStateIds: string[],\n  fromStateIds: string[],\n  maxI: number,\n): number {\n  for (let i = 0; i < maxI; i++) {\n    const toSegment = toStateIds[i];\n    const fromSegment = fromStateIds[i];\n\n    // Different segment names - immediate difference\n    if (toSegment !== fromSegment) {\n      return i;\n    }\n\n    if (!segmentParamsEqual(toSegment, toMetaParams, toState, fromState)) {\n      return i;\n    }\n  }\n\n  return maxI;\n}\n\n/**\n * Converts a route name to an array of hierarchical segment identifiers.\n * Each segment ID includes all parent segments in the path.\n *\n * @param name - Route name in dot notation (e.g., 'users.profile.edit')\n * @returns Array of cumulative segment IDs\n * @throws {Error} If route depth exceeds maximum allowed depth\n *\n * @example\n * // Simple route\n * nameToIDs('users');\n * // Returns: ['users']\n *\n * @example\n * // Nested route\n * nameToIDs('users.profile.edit');\n * // Returns: ['users', 'users.profile', 'users.profile.edit']\n *\n * @example\n * // Empty string (root route)\n * nameToIDs('');\n * // Returns: ['']\n *\n * @remarks\n * Input parameter is NOT validated in this function for performance reasons.\n * Validation significantly slows down nameToIDs execution.\n * The input should be validated by the function/method that calls nameToIDs.\n */\n// Module-global cache (shared across all router instances): bounded in practice by\n// the app's route-name vocabulary, which is stable across cloneRouter() requests, so\n// it does not grow per request. Intentionally NOT cleared on dispose() — it is not\n// per-router, so one router's teardown must not evict entries other routers rely on.\nconst nameToIDsCache = new Map<string, string[]>();\n\nexport function nameToIDs(name: string): string[] {\n  const cached = nameToIDsCache.get(name);\n\n  // Stryker disable next-line BlockStatement: equivalent — dropping the cache-hit early return recomputes the identical frozen id chain (the cache is a perf optimization, not a correctness gate).\n  if (cached) {\n    return cached;\n  }\n\n  const result = computeNameToIDs(name);\n\n  Object.freeze(result);\n  nameToIDsCache.set(name, result);\n\n  return result;\n}\n\nfunction computeNameToIDs(name: string): string[] {\n  if (!name) {\n    return [DEFAULT_ROUTE_NAME];\n  }\n\n  const firstDot = name.indexOf(ROUTE_SEGMENT_SEPARATOR);\n\n  if (firstDot === -1) {\n    return [name];\n  }\n\n  const secondDot = name.indexOf(ROUTE_SEGMENT_SEPARATOR, firstDot + 1);\n\n  if (secondDot === -1) {\n    return [name.slice(0, firstDot), name];\n  }\n\n  const thirdDot = name.indexOf(ROUTE_SEGMENT_SEPARATOR, secondDot + 1);\n\n  // Stryker disable next-line UnaryOperator,BlockStatement: equivalent — inverting/emptying the 3-segment fast path routes the name through nameToIDsGeneral (below), which yields the identical id chain (same rationale as the L242 ArithmeticOperator disable). The ConditionalExpression/EqualityOperator siblings stay live (→true and !== are killed).\n  if (thirdDot === -1) {\n    return [name.slice(0, firstDot), name.slice(0, secondDot), name];\n  }\n\n  // Stryker disable next-line ArithmeticOperator: equivalent — `thirdDot - 1` makes fourthDot non-(-1), routing 5+ segment names through nameToIDsGeneral, which yields the identical id chain.\n  const fourthDot = name.indexOf(ROUTE_SEGMENT_SEPARATOR, thirdDot + 1);\n\n  // Stryker disable next-line UnaryOperator,BlockStatement: equivalent — inverting/emptying the 4-segment fast path routes the name through nameToIDsGeneral (below), which yields the identical id chain (same rationale as the L242 ArithmeticOperator disable). The ConditionalExpression/EqualityOperator siblings stay live (→true and !== are killed).\n  if (fourthDot === -1) {\n    return [\n      name.slice(0, firstDot),\n      name.slice(0, secondDot),\n      name.slice(0, thirdDot),\n      name,\n    ];\n  }\n\n  return nameToIDsGeneral(name);\n}\n\n/**\n * Calculates the transition path between two router states.\n * Determines which route segments need to be deactivated and activated\n * to transition from one state to another.\n *\n * @param toState - Target state to transition to\n * @param fromState - Current state to transition from (optional)\n * @returns Transition path with intersection and segments to activate/deactivate\n *\n * @throws {TypeError} When toState is null or undefined\n * @throws {TypeError} When toState is not an object\n * @throws {TypeError} When toState.name is missing or not a string\n * @throws {TypeError} When toState.params is missing or not an object\n * @throws {TypeError} When toState.path is missing or not a string\n * @throws {TypeError} When toState.name contains invalid route format:\n *   - Contains only whitespace (e.g., \"   \")\n *   - Has consecutive dots (e.g., \"users..profile\")\n *   - Has leading/trailing dots (e.g., \".users\" or \"users.\")\n *   - Segments don't match pattern [a-zA-Z_][a-zA-Z0-9_-]* (e.g., \"users.123\")\n *   - Contains spaces or special characters (e.g., \"users profile\")\n *   - Exceeds maximum length (8192 characters)\n * @throws {TypeError} When fromState is provided and has any of the validation errors listed above for toState\n *\n * @example\n * // ✅ Valid calls\n * getTransitionPath({ name: 'users.profile', params: {}, path: '/users/profile' });\n * getTransitionPath(toState, fromState);\n * getTransitionPath({ name: '', params: {}, path: '/' }); // root route\n *\n * @example\n * // ❌ Invalid calls that throw TypeError\n * getTransitionPath(null);                                    // toState is null\n * getTransitionPath(undefined);                               // toState is undefined\n * getTransitionPath({});                                      // missing required fields\n * getTransitionPath({ name: 123, params: {}, path: '/' });    // name not a string\n * getTransitionPath({ name: 'home', path: '/' });             // missing params\n * getTransitionPath({ name: 'users..profile', params: {}, path: '/' }); // consecutive dots\n * getTransitionPath({ name: '.users', params: {}, path: '/' });         // leading dot\n * getTransitionPath({ name: 'users.', params: {}, path: '/' });         // trailing dot\n * getTransitionPath({ name: 'users profile', params: {}, path: '/' });  // contains space\n * getTransitionPath({ name: 'users.123', params: {}, path: '/' });      // segment starts with number\n * getTransitionPath(validToState, { name: 'invalid..route', params: {}, path: '/' }); // fromState invalid\n *\n * @example\n * // Full activation (no fromState)\n * getTransitionPath(makeState('users.profile'));\n * // Returns: {\n * //   intersection: '',\n * //   toActivate: ['users', 'users.profile'],\n * //   toDeactivate: []\n * // }\n *\n * @example\n * // Partial transition with common ancestor\n * getTransitionPath(\n *   makeState('users.profile'),\n *   makeState('users.list')\n * );\n * // Returns: {\n * //   intersection: 'users',\n * //   toActivate: ['users.profile'],\n * //   toDeactivate: ['users.list']\n * // }\n *\n * @example\n * // Complete route change\n * getTransitionPath(\n *   makeState('admin.dashboard'),\n *   makeState('users.profile')\n * );\n * // Returns: {\n * //   intersection: '',\n * //   toActivate: ['admin', 'admin.dashboard'],\n * //   toDeactivate: ['users.profile', 'users']\n * // }\n */\n// Single-entry cache: shouldUpdateNode calls getTransitionPath N times per\n// navigation with the same state objects (once per subscribed node).\n// Cache by reference eliminates N-1 redundant computations.\n// Module-global (≤2 State refs); not cleared on dispose — negligible, not per-router.\nlet cached1To: State | undefined;\nlet cached1From: State | undefined;\nlet cached1Result: TransitionPath | null = null;\n\nlet cached2To: State | undefined;\nlet cached2From: State | undefined;\nlet cached2Result: TransitionPath | null = null;\n\nfunction computeTransitionPath(\n  toState: State,\n  fromState: State | undefined,\n  getMeta: RouteMetaLookup,\n): TransitionPath {\n  // ===== FAST PATH 1: Initial navigation (no fromState) =====\n  // This is the best performing case in benchmarks (5M ops/sec)\n  if (!fromState) {\n    return {\n      intersection: EMPTY_INTERSECTION,\n      toActivate: nameToIDs(toState.name),\n      toDeactivate: FROZEN_EMPTY_ARRAY,\n    };\n  }\n\n  // ===== FAST PATH 3: Route name not in tree → full reload =====\n  // Ownership is read from the live matcher by `state.name` (RFC-4 M2 / #1548 —\n  // the per-State `stateMetaStore` WeakMap was removed). `getMeta` returns\n  // `undefined` only when the name is not in the tree — a CRUD-removed route.\n  const toMetaParams = getMeta(toState.name);\n  const fromMetaParams = getMeta(fromState.name);\n\n  if (!toMetaParams && !fromMetaParams) {\n    // FAST PATH 3 (both names gone from the tree — e.g. `replace()`d away, or a\n    // survivor state whose route was removed). Consumers read the result\n    // order-INSENSITIVELY, so the from-chain is returned as-is (root→leaf, no\n    // reverse needed): `shouldUpdateNode` reads `toDeactivate` by MEMBERSHIP\n    // (`.includes`). Any state whose name IS still in the tree — every navigate\n    // pipeline state, popstate/start, and `canNavigateTo`'s built toState — takes\n    // the STANDARD PATH below, which trims the shared ancestor and reverses\n    // correctly. (Pre-#1548 this branch keyed on a missing per-State WeakMap\n    // entry; it now keys on tree membership by name.)\n    return {\n      intersection: EMPTY_INTERSECTION,\n      toActivate: nameToIDs(toState.name),\n      toDeactivate: nameToIDs(fromState.name),\n    };\n  }\n\n  // ===== STANDARD PATH: Routes with parameters =====\n  const toStateIds = nameToIDs(toState.name);\n  const fromStateIds = nameToIDs(fromState.name);\n  // Stryker disable next-line MethodExpression: equivalent — Math.max reads one index past the shorter id array; that slot is undefined, so the `toSegment !== fromSegment` check in pointOfDifference returns the same divergence index Math.min would stop at.\n  const maxI = Math.min(fromStateIds.length, toStateIds.length);\n\n  const i = pointOfDifference(\n    (toMetaParams ?? fromMetaParams) as Record<string, unknown>,\n    toState,\n    fromState,\n    toStateIds,\n    fromStateIds,\n    maxI,\n  );\n\n  // Optimization: Build deactivation list in reverse order directly\n  // instead of slice(i).toReversed() which creates 2 arrays\n  let toDeactivate: string[];\n\n  if (i >= fromStateIds.length) {\n    toDeactivate = FROZEN_EMPTY_ARRAY;\n  } else if (i === 0 && fromStateIds.length === 1) {\n    // Single-segment route: reversed = original, reuse cached frozen array\n    toDeactivate = fromStateIds;\n  } else {\n    toDeactivate = [];\n\n    for (let j = fromStateIds.length - 1; j >= i; j--) {\n      toDeactivate.push(fromStateIds[j]);\n    }\n  }\n\n  // Build activation list — reuse cached frozen array when using full list\n  const toActivate = i === 0 ? toStateIds : toStateIds.slice(i);\n\n  // Determine intersection point (common ancestor)\n  const intersection = i > 0 ? fromStateIds[i - 1] : EMPTY_INTERSECTION;\n\n  return {\n    intersection,\n    toDeactivate,\n    toActivate,\n  };\n}\n\nexport function getTransitionPath(\n  toState: State,\n  fromState: State | undefined,\n  getMeta: RouteMetaLookup,\n): TransitionPath {\n  // Cache keys on (toState, fromState) identity only — `getMeta` is deterministic\n  // per route name and per-router (states are unique per router), so the same\n  // state pair always resolves the same meta, and the cache stays correct\n  // without keying on the callback (RFC-4 M2 / #1548).\n  // Stryker disable BlockStatement: equivalent — both cache short-circuits below; emptying either early-return recomputes the identical TransitionPath (computeTransitionPath is deterministic for the same to/from states) and re-caches it. Restored right after.\n  if (\n    cached1Result !== null &&\n    toState === cached1To &&\n    fromState === cached1From\n  ) {\n    return cached1Result;\n  }\n\n  if (\n    cached2Result !== null &&\n    toState === cached2To &&\n    fromState === cached2From\n  ) {\n    return cached2Result;\n  }\n  // Stryker restore BlockStatement\n\n  const result = computeTransitionPath(toState, fromState, getMeta);\n\n  cached2To = cached1To;\n  cached2From = cached1From;\n  cached2Result = cached1Result;\n\n  cached1To = toState;\n  cached1From = fromState;\n  cached1Result = result;\n\n  return result;\n}\n"],"mappings":"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"}

package/dist/cjs/types/RouterValidator.d.ts

@@ -93,6 +93,20 @@ interface RouterValidator {
   state: {
     validateMakeStateArgs: (name: unknown, params: unknown, path: unknown) => void;
     validateAreStatesEqualArgs: (s1: unknown, s2: unknown, ignoreQP: unknown) => void;
+    /**
+     * The mode gate's opt-in diagnostic (#1575). Core DROPS a query key the
+     * active `queryParamsMode` will not print — silently, by the same
+     * always-on-fixes / opt-in-diagnoses split the channel guard follows. This
+     * hook is what makes the drop visible in development.
+     *
+     * Called once per dropped key, from the gate itself, so the report cannot
+     * disagree with what was actually dropped. A `defaultSearch` declared for
+     * such a key surfaces through the same call — it is dead config in these
+     * modes, and that is the edge worth naming out loud.
+     */
+    reportDroppedQueryKey: (routeName: string, key: string) => void;
+    /** Opt-in diagnostic for a key the route declares NOWHERE (#1579). */
+    reportUndeclaredParamKey: (routeName: string, key: string) => void;
   };
   /**
    * Event bus validation methods

package/dist/cjs/types/RouterValidator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RouterValidator.d.ts","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"}
+{"version":3,"file":"RouterValidator.d.ts","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;;;;;;;;;;;;IAaF,wBAAwB,mBAAmB;;IAG3C,2BAA2B,mBAAmB;;;;;EAMhD;IACE,uBAAuB,eAAe;IACtC,0BACE,eACA,mBACA"}

package/dist/cjs/types/api.d.ts

@@ -1,6 +1,5 @@
-import { RouteTreeState } from "./route-node-types.js";
-import { Params, SimpleState, State, StateMetaInput, Unsubscribe } from "./base.js";
-import { DefaultDependencies, GuardFnFactory, Options, Plugin, Route, RouteConfigUpdate } from "./router.js";
+import { Params, SearchParams, SimpleState, State, Unsubscribe } from "./base.js";
+import { AnyOptions, DefaultDependencies, GuardFnFactory, Plugin, Route, RouteConfigUpdate } from "./router.js";
 import { EventMethodMap, EventName } from "./constants.js";
 import { TreeChangedEvent } from "./tree-changed.js";
 import { NavigationOptions, StateContext } from "../types.js";
@@ -11,14 +10,14 @@ import { NavigationOptions, StateContext } from "../types.js";
  *
  * To add a new interceptable method:
  * 1. Add its signature here
- * 2. Wrap it with `createInterceptable()` / `createBinaryInterceptable()` in
+ * 2. Wrap it with `createInterceptable()` / `createTernaryInterceptable()` 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;
+  buildPath: (route: string, params?: Params, search?: SearchParams) => string;
+  forwardState: (routeName: string, routeParams: Params, routeSearch?: SearchParams) => SimpleState;
 }
 /**
  * Type-safe interceptor callback.
@@ -69,9 +68,8 @@ interface ContextNamespaceClaim<T = unknown> {
  * 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>;
+  makeState: <P extends Params = Params, S extends SearchParams = SearchParams>(name: string, params?: P, search?: S, path?: string) => State<P, S>;
+  forwardState: <P extends Params = Params, S extends SearchParams = SearchParams>(routeName: string, routeParams: P, routeSearch?: S) => SimpleState<P, S>;
   matchPath: <P extends Params = Params>(path: string) => State<P> | undefined;
   /**
    * Navigate to a fully-built `State`, skipping the redundant
@@ -97,8 +95,19 @@ interface PluginApi {
   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;
+  /**
+   * Builds the State `navigate` would commit, without committing it: resolves
+   * `forwardTo`, checks existence (`undefined` = unknown route) and merges the
+   * route defaults.
+   *
+   * `search` is the query channel (#1571). It was the ONE pipeline entry point
+   * without the slot — `navigate` / `buildPath` / `canNavigateTo` /
+   * `isActiveRoute` / `makeState` all take one — so a query intent could only
+   * be spelled by riding declared keys in the `params` bag. An explicit value
+   * beats such a twin, matching the other five.
+   */
+  buildNavigationState: (name: string, params?: Params, search?: SearchParams) => State | undefined;
+  getOptions: () => AnyOptions;
   getTree: () => unknown;
   addInterceptor: <M extends keyof InterceptableMethodMap>(method: M, fn: InterceptorFn<M>) => Unsubscribe;
   extendRouter: (extensions: Record<string, unknown>) => Unsubscribe;

package/dist/cjs/types/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","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"}
+{"version":3,"file":"api.d.ts","names":[],"sources":["../../../src/types/api.ts"],"mappings":";;;;;;;;;;;;;;;;UAoCiB;EACf,QAAQ,kBAAkB,QAAQ;EAClC,YAAY,eAAe,SAAS,QAAQ,SAAS;EACrD,eACE,mBACA,aAAa,QACb,cAAc,iBACX;;;;;;KAOK,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,QAAQ,UAAU,eAAe,cAC9D,cACA,SAAS,GACT,SAAS,GACT,kBACG,MAAM,GAAG;EAEd,eACE,UAAU,SAAS,QACnB,UAAU,eAAe,cAEzB,mBACA,aAAa,GACb,cAAc,MACX,YAAY,GAAG;EAEpB,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;;;;;;;;;;;;EAaL,uBACE,cACA,SAAS,QACT,SAAS,iBACN;EAEL,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/cjs/types/base.d.ts

@@ -10,9 +10,15 @@ import { StateContext } from "../types.js";
  * has no additional effect after the first call.
  */
 type Unsubscribe = () => void;
-interface SimpleState<P extends Params = Params> {
+interface SimpleState<P extends Params = Params, S extends SearchParams = SearchParams> {
   name: string;
   params: P;
+  /**
+   * Query channel — see {@link SearchParams}. Split out of the former single
+   * `params` bag (RFC-4 M2 / #1548). Always present: a frozen empty object when
+   * there are no query params.
+   */
+  search: S;
 }
 type TransitionPhase = "deactivating" | "activating";
 type TransitionReason = "success" | "blocked" | "cancelled" | "error";
@@ -30,9 +36,15 @@ interface TransitionMeta {
     intersection: string;
   };
 }
-interface State<P extends Params = Params> {
+interface State<P extends Params = Params, S extends SearchParams = SearchParams> {
   name: string;
   params: P;
+  /**
+   * Query channel — see {@link SearchParams}. Holds ONLY query-string params;
+   * path params live in {@link State.params} (RFC-4 M2 / #1548). Always present:
+   * a frozen empty object when there are no query params.
+   */
+  search: S;
   path: string;
   transition: TransitionMeta;
   /**
@@ -57,8 +69,36 @@ interface State<P extends Params = Params> {
    */
   context: StateContext & Record<string, unknown>;
 }
-interface StateMetaInput<P extends Params = Params> {
+/**
+ * Descriptor form of a navigation target (RFC-4 M2 / #1548). The two-channel
+ * counterpart to the positional `navigate(name, params, search, opts)` form:
+ * `params` is the path channel, `search` the query channel. Passed as the first
+ * argument to `router.navigate(target, opts?)` / `router.buildPath(target)` /
+ * `router.isActiveRoute(target)` and as the `to` prop of framework `<Link>`s,
+ * so a target can be threaded as one value instead of positional arguments.
+ */
+interface NavigationTarget<P extends Params = Params, S extends SearchParams = SearchParams> {
+  name: string;
+  params?: P;
+  search?: S;
+}
+/**
+ * The two navigation channels a per-route codec operates on (RFC-4 M2 / #1548):
+ * `params` is the path channel, `search` the query channel. Used as **both** the
+ * input and the output of {@link Route.encodeParams} / {@link Route.decodeParams}
+ * — a codec transforms whichever channel(s) it owns and returns the other channel
+ * unchanged (it must be passed through explicitly).
+ *
+ * @remarks
+ * v1 ran the whole (path + query) bag through both callbacks, so a query value
+ * reached `decodeParams`. This two-channel shape preserves that reach: the query
+ * arrives in `search` rather than merged into `params`. Value semantics are
+ * unchanged — only the storage location differs (M2 keeps query parsing/printing
+ * exactly as v1).
+ */
+interface ParamsSearch<P extends Params = Params, S extends SearchParams = SearchParams> {
   params: P;
+  search: S;
 }
 /**
  * Parsed shape produced by `serializeRouterState()` (`@real-router/ssr-utils`,
@@ -90,6 +130,25 @@ interface RouterError extends Error {
 interface Params {
   [key: string]: string | string[] | number | number[] | boolean | boolean[] | Params | Params[] | Record<string, string | number | boolean> | null | undefined;
 }
+/**
+ * Query-parameter primitive values. Mirrors the engine's `QueryParamPrimitive`
+ * (`engine/search-params/types.ts`) — the value form is identical to v1's query
+ * half (the union produced across `queryParamsMode` formats).
+ */
+type SearchParamPrimitive = string | number | boolean | null;
+/**
+ * A single query-parameter value — a primitive or an array of primitives.
+ */
+type SearchParamValue = SearchParamPrimitive | SearchParamPrimitive[];
+/**
+ * Query-parameter bag carried by {@link State.search} — the query channel,
+ * split out of the former single `params` bag in M2 (RFC-4 M2 / #1548). Only
+ * the storage location changes vs v1; value semantics (modes, `queryParamsMode`,
+ * ternary arrays) are unchanged. Structurally matches the engine's internal
+ * `SearchParams` (`engine/search-params/types.ts`), so match results flow into
+ * `State.search` without conversion.
+ */
+type SearchParams = Record<string, SearchParamValue | undefined>;
 //#endregion
-export { Params, RouterError, SerializedRouterState, SimpleState, State, StateMetaInput, TransitionMeta, TransitionPhase, TransitionReason, Unsubscribe };
+export { NavigationTarget, Params, ParamsSearch, RouterError, SearchParamPrimitive, SearchParamValue, SearchParams, SerializedRouterState, SimpleState, State, TransitionMeta, TransitionPhase, TransitionReason, Unsubscribe };
 //# sourceMappingURL=base.d.ts.map

package/dist/cjs/types/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","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;;;;;;;;;;KAWE,sBAAsB,UAAU,SAAS,UAAU,KAC7D,MAAM;;;;;;;UAUS,oBAAoB;GAClC;WACQ;WACA;WACA;EACT,UAAU;EACV,mBAAmB,KAAK;EACxB,sBAAsB,QAAQ;EAC9B,WAAW;EACX,WAAW;EACX,cAAc;;UAGC;GACd,4EAOG,SACA,WACA"}
+{"version":3,"file":"base.d.ts","names":[],"sources":["../../../src/types/base.ts"],"mappings":";;;;;;;;;;;KAmBY;UAEK,YACf,UAAU,SAAS,QACnB,UAAU,eAAe;EAEzB;EACA,QAAQ;;;;;;EAMR,QAAQ;;KAGE;KAEA;UAEK;EACf,OAAO;EACP,QAAQ;EACR;EACA;EACA;EACA;EACA;EACA;IACE;IACA;IACA;;;UAIa,MACf,UAAU,SAAS,QACnB,UAAU,eAAe;EAEzB;EACA,QAAQ;;;;;;EAMR,QAAQ;EACR;EACA,YAAY;;;;;;;;;;;;;;;;;;;;;EAqBZ,SAAS,eAAe;;;;;;;;;;UAWT,iBACf,UAAU,SAAS,QACnB,UAAU,eAAe;EAEzB;EACA,SAAS;EACT,SAAS;;;;;;;;;;;;;;;;UAiBM,aACf,UAAU,SAAS,QACnB,UAAU,eAAe;EAEzB,QAAQ;EACR,QAAQ;;;;;;;;;;KAWE,sBAAsB,UAAU,SAAS,UAAU,KAC7D,MAAM;;;;;;;UAUS,oBAAoB;GAClC;WACQ;WACA;WACA;EACT,UAAU;EACV,mBAAmB,KAAK;EACxB,sBAAsB,QAAQ;EAC9B,WAAW;EACX,WAAW;EACX,cAAc;;UAGC;GACd,4EAOG,SACA,WACA;;;;;;;KAUM;;;;KAKA,mBAAmB,uBAAuB;;;;;;;;;KAU1C,eAAe,eAAe"}

package/dist/cjs/types/constants.d.ts

@@ -66,6 +66,7 @@ interface ErrorCodeToValueMap {
   CONTEXT_NAMESPACE_ALREADY_CLAIMED: "CONTEXT_NAMESPACE_ALREADY_CLAIMED";
   REENTRANT_NAVIGATION: "REENTRANT_NAVIGATION";
   REENTRANT_TREE_MUTATION: "REENTRANT_TREE_MUTATION";
+  WRONG_CHANNEL: "WRONG_CHANNEL";
 }
 //#endregion
 export { ErrorCodeKeys, ErrorCodeToValueMap, ErrorCodeValues, EventMethodMap, EventName, EventToNameMap, EventToPluginMap, EventsKeys, PluginMethod };

package/dist/cjs/types/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","names":[],"sources":["../../../src/types/constants.ts"],"mappings":";;;;KAGY;;;;KAYA;;;;KAYA;;;;KAYA;;;;KAiBA;;;;UAmBK;WACN;WACA;WACA;WACA;WACA;WACA;WACA;;;;;UAMM;EACf;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;KAOU,oBACT,KAAK,cAAc,eAAe,KAAK,iBAAiB;;;;UAM1C;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA"}
+{"version":3,"file":"constants.d.ts","names":[],"sources":["../../../src/types/constants.ts"],"mappings":";;;;KAGY;;;;KAYA;;;;KAYA;;;;KAYA;;;;KAiBA;;;;UAmBK;WACN;WACA;WACA;WACA;WACA;WACA;WACA;;;;;UAMM;EACf;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;KAOU,oBACT,KAAK,cAAc,eAAe,KAAK,iBAAiB;;;;UAM1C;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA"}