@real-router/hash-plugin 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Oleg Ivanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,210 @@
+# @real-router/hash-plugin
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue.svg)](https://www.typescriptlang.org/)
+
+Hash-based routing plugin for Real-Router. Uses URL hash fragment for navigation — no server configuration needed.
+
+## Installation
+
+```bash
+npm install @real-router/hash-plugin
+# or
+pnpm add @real-router/hash-plugin
+# or
+yarn add @real-router/hash-plugin
+# or
+bun add @real-router/hash-plugin
+```
+
+## Quick Start
+
+```typescript
+import { createRouter } from "@real-router/core";
+import { hashPluginFactory } from "@real-router/hash-plugin";
+
+const router = createRouter([
+  { name: "home", path: "/" },
+  { name: "products", path: "/products/:id" },
+  { name: "cart", path: "/cart" },
+]);
+
+// Basic usage
+router.usePlugin(hashPluginFactory());
+
+// With options
+router.usePlugin(
+  hashPluginFactory({
+    hashPrefix: "!",
+  }),
+);
+
+await router.start();
+```
+
+---
+
+## Configuration
+
+```typescript
+router.usePlugin(
+  hashPluginFactory({
+    hashPrefix: "!",
+    forceDeactivate: true,
+  }),
+);
+
+router.navigate("products", { id: "123" });
+// URL: http://example.com/#!/products/123
+```
+
+| Option            | Type      | Default | Description                                           |
+| ----------------- | --------- | ------- | ----------------------------------------------------- |
+| `hashPrefix`      | `string`  | `""`    | Prefix after `#` (e.g., `"!"` → `#!/path`)            |
+| `base`            | `string`  | `""`    | Base path before hash (e.g., `"/app"` → `/app#/path`) |
+| `forceDeactivate` | `boolean` | `true`  | Bypass `canDeactivate` guards on browser back/forward |
+
+> **Looking for History API routing?** Use [`@real-router/browser-plugin`](https://www.npmjs.com/package/@real-router/browser-plugin) instead.
+
+See [Wiki](https://github.com/greydragon888/real-router/wiki/hash-plugin) for detailed option descriptions and examples.
+
+---
+
+## Added Router Methods
+
+The plugin extends the router instance with browser-specific methods (via [`extendRouter()`](https://github.com/greydragon888/real-router/wiki/extendRouter)):
+
+#### `router.buildUrl(name: string, params?: Params): string`
+
+Build full URL with hash prefix.\
+`name: string` — route name\
+`params?: Params` — route parameters\
+Returns: `string` — full URL\
+[Wiki](https://github.com/greydragon888/real-router/wiki/hash-plugin#5-router-interaction)
+
+```typescript
+router.buildUrl("users", { id: "123" });
+// => "#!/users/123" (with hashPrefix "!")
+```
+
+#### `router.matchUrl(url: string): State | undefined`
+
+Parse URL to router state.\
+`url: string` — URL to parse\
+Returns: `State | undefined`\
+[Wiki](https://github.com/greydragon888/real-router/wiki/hash-plugin#5-router-interaction)
+
+```typescript
+const state = router.matchUrl("https://example.com/#!/users/123");
+// => { name: "users", params: { id: "123" }, ... }
+```
+
+#### `router.replaceHistoryState(name: string, params?: Params, title?: string): void`
+
+Update browser URL without triggering navigation.\
+`name: string` — route name\
+`params?: Params` — route parameters\
+`title?: string` — page title\
+Returns: `void`\
+[Wiki](https://github.com/greydragon888/real-router/wiki/hash-plugin#5-router-interaction)
+
+```typescript
+router.replaceHistoryState("users", { id: "456" });
+```
+
+---
+
+## Usage Examples
+
+### Hashbang Routing
+
+```typescript
+router.usePlugin(
+  hashPluginFactory({
+    hashPrefix: "!",
+  }),
+);
+
+router.navigate("users", { id: "123" });
+// URL: #!/users/123
+```
+
+### With Base Path
+
+```typescript
+router.usePlugin(
+  hashPluginFactory({
+    hashPrefix: "!",
+    base: "/app",
+  }),
+);
+
+router.navigate("users", { id: "123" });
+// URL: /app#!/users/123
+```
+
+### Form Protection
+
+```typescript
+router.usePlugin(
+  hashPluginFactory({
+    forceDeactivate: false,
+  }),
+);
+
+import { getLifecycleApi } from "@real-router/core";
+
+const lifecycle = getLifecycleApi(router);
+lifecycle.addDeactivateGuard("checkout", () => (toState, fromState) => {
+  return !hasUnsavedChanges(); // false blocks navigation
+});
+```
+
+---
+
+## SSR Support
+
+The plugin is SSR-safe with automatic fallback:
+
+```typescript
+// Server-side — no errors, methods return safe defaults
+router.usePlugin(hashPluginFactory());
+router.buildUrl("home"); // Works
+router.matchUrl("/path"); // Returns undefined
+```
+
+---
+
+## Why Hash Routing?
+
+Hash-based routing stores the entire route in the URL hash fragment (`#/path`). This means:
+
+- **No server configuration** — the server always serves the same `index.html` regardless of the URL
+- **Works on static hosting** — GitHub Pages, S3, Netlify (without redirect rules)
+- **Legacy browser support** — works everywhere that supports `hashchange` events
+
+The tradeoff is less clean URLs (`example.com/#!/users` vs `example.com/users`).
+
+---
+
+## Documentation
+
+Full documentation available on the [Wiki](https://github.com/greydragon888/real-router/wiki/hash-plugin):
+
+- [Configuration Options](https://github.com/greydragon888/real-router/wiki/hash-plugin#3-configuration-options)
+- [Lifecycle Hooks](https://github.com/greydragon888/real-router/wiki/hash-plugin#4-lifecycle-hooks)
+- [Router Methods](https://github.com/greydragon888/real-router/wiki/hash-plugin#5-router-interaction)
+- [Behavior & Edge Cases](https://github.com/greydragon888/real-router/wiki/hash-plugin#8-behavior)
+
+---
+
+## Related Packages
+
+- [@real-router/core](https://www.npmjs.com/package/@real-router/core) — Core router
+- [@real-router/browser-plugin](https://www.npmjs.com/package/@real-router/browser-plugin) — History API routing
+- [@real-router/react](https://www.npmjs.com/package/@real-router/react) — React integration
+- [@real-router/logger-plugin](https://www.npmjs.com/package/@real-router/logger-plugin) — Debug logging
+
+## License
+
+MIT © [Oleg Ivanov](https://github.com/greydragon888)

package/dist/cjs/index.d.ts

@@ -0,0 +1,109 @@
+import { State as State$1, PluginFactory, Params as Params$1 } from '@real-router/core';
+
+/**
+ * Hash-based routing plugin configuration.
+ * Uses URL hash fragment for navigation (e.g., example.com/#/path).
+ */
+interface HashPluginOptions {
+    /**
+     * Prefix for hash (e.g., "!" for "#!/path").
+     *
+     * @default ""
+     */
+    hashPrefix?: string;
+    /**
+     * Base path prepended before hash (e.g., "/app" → "/app#/path").
+     *
+     * @default ""
+     */
+    base?: string;
+    /**
+     * Force deactivation of current route even if canDeactivate returns false.
+     *
+     * @default true
+     */
+    forceDeactivate?: boolean;
+}
+
+interface HistoryBrowser {
+    pushState: (state: State$1, path: string) => void;
+    replaceState: (state: State$1, path: string) => void;
+    addPopstateListener: (fn: (evt: PopStateEvent) => void) => () => void;
+    getHash: () => string;
+}
+interface Browser extends HistoryBrowser {
+    getLocation: () => string;
+}
+
+declare function hashPluginFactory(opts?: Partial<HashPluginOptions>, browser?: Browser): PluginFactory;
+
+type TransitionPhase = "deactivating" | "activating";
+type TransitionReason = "success" | "blocked" | "cancelled" | "error";
+interface TransitionMeta {
+    readonly reload?: boolean;
+    readonly redirected?: boolean;
+    phase: TransitionPhase;
+    from?: string;
+    reason: TransitionReason;
+    blocker?: string;
+    segments: {
+        deactivated: string[];
+        activated: string[];
+        intersection: string;
+    };
+}
+interface State<P extends Params = Params, MP extends Params = Params> {
+    name: string;
+    params: P;
+    path: string;
+    meta?: StateMeta<MP> | undefined;
+    transition?: TransitionMeta | undefined;
+}
+interface StateMeta<P extends Params = Params> {
+    id: number;
+    params: P;
+}
+interface Params {
+    [key: string]: string | string[] | number | number[] | boolean | boolean[] | Params | Params[] | Record<string, string | number | boolean> | null | undefined;
+}
+
+/**
+ * Enhanced type guard for State with deep validation.
+ * Checks not only presence but also types of all required fields.
+ * Validates params using isParams and meta structure if present.
+ *
+ * @param value - Value to check
+ * @returns true if value is a valid State object with correct types
+ *
+ * @example
+ * isStateStrict({ name: 'home', params: {}, path: '/', meta: { id: 1 } }); // true
+ * isStateStrict({ name: 'home', params: 'invalid', path: '/' }); // false
+ */
+declare function isStateStrict<P extends Params = Params, MP extends Params = Params>(value: unknown): value is State<P, MP>;
+
+/**
+ * Module augmentation for real-router.
+ * Extends Router interface with hash plugin methods.
+ */
+declare module "@real-router/core" {
+    interface Router {
+        /**
+         * Builds full URL for a route with base path and hash prefix.
+         * Added by hash plugin.
+         */
+        buildUrl: (name: string, params?: Params$1) => string;
+        /**
+         * Matches URL and returns corresponding state.
+         * Added by hash plugin.
+         */
+        matchUrl: (url: string) => State$1 | undefined;
+        /**
+         * Replaces current history state without triggering navigation.
+         * Added by hash plugin.
+         */
+        replaceHistoryState: (name: string, params?: Params$1, title?: string) => void;
+        start(path?: string): Promise<State$1>;
+    }
+}
+
+export { type Browser, type HashPluginOptions, hashPluginFactory, isStateStrict as isState };

package/dist/cjs/index.js

@@ -0,0 +1 @@
+var e=require("@real-router/core"),t=/^[A-Z_a-z][\w-]*(?:\.[A-Z_a-z][\w-]*)*$/;function r(e,t=new WeakSet){if(null==e)return!0;const n=typeof e;if("string"===n||"boolean"===n)return!0;if("number"===n)return Number.isFinite(e);if("function"===n||"symbol"===n)return!1;if(Array.isArray(e))return!t.has(e)&&(t.add(e),e.every(e=>r(e,t)));if("object"===n){if(t.has(e))return!1;t.add(e);const n=Object.getPrototypeOf(e);return(null===n||n===Object.prototype)&&Object.values(e).every(e=>r(e,t))}return!1}function n(e){if(null==e)return!0;const t=typeof e;return"string"===t||"boolean"===t||"number"===t&&Number.isFinite(e)}function o(e){if("object"!=typeof e||null===e||Array.isArray(e))return!1;const t=Object.getPrototypeOf(e);if(null!==t&&t!==Object.prototype)return!1;let o=!1;for(const t in e){if(!Object.hasOwn(e,t))continue;const r=e[t];if(!n(r)){const e=typeof r;if("function"===e||"symbol"===e)return!1;o=!0;break}}return!o||r(e)}function a(e){if(null==e)return!0;const t=typeof e;return"string"===t||"boolean"===t||("number"===t?Number.isFinite(e):!!Array.isArray(e)&&e.every(e=>{const t=typeof e;return"string"===t||"boolean"===t||"number"===t&&Number.isFinite(e)}))}function i(e){if("object"!=typeof e||null===e)return!1;const r=e;return!!function(e){return function(e){return"string"==typeof e&&(""===e||!(e.length>1e4)&&(!!e.startsWith("@@")||t.test(e)))}(e.name)&&"string"==typeof e.path&&o(e.params)}(r)&&(void 0===r.meta||function(e){if("object"!=typeof e||null===e)return!1;const t=e;return!("params"in t&&!function(e){if("object"!=typeof e||null===e||Array.isArray(e))return!1;for(const t in e)if(Object.hasOwn(e,t)&&!a(e[t]))return!1;return!0}(t.params)||"id"in t&&"number"!=typeof t.id)}(r.meta))}var s=(e,t)=>{globalThis.history.pushState(e,"",t)},c=(e,t)=>{globalThis.history.replaceState(e,"",t)},u=e=>(globalThis.addEventListener("popstate",e),()=>{globalThis.removeEventListener("popstate",e)}),l=()=>globalThis.location.hash,p=()=>{},f=e=>{let t=!1;return r=>{t||(console.warn(`[browser-env] Browser API is running in a non-browser environment (context: "${e}"). Method "${r}" is a no-op. This is expected for SSR, but may indicate misconfiguration if you expected browser behavior.`),t=!0)}},h=e=>{const t=f(e);return{pushState:()=>{t("pushState")},replaceState:()=>{t("replaceState")},addPopstateListener:()=>(t("addPopstateListener"),p),getHash:()=>(t("getHash"),"")}};function d(e,t,r,n){const o={meta:e.meta,name:e.name,params:e.params,path:e.path};r?n.replaceState(o,t):n.pushState(o,t)}function m(t){let r=!1,n=null;async function o(a){if(r)return console.warn(`[${t.loggerContext}] Transition in progress, deferring popstate event`),void(n=a);r=!0;try{const e=function(e,t,r){if(i(e.state))return{name:e.state.name,params:e.state.params};const n=t.matchPath(r.getLocation());return n?{name:n.name,params:n.params}:void 0}(a,t.api,t.browser);e?await t.router.navigate(e.name,e.params,t.transitionOptions):await t.router.navigateToDefault({...t.transitionOptions,reload:!0,replace:!0})}catch(r){r instanceof e.RouterError||function(e){console.error(`[${t.loggerContext}] Critical error in onPopState`,e);try{const e=t.router.getState();if(e){const r=t.buildUrl(e.name,e.params);t.browser.replaceState(e,r)}}catch(e){console.error(`[${t.loggerContext}] Failed to recover from critical error`,e)}}(r)}finally{r=!1,function(){if(n){const e=n;n=null,console.warn(`[${t.loggerContext}] Processing deferred popstate event`),o(e)}}()}}return e=>{o(e)}}function b(e,t,r,n){return(o,a={})=>{const i=e.buildState(o,a);if(!i)throw new Error(`[real-router] Cannot replace state: route "${o}" is not found`);d(e.makeState(i.name,i.params,t.buildPath(i.name,i.params),{params:i.meta},1),n(o,a),!0,r)}}var g={hashPrefix:"",base:"",forceDeactivate:!0},v="hash-plugin",y=new Map;function w(e,t,r){const n=(e=>{const t=y.get(e);if(void 0!==t)return t;const r=e.replaceAll(/[$()*+.?[\\\]^{|}-]/g,String.raw`\$&`);return y.set(e,r),r})(t);return(n?e.replace(r.get(`^#${n}`),""):e.slice(1))||"/"}var S,P,$=class{#e;#t;#r;#n;#o;constructor(e,t,r,n,o,a,i){var s;this.#e=e,this.#t=n,this.#r=(s=n,t.addInterceptor("start",(e,t)=>e(t??s.getLocation())));const c=(t,n)=>{const o=e.buildPath(t,n);return`${r.base}#${r.hashPrefix}${o}`};this.#n=t.extendRouter({buildUrl:c,matchUrl:e=>{const n=function(e,t,r){const n=function(e,t){try{const r=new URL(e,globalThis.location.origin);return["http:","https:"].includes(r.protocol)?r:(console.warn(`[${t}] Invalid URL protocol in ${e}`),null)}catch(r){return console.warn(`[${t}] Could not parse url ${e}`,r),null}}(e,v);return n?w(n.hash,t,r)+n.search:null}(e,r.hashPrefix,o);return n?t.matchPath(n):void 0},replaceHistoryState:b(t,e,n,c)});const u=m({router:e,api:t,browser:n,transitionOptions:a,loggerContext:"hash-plugin",buildUrl:(t,r)=>e.buildUrl(t,r)});this.#o=function(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()}}}({browser:n,shared:i,handler:u,cleanup:()=>{this.#r(),this.#n()}})}getPlugin(){return{...this.#o,onTransitionSuccess:(e,t,r)=>{const n=(a=t,i=this.#e,((o=r).replace??!a)||!!o.reload&&i.areStatesEqual(e,a,!1));var o,a,i;d(e,this.#e.buildUrl(e.name,e.params),n,this.#t)}}}},L=(S=g,P=v,e=>{if(e)for(const t of Object.keys(e))if(t in S){const r=e[t],n=typeof S[t],o=typeof r;if(void 0!==r&&o!==n)throw new Error(`[${P}] Invalid type for '${t}': expected ${n}, got ${o}`)}});exports.hashPluginFactory=function(t,r){L(t);const n={...g,...t};n.base=function(e){if(!e)return e;let t=e;return t.startsWith("/")||(t=`/${t}`),t.endsWith("/")&&(t=t.slice(0,-1)),t}(n.base);const o=function(){const e=new Map;return{get(t){const r=e.get(t);if(void 0!==r)return r;const n=new RegExp(t);return e.set(t,n),n}}}(),a=r??function(e,t){if(void 0!==globalThis.window&&globalThis.history)return{pushState:s,replaceState:c,addPopstateListener:u,getLocation:e,getHash:l};const r=f(t);return{...h(t),getLocation:()=>(r("getLocation"),"")}}(()=>(e=>{try{return encodeURI(decodeURI(e))}catch(t){return console.warn(`[browser-env] Could not encode path "${e}"`,t),e}})(w(globalThis.location.hash,n.hashPrefix,o))+globalThis.location.search,"hash-plugin"),i={forceDeactivate:n.forceDeactivate,source:"popstate",replace:!0},p={removePopStateListener:void 0};return function(t){return new $(t,e.getPluginApi(t),n,a,o,i,p).getPlugin()}},exports.isState=i;//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/constants.ts","../../src/hash-utils.ts","../../src/plugin.ts","../../src/validation.ts","../../src/factory.ts"],"names":["i","f","c","getPluginApi"],"mappings":"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","file":"index.js","sourcesContent":["// 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 { safeParseUrl } from \"browser-env\";\n\nimport { LOGGER_CONTEXT } from \"./constants\";\n\nexport interface RegExpCache {\n  get: (pattern: string) => RegExp;\n}\n\nconst escapeRegExpCache = new Map<string, string>();\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\nexport function createRegExpCache(): RegExpCache {\n  const cache = new Map<string, RegExp>();\n\n  return {\n    get(pattern: string): RegExp {\n      const cached = cache.get(pattern);\n\n      if (cached !== undefined) {\n        return cached;\n      }\n\n      const newRegExp = new RegExp(pattern);\n\n      cache.set(pattern, newRegExp);\n\n      return newRegExp;\n    },\n  };\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 hashPrefix - Hash prefix to strip (e.g., \"!\")\n * @param regExpCache - RegExp cache for compiled patterns\n * @returns Extracted path (e.g., \"/path\")\n */\nexport function extractHashPath(\n  hash: string,\n  hashPrefix: string,\n  regExpCache: RegExpCache,\n): string {\n  const escapedHashPrefix = escapeRegExp(hashPrefix);\n  const path = escapedHashPrefix\n    ? hash.replace(regExpCache.get(`^#${escapedHashPrefix}`), \"\")\n    : hash.slice(1);\n\n  return path || \"/\";\n}\n\nexport function hashUrlToPath(\n  url: string,\n  hashPrefix: string,\n  regExpCache: RegExpCache,\n): string | null {\n  const parsedUrl = safeParseUrl(url, LOGGER_CONTEXT);\n\n  return parsedUrl\n    ? extractHashPath(parsedUrl.hash, hashPrefix, regExpCache) +\n        parsedUrl.search\n    : null;\n}\n","import {\n  createPopstateHandler,\n  createPopstateLifecycle,\n  createStartInterceptor,\n  createReplaceHistoryState,\n  shouldReplaceHistory,\n  updateBrowserState,\n} from \"browser-env\";\n\nimport { hashUrlToPath } from \"./hash-utils\";\n\nimport type { RegExpCache } from \"./hash-utils\";\nimport type { HashPluginOptions } from \"./types\";\nimport type {\n  NavigationOptions,\n  Params,\n  PluginApi,\n  Router,\n  State,\n  Plugin,\n} from \"@real-router/core\";\nimport type { Browser, SharedFactoryState } from \"browser-env\";\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    regExpCache: RegExpCache,\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 pluginBuildUrl = (route: string, params?: Params) => {\n      const path = router.buildPath(route, params);\n\n      return `${options.base}#${options.hashPrefix}${path}`;\n    };\n\n    this.#removeExtensions = api.extendRouter({\n      buildUrl: pluginBuildUrl,\n      matchUrl: (url: string) => {\n        const path = hashUrlToPath(url, options.hashPrefix, regExpCache);\n\n        return path ? api.matchPath(path) : undefined;\n      },\n      replaceHistoryState: createReplaceHistoryState(\n        api,\n        router,\n        browser,\n        pluginBuildUrl,\n      ),\n    });\n\n    const handler = createPopstateHandler({\n      router,\n      api,\n      browser,\n      transitionOptions,\n      loggerContext: \"hash-plugin\",\n      buildUrl: (name: string, params?: Params) =>\n        router.buildUrl(name, params),\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          this.#router,\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 { createOptionsValidator } from \"browser-env\";\n\nimport { LOGGER_CONTEXT, defaultOptions } from \"./constants\";\n\nimport type { HashPluginOptions } from \"./types\";\n\nexport const validateOptions = createOptionsValidator<HashPluginOptions>(\n  defaultOptions,\n  LOGGER_CONTEXT,\n);\n","import { getPluginApi } from \"@real-router/core\";\nimport {\n  createSafeBrowser,\n  normalizeBase,\n  safelyEncodePath,\n} from \"browser-env\";\n\nimport { defaultOptions, source } from \"./constants\";\nimport { createRegExpCache, extractHashPath } from \"./hash-utils\";\nimport { HashPlugin } from \"./plugin\";\nimport { validateOptions } from \"./validation\";\n\nimport type { HashPluginOptions } from \"./types\";\nimport type { PluginFactory, Router } from \"@real-router/core\";\nimport type { Browser, SharedFactoryState } from \"browser-env\";\n\nexport function hashPluginFactory(\n  opts?: Partial<HashPluginOptions>,\n  browser?: Browser,\n): PluginFactory {\n  validateOptions(opts);\n\n  const options: Required<HashPluginOptions> = { ...defaultOptions, ...opts };\n\n  options.base = normalizeBase(options.base);\n\n  const regExpCache = createRegExpCache();\n  const resolvedBrowser =\n    browser ??\n    createSafeBrowser(\n      () =>\n        safelyEncodePath(\n          extractHashPath(\n            globalThis.location.hash,\n            options.hashPrefix,\n            regExpCache,\n          ),\n        ) + globalThis.location.search,\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      regExpCache,\n      transitionOptions,\n      shared,\n    );\n\n    return plugin.getPlugin();\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"},"../type-guards/dist/esm/index.mjs":{"bytes":3451,"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"},"../browser-env/dist/esm/index.mjs":{"bytes":4084,"imports":[{"path":"../type-guards/dist/esm/index.mjs","kind":"import-statement","original":"type-guards"},{"path":"@real-router/core","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"},"src/constants.ts":{"bytes":367,"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/hash-utils.ts":{"bytes":1808,"imports":[{"path":"../browser-env/dist/esm/index.mjs","kind":"import-statement","original":"browser-env"},{"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/plugin.ts":{"bytes":2749,"imports":[{"path":"../browser-env/dist/esm/index.mjs","kind":"import-statement","original":"browser-env"},{"path":"src/hash-utils.ts","kind":"import-statement","original":"./hash-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/validation.ts":{"bytes":282,"imports":[{"path":"../browser-env/dist/esm/index.mjs","kind":"import-statement","original":"browser-env"},{"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/factory.ts":{"bytes":1621,"imports":[{"path":"@real-router/core","kind":"import-statement","external":true},{"path":"../browser-env/dist/esm/index.mjs","kind":"import-statement","original":"browser-env"},{"path":"src/constants.ts","kind":"import-statement","original":"./constants"},{"path":"src/hash-utils.ts","kind":"import-statement","original":"./hash-utils"},{"path":"src/plugin.ts","kind":"import-statement","original":"./plugin"},{"path":"src/validation.ts","kind":"import-statement","original":"./validation"},{"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":1283,"imports":[{"path":"src/factory.ts","kind":"import-statement","original":"./factory"},{"path":"../type-guards/dist/esm/index.mjs","kind":"import-statement","original":"type-guards"},{"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":10268},"dist/cjs/index.js":{"imports":[{"path":"@real-router/core","kind":"import-statement","external":true},{"path":"@real-router/core","kind":"import-statement","external":true}],"exports":["hashPluginFactory","isState"],"entryPoint":"src/index.ts","inputs":{"src/factory.ts":{"bytesInOutput":906},"../type-guards/dist/esm/index.mjs":{"bytesInOutput":2337},"../browser-env/dist/esm/index.mjs":{"bytesInOutput":4688},"src/constants.ts":{"bytesInOutput":141},"src/hash-utils.ts":{"bytesInOutput":1091},"src/plugin.ts":{"bytesInOutput":1615},"src/validation.ts":{"bytesInOutput":63},"src/index.ts":{"bytesInOutput":0}},"bytes":11085}}}

package/dist/esm/index.d.mts

@@ -0,0 +1,109 @@
+import { State as State$1, PluginFactory, Params as Params$1 } from '@real-router/core';
+
+/**
+ * Hash-based routing plugin configuration.
+ * Uses URL hash fragment for navigation (e.g., example.com/#/path).
+ */
+interface HashPluginOptions {
+    /**
+     * Prefix for hash (e.g., "!" for "#!/path").
+     *
+     * @default ""
+     */
+    hashPrefix?: string;
+    /**
+     * Base path prepended before hash (e.g., "/app" → "/app#/path").
+     *
+     * @default ""
+     */
+    base?: string;
+    /**
+     * Force deactivation of current route even if canDeactivate returns false.
+     *
+     * @default true
+     */
+    forceDeactivate?: boolean;
+}
+
+interface HistoryBrowser {
+    pushState: (state: State$1, path: string) => void;
+    replaceState: (state: State$1, path: string) => void;
+    addPopstateListener: (fn: (evt: PopStateEvent) => void) => () => void;
+    getHash: () => string;
+}
+interface Browser extends HistoryBrowser {
+    getLocation: () => string;
+}
+
+declare function hashPluginFactory(opts?: Partial<HashPluginOptions>, browser?: Browser): PluginFactory;
+
+type TransitionPhase = "deactivating" | "activating";
+type TransitionReason = "success" | "blocked" | "cancelled" | "error";
+interface TransitionMeta {
+    readonly reload?: boolean;
+    readonly redirected?: boolean;
+    phase: TransitionPhase;
+    from?: string;
+    reason: TransitionReason;
+    blocker?: string;
+    segments: {
+        deactivated: string[];
+        activated: string[];
+        intersection: string;
+    };
+}
+interface State<P extends Params = Params, MP extends Params = Params> {
+    name: string;
+    params: P;
+    path: string;
+    meta?: StateMeta<MP> | undefined;
+    transition?: TransitionMeta | undefined;
+}
+interface StateMeta<P extends Params = Params> {
+    id: number;
+    params: P;
+}
+interface Params {
+    [key: string]: string | string[] | number | number[] | boolean | boolean[] | Params | Params[] | Record<string, string | number | boolean> | null | undefined;
+}
+
+/**
+ * Enhanced type guard for State with deep validation.
+ * Checks not only presence but also types of all required fields.
+ * Validates params using isParams and meta structure if present.
+ *
+ * @param value - Value to check
+ * @returns true if value is a valid State object with correct types
+ *
+ * @example
+ * isStateStrict({ name: 'home', params: {}, path: '/', meta: { id: 1 } }); // true
+ * isStateStrict({ name: 'home', params: 'invalid', path: '/' }); // false
+ */
+declare function isStateStrict<P extends Params = Params, MP extends Params = Params>(value: unknown): value is State<P, MP>;
+
+/**
+ * Module augmentation for real-router.
+ * Extends Router interface with hash plugin methods.
+ */
+declare module "@real-router/core" {
+    interface Router {
+        /**
+         * Builds full URL for a route with base path and hash prefix.
+         * Added by hash plugin.
+         */
+        buildUrl: (name: string, params?: Params$1) => string;
+        /**
+         * Matches URL and returns corresponding state.
+         * Added by hash plugin.
+         */
+        matchUrl: (url: string) => State$1 | undefined;
+        /**
+         * Replaces current history state without triggering navigation.
+         * Added by hash plugin.
+         */
+        replaceHistoryState: (name: string, params?: Params$1, title?: string) => void;
+        start(path?: string): Promise<State$1>;
+    }
+}
+
+export { type Browser, type HashPluginOptions, hashPluginFactory, isStateStrict as isState };

package/dist/esm/index.mjs

@@ -0,0 +1 @@
+import{getPluginApi as e,RouterError as t}from"@real-router/core";var r=/^[A-Z_a-z][\w-]*(?:\.[A-Z_a-z][\w-]*)*$/;function n(e,t=new WeakSet){if(null==e)return!0;const r=typeof e;if("string"===r||"boolean"===r)return!0;if("number"===r)return Number.isFinite(e);if("function"===r||"symbol"===r)return!1;if(Array.isArray(e))return!t.has(e)&&(t.add(e),e.every(e=>n(e,t)));if("object"===r){if(t.has(e))return!1;t.add(e);const r=Object.getPrototypeOf(e);return(null===r||r===Object.prototype)&&Object.values(e).every(e=>n(e,t))}return!1}function o(e){if(null==e)return!0;const t=typeof e;return"string"===t||"boolean"===t||"number"===t&&Number.isFinite(e)}function a(e){if("object"!=typeof e||null===e||Array.isArray(e))return!1;const t=Object.getPrototypeOf(e);if(null!==t&&t!==Object.prototype)return!1;let r=!1;for(const t in e){if(!Object.hasOwn(e,t))continue;const n=e[t];if(!o(n)){const e=typeof n;if("function"===e||"symbol"===e)return!1;r=!0;break}}return!r||n(e)}function i(e){if(null==e)return!0;const t=typeof e;return"string"===t||"boolean"===t||("number"===t?Number.isFinite(e):!!Array.isArray(e)&&e.every(e=>{const t=typeof e;return"string"===t||"boolean"===t||"number"===t&&Number.isFinite(e)}))}function s(e){if("object"!=typeof e||null===e)return!1;const t=e;return!!function(e){return function(e){return"string"==typeof e&&(""===e||!(e.length>1e4)&&(!!e.startsWith("@@")||r.test(e)))}(e.name)&&"string"==typeof e.path&&a(e.params)}(t)&&(void 0===t.meta||function(e){if("object"!=typeof e||null===e)return!1;const t=e;return!("params"in t&&!function(e){if("object"!=typeof e||null===e||Array.isArray(e))return!1;for(const t in e)if(Object.hasOwn(e,t)&&!i(e[t]))return!1;return!0}(t.params)||"id"in t&&"number"!=typeof t.id)}(t.meta))}var c=(e,t)=>{globalThis.history.pushState(e,"",t)},u=(e,t)=>{globalThis.history.replaceState(e,"",t)},l=e=>(globalThis.addEventListener("popstate",e),()=>{globalThis.removeEventListener("popstate",e)}),p=()=>globalThis.location.hash,f=()=>{},h=e=>{let t=!1;return r=>{t||(console.warn(`[browser-env] Browser API is running in a non-browser environment (context: "${e}"). Method "${r}" is a no-op. This is expected for SSR, but may indicate misconfiguration if you expected browser behavior.`),t=!0)}},d=e=>{const t=h(e);return{pushState:()=>{t("pushState")},replaceState:()=>{t("replaceState")},addPopstateListener:()=>(t("addPopstateListener"),f),getHash:()=>(t("getHash"),"")}};function m(e,t,r,n){const o={meta:e.meta,name:e.name,params:e.params,path:e.path};r?n.replaceState(o,t):n.pushState(o,t)}function b(e){let r=!1,n=null;async function o(a){if(r)return console.warn(`[${e.loggerContext}] Transition in progress, deferring popstate event`),void(n=a);r=!0;try{const t=function(e,t,r){if(s(e.state))return{name:e.state.name,params:e.state.params};const n=t.matchPath(r.getLocation());return n?{name:n.name,params:n.params}:void 0}(a,e.api,e.browser);t?await e.router.navigate(t.name,t.params,e.transitionOptions):await e.router.navigateToDefault({...e.transitionOptions,reload:!0,replace:!0})}catch(r){r instanceof t||function(t){console.error(`[${e.loggerContext}] Critical error in onPopState`,t);try{const t=e.router.getState();if(t){const r=e.buildUrl(t.name,t.params);e.browser.replaceState(t,r)}}catch(t){console.error(`[${e.loggerContext}] Failed to recover from critical error`,t)}}(r)}finally{r=!1,function(){if(n){const t=n;n=null,console.warn(`[${e.loggerContext}] Processing deferred popstate event`),o(t)}}()}}return e=>{o(e)}}function g(e,t,r,n){return(o,a={})=>{const i=e.buildState(o,a);if(!i)throw new Error(`[real-router] Cannot replace state: route "${o}" is not found`);m(e.makeState(i.name,i.params,t.buildPath(i.name,i.params),{params:i.meta},1),n(o,a),!0,r)}}var v={hashPrefix:"",base:"",forceDeactivate:!0},y="hash-plugin",w=new Map;function S(e,t,r){const n=(e=>{const t=w.get(e);if(void 0!==t)return t;const r=e.replaceAll(/[$()*+.?[\\\]^{|}-]/g,String.raw`\$&`);return w.set(e,r),r})(t);return(n?e.replace(r.get(`^#${n}`),""):e.slice(1))||"/"}var P,$,L=class{#e;#t;#r;#n;#o;constructor(e,t,r,n,o,a,i){var s;this.#e=e,this.#t=n,this.#r=(s=n,t.addInterceptor("start",(e,t)=>e(t??s.getLocation())));const c=(t,n)=>{const o=e.buildPath(t,n);return`${r.base}#${r.hashPrefix}${o}`};this.#n=t.extendRouter({buildUrl:c,matchUrl:e=>{const n=function(e,t,r){const n=function(e,t){try{const r=new URL(e,globalThis.location.origin);return["http:","https:"].includes(r.protocol)?r:(console.warn(`[${t}] Invalid URL protocol in ${e}`),null)}catch(r){return console.warn(`[${t}] Could not parse url ${e}`,r),null}}(e,y);return n?S(n.hash,t,r)+n.search:null}(e,r.hashPrefix,o);return n?t.matchPath(n):void 0},replaceHistoryState:g(t,e,n,c)});const u=b({router:e,api:t,browser:n,transitionOptions:a,loggerContext:"hash-plugin",buildUrl:(t,r)=>e.buildUrl(t,r)});this.#o=function(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()}}}({browser:n,shared:i,handler:u,cleanup:()=>{this.#r(),this.#n()}})}getPlugin(){return{...this.#o,onTransitionSuccess:(e,t,r)=>{const n=(a=t,i=this.#e,((o=r).replace??!a)||!!o.reload&&i.areStatesEqual(e,a,!1));var o,a,i;m(e,this.#e.buildUrl(e.name,e.params),n,this.#t)}}}},x=(P=v,$=y,e=>{if(e)for(const t of Object.keys(e))if(t in P){const r=e[t],n=typeof P[t],o=typeof r;if(void 0!==r&&o!==n)throw new Error(`[${$}] Invalid type for '${t}': expected ${n}, got ${o}`)}});function O(t,r){x(t);const n={...v,...t};n.base=function(e){if(!e)return e;let t=e;return t.startsWith("/")||(t=`/${t}`),t.endsWith("/")&&(t=t.slice(0,-1)),t}(n.base);const o=function(){const e=new Map;return{get(t){const r=e.get(t);if(void 0!==r)return r;const n=new RegExp(t);return e.set(t,n),n}}}(),a=r??function(e,t){if(void 0!==globalThis.window&&globalThis.history)return{pushState:c,replaceState:u,addPopstateListener:l,getLocation:e,getHash:p};const r=h(t);return{...d(t),getLocation:()=>(r("getLocation"),"")}}(()=>(e=>{try{return encodeURI(decodeURI(e))}catch(t){return console.warn(`[browser-env] Could not encode path "${e}"`,t),e}})(S(globalThis.location.hash,n.hashPrefix,o))+globalThis.location.search,"hash-plugin"),i={forceDeactivate:n.forceDeactivate,source:"popstate",replace:!0},s={removePopStateListener:void 0};return function(t){return new L(t,e(t),n,a,o,i,s).getPlugin()}}export{O as hashPluginFactory,s as isState};//# sourceMappingURL=index.mjs.map

package/dist/esm/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/constants.ts","../../src/hash-utils.ts","../../src/plugin.ts","../../src/validation.ts","../../src/factory.ts"],"names":["i","f","c"],"mappings":"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","file":"index.mjs","sourcesContent":["// 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 { safeParseUrl } from \"browser-env\";\n\nimport { LOGGER_CONTEXT } from \"./constants\";\n\nexport interface RegExpCache {\n  get: (pattern: string) => RegExp;\n}\n\nconst escapeRegExpCache = new Map<string, string>();\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\nexport function createRegExpCache(): RegExpCache {\n  const cache = new Map<string, RegExp>();\n\n  return {\n    get(pattern: string): RegExp {\n      const cached = cache.get(pattern);\n\n      if (cached !== undefined) {\n        return cached;\n      }\n\n      const newRegExp = new RegExp(pattern);\n\n      cache.set(pattern, newRegExp);\n\n      return newRegExp;\n    },\n  };\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 hashPrefix - Hash prefix to strip (e.g., \"!\")\n * @param regExpCache - RegExp cache for compiled patterns\n * @returns Extracted path (e.g., \"/path\")\n */\nexport function extractHashPath(\n  hash: string,\n  hashPrefix: string,\n  regExpCache: RegExpCache,\n): string {\n  const escapedHashPrefix = escapeRegExp(hashPrefix);\n  const path = escapedHashPrefix\n    ? hash.replace(regExpCache.get(`^#${escapedHashPrefix}`), \"\")\n    : hash.slice(1);\n\n  return path || \"/\";\n}\n\nexport function hashUrlToPath(\n  url: string,\n  hashPrefix: string,\n  regExpCache: RegExpCache,\n): string | null {\n  const parsedUrl = safeParseUrl(url, LOGGER_CONTEXT);\n\n  return parsedUrl\n    ? extractHashPath(parsedUrl.hash, hashPrefix, regExpCache) +\n        parsedUrl.search\n    : null;\n}\n","import {\n  createPopstateHandler,\n  createPopstateLifecycle,\n  createStartInterceptor,\n  createReplaceHistoryState,\n  shouldReplaceHistory,\n  updateBrowserState,\n} from \"browser-env\";\n\nimport { hashUrlToPath } from \"./hash-utils\";\n\nimport type { RegExpCache } from \"./hash-utils\";\nimport type { HashPluginOptions } from \"./types\";\nimport type {\n  NavigationOptions,\n  Params,\n  PluginApi,\n  Router,\n  State,\n  Plugin,\n} from \"@real-router/core\";\nimport type { Browser, SharedFactoryState } from \"browser-env\";\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    regExpCache: RegExpCache,\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 pluginBuildUrl = (route: string, params?: Params) => {\n      const path = router.buildPath(route, params);\n\n      return `${options.base}#${options.hashPrefix}${path}`;\n    };\n\n    this.#removeExtensions = api.extendRouter({\n      buildUrl: pluginBuildUrl,\n      matchUrl: (url: string) => {\n        const path = hashUrlToPath(url, options.hashPrefix, regExpCache);\n\n        return path ? api.matchPath(path) : undefined;\n      },\n      replaceHistoryState: createReplaceHistoryState(\n        api,\n        router,\n        browser,\n        pluginBuildUrl,\n      ),\n    });\n\n    const handler = createPopstateHandler({\n      router,\n      api,\n      browser,\n      transitionOptions,\n      loggerContext: \"hash-plugin\",\n      buildUrl: (name: string, params?: Params) =>\n        router.buildUrl(name, params),\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          this.#router,\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 { createOptionsValidator } from \"browser-env\";\n\nimport { LOGGER_CONTEXT, defaultOptions } from \"./constants\";\n\nimport type { HashPluginOptions } from \"./types\";\n\nexport const validateOptions = createOptionsValidator<HashPluginOptions>(\n  defaultOptions,\n  LOGGER_CONTEXT,\n);\n","import { getPluginApi } from \"@real-router/core\";\nimport {\n  createSafeBrowser,\n  normalizeBase,\n  safelyEncodePath,\n} from \"browser-env\";\n\nimport { defaultOptions, source } from \"./constants\";\nimport { createRegExpCache, extractHashPath } from \"./hash-utils\";\nimport { HashPlugin } from \"./plugin\";\nimport { validateOptions } from \"./validation\";\n\nimport type { HashPluginOptions } from \"./types\";\nimport type { PluginFactory, Router } from \"@real-router/core\";\nimport type { Browser, SharedFactoryState } from \"browser-env\";\n\nexport function hashPluginFactory(\n  opts?: Partial<HashPluginOptions>,\n  browser?: Browser,\n): PluginFactory {\n  validateOptions(opts);\n\n  const options: Required<HashPluginOptions> = { ...defaultOptions, ...opts };\n\n  options.base = normalizeBase(options.base);\n\n  const regExpCache = createRegExpCache();\n  const resolvedBrowser =\n    browser ??\n    createSafeBrowser(\n      () =>\n        safelyEncodePath(\n          extractHashPath(\n            globalThis.location.hash,\n            options.hashPrefix,\n            regExpCache,\n          ),\n        ) + globalThis.location.search,\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      regExpCache,\n      transitionOptions,\n      shared,\n    );\n\n    return plugin.getPlugin();\n  };\n}\n"]}

package/dist/esm/metafile-esm.json

@@ -0,0 +1 @@
+{"inputs":{"../type-guards/dist/esm/index.mjs":{"bytes":3451,"imports":[],"format":"esm"},"../browser-env/dist/esm/index.mjs":{"bytes":4084,"imports":[{"path":"../type-guards/dist/esm/index.mjs","kind":"import-statement","original":"type-guards"},{"path":"@real-router/core","kind":"import-statement","external":true}],"format":"esm"},"src/constants.ts":{"bytes":367,"imports":[],"format":"esm"},"src/hash-utils.ts":{"bytes":1808,"imports":[{"path":"../browser-env/dist/esm/index.mjs","kind":"import-statement","original":"browser-env"},{"path":"src/constants.ts","kind":"import-statement","original":"./constants"}],"format":"esm"},"src/plugin.ts":{"bytes":2749,"imports":[{"path":"../browser-env/dist/esm/index.mjs","kind":"import-statement","original":"browser-env"},{"path":"src/hash-utils.ts","kind":"import-statement","original":"./hash-utils"}],"format":"esm"},"src/validation.ts":{"bytes":282,"imports":[{"path":"../browser-env/dist/esm/index.mjs","kind":"import-statement","original":"browser-env"},{"path":"src/constants.ts","kind":"import-statement","original":"./constants"}],"format":"esm"},"src/factory.ts":{"bytes":1621,"imports":[{"path":"@real-router/core","kind":"import-statement","external":true},{"path":"../browser-env/dist/esm/index.mjs","kind":"import-statement","original":"browser-env"},{"path":"src/constants.ts","kind":"import-statement","original":"./constants"},{"path":"src/hash-utils.ts","kind":"import-statement","original":"./hash-utils"},{"path":"src/plugin.ts","kind":"import-statement","original":"./plugin"},{"path":"src/validation.ts","kind":"import-statement","original":"./validation"}],"format":"esm"},"src/index.ts":{"bytes":1283,"imports":[{"path":"src/factory.ts","kind":"import-statement","original":"./factory"},{"path":"../type-guards/dist/esm/index.mjs","kind":"import-statement","original":"type-guards"}],"format":"esm"}},"outputs":{"dist/esm/index.mjs.map":{"imports":[],"exports":[],"inputs":{},"bytes":10268},"dist/esm/index.mjs":{"imports":[{"path":"@real-router/core","kind":"import-statement","external":true},{"path":"@real-router/core","kind":"import-statement","external":true}],"exports":["hashPluginFactory","isState"],"entryPoint":"src/index.ts","inputs":{"src/factory.ts":{"bytesInOutput":906},"../type-guards/dist/esm/index.mjs":{"bytesInOutput":2337},"../browser-env/dist/esm/index.mjs":{"bytesInOutput":4688},"src/constants.ts":{"bytesInOutput":141},"src/hash-utils.ts":{"bytesInOutput":1091},"src/plugin.ts":{"bytesInOutput":1615},"src/validation.ts":{"bytesInOutput":63},"src/index.ts":{"bytesInOutput":0}},"bytes":11085}}}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@real-router/hash-plugin",
+  "version": "0.0.1",
+  "type": "commonjs",
+  "description": "Hash-based routing plugin for Real-Router",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.mjs",
+  "types": "./dist/esm/index.d.mts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": {
+        "import": "./dist/esm/index.d.mts",
+        "require": "./dist/cjs/index.d.ts"
+      },
+      "import": "./dist/esm/index.mjs",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/greydragon888/real-router.git"
+  },
+  "keywords": [
+    "real-router",
+    "hash",
+    "routing",
+    "navigation"
+  ],
+  "author": {
+    "name": "Oleg Ivanov",
+    "email": "greydragon888@gmail.com",
+    "url": "https://github.com/greydragon888"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/greydragon888/real-router",
+  "bugs": {
+    "url": "https://github.com/greydragon888/real-router/issues"
+  },
+  "scripts": {
+    "test": "vitest",
+    "build": "tsup",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint --cache --ext .ts src/ tests/ --fix --max-warnings 0",
+    "lint:package": "publint",
+    "lint:types": "attw --pack ."
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@real-router/core": "workspace:^"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "6.9.1",
+    "browser-env": "workspace:^",
+    "jsdom": "27.4.0",
+    "type-guards": "workspace:^"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,16 @@
+// packages/hash-plugin/src/constants.ts
+
+import type { HashPluginOptions } from "./types";
+
+export const defaultOptions: Required<HashPluginOptions> = {
+  hashPrefix: "",
+  base: "",
+  forceDeactivate: true,
+};
+
+/**
+ * Source identifier for transitions triggered by browser events.
+ */
+export const source = "popstate";
+
+export const LOGGER_CONTEXT = "hash-plugin";

package/src/factory.ts

@@ -0,0 +1,63 @@
+import { getPluginApi } from "@real-router/core";
+import {
+  createSafeBrowser,
+  normalizeBase,
+  safelyEncodePath,
+} from "browser-env";
+
+import { defaultOptions, source } from "./constants";
+import { createRegExpCache, extractHashPath } from "./hash-utils";
+import { HashPlugin } from "./plugin";
+import { validateOptions } from "./validation";
+
+import type { HashPluginOptions } from "./types";
+import type { PluginFactory, Router } from "@real-router/core";
+import type { Browser, SharedFactoryState } from "browser-env";
+
+export function hashPluginFactory(
+  opts?: Partial<HashPluginOptions>,
+  browser?: Browser,
+): PluginFactory {
+  validateOptions(opts);
+
+  const options: Required<HashPluginOptions> = { ...defaultOptions, ...opts };
+
+  options.base = normalizeBase(options.base);
+
+  const regExpCache = createRegExpCache();
+  const resolvedBrowser =
+    browser ??
+    createSafeBrowser(
+      () =>
+        safelyEncodePath(
+          extractHashPath(
+            globalThis.location.hash,
+            options.hashPrefix,
+            regExpCache,
+          ),
+        ) + globalThis.location.search,
+      "hash-plugin",
+    );
+
+  const transitionOptions = {
+    forceDeactivate: options.forceDeactivate,
+    source,
+    replace: true as const,
+  };
+
+  const shared: SharedFactoryState = { removePopStateListener: undefined };
+
+  return function hashPlugin(routerBase) {
+    const plugin = new HashPlugin(
+      routerBase as Router,
+      getPluginApi(routerBase),
+      options,
+      resolvedBrowser,
+      regExpCache,
+      transitionOptions,
+      shared,
+    );
+
+    return plugin.getPlugin();
+  };
+}

package/src/hash-utils.ts

@@ -0,0 +1,79 @@
+// packages/hash-plugin/src/hash-utils.ts
+
+import { safeParseUrl } from "browser-env";
+
+import { LOGGER_CONTEXT } from "./constants";
+
+export interface RegExpCache {
+  get: (pattern: string) => RegExp;
+}
+
+const escapeRegExpCache = new Map<string, string>();
+
+export const escapeRegExp = (str: string): string => {
+  const cached = escapeRegExpCache.get(str);
+
+  if (cached !== undefined) {
+    return cached;
+  }
+
+  const escaped = str.replaceAll(/[$()*+.?[\\\]^{|}-]/g, String.raw`\$&`);
+
+  escapeRegExpCache.set(str, escaped);
+
+  return escaped;
+};
+
+export function createRegExpCache(): RegExpCache {
+  const cache = new Map<string, RegExp>();
+
+  return {
+    get(pattern: string): RegExp {
+      const cached = cache.get(pattern);
+
+      if (cached !== undefined) {
+        return cached;
+      }
+
+      const newRegExp = new RegExp(pattern);
+
+      cache.set(pattern, newRegExp);
+
+      return newRegExp;
+    },
+  };
+}
+
+/**
+ * Extract path from URL hash, stripping hash prefix.
+ *
+ * @param hash - URL hash (e.g., "#/path" or "#!/path")
+ * @param hashPrefix - Hash prefix to strip (e.g., "!")
+ * @param regExpCache - RegExp cache for compiled patterns
+ * @returns Extracted path (e.g., "/path")
+ */
+export function extractHashPath(
+  hash: string,
+  hashPrefix: string,
+  regExpCache: RegExpCache,
+): string {
+  const escapedHashPrefix = escapeRegExp(hashPrefix);
+  const path = escapedHashPrefix
+    ? hash.replace(regExpCache.get(`^#${escapedHashPrefix}`), "")
+    : hash.slice(1);
+
+  return path || "/";
+}
+
+export function hashUrlToPath(
+  url: string,
+  hashPrefix: string,
+  regExpCache: RegExpCache,
+): string | null {
+  const parsedUrl = safeParseUrl(url, LOGGER_CONTEXT);
+
+  return parsedUrl
+    ? extractHashPath(parsedUrl.hash, hashPrefix, regExpCache) +
+        parsedUrl.search
+    : null;
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+// packages/hash-plugin/src/index.ts
+/* eslint-disable @typescript-eslint/method-signature-style -- method syntax required for declaration merging overload (property syntax causes TS2717) */
+// Public API exports for hash-plugin
+
+import type { Params, State } from "@real-router/core";
+
+// Main plugin factory
+export { hashPluginFactory } from "./factory";
+
+// Types
+export type { HashPluginOptions } from "./types";
+
+export type { Browser } from "browser-env";
+
+// Type guards
+export { isStateStrict as isState } from "type-guards";
+
+/**
+ * Module augmentation for real-router.
+ * Extends Router interface with hash plugin methods.
+ */
+declare module "@real-router/core" {
+  interface Router {
+    /**
+     * Builds full URL for a route with base path and hash prefix.
+     * Added by hash plugin.
+     */
+    buildUrl: (name: string, params?: Params) => string;
+
+    /**
+     * Matches URL and returns corresponding state.
+     * Added by hash plugin.
+     */
+    matchUrl: (url: string) => State | undefined;
+
+    /**
+     * Replaces current history state without triggering navigation.
+     * Added by hash plugin.
+     */
+    replaceHistoryState: (
+      name: string,
+      params?: Params,
+      title?: string,
+    ) => void;
+
+    start(path?: string): Promise<State>;
+  }
+}

package/src/plugin.ts

@@ -0,0 +1,113 @@
+import {
+  createPopstateHandler,
+  createPopstateLifecycle,
+  createStartInterceptor,
+  createReplaceHistoryState,
+  shouldReplaceHistory,
+  updateBrowserState,
+} from "browser-env";
+
+import { hashUrlToPath } from "./hash-utils";
+
+import type { RegExpCache } from "./hash-utils";
+import type { HashPluginOptions } from "./types";
+import type {
+  NavigationOptions,
+  Params,
+  PluginApi,
+  Router,
+  State,
+  Plugin,
+} from "@real-router/core";
+import type { Browser, SharedFactoryState } from "browser-env";
+
+export class HashPlugin {
+  readonly #router: Router;
+  readonly #browser: Browser;
+  readonly #removeStartInterceptor: () => void;
+  readonly #removeExtensions: () => void;
+  readonly #lifecycle: Pick<Plugin, "onStart" | "onStop" | "teardown">;
+
+  constructor(
+    router: Router,
+    api: PluginApi,
+    options: Required<HashPluginOptions>,
+    browser: Browser,
+    regExpCache: RegExpCache,
+    transitionOptions: {
+      source: string;
+      replace: true;
+      forceDeactivate?: boolean;
+    },
+    shared: SharedFactoryState,
+  ) {
+    this.#router = router;
+    this.#browser = browser;
+
+    this.#removeStartInterceptor = createStartInterceptor(api, browser);
+
+    const pluginBuildUrl = (route: string, params?: Params) => {
+      const path = router.buildPath(route, params);
+
+      return `${options.base}#${options.hashPrefix}${path}`;
+    };
+
+    this.#removeExtensions = api.extendRouter({
+      buildUrl: pluginBuildUrl,
+      matchUrl: (url: string) => {
+        const path = hashUrlToPath(url, options.hashPrefix, regExpCache);
+
+        return path ? api.matchPath(path) : undefined;
+      },
+      replaceHistoryState: createReplaceHistoryState(
+        api,
+        router,
+        browser,
+        pluginBuildUrl,
+      ),
+    });
+
+    const handler = createPopstateHandler({
+      router,
+      api,
+      browser,
+      transitionOptions,
+      loggerContext: "hash-plugin",
+      buildUrl: (name: string, params?: Params) =>
+        router.buildUrl(name, params),
+    });
+
+    this.#lifecycle = createPopstateLifecycle({
+      browser,
+      shared,
+      handler,
+      cleanup: () => {
+        this.#removeStartInterceptor();
+        this.#removeExtensions();
+      },
+    });
+  }
+
+  getPlugin(): Plugin {
+    return {
+      ...this.#lifecycle,
+
+      onTransitionSuccess: (
+        toState: State,
+        fromState: State | undefined,
+        navOptions: NavigationOptions,
+      ) => {
+        const replaceHistory = shouldReplaceHistory(
+          navOptions,
+          toState,
+          fromState,
+          this.#router,
+        );
+
+        const url = this.#router.buildUrl(toState.name, toState.params);
+
+        updateBrowserState(toState, url, replaceHistory, this.#browser);
+      },
+    };
+  }
+}

package/src/types.ts

@@ -0,0 +1,28 @@
+// packages/hash-plugin/src/types.ts
+
+/**
+ * Hash-based routing plugin configuration.
+ * Uses URL hash fragment for navigation (e.g., example.com/#/path).
+ */
+export interface HashPluginOptions {
+  /**
+   * Prefix for hash (e.g., "!" for "#!/path").
+   *
+   * @default ""
+   */
+  hashPrefix?: string;
+
+  /**
+   * Base path prepended before hash (e.g., "/app" → "/app#/path").
+   *
+   * @default ""
+   */
+  base?: string;
+
+  /**
+   * Force deactivation of current route even if canDeactivate returns false.
+   *
+   * @default true
+   */
+  forceDeactivate?: boolean;
+}

package/src/validation.ts

@@ -0,0 +1,10 @@
+import { createOptionsValidator } from "browser-env";
+
+import { LOGGER_CONTEXT, defaultOptions } from "./constants";
+
+import type { HashPluginOptions } from "./types";
+
+export const validateOptions = createOptionsValidator<HashPluginOptions>(
+  defaultOptions,
+  LOGGER_CONTEXT,
+);