@real-router/core 0.46.0 → 0.48.0

package/src/api/getRoutesApi.ts

@@ -28,6 +28,7 @@ import type {
   ForwardToCallback,
   Params,
   Router,
+  TransitionMeta,
 } from "@real-router/types";
 import type { RouteDefinition, RouteTree } from "route-tree";
 
@@ -250,6 +251,7 @@ function replaceRoutes<
   routes: Route<Dependencies>[],
   ctx: RouterInternals<Dependencies>,
   currentPath: string | undefined,
+  previousTransition: TransitionMeta | undefined,
 ): void {
   // Step 2: Clear route data (WITHOUT tree rebuild)
   clearRouteData(store);
@@ -276,12 +278,16 @@ function replaceRoutes<
   // Step 5: One tree rebuild
   store.treeOperations.commitTreeChanges(store);
 
-  // Step 6: Revalidate state
+  // Step 6: Revalidate state (preserve transition from previous state)
   if (currentPath !== undefined) {
     const revalidated = ctx.matchPath(currentPath, ctx.getOptions());
 
     if (revalidated) {
-      ctx.setState(revalidated);
+      ctx.setState({
+        ...revalidated,
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- previousTransition is guaranteed defined: currentPath is only set when getState() returned a state, which always has transition
+        transition: previousTransition!,
+      });
     } else {
       ctx.clearState();
     }
@@ -565,9 +571,15 @@ export function getRoutesApi<
       ctx.validator?.routes.validateAddRouteArgs(routeArray);
       ctx.validator?.routes.validateRoutes(routeArray, store);
 
-      const currentPath = router.getState()?.path;
+      const currentState = router.getState();
 
-      replaceRoutes(store, routeArray, ctx, currentPath);
+      replaceRoutes(
+        store,
+        routeArray,
+        ctx,
+        currentState?.path,
+        currentState?.transition,
+      );
     },
   };
 }

package/src/constants.ts

@@ -6,6 +6,7 @@ import type {
   ErrorCodeToValueMap,
   ErrorCodeKeys,
   ErrorCodeValues,
+  TransitionMeta,
 } from "@real-router/types";
 
 export type ConstantsKeys = "UNKNOWN_ROUTE";
@@ -35,6 +36,7 @@ export const errorCodes: ErrorCodeToValueMap = Object.freeze({
   TRANSITION_CANCELLED: "CANCELLED", // Navigation cancelled by user or new navigation
   ROUTER_DISPOSED: "DISPOSED", // Router has been disposed
   PLUGIN_CONFLICT: "PLUGIN_CONFLICT", // Plugin tried to extend router with already-existing property
+  CONTEXT_NAMESPACE_ALREADY_CLAIMED: "CONTEXT_NAMESPACE_ALREADY_CLAIMED", // Plugin tried to claim a context namespace already owned by another plugin
 });
 
 /**
@@ -85,3 +87,15 @@ export const DEFAULT_LIMITS = {
 } as const;
 
 export const EMPTY_PARAMS: Readonly<Record<string, never>> = Object.freeze({});
+
+const FROZEN_EMPTY_SEGMENTS = Object.freeze({
+  deactivated: Object.freeze([]) as unknown as string[],
+  activated: Object.freeze([]) as unknown as string[],
+  intersection: "",
+});
+
+export const DEFAULT_TRANSITION = Object.freeze({
+  phase: "activating",
+  reason: "success",
+  segments: FROZEN_EMPTY_SEGMENTS,
+}) as TransitionMeta;

package/src/helpers.ts

@@ -109,65 +109,30 @@ export function deepFreezeState<T extends State>(state: T): T {
   return clonedState;
 }
 
-// WeakSet to track already frozen root objects for O(1) re-freeze check
-const frozenRoots = new WeakSet<object>();
-
-// Module-scope recursive freeze function - better JIT optimization, no allocation per call
-function freezeRecursive(obj: unknown): void {
-  // Skip primitives, null
-  if (obj === null || typeof obj !== "object") {
-    return;
-  }
-
-  // Skip already frozen objects (handles potential shared refs)
-  if (Object.isFrozen(obj)) {
-    return;
-  }
-
-  // Freeze the object/array
-  Object.freeze(obj);
-
-  // Iterate without Object.values() allocation
-  if (Array.isArray(obj)) {
-    for (const item of obj) {
-      freezeRecursive(item);
-    }
-  } else {
-    for (const key in obj) {
-      freezeRecursive((obj as Record<string, unknown>)[key]);
-    }
-  }
-}
-
 /**
- * Freezes State object in-place without cloning.
- * Optimized for hot paths where state is known to be a fresh object.
+ * Shallow-freezes a State object in place.
+ *
+ * Freezes only the top-level State object (blocks reassignment of `name`,
+ * `params`, `path`, `transition`, `context`). Nested objects (`params`,
+ * `transition`, `transition.segments`, `transition.segments.{deactivated,activated}`)
+ * are expected to be **already frozen at creation time** by their producers:
+ *
+ * - `params` frozen in `makeState()` / `navigateToNotFound()`
+ * - `transition`, `segments`, `deactivated`, `activated` frozen in
+ *   `buildTransitionMeta()` (or inline in `navigateToNotFound()`)
  *
- * IMPORTANT: Only use this when you know the state is a fresh object
- * that hasn't been exposed to external code yet (e.g., from makeState()).
+ * `state.context` is **intentionally not frozen** — plugins write to it via
+ * `claim.write(state, value)` after state creation.
  *
- * @param state - The State object to freeze (must be a fresh object)
- * @returns The same state object, now frozen
  * @internal
  */
 export function freezeStateInPlace<T extends State>(state: T): T {
-  // Early return for null/undefined - state from makeState() is never null
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- defensive guard against external misuse
   if (!state) {
     return state;
   }
 
-  // Fast path: already processed root object - O(1) check
-  if (frozenRoots.has(state)) {
-    return state;
-  }
-
-  freezeRecursive(state);
-
-  // Mark root as processed for future calls
-  frozenRoots.add(state);
-
-  return state;
+  return Object.freeze(state);
 }
 
 /**

package/src/internals.ts

@@ -90,6 +90,7 @@ export interface RouterInternals<
   readonly clearState: () => void;
   readonly setState: (state: State) => void;
   readonly routerExtensions: { keys: string[] }[];
+  readonly contextClaimRecords: Set<string>;
 }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- existential type: stores RouterInternals for all Dependencies types

package/src/namespaces/NavigationNamespace/NavigationNamespace.ts

@@ -10,7 +10,7 @@ import {
 import { completeTransition } from "./transition/completeTransition";
 import { routeTransitionError } from "./transition/errorHandling";
 import { executeGuardPipeline } from "./transition/guardPhase";
-import { errorCodes, constants } from "../../constants";
+import { EMPTY_PARAMS, errorCodes, constants } from "../../constants";
 import { RouterError } from "../../RouterError";
 import { getTransitionPath, nameToIDs } from "../../transitionPath";
 
@@ -310,9 +310,10 @@ export class NavigationNamespace {
 
     const state: State = {
       name: constants.UNKNOWN_ROUTE,
-      params: {} as Params,
+      params: EMPTY_PARAMS as Params,
       path,
       transition: transitionMeta,
+      context: {},
     };
 
     Object.freeze(state);

package/src/namespaces/NavigationNamespace/transition/completeTransition.ts

@@ -1,5 +1,4 @@
 import { errorCodes, constants } from "../../../constants";
-import { freezeStateInPlace } from "../../../helpers";
 import { RouterError } from "../../../RouterError";
 
 import type { NavigationDependencies, NavigationContext } from "../types";
@@ -20,14 +19,19 @@ function buildTransitionMeta(
   toActivate: string[],
   intersection: string,
 ): TransitionMeta {
+  Object.freeze(toDeactivate);
+  Object.freeze(toActivate);
+
+  const segments = Object.freeze({
+    deactivated: toDeactivate,
+    activated: toActivate,
+    intersection,
+  });
+
   const meta: MutableTransitionMeta = {
     phase: "activating",
     reason: "success",
-    segments: {
-      deactivated: toDeactivate,
-      activated: toActivate,
-      intersection,
-    },
+    segments,
   };
 
   if (fromState?.name !== undefined) {
@@ -42,7 +46,7 @@ function buildTransitionMeta(
     meta.redirected = opts.redirected;
   }
 
-  return meta;
+  return Object.freeze(meta);
 }
 
 function stripSignal({
@@ -88,7 +92,7 @@ export function completeTransition(
     intersection,
   );
 
-  const finalState = freezeStateInPlace(toState);
+  const finalState = Object.freeze(toState);
 
   deps.setState(finalState);
 

package/src/namespaces/RoutesNamespace/RoutesNamespace.ts

@@ -7,7 +7,7 @@ import {
   rebuildTreeInPlace,
   resetStore,
 } from "./routesStore";
-import { constants } from "../../constants";
+import { constants, DEFAULT_TRANSITION } from "../../constants";
 import { getTransitionPath } from "../../transitionPath";
 
 import type { RoutesStore } from "./routesStore";
@@ -107,7 +107,7 @@ export class RoutesNamespace<
         );
       }
 
-      if (toState.transition?.reload) {
+      if (toState.transition.reload) {
         return true;
       }
 
@@ -403,6 +403,8 @@ export class RoutesNamespace<
         name,
         params: effectiveParams,
         path: "",
+        transition: DEFAULT_TRANSITION,
+        context: {},
       };
 
       return this.#deps.areStatesEqual(

package/src/namespaces/StateNamespace/StateNamespace.ts

@@ -1,7 +1,7 @@
 // packages/core/src/namespaces/StateNamespace/StateNamespace.ts
 
 import { areParamValuesEqual } from "./helpers";
-import { EMPTY_PARAMS } from "../../constants";
+import { DEFAULT_TRANSITION, EMPTY_PARAMS } from "../../constants";
 import { freezeStateInPlace } from "../../helpers";
 import { setStateMetaParams } from "../../stateMetaStore";
 
@@ -97,7 +97,15 @@ export class StateNamespace {
   // =========================================================================
 
   /**
-   * Creates a frozen state object for a route.
+   * Creates a state object for a route.
+   *
+   * `params` is frozen at creation so it is always immutable, even when
+   * `skipFreeze=true` is passed to defer the outer `Object.freeze(state)` call.
+   * This keeps params-freezing invariants independent of transition-pipeline
+   * mutation (e.g. `completeTransition` attaching `state.transition`).
+   *
+   * `context` is initialized as a fresh empty object — intentionally NOT frozen
+   * so plugins can publish data via `claim.write(state, value)` after creation.
    */
   makeState<P extends Params = Params>(
     name: string,
@@ -114,18 +122,23 @@ export class StateNamespace {
     let mergedParams: P;
 
     if (hasDefaultParams) {
-      mergedParams = { ...defaultParamsConfig[name], ...params } as P;
+      mergedParams = Object.freeze({
+        ...defaultParamsConfig[name],
+        ...params,
+      }) as P;
     } else if (!params || params === EMPTY_PARAMS) {
       mergedParams = EMPTY_PARAMS as P;
     } else {
-      mergedParams = { ...params };
+      mergedParams = Object.freeze({ ...params }) as P;
     }
 
-    const state: State<P> = {
+    const state = {
       name,
       params: mergedParams,
       path: path ?? this.#deps.buildPath(name, params),
-    };
+      context: {},
+      ...(!skipFreeze && { transition: DEFAULT_TRANSITION }),
+    } as State<P>;
 
     if (meta) {
       setStateMetaParams(state, meta as unknown as Params);