blecsd 0.1.1 → 0.3.0

package/dist/systems/index.d.ts

@@ -1,12 +1,15 @@
-import { S as Scheduler } from '../scheduler-DcfoFuum.js';
-import { S as System, W as World, E as Entity, L as LoopPhase } from '../types-BcsvoKzf.js';
-import { d as CollisionPair, f as EmitterAppearance, R as RenderedTileCell } from '../tilemap-D1HJvKy3.js';
-import { E as EventBus, U as UIEventMap } from '../events-BbbxkgvX.js';
-import { b as KeyEvent } from '../keyParser-Bwm8-l7v.js';
+import { S as Scheduler } from '../scheduler-CMcYew9Z.js';
+import { S as System, W as World, E as Entity, L as LoopPhase } from '../types-CPB4CpbH.js';
+import { d as CollisionPair, f as EmitterAppearance, R as RenderedTileCell } from '../tilemap-BirMJdbu.js';
+import { a as EventBus, U as UIEventMap } from '../events-9ForpTfM.js';
+import { P as PackedStore, a as PackedHandle } from '../packedStore-BgvnEdE7.js';
+import { b as KeyEvent } from '../keyParser-BnHbg2iD.js';
 import { M as MouseEvent } from '../mouseParser-Cfrbn3AX.js';
 import { Writable } from 'node:stream';
 import { c as CellChange, S as ScreenBufferData, C as Cell } from '../cell-DwIu2ryP.js';
 import { D as DoubleBufferData } from '../doubleBuffer-CKQFmlPN.js';
+import { D as DirtyTracker } from '../dirtyTracking-C4v8MmM9.js';
+import { a as ComponentStore } from '../componentStorage-CJTh-TPO.js';
 import { z } from 'zod';
 import { V as VirtualizedLineStore } from '../virtualizedLineStore-DwPEvPkk.js';
 import 'bitecs';
@@ -20,6 +23,9 @@ import 'bitecs';
 /**
  * Query all entities with the Animation component.
  *
+ * PERF: Converts iterator to array for system processing.
+ * Array allocation is unavoidable here as we need to iterate over entities.
+ *
  * @param world - The ECS world
  * @returns Array of entity IDs with Animation component
  */
@@ -271,6 +277,10 @@ declare function updateCameras(world: World, deltaTime: number): void;
 /**
  * Collision system for detecting entity collisions.
  * Processes all entities with Collider component.
+ *
+ * Uses PackedStore for cache-friendly dense iteration of active pairs,
+ * with numeric pair keys to eliminate per-frame string allocation.
+ *
  * @module systems/collisionSystem
  */
 
@@ -296,16 +306,34 @@ interface CollisionEventMap {
     /** Fired when an entity exits a trigger zone */
     triggerExit: CollisionEventData;
 }
+/**
+ * Readonly view of active collision/trigger pairs.
+ * Provides dense data for cache-friendly iteration without
+ * exposing mutable store internals. Do not cache this view
+ * across frames, as the underlying data may be reallocated.
+ */
+interface ActivePairsView {
+    /** Dense array of active pairs. Read-only; do not mutate elements or indices. */
+    readonly data: ReadonlyArray<CollisionPair>;
+    /** Number of live pairs in the data array (iterate data[0..size-1]). */
+    readonly size: number;
+}
 /**
  * Collision system state.
+ * Uses PackedStore for cache-friendly dense storage and iteration
+ * of active collision and trigger pairs.
  */
 interface CollisionSystemState {
     /** Event bus for collision events */
     readonly eventBus: EventBus<CollisionEventMap>;
-    /** Currently active collision pairs */
-    readonly activePairs: Map<string, CollisionPair>;
-    /** Currently active trigger pairs */
-    readonly activeTriggers: Map<string, CollisionPair>;
+    /** Currently active collision pairs (dense packed storage) */
+    readonly activePairs: PackedStore<CollisionPair>;
+    /** Currently active trigger pairs (dense packed storage) */
+    readonly activeTriggers: PackedStore<CollisionPair>;
+    /** Maps numeric pair key to handle in activePairs for O(1) lookup */
+    readonly pairHandles: Map<number, PackedHandle>;
+    /** Maps numeric pair key to handle in activeTriggers for O(1) lookup */
+    readonly triggerHandles: Map<number, PackedHandle>;
 }
 /**
  * Gets the collision event bus.
@@ -324,17 +352,53 @@ interface CollisionSystemState {
  */
 declare function getCollisionEventBus(): EventBus<CollisionEventMap>;
 /**
- * Gets the current active collision pairs.
+ * Gets the current number of active collision pairs.
+ *
+ * @returns Number of active solid collision pairs
+ *
+ * @example
+ * ```typescript
+ * import { getActiveCollisionCount } from 'blecsd';
  *
- * @returns Map of active collision pairs
+ * const count = getActiveCollisionCount();
+ * console.log(`${count} active collisions`);
+ * ```
  */
-declare function getActiveCollisions(): ReadonlyMap<string, CollisionPair>;
+declare function getActiveCollisionCount(): number;
 /**
- * Gets the current active trigger pairs.
+ * Gets the current active collision pairs as a readonly view.
+ * Iterate data[0..size-1] for dense, cache-friendly access.
+ *
+ * The returned view is a snapshot reference into the live store.
+ * Do not cache it across frames or mutate its contents.
  *
- * @returns Map of active trigger pairs
+ * @returns Readonly view of active collision pairs
  */
-declare function getActiveTriggers(): ReadonlyMap<string, CollisionPair>;
+declare function getActiveCollisions(): ActivePairsView;
+/**
+ * Gets the current number of active trigger pairs.
+ *
+ * @returns Number of active trigger pairs
+ *
+ * @example
+ * ```typescript
+ * import { getActiveTriggerCount } from 'blecsd';
+ *
+ * const count = getActiveTriggerCount();
+ * console.log(`${count} active triggers`);
+ * ```
+ */
+declare function getActiveTriggerCount(): number;
+/**
+ * Gets the current active trigger pairs as a readonly view.
+ * Iterate data[0..size-1] for dense, cache-friendly access.
+ *
+ * The returned view is a snapshot reference into the live store.
+ * Do not cache it across frames or mutate its contents.
+ *
+ * @returns Readonly view of active trigger pairs
+ */
+declare function getActiveTriggers(): ActivePairsView;
 /**
  * Resets the collision system state.
  * Useful for testing or scene changes.
@@ -420,6 +484,7 @@ declare function createCollisionSystem(): System;
 declare function registerCollisionSystem(scheduler: Scheduler, priority?: number): void;
 /**
  * Checks if an entity is currently colliding with any other entity.
+ * Uses dense iteration over the packed collision store.
  *
  * @param eid - The entity to check
  * @returns true if entity is in any active collision
@@ -436,6 +501,7 @@ declare function registerCollisionSystem(scheduler: Scheduler, priority?: number
 declare function isColliding(eid: number): boolean;
 /**
  * Checks if an entity is currently in any trigger zone.
+ * Uses dense iteration over the packed trigger store.
  *
  * @param eid - The entity to check
  * @returns true if entity is in any active trigger
@@ -452,6 +518,7 @@ declare function isColliding(eid: number): boolean;
 declare function isInTrigger(eid: number): boolean;
 /**
  * Gets all entities currently colliding with a specific entity.
+ * Uses dense iteration over the packed collision store.
  *
  * @param eid - The entity to check
  * @returns Array of entity IDs colliding with this entity
@@ -469,6 +536,7 @@ declare function isInTrigger(eid: number): boolean;
 declare function getCollidingEntities(eid: number): number[];
 /**
  * Gets all trigger zones an entity is currently in.
+ * Uses dense iteration over the packed trigger store.
  *
  * @param eid - The entity to check
  * @returns Array of entity IDs of triggers this entity is in
@@ -486,6 +554,7 @@ declare function getCollidingEntities(eid: number): number[];
 declare function getTriggerZones(eid: number): number[];
 /**
  * Checks if two specific entities are currently colliding.
+ * Uses handle-based O(1) lookup via numeric pair key.
  *
  * @param eidA - First entity
  * @param eidB - Second entity
@@ -780,14 +849,7 @@ declare function createDragSystem(eventBus: EventBus<DragEventMap>): {
      * @returns True if position was updated
      */
     updateDrag(world: World, mouseX: number, mouseY: number): boolean;
-    /**
-     * Ends the current drag operation.
-     *
-     * @param world - The ECS world
-     * @param dropTarget - Entity under the drop point (if any)
-     * @param cancelled - Whether the drag was cancelled
-     */
-    endDrag(world: World, dropTarget?: Entity | null, cancelled?: boolean): void;
+    endDrag: (world: World, dropTarget?: Entity | null, cancelled?: boolean) => void;
     /**
      * Cancels the current drag and restores original position.
      *
@@ -1471,6 +1533,8 @@ declare function pointInEntity(world: World, eid: Entity, x: number, y: number):
  * Performs hit testing at a point to find all entities under it.
  * Returns entities sorted by z-index (highest first).
  *
+ * PERF: Uses iterator directly to avoid intermediate array allocation.
+ *
  * @param world - The ECS world
  * @param x - X coordinate to test
  * @param y - Y coordinate to test
@@ -1584,6 +1648,8 @@ declare function clearEntityInput(world: World, eid: Entity): void;
  * Query all entities that can receive input.
  * Returns entities with either Interactive or Focusable components.
  *
+ * PERF: Processes iterators directly to minimize allocations.
+ *
  * @param world - The ECS world
  * @returns Array of entity IDs that can receive input
  */
@@ -1770,6 +1836,9 @@ declare function getComputedBounds(world: World, eid: Entity): {
 /**
  * Query all entities with the Velocity component.
  *
+ * PERF: Converts iterator to array for system processing.
+ * Array allocation is unavoidable here as we need to iterate over entities.
+ *
  * @param world - The ECS world
  * @returns Array of entity IDs with Velocity component
  */
@@ -1802,7 +1871,7 @@ declare function hasMovementSystem(world: World, eid: number): boolean;
  * import { createScheduler, LoopPhase, movementSystem } from 'blecsd';
  *
  * const scheduler = createScheduler();
- * scheduler.registerSystem(LoopPhase.PHYSICS, movementSystem);
+ * scheduler.registerSystem(LoopPhase.ANIMATION, movementSystem);
  *
  * // In game loop
  * scheduler.run(world, deltaTime);
@@ -1822,7 +1891,7 @@ declare const movementSystem: System;
  *
  * const scheduler = createScheduler();
  * const system = createMovementSystem();
- * scheduler.registerSystem(LoopPhase.PHYSICS, system);
+ * scheduler.registerSystem(LoopPhase.ANIMATION, system);
  * ```
  */
 declare function createMovementSystem(): System;
@@ -1899,6 +1968,7 @@ declare function createOutputState(): OutputState;
  *
  * @param state - Output state
  * @param changes - Array of cell changes
+ * @param skipSort - Skip sorting if changes are already in row-major order
  * @returns ANSI output string
  *
  * @example
@@ -1910,7 +1980,7 @@ declare function createOutputState(): OutputState;
  * process.stdout.write(output);
  * ```
  */
-declare function generateOutput(state: OutputState, changes: readonly CellChange[]): string;
+declare function generateOutput(state: OutputState, changes: readonly CellChange[], skipSort?: boolean): string;
 /**
  * Sets the output stream for the output system.
  *
@@ -2399,6 +2469,8 @@ interface ParticleSystemConfig {
     readonly particles: EntityProvider;
     /** Maximum concurrent particles (default: 1000) */
     readonly maxParticles?: number;
+    /** Archetype pool name for zero-alloc entity recycling (optional) */
+    readonly archetypeName?: string;
 }
 /**
  * Spawns a single particle from an emitter at a random angle within the spread.
@@ -2406,9 +2478,10 @@ interface ParticleSystemConfig {
  * @param world - The ECS world
  * @param emitterId - The emitter entity ID
  * @param appearance - Visual appearance config
+ * @param archetypeName - Optional archetype pool name for entity recycling
  * @returns The spawned particle entity ID, or -1 if spawn failed
  */
-declare function spawnParticle(world: World, emitterId: Entity, appearance: EmitterAppearance): Entity;
+declare function spawnParticle(world: World, emitterId: Entity, appearance: EmitterAppearance, archetypeName?: string): Entity;
 /**
  * Triggers a burst of particles from an emitter.
  *
@@ -2446,10 +2519,14 @@ declare function moveParticle(world: World, eid: Entity, delta: number): void;
 /**
  * Removes a dead particle and cleans up tracking.
  *
+ * When an archetype name is provided, the entity is returned to the pool
+ * instead of being fully removed from the world.
+ *
  * @param world - The ECS world
  * @param eid - The particle entity ID
+ * @param archetypeName - Optional archetype pool name for entity recycling
  */
-declare function killParticle(world: World, eid: Entity): void;
+declare function killParticle(world: World, eid: Entity, archetypeName?: string): void;
 declare function createParticleSystem(config: ParticleSystemConfig): System;
 
 /**
@@ -2466,8 +2543,8 @@ interface RenderContext {
     readonly world: World;
     /** The screen buffer to render to */
     readonly buffer: ScreenBufferData;
-    /** The double buffer for dirty tracking */
-    readonly doubleBuffer: DoubleBufferData;
+    /** The dirty tracker for optimized rendering */
+    readonly dirtyTracker: DirtyTracker;
 }
 /**
  * Computed bounds for an entity.
@@ -2541,30 +2618,101 @@ declare function renderContent(_ctx: RenderContext, _eid: Entity, _contentBounds
  */
 declare function renderScrollbar(_ctx: RenderContext, _eid: Entity, _bounds: EntityBounds): void;
 /**
- * Sets the double buffer for the render system.
+ * Recursively renders an entity and its children in tree order.
+ * @internal Currently unused, reserved for future tree-based rendering mode.
+ *
+ * @param ctx - Render context
+ * @param eid - Entity ID
+ */
+/**
+ * Viewport bounds for culling off-screen entities.
+ * Defaults to null (no culling). Set via setViewportBounds().
+ */
+interface ViewportBounds {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * Sets the viewport bounds for culling.
+ * Entities outside these bounds will be skipped during rendering.
+ *
+ * Pass null to disable viewport culling (default).
+ * Typically set to screen dimensions for scrollable content optimization.
+ *
+ * @param bounds - Viewport bounds or null to disable culling
+ *
+ * @example
+ * ```typescript
+ * import { setViewportBounds } from 'blecsd';
+ *
+ * // Enable viewport culling for 80x24 screen
+ * setViewportBounds({ x: 0, y: 0, width: 80, height: 24 });
+ *
+ * // Disable viewport culling
+ * setViewportBounds(null);
+ * ```
+ */
+declare function setViewportBounds(bounds: ViewportBounds | null): void;
+/**
+ * Gets the current viewport bounds.
+ *
+ * @returns Current viewport bounds or null if disabled
+ */
+declare function getViewportBounds(): ViewportBounds | null;
+/**
+ * Sets the dirty tracker and screen buffer for the render system.
  * Must be called before running the render system.
  *
- * @param db - The double buffer to render to
+ * @param tracker - The dirty tracker for optimized rendering
+ * @param buffer - The screen buffer to render to
  *
  * @example
  * ```typescript
- * import { setRenderBuffer, createDoubleBuffer } from 'blecsd';
+ * import { setRenderBuffer, createDirtyTracker } from 'blecsd';
+ * import { createScreenBuffer } from 'blecsd';
  *
- * const db = createDoubleBuffer(80, 24);
- * setRenderBuffer(db);
+ * const tracker = createDirtyTracker(80, 24);
+ * const buffer = createScreenBuffer(80, 24);
+ * setRenderBuffer(tracker, buffer);
  * ```
  */
-declare function setRenderBuffer(db: DoubleBufferData): void;
+declare function setRenderBuffer(tracker: DirtyTracker, buffer: ScreenBufferData): void;
 /**
- * Gets the current render buffer.
+ * Gets the current dirty tracker.
  *
- * @returns The current double buffer or null
+ * @returns The current dirty tracker or null
  */
-declare function getRenderBuffer(): DoubleBufferData | null;
+declare function getRenderBuffer(): DirtyTracker | null;
 /**
- * Clears the render buffer reference.
+ * Clears the render buffer references.
  */
 declare function clearRenderBuffer(): void;
+/**
+ * Enables or disables z-order occlusion culling.
+ * When enabled, entities fully hidden behind higher z-index entities are skipped during rendering.
+ *
+ * Disabled by default. Enable for applications with many overlapping widgets (modals, dialogs, overlays)
+ * where the performance benefit outweighs the culling overhead.
+ *
+ * @param enabled - Whether to enable occlusion culling (default: false)
+ *
+ * @example
+ * ```typescript
+ * import { setOcclusionCulling } from 'blecsd';
+ *
+ * // Enable occlusion culling for layered UI
+ * setOcclusionCulling(true);
+ * ```
+ */
+declare function setOcclusionCulling(enabled: boolean): void;
+/**
+ * Gets the current occlusion culling state.
+ *
+ * @returns True if occlusion culling is enabled
+ */
+declare function isOcclusionCullingEnabled(): boolean;
 /**
  * Render system that draws visible, dirty entities to the screen buffer.
  * Entities are rendered in z-index order (lower z first, higher z on top).
@@ -2573,21 +2721,33 @@ declare function clearRenderBuffer(): void;
  * 1. Queries all entities with Position and Renderable
  * 2. Filters to visible, dirty entities
  * 3. Sorts by z-index
- * 4. Renders each entity (background, border, content)
- * 5. Marks entities as clean
+ * 4. Applies viewport bounds culling (skips off-screen entities)
+ * 5. Applies z-order occlusion culling (skips fully hidden entities)
+ * 6. Renders each visible entity (background, border, content)
+ * 7. Marks entities as clean
+ *
+ * Viewport culling: entities completely outside the viewport bounds are skipped
+ * to improve performance in scrollable content with many off-screen entities.
+ * Enable via `setViewportBounds({ x, y, width, height })`.
+ *
+ * Occlusion culling: entities fully covered by higher z-index entities are
+ * skipped to improve performance in layered UIs (modals, dialogs, overlays).
+ * Enable via `setOcclusionCulling(true)`.
  *
  * @param world - The ECS world
  * @returns The world (unchanged)
  *
  * @example
  * ```typescript
- * import { renderSystem, setRenderBuffer, createScheduler, LoopPhase } from 'blecsd';
+ * import { renderSystem, setRenderBuffer, setViewportBounds, createScheduler, LoopPhase } from 'blecsd';
  *
  * const scheduler = createScheduler();
  * scheduler.registerSystem(LoopPhase.RENDER, renderSystem);
  *
- * // Before running, set the render buffer
- * setRenderBuffer(doubleBuffer);
+ * // Set render buffer and enable viewport culling
+ * setRenderBuffer(dirtyTracker, screenBuffer);
+ * setViewportBounds({ x: 0, y: 0, width: 80, height: 24 });
+ *
  * scheduler.run(world, deltaTime);
  * ```
  */
@@ -2866,6 +3026,11 @@ declare function createSmoothScrollSystem(physics?: Partial<ScrollPhysicsConfig>
  * which entities overlap it. Enables efficient broad-phase collision
  * detection by only checking entities in the same or adjacent cells.
  *
+ * Supports incremental updates: tracks which entities have moved since
+ * the last frame via a PackedStore dirty set, and only re-hashes those
+ * entities. Falls back to full rebuild when the dirty fraction exceeds
+ * a configurable threshold.
+ *
  * @module systems/spatialHash
  */
 
@@ -2905,6 +3070,32 @@ interface SpatialHashStats {
     readonly averageEntitiesPerCell: number;
     readonly maxEntitiesInCell: number;
 }
+/**
+ * Cached bounds for a single entity (position + collider offset + size).
+ */
+interface PrevBounds {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/**
+ * Internal state for the incremental spatial hash system.
+ * Tracks which entities need re-hashing via a PackedStore dirty set,
+ * and caches previous positions for change detection.
+ */
+interface SpatialHashSystemState {
+    /** Dense packed store of dirty entity IDs for cache-friendly iteration */
+    readonly dirtyEntities: PackedStore<number>;
+    /** O(1) dedup: entity IDs currently in the dirty store */
+    readonly dirtyLookup: Set<number>;
+    /** Previous bounds per entity, backed by PackedStore for cache-friendly iteration */
+    readonly prevBounds: ComponentStore<PrevBounds>;
+    /** Whether the system has run at least once (first frame needs full rebuild) */
+    initialized: boolean;
+    /** Fraction of entities that must be dirty to trigger full rebuild (0.0-1.0) */
+    dirtyThreshold: number;
+}
 /** Default cell size */
 declare const DEFAULT_CELL_SIZE = 8;
 /**
@@ -3088,8 +3279,23 @@ declare function getSpatialHashStats(grid: SpatialHashGrid): SpatialHashStats;
  * ```
  */
 declare function rebuildSpatialHash(grid: SpatialHashGrid, world: World): void;
+/**
+ * Creates a fresh spatial hash system state for incremental updates.
+ *
+ * @param dirtyThreshold - Fraction of entities above which full rebuild is used (default: 0.5)
+ * @returns New system state
+ *
+ * @example
+ * ```typescript
+ * import { createSpatialHashSystemState } from 'blecsd';
+ *
+ * const state = createSpatialHashSystemState(0.3);
+ * ```
+ */
+declare function createSpatialHashSystemState(dirtyThreshold?: number): SpatialHashSystemState;
 /**
  * Sets the spatial hash grid for the system to use.
+ * Resets incremental state so the next tick performs a full rebuild.
  *
  * @param grid - The spatial hash grid
  *
@@ -3109,7 +3315,96 @@ declare function setSpatialHashGrid(grid: SpatialHashGrid): void;
  */
 declare function getSpatialHashGrid(): SpatialHashGrid | null;
 /**
- * Spatial hash system that rebuilds the grid each frame.
+ * Gets the current incremental update system state.
+ *
+ * @returns The system state
+ */
+declare function getSpatialHashSystemState(): SpatialHashSystemState;
+/**
+ * Marks an entity as needing re-hashing on the next system tick.
+ * Use this when an external system knows an entity's position or
+ * collider changed, to avoid waiting for the position comparison scan.
+ *
+ * @param eid - Entity to mark dirty
+ *
+ * @example
+ * ```typescript
+ * import { markSpatialDirty } from 'blecsd';
+ *
+ * // After teleporting an entity, mark it dirty
+ * Position.x[entity] = 100;
+ * Position.y[entity] = 200;
+ * markSpatialDirty(entity);
+ * ```
+ */
+declare function markSpatialDirty(eid: Entity): void;
+/**
+ * Gets the number of entities currently marked as dirty.
+ *
+ * @returns Count of dirty entities awaiting re-hash
+ *
+ * @example
+ * ```typescript
+ * import { getSpatialDirtyCount } from 'blecsd';
+ *
+ * console.log(`${getSpatialDirtyCount()} entities need re-hashing`);
+ * ```
+ */
+declare function getSpatialDirtyCount(): number;
+/**
+ * Resets the incremental spatial hash system state.
+ * Clears dirty entities, position cache, and forces a full rebuild on next tick.
+ * Useful for testing or scene transitions.
+ *
+ * @example
+ * ```typescript
+ * import { resetSpatialHashState } from 'blecsd';
+ *
+ * resetSpatialHashState();
+ * ```
+ */
+declare function resetSpatialHashState(): void;
+/**
+ * Sets the dirty threshold for the incremental update system.
+ * When the fraction of dirty entities exceeds this value,
+ * a full rebuild is used instead of incremental updates.
+ *
+ * @param threshold - Fraction between 0.0 and 1.0 (default: 0.5)
+ *
+ * @example
+ * ```typescript
+ * import { setSpatialDirtyThreshold } from 'blecsd';
+ *
+ * // Use full rebuild when more than 30% of entities moved
+ * setSpatialDirtyThreshold(0.3);
+ * ```
+ */
+declare function setSpatialDirtyThreshold(threshold: number): void;
+/**
+ * Performs an incremental update of the spatial hash grid.
+ * Only re-inserts entities that were marked dirty (moved, resized, or new).
+ * Falls back to full rebuild when dirty count exceeds the threshold.
+ *
+ * @param grid - The spatial hash grid
+ * @param state - The incremental update state
+ * @param world - The ECS world
+ *
+ * @example
+ * ```typescript
+ * import { createSpatialHash, createSpatialHashSystemState, incrementalSpatialUpdate } from 'blecsd';
+ *
+ * const grid = createSpatialHash({ cellSize: 4 });
+ * const state = createSpatialHashSystemState();
+ * incrementalSpatialUpdate(grid, state, world);
+ * ```
+ */
+declare function incrementalSpatialUpdate(grid: SpatialHashGrid, state: SpatialHashSystemState, world: World): void;
+/**
+ * Spatial hash system with incremental updates.
+ *
+ * On the first frame, performs a full rebuild. On subsequent frames,
+ * detects which entities moved and only re-hashes those. Falls back
+ * to full rebuild when the dirty fraction exceeds the configured threshold.
  *
  * Register this in the EARLY_UPDATE phase to ensure collision queries
  * use up-to-date spatial data.
@@ -3728,18 +4023,23 @@ interface CullingResult {
     /** Number of entities culled (not visible) */
     readonly culled: number;
 }
+/**
+ * Cached bounds for a single entity in the position cache.
+ */
+interface CachedBounds {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
 /**
  * Entity position cache for incremental updates.
+ * Uses a single ComponentStore instead of 4 separate Maps,
+ * reducing hash lookups from 4 to 1 per entity per frame.
  */
 interface PositionCache {
-    /** Previous x position per entity */
-    readonly prevX: Map<number, number>;
-    /** Previous y position per entity */
-    readonly prevY: Map<number, number>;
-    /** Previous width per entity */
-    readonly prevW: Map<number, number>;
-    /** Previous height per entity */
-    readonly prevH: Map<number, number>;
+    /** Previous bounds per entity */
+    readonly bounds: ComponentStore<CachedBounds>;
 }
 /**
  * Creates a position cache for tracking entity movement.
@@ -3868,6 +4168,7 @@ declare function createVisibilityCullingSystem(grid: SpatialHashGrid, getViewpor
  *
  * @module systems/workerPool
  */
+
 /**
  * Configuration for the worker pool.
  */
@@ -4033,4 +4334,4 @@ declare function getWorkerPoolState(): WorkerPoolState;
  */
 declare function destroyWorkerPool(): void;
 
-export { type BehaviorSystemConfig, type BudgetAlert, type CellCoord, type CollisionEventData, type CollisionEventMap, type CollisionSystemState, ComputedLayout, type ComputedLayoutData, type CullingResult, DEFAULT_CELL_SIZE, type DirtyRect, type DragConstraints, type DragEndEvent, type DragEventMap, type DragMoveEvent, type DragStartEvent, type DragState, type DragVerifyCallback, type DropEvent, type EntityProvider, type FocusEventData, type FocusEventMap, type FocusEventType, type FrameBudgetConfig, type FrameBudgetManager, type FrameStats, type HitTestResult, type InputEventType, type InputSystemState, type LineRenderConfig, LineRenderConfigSchema, type MoveResult, type MovementApplier, type OutputState, type PanelConstraints, type PanelMoveConfig, type PanelMoveState, type ParticleSystemConfig, type PoolStats, type PoolTask, type PositionCache, type PositionResolver, type QueuedInputEvent, type QueuedKeyEvent, type QueuedMouseEvent, type RenderContext, type ResizeHandle, type ScrollAnimationState, type ScrollEvent, type ScrollPhysicsConfig, type SpatialHashConfig, type SpatialHashGrid, type SpatialHashStats, type SyncHandler, type SystemTiming, type TaskPriority, type TaskResult, type TileMapBuffer, type TileMapCamera, type TileMapRendererConfig, type Viewport, type VirtualizedRenderContext, type WorkerPoolConfig, type WorkerPoolState, ageParticle, animationSystem, applyScrollImpulse, areColliding, beginMove, beginResize, blurAll, burstParticles, cameraSystem, cancelAllOfType, cancelMoveOrResize, cancelTask, captureMouseTo, cleanup, cleanupEntityResources, cleanupVirtualizedRenderSystem, clearAllScrollStates, clearDragConstraints, clearEntityInput, clearEventQueue, clearFocusStack, clearLineRenderConfig, clearOutputBuffer, clearOutputStream, clearPositionCache, clearRenderBuffer, clearScreen, clearSpatialHash, clearTileMapRenderBuffer, clearVirtualizedRenderBuffer, collisionSystem, computeLayoutNow, createAnimationSystem, createBehaviorSystem, createCameraSystem, createCollisionSystem, createDragSystem, createEmptyBuffer, createFocusSystem, createFrameBudgetManager, createIncrementalSpatialSystem, createInputSystem, createLayoutSystem, createMovementSystem, createOutputState, createOutputSystem, createPanelConstraints, createPanelMoveConfig, createPanelMoveState, createParticleSystem, createPositionCache, createRenderSystem, createSmoothScrollSystem, createSpatialHash, createSpatialHashSystem, createStateMachineSystem, createTilemapRenderSystem, createVirtualizedRenderSystem, createVisibilityCullingSystem, createWorkerPool, cursorHome, destroyFrameBudgetManager, destroyWorkerPool, detectCollisions, detectResizeHandle, endMoveOrResize, endUserScroll, enterAlternateScreen, exportFrameBudgetMetrics, focusEntity, focusFirst, focusLast, focusNext, focusOffset, focusPop, focusPrev, focusPush, focusSystem, generateOutput, getActiveCollisions, getActiveTriggers, getCollidingEntities, getCollisionEventBus, getComputedBounds, getComputedLayout, getDragConstraints, getDragVerifyCallback, getEntitiesAtPoint, getEntitiesInCell, getEventQueue, getFocusEventBus, getFocusStackDepth, getFocusableEntities, getFocused, getFrameBudgetStats, getInputEventBus, getInteractiveEntityAt, getLineRenderConfig, getLineStore, getMouseCaptureEntity, getNearbyEntities, getOutputBuffer, getOutputState, getOutputStream, getRenderBuffer, getScrollPosition, getScrollState, getSpatialHashGrid, getSpatialHashStats, getStateAgeStore, getSystemStateAge, getTileMapRenderBuffer, getTileMapRendererConfig, getTriggerZones, getVirtualizedRenderBuffer, getWorkerPoolState, hasAnimationSystem, hasComputedLayout, hasMovementSystem, hideCursor, hitTest, inputState, inputSystem, insertEntity, invalidateAllLayouts, invalidateLayout, isColliding, isInTrigger, isMouseCaptured, isScrolling, keyboardMove, keyboardResize, killParticle, layoutSystem, leaveAlternateScreen, markAllDirty, mergeDirtyRects, moveParticle, movementSystem, onBudgetAlert, outputSystem, peekFocusStack, performCulling, pointInEntity, profiledSystem, queryAnimation, queryArea, queryCameras, queryColliders, queryInputReceivers, queryMovement, queryStateMachine, queryVisibleEntities, queueKeyEvent, queueMouseEvent, rebuildSpatialHash, recordFrameBudgetSystemTime, recordFrameTime, recordPhaseTime, registerAnimationSystem, registerCameraSystem, registerCollisionSystem, registerInputSystem, registerLineStore, registerMovementSystem, registerStateMachineSystem, registerTaskHandler, releaseMouse, removeEntityFromGrid, removeFromCache, removeScrollState, renderAllTileMaps, renderBackground, renderBorder, renderContent, renderRect, renderScrollbar, renderSystem, renderText, renderTileMapToBuffer, resetAttributes, resetCollisionState, resetDragStores, resetFocusEventBus, resetFrameBudget, resetInputState, resetOutputState, resetStateAge, resetTileMapRenderer, restoreFocus, rewindFocus, saveFocus, setDragConstraints, setDragVerifyCallback, setLineRenderConfig, setOutputBuffer, setOutputStream, setRenderBuffer, setScrollImmediate, setSpatialHashGrid, setTileMapRendererConfig, setVirtualizedRenderBuffer, showCursor, smoothScrollTo, spatialHashSystem, spawnParticle, startUserScroll, stateMachineSystem, submitTask, tilemapRenderSystem, unregisterLineStore, updateAnimations, updateCameras, updateEntityIfMoved, updateLineStore, updateMove, updateMovements, updateResize, updateScrollPhysics, updateStateAges, virtualizedRenderSystem, worldToCell, writeRaw };
+export { type ActivePairsView, type BehaviorSystemConfig, type BudgetAlert, type CachedBounds, type CellCoord, type CollisionEventData, type CollisionEventMap, type CollisionSystemState, ComputedLayout, type ComputedLayoutData, type CullingResult, DEFAULT_CELL_SIZE, type DirtyRect, type DragConstraints, type DragEndEvent, type DragEventMap, type DragMoveEvent, type DragStartEvent, type DragState, type DragVerifyCallback, type DropEvent, type EntityProvider, type FocusEventData, type FocusEventMap, type FocusEventType, type FrameBudgetConfig, type FrameBudgetManager, type FrameStats, type HitTestResult, type InputEventType, type InputSystemState, type LineRenderConfig, LineRenderConfigSchema, type MoveResult, type MovementApplier, type OutputState, type PanelConstraints, type PanelMoveConfig, type PanelMoveState, type ParticleSystemConfig, type PoolStats, type PoolTask, type PositionCache, type PositionResolver, type PrevBounds, type QueuedInputEvent, type QueuedKeyEvent, type QueuedMouseEvent, type RenderContext, type ResizeHandle, type ScrollAnimationState, type ScrollEvent, type ScrollPhysicsConfig, type SpatialHashConfig, type SpatialHashGrid, type SpatialHashStats, type SpatialHashSystemState, type SyncHandler, type SystemTiming, type TaskPriority, type TaskResult, type TileMapBuffer, type TileMapCamera, type TileMapRendererConfig, type Viewport, type VirtualizedRenderContext, type WorkerPoolConfig, type WorkerPoolState, ageParticle, animationSystem, applyScrollImpulse, areColliding, beginMove, beginResize, blurAll, burstParticles, cameraSystem, cancelAllOfType, cancelMoveOrResize, cancelTask, captureMouseTo, cleanup, cleanupEntityResources, cleanupVirtualizedRenderSystem, clearAllScrollStates, clearDragConstraints, clearEntityInput, clearEventQueue, clearFocusStack, clearLineRenderConfig, clearOutputBuffer, clearOutputStream, clearPositionCache, clearRenderBuffer, clearScreen, clearSpatialHash, clearTileMapRenderBuffer, clearVirtualizedRenderBuffer, collisionSystem, computeLayoutNow, createAnimationSystem, createBehaviorSystem, createCameraSystem, createCollisionSystem, createDragSystem, createEmptyBuffer, createFocusSystem, createFrameBudgetManager, createIncrementalSpatialSystem, createInputSystem, createLayoutSystem, createMovementSystem, createOutputState, createOutputSystem, createPanelConstraints, createPanelMoveConfig, createPanelMoveState, createParticleSystem, createPositionCache, createRenderSystem, createSmoothScrollSystem, createSpatialHash, createSpatialHashSystem, createSpatialHashSystemState, createStateMachineSystem, createTilemapRenderSystem, createVirtualizedRenderSystem, createVisibilityCullingSystem, createWorkerPool, cursorHome, destroyFrameBudgetManager, destroyWorkerPool, detectCollisions, detectResizeHandle, endMoveOrResize, endUserScroll, enterAlternateScreen, exportFrameBudgetMetrics, focusEntity, focusFirst, focusLast, focusNext, focusOffset, focusPop, focusPrev, focusPush, focusSystem, generateOutput, getActiveCollisionCount, getActiveCollisions, getActiveTriggerCount, getActiveTriggers, getCollidingEntities, getCollisionEventBus, getComputedBounds, getComputedLayout, getDragConstraints, getDragVerifyCallback, getEntitiesAtPoint, getEntitiesInCell, getEventQueue, getFocusEventBus, getFocusStackDepth, getFocusableEntities, getFocused, getFrameBudgetStats, getInputEventBus, getInteractiveEntityAt, getLineRenderConfig, getLineStore, getMouseCaptureEntity, getNearbyEntities, getOutputBuffer, getOutputState, getOutputStream, getRenderBuffer, getScrollPosition, getScrollState, getSpatialDirtyCount, getSpatialHashGrid, getSpatialHashStats, getSpatialHashSystemState, getStateAgeStore, getSystemStateAge, getTileMapRenderBuffer, getTileMapRendererConfig, getTriggerZones, getViewportBounds, getVirtualizedRenderBuffer, getWorkerPoolState, hasAnimationSystem, hasComputedLayout, hasMovementSystem, hideCursor, hitTest, incrementalSpatialUpdate, inputState, inputSystem, insertEntity, invalidateAllLayouts, invalidateLayout, isColliding, isInTrigger, isMouseCaptured, isOcclusionCullingEnabled, isScrolling, keyboardMove, keyboardResize, killParticle, layoutSystem, leaveAlternateScreen, markAllDirty, markSpatialDirty, mergeDirtyRects, moveParticle, movementSystem, onBudgetAlert, outputSystem, peekFocusStack, performCulling, pointInEntity, profiledSystem, queryAnimation, queryArea, queryCameras, queryColliders, queryInputReceivers, queryMovement, queryStateMachine, queryVisibleEntities, queueKeyEvent, queueMouseEvent, rebuildSpatialHash, recordFrameBudgetSystemTime, recordFrameTime, recordPhaseTime, registerAnimationSystem, registerCameraSystem, registerCollisionSystem, registerInputSystem, registerLineStore, registerMovementSystem, registerStateMachineSystem, registerTaskHandler, releaseMouse, removeEntityFromGrid, removeFromCache, removeScrollState, renderAllTileMaps, renderBackground, renderBorder, renderContent, renderRect, renderScrollbar, renderSystem, renderText, renderTileMapToBuffer, resetAttributes, resetCollisionState, resetDragStores, resetFocusEventBus, resetFrameBudget, resetInputState, resetOutputState, resetSpatialHashState, resetStateAge, resetTileMapRenderer, restoreFocus, rewindFocus, saveFocus, setDragConstraints, setDragVerifyCallback, setLineRenderConfig, setOcclusionCulling, setOutputBuffer, setOutputStream, setRenderBuffer, setScrollImmediate, setSpatialDirtyThreshold, setSpatialHashGrid, setTileMapRendererConfig, setViewportBounds, setVirtualizedRenderBuffer, showCursor, smoothScrollTo, spatialHashSystem, spawnParticle, startUserScroll, stateMachineSystem, submitTask, tilemapRenderSystem, unregisterLineStore, updateAnimations, updateCameras, updateEntityIfMoved, updateLineStore, updateMove, updateMovements, updateResize, updateScrollPhysics, updateStateAges, virtualizedRenderSystem, worldToCell, writeRaw };