@pithyjs/router 0.1.0-beta.0

package/dist/index.js

@@ -0,0 +1,49 @@
+/** @codex
+{
+  "id": "pithy.router",
+  "title": "PithyJS Router Core",
+  "category": "feature"
+}
+*/
+// Export core types
+export * from './router/core/types';
+// Export matcher utilities
+export * from './router/core/matcher';
+// Export route tree utilities
+export * from './router/core/route-tree';
+// Export parameter utilities
+export * from './router/core/params';
+// Export utility functions
+export * from './router/core/utils';
+// Export router core
+export * from './router/core/router';
+// Export configuration utilities
+export * from './router/core/config';
+// Export history management
+export * from './router/core/history';
+// Export router directives
+export * from './router/integration/directives';
+// Export directive binder for core integration
+export { setGlobalRouter, getGlobalRouter, } from './router/integration/directive-binder';
+// Export loader system
+export * from './router/features/loaders';
+// Export guards system
+export * from './router/features/guards';
+// Export prefetch system
+export * from './router/features/prefetch';
+// Export HMR system
+export * from './router/integration/hmr';
+// Export link interceptor
+export * from './router/integration/link-interceptor';
+// Export scroll and focus management
+export * from './router/features/ux/scroll-focus';
+// Export view transitions
+export * from './router/features/ux/transitions';
+// Export error handling system
+export * from './router/features/errors';
+// Export outlet system
+export { OutletManager } from './router/features/outlet';
+export { buildSegmentChain } from './router/features/outlet/segment-chain';
+// Export history adapters
+export { BrowserHistoryAdapter, MemoryHistoryAdapter, } from './router/integration/history-adapter';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF,oBAAoB;AACpB,cAAc,qBAAqB,CAAC;AAEpC,2BAA2B;AAC3B,cAAc,uBAAuB,CAAC;AAEtC,8BAA8B;AAC9B,cAAc,0BAA0B,CAAC;AAEzC,6BAA6B;AAC7B,cAAc,sBAAsB,CAAC;AAErC,2BAA2B;AAC3B,cAAc,qBAAqB,CAAC;AAEpC,qBAAqB;AACrB,cAAc,sBAAsB,CAAC;AAErC,iCAAiC;AACjC,cAAc,sBAAsB,CAAC;AAErC,4BAA4B;AAC5B,cAAc,uBAAuB,CAAC;AAEtC,2BAA2B;AAC3B,cAAc,iCAAiC,CAAC;AAEhD,+CAA+C;AAC/C,OAAO,EACL,eAAe,EACf,eAAe,GAChB,MAAM,uCAAuC,CAAC;AAE/C,uBAAuB;AACvB,cAAc,2BAA2B,CAAC;AAE1C,uBAAuB;AACvB,cAAc,0BAA0B,CAAC;AAEzC,yBAAyB;AACzB,cAAc,4BAA4B,CAAC;AAE3C,oBAAoB;AACpB,cAAc,0BAA0B,CAAC;AAEzC,0BAA0B;AAC1B,cAAc,uCAAuC,CAAC;AAEtD,qCAAqC;AACrC,cAAc,mCAAmC,CAAC;AAElD,0BAA0B;AAC1B,cAAc,kCAAkC,CAAC;AAEjD,+BAA+B;AAC/B,cAAc,0BAA0B,CAAC;AAEzC,uBAAuB;AACvB,OAAO,EAAE,aAAa,EAAuB,MAAM,0BAA0B,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAE3E,0BAA0B;AAC1B,OAAO,EACL,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,sCAAsC,CAAC"}

package/dist/router/core/config.d.ts

@@ -0,0 +1,22 @@
+/** @codex
+{
+  "id": "pithy.router.core.config",
+  "title": "Router Configuration Normalization",
+  "category": "runtime"
+}
+*/
+import type { RouterConfig } from './types';
+/** @codexApi {"parent":"pithy.router.core.config","name":"normalizeConfig","stability":"stable","signature":"(config?: RouterConfig) => RouterConfig"} */
+/**
+ * Normalize and merge user-provided router configuration with defaults
+ * @param config - User-provided router configuration
+ * @returns Normalized router configuration with all required fields
+ */
+export declare function normalizeConfig(config?: RouterConfig): RouterConfig;
+/** @codexApi {"parent":"pithy.router.core.config","name":"initializeScrollRestoration","stability":"stable","signature":"() => void"} */
+/**
+ * Initialize manual scroll restoration to disable browser's automatic behavior
+ * This is a side effect that should be called once during router initialization
+ */
+export declare function initializeScrollRestoration(): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/router/core/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/router/core/config.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AA+B5C,0JAA0J;AAC1J;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,GAAE,YAAiB,GAAG,YAAY,CAKvE;AAED,yIAAyI;AACzI;;;GAGG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAQlD"}

package/dist/router/core/config.js

@@ -0,0 +1,54 @@
+/** @codex
+{
+  "id": "pithy.router.core.config",
+  "title": "Router Configuration Normalization",
+  "category": "runtime"
+}
+*/
+/**
+ * Default router configuration values
+ */
+const DEFAULT_CONFIG = {
+    basePath: '',
+    trailingSlash: 'never',
+    decodeParams: true,
+    viewTransitions: false,
+    a11y: true,
+    interceptLinks: true,
+    linkIgnoreAttr: 'data-router-ignore',
+    loadingPolicy: 'replace',
+    popstateLoading: 'none',
+    setAsGlobal: true,
+    // exposeToWindow will be set dynamically in Router constructor based on env
+    exposeToWindow: false,
+    windowKey: 'router',
+    outletSelector: '[data-router-outlet]',
+};
+/** @codexApi {"parent":"pithy.router.core.config","name":"normalizeConfig","stability":"stable","signature":"(config?: RouterConfig) => RouterConfig"} */
+/**
+ * Normalize and merge user-provided router configuration with defaults
+ * @param config - User-provided router configuration
+ * @returns Normalized router configuration with all required fields
+ */
+export function normalizeConfig(config = {}) {
+    return {
+        ...DEFAULT_CONFIG,
+        ...config,
+    };
+}
+/** @codexApi {"parent":"pithy.router.core.config","name":"initializeScrollRestoration","stability":"stable","signature":"() => void"} */
+/**
+ * Initialize manual scroll restoration to disable browser's automatic behavior
+ * This is a side effect that should be called once during router initialization
+ */
+export function initializeScrollRestoration() {
+    try {
+        if (typeof history !== 'undefined' && 'scrollRestoration' in history) {
+            history.scrollRestoration = 'manual';
+        }
+    }
+    catch (e) {
+        console.warn('[Router] Failed to set scroll restoration to manual:', e);
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/router/core/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/router/core/config.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAaF;;GAEG;AACH,MAAM,cAAc,GAAoC;IACtD,QAAQ,EAAE,EAAE;IACZ,aAAa,EAAE,OAAO;IACtB,YAAY,EAAE,IAAI;IAClB,eAAe,EAAE,KAAK;IACtB,IAAI,EAAE,IAAI;IACV,cAAc,EAAE,IAAI;IACpB,cAAc,EAAE,oBAAoB;IACpC,aAAa,EAAE,SAAS;IACxB,eAAe,EAAE,MAAM;IACvB,WAAW,EAAE,IAAI;IACjB,4EAA4E;IAC5E,cAAc,EAAE,KAAK;IACrB,SAAS,EAAE,QAAQ;IACnB,cAAc,EAAE,sBAAsB;CACvC,CAAC;AAEF,0JAA0J;AAC1J;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,SAAuB,EAAE;IACvD,OAAO;QACL,GAAG,cAAc;QACjB,GAAG,MAAM;KACM,CAAC;AACpB,CAAC;AAED,yIAAyI;AACzI;;;GAGG;AACH,MAAM,UAAU,2BAA2B;IACzC,IAAI,CAAC;QACH,IAAI,OAAO,OAAO,KAAK,WAAW,IAAI,mBAAmB,IAAI,OAAO,EAAE,CAAC;YACrE,OAAO,CAAC,iBAAiB,GAAG,QAAQ,CAAC;QACvC,CAAC;IACH,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,CAAC,IAAI,CAAC,sDAAsD,EAAE,CAAC,CAAC,CAAC;IAC1E,CAAC;AACH,CAAC"}

package/dist/router/core/constants.d.ts

@@ -0,0 +1,89 @@
+/** @codex
+{
+  "id": "pithy.router.constants",
+  "title": "Router Configuration Constants",
+  "category": "config"
+}
+*/
+/**
+ * Router package constants
+ *
+ * Centralized location for all magic numbers and configuration defaults
+ * used throughout the router package.
+ */
+/**
+ * Prefetch configuration defaults
+ */
+export declare const PREFETCH_DEFAULTS: {
+    /** Default hover delay before prefetching (ms) */
+    readonly HOVER_DELAY: 150;
+    /** Default cache TTL for prefetched resources (ms) - 5 minutes */
+    readonly CACHE_TTL: 300000;
+    /** Intent velocity threshold for mouse movement (pixels/second) */
+    readonly INTENT_VELOCITY_THRESHOLD: 100;
+    /** Number of samples for direction detection */
+    readonly INTENT_DIRECTION_SAMPLES: 3;
+    /** Maximum cache size for prefetched resources */
+    readonly MAX_CACHE_SIZE: 100;
+};
+/**
+ * Scroll and focus management defaults
+ */
+export declare const SCROLL_FOCUS_DEFAULTS: {
+    /** Delay before attempting to scroll to anchor (ms) */
+    readonly ANCHOR_DELAY: 100;
+    /** Number of retries for anchor scrolling */
+    readonly ANCHOR_RETRIES: 3;
+    /** Maximum age for scroll positions (ms) - 5 minutes */
+    readonly SCROLL_POSITION_MAX_AGE: number;
+    /** Clean old positions interval (ms) - 1 second */
+    readonly CLEAN_POSITIONS_INTERVAL: 1000;
+    /** Default max age for cleanup (ms) - 30 minutes */
+    readonly DEFAULT_CLEANUP_MAX_AGE: number;
+    /** Announcer element offset (for accessibility) */
+    readonly ANNOUNCER_OFFSET: -10000;
+};
+/**
+ * Loader configuration defaults
+ */
+export declare const LOADER_DEFAULTS: {
+    /** Default cache TTL for loader data (ms) - 5 minutes */
+    readonly CACHE_TTL: 300000;
+    /** Default maximum cache size */
+    readonly MAX_CACHE_SIZE: 100;
+};
+/**
+ * Route matcher scoring weights
+ */
+export declare const MATCHER_SCORES: {
+    /** Weight for static segments */
+    readonly STATIC_SEGMENT_WEIGHT: 3;
+    /** Multiplier for segment score calculation */
+    readonly SCORE_MULTIPLIER: 100;
+};
+/**
+ * Loading UI styling constants
+ */
+export declare const LOADING_UI: {
+    /** Spinner size (px) */
+    readonly SPINNER_SIZE: 36;
+    /** Spinner border width (px) */
+    readonly SPINNER_BORDER: 4;
+    /** Loading overlay z-index */
+    readonly OVERLAY_Z_INDEX: 1000;
+    /** Spinner animation duration (degrees) */
+    readonly SPINNER_ROTATION: 360;
+};
+/**
+ * General router configuration
+ */
+export declare const ROUTER_CONFIG: {
+    /** Default navigation transaction ID for initial mount */
+    readonly INITIAL_NAV_ID: 0;
+};
+/**
+ * Route module types for cache keys and invalidation
+ */
+export declare const ROUTE_MODULE_TYPES: readonly ["page", "layout", "loading", "error", "loader", "config"];
+export type RouteModuleType = (typeof ROUTE_MODULE_TYPES)[number];
+//# sourceMappingURL=constants.d.ts.map

package/dist/router/core/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/router/core/constants.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF;;;;;GAKG;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB;IAC5B,kDAAkD;;IAGlD,kEAAkE;;IAGlE,mEAAmE;;IAGnE,gDAAgD;;IAGhD,kDAAkD;;CAE1C,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,qBAAqB;IAChC,uDAAuD;;IAGvD,6CAA6C;;IAG7C,wDAAwD;;IAGxD,mDAAmD;;IAGnD,oDAAoD;;IAGpD,mDAAmD;;CAE3C,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,eAAe;IAC1B,yDAAyD;;IAGzD,iCAAiC;;CAEzB,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,cAAc;IACzB,iCAAiC;;IAGjC,+CAA+C;;CAEvC,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,UAAU;IACrB,wBAAwB;;IAGxB,gCAAgC;;IAGhC,8BAA8B;;IAG9B,2CAA2C;;CAEnC,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,aAAa;IACxB,0DAA0D;;CAElD,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,kBAAkB,qEAOrB,CAAC;AACX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/router/core/constants.js

@@ -0,0 +1,95 @@
+/** @codex
+{
+  "id": "pithy.router.constants",
+  "title": "Router Configuration Constants",
+  "category": "config"
+}
+*/
+/**
+ * Router package constants
+ *
+ * Centralized location for all magic numbers and configuration defaults
+ * used throughout the router package.
+ */
+/**
+ * Prefetch configuration defaults
+ */
+export const PREFETCH_DEFAULTS = {
+    /** Default hover delay before prefetching (ms) */
+    HOVER_DELAY: 150,
+    /** Default cache TTL for prefetched resources (ms) - 5 minutes */
+    CACHE_TTL: 300000,
+    /** Intent velocity threshold for mouse movement (pixels/second) */
+    INTENT_VELOCITY_THRESHOLD: 100,
+    /** Number of samples for direction detection */
+    INTENT_DIRECTION_SAMPLES: 3,
+    /** Maximum cache size for prefetched resources */
+    MAX_CACHE_SIZE: 100,
+};
+/**
+ * Scroll and focus management defaults
+ */
+export const SCROLL_FOCUS_DEFAULTS = {
+    /** Delay before attempting to scroll to anchor (ms) */
+    ANCHOR_DELAY: 100,
+    /** Number of retries for anchor scrolling */
+    ANCHOR_RETRIES: 3,
+    /** Maximum age for scroll positions (ms) - 5 minutes */
+    SCROLL_POSITION_MAX_AGE: 5 * 60 * 1000,
+    /** Clean old positions interval (ms) - 1 second */
+    CLEAN_POSITIONS_INTERVAL: 1000,
+    /** Default max age for cleanup (ms) - 30 minutes */
+    DEFAULT_CLEANUP_MAX_AGE: 30 * 60 * 1000,
+    /** Announcer element offset (for accessibility) */
+    ANNOUNCER_OFFSET: -10000,
+};
+/**
+ * Loader configuration defaults
+ */
+export const LOADER_DEFAULTS = {
+    /** Default cache TTL for loader data (ms) - 5 minutes */
+    CACHE_TTL: 300000,
+    /** Default maximum cache size */
+    MAX_CACHE_SIZE: 100,
+};
+/**
+ * Route matcher scoring weights
+ */
+export const MATCHER_SCORES = {
+    /** Weight for static segments */
+    STATIC_SEGMENT_WEIGHT: 3,
+    /** Multiplier for segment score calculation */
+    SCORE_MULTIPLIER: 100,
+};
+/**
+ * Loading UI styling constants
+ */
+export const LOADING_UI = {
+    /** Spinner size (px) */
+    SPINNER_SIZE: 36,
+    /** Spinner border width (px) */
+    SPINNER_BORDER: 4,
+    /** Loading overlay z-index */
+    OVERLAY_Z_INDEX: 1000,
+    /** Spinner animation duration (degrees) */
+    SPINNER_ROTATION: 360,
+};
+/**
+ * General router configuration
+ */
+export const ROUTER_CONFIG = {
+    /** Default navigation transaction ID for initial mount */
+    INITIAL_NAV_ID: 0,
+};
+/**
+ * Route module types for cache keys and invalidation
+ */
+export const ROUTE_MODULE_TYPES = [
+    'page',
+    'layout',
+    'loading',
+    'error',
+    'loader',
+    'config',
+];
+//# sourceMappingURL=constants.js.map

package/dist/router/core/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/router/core/constants.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,kDAAkD;IAClD,WAAW,EAAE,GAAG;IAEhB,kEAAkE;IAClE,SAAS,EAAE,MAAM;IAEjB,mEAAmE;IACnE,yBAAyB,EAAE,GAAG;IAE9B,gDAAgD;IAChD,wBAAwB,EAAE,CAAC;IAE3B,kDAAkD;IAClD,cAAc,EAAE,GAAG;CACX,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,uDAAuD;IACvD,YAAY,EAAE,GAAG;IAEjB,6CAA6C;IAC7C,cAAc,EAAE,CAAC;IAEjB,wDAAwD;IACxD,uBAAuB,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI;IAEtC,mDAAmD;IACnD,wBAAwB,EAAE,IAAI;IAE9B,oDAAoD;IACpD,uBAAuB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI;IAEvC,mDAAmD;IACnD,gBAAgB,EAAE,CAAC,KAAK;CAChB,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,yDAAyD;IACzD,SAAS,EAAE,MAAM;IAEjB,iCAAiC;IACjC,cAAc,EAAE,GAAG;CACX,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,iCAAiC;IACjC,qBAAqB,EAAE,CAAC;IAExB,+CAA+C;IAC/C,gBAAgB,EAAE,GAAG;CACb,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,wBAAwB;IACxB,YAAY,EAAE,EAAE;IAEhB,gCAAgC;IAChC,cAAc,EAAE,CAAC;IAEjB,8BAA8B;IAC9B,eAAe,EAAE,IAAI;IAErB,2CAA2C;IAC3C,gBAAgB,EAAE,GAAG;CACb,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,0DAA0D;IAC1D,cAAc,EAAE,CAAC;CACT,CAAC;AAEX;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,MAAM;IACN,QAAQ;IACR,SAAS;IACT,OAAO;IACP,QAAQ;IACR,QAAQ;CACA,CAAC"}

package/dist/router/core/history.d.ts

@@ -0,0 +1,54 @@
+/** @codex
+{
+  "id": "pithy.router.core.history",
+  "title": "Browser History Interaction",
+  "category": "runtime"
+}
+*/
+import type { HistoryAdapter } from './types';
+/** @codexApi {"parent":"pithy.router.core.history","name":"HistoryManager","stability":"stable","signature":"class HistoryManager","description":"Centralizes browser history state, scroll restoration, and popstate handling"} */
+/**
+ * HistoryManager handles all browser history API interactions
+ * Centralizes history state management, scroll restoration, and popstate handling
+ * Uses HistoryAdapter for environment-agnostic history operations (enables SSR)
+ */
+export declare class HistoryManager {
+    private lastCommittedUrl;
+    private adapter;
+    constructor(adapter: HistoryAdapter);
+    /**
+     * Get the last committed URL (for snap-back on guard denial)
+     * @returns Last committed URL string
+     */
+    getLastCommittedUrl(): string;
+    /**
+     * Push a new history entry
+     * @param state - State object to associate with the entry
+     * @param url - URL for the new entry
+     */
+    push(state: unknown, url: string): void;
+    /**
+     * Replace the current history entry
+     * @param state - State object to associate with the entry
+     * @param url - URL for the replacement entry
+     */
+    replace(state: unknown, url: string): void;
+    /**
+     * Snap back to the last committed URL (used when guards block navigation)
+     */
+    snapBack(): void;
+    /**
+     * Go back in history (delegates to adapter)
+     */
+    back(): void;
+    /**
+     * Go forward in history (delegates to adapter)
+     */
+    forward(): void;
+    /**
+     * Save current scroll position to history.state before navigation
+     * This captures window scroll and any scrollable containers marked with [data-remember-scroll]
+     */
+    saveScrollPosition(): void;
+}
+//# sourceMappingURL=history.d.ts.map

package/dist/router/core/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../../src/router/core/history.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAGF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,oOAAoO;AACpO;;;;GAIG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,OAAO,CAAiB;gBAEpB,OAAO,EAAE,cAAc;IAMnC;;;OAGG;IACI,mBAAmB,IAAI,MAAM;IAIpC;;;;OAIG;IACI,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAK9C;;;;OAIG;IACI,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAKjD;;OAEG;IACI,QAAQ,IAAI,IAAI;IAQvB;;OAEG;IACI,IAAI,IAAI,IAAI;IAInB;;OAEG;IACI,OAAO,IAAI,IAAI;IAItB;;;OAGG;IACI,kBAAkB,IAAI,IAAI;CAoBlC"}

package/dist/router/core/history.js

@@ -0,0 +1,89 @@
+/** @codex
+{
+  "id": "pithy.router.core.history",
+  "title": "Browser History Interaction",
+  "category": "runtime"
+}
+*/
+import { selectorFor } from './utils';
+/** @codexApi {"parent":"pithy.router.core.history","name":"HistoryManager","stability":"stable","signature":"class HistoryManager","description":"Centralizes browser history state, scroll restoration, and popstate handling"} */
+/**
+ * HistoryManager handles all browser history API interactions
+ * Centralizes history state management, scroll restoration, and popstate handling
+ * Uses HistoryAdapter for environment-agnostic history operations (enables SSR)
+ */
+export class HistoryManager {
+    constructor(adapter) {
+        this.adapter = adapter;
+        const location = adapter.getLocation();
+        this.lastCommittedUrl = location.path + location.search + location.hash;
+    }
+    /**
+     * Get the last committed URL (for snap-back on guard denial)
+     * @returns Last committed URL string
+     */
+    getLastCommittedUrl() {
+        return this.lastCommittedUrl;
+    }
+    /**
+     * Push a new history entry
+     * @param state - State object to associate with the entry
+     * @param url - URL for the new entry
+     */
+    push(state, url) {
+        this.adapter.push(url, state);
+        this.lastCommittedUrl = url;
+    }
+    /**
+     * Replace the current history entry
+     * @param state - State object to associate with the entry
+     * @param url - URL for the replacement entry
+     */
+    replace(state, url) {
+        this.adapter.replace(url, state);
+        this.lastCommittedUrl = url;
+    }
+    /**
+     * Snap back to the last committed URL (used when guards block navigation)
+     */
+    snapBack() {
+        // Get current state from browser (adapter-agnostic way would require extending HistoryAdapter)
+        // For now, assume browser environment in snapBack
+        if (typeof window !== 'undefined' && window.history) {
+            this.adapter.replace(this.lastCommittedUrl, window.history.state);
+        }
+    }
+    /**
+     * Go back in history (delegates to adapter)
+     */
+    back() {
+        this.adapter.back();
+    }
+    /**
+     * Go forward in history (delegates to adapter)
+     */
+    forward() {
+        this.adapter.forward();
+    }
+    /**
+     * Save current scroll position to history.state before navigation
+     * This captures window scroll and any scrollable containers marked with [data-remember-scroll]
+     */
+    saveScrollPosition() {
+        // Only save scroll in browser environment
+        if (typeof window === 'undefined' || typeof document === 'undefined') {
+            return;
+        }
+        const scroll = {
+            window: { x: window.scrollX, y: window.scrollY },
+            containers: Array.from(document.querySelectorAll('[data-remember-scroll]')).map(el => ({
+                sel: selectorFor(el),
+                x: el.scrollLeft,
+                y: el.scrollTop,
+            })),
+            ts: Date.now(),
+        };
+        this.adapter.saveScrollPosition(scroll);
+    }
+}
+//# sourceMappingURL=history.js.map

package/dist/router/core/history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.js","sourceRoot":"","sources":["../../../src/router/core/history.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGtC,oOAAoO;AACpO;;;;GAIG;AACH,MAAM,OAAO,cAAc;IAIzB,YAAY,OAAuB;QACjC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,MAAM,QAAQ,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;QACvC,IAAI,CAAC,gBAAgB,GAAG,QAAQ,CAAC,IAAI,GAAG,QAAQ,CAAC,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC;IAC1E,CAAC;IAED;;;OAGG;IACI,mBAAmB;QACxB,OAAO,IAAI,CAAC,gBAAgB,CAAC;IAC/B,CAAC;IAED;;;;OAIG;IACI,IAAI,CAAC,KAAc,EAAE,GAAW;QACrC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC9B,IAAI,CAAC,gBAAgB,GAAG,GAAG,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACI,OAAO,CAAC,KAAc,EAAE,GAAW;QACxC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACjC,IAAI,CAAC,gBAAgB,GAAG,GAAG,CAAC;IAC9B,CAAC;IAED;;OAEG;IACI,QAAQ;QACb,+FAA+F;QAC/F,kDAAkD;QAClD,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACpD,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACpE,CAAC;IACH,CAAC;IAED;;OAEG;IACI,IAAI;QACT,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IACtB,CAAC;IAED;;OAEG;IACI,OAAO;QACZ,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IACzB,CAAC;IAED;;;OAGG;IACI,kBAAkB;QACvB,0CAA0C;QAC1C,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE,CAAC;YACrE,OAAO;QACT,CAAC;QAED,MAAM,MAAM,GAAG;YACb,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,EAAE,MAAM,CAAC,OAAO,EAAE;YAChD,UAAU,EAAE,KAAK,CAAC,IAAI,CACpB,QAAQ,CAAC,gBAAgB,CAAc,wBAAwB,CAAC,CACjE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;gBACX,GAAG,EAAE,WAAW,CAAC,EAAE,CAAC;gBACpB,CAAC,EAAE,EAAE,CAAC,UAAU;gBAChB,CAAC,EAAE,EAAE,CAAC,SAAS;aAChB,CAAC,CAAC;YACH,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE;SACf,CAAC;QAEF,IAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC1C,CAAC;CACF"}

package/dist/router/core/matcher.d.ts

@@ -0,0 +1,43 @@
+/** @codex
+{
+  "id": "pithy.router.matcher",
+  "title": "Route Path Matching Engine",
+  "category": "runtime"
+}
+*/
+import { RouteMatch, RouteParams, RouteSegment, RouterConfig, TrailingSlashPolicy } from './types';
+/** @codexApi {"parent":"pithy.router.matcher","name":"parseRoutePattern","stability":"stable","signature":"(pattern: string) => RouteSegment[]","description":"Parse a route pattern into typed segments (static, dynamic, catch-all, group)"} */
+/**
+ * Parse a route pattern into segments with type information
+ * Handles static, dynamic [id], catch-all [...slug], and groups (group)
+ */
+export declare function parseRoutePattern(pattern: string): RouteSegment[];
+/** @codexApi {"parent":"pithy.router.matcher","name":"calculateRouteScore","stability":"stable","signature":"(segments: RouteSegment[]) => number","description":"Calculate route precedence score for conflict resolution"} */
+/**
+ * Calculate route precedence score for conflict resolution
+ * Higher score = higher precedence
+ * Rules: Static > Dynamic > CatchAll, Longer > Shorter
+ */
+export declare function calculateRouteScore(segments: RouteSegment[]): number;
+/** @codexApi {"parent":"pithy.router.matcher","name":"normalizePath","stability":"stable","signature":"(path: string, policy?: TrailingSlashPolicy) => string","description":"Normalize path according to trailing slash policy"} */
+/**
+ * Normalize path according to trailing slash policy
+ */
+export declare function normalizePath(path: string, policy?: TrailingSlashPolicy): string;
+/** @codexApi {"parent":"pithy.router.matcher","name":"extractParams","stability":"stable","signature":"(pathSegments: string[], routeSegments: RouteSegment[], decodeParams?: boolean) => RouteParams","description":"Extract parameters from a matched path using route segments"} */
+/**
+ * Extract parameters from a matched path using route segments
+ */
+export declare function extractParams(pathSegments: string[], routeSegments: RouteSegment[], decodeParams?: boolean): RouteParams;
+/** @codexApi {"parent":"pithy.router.matcher","name":"matchRoute","stability":"stable","signature":"(path: string, pattern: string, config?: RouterConfig) => RouteMatch | null","description":"Check if a path matches a route pattern and return match details"} */
+/**
+ * Check if a path matches a route pattern
+ */
+export declare function matchRoute(path: string, pattern: string, config?: RouterConfig): RouteMatch | null;
+/** @codexApi {"parent":"pithy.router.matcher","name":"findBestMatch","stability":"stable","signature":"(path: string, patterns: string[], config?: RouterConfig) => RouteMatch | null","description":"Find the best matching route by highest precedence score"} */
+/**
+ * Find the best matching route from a list of patterns
+ * Returns the route with the highest precedence score
+ */
+export declare function findBestMatch(path: string, patterns: string[], config?: RouterConfig): RouteMatch | null;
+//# sourceMappingURL=matcher.d.ts.map

package/dist/router/core/matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matcher.d.ts","sourceRoot":"","sources":["../../../src/router/core/matcher.ts"],"names":[],"mappings":"AAAA;;;;;;EAME;AAEF,OAAO,EACL,UAAU,EACV,WAAW,EACX,YAAY,EAEZ,YAAY,EACZ,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAGjB,kPAAkP;AAClP;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,EAAE,CAmEjE;AAED,gOAAgO;AAChO;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,MAAM,CAqBpE;AAED,qOAAqO;AACrO;;GAEG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,MAAM,GAAE,mBAA6B,GACpC,MAAM,CAeR;AAED,uRAAuR;AACvR;;GAEG;AACH,wBAAgB,aAAa,CAC3B,YAAY,EAAE,MAAM,EAAE,EACtB,aAAa,EAAE,YAAY,EAAE,EAC7B,YAAY,UAAO,GAClB,WAAW,CA4Cb;AAED,sQAAsQ;AACtQ;;GAEG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,YAAiB,GACxB,UAAU,GAAG,IAAI,CAgCnB;AA0CD,oQAAoQ;AACpQ;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAAE,EAClB,MAAM,GAAE,YAAiB,GACxB,UAAU,GAAG,IAAI,CAoBnB"}