@but212/atom-effect-jquery 0.31.0 → 0.32.0

package/dist/core/dom.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Iterates over a jQuery collection and executes a callback for each HTMLElement.
+ *
+ * Reason: jQuery collections can contain non-element nodes (e.g., text or
+ * comment nodes). This utility provides a safe, element-only iteration path
+ * required for establishing reactive bindings and event listeners.
+ *
+ * @param jq - The jQuery collection to iterate over.
+ * @param fn - The callback function to execute for each element.
+ * @returns The original jQuery collection for chaining.
+ * @internal
+ */
+export declare function atomEachElement(jq: JQuery, fn: (el: HTMLElement) => void): JQuery;
+/**
+ * Normalizes a binding source into a tuple containing the source and optional configuration.
+ *
+ * Logic: This utility uses heuristics to determine if an input represents a
+ * configuration tuple (e.g., `[source, options]`) or a simple array-based
+ * data value. This is used in unified bindings to support overloaded signatures.
+ *
+ * @param val - The value or tuple to unpack.
+ * @returns A tuple where the first element is the source and the second is optional config.
+ * @internal
+ */
+export declare function unpack<T, O>(val: T | [T, O]): [T, O?];
+//# sourceMappingURL=dom.d.ts.map

package/dist/core/dom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../src/core/dom.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,CAQjF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAgBrD"}

package/dist/core/effect-factory.d.ts

@@ -0,0 +1,34 @@
+import { AsyncReactiveValue } from '../types';
+/**
+ * Enumeration of binding types for debugging and performance tracking.
+ * @internal
+ */
+export type BindingDebugType = 'text' | 'html' | 'show' | 'hide' | 'checked' | `class.${string & {}}` | `css.${string & {}}` | `attr.${string & {}}` | `prop.${string & {}}` | (string & {});
+/**
+ * Establishes a reactive effect between a single source and a DOM element.
+ *
+ * Lifecycle: The created effect is automatically registered with the global
+ * `registry` and linked to the target element.
+ *
+ * @param el - The target DOM element.
+ * @param source - The reactive atom, function, or static value.
+ * @param updater - The function that applies the value to the DOM.
+ * @param debugType - Metadata for debugging.
+ * @internal
+ */
+export declare function registerReactiveEffect<T>(el: Element, source: AsyncReactiveValue<T>, updater: (value: T) => void, debugType: BindingDebugType): void;
+/**
+ * Establishes a reactive effect between a map of sources and a DOM element.
+ *
+ * Optimization: Single-pass Collection
+ * Replaces multiple array methods (map/filter/forEach) with a single for-loop
+ * to reduce memory allocation and GC pressure on every state change.
+ *
+ * @param el - The target DOM element.
+ * @param sourceMap - A record of property keys and reactive values.
+ * @param updater - The function that applies the entire map to the DOM.
+ * @param debugType - Metadata for debugging.
+ * @internal
+ */
+export declare function registerMapEffect<T>(el: Element, sourceMap: Record<string, AsyncReactiveValue<T>>, updater: (map: Record<string, T>) => void, debugType: BindingDebugType): void;
+//# sourceMappingURL=effect-factory.d.ts.map

package/dist/core/effect-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect-factory.d.ts","sourceRoot":"","sources":["../../src/core/effect-factory.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAIlD;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,MAAM,GACN,MAAM,GACN,MAAM,GACN,SAAS,GACT,SAAS,MAAM,GAAG,EAAE,EAAE,GACtB,OAAO,MAAM,GAAG,EAAE,EAAE,GACpB,QAAQ,MAAM,GAAG,EAAE,EAAE,GACrB,QAAQ,MAAM,GAAG,EAAE,EAAE,GACrB,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AA4ElB;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,EACtC,EAAE,EAAE,OAAO,EACX,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC7B,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,EAC3B,SAAS,EAAE,gBAAgB,GAC1B,IAAI,CAsBN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,EAAE,EAAE,OAAO,EACX,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC,EAChD,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,IAAI,EACzC,SAAS,EAAE,gBAAgB,GAC1B,IAAI,CA4DN"}

package/dist/core/jquery-patch.d.ts

@@ -0,0 +1,12 @@
+import { PatchOptions } from '../types';
+/**
+ * Enables global patches for jQuery to integrate reactive state management.
+ * @internal
+ */
+export declare function enablejQueryOverrides(options?: PatchOptions): void;
+/**
+ * Restores jQuery prototype methods to their original native state.
+ * @internal
+ */
+export declare function disablejQueryOverrides(): void;
+//# sourceMappingURL=jquery-patch.d.ts.map

package/dist/core/jquery-patch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jquery-patch.d.ts","sourceRoot":"","sources":["../../src/core/jquery-patch.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAqH5C;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,YAAiB,GAAG,IAAI,CAqEtE;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAW7C"}

package/dist/core/namespace.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Returns a promise that resolves after the next reactive update cycle has completed.
+ *
+ * When to use:
+ * - To perform manual DOM measurements after reactive changes have been applied.
+ * - To coordinate external library initializations that depend on the current DOM state.
+ *
+ * @returns A promise that resolves when the DOM has been synchronized with the latest state.
+ */
+export declare const nextTick: () => Promise<void>;
+//# sourceMappingURL=namespace.d.ts.map

package/dist/core/namespace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespace.d.ts","sourceRoot":"","sources":["../../src/core/namespace.ts"],"names":[],"mappings":"AAkBA;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ,QAAO,OAAO,CAAC,IAAI,CAAiB,CAAC"}

package/dist/core/navigation.d.ts

@@ -0,0 +1,172 @@
+import { Option, Result } from '@but212/atom-effect-utils';
+/** @internal */
+export type NavigationType = 'init' | 'push' | 'replace' | 'pop';
+/** @internal */
+export interface ContentState {
+    html: string;
+    title: string | null;
+    attributes?: Record<string, string>;
+    redirectUrl?: string | null | undefined;
+    meta?: Record<string, string>;
+}
+/** @internal */
+export declare const normalizePath: (path: string) => string;
+/** @internal */
+export declare const splitPath: (path: string) => {
+    route: string;
+    query: Option<string>;
+};
+/** @internal */
+export declare const parseQuery: (raw: string) => Record<string, string>;
+/** @internal */
+export declare const getAbsoluteUrl: (url: string, base: string) => Result<URL, Error>;
+/**
+ * SEO Metadata Schema
+ * Defines the mapping between internal state keys and physical HTML tags.
+ */
+export declare const META_SCHEMA: readonly [{
+    readonly selector: "meta[name=\"description\"]";
+    readonly tag: "meta";
+    readonly attr: "content";
+    readonly key: "description";
+    readonly staticAttrs: {
+        readonly name: "description";
+    };
+}, {
+    readonly selector: "meta[name=\"keywords\"]";
+    readonly tag: "meta";
+    readonly attr: "content";
+    readonly key: "keywords";
+    readonly staticAttrs: {
+        readonly name: "keywords";
+    };
+}, {
+    readonly selector: "link[rel=\"canonical\"]";
+    readonly tag: "link";
+    readonly attr: "href";
+    readonly key: "canonical";
+    readonly staticAttrs: {
+        readonly rel: "canonical";
+    };
+}];
+/**
+ * Synchronizes document head metadata with the provided state.
+ *
+ * Why: Ensures SEO-critical tags stay in sync during SPA transitions
+ * without a full page reload.
+ *
+ * Side Effect: Creates missing tags in `<head>` if defined in `meta` record.
+ */
+export declare function syncMetaData(win: Window, meta?: Record<string, string>): void;
+/**
+ * Updates element attributes while preserving internal tracking IDs.
+ *
+ * Constraint: Attributes in `ATTR_PRESERVE` (like `id`) are never removed,
+ * even if missing from the next state, to prevent breaking DOM references.
+ */
+export declare function updateAttributes(el: HTMLElement, next: Record<string, string>): void;
+/**
+ * Manages viewport scrolling after a navigation event.
+ * Priority: Hash element > Window top (if fallback enabled).
+ */
+export declare function performScroll(win: Window, hash?: string, fallbackToTop?: boolean): void;
+/**
+ * Filters click events to determine if they should trigger client-side navigation.
+ *
+ * Why: Ignores modified clicks (Ctrl+Click) or right-clicks to preserve native
+ * browser features (e.g., "Open in new tab").
+ */
+export declare function isNavigationClick(e: MouseEvent | JQuery.TriggeredEvent): boolean;
+/**
+ * Determines if a link click should be intercepted by the SPA router.
+ *
+ * Example:
+ * ```ts
+ * $(document).on('click', 'a', (e) => {
+ *   if (isInterceptee(e.currentTarget)) {
+ *     e.preventDefault();
+ *     navigate(e.currentTarget.href);
+ *   }
+ * });
+ * ```
+ */
+export declare function isInterceptee(el: Element, win?: Window): boolean;
+/** @internal */
+export declare function getUrlParts(url: string, base: string): {
+    pathAndSearch: string;
+    hash: string;
+};
+/**
+ * Calculates whether the viewport should scroll after a navigation transition.
+ *
+ * Why: Prevents jarring scroll jumps during 'Pop' (Back/Forward) events while
+ * ensuring 'Push' events start at the top of the new content.
+ */
+export declare function getScrollDecision(params: {
+    hash: string;
+    type: NavigationType;
+    isNewTarget: boolean;
+    prevHash: string;
+    scrollToTop: boolean;
+}): {
+    shouldScroll: boolean;
+    resetScroll: boolean;
+};
+/** @internal */
+export declare function extractMetaData(doc: Document | Element): Record<string, string>;
+/** @internal Extracts path relative to a base for routing logic. */
+export declare function resolveAnchorPath(el: Element, base?: string): string;
+/**
+ * Parses raw HTML strings into a structured `ContentState`.
+ *
+ * Why: Allows the router to perform "Fragment Extraction" — extracting
+ * only specific container content and page metadata from a full server response.
+ */
+export declare function extractContent(params: {
+    html: string;
+    selector?: string | undefined;
+    redirectUrl?: string | null | undefined;
+}): ContentState;
+/** @internal */
+export declare function updateActiveState(params: {
+    el: Element;
+    active: boolean;
+    activeClass: string;
+}): void;
+/** @internal SPA Link Recognition Specification */
+export declare const NAV_SPEC: {
+    readonly selectors: "a, [data-route]";
+    readonly attributes: readonly ["href", "data-route", "xlink:href"];
+};
+/** @internal */
+export type NavFeatureType = 'nav' | 'router';
+/**
+ * Coordination layer to prevent feature collisions.
+ *
+ * Why: Prevents race conditions when both `atomNav` and `$.route` are applied
+ * to the same DOM element. It also aggregates 'Leave' guards for the entire tree.
+ *
+ * @internal
+ */
+declare class NavigationCoordinator {
+    private managers;
+    /**
+     * Registers a navigation manager.
+     * Warning: Throws a console warning if a target is double-managed by
+     * different navigation features.
+     */
+    register(target: Element, type: NavFeatureType, canLeave?: () => boolean): void;
+    /**
+     * Checks if navigation is allowed by scanning all registered guards
+     * within the container.
+     */
+    canLeaveWithin(container: Element): boolean;
+    /** @internal */
+    isNestedIn(el: Element, type: NavFeatureType): boolean;
+    /** @internal */
+    getManagerType(target: Element): NavFeatureType | undefined;
+}
+/** Global singleton for managing cross-component navigation lifecycle. */
+export declare const navCoordinator: NavigationCoordinator;
+export {};
+//# sourceMappingURL=navigation.d.ts.map

package/dist/core/navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/core/navigation.ts"],"names":[],"mappings":"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"}

package/dist/core/registry.d.ts

@@ -0,0 +1,189 @@
+import { SlotBuffer } from '@but212/atom-effect-utils';
+import { EffectObject } from '../types';
+/**
+ * Configures whether the automated MutationObserver cleanup system is allowed to run.
+ *
+ * Logic: This provides explicit control over the global 'safety-net' observer,
+ * allowing it to be disabled in environments or scenarios where manual
+ * lifecycle management is strictly enforced.
+ *
+ * @param allowed - True to allow auto-cleanup, false to disable it.
+ * @internal
+ */
+export declare function setAutoCleanupAllowed(allowed: boolean): void;
+/**
+ * Represents the lifecycle metadata for a bound element.
+ * @internal
+ */
+export interface BindingRecord {
+    /**
+     * A collection of individual cleanup tasks (e.g., effect disposals).
+     * Optimization: Uses SlotBuffer to minimize heap allocations for small
+     * collections (1-4 items), which represents the vast majority of use cases.
+     */
+    tasks?: SlotBuffer<() => void>;
+    /** An optional component-level teardown function. */
+    teardown?: (() => void) | undefined;
+}
+/**
+ * The central registry for managing reactive resources and element lifecycles.
+ *
+ * Logic: Safety & Memory Management
+ * - WeakMap Storage: Binding records are stored in `WeakMap` instances to avoid
+ *   holding strong references to DOM elements. This allows the garbage collector
+ *   to reclaim memory even if elements are not explicitly unmounted.
+ * - Flag System: `WeakSet` is used for `keep` and `ignored` states to ensure that
+ *   metadata does not leak for nodes that are removed without a cleanup call.
+ * - Performance: The registry uses CSS markers (`_aes-bound`, `_aes-has-shadow`)
+ *   to perform high-speed scoped queries (`querySelectorAll`) during tree
+ *   disposal, avoiding expensive full-tree traversals.
+ *
+ * @internal
+ */
+declare class BindingRegistry {
+    private records;
+    private kept;
+    private ignored;
+    private shadows;
+    private autoCleanupScheduled;
+    /**
+     * Marks a node to preserve its reactive resources even if detached from the DOM.
+     * (e.g., used by jQuery's `.detach()` method).
+     */
+    keep(node: Node): void;
+    /** Determines if a node is marked for resource preservation. */
+    isKept(node: Node): boolean;
+    /**
+     * Marks a node to be ignored by the next automated cleanup cycle.
+     * This prevents redundant cleanup calls during complex DOM manipulations.
+     */
+    markIgnored(node: Node): void;
+    /** Determines if a node is currently marked to be ignored. */
+    isIgnored(node: Node): boolean;
+    /**
+     * Removes the 'ignored' flag, re-enabling standard cleanup logic for the node.
+     * @internal
+     */
+    unmarkIgnored(node: Node): void;
+    /** @internal */
+    isAutoCleanupScheduled(): boolean;
+    /** @internal */
+    setAutoCleanupScheduled(scheduled: boolean): void;
+    /**
+     * Performs a move-aware cleanup of a node and its descendants.
+     *
+     * Logic: Deferring the cleanup to a microtask allows elements to be
+     * disconnected and then immediately reconnected (moved) without
+     * losing their reactive state.
+     *
+     * @param node - The node to tentatively clean up.
+     */
+    deferCleanup(node: Node): void;
+    /**
+     * Registers a ShadowRoot to a host element for AEJ lifecycle tracking.
+     *
+     * @param host - The host element.
+     * @param sr - The ShadowRoot (can be 'open' or 'closed').
+     * @internal
+     */
+    registerShadow(host: Element, sr: ShadowRoot): void;
+    /**
+     * Safely adds a CSS marker to an element, deferring if it's currently being constructed.
+     */
+    private safeMark;
+    /**
+     * Marks a host element to indicate it possesses a managed ShadowRoot.
+     *
+     * Optimization: This adds a CSS marker used by `cleanupDescendants` to
+     * locate isolated Shadow DOM trees efficiently without full-tree traversal.
+     *
+     * @param host - The host element to mark.
+     * @internal
+     */
+    markHost(host: Element): void;
+    /**
+     * Retrieves the ShadowRoot for a host element, including tracked 'closed' roots.
+     * @internal
+     */
+    getShadow(host: Element): ShadowRoot | null;
+    /**
+     * Retrieves or initializes the binding record for a specific element.
+     *
+     * Logic: The auto-cleanup MutationObserver is lazily initialized when
+     * the first reactive binding is registered in the document.
+     */
+    private getOrCreateRecord;
+    /** Internal helper to append a cleanup task to an element's record. */
+    private addCleanup;
+    /**
+     * Registers a reactive effect to be tracked and disposed with the element.
+     *
+     * Constraint: Effects must be registered to ensure synchronous disposal
+     * when the host element is destroyed or unmounted.
+     *
+     * @param element - The host element.
+     * @param effect - The reactive effect object.
+     */
+    trackEffect(element: Element, effect: EffectObject): void;
+    /** Registers a generic cleanup function to be executed with the element. @internal */
+    onCleanup(element: Element, cleanupFunction: () => void): void;
+    /** Assigns a component-level teardown function to an element. @internal */
+    setTeardown(element: Element, teardownFunction: (() => void) | undefined): void;
+    /** Determines if an element has any active bindings. */
+    hasBind(element: Element): boolean;
+    /**
+     * Disposes of all reactive resources associated with a single node.
+     *
+     * @param node - The node to clean up.
+     */
+    cleanup(node: Node): void;
+    /**
+     * Efficiently cleans up reactive bindings within a DOM subtree.
+     *
+     * Logic: Snapshot Strategy
+     * This method uses `querySelectorAll` to obtain a static snapshot of bound
+     * elements before iteration begins. This ensures stability and prevents
+     * missed nodes if the DOM structure or classes are modified during cleanup.
+     *
+     * @param root - The root of the subtree or fragment to clean up.
+     */
+    cleanupDescendants(root: Element | DocumentFragment | ShadowRoot): void;
+    /**
+     * Performs a deep recursive cleanup of a node and all its internal subtrees (including Shadow DOM).
+     * @internal
+     */
+    cleanupTree(node: Node): void;
+}
+/** The global instance of the BindingRegistry. */
+export declare const registry: BindingRegistry;
+/**
+ * Initializes an automated MutationObserver safety net for a specific root.
+ *
+ * Logic: DOM Safety Net
+ * Standard browser operations (e.g., setting `innerHTML = ''`) bypass jQuery's
+ * internal hooks. This observer acts as a fallback, detecting removed nodes
+ * that were not processed by patched jQuery methods.
+ *
+ * @param root - The DOM element or fragment to monitor.
+ * @internal
+ */
+export declare function enableAutoCleanup(root: Element | ShadowRoot | DocumentFragment): void;
+/**
+ * Disconnects and destroys all registered auto-cleanup observers.
+ * @internal
+ */
+export declare function disableAutoCleanup(): void;
+/**
+ * Disconnects the auto-cleanup observer for a specific root node.
+ *
+ * Logic: Scoped Disposal
+ * This is used to release strong references held by the registry to specific
+ * boundaries (e.g., ShadowRoots) to prevent memory leaks when components
+ * are permanently removed.
+ *
+ * @param root - The specific node to stop monitoring.
+ * @internal
+ */
+export declare function disableAutoCleanupFor(root: Node): void;
+export {};
+//# sourceMappingURL=registry.d.ts.map

package/dist/core/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/core/registry.ts"],"names":[],"mappings":"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"}

package/dist/core/symbols.d.ts

@@ -0,0 +1,33 @@
+/** Symbol used to mark a DOM element as hydrated with reactive bindings. */
+export declare const HYDRATION_MARKER: unique symbol;
+/** Symbol used to indicate that an element has an active lifecycle MutationObserver attached. */
+export declare const CLEANUP_MARKER: unique symbol;
+/**
+ * Event name used for the bubbling context discovery mechanism.
+ *
+ * Logic: Dependency Injection
+ * Descendant elements dispatch this event to locate reactive providers
+ * higher in the DOM tree, including across Shadow DOM boundaries.
+ */
+export declare const CONTEXT_REQUEST = "aej:context-request";
+/**
+ * Payload structure for context discovery events.
+ * @internal
+ */
+export interface ContextRequestDetail {
+    /** The unique key or symbol of the requested context. */
+    key: string | symbol;
+    /** A callback executed by the provider to deliver the reactive value. */
+    callback: (atom: unknown) => void;
+}
+/**
+ * A unique symbol used to mark event handlers as already wrapped in a batch.
+ *
+ * Reason: Batch Coalescing
+ * This prevents redundant nested `batch()` calls when re-binding
+ * handlers or during multiple patch cycles, maintaining flat execution stacks.
+ *
+ * @internal
+ */
+export declare const INTERNAL_HANDLER: unique symbol;
+//# sourceMappingURL=symbols.d.ts.map

package/dist/core/symbols.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbols.d.ts","sourceRoot":"","sources":["../../src/core/symbols.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,eAA6B,CAAC;AAE3D,iGAAiG;AACjG,eAAO,MAAM,cAAc,eAAoC,CAAC;AAEhE;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,wBAAwB,CAAC;AAErD;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,yDAAyD;IACzD,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,yEAAyE;IACzE,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,eAAqC,CAAC"}

package/dist/features/fetch.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fetch.d.ts.map

package/dist/features/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../../src/features/fetch.ts"],"names":[],"mappings":""}

package/dist/features/nav.d.ts

@@ -0,0 +1,23 @@
+import { AtomNav, AtomNavOptions } from '../types';
+/**
+ * Initializes a reactive navigation manager for PJAX transitions.
+ *
+ * When to use:
+ * - Use when you want to enable "Single Page" behavior by fetching HTML
+ *   fragments from the server instead of performing full page reloads.
+ *
+ * @param options - Configuration for target containers, headers, and lifecycle hooks.
+ * @returns A navigation controller with reactive status monitoring and programmatic controls.
+ *
+ * @example
+ * ```typescript
+ * const nav = $.atomNav({
+ *   target: '#main-content',
+ *   onMount: ($el) => console.log('Content swapped!'),
+ * });
+ *
+ * nav.navigate('/dashboard');
+ * ```
+ */
+export declare function atomNav(options: AtomNavOptions): AtomNav;
+//# sourceMappingURL=nav.d.ts.map

package/dist/features/nav.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav.d.ts","sourceRoot":"","sources":["../../src/features/nav.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAgB,MAAM,SAAS,CAAC;AA0GrE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CA8UxD"}

package/dist/features/route/core.d.ts

@@ -0,0 +1,83 @@
+import { RouteDefinition, Router } from '../../types';
+import { MatchEntry, MatchResult } from './types';
+/**
+ * Factory for creating a URL adapter based on the application's routing strategy.
+ *
+ * When to use:
+ * - Use 'history' for clean URLs (requires server-side fallback to index.html).
+ * - Use 'hash' for legacy support or environments where the server is not configurable.
+ *
+ * @param mode - 'history' or 'hash'.
+ * @param basePath - Optional root segment (e.g., '/admin') if the app is not at domain root.
+ *
+ * @example
+ * const adapter = createAdapter('history', '/my-app');
+ */
+export declare const createAdapter: (mode: "history" | "hash", basePath?: string) => {
+    get: () => import('./types').URLState;
+    commit: (path: string) => import('./types').URLState;
+    revert: (prev: string) => void;
+    resolveAnchor: (el: Element) => string;
+    setupListener: (h: () => void) => () => void;
+};
+export interface RouteMatcher {
+    readonly exact: Map<string, MatchEntry>;
+    readonly dynamic: MatchEntry[];
+}
+/**
+ * Optimization: Separation of Concerns
+ * Partitions routes into 'exact' and 'dynamic' buckets to enable O(1) lookups for static paths.
+ */
+export declare function createRouteMatcher(routes: Record<string, RouteDefinition>): RouteMatcher;
+/**
+ * Attempts to match a path against the compiled routing table.
+ */
+export declare function matchRoute(matcher: RouteMatcher, path: string): MatchResult;
+/**
+ * Finds the canonical route pattern for a given resolved path.
+ */
+export declare function getRoutePattern(matcher: RouteMatcher, path: string): string;
+/**
+ * Resolves a raw path into a matched route definition with parameters and 404 fallback logic.
+ */
+export declare function resolveRoute(matcher: RouteMatcher, path: string, routes: Record<string, RouteDefinition>, notFoundPath?: string): {
+    def: RouteDefinition;
+    pattern: string;
+    params: Record<string, string>;
+    isMatch: boolean;
+} | {
+    def: RouteDefinition | undefined;
+    pattern: string;
+    params: {};
+    isMatch: boolean;
+};
+/**
+ * Logic: Navigation Pipeline Orchestration
+ * Coordinates the full transition sequence: matching, parameter merging, and guard execution.
+ *
+ * When to use:
+ * - Invoked internally by the router during navigation requests.
+ *
+ * Caution:
+ * - Guards (`onEnter`) must be side-effect free relative to the router's internal state.
+ */
+export declare function resolveNavigation(matcher: RouteMatcher, config: {
+    routes: Record<string, RouteDefinition>;
+    default: string;
+    notFound: string;
+}, path: string, query: Record<string, string>, router: Router): {
+    success: boolean;
+    path?: never;
+    query?: never;
+    params?: never;
+    def?: never;
+} | {
+    success: boolean;
+    path: string;
+    query: Record<string, string>;
+    params: {
+        [x: string]: string;
+    };
+    def: RouteDefinition | undefined;
+};
+//# sourceMappingURL=core.d.ts.map

package/dist/features/route/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../../src/features/route/core.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAc,MAAM,SAAS,CAAC;AA+DnE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,GAAG,MAAM,EAAE,WAAW,MAAM;;mBAKtD,MAAM;mBACN,MAAM;wBACD,OAAO;uBACR,MAAM,IAAI;CAEhC,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,UAAU,EAAE,CAAC;CAChC;AAiGD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,GAAG,YAAY,CAYxF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAQ3E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAK3E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACvC,YAAY,CAAC,EAAE,MAAM;;;;;;;;;;EAUtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EACtF,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC7B,MAAM,EAAE,MAAM;;;;;;;;;;;;;;EA8Bf"}