@real-router/core 0.54.3 → 0.54.4

package/dist/cjs/api.d.ts

@@ -20,6 +20,69 @@ declare function getDependenciesApi<Dependencies extends DefaultDependencies = D
 declare function getLifecycleApi<Dependencies extends DefaultDependencies = DefaultDependencies>(router: Router<Dependencies>): LifecycleApi<Dependencies>;
 //#endregion
 //#region src/api/cloneRouter.d.ts
+/**
+ * Build an independent router instance that shares the route tree, options,
+ * lifecycle guards, and plugin factories of `router`. The primary use case
+ * is **SSR multi-tenancy** — one base router per process, one clone per
+ * request.
+ *
+ * @param router - Source router (must not be disposed).
+ * @param dependencies - Optional per-clone overrides merged on top of the
+ *   base router's dependencies. Always **fresh per call** in the documented
+ *   SSR pattern: pass per-request state here, never store it in the base.
+ *
+ * @remarks
+ *
+ * **Dependency merge — shallow by design.** `base.dependencies` are spread
+ * into the clone via `{ ...sourceDeps, ...dependencies }`. Top-level keys
+ * are new objects, but **values are shared by reference**: a `Map`, `Set`,
+ * class instance, function, or nested plain object stored in
+ * `base.dependencies` is the **same instance** in every clone. Mutations
+ * in one clone are visible in the base and in every sibling clone.
+ *
+ * This is intentional. `structuredClone` of dep values is **not** applied
+ * because it would:
+ * - strip class prototypes (`new DbClient()` → plain object, methods lost)
+ * - reject functions and symbols (`DataCloneError`)
+ * - fragment singleton pools (one connection pool per request — pool
+ *   semantics destroyed)
+ * - reject circular references
+ *
+ * **SSR rule of thumb.** Place values in `base.dependencies` according to
+ * their lifecycle:
+ *
+ * - **Singletons / shared services** → `base.dependencies`. Examples: DB
+ *   client, connection pool, logger, config, feature-flag client. Process-
+ *   wide pooling depends on sharing these by reference.
+ * - **Per-request state** → the `dependencies` override parameter (or
+ *   `createRequestScope`'s `deps` argument). Examples: `currentUser`,
+ *   `traceId`, `sessionId`, `abortSignal`. The override is applied last,
+ *   so it wins over base keys; pass a fresh object per call.
+ *
+ * Cross-request data leaks are **only possible** when per-request mutable
+ * state is incorrectly placed in `base.dependencies`. The override slot is
+ * the safe channel.
+ *
+ * @example
+ * ```typescript
+ * // Server boot — singletons only
+ * const base = createRouter(routes, options, {
+ *   db: new DbClient(dbUrl),
+ *   logger,
+ * });
+ *
+ * // Per request — fresh override per call
+ * const clone = cloneRouter(base, {
+ *   currentUser,
+ *   traceId,
+ * });
+ * // clone.deps.db === base.deps.db  ✓ shared pool (intentional)
+ * // clone.deps.currentUser          ✓ unique per request
+ * ```
+ *
+ * @see createRequestScope — `@real-router/core/utils` SSR helper that
+ *   wraps this function and injects `abortSignal` automatically.
+ */
 declare function cloneRouter<Dependencies extends DefaultDependencies = DefaultDependencies>(router: Router<Dependencies>, dependencies?: Dependencies): Router$1<Dependencies>;
 //#endregion
 export { type DependenciesApi, type LifecycleApi, type PluginApi, type RoutesApi, cloneRouter, getDependenciesApi, getLifecycleApi, getPluginApi, getRoutesApi };

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

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","names":[],"sources":["../../src/api/types.ts","../../src/api/getPluginApi.ts","../../src/api/getRoutesApi.ts","../../src/api/getDependenciesApi.ts","../../src/api/getLifecycleApi.ts","../../src/api/cloneRouter.ts"],"mappings":";;;;;UAGiB,SAAA,SAAkB,IAAA,CAAK,WAAA;EACtC,OAAA,QAAe,SAAA;AAAA;;;iBCkBD,YAAA,sBACO,mBAAA,GAAsB,mBAAA,CAAA,CAC3C,MAAA,EAAQ,MAAA,CAAO,YAAA,IAAgB,SAAA;;;iBCgYjB,YAAA,sBACO,mBAAA,GAAsB,mBAAA,CAAA,CAC3C,MAAA,EAAQ,MAAA,CAAO,YAAA,IAAgB,SAAA,CAAU,YAAA;;;iBCzU3B,kBAAA,sBACO,mBAAA,GAAsB,mBAAA,CAAA,CAC3C,MAAA,EAAQ,MAAA,CAAO,YAAA,IAAgB,eAAA,CAAgB,YAAA;;;iBC7EjC,eAAA,sBACO,mBAAA,GAAsB,mBAAA,CAAA,CAC3C,MAAA,EAAQ,MAAA,CAAO,YAAA,IAAgB,YAAA,CAAa,YAAA;;;iBCG9B,WAAA,sBACO,mBAAA,GAAsB,mBAAA,CAAA,CAE3C,MAAA,EAAQ,MAAA,CAAO,YAAA,GACf,YAAA,GAAe,YAAA,GACd,QAAA,CAAY,YAAA"}
+{"version":3,"file":"api.d.ts","names":[],"sources":["../../src/api/types.ts","../../src/api/getPluginApi.ts","../../src/api/getRoutesApi.ts","../../src/api/getDependenciesApi.ts","../../src/api/getLifecycleApi.ts","../../src/api/cloneRouter.ts"],"mappings":";;;;;UAGiB,SAAA,SAAkB,IAAA,CAAK,WAAA;EACtC,OAAA,QAAe,SAAA;AAAA;;;iBCkBD,YAAA,sBACO,mBAAA,GAAsB,mBAAA,CAAA,CAC3C,MAAA,EAAQ,MAAA,CAAO,YAAA,IAAgB,SAAA;;;iBCgYjB,YAAA,sBACO,mBAAA,GAAsB,mBAAA,CAAA,CAC3C,MAAA,EAAQ,MAAA,CAAO,YAAA,IAAgB,SAAA,CAAU,YAAA;;;iBCzU3B,kBAAA,sBACO,mBAAA,GAAsB,mBAAA,CAAA,CAC3C,MAAA,EAAQ,MAAA,CAAO,YAAA,IAAgB,eAAA,CAAgB,YAAA;;;iBC7EjC,eAAA,sBACO,mBAAA,GAAsB,mBAAA,CAAA,CAC3C,MAAA,EAAQ,MAAA,CAAO,YAAA,IAAgB,YAAA,CAAa,YAAA;;;;;;AJL9C;;;;;;;;;;;;;AAC0B;;;;ACkB1B;;;;;;;;;;;;;;;;;;AAE0C;;;;ACgY1C;;;;;;;;;;;;;;;;;;;;AAEuD;iBGhVvC,WAAA,sBACO,mBAAA,GAAsB,mBAAA,CAAA,CAE3C,MAAA,EAAQ,MAAA,CAAO,YAAA,GACf,YAAA,GAAe,YAAA,GACd,QAAA,CAAY,YAAA"}

package/dist/cjs/cloneRouter-CR7rdWPl.js.map

@@ -1 +1 @@
-{"version":3,"file":"cloneRouter-CR7rdWPl.js","names":["RouterError","errorCodes","getInternals","RouterError","errorCodes","getInternals","getInternals","RouterError","errorCodes","routeTreeToDefinitions","RouterClass"],"sources":["../../src/api/helpers.ts","../../src/api/getPluginApi.ts","../../src/api/getLifecycleApi.ts","../../src/api/cloneRouter.ts"],"sourcesContent":["// packages/core/src/api/helpers.ts\n\nimport { errorCodes } from \"../constants\";\nimport { RouterError } from \"../RouterError\";\n\nexport function throwIfDisposed(isDisposed: () => boolean): void {\n  if (isDisposed()) {\n    throw new RouterError(errorCodes.ROUTER_DISPOSED);\n  }\n}\n","import { throwIfDisposed } from \"./helpers\";\nimport { errorCodes } from \"../constants\";\nimport { getInternals } from \"../internals\";\nimport { RouterError } from \"../RouterError\";\n\nimport type { PluginApi } from \"./types\";\nimport type {\n  ContextNamespaceClaim,\n  DefaultDependencies,\n  Params,\n  Router,\n  State,\n} from \"@real-router/types\";\n\n// Cache the assembled PluginApi per router — mirrors getNavigator() (#525):\n// avoids re-allocating the closure-bag on each call (plugins call this once\n// at init, but tests + nested plugins poll it), and gives spy/stub helpers\n// a stable object identity to attach to (e.g. spying on\n// `getPluginApi(router).navigateToState` to inject errors in popstate\n// recovery tests).\nconst cache = new WeakMap<object, PluginApi>();\n\nexport function getPluginApi<\n  Dependencies extends DefaultDependencies = DefaultDependencies,\n>(router: Router<Dependencies>): PluginApi {\n  const cached = cache.get(router);\n\n  if (cached) {\n    return cached;\n  }\n\n  const ctx = getInternals(router);\n  const api: PluginApi = {\n    makeState: (name, params, path, meta) => {\n      ctx.validator?.state.validateMakeStateArgs(name, params, path);\n\n      return ctx.makeState(\n        name,\n        params,\n        path,\n        meta?.params as\n          | Record<string, Record<string, \"url\" | \"query\">>\n          | undefined,\n      );\n    },\n    buildState: (routeName, routeParams) => {\n      ctx.validator?.routes.validateStateBuilderArgs(\n        routeName,\n        routeParams,\n        \"buildState\",\n      );\n\n      const { name, params } = ctx.forwardState(routeName, routeParams);\n\n      return ctx.buildStateResolved(name, params);\n    },\n    forwardState: <P extends Params = Params>(\n      routeName: string,\n      routeParams: P,\n    ) => {\n      ctx.validator?.routes.validateStateBuilderArgs(\n        routeName,\n        routeParams,\n        \"forwardState\",\n      );\n\n      return ctx.forwardState(routeName, routeParams);\n    },\n    matchPath: (path) => {\n      ctx.validator?.routes.validateMatchPathArgs(path);\n\n      return ctx.matchPath(path, ctx.getOptions());\n    },\n    navigateToState: (state, options) => {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.navigation.validateNavigateToStateArgs(state);\n\n      if (options !== undefined) {\n        ctx.validator?.navigation.validateNavigationOptions(\n          options,\n          \"navigateToState\",\n        );\n      }\n\n      return ctx.navigateToState(state, options);\n    },\n    setRootPath: (rootPath) => {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.routes.validateSetRootPathArgs(rootPath);\n\n      ctx.setRootPath(rootPath);\n    },\n    getRootPath: ctx.getRootPath,\n    addEventListener: (eventName, cb) => {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.eventBus.validateListenerArgs(eventName, cb);\n\n      return ctx.addEventListener(eventName, cb);\n    },\n    buildNavigationState: (name, params = {}) => {\n      ctx.validator?.routes.validateStateBuilderArgs(\n        name,\n        params,\n        \"buildNavigationState\",\n      );\n\n      const { name: resolvedName, params: resolvedParams } = ctx.forwardState(\n        name,\n        params,\n      );\n      const routeInfo = ctx.buildStateResolved(resolvedName, resolvedParams);\n\n      if (!routeInfo) {\n        return;\n      }\n\n      return ctx.makeState(\n        routeInfo.name,\n        routeInfo.params,\n        ctx.buildPath(routeInfo.name, routeInfo.params),\n        routeInfo.meta,\n      );\n    },\n    getOptions: ctx.getOptions,\n    getTree: ctx.getTree,\n    addInterceptor: (method, fn) => {\n      throwIfDisposed(ctx.isDisposed);\n      ctx.validator?.plugins.validateAddInterceptorArgs(method, fn);\n      let list = ctx.interceptors.get(method);\n\n      if (!list) {\n        list = [];\n        ctx.interceptors.set(method, list);\n      }\n\n      list.push(fn);\n\n      return () => {\n        const index = list.indexOf(fn);\n\n        if (index !== -1) {\n          list.splice(index, 1);\n        }\n      };\n    },\n    getRouteConfig: (name) => {\n      const store = ctx.routeGetStore();\n\n      if (!store.matcher.hasRoute(name)) {\n        return;\n      }\n\n      return store.routeCustomFields[name];\n    },\n    extendRouter: (extensions: Record<string, unknown>) => {\n      throwIfDisposed(ctx.isDisposed);\n\n      const keys = Object.keys(extensions);\n\n      for (const key of keys) {\n        if (key in router) {\n          throw new RouterError(errorCodes.PLUGIN_CONFLICT, {\n            message: `Cannot extend router: property \"${key}\" already exists`,\n          });\n        }\n      }\n\n      for (const key of keys) {\n        (router as Record<string, unknown>)[key] = extensions[key];\n      }\n\n      const extensionRecord = { keys };\n\n      ctx.routerExtensions.push(extensionRecord);\n\n      let removed = false;\n\n      return () => {\n        if (removed) {\n          return;\n        }\n\n        removed = true;\n\n        for (const key of extensionRecord.keys) {\n          delete (router as Record<string, unknown>)[key];\n        }\n\n        const idx = ctx.routerExtensions.indexOf(extensionRecord);\n\n        if (idx !== -1) {\n          ctx.routerExtensions.splice(idx, 1);\n        }\n      };\n    },\n    emitTransitionError: (error) => {\n      throwIfDisposed(ctx.isDisposed);\n      ctx.emitTransitionError(error);\n    },\n    claimContextNamespace: (namespace: string) => {\n      throwIfDisposed(ctx.isDisposed);\n\n      if (ctx.contextClaimRecords.has(namespace)) {\n        throw new RouterError(errorCodes.CONTEXT_NAMESPACE_ALREADY_CLAIMED, {\n          message: `Cannot claim context namespace: \"${namespace}\" is already claimed by another plugin`,\n        });\n      }\n\n      ctx.contextClaimRecords.add(namespace);\n\n      return {\n        write(state: State, value: unknown) {\n          state.context[namespace] = value;\n        },\n        release() {\n          ctx.contextClaimRecords.delete(namespace);\n        },\n      } satisfies ContextNamespaceClaim;\n    },\n  };\n\n  cache.set(router, api);\n\n  return api;\n}\n","import { throwIfDisposed } from \"./helpers\";\nimport { getInternals } from \"../internals\";\n\nimport type { LifecycleApi } from \"./types\";\nimport type { DefaultDependencies, Router } from \"@real-router/types\";\n\nexport function getLifecycleApi<\n  Dependencies extends DefaultDependencies = DefaultDependencies,\n>(router: Router<Dependencies>): LifecycleApi<Dependencies> {\n  const ctx = getInternals(router);\n  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guaranteed set after wiring\n  const lifecycleNamespace = ctx.routeGetStore().lifecycleNamespace!;\n\n  return {\n    addActivateGuard(name, handler) {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.routes.validateRouteName(name, \"addActivateGuard\");\n      ctx.validator?.lifecycle.validateHandler(handler, \"addActivateGuard\");\n\n      const activateCount = lifecycleNamespace.getHandlerCount(\"activate\");\n\n      ctx.validator?.lifecycle.validateHandlerLimit(\n        activateCount,\n        ctx.dependenciesGetStore().limits,\n        \"canActivate\",\n      );\n\n      lifecycleNamespace.addCanActivate(name, handler);\n    },\n\n    addDeactivateGuard(name, handler) {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.routes.validateRouteName(name, \"addDeactivateGuard\");\n      ctx.validator?.lifecycle.validateHandler(handler, \"addDeactivateGuard\");\n\n      const deactivateCount = lifecycleNamespace.getHandlerCount(\"deactivate\");\n\n      ctx.validator?.lifecycle.validateHandlerLimit(\n        deactivateCount,\n        ctx.dependenciesGetStore().limits,\n        \"canDeactivate\",\n      );\n\n      lifecycleNamespace.addCanDeactivate(name, handler);\n    },\n\n    removeActivateGuard(name) {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.routes.validateRouteName(name, \"removeActivateGuard\");\n\n      lifecycleNamespace.clearCanActivate(name);\n    },\n\n    removeDeactivateGuard(name) {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.routes.validateRouteName(name, \"removeDeactivateGuard\");\n\n      lifecycleNamespace.clearCanDeactivate(name);\n    },\n  };\n}\n","import { routeTreeToDefinitions } from \"route-tree\";\n\nimport { errorCodes } from \"../constants\";\nimport { getInternals } from \"../internals\";\nimport { Router as RouterClass } from \"../Router\";\nimport { RouterError } from \"../RouterError\";\nimport { getLifecycleApi } from \"./getLifecycleApi\";\n\nimport type { Route } from \"../types\";\nimport type { DefaultDependencies, Router } from \"@real-router/types\";\n\nexport function cloneRouter<\n  Dependencies extends DefaultDependencies = DefaultDependencies,\n>(\n  router: Router<Dependencies>,\n  dependencies?: Dependencies,\n): RouterClass<Dependencies> {\n  const ctx = getInternals(router);\n\n  if (ctx.isDisposed()) {\n    throw new RouterError(errorCodes.ROUTER_DISPOSED);\n  }\n\n  ctx.validator?.dependencies.validateCloneArgs(dependencies);\n\n  // Get source store directly\n  const sourceStore = ctx.routeGetStore();\n  const routes = routeTreeToDefinitions(sourceStore.tree);\n  const routeConfig = sourceStore.config;\n  const resolvedForwardMap = sourceStore.resolvedForwardMap;\n  const routeCustomFields = sourceStore.routeCustomFields;\n\n  const options = ctx.cloneOptions();\n  const sourceDeps = ctx.cloneDependencies();\n  const [canDeactivateFactories, canActivateFactories] =\n    ctx.getLifecycleFactories();\n  const pluginFactories = ctx.getPluginFactories();\n\n  const mergedDeps = {\n    ...sourceDeps,\n    ...dependencies,\n  } as Dependencies;\n\n  const newRouter = new RouterClass<Dependencies>(\n    routes as Route<Dependencies>[],\n    options,\n    mergedDeps,\n  );\n\n  const lifecycle = getLifecycleApi(newRouter);\n\n  for (const [name, handler] of Object.entries(canDeactivateFactories)) {\n    lifecycle.addDeactivateGuard(name, handler);\n  }\n\n  for (const [name, handler] of Object.entries(canActivateFactories)) {\n    lifecycle.addActivateGuard(name, handler);\n  }\n\n  if (pluginFactories.length > 0) {\n    newRouter.usePlugin(...pluginFactories);\n  }\n\n  const newCtx = getInternals(newRouter);\n  const newStore = newCtx.routeGetStore();\n\n  // Apply cloned config directly to new store\n  Object.assign(newStore.config.decoders, routeConfig.decoders);\n  Object.assign(newStore.config.encoders, routeConfig.encoders);\n  Object.assign(newStore.config.defaultParams, routeConfig.defaultParams);\n  Object.assign(newStore.config.forwardMap, routeConfig.forwardMap);\n  Object.assign(newStore.config.forwardFnMap, routeConfig.forwardFnMap);\n  Object.assign(newStore.resolvedForwardMap, resolvedForwardMap);\n  Object.assign(newStore.routeCustomFields, routeCustomFields);\n\n  return newRouter;\n}\n"],"mappings":"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"}
+{"version":3,"file":"cloneRouter-CR7rdWPl.js","names":["RouterError","errorCodes","getInternals","RouterError","errorCodes","getInternals","getInternals","RouterError","errorCodes","routeTreeToDefinitions","RouterClass"],"sources":["../../src/api/helpers.ts","../../src/api/getPluginApi.ts","../../src/api/getLifecycleApi.ts","../../src/api/cloneRouter.ts"],"sourcesContent":["// packages/core/src/api/helpers.ts\n\nimport { errorCodes } from \"../constants\";\nimport { RouterError } from \"../RouterError\";\n\nexport function throwIfDisposed(isDisposed: () => boolean): void {\n  if (isDisposed()) {\n    throw new RouterError(errorCodes.ROUTER_DISPOSED);\n  }\n}\n","import { throwIfDisposed } from \"./helpers\";\nimport { errorCodes } from \"../constants\";\nimport { getInternals } from \"../internals\";\nimport { RouterError } from \"../RouterError\";\n\nimport type { PluginApi } from \"./types\";\nimport type {\n  ContextNamespaceClaim,\n  DefaultDependencies,\n  Params,\n  Router,\n  State,\n} from \"@real-router/types\";\n\n// Cache the assembled PluginApi per router — mirrors getNavigator() (#525):\n// avoids re-allocating the closure-bag on each call (plugins call this once\n// at init, but tests + nested plugins poll it), and gives spy/stub helpers\n// a stable object identity to attach to (e.g. spying on\n// `getPluginApi(router).navigateToState` to inject errors in popstate\n// recovery tests).\nconst cache = new WeakMap<object, PluginApi>();\n\nexport function getPluginApi<\n  Dependencies extends DefaultDependencies = DefaultDependencies,\n>(router: Router<Dependencies>): PluginApi {\n  const cached = cache.get(router);\n\n  if (cached) {\n    return cached;\n  }\n\n  const ctx = getInternals(router);\n  const api: PluginApi = {\n    makeState: (name, params, path, meta) => {\n      ctx.validator?.state.validateMakeStateArgs(name, params, path);\n\n      return ctx.makeState(\n        name,\n        params,\n        path,\n        meta?.params as\n          | Record<string, Record<string, \"url\" | \"query\">>\n          | undefined,\n      );\n    },\n    buildState: (routeName, routeParams) => {\n      ctx.validator?.routes.validateStateBuilderArgs(\n        routeName,\n        routeParams,\n        \"buildState\",\n      );\n\n      const { name, params } = ctx.forwardState(routeName, routeParams);\n\n      return ctx.buildStateResolved(name, params);\n    },\n    forwardState: <P extends Params = Params>(\n      routeName: string,\n      routeParams: P,\n    ) => {\n      ctx.validator?.routes.validateStateBuilderArgs(\n        routeName,\n        routeParams,\n        \"forwardState\",\n      );\n\n      return ctx.forwardState(routeName, routeParams);\n    },\n    matchPath: (path) => {\n      ctx.validator?.routes.validateMatchPathArgs(path);\n\n      return ctx.matchPath(path, ctx.getOptions());\n    },\n    navigateToState: (state, options) => {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.navigation.validateNavigateToStateArgs(state);\n\n      if (options !== undefined) {\n        ctx.validator?.navigation.validateNavigationOptions(\n          options,\n          \"navigateToState\",\n        );\n      }\n\n      return ctx.navigateToState(state, options);\n    },\n    setRootPath: (rootPath) => {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.routes.validateSetRootPathArgs(rootPath);\n\n      ctx.setRootPath(rootPath);\n    },\n    getRootPath: ctx.getRootPath,\n    addEventListener: (eventName, cb) => {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.eventBus.validateListenerArgs(eventName, cb);\n\n      return ctx.addEventListener(eventName, cb);\n    },\n    buildNavigationState: (name, params = {}) => {\n      ctx.validator?.routes.validateStateBuilderArgs(\n        name,\n        params,\n        \"buildNavigationState\",\n      );\n\n      const { name: resolvedName, params: resolvedParams } = ctx.forwardState(\n        name,\n        params,\n      );\n      const routeInfo = ctx.buildStateResolved(resolvedName, resolvedParams);\n\n      if (!routeInfo) {\n        return;\n      }\n\n      return ctx.makeState(\n        routeInfo.name,\n        routeInfo.params,\n        ctx.buildPath(routeInfo.name, routeInfo.params),\n        routeInfo.meta,\n      );\n    },\n    getOptions: ctx.getOptions,\n    getTree: ctx.getTree,\n    addInterceptor: (method, fn) => {\n      throwIfDisposed(ctx.isDisposed);\n      ctx.validator?.plugins.validateAddInterceptorArgs(method, fn);\n      let list = ctx.interceptors.get(method);\n\n      if (!list) {\n        list = [];\n        ctx.interceptors.set(method, list);\n      }\n\n      list.push(fn);\n\n      return () => {\n        const index = list.indexOf(fn);\n\n        if (index !== -1) {\n          list.splice(index, 1);\n        }\n      };\n    },\n    getRouteConfig: (name) => {\n      const store = ctx.routeGetStore();\n\n      if (!store.matcher.hasRoute(name)) {\n        return;\n      }\n\n      return store.routeCustomFields[name];\n    },\n    extendRouter: (extensions: Record<string, unknown>) => {\n      throwIfDisposed(ctx.isDisposed);\n\n      const keys = Object.keys(extensions);\n\n      for (const key of keys) {\n        if (key in router) {\n          throw new RouterError(errorCodes.PLUGIN_CONFLICT, {\n            message: `Cannot extend router: property \"${key}\" already exists`,\n          });\n        }\n      }\n\n      for (const key of keys) {\n        (router as Record<string, unknown>)[key] = extensions[key];\n      }\n\n      const extensionRecord = { keys };\n\n      ctx.routerExtensions.push(extensionRecord);\n\n      let removed = false;\n\n      return () => {\n        if (removed) {\n          return;\n        }\n\n        removed = true;\n\n        for (const key of extensionRecord.keys) {\n          delete (router as Record<string, unknown>)[key];\n        }\n\n        const idx = ctx.routerExtensions.indexOf(extensionRecord);\n\n        if (idx !== -1) {\n          ctx.routerExtensions.splice(idx, 1);\n        }\n      };\n    },\n    emitTransitionError: (error) => {\n      throwIfDisposed(ctx.isDisposed);\n      ctx.emitTransitionError(error);\n    },\n    claimContextNamespace: (namespace: string) => {\n      throwIfDisposed(ctx.isDisposed);\n\n      if (ctx.contextClaimRecords.has(namespace)) {\n        throw new RouterError(errorCodes.CONTEXT_NAMESPACE_ALREADY_CLAIMED, {\n          message: `Cannot claim context namespace: \"${namespace}\" is already claimed by another plugin`,\n        });\n      }\n\n      ctx.contextClaimRecords.add(namespace);\n\n      return {\n        write(state: State, value: unknown) {\n          state.context[namespace] = value;\n        },\n        release() {\n          ctx.contextClaimRecords.delete(namespace);\n        },\n      } satisfies ContextNamespaceClaim;\n    },\n  };\n\n  cache.set(router, api);\n\n  return api;\n}\n","import { throwIfDisposed } from \"./helpers\";\nimport { getInternals } from \"../internals\";\n\nimport type { LifecycleApi } from \"./types\";\nimport type { DefaultDependencies, Router } from \"@real-router/types\";\n\nexport function getLifecycleApi<\n  Dependencies extends DefaultDependencies = DefaultDependencies,\n>(router: Router<Dependencies>): LifecycleApi<Dependencies> {\n  const ctx = getInternals(router);\n  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guaranteed set after wiring\n  const lifecycleNamespace = ctx.routeGetStore().lifecycleNamespace!;\n\n  return {\n    addActivateGuard(name, handler) {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.routes.validateRouteName(name, \"addActivateGuard\");\n      ctx.validator?.lifecycle.validateHandler(handler, \"addActivateGuard\");\n\n      const activateCount = lifecycleNamespace.getHandlerCount(\"activate\");\n\n      ctx.validator?.lifecycle.validateHandlerLimit(\n        activateCount,\n        ctx.dependenciesGetStore().limits,\n        \"canActivate\",\n      );\n\n      lifecycleNamespace.addCanActivate(name, handler);\n    },\n\n    addDeactivateGuard(name, handler) {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.routes.validateRouteName(name, \"addDeactivateGuard\");\n      ctx.validator?.lifecycle.validateHandler(handler, \"addDeactivateGuard\");\n\n      const deactivateCount = lifecycleNamespace.getHandlerCount(\"deactivate\");\n\n      ctx.validator?.lifecycle.validateHandlerLimit(\n        deactivateCount,\n        ctx.dependenciesGetStore().limits,\n        \"canDeactivate\",\n      );\n\n      lifecycleNamespace.addCanDeactivate(name, handler);\n    },\n\n    removeActivateGuard(name) {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.routes.validateRouteName(name, \"removeActivateGuard\");\n\n      lifecycleNamespace.clearCanActivate(name);\n    },\n\n    removeDeactivateGuard(name) {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.routes.validateRouteName(name, \"removeDeactivateGuard\");\n\n      lifecycleNamespace.clearCanDeactivate(name);\n    },\n  };\n}\n","import { routeTreeToDefinitions } from \"route-tree\";\n\nimport { errorCodes } from \"../constants\";\nimport { getInternals } from \"../internals\";\nimport { Router as RouterClass } from \"../Router\";\nimport { RouterError } from \"../RouterError\";\nimport { getLifecycleApi } from \"./getLifecycleApi\";\n\nimport type { Route } from \"../types\";\nimport type { DefaultDependencies, Router } from \"@real-router/types\";\n\n/**\n * Build an independent router instance that shares the route tree, options,\n * lifecycle guards, and plugin factories of `router`. The primary use case\n * is **SSR multi-tenancy** — one base router per process, one clone per\n * request.\n *\n * @param router - Source router (must not be disposed).\n * @param dependencies - Optional per-clone overrides merged on top of the\n *   base router's dependencies. Always **fresh per call** in the documented\n *   SSR pattern: pass per-request state here, never store it in the base.\n *\n * @remarks\n *\n * **Dependency merge — shallow by design.** `base.dependencies` are spread\n * into the clone via `{ ...sourceDeps, ...dependencies }`. Top-level keys\n * are new objects, but **values are shared by reference**: a `Map`, `Set`,\n * class instance, function, or nested plain object stored in\n * `base.dependencies` is the **same instance** in every clone. Mutations\n * in one clone are visible in the base and in every sibling clone.\n *\n * This is intentional. `structuredClone` of dep values is **not** applied\n * because it would:\n * - strip class prototypes (`new DbClient()` → plain object, methods lost)\n * - reject functions and symbols (`DataCloneError`)\n * - fragment singleton pools (one connection pool per request — pool\n *   semantics destroyed)\n * - reject circular references\n *\n * **SSR rule of thumb.** Place values in `base.dependencies` according to\n * their lifecycle:\n *\n * - **Singletons / shared services** → `base.dependencies`. Examples: DB\n *   client, connection pool, logger, config, feature-flag client. Process-\n *   wide pooling depends on sharing these by reference.\n * - **Per-request state** → the `dependencies` override parameter (or\n *   `createRequestScope`'s `deps` argument). Examples: `currentUser`,\n *   `traceId`, `sessionId`, `abortSignal`. The override is applied last,\n *   so it wins over base keys; pass a fresh object per call.\n *\n * Cross-request data leaks are **only possible** when per-request mutable\n * state is incorrectly placed in `base.dependencies`. The override slot is\n * the safe channel.\n *\n * @example\n * ```typescript\n * // Server boot — singletons only\n * const base = createRouter(routes, options, {\n *   db: new DbClient(dbUrl),\n *   logger,\n * });\n *\n * // Per request — fresh override per call\n * const clone = cloneRouter(base, {\n *   currentUser,\n *   traceId,\n * });\n * // clone.deps.db === base.deps.db  ✓ shared pool (intentional)\n * // clone.deps.currentUser          ✓ unique per request\n * ```\n *\n * @see createRequestScope — `@real-router/core/utils` SSR helper that\n *   wraps this function and injects `abortSignal` automatically.\n */\nexport function cloneRouter<\n  Dependencies extends DefaultDependencies = DefaultDependencies,\n>(\n  router: Router<Dependencies>,\n  dependencies?: Dependencies,\n): RouterClass<Dependencies> {\n  const ctx = getInternals(router);\n\n  if (ctx.isDisposed()) {\n    throw new RouterError(errorCodes.ROUTER_DISPOSED);\n  }\n\n  ctx.validator?.dependencies.validateCloneArgs(dependencies);\n\n  // Get source store directly\n  const sourceStore = ctx.routeGetStore();\n  const routes = routeTreeToDefinitions(sourceStore.tree);\n  const routeConfig = sourceStore.config;\n  const resolvedForwardMap = sourceStore.resolvedForwardMap;\n  const routeCustomFields = sourceStore.routeCustomFields;\n\n  const options = ctx.cloneOptions();\n  const sourceDeps = ctx.cloneDependencies();\n  const [canDeactivateFactories, canActivateFactories] =\n    ctx.getLifecycleFactories();\n  const pluginFactories = ctx.getPluginFactories();\n\n  const mergedDeps = {\n    ...sourceDeps,\n    ...dependencies,\n  } as Dependencies;\n\n  const newRouter = new RouterClass<Dependencies>(\n    routes as Route<Dependencies>[],\n    options,\n    mergedDeps,\n  );\n\n  const lifecycle = getLifecycleApi(newRouter);\n\n  for (const [name, handler] of Object.entries(canDeactivateFactories)) {\n    lifecycle.addDeactivateGuard(name, handler);\n  }\n\n  for (const [name, handler] of Object.entries(canActivateFactories)) {\n    lifecycle.addActivateGuard(name, handler);\n  }\n\n  if (pluginFactories.length > 0) {\n    newRouter.usePlugin(...pluginFactories);\n  }\n\n  const newCtx = getInternals(newRouter);\n  const newStore = newCtx.routeGetStore();\n\n  // Apply cloned config directly to new store\n  Object.assign(newStore.config.decoders, routeConfig.decoders);\n  Object.assign(newStore.config.encoders, routeConfig.encoders);\n  Object.assign(newStore.config.defaultParams, routeConfig.defaultParams);\n  Object.assign(newStore.config.forwardMap, routeConfig.forwardMap);\n  Object.assign(newStore.config.forwardFnMap, routeConfig.forwardFnMap);\n  Object.assign(newStore.resolvedForwardMap, resolvedForwardMap);\n  Object.assign(newStore.routeCustomFields, routeCustomFields);\n\n  return newRouter;\n}\n"],"mappings":"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"}

package/dist/esm/api.d.mts

@@ -20,6 +20,69 @@ declare function getDependenciesApi<Dependencies extends DefaultDependencies = D
 declare function getLifecycleApi<Dependencies extends DefaultDependencies = DefaultDependencies>(router: Router<Dependencies>): LifecycleApi<Dependencies>;
 //#endregion
 //#region src/api/cloneRouter.d.ts
+/**
+ * Build an independent router instance that shares the route tree, options,
+ * lifecycle guards, and plugin factories of `router`. The primary use case
+ * is **SSR multi-tenancy** — one base router per process, one clone per
+ * request.
+ *
+ * @param router - Source router (must not be disposed).
+ * @param dependencies - Optional per-clone overrides merged on top of the
+ *   base router's dependencies. Always **fresh per call** in the documented
+ *   SSR pattern: pass per-request state here, never store it in the base.
+ *
+ * @remarks
+ *
+ * **Dependency merge — shallow by design.** `base.dependencies` are spread
+ * into the clone via `{ ...sourceDeps, ...dependencies }`. Top-level keys
+ * are new objects, but **values are shared by reference**: a `Map`, `Set`,
+ * class instance, function, or nested plain object stored in
+ * `base.dependencies` is the **same instance** in every clone. Mutations
+ * in one clone are visible in the base and in every sibling clone.
+ *
+ * This is intentional. `structuredClone` of dep values is **not** applied
+ * because it would:
+ * - strip class prototypes (`new DbClient()` → plain object, methods lost)
+ * - reject functions and symbols (`DataCloneError`)
+ * - fragment singleton pools (one connection pool per request — pool
+ *   semantics destroyed)
+ * - reject circular references
+ *
+ * **SSR rule of thumb.** Place values in `base.dependencies` according to
+ * their lifecycle:
+ *
+ * - **Singletons / shared services** → `base.dependencies`. Examples: DB
+ *   client, connection pool, logger, config, feature-flag client. Process-
+ *   wide pooling depends on sharing these by reference.
+ * - **Per-request state** → the `dependencies` override parameter (or
+ *   `createRequestScope`'s `deps` argument). Examples: `currentUser`,
+ *   `traceId`, `sessionId`, `abortSignal`. The override is applied last,
+ *   so it wins over base keys; pass a fresh object per call.
+ *
+ * Cross-request data leaks are **only possible** when per-request mutable
+ * state is incorrectly placed in `base.dependencies`. The override slot is
+ * the safe channel.
+ *
+ * @example
+ * ```typescript
+ * // Server boot — singletons only
+ * const base = createRouter(routes, options, {
+ *   db: new DbClient(dbUrl),
+ *   logger,
+ * });
+ *
+ * // Per request — fresh override per call
+ * const clone = cloneRouter(base, {
+ *   currentUser,
+ *   traceId,
+ * });
+ * // clone.deps.db === base.deps.db  ✓ shared pool (intentional)
+ * // clone.deps.currentUser          ✓ unique per request
+ * ```
+ *
+ * @see createRequestScope — `@real-router/core/utils` SSR helper that
+ *   wraps this function and injects `abortSignal` automatically.
+ */
 declare function cloneRouter<Dependencies extends DefaultDependencies = DefaultDependencies>(router: Router<Dependencies>, dependencies?: Dependencies): Router$1<Dependencies>;
 //#endregion
 export { type DependenciesApi, type LifecycleApi, type PluginApi, type RoutesApi, cloneRouter, getDependenciesApi, getLifecycleApi, getPluginApi, getRoutesApi };

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

@@ -1 +1 @@
-{"version":3,"file":"api.d.mts","names":[],"sources":["../../src/api/types.ts","../../src/api/getPluginApi.ts","../../src/api/getRoutesApi.ts","../../src/api/getDependenciesApi.ts","../../src/api/getLifecycleApi.ts","../../src/api/cloneRouter.ts"],"mappings":";;;;;UAGiB,SAAA,SAAkB,IAAA,CAAK,WAAA;EACtC,OAAA,QAAe,SAAA;AAAA;;;iBCkBD,YAAA,sBACO,mBAAA,GAAsB,mBAAA,CAAA,CAC3C,MAAA,EAAQ,MAAA,CAAO,YAAA,IAAgB,SAAA;;;iBCgYjB,YAAA,sBACO,mBAAA,GAAsB,mBAAA,CAAA,CAC3C,MAAA,EAAQ,MAAA,CAAO,YAAA,IAAgB,SAAA,CAAU,YAAA;;;iBCzU3B,kBAAA,sBACO,mBAAA,GAAsB,mBAAA,CAAA,CAC3C,MAAA,EAAQ,MAAA,CAAO,YAAA,IAAgB,eAAA,CAAgB,YAAA;;;iBC7EjC,eAAA,sBACO,mBAAA,GAAsB,mBAAA,CAAA,CAC3C,MAAA,EAAQ,MAAA,CAAO,YAAA,IAAgB,YAAA,CAAa,YAAA;;;iBCG9B,WAAA,sBACO,mBAAA,GAAsB,mBAAA,CAAA,CAE3C,MAAA,EAAQ,MAAA,CAAO,YAAA,GACf,YAAA,GAAe,YAAA,GACd,QAAA,CAAY,YAAA"}
+{"version":3,"file":"api.d.mts","names":[],"sources":["../../src/api/types.ts","../../src/api/getPluginApi.ts","../../src/api/getRoutesApi.ts","../../src/api/getDependenciesApi.ts","../../src/api/getLifecycleApi.ts","../../src/api/cloneRouter.ts"],"mappings":";;;;;UAGiB,SAAA,SAAkB,IAAA,CAAK,WAAA;EACtC,OAAA,QAAe,SAAA;AAAA;;;iBCkBD,YAAA,sBACO,mBAAA,GAAsB,mBAAA,CAAA,CAC3C,MAAA,EAAQ,MAAA,CAAO,YAAA,IAAgB,SAAA;;;iBCgYjB,YAAA,sBACO,mBAAA,GAAsB,mBAAA,CAAA,CAC3C,MAAA,EAAQ,MAAA,CAAO,YAAA,IAAgB,SAAA,CAAU,YAAA;;;iBCzU3B,kBAAA,sBACO,mBAAA,GAAsB,mBAAA,CAAA,CAC3C,MAAA,EAAQ,MAAA,CAAO,YAAA,IAAgB,eAAA,CAAgB,YAAA;;;iBC7EjC,eAAA,sBACO,mBAAA,GAAsB,mBAAA,CAAA,CAC3C,MAAA,EAAQ,MAAA,CAAO,YAAA,IAAgB,YAAA,CAAa,YAAA;;;;;;AJL9C;;;;;;;;;;;;;AAC0B;;;;ACkB1B;;;;;;;;;;;;;;;;;;AAE0C;;;;ACgY1C;;;;;;;;;;;;;;;;;;;;AAEuD;iBGhVvC,WAAA,sBACO,mBAAA,GAAsB,mBAAA,CAAA,CAE3C,MAAA,EAAQ,MAAA,CAAO,YAAA,GACf,YAAA,GAAe,YAAA,GACd,QAAA,CAAY,YAAA"}

package/dist/esm/cloneRouter-BBjARLMk.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"cloneRouter-BBjARLMk.mjs","names":["routeTreeToDefinitions","RouterClass"],"sources":["../../src/api/helpers.ts","../../src/api/getPluginApi.ts","../../src/api/getLifecycleApi.ts","../../src/api/cloneRouter.ts"],"sourcesContent":["// packages/core/src/api/helpers.ts\n\nimport { errorCodes } from \"../constants\";\nimport { RouterError } from \"../RouterError\";\n\nexport function throwIfDisposed(isDisposed: () => boolean): void {\n  if (isDisposed()) {\n    throw new RouterError(errorCodes.ROUTER_DISPOSED);\n  }\n}\n","import { throwIfDisposed } from \"./helpers\";\nimport { errorCodes } from \"../constants\";\nimport { getInternals } from \"../internals\";\nimport { RouterError } from \"../RouterError\";\n\nimport type { PluginApi } from \"./types\";\nimport type {\n  ContextNamespaceClaim,\n  DefaultDependencies,\n  Params,\n  Router,\n  State,\n} from \"@real-router/types\";\n\n// Cache the assembled PluginApi per router — mirrors getNavigator() (#525):\n// avoids re-allocating the closure-bag on each call (plugins call this once\n// at init, but tests + nested plugins poll it), and gives spy/stub helpers\n// a stable object identity to attach to (e.g. spying on\n// `getPluginApi(router).navigateToState` to inject errors in popstate\n// recovery tests).\nconst cache = new WeakMap<object, PluginApi>();\n\nexport function getPluginApi<\n  Dependencies extends DefaultDependencies = DefaultDependencies,\n>(router: Router<Dependencies>): PluginApi {\n  const cached = cache.get(router);\n\n  if (cached) {\n    return cached;\n  }\n\n  const ctx = getInternals(router);\n  const api: PluginApi = {\n    makeState: (name, params, path, meta) => {\n      ctx.validator?.state.validateMakeStateArgs(name, params, path);\n\n      return ctx.makeState(\n        name,\n        params,\n        path,\n        meta?.params as\n          | Record<string, Record<string, \"url\" | \"query\">>\n          | undefined,\n      );\n    },\n    buildState: (routeName, routeParams) => {\n      ctx.validator?.routes.validateStateBuilderArgs(\n        routeName,\n        routeParams,\n        \"buildState\",\n      );\n\n      const { name, params } = ctx.forwardState(routeName, routeParams);\n\n      return ctx.buildStateResolved(name, params);\n    },\n    forwardState: <P extends Params = Params>(\n      routeName: string,\n      routeParams: P,\n    ) => {\n      ctx.validator?.routes.validateStateBuilderArgs(\n        routeName,\n        routeParams,\n        \"forwardState\",\n      );\n\n      return ctx.forwardState(routeName, routeParams);\n    },\n    matchPath: (path) => {\n      ctx.validator?.routes.validateMatchPathArgs(path);\n\n      return ctx.matchPath(path, ctx.getOptions());\n    },\n    navigateToState: (state, options) => {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.navigation.validateNavigateToStateArgs(state);\n\n      if (options !== undefined) {\n        ctx.validator?.navigation.validateNavigationOptions(\n          options,\n          \"navigateToState\",\n        );\n      }\n\n      return ctx.navigateToState(state, options);\n    },\n    setRootPath: (rootPath) => {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.routes.validateSetRootPathArgs(rootPath);\n\n      ctx.setRootPath(rootPath);\n    },\n    getRootPath: ctx.getRootPath,\n    addEventListener: (eventName, cb) => {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.eventBus.validateListenerArgs(eventName, cb);\n\n      return ctx.addEventListener(eventName, cb);\n    },\n    buildNavigationState: (name, params = {}) => {\n      ctx.validator?.routes.validateStateBuilderArgs(\n        name,\n        params,\n        \"buildNavigationState\",\n      );\n\n      const { name: resolvedName, params: resolvedParams } = ctx.forwardState(\n        name,\n        params,\n      );\n      const routeInfo = ctx.buildStateResolved(resolvedName, resolvedParams);\n\n      if (!routeInfo) {\n        return;\n      }\n\n      return ctx.makeState(\n        routeInfo.name,\n        routeInfo.params,\n        ctx.buildPath(routeInfo.name, routeInfo.params),\n        routeInfo.meta,\n      );\n    },\n    getOptions: ctx.getOptions,\n    getTree: ctx.getTree,\n    addInterceptor: (method, fn) => {\n      throwIfDisposed(ctx.isDisposed);\n      ctx.validator?.plugins.validateAddInterceptorArgs(method, fn);\n      let list = ctx.interceptors.get(method);\n\n      if (!list) {\n        list = [];\n        ctx.interceptors.set(method, list);\n      }\n\n      list.push(fn);\n\n      return () => {\n        const index = list.indexOf(fn);\n\n        if (index !== -1) {\n          list.splice(index, 1);\n        }\n      };\n    },\n    getRouteConfig: (name) => {\n      const store = ctx.routeGetStore();\n\n      if (!store.matcher.hasRoute(name)) {\n        return;\n      }\n\n      return store.routeCustomFields[name];\n    },\n    extendRouter: (extensions: Record<string, unknown>) => {\n      throwIfDisposed(ctx.isDisposed);\n\n      const keys = Object.keys(extensions);\n\n      for (const key of keys) {\n        if (key in router) {\n          throw new RouterError(errorCodes.PLUGIN_CONFLICT, {\n            message: `Cannot extend router: property \"${key}\" already exists`,\n          });\n        }\n      }\n\n      for (const key of keys) {\n        (router as Record<string, unknown>)[key] = extensions[key];\n      }\n\n      const extensionRecord = { keys };\n\n      ctx.routerExtensions.push(extensionRecord);\n\n      let removed = false;\n\n      return () => {\n        if (removed) {\n          return;\n        }\n\n        removed = true;\n\n        for (const key of extensionRecord.keys) {\n          delete (router as Record<string, unknown>)[key];\n        }\n\n        const idx = ctx.routerExtensions.indexOf(extensionRecord);\n\n        if (idx !== -1) {\n          ctx.routerExtensions.splice(idx, 1);\n        }\n      };\n    },\n    emitTransitionError: (error) => {\n      throwIfDisposed(ctx.isDisposed);\n      ctx.emitTransitionError(error);\n    },\n    claimContextNamespace: (namespace: string) => {\n      throwIfDisposed(ctx.isDisposed);\n\n      if (ctx.contextClaimRecords.has(namespace)) {\n        throw new RouterError(errorCodes.CONTEXT_NAMESPACE_ALREADY_CLAIMED, {\n          message: `Cannot claim context namespace: \"${namespace}\" is already claimed by another plugin`,\n        });\n      }\n\n      ctx.contextClaimRecords.add(namespace);\n\n      return {\n        write(state: State, value: unknown) {\n          state.context[namespace] = value;\n        },\n        release() {\n          ctx.contextClaimRecords.delete(namespace);\n        },\n      } satisfies ContextNamespaceClaim;\n    },\n  };\n\n  cache.set(router, api);\n\n  return api;\n}\n","import { throwIfDisposed } from \"./helpers\";\nimport { getInternals } from \"../internals\";\n\nimport type { LifecycleApi } from \"./types\";\nimport type { DefaultDependencies, Router } from \"@real-router/types\";\n\nexport function getLifecycleApi<\n  Dependencies extends DefaultDependencies = DefaultDependencies,\n>(router: Router<Dependencies>): LifecycleApi<Dependencies> {\n  const ctx = getInternals(router);\n  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guaranteed set after wiring\n  const lifecycleNamespace = ctx.routeGetStore().lifecycleNamespace!;\n\n  return {\n    addActivateGuard(name, handler) {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.routes.validateRouteName(name, \"addActivateGuard\");\n      ctx.validator?.lifecycle.validateHandler(handler, \"addActivateGuard\");\n\n      const activateCount = lifecycleNamespace.getHandlerCount(\"activate\");\n\n      ctx.validator?.lifecycle.validateHandlerLimit(\n        activateCount,\n        ctx.dependenciesGetStore().limits,\n        \"canActivate\",\n      );\n\n      lifecycleNamespace.addCanActivate(name, handler);\n    },\n\n    addDeactivateGuard(name, handler) {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.routes.validateRouteName(name, \"addDeactivateGuard\");\n      ctx.validator?.lifecycle.validateHandler(handler, \"addDeactivateGuard\");\n\n      const deactivateCount = lifecycleNamespace.getHandlerCount(\"deactivate\");\n\n      ctx.validator?.lifecycle.validateHandlerLimit(\n        deactivateCount,\n        ctx.dependenciesGetStore().limits,\n        \"canDeactivate\",\n      );\n\n      lifecycleNamespace.addCanDeactivate(name, handler);\n    },\n\n    removeActivateGuard(name) {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.routes.validateRouteName(name, \"removeActivateGuard\");\n\n      lifecycleNamespace.clearCanActivate(name);\n    },\n\n    removeDeactivateGuard(name) {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.routes.validateRouteName(name, \"removeDeactivateGuard\");\n\n      lifecycleNamespace.clearCanDeactivate(name);\n    },\n  };\n}\n","import { routeTreeToDefinitions } from \"route-tree\";\n\nimport { errorCodes } from \"../constants\";\nimport { getInternals } from \"../internals\";\nimport { Router as RouterClass } from \"../Router\";\nimport { RouterError } from \"../RouterError\";\nimport { getLifecycleApi } from \"./getLifecycleApi\";\n\nimport type { Route } from \"../types\";\nimport type { DefaultDependencies, Router } from \"@real-router/types\";\n\nexport function cloneRouter<\n  Dependencies extends DefaultDependencies = DefaultDependencies,\n>(\n  router: Router<Dependencies>,\n  dependencies?: Dependencies,\n): RouterClass<Dependencies> {\n  const ctx = getInternals(router);\n\n  if (ctx.isDisposed()) {\n    throw new RouterError(errorCodes.ROUTER_DISPOSED);\n  }\n\n  ctx.validator?.dependencies.validateCloneArgs(dependencies);\n\n  // Get source store directly\n  const sourceStore = ctx.routeGetStore();\n  const routes = routeTreeToDefinitions(sourceStore.tree);\n  const routeConfig = sourceStore.config;\n  const resolvedForwardMap = sourceStore.resolvedForwardMap;\n  const routeCustomFields = sourceStore.routeCustomFields;\n\n  const options = ctx.cloneOptions();\n  const sourceDeps = ctx.cloneDependencies();\n  const [canDeactivateFactories, canActivateFactories] =\n    ctx.getLifecycleFactories();\n  const pluginFactories = ctx.getPluginFactories();\n\n  const mergedDeps = {\n    ...sourceDeps,\n    ...dependencies,\n  } as Dependencies;\n\n  const newRouter = new RouterClass<Dependencies>(\n    routes as Route<Dependencies>[],\n    options,\n    mergedDeps,\n  );\n\n  const lifecycle = getLifecycleApi(newRouter);\n\n  for (const [name, handler] of Object.entries(canDeactivateFactories)) {\n    lifecycle.addDeactivateGuard(name, handler);\n  }\n\n  for (const [name, handler] of Object.entries(canActivateFactories)) {\n    lifecycle.addActivateGuard(name, handler);\n  }\n\n  if (pluginFactories.length > 0) {\n    newRouter.usePlugin(...pluginFactories);\n  }\n\n  const newCtx = getInternals(newRouter);\n  const newStore = newCtx.routeGetStore();\n\n  // Apply cloned config directly to new store\n  Object.assign(newStore.config.decoders, routeConfig.decoders);\n  Object.assign(newStore.config.encoders, routeConfig.encoders);\n  Object.assign(newStore.config.defaultParams, routeConfig.defaultParams);\n  Object.assign(newStore.config.forwardMap, routeConfig.forwardMap);\n  Object.assign(newStore.config.forwardFnMap, routeConfig.forwardFnMap);\n  Object.assign(newStore.resolvedForwardMap, resolvedForwardMap);\n  Object.assign(newStore.routeCustomFields, routeCustomFields);\n\n  return newRouter;\n}\n"],"mappings":"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"}
+{"version":3,"file":"cloneRouter-BBjARLMk.mjs","names":["routeTreeToDefinitions","RouterClass"],"sources":["../../src/api/helpers.ts","../../src/api/getPluginApi.ts","../../src/api/getLifecycleApi.ts","../../src/api/cloneRouter.ts"],"sourcesContent":["// packages/core/src/api/helpers.ts\n\nimport { errorCodes } from \"../constants\";\nimport { RouterError } from \"../RouterError\";\n\nexport function throwIfDisposed(isDisposed: () => boolean): void {\n  if (isDisposed()) {\n    throw new RouterError(errorCodes.ROUTER_DISPOSED);\n  }\n}\n","import { throwIfDisposed } from \"./helpers\";\nimport { errorCodes } from \"../constants\";\nimport { getInternals } from \"../internals\";\nimport { RouterError } from \"../RouterError\";\n\nimport type { PluginApi } from \"./types\";\nimport type {\n  ContextNamespaceClaim,\n  DefaultDependencies,\n  Params,\n  Router,\n  State,\n} from \"@real-router/types\";\n\n// Cache the assembled PluginApi per router — mirrors getNavigator() (#525):\n// avoids re-allocating the closure-bag on each call (plugins call this once\n// at init, but tests + nested plugins poll it), and gives spy/stub helpers\n// a stable object identity to attach to (e.g. spying on\n// `getPluginApi(router).navigateToState` to inject errors in popstate\n// recovery tests).\nconst cache = new WeakMap<object, PluginApi>();\n\nexport function getPluginApi<\n  Dependencies extends DefaultDependencies = DefaultDependencies,\n>(router: Router<Dependencies>): PluginApi {\n  const cached = cache.get(router);\n\n  if (cached) {\n    return cached;\n  }\n\n  const ctx = getInternals(router);\n  const api: PluginApi = {\n    makeState: (name, params, path, meta) => {\n      ctx.validator?.state.validateMakeStateArgs(name, params, path);\n\n      return ctx.makeState(\n        name,\n        params,\n        path,\n        meta?.params as\n          | Record<string, Record<string, \"url\" | \"query\">>\n          | undefined,\n      );\n    },\n    buildState: (routeName, routeParams) => {\n      ctx.validator?.routes.validateStateBuilderArgs(\n        routeName,\n        routeParams,\n        \"buildState\",\n      );\n\n      const { name, params } = ctx.forwardState(routeName, routeParams);\n\n      return ctx.buildStateResolved(name, params);\n    },\n    forwardState: <P extends Params = Params>(\n      routeName: string,\n      routeParams: P,\n    ) => {\n      ctx.validator?.routes.validateStateBuilderArgs(\n        routeName,\n        routeParams,\n        \"forwardState\",\n      );\n\n      return ctx.forwardState(routeName, routeParams);\n    },\n    matchPath: (path) => {\n      ctx.validator?.routes.validateMatchPathArgs(path);\n\n      return ctx.matchPath(path, ctx.getOptions());\n    },\n    navigateToState: (state, options) => {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.navigation.validateNavigateToStateArgs(state);\n\n      if (options !== undefined) {\n        ctx.validator?.navigation.validateNavigationOptions(\n          options,\n          \"navigateToState\",\n        );\n      }\n\n      return ctx.navigateToState(state, options);\n    },\n    setRootPath: (rootPath) => {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.routes.validateSetRootPathArgs(rootPath);\n\n      ctx.setRootPath(rootPath);\n    },\n    getRootPath: ctx.getRootPath,\n    addEventListener: (eventName, cb) => {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.eventBus.validateListenerArgs(eventName, cb);\n\n      return ctx.addEventListener(eventName, cb);\n    },\n    buildNavigationState: (name, params = {}) => {\n      ctx.validator?.routes.validateStateBuilderArgs(\n        name,\n        params,\n        \"buildNavigationState\",\n      );\n\n      const { name: resolvedName, params: resolvedParams } = ctx.forwardState(\n        name,\n        params,\n      );\n      const routeInfo = ctx.buildStateResolved(resolvedName, resolvedParams);\n\n      if (!routeInfo) {\n        return;\n      }\n\n      return ctx.makeState(\n        routeInfo.name,\n        routeInfo.params,\n        ctx.buildPath(routeInfo.name, routeInfo.params),\n        routeInfo.meta,\n      );\n    },\n    getOptions: ctx.getOptions,\n    getTree: ctx.getTree,\n    addInterceptor: (method, fn) => {\n      throwIfDisposed(ctx.isDisposed);\n      ctx.validator?.plugins.validateAddInterceptorArgs(method, fn);\n      let list = ctx.interceptors.get(method);\n\n      if (!list) {\n        list = [];\n        ctx.interceptors.set(method, list);\n      }\n\n      list.push(fn);\n\n      return () => {\n        const index = list.indexOf(fn);\n\n        if (index !== -1) {\n          list.splice(index, 1);\n        }\n      };\n    },\n    getRouteConfig: (name) => {\n      const store = ctx.routeGetStore();\n\n      if (!store.matcher.hasRoute(name)) {\n        return;\n      }\n\n      return store.routeCustomFields[name];\n    },\n    extendRouter: (extensions: Record<string, unknown>) => {\n      throwIfDisposed(ctx.isDisposed);\n\n      const keys = Object.keys(extensions);\n\n      for (const key of keys) {\n        if (key in router) {\n          throw new RouterError(errorCodes.PLUGIN_CONFLICT, {\n            message: `Cannot extend router: property \"${key}\" already exists`,\n          });\n        }\n      }\n\n      for (const key of keys) {\n        (router as Record<string, unknown>)[key] = extensions[key];\n      }\n\n      const extensionRecord = { keys };\n\n      ctx.routerExtensions.push(extensionRecord);\n\n      let removed = false;\n\n      return () => {\n        if (removed) {\n          return;\n        }\n\n        removed = true;\n\n        for (const key of extensionRecord.keys) {\n          delete (router as Record<string, unknown>)[key];\n        }\n\n        const idx = ctx.routerExtensions.indexOf(extensionRecord);\n\n        if (idx !== -1) {\n          ctx.routerExtensions.splice(idx, 1);\n        }\n      };\n    },\n    emitTransitionError: (error) => {\n      throwIfDisposed(ctx.isDisposed);\n      ctx.emitTransitionError(error);\n    },\n    claimContextNamespace: (namespace: string) => {\n      throwIfDisposed(ctx.isDisposed);\n\n      if (ctx.contextClaimRecords.has(namespace)) {\n        throw new RouterError(errorCodes.CONTEXT_NAMESPACE_ALREADY_CLAIMED, {\n          message: `Cannot claim context namespace: \"${namespace}\" is already claimed by another plugin`,\n        });\n      }\n\n      ctx.contextClaimRecords.add(namespace);\n\n      return {\n        write(state: State, value: unknown) {\n          state.context[namespace] = value;\n        },\n        release() {\n          ctx.contextClaimRecords.delete(namespace);\n        },\n      } satisfies ContextNamespaceClaim;\n    },\n  };\n\n  cache.set(router, api);\n\n  return api;\n}\n","import { throwIfDisposed } from \"./helpers\";\nimport { getInternals } from \"../internals\";\n\nimport type { LifecycleApi } from \"./types\";\nimport type { DefaultDependencies, Router } from \"@real-router/types\";\n\nexport function getLifecycleApi<\n  Dependencies extends DefaultDependencies = DefaultDependencies,\n>(router: Router<Dependencies>): LifecycleApi<Dependencies> {\n  const ctx = getInternals(router);\n  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guaranteed set after wiring\n  const lifecycleNamespace = ctx.routeGetStore().lifecycleNamespace!;\n\n  return {\n    addActivateGuard(name, handler) {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.routes.validateRouteName(name, \"addActivateGuard\");\n      ctx.validator?.lifecycle.validateHandler(handler, \"addActivateGuard\");\n\n      const activateCount = lifecycleNamespace.getHandlerCount(\"activate\");\n\n      ctx.validator?.lifecycle.validateHandlerLimit(\n        activateCount,\n        ctx.dependenciesGetStore().limits,\n        \"canActivate\",\n      );\n\n      lifecycleNamespace.addCanActivate(name, handler);\n    },\n\n    addDeactivateGuard(name, handler) {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.routes.validateRouteName(name, \"addDeactivateGuard\");\n      ctx.validator?.lifecycle.validateHandler(handler, \"addDeactivateGuard\");\n\n      const deactivateCount = lifecycleNamespace.getHandlerCount(\"deactivate\");\n\n      ctx.validator?.lifecycle.validateHandlerLimit(\n        deactivateCount,\n        ctx.dependenciesGetStore().limits,\n        \"canDeactivate\",\n      );\n\n      lifecycleNamespace.addCanDeactivate(name, handler);\n    },\n\n    removeActivateGuard(name) {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.routes.validateRouteName(name, \"removeActivateGuard\");\n\n      lifecycleNamespace.clearCanActivate(name);\n    },\n\n    removeDeactivateGuard(name) {\n      throwIfDisposed(ctx.isDisposed);\n\n      ctx.validator?.routes.validateRouteName(name, \"removeDeactivateGuard\");\n\n      lifecycleNamespace.clearCanDeactivate(name);\n    },\n  };\n}\n","import { routeTreeToDefinitions } from \"route-tree\";\n\nimport { errorCodes } from \"../constants\";\nimport { getInternals } from \"../internals\";\nimport { Router as RouterClass } from \"../Router\";\nimport { RouterError } from \"../RouterError\";\nimport { getLifecycleApi } from \"./getLifecycleApi\";\n\nimport type { Route } from \"../types\";\nimport type { DefaultDependencies, Router } from \"@real-router/types\";\n\n/**\n * Build an independent router instance that shares the route tree, options,\n * lifecycle guards, and plugin factories of `router`. The primary use case\n * is **SSR multi-tenancy** — one base router per process, one clone per\n * request.\n *\n * @param router - Source router (must not be disposed).\n * @param dependencies - Optional per-clone overrides merged on top of the\n *   base router's dependencies. Always **fresh per call** in the documented\n *   SSR pattern: pass per-request state here, never store it in the base.\n *\n * @remarks\n *\n * **Dependency merge — shallow by design.** `base.dependencies` are spread\n * into the clone via `{ ...sourceDeps, ...dependencies }`. Top-level keys\n * are new objects, but **values are shared by reference**: a `Map`, `Set`,\n * class instance, function, or nested plain object stored in\n * `base.dependencies` is the **same instance** in every clone. Mutations\n * in one clone are visible in the base and in every sibling clone.\n *\n * This is intentional. `structuredClone` of dep values is **not** applied\n * because it would:\n * - strip class prototypes (`new DbClient()` → plain object, methods lost)\n * - reject functions and symbols (`DataCloneError`)\n * - fragment singleton pools (one connection pool per request — pool\n *   semantics destroyed)\n * - reject circular references\n *\n * **SSR rule of thumb.** Place values in `base.dependencies` according to\n * their lifecycle:\n *\n * - **Singletons / shared services** → `base.dependencies`. Examples: DB\n *   client, connection pool, logger, config, feature-flag client. Process-\n *   wide pooling depends on sharing these by reference.\n * - **Per-request state** → the `dependencies` override parameter (or\n *   `createRequestScope`'s `deps` argument). Examples: `currentUser`,\n *   `traceId`, `sessionId`, `abortSignal`. The override is applied last,\n *   so it wins over base keys; pass a fresh object per call.\n *\n * Cross-request data leaks are **only possible** when per-request mutable\n * state is incorrectly placed in `base.dependencies`. The override slot is\n * the safe channel.\n *\n * @example\n * ```typescript\n * // Server boot — singletons only\n * const base = createRouter(routes, options, {\n *   db: new DbClient(dbUrl),\n *   logger,\n * });\n *\n * // Per request — fresh override per call\n * const clone = cloneRouter(base, {\n *   currentUser,\n *   traceId,\n * });\n * // clone.deps.db === base.deps.db  ✓ shared pool (intentional)\n * // clone.deps.currentUser          ✓ unique per request\n * ```\n *\n * @see createRequestScope — `@real-router/core/utils` SSR helper that\n *   wraps this function and injects `abortSignal` automatically.\n */\nexport function cloneRouter<\n  Dependencies extends DefaultDependencies = DefaultDependencies,\n>(\n  router: Router<Dependencies>,\n  dependencies?: Dependencies,\n): RouterClass<Dependencies> {\n  const ctx = getInternals(router);\n\n  if (ctx.isDisposed()) {\n    throw new RouterError(errorCodes.ROUTER_DISPOSED);\n  }\n\n  ctx.validator?.dependencies.validateCloneArgs(dependencies);\n\n  // Get source store directly\n  const sourceStore = ctx.routeGetStore();\n  const routes = routeTreeToDefinitions(sourceStore.tree);\n  const routeConfig = sourceStore.config;\n  const resolvedForwardMap = sourceStore.resolvedForwardMap;\n  const routeCustomFields = sourceStore.routeCustomFields;\n\n  const options = ctx.cloneOptions();\n  const sourceDeps = ctx.cloneDependencies();\n  const [canDeactivateFactories, canActivateFactories] =\n    ctx.getLifecycleFactories();\n  const pluginFactories = ctx.getPluginFactories();\n\n  const mergedDeps = {\n    ...sourceDeps,\n    ...dependencies,\n  } as Dependencies;\n\n  const newRouter = new RouterClass<Dependencies>(\n    routes as Route<Dependencies>[],\n    options,\n    mergedDeps,\n  );\n\n  const lifecycle = getLifecycleApi(newRouter);\n\n  for (const [name, handler] of Object.entries(canDeactivateFactories)) {\n    lifecycle.addDeactivateGuard(name, handler);\n  }\n\n  for (const [name, handler] of Object.entries(canActivateFactories)) {\n    lifecycle.addActivateGuard(name, handler);\n  }\n\n  if (pluginFactories.length > 0) {\n    newRouter.usePlugin(...pluginFactories);\n  }\n\n  const newCtx = getInternals(newRouter);\n  const newStore = newCtx.routeGetStore();\n\n  // Apply cloned config directly to new store\n  Object.assign(newStore.config.decoders, routeConfig.decoders);\n  Object.assign(newStore.config.encoders, routeConfig.encoders);\n  Object.assign(newStore.config.defaultParams, routeConfig.defaultParams);\n  Object.assign(newStore.config.forwardMap, routeConfig.forwardMap);\n  Object.assign(newStore.config.forwardFnMap, routeConfig.forwardFnMap);\n  Object.assign(newStore.resolvedForwardMap, resolvedForwardMap);\n  Object.assign(newStore.routeCustomFields, routeCustomFields);\n\n  return newRouter;\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/core",
-  "version": "0.54.3",
+  "version": "0.54.4",
   "type": "commonjs",
   "description": "A simple, powerful, view-agnostic, modular and extensible router",
   "main": "./dist/cjs/index.js",

package/src/api/cloneRouter.ts

@@ -9,6 +9,69 @@ import { getLifecycleApi } from "./getLifecycleApi";
 import type { Route } from "../types";
 import type { DefaultDependencies, Router } from "@real-router/types";
 
+/**
+ * Build an independent router instance that shares the route tree, options,
+ * lifecycle guards, and plugin factories of `router`. The primary use case
+ * is **SSR multi-tenancy** — one base router per process, one clone per
+ * request.
+ *
+ * @param router - Source router (must not be disposed).
+ * @param dependencies - Optional per-clone overrides merged on top of the
+ *   base router's dependencies. Always **fresh per call** in the documented
+ *   SSR pattern: pass per-request state here, never store it in the base.
+ *
+ * @remarks
+ *
+ * **Dependency merge — shallow by design.** `base.dependencies` are spread
+ * into the clone via `{ ...sourceDeps, ...dependencies }`. Top-level keys
+ * are new objects, but **values are shared by reference**: a `Map`, `Set`,
+ * class instance, function, or nested plain object stored in
+ * `base.dependencies` is the **same instance** in every clone. Mutations
+ * in one clone are visible in the base and in every sibling clone.
+ *
+ * This is intentional. `structuredClone` of dep values is **not** applied
+ * because it would:
+ * - strip class prototypes (`new DbClient()` → plain object, methods lost)
+ * - reject functions and symbols (`DataCloneError`)
+ * - fragment singleton pools (one connection pool per request — pool
+ *   semantics destroyed)
+ * - reject circular references
+ *
+ * **SSR rule of thumb.** Place values in `base.dependencies` according to
+ * their lifecycle:
+ *
+ * - **Singletons / shared services** → `base.dependencies`. Examples: DB
+ *   client, connection pool, logger, config, feature-flag client. Process-
+ *   wide pooling depends on sharing these by reference.
+ * - **Per-request state** → the `dependencies` override parameter (or
+ *   `createRequestScope`'s `deps` argument). Examples: `currentUser`,
+ *   `traceId`, `sessionId`, `abortSignal`. The override is applied last,
+ *   so it wins over base keys; pass a fresh object per call.
+ *
+ * Cross-request data leaks are **only possible** when per-request mutable
+ * state is incorrectly placed in `base.dependencies`. The override slot is
+ * the safe channel.
+ *
+ * @example
+ * ```typescript
+ * // Server boot — singletons only
+ * const base = createRouter(routes, options, {
+ *   db: new DbClient(dbUrl),
+ *   logger,
+ * });
+ *
+ * // Per request — fresh override per call
+ * const clone = cloneRouter(base, {
+ *   currentUser,
+ *   traceId,
+ * });
+ * // clone.deps.db === base.deps.db  ✓ shared pool (intentional)
+ * // clone.deps.currentUser          ✓ unique per request
+ * ```
+ *
+ * @see createRequestScope — `@real-router/core/utils` SSR helper that
+ *   wraps this function and injects `abortSignal` automatically.
+ */
 export function cloneRouter<
   Dependencies extends DefaultDependencies = DefaultDependencies,
 >(