@real-router/hash-plugin 0.6.3 → 0.7.0

package/README.md

@@ -95,6 +95,21 @@ lifecycle.addDeactivateGuard(
 );
 ```
 
+## Limitations
+
+### URL Fragments via `<Link hash>` / `opts.hash`
+
+Hash-plugin uses `#` as the route delimiter — URL fragments are structurally incompatible. The signatures of `router.buildUrl(name, params, options?)` and `router.replaceHistoryState(name, params, options?)` accept `{ hash }` for typing parity with the other URL plugins, but at runtime the option is **silently ignored** and a one-time `console.warn` is emitted on the first invocation:
+
+```text
+[@real-router/hash-plugin] `hash` option is ignored — `#` is reserved for the route delimiter.
+Use browser-plugin or navigation-plugin for URL fragments.
+```
+
+`state.context.url` is **not** populated under hash-plugin (`undefined` at runtime). Hash-aware sources (`useIsActiveRoute`, `<Link hash>` active state) consequently return `false` for any non-undefined `hash`. Only one URL plugin (`browser-plugin`, `navigation-plugin`, or `hash-plugin`) may be installed per router instance.
+
+If you need URL fragments for tab-style UIs or anchor scrolling, use [`@real-router/browser-plugin`](../browser-plugin/) or [`@real-router/navigation-plugin`](../navigation-plugin/) instead — see the [Hash Fragment Support](https://github.com/greydragon888/real-router/wiki/Hash) wiki page.
+
 ## SSR Support
 
 SSR-safe — automatically detects the environment and falls back to no-ops:

package/dist/cjs/index.d.ts

@@ -1,4 +1,6 @@
 import { Params, PluginFactory, State } from "@real-router/core";
+import { Params as Params$1, State as State$1 } from "@real-router/types";
+
 //#region ../../shared/browser-env/types.d.ts
 interface HistoryBrowser {
   pushState: (state: unknown, path: string) => void;
@@ -39,81 +41,6 @@ interface HashPluginOptions {
 //#region src/factory.d.ts
 declare function hashPluginFactory(opts?: Partial<HashPluginOptions>, browser?: Browser): PluginFactory;
 //#endregion
-//#region ../core-types/dist/esm/index.d.mts
-type TransitionPhase = "deactivating" | "activating";
-type TransitionReason = "success" | "blocked" | "cancelled" | "error";
-interface TransitionMeta {
-  phase: TransitionPhase;
-  reason: TransitionReason;
-  reload?: boolean;
-  redirected?: boolean;
-  from?: string;
-  blocker?: string;
-  segments: {
-    deactivated: string[];
-    activated: string[];
-    intersection: string;
-  };
-}
-/**
- * Empty interface extended by plugins via module augmentation to declare
- * typed `state.context.<namespace>` fields.
- *
- * @description
- * Plugins add typed context namespaces by augmenting this interface:
- *
- * ```typescript
- * declare module "@real-router/types" {
- *   interface StateContext {
- *     navigation: { direction: "forward" | "back" | "navigate" };
- *   }
- * }
- * ```
- *
- * After augmentation, `state.context.navigation` becomes typed. The intersection
- * with `Record<string, unknown>` in {@link State.context} keeps the type open,
- * so plugins that don't augment can still write arbitrary namespaces.
- *
- * @see {@link State.context}
- * @see {@link ContextNamespaceClaim}
- */
-interface StateContext {}
-interface State$1<P extends Params$1 = Params$1> {
-  name: string;
-  params: P;
-  path: string;
-  transition: TransitionMeta;
-  /**
-   * Plugin-extensible per-route data, attached by plugins via
-   * `PluginApi.claimContextNamespace()` + `claim.write(state, value)`.
-   *
-   * @description
-   * Required field — always present as at least `{}` on every State created by
-   * the router (via `makeState`, `navigateToNotFound`, or `cloneRouter`).
-   *
-   * Typed extensions come from plugins augmenting {@link StateContext} through
-   * module augmentation. The intersection with `Record<string, unknown>` allows
-   * untyped namespaces (inline plugins, tests, or plugins that skip augmentation)
-   * to write without compile errors.
-   *
-   * The `context` object itself is **not frozen** — this is intentional, so
-   * plugins can attach data without cloning state. Core structural fields
-   * (`name`, `params`, `path`, `transition`) remain immutable via shallow
-   * `Object.freeze(state)`.
-   *
-   * @see {@link StateContext}
-   */
-  context: StateContext & Record<string, unknown>;
-}
-interface Params$1 {
-  [key: string]: string | string[] | number | number[] | boolean | boolean[] | Params$1 | Params$1[] | Record<string, string | number | boolean> | null | undefined;
-} //#endregion
-//#region src/limits.d.ts
-/**
- * Configuration for router resource limits.
- * Controls maximum allowed values for various router operations to prevent resource exhaustion.
- */
-//#endregion
 //#region ../type-guards/dist/esm/index.d.mts
 /**
  * Enhanced type guard for State with deep validation.
@@ -140,24 +67,50 @@ declare function isStateStrict<P extends Params$1 = Params$1>(value: unknown): v
 /**
  * Module augmentation for real-router.
  * Extends Router interface with hash plugin methods.
+ *
+ * NavigationOptions augmentation (#532) keeps the `hash` / `hashChange` keys
+ * known to TypeScript even when only hash-plugin is installed — runtime
+ * silently ignores them with a one-time warn.
  */
+declare module "@real-router/types" {
+  interface NavigationOptions {
+    /**
+     * URL fragment override (decoded, no leading "#"). Ignored by hash-plugin
+     * (URL fragments are structurally incompatible with hash routing); see
+     * `Router.buildUrl`. (#532)
+     */
+    hash?: string;
+    /** @internal — not used by hash-plugin. */
+    hashChange?: boolean;
+  }
+}
 declare module "@real-router/core" {
   interface Router {
     /**
      * Builds full URL for a route with base path and hash prefix.
      * Added by hash plugin.
+     *
+     * The optional `hash` option exists for typing parity with browser-plugin
+     * and navigation-plugin (#532). hash-plugin uses `#` as the route
+     * delimiter, so the option is silently ignored at runtime and a
+     * one-time `console.warn` is emitted.
      */
-    buildUrl: (name: string, params?: Params) => string;
+    buildUrl(name: string, params?: Params, options?: {
+      hash?: string;
+    }): string;
     /**
      * Matches URL and returns corresponding state.
      * Added by hash plugin.
      */
-    matchUrl: (url: string) => State | undefined;
+    matchUrl(url: string): State | undefined;
     /**
      * Replaces current history state without triggering navigation.
-     * Added by hash plugin.
+     * Added by hash plugin. The optional `hash` option is ignored (see
+     * `buildUrl`).
      */
-    replaceHistoryState: (name: string, params?: Params) => void;
+    replaceHistoryState(name: string, params?: Params, options?: {
+      hash?: string;
+    }): void;
     start(path?: string): Promise<State>;
   }
 } //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":["ArrayFormat","BooleanFormat","NullFormat","NumberFormat","QueryParamsOptions","arrayFormat","booleanFormat","nullFormat","numberFormat","QueryParamsMode","ParamSource","ParamTypeMap","Record","RouteTreeStateMeta","RouteParams","key","RouteTreeState","P","name","params","meta","Unsubscribe","SimpleState","Params","TransitionPhase","TransitionReason","TransitionMeta","phase","reason","reload","redirected","from","blocker","segments","deactivated","activated","intersection","StateContext","State","path","transition","context","StateMetaInput","RouterError","Error","code","segment","redirect","setCode","setErrorInstance","err","setAdditionalFields","fields","hasField","getField","toJSON","NavigationOptions","AbortSignal","replace","force","forceDeactivate","signal","LimitsConfig","maxDependencies","maxPlugins","maxListeners","warnListeners","maxEventDepth","maxLifecycleHandlers","LogLevel","LogLevelConfig","LogCallback","level","message","args","LoggerConfig","callback","callbackIgnoresLevel","DefaultRouteCallback","K","Dependencies","getDependency","ForwardToCallback","DefaultParamsCallback","Options","Partial","defaultRoute","defaultParams","trailingSlash","urlParamsEncoding","queryParamsMode","queryParams","allowNotFound","rewritePathOnMatch","logger","limits","GuardFn","Promise","toState","fromState","DefaultDependencies","Config","decoders","encoders","forwardMap","Plugin","onStart","onStop","onTransitionStart","onTransitionLeaveApprove","onTransitionCancel","onTransitionError","onTransitionSuccess","opts","teardown","SubscribeState","route","previousRoute","SubscribeFn","state","LeaveState","nextRoute","LeaveFn","Listener","next","val","error","complete","Subscription","unsubscribe","Navigator","navigate","routeName","routeParams","options","getState","isActiveRoute","strictEquality","ignoreQueryParams","canNavigateTo","subscribe","listener","subscribeLeave","isLeaveApproved","Router","D","PluginFactory","buildPath","getPreviousState","areStatesEqual","state1","state2","shouldUpdateNode","nodeName","isActive","start","startPath","stop","dispose","usePlugin","plugins","navigateToDefault","navigateToNotFound","router","GuardFnFactory","Route","canActivate","canDeactivate","forwardTo","children","encodeParams","stateParams","decodeParams","pathParams","RouteConfigUpdate","PluginMethod","EventName","EventsKeys","ErrorCodeValues","ErrorCodeKeys","EventToPluginMap","ROUTER_START","ROUTER_STOP","TRANSITION_START","TRANSITION_LEAVE_APPROVE","TRANSITION_CANCEL","TRANSITION_SUCCESS","TRANSITION_ERROR","EventToNameMap","EventMethodMap","ErrorCodeToValueMap","ROUTER_NOT_STARTED","NO_START_PATH_OR_STATE","ROUTER_ALREADY_STARTED","ROUTE_NOT_FOUND","SAME_STATES","CANNOT_DEACTIVATE","CANNOT_ACTIVATE","TRANSITION_ERR","TRANSITION_CANCELLED","ROUTER_DISPOSED","PLUGIN_CONFLICT","CONTEXT_NAMESPACE_ALREADY_CLAIMED","InterceptableMethodMap","forwardState","add","routes","parent","InterceptorFn","M","Parameters","ReturnType","ContextNamespaceClaim","T","write","value","release","PluginApi","E","makeState","buildState","matchPath","navigateToState","setRootPath","rootPath","getRootPath","addEventListener","eventName","cb","buildNavigationState","getOptions","getTree","addInterceptor","method","fn","extendRouter","extensions","emitTransitionError","claimContextNamespace","namespace","getRouteConfig","RoutesApi","remove","update","updates","clear","has","get","DependenciesApi","getAll","set","setAll","deps","reset","LifecycleApi","addActivateGuard","canActivateHandler","addDeactivateGuard","canDeactivateHandler","removeActivateGuard","removeDeactivateGuard","NavigationOptions","Params","State","isNavigationOptions","value","isRouteName","name","isState","P","isStateStrict","isString","isBoolean","isObjKey","T","Extract","key","obj","isPrimitiveValue","isParams","isParamsStrict","validateRouteName","methodName","validateState","state","method","getTypeDescription"],"sources":["../../../../shared/browser-env/types.ts","../../src/types.ts","../../src/factory.ts","../../../core-types/dist/esm/index.d.mts","../../../type-guards/dist/esm/index.d.mts","../../src/index.ts"],"mappings":";;UAAiB,cAAA;EACf,SAAA,GAAY,KAAA,WAAgB,IAAA;EAC5B,YAAA,GAAe,KAAA,WAAgB,IAAA;EAC/B,mBAAA,GAAsB,EAAA,GAAK,GAAA,EAAK,aAAA;EAChC,OAAA;AAAA;AAAA,UAGe,OAAA,SAAgB,cAAA;EAC/B,WAAA;AAAA;;;;;;;UCFe,iBAAA;EDNc;;;;;ECY7B,UAAA;EDVA;;;;;ECiBA,IAAA;EDhBsB;;;;AAIxB;ECmBE,eAAA;AAAA;;;iBCdc,iBAAA,CACd,IAAA,GAAO,OAAA,CAAQ,iBAAA,GACf,OAAA,GAAU,OAAA,GACT,aAAA;;;KC4CEwB,eAAAA;AAAAA,KACAC,gBAAAA;AAAAA,UACKC,cAAAA;EACRC,KAAAA,EAAOH,eAAAA;EACPI,MAAAA,EAAQH,gBAAAA;EACRI,MAAAA;EACAC,UAAAA;EACAC,IAAAA;EACAC,OAAAA;EACAC,QAAAA;IACEC,WAAAA;IACAC,SAAAA;IACAC,YAAAA;EAAAA;AAAAA;;;;;;;;;;;;;;;;AAAY;;;;;AAyBM;;UAAZC,YAAAA;AAAAA,UACAC,OAAAA,WAAgBf,QAAAA,GAASA,QAAAA;EACjCL,IAAAA;EACAC,MAAAA,EAAQF,CAAAA;EACRsB,IAAAA;EACAC,UAAAA,EAAYd,cAAAA;EAqBYd;;;;;;;;;;;;;;;;;AAqLJ;;;EArLpB6B,OAAAA,EAASJ,YAAAA,GAAezB,MAAAA;AAAAA;AAAAA,UAuLhBW,QAAAA;EAAAA,CACPR,GAAAA,yEAA4EQ,QAAAA,GAASA,QAAAA,KAAWX,MAAAA;AAAAA;AAAAA;;;;;;;;;AAtP9E;;;;;;;;;;iBCqBJkQ,aAAAA,WAAwBR,QAAAA,GAASA,QAAAA,CAAAA,CAAQG,KAAAA,YAAiBA,KAAAA,IAASF,OAAAA,CAAMM,CAAAA;AAAAA;;;;;;ADV1E;;;;;;;;YEjDJ,MAAA;ILpBV;;;;IKyBE,QAAA,GAAW,IAAA,UAAc,MAAA,GAAS,MAAA;ILxBT;;;;IK8BzB,QAAA,GAAW,GAAA,aAAgB,KAAA;IL1Bd;;;;IKgCb,mBAAA,GAAsB,IAAA,UAAc,MAAA,GAAS,MAAA;IAE7C,KAAA,CAAM,IAAA,YAAgB,OAAA,CAAQ,KAAA;EAAA;AAAA"}
+{"version":3,"file":"index.d.ts","names":["NavigationOptions","Params","State","isNavigationOptions","value","isRouteName","name","isState","P","isStateStrict","isString","isBoolean","isObjKey","T","Extract","key","obj","isPrimitiveValue","isParams","isParamsStrict","validateRouteName","methodName","validateState","state","method","getTypeDescription"],"sources":["../../../../shared/browser-env/types.ts","../../src/types.ts","../../src/factory.ts","../../../type-guards/dist/esm/index.d.mts","../../src/index.ts"],"mappings":";;;;UAAiB,cAAA;EACf,SAAA,GAAY,KAAA,WAAgB,IAAA;EAC5B,YAAA,GAAe,KAAA,WAAgB,IAAA;EAC/B,mBAAA,GAAsB,EAAA,GAAK,GAAA,EAAK,aAAA;EAChC,OAAA;AAAA;AAAA,UAGe,OAAA,SAAgB,cAAA;EAC/B,WAAA;AAAA;;;;;;;UCFe,iBAAA;EDNA;;;;;ECYf,UAAA;EDX4B;;;;;ECkB5B,IAAA;EDhB2B;;;;;ECuB3B,eAAA;AAAA;;;iBCdc,iBAAA,CACd,IAAA,GAAO,OAAA,CAAQ,iBAAA,GACf,OAAA,GAAU,OAAA,GACT,aAAA;;;;;;;;;;;;;;;iBCkEcS,aAAAA,WAAwBR,QAAAA,GAASA,QAAAA,CAAAA,CAAQG,KAAAA,YAAiBA,KAAAA,IAASF,OAAAA,CAAMM,CAAAA;AAAAA;;;;;;;;;AHjF1F;;;;;;;;AAAA;EAAA,UI0BY,iBAAA;IJvBV;;;;;II6BE,IAAA;IJ5BK;II8BL,UAAA;EAAA;AAAA;AAAA;EAAA,UAKQ,MAAA;;;;AHjCZ;;;;;;IG2CI,QAAA,CACE,IAAA,UACA,MAAA,GAAS,MAAA,EACT,OAAA;MAAY,IAAA;IAAA;;;;AFxClB;IE+CI,QAAA,CAAS,GAAA,WAAc,KAAA;IF/CM;;;;;IEsD7B,mBAAA,CACE,IAAA,UACA,MAAA,GAAS,MAAA,EACT,OAAA;MAAY,IAAA;IAAA;IAGd,KAAA,CAAM,IAAA,YAAgB,OAAA,CAAQ,KAAA;EAAA;AAAA"}

package/dist/cjs/index.js

@@ -1,2 +1,2 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require(`@real-router/core/api`),t=require(`@real-router/core`);const n=()=>globalThis.window!==void 0&&!!globalThis.history,r=(e,t)=>{globalThis.history.pushState(e,``,t)},i=(e,t)=>{globalThis.history.replaceState(e,``,t)},a=e=>(globalThis.addEventListener(`popstate`,e),()=>{globalThis.removeEventListener(`popstate`,e)}),o=()=>globalThis.location.hash;function s(e){if(!e)return e;let t=e.replaceAll(/\/+/g,`/`);return t.startsWith(`/`)||(t=`/${t}`),t.length>1&&t.endsWith(`/`)&&(t=t.slice(0,-1)),t===`/`?``:t}const c=e=>{try{return encodeURI(decodeURI(e))}catch(t){return console.warn(`[browser-env] Could not encode path "${e}"`,t),e}},l=()=>{},u=e=>{let t=!1;return n=>{t||=(console.warn(`[browser-env] Browser API is running in a non-browser environment (context: "${e}"). Method "${n}" is a no-op. This is expected for SSR, but may indicate misconfiguration if you expected browser behavior.`),!0)}},d=e=>{let t=u(e);return{pushState:()=>{t(`pushState`)},replaceState:()=>{t(`replaceState`)},addPopstateListener:()=>(t(`addPopstateListener`),l),getHash:()=>(t(`getHash`),``)}},f=/^[A-Z_a-z][\w-]*(?:\.[A-Z_a-z][\w-]*)*$/;function p(e){return typeof e==`string`?e===``?!0:e.length>1e4?!1:e.startsWith(`@@`)?!0:f.test(e):!1}function m(e,t=new WeakSet){if(e==null)return!0;let n=typeof e;if(n===`string`||n===`boolean`)return!0;if(n===`number`)return Number.isFinite(e);if(n===`function`||n===`symbol`)return!1;if(Array.isArray(e))return t.has(e)?!1:(t.add(e),e.every(e=>m(e,t)));if(n===`object`){if(t.has(e))return!1;t.add(e);let n=Object.getPrototypeOf(e);return n!==null&&n!==Object.prototype?!1:Object.values(e).every(e=>m(e,t))}return!1}function h(e){if(e==null)return!0;let t=typeof e;return t===`string`||t===`boolean`?!0:t===`number`?Number.isFinite(e):!1}function g(e){if(typeof e!=`object`||!e||Array.isArray(e))return!1;let t=Object.getPrototypeOf(e);if(t!==null&&t!==Object.prototype)return!1;let n=!1;for(let t in e){if(!Object.hasOwn(e,t))continue;let r=e[t];if(!h(r)){let e=typeof r;if(e===`function`||e===`symbol`)return!1;n=!0;break}}return n?m(e):!0}function _(e){return p(e.name)&&typeof e.path==`string`&&g(e.params)}function v(e){return!(typeof e!=`object`||!e||!_(e))}function y(e,t,n){return v(e.state)?t.makeState(e.state.name,e.state.params,e.state.path):t.matchPath(n.getLocation())}function b(e,t,n,r){let i={name:e.name,params:e.params,path:e.path};n?r.replaceState(i,t):r.pushState(i,t)}function x(e,t,n){return r=>{if(r)for(let i of Object.keys(r)){if(!(i in e))continue;let a=r[i];if(a===void 0)continue;let o=typeof e[i],s=typeof a;if(s!==o)throw Error(`[${t}] Invalid type for '${i}': expected ${o}, got ${s}`);let c=n?.[i];if(c){let e=c.validate(a);if(e!==null)throw Error(`[${t}] Invalid '${i}': ${e}`)}}}}const S=/[\u0000-\u001F\u007F]/,C={validate:e=>S.test(e)?`must not contain control characters`:e.split(`/`).includes(`..`)?`must not contain '..' segments`:null},w={validate:e=>S.test(e)?`must not contain control characters`:e.includes(`/`)?`must not contain '/' (slash is added before the path automatically)`:e.includes(`#`)?`must not contain '#' (it is added as the hash delimiter)`:e.includes(`?`)?`must not contain '?' (it conflicts with the query delimiter)`:null};function T(e,t){if(n())return{pushState:r,replaceState:i,addPopstateListener:a,getLocation:e,getHash:o};let s=u(t);return{...d(t),getLocation:()=>(s(`getLocation`),``)}}function E(e){let n=!1,r=null;function i(){if(r){let t=r;r=null,console.warn(`[${e.loggerContext}] Processing deferred popstate event`),s(t)}}function a(){let t=e.router.getState();if(!t)return;let n=e.buildUrl(t.name,t.params);e.browser.replaceState(t,n)}function o(t){console.error(`[${e.loggerContext}] Critical error in onPopState`,t);try{a()}catch(t){console.error(`[${e.loggerContext}] Failed to recover from critical error`,t)}}async function s(s){if(n){console.warn(`[${e.loggerContext}] Transition in progress, deferring popstate event`),r=s;return}n=!0;try{let n=y(s,e.api,e.browser);if(n)await e.api.navigateToState(n,e.transitionOptions);else if(e.allowNotFound)e.router.navigateToNotFound(e.browser.getLocation());else{let n=new t.RouterError(t.errorCodes.ROUTE_NOT_FOUND,{path:e.browser.getLocation()});e.api.emitTransitionError(n),a()}}catch(e){if(e instanceof t.RouterError)try{a()}catch{}else o(e)}finally{n=!1,i()}}return e=>void s(e)}function D(e){return{onStart:()=>{e.shared.removePopStateListener&&e.shared.removePopStateListener(),e.shared.removePopStateListener=e.browser.addPopstateListener(e.handler)},onStop:()=>{e.shared.removePopStateListener&&(e.shared.removePopStateListener(),e.shared.removePopStateListener=void 0)},teardown:()=>{e.shared.removePopStateListener&&(e.shared.removePopStateListener(),e.shared.removePopStateListener=void 0),e.cleanup()}}}function O(e,t){return e.addInterceptor(`start`,(e,n)=>e(n??t.getLocation()))}function k(e,t,n,r,i=!0){let a={name:``,params:{},path:``};return(o,s={})=>{let c=e.buildState(o,s);if(!c)throw Error(`[real-router] Cannot replace state: route "${o}" is not found`);let l=e.makeState(c.name,c.params,t.buildPath(c.name,c.params),{params:c.meta}),u=i?n.getHash():``,d=r(o,s)+u;a.name=l.name,a.params=l.params,a.path=l.path,n.replaceState(a,d)}}function A(e,t,n){return e.replace===!0?!0:n?!!e.reload&&t.path===n.path:e.replace!==!1}function j(e){let t=e,n=t.indexOf(`://`);if(n!==-1){let e=n+3,r=t.length;for(let n=e;n<t.length;n++){let e=t[n];if(e===`/`||e===`?`||e===`#`){r=n;break}}t=r===t.length?`/`:t.slice(r),(t.startsWith(`?`)||t.startsWith(`#`))&&(t=`/${t}`)}let r=t.indexOf(`#`),i=r===-1?``:t.slice(r),a=r===-1?t:t.slice(0,r),o=a.indexOf(`?`),s=o===-1?``:a.slice(o);return{pathname:o===-1?a:a.slice(0,o),search:s,hash:i}}const M={hashPrefix:``,base:``,forceDeactivate:!0},N=`hash-plugin`;function P(e){return e.replaceAll(/[$()*+.?[\\\]^{|}-]/g,String.raw`\$&`)}function F(e){return e?RegExp(`^#${P(e)}`):null}function I(e,t){return e===``||e===`#`?`/`:(t?e.replace(t,``):e.slice(1))||`/`}function L(e,t){let n=j(e),r=I(n.hash,t);return r.includes(`?`)?r:r+n.search}function R(e,t,n){let r=c(I(e,n));return r.includes(`?`)?r:r+t}var z=class{#e;#t;#n;#r;#i;constructor(e,t,n,r,i,a,o){this.#e=e,this.#t=r,this.#n=O(t,r);let s=`${n.base}#${n.hashPrefix}`,c=(t,n)=>s+e.buildPath(t,n);this.#r=t.extendRouter({buildUrl:c,matchUrl:e=>t.matchPath(L(e,i))??void 0,replaceHistoryState:k(t,e,r,c,!1)}),this.#i=D({browser:r,shared:o,handler:E({router:e,api:t,browser:r,allowNotFound:t.getOptions().allowNotFound,transitionOptions:a,loggerContext:N,buildUrl:c}),cleanup:()=>{this.#n(),this.#r()}})}getPlugin(){return{...this.#i,onTransitionSuccess:(e,t,n)=>{let r=A(n,e,t);b(e,this.#e.buildUrl(e.name,e.params),r,this.#t)}}}};const B=x(M,N,{base:C,hashPrefix:w});function V(t,n){B(t);let r=t?Object.fromEntries(Object.entries(t).filter(([,e])=>e!==void 0)):{},i={...M,...r};i.base=s(i.base);let a=F(i.hashPrefix),o=n??T(()=>R(globalThis.location.hash,globalThis.location.search,a),`hash-plugin`),c={forceDeactivate:i.forceDeactivate,source:`popstate`,replace:!0},l={removePopStateListener:void 0};return function(t){return new z(t,(0,e.getPluginApi)(t),i,o,a,c,l).getPlugin()}}exports.hashPluginFactory=V,exports.isState=v;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require(`@real-router/core/api`),t=require(`@real-router/core`);const n=()=>globalThis.window!==void 0&&!!globalThis.history,r=(e,t)=>{globalThis.history.pushState(e,``,t)},i=(e,t)=>{globalThis.history.replaceState(e,``,t)},a=e=>(globalThis.addEventListener(`popstate`,e),()=>{globalThis.removeEventListener(`popstate`,e)}),o=()=>globalThis.location.hash;function s(e){if(!e)return e;let t=e.replaceAll(/\/+/g,`/`);return t.startsWith(`/`)||(t=`/${t}`),t.length>1&&t.endsWith(`/`)&&(t=t.slice(0,-1)),t===`/`?``:t}const c=e=>{try{return encodeURI(decodeURI(e))}catch(t){return console.warn(`[browser-env] Could not encode path "${e}"`,t),e}},l=()=>{},u=e=>{let t=!1;return n=>{t||=(console.warn(`[browser-env] Browser API is running in a non-browser environment (context: "${e}"). Method "${n}" is a no-op. This is expected for SSR, but may indicate misconfiguration if you expected browser behavior.`),!0)}},d=e=>{let t=u(e);return{pushState:()=>{t(`pushState`)},replaceState:()=>{t(`replaceState`)},addPopstateListener:()=>(t(`addPopstateListener`),l),getHash:()=>(t(`getHash`),``)}},f=/^[A-Z_a-z][\w-]*(?:\.[A-Z_a-z][\w-]*)*$/;function p(e){return typeof e==`string`?e===``?!0:e.length>1e4?!1:e.startsWith(`@@`)?!0:f.test(e):!1}function m(e,t=new WeakSet){if(e==null)return!0;let n=typeof e;if(n===`string`||n===`boolean`)return!0;if(n===`number`)return Number.isFinite(e);if(n===`function`||n===`symbol`)return!1;if(Array.isArray(e))return t.has(e)?!1:(t.add(e),e.every(e=>m(e,t)));if(n===`object`){if(t.has(e))return!1;t.add(e);let n=Object.getPrototypeOf(e);return n!==null&&n!==Object.prototype?!1:Object.values(e).every(e=>m(e,t))}return!1}function h(e){if(e==null)return!0;let t=typeof e;return t===`string`||t===`boolean`?!0:t===`number`?Number.isFinite(e):!1}function g(e){if(typeof e!=`object`||!e||Array.isArray(e))return!1;let t=Object.getPrototypeOf(e);if(t!==null&&t!==Object.prototype)return!1;let n=!1;for(let t in e){if(!Object.hasOwn(e,t))continue;let r=e[t];if(!h(r)){let e=typeof r;if(e===`function`||e===`symbol`)return!1;n=!0;break}}return n?m(e):!0}function _(e){return p(e.name)&&typeof e.path==`string`&&g(e.params)}function v(e){return!(typeof e!=`object`||!e||!_(e))}function y(e,t,n){return v(e.state)?t.makeState(e.state.name,e.state.params,e.state.path):t.matchPath(n.getLocation())}function b(e,t,n,r){let i={name:e.name,params:e.params,path:e.path};n?r.replaceState(i,t):r.pushState(i,t)}function x(e,t,n){return r=>{if(r)for(let i of Object.keys(r)){if(!(i in e))continue;let a=r[i];if(a===void 0)continue;let o=typeof e[i],s=typeof a;if(s!==o)throw Error(`[${t}] Invalid type for '${i}': expected ${o}, got ${s}`);let c=n?.[i];if(c){let e=c.validate(a);if(e!==null)throw Error(`[${t}] Invalid '${i}': ${e}`)}}}}const S=/[\u0000-\u001F\u007F]/,C={validate:e=>S.test(e)?`must not contain control characters`:e.split(`/`).includes(`..`)?`must not contain '..' segments`:null},w={validate:e=>S.test(e)?`must not contain control characters`:e.includes(`/`)?`must not contain '/' (slash is added before the path automatically)`:e.includes(`#`)?`must not contain '#' (it is added as the hash delimiter)`:e.includes(`?`)?`must not contain '?' (it conflicts with the query delimiter)`:null};function T(e,t){if(n())return{pushState:r,replaceState:i,addPopstateListener:a,getLocation:e,getHash:o};let s=u(t);return{...d(t),getLocation:()=>(s(`getLocation`),``)}}function E(e,t){if(!e.getCurrentHash)return{};let n=e.getCurrentHash();return n!==(e.getCurrentContextHash?e.getCurrentContextHash():``)&&e.router.getState()?.path===t?{hash:n,force:!0,hashChange:!0}:{hash:n}}function D(e){let n=!1,r=null;function i(){if(r){let t=r;r=null,console.warn(`[${e.loggerContext}] Processing deferred popstate event`),s(t)}}function a(){let t=e.router.getState();if(!t)return;let n=t.context?.url?.hash,r=e.buildUrl(t.name,t.params,n?{hash:n}:void 0);e.browser.replaceState(t,r)}function o(t){console.error(`[${e.loggerContext}] Critical error in onPopState`,t);try{a()}catch(t){console.error(`[${e.loggerContext}] Failed to recover from critical error`,t)}}async function s(s){if(n){console.warn(`[${e.loggerContext}] Transition in progress, deferring popstate event`),r=s;return}n=!0;try{let n=y(s,e.api,e.browser);if(n)await e.api.navigateToState(n,{...e.transitionOptions,...E(e,n.path)});else if(e.allowNotFound)e.router.navigateToNotFound(e.browser.getLocation());else{let n=new t.RouterError(t.errorCodes.ROUTE_NOT_FOUND,{path:e.browser.getLocation()});e.api.emitTransitionError(n),a()}}catch(e){if(e instanceof t.RouterError)try{a()}catch{}else o(e)}finally{n=!1,i()}}return e=>void s(e)}function O(e){return{onStart:()=>{e.shared.removePopStateListener&&e.shared.removePopStateListener(),e.shared.removePopStateListener=e.browser.addPopstateListener(e.handler)},onStop:()=>{e.shared.removePopStateListener&&(e.shared.removePopStateListener(),e.shared.removePopStateListener=void 0)},teardown:()=>{e.shared.removePopStateListener&&(e.shared.removePopStateListener(),e.shared.removePopStateListener=void 0),e.cleanup()}}}function k(e){return encodeURI(e).replaceAll(`#`,`%23`)}function A(e){try{return decodeURIComponent(e)}catch{return e}}function j(e){return A(e.startsWith(`#`)?e.slice(1):e)}function M(e,t){return e.addInterceptor(`start`,(e,n)=>e(n??t.getLocation()))}function N(e,t,n,r,i=!0){let a={name:``,params:{},path:``};return(o,s={},c)=>{let l=e.buildState(o,s);if(!l)throw Error(`[real-router] Cannot replace state: route "${o}" is not found`);let u=e.makeState(l.name,l.params,t.buildPath(l.name,l.params),{params:l.meta}),d;if(c?.hash!==void 0){let e=j(c.hash);d=e?`#${k(e)}`:``}else d=i?n.getHash():``;let f=r(o,s)+d;a.name=u.name,a.params=u.params,a.path=u.path,n.replaceState(a,f)}}function P(e,t,n){return e.replace===!0?!0:n?!!e.reload&&t.path===n.path:e.replace!==!1}function F(e){let t=e,n=t.indexOf(`://`);if(n!==-1){let e=n+3,r=t.length;for(let n=e;n<t.length;n++){let e=t[n];if(e===`/`||e===`?`||e===`#`){r=n;break}}t=r===t.length?`/`:t.slice(r),(t.startsWith(`?`)||t.startsWith(`#`))&&(t=`/${t}`)}let r=t.indexOf(`#`),i=r===-1?``:t.slice(r),a=r===-1?t:t.slice(0,r),o=a.indexOf(`?`),s=o===-1?``:a.slice(o);return{pathname:o===-1?a:a.slice(0,o),search:s,hash:i}}const I={hashPrefix:``,base:``,forceDeactivate:!0},L=`hash-plugin`;function R(e){return e.replaceAll(/[$()*+.?[\\\]^{|}-]/g,String.raw`\$&`)}function z(e){return e?RegExp(`^#${R(e)}`):null}function B(e,t){return e===``||e===`#`?`/`:(t?e.replace(t,``):e.slice(1))||`/`}function V(e,t){let n=F(e),r=B(n.hash,t);return r.includes(`?`)?r:r+n.search}function H(e,t,n){let r=c(B(e,n));return r.includes(`?`)?r:r+t}var U=class{#e;#t;#n;#r;#i;#a;constructor(e,t,n,r,i,a,o){this.#e=e,this.#t=r,this.#n=M(t,r);let s=!1,c=()=>{s||(s=!0,console.warn("[@real-router/hash-plugin] `hash` option is ignored — `#` is reserved for the route delimiter. URL fragments are not supported with hash-plugin; use @real-router/browser-plugin or @real-router/navigation-plugin if you need them."))},l=`${n.base}#${n.hashPrefix}`,u=(t,n,r)=>(r?.hash!==void 0&&c(),l+e.buildPath(t,n));this.#a=c,this.#r=t.extendRouter({buildUrl:u,matchUrl:e=>t.matchPath(V(e,i))??void 0,replaceHistoryState:N(t,e,r,u,!1)}),this.#i=O({browser:r,shared:o,handler:D({router:e,api:t,browser:r,allowNotFound:t.getOptions().allowNotFound,transitionOptions:a,loggerContext:L,buildUrl:u}),cleanup:()=>{this.#n(),this.#r()}})}getPlugin(){return{...this.#i,onTransitionSuccess:(e,t,n)=>{n.hash!==void 0&&this.#a();let r=P(n,e,t);b(e,this.#e.buildUrl(e.name,e.params),r,this.#t)}}}};const W=x(I,L,{base:C,hashPrefix:w});function G(t,n){W(t);let r=t?Object.fromEntries(Object.entries(t).filter(([,e])=>e!==void 0)):{},i={...I,...r};i.base=s(i.base);let a=z(i.hashPrefix),o=n??T(()=>H(globalThis.location.hash,globalThis.location.search,a),`hash-plugin`),c={forceDeactivate:i.forceDeactivate,source:`popstate`,replace:!0},l={removePopStateListener:void 0};return function(t){return new U(t,(0,e.getPluginApi)(t),i,o,a,c,l).getPlugin()}}exports.hashPluginFactory=G,exports.isState=v;
 //# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["isState","RouterError","errorCodes","#router","#browser","#removeStartInterceptor","#removeExtensions","#lifecycle"],"sources":["../../../../shared/browser-env/detect.ts","../../../../shared/browser-env/history-api.ts","../../../../shared/browser-env/utils.ts","../../../../shared/browser-env/ssr-fallback.ts","../../../type-guards/dist/esm/index.mjs","../../../../shared/browser-env/popstate-utils.ts","../../../../shared/browser-env/validation.ts","../../../../shared/browser-env/safe-browser.ts","../../../../shared/browser-env/popstate-handler.ts","../../../../shared/browser-env/plugin-utils.ts","../../../../shared/browser-env/url-parsing.ts","../../src/constants.ts","../../src/hash-utils.ts","../../src/plugin.ts","../../src/validation.ts","../../src/factory.ts"],"sourcesContent":["export const isBrowserEnvironment = (): boolean =>\n  typeof globalThis.window !== \"undefined\" && !!globalThis.history;\n","import type { HistoryBrowser } from \"./types.js\";\n\nexport const pushState = (state: unknown, path: string): void => {\n  globalThis.history.pushState(state, \"\", path);\n};\n\nexport const replaceState = (state: unknown, path: string): void => {\n  globalThis.history.replaceState(state, \"\", path);\n};\n\nexport const addPopstateListener: HistoryBrowser[\"addPopstateListener\"] = (\n  fn,\n) => {\n  globalThis.addEventListener(\"popstate\", fn);\n\n  return () => {\n    globalThis.removeEventListener(\"popstate\", fn);\n  };\n};\n\nexport const getHash = (): string => globalThis.location.hash;\n","/**\n * Normalizes base path to canonical form: leading slash, no trailing slash,\n * no repeated slashes. Isolated \"/\" collapses to \"\".\n *\n * @example\n * normalizeBase(\"app\")     // \"/app\"\n * normalizeBase(\"/app/\")   // \"/app\"\n * normalizeBase(\"//app//\") // \"/app\"\n * normalizeBase(\"\")        // \"\"\n * normalizeBase(\"/\")       // \"\"\n */\nexport function normalizeBase(base: string): string {\n  if (!base) {\n    return base;\n  }\n\n  let result = base.replaceAll(/\\/+/g, \"/\");\n\n  if (!result.startsWith(\"/\")) {\n    result = `/${result}`;\n  }\n\n  if (result.length > 1 && result.endsWith(\"/\")) {\n    result = result.slice(0, -1);\n  }\n\n  return result === \"/\" ? \"\" : result;\n}\n\nexport const safelyEncodePath = (path: string): string => {\n  try {\n    return encodeURI(decodeURI(path));\n  } catch (error) {\n    console.warn(`[browser-env] Could not encode path \"${path}\"`, error);\n\n    return path;\n  }\n};\n","import type { HistoryBrowser } from \"./types.js\";\n\nconst NOOP = (): void => {};\n\nexport const createWarnOnce = (context: string) => {\n  let hasWarned = false;\n\n  return (method: string): void => {\n    if (!hasWarned) {\n      console.warn(\n        `[browser-env] Browser API is running in a non-browser environment (context: \"${context}\"). ` +\n          `Method \"${method}\" is a no-op. ` +\n          `This is expected for SSR, but may indicate misconfiguration if you expected browser behavior.`,\n      );\n      hasWarned = true;\n    }\n  };\n};\n\nexport const createHistoryFallbackBrowser = (\n  context: string,\n): HistoryBrowser => {\n  const warnOnce = createWarnOnce(context);\n\n  return {\n    pushState: () => {\n      warnOnce(\"pushState\");\n    },\n    replaceState: () => {\n      warnOnce(\"replaceState\");\n    },\n    addPopstateListener: () => {\n      warnOnce(\"addPopstateListener\");\n\n      return NOOP;\n    },\n    getHash: () => {\n      warnOnce(\"getHash\");\n\n      return \"\";\n    },\n  };\n};\n","const e=[`replace`,`reload`,`force`,`forceDeactivate`,`redirected`];function t(t){if(typeof t!=`object`||!t||Array.isArray(t))return!1;let n=t;for(let t of e){let e=n[t];if(e!==void 0&&typeof e!=`boolean`)return!1}let r=n.signal;return!(r!==void 0&&!(r instanceof AbortSignal))}const n=/\\S/,r=/^[A-Z_a-z][\\w-]*(?:\\.[A-Z_a-z][\\w-]*)*$/;function i(e,t){return TypeError(`[router.${e}] ${t}`)}function a(e){return typeof e==`string`?e===``?!0:e.length>1e4?!1:e.startsWith(`@@`)?!0:r.test(e):!1}function o(e,t=new WeakSet){if(e==null)return!0;let n=typeof e;if(n===`string`||n===`boolean`)return!0;if(n===`number`)return Number.isFinite(e);if(n===`function`||n===`symbol`)return!1;if(Array.isArray(e))return t.has(e)?!1:(t.add(e),e.every(e=>o(e,t)));if(n===`object`){if(t.has(e))return!1;t.add(e);let n=Object.getPrototypeOf(e);return n!==null&&n!==Object.prototype?!1:Object.values(e).every(e=>o(e,t))}return!1}function s(e){if(e==null)return!0;let t=typeof e;return t===`string`||t===`boolean`?!0:t===`number`?Number.isFinite(e):!1}function c(e){if(typeof e!=`object`||!e||Array.isArray(e))return!1;let t=Object.getPrototypeOf(e);if(t!==null&&t!==Object.prototype)return!1;let n=!1;for(let t in e){if(!Object.hasOwn(e,t))continue;let r=e[t];if(!s(r)){let e=typeof r;if(e===`function`||e===`symbol`)return!1;n=!0;break}}return n?o(e):!0}function l(e){if(e==null)return!0;let t=typeof e;return t===`string`||t===`boolean`?!0:t===`number`?Number.isFinite(e):Array.isArray(e)?e.every(e=>{let t=typeof e;return t===`string`||t===`boolean`?!0:t===`number`?Number.isFinite(e):!1}):!1}function u(e){if(typeof e!=`object`||!e||Array.isArray(e))return!1;for(let t in e){if(!Object.hasOwn(e,t))continue;let n=e[t];if(!l(n))return!1}return!0}function d(e){return a(e.name)&&typeof e.path==`string`&&c(e.params)}function f(e){return typeof e!=`object`||!e?!1:d(e)}function p(e){return!(typeof e!=`object`||!e||!d(e))}function m(e){return typeof e==`string`}function h(e){return typeof e==`boolean`}function g(e,t){return e in t}function _(e){return typeof e==`number`?Number.isFinite(e):typeof e==`string`||typeof e==`boolean`}function v(e,t){if(typeof e!=`string`)throw i(t,`Route name must be a string, got ${typeof e}`);if(e!==``){if(!n.test(e))throw i(t,`Route name cannot contain only whitespace`);if(e.length>1e4)throw i(t,`Route name exceeds maximum length of 10000 characters. This is a technical safety limit.`);if(!e.startsWith(`@@`)&&!r.test(e))throw i(t,`Invalid route name \"${e}\". Each segment must start with a letter or underscore, followed by letters, numbers, underscores, or hyphens. Segments are separated by dots (e.g., \"users.profile\").`)}}function y(e){return e===null?`null`:Array.isArray(e)?`array[${e.length}]`:typeof e==`object`?`constructor`in e&&e.constructor.name!==`Object`?e.constructor.name:`object`:typeof e}function b(e,t){if(!f(e))throw TypeError(`[${t}] Invalid state structure: ${y(e)}. Expected State object with name, params, and path properties.`)}export{y as getTypeDescription,h as isBoolean,t as isNavigationOptions,g as isObjKey,c as isParams,u as isParamsStrict,_ as isPrimitiveValue,a as isRouteName,f as isState,p as isStateStrict,m as isString,v as validateRouteName,b as validateState};\n//# sourceMappingURL=index.mjs.map","import { isStateStrict as isState } from \"type-guards\";\n\nimport type { Browser } from \"./types.js\";\nimport type { State, Params } from \"@real-router/core\";\nimport type { PluginApi } from \"@real-router/core/api\";\n\n/**\n * Resolves the popstate event into a navigation-ready `State`.\n *\n * - If `history.state` is a valid router state ({name, params, path} written\n *   by browser-plugin/hash-plugin during their previous navigation), it is\n *   the source of truth — synthesize a fully-typed `State` from it via\n *   `api.makeState`. The synthesized `transition`/`context` fields are\n *   placeholders; the navigation pipeline (`completeTransition` and plugin\n *   claim writes) replaces them.\n *   This branch is mandatory for hash-plugin: `browser.getLocation()`\n *   returns the History pathname, not the hash, so the matchPath fallback\n *   below cannot extract the hash route.\n * - Otherwise (e.g. manually entered URL with no recorded state), fall\n *   back to `api.matchPath(browser.getLocation())`. browser-plugin's\n *   `getLocation` returns the URL pathname — this works.\n * - `undefined` when neither path produces a match.\n *\n * Replaces the previous `{ name, params }` shape so the caller can hand\n * the State directly to `router.navigateToState(state, opts)` and skip\n * the redundant `forwardState`/`buildPath` round-trip in\n * `buildNavigateState` (issue #525).\n */\nexport function getRouteFromEvent(\n  evt: PopStateEvent,\n  api: PluginApi,\n  browser: Browser,\n): State | undefined {\n  if (isState(evt.state)) {\n    return api.makeState(evt.state.name, evt.state.params, evt.state.path);\n  }\n\n  return api.matchPath(browser.getLocation());\n}\n\n/**\n * Updates browser state (pushState or replaceState)\n *\n * @param state - Router state\n * @param url - URL to set\n * @param replace - Whether to replace instead of push\n * @param browser - Browser API instance\n */\nexport function updateBrowserState(\n  state: State,\n  url: string,\n  replace: boolean,\n  browser: Browser,\n): void {\n  const historyState = {\n    name: state.name,\n    params: state.params,\n    path: state.path,\n  };\n\n  if (replace) {\n    browser.replaceState(historyState, url);\n  } else {\n    browser.pushState(historyState, url);\n  }\n}\n\n/**\n * Creates a `updateBrowserState` closure that reuses a single mutable buffer\n * across calls instead of allocating a fresh `{ name, params, path }` object\n * per push/replace.\n *\n * Why: Browsers structured-clone `history.state` synchronously inside\n * `pushState`/`replaceState`, so the caller never sees the buffer escape —\n * it can be safely overwritten before the next call. Eliminates one\n * allocation per navigation on the hot path.\n *\n * Each plugin instance must own its own buffer (do not share across plugins).\n */\nexport function createUpdateBrowserState(): (\n  state: State,\n  url: string,\n  replace: boolean,\n  browser: Browser,\n) => void {\n  const buffer = {\n    name: \"\",\n    params: {} as Params,\n    path: \"\",\n  };\n\n  return (state, url, replace, browser) => {\n    buffer.name = state.name;\n    buffer.params = state.params;\n    buffer.path = state.path;\n\n    if (replace) {\n      browser.replaceState(buffer, url);\n    } else {\n      browser.pushState(buffer, url);\n    }\n  };\n}\n","export interface OptionRule<T> {\n  validate: (value: T) => string | null;\n}\n\nexport type OptionRules<T extends object> = {\n  [K in keyof T]?: OptionRule<NonNullable<T[K]>>;\n};\n\nexport function createOptionsValidator<T extends object>(\n  defaults: Required<T>,\n  loggerContext: string,\n  rules?: OptionRules<T>,\n): (opts: Partial<T> | undefined) => void {\n  return (opts) => {\n    if (!opts) {\n      return;\n    }\n\n    for (const key of Object.keys(opts)) {\n      if (!(key in defaults)) {\n        continue;\n      }\n\n      const value = opts[key as keyof typeof opts];\n\n      if (value === undefined) {\n        continue;\n      }\n\n      const expected = typeof defaults[key as keyof typeof defaults];\n      const actual = typeof value;\n\n      if (actual !== expected) {\n        throw new Error(\n          `[${loggerContext}] Invalid type for '${key}': expected ${expected}, got ${actual}`,\n        );\n      }\n\n      const rule = rules?.[key as keyof T];\n\n      if (rule) {\n        const msg = (rule.validate as (input: unknown) => string | null)(value);\n\n        if (msg !== null) {\n          throw new Error(`[${loggerContext}] Invalid '${key}': ${msg}`);\n        }\n      }\n    }\n  };\n}\n\n// eslint-disable-next-line no-control-regex -- control characters are exactly what this rule rejects\nconst CONTROL_CHARS = /[\\u0000-\\u001F\\u007F]/;\n\nexport const safeBaseRule: OptionRule<string> = {\n  validate: (value) => {\n    if (CONTROL_CHARS.test(value)) {\n      return \"must not contain control characters\";\n    }\n\n    if (value.split(\"/\").includes(\"..\")) {\n      return \"must not contain '..' segments\";\n    }\n\n    return null;\n  },\n};\n\nexport const safeHashPrefixRule: OptionRule<string> = {\n  validate: (value) => {\n    if (CONTROL_CHARS.test(value)) {\n      return \"must not contain control characters\";\n    }\n\n    if (value.includes(\"/\")) {\n      return \"must not contain '/' (slash is added before the path automatically)\";\n    }\n\n    if (value.includes(\"#\")) {\n      return \"must not contain '#' (it is added as the hash delimiter)\";\n    }\n\n    if (value.includes(\"?\")) {\n      return \"must not contain '?' (it conflicts with the query delimiter)\";\n    }\n\n    return null;\n  },\n};\n\nexport const nonNegativeIntegerRule: OptionRule<number> = {\n  validate: (value) => {\n    if (!Number.isFinite(value)) {\n      return `expected finite number, got ${String(value)}`;\n    }\n\n    if (!Number.isInteger(value)) {\n      return `expected integer, got ${String(value)}`;\n    }\n\n    if (value < 0) {\n      return `expected non-negative integer, got ${value}`;\n    }\n\n    return null;\n  },\n};\n","import { isBrowserEnvironment } from \"./detect.js\";\nimport {\n  pushState,\n  replaceState,\n  addPopstateListener,\n  getHash,\n} from \"./history-api.js\";\nimport {\n  createWarnOnce,\n  createHistoryFallbackBrowser,\n} from \"./ssr-fallback.js\";\n\nimport type { Browser } from \"./types.js\";\n\nexport function createSafeBrowser(\n  getLocation: () => string,\n  context: string,\n): Browser {\n  if (isBrowserEnvironment()) {\n    return {\n      pushState,\n      replaceState,\n      addPopstateListener,\n      getLocation,\n      getHash,\n    };\n  }\n\n  const warnOnce = createWarnOnce(context);\n\n  return {\n    ...createHistoryFallbackBrowser(context),\n    getLocation: () => {\n      warnOnce(\"getLocation\");\n\n      return \"\";\n    },\n  };\n}\n","import { errorCodes, RouterError } from \"@real-router/core\";\n\nimport { getRouteFromEvent } from \"./popstate-utils.js\";\n\nimport type { Browser, SharedFactoryState } from \"./types.js\";\nimport type { Params, Plugin, Router } from \"@real-router/core\";\nimport type { PluginApi } from \"@real-router/core/api\";\n\n/**\n * Navigation options used by the popstate handler to trigger a\n * router.navigate() call from a back/forward event. `source` identifies\n * the origin of the transition to downstream context consumers;\n * `replace: true` keeps the history stack in sync with the browser.\n */\nexport interface PopstateTransitionOptions {\n  source: string;\n  replace: true;\n  forceDeactivate?: boolean;\n}\n\nexport interface PopstateHandlerDeps {\n  router: Router;\n  api: PluginApi;\n  browser: Browser;\n  allowNotFound: boolean;\n  transitionOptions: PopstateTransitionOptions;\n  loggerContext: string;\n  buildUrl: (name: string, params?: Params) => string;\n}\n\nexport function createPopstateHandler(\n  deps: PopstateHandlerDeps,\n): (evt: PopStateEvent) => void {\n  let isTransitioning = false;\n  let deferredEvent: PopStateEvent | null = null;\n\n  function processDeferredEvent(): void {\n    if (deferredEvent) {\n      const evt = deferredEvent;\n\n      deferredEvent = null;\n      console.warn(\n        `[${deps.loggerContext}] Processing deferred popstate event`,\n      );\n      void onPopState(evt);\n    }\n  }\n\n  function rollbackUrlToCurrentState(): void {\n    const currentState = deps.router.getState();\n\n    /* v8 ignore next -- @preserve: router always has state after start(); defensive guard for edge cases */\n    if (!currentState) {\n      return;\n    }\n\n    const url = deps.buildUrl(currentState.name, currentState.params);\n\n    deps.browser.replaceState(currentState, url);\n  }\n\n  function recoverFromCriticalError(error: unknown): void {\n    console.error(\n      `[${deps.loggerContext}] Critical error in onPopState`,\n      error,\n    );\n\n    try {\n      rollbackUrlToCurrentState();\n    } catch (recoveryError) {\n      console.error(\n        `[${deps.loggerContext}] Failed to recover from critical error`,\n        recoveryError,\n      );\n    }\n  }\n\n  async function onPopState(evt: PopStateEvent): Promise<void> {\n    if (isTransitioning) {\n      console.warn(\n        `[${deps.loggerContext}] Transition in progress, deferring popstate event`,\n      );\n      deferredEvent = evt;\n\n      return;\n    }\n\n    isTransitioning = true;\n\n    try {\n      const matched = getRouteFromEvent(evt, deps.api, deps.browser);\n\n      if (matched) {\n        // api.navigateToState — plugin-only entry point. Preserves\n        // matchSourceTrailingSlash output and skips the redundant\n        // forwardState/buildPath round-trip (#525).\n        await deps.api.navigateToState(matched, deps.transitionOptions);\n      } else if (deps.allowNotFound) {\n        deps.router.navigateToNotFound(deps.browser.getLocation());\n      } else {\n        // Strict mode — unmatched URL is an error. Emit $$error and sync URL\n        // back to the current router state (no silent fallback to defaultRoute).\n        const err = new RouterError(errorCodes.ROUTE_NOT_FOUND, {\n          path: deps.browser.getLocation(),\n        });\n\n        deps.api.emitTransitionError(err);\n        rollbackUrlToCurrentState();\n      }\n    } catch (error) {\n      if (error instanceof RouterError) {\n        // navigate() already emitted $$error — just sync URL with router state.\n        // Swallow rollback errors: teardown races may remove router.buildUrl\n        // while a popstate event is still queued.\n        try {\n          rollbackUrlToCurrentState();\n        } catch {\n          // noop — nothing safe to do here\n        }\n      } else {\n        recoverFromCriticalError(error);\n      }\n    } finally {\n      isTransitioning = false;\n      processDeferredEvent();\n    }\n  }\n\n  return (evt: PopStateEvent) => void onPopState(evt);\n}\n\nexport interface PopstateLifecycleDeps {\n  browser: Browser;\n  shared: SharedFactoryState;\n  handler: (evt: PopStateEvent) => void;\n  cleanup: () => void;\n}\n\nexport function createPopstateLifecycle(\n  deps: PopstateLifecycleDeps,\n): Pick<Plugin, \"onStart\" | \"onStop\" | \"teardown\"> {\n  return {\n    onStart: () => {\n      if (deps.shared.removePopStateListener) {\n        deps.shared.removePopStateListener();\n      }\n\n      deps.shared.removePopStateListener = deps.browser.addPopstateListener(\n        deps.handler,\n      );\n    },\n\n    onStop: () => {\n      if (deps.shared.removePopStateListener) {\n        deps.shared.removePopStateListener();\n        deps.shared.removePopStateListener = undefined;\n      }\n    },\n\n    teardown: () => {\n      if (deps.shared.removePopStateListener) {\n        deps.shared.removePopStateListener();\n        deps.shared.removePopStateListener = undefined;\n      }\n\n      deps.cleanup();\n    },\n  };\n}\n","import type {\n  NavigationOptions,\n  Params,\n  Router,\n  State,\n} from \"@real-router/core\";\nimport type { PluginApi } from \"@real-router/core/api\";\n\nexport interface LocationSource {\n  getLocation: () => string;\n}\n\n/**\n * Minimal browser surface needed by `createReplaceHistoryState`.\n *\n * Both `Browser` (History API) and navigation-plugin's `NavigationBrowser`\n * (Navigation API) satisfy this structurally — the function never needs\n * `pushState`/`addPopstateListener`, only the replace path.\n */\nexport interface ReplaceStateBrowser {\n  replaceState: (state: unknown, url: string) => void;\n  getHash: () => string;\n}\n\nexport function createStartInterceptor(\n  api: PluginApi,\n  browser: LocationSource,\n): () => void {\n  return api.addInterceptor(\"start\", (next, path) =>\n    next(path ?? browser.getLocation()),\n  );\n}\n\nexport function createReplaceHistoryState(\n  api: PluginApi,\n  router: Router,\n  browser: ReplaceStateBrowser,\n  buildUrl: (name: string, params?: Params) => string,\n  preserveHash = true,\n): (name: string, params?: Params) => void {\n  // Reusable buffer — browsers structured-clone state synchronously inside\n  // replaceState, so the buffer never escapes. Eliminates one allocation per\n  // navigation on the hot path. (Mirrors createUpdateBrowserState.)\n  const buffer = {\n    name: \"\",\n    params: {} as Params,\n    path: \"\",\n  };\n\n  return (name: string, params: Params = {}) => {\n    const state = api.buildState(name, params);\n\n    if (!state) {\n      throw new Error(\n        `[real-router] Cannot replace state: route \"${name}\" is not found`,\n      );\n    }\n\n    const builtState = api.makeState(\n      state.name,\n      state.params,\n      router.buildPath(state.name, state.params),\n      {\n        params: state.meta,\n      },\n    );\n\n    const hash = preserveHash ? browser.getHash() : \"\";\n    const url = buildUrl(name, params) + hash;\n\n    buffer.name = builtState.name;\n    buffer.params = builtState.params;\n    buffer.path = builtState.path;\n\n    browser.replaceState(buffer, url);\n  };\n}\n\nexport function shouldReplaceHistory(\n  navOptions: NavigationOptions,\n  toState: State,\n  fromState: State | undefined,\n): boolean {\n  if (navOptions.replace === true) {\n    return true;\n  }\n\n  if (!fromState) {\n    return navOptions.replace !== false;\n  }\n\n  return !!navOptions.reload && toState.path === fromState.path;\n}\n","export interface ParsedUrl {\n  pathname: string;\n  search: string;\n  hash: string;\n}\n\n/**\n * Scheme-agnostic URL parser.\n *\n * Extracts `pathname`, `search`, and `hash` from any string — absolute\n * (`scheme://authority/path?q#h`), path-relative (`/path?q#h`), or opaque\n * (`data:...`, `javascript:...`). Never throws, never returns null.\n *\n * Routing does not care about scheme or authority, only about the path part.\n * This keeps `browser-plugin`, `navigation-plugin`, and `hash-plugin` working\n * in Electron (`file://`, `app://`), Tauri (`tauri://`, `https://`), and any\n * other webview that may ship with non-HTTP origins. See issue #496.\n */\nexport function safeParseUrl(url: string): ParsedUrl {\n  let rest = url;\n\n  const schemeIdx = rest.indexOf(\"://\");\n\n  if (schemeIdx !== -1) {\n    const authorityStart = schemeIdx + 3;\n    let pathStart = rest.length;\n\n    for (let i = authorityStart; i < rest.length; i++) {\n      const ch = rest[i];\n\n      if (ch === \"/\" || ch === \"?\" || ch === \"#\") {\n        pathStart = i;\n\n        break;\n      }\n    }\n\n    rest = pathStart === rest.length ? \"/\" : rest.slice(pathStart);\n\n    if (rest.startsWith(\"?\") || rest.startsWith(\"#\")) {\n      rest = `/${rest}`;\n    }\n  }\n\n  const hashIdx = rest.indexOf(\"#\");\n  const hash = hashIdx === -1 ? \"\" : rest.slice(hashIdx);\n  const beforeHash = hashIdx === -1 ? rest : rest.slice(0, hashIdx);\n\n  const queryIdx = beforeHash.indexOf(\"?\");\n  const search = queryIdx === -1 ? \"\" : beforeHash.slice(queryIdx);\n  const pathname = queryIdx === -1 ? beforeHash : beforeHash.slice(0, queryIdx);\n\n  return { pathname, search, hash };\n}\n","// packages/hash-plugin/src/constants.ts\n\nimport type { HashPluginOptions } from \"./types\";\n\nexport const defaultOptions: Required<HashPluginOptions> = {\n  hashPrefix: \"\",\n  base: \"\",\n  forceDeactivate: true,\n};\n\n/**\n * Source identifier for transitions triggered by browser events.\n */\nexport const source = \"popstate\";\n\nexport const LOGGER_CONTEXT = \"hash-plugin\";\n","// packages/hash-plugin/src/hash-utils.ts\n\nimport { safelyEncodePath, safeParseUrl } from \"./browser-env\";\n\nfunction escapeRegExp(str: string): string {\n  return str.replaceAll(/[$()*+.?[\\\\\\]^{|}-]/g, String.raw`\\$&`);\n}\n\nexport function createHashPrefixRegex(hashPrefix: string): RegExp | null {\n  if (!hashPrefix) {\n    return null;\n  }\n\n  return new RegExp(`^#${escapeRegExp(hashPrefix)}`);\n}\n\n/**\n * Extract path from URL hash, stripping hash prefix.\n *\n * @param hash - URL hash (e.g., \"#/path\" or \"#!/path\")\n * @param prefixRegex - Pre-compiled regex for prefix stripping (null if no prefix)\n * @returns Extracted path (e.g., \"/path\")\n */\nexport function extractHashPath(\n  hash: string,\n  prefixRegex: RegExp | null,\n): string {\n  if (hash === \"\" || hash === \"#\") {\n    return \"/\";\n  }\n\n  const path = prefixRegex ? hash.replace(prefixRegex, \"\") : hash.slice(1);\n\n  return path || \"/\";\n}\n\nexport function hashUrlToPath(url: string, prefixRegex: RegExp | null): string {\n  const parsedUrl = safeParseUrl(url);\n  const hashPath = extractHashPath(parsedUrl.hash, prefixRegex);\n\n  return hashPath.includes(\"?\") ? hashPath : hashPath + parsedUrl.search;\n}\n\n/**\n * Build the router-side location string from a hash + query pair.\n *\n * Encodes the hash path via `safelyEncodePath` after stripping the\n * configured prefix, then appends the outer `search` only when the hash\n * path itself does not already carry a `?` — otherwise the outer search\n * would be duplicated (see `url.test.ts` — \"well-formed path (no double '?')\").\n *\n * Used by the `createSafeBrowser` `getLocation` callback both in the\n * production factory and in functional/stress test helpers. Extracting\n * here keeps the production path and test mocks aligned; a regression in\n * this logic previously slipped between the two.\n */\nexport function buildHashLocation(\n  hash: string,\n  search: string,\n  prefixRegex: RegExp | null,\n): string {\n  const hashPath = safelyEncodePath(extractHashPath(hash, prefixRegex));\n\n  return hashPath.includes(\"?\") ? hashPath : hashPath + search;\n}\n","import {\n  createPopstateHandler,\n  createPopstateLifecycle,\n  createStartInterceptor,\n  createReplaceHistoryState,\n  shouldReplaceHistory,\n  updateBrowserState,\n} from \"./browser-env\";\nimport { LOGGER_CONTEXT } from \"./constants\";\nimport { hashUrlToPath } from \"./hash-utils\";\n\nimport type { Browser, SharedFactoryState } from \"./browser-env\";\nimport type { HashPluginOptions } from \"./types\";\nimport type {\n  NavigationOptions,\n  Params,\n  Router,\n  State,\n  Plugin,\n} from \"@real-router/core\";\nimport type { PluginApi } from \"@real-router/core/api\";\n\nexport class HashPlugin {\n  readonly #router: Router;\n  readonly #browser: Browser;\n  readonly #removeStartInterceptor: () => void;\n  readonly #removeExtensions: () => void;\n  readonly #lifecycle: Pick<Plugin, \"onStart\" | \"onStop\" | \"teardown\">;\n\n  constructor(\n    router: Router,\n    api: PluginApi,\n    options: Required<HashPluginOptions>,\n    browser: Browser,\n    prefixRegex: RegExp | null,\n    transitionOptions: {\n      source: string;\n      replace: true;\n      forceDeactivate?: boolean;\n    },\n    shared: SharedFactoryState,\n  ) {\n    this.#router = router;\n    this.#browser = browser;\n\n    this.#removeStartInterceptor = createStartInterceptor(api, browser);\n\n    const urlPrefix = `${options.base}#${options.hashPrefix}`;\n    const pluginBuildUrl = (route: string, params?: Params) =>\n      urlPrefix + router.buildPath(route, params);\n\n    this.#removeExtensions = api.extendRouter({\n      buildUrl: pluginBuildUrl,\n      matchUrl: (url: string) =>\n        api.matchPath(hashUrlToPath(url, prefixRegex)) ?? undefined,\n      replaceHistoryState: createReplaceHistoryState(\n        api,\n        router,\n        browser,\n        pluginBuildUrl,\n        false,\n      ),\n    });\n\n    const handler = createPopstateHandler({\n      router,\n      api,\n      browser,\n      allowNotFound: api.getOptions().allowNotFound,\n      transitionOptions,\n      loggerContext: LOGGER_CONTEXT,\n      buildUrl: pluginBuildUrl,\n    });\n\n    this.#lifecycle = createPopstateLifecycle({\n      browser,\n      shared,\n      handler,\n      cleanup: () => {\n        this.#removeStartInterceptor();\n        this.#removeExtensions();\n      },\n    });\n  }\n\n  getPlugin(): Plugin {\n    return {\n      ...this.#lifecycle,\n\n      onTransitionSuccess: (\n        toState: State,\n        fromState: State | undefined,\n        navOptions: NavigationOptions,\n      ) => {\n        const replaceHistory = shouldReplaceHistory(\n          navOptions,\n          toState,\n          fromState,\n        );\n\n        const url = this.#router.buildUrl(toState.name, toState.params);\n\n        updateBrowserState(toState, url, replaceHistory, this.#browser);\n      },\n    };\n  }\n}\n","import {\n  createOptionsValidator,\n  safeBaseRule,\n  safeHashPrefixRule,\n} from \"./browser-env\";\nimport { LOGGER_CONTEXT, defaultOptions } from \"./constants\";\n\nimport type { HashPluginOptions } from \"./types\";\n\nexport const validateOptions = createOptionsValidator<HashPluginOptions>(\n  defaultOptions,\n  LOGGER_CONTEXT,\n  { base: safeBaseRule, hashPrefix: safeHashPrefixRule },\n);\n","import { getPluginApi } from \"@real-router/core/api\";\n\nimport { createSafeBrowser, normalizeBase } from \"./browser-env\";\nimport { defaultOptions, source } from \"./constants\";\nimport { buildHashLocation, createHashPrefixRegex } from \"./hash-utils\";\nimport { HashPlugin } from \"./plugin\";\nimport { validateOptions } from \"./validation\";\n\nimport type { Browser, SharedFactoryState } from \"./browser-env\";\nimport type { HashPluginOptions } from \"./types\";\nimport type { PluginFactory, Router } from \"@real-router/core\";\n\nexport function hashPluginFactory(\n  opts?: Partial<HashPluginOptions>,\n  browser?: Browser,\n): PluginFactory {\n  validateOptions(opts);\n\n  const definedOpts = opts\n    ? Object.fromEntries(\n        Object.entries(opts).filter(\n          // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime may receive explicit undefined via conditional spreads (exactOptionalPropertyTypes does not apply here)\n          ([, value]) => value !== undefined,\n        ),\n      )\n    : {};\n  const options: Required<HashPluginOptions> = {\n    ...defaultOptions,\n    ...definedOpts,\n  };\n\n  options.base = normalizeBase(options.base);\n\n  const prefixRegex = createHashPrefixRegex(options.hashPrefix);\n  const resolvedBrowser =\n    browser ??\n    createSafeBrowser(\n      () =>\n        buildHashLocation(\n          globalThis.location.hash,\n          globalThis.location.search,\n          prefixRegex,\n        ),\n      \"hash-plugin\",\n    );\n\n  const transitionOptions = {\n    forceDeactivate: options.forceDeactivate,\n    source,\n    replace: true as const,\n  };\n\n  const shared: SharedFactoryState = { removePopStateListener: undefined };\n\n  return function hashPlugin(routerBase) {\n    const plugin = new HashPlugin(\n      routerBase as Router,\n      getPluginApi(routerBase),\n      options,\n      resolvedBrowser,\n      prefixRegex,\n      transitionOptions,\n      shared,\n    );\n\n    return plugin.getPlugin();\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":["isState","RouterError","errorCodes","#router","#browser","#removeStartInterceptor","#removeExtensions","#lifecycle","#warnHashIgnored"],"sources":["../../../../shared/browser-env/detect.ts","../../../../shared/browser-env/history-api.ts","../../../../shared/browser-env/utils.ts","../../../../shared/browser-env/ssr-fallback.ts","../../../type-guards/dist/esm/index.mjs","../../../../shared/browser-env/popstate-utils.ts","../../../../shared/browser-env/validation.ts","../../../../shared/browser-env/safe-browser.ts","../../../../shared/browser-env/popstate-handler.ts","../../../../shared/browser-env/url-context.ts","../../../../shared/browser-env/plugin-utils.ts","../../../../shared/browser-env/url-parsing.ts","../../src/constants.ts","../../src/hash-utils.ts","../../src/plugin.ts","../../src/validation.ts","../../src/factory.ts"],"sourcesContent":["export const isBrowserEnvironment = (): boolean =>\n  typeof globalThis.window !== \"undefined\" && !!globalThis.history;\n","import type { HistoryBrowser } from \"./types.js\";\n\nexport const pushState = (state: unknown, path: string): void => {\n  globalThis.history.pushState(state, \"\", path);\n};\n\nexport const replaceState = (state: unknown, path: string): void => {\n  globalThis.history.replaceState(state, \"\", path);\n};\n\nexport const addPopstateListener: HistoryBrowser[\"addPopstateListener\"] = (\n  fn,\n) => {\n  globalThis.addEventListener(\"popstate\", fn);\n\n  return () => {\n    globalThis.removeEventListener(\"popstate\", fn);\n  };\n};\n\nexport const getHash = (): string => globalThis.location.hash;\n","/**\n * Normalizes base path to canonical form: leading slash, no trailing slash,\n * no repeated slashes. Isolated \"/\" collapses to \"\".\n *\n * @example\n * normalizeBase(\"app\")     // \"/app\"\n * normalizeBase(\"/app/\")   // \"/app\"\n * normalizeBase(\"//app//\") // \"/app\"\n * normalizeBase(\"\")        // \"\"\n * normalizeBase(\"/\")       // \"\"\n */\nexport function normalizeBase(base: string): string {\n  if (!base) {\n    return base;\n  }\n\n  let result = base.replaceAll(/\\/+/g, \"/\");\n\n  if (!result.startsWith(\"/\")) {\n    result = `/${result}`;\n  }\n\n  if (result.length > 1 && result.endsWith(\"/\")) {\n    result = result.slice(0, -1);\n  }\n\n  return result === \"/\" ? \"\" : result;\n}\n\nexport const safelyEncodePath = (path: string): string => {\n  try {\n    return encodeURI(decodeURI(path));\n  } catch (error) {\n    console.warn(`[browser-env] Could not encode path \"${path}\"`, error);\n\n    return path;\n  }\n};\n","import type { HistoryBrowser } from \"./types.js\";\n\nconst NOOP = (): void => {};\n\nexport const createWarnOnce = (context: string) => {\n  let hasWarned = false;\n\n  return (method: string): void => {\n    if (!hasWarned) {\n      console.warn(\n        `[browser-env] Browser API is running in a non-browser environment (context: \"${context}\"). ` +\n          `Method \"${method}\" is a no-op. ` +\n          `This is expected for SSR, but may indicate misconfiguration if you expected browser behavior.`,\n      );\n      hasWarned = true;\n    }\n  };\n};\n\nexport const createHistoryFallbackBrowser = (\n  context: string,\n): HistoryBrowser => {\n  const warnOnce = createWarnOnce(context);\n\n  return {\n    pushState: () => {\n      warnOnce(\"pushState\");\n    },\n    replaceState: () => {\n      warnOnce(\"replaceState\");\n    },\n    addPopstateListener: () => {\n      warnOnce(\"addPopstateListener\");\n\n      return NOOP;\n    },\n    getHash: () => {\n      warnOnce(\"getHash\");\n\n      return \"\";\n    },\n  };\n};\n","const e=[`replace`,`reload`,`force`,`forceDeactivate`,`redirected`];function t(t){if(typeof t!=`object`||!t||Array.isArray(t))return!1;let n=t;for(let t of e){let e=n[t];if(e!==void 0&&typeof e!=`boolean`)return!1}let r=n.signal;return!(r!==void 0&&!(r instanceof AbortSignal))}const n=/\\S/,r=/^[A-Z_a-z][\\w-]*(?:\\.[A-Z_a-z][\\w-]*)*$/;function i(e,t){return TypeError(`[router.${e}] ${t}`)}function a(e){return typeof e==`string`?e===``?!0:e.length>1e4?!1:e.startsWith(`@@`)?!0:r.test(e):!1}function o(e,t=new WeakSet){if(e==null)return!0;let n=typeof e;if(n===`string`||n===`boolean`)return!0;if(n===`number`)return Number.isFinite(e);if(n===`function`||n===`symbol`)return!1;if(Array.isArray(e))return t.has(e)?!1:(t.add(e),e.every(e=>o(e,t)));if(n===`object`){if(t.has(e))return!1;t.add(e);let n=Object.getPrototypeOf(e);return n!==null&&n!==Object.prototype?!1:Object.values(e).every(e=>o(e,t))}return!1}function s(e){if(e==null)return!0;let t=typeof e;return t===`string`||t===`boolean`?!0:t===`number`?Number.isFinite(e):!1}function c(e){if(typeof e!=`object`||!e||Array.isArray(e))return!1;let t=Object.getPrototypeOf(e);if(t!==null&&t!==Object.prototype)return!1;let n=!1;for(let t in e){if(!Object.hasOwn(e,t))continue;let r=e[t];if(!s(r)){let e=typeof r;if(e===`function`||e===`symbol`)return!1;n=!0;break}}return n?o(e):!0}function l(e){if(e==null)return!0;let t=typeof e;return t===`string`||t===`boolean`?!0:t===`number`?Number.isFinite(e):Array.isArray(e)?e.every(e=>{let t=typeof e;return t===`string`||t===`boolean`?!0:t===`number`?Number.isFinite(e):!1}):!1}function u(e){if(typeof e!=`object`||!e||Array.isArray(e))return!1;for(let t in e){if(!Object.hasOwn(e,t))continue;let n=e[t];if(!l(n))return!1}return!0}function d(e){return a(e.name)&&typeof e.path==`string`&&c(e.params)}function f(e){return typeof e!=`object`||!e?!1:d(e)}function p(e){return!(typeof e!=`object`||!e||!d(e))}function m(e){return typeof e==`string`}function h(e){return typeof e==`boolean`}function g(e,t){return e in t}function _(e){return typeof e==`number`?Number.isFinite(e):typeof e==`string`||typeof e==`boolean`}function v(e,t){if(typeof e!=`string`)throw i(t,`Route name must be a string, got ${typeof e}`);if(e!==``){if(!n.test(e))throw i(t,`Route name cannot contain only whitespace`);if(e.length>1e4)throw i(t,`Route name exceeds maximum length of 10000 characters. This is a technical safety limit.`);if(!e.startsWith(`@@`)&&!r.test(e))throw i(t,`Invalid route name \"${e}\". Each segment must start with a letter or underscore, followed by letters, numbers, underscores, or hyphens. Segments are separated by dots (e.g., \"users.profile\").`)}}function y(e){return e===null?`null`:Array.isArray(e)?`array[${e.length}]`:typeof e==`object`?`constructor`in e&&e.constructor.name!==`Object`?e.constructor.name:`object`:typeof e}function b(e,t){if(!f(e))throw TypeError(`[${t}] Invalid state structure: ${y(e)}. Expected State object with name, params, and path properties.`)}export{y as getTypeDescription,h as isBoolean,t as isNavigationOptions,g as isObjKey,c as isParams,u as isParamsStrict,_ as isPrimitiveValue,a as isRouteName,f as isState,p as isStateStrict,m as isString,v as validateRouteName,b as validateState};\n//# sourceMappingURL=index.mjs.map","import { isStateStrict as isState } from \"type-guards\";\n\nimport type { Browser } from \"./types.js\";\nimport type { State, Params } from \"@real-router/core\";\nimport type { PluginApi } from \"@real-router/core/api\";\n\n/**\n * Resolves the popstate event into a navigation-ready `State`.\n *\n * - If `history.state` is a valid router state ({name, params, path} written\n *   by browser-plugin/hash-plugin during their previous navigation), it is\n *   the source of truth — synthesize a fully-typed `State` from it via\n *   `api.makeState`. The synthesized `transition`/`context` fields are\n *   placeholders; the navigation pipeline (`completeTransition` and plugin\n *   claim writes) replaces them.\n *   This branch is mandatory for hash-plugin: `browser.getLocation()`\n *   returns the History pathname, not the hash, so the matchPath fallback\n *   below cannot extract the hash route.\n * - Otherwise (e.g. manually entered URL with no recorded state), fall\n *   back to `api.matchPath(browser.getLocation())`. browser-plugin's\n *   `getLocation` returns the URL pathname — this works.\n * - `undefined` when neither path produces a match.\n *\n * Replaces the previous `{ name, params }` shape so the caller can hand\n * the State directly to `router.navigateToState(state, opts)` and skip\n * the redundant `forwardState`/`buildPath` round-trip in\n * `buildNavigateState` (issue #525).\n */\nexport function getRouteFromEvent(\n  evt: PopStateEvent,\n  api: PluginApi,\n  browser: Browser,\n): State | undefined {\n  if (isState(evt.state)) {\n    return api.makeState(evt.state.name, evt.state.params, evt.state.path);\n  }\n\n  return api.matchPath(browser.getLocation());\n}\n\n/**\n * Updates browser state (pushState or replaceState)\n *\n * @param state - Router state\n * @param url - URL to set\n * @param replace - Whether to replace instead of push\n * @param browser - Browser API instance\n */\nexport function updateBrowserState(\n  state: State,\n  url: string,\n  replace: boolean,\n  browser: Browser,\n): void {\n  const historyState = {\n    name: state.name,\n    params: state.params,\n    path: state.path,\n  };\n\n  if (replace) {\n    browser.replaceState(historyState, url);\n  } else {\n    browser.pushState(historyState, url);\n  }\n}\n\n/**\n * Creates a `updateBrowserState` closure that reuses a single mutable buffer\n * across calls instead of allocating a fresh `{ name, params, path }` object\n * per push/replace.\n *\n * Why: Browsers structured-clone `history.state` synchronously inside\n * `pushState`/`replaceState`, so the caller never sees the buffer escape —\n * it can be safely overwritten before the next call. Eliminates one\n * allocation per navigation on the hot path.\n *\n * Each plugin instance must own its own buffer (do not share across plugins).\n */\nexport function createUpdateBrowserState(): (\n  state: State,\n  url: string,\n  replace: boolean,\n  browser: Browser,\n) => void {\n  const buffer = {\n    name: \"\",\n    params: {} as Params,\n    path: \"\",\n  };\n\n  return (state, url, replace, browser) => {\n    buffer.name = state.name;\n    buffer.params = state.params;\n    buffer.path = state.path;\n\n    if (replace) {\n      browser.replaceState(buffer, url);\n    } else {\n      browser.pushState(buffer, url);\n    }\n  };\n}\n","export interface OptionRule<T> {\n  validate: (value: T) => string | null;\n}\n\nexport type OptionRules<T extends object> = {\n  [K in keyof T]?: OptionRule<NonNullable<T[K]>>;\n};\n\nexport function createOptionsValidator<T extends object>(\n  defaults: Required<T>,\n  loggerContext: string,\n  rules?: OptionRules<T>,\n): (opts: Partial<T> | undefined) => void {\n  return (opts) => {\n    if (!opts) {\n      return;\n    }\n\n    for (const key of Object.keys(opts)) {\n      if (!(key in defaults)) {\n        continue;\n      }\n\n      const value = opts[key as keyof typeof opts];\n\n      if (value === undefined) {\n        continue;\n      }\n\n      const expected = typeof defaults[key as keyof typeof defaults];\n      const actual = typeof value;\n\n      if (actual !== expected) {\n        throw new Error(\n          `[${loggerContext}] Invalid type for '${key}': expected ${expected}, got ${actual}`,\n        );\n      }\n\n      const rule = rules?.[key as keyof T];\n\n      if (rule) {\n        const msg = (rule.validate as (input: unknown) => string | null)(value);\n\n        if (msg !== null) {\n          throw new Error(`[${loggerContext}] Invalid '${key}': ${msg}`);\n        }\n      }\n    }\n  };\n}\n\n// eslint-disable-next-line no-control-regex -- control characters are exactly what this rule rejects\nconst CONTROL_CHARS = /[\\u0000-\\u001F\\u007F]/;\n\nexport const safeBaseRule: OptionRule<string> = {\n  validate: (value) => {\n    if (CONTROL_CHARS.test(value)) {\n      return \"must not contain control characters\";\n    }\n\n    if (value.split(\"/\").includes(\"..\")) {\n      return \"must not contain '..' segments\";\n    }\n\n    return null;\n  },\n};\n\nexport const safeHashPrefixRule: OptionRule<string> = {\n  validate: (value) => {\n    if (CONTROL_CHARS.test(value)) {\n      return \"must not contain control characters\";\n    }\n\n    if (value.includes(\"/\")) {\n      return \"must not contain '/' (slash is added before the path automatically)\";\n    }\n\n    if (value.includes(\"#\")) {\n      return \"must not contain '#' (it is added as the hash delimiter)\";\n    }\n\n    if (value.includes(\"?\")) {\n      return \"must not contain '?' (it conflicts with the query delimiter)\";\n    }\n\n    return null;\n  },\n};\n\nexport const nonNegativeIntegerRule: OptionRule<number> = {\n  validate: (value) => {\n    if (!Number.isFinite(value)) {\n      return `expected finite number, got ${String(value)}`;\n    }\n\n    if (!Number.isInteger(value)) {\n      return `expected integer, got ${String(value)}`;\n    }\n\n    if (value < 0) {\n      return `expected non-negative integer, got ${value}`;\n    }\n\n    return null;\n  },\n};\n","import { isBrowserEnvironment } from \"./detect.js\";\nimport {\n  pushState,\n  replaceState,\n  addPopstateListener,\n  getHash,\n} from \"./history-api.js\";\nimport {\n  createWarnOnce,\n  createHistoryFallbackBrowser,\n} from \"./ssr-fallback.js\";\n\nimport type { Browser } from \"./types.js\";\n\nexport function createSafeBrowser(\n  getLocation: () => string,\n  context: string,\n): Browser {\n  if (isBrowserEnvironment()) {\n    return {\n      pushState,\n      replaceState,\n      addPopstateListener,\n      getLocation,\n      getHash,\n    };\n  }\n\n  const warnOnce = createWarnOnce(context);\n\n  return {\n    ...createHistoryFallbackBrowser(context),\n    getLocation: () => {\n      warnOnce(\"getLocation\");\n\n      return \"\";\n    },\n  };\n}\n","import { errorCodes, RouterError } from \"@real-router/core\";\n\nimport { getRouteFromEvent } from \"./popstate-utils.js\";\n\nimport type { Browser, SharedFactoryState } from \"./types.js\";\nimport type { Params, Plugin, Router } from \"@real-router/core\";\nimport type { PluginApi } from \"@real-router/core/api\";\n\n/**\n * Navigation options used by the popstate handler to trigger a\n * router.navigate() call from a back/forward event. `source` identifies\n * the origin of the transition to downstream context consumers;\n * `replace: true` keeps the history stack in sync with the browser.\n */\nexport interface PopstateTransitionOptions {\n  source: string;\n  replace: true;\n  forceDeactivate?: boolean;\n}\n\nexport interface PopstateHandlerDeps {\n  router: Router;\n  api: PluginApi;\n  browser: Browser;\n  allowNotFound: boolean;\n  transitionOptions: PopstateTransitionOptions;\n  loggerContext: string;\n  buildUrl: (\n    name: string,\n    params?: Params,\n    options?: { hash?: string },\n  ) => string;\n  /**\n   * Decoded hash of the current browser location (no leading \"#\"). Defaults\n   * to a no-op (returns \"\") for plugins that do not participate in URL\n   * fragment tracking — namely hash-plugin, where `#` is the route delimiter.\n   * (#532)\n   */\n  getCurrentHash?: () => string;\n  /**\n   * Decoded hash from the previous transition's `state.context.url.hash`\n   * (no leading \"#\"). Used by the popstate handler to detect hash-only\n   * navigation and add `force: true, hashChange: true` to bypass SAME_STATES.\n   * Defaults to no-op (returns \"\") for hash-plugin. (#532)\n   */\n  getCurrentContextHash?: () => string;\n}\n\n/**\n * Hash augmentation for popstate-driven navigateToState (#532).\n * Returns a partial options object that the caller spreads on top of\n * `deps.transitionOptions`. When the handler is wired without hash support\n * (hash-plugin), both deps default to undefined and an empty object is\n * returned — preserving the legacy behavior for that plugin.\n */\nfunction resolveHashOptions(\n  deps: PopstateHandlerDeps,\n  matchedPath: string,\n): { hash?: string; force?: true; hashChange?: true } {\n  if (!deps.getCurrentHash) {\n    return {};\n  }\n\n  const newHash = deps.getCurrentHash();\n  const prevHash = deps.getCurrentContextHash\n    ? deps.getCurrentContextHash()\n    : \"\";\n  const hashChange =\n    newHash !== prevHash && deps.router.getState()?.path === matchedPath;\n\n  return hashChange\n    ? { hash: newHash, force: true, hashChange: true }\n    : { hash: newHash };\n}\n\nexport function createPopstateHandler(\n  deps: PopstateHandlerDeps,\n): (evt: PopStateEvent) => void {\n  let isTransitioning = false;\n  let deferredEvent: PopStateEvent | null = null;\n\n  function processDeferredEvent(): void {\n    if (deferredEvent) {\n      const evt = deferredEvent;\n\n      deferredEvent = null;\n      console.warn(\n        `[${deps.loggerContext}] Processing deferred popstate event`,\n      );\n      void onPopState(evt);\n    }\n  }\n\n  function rollbackUrlToCurrentState(): void {\n    const currentState = deps.router.getState();\n\n    /* v8 ignore next -- @preserve: router always has state after start(); defensive guard for edge cases */\n    if (!currentState) {\n      return;\n    }\n\n    // Preserve hash on rollback so guard rejection / unmatched URL on\n    // popstate doesn't strip the fragment from the visible URL (#532).\n    const ctxHash = (\n      currentState.context as { url?: { hash?: string } } | undefined\n    )?.url?.hash;\n    const url = deps.buildUrl(\n      currentState.name,\n      currentState.params,\n      ctxHash ? { hash: ctxHash } : undefined,\n    );\n\n    deps.browser.replaceState(currentState, url);\n  }\n\n  function recoverFromCriticalError(error: unknown): void {\n    console.error(\n      `[${deps.loggerContext}] Critical error in onPopState`,\n      error,\n    );\n\n    try {\n      rollbackUrlToCurrentState();\n    } catch (recoveryError) {\n      console.error(\n        `[${deps.loggerContext}] Failed to recover from critical error`,\n        recoveryError,\n      );\n    }\n  }\n\n  async function onPopState(evt: PopStateEvent): Promise<void> {\n    if (isTransitioning) {\n      console.warn(\n        `[${deps.loggerContext}] Transition in progress, deferring popstate event`,\n      );\n      deferredEvent = evt;\n\n      return;\n    }\n\n    isTransitioning = true;\n\n    try {\n      const matched = getRouteFromEvent(evt, deps.api, deps.browser);\n\n      if (matched) {\n        // api.navigateToState — plugin-only entry point. Preserves\n        // matchSourceTrailingSlash output and skips the redundant\n        // forwardState/buildPath round-trip (#525). Hash augmentation (#532)\n        // extracted into resolveHashOptions so this branch stays readable.\n        await deps.api.navigateToState(matched, {\n          ...deps.transitionOptions,\n          ...resolveHashOptions(deps, matched.path),\n        });\n      } else if (deps.allowNotFound) {\n        deps.router.navigateToNotFound(deps.browser.getLocation());\n      } else {\n        // Strict mode — unmatched URL is an error. Emit $$error and sync URL\n        // back to the current router state (no silent fallback to defaultRoute).\n        const err = new RouterError(errorCodes.ROUTE_NOT_FOUND, {\n          path: deps.browser.getLocation(),\n        });\n\n        deps.api.emitTransitionError(err);\n        rollbackUrlToCurrentState();\n      }\n    } catch (error) {\n      if (error instanceof RouterError) {\n        // navigate() already emitted $$error — just sync URL with router state.\n        // Swallow rollback errors: teardown races may remove router.buildUrl\n        // while a popstate event is still queued.\n        try {\n          rollbackUrlToCurrentState();\n        } catch {\n          // noop — nothing safe to do here\n        }\n      } else {\n        recoverFromCriticalError(error);\n      }\n    } finally {\n      isTransitioning = false;\n      processDeferredEvent();\n    }\n  }\n\n  return (evt: PopStateEvent) => void onPopState(evt);\n}\n\nexport interface PopstateLifecycleDeps {\n  browser: Browser;\n  shared: SharedFactoryState;\n  handler: (evt: PopStateEvent) => void;\n  cleanup: () => void;\n}\n\nexport function createPopstateLifecycle(\n  deps: PopstateLifecycleDeps,\n): Pick<Plugin, \"onStart\" | \"onStop\" | \"teardown\"> {\n  return {\n    onStart: () => {\n      if (deps.shared.removePopStateListener) {\n        deps.shared.removePopStateListener();\n      }\n\n      deps.shared.removePopStateListener = deps.browser.addPopstateListener(\n        deps.handler,\n      );\n    },\n\n    onStop: () => {\n      if (deps.shared.removePopStateListener) {\n        deps.shared.removePopStateListener();\n        deps.shared.removePopStateListener = undefined;\n      }\n    },\n\n    teardown: () => {\n      if (deps.shared.removePopStateListener) {\n        deps.shared.removePopStateListener();\n        deps.shared.removePopStateListener = undefined;\n      }\n\n      deps.cleanup();\n    },\n  };\n}\n","/**\n * URL fragment (\"hash\") shared layer (#532).\n *\n * Both URL plugins (navigation-plugin, browser-plugin) claim the `\"url\"`\n * `state.context` namespace and write `UrlContext` on every transition.\n * Mutually exclusive at runtime — only one URL plugin is installed per router.\n *\n * Hash form: decoded, no leading \"#\" — symmetric to `params` (no leading \"?\").\n * Encoding to/from URL form happens at the boundary (URL build / URL parse).\n */\n\nexport interface UrlContext {\n  /** Decoded fragment, no leading \"#\". Empty string when URL has no fragment. */\n  hash: string;\n  /** Whether `hash` differs from the previous transition's `state.context.url.hash`. */\n  hashChanged: boolean;\n}\n\n/**\n * Encode for URL fragment per RFC 3986: preserves sub-delims (`&`, `=`, `?`,\n * `:`, etc.) and the path/query characters that `encodeURI` already leaves\n * alone. Defensively percent-escapes `#` (a stray `#` in a decoded fragment\n * would otherwise terminate the fragment in the rendered URL).\n *\n * `encodeURIComponent` over-encodes RFC-3986 sub-delims (`&` → `%26`) and is\n * therefore wrong for fragments.\n */\nexport function encodeHashFragment(decoded: string): string {\n  return encodeURI(decoded).replaceAll(\"#\", \"%23\");\n}\n\n/**\n * Decode a percent-encoded fragment. Falls back to the raw input on malformed\n * escapes — matches the resilience pattern in scroll-restore.\n */\nexport function decodeHashFragment(encoded: string): string {\n  try {\n    return decodeURIComponent(encoded);\n  } catch {\n    return encoded;\n  }\n}\n\n/**\n * Normalize user-provided hash input: strip a leading \"#\" if present, then\n * decode. Defensive against `<Link hash=\"#section\">` — the prop is documented\n * to accept the fragment name without \"#\", but we accept both gracefully.\n */\nexport function normalizeHashInput(input: string): string {\n  const stripped = input.startsWith(\"#\") ? input.slice(1) : input;\n\n  return decodeHashFragment(stripped);\n}\n\n/**\n * Read the current browser hash in decoded form, no leading \"#\".\n * Accepts any object with a `getHash()` method — works for both `Browser`\n * (History API) and `NavigationBrowser` (Navigation API). SSR-safe via the\n * abstractions, which return `\"\"` outside a real browser.\n */\nexport function getDecodedHash(browser: { getHash: () => string }): string {\n  const raw = browser.getHash();\n\n  if (!raw) {\n    return \"\";\n  }\n\n  const stripped = raw.startsWith(\"#\") ? raw.slice(1) : raw;\n\n  return decodeHashFragment(stripped);\n}\n","import { encodeHashFragment, normalizeHashInput } from \"./url-context.js\";\n\nimport type {\n  NavigationOptions,\n  Params,\n  Router,\n  State,\n} from \"@real-router/core\";\nimport type { PluginApi } from \"@real-router/core/api\";\n\nexport interface LocationSource {\n  getLocation: () => string;\n}\n\n/**\n * Minimal browser surface needed by `createReplaceHistoryState`.\n *\n * Both `Browser` (History API) and navigation-plugin's `NavigationBrowser`\n * (Navigation API) satisfy this structurally — the function never needs\n * `pushState`/`addPopstateListener`, only the replace path.\n */\nexport interface ReplaceStateBrowser {\n  replaceState: (state: unknown, url: string) => void;\n  getHash: () => string;\n}\n\n/**\n * Hash override option for `replaceHistoryState` (#532). Tri-state semantics:\n *   `undefined`  — preserve the current browser hash (legacy behavior, default)\n *   `\"\"`         — explicitly clear the fragment\n *   non-empty    — explicitly set the fragment (decoded form, no leading \"#\")\n */\nexport interface ReplaceHistoryStateOptions {\n  hash?: string;\n}\n\nexport function createStartInterceptor(\n  api: PluginApi,\n  browser: LocationSource,\n): () => void {\n  return api.addInterceptor(\"start\", (next, path) =>\n    next(path ?? browser.getLocation()),\n  );\n}\n\nexport function createReplaceHistoryState(\n  api: PluginApi,\n  router: Router,\n  browser: ReplaceStateBrowser,\n  buildUrl: (\n    name: string,\n    params?: Params,\n    options?: ReplaceHistoryStateOptions,\n  ) => string,\n  preserveHash = true,\n): (\n  name: string,\n  params?: Params,\n  options?: ReplaceHistoryStateOptions,\n) => void {\n  // Reusable buffer — browsers structured-clone state synchronously inside\n  // replaceState, so the buffer never escapes. Eliminates one allocation per\n  // navigation on the hot path. (Mirrors createUpdateBrowserState.)\n  const buffer = {\n    name: \"\",\n    params: {} as Params,\n    path: \"\",\n  };\n\n  return (\n    name: string,\n    params: Params = {},\n    options?: ReplaceHistoryStateOptions,\n  ) => {\n    const state = api.buildState(name, params);\n\n    if (!state) {\n      throw new Error(\n        `[real-router] Cannot replace state: route \"${name}\" is not found`,\n      );\n    }\n\n    const builtState = api.makeState(\n      state.name,\n      state.params,\n      router.buildPath(state.name, state.params),\n      {\n        params: state.meta,\n      },\n    );\n\n    // Tri-state hash semantics (#532):\n    //   options.hash === undefined → preserve (legacy behavior, controlled by\n    //                                preserveHash flag — true for browser/\n    //                                navigation plugins, false for hash-plugin)\n    //   options.hash === \"\"        → explicitly clear\n    //   options.hash === \"value\"   → explicitly set\n    let hashSegment: string;\n\n    if (options?.hash !== undefined) {\n      const norm = normalizeHashInput(options.hash);\n\n      hashSegment = norm ? `#${encodeHashFragment(norm)}` : \"\";\n    } else if (preserveHash) {\n      hashSegment = browser.getHash();\n    } else {\n      hashSegment = \"\";\n    }\n\n    // Pass hash through buildUrl when the plugin understands it (avoids\n    // double-append). Hash-plugin's buildUrl ignores the option and warns,\n    // so call without options here for semantic clarity — but the result is\n    // identical because hashSegment is \"\" in that branch (preserveHash=false).\n    const url = buildUrl(name, params) + hashSegment;\n\n    buffer.name = builtState.name;\n    buffer.params = builtState.params;\n    buffer.path = builtState.path;\n\n    browser.replaceState(buffer, url);\n  };\n}\n\nexport function shouldReplaceHistory(\n  navOptions: NavigationOptions,\n  toState: State,\n  fromState: State | undefined,\n): boolean {\n  if (navOptions.replace === true) {\n    return true;\n  }\n\n  if (!fromState) {\n    return navOptions.replace !== false;\n  }\n\n  return !!navOptions.reload && toState.path === fromState.path;\n}\n","export interface ParsedUrl {\n  pathname: string;\n  search: string;\n  hash: string;\n}\n\n/**\n * Scheme-agnostic URL parser.\n *\n * Extracts `pathname`, `search`, and `hash` from any string — absolute\n * (`scheme://authority/path?q#h`), path-relative (`/path?q#h`), or opaque\n * (`data:...`, `javascript:...`). Never throws, never returns null.\n *\n * Routing does not care about scheme or authority, only about the path part.\n * This keeps `browser-plugin`, `navigation-plugin`, and `hash-plugin` working\n * in Electron (`file://`, `app://`), Tauri (`tauri://`, `https://`), and any\n * other webview that may ship with non-HTTP origins. See issue #496.\n */\nexport function safeParseUrl(url: string): ParsedUrl {\n  let rest = url;\n\n  const schemeIdx = rest.indexOf(\"://\");\n\n  if (schemeIdx !== -1) {\n    const authorityStart = schemeIdx + 3;\n    let pathStart = rest.length;\n\n    for (let i = authorityStart; i < rest.length; i++) {\n      const ch = rest[i];\n\n      if (ch === \"/\" || ch === \"?\" || ch === \"#\") {\n        pathStart = i;\n\n        break;\n      }\n    }\n\n    rest = pathStart === rest.length ? \"/\" : rest.slice(pathStart);\n\n    if (rest.startsWith(\"?\") || rest.startsWith(\"#\")) {\n      rest = `/${rest}`;\n    }\n  }\n\n  const hashIdx = rest.indexOf(\"#\");\n  const hash = hashIdx === -1 ? \"\" : rest.slice(hashIdx);\n  const beforeHash = hashIdx === -1 ? rest : rest.slice(0, hashIdx);\n\n  const queryIdx = beforeHash.indexOf(\"?\");\n  const search = queryIdx === -1 ? \"\" : beforeHash.slice(queryIdx);\n  const pathname = queryIdx === -1 ? beforeHash : beforeHash.slice(0, queryIdx);\n\n  return { pathname, search, hash };\n}\n","// packages/hash-plugin/src/constants.ts\n\nimport type { HashPluginOptions } from \"./types\";\n\nexport const defaultOptions: Required<HashPluginOptions> = {\n  hashPrefix: \"\",\n  base: \"\",\n  forceDeactivate: true,\n};\n\n/**\n * Source identifier for transitions triggered by browser events.\n */\nexport const source = \"popstate\";\n\nexport const LOGGER_CONTEXT = \"hash-plugin\";\n","// packages/hash-plugin/src/hash-utils.ts\n\nimport { safelyEncodePath, safeParseUrl } from \"./browser-env\";\n\nfunction escapeRegExp(str: string): string {\n  return str.replaceAll(/[$()*+.?[\\\\\\]^{|}-]/g, String.raw`\\$&`);\n}\n\nexport function createHashPrefixRegex(hashPrefix: string): RegExp | null {\n  if (!hashPrefix) {\n    return null;\n  }\n\n  return new RegExp(`^#${escapeRegExp(hashPrefix)}`);\n}\n\n/**\n * Extract path from URL hash, stripping hash prefix.\n *\n * @param hash - URL hash (e.g., \"#/path\" or \"#!/path\")\n * @param prefixRegex - Pre-compiled regex for prefix stripping (null if no prefix)\n * @returns Extracted path (e.g., \"/path\")\n */\nexport function extractHashPath(\n  hash: string,\n  prefixRegex: RegExp | null,\n): string {\n  if (hash === \"\" || hash === \"#\") {\n    return \"/\";\n  }\n\n  const path = prefixRegex ? hash.replace(prefixRegex, \"\") : hash.slice(1);\n\n  return path || \"/\";\n}\n\nexport function hashUrlToPath(url: string, prefixRegex: RegExp | null): string {\n  const parsedUrl = safeParseUrl(url);\n  const hashPath = extractHashPath(parsedUrl.hash, prefixRegex);\n\n  return hashPath.includes(\"?\") ? hashPath : hashPath + parsedUrl.search;\n}\n\n/**\n * Build the router-side location string from a hash + query pair.\n *\n * Encodes the hash path via `safelyEncodePath` after stripping the\n * configured prefix, then appends the outer `search` only when the hash\n * path itself does not already carry a `?` — otherwise the outer search\n * would be duplicated (see `url.test.ts` — \"well-formed path (no double '?')\").\n *\n * Used by the `createSafeBrowser` `getLocation` callback both in the\n * production factory and in functional/stress test helpers. Extracting\n * here keeps the production path and test mocks aligned; a regression in\n * this logic previously slipped between the two.\n */\nexport function buildHashLocation(\n  hash: string,\n  search: string,\n  prefixRegex: RegExp | null,\n): string {\n  const hashPath = safelyEncodePath(extractHashPath(hash, prefixRegex));\n\n  return hashPath.includes(\"?\") ? hashPath : hashPath + search;\n}\n","import {\n  createPopstateHandler,\n  createPopstateLifecycle,\n  createStartInterceptor,\n  createReplaceHistoryState,\n  shouldReplaceHistory,\n  updateBrowserState,\n} from \"./browser-env\";\nimport { LOGGER_CONTEXT } from \"./constants\";\nimport { hashUrlToPath } from \"./hash-utils\";\n\nimport type { Browser, SharedFactoryState } from \"./browser-env\";\nimport type { HashPluginOptions } from \"./types\";\nimport type {\n  NavigationOptions,\n  Params,\n  Router,\n  State,\n  Plugin,\n} from \"@real-router/core\";\nimport type { PluginApi } from \"@real-router/core/api\";\n\nexport class HashPlugin {\n  readonly #router: Router;\n  readonly #browser: Browser;\n  readonly #removeStartInterceptor: () => void;\n  readonly #removeExtensions: () => void;\n  readonly #lifecycle: Pick<Plugin, \"onStart\" | \"onStop\" | \"teardown\">;\n  readonly #warnHashIgnored!: () => void;\n\n  constructor(\n    router: Router,\n    api: PluginApi,\n    options: Required<HashPluginOptions>,\n    browser: Browser,\n    prefixRegex: RegExp | null,\n    transitionOptions: {\n      source: string;\n      replace: true;\n      forceDeactivate?: boolean;\n    },\n    shared: SharedFactoryState,\n  ) {\n    this.#router = router;\n    this.#browser = browser;\n\n    this.#removeStartInterceptor = createStartInterceptor(api, browser);\n\n    // Hash limitation warn-once (#532). hash-plugin uses `#` as the route\n    // delimiter, so URL fragments are structurally incompatible. Plugin\n    // accepts the `hash` option for typing parity with browser/navigation\n    // plugins, ignores it, and emits a single console.warn the first time\n    // any consumer surfaces a hash. Existing `createWarnOnce` in browser-env\n    // is SSR-specific (different signature) — inline pattern here.\n    let hashWarned = false;\n    const warnHashIgnored = (): void => {\n      if (hashWarned) {\n        return;\n      }\n\n      hashWarned = true;\n      console.warn(\n        \"[@real-router/hash-plugin] `hash` option is ignored — `#` is reserved for the route delimiter. \" +\n          \"URL fragments are not supported with hash-plugin; use @real-router/browser-plugin or \" +\n          \"@real-router/navigation-plugin if you need them.\",\n      );\n    };\n\n    const urlPrefix = `${options.base}#${options.hashPrefix}`;\n    const pluginBuildUrl = (\n      route: string,\n      params?: Params,\n      opts?: { hash?: string },\n    ) => {\n      if (opts?.hash !== undefined) {\n        warnHashIgnored();\n      }\n\n      return urlPrefix + router.buildPath(route, params);\n    };\n\n    this.#warnHashIgnored = warnHashIgnored;\n\n    this.#removeExtensions = api.extendRouter({\n      buildUrl: pluginBuildUrl,\n      matchUrl: (url: string) =>\n        api.matchPath(hashUrlToPath(url, prefixRegex)) ?? undefined,\n      replaceHistoryState: createReplaceHistoryState(\n        api,\n        router,\n        browser,\n        pluginBuildUrl,\n        false,\n      ),\n    });\n\n    const handler = createPopstateHandler({\n      router,\n      api,\n      browser,\n      allowNotFound: api.getOptions().allowNotFound,\n      transitionOptions,\n      loggerContext: LOGGER_CONTEXT,\n      buildUrl: pluginBuildUrl,\n    });\n\n    this.#lifecycle = createPopstateLifecycle({\n      browser,\n      shared,\n      handler,\n      cleanup: () => {\n        this.#removeStartInterceptor();\n        this.#removeExtensions();\n      },\n    });\n  }\n\n  getPlugin(): Plugin {\n    return {\n      ...this.#lifecycle,\n\n      onTransitionSuccess: (\n        toState: State,\n        fromState: State | undefined,\n        navOptions: NavigationOptions,\n      ) => {\n        // Hash limitation (#532): warn once if a consumer programmatically\n        // requested a fragment via `router.navigate(..., { hash })`.\n        if (navOptions.hash !== undefined) {\n          this.#warnHashIgnored();\n        }\n\n        const replaceHistory = shouldReplaceHistory(\n          navOptions,\n          toState,\n          fromState,\n        );\n\n        const url = this.#router.buildUrl(toState.name, toState.params);\n\n        updateBrowserState(toState, url, replaceHistory, this.#browser);\n      },\n    };\n  }\n}\n","import {\n  createOptionsValidator,\n  safeBaseRule,\n  safeHashPrefixRule,\n} from \"./browser-env\";\nimport { LOGGER_CONTEXT, defaultOptions } from \"./constants\";\n\nimport type { HashPluginOptions } from \"./types\";\n\nexport const validateOptions = createOptionsValidator<HashPluginOptions>(\n  defaultOptions,\n  LOGGER_CONTEXT,\n  { base: safeBaseRule, hashPrefix: safeHashPrefixRule },\n);\n","import { getPluginApi } from \"@real-router/core/api\";\n\nimport { createSafeBrowser, normalizeBase } from \"./browser-env\";\nimport { defaultOptions, source } from \"./constants\";\nimport { buildHashLocation, createHashPrefixRegex } from \"./hash-utils\";\nimport { HashPlugin } from \"./plugin\";\nimport { validateOptions } from \"./validation\";\n\nimport type { Browser, SharedFactoryState } from \"./browser-env\";\nimport type { HashPluginOptions } from \"./types\";\nimport type { PluginFactory, Router } from \"@real-router/core\";\n\nexport function hashPluginFactory(\n  opts?: Partial<HashPluginOptions>,\n  browser?: Browser,\n): PluginFactory {\n  validateOptions(opts);\n\n  const definedOpts = opts\n    ? Object.fromEntries(\n        Object.entries(opts).filter(\n          // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime may receive explicit undefined via conditional spreads (exactOptionalPropertyTypes does not apply here)\n          ([, value]) => value !== undefined,\n        ),\n      )\n    : {};\n  const options: Required<HashPluginOptions> = {\n    ...defaultOptions,\n    ...definedOpts,\n  };\n\n  options.base = normalizeBase(options.base);\n\n  const prefixRegex = createHashPrefixRegex(options.hashPrefix);\n  const resolvedBrowser =\n    browser ??\n    createSafeBrowser(\n      () =>\n        buildHashLocation(\n          globalThis.location.hash,\n          globalThis.location.search,\n          prefixRegex,\n        ),\n      \"hash-plugin\",\n    );\n\n  const transitionOptions = {\n    forceDeactivate: options.forceDeactivate,\n    source,\n    replace: true as const,\n  };\n\n  const shared: SharedFactoryState = { removePopStateListener: undefined };\n\n  return function hashPlugin(routerBase) {\n    const plugin = new HashPlugin(\n      routerBase as Router,\n      getPluginApi(routerBase),\n      options,\n      resolvedBrowser,\n      prefixRegex,\n      transitionOptions,\n      shared,\n    );\n\n    return plugin.getPlugin();\n  };\n}\n"],"mappings":"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"}

package/dist/esm/index.d.mts

@@ -1,4 +1,5 @@
 import { Params, PluginFactory, State } from "@real-router/core";
+import { Params as Params$1, State as State$1 } from "@real-router/types";
 
 //#region ../../shared/browser-env/types.d.ts
 interface HistoryBrowser {
@@ -40,81 +41,6 @@ interface HashPluginOptions {
 //#region src/factory.d.ts
 declare function hashPluginFactory(opts?: Partial<HashPluginOptions>, browser?: Browser): PluginFactory;
 //#endregion
-//#region ../core-types/dist/esm/index.d.mts
-type TransitionPhase = "deactivating" | "activating";
-type TransitionReason = "success" | "blocked" | "cancelled" | "error";
-interface TransitionMeta {
-  phase: TransitionPhase;
-  reason: TransitionReason;
-  reload?: boolean;
-  redirected?: boolean;
-  from?: string;
-  blocker?: string;
-  segments: {
-    deactivated: string[];
-    activated: string[];
-    intersection: string;
-  };
-}
-/**
- * Empty interface extended by plugins via module augmentation to declare
- * typed `state.context.<namespace>` fields.
- *
- * @description
- * Plugins add typed context namespaces by augmenting this interface:
- *
- * ```typescript
- * declare module "@real-router/types" {
- *   interface StateContext {
- *     navigation: { direction: "forward" | "back" | "navigate" };
- *   }
- * }
- * ```
- *
- * After augmentation, `state.context.navigation` becomes typed. The intersection
- * with `Record<string, unknown>` in {@link State.context} keeps the type open,
- * so plugins that don't augment can still write arbitrary namespaces.
- *
- * @see {@link State.context}
- * @see {@link ContextNamespaceClaim}
- */
-interface StateContext {}
-interface State$1<P extends Params$1 = Params$1> {
-  name: string;
-  params: P;
-  path: string;
-  transition: TransitionMeta;
-  /**
-   * Plugin-extensible per-route data, attached by plugins via
-   * `PluginApi.claimContextNamespace()` + `claim.write(state, value)`.
-   *
-   * @description
-   * Required field — always present as at least `{}` on every State created by
-   * the router (via `makeState`, `navigateToNotFound`, or `cloneRouter`).
-   *
-   * Typed extensions come from plugins augmenting {@link StateContext} through
-   * module augmentation. The intersection with `Record<string, unknown>` allows
-   * untyped namespaces (inline plugins, tests, or plugins that skip augmentation)
-   * to write without compile errors.
-   *
-   * The `context` object itself is **not frozen** — this is intentional, so
-   * plugins can attach data without cloning state. Core structural fields
-   * (`name`, `params`, `path`, `transition`) remain immutable via shallow
-   * `Object.freeze(state)`.
-   *
-   * @see {@link StateContext}
-   */
-  context: StateContext & Record<string, unknown>;
-}
-interface Params$1 {
-  [key: string]: string | string[] | number | number[] | boolean | boolean[] | Params$1 | Params$1[] | Record<string, string | number | boolean> | null | undefined;
-} //#endregion
-//#region src/limits.d.ts
-/**
- * Configuration for router resource limits.
- * Controls maximum allowed values for various router operations to prevent resource exhaustion.
- */
-//#endregion
 //#region ../type-guards/dist/esm/index.d.mts
 /**
  * Enhanced type guard for State with deep validation.
@@ -141,24 +67,50 @@ declare function isStateStrict<P extends Params$1 = Params$1>(value: unknown): v
 /**
  * Module augmentation for real-router.
  * Extends Router interface with hash plugin methods.
+ *
+ * NavigationOptions augmentation (#532) keeps the `hash` / `hashChange` keys
+ * known to TypeScript even when only hash-plugin is installed — runtime
+ * silently ignores them with a one-time warn.
  */
+declare module "@real-router/types" {
+  interface NavigationOptions {
+    /**
+     * URL fragment override (decoded, no leading "#"). Ignored by hash-plugin
+     * (URL fragments are structurally incompatible with hash routing); see
+     * `Router.buildUrl`. (#532)
+     */
+    hash?: string;
+    /** @internal — not used by hash-plugin. */
+    hashChange?: boolean;
+  }
+}
 declare module "@real-router/core" {
   interface Router {
     /**
      * Builds full URL for a route with base path and hash prefix.
      * Added by hash plugin.
+     *
+     * The optional `hash` option exists for typing parity with browser-plugin
+     * and navigation-plugin (#532). hash-plugin uses `#` as the route
+     * delimiter, so the option is silently ignored at runtime and a
+     * one-time `console.warn` is emitted.
      */
-    buildUrl: (name: string, params?: Params) => string;
+    buildUrl(name: string, params?: Params, options?: {
+      hash?: string;
+    }): string;
     /**
      * Matches URL and returns corresponding state.
      * Added by hash plugin.
      */
-    matchUrl: (url: string) => State | undefined;
+    matchUrl(url: string): State | undefined;
     /**
      * Replaces current history state without triggering navigation.
-     * Added by hash plugin.
+     * Added by hash plugin. The optional `hash` option is ignored (see
+     * `buildUrl`).
      */
-    replaceHistoryState: (name: string, params?: Params) => void;
+    replaceHistoryState(name: string, params?: Params, options?: {
+      hash?: string;
+    }): void;
     start(path?: string): Promise<State>;
   }
 } //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":["ArrayFormat","BooleanFormat","NullFormat","NumberFormat","QueryParamsOptions","arrayFormat","booleanFormat","nullFormat","numberFormat","QueryParamsMode","ParamSource","ParamTypeMap","Record","RouteTreeStateMeta","RouteParams","key","RouteTreeState","P","name","params","meta","Unsubscribe","SimpleState","Params","TransitionPhase","TransitionReason","TransitionMeta","phase","reason","reload","redirected","from","blocker","segments","deactivated","activated","intersection","StateContext","State","path","transition","context","StateMetaInput","RouterError","Error","code","segment","redirect","setCode","setErrorInstance","err","setAdditionalFields","fields","hasField","getField","toJSON","NavigationOptions","AbortSignal","replace","force","forceDeactivate","signal","LimitsConfig","maxDependencies","maxPlugins","maxListeners","warnListeners","maxEventDepth","maxLifecycleHandlers","LogLevel","LogLevelConfig","LogCallback","level","message","args","LoggerConfig","callback","callbackIgnoresLevel","DefaultRouteCallback","K","Dependencies","getDependency","ForwardToCallback","DefaultParamsCallback","Options","Partial","defaultRoute","defaultParams","trailingSlash","urlParamsEncoding","queryParamsMode","queryParams","allowNotFound","rewritePathOnMatch","logger","limits","GuardFn","Promise","toState","fromState","DefaultDependencies","Config","decoders","encoders","forwardMap","Plugin","onStart","onStop","onTransitionStart","onTransitionLeaveApprove","onTransitionCancel","onTransitionError","onTransitionSuccess","opts","teardown","SubscribeState","route","previousRoute","SubscribeFn","state","LeaveState","nextRoute","LeaveFn","Listener","next","val","error","complete","Subscription","unsubscribe","Navigator","navigate","routeName","routeParams","options","getState","isActiveRoute","strictEquality","ignoreQueryParams","canNavigateTo","subscribe","listener","subscribeLeave","isLeaveApproved","Router","D","PluginFactory","buildPath","getPreviousState","areStatesEqual","state1","state2","shouldUpdateNode","nodeName","isActive","start","startPath","stop","dispose","usePlugin","plugins","navigateToDefault","navigateToNotFound","router","GuardFnFactory","Route","canActivate","canDeactivate","forwardTo","children","encodeParams","stateParams","decodeParams","pathParams","RouteConfigUpdate","PluginMethod","EventName","EventsKeys","ErrorCodeValues","ErrorCodeKeys","EventToPluginMap","ROUTER_START","ROUTER_STOP","TRANSITION_START","TRANSITION_LEAVE_APPROVE","TRANSITION_CANCEL","TRANSITION_SUCCESS","TRANSITION_ERROR","EventToNameMap","EventMethodMap","ErrorCodeToValueMap","ROUTER_NOT_STARTED","NO_START_PATH_OR_STATE","ROUTER_ALREADY_STARTED","ROUTE_NOT_FOUND","SAME_STATES","CANNOT_DEACTIVATE","CANNOT_ACTIVATE","TRANSITION_ERR","TRANSITION_CANCELLED","ROUTER_DISPOSED","PLUGIN_CONFLICT","CONTEXT_NAMESPACE_ALREADY_CLAIMED","InterceptableMethodMap","forwardState","add","routes","parent","InterceptorFn","M","Parameters","ReturnType","ContextNamespaceClaim","T","write","value","release","PluginApi","E","makeState","buildState","matchPath","navigateToState","setRootPath","rootPath","getRootPath","addEventListener","eventName","cb","buildNavigationState","getOptions","getTree","addInterceptor","method","fn","extendRouter","extensions","emitTransitionError","claimContextNamespace","namespace","getRouteConfig","RoutesApi","remove","update","updates","clear","has","get","DependenciesApi","getAll","set","setAll","deps","reset","LifecycleApi","addActivateGuard","canActivateHandler","addDeactivateGuard","canDeactivateHandler","removeActivateGuard","removeDeactivateGuard","NavigationOptions","Params","State","isNavigationOptions","value","isRouteName","name","isState","P","isStateStrict","isString","isBoolean","isObjKey","T","Extract","key","obj","isPrimitiveValue","isParams","isParamsStrict","validateRouteName","methodName","validateState","state","method","getTypeDescription"],"sources":["../../../../shared/browser-env/types.ts","../../src/types.ts","../../src/factory.ts","../../../core-types/dist/esm/index.d.mts","../../../type-guards/dist/esm/index.d.mts","../../src/index.ts"],"mappings":";;;UAAiB,cAAA;EACf,SAAA,GAAY,KAAA,WAAgB,IAAA;EAC5B,YAAA,GAAe,KAAA,WAAgB,IAAA;EAC/B,mBAAA,GAAsB,EAAA,GAAK,GAAA,EAAK,aAAA;EAChC,OAAA;AAAA;AAAA,UAGe,OAAA,SAAgB,cAAA;EAC/B,WAAA;AAAA;;;;;;;UCFe,iBAAA;EDNc;;;;;ECY7B,UAAA;EDVA;;;;;ECiBA,IAAA;EDhBsB;;;;AAIxB;ECmBE,eAAA;AAAA;;;iBCdc,iBAAA,CACd,IAAA,GAAO,OAAA,CAAQ,iBAAA,GACf,OAAA,GAAU,OAAA,GACT,aAAA;;;KC4CEwB,eAAAA;AAAAA,KACAC,gBAAAA;AAAAA,UACKC,cAAAA;EACRC,KAAAA,EAAOH,eAAAA;EACPI,MAAAA,EAAQH,gBAAAA;EACRI,MAAAA;EACAC,UAAAA;EACAC,IAAAA;EACAC,OAAAA;EACAC,QAAAA;IACEC,WAAAA;IACAC,SAAAA;IACAC,YAAAA;EAAAA;AAAAA;;;;;;;;;;;;;;;;AAAY;;;;;AAyBM;;UAAZC,YAAAA;AAAAA,UACAC,OAAAA,WAAgBf,QAAAA,GAASA,QAAAA;EACjCL,IAAAA;EACAC,MAAAA,EAAQF,CAAAA;EACRsB,IAAAA;EACAC,UAAAA,EAAYd,cAAAA;EAqBYd;;;;;;;;;;;;;;;;;AAqLJ;;;EArLpB6B,OAAAA,EAASJ,YAAAA,GAAezB,MAAAA;AAAAA;AAAAA,UAuLhBW,QAAAA;EAAAA,CACPR,GAAAA,yEAA4EQ,QAAAA,GAASA,QAAAA,KAAWX,MAAAA;AAAAA;AAAAA;;;;;;;;;AAtP9E;;;;;;;;;;iBCqBJkQ,aAAAA,WAAwBR,QAAAA,GAASA,QAAAA,CAAAA,CAAQG,KAAAA,YAAiBA,KAAAA,IAASF,OAAAA,CAAMM,CAAAA;AAAAA;;;;;;ADV1E;;;;;;;;YEjDJ,MAAA;ILpBV;;;;IKyBE,QAAA,GAAW,IAAA,UAAc,MAAA,GAAS,MAAA;ILxBT;;;;IK8BzB,QAAA,GAAW,GAAA,aAAgB,KAAA;IL1Bd;;;;IKgCb,mBAAA,GAAsB,IAAA,UAAc,MAAA,GAAS,MAAA;IAE7C,KAAA,CAAM,IAAA,YAAgB,OAAA,CAAQ,KAAA;EAAA;AAAA"}
+{"version":3,"file":"index.d.mts","names":["NavigationOptions","Params","State","isNavigationOptions","value","isRouteName","name","isState","P","isStateStrict","isString","isBoolean","isObjKey","T","Extract","key","obj","isPrimitiveValue","isParams","isParamsStrict","validateRouteName","methodName","validateState","state","method","getTypeDescription"],"sources":["../../../../shared/browser-env/types.ts","../../src/types.ts","../../src/factory.ts","../../../type-guards/dist/esm/index.d.mts","../../src/index.ts"],"mappings":";;;;UAAiB,cAAA;EACf,SAAA,GAAY,KAAA,WAAgB,IAAA;EAC5B,YAAA,GAAe,KAAA,WAAgB,IAAA;EAC/B,mBAAA,GAAsB,EAAA,GAAK,GAAA,EAAK,aAAA;EAChC,OAAA;AAAA;AAAA,UAGe,OAAA,SAAgB,cAAA;EAC/B,WAAA;AAAA;;;;;;;UCFe,iBAAA;EDNA;;;;;ECYf,UAAA;EDX4B;;;;;ECkB5B,IAAA;EDhB2B;;;;;ECuB3B,eAAA;AAAA;;;iBCdc,iBAAA,CACd,IAAA,GAAO,OAAA,CAAQ,iBAAA,GACf,OAAA,GAAU,OAAA,GACT,aAAA;;;;;;;;;;;;;;;iBCkEcS,aAAAA,WAAwBR,QAAAA,GAASA,QAAAA,CAAAA,CAAQG,KAAAA,YAAiBA,KAAAA,IAASF,OAAAA,CAAMM,CAAAA;AAAAA;;;;;;;;;AHjF1F;;;;;;;;AAAA;EAAA,UI0BY,iBAAA;IJvBV;;;;;II6BE,IAAA;IJ5BK;II8BL,UAAA;EAAA;AAAA;AAAA;EAAA,UAKQ,MAAA;;;;AHjCZ;;;;;;IG2CI,QAAA,CACE,IAAA,UACA,MAAA,GAAS,MAAA,EACT,OAAA;MAAY,IAAA;IAAA;;;;AFxClB;IE+CI,QAAA,CAAS,GAAA,WAAc,KAAA;IF/CM;;;;;IEsD7B,mBAAA,CACE,IAAA,UACA,MAAA,GAAS,MAAA,EACT,OAAA;MAAY,IAAA;IAAA;IAGd,KAAA,CAAM,IAAA,YAAgB,OAAA,CAAQ,KAAA;EAAA;AAAA"}

package/dist/esm/index.mjs

@@ -1,2 +1,2 @@
-import{getPluginApi as e}from"@real-router/core/api";import{RouterError as t,errorCodes as n}from"@real-router/core";const r=()=>globalThis.window!==void 0&&!!globalThis.history,i=(e,t)=>{globalThis.history.pushState(e,``,t)},a=(e,t)=>{globalThis.history.replaceState(e,``,t)},o=e=>(globalThis.addEventListener(`popstate`,e),()=>{globalThis.removeEventListener(`popstate`,e)}),s=()=>globalThis.location.hash;function c(e){if(!e)return e;let t=e.replaceAll(/\/+/g,`/`);return t.startsWith(`/`)||(t=`/${t}`),t.length>1&&t.endsWith(`/`)&&(t=t.slice(0,-1)),t===`/`?``:t}const l=e=>{try{return encodeURI(decodeURI(e))}catch(t){return console.warn(`[browser-env] Could not encode path "${e}"`,t),e}},u=()=>{},d=e=>{let t=!1;return n=>{t||=(console.warn(`[browser-env] Browser API is running in a non-browser environment (context: "${e}"). Method "${n}" is a no-op. This is expected for SSR, but may indicate misconfiguration if you expected browser behavior.`),!0)}},f=e=>{let t=d(e);return{pushState:()=>{t(`pushState`)},replaceState:()=>{t(`replaceState`)},addPopstateListener:()=>(t(`addPopstateListener`),u),getHash:()=>(t(`getHash`),``)}},p=/^[A-Z_a-z][\w-]*(?:\.[A-Z_a-z][\w-]*)*$/;function m(e){return typeof e==`string`?e===``?!0:e.length>1e4?!1:e.startsWith(`@@`)?!0:p.test(e):!1}function h(e,t=new WeakSet){if(e==null)return!0;let n=typeof e;if(n===`string`||n===`boolean`)return!0;if(n===`number`)return Number.isFinite(e);if(n===`function`||n===`symbol`)return!1;if(Array.isArray(e))return t.has(e)?!1:(t.add(e),e.every(e=>h(e,t)));if(n===`object`){if(t.has(e))return!1;t.add(e);let n=Object.getPrototypeOf(e);return n!==null&&n!==Object.prototype?!1:Object.values(e).every(e=>h(e,t))}return!1}function g(e){if(e==null)return!0;let t=typeof e;return t===`string`||t===`boolean`?!0:t===`number`?Number.isFinite(e):!1}function _(e){if(typeof e!=`object`||!e||Array.isArray(e))return!1;let t=Object.getPrototypeOf(e);if(t!==null&&t!==Object.prototype)return!1;let n=!1;for(let t in e){if(!Object.hasOwn(e,t))continue;let r=e[t];if(!g(r)){let e=typeof r;if(e===`function`||e===`symbol`)return!1;n=!0;break}}return n?h(e):!0}function v(e){return m(e.name)&&typeof e.path==`string`&&_(e.params)}function y(e){return!(typeof e!=`object`||!e||!v(e))}function b(e,t,n){return y(e.state)?t.makeState(e.state.name,e.state.params,e.state.path):t.matchPath(n.getLocation())}function x(e,t,n,r){let i={name:e.name,params:e.params,path:e.path};n?r.replaceState(i,t):r.pushState(i,t)}function S(e,t,n){return r=>{if(r)for(let i of Object.keys(r)){if(!(i in e))continue;let a=r[i];if(a===void 0)continue;let o=typeof e[i],s=typeof a;if(s!==o)throw Error(`[${t}] Invalid type for '${i}': expected ${o}, got ${s}`);let c=n?.[i];if(c){let e=c.validate(a);if(e!==null)throw Error(`[${t}] Invalid '${i}': ${e}`)}}}}const C=/[\u0000-\u001F\u007F]/,w={validate:e=>C.test(e)?`must not contain control characters`:e.split(`/`).includes(`..`)?`must not contain '..' segments`:null},T={validate:e=>C.test(e)?`must not contain control characters`:e.includes(`/`)?`must not contain '/' (slash is added before the path automatically)`:e.includes(`#`)?`must not contain '#' (it is added as the hash delimiter)`:e.includes(`?`)?`must not contain '?' (it conflicts with the query delimiter)`:null};function E(e,t){if(r())return{pushState:i,replaceState:a,addPopstateListener:o,getLocation:e,getHash:s};let n=d(t);return{...f(t),getLocation:()=>(n(`getLocation`),``)}}function D(e){let r=!1,i=null;function a(){if(i){let t=i;i=null,console.warn(`[${e.loggerContext}] Processing deferred popstate event`),c(t)}}function o(){let t=e.router.getState();if(!t)return;let n=e.buildUrl(t.name,t.params);e.browser.replaceState(t,n)}function s(t){console.error(`[${e.loggerContext}] Critical error in onPopState`,t);try{o()}catch(t){console.error(`[${e.loggerContext}] Failed to recover from critical error`,t)}}async function c(c){if(r){console.warn(`[${e.loggerContext}] Transition in progress, deferring popstate event`),i=c;return}r=!0;try{let r=b(c,e.api,e.browser);if(r)await e.api.navigateToState(r,e.transitionOptions);else if(e.allowNotFound)e.router.navigateToNotFound(e.browser.getLocation());else{let r=new t(n.ROUTE_NOT_FOUND,{path:e.browser.getLocation()});e.api.emitTransitionError(r),o()}}catch(e){if(e instanceof t)try{o()}catch{}else s(e)}finally{r=!1,a()}}return e=>void c(e)}function O(e){return{onStart:()=>{e.shared.removePopStateListener&&e.shared.removePopStateListener(),e.shared.removePopStateListener=e.browser.addPopstateListener(e.handler)},onStop:()=>{e.shared.removePopStateListener&&(e.shared.removePopStateListener(),e.shared.removePopStateListener=void 0)},teardown:()=>{e.shared.removePopStateListener&&(e.shared.removePopStateListener(),e.shared.removePopStateListener=void 0),e.cleanup()}}}function k(e,t){return e.addInterceptor(`start`,(e,n)=>e(n??t.getLocation()))}function A(e,t,n,r,i=!0){let a={name:``,params:{},path:``};return(o,s={})=>{let c=e.buildState(o,s);if(!c)throw Error(`[real-router] Cannot replace state: route "${o}" is not found`);let l=e.makeState(c.name,c.params,t.buildPath(c.name,c.params),{params:c.meta}),u=i?n.getHash():``,d=r(o,s)+u;a.name=l.name,a.params=l.params,a.path=l.path,n.replaceState(a,d)}}function j(e,t,n){return e.replace===!0?!0:n?!!e.reload&&t.path===n.path:e.replace!==!1}function M(e){let t=e,n=t.indexOf(`://`);if(n!==-1){let e=n+3,r=t.length;for(let n=e;n<t.length;n++){let e=t[n];if(e===`/`||e===`?`||e===`#`){r=n;break}}t=r===t.length?`/`:t.slice(r),(t.startsWith(`?`)||t.startsWith(`#`))&&(t=`/${t}`)}let r=t.indexOf(`#`),i=r===-1?``:t.slice(r),a=r===-1?t:t.slice(0,r),o=a.indexOf(`?`),s=o===-1?``:a.slice(o);return{pathname:o===-1?a:a.slice(0,o),search:s,hash:i}}const N={hashPrefix:``,base:``,forceDeactivate:!0},P=`hash-plugin`;function F(e){return e.replaceAll(/[$()*+.?[\\\]^{|}-]/g,String.raw`\$&`)}function I(e){return e?RegExp(`^#${F(e)}`):null}function L(e,t){return e===``||e===`#`?`/`:(t?e.replace(t,``):e.slice(1))||`/`}function R(e,t){let n=M(e),r=L(n.hash,t);return r.includes(`?`)?r:r+n.search}function z(e,t,n){let r=l(L(e,n));return r.includes(`?`)?r:r+t}var B=class{#e;#t;#n;#r;#i;constructor(e,t,n,r,i,a,o){this.#e=e,this.#t=r,this.#n=k(t,r);let s=`${n.base}#${n.hashPrefix}`,c=(t,n)=>s+e.buildPath(t,n);this.#r=t.extendRouter({buildUrl:c,matchUrl:e=>t.matchPath(R(e,i))??void 0,replaceHistoryState:A(t,e,r,c,!1)}),this.#i=O({browser:r,shared:o,handler:D({router:e,api:t,browser:r,allowNotFound:t.getOptions().allowNotFound,transitionOptions:a,loggerContext:P,buildUrl:c}),cleanup:()=>{this.#n(),this.#r()}})}getPlugin(){return{...this.#i,onTransitionSuccess:(e,t,n)=>{let r=j(n,e,t);x(e,this.#e.buildUrl(e.name,e.params),r,this.#t)}}}};const V=S(N,P,{base:w,hashPrefix:T});function H(t,n){V(t);let r=t?Object.fromEntries(Object.entries(t).filter(([,e])=>e!==void 0)):{},i={...N,...r};i.base=c(i.base);let a=I(i.hashPrefix),o=n??E(()=>z(globalThis.location.hash,globalThis.location.search,a),`hash-plugin`),s={forceDeactivate:i.forceDeactivate,source:`popstate`,replace:!0},l={removePopStateListener:void 0};return function(t){return new B(t,e(t),i,o,a,s,l).getPlugin()}}export{H as hashPluginFactory,y as isState};
+import{getPluginApi as e}from"@real-router/core/api";import{RouterError as t,errorCodes as n}from"@real-router/core";const r=()=>globalThis.window!==void 0&&!!globalThis.history,i=(e,t)=>{globalThis.history.pushState(e,``,t)},a=(e,t)=>{globalThis.history.replaceState(e,``,t)},o=e=>(globalThis.addEventListener(`popstate`,e),()=>{globalThis.removeEventListener(`popstate`,e)}),s=()=>globalThis.location.hash;function c(e){if(!e)return e;let t=e.replaceAll(/\/+/g,`/`);return t.startsWith(`/`)||(t=`/${t}`),t.length>1&&t.endsWith(`/`)&&(t=t.slice(0,-1)),t===`/`?``:t}const l=e=>{try{return encodeURI(decodeURI(e))}catch(t){return console.warn(`[browser-env] Could not encode path "${e}"`,t),e}},u=()=>{},d=e=>{let t=!1;return n=>{t||=(console.warn(`[browser-env] Browser API is running in a non-browser environment (context: "${e}"). Method "${n}" is a no-op. This is expected for SSR, but may indicate misconfiguration if you expected browser behavior.`),!0)}},f=e=>{let t=d(e);return{pushState:()=>{t(`pushState`)},replaceState:()=>{t(`replaceState`)},addPopstateListener:()=>(t(`addPopstateListener`),u),getHash:()=>(t(`getHash`),``)}},p=/^[A-Z_a-z][\w-]*(?:\.[A-Z_a-z][\w-]*)*$/;function m(e){return typeof e==`string`?e===``?!0:e.length>1e4?!1:e.startsWith(`@@`)?!0:p.test(e):!1}function h(e,t=new WeakSet){if(e==null)return!0;let n=typeof e;if(n===`string`||n===`boolean`)return!0;if(n===`number`)return Number.isFinite(e);if(n===`function`||n===`symbol`)return!1;if(Array.isArray(e))return t.has(e)?!1:(t.add(e),e.every(e=>h(e,t)));if(n===`object`){if(t.has(e))return!1;t.add(e);let n=Object.getPrototypeOf(e);return n!==null&&n!==Object.prototype?!1:Object.values(e).every(e=>h(e,t))}return!1}function g(e){if(e==null)return!0;let t=typeof e;return t===`string`||t===`boolean`?!0:t===`number`?Number.isFinite(e):!1}function _(e){if(typeof e!=`object`||!e||Array.isArray(e))return!1;let t=Object.getPrototypeOf(e);if(t!==null&&t!==Object.prototype)return!1;let n=!1;for(let t in e){if(!Object.hasOwn(e,t))continue;let r=e[t];if(!g(r)){let e=typeof r;if(e===`function`||e===`symbol`)return!1;n=!0;break}}return n?h(e):!0}function v(e){return m(e.name)&&typeof e.path==`string`&&_(e.params)}function y(e){return!(typeof e!=`object`||!e||!v(e))}function b(e,t,n){return y(e.state)?t.makeState(e.state.name,e.state.params,e.state.path):t.matchPath(n.getLocation())}function x(e,t,n,r){let i={name:e.name,params:e.params,path:e.path};n?r.replaceState(i,t):r.pushState(i,t)}function S(e,t,n){return r=>{if(r)for(let i of Object.keys(r)){if(!(i in e))continue;let a=r[i];if(a===void 0)continue;let o=typeof e[i],s=typeof a;if(s!==o)throw Error(`[${t}] Invalid type for '${i}': expected ${o}, got ${s}`);let c=n?.[i];if(c){let e=c.validate(a);if(e!==null)throw Error(`[${t}] Invalid '${i}': ${e}`)}}}}const C=/[\u0000-\u001F\u007F]/,w={validate:e=>C.test(e)?`must not contain control characters`:e.split(`/`).includes(`..`)?`must not contain '..' segments`:null},T={validate:e=>C.test(e)?`must not contain control characters`:e.includes(`/`)?`must not contain '/' (slash is added before the path automatically)`:e.includes(`#`)?`must not contain '#' (it is added as the hash delimiter)`:e.includes(`?`)?`must not contain '?' (it conflicts with the query delimiter)`:null};function E(e,t){if(r())return{pushState:i,replaceState:a,addPopstateListener:o,getLocation:e,getHash:s};let n=d(t);return{...f(t),getLocation:()=>(n(`getLocation`),``)}}function D(e,t){if(!e.getCurrentHash)return{};let n=e.getCurrentHash();return n!==(e.getCurrentContextHash?e.getCurrentContextHash():``)&&e.router.getState()?.path===t?{hash:n,force:!0,hashChange:!0}:{hash:n}}function O(e){let r=!1,i=null;function a(){if(i){let t=i;i=null,console.warn(`[${e.loggerContext}] Processing deferred popstate event`),c(t)}}function o(){let t=e.router.getState();if(!t)return;let n=t.context?.url?.hash,r=e.buildUrl(t.name,t.params,n?{hash:n}:void 0);e.browser.replaceState(t,r)}function s(t){console.error(`[${e.loggerContext}] Critical error in onPopState`,t);try{o()}catch(t){console.error(`[${e.loggerContext}] Failed to recover from critical error`,t)}}async function c(c){if(r){console.warn(`[${e.loggerContext}] Transition in progress, deferring popstate event`),i=c;return}r=!0;try{let r=b(c,e.api,e.browser);if(r)await e.api.navigateToState(r,{...e.transitionOptions,...D(e,r.path)});else if(e.allowNotFound)e.router.navigateToNotFound(e.browser.getLocation());else{let r=new t(n.ROUTE_NOT_FOUND,{path:e.browser.getLocation()});e.api.emitTransitionError(r),o()}}catch(e){if(e instanceof t)try{o()}catch{}else s(e)}finally{r=!1,a()}}return e=>void c(e)}function k(e){return{onStart:()=>{e.shared.removePopStateListener&&e.shared.removePopStateListener(),e.shared.removePopStateListener=e.browser.addPopstateListener(e.handler)},onStop:()=>{e.shared.removePopStateListener&&(e.shared.removePopStateListener(),e.shared.removePopStateListener=void 0)},teardown:()=>{e.shared.removePopStateListener&&(e.shared.removePopStateListener(),e.shared.removePopStateListener=void 0),e.cleanup()}}}function A(e){return encodeURI(e).replaceAll(`#`,`%23`)}function j(e){try{return decodeURIComponent(e)}catch{return e}}function M(e){return j(e.startsWith(`#`)?e.slice(1):e)}function N(e,t){return e.addInterceptor(`start`,(e,n)=>e(n??t.getLocation()))}function P(e,t,n,r,i=!0){let a={name:``,params:{},path:``};return(o,s={},c)=>{let l=e.buildState(o,s);if(!l)throw Error(`[real-router] Cannot replace state: route "${o}" is not found`);let u=e.makeState(l.name,l.params,t.buildPath(l.name,l.params),{params:l.meta}),d;if(c?.hash!==void 0){let e=M(c.hash);d=e?`#${A(e)}`:``}else d=i?n.getHash():``;let f=r(o,s)+d;a.name=u.name,a.params=u.params,a.path=u.path,n.replaceState(a,f)}}function F(e,t,n){return e.replace===!0?!0:n?!!e.reload&&t.path===n.path:e.replace!==!1}function I(e){let t=e,n=t.indexOf(`://`);if(n!==-1){let e=n+3,r=t.length;for(let n=e;n<t.length;n++){let e=t[n];if(e===`/`||e===`?`||e===`#`){r=n;break}}t=r===t.length?`/`:t.slice(r),(t.startsWith(`?`)||t.startsWith(`#`))&&(t=`/${t}`)}let r=t.indexOf(`#`),i=r===-1?``:t.slice(r),a=r===-1?t:t.slice(0,r),o=a.indexOf(`?`),s=o===-1?``:a.slice(o);return{pathname:o===-1?a:a.slice(0,o),search:s,hash:i}}const L={hashPrefix:``,base:``,forceDeactivate:!0},R=`hash-plugin`;function z(e){return e.replaceAll(/[$()*+.?[\\\]^{|}-]/g,String.raw`\$&`)}function B(e){return e?RegExp(`^#${z(e)}`):null}function V(e,t){return e===``||e===`#`?`/`:(t?e.replace(t,``):e.slice(1))||`/`}function H(e,t){let n=I(e),r=V(n.hash,t);return r.includes(`?`)?r:r+n.search}function U(e,t,n){let r=l(V(e,n));return r.includes(`?`)?r:r+t}var W=class{#e;#t;#n;#r;#i;#a;constructor(e,t,n,r,i,a,o){this.#e=e,this.#t=r,this.#n=N(t,r);let s=!1,c=()=>{s||(s=!0,console.warn("[@real-router/hash-plugin] `hash` option is ignored — `#` is reserved for the route delimiter. URL fragments are not supported with hash-plugin; use @real-router/browser-plugin or @real-router/navigation-plugin if you need them."))},l=`${n.base}#${n.hashPrefix}`,u=(t,n,r)=>(r?.hash!==void 0&&c(),l+e.buildPath(t,n));this.#a=c,this.#r=t.extendRouter({buildUrl:u,matchUrl:e=>t.matchPath(H(e,i))??void 0,replaceHistoryState:P(t,e,r,u,!1)}),this.#i=k({browser:r,shared:o,handler:O({router:e,api:t,browser:r,allowNotFound:t.getOptions().allowNotFound,transitionOptions:a,loggerContext:R,buildUrl:u}),cleanup:()=>{this.#n(),this.#r()}})}getPlugin(){return{...this.#i,onTransitionSuccess:(e,t,n)=>{n.hash!==void 0&&this.#a();let r=F(n,e,t);x(e,this.#e.buildUrl(e.name,e.params),r,this.#t)}}}};const G=S(L,R,{base:w,hashPrefix:T});function K(t,n){G(t);let r=t?Object.fromEntries(Object.entries(t).filter(([,e])=>e!==void 0)):{},i={...L,...r};i.base=c(i.base);let a=B(i.hashPrefix),o=n??E(()=>U(globalThis.location.hash,globalThis.location.search,a),`hash-plugin`),s={forceDeactivate:i.forceDeactivate,source:`popstate`,replace:!0},l={removePopStateListener:void 0};return function(t){return new W(t,e(t),i,o,a,s,l).getPlugin()}}export{K as hashPluginFactory,y as isState};
 //# sourceMappingURL=index.mjs.map

package/dist/esm/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":["isState","#router","#browser","#removeStartInterceptor","#removeExtensions","#lifecycle"],"sources":["../../../../shared/browser-env/detect.ts","../../../../shared/browser-env/history-api.ts","../../../../shared/browser-env/utils.ts","../../../../shared/browser-env/ssr-fallback.ts","../../../type-guards/dist/esm/index.mjs","../../../../shared/browser-env/popstate-utils.ts","../../../../shared/browser-env/validation.ts","../../../../shared/browser-env/safe-browser.ts","../../../../shared/browser-env/popstate-handler.ts","../../../../shared/browser-env/plugin-utils.ts","../../../../shared/browser-env/url-parsing.ts","../../src/constants.ts","../../src/hash-utils.ts","../../src/plugin.ts","../../src/validation.ts","../../src/factory.ts"],"sourcesContent":["export const isBrowserEnvironment = (): boolean =>\n  typeof globalThis.window !== \"undefined\" && !!globalThis.history;\n","import type { HistoryBrowser } from \"./types.js\";\n\nexport const pushState = (state: unknown, path: string): void => {\n  globalThis.history.pushState(state, \"\", path);\n};\n\nexport const replaceState = (state: unknown, path: string): void => {\n  globalThis.history.replaceState(state, \"\", path);\n};\n\nexport const addPopstateListener: HistoryBrowser[\"addPopstateListener\"] = (\n  fn,\n) => {\n  globalThis.addEventListener(\"popstate\", fn);\n\n  return () => {\n    globalThis.removeEventListener(\"popstate\", fn);\n  };\n};\n\nexport const getHash = (): string => globalThis.location.hash;\n","/**\n * Normalizes base path to canonical form: leading slash, no trailing slash,\n * no repeated slashes. Isolated \"/\" collapses to \"\".\n *\n * @example\n * normalizeBase(\"app\")     // \"/app\"\n * normalizeBase(\"/app/\")   // \"/app\"\n * normalizeBase(\"//app//\") // \"/app\"\n * normalizeBase(\"\")        // \"\"\n * normalizeBase(\"/\")       // \"\"\n */\nexport function normalizeBase(base: string): string {\n  if (!base) {\n    return base;\n  }\n\n  let result = base.replaceAll(/\\/+/g, \"/\");\n\n  if (!result.startsWith(\"/\")) {\n    result = `/${result}`;\n  }\n\n  if (result.length > 1 && result.endsWith(\"/\")) {\n    result = result.slice(0, -1);\n  }\n\n  return result === \"/\" ? \"\" : result;\n}\n\nexport const safelyEncodePath = (path: string): string => {\n  try {\n    return encodeURI(decodeURI(path));\n  } catch (error) {\n    console.warn(`[browser-env] Could not encode path \"${path}\"`, error);\n\n    return path;\n  }\n};\n","import type { HistoryBrowser } from \"./types.js\";\n\nconst NOOP = (): void => {};\n\nexport const createWarnOnce = (context: string) => {\n  let hasWarned = false;\n\n  return (method: string): void => {\n    if (!hasWarned) {\n      console.warn(\n        `[browser-env] Browser API is running in a non-browser environment (context: \"${context}\"). ` +\n          `Method \"${method}\" is a no-op. ` +\n          `This is expected for SSR, but may indicate misconfiguration if you expected browser behavior.`,\n      );\n      hasWarned = true;\n    }\n  };\n};\n\nexport const createHistoryFallbackBrowser = (\n  context: string,\n): HistoryBrowser => {\n  const warnOnce = createWarnOnce(context);\n\n  return {\n    pushState: () => {\n      warnOnce(\"pushState\");\n    },\n    replaceState: () => {\n      warnOnce(\"replaceState\");\n    },\n    addPopstateListener: () => {\n      warnOnce(\"addPopstateListener\");\n\n      return NOOP;\n    },\n    getHash: () => {\n      warnOnce(\"getHash\");\n\n      return \"\";\n    },\n  };\n};\n","const e=[`replace`,`reload`,`force`,`forceDeactivate`,`redirected`];function t(t){if(typeof t!=`object`||!t||Array.isArray(t))return!1;let n=t;for(let t of e){let e=n[t];if(e!==void 0&&typeof e!=`boolean`)return!1}let r=n.signal;return!(r!==void 0&&!(r instanceof AbortSignal))}const n=/\\S/,r=/^[A-Z_a-z][\\w-]*(?:\\.[A-Z_a-z][\\w-]*)*$/;function i(e,t){return TypeError(`[router.${e}] ${t}`)}function a(e){return typeof e==`string`?e===``?!0:e.length>1e4?!1:e.startsWith(`@@`)?!0:r.test(e):!1}function o(e,t=new WeakSet){if(e==null)return!0;let n=typeof e;if(n===`string`||n===`boolean`)return!0;if(n===`number`)return Number.isFinite(e);if(n===`function`||n===`symbol`)return!1;if(Array.isArray(e))return t.has(e)?!1:(t.add(e),e.every(e=>o(e,t)));if(n===`object`){if(t.has(e))return!1;t.add(e);let n=Object.getPrototypeOf(e);return n!==null&&n!==Object.prototype?!1:Object.values(e).every(e=>o(e,t))}return!1}function s(e){if(e==null)return!0;let t=typeof e;return t===`string`||t===`boolean`?!0:t===`number`?Number.isFinite(e):!1}function c(e){if(typeof e!=`object`||!e||Array.isArray(e))return!1;let t=Object.getPrototypeOf(e);if(t!==null&&t!==Object.prototype)return!1;let n=!1;for(let t in e){if(!Object.hasOwn(e,t))continue;let r=e[t];if(!s(r)){let e=typeof r;if(e===`function`||e===`symbol`)return!1;n=!0;break}}return n?o(e):!0}function l(e){if(e==null)return!0;let t=typeof e;return t===`string`||t===`boolean`?!0:t===`number`?Number.isFinite(e):Array.isArray(e)?e.every(e=>{let t=typeof e;return t===`string`||t===`boolean`?!0:t===`number`?Number.isFinite(e):!1}):!1}function u(e){if(typeof e!=`object`||!e||Array.isArray(e))return!1;for(let t in e){if(!Object.hasOwn(e,t))continue;let n=e[t];if(!l(n))return!1}return!0}function d(e){return a(e.name)&&typeof e.path==`string`&&c(e.params)}function f(e){return typeof e!=`object`||!e?!1:d(e)}function p(e){return!(typeof e!=`object`||!e||!d(e))}function m(e){return typeof e==`string`}function h(e){return typeof e==`boolean`}function g(e,t){return e in t}function _(e){return typeof e==`number`?Number.isFinite(e):typeof e==`string`||typeof e==`boolean`}function v(e,t){if(typeof e!=`string`)throw i(t,`Route name must be a string, got ${typeof e}`);if(e!==``){if(!n.test(e))throw i(t,`Route name cannot contain only whitespace`);if(e.length>1e4)throw i(t,`Route name exceeds maximum length of 10000 characters. This is a technical safety limit.`);if(!e.startsWith(`@@`)&&!r.test(e))throw i(t,`Invalid route name \"${e}\". Each segment must start with a letter or underscore, followed by letters, numbers, underscores, or hyphens. Segments are separated by dots (e.g., \"users.profile\").`)}}function y(e){return e===null?`null`:Array.isArray(e)?`array[${e.length}]`:typeof e==`object`?`constructor`in e&&e.constructor.name!==`Object`?e.constructor.name:`object`:typeof e}function b(e,t){if(!f(e))throw TypeError(`[${t}] Invalid state structure: ${y(e)}. Expected State object with name, params, and path properties.`)}export{y as getTypeDescription,h as isBoolean,t as isNavigationOptions,g as isObjKey,c as isParams,u as isParamsStrict,_ as isPrimitiveValue,a as isRouteName,f as isState,p as isStateStrict,m as isString,v as validateRouteName,b as validateState};\n//# sourceMappingURL=index.mjs.map","import { isStateStrict as isState } from \"type-guards\";\n\nimport type { Browser } from \"./types.js\";\nimport type { State, Params } from \"@real-router/core\";\nimport type { PluginApi } from \"@real-router/core/api\";\n\n/**\n * Resolves the popstate event into a navigation-ready `State`.\n *\n * - If `history.state` is a valid router state ({name, params, path} written\n *   by browser-plugin/hash-plugin during their previous navigation), it is\n *   the source of truth — synthesize a fully-typed `State` from it via\n *   `api.makeState`. The synthesized `transition`/`context` fields are\n *   placeholders; the navigation pipeline (`completeTransition` and plugin\n *   claim writes) replaces them.\n *   This branch is mandatory for hash-plugin: `browser.getLocation()`\n *   returns the History pathname, not the hash, so the matchPath fallback\n *   below cannot extract the hash route.\n * - Otherwise (e.g. manually entered URL with no recorded state), fall\n *   back to `api.matchPath(browser.getLocation())`. browser-plugin's\n *   `getLocation` returns the URL pathname — this works.\n * - `undefined` when neither path produces a match.\n *\n * Replaces the previous `{ name, params }` shape so the caller can hand\n * the State directly to `router.navigateToState(state, opts)` and skip\n * the redundant `forwardState`/`buildPath` round-trip in\n * `buildNavigateState` (issue #525).\n */\nexport function getRouteFromEvent(\n  evt: PopStateEvent,\n  api: PluginApi,\n  browser: Browser,\n): State | undefined {\n  if (isState(evt.state)) {\n    return api.makeState(evt.state.name, evt.state.params, evt.state.path);\n  }\n\n  return api.matchPath(browser.getLocation());\n}\n\n/**\n * Updates browser state (pushState or replaceState)\n *\n * @param state - Router state\n * @param url - URL to set\n * @param replace - Whether to replace instead of push\n * @param browser - Browser API instance\n */\nexport function updateBrowserState(\n  state: State,\n  url: string,\n  replace: boolean,\n  browser: Browser,\n): void {\n  const historyState = {\n    name: state.name,\n    params: state.params,\n    path: state.path,\n  };\n\n  if (replace) {\n    browser.replaceState(historyState, url);\n  } else {\n    browser.pushState(historyState, url);\n  }\n}\n\n/**\n * Creates a `updateBrowserState` closure that reuses a single mutable buffer\n * across calls instead of allocating a fresh `{ name, params, path }` object\n * per push/replace.\n *\n * Why: Browsers structured-clone `history.state` synchronously inside\n * `pushState`/`replaceState`, so the caller never sees the buffer escape —\n * it can be safely overwritten before the next call. Eliminates one\n * allocation per navigation on the hot path.\n *\n * Each plugin instance must own its own buffer (do not share across plugins).\n */\nexport function createUpdateBrowserState(): (\n  state: State,\n  url: string,\n  replace: boolean,\n  browser: Browser,\n) => void {\n  const buffer = {\n    name: \"\",\n    params: {} as Params,\n    path: \"\",\n  };\n\n  return (state, url, replace, browser) => {\n    buffer.name = state.name;\n    buffer.params = state.params;\n    buffer.path = state.path;\n\n    if (replace) {\n      browser.replaceState(buffer, url);\n    } else {\n      browser.pushState(buffer, url);\n    }\n  };\n}\n","export interface OptionRule<T> {\n  validate: (value: T) => string | null;\n}\n\nexport type OptionRules<T extends object> = {\n  [K in keyof T]?: OptionRule<NonNullable<T[K]>>;\n};\n\nexport function createOptionsValidator<T extends object>(\n  defaults: Required<T>,\n  loggerContext: string,\n  rules?: OptionRules<T>,\n): (opts: Partial<T> | undefined) => void {\n  return (opts) => {\n    if (!opts) {\n      return;\n    }\n\n    for (const key of Object.keys(opts)) {\n      if (!(key in defaults)) {\n        continue;\n      }\n\n      const value = opts[key as keyof typeof opts];\n\n      if (value === undefined) {\n        continue;\n      }\n\n      const expected = typeof defaults[key as keyof typeof defaults];\n      const actual = typeof value;\n\n      if (actual !== expected) {\n        throw new Error(\n          `[${loggerContext}] Invalid type for '${key}': expected ${expected}, got ${actual}`,\n        );\n      }\n\n      const rule = rules?.[key as keyof T];\n\n      if (rule) {\n        const msg = (rule.validate as (input: unknown) => string | null)(value);\n\n        if (msg !== null) {\n          throw new Error(`[${loggerContext}] Invalid '${key}': ${msg}`);\n        }\n      }\n    }\n  };\n}\n\n// eslint-disable-next-line no-control-regex -- control characters are exactly what this rule rejects\nconst CONTROL_CHARS = /[\\u0000-\\u001F\\u007F]/;\n\nexport const safeBaseRule: OptionRule<string> = {\n  validate: (value) => {\n    if (CONTROL_CHARS.test(value)) {\n      return \"must not contain control characters\";\n    }\n\n    if (value.split(\"/\").includes(\"..\")) {\n      return \"must not contain '..' segments\";\n    }\n\n    return null;\n  },\n};\n\nexport const safeHashPrefixRule: OptionRule<string> = {\n  validate: (value) => {\n    if (CONTROL_CHARS.test(value)) {\n      return \"must not contain control characters\";\n    }\n\n    if (value.includes(\"/\")) {\n      return \"must not contain '/' (slash is added before the path automatically)\";\n    }\n\n    if (value.includes(\"#\")) {\n      return \"must not contain '#' (it is added as the hash delimiter)\";\n    }\n\n    if (value.includes(\"?\")) {\n      return \"must not contain '?' (it conflicts with the query delimiter)\";\n    }\n\n    return null;\n  },\n};\n\nexport const nonNegativeIntegerRule: OptionRule<number> = {\n  validate: (value) => {\n    if (!Number.isFinite(value)) {\n      return `expected finite number, got ${String(value)}`;\n    }\n\n    if (!Number.isInteger(value)) {\n      return `expected integer, got ${String(value)}`;\n    }\n\n    if (value < 0) {\n      return `expected non-negative integer, got ${value}`;\n    }\n\n    return null;\n  },\n};\n","import { isBrowserEnvironment } from \"./detect.js\";\nimport {\n  pushState,\n  replaceState,\n  addPopstateListener,\n  getHash,\n} from \"./history-api.js\";\nimport {\n  createWarnOnce,\n  createHistoryFallbackBrowser,\n} from \"./ssr-fallback.js\";\n\nimport type { Browser } from \"./types.js\";\n\nexport function createSafeBrowser(\n  getLocation: () => string,\n  context: string,\n): Browser {\n  if (isBrowserEnvironment()) {\n    return {\n      pushState,\n      replaceState,\n      addPopstateListener,\n      getLocation,\n      getHash,\n    };\n  }\n\n  const warnOnce = createWarnOnce(context);\n\n  return {\n    ...createHistoryFallbackBrowser(context),\n    getLocation: () => {\n      warnOnce(\"getLocation\");\n\n      return \"\";\n    },\n  };\n}\n","import { errorCodes, RouterError } from \"@real-router/core\";\n\nimport { getRouteFromEvent } from \"./popstate-utils.js\";\n\nimport type { Browser, SharedFactoryState } from \"./types.js\";\nimport type { Params, Plugin, Router } from \"@real-router/core\";\nimport type { PluginApi } from \"@real-router/core/api\";\n\n/**\n * Navigation options used by the popstate handler to trigger a\n * router.navigate() call from a back/forward event. `source` identifies\n * the origin of the transition to downstream context consumers;\n * `replace: true` keeps the history stack in sync with the browser.\n */\nexport interface PopstateTransitionOptions {\n  source: string;\n  replace: true;\n  forceDeactivate?: boolean;\n}\n\nexport interface PopstateHandlerDeps {\n  router: Router;\n  api: PluginApi;\n  browser: Browser;\n  allowNotFound: boolean;\n  transitionOptions: PopstateTransitionOptions;\n  loggerContext: string;\n  buildUrl: (name: string, params?: Params) => string;\n}\n\nexport function createPopstateHandler(\n  deps: PopstateHandlerDeps,\n): (evt: PopStateEvent) => void {\n  let isTransitioning = false;\n  let deferredEvent: PopStateEvent | null = null;\n\n  function processDeferredEvent(): void {\n    if (deferredEvent) {\n      const evt = deferredEvent;\n\n      deferredEvent = null;\n      console.warn(\n        `[${deps.loggerContext}] Processing deferred popstate event`,\n      );\n      void onPopState(evt);\n    }\n  }\n\n  function rollbackUrlToCurrentState(): void {\n    const currentState = deps.router.getState();\n\n    /* v8 ignore next -- @preserve: router always has state after start(); defensive guard for edge cases */\n    if (!currentState) {\n      return;\n    }\n\n    const url = deps.buildUrl(currentState.name, currentState.params);\n\n    deps.browser.replaceState(currentState, url);\n  }\n\n  function recoverFromCriticalError(error: unknown): void {\n    console.error(\n      `[${deps.loggerContext}] Critical error in onPopState`,\n      error,\n    );\n\n    try {\n      rollbackUrlToCurrentState();\n    } catch (recoveryError) {\n      console.error(\n        `[${deps.loggerContext}] Failed to recover from critical error`,\n        recoveryError,\n      );\n    }\n  }\n\n  async function onPopState(evt: PopStateEvent): Promise<void> {\n    if (isTransitioning) {\n      console.warn(\n        `[${deps.loggerContext}] Transition in progress, deferring popstate event`,\n      );\n      deferredEvent = evt;\n\n      return;\n    }\n\n    isTransitioning = true;\n\n    try {\n      const matched = getRouteFromEvent(evt, deps.api, deps.browser);\n\n      if (matched) {\n        // api.navigateToState — plugin-only entry point. Preserves\n        // matchSourceTrailingSlash output and skips the redundant\n        // forwardState/buildPath round-trip (#525).\n        await deps.api.navigateToState(matched, deps.transitionOptions);\n      } else if (deps.allowNotFound) {\n        deps.router.navigateToNotFound(deps.browser.getLocation());\n      } else {\n        // Strict mode — unmatched URL is an error. Emit $$error and sync URL\n        // back to the current router state (no silent fallback to defaultRoute).\n        const err = new RouterError(errorCodes.ROUTE_NOT_FOUND, {\n          path: deps.browser.getLocation(),\n        });\n\n        deps.api.emitTransitionError(err);\n        rollbackUrlToCurrentState();\n      }\n    } catch (error) {\n      if (error instanceof RouterError) {\n        // navigate() already emitted $$error — just sync URL with router state.\n        // Swallow rollback errors: teardown races may remove router.buildUrl\n        // while a popstate event is still queued.\n        try {\n          rollbackUrlToCurrentState();\n        } catch {\n          // noop — nothing safe to do here\n        }\n      } else {\n        recoverFromCriticalError(error);\n      }\n    } finally {\n      isTransitioning = false;\n      processDeferredEvent();\n    }\n  }\n\n  return (evt: PopStateEvent) => void onPopState(evt);\n}\n\nexport interface PopstateLifecycleDeps {\n  browser: Browser;\n  shared: SharedFactoryState;\n  handler: (evt: PopStateEvent) => void;\n  cleanup: () => void;\n}\n\nexport function createPopstateLifecycle(\n  deps: PopstateLifecycleDeps,\n): Pick<Plugin, \"onStart\" | \"onStop\" | \"teardown\"> {\n  return {\n    onStart: () => {\n      if (deps.shared.removePopStateListener) {\n        deps.shared.removePopStateListener();\n      }\n\n      deps.shared.removePopStateListener = deps.browser.addPopstateListener(\n        deps.handler,\n      );\n    },\n\n    onStop: () => {\n      if (deps.shared.removePopStateListener) {\n        deps.shared.removePopStateListener();\n        deps.shared.removePopStateListener = undefined;\n      }\n    },\n\n    teardown: () => {\n      if (deps.shared.removePopStateListener) {\n        deps.shared.removePopStateListener();\n        deps.shared.removePopStateListener = undefined;\n      }\n\n      deps.cleanup();\n    },\n  };\n}\n","import type {\n  NavigationOptions,\n  Params,\n  Router,\n  State,\n} from \"@real-router/core\";\nimport type { PluginApi } from \"@real-router/core/api\";\n\nexport interface LocationSource {\n  getLocation: () => string;\n}\n\n/**\n * Minimal browser surface needed by `createReplaceHistoryState`.\n *\n * Both `Browser` (History API) and navigation-plugin's `NavigationBrowser`\n * (Navigation API) satisfy this structurally — the function never needs\n * `pushState`/`addPopstateListener`, only the replace path.\n */\nexport interface ReplaceStateBrowser {\n  replaceState: (state: unknown, url: string) => void;\n  getHash: () => string;\n}\n\nexport function createStartInterceptor(\n  api: PluginApi,\n  browser: LocationSource,\n): () => void {\n  return api.addInterceptor(\"start\", (next, path) =>\n    next(path ?? browser.getLocation()),\n  );\n}\n\nexport function createReplaceHistoryState(\n  api: PluginApi,\n  router: Router,\n  browser: ReplaceStateBrowser,\n  buildUrl: (name: string, params?: Params) => string,\n  preserveHash = true,\n): (name: string, params?: Params) => void {\n  // Reusable buffer — browsers structured-clone state synchronously inside\n  // replaceState, so the buffer never escapes. Eliminates one allocation per\n  // navigation on the hot path. (Mirrors createUpdateBrowserState.)\n  const buffer = {\n    name: \"\",\n    params: {} as Params,\n    path: \"\",\n  };\n\n  return (name: string, params: Params = {}) => {\n    const state = api.buildState(name, params);\n\n    if (!state) {\n      throw new Error(\n        `[real-router] Cannot replace state: route \"${name}\" is not found`,\n      );\n    }\n\n    const builtState = api.makeState(\n      state.name,\n      state.params,\n      router.buildPath(state.name, state.params),\n      {\n        params: state.meta,\n      },\n    );\n\n    const hash = preserveHash ? browser.getHash() : \"\";\n    const url = buildUrl(name, params) + hash;\n\n    buffer.name = builtState.name;\n    buffer.params = builtState.params;\n    buffer.path = builtState.path;\n\n    browser.replaceState(buffer, url);\n  };\n}\n\nexport function shouldReplaceHistory(\n  navOptions: NavigationOptions,\n  toState: State,\n  fromState: State | undefined,\n): boolean {\n  if (navOptions.replace === true) {\n    return true;\n  }\n\n  if (!fromState) {\n    return navOptions.replace !== false;\n  }\n\n  return !!navOptions.reload && toState.path === fromState.path;\n}\n","export interface ParsedUrl {\n  pathname: string;\n  search: string;\n  hash: string;\n}\n\n/**\n * Scheme-agnostic URL parser.\n *\n * Extracts `pathname`, `search`, and `hash` from any string — absolute\n * (`scheme://authority/path?q#h`), path-relative (`/path?q#h`), or opaque\n * (`data:...`, `javascript:...`). Never throws, never returns null.\n *\n * Routing does not care about scheme or authority, only about the path part.\n * This keeps `browser-plugin`, `navigation-plugin`, and `hash-plugin` working\n * in Electron (`file://`, `app://`), Tauri (`tauri://`, `https://`), and any\n * other webview that may ship with non-HTTP origins. See issue #496.\n */\nexport function safeParseUrl(url: string): ParsedUrl {\n  let rest = url;\n\n  const schemeIdx = rest.indexOf(\"://\");\n\n  if (schemeIdx !== -1) {\n    const authorityStart = schemeIdx + 3;\n    let pathStart = rest.length;\n\n    for (let i = authorityStart; i < rest.length; i++) {\n      const ch = rest[i];\n\n      if (ch === \"/\" || ch === \"?\" || ch === \"#\") {\n        pathStart = i;\n\n        break;\n      }\n    }\n\n    rest = pathStart === rest.length ? \"/\" : rest.slice(pathStart);\n\n    if (rest.startsWith(\"?\") || rest.startsWith(\"#\")) {\n      rest = `/${rest}`;\n    }\n  }\n\n  const hashIdx = rest.indexOf(\"#\");\n  const hash = hashIdx === -1 ? \"\" : rest.slice(hashIdx);\n  const beforeHash = hashIdx === -1 ? rest : rest.slice(0, hashIdx);\n\n  const queryIdx = beforeHash.indexOf(\"?\");\n  const search = queryIdx === -1 ? \"\" : beforeHash.slice(queryIdx);\n  const pathname = queryIdx === -1 ? beforeHash : beforeHash.slice(0, queryIdx);\n\n  return { pathname, search, hash };\n}\n","// packages/hash-plugin/src/constants.ts\n\nimport type { HashPluginOptions } from \"./types\";\n\nexport const defaultOptions: Required<HashPluginOptions> = {\n  hashPrefix: \"\",\n  base: \"\",\n  forceDeactivate: true,\n};\n\n/**\n * Source identifier for transitions triggered by browser events.\n */\nexport const source = \"popstate\";\n\nexport const LOGGER_CONTEXT = \"hash-plugin\";\n","// packages/hash-plugin/src/hash-utils.ts\n\nimport { safelyEncodePath, safeParseUrl } from \"./browser-env\";\n\nfunction escapeRegExp(str: string): string {\n  return str.replaceAll(/[$()*+.?[\\\\\\]^{|}-]/g, String.raw`\\$&`);\n}\n\nexport function createHashPrefixRegex(hashPrefix: string): RegExp | null {\n  if (!hashPrefix) {\n    return null;\n  }\n\n  return new RegExp(`^#${escapeRegExp(hashPrefix)}`);\n}\n\n/**\n * Extract path from URL hash, stripping hash prefix.\n *\n * @param hash - URL hash (e.g., \"#/path\" or \"#!/path\")\n * @param prefixRegex - Pre-compiled regex for prefix stripping (null if no prefix)\n * @returns Extracted path (e.g., \"/path\")\n */\nexport function extractHashPath(\n  hash: string,\n  prefixRegex: RegExp | null,\n): string {\n  if (hash === \"\" || hash === \"#\") {\n    return \"/\";\n  }\n\n  const path = prefixRegex ? hash.replace(prefixRegex, \"\") : hash.slice(1);\n\n  return path || \"/\";\n}\n\nexport function hashUrlToPath(url: string, prefixRegex: RegExp | null): string {\n  const parsedUrl = safeParseUrl(url);\n  const hashPath = extractHashPath(parsedUrl.hash, prefixRegex);\n\n  return hashPath.includes(\"?\") ? hashPath : hashPath + parsedUrl.search;\n}\n\n/**\n * Build the router-side location string from a hash + query pair.\n *\n * Encodes the hash path via `safelyEncodePath` after stripping the\n * configured prefix, then appends the outer `search` only when the hash\n * path itself does not already carry a `?` — otherwise the outer search\n * would be duplicated (see `url.test.ts` — \"well-formed path (no double '?')\").\n *\n * Used by the `createSafeBrowser` `getLocation` callback both in the\n * production factory and in functional/stress test helpers. Extracting\n * here keeps the production path and test mocks aligned; a regression in\n * this logic previously slipped between the two.\n */\nexport function buildHashLocation(\n  hash: string,\n  search: string,\n  prefixRegex: RegExp | null,\n): string {\n  const hashPath = safelyEncodePath(extractHashPath(hash, prefixRegex));\n\n  return hashPath.includes(\"?\") ? hashPath : hashPath + search;\n}\n","import {\n  createPopstateHandler,\n  createPopstateLifecycle,\n  createStartInterceptor,\n  createReplaceHistoryState,\n  shouldReplaceHistory,\n  updateBrowserState,\n} from \"./browser-env\";\nimport { LOGGER_CONTEXT } from \"./constants\";\nimport { hashUrlToPath } from \"./hash-utils\";\n\nimport type { Browser, SharedFactoryState } from \"./browser-env\";\nimport type { HashPluginOptions } from \"./types\";\nimport type {\n  NavigationOptions,\n  Params,\n  Router,\n  State,\n  Plugin,\n} from \"@real-router/core\";\nimport type { PluginApi } from \"@real-router/core/api\";\n\nexport class HashPlugin {\n  readonly #router: Router;\n  readonly #browser: Browser;\n  readonly #removeStartInterceptor: () => void;\n  readonly #removeExtensions: () => void;\n  readonly #lifecycle: Pick<Plugin, \"onStart\" | \"onStop\" | \"teardown\">;\n\n  constructor(\n    router: Router,\n    api: PluginApi,\n    options: Required<HashPluginOptions>,\n    browser: Browser,\n    prefixRegex: RegExp | null,\n    transitionOptions: {\n      source: string;\n      replace: true;\n      forceDeactivate?: boolean;\n    },\n    shared: SharedFactoryState,\n  ) {\n    this.#router = router;\n    this.#browser = browser;\n\n    this.#removeStartInterceptor = createStartInterceptor(api, browser);\n\n    const urlPrefix = `${options.base}#${options.hashPrefix}`;\n    const pluginBuildUrl = (route: string, params?: Params) =>\n      urlPrefix + router.buildPath(route, params);\n\n    this.#removeExtensions = api.extendRouter({\n      buildUrl: pluginBuildUrl,\n      matchUrl: (url: string) =>\n        api.matchPath(hashUrlToPath(url, prefixRegex)) ?? undefined,\n      replaceHistoryState: createReplaceHistoryState(\n        api,\n        router,\n        browser,\n        pluginBuildUrl,\n        false,\n      ),\n    });\n\n    const handler = createPopstateHandler({\n      router,\n      api,\n      browser,\n      allowNotFound: api.getOptions().allowNotFound,\n      transitionOptions,\n      loggerContext: LOGGER_CONTEXT,\n      buildUrl: pluginBuildUrl,\n    });\n\n    this.#lifecycle = createPopstateLifecycle({\n      browser,\n      shared,\n      handler,\n      cleanup: () => {\n        this.#removeStartInterceptor();\n        this.#removeExtensions();\n      },\n    });\n  }\n\n  getPlugin(): Plugin {\n    return {\n      ...this.#lifecycle,\n\n      onTransitionSuccess: (\n        toState: State,\n        fromState: State | undefined,\n        navOptions: NavigationOptions,\n      ) => {\n        const replaceHistory = shouldReplaceHistory(\n          navOptions,\n          toState,\n          fromState,\n        );\n\n        const url = this.#router.buildUrl(toState.name, toState.params);\n\n        updateBrowserState(toState, url, replaceHistory, this.#browser);\n      },\n    };\n  }\n}\n","import {\n  createOptionsValidator,\n  safeBaseRule,\n  safeHashPrefixRule,\n} from \"./browser-env\";\nimport { LOGGER_CONTEXT, defaultOptions } from \"./constants\";\n\nimport type { HashPluginOptions } from \"./types\";\n\nexport const validateOptions = createOptionsValidator<HashPluginOptions>(\n  defaultOptions,\n  LOGGER_CONTEXT,\n  { base: safeBaseRule, hashPrefix: safeHashPrefixRule },\n);\n","import { getPluginApi } from \"@real-router/core/api\";\n\nimport { createSafeBrowser, normalizeBase } from \"./browser-env\";\nimport { defaultOptions, source } from \"./constants\";\nimport { buildHashLocation, createHashPrefixRegex } from \"./hash-utils\";\nimport { HashPlugin } from \"./plugin\";\nimport { validateOptions } from \"./validation\";\n\nimport type { Browser, SharedFactoryState } from \"./browser-env\";\nimport type { HashPluginOptions } from \"./types\";\nimport type { PluginFactory, Router } from \"@real-router/core\";\n\nexport function hashPluginFactory(\n  opts?: Partial<HashPluginOptions>,\n  browser?: Browser,\n): PluginFactory {\n  validateOptions(opts);\n\n  const definedOpts = opts\n    ? Object.fromEntries(\n        Object.entries(opts).filter(\n          // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime may receive explicit undefined via conditional spreads (exactOptionalPropertyTypes does not apply here)\n          ([, value]) => value !== undefined,\n        ),\n      )\n    : {};\n  const options: Required<HashPluginOptions> = {\n    ...defaultOptions,\n    ...definedOpts,\n  };\n\n  options.base = normalizeBase(options.base);\n\n  const prefixRegex = createHashPrefixRegex(options.hashPrefix);\n  const resolvedBrowser =\n    browser ??\n    createSafeBrowser(\n      () =>\n        buildHashLocation(\n          globalThis.location.hash,\n          globalThis.location.search,\n          prefixRegex,\n        ),\n      \"hash-plugin\",\n    );\n\n  const transitionOptions = {\n    forceDeactivate: options.forceDeactivate,\n    source,\n    replace: true as const,\n  };\n\n  const shared: SharedFactoryState = { removePopStateListener: undefined };\n\n  return function hashPlugin(routerBase) {\n    const plugin = new HashPlugin(\n      routerBase as Router,\n      getPluginApi(routerBase),\n      options,\n      resolvedBrowser,\n      prefixRegex,\n      transitionOptions,\n      shared,\n    );\n\n    return plugin.getPlugin();\n  };\n}\n"],"mappings":"qHAAA,MAAa,MACJ,WAAW,SAAW,QAAe,CAAC,CAAC,WAAW,QCC9C,GAAa,EAAgB,IAAuB,CAC/D,WAAW,QAAQ,UAAU,EAAO,GAAI,EAAK,EAGlC,GAAgB,EAAgB,IAAuB,CAClE,WAAW,QAAQ,aAAa,EAAO,GAAI,EAAK,EAGrC,EACX,IAEA,WAAW,iBAAiB,WAAY,EAAG,KAE9B,CACX,WAAW,oBAAoB,WAAY,EAAG,GAIrC,MAAwB,WAAW,SAAS,KCTzD,SAAgB,EAAc,EAAsB,CAClD,GAAI,CAAC,EACH,OAAO,EAGT,IAAI,EAAS,EAAK,WAAW,OAAQ,IAAI,CAUzC,OARK,EAAO,WAAW,IAAI,GACzB,EAAS,IAAI,KAGX,EAAO,OAAS,GAAK,EAAO,SAAS,IAAI,GAC3C,EAAS,EAAO,MAAM,EAAG,GAAG,EAGvB,IAAW,IAAM,GAAK,EAG/B,MAAa,EAAoB,GAAyB,CACxD,GAAI,CACF,OAAO,UAAU,UAAU,EAAK,CAAC,OAC1B,EAAO,CAGd,OAFA,QAAQ,KAAK,wCAAwC,EAAK,GAAI,EAAM,CAE7D,ICjCL,MAAmB,GAEZ,EAAkB,GAAoB,CACjD,IAAI,EAAY,GAEhB,MAAQ,IAAyB,CAC/B,AAME,KALA,QAAQ,KACN,gFAAgF,EAAQ,cAC3E,EAAO,6GAErB,CACW,MAKL,EACX,GACmB,CACnB,IAAM,EAAW,EAAe,EAAQ,CAExC,MAAO,CACL,cAAiB,CACf,EAAS,YAAY,EAEvB,iBAAoB,CAClB,EAAS,eAAe,EAE1B,yBACE,EAAS,sBAAsB,CAExB,GAET,aACE,EAAS,UAAU,CAEZ,IAEV,ECzCgS,EAAE,0CAAiG,SAAS,EAAE,EAAE,CAAC,OAAO,OAAO,GAAG,SAAS,IAAI,GAAG,CAAC,EAAE,EAAE,OAAO,IAAI,CAAC,EAAE,EAAE,WAAW,KAAK,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,QAAQ,CAAC,GAAG,GAAG,KAAK,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,UAAU,IAAI,UAAU,MAAM,CAAC,EAAE,GAAG,IAAI,SAAS,OAAO,OAAO,SAAS,EAAE,CAAC,GAAG,IAAI,YAAY,IAAI,SAAS,MAAM,CAAC,EAAE,GAAG,MAAM,QAAQ,EAAE,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,GAAG,EAAE,EAAE,EAAE,CAAC,EAAE,GAAG,IAAI,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,eAAe,EAAE,CAAC,OAAO,IAAI,MAAM,IAAI,OAAO,UAAU,CAAC,EAAE,OAAO,OAAO,EAAE,CAAC,MAAM,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,GAAG,GAAG,KAAK,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,IAAI,UAAU,IAAI,UAAU,CAAC,EAAE,IAAI,SAAS,OAAO,SAAS,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,EAAE,CAAC,GAAG,OAAO,GAAG,UAAU,CAAC,GAAG,MAAM,QAAQ,EAAE,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,eAAe,EAAE,CAAC,GAAG,IAAI,MAAM,IAAI,OAAO,UAAU,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,IAAI,KAAK,EAAE,CAAC,GAAG,CAAC,OAAO,OAAO,EAAE,EAAE,CAAC,SAAS,IAAI,EAAE,EAAE,GAAG,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,YAAY,IAAI,SAAS,MAAM,CAAC,EAAE,EAAE,CAAC,EAAE,OAAO,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC,EAA4Y,SAAS,EAAE,EAAE,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,EAAE,EAAE,OAAO,CAAqD,SAAS,EAAE,EAAE,CAAC,MAAM,EAAE,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,EC4B52D,SAAgB,EACd,EACA,EACA,EACmB,CAKnB,OAJIA,EAAQ,EAAI,MAAM,CACb,EAAI,UAAU,EAAI,MAAM,KAAM,EAAI,MAAM,OAAQ,EAAI,MAAM,KAAK,CAGjE,EAAI,UAAU,EAAQ,aAAa,CAAC,CAW7C,SAAgB,EACd,EACA,EACA,EACA,EACM,CACN,IAAM,EAAe,CACnB,KAAM,EAAM,KACZ,OAAQ,EAAM,OACd,KAAM,EAAM,KACb,CAEG,EACF,EAAQ,aAAa,EAAc,EAAI,CAEvC,EAAQ,UAAU,EAAc,EAAI,CCvDxC,SAAgB,EACd,EACA,EACA,EACwC,CACxC,MAAQ,IAAS,CACV,KAIL,IAAK,IAAM,KAAO,OAAO,KAAK,EAAK,CAAE,CACnC,GAAI,EAAE,KAAO,GACX,SAGF,IAAM,EAAQ,EAAK,GAEnB,GAAI,IAAU,IAAA,GACZ,SAGF,IAAM,EAAW,OAAO,EAAS,GAC3B,EAAS,OAAO,EAEtB,GAAI,IAAW,EACb,MAAU,MACR,IAAI,EAAc,sBAAsB,EAAI,cAAc,EAAS,QAAQ,IAC5E,CAGH,IAAM,EAAO,IAAQ,GAErB,GAAI,EAAM,CACR,IAAM,EAAO,EAAK,SAA+C,EAAM,CAEvE,GAAI,IAAQ,KACV,MAAU,MAAM,IAAI,EAAc,aAAa,EAAI,KAAK,IAAM,IAQxE,MAAM,EAAgB,wBAET,EAAmC,CAC9C,SAAW,GACL,EAAc,KAAK,EAAM,CACpB,sCAGL,EAAM,MAAM,IAAI,CAAC,SAAS,KAAK,CAC1B,iCAGF,KAEV,CAEY,EAAyC,CACpD,SAAW,GACL,EAAc,KAAK,EAAM,CACpB,sCAGL,EAAM,SAAS,IAAI,CACd,sEAGL,EAAM,SAAS,IAAI,CACd,2DAGL,EAAM,SAAS,IAAI,CACd,+DAGF,KAEV,CC1ED,SAAgB,EACd,EACA,EACS,CACT,GAAI,GAAsB,CACxB,MAAO,CACL,YACA,eACA,sBACA,cACA,UACD,CAGH,IAAM,EAAW,EAAe,EAAQ,CAExC,MAAO,CACL,GAAG,EAA6B,EAAQ,CACxC,iBACE,EAAS,cAAc,CAEhB,IAEV,CCPH,SAAgB,EACd,EAC8B,CAC9B,IAAI,EAAkB,GAClB,EAAsC,KAE1C,SAAS,GAA6B,CACpC,GAAI,EAAe,CACjB,IAAM,EAAM,EAEZ,EAAgB,KAChB,QAAQ,KACN,IAAI,EAAK,cAAc,sCACxB,CACI,EAAW,EAAI,EAIxB,SAAS,GAAkC,CACzC,IAAM,EAAe,EAAK,OAAO,UAAU,CAG3C,GAAI,CAAC,EACH,OAGF,IAAM,EAAM,EAAK,SAAS,EAAa,KAAM,EAAa,OAAO,CAEjE,EAAK,QAAQ,aAAa,EAAc,EAAI,CAG9C,SAAS,EAAyB,EAAsB,CACtD,QAAQ,MACN,IAAI,EAAK,cAAc,gCACvB,EACD,CAED,GAAI,CACF,GAA2B,OACpB,EAAe,CACtB,QAAQ,MACN,IAAI,EAAK,cAAc,yCACvB,EACD,EAIL,eAAe,EAAW,EAAmC,CAC3D,GAAI,EAAiB,CACnB,QAAQ,KACN,IAAI,EAAK,cAAc,oDACxB,CACD,EAAgB,EAEhB,OAGF,EAAkB,GAElB,GAAI,CACF,IAAM,EAAU,EAAkB,EAAK,EAAK,IAAK,EAAK,QAAQ,CAE9D,GAAI,EAIF,MAAM,EAAK,IAAI,gBAAgB,EAAS,EAAK,kBAAkB,SACtD,EAAK,cACd,EAAK,OAAO,mBAAmB,EAAK,QAAQ,aAAa,CAAC,KACrD,CAGL,IAAM,EAAM,IAAI,EAAY,EAAW,gBAAiB,CACtD,KAAM,EAAK,QAAQ,aAAa,CACjC,CAAC,CAEF,EAAK,IAAI,oBAAoB,EAAI,CACjC,GAA2B,QAEtB,EAAO,CACd,GAAI,aAAiB,EAInB,GAAI,CACF,GAA2B,MACrB,OAIR,EAAyB,EAAM,QAEzB,CACR,EAAkB,GAClB,GAAsB,EAI1B,MAAQ,IAAuB,KAAK,EAAW,EAAI,CAUrD,SAAgB,EACd,EACiD,CACjD,MAAO,CACL,YAAe,CACT,EAAK,OAAO,wBACd,EAAK,OAAO,wBAAwB,CAGtC,EAAK,OAAO,uBAAyB,EAAK,QAAQ,oBAChD,EAAK,QACN,EAGH,WAAc,CACR,EAAK,OAAO,yBACd,EAAK,OAAO,wBAAwB,CACpC,EAAK,OAAO,uBAAyB,IAAA,KAIzC,aAAgB,CACV,EAAK,OAAO,yBACd,EAAK,OAAO,wBAAwB,CACpC,EAAK,OAAO,uBAAyB,IAAA,IAGvC,EAAK,SAAS,EAEjB,CC/IH,SAAgB,EACd,EACA,EACY,CACZ,OAAO,EAAI,eAAe,SAAU,EAAM,IACxC,EAAK,GAAQ,EAAQ,aAAa,CAAC,CACpC,CAGH,SAAgB,EACd,EACA,EACA,EACA,EACA,EAAe,GAC0B,CAIzC,IAAM,EAAS,CACb,KAAM,GACN,OAAQ,EAAE,CACV,KAAM,GACP,CAED,OAAQ,EAAc,EAAiB,EAAE,GAAK,CAC5C,IAAM,EAAQ,EAAI,WAAW,EAAM,EAAO,CAE1C,GAAI,CAAC,EACH,MAAU,MACR,8CAA8C,EAAK,gBACpD,CAGH,IAAM,EAAa,EAAI,UACrB,EAAM,KACN,EAAM,OACN,EAAO,UAAU,EAAM,KAAM,EAAM,OAAO,CAC1C,CACE,OAAQ,EAAM,KACf,CACF,CAEK,EAAO,EAAe,EAAQ,SAAS,CAAG,GAC1C,EAAM,EAAS,EAAM,EAAO,CAAG,EAErC,EAAO,KAAO,EAAW,KACzB,EAAO,OAAS,EAAW,OAC3B,EAAO,KAAO,EAAW,KAEzB,EAAQ,aAAa,EAAQ,EAAI,EAIrC,SAAgB,EACd,EACA,EACA,EACS,CAST,OARI,EAAW,UAAY,GAClB,GAGJ,EAIE,CAAC,CAAC,EAAW,QAAU,EAAQ,OAAS,EAAU,KAHhD,EAAW,UAAY,GCtElC,SAAgB,EAAa,EAAwB,CACnD,IAAI,EAAO,EAEL,EAAY,EAAK,QAAQ,MAAM,CAErC,GAAI,IAAc,GAAI,CACpB,IAAM,EAAiB,EAAY,EAC/B,EAAY,EAAK,OAErB,IAAK,IAAI,EAAI,EAAgB,EAAI,EAAK,OAAQ,IAAK,CACjD,IAAM,EAAK,EAAK,GAEhB,GAAI,IAAO,KAAO,IAAO,KAAO,IAAO,IAAK,CAC1C,EAAY,EAEZ,OAIJ,EAAO,IAAc,EAAK,OAAS,IAAM,EAAK,MAAM,EAAU,EAE1D,EAAK,WAAW,IAAI,EAAI,EAAK,WAAW,IAAI,IAC9C,EAAO,IAAI,KAIf,IAAM,EAAU,EAAK,QAAQ,IAAI,CAC3B,EAAO,IAAY,GAAK,GAAK,EAAK,MAAM,EAAQ,CAChD,EAAa,IAAY,GAAK,EAAO,EAAK,MAAM,EAAG,EAAQ,CAE3D,EAAW,EAAW,QAAQ,IAAI,CAClC,EAAS,IAAa,GAAK,GAAK,EAAW,MAAM,EAAS,CAGhE,MAAO,CAAE,SAFQ,IAAa,GAAK,EAAa,EAAW,MAAM,EAAG,EAAS,CAE1D,SAAQ,OAAM,CChDnC,MAAa,EAA8C,CACzD,WAAY,GACZ,KAAM,GACN,gBAAiB,GAClB,CAOY,EAAiB,cCX9B,SAAS,EAAa,EAAqB,CACzC,OAAO,EAAI,WAAW,uBAAwB,OAAO,GAAG,MAAM,CAGhE,SAAgB,EAAsB,EAAmC,CAKvE,OAJK,EAIM,OAAO,KAAK,EAAa,EAAW,GAAG,CAHzC,KAaX,SAAgB,EACd,EACA,EACQ,CAOR,OANI,IAAS,IAAM,IAAS,IACnB,KAGI,EAAc,EAAK,QAAQ,EAAa,GAAG,CAAG,EAAK,MAAM,EAAE,GAEzD,IAGjB,SAAgB,EAAc,EAAa,EAAoC,CAC7E,IAAM,EAAY,EAAa,EAAI,CAC7B,EAAW,EAAgB,EAAU,KAAM,EAAY,CAE7D,OAAO,EAAS,SAAS,IAAI,CAAG,EAAW,EAAW,EAAU,OAgBlE,SAAgB,EACd,EACA,EACA,EACQ,CACR,IAAM,EAAW,EAAiB,EAAgB,EAAM,EAAY,CAAC,CAErE,OAAO,EAAS,SAAS,IAAI,CAAG,EAAW,EAAW,ECzCxD,IAAa,EAAb,KAAwB,CACtB,GACA,GACA,GACA,GACA,GAEA,YACE,EACA,EACA,EACA,EACA,EACA,EAKA,EACA,CACA,MAAA,EAAe,EACf,MAAA,EAAgB,EAEhB,MAAA,EAA+B,EAAuB,EAAK,EAAQ,CAEnE,IAAM,EAAY,GAAG,EAAQ,KAAK,GAAG,EAAQ,aACvC,GAAkB,EAAe,IACrC,EAAY,EAAO,UAAU,EAAO,EAAO,CAE7C,MAAA,EAAyB,EAAI,aAAa,CACxC,SAAU,EACV,SAAW,GACT,EAAI,UAAU,EAAc,EAAK,EAAY,CAAC,EAAI,IAAA,GACpD,oBAAqB,EACnB,EACA,EACA,EACA,EACA,GACD,CACF,CAAC,CAYF,MAAA,EAAkB,EAAwB,CACxC,UACA,SACA,QAbc,EAAsB,CACpC,SACA,MACA,UACA,cAAe,EAAI,YAAY,CAAC,cAChC,oBACA,cAAe,EACf,SAAU,EACX,CAAC,CAMA,YAAe,CACb,MAAA,GAA8B,CAC9B,MAAA,GAAwB,EAE3B,CAAC,CAGJ,WAAoB,CAClB,MAAO,CACL,GAAG,MAAA,EAEH,qBACE,EACA,EACA,IACG,CACH,IAAM,EAAiB,EACrB,EACA,EACA,EACD,CAID,EAAmB,EAFP,MAAA,EAAa,SAAS,EAAQ,KAAM,EAAQ,OAAO,CAE9B,EAAgB,MAAA,EAAc,EAElE,GC/FL,MAAa,EAAkB,EAC7B,EACA,EACA,CAAE,KAAM,EAAc,WAAY,EAAoB,CACvD,CCDD,SAAgB,EACd,EACA,EACe,CACf,EAAgB,EAAK,CAErB,IAAM,EAAc,EAChB,OAAO,YACL,OAAO,QAAQ,EAAK,CAAC,QAElB,EAAG,KAAW,IAAU,IAAA,GAC1B,CACF,CACD,EAAE,CACA,EAAuC,CAC3C,GAAG,EACH,GAAG,EACJ,CAED,EAAQ,KAAO,EAAc,EAAQ,KAAK,CAE1C,IAAM,EAAc,EAAsB,EAAQ,WAAW,CACvD,EACJ,GACA,MAEI,EACE,WAAW,SAAS,KACpB,WAAW,SAAS,OACpB,EACD,CACH,cACD,CAEG,EAAoB,CACxB,gBAAiB,EAAQ,gBACzB,kBACA,QAAS,GACV,CAEK,EAA6B,CAAE,uBAAwB,IAAA,GAAW,CAExE,OAAO,SAAoB,EAAY,CAWrC,OAVe,IAAI,EACjB,EACA,EAAa,EAAW,CACxB,EACA,EACA,EACA,EACA,EACD,CAEa,WAAW"}
+{"version":3,"file":"index.mjs","names":["isState","#router","#browser","#removeStartInterceptor","#removeExtensions","#lifecycle","#warnHashIgnored"],"sources":["../../../../shared/browser-env/detect.ts","../../../../shared/browser-env/history-api.ts","../../../../shared/browser-env/utils.ts","../../../../shared/browser-env/ssr-fallback.ts","../../../type-guards/dist/esm/index.mjs","../../../../shared/browser-env/popstate-utils.ts","../../../../shared/browser-env/validation.ts","../../../../shared/browser-env/safe-browser.ts","../../../../shared/browser-env/popstate-handler.ts","../../../../shared/browser-env/url-context.ts","../../../../shared/browser-env/plugin-utils.ts","../../../../shared/browser-env/url-parsing.ts","../../src/constants.ts","../../src/hash-utils.ts","../../src/plugin.ts","../../src/validation.ts","../../src/factory.ts"],"sourcesContent":["export const isBrowserEnvironment = (): boolean =>\n  typeof globalThis.window !== \"undefined\" && !!globalThis.history;\n","import type { HistoryBrowser } from \"./types.js\";\n\nexport const pushState = (state: unknown, path: string): void => {\n  globalThis.history.pushState(state, \"\", path);\n};\n\nexport const replaceState = (state: unknown, path: string): void => {\n  globalThis.history.replaceState(state, \"\", path);\n};\n\nexport const addPopstateListener: HistoryBrowser[\"addPopstateListener\"] = (\n  fn,\n) => {\n  globalThis.addEventListener(\"popstate\", fn);\n\n  return () => {\n    globalThis.removeEventListener(\"popstate\", fn);\n  };\n};\n\nexport const getHash = (): string => globalThis.location.hash;\n","/**\n * Normalizes base path to canonical form: leading slash, no trailing slash,\n * no repeated slashes. Isolated \"/\" collapses to \"\".\n *\n * @example\n * normalizeBase(\"app\")     // \"/app\"\n * normalizeBase(\"/app/\")   // \"/app\"\n * normalizeBase(\"//app//\") // \"/app\"\n * normalizeBase(\"\")        // \"\"\n * normalizeBase(\"/\")       // \"\"\n */\nexport function normalizeBase(base: string): string {\n  if (!base) {\n    return base;\n  }\n\n  let result = base.replaceAll(/\\/+/g, \"/\");\n\n  if (!result.startsWith(\"/\")) {\n    result = `/${result}`;\n  }\n\n  if (result.length > 1 && result.endsWith(\"/\")) {\n    result = result.slice(0, -1);\n  }\n\n  return result === \"/\" ? \"\" : result;\n}\n\nexport const safelyEncodePath = (path: string): string => {\n  try {\n    return encodeURI(decodeURI(path));\n  } catch (error) {\n    console.warn(`[browser-env] Could not encode path \"${path}\"`, error);\n\n    return path;\n  }\n};\n","import type { HistoryBrowser } from \"./types.js\";\n\nconst NOOP = (): void => {};\n\nexport const createWarnOnce = (context: string) => {\n  let hasWarned = false;\n\n  return (method: string): void => {\n    if (!hasWarned) {\n      console.warn(\n        `[browser-env] Browser API is running in a non-browser environment (context: \"${context}\"). ` +\n          `Method \"${method}\" is a no-op. ` +\n          `This is expected for SSR, but may indicate misconfiguration if you expected browser behavior.`,\n      );\n      hasWarned = true;\n    }\n  };\n};\n\nexport const createHistoryFallbackBrowser = (\n  context: string,\n): HistoryBrowser => {\n  const warnOnce = createWarnOnce(context);\n\n  return {\n    pushState: () => {\n      warnOnce(\"pushState\");\n    },\n    replaceState: () => {\n      warnOnce(\"replaceState\");\n    },\n    addPopstateListener: () => {\n      warnOnce(\"addPopstateListener\");\n\n      return NOOP;\n    },\n    getHash: () => {\n      warnOnce(\"getHash\");\n\n      return \"\";\n    },\n  };\n};\n","const e=[`replace`,`reload`,`force`,`forceDeactivate`,`redirected`];function t(t){if(typeof t!=`object`||!t||Array.isArray(t))return!1;let n=t;for(let t of e){let e=n[t];if(e!==void 0&&typeof e!=`boolean`)return!1}let r=n.signal;return!(r!==void 0&&!(r instanceof AbortSignal))}const n=/\\S/,r=/^[A-Z_a-z][\\w-]*(?:\\.[A-Z_a-z][\\w-]*)*$/;function i(e,t){return TypeError(`[router.${e}] ${t}`)}function a(e){return typeof e==`string`?e===``?!0:e.length>1e4?!1:e.startsWith(`@@`)?!0:r.test(e):!1}function o(e,t=new WeakSet){if(e==null)return!0;let n=typeof e;if(n===`string`||n===`boolean`)return!0;if(n===`number`)return Number.isFinite(e);if(n===`function`||n===`symbol`)return!1;if(Array.isArray(e))return t.has(e)?!1:(t.add(e),e.every(e=>o(e,t)));if(n===`object`){if(t.has(e))return!1;t.add(e);let n=Object.getPrototypeOf(e);return n!==null&&n!==Object.prototype?!1:Object.values(e).every(e=>o(e,t))}return!1}function s(e){if(e==null)return!0;let t=typeof e;return t===`string`||t===`boolean`?!0:t===`number`?Number.isFinite(e):!1}function c(e){if(typeof e!=`object`||!e||Array.isArray(e))return!1;let t=Object.getPrototypeOf(e);if(t!==null&&t!==Object.prototype)return!1;let n=!1;for(let t in e){if(!Object.hasOwn(e,t))continue;let r=e[t];if(!s(r)){let e=typeof r;if(e===`function`||e===`symbol`)return!1;n=!0;break}}return n?o(e):!0}function l(e){if(e==null)return!0;let t=typeof e;return t===`string`||t===`boolean`?!0:t===`number`?Number.isFinite(e):Array.isArray(e)?e.every(e=>{let t=typeof e;return t===`string`||t===`boolean`?!0:t===`number`?Number.isFinite(e):!1}):!1}function u(e){if(typeof e!=`object`||!e||Array.isArray(e))return!1;for(let t in e){if(!Object.hasOwn(e,t))continue;let n=e[t];if(!l(n))return!1}return!0}function d(e){return a(e.name)&&typeof e.path==`string`&&c(e.params)}function f(e){return typeof e!=`object`||!e?!1:d(e)}function p(e){return!(typeof e!=`object`||!e||!d(e))}function m(e){return typeof e==`string`}function h(e){return typeof e==`boolean`}function g(e,t){return e in t}function _(e){return typeof e==`number`?Number.isFinite(e):typeof e==`string`||typeof e==`boolean`}function v(e,t){if(typeof e!=`string`)throw i(t,`Route name must be a string, got ${typeof e}`);if(e!==``){if(!n.test(e))throw i(t,`Route name cannot contain only whitespace`);if(e.length>1e4)throw i(t,`Route name exceeds maximum length of 10000 characters. This is a technical safety limit.`);if(!e.startsWith(`@@`)&&!r.test(e))throw i(t,`Invalid route name \"${e}\". Each segment must start with a letter or underscore, followed by letters, numbers, underscores, or hyphens. Segments are separated by dots (e.g., \"users.profile\").`)}}function y(e){return e===null?`null`:Array.isArray(e)?`array[${e.length}]`:typeof e==`object`?`constructor`in e&&e.constructor.name!==`Object`?e.constructor.name:`object`:typeof e}function b(e,t){if(!f(e))throw TypeError(`[${t}] Invalid state structure: ${y(e)}. Expected State object with name, params, and path properties.`)}export{y as getTypeDescription,h as isBoolean,t as isNavigationOptions,g as isObjKey,c as isParams,u as isParamsStrict,_ as isPrimitiveValue,a as isRouteName,f as isState,p as isStateStrict,m as isString,v as validateRouteName,b as validateState};\n//# sourceMappingURL=index.mjs.map","import { isStateStrict as isState } from \"type-guards\";\n\nimport type { Browser } from \"./types.js\";\nimport type { State, Params } from \"@real-router/core\";\nimport type { PluginApi } from \"@real-router/core/api\";\n\n/**\n * Resolves the popstate event into a navigation-ready `State`.\n *\n * - If `history.state` is a valid router state ({name, params, path} written\n *   by browser-plugin/hash-plugin during their previous navigation), it is\n *   the source of truth — synthesize a fully-typed `State` from it via\n *   `api.makeState`. The synthesized `transition`/`context` fields are\n *   placeholders; the navigation pipeline (`completeTransition` and plugin\n *   claim writes) replaces them.\n *   This branch is mandatory for hash-plugin: `browser.getLocation()`\n *   returns the History pathname, not the hash, so the matchPath fallback\n *   below cannot extract the hash route.\n * - Otherwise (e.g. manually entered URL with no recorded state), fall\n *   back to `api.matchPath(browser.getLocation())`. browser-plugin's\n *   `getLocation` returns the URL pathname — this works.\n * - `undefined` when neither path produces a match.\n *\n * Replaces the previous `{ name, params }` shape so the caller can hand\n * the State directly to `router.navigateToState(state, opts)` and skip\n * the redundant `forwardState`/`buildPath` round-trip in\n * `buildNavigateState` (issue #525).\n */\nexport function getRouteFromEvent(\n  evt: PopStateEvent,\n  api: PluginApi,\n  browser: Browser,\n): State | undefined {\n  if (isState(evt.state)) {\n    return api.makeState(evt.state.name, evt.state.params, evt.state.path);\n  }\n\n  return api.matchPath(browser.getLocation());\n}\n\n/**\n * Updates browser state (pushState or replaceState)\n *\n * @param state - Router state\n * @param url - URL to set\n * @param replace - Whether to replace instead of push\n * @param browser - Browser API instance\n */\nexport function updateBrowserState(\n  state: State,\n  url: string,\n  replace: boolean,\n  browser: Browser,\n): void {\n  const historyState = {\n    name: state.name,\n    params: state.params,\n    path: state.path,\n  };\n\n  if (replace) {\n    browser.replaceState(historyState, url);\n  } else {\n    browser.pushState(historyState, url);\n  }\n}\n\n/**\n * Creates a `updateBrowserState` closure that reuses a single mutable buffer\n * across calls instead of allocating a fresh `{ name, params, path }` object\n * per push/replace.\n *\n * Why: Browsers structured-clone `history.state` synchronously inside\n * `pushState`/`replaceState`, so the caller never sees the buffer escape —\n * it can be safely overwritten before the next call. Eliminates one\n * allocation per navigation on the hot path.\n *\n * Each plugin instance must own its own buffer (do not share across plugins).\n */\nexport function createUpdateBrowserState(): (\n  state: State,\n  url: string,\n  replace: boolean,\n  browser: Browser,\n) => void {\n  const buffer = {\n    name: \"\",\n    params: {} as Params,\n    path: \"\",\n  };\n\n  return (state, url, replace, browser) => {\n    buffer.name = state.name;\n    buffer.params = state.params;\n    buffer.path = state.path;\n\n    if (replace) {\n      browser.replaceState(buffer, url);\n    } else {\n      browser.pushState(buffer, url);\n    }\n  };\n}\n","export interface OptionRule<T> {\n  validate: (value: T) => string | null;\n}\n\nexport type OptionRules<T extends object> = {\n  [K in keyof T]?: OptionRule<NonNullable<T[K]>>;\n};\n\nexport function createOptionsValidator<T extends object>(\n  defaults: Required<T>,\n  loggerContext: string,\n  rules?: OptionRules<T>,\n): (opts: Partial<T> | undefined) => void {\n  return (opts) => {\n    if (!opts) {\n      return;\n    }\n\n    for (const key of Object.keys(opts)) {\n      if (!(key in defaults)) {\n        continue;\n      }\n\n      const value = opts[key as keyof typeof opts];\n\n      if (value === undefined) {\n        continue;\n      }\n\n      const expected = typeof defaults[key as keyof typeof defaults];\n      const actual = typeof value;\n\n      if (actual !== expected) {\n        throw new Error(\n          `[${loggerContext}] Invalid type for '${key}': expected ${expected}, got ${actual}`,\n        );\n      }\n\n      const rule = rules?.[key as keyof T];\n\n      if (rule) {\n        const msg = (rule.validate as (input: unknown) => string | null)(value);\n\n        if (msg !== null) {\n          throw new Error(`[${loggerContext}] Invalid '${key}': ${msg}`);\n        }\n      }\n    }\n  };\n}\n\n// eslint-disable-next-line no-control-regex -- control characters are exactly what this rule rejects\nconst CONTROL_CHARS = /[\\u0000-\\u001F\\u007F]/;\n\nexport const safeBaseRule: OptionRule<string> = {\n  validate: (value) => {\n    if (CONTROL_CHARS.test(value)) {\n      return \"must not contain control characters\";\n    }\n\n    if (value.split(\"/\").includes(\"..\")) {\n      return \"must not contain '..' segments\";\n    }\n\n    return null;\n  },\n};\n\nexport const safeHashPrefixRule: OptionRule<string> = {\n  validate: (value) => {\n    if (CONTROL_CHARS.test(value)) {\n      return \"must not contain control characters\";\n    }\n\n    if (value.includes(\"/\")) {\n      return \"must not contain '/' (slash is added before the path automatically)\";\n    }\n\n    if (value.includes(\"#\")) {\n      return \"must not contain '#' (it is added as the hash delimiter)\";\n    }\n\n    if (value.includes(\"?\")) {\n      return \"must not contain '?' (it conflicts with the query delimiter)\";\n    }\n\n    return null;\n  },\n};\n\nexport const nonNegativeIntegerRule: OptionRule<number> = {\n  validate: (value) => {\n    if (!Number.isFinite(value)) {\n      return `expected finite number, got ${String(value)}`;\n    }\n\n    if (!Number.isInteger(value)) {\n      return `expected integer, got ${String(value)}`;\n    }\n\n    if (value < 0) {\n      return `expected non-negative integer, got ${value}`;\n    }\n\n    return null;\n  },\n};\n","import { isBrowserEnvironment } from \"./detect.js\";\nimport {\n  pushState,\n  replaceState,\n  addPopstateListener,\n  getHash,\n} from \"./history-api.js\";\nimport {\n  createWarnOnce,\n  createHistoryFallbackBrowser,\n} from \"./ssr-fallback.js\";\n\nimport type { Browser } from \"./types.js\";\n\nexport function createSafeBrowser(\n  getLocation: () => string,\n  context: string,\n): Browser {\n  if (isBrowserEnvironment()) {\n    return {\n      pushState,\n      replaceState,\n      addPopstateListener,\n      getLocation,\n      getHash,\n    };\n  }\n\n  const warnOnce = createWarnOnce(context);\n\n  return {\n    ...createHistoryFallbackBrowser(context),\n    getLocation: () => {\n      warnOnce(\"getLocation\");\n\n      return \"\";\n    },\n  };\n}\n","import { errorCodes, RouterError } from \"@real-router/core\";\n\nimport { getRouteFromEvent } from \"./popstate-utils.js\";\n\nimport type { Browser, SharedFactoryState } from \"./types.js\";\nimport type { Params, Plugin, Router } from \"@real-router/core\";\nimport type { PluginApi } from \"@real-router/core/api\";\n\n/**\n * Navigation options used by the popstate handler to trigger a\n * router.navigate() call from a back/forward event. `source` identifies\n * the origin of the transition to downstream context consumers;\n * `replace: true` keeps the history stack in sync with the browser.\n */\nexport interface PopstateTransitionOptions {\n  source: string;\n  replace: true;\n  forceDeactivate?: boolean;\n}\n\nexport interface PopstateHandlerDeps {\n  router: Router;\n  api: PluginApi;\n  browser: Browser;\n  allowNotFound: boolean;\n  transitionOptions: PopstateTransitionOptions;\n  loggerContext: string;\n  buildUrl: (\n    name: string,\n    params?: Params,\n    options?: { hash?: string },\n  ) => string;\n  /**\n   * Decoded hash of the current browser location (no leading \"#\"). Defaults\n   * to a no-op (returns \"\") for plugins that do not participate in URL\n   * fragment tracking — namely hash-plugin, where `#` is the route delimiter.\n   * (#532)\n   */\n  getCurrentHash?: () => string;\n  /**\n   * Decoded hash from the previous transition's `state.context.url.hash`\n   * (no leading \"#\"). Used by the popstate handler to detect hash-only\n   * navigation and add `force: true, hashChange: true` to bypass SAME_STATES.\n   * Defaults to no-op (returns \"\") for hash-plugin. (#532)\n   */\n  getCurrentContextHash?: () => string;\n}\n\n/**\n * Hash augmentation for popstate-driven navigateToState (#532).\n * Returns a partial options object that the caller spreads on top of\n * `deps.transitionOptions`. When the handler is wired without hash support\n * (hash-plugin), both deps default to undefined and an empty object is\n * returned — preserving the legacy behavior for that plugin.\n */\nfunction resolveHashOptions(\n  deps: PopstateHandlerDeps,\n  matchedPath: string,\n): { hash?: string; force?: true; hashChange?: true } {\n  if (!deps.getCurrentHash) {\n    return {};\n  }\n\n  const newHash = deps.getCurrentHash();\n  const prevHash = deps.getCurrentContextHash\n    ? deps.getCurrentContextHash()\n    : \"\";\n  const hashChange =\n    newHash !== prevHash && deps.router.getState()?.path === matchedPath;\n\n  return hashChange\n    ? { hash: newHash, force: true, hashChange: true }\n    : { hash: newHash };\n}\n\nexport function createPopstateHandler(\n  deps: PopstateHandlerDeps,\n): (evt: PopStateEvent) => void {\n  let isTransitioning = false;\n  let deferredEvent: PopStateEvent | null = null;\n\n  function processDeferredEvent(): void {\n    if (deferredEvent) {\n      const evt = deferredEvent;\n\n      deferredEvent = null;\n      console.warn(\n        `[${deps.loggerContext}] Processing deferred popstate event`,\n      );\n      void onPopState(evt);\n    }\n  }\n\n  function rollbackUrlToCurrentState(): void {\n    const currentState = deps.router.getState();\n\n    /* v8 ignore next -- @preserve: router always has state after start(); defensive guard for edge cases */\n    if (!currentState) {\n      return;\n    }\n\n    // Preserve hash on rollback so guard rejection / unmatched URL on\n    // popstate doesn't strip the fragment from the visible URL (#532).\n    const ctxHash = (\n      currentState.context as { url?: { hash?: string } } | undefined\n    )?.url?.hash;\n    const url = deps.buildUrl(\n      currentState.name,\n      currentState.params,\n      ctxHash ? { hash: ctxHash } : undefined,\n    );\n\n    deps.browser.replaceState(currentState, url);\n  }\n\n  function recoverFromCriticalError(error: unknown): void {\n    console.error(\n      `[${deps.loggerContext}] Critical error in onPopState`,\n      error,\n    );\n\n    try {\n      rollbackUrlToCurrentState();\n    } catch (recoveryError) {\n      console.error(\n        `[${deps.loggerContext}] Failed to recover from critical error`,\n        recoveryError,\n      );\n    }\n  }\n\n  async function onPopState(evt: PopStateEvent): Promise<void> {\n    if (isTransitioning) {\n      console.warn(\n        `[${deps.loggerContext}] Transition in progress, deferring popstate event`,\n      );\n      deferredEvent = evt;\n\n      return;\n    }\n\n    isTransitioning = true;\n\n    try {\n      const matched = getRouteFromEvent(evt, deps.api, deps.browser);\n\n      if (matched) {\n        // api.navigateToState — plugin-only entry point. Preserves\n        // matchSourceTrailingSlash output and skips the redundant\n        // forwardState/buildPath round-trip (#525). Hash augmentation (#532)\n        // extracted into resolveHashOptions so this branch stays readable.\n        await deps.api.navigateToState(matched, {\n          ...deps.transitionOptions,\n          ...resolveHashOptions(deps, matched.path),\n        });\n      } else if (deps.allowNotFound) {\n        deps.router.navigateToNotFound(deps.browser.getLocation());\n      } else {\n        // Strict mode — unmatched URL is an error. Emit $$error and sync URL\n        // back to the current router state (no silent fallback to defaultRoute).\n        const err = new RouterError(errorCodes.ROUTE_NOT_FOUND, {\n          path: deps.browser.getLocation(),\n        });\n\n        deps.api.emitTransitionError(err);\n        rollbackUrlToCurrentState();\n      }\n    } catch (error) {\n      if (error instanceof RouterError) {\n        // navigate() already emitted $$error — just sync URL with router state.\n        // Swallow rollback errors: teardown races may remove router.buildUrl\n        // while a popstate event is still queued.\n        try {\n          rollbackUrlToCurrentState();\n        } catch {\n          // noop — nothing safe to do here\n        }\n      } else {\n        recoverFromCriticalError(error);\n      }\n    } finally {\n      isTransitioning = false;\n      processDeferredEvent();\n    }\n  }\n\n  return (evt: PopStateEvent) => void onPopState(evt);\n}\n\nexport interface PopstateLifecycleDeps {\n  browser: Browser;\n  shared: SharedFactoryState;\n  handler: (evt: PopStateEvent) => void;\n  cleanup: () => void;\n}\n\nexport function createPopstateLifecycle(\n  deps: PopstateLifecycleDeps,\n): Pick<Plugin, \"onStart\" | \"onStop\" | \"teardown\"> {\n  return {\n    onStart: () => {\n      if (deps.shared.removePopStateListener) {\n        deps.shared.removePopStateListener();\n      }\n\n      deps.shared.removePopStateListener = deps.browser.addPopstateListener(\n        deps.handler,\n      );\n    },\n\n    onStop: () => {\n      if (deps.shared.removePopStateListener) {\n        deps.shared.removePopStateListener();\n        deps.shared.removePopStateListener = undefined;\n      }\n    },\n\n    teardown: () => {\n      if (deps.shared.removePopStateListener) {\n        deps.shared.removePopStateListener();\n        deps.shared.removePopStateListener = undefined;\n      }\n\n      deps.cleanup();\n    },\n  };\n}\n","/**\n * URL fragment (\"hash\") shared layer (#532).\n *\n * Both URL plugins (navigation-plugin, browser-plugin) claim the `\"url\"`\n * `state.context` namespace and write `UrlContext` on every transition.\n * Mutually exclusive at runtime — only one URL plugin is installed per router.\n *\n * Hash form: decoded, no leading \"#\" — symmetric to `params` (no leading \"?\").\n * Encoding to/from URL form happens at the boundary (URL build / URL parse).\n */\n\nexport interface UrlContext {\n  /** Decoded fragment, no leading \"#\". Empty string when URL has no fragment. */\n  hash: string;\n  /** Whether `hash` differs from the previous transition's `state.context.url.hash`. */\n  hashChanged: boolean;\n}\n\n/**\n * Encode for URL fragment per RFC 3986: preserves sub-delims (`&`, `=`, `?`,\n * `:`, etc.) and the path/query characters that `encodeURI` already leaves\n * alone. Defensively percent-escapes `#` (a stray `#` in a decoded fragment\n * would otherwise terminate the fragment in the rendered URL).\n *\n * `encodeURIComponent` over-encodes RFC-3986 sub-delims (`&` → `%26`) and is\n * therefore wrong for fragments.\n */\nexport function encodeHashFragment(decoded: string): string {\n  return encodeURI(decoded).replaceAll(\"#\", \"%23\");\n}\n\n/**\n * Decode a percent-encoded fragment. Falls back to the raw input on malformed\n * escapes — matches the resilience pattern in scroll-restore.\n */\nexport function decodeHashFragment(encoded: string): string {\n  try {\n    return decodeURIComponent(encoded);\n  } catch {\n    return encoded;\n  }\n}\n\n/**\n * Normalize user-provided hash input: strip a leading \"#\" if present, then\n * decode. Defensive against `<Link hash=\"#section\">` — the prop is documented\n * to accept the fragment name without \"#\", but we accept both gracefully.\n */\nexport function normalizeHashInput(input: string): string {\n  const stripped = input.startsWith(\"#\") ? input.slice(1) : input;\n\n  return decodeHashFragment(stripped);\n}\n\n/**\n * Read the current browser hash in decoded form, no leading \"#\".\n * Accepts any object with a `getHash()` method — works for both `Browser`\n * (History API) and `NavigationBrowser` (Navigation API). SSR-safe via the\n * abstractions, which return `\"\"` outside a real browser.\n */\nexport function getDecodedHash(browser: { getHash: () => string }): string {\n  const raw = browser.getHash();\n\n  if (!raw) {\n    return \"\";\n  }\n\n  const stripped = raw.startsWith(\"#\") ? raw.slice(1) : raw;\n\n  return decodeHashFragment(stripped);\n}\n","import { encodeHashFragment, normalizeHashInput } from \"./url-context.js\";\n\nimport type {\n  NavigationOptions,\n  Params,\n  Router,\n  State,\n} from \"@real-router/core\";\nimport type { PluginApi } from \"@real-router/core/api\";\n\nexport interface LocationSource {\n  getLocation: () => string;\n}\n\n/**\n * Minimal browser surface needed by `createReplaceHistoryState`.\n *\n * Both `Browser` (History API) and navigation-plugin's `NavigationBrowser`\n * (Navigation API) satisfy this structurally — the function never needs\n * `pushState`/`addPopstateListener`, only the replace path.\n */\nexport interface ReplaceStateBrowser {\n  replaceState: (state: unknown, url: string) => void;\n  getHash: () => string;\n}\n\n/**\n * Hash override option for `replaceHistoryState` (#532). Tri-state semantics:\n *   `undefined`  — preserve the current browser hash (legacy behavior, default)\n *   `\"\"`         — explicitly clear the fragment\n *   non-empty    — explicitly set the fragment (decoded form, no leading \"#\")\n */\nexport interface ReplaceHistoryStateOptions {\n  hash?: string;\n}\n\nexport function createStartInterceptor(\n  api: PluginApi,\n  browser: LocationSource,\n): () => void {\n  return api.addInterceptor(\"start\", (next, path) =>\n    next(path ?? browser.getLocation()),\n  );\n}\n\nexport function createReplaceHistoryState(\n  api: PluginApi,\n  router: Router,\n  browser: ReplaceStateBrowser,\n  buildUrl: (\n    name: string,\n    params?: Params,\n    options?: ReplaceHistoryStateOptions,\n  ) => string,\n  preserveHash = true,\n): (\n  name: string,\n  params?: Params,\n  options?: ReplaceHistoryStateOptions,\n) => void {\n  // Reusable buffer — browsers structured-clone state synchronously inside\n  // replaceState, so the buffer never escapes. Eliminates one allocation per\n  // navigation on the hot path. (Mirrors createUpdateBrowserState.)\n  const buffer = {\n    name: \"\",\n    params: {} as Params,\n    path: \"\",\n  };\n\n  return (\n    name: string,\n    params: Params = {},\n    options?: ReplaceHistoryStateOptions,\n  ) => {\n    const state = api.buildState(name, params);\n\n    if (!state) {\n      throw new Error(\n        `[real-router] Cannot replace state: route \"${name}\" is not found`,\n      );\n    }\n\n    const builtState = api.makeState(\n      state.name,\n      state.params,\n      router.buildPath(state.name, state.params),\n      {\n        params: state.meta,\n      },\n    );\n\n    // Tri-state hash semantics (#532):\n    //   options.hash === undefined → preserve (legacy behavior, controlled by\n    //                                preserveHash flag — true for browser/\n    //                                navigation plugins, false for hash-plugin)\n    //   options.hash === \"\"        → explicitly clear\n    //   options.hash === \"value\"   → explicitly set\n    let hashSegment: string;\n\n    if (options?.hash !== undefined) {\n      const norm = normalizeHashInput(options.hash);\n\n      hashSegment = norm ? `#${encodeHashFragment(norm)}` : \"\";\n    } else if (preserveHash) {\n      hashSegment = browser.getHash();\n    } else {\n      hashSegment = \"\";\n    }\n\n    // Pass hash through buildUrl when the plugin understands it (avoids\n    // double-append). Hash-plugin's buildUrl ignores the option and warns,\n    // so call without options here for semantic clarity — but the result is\n    // identical because hashSegment is \"\" in that branch (preserveHash=false).\n    const url = buildUrl(name, params) + hashSegment;\n\n    buffer.name = builtState.name;\n    buffer.params = builtState.params;\n    buffer.path = builtState.path;\n\n    browser.replaceState(buffer, url);\n  };\n}\n\nexport function shouldReplaceHistory(\n  navOptions: NavigationOptions,\n  toState: State,\n  fromState: State | undefined,\n): boolean {\n  if (navOptions.replace === true) {\n    return true;\n  }\n\n  if (!fromState) {\n    return navOptions.replace !== false;\n  }\n\n  return !!navOptions.reload && toState.path === fromState.path;\n}\n","export interface ParsedUrl {\n  pathname: string;\n  search: string;\n  hash: string;\n}\n\n/**\n * Scheme-agnostic URL parser.\n *\n * Extracts `pathname`, `search`, and `hash` from any string — absolute\n * (`scheme://authority/path?q#h`), path-relative (`/path?q#h`), or opaque\n * (`data:...`, `javascript:...`). Never throws, never returns null.\n *\n * Routing does not care about scheme or authority, only about the path part.\n * This keeps `browser-plugin`, `navigation-plugin`, and `hash-plugin` working\n * in Electron (`file://`, `app://`), Tauri (`tauri://`, `https://`), and any\n * other webview that may ship with non-HTTP origins. See issue #496.\n */\nexport function safeParseUrl(url: string): ParsedUrl {\n  let rest = url;\n\n  const schemeIdx = rest.indexOf(\"://\");\n\n  if (schemeIdx !== -1) {\n    const authorityStart = schemeIdx + 3;\n    let pathStart = rest.length;\n\n    for (let i = authorityStart; i < rest.length; i++) {\n      const ch = rest[i];\n\n      if (ch === \"/\" || ch === \"?\" || ch === \"#\") {\n        pathStart = i;\n\n        break;\n      }\n    }\n\n    rest = pathStart === rest.length ? \"/\" : rest.slice(pathStart);\n\n    if (rest.startsWith(\"?\") || rest.startsWith(\"#\")) {\n      rest = `/${rest}`;\n    }\n  }\n\n  const hashIdx = rest.indexOf(\"#\");\n  const hash = hashIdx === -1 ? \"\" : rest.slice(hashIdx);\n  const beforeHash = hashIdx === -1 ? rest : rest.slice(0, hashIdx);\n\n  const queryIdx = beforeHash.indexOf(\"?\");\n  const search = queryIdx === -1 ? \"\" : beforeHash.slice(queryIdx);\n  const pathname = queryIdx === -1 ? beforeHash : beforeHash.slice(0, queryIdx);\n\n  return { pathname, search, hash };\n}\n","// packages/hash-plugin/src/constants.ts\n\nimport type { HashPluginOptions } from \"./types\";\n\nexport const defaultOptions: Required<HashPluginOptions> = {\n  hashPrefix: \"\",\n  base: \"\",\n  forceDeactivate: true,\n};\n\n/**\n * Source identifier for transitions triggered by browser events.\n */\nexport const source = \"popstate\";\n\nexport const LOGGER_CONTEXT = \"hash-plugin\";\n","// packages/hash-plugin/src/hash-utils.ts\n\nimport { safelyEncodePath, safeParseUrl } from \"./browser-env\";\n\nfunction escapeRegExp(str: string): string {\n  return str.replaceAll(/[$()*+.?[\\\\\\]^{|}-]/g, String.raw`\\$&`);\n}\n\nexport function createHashPrefixRegex(hashPrefix: string): RegExp | null {\n  if (!hashPrefix) {\n    return null;\n  }\n\n  return new RegExp(`^#${escapeRegExp(hashPrefix)}`);\n}\n\n/**\n * Extract path from URL hash, stripping hash prefix.\n *\n * @param hash - URL hash (e.g., \"#/path\" or \"#!/path\")\n * @param prefixRegex - Pre-compiled regex for prefix stripping (null if no prefix)\n * @returns Extracted path (e.g., \"/path\")\n */\nexport function extractHashPath(\n  hash: string,\n  prefixRegex: RegExp | null,\n): string {\n  if (hash === \"\" || hash === \"#\") {\n    return \"/\";\n  }\n\n  const path = prefixRegex ? hash.replace(prefixRegex, \"\") : hash.slice(1);\n\n  return path || \"/\";\n}\n\nexport function hashUrlToPath(url: string, prefixRegex: RegExp | null): string {\n  const parsedUrl = safeParseUrl(url);\n  const hashPath = extractHashPath(parsedUrl.hash, prefixRegex);\n\n  return hashPath.includes(\"?\") ? hashPath : hashPath + parsedUrl.search;\n}\n\n/**\n * Build the router-side location string from a hash + query pair.\n *\n * Encodes the hash path via `safelyEncodePath` after stripping the\n * configured prefix, then appends the outer `search` only when the hash\n * path itself does not already carry a `?` — otherwise the outer search\n * would be duplicated (see `url.test.ts` — \"well-formed path (no double '?')\").\n *\n * Used by the `createSafeBrowser` `getLocation` callback both in the\n * production factory and in functional/stress test helpers. Extracting\n * here keeps the production path and test mocks aligned; a regression in\n * this logic previously slipped between the two.\n */\nexport function buildHashLocation(\n  hash: string,\n  search: string,\n  prefixRegex: RegExp | null,\n): string {\n  const hashPath = safelyEncodePath(extractHashPath(hash, prefixRegex));\n\n  return hashPath.includes(\"?\") ? hashPath : hashPath + search;\n}\n","import {\n  createPopstateHandler,\n  createPopstateLifecycle,\n  createStartInterceptor,\n  createReplaceHistoryState,\n  shouldReplaceHistory,\n  updateBrowserState,\n} from \"./browser-env\";\nimport { LOGGER_CONTEXT } from \"./constants\";\nimport { hashUrlToPath } from \"./hash-utils\";\n\nimport type { Browser, SharedFactoryState } from \"./browser-env\";\nimport type { HashPluginOptions } from \"./types\";\nimport type {\n  NavigationOptions,\n  Params,\n  Router,\n  State,\n  Plugin,\n} from \"@real-router/core\";\nimport type { PluginApi } from \"@real-router/core/api\";\n\nexport class HashPlugin {\n  readonly #router: Router;\n  readonly #browser: Browser;\n  readonly #removeStartInterceptor: () => void;\n  readonly #removeExtensions: () => void;\n  readonly #lifecycle: Pick<Plugin, \"onStart\" | \"onStop\" | \"teardown\">;\n  readonly #warnHashIgnored!: () => void;\n\n  constructor(\n    router: Router,\n    api: PluginApi,\n    options: Required<HashPluginOptions>,\n    browser: Browser,\n    prefixRegex: RegExp | null,\n    transitionOptions: {\n      source: string;\n      replace: true;\n      forceDeactivate?: boolean;\n    },\n    shared: SharedFactoryState,\n  ) {\n    this.#router = router;\n    this.#browser = browser;\n\n    this.#removeStartInterceptor = createStartInterceptor(api, browser);\n\n    // Hash limitation warn-once (#532). hash-plugin uses `#` as the route\n    // delimiter, so URL fragments are structurally incompatible. Plugin\n    // accepts the `hash` option for typing parity with browser/navigation\n    // plugins, ignores it, and emits a single console.warn the first time\n    // any consumer surfaces a hash. Existing `createWarnOnce` in browser-env\n    // is SSR-specific (different signature) — inline pattern here.\n    let hashWarned = false;\n    const warnHashIgnored = (): void => {\n      if (hashWarned) {\n        return;\n      }\n\n      hashWarned = true;\n      console.warn(\n        \"[@real-router/hash-plugin] `hash` option is ignored — `#` is reserved for the route delimiter. \" +\n          \"URL fragments are not supported with hash-plugin; use @real-router/browser-plugin or \" +\n          \"@real-router/navigation-plugin if you need them.\",\n      );\n    };\n\n    const urlPrefix = `${options.base}#${options.hashPrefix}`;\n    const pluginBuildUrl = (\n      route: string,\n      params?: Params,\n      opts?: { hash?: string },\n    ) => {\n      if (opts?.hash !== undefined) {\n        warnHashIgnored();\n      }\n\n      return urlPrefix + router.buildPath(route, params);\n    };\n\n    this.#warnHashIgnored = warnHashIgnored;\n\n    this.#removeExtensions = api.extendRouter({\n      buildUrl: pluginBuildUrl,\n      matchUrl: (url: string) =>\n        api.matchPath(hashUrlToPath(url, prefixRegex)) ?? undefined,\n      replaceHistoryState: createReplaceHistoryState(\n        api,\n        router,\n        browser,\n        pluginBuildUrl,\n        false,\n      ),\n    });\n\n    const handler = createPopstateHandler({\n      router,\n      api,\n      browser,\n      allowNotFound: api.getOptions().allowNotFound,\n      transitionOptions,\n      loggerContext: LOGGER_CONTEXT,\n      buildUrl: pluginBuildUrl,\n    });\n\n    this.#lifecycle = createPopstateLifecycle({\n      browser,\n      shared,\n      handler,\n      cleanup: () => {\n        this.#removeStartInterceptor();\n        this.#removeExtensions();\n      },\n    });\n  }\n\n  getPlugin(): Plugin {\n    return {\n      ...this.#lifecycle,\n\n      onTransitionSuccess: (\n        toState: State,\n        fromState: State | undefined,\n        navOptions: NavigationOptions,\n      ) => {\n        // Hash limitation (#532): warn once if a consumer programmatically\n        // requested a fragment via `router.navigate(..., { hash })`.\n        if (navOptions.hash !== undefined) {\n          this.#warnHashIgnored();\n        }\n\n        const replaceHistory = shouldReplaceHistory(\n          navOptions,\n          toState,\n          fromState,\n        );\n\n        const url = this.#router.buildUrl(toState.name, toState.params);\n\n        updateBrowserState(toState, url, replaceHistory, this.#browser);\n      },\n    };\n  }\n}\n","import {\n  createOptionsValidator,\n  safeBaseRule,\n  safeHashPrefixRule,\n} from \"./browser-env\";\nimport { LOGGER_CONTEXT, defaultOptions } from \"./constants\";\n\nimport type { HashPluginOptions } from \"./types\";\n\nexport const validateOptions = createOptionsValidator<HashPluginOptions>(\n  defaultOptions,\n  LOGGER_CONTEXT,\n  { base: safeBaseRule, hashPrefix: safeHashPrefixRule },\n);\n","import { getPluginApi } from \"@real-router/core/api\";\n\nimport { createSafeBrowser, normalizeBase } from \"./browser-env\";\nimport { defaultOptions, source } from \"./constants\";\nimport { buildHashLocation, createHashPrefixRegex } from \"./hash-utils\";\nimport { HashPlugin } from \"./plugin\";\nimport { validateOptions } from \"./validation\";\n\nimport type { Browser, SharedFactoryState } from \"./browser-env\";\nimport type { HashPluginOptions } from \"./types\";\nimport type { PluginFactory, Router } from \"@real-router/core\";\n\nexport function hashPluginFactory(\n  opts?: Partial<HashPluginOptions>,\n  browser?: Browser,\n): PluginFactory {\n  validateOptions(opts);\n\n  const definedOpts = opts\n    ? Object.fromEntries(\n        Object.entries(opts).filter(\n          // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime may receive explicit undefined via conditional spreads (exactOptionalPropertyTypes does not apply here)\n          ([, value]) => value !== undefined,\n        ),\n      )\n    : {};\n  const options: Required<HashPluginOptions> = {\n    ...defaultOptions,\n    ...definedOpts,\n  };\n\n  options.base = normalizeBase(options.base);\n\n  const prefixRegex = createHashPrefixRegex(options.hashPrefix);\n  const resolvedBrowser =\n    browser ??\n    createSafeBrowser(\n      () =>\n        buildHashLocation(\n          globalThis.location.hash,\n          globalThis.location.search,\n          prefixRegex,\n        ),\n      \"hash-plugin\",\n    );\n\n  const transitionOptions = {\n    forceDeactivate: options.forceDeactivate,\n    source,\n    replace: true as const,\n  };\n\n  const shared: SharedFactoryState = { removePopStateListener: undefined };\n\n  return function hashPlugin(routerBase) {\n    const plugin = new HashPlugin(\n      routerBase as Router,\n      getPluginApi(routerBase),\n      options,\n      resolvedBrowser,\n      prefixRegex,\n      transitionOptions,\n      shared,\n    );\n\n    return plugin.getPlugin();\n  };\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/hash-plugin",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "type": "commonjs",
   "description": "Hash-based routing plugin for Real-Router",
   "main": "./dist/cjs/index.js",
@@ -43,7 +43,8 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.51.0"
+    "@real-router/core": "^0.51.0",
+    "@real-router/types": "^0.35.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "6.9.1",

package/src/index.ts

@@ -18,26 +18,57 @@ export { isStateStrict as isState } from "type-guards";
 /**
  * Module augmentation for real-router.
  * Extends Router interface with hash plugin methods.
+ *
+ * NavigationOptions augmentation (#532) keeps the `hash` / `hashChange` keys
+ * known to TypeScript even when only hash-plugin is installed — runtime
+ * silently ignores them with a one-time warn.
  */
+declare module "@real-router/types" {
+  interface NavigationOptions {
+    /**
+     * URL fragment override (decoded, no leading "#"). Ignored by hash-plugin
+     * (URL fragments are structurally incompatible with hash routing); see
+     * `Router.buildUrl`. (#532)
+     */
+    hash?: string;
+    /** @internal — not used by hash-plugin. */
+    hashChange?: boolean;
+  }
+}
+
 declare module "@real-router/core" {
   interface Router {
     /**
      * Builds full URL for a route with base path and hash prefix.
      * Added by hash plugin.
+     *
+     * The optional `hash` option exists for typing parity with browser-plugin
+     * and navigation-plugin (#532). hash-plugin uses `#` as the route
+     * delimiter, so the option is silently ignored at runtime and a
+     * one-time `console.warn` is emitted.
      */
-    buildUrl: (name: string, params?: Params) => string;
+    buildUrl(
+      name: string,
+      params?: Params,
+      options?: { hash?: string },
+    ): string;
 
     /**
      * Matches URL and returns corresponding state.
      * Added by hash plugin.
      */
-    matchUrl: (url: string) => State | undefined;
+    matchUrl(url: string): State | undefined;
 
     /**
      * Replaces current history state without triggering navigation.
-     * Added by hash plugin.
+     * Added by hash plugin. The optional `hash` option is ignored (see
+     * `buildUrl`).
      */
-    replaceHistoryState: (name: string, params?: Params) => void;
+    replaceHistoryState(
+      name: string,
+      params?: Params,
+      options?: { hash?: string },
+    ): void;
 
     start(path?: string): Promise<State>;
   }

package/src/plugin.ts

@@ -26,6 +26,7 @@ export class HashPlugin {
   readonly #removeStartInterceptor: () => void;
   readonly #removeExtensions: () => void;
   readonly #lifecycle: Pick<Plugin, "onStart" | "onStop" | "teardown">;
+  readonly #warnHashIgnored!: () => void;
 
   constructor(
     router: Router,
@@ -45,9 +46,40 @@ export class HashPlugin {
 
     this.#removeStartInterceptor = createStartInterceptor(api, browser);
 
+    // Hash limitation warn-once (#532). hash-plugin uses `#` as the route
+    // delimiter, so URL fragments are structurally incompatible. Plugin
+    // accepts the `hash` option for typing parity with browser/navigation
+    // plugins, ignores it, and emits a single console.warn the first time
+    // any consumer surfaces a hash. Existing `createWarnOnce` in browser-env
+    // is SSR-specific (different signature) — inline pattern here.
+    let hashWarned = false;
+    const warnHashIgnored = (): void => {
+      if (hashWarned) {
+        return;
+      }
+
+      hashWarned = true;
+      console.warn(
+        "[@real-router/hash-plugin] `hash` option is ignored — `#` is reserved for the route delimiter. " +
+          "URL fragments are not supported with hash-plugin; use @real-router/browser-plugin or " +
+          "@real-router/navigation-plugin if you need them.",
+      );
+    };
+
     const urlPrefix = `${options.base}#${options.hashPrefix}`;
-    const pluginBuildUrl = (route: string, params?: Params) =>
-      urlPrefix + router.buildPath(route, params);
+    const pluginBuildUrl = (
+      route: string,
+      params?: Params,
+      opts?: { hash?: string },
+    ) => {
+      if (opts?.hash !== undefined) {
+        warnHashIgnored();
+      }
+
+      return urlPrefix + router.buildPath(route, params);
+    };
+
+    this.#warnHashIgnored = warnHashIgnored;
 
     this.#removeExtensions = api.extendRouter({
       buildUrl: pluginBuildUrl,
@@ -92,6 +124,12 @@ export class HashPlugin {
         fromState: State | undefined,
         navOptions: NavigationOptions,
       ) => {
+        // Hash limitation (#532): warn once if a consumer programmatically
+        // requested a fragment via `router.navigate(..., { hash })`.
+        if (navOptions.hash !== undefined) {
+          this.#warnHashIgnored();
+        }
+
         const replaceHistory = shouldReplaceHistory(
           navOptions,
           toState,