@real-router/browser-plugin 0.17.6 → 0.17.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@real-router/browser-plugin",
-  "version": "0.17.6",
+  "version": "0.17.8",
   "type": "commonjs",
   "description": "Browser integration plugin with History API, hash routing, and popstate support",
   "main": "./dist/cjs/index.js",
@@ -18,8 +18,7 @@
     }
   },
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "repository": {
     "type": "git",
@@ -45,7 +44,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@real-router/core": "^0.56.0",
+    "@real-router/core": "^0.58.0",
     "@real-router/types": "^0.36.0"
   },
   "devDependencies": {

package/src/constants.ts

@@ -1,15 +0,0 @@
-import type { BrowserPluginOptions } from "./types";
-
-export const defaultOptions: Required<BrowserPluginOptions> = {
-  forceDeactivate: true,
-  base: "",
-};
-
-/**
- * Source identifier for transitions triggered by browser events.
- * Used to distinguish browser-initiated navigation (back/forward buttons)
- * from programmatic navigation (router.navigate()).
- */
-export const POPSTATE_SOURCE = "popstate";
-
-export const LOGGER_CONTEXT = "browser-plugin";

package/src/factory.ts

@@ -1,225 +0,0 @@
-import { getPluginApi } from "@real-router/core/api";
-
-import {
-  buildUrl,
-  createPluginBuildUrl,
-  createPopstateHandler,
-  createPopstateLifecycle,
-  createReplaceHistoryState,
-  createSafeBrowser,
-  createStartInterceptor,
-  createUpdateBrowserState,
-  encodeHashFragment,
-  extractPath,
-  getDecodedHash,
-  normalizeBase,
-  normalizeHashInput,
-  safelyEncodePath,
-  shouldReplaceHistory,
-  urlToPath,
-} from "./browser-env";
-import { defaultOptions, LOGGER_CONTEXT, POPSTATE_SOURCE } from "./constants";
-import { validateOptions } from "./validation";
-
-import type {
-  Browser,
-  PopstateTransitionOptions,
-  SharedFactoryState,
-  UrlContext,
-} from "./browser-env";
-import type { BrowserContext, BrowserPluginOptions } from "./types";
-import type {
-  NavigationOptions,
-  Plugin,
-  PluginFactory,
-  Router,
-  State,
-} from "@real-router/core";
-import type { PluginApi } from "@real-router/core/api";
-
-const FROZEN_POPSTATE: BrowserContext = Object.freeze({
-  source: "popstate",
-  direction: "back",
-});
-const FROZEN_NAVIGATE: BrowserContext = Object.freeze({
-  source: "navigate",
-  direction: "forward",
-});
-
-export function browserPluginFactory(
-  opts?: Partial<BrowserPluginOptions>,
-  browser?: Browser,
-): PluginFactory {
-  validateOptions(opts);
-
-  const options: Required<BrowserPluginOptions> = {
-    ...defaultOptions,
-    ...opts,
-  };
-
-  options.base = normalizeBase(options.base);
-
-  const resolvedBrowser = browser ?? createDefaultBrowser(options.base);
-
-  const transitionOptions = {
-    forceDeactivate: options.forceDeactivate,
-    source: POPSTATE_SOURCE,
-    replace: true as const,
-  };
-
-  const shared: SharedFactoryState = { removePopStateListener: undefined };
-
-  return function browserPlugin(routerBase) {
-    return createBrowserPlugin(
-      routerBase as Router,
-      getPluginApi(routerBase),
-      options,
-      resolvedBrowser,
-      transitionOptions,
-      shared,
-    );
-  };
-}
-
-/**
- * Creates the default `Browser` for the plugin, with a memoized `getLocation`
- * that skips re-running `extractPath`/`safelyEncodePath` when neither
- * `pathname` nor `search` has changed since the last call (#8.2 A7).
- *
- * Initial sentinel is `"\0"` — a NUL byte cannot appear in a real
- * `location.pathname`, so the first call is always a miss without needing a
- * separate "primed" flag.
- */
-function createDefaultBrowser(base: string): Browser {
-  let cachedPathname = "\0";
-  let cachedSearch = "";
-  let cachedResult = "";
-
-  return createSafeBrowser(() => {
-    const { pathname, search } = globalThis.location;
-
-    if (pathname === cachedPathname && search === cachedSearch) {
-      return cachedResult;
-    }
-
-    cachedPathname = pathname;
-    cachedSearch = search;
-    cachedResult = safelyEncodePath(extractPath(pathname, base)) + search;
-
-    return cachedResult;
-  }, "browser-plugin");
-}
-
-function createBrowserPlugin(
-  router: Router,
-  api: PluginApi,
-  options: Required<BrowserPluginOptions>,
-  browser: Browser,
-  transitionOptions: PopstateTransitionOptions,
-  shared: SharedFactoryState,
-): Plugin {
-  const claim = api.claimContextNamespace("browser");
-  // Shared URL namespace (#532) — both navigation-plugin and browser-plugin
-  // claim "url"; mutually exclusive at runtime.
-  const urlClaim = api.claimContextNamespace("url") as {
-    write: (state: State, value: UrlContext) => void;
-    release: () => void;
-  };
-  const updateState = createUpdateBrowserState();
-  const removeStartInterceptor = createStartInterceptor(api, browser);
-
-  const pluginBuildUrl = createPluginBuildUrl(router, options.base);
-
-  const removeExtensions = api.extendRouter({
-    buildUrl: pluginBuildUrl,
-    matchUrl: (url: string) =>
-      api.matchPath(urlToPath(url, options.base)) ?? undefined,
-    replaceHistoryState: createReplaceHistoryState(
-      api,
-      router,
-      browser,
-      pluginBuildUrl,
-    ),
-  });
-
-  const handler = createPopstateHandler({
-    router,
-    api,
-    browser,
-    allowNotFound: api.getOptions().allowNotFound,
-    transitionOptions,
-    loggerContext: LOGGER_CONTEXT,
-    buildUrl: pluginBuildUrl,
-    // Hash bridging (#532). popstate doesn't carry a URL — we sample
-    // location.hash after the browser has updated to the destination.
-    getCurrentHash: () => getDecodedHash(browser),
-    getCurrentContextHash: () =>
-      (router.getState()?.context as { url?: { hash?: string } } | undefined)
-        ?.url?.hash ?? "",
-  });
-
-  const lifecycle = createPopstateLifecycle({
-    browser,
-    shared,
-    handler,
-    cleanup: () => {
-      removeStartInterceptor();
-      removeExtensions();
-      claim.release();
-      urlClaim.release();
-    },
-  });
-
-  return {
-    ...lifecycle,
-
-    onTransitionSuccess: (
-      toState: State,
-      fromState: State | undefined,
-      navOptions: NavigationOptions,
-    ) => {
-      const replaceHistory = shouldReplaceHistory(
-        navOptions,
-        toState,
-        fromState,
-      );
-
-      // Tri-state hash resolution (#532).
-      //   navOptions.hash === undefined → preserve current browser hash
-      //   navOptions.hash === ""        → explicitly clear
-      //   navOptions.hash === "value"   → explicitly set
-      //
-      // The "preserve" branch reads location.hash from the browser, not
-      // fromState.context.url.hash — captures dynamic fragment changes
-      // (anchor clicks, manual location.hash assignment) made outside the
-      // plugin. hashChanged compares the chosen hash against the published
-      // previous hash so subscribers see a true signal.
-      const browserHash = getDecodedHash(browser);
-      const publishedPrevHash =
-        (fromState?.context as { url?: { hash?: string } } | undefined)?.url
-          ?.hash ?? "";
-
-      const hash =
-        navOptions.hash === undefined
-          ? browserHash
-          : normalizeHashInput(navOptions.hash);
-
-      urlClaim.write(
-        toState,
-        Object.freeze({
-          hash,
-          hashChanged: navOptions.hashChange ?? hash !== publishedPrevHash,
-        }),
-      );
-
-      const url = buildUrl(toState.path, options.base);
-      const finalUrl = hash ? `${url}#${encodeHashFragment(hash)}` : url;
-
-      updateState(toState, finalUrl, replaceHistory, browser);
-
-      const isPopstate = navOptions.source === POPSTATE_SOURCE;
-
-      claim.write(toState, isPopstate ? FROZEN_POPSTATE : FROZEN_NAVIGATE);
-    },
-  };
-}

package/src/index.ts

@@ -1,82 +0,0 @@
-/* eslint-disable @typescript-eslint/method-signature-style -- method syntax required for declaration merging overload (property syntax causes TS2717) */
-
-import type { Params, State } from "@real-router/core";
-
-// Main plugin factory
-export { browserPluginFactory } from "./factory";
-
-// Types
-export type {
-  BrowserPluginOptions,
-  BrowserContext,
-  BrowserDirection,
-  BrowserSource,
-} 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 browser plugin methods.
- */
-declare module "@real-router/types" {
-  interface StateContext {
-    browser?: import("./types").BrowserContext;
-    /**
-     * URL fragment ("hash") layer state (#532). Populated by both URL plugins
-     * (navigation-plugin, browser-plugin) — they are mutually exclusive at
-     * runtime, so only one writes to this namespace.
-     */
-    url?: import("./browser-env").UrlContext;
-  }
-
-  interface NavigationOptions {
-    /** @internal — set by browser/hash/navigation plugins to mark transition origin. */
-    source?: string;
-    /**
-     * URL fragment override (decoded, no leading "#") (#532).
-     * Tri-state: `undefined` → preserve current; `""` → clear; non-empty → set.
-     */
-    hash?: string;
-    /**
-     * @internal — set by URL plugins on hash-only browser-driven navigation.
-     * Subscribers should branch on `state.context.url.hashChanged` instead.
-     */
-    hashChange?: boolean;
-  }
-}
-
-declare module "@real-router/core" {
-  interface Router {
-    /**
-     * Builds full URL for a route with base path and (optionally) hash fragment.
-     * Added by browser plugin.
-     */
-    buildUrl(
-      name: string,
-      params?: Params,
-      options?: { hash?: string },
-    ): 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,
-      options?: { hash?: string },
-    ): void;
-
-    start(path?: string): Promise<State>;
-  }
-}

package/src/types.ts

@@ -1,36 +0,0 @@
-/**
- * Browser plugin configuration.
- */
-export type BrowserSource = "popstate" | "navigate";
-
-/**
- * Logical direction of the navigation that produced the current state.
- * Derived from `source`: any popstate event (browser back / forward / hash
- * jump) maps to `"back"`; programmatic `router.navigate()` maps to
- * `"forward"`. The Web Platform does not surface a true forward-vs-back
- * distinction in the popstate event, so consumers wanting reverse-aware
- * animations should read this field rather than maintaining their own
- * popstate listener.
- */
-export type BrowserDirection = "forward" | "back";
-
-export interface BrowserContext {
-  source: BrowserSource;
-  direction: BrowserDirection;
-}
-
-export interface BrowserPluginOptions {
-  /**
-   * 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;
-}

package/src/validation.ts

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