@tvuikit/navigation 0.1.0

package/dist/core/NavigationEngine.d.ts

@@ -0,0 +1,50 @@
+import type { Direction, FocusOptions, FocusGroupOptions, GroupId, NavigationEngineOptions, MoveOptions, NodeId, RegistryUpdate } from "./types.js";
+export declare class NavigationEngine extends EventTarget {
+    private readonly registry;
+    private readonly index;
+    private readonly maxRings;
+    private readonly fallbackToScan;
+    private focusedId;
+    private readonly scratchCandidates;
+    private readonly lastFocusedByGroup;
+    constructor(opts: NavigationEngineOptions);
+    get focused(): NodeId | null;
+    /**
+     * Syncs registry caches and updates the spatial index.
+     * For maximum perf, call this once per "frame/tick" from your app and keep
+     * engine operations `sync:false`.
+     */
+    sync(hint?: RegistryUpdate): void;
+    focus(id: NodeId, options?: FocusOptions): void;
+    blur(options?: {
+        signal?: AbortSignal;
+        reason?: "programmatic";
+    }): void;
+    /**
+     * Programmatically focuses a group.
+     * - If the group has focus history, restores to the last focused node in the group (when valid).
+     * - Otherwise focuses the first eligible node found in the registry with that group id.
+     */
+    focusGroup(groupId: GroupId, options?: FocusGroupOptions): void;
+    /**
+     * Clears stored focus history.
+     * If `groupId` is omitted, clears all groups.
+     */
+    clearGroupHistory(groupId?: GroupId): void;
+    /**
+     * Alias for `clearGroupHistory()` (programmatic focus history reset).
+     */
+    resetGroupHistory(groupId?: GroupId): void;
+    move(direction: Direction, options?: MoveOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | AddEventListenerOptions): void;
+    removeEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | EventListenerOptions): void;
+    private upsertIndex;
+    private groupOf;
+    private recordGroupHistory;
+    private isEligible;
+    private isEligibleInGroup;
+    private redirectOnGroupEnter;
+    private pickNext;
+    private isBoundaryBlocked;
+}
+//# sourceMappingURL=NavigationEngine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"NavigationEngine.d.ts","sourceRoot":"","sources":["../../src/core/NavigationEngine.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,SAAS,EACT,YAAY,EACZ,iBAAiB,EACjB,OAAO,EACP,uBAAuB,EACvB,WAAW,EACX,MAAM,EAEN,cAAc,EAEf,MAAM,YAAY,CAAC;AAUpB,qBAAa,gBAAiB,SAAQ,WAAW;IAC/C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmB;IACzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAU;IAEzC,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAqB;IAEvD,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAA8B;gBAErD,IAAI,EAAE,uBAAuB;IAQzC,IAAI,OAAO,IAAI,MAAM,GAAG,IAAI,CAE3B;IAED;;;;OAIG;IACH,IAAI,CAAC,IAAI,CAAC,EAAE,cAAc,GAAG,IAAI;IAwBjC,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IAqC/C,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,MAAM,CAAC,EAAE,cAAc,CAAA;KAAE,GAAG,IAAI;IAkBvE;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,IAAI;IAmC/D;;;OAGG;IACH,iBAAiB,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI;IAQ1C;;OAEG;IACH,iBAAiB,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI;IAI1C,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI;IA4CvD,gBAAgB,CACd,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,kCAAkC,GAAG,IAAI,EACnD,OAAO,CAAC,EAAE,OAAO,GAAG,uBAAuB,GAC1C,IAAI;IAQP,mBAAmB,CACjB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,kCAAkC,GAAG,IAAI,EACnD,OAAO,CAAC,EAAE,OAAO,GAAG,oBAAoB,GACvC,IAAI;IASP,OAAO,CAAC,WAAW;IAMnB,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,oBAAoB;IAe5B,OAAO,CAAC,QAAQ;IAwEhB,OAAO,CAAC,iBAAiB;CAW1B"}

package/dist/core/NavigationStore.d.ts

@@ -0,0 +1,194 @@
+import type { Direction, DirectionBoundary, FocusOptions, FocusGroupOptions, GroupId, MoveOptions, NodeId, RegistryUpdate, SpatialRegistry } from "./types.js";
+import type { NavigationEventMap } from "./events.js";
+import { NavigationEngine } from "./NavigationEngine.js";
+import { type GenericRegistry, type GenericNodeConfig } from "../registries/genericRegistry.js";
+/**
+ * A source registry can be either a GenericRegistry or any SpatialRegistry.
+ * DomRegistry is a SpatialRegistry with additional DOM-specific methods.
+ */
+export type SourceRegistry = SpatialRegistry;
+/**
+ * Configuration for creating a NavigationStore.
+ */
+export type NavigationStoreOptions = {
+    /**
+     * Uniform grid cell size (world units). Tune per app scale.
+     * Default: 256
+     */
+    cellSize?: number;
+    /**
+     * How many nearby cells to expand when searching for candidates.
+     * Default: 4
+     */
+    maxRings?: number;
+    /**
+     * If the bounded index query returns zero candidates, optionally fall back to
+     * a single O(N) scan for correctness in sparse layouts.
+     * Default: true
+     */
+    fallbackToScan?: boolean;
+};
+/**
+ * Listener for store state changes.
+ * Called when focus changes or sources are added/removed.
+ */
+export type StoreListener = () => void;
+/**
+ * A unified navigation store that bundles the engine and a dynamic multi-source registry.
+ *
+ * Key features:
+ * - Single object to pass around (or import as module singleton)
+ * - Lazy source creation via `getSource(name)`
+ * - Works with `useSyncExternalStore` for React integration
+ * - Works across React reconcilers (no context dependency)
+ */
+export type NavigationStore = {
+    /** The underlying navigation engine */
+    readonly engine: NavigationEngine;
+    /** The combined registry (internal, prefer using store methods) */
+    readonly registry: SpatialRegistry;
+    /**
+     * Get or create a source registry by name.
+     * If the source doesn't exist, creates a new GenericRegistry.
+     *
+     * @example
+     * const pixiRegistry = store.getSource("pixi");
+     * pixiRegistry.register({ id: "tile-1", rect: { x: 0, y: 0, w: 100, h: 100 } });
+     */
+    getSource(name: string): GenericRegistry;
+    /**
+     * Get an existing source registry by name (without creating).
+     * Returns undefined if the source doesn't exist.
+     * Use this when you need to access a specific registry type (like DomRegistry).
+     */
+    getExistingSource(name: string): SourceRegistry | undefined;
+    /**
+     * Add a pre-existing registry as a source.
+     * Use this to add a DomRegistry or other custom registry.
+     *
+     * @example
+     * const domRegistry = createDomRegistry();
+     * store.addSource("dom", domRegistry);
+     */
+    addSource(name: string, registry: SourceRegistry): void;
+    /**
+     * Check if a source exists.
+     */
+    hasSource(name: string): boolean;
+    /**
+     * Remove a source and all its registered nodes.
+     * Returns true if the source existed.
+     */
+    removeSource(name: string): boolean;
+    /**
+     * List all source names.
+     */
+    sourceNames(): readonly string[];
+    /**
+     * Get the currently focused node ID (with source prefix).
+     */
+    readonly focused: NodeId | null;
+    /**
+     * Check if a specific node is focused.
+     * @param id The node ID (with source prefix, e.g., "pixi:tile-1")
+     */
+    isFocused(id: NodeId): boolean;
+    /**
+     * Focus a node by ID.
+     * @param id The node ID (with source prefix, e.g., "pixi:tile-1")
+     */
+    focus(id: NodeId, options?: FocusOptions): void;
+    /**
+     * Remove focus from the currently focused node.
+     */
+    blur(options?: {
+        signal?: AbortSignal;
+    }): void;
+    /**
+     * Focus a group (restore history or focus first node).
+     */
+    focusGroup(groupId: GroupId, options?: FocusGroupOptions): void;
+    /**
+     * Move focus in a direction.
+     */
+    move(direction: Direction, options?: MoveOptions): void;
+    /**
+     * Sync the registry (call once per frame for best perf).
+     */
+    sync(hint?: RegistryUpdate): void;
+    /**
+     * Register a node with a source.
+     * Convenience method that handles ID namespacing.
+     *
+     * @param source Source name (e.g., "pixi")
+     * @param config Node config with local ID
+     */
+    register(source: string, config: GenericNodeConfig): void;
+    /**
+     * Unregister a node.
+     * @param source Source name
+     * @param id Local node ID (without prefix)
+     */
+    unregister(source: string, id: NodeId): void;
+    /**
+     * Subscribe to store changes (focus changes, source changes).
+     * Compatible with React's useSyncExternalStore.
+     *
+     * @returns Unsubscribe function
+     */
+    subscribe(listener: StoreListener): () => void;
+    /**
+     * Get a snapshot of the current focus state.
+     * Compatible with React's useSyncExternalStore.
+     */
+    getSnapshot(): NodeId | null;
+    /**
+     * Add an event listener to the engine.
+     */
+    addEventListener<K extends keyof NavigationEventMap>(type: K, listener: (ev: NavigationEventMap[K]) => void, options?: boolean | AddEventListenerOptions): void;
+    /**
+     * Remove an event listener from the engine.
+     */
+    removeEventListener<K extends keyof NavigationEventMap>(type: K, listener: (ev: NavigationEventMap[K]) => void, options?: boolean | EventListenerOptions): void;
+    /**
+     * Set boundary configuration for a group.
+     */
+    setGroupBoundary(groupId: GroupId, boundary: DirectionBoundary): void;
+    /**
+     * Clear boundary configuration for a group.
+     */
+    clearGroupBoundary(groupId: GroupId): void;
+    /**
+     * Set whether a group should restore focus history on enter.
+     */
+    setGroupRestoreOnEnter(groupId: GroupId, enabled: boolean): void;
+    /**
+     * Clear restore-on-enter configuration for a group.
+     */
+    clearGroupRestoreOnEnter(groupId: GroupId): void;
+    /**
+     * Clear group focus history.
+     */
+    clearGroupHistory(groupId?: GroupId): void;
+};
+/**
+ * Create a new NavigationStore.
+ *
+ * @example
+ * // Create store
+ * const nav = createNavigationStore();
+ *
+ * // Use in React
+ * <NavigationProvider store={nav}>
+ *   <Focusable id="btn-1">Click</Focusable>
+ *   <PixiStage>
+ *     <PixiTile store={nav} id="tile-1" rect={rect} />
+ *   </PixiStage>
+ * </NavigationProvider>
+ *
+ * // Or import directly in any component
+ * import { nav } from "./nav";
+ * nav.focus("pixi:tile-1");
+ */
+export declare function createNavigationStore(options?: NavigationStoreOptions): NavigationStore;
+//# sourceMappingURL=NavigationStore.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"NavigationStore.d.ts","sourceRoot":"","sources":["../../src/core/NavigationStore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,OAAO,EACP,WAAW,EAEX,MAAM,EAEN,cAAc,EACd,eAAe,EAChB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAyB,KAAK,eAAe,EAAE,KAAK,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAEvH;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,eAAe,CAAC;AAE7C;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC;AAEvC;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAElC,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IAInC;;;;;;;OAOG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAAC;IAEzC;;;;OAIG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;IAE5D;;;;;;;OAOG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,IAAI,CAAC;IAExD;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAEjC;;;OAGG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAEpC;;OAEG;IACH,WAAW,IAAI,SAAS,MAAM,EAAE,CAAC;IAIjC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAEhC;;;OAGG;IACH,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAE/B;;;OAGG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAEhD;;OAEG;IACH,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,IAAI,CAAC;IAE/C;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAEhE;;OAEG;IACH,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAExD;;OAEG;IACH,IAAI,CAAC,IAAI,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IAIlC;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAE1D;;;;OAIG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAI7C;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,IAAI,CAAC;IAE/C;;;OAGG;IACH,WAAW,IAAI,MAAM,GAAG,IAAI,CAAC;IAI7B;;OAEG;IACH,gBAAgB,CAAC,CAAC,SAAS,MAAM,kBAAkB,EACjD,IAAI,EAAE,CAAC,EACP,QAAQ,EAAE,CAAC,EAAE,EAAE,kBAAkB,CAAC,CAAC,CAAC,KAAK,IAAI,EAC7C,OAAO,CAAC,EAAE,OAAO,GAAG,uBAAuB,GAC1C,IAAI,CAAC;IAER;;OAEG;IACH,mBAAmB,CAAC,CAAC,SAAS,MAAM,kBAAkB,EACpD,IAAI,EAAE,CAAC,EACP,QAAQ,EAAE,CAAC,EAAE,EAAE,kBAAkB,CAAC,CAAC,CAAC,KAAK,IAAI,EAC7C,OAAO,CAAC,EAAE,OAAO,GAAG,oBAAoB,GACvC,IAAI,CAAC;IAIR;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAEtE;;OAEG;IACH,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAE3C;;OAEG;IACH,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAEjE;;OAEG;IACH,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAEjD;;OAEG;IACH,iBAAiB,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC5C,CAAC;AAsNF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,eAAe,CAuKvF"}

package/dist/core/abort.d.ts

@@ -0,0 +1,2 @@
+export declare function throwIfAborted(signal?: AbortSignal): void;
+//# sourceMappingURL=abort.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../../src/core/abort.ts"],"names":[],"mappings":"AAAA,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAWzD"}

package/dist/core/debug.d.ts

@@ -0,0 +1,39 @@
+import type { NavigationEngine } from "./NavigationEngine.js";
+import type { SpatialRegistry } from "./types.js";
+export type DebugLogLevel = "none" | "moves" | "verbose";
+export type DebugOptions = {
+    /**
+     * Log level for console output.
+     * - "none": no logging
+     * - "moves": log focus changes and move events
+     * - "verbose": log everything including sync events
+     */
+    logLevel?: DebugLogLevel;
+    /**
+     * Custom logger function. Defaults to console.log.
+     */
+    logger?: (...args: unknown[]) => void;
+    /**
+     * If true, renders an overlay showing registered node bounds.
+     * Only works in browser environments.
+     */
+    showOverlay?: boolean;
+    /**
+     * Overlay z-index. Default: 9999
+     */
+    overlayZIndex?: number;
+};
+/**
+ * Attaches debug instrumentation to a NavigationEngine.
+ * Returns a cleanup function.
+ */
+export declare function attachDebug(engine: NavigationEngine, registry: SpatialRegistry, options?: DebugOptions): () => void;
+/**
+ * Debug utility: get engine stats for performance monitoring.
+ */
+export declare function getEngineStats(registry: SpatialRegistry): {
+    nodeCount: number;
+    enabledCount: number;
+    visibleCount: number;
+};
+//# sourceMappingURL=debug.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../../src/core/debug.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAwC,eAAe,EAAE,MAAM,YAAY,CAAC;AAExF,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAEzD,MAAM,MAAM,YAAY,GAAG;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;IAEzB;;OAEG;IACH,MAAM,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAEtC;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAqFF;;;GAGG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,gBAAgB,EACxB,QAAQ,EAAE,eAAe,EACzB,OAAO,GAAE,YAAiB,GACzB,MAAM,IAAI,CAgGZ;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,eAAe,GAAG;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB,CAeA"}

package/dist/core/events.d.ts

@@ -0,0 +1,36 @@
+import type { Direction, FocusReason, NodeId, Rect } from "./types.js";
+export type FocusEventDetail = {
+    nodeId: NodeId;
+    reason: FocusReason;
+    bounds: Rect | null;
+};
+export type BlurEventDetail = {
+    nodeId: NodeId;
+    reason: FocusReason;
+    bounds: Rect | null;
+};
+export type MoveEventDetail = {
+    from: NodeId | null;
+    to: NodeId | null;
+    direction: Direction;
+};
+export type RejectEventDetail = {
+    from: NodeId | null;
+    direction: Direction;
+    reason: "no-focused-node" | "no-candidates" | "all-filtered" | "no-bounds" | "boundary-blocked";
+};
+export type RegistrySyncEventDetail = {
+    hint?: {
+        added?: NodeId[];
+        removed?: NodeId[];
+        changed?: NodeId[];
+    };
+};
+export type NavigationEventMap = {
+    focus: CustomEvent<FocusEventDetail>;
+    blur: CustomEvent<BlurEventDetail>;
+    move: CustomEvent<MoveEventDetail>;
+    reject: CustomEvent<RejectEventDetail>;
+    sync: CustomEvent<RegistrySyncEventDetail>;
+};
+//# sourceMappingURL=events.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/core/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,IAAI,GAAG,IAAI,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE,IAAI,GAAG,IAAI,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,SAAS,EAAE,SAAS,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,iBAAiB,GAAG,eAAe,GAAG,cAAc,GAAG,WAAW,GAAG,kBAAkB,CAAC;CACjG,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,CAAC,EAAE;QACL,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,EAAE,WAAW,CAAC,gBAAgB,CAAC,CAAC;IACrC,IAAI,EAAE,WAAW,CAAC,eAAe,CAAC,CAAC;IACnC,IAAI,EAAE,WAAW,CAAC,eAAe,CAAC,CAAC;IACnC,MAAM,EAAE,WAAW,CAAC,iBAAiB,CAAC,CAAC;IACvC,IAAI,EAAE,WAAW,CAAC,uBAAuB,CAAC,CAAC;CAC5C,CAAC"}

package/dist/core/geometry.d.ts

@@ -0,0 +1,7 @@
+import type { Rect } from "./types.js";
+export declare function centerX(r: Rect): number;
+export declare function centerY(r: Rect): number;
+export declare function right(r: Rect): number;
+export declare function bottom(r: Rect): number;
+export declare function intersects(a: Rect, b: Rect): boolean;
+//# sourceMappingURL=geometry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"geometry.d.ts","sourceRoot":"","sources":["../../src/core/geometry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvC,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,GAAG,MAAM,CAEvC;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,GAAG,MAAM,CAEvC;AAED,wBAAgB,KAAK,CAAC,CAAC,EAAE,IAAI,GAAG,MAAM,CAErC;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,GAAG,MAAM,CAEtC;AAED,wBAAgB,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,GAAG,OAAO,CAEpD"}

package/dist/core/spatial/UniformGridIndex.d.ts

@@ -0,0 +1,17 @@
+import type { NodeId, Rect } from "../types.js";
+export declare class UniformGridIndex {
+    private readonly cellSize;
+    private readonly byCell;
+    private readonly nodeCells;
+    constructor(cellSize: number);
+    clear(): void;
+    upsert(id: NodeId, r: Rect): void;
+    remove(id: NodeId): void;
+    /**
+     * Returns a deduped candidate set from an expanding ring search around (cx, cy).
+     * This is designed to keep worst-case bounded by `maxRings`.
+     */
+    queryRings(cx: number, cy: number, maxRings: number, out: Set<NodeId>): Set<NodeId>;
+    private cellHashesForRect;
+}
+//# sourceMappingURL=UniformGridIndex.d.ts.map

package/dist/core/spatial/UniformGridIndex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"UniformGridIndex.d.ts","sourceRoot":"","sources":["../../../src/core/spatial/UniformGridIndex.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAoBhD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IACtD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA+B;gBAE7C,QAAQ,EAAE,MAAM;IAO5B,KAAK,IAAI,IAAI;IAKb,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,IAAI,GAAG,IAAI;IAejC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAkBxB;;;OAGG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC;IAmBnF,OAAO,CAAC,iBAAiB;CAS1B"}

package/dist/core/types.d.ts

@@ -0,0 +1,142 @@
+export type NodeId = string;
+export type GroupId = string;
+export type Direction = "left" | "right" | "up" | "down";
+export type DirectionBoundary = {
+    left?: boolean;
+    right?: boolean;
+    up?: boolean;
+    down?: boolean;
+};
+export type Rect = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+export type FocusReason = "programmatic" | "move";
+export type NavigationEngineOptions = {
+    registry: SpatialRegistry;
+    /**
+     * Uniform grid cell size (world units). Tune per app scale.
+     * Bigger cell size = fewer index cells, but more candidates per query.
+     */
+    cellSize?: number;
+    /**
+     * How many nearby cells to expand when searching for candidates.
+     * Kept small to bound worst-case work.
+     */
+    maxRings?: number;
+    /**
+     * If the bounded index query returns zero candidates, optionally fall back to
+     * a single O(N) scan for correctness in sparse layouts.
+     *
+     * Default: true
+     */
+    fallbackToScan?: boolean;
+};
+export type FocusOptions = {
+    signal?: AbortSignal;
+    reason?: FocusReason;
+    /**
+     * If true, updates the registry cache/index before focusing.
+     * Prefer batching updates externally in your render/tick loop for max perf.
+     */
+    sync?: boolean;
+};
+export type FocusGroupFallback = "history-first" | "history" | "first" | "none";
+export type FocusGroupOptions = FocusOptions & {
+    /**
+     * If provided, attempts to focus this specific node within the group first.
+     */
+    id?: NodeId;
+    /**
+     * What to do if `id` is not provided or not eligible / not in group.
+     * Default: "history-first"
+     */
+    fallback?: FocusGroupFallback;
+};
+export type MoveOptions = {
+    signal?: AbortSignal;
+    /**
+     * If true, updates the registry cache/index before computing the move.
+     * Prefer batching updates externally in your render/tick loop for max perf.
+     */
+    sync?: boolean;
+};
+export type RegistryUpdate = {
+    added?: NodeId[];
+    removed?: NodeId[];
+    changed?: NodeId[];
+};
+export interface SpatialRegistry {
+    /**
+     * Returns all currently-registered node ids. For performance this should
+     * return a stable array when possible.
+     */
+    ids(): readonly NodeId[];
+    /**
+     * Returns cached bounds for a node in world coordinates.
+     * Must be fast and must not force expensive layout/draw work.
+     */
+    bounds(id: NodeId): Rect | null;
+    /**
+     * Performs a best-effort fast sync to refresh cached bounds/index.
+     * Should be idempotent and allow partial/incremental updates.
+     */
+    sync?(hint?: RegistryUpdate): void;
+    /**
+     * Optional hint provider: returns a best-effort incremental update set since the
+     * last call. Implementations may clear their internal pending set after returning.
+     *
+     * If present, `NavigationEngine.sync()` will use this when no explicit hint is passed.
+     */
+    pendingUpdate?(): RegistryUpdate | undefined;
+    /**
+     * Called when the engine focuses/defocuses a node.
+     * Should be cheap (e.g. toggle class, set internal state).
+     */
+    onFocus?(id: NodeId, reason: FocusReason): void;
+    onBlur?(id: NodeId, reason: FocusReason): void;
+    /**
+     * Filter helpers. If absent, engine assumes true.
+     */
+    enabled?(id: NodeId): boolean;
+    visible?(id: NodeId): boolean;
+    /**
+     * Optional focus group id for a node.
+     * Used by the engine to implement group-scoped focus history and restore-on-enter behavior.
+     */
+    group?(id: NodeId): GroupId | null;
+    /**
+     * Check if a direction is blocked for leaving a group.
+     * Used by the engine to implement focus boundaries/trapping.
+     */
+    groupBoundary?(groupId: GroupId, direction: Direction): boolean;
+    /**
+     * Set boundary config for a group.
+     * Called by FocusGroup component to register boundaries.
+     */
+    setGroupBoundary?(groupId: GroupId, boundary: DirectionBoundary): void;
+    /**
+     * Clear boundary config for a group.
+     * Called when FocusGroup unmounts.
+     */
+    clearGroupBoundary?(groupId: GroupId): void;
+    /**
+     * Check if a group should restore focus history on enter.
+     * Returns undefined if not explicitly configured (allows engine fallback).
+     * Used by the engine for restore-on-enter behavior.
+     */
+    groupRestoreOnEnter?(groupId: GroupId): boolean | undefined;
+    /**
+     * Set restore-on-enter config for a group.
+     * Called by FocusGroup component.
+     */
+    setGroupRestoreOnEnter?(groupId: GroupId, enabled: boolean): void;
+    /**
+     * Clear restore-on-enter config for a group.
+     * Called when FocusGroup unmounts.
+     */
+    clearGroupRestoreOnEnter?(groupId: GroupId): void;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./core/NavigationEngine.js";
+export * from "./core/NavigationStore.js";
+export * from "./core/types.js";
+export * from "./core/events.js";
+export * from "./core/abort.js";
+export * from "./core/debug.js";
+export * from "./registries/genericRegistry.js";
+export * from "./registries/combinedRegistry.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAEhC,cAAc,iCAAiC,CAAC;AAChD,cAAc,kCAAkC,CAAC"}