blecsd 0.4.0 → 0.6.0

package/dist/positioning-DiUivJXa.d.ts

@@ -0,0 +1,917 @@
+import { W as World, E as Entity } from './types-B8LmNkzG.js';
+import * as bitecs from 'bitecs';
+import { ComponentRef, QueryTerm, QueryResult } from 'bitecs';
+import { z } from 'zod';
+
+/**
+ * Entity disposal and cleanup system.
+ *
+ * Handles proper cleanup of entities including:
+ * - Deferred destruction (mark for destruction, process at frame end)
+ * - Hierarchy cleanup (remove from parent, destroy children)
+ * - Lifecycle event emission
+ * - Store cleanup
+ * - Entity recycling
+ *
+ * @module core/disposal
+ *
+ * @example
+ * ```typescript
+ * import { destroyEntity, destroyAllChildren, flushDestroyQueue } from 'blecsd';
+ *
+ * // Mark entity for destruction (deferred)
+ * destroyEntity(world, entity);
+ *
+ * // At end of frame, process all pending destructions
+ * flushDestroyQueue(world);
+ *
+ * // Or destroy immediately
+ * destroyEntity(world, entity, { immediate: true });
+ * ```
+ */
+
+/**
+ * Options for entity destruction.
+ */
+interface DestroyOptions {
+    /**
+     * If true, destroy immediately instead of deferring to end of frame.
+     * Use with caution as this may cause issues during iteration.
+     */
+    immediate?: boolean;
+    /**
+     * If true, also destroy all children recursively.
+     * Defaults to true.
+     */
+    destroyChildren?: boolean;
+    /**
+     * If true, emit destroy event before cleanup.
+     * Defaults to true.
+     */
+    emitEvent?: boolean;
+}
+/**
+ * Callback for custom cleanup when an entity is destroyed.
+ */
+type CleanupCallback = (world: World, entity: Entity) => void;
+/**
+ * Registers a cleanup callback that runs when any entity is destroyed.
+ *
+ * Use this to register store cleanup functions.
+ *
+ * @param callback - Function to call during entity cleanup
+ * @returns Function to unregister the callback
+ *
+ * @example
+ * ```typescript
+ * import { registerCleanupCallback } from 'blecsd';
+ *
+ * // Register cleanup for a custom store
+ * const unregister = registerCleanupCallback((world, entity) => {
+ *   myCustomStore.delete(entity);
+ * });
+ *
+ * // Later, unregister if needed
+ * unregister();
+ * ```
+ */
+declare function registerCleanupCallback(callback: CleanupCallback): () => void;
+/**
+ * Clears all registered cleanup callbacks.
+ * Primarily for testing.
+ */
+declare function clearCleanupCallbacks(): void;
+/**
+ * Marks an entity for destruction.
+ *
+ * By default, destruction is deferred to the end of the frame via
+ * `flushDestroyQueue()`. This prevents issues when destroying entities
+ * during iteration.
+ *
+ * @param world - The ECS world
+ * @param entity - The entity to destroy
+ * @param options - Destruction options
+ *
+ * @example
+ * ```typescript
+ * import { destroyEntity } from 'blecsd';
+ *
+ * // Deferred destruction (recommended)
+ * destroyEntity(world, entity);
+ *
+ * // Immediate destruction
+ * destroyEntity(world, entity, { immediate: true });
+ *
+ * // Don't destroy children
+ * destroyEntity(world, entity, { destroyChildren: false });
+ * ```
+ */
+declare function destroyEntity(world: World, entity: Entity, options?: DestroyOptions): void;
+/**
+ * Destroys all children of an entity without destroying the parent.
+ *
+ * @param world - The ECS world
+ * @param parent - The parent entity
+ * @param options - Destruction options (immediate applies to all children)
+ *
+ * @example
+ * ```typescript
+ * import { destroyAllChildren } from 'blecsd';
+ *
+ * // Clear all children from a container
+ * destroyAllChildren(world, container);
+ * ```
+ */
+declare function destroyAllChildren(world: World, parent: Entity, options?: DestroyOptions): void;
+/**
+ * Checks if an entity is marked for destruction.
+ *
+ * @param entity - The entity to check
+ * @returns true if entity is queued for destruction
+ */
+declare function isMarkedForDestruction(entity: Entity): boolean;
+/**
+ * Processes all entities marked for destruction.
+ *
+ * Should be called at the end of each frame, typically in POST_RENDER phase.
+ *
+ * @param world - The ECS world
+ * @returns Number of entities destroyed
+ *
+ * @example
+ * ```typescript
+ * import { flushDestroyQueue } from 'blecsd';
+ *
+ * // In your game loop's post-render phase:
+ * const destroyed = flushDestroyQueue(world);
+ * ```
+ */
+declare function flushDestroyQueue(world: World): number;
+/**
+ * Destroys all entities in a world.
+ *
+ * This performs immediate destruction of all entities.
+ *
+ * @param world - The ECS world to clear
+ *
+ * @example
+ * ```typescript
+ * import { destroyWorld } from 'blecsd';
+ *
+ * // Clean up everything before resetting
+ * destroyWorld(world);
+ * ```
+ */
+declare function destroyWorld(world: World): void;
+/**
+ * Gets the number of entities currently queued for destruction.
+ *
+ * @param world - Optional world to check (if not provided, returns global count)
+ * @returns Number of entities in destroy queue
+ */
+declare function getDestroyQueueSize(world?: World): number;
+/**
+ * Clears the destruction queue without destroying entities.
+ *
+ * Use with caution - entities will remain but won't be destroyed.
+ *
+ * @param world - The ECS world
+ */
+declare function clearDestroyQueue(world: World): void;
+/**
+ * Resets all disposal state.
+ * Primarily for testing.
+ */
+declare function resetDisposalState(): void;
+
+/**
+ * ECS World creation and management
+ * @module core/world
+ */
+
+/**
+ * Creates a new ECS world for the game.
+ *
+ * @returns A new World instance
+ *
+ * @example
+ * ```typescript
+ * import { createWorld } from 'blecsd';
+ *
+ * const world = createWorld();
+ * ```
+ */
+declare function createWorld(): World;
+/**
+ * Resets an existing world, removing all entities and resetting component data.
+ * Useful for level reloading or game restart.
+ *
+ * @param world - The world to reset
+ *
+ * @example
+ * ```typescript
+ * import { createWorld, resetWorld } from 'blecsd';
+ *
+ * const world = createWorld();
+ * // ... game runs ...
+ * resetWorld(world); // Clear everything for new game
+ * ```
+ */
+declare function resetWorld(world: World): void;
+
+/**
+ * Creates a new entity in the world.
+ *
+ * @param world - The ECS world to add the entity to
+ * @returns The newly created entity ID
+ *
+ * @example
+ * ```typescript
+ * import { createWorld, addEntity } from 'blecsd';
+ *
+ * const world = createWorld();
+ * const player = addEntity(world);
+ * const enemy = addEntity(world);
+ * ```
+ */
+declare function addEntity(world: World): Entity;
+/**
+ * Removes an entity and all its components from the world.
+ *
+ * @param world - The ECS world containing the entity
+ * @param eid - The entity ID to remove
+ *
+ * @example
+ * ```typescript
+ * import { createWorld, addEntity, removeEntity } from 'blecsd';
+ *
+ * const world = createWorld();
+ * const entity = addEntity(world);
+ * // ... use entity ...
+ * removeEntity(world, entity); // Clean up when done
+ * ```
+ */
+declare function removeEntity(world: World, eid: Entity): void;
+/**
+ * Checks if an entity exists in the world.
+ *
+ * @param world - The ECS world to check
+ * @param eid - The entity ID to check
+ * @returns True if the entity exists, false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { createWorld, addEntity, removeEntity, entityExists } from 'blecsd';
+ *
+ * const world = createWorld();
+ * const entity = addEntity(world);
+ *
+ * console.log(entityExists(world, entity)); // true
+ * removeEntity(world, entity);
+ * console.log(entityExists(world, entity)); // false
+ * ```
+ */
+declare function entityExists(world: World, eid: Entity): boolean;
+/**
+ * Gets all entity IDs currently in the world.
+ *
+ * @param world - The ECS world to query
+ * @returns Array of all entity IDs in the world
+ *
+ * @example
+ * ```typescript
+ * import { createWorld, addEntity, getAllEntities } from 'blecsd';
+ *
+ * const world = createWorld();
+ * addEntity(world);
+ * addEntity(world);
+ * addEntity(world);
+ *
+ * const entities = getAllEntities(world);
+ * console.log(entities.length); // 3
+ * ```
+ */
+declare function getAllEntities(world: World): readonly Entity[];
+/**
+ * Adds a component to an entity.
+ *
+ * @param world - The ECS world
+ * @param eid - The entity to add the component to
+ * @param component - The component to add
+ *
+ * @example
+ * ```typescript
+ * import { createWorld, addEntity, addComponent, Position } from 'blecsd';
+ *
+ * const world = createWorld();
+ * const entity = addEntity(world);
+ * addComponent(world, entity, Position);
+ * Position.x[entity] = 100;
+ * Position.y[entity] = 50;
+ * ```
+ */
+declare function addComponent(world: World, eid: Entity, component: ComponentRef): void;
+/**
+ * Checks if an entity has a specific component.
+ *
+ * @param world - The ECS world
+ * @param eid - The entity to check
+ * @param component - The component to check for
+ * @returns True if the entity has the component, false otherwise
+ *
+ * @example
+ * ```typescript
+ * import { createWorld, addEntity, addComponent, hasComponent, Position } from 'blecsd';
+ *
+ * const world = createWorld();
+ * const entity = addEntity(world);
+ *
+ * console.log(hasComponent(world, entity, Position)); // false
+ * addComponent(world, entity, Position);
+ * console.log(hasComponent(world, entity, Position)); // true
+ * ```
+ */
+declare function hasComponent(world: World, eid: Entity, component: ComponentRef): boolean;
+/**
+ * Removes a component from an entity.
+ *
+ * @param world - The ECS world
+ * @param eid - The entity to remove the component from
+ * @param component - The component to remove
+ *
+ * @example
+ * ```typescript
+ * import { createWorld, addEntity, addComponent, removeComponent, hasComponent, Position } from 'blecsd';
+ *
+ * const world = createWorld();
+ * const entity = addEntity(world);
+ * addComponent(world, entity, Position);
+ *
+ * console.log(hasComponent(world, entity, Position)); // true
+ * removeComponent(world, entity, Position);
+ * console.log(hasComponent(world, entity, Position)); // false
+ * ```
+ */
+declare function removeComponent(world: World, eid: Entity, component: ComponentRef): void;
+/**
+ * Queries the world for entities that have all specified components.
+ *
+ * @param world - The ECS world to query
+ * @param components - Array of components that entities must have
+ * @returns Array of entity IDs that match the query
+ *
+ * @example
+ * ```typescript
+ * import { createWorld, addEntity, addComponent, query, Position, Velocity } from 'blecsd';
+ *
+ * const world = createWorld();
+ *
+ * // Create entities with different component combinations
+ * const staticEntity = addEntity(world);
+ * addComponent(world, staticEntity, Position);
+ *
+ * const movingEntity = addEntity(world);
+ * addComponent(world, movingEntity, Position);
+ * addComponent(world, movingEntity, Velocity);
+ *
+ * // Query for entities with both Position and Velocity
+ * const movingEntities = query(world, [Position, Velocity]);
+ * console.log(movingEntities.length); // 1 (only movingEntity)
+ * ```
+ */
+declare function query(world: World, components: QueryTerm[]): QueryResult;
+/**
+ * Registers a component with the world. This is typically called automatically
+ * when components are first used, but can be useful for advanced scenarios.
+ *
+ * @param world - The ECS world
+ * @param component - The component to register
+ *
+ * @example
+ * ```typescript
+ * import { createWorld, registerComponent, Position } from 'blecsd';
+ *
+ * const world = createWorld();
+ * registerComponent(world, Position);
+ * ```
+ */
+declare const registerComponent: (world: bitecs.World, component: ComponentRef) => bitecs.ComponentData;
+/**
+ * Creates a component with a custom backing store. Useful for components that
+ * need special memory layouts or interop with external systems.
+ *
+ * @param store - Custom store object with typed arrays
+ * @returns A component that uses the provided store
+ *
+ * @example
+ * ```typescript
+ * import { withStore } from 'blecsd';
+ *
+ * // Create a component backed by custom Float32Arrays
+ * const CustomPosition = withStore({
+ *   x: new Float32Array(10000),
+ *   y: new Float32Array(10000),
+ * });
+ * ```
+ */
+declare const withStore: <T>(createStore: (eid: bitecs.EntityId) => T) => (relation: bitecs.Relation<T>) => bitecs.Relation<T>;
+
+/**
+ * Hit Test System with Z-Order Aware Clickable Sorting
+ *
+ * Provides efficient hit testing for mouse interactions, sorting clickable
+ * elements by z-index so the topmost element receives events first.
+ *
+ * @module core/hitTest
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createClickableCache,
+ *   hitTest,
+ *   hitTestAll,
+ *   invalidateClickableCache,
+ * } from 'blecsd';
+ *
+ * // Create cache for efficient hit testing
+ * const cache = createClickableCache();
+ *
+ * // Hit test at mouse position - returns topmost entity
+ * const topEntity = hitTest(world, mouseX, mouseY, cache);
+ *
+ * // Get all entities under point, sorted by z-index (highest first)
+ * const allEntities = hitTestAll(world, mouseX, mouseY, cache);
+ *
+ * // Invalidate cache when hierarchy changes
+ * invalidateClickableCache(cache);
+ * ```
+ */
+
+/**
+ * Cache for clickable element sorting.
+ *
+ * Maintains a sorted list of clickable/hoverable entities for efficient
+ * hit testing. The cache is invalidated when the hierarchy changes.
+ */
+interface ClickableCache {
+    /** Sorted entities (highest z-index first) */
+    entities: Entity[];
+    /** Whether cache needs rebuilding */
+    dirty: boolean;
+    /** Last known count for quick dirty check */
+    lastCount: number;
+}
+/**
+ * Result of a hit test operation.
+ */
+interface HitTestResult {
+    /** The entity under the point (topmost if multiple) */
+    readonly entity: Entity;
+    /** Z-index of the entity */
+    readonly zIndex: number;
+}
+/**
+ * Options for hit testing.
+ */
+interface HitTestOptions {
+    /** Use cached positions for faster testing (default: true) */
+    useCachedPositions?: boolean;
+    /** Only test clickable entities (default: true) */
+    clickableOnly?: boolean;
+    /** Only test hoverable entities (default: false) */
+    hoverableOnly?: boolean;
+    /** Test both clickable and hoverable (default: false) */
+    interactiveOnly?: boolean;
+}
+/**
+ * Creates a new clickable cache.
+ *
+ * The cache stores a z-index sorted list of interactive entities
+ * for efficient hit testing.
+ *
+ * @returns A new ClickableCache
+ *
+ * @example
+ * ```typescript
+ * import { createClickableCache } from 'blecsd';
+ *
+ * const cache = createClickableCache();
+ * ```
+ */
+declare function createClickableCache(): ClickableCache;
+/**
+ * Marks the clickable cache as needing rebuild.
+ *
+ * Call this when:
+ * - Entities are added or removed
+ * - Z-index values change
+ * - Interactive state changes (clickable/hoverable toggled)
+ *
+ * @param cache - The clickable cache
+ *
+ * @example
+ * ```typescript
+ * import { invalidateClickableCache } from 'blecsd';
+ *
+ * // After adding a new clickable entity
+ * invalidateClickableCache(cache);
+ * ```
+ */
+declare function invalidateClickableCache(cache: ClickableCache): void;
+/**
+ * Checks if the cache needs rebuilding.
+ *
+ * @param cache - The clickable cache
+ * @returns true if cache is dirty
+ */
+declare function isCacheDirty(cache: ClickableCache): boolean;
+/**
+ * Rebuilds the clickable cache if needed.
+ *
+ * Queries for all interactive entities and sorts them by z-index
+ * in descending order (highest z-index first for hit testing).
+ *
+ * @param world - The ECS world
+ * @param cache - The clickable cache
+ *
+ * @example
+ * ```typescript
+ * import { updateClickableCache } from 'blecsd';
+ *
+ * // Rebuild cache before hit testing
+ * updateClickableCache(world, cache);
+ * ```
+ */
+declare function updateClickableCache(world: World, cache: ClickableCache): void;
+/**
+ * Gets the current sorted clickable entities from cache.
+ *
+ * @param world - The ECS world
+ * @param cache - The clickable cache
+ * @returns Array of entities sorted by z-index (highest first)
+ */
+declare function getClickableEntities(world: World, cache: ClickableCache): readonly Entity[];
+/**
+ * Gets the count of clickable entities.
+ *
+ * @param world - The ECS world
+ * @param cache - The clickable cache
+ * @returns Number of clickable/hoverable entities
+ */
+declare function getClickableCount(world: World, cache: ClickableCache): number;
+declare function hitTest(world: World, x: number, y: number, cache?: ClickableCache, options?: HitTestOptions): Entity | null;
+/**
+ * Performs a hit test and returns all entities at the point.
+ *
+ * Returns entities sorted by z-index (highest first).
+ *
+ * @param world - The ECS world
+ * @param x - Screen X coordinate
+ * @param y - Screen Y coordinate
+ * @param cache - Optional clickable cache for efficiency
+ * @param options - Hit test options
+ * @returns Array of entities at the point, sorted by z-index (highest first)
+ *
+ * @example
+ * ```typescript
+ * import { hitTestAll, createClickableCache } from 'blecsd';
+ *
+ * const cache = createClickableCache();
+ *
+ * // Get all entities under mouse position
+ * const entities = hitTestAll(world, mouseX, mouseY, cache);
+ *
+ * for (const eid of entities) {
+ *   console.log(`Entity ${eid} at z=${getZIndex(world, eid)}`);
+ * }
+ * ```
+ */
+declare function hitTestAll(world: World, x: number, y: number, cache?: ClickableCache, options?: HitTestOptions): Entity[];
+/**
+ * Performs a hit test with detailed results.
+ *
+ * @param world - The ECS world
+ * @param x - Screen X coordinate
+ * @param y - Screen Y coordinate
+ * @param cache - Optional clickable cache for efficiency
+ * @param options - Hit test options
+ * @returns Array of HitTestResults with entity and z-index
+ *
+ * @example
+ * ```typescript
+ * import { hitTestDetailed, createClickableCache } from 'blecsd';
+ *
+ * const cache = createClickableCache();
+ *
+ * const results = hitTestDetailed(world, mouseX, mouseY, cache);
+ * for (const { entity, zIndex } of results) {
+ *   console.log(`Entity ${entity} at z=${zIndex}`);
+ * }
+ * ```
+ */
+declare function hitTestDetailed(world: World, x: number, y: number, cache?: ClickableCache, options?: HitTestOptions): HitTestResult[];
+/**
+ * Checks if any clickable entity is under the point.
+ *
+ * @param world - The ECS world
+ * @param x - Screen X coordinate
+ * @param y - Screen Y coordinate
+ * @param cache - Optional clickable cache
+ * @returns true if any clickable entity is under the point
+ */
+declare function hasClickableAt(world: World, x: number, y: number, cache?: ClickableCache): boolean;
+/**
+ * Checks if any hoverable entity is under the point.
+ *
+ * @param world - The ECS world
+ * @param x - Screen X coordinate
+ * @param y - Screen Y coordinate
+ * @param cache - Optional clickable cache
+ * @returns true if any hoverable entity is under the point
+ */
+declare function hasHoverableAt(world: World, x: number, y: number, cache?: ClickableCache): boolean;
+/**
+ * Gets the topmost clickable entity at a point.
+ *
+ * Convenience wrapper for hitTest with clickableOnly=true.
+ *
+ * @param world - The ECS world
+ * @param x - Screen X coordinate
+ * @param y - Screen Y coordinate
+ * @param cache - Optional clickable cache
+ * @returns Topmost clickable entity or null
+ */
+declare function getClickableAt(world: World, x: number, y: number, cache?: ClickableCache): Entity | null;
+/**
+ * Gets the topmost hoverable entity at a point.
+ *
+ * Convenience wrapper for hitTest with hoverableOnly=true.
+ *
+ * @param world - The ECS world
+ * @param x - Screen X coordinate
+ * @param y - Screen Y coordinate
+ * @param cache - Optional clickable cache
+ * @returns Topmost hoverable entity or null
+ */
+declare function getHoverableAt(world: World, x: number, y: number, cache?: ClickableCache): Entity | null;
+/**
+ * Gets all clickable entities at a point.
+ *
+ * @param world - The ECS world
+ * @param x - Screen X coordinate
+ * @param y - Screen Y coordinate
+ * @param cache - Optional clickable cache
+ * @returns Array of clickable entities (highest z-index first)
+ */
+declare function getAllClickablesAt(world: World, x: number, y: number, cache?: ClickableCache): Entity[];
+/**
+ * Gets all hoverable entities at a point.
+ *
+ * @param world - The ECS world
+ * @param x - Screen X coordinate
+ * @param y - Screen Y coordinate
+ * @param cache - Optional clickable cache
+ * @returns Array of hoverable entities (highest z-index first)
+ */
+declare function getAllHoverablesAt(world: World, x: number, y: number, cache?: ClickableCache): Entity[];
+
+/**
+ * Advanced positioning system with percentage and expression support.
+ * Resolves position values to absolute coordinates.
+ * @module core/positioning
+ */
+
+/**
+ * Position value types supported by the positioning system.
+ * - number: absolute position in cells
+ * - string: percentage ('50%'), expression ('50%-5'), or keyword ('center', 'half')
+ */
+type PositionValue = number | string;
+/**
+ * Schema for validating position values.
+ * Accepts numbers, percentage strings, expressions, and keywords.
+ *
+ * @example
+ * ```typescript
+ * import { PositionValueSchema } from 'blecsd';
+ *
+ * PositionValueSchema.parse(10);        // Valid: absolute
+ * PositionValueSchema.parse('50%');     // Valid: percentage
+ * PositionValueSchema.parse('50%-5');   // Valid: expression
+ * PositionValueSchema.parse('center');  // Valid: keyword
+ * ```
+ */
+declare const PositionValueSchema: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+/**
+ * Resolves a position value to an absolute coordinate.
+ *
+ * Supports:
+ * - Numbers: returned as-is
+ * - Percentages: '50%' → parentSize * 0.5
+ * - Expressions: '50%-5' → (parentSize * 0.5) - 5
+ * - Keywords:
+ *   - 'center': (parentSize - elementSize) / 2
+ *   - 'half': parentSize / 2
+ *   - 'left'/'top': 0
+ *   - 'right'/'bottom': parentSize - elementSize
+ *
+ * @param value - Position value to resolve
+ * @param parentSize - Size of the parent container
+ * @param elementSize - Size of the element (for centering)
+ * @returns Resolved absolute position
+ *
+ * @example
+ * ```typescript
+ * import { parsePosition } from 'blecsd';
+ *
+ * // Absolute position
+ * parsePosition(10, 100, 20); // 10
+ *
+ * // Percentage
+ * parsePosition('50%', 100, 20); // 50
+ *
+ * // Expression
+ * parsePosition('50%-5', 100, 20); // 45
+ * parsePosition('100%-10', 100, 20); // 90
+ *
+ * // Keywords
+ * parsePosition('center', 100, 20); // 40 ((100-20)/2)
+ * parsePosition('half', 100, 20); // 50 (100/2)
+ * parsePosition('right', 100, 20); // 80 (100-20)
+ * ```
+ */
+declare function parsePosition(value: PositionValue, parentSize: number, elementSize?: number): number;
+/**
+ * Resolves a position value that may be negative (from right/bottom edge).
+ * Negative values are converted to offsets from the opposite edge.
+ *
+ * @param value - Position value to resolve
+ * @param parentSize - Size of the parent container
+ * @param elementSize - Size of the element
+ * @returns Resolved absolute position
+ *
+ * @example
+ * ```typescript
+ * import { parsePositionWithNegative } from 'blecsd';
+ *
+ * // Positive values work normally
+ * parsePositionWithNegative(10, 100, 20); // 10
+ *
+ * // Negative values are from the right/bottom
+ * parsePositionWithNegative(-10, 100, 20); // 70 (100 - 10 - 20)
+ * parsePositionWithNegative(-5, 100, 10); // 85 (100 - 5 - 10)
+ * ```
+ */
+declare function parsePositionWithNegative(value: PositionValue, parentSize: number, elementSize?: number): number;
+/**
+ * Validates that a position value is within valid bounds.
+ *
+ * @param value - Resolved position value
+ * @param parentSize - Size of the parent container
+ * @param elementSize - Size of the element
+ * @returns Clamped position value within bounds
+ *
+ * @example
+ * ```typescript
+ * import { clampPosition } from 'blecsd';
+ *
+ * clampPosition(-10, 100, 20); // 0 (can't be negative)
+ * clampPosition(90, 100, 20); // 80 (element must fit)
+ * clampPosition(50, 100, 20); // 50 (within bounds)
+ * ```
+ */
+declare function clampPosition(value: number, parentSize: number, elementSize?: number): number;
+/**
+ * Checks if a position value is a percentage or expression containing a percentage.
+ *
+ * @param value - Position value to check
+ * @returns true if the value contains a percentage
+ *
+ * @example
+ * ```typescript
+ * import { isPercentagePosition } from 'blecsd';
+ *
+ * isPercentagePosition('50%'); // true
+ * isPercentagePosition('50%-5'); // true
+ * isPercentagePosition(50); // false
+ * isPercentagePosition('center'); // false
+ * ```
+ */
+declare function isPercentagePosition(value: PositionValue): boolean;
+/**
+ * Checks if a position value is a keyword.
+ *
+ * @param value - Position value to check
+ * @returns true if the value is a position keyword
+ *
+ * @example
+ * ```typescript
+ * import { isKeywordPosition } from 'blecsd';
+ *
+ * isKeywordPosition('center'); // true
+ * isKeywordPosition('half'); // true
+ * isKeywordPosition('50%'); // false
+ * isKeywordPosition(50); // false
+ * ```
+ */
+declare function isKeywordPosition(value: PositionValue): boolean;
+/**
+ * Creates a position value that centers an element.
+ *
+ * @returns 'center' keyword
+ *
+ * @example
+ * ```typescript
+ * import { centerPosition, parsePosition } from 'blecsd';
+ *
+ * const pos = centerPosition();
+ * const resolved = parsePosition(pos, 100, 20); // 40
+ * ```
+ */
+declare function centerPosition(): 'center';
+/**
+ * Creates a percentage position value.
+ *
+ * @param percent - Percentage value (0-100)
+ * @returns Percentage string
+ *
+ * @example
+ * ```typescript
+ * import { percentPosition, parsePosition } from 'blecsd';
+ *
+ * const pos = percentPosition(50);
+ * const resolved = parsePosition(pos, 100, 0); // 50
+ * ```
+ */
+declare function percentPosition(percent: number): string;
+/**
+ * Creates a percentage position with an offset.
+ *
+ * @param percent - Percentage value (0-100)
+ * @param offset - Offset to add (negative to subtract)
+ * @returns Expression string
+ *
+ * @example
+ * ```typescript
+ * import { percentOffsetPosition, parsePosition } from 'blecsd';
+ *
+ * const pos = percentOffsetPosition(50, -5);
+ * const resolved = parsePosition(pos, 100, 0); // 45
+ *
+ * const pos2 = percentOffsetPosition(100, -10);
+ * const resolved2 = parsePosition(pos2, 100, 0); // 90
+ * ```
+ */
+declare function percentOffsetPosition(percent: number, offset: number): string;
+/**
+ * Resolves both X and Y position values at once.
+ *
+ * @param x - X position value
+ * @param y - Y position value
+ * @param parentWidth - Parent container width
+ * @param parentHeight - Parent container height
+ * @param elementWidth - Element width (for centering)
+ * @param elementHeight - Element height (for centering)
+ * @returns Resolved { x, y } coordinates
+ *
+ * @example
+ * ```typescript
+ * import { resolvePosition } from 'blecsd';
+ *
+ * const pos = resolvePosition('center', 'center', 100, 80, 20, 10);
+ * // pos = { x: 40, y: 35 }
+ *
+ * const pos2 = resolvePosition('50%-5', '100%-10', 100, 80, 0, 0);
+ * // pos2 = { x: 45, y: 70 }
+ * ```
+ */
+declare function resolvePosition(x: PositionValue, y: PositionValue, parentWidth: number, parentHeight: number, elementWidth?: number, elementHeight?: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Resolves position values and clamps them to valid bounds.
+ *
+ * @param x - X position value
+ * @param y - Y position value
+ * @param parentWidth - Parent container width
+ * @param parentHeight - Parent container height
+ * @param elementWidth - Element width
+ * @param elementHeight - Element height
+ * @returns Resolved and clamped { x, y } coordinates
+ *
+ * @example
+ * ```typescript
+ * import { resolvePositionClamped } from 'blecsd';
+ *
+ * // Position that would go off-screen is clamped
+ * const pos = resolvePositionClamped('100%', '100%', 100, 80, 20, 10);
+ * // pos = { x: 80, y: 70 } (clamped so element fits)
+ * ```
+ */
+declare function resolvePositionClamped(x: PositionValue, y: PositionValue, parentWidth: number, parentHeight: number, elementWidth?: number, elementHeight?: number): {
+    x: number;
+    y: number;
+};
+
+export { withStore as $, getHoverableAt as A, hasClickableAt as B, type CleanupCallback as C, type DestroyOptions as D, hasHoverableAt as E, hitTestAll as F, hitTestDetailed as G, type HitTestResult as H, invalidateClickableCache as I, isCacheDirty as J, isKeywordPosition as K, isMarkedForDestruction as L, isPercentagePosition as M, parsePosition as N, parsePositionWithNegative as O, type PositionValue as P, percentOffsetPosition as Q, percentPosition as R, query as S, registerCleanupCallback as T, registerComponent as U, removeComponent as V, resetDisposalState as W, resetWorld as X, resolvePosition as Y, resolvePositionClamped as Z, updateClickableCache as _, PositionValueSchema as a, addComponent as b, addEntity as c, createWorld as d, destroyWorld as e, hitTest as f, type ClickableCache as g, hasComponent as h, type HitTestOptions as i, centerPosition as j, clampPosition as k, clearCleanupCallbacks as l, clearDestroyQueue as m, createClickableCache as n, destroyAllChildren as o, destroyEntity as p, entityExists as q, removeEntity as r, flushDestroyQueue as s, getAllClickablesAt as t, getAllEntities as u, getAllHoverablesAt as v, getClickableAt as w, getClickableCount as x, getClickableEntities as y, getDestroyQueueSize as z };