@real-router/browser-plugin 0.1.0

package/dist/cjs/index.d.ts

@@ -0,0 +1,252 @@
+import { State, DoneFn, PluginFactory, Params } from '@real-router/core';
+export { isHistoryState, isStateStrict as isState } from 'type-guards';
+
+/**
+ * Common options shared between hash and history modes
+ */
+interface BaseBrowserPluginOptions {
+    /**
+     * Force deactivation of current route even if canDeactivate returns false.
+     *
+     * @default true
+     */
+    forceDeactivate?: boolean;
+    /**
+     * Base path for all routes (e.g., "/app" for hosted at /app/).
+     *
+     * @default ""
+     */
+    base?: string;
+    /**
+     * Merge new state with existing history.state when updating.
+     * Useful for preserving external state set by other code.
+     *
+     * @default false
+     */
+    mergeState?: boolean;
+}
+/**
+ * Hash-based routing configuration.
+ * Uses URL hash for navigation (e.g., example.com/#/path).
+ *
+ * @example
+ * ```ts
+ * // Standard hash routing
+ * browserPluginFactory({ useHash: true })
+ * // → example.com/#/users
+ *
+ * // Hash routing with prefix
+ * browserPluginFactory({ useHash: true, hashPrefix: "!" })
+ * // → example.com/#!/users
+ * ```
+ */
+interface HashModeOptions extends BaseBrowserPluginOptions {
+    /**
+     * Enable hash-based routing
+     */
+    useHash: true;
+    /**
+     * Prefix for hash (e.g., "!" for "#!/path").
+     * Only valid when useHash is true.
+     *
+     * @default ""
+     */
+    hashPrefix?: string;
+    /**
+     * Not available in hash mode.
+     * Hash preservation only works with HTML5 History API.
+     * Use `useHash: false` to enable this option.
+     */
+    preserveHash?: never;
+}
+/**
+ * HTML5 History API routing configuration.
+ * Uses pushState/replaceState for navigation (e.g., example.com/path).
+ *
+ * @example
+ * ```ts
+ * // Standard history routing
+ * browserPluginFactory({ useHash: false })
+ * // → example.com/users
+ *
+ * // Preserve URL hash fragments
+ * browserPluginFactory({ useHash: false, preserveHash: true })
+ * // → example.com/users#section
+ * ```
+ */
+interface HistoryModeOptions extends BaseBrowserPluginOptions {
+    /**
+     * Disable hash-based routing (use HTML5 History API)
+     *
+     * @default false
+     */
+    useHash?: false;
+    /**
+     * Preserve URL hash fragment on initial navigation.
+     * Only valid when useHash is false.
+     *
+     * @default true
+     */
+    preserveHash?: boolean;
+    /**
+     * Not available in history mode.
+     * Hash prefix only works with hash-based routing.
+     * Use `useHash: true` to enable this option.
+     */
+    hashPrefix?: never;
+}
+/**
+ * Type-safe browser plugin configuration.
+ *
+ * Uses discriminated union to prevent conflicting options:
+ * - Hash mode (useHash: true): allows hashPrefix, forbids preserveHash
+ * - History mode (useHash: false): allows preserveHash, forbids hashPrefix
+ *
+ * @example
+ * ```ts
+ * // ✅ Valid: Hash mode with prefix
+ * const config1: BrowserPluginOptions = {
+ *   useHash: true,
+ *   hashPrefix: "!"
+ * };
+ *
+ * // ✅ Valid: History mode with hash preservation
+ * const config2: BrowserPluginOptions = {
+ *   useHash: false,
+ *   preserveHash: true
+ * };
+ *
+ * // ❌ Error: Cannot use preserveHash with hash mode
+ * const config3: BrowserPluginOptions = {
+ *   useHash: true,
+ *   preserveHash: true  // Type error!
+ * };
+ *
+ * // ❌ Error: Cannot use hashPrefix with history mode
+ * const config4: BrowserPluginOptions = {
+ *   useHash: false,
+ *   hashPrefix: "!"  // Type error!
+ * };
+ * ```
+ */
+type BrowserPluginOptions = HashModeOptions | HistoryModeOptions;
+/**
+ * Browser API abstraction for cross-environment compatibility.
+ * Provides same interface in browser and SSR contexts.
+ */
+interface Browser {
+    /**
+     * Gets base path from current browser location
+     *
+     * @returns Current pathname
+     */
+    getBase: () => string;
+    /**
+     * Pushes new state to browser history
+     *
+     * @param state - History state object
+     * @param title - Document title (usually ignored by browsers)
+     * @param path - URL path
+     */
+    pushState: (state: HistoryState, title: string | null, path: string) => void;
+    /**
+     * Replaces current history state
+     *
+     * @param state - History state object
+     * @param title - Document title (usually ignored by browsers)
+     * @param path - URL path
+     */
+    replaceState: (state: HistoryState, title: string | null, path: string) => void;
+    /**
+     * Adds popstate/hashchange event listeners.
+     * Overloaded to support both PopStateEvent and HashChangeEvent.
+     *
+     * @param fn - Event handler
+     * @param opts - Plugin options
+     * @returns Cleanup function to remove listeners
+     */
+    addPopstateListener: ((fn: (evt: PopStateEvent) => void, opts: BrowserPluginOptions) => () => void) & ((fn: (evt: HashChangeEvent) => void, opts: BrowserPluginOptions) => () => void);
+    /**
+     * Gets current location path respecting plugin options
+     *
+     * @param opts - Plugin options
+     * @returns Current path string
+     */
+    getLocation: (opts: BrowserPluginOptions) => string;
+    /**
+     * Gets current history state with validation
+     *
+     * @returns Valid history state or undefined
+     */
+    getState: () => HistoryState | undefined;
+    /**
+     * Gets current URL hash
+     *
+     * @returns Hash string (including #)
+     */
+    getHash: () => string;
+}
+/**
+ * History state object stored in browser history.
+ * Extends real-router State with additional properties that may be set by external code.
+ */
+type HistoryState = State & Record<string, unknown>;
+type StartRouterArguments = [] | [done: DoneFn] | [startPathOrState: string | State] | [startPathOrState: string | State, done: DoneFn];
+
+/**
+ * Browser plugin factory for real-router.
+ * Integrates router with browser history API.
+ *
+ * Features:
+ * - Syncs router state with browser history (pushState/replaceState)
+ * - Handles popstate events for browser back/forward navigation
+ * - Supports hash-based routing for legacy browsers
+ * - Provides URL building and matching utilities
+ * - SSR-safe with graceful fallbacks
+ * - Runtime validation warns about conflicting options
+ *
+ * @param opts - Plugin configuration options
+ * @param browser - Browser API abstraction (for testing/SSR)
+ * @returns Plugin factory function
+ *
+ * @example
+ * ```ts
+ * // Hash routing
+ * router.usePlugin(browserPluginFactory({ useHash: true, hashPrefix: "!" }));
+ *
+ * // History routing with hash preservation
+ * router.usePlugin(browserPluginFactory({ useHash: false, preserveHash: true }));
+ * ```
+ */
+declare function browserPluginFactory(opts?: Partial<BrowserPluginOptions>, browser?: Browser): PluginFactory;
+
+/**
+ * Module augmentation for real-router.
+ * Extends Router interface with browser plugin methods.
+ */
+declare module "@real-router/core" {
+    interface Router {
+        /**
+         * Builds full URL for a route with base path and hash prefix.
+         * Added by browser plugin.
+         */
+        buildUrl: (name: string, params?: Params) => string;
+        /**
+         * Matches URL and returns corresponding state.
+         * Added by browser plugin.
+         */
+        matchUrl: (url: string) => State | undefined;
+        /**
+         * Replaces current history state without triggering navigation.
+         * Added by browser plugin.
+         */
+        replaceHistoryState: (name: string, params?: Params, title?: string) => void;
+        /**
+         * Last known router state.
+         * Added by browser plugin.
+         */
+        lastKnownState?: State;
+    }
+}
+
+export { type Browser, type BrowserPluginOptions, type HistoryState, type StartRouterArguments, browserPluginFactory };

package/dist/cjs/index.js

@@ -0,0 +1 @@
+var e=require("type-guards"),t=require("@real-router/core"),a={forceDeactivate:!0,useHash:!1,hashPrefix:"",base:"",mergeState:!1,preserveHash:!0},r="popstate",n="browser-plugin",o=()=>{},s=new Map,i=e=>{const t=s.get(e);if(void 0!==t)return t;const a=e.replaceAll(/[$()*+.?[\\\]^{|}-]/g,String.raw`\$&`);return s.set(e,a),a};function l(e,t,a,r,n){const o={meta:e.meta,name:e.name,params:e.params,path:e.path},s=n.mergeState&&r.getState()?{...r.getState(),...o}:o;a?r.replaceState(s,"",t):r.pushState(s,"",t)}function c(e,t){return e in t}function u(e,t,a){const r=typeof t;return r===a||void 0===t||(console.warn(`[${n}] Invalid type for '${e}': expected ${a}, got ${r}`),!1)}var h=()=>{},p=()=>globalThis.location.pathname,d=(()=>{let e,t=!1;return()=>{const a=globalThis.navigator.userAgent;return a!==e&&(e=a,t=!a.includes("Trident")),t}})(),g=(e,t,a)=>{globalThis.history.pushState(e,t??"",a)},f=(e,t,a)=>{globalThis.history.replaceState(e,t??"",a)},b=(e,t)=>{const a=t.useHash&&!d();return globalThis.addEventListener("popstate",e),a&&globalThis.addEventListener("hashchange",e),()=>{globalThis.removeEventListener("popstate",e),a&&globalThis.removeEventListener("hashchange",e)}},S=(()=>{const e=new Map;return t=>{let a=e.get(t);return a||(a=new RegExp(t),e.set(t,a)),a}})(),m=e=>{const{useHash:t,hashPrefix:a="",base:r=""}=e;if(!a&&!r){const e=t?globalThis.location.hash.slice(1):globalThis.location.pathname;return(v(e)||"/")+globalThis.location.search}const n=i(a),o=i(r),s=t?globalThis.location.hash.replace(S(`^#${n}`),""):globalThis.location.pathname.replace(S(`^${o}`),"");return(v(s)||"/")+globalThis.location.search},v=e=>{try{return encodeURI(decodeURI(e))}catch(t){return console.warn(`[${n}] Could not encode path "${e}"`,t),e}},T=()=>{if(globalThis.history.state){if(e.isHistoryState(globalThis.history.state))return globalThis.history.state;console.warn(`[${n}] History state is not a valid state object, ignoring`,globalThis.history.state)}},y=()=>globalThis.location.hash;Object.defineProperty(exports,"isHistoryState",{enumerable:!0,get:function(){return e.isHistoryState}}),Object.defineProperty(exports,"isState",{enumerable:!0,get:function(){return e.isStateStrict}}),exports.browserPluginFactory=function(s,d=function(){return void 0!==globalThis.window&&globalThis.history?{getBase:p,pushState:g,replaceState:f,addPopstateListener:b,getLocation:m,getState:T,getHash:y}:function(){let e=!1;const t=t=>{e||(console.warn(`[${n}] Browser plugin is running in a non-browser environment. Method "${t}" is a no-op. This is expected for SSR, but may indicate misconfiguration if you expected browser behavior.`),e=!0)};return{getBase:()=>(t("getBase"),""),pushState:()=>{t("pushState")},replaceState:()=>{t("replaceState")},addPopstateListener:()=>(t("addPopstateListener"),h),getLocation:()=>(t("getLocation"),""),getState:()=>{t("getState")},getHash:()=>(t("getHash"),"")}}()}()){const S=function(e,t){if(!e)return!1;let a=!1;for(const r of Object.keys(e))c(r,t)&&(u(r,e[r],typeof t[r])||(a=!0));if(!0===e.useHash&&"preserveHash"in e&&console.warn(`[${n}] preserveHash ignored in hash mode`),!1===e.useHash&&"hashPrefix"in e){const t=e.hashPrefix;void 0!==t&&""!==t&&console.warn(`[${n}] hashPrefix ignored in history mode`)}return a}(s,a);let v={...a,...s};S&&(console.warn(`[${n}] Using default options due to invalid types`),v={...a}),!0===v.useHash?delete v.preserveHash:delete v.hashPrefix,v.base&&"string"==typeof v.base&&(v.base.startsWith("/")||(v.base=`/${v.base}`),v.base.endsWith("/")&&(v.base=v.base.slice(0,-1)));const w=new Map,$=e=>{const t=w.get(e);if(void 0!==t)return t;const a=new RegExp(e);return w.set(e,a),a},H=v.forceDeactivate,P=void 0===H?{source:r}:{forceDeactivate:H,source:r};let L;return function(a){const s=a.start;let c,u=!1,h=null;const p=()=>v.base??"",g=v.hashPrefix??"",f=i(g),b=v.useHash?`#${g}`:"",S=f?$(`^#${f}`):null;function m(){if(h){const e=h;h=null,console.warn(`[${n}] Processing deferred popstate event`),T(e)}}function T(o){if(u)return console.warn(`[${n}] Transition in progress, deferring popstate event`),void(h=o);try{const n=a.getState(),s=function(t,a,r,n,o){return e.isStateStrict(t.state)?a.makeState(t.state.name,t.state.params,t.state.path,{...t.state.meta,params:t.state.meta?.params??{},options:t.state.meta?.options??{},redirected:!!t.state.meta?.redirected,source:o},t.state.meta?.id):a.matchPath(r.getLocation(n),o)}(o,a,d,v,r),i=!e.isStateStrict(o.state);if(!s&&function(e,t){const a=e.getOptions(),{defaultRoute:r}=a;return!!r&&(e.navigateToDefault({...t,reload:!0,replace:!0}),!0)}(a,P))return;if(function(e,t,a){return!e||!(!t||!a.areStatesEqual(e,t,!1))}(s,n,a))return;u=!0,a.navigateToState(s,n,P,(e,r)=>{u=!1,function(e,a,r,n,o,s,i){e?e.code===t.errorCodes.CANNOT_DEACTIVATE&&a&&r&&!n&&l(r,o.buildUrl(r.name,r.params),!0,s,i):o.invokeEventListeners(t.events.TRANSITION_SUCCESS,a,r,{replace:!0})}(e,r,n,i,a,d,v),m()},!1)}catch(e){u=!1,console.error(`[${n}] Critical error in onPopState`,e);try{const e=a.getState();if(e){const t=a.buildUrl(e.name,e.params);d.replaceState(e,"",t)}}catch(e){console.error(`[${n}] Failed to recover from critical error`,e)}m()}}return a.start=(...e)=>{const[t,r]=function(e,t,a){if(0===e.length){const e=t.getLocation(a);return"/"===e?[void 0,o]:[e,o]}if(1===e.length)return"function"==typeof e[0]?[t.getLocation(a),e[0]]:[e[0],o];const[r,n]=e;return[r,n]}(e,d,v);return t?s(t,r):s(r),a},a.buildUrl=(e,t)=>{const r=a.buildPath(e,t);return p()+b+r},a.matchUrl=e=>{const t=(e=>{try{const t=new URL(e,globalThis.location.origin),a=t.pathname,r=t.hash,o=t.search,s=p();if(!["http:","https:"].includes(t.protocol))return console.warn(`[${n}] Invalid URL protocol in ${e}`),null;if(v.useHash)return(S?r.replace(S,""):r.slice(1))+o;if(s){const e=i(s),t=$(`^${e}`),r=a.replace(t,"");return(r.startsWith("/")?"":"/")+r+o}return a+o}catch(t){return console.warn(`[${n}] Could not parse url ${e}`,t),null}})(e);return t?a.matchPath(t,r):void 0},a.replaceHistoryState=(e,t={})=>{const r=a.buildState(e,t);if(!r)throw new Error(`[real-router] Cannot replace state: route "${e}" is not found`);l(a.makeState(r.name,r.params,a.buildPath(r.name,r.params),{params:r.meta,options:{},redirected:!1},1),a.buildUrl(e,t),!0,d,v)},Object.defineProperty(a,"lastKnownState",{get:()=>c,set(e){c=e?Object.freeze({...e}):void 0},enumerable:!0,configurable:!0}),{onStart:()=>{L&&L(),L=d.addPopstateListener(T,v)},onStop:()=>{L&&(L(),L=void 0)},onTransitionSuccess:(e,t,r)=>{a.lastKnownState=e;const n=(r.replace??!t)||!!r.reload&&a.areStatesEqual(e,t,!1),o=a.buildUrl(e.name,e.params);l(e,!v.preserveHash||t&&t.path!==e.path?o:o+d.getHash(),n,d,v)},teardown:()=>{L&&(L(),L=void 0),a.start=s,delete a.buildUrl,delete a.matchUrl,delete a.replaceHistoryState,delete a.lastKnownState}}}};//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/constants.ts","../../src/utils.ts","../../src/browser.ts","../../src/plugin.ts"],"names":["source","isState","events","errorCodes","defaultOptions","rawPath","safePath","isHistoryState","getCachedRegExp","getBase"],"mappings":"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","file":"index.js","sourcesContent":["// packages/browser-plugin/modules/constants.ts\n\n/**\n * Internal type for default options.\n *\n * Why separate type instead of BrowserPluginOptions?\n *\n * BrowserPluginOptions is a discriminated union:\n * - HashModeOptions: allows hashPrefix, forbids preserveHash (never)\n * - HistoryModeOptions: allows preserveHash, forbids hashPrefix (never)\n *\n * We cannot create a single object of type BrowserPluginOptions that contains\n * BOTH hashPrefix and preserveHash - one will always be 'never' depending on useHash.\n *\n * Example - this would fail TypeScript:\n * const defaults: BrowserPluginOptions = {\n *   useHash: false,      // → HistoryModeOptions branch\n *   preserveHash: true,  // ✅ OK\n *   hashPrefix: \"\"       // ❌ Error: Type 'string' is not assignable to type 'never'\n * };\n *\n * DefaultBrowserPluginOptions solves this by containing ALL options,\n * enabling:\n * - Default values for every option\n * - Type validation via typeof defaultOptions\n * - Runtime validation of user-provided option types\n */\nexport interface DefaultBrowserPluginOptions {\n  forceDeactivate: boolean;\n  useHash: boolean;\n  base: string;\n  mergeState: boolean;\n  preserveHash: boolean;\n  hashPrefix: string;\n}\n\nexport const defaultOptions: DefaultBrowserPluginOptions = {\n  forceDeactivate: true,\n  useHash: false,\n  hashPrefix: \"\",\n  base: \"\",\n  mergeState: false,\n  preserveHash: true,\n};\n\n/**\n * Source identifier for transitions triggered by browser events.\n * Used to distinguish browser-initiated navigation (back/forward buttons)\n * from programmatic navigation (router.navigate()).\n */\nexport const source = \"popstate\";\n\nexport const LOGGER_CONTEXT = \"browser-plugin\";\n","// packages/browser-plugin/modules/utils.ts\n\nimport { errorCodes, events } from \"@real-router/core\";\nimport { isStateStrict as isState } from \"type-guards\";\n\nimport { type DefaultBrowserPluginOptions, LOGGER_CONTEXT } from \"./constants\";\n\nimport type {\n  BrowserPluginOptions,\n  HistoryState,\n  StartRouterArguments,\n  Browser,\n} from \"./types\";\nimport type {\n  Router,\n  State,\n  DoneFn,\n  NavigationOptions,\n  RouterError,\n} from \"@real-router/core\";\n\n/**\n * No-op function for default callbacks\n */\nexport const noop = (): void => undefined;\n\n/**\n * Cache for escaped RegExp strings\n */\nconst escapeRegExpCache = new Map<string, string>();\n\n/**\n * Escapes special RegExp characters in a string.\n * Used to safely build RegExp from user-provided strings (hashPrefix, base).\n *\n * @param str - String to escape\n * @returns Escaped string safe for RegExp construction\n */\nexport const escapeRegExp = (str: string): string => {\n  const cached = escapeRegExpCache.get(str);\n\n  if (cached !== undefined) {\n    return cached;\n  }\n\n  const escaped = str.replaceAll(/[$()*+.?[\\\\\\]^{|}-]/g, String.raw`\\$&`);\n\n  escapeRegExpCache.set(str, escaped);\n\n  return escaped;\n};\n\n/**\n * Extracts start router arguments from various overloads\n *\n * @param args - Arguments passed to router.start()\n * @param browser - Browser API instance\n * @param options - Browser plugin options\n * @returns Tuple of [startPathOrState, done callback]\n */\nexport function getStartRouterArguments(\n  args: StartRouterArguments,\n  browser: Browser,\n  options: BrowserPluginOptions,\n): [startPathOrState: string | State | undefined, done: DoneFn] {\n  if (args.length === 0) {\n    const location = browser.getLocation(options);\n\n    if (location === \"/\") {\n      return [undefined, noop];\n    }\n\n    return [location, noop];\n  }\n\n  if (args.length === 1) {\n    if (typeof args[0] === \"function\") {\n      return [browser.getLocation(options), args[0]];\n    }\n\n    return [args[0], noop];\n  }\n\n  // args.length === 2\n  const [pathOrState, done] = args as [string | State, DoneFn];\n\n  return [pathOrState, done];\n}\n\n/**\n * Creates state from popstate event\n *\n * @param evt - PopStateEvent from browser\n * @param router - Router instance\n * @param browser - Browser API instance\n * @param options - Browser plugin options\n * @param source - Event source identifier\n * @returns Router state or undefined\n */\nexport function createStateFromEvent(\n  evt: PopStateEvent,\n  router: Router,\n  browser: Browser,\n  options: BrowserPluginOptions,\n  source: string,\n): State | undefined {\n  const isNewState = !isState(evt.state);\n\n  if (isNewState) {\n    return router.matchPath(browser.getLocation(options), source);\n  }\n\n  return router.makeState(\n    evt.state.name,\n    evt.state.params,\n    evt.state.path,\n    {\n      ...evt.state.meta,\n      params: evt.state.meta?.params ?? {},\n      options: evt.state.meta?.options ?? {},\n      redirected: !!evt.state.meta?.redirected,\n      source,\n    },\n    evt.state.meta?.id,\n  );\n}\n\n/**\n * Checks if transition should be skipped (same states)\n *\n * @param newState - New state from event\n * @param currentState - Current router state\n * @param router - Router instance\n * @returns true if transition should be skipped\n */\nexport function shouldSkipTransition(\n  newState: State | undefined,\n  currentState: State | undefined,\n  router: Router,\n): boolean {\n  if (!newState) {\n    return true;\n  }\n\n  return !!(\n    currentState && router.areStatesEqual(newState, currentState, false)\n  );\n}\n\n/**\n * Handles missing state by navigating to default route\n *\n * @param router - Router instance\n * @param transitionOptions - Options for transition\n * @returns true if handled, false if no default route\n */\nexport function handleMissingState(\n  router: Router,\n  transitionOptions: NavigationOptions,\n): boolean {\n  const routerOptions = router.getOptions();\n  const { defaultRoute } = routerOptions;\n\n  if (!defaultRoute) {\n    return false;\n  }\n\n  router.navigateToDefault({\n    ...transitionOptions,\n    reload: true,\n    replace: true,\n  });\n\n  return true;\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 * @param options - Browser plugin options\n */\nexport function updateBrowserState(\n  state: State,\n  url: string,\n  replace: boolean,\n  browser: Browser,\n  options: BrowserPluginOptions,\n): void {\n  const trimmedState: HistoryState = {\n    meta: state.meta,\n    name: state.name,\n    params: state.params,\n    path: state.path,\n  };\n\n  const finalState: HistoryState =\n    options.mergeState && browser.getState()\n      ? { ...browser.getState(), ...trimmedState }\n      : trimmedState;\n\n  if (replace) {\n    browser.replaceState(finalState, \"\", url);\n  } else {\n    browser.pushState(finalState, \"\", url);\n  }\n}\n\n/**\n * Handles transition result (success, redirect, or error)\n *\n * @param err - Router error or undefined if successful\n * @param toState - Target state\n * @param fromState - Source state\n * @param isNewState - Whether this is a new state (not from history)\n * @param router - Router instance\n * @param browser - Browser API instance\n * @param options - Browser plugin options\n */\nexport function handleTransitionResult(\n  err: RouterError | undefined,\n  toState: State | undefined,\n  fromState: State | undefined,\n  isNewState: boolean,\n  router: Router,\n  browser: Browser,\n  options: BrowserPluginOptions,\n): void {\n  // Successful transition\n  if (!err) {\n    router.invokeEventListeners(events.TRANSITION_SUCCESS, toState, fromState, {\n      replace: true,\n    });\n\n    return;\n  }\n\n  // Handle CANNOT_DEACTIVATE\n  if (\n    err.code === errorCodes.CANNOT_DEACTIVATE &&\n    toState &&\n    fromState &&\n    !isNewState\n  ) {\n    const url = router.buildUrl(fromState.name, fromState.params);\n\n    updateBrowserState(fromState, url, true, browser, options);\n  }\n}\n\n/**\n * Type guard to check if a key exists in default options\n */\nfunction isDefaultOptionKey(\n  key: string,\n  defaults: DefaultBrowserPluginOptions,\n): key is keyof DefaultBrowserPluginOptions {\n  return key in defaults;\n}\n\n/**\n * Validates that an option value has the correct type\n */\nfunction validateOptionType(\n  key: keyof DefaultBrowserPluginOptions,\n  value: unknown,\n  expectedType: string,\n): boolean {\n  const actualType = typeof value;\n\n  if (actualType !== expectedType && value !== undefined) {\n    console.warn(\n      `[${LOGGER_CONTEXT}] Invalid type for '${key}': expected ${expectedType}, got ${actualType}`,\n    );\n\n    return false;\n  }\n\n  return true;\n}\n\n/**\n * Validates browser plugin options and warns about conflicting configurations.\n * TypeScript types prevent conflicts at compile-time, but runtime validation\n * is needed for JavaScript users and dynamic configurations.\n *\n * IMPORTANT: This validates only user-provided options, not merged defaults.\n *\n * @returns true if invalid types detected, false otherwise\n */\nexport function validateOptions(\n  opts: Partial<BrowserPluginOptions> | undefined,\n  defaultOptions: DefaultBrowserPluginOptions,\n): boolean {\n  if (!opts) {\n    return false;\n  }\n\n  let hasInvalidTypes = false;\n\n  // Validate option types against defaults\n  // Using Object.keys ensures we only check properties that actually exist\n  for (const key of Object.keys(opts)) {\n    if (isDefaultOptionKey(key, defaultOptions)) {\n      const expectedType = typeof defaultOptions[key];\n      const value = opts[key];\n      const isValid = validateOptionType(key, value, expectedType);\n\n      if (!isValid) {\n        hasInvalidTypes = true;\n      }\n    }\n  }\n\n  // Check for hash mode conflicts\n  // Runtime validation for JS users - TypeScript prevents this at compile time\n\n  if (opts.useHash === true && \"preserveHash\" in opts) {\n    console.warn(`[${LOGGER_CONTEXT}] preserveHash ignored in hash mode`);\n  }\n\n  // Check for history mode conflicts\n  // Runtime validation for JS users - TypeScript prevents this at compile time\n\n  if (opts.useHash === false && \"hashPrefix\" in opts) {\n    // Single type assertion needed: TypeScript narrows opts to HistoryModeOptions\n    // where hashPrefix is 'never', but we need to check it at runtime for JS users\n    const optsRecord = opts as unknown as Record<string, unknown>;\n    const hashPrefix = optsRecord.hashPrefix;\n\n    if (hashPrefix !== undefined && hashPrefix !== \"\") {\n      console.warn(`[${LOGGER_CONTEXT}] hashPrefix ignored in history mode`);\n    }\n  }\n\n  return hasInvalidTypes;\n}\n","// packages/browser-plugin/modules/browser.ts\n\nimport { isHistoryState } from \"type-guards\";\n\nimport { LOGGER_CONTEXT } from \"./constants\";\nimport { escapeRegExp } from \"./utils\";\n\nimport type { Browser, BrowserPluginOptions, HistoryState } from \"./types\";\nimport type { State } from \"@real-router/core\";\n\n/** No-operation cleanup function for fallback browser */\nconst NOOP = (): void => {};\n\n/**\n * Returns current base path from browser location\n */\nconst getBase = () => globalThis.location.pathname;\n\n/**\n * Detects if browser supports popstate events on hash changes.\n * Old IE (Trident engine) doesn't fire popstate on hashchange.\n * Uses memoization based on userAgent for performance while remaining testable.\n */\nconst supportsPopStateOnHashChange = (() => {\n  let cachedUserAgent: string | undefined;\n  let cachedResult = false;\n\n  return (): boolean => {\n    // Note: This function is only called from real browser's addPopstateListener,\n    // never from fallback browser (SSR), so window is guaranteed to exist\n    const currentUserAgent = globalThis.navigator.userAgent;\n\n    // Only recalculate if userAgent changed (or first call)\n    if (currentUserAgent !== cachedUserAgent) {\n      cachedUserAgent = currentUserAgent;\n      cachedResult = !currentUserAgent.includes(\"Trident\");\n    }\n\n    return cachedResult;\n  };\n})();\n\n/**\n * Pushes new state to browser history\n */\nconst pushState = (state: State, title: string | null, path: string | URL) => {\n  globalThis.history.pushState(state, title ?? \"\", path);\n};\n\n/**\n * Replaces current state in browser history\n */\nconst replaceState = (\n  state: State,\n  title: string | null,\n  path: string | URL,\n) => {\n  globalThis.history.replaceState(state, title ?? \"\", path);\n};\n\n/**\n * Adds popstate/hashchange event listeners based on browser capabilities\n *\n * @param fn - Event handler function\n * @param opts - Browser plugin options\n * @returns Cleanup function to remove listeners\n */\nconst addPopstateListener: Browser[\"addPopstateListener\"] = (fn, opts) => {\n  const needsHashChangeListener =\n    opts.useHash && !supportsPopStateOnHashChange();\n\n  globalThis.addEventListener(\"popstate\", fn as (evt: PopStateEvent) => void);\n\n  if (needsHashChangeListener) {\n    globalThis.addEventListener(\n      \"hashchange\",\n      fn as (evt: HashChangeEvent) => void,\n    );\n  }\n\n  return () => {\n    globalThis.removeEventListener(\n      \"popstate\",\n      fn as (evt: PopStateEvent) => void,\n    );\n\n    if (needsHashChangeListener) {\n      globalThis.removeEventListener(\n        \"hashchange\",\n        fn as (evt: HashChangeEvent) => void,\n      );\n    }\n  };\n};\n\n/**\n * Creates RegExp cache for getLocation optimization\n */\nconst createRegExpCache = () => {\n  const cache = new Map<string, RegExp>();\n\n  return (pattern: string): RegExp => {\n    let regex = cache.get(pattern);\n\n    if (!regex) {\n      regex = new RegExp(pattern);\n      cache.set(pattern, regex);\n    }\n\n    return regex;\n  };\n};\n\nconst getCachedRegExp = createRegExpCache();\n\n/**\n * Gets current location path from browser, respecting plugin options\n *\n * @param opts - Browser plugin options\n * @returns Current path string\n */\nconst getLocation = (opts: BrowserPluginOptions) => {\n  const { useHash, hashPrefix = \"\", base = \"\" } = opts;\n\n  // Optimization: skip RegExp for empty values\n  if (!hashPrefix && !base) {\n    const rawPath = useHash\n      ? globalThis.location.hash.slice(1)\n      : globalThis.location.pathname;\n    const safePath = safelyEncodePath(rawPath);\n\n    return (safePath || \"/\") + globalThis.location.search;\n  }\n\n  const escapedHashPrefix = escapeRegExp(hashPrefix);\n  const escapedBase = escapeRegExp(base);\n\n  const rawPath = useHash\n    ? globalThis.location.hash.replace(\n        getCachedRegExp(`^#${escapedHashPrefix}`),\n        \"\",\n      )\n    : globalThis.location.pathname.replace(\n        getCachedRegExp(`^${escapedBase}`),\n        \"\",\n      );\n\n  const safePath = safelyEncodePath(rawPath);\n\n  return (safePath || \"/\") + globalThis.location.search;\n};\n\n/**\n * Safely encodes/decodes path to normalize URL encoding\n *\n * @param path - Path to normalize\n * @returns Normalized path or original on error\n */\nconst safelyEncodePath = (path: string): string => {\n  try {\n    return encodeURI(decodeURI(path));\n  } catch (error) {\n    console.warn(`[${LOGGER_CONTEXT}] Could not encode path \"${path}\"`, error);\n\n    return path;\n  }\n};\n\n/**\n * Gets current history state with validation.\n * Returns undefined instead of throwing for safer error handling.\n *\n * @returns Valid history state or undefined\n */\nconst getState = (): HistoryState | undefined => {\n  if (!globalThis.history.state) {\n    return undefined;\n  }\n\n  // Validate state structure instead of throwing\n  if (!isHistoryState(globalThis.history.state)) {\n    console.warn(\n      `[${LOGGER_CONTEXT}] History state is not a valid state object, ignoring`,\n      globalThis.history.state,\n    );\n\n    return undefined;\n  }\n\n  return globalThis.history.state as HistoryState;\n};\n\n/**\n * Gets current URL hash\n */\nconst getHash = () => globalThis.location.hash;\n\n/**\n * Creates a fallback browser for non-browser environments (SSR).\n * Logs warning on first method call to help diagnose misconfiguration.\n *\n * @returns Browser API with no-op implementations\n */\nfunction createFallbackBrowser(): Browser {\n  let hasWarned = false;\n\n  const warnOnce = (method: string) => {\n    if (!hasWarned) {\n      console.warn(\n        `[${LOGGER_CONTEXT}] Browser plugin is running in a non-browser environment. ` +\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  return {\n    getBase: () => {\n      warnOnce(\"getBase\");\n\n      return \"\";\n    },\n    pushState: () => {\n      warnOnce(\"pushState\");\n    },\n    replaceState: () => {\n      warnOnce(\"replaceState\");\n    },\n    addPopstateListener: () => {\n      warnOnce(\"addPopstateListener\");\n\n      return NOOP;\n    },\n    getLocation: () => {\n      warnOnce(\"getLocation\");\n\n      return \"\";\n    },\n    getState: () => {\n      warnOnce(\"getState\");\n\n      // eslint-disable-next-line unicorn/no-useless-undefined\n      return undefined;\n    },\n    getHash: () => {\n      warnOnce(\"getHash\");\n\n      return \"\";\n    },\n  };\n}\n\n/**\n * Creates browser API abstraction that works in both browser and SSR environments\n *\n * @returns Browser API object\n */\nexport function createSafeBrowser(): Browser {\n  const isBrowser =\n    typeof globalThis.window !== \"undefined\" && !!globalThis.history;\n\n  return isBrowser\n    ? {\n        getBase,\n        pushState,\n        replaceState,\n        addPopstateListener,\n        getLocation,\n        getState,\n        getHash,\n      }\n    : createFallbackBrowser();\n}\n","// packages/browser-plugin/modules/plugin.ts\n\nimport { isStateStrict as isState } from \"type-guards\";\n\nimport { createSafeBrowser } from \"./browser\";\nimport { defaultOptions, LOGGER_CONTEXT, source } from \"./constants\";\nimport {\n  escapeRegExp,\n  createStateFromEvent,\n  shouldSkipTransition,\n  handleMissingState,\n  updateBrowserState,\n  handleTransitionResult,\n  getStartRouterArguments,\n  validateOptions,\n} from \"./utils\";\n\nimport type {\n  BrowserPluginOptions,\n  Browser,\n  HistoryState,\n  StartRouterArguments,\n} from \"./types\";\nimport type {\n  PluginFactory,\n  Router,\n  RouterError,\n  State,\n} from \"@real-router/core\";\n\n/**\n * Browser plugin factory for real-router.\n * Integrates router with browser history API.\n *\n * Features:\n * - Syncs router state with browser history (pushState/replaceState)\n * - Handles popstate events for browser back/forward navigation\n * - Supports hash-based routing for legacy browsers\n * - Provides URL building and matching utilities\n * - SSR-safe with graceful fallbacks\n * - Runtime validation warns about conflicting options\n *\n * @param opts - Plugin configuration options\n * @param browser - Browser API abstraction (for testing/SSR)\n * @returns Plugin factory function\n *\n * @example\n * ```ts\n * // Hash routing\n * router.usePlugin(browserPluginFactory({ useHash: true, hashPrefix: \"!\" }));\n *\n * // History routing with hash preservation\n * router.usePlugin(browserPluginFactory({ useHash: false, preserveHash: true }));\n * ```\n */\nexport function browserPluginFactory(\n  opts?: Partial<BrowserPluginOptions>,\n  browser: Browser = createSafeBrowser(),\n): PluginFactory {\n  // Validate user-provided options before merging with defaults\n  const hasInvalidTypes = validateOptions(opts, defaultOptions);\n\n  let options = { ...defaultOptions, ...opts } as BrowserPluginOptions;\n\n  // Skip normalization if invalid types detected (prevents runtime errors)\n  if (hasInvalidTypes) {\n    console.warn(\n      `[${LOGGER_CONTEXT}] Using default options due to invalid types`,\n    );\n    options = { ...defaultOptions } as BrowserPluginOptions;\n  }\n\n  // Remove conflicting properties based on mode to prevent misuse\n  // This ensures options object is clean even if JS users pass invalid config\n  if (options.useHash === true) {\n    // Hash mode: remove history-only options\n    delete (options as unknown as Record<string, unknown>).preserveHash;\n  } else {\n    // History mode (default): remove hash-only options\n    delete (options as unknown as Record<string, unknown>).hashPrefix;\n  }\n\n  // Normalize base path to prevent common configuration errors\n  // Type check needed for runtime safety (JS users may pass wrong types)\n  if (options.base && typeof options.base === \"string\") {\n    // Ensure leading slash for absolute paths\n    if (!options.base.startsWith(\"/\")) {\n      options.base = `/${options.base}`;\n    }\n\n    // Remove trailing slash to prevent double slashes\n    if (options.base.endsWith(\"/\")) {\n      options.base = options.base.slice(0, -1);\n    }\n  }\n\n  // Cache RegExp patterns at plugin creation for performance\n  const regExpCache = new Map<string, RegExp>();\n  const getCachedRegExp = (pattern: string): RegExp => {\n    const cached = regExpCache.get(pattern);\n\n    if (cached !== undefined) {\n      return cached;\n    }\n\n    const newRegExp = new RegExp(pattern);\n\n    regExpCache.set(pattern, newRegExp);\n\n    return newRegExp;\n  };\n\n  // Create transition options with proper typing for exactOptionalPropertyTypes\n  const forceDeactivate = options.forceDeactivate;\n  /* v8 ignore next 2 -- @preserve both branches tested, coverage tool limitation */\n  const transitionOptions =\n    forceDeactivate === undefined ? { source } : { forceDeactivate, source };\n\n  let removePopStateListener: (() => void) | undefined;\n\n  return function browserPlugin(router: Router) {\n    // Store original methods for restoration on teardown\n    const routerStart = router.start;\n\n    // Transition state management\n    let isTransitioning = false;\n\n    // Deferred popstate event queue (stores only the last event)\n    let deferredPopstateEvent: PopStateEvent | null = null;\n\n    // Frozen copy of lastKnownState for immutability\n    let cachedFrozenState: State | undefined;\n\n    // Options can be changed at runtime in onStart\n    /* v8 ignore next -- @preserve fallback for undefined base */\n    const getBase = () => options.base ?? \"\";\n    /* v8 ignore next -- @preserve fallback for undefined hashPrefix */\n    const hashPrefix = options.hashPrefix ?? \"\";\n    const escapedHashPrefix = escapeRegExp(hashPrefix);\n    const prefix = options.useHash ? `#${hashPrefix}` : \"\";\n\n    // Pre-compute RegExp patterns\n    const hashPrefixRegExp = escapedHashPrefix\n      ? getCachedRegExp(`^#${escapedHashPrefix}`)\n      : null;\n\n    /**\n     * Parses URL and extracts path using native URL API.\n     * More robust than regex parsing - handles IPv6, Unicode, edge cases.\n     *\n     * @param url - URL to parse\n     * @returns Path string or null on parse error\n     */\n    const urlToPath = (url: string): string | null => {\n      try {\n        // Use URL API for reliable parsing\n        const parsedUrl = new URL(url, globalThis.location.origin);\n        const pathname = parsedUrl.pathname;\n        const hash = parsedUrl.hash;\n        const search = parsedUrl.search;\n        const base = getBase();\n\n        if (![\"http:\", \"https:\"].includes(parsedUrl.protocol)) {\n          console.warn(`[${LOGGER_CONTEXT}] Invalid URL protocol in ${url}`);\n\n          return null;\n        }\n\n        if (options.useHash) {\n          // Use cached RegExp or simple slice if no prefix\n          const path = hashPrefixRegExp\n            ? hash.replace(hashPrefixRegExp, \"\")\n            : hash.slice(1);\n\n          return path + search;\n        } else if (base) {\n          // Remove base prefix\n          const escapedBase = escapeRegExp(base);\n          const baseRegExp = getCachedRegExp(`^${escapedBase}`);\n          const stripped = pathname.replace(baseRegExp, \"\");\n\n          return (stripped.startsWith(\"/\") ? \"\" : \"/\") + stripped + search;\n        }\n\n        return pathname + search;\n      } catch (error) {\n        // Graceful fallback instead of throw\n        console.warn(`[${LOGGER_CONTEXT}] Could not parse url ${url}`, error);\n\n        return null;\n      }\n    };\n\n    /**\n     * Overrides router.start to integrate with browser location.\n     * If no start path is provided, uses current browser URL.\n     */\n    router.start = (...args: StartRouterArguments) => {\n      const [startPath, done] = getStartRouterArguments(args, browser, options);\n\n      if (startPath) {\n        routerStart(startPath, done);\n      } else {\n        routerStart(done);\n      }\n\n      return router;\n    };\n\n    /**\n     * Builds URL from route name and params.\n     * Adds base path and hash prefix according to options.\n     *\n     * @security\n     * When using buildUrl output in templates:\n     * - ✅ SAFE: Modern frameworks (React, Vue, Angular) auto-escape in templates\n     * - ✅ SAFE: Setting href attribute via DOM API (element.href = url)\n     * - ❌ UNSAFE: Using innerHTML or similar without escaping\n     *\n     * @example\n     * // Safe - React auto-escapes\n     * <Link to={router.buildUrl('users', params)} />\n     *\n     * // Safe - Vue auto-escapes\n     * <router-link :to=\"router.buildUrl('users', params)\" />\n     *\n     * // Unsafe - manual HTML construction\n     * element.innerHTML = `<a href=\"${router.buildUrl('users', params)}\">Link</a>`; // ❌ DON'T\n     */\n    router.buildUrl = (route, params) => {\n      const path = router.buildPath(route, params);\n\n      return getBase() + prefix + path;\n    };\n\n    /**\n     * Matches URL and returns corresponding state\n     */\n    router.matchUrl = (url) => {\n      const path = urlToPath(url);\n\n      return path ? router.matchPath(path, source) : undefined;\n    };\n\n    /**\n     * Replaces current history state without triggering navigation.\n     * Useful for updating URL without causing a full transition.\n     */\n    router.replaceHistoryState = (name, params = {}) => {\n      const state = router.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 = router.makeState(\n        state.name,\n        state.params,\n        router.buildPath(state.name, state.params),\n        {\n          params: state.meta,\n          options: {},\n          redirected: false,\n        },\n        1, // forceId\n      );\n      const url = router.buildUrl(name, params);\n\n      updateBrowserState(builtState, url, true, browser, options);\n    };\n\n    /**\n     * lastKnownState: Immutable reference to last successful state.\n     * Uses caching to avoid creating new objects on every read.\n     * Optimized: Single copy + freeze operation instead of double copying.\n     */\n    Object.defineProperty(router, \"lastKnownState\", {\n      get() {\n        // Note: After teardown, this property is deleted from router,\n        // so this getter is only called while plugin is active\n        return cachedFrozenState;\n      },\n      set(value?: State) {\n        // Create frozen copy in one operation (no double copying)\n        cachedFrozenState = value ? Object.freeze({ ...value }) : undefined;\n      },\n      enumerable: true,\n      configurable: true,\n    });\n\n    /**\n     * Processes a deferred popstate event if one exists.\n     * Called after transition completes.\n     */\n    function processDeferredEvent() {\n      if (deferredPopstateEvent) {\n        const event = deferredPopstateEvent;\n\n        deferredPopstateEvent = null; // Clear before processing\n        console.warn(`[${LOGGER_CONTEXT}] Processing deferred popstate event`);\n        onPopState(event);\n      }\n    }\n\n    /**\n     * Main popstate event handler.\n     * Protected against concurrent transitions and handles errors gracefully.\n     * Defers events during transitions to prevent browser history desync.\n     */\n    function onPopState(evt: PopStateEvent) {\n      // Race condition protection: defer event if transition in progress\n      if (isTransitioning) {\n        console.warn(\n          `[${LOGGER_CONTEXT}] Transition in progress, deferring popstate event`,\n        );\n        // Store only the latest event (skip intermediate states)\n        deferredPopstateEvent = evt;\n\n        return;\n      }\n\n      // Top-level error recovery\n      try {\n        const routerState = router.getState();\n        const state = createStateFromEvent(\n          evt,\n          router,\n          browser,\n          options,\n          source,\n        );\n        const isNewState = !isState(evt.state);\n\n        // Handle missing state\n        if (!state && handleMissingState(router, transitionOptions)) {\n          return;\n        }\n\n        // Skip if states are equal\n        if (shouldSkipTransition(state, routerState, router)) {\n          return;\n        }\n\n        // Execute transition with race protection\n        // Note: state is guaranteed to be defined here because:\n        // 1. handleMissingState handles !state case (line 332)\n        // 2. shouldSkipTransition returns true when !state (utils.ts:136)\n        isTransitioning = true;\n\n        // Use internal navigateToState without emitting TRANSITION_SUCCESS\n        // We'll emit it in handleTransitionResult if needed\n        router.navigateToState(\n          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guaranteed by shouldSkipTransition\n          state!,\n          routerState,\n          transitionOptions,\n          (err: RouterError | undefined, toState: State | undefined) => {\n            isTransitioning = false;\n            handleTransitionResult(\n              err,\n              toState,\n              routerState,\n              isNewState,\n              router,\n              browser,\n              options,\n            );\n\n            // Process any deferred popstate events after transition completes\n            processDeferredEvent();\n          },\n          false, // emitSuccess = false - handleTransitionResult will emit if needed\n        );\n      } catch (error) {\n        isTransitioning = false;\n        console.error(\n          `[${LOGGER_CONTEXT}] Critical error in onPopState`,\n          error,\n        );\n\n        // Attempt recovery: sync browser with router state\n        try {\n          const currentState = router.getState();\n\n          if (currentState) {\n            const url = router.buildUrl(currentState.name, currentState.params);\n\n            browser.replaceState(currentState as HistoryState, \"\", url);\n          }\n        } catch (recoveryError) {\n          // If recovery fails, there's nothing more we can do\n          console.error(\n            `[${LOGGER_CONTEXT}] Failed to recover from critical error`,\n            recoveryError,\n          );\n        }\n\n        // Process any deferred events even after error\n        processDeferredEvent();\n      }\n    }\n\n    return {\n      /**\n       * Called when router.start() is invoked.\n       * Sets up browser history integration.\n       */\n      onStart: () => {\n        if (removePopStateListener) {\n          removePopStateListener();\n        }\n\n        removePopStateListener = browser.addPopstateListener(\n          onPopState,\n          options,\n        );\n      },\n\n      /**\n       * Called when router.stop() is invoked.\n       * Cleans up event listeners.\n       */\n      onStop: () => {\n        if (removePopStateListener) {\n          removePopStateListener();\n          removePopStateListener = undefined;\n        }\n      },\n\n      /**\n       * Called after successful navigation.\n       * Updates browser history with new state.\n       */\n      onTransitionSuccess: (toState, fromState, navOptions) => {\n        router.lastKnownState = toState;\n\n        // Determine if we should replace or push history entry\n        const replaceHistory =\n          (navOptions.replace ?? !fromState) ||\n          (!!navOptions.reload &&\n            router.areStatesEqual(toState, fromState, false));\n\n        // Build URL with base and hash prefix\n        const url = router.buildUrl(toState.name, toState.params);\n\n        // Preserve hash fragment if configured\n        // Note: preserveHash is deleted in hash mode, so it's always undefined there\n        const shouldPreserveHash =\n          options.preserveHash &&\n          (!fromState || fromState.path === toState.path);\n\n        const finalUrl = shouldPreserveHash ? url + browser.getHash() : url;\n\n        // Update browser history\n        updateBrowserState(toState, finalUrl, replaceHistory, browser, options);\n      },\n\n      /**\n       * Called when plugin is unsubscribed.\n       * Restores original router state for clean teardown.\n       */\n      teardown: () => {\n        // Remove event listeners\n        if (removePopStateListener) {\n          removePopStateListener();\n          removePopStateListener = undefined;\n        }\n\n        // Restore original router methods\n        router.start = routerStart;\n\n        // Clean up added properties\n        delete (router as Partial<Router>).buildUrl;\n        delete (router as Partial<Router>).matchUrl;\n        delete (router as Partial<Router>).replaceHistoryState;\n        delete (router as Partial<Router>).lastKnownState;\n      },\n    };\n  };\n}\n"]}

package/dist/cjs/metafile-cjs.json

@@ -0,0 +1 @@
+{"inputs":{"../../node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js":{"bytes":569,"imports":[],"format":"esm"},"src/constants.ts":{"bytes":1668,"imports":[{"path":"/Users/olegivanov/WebstormProjects/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"},"src/utils.ts":{"bytes":8548,"imports":[{"path":"@real-router/core","kind":"import-statement","external":true},{"path":"type-guards","kind":"import-statement","external":true},{"path":"src/constants.ts","kind":"import-statement","original":"./constants"},{"path":"/Users/olegivanov/WebstormProjects/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"},"src/browser.ts":{"bytes":6815,"imports":[{"path":"type-guards","kind":"import-statement","external":true},{"path":"src/constants.ts","kind":"import-statement","original":"./constants"},{"path":"src/utils.ts","kind":"import-statement","original":"./utils"},{"path":"/Users/olegivanov/WebstormProjects/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"},"src/plugin.ts":{"bytes":15343,"imports":[{"path":"type-guards","kind":"import-statement","external":true},{"path":"src/browser.ts","kind":"import-statement","original":"./browser"},{"path":"src/constants.ts","kind":"import-statement","original":"./constants"},{"path":"src/utils.ts","kind":"import-statement","original":"./utils"},{"path":"/Users/olegivanov/WebstormProjects/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"},"src/index.ts":{"bytes":1277,"imports":[{"path":"src/plugin.ts","kind":"import-statement","original":"./plugin"},{"path":"type-guards","kind":"import-statement","external":true},{"path":"/Users/olegivanov/WebstormProjects/real-router/node_modules/.pnpm/tsup@8.5.1_jiti@2.6.1_postcss@8.5.6_typescript@5.9.3/node_modules/tsup/assets/cjs_shims.js","kind":"import-statement","external":true}],"format":"esm"}},"outputs":{"dist/cjs/index.js.map":{"imports":[],"exports":[],"inputs":{},"bytes":45931},"dist/cjs/index.js":{"imports":[{"path":"type-guards","kind":"import-statement","external":true},{"path":"type-guards","kind":"import-statement","external":true},{"path":"@real-router/core","kind":"import-statement","external":true},{"path":"type-guards","kind":"import-statement","external":true},{"path":"type-guards","kind":"import-statement","external":true}],"exports":["browserPluginFactory","isHistoryState","isState"],"entryPoint":"src/index.ts","inputs":{"src/plugin.ts":{"bytesInOutput":8327},"src/browser.ts":{"bytesInOutput":4042},"src/constants.ts":{"bytesInOutput":205},"src/utils.ts":{"bytesInOutput":4084},"src/index.ts":{"bytesInOutput":80}},"bytes":17179}}}

package/dist/esm/index.d.mts

@@ -0,0 +1,252 @@
+import { State, DoneFn, PluginFactory, Params } from '@real-router/core';
+export { isHistoryState, isStateStrict as isState } from 'type-guards';
+
+/**
+ * Common options shared between hash and history modes
+ */
+interface BaseBrowserPluginOptions {
+    /**
+     * Force deactivation of current route even if canDeactivate returns false.
+     *
+     * @default true
+     */
+    forceDeactivate?: boolean;
+    /**
+     * Base path for all routes (e.g., "/app" for hosted at /app/).
+     *
+     * @default ""
+     */
+    base?: string;
+    /**
+     * Merge new state with existing history.state when updating.
+     * Useful for preserving external state set by other code.
+     *
+     * @default false
+     */
+    mergeState?: boolean;
+}
+/**
+ * Hash-based routing configuration.
+ * Uses URL hash for navigation (e.g., example.com/#/path).
+ *
+ * @example
+ * ```ts
+ * // Standard hash routing
+ * browserPluginFactory({ useHash: true })
+ * // → example.com/#/users
+ *
+ * // Hash routing with prefix
+ * browserPluginFactory({ useHash: true, hashPrefix: "!" })
+ * // → example.com/#!/users
+ * ```
+ */
+interface HashModeOptions extends BaseBrowserPluginOptions {
+    /**
+     * Enable hash-based routing
+     */
+    useHash: true;
+    /**
+     * Prefix for hash (e.g., "!" for "#!/path").
+     * Only valid when useHash is true.
+     *
+     * @default ""
+     */
+    hashPrefix?: string;
+    /**
+     * Not available in hash mode.
+     * Hash preservation only works with HTML5 History API.
+     * Use `useHash: false` to enable this option.
+     */
+    preserveHash?: never;
+}
+/**
+ * HTML5 History API routing configuration.
+ * Uses pushState/replaceState for navigation (e.g., example.com/path).
+ *
+ * @example
+ * ```ts
+ * // Standard history routing
+ * browserPluginFactory({ useHash: false })
+ * // → example.com/users
+ *
+ * // Preserve URL hash fragments
+ * browserPluginFactory({ useHash: false, preserveHash: true })
+ * // → example.com/users#section
+ * ```
+ */
+interface HistoryModeOptions extends BaseBrowserPluginOptions {
+    /**
+     * Disable hash-based routing (use HTML5 History API)
+     *
+     * @default false
+     */
+    useHash?: false;
+    /**
+     * Preserve URL hash fragment on initial navigation.
+     * Only valid when useHash is false.
+     *
+     * @default true
+     */
+    preserveHash?: boolean;
+    /**
+     * Not available in history mode.
+     * Hash prefix only works with hash-based routing.
+     * Use `useHash: true` to enable this option.
+     */
+    hashPrefix?: never;
+}
+/**
+ * Type-safe browser plugin configuration.
+ *
+ * Uses discriminated union to prevent conflicting options:
+ * - Hash mode (useHash: true): allows hashPrefix, forbids preserveHash
+ * - History mode (useHash: false): allows preserveHash, forbids hashPrefix
+ *
+ * @example
+ * ```ts
+ * // ✅ Valid: Hash mode with prefix
+ * const config1: BrowserPluginOptions = {
+ *   useHash: true,
+ *   hashPrefix: "!"
+ * };
+ *
+ * // ✅ Valid: History mode with hash preservation
+ * const config2: BrowserPluginOptions = {
+ *   useHash: false,
+ *   preserveHash: true
+ * };
+ *
+ * // ❌ Error: Cannot use preserveHash with hash mode
+ * const config3: BrowserPluginOptions = {
+ *   useHash: true,
+ *   preserveHash: true  // Type error!
+ * };
+ *
+ * // ❌ Error: Cannot use hashPrefix with history mode
+ * const config4: BrowserPluginOptions = {
+ *   useHash: false,
+ *   hashPrefix: "!"  // Type error!
+ * };
+ * ```
+ */
+type BrowserPluginOptions = HashModeOptions | HistoryModeOptions;
+/**
+ * Browser API abstraction for cross-environment compatibility.
+ * Provides same interface in browser and SSR contexts.
+ */
+interface Browser {
+    /**
+     * Gets base path from current browser location
+     *
+     * @returns Current pathname
+     */
+    getBase: () => string;
+    /**
+     * Pushes new state to browser history
+     *
+     * @param state - History state object
+     * @param title - Document title (usually ignored by browsers)
+     * @param path - URL path
+     */
+    pushState: (state: HistoryState, title: string | null, path: string) => void;
+    /**
+     * Replaces current history state
+     *
+     * @param state - History state object
+     * @param title - Document title (usually ignored by browsers)
+     * @param path - URL path
+     */
+    replaceState: (state: HistoryState, title: string | null, path: string) => void;
+    /**
+     * Adds popstate/hashchange event listeners.
+     * Overloaded to support both PopStateEvent and HashChangeEvent.
+     *
+     * @param fn - Event handler
+     * @param opts - Plugin options
+     * @returns Cleanup function to remove listeners
+     */
+    addPopstateListener: ((fn: (evt: PopStateEvent) => void, opts: BrowserPluginOptions) => () => void) & ((fn: (evt: HashChangeEvent) => void, opts: BrowserPluginOptions) => () => void);
+    /**
+     * Gets current location path respecting plugin options
+     *
+     * @param opts - Plugin options
+     * @returns Current path string
+     */
+    getLocation: (opts: BrowserPluginOptions) => string;
+    /**
+     * Gets current history state with validation
+     *
+     * @returns Valid history state or undefined
+     */
+    getState: () => HistoryState | undefined;
+    /**
+     * Gets current URL hash
+     *
+     * @returns Hash string (including #)
+     */
+    getHash: () => string;
+}
+/**
+ * History state object stored in browser history.
+ * Extends real-router State with additional properties that may be set by external code.
+ */
+type HistoryState = State & Record<string, unknown>;
+type StartRouterArguments = [] | [done: DoneFn] | [startPathOrState: string | State] | [startPathOrState: string | State, done: DoneFn];
+
+/**
+ * Browser plugin factory for real-router.
+ * Integrates router with browser history API.
+ *
+ * Features:
+ * - Syncs router state with browser history (pushState/replaceState)
+ * - Handles popstate events for browser back/forward navigation
+ * - Supports hash-based routing for legacy browsers
+ * - Provides URL building and matching utilities
+ * - SSR-safe with graceful fallbacks
+ * - Runtime validation warns about conflicting options
+ *
+ * @param opts - Plugin configuration options
+ * @param browser - Browser API abstraction (for testing/SSR)
+ * @returns Plugin factory function
+ *
+ * @example
+ * ```ts
+ * // Hash routing
+ * router.usePlugin(browserPluginFactory({ useHash: true, hashPrefix: "!" }));
+ *
+ * // History routing with hash preservation
+ * router.usePlugin(browserPluginFactory({ useHash: false, preserveHash: true }));
+ * ```
+ */
+declare function browserPluginFactory(opts?: Partial<BrowserPluginOptions>, browser?: Browser): PluginFactory;
+
+/**
+ * Module augmentation for real-router.
+ * Extends Router interface with browser plugin methods.
+ */
+declare module "@real-router/core" {
+    interface Router {
+        /**
+         * Builds full URL for a route with base path and hash prefix.
+         * Added by browser plugin.
+         */
+        buildUrl: (name: string, params?: Params) => string;
+        /**
+         * Matches URL and returns corresponding state.
+         * Added by browser plugin.
+         */
+        matchUrl: (url: string) => State | undefined;
+        /**
+         * Replaces current history state without triggering navigation.
+         * Added by browser plugin.
+         */
+        replaceHistoryState: (name: string, params?: Params, title?: string) => void;
+        /**
+         * Last known router state.
+         * Added by browser plugin.
+         */
+        lastKnownState?: State;
+    }
+}
+
+export { type Browser, type BrowserPluginOptions, type HistoryState, type StartRouterArguments, browserPluginFactory };