blecsd 0.2.0 → 0.4.0

package/dist/dirtyTracking-C4v8MmM9.d.ts

@@ -0,0 +1,235 @@
+import { E as Entity, W as World } from './types-CPB4CpbH.js';
+
+/**
+ * Unified dirty tracking system for efficient rendering.
+ * Combines entity-level tracking with cell-level bitsets for optimal performance.
+ *
+ * @module core/dirtyTracking
+ *
+ * @example
+ * ```typescript
+ * import { createDirtyTracker, markEntityDirty, getDirtyRegions } from 'blecsd';
+ *
+ * // Create tracker
+ * const tracker = createDirtyTracker(80, 24);
+ *
+ * // Mark entity as dirty (automatically tracks bounds)
+ * markEntityDirty(tracker, world, entityId);
+ *
+ * // Get dirty regions for rendering
+ * const regions = getDirtyRegions(tracker);
+ * for (const rect of regions) {
+ *   renderRect(rect.x, rect.y, rect.width, rect.height);
+ * }
+ *
+ * // Clear after rendering
+ * clearDirtyTracking(tracker);
+ * ```
+ */
+
+/**
+ * Rectangle representing a dirty region.
+ */
+interface DirtyRect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * Cached entity bounds for motion detection.
+ * @internal
+ */
+interface EntityBoundsCache {
+    prevX: number;
+    prevY: number;
+    prevWidth: number;
+    prevHeight: number;
+    wasVisible: boolean;
+}
+/**
+ * Unified dirty tracker combining entity-level and cell-level tracking.
+ */
+interface DirtyTracker {
+    /** Screen width in cells */
+    readonly width: number;
+    /** Screen height in cells */
+    readonly height: number;
+    /** Bitset for dirty cells (one bit per cell) */
+    readonly dirtyCells: Uint8Array;
+    /** Set of dirty entities */
+    readonly dirtyEntities: Set<Entity>;
+    /** Cache of previous entity bounds */
+    readonly entityBoundsCache: Map<Entity, EntityBoundsCache>;
+    /** Computed dirty regions (lazily calculated) */
+    readonly dirtyRegions: DirtyRect[];
+    /** Whether dirtyRegions needs recalculation */
+    regionsStale: boolean;
+    /** Force full screen redraw */
+    forceFullRedraw: boolean;
+    /** Frame counter for debugging */
+    frameCount: number;
+}
+/**
+ * Creates a new unified dirty tracker.
+ *
+ * @param width - Screen width in cells
+ * @param height - Screen height in cells
+ * @returns New dirty tracker instance
+ *
+ * @example
+ * ```typescript
+ * const tracker = createDirtyTracker(80, 24);
+ * ```
+ */
+declare function createDirtyTracker(width: number, height: number): DirtyTracker;
+/**
+ * Marks an entity as dirty, tracking its bounds for optimal region calculation.
+ *
+ * @param tracker - Dirty tracker instance
+ * @param world - ECS world
+ * @param eid - Entity ID
+ *
+ * @example
+ * ```typescript
+ * // Entity moved or changed - mark it dirty
+ * markEntityDirty(tracker, world, boxEntity);
+ * ```
+ */
+declare function markEntityDirty(tracker: DirtyTracker, world: World, eid: Entity): void;
+/**
+ * Removes an entity from dirty tracking (call when entity is destroyed).
+ *
+ * @param tracker - Dirty tracker instance
+ * @param eid - Entity ID
+ *
+ * @example
+ * ```typescript
+ * // Entity destroyed - clean up tracking
+ * removeEntityFromTracking(tracker, destroyedEntity);
+ * ```
+ */
+declare function removeEntityFromTracking(tracker: DirtyTracker, eid: Entity): void;
+/**
+ * Marks a single cell as dirty using bitset.
+ *
+ * @param tracker - Dirty tracker instance
+ * @param x - Cell X coordinate
+ * @param y - Cell Y coordinate
+ *
+ * @example
+ * ```typescript
+ * // Mark specific cell dirty
+ * markCellDirty(tracker, 10, 5);
+ * ```
+ */
+declare function markCellDirty(tracker: DirtyTracker, x: number, y: number): void;
+/**
+ * Checks if a cell is marked dirty.
+ *
+ * @param tracker - Dirty tracker instance
+ * @param x - Cell X coordinate
+ * @param y - Cell Y coordinate
+ * @returns True if cell is dirty
+ *
+ * @example
+ * ```typescript
+ * if (isCellDirty(tracker, 10, 5)) {
+ *   // Cell needs redraw
+ * }
+ * ```
+ */
+declare function isCellDirty(tracker: DirtyTracker, x: number, y: number): boolean;
+/**
+ * Marks a rectangular region as dirty using cell bitsets.
+ *
+ * @param tracker - Dirty tracker instance
+ * @param x - Region X coordinate
+ * @param y - Region Y coordinate
+ * @param width - Region width
+ * @param height - Region height
+ *
+ * @example
+ * ```typescript
+ * // Mark 10x5 region dirty
+ * markRegionDirty(tracker, 0, 0, 10, 5);
+ * ```
+ */
+declare function markRegionDirty(tracker: DirtyTracker, x: number, y: number, width: number, height: number): void;
+/**
+ * Converts bitset dirty cells into coalesced rectangular regions.
+ * Uses scanline algorithm for efficient region merging.
+ *
+ * @param tracker - Dirty tracker instance
+ * @returns Array of dirty rectangles
+ *
+ * @example
+ * ```typescript
+ * const regions = getDirtyRegions(tracker);
+ * for (const rect of regions) {
+ *   console.log(`Dirty: ${rect.x},${rect.y} ${rect.width}x${rect.height}`);
+ * }
+ * ```
+ */
+declare function getDirtyRegions(tracker: DirtyTracker): readonly DirtyRect[];
+/**
+ * Checks if tracker has any dirty regions.
+ *
+ * @param tracker - Dirty tracker instance
+ * @returns True if any cells are dirty
+ *
+ * @example
+ * ```typescript
+ * if (hasDirtyRegions(tracker)) {
+ *   render();
+ * }
+ * ```
+ */
+declare function hasDirtyRegions(tracker: DirtyTracker): boolean;
+/**
+ * Clears all dirty tracking state after rendering.
+ *
+ * @param tracker - Dirty tracker instance
+ *
+ * @example
+ * ```typescript
+ * // After rendering
+ * render(getDirtyRegions(tracker));
+ * clearDirtyTracking(tracker);
+ * ```
+ */
+declare function clearDirtyTracking(tracker: DirtyTracker): void;
+/**
+ * Forces a full screen redraw on next render.
+ *
+ * @param tracker - Dirty tracker instance
+ *
+ * @example
+ * ```typescript
+ * // Terminal resized - force full redraw
+ * forceFullRedraw(tracker);
+ * ```
+ */
+declare function forceFullRedraw(tracker: DirtyTracker): void;
+/**
+ * Gets debug statistics about dirty tracking state.
+ *
+ * @param tracker - Dirty tracker instance
+ * @returns Debug statistics
+ *
+ * @example
+ * ```typescript
+ * const stats = getDirtyTrackingStats(tracker);
+ * console.log(`Dirty cells: ${stats.dirtyCellCount}`);
+ * console.log(`Dirty entities: ${stats.dirtyEntityCount}`);
+ * ```
+ */
+declare function getDirtyTrackingStats(tracker: DirtyTracker): {
+    readonly dirtyCellCount: number;
+    readonly dirtyEntityCount: number;
+    readonly cachedEntityCount: number;
+    readonly dirtyRegionCount: number;
+    readonly frameCount: number;
+};
+
+export { type DirtyTracker as D, createDirtyTracker as a, getDirtyTrackingStats as b, clearDirtyTracking as c, markEntityDirty as d, markRegionDirty as e, forceFullRedraw as f, getDirtyRegions as g, hasDirtyRegions as h, isCellDirty as i, type DirtyRect as j, markCellDirty as m, removeEntityFromTracking as r };

package/dist/errors/index.d.ts

@@ -342,19 +342,19 @@ type BlECSdErrorKind = 'validation' | 'terminal' | 'system' | 'entity' | 'compon
  */
 interface ErrorContext {
     /** The entity ID involved (if applicable) */
-    readonly entityId?: number;
+    readonly entityId?: number | undefined;
     /** The component name involved (if applicable) */
-    readonly componentName?: string;
+    readonly componentName?: string | undefined;
     /** The system name involved (if applicable) */
-    readonly systemName?: string;
+    readonly systemName?: string | undefined;
     /** The file path involved (if applicable) */
-    readonly filePath?: string;
+    readonly filePath?: string | undefined;
     /** The function name where error occurred */
-    readonly functionName?: string;
+    readonly functionName?: string | undefined;
     /** Additional data for debugging */
-    readonly data?: Readonly<Record<string, unknown>>;
+    readonly data?: Readonly<Record<string, unknown>> | undefined;
     /** Zod validation issues (for validation errors) */
-    readonly zodIssues?: readonly core.$ZodIssue[];
+    readonly zodIssues?: readonly core.$ZodIssue[] | undefined;
 }
 /**
  * Base error data common to all BlECSd errors.
@@ -369,9 +369,9 @@ interface BlECSdErrorBase<K extends BlECSdErrorKind, C extends BlECSdErrorCodeTy
     /** Timestamp when error was created */
     readonly timestamp: number;
     /** Original cause (if wrapping another error) */
-    readonly cause?: Error;
+    readonly cause?: Error | undefined;
     /** Additional context for debugging */
-    readonly context?: ErrorContext;
+    readonly context?: ErrorContext | undefined;
 }
 /**
  * Validation error for input/config validation failures.
@@ -459,16 +459,16 @@ interface NativeBlECSdError extends Error {
  */
 interface ErrorOptions {
     /** Original cause (if wrapping another error) */
-    readonly cause?: Error;
+    readonly cause?: Error | undefined;
     /** Additional context for debugging */
-    readonly context?: ErrorContext;
+    readonly context?: ErrorContext | undefined;
 }
 /**
  * Options for validation errors with Zod issues.
  */
 interface ValidationErrorOptions extends ErrorOptions {
     /** Zod validation issues */
-    readonly zodIssues?: readonly core.$ZodIssue[];
+    readonly zodIssues?: readonly core.$ZodIssue[] | undefined;
 }
 /**
  * Creates a validation error.

package/dist/errors/index.js

@@ -1 +1 @@
-export{a as BLECSD_ERROR_SYMBOL,k as BlECSdErrorCode,f as ComponentErrorCode,i as ConfigErrorCode,e as EntityErrorCode,g as InputErrorCode,j as InternalErrorCode,h as RenderErrorCode,d as SystemErrorCode,c as TerminalErrorCode,b as ValidationErrorCode,p as createComponentError,s as createConfigError,o as createEntityError,q as createInputError,t as createInternalError,r as createRenderError,n as createSystemError,m as createTerminalError,l as createValidationError,O as err,W as flatMap,v as fromNativeError,J as hasBlECSdErrorShape,L as hasCause,K as hasContext,H as hasErrorCode,M as hasZodIssues,I as isBlECSdError,B as isComponentError,E as isConfigError,A as isEntityError,Q as isErr,G as isErrorKind,C as isInputError,F as isInternalError,P as isOk,D as isRenderError,z as isSystemError,y as isTerminalError,x as isValidationError,U as map,V as mapError,N as ok,u as toNativeError,R as unwrap,S as unwrapOr,T as unwrapOrElse,w as wrapError}from'../chunk-3B7MIVW6.js';import'../chunk-5PELJRUQ.js';
+export{a as BLECSD_ERROR_SYMBOL,k as BlECSdErrorCode,f as ComponentErrorCode,i as ConfigErrorCode,e as EntityErrorCode,g as InputErrorCode,j as InternalErrorCode,h as RenderErrorCode,d as SystemErrorCode,c as TerminalErrorCode,b as ValidationErrorCode,p as createComponentError,s as createConfigError,o as createEntityError,q as createInputError,t as createInternalError,r as createRenderError,n as createSystemError,m as createTerminalError,l as createValidationError,O as err,W as flatMap,v as fromNativeError,J as hasBlECSdErrorShape,L as hasCause,K as hasContext,H as hasErrorCode,M as hasZodIssues,I as isBlECSdError,B as isComponentError,E as isConfigError,A as isEntityError,Q as isErr,G as isErrorKind,C as isInputError,F as isInternalError,P as isOk,D as isRenderError,z as isSystemError,y as isTerminalError,x as isValidationError,U as map,V as mapError,N as ok,u as toNativeError,R as unwrap,S as unwrapOr,T as unwrapOrElse,w as wrapError}from'../chunk-RZ7FGVI6.js';import'../chunk-5PELJRUQ.js';

package/dist/{events-BbbxkgvX.d.ts → events-9ForpTfM.d.ts}

@@ -1,4 +1,4 @@
-import { U as Unsubscribe } from './types-BcsvoKzf.js';
+import { U as Unsubscribe, W as World, E as Entity } from './types-CPB4CpbH.js';
 
 /**
  * Typed EventEmitter implementation for type-safe event handling
@@ -85,6 +85,12 @@ interface ScreenEventMap {
         frameTime: number;
     };
     destroy: Record<string, never>;
+    warning: {
+        type: string;
+        message: string;
+        metadata: Record<string, unknown>;
+        timestamp: number;
+    };
 }
 /**
  * Type-safe EventBus interface.
@@ -121,5 +127,72 @@ interface EventBus<T extends EventMap> {
  * ```
  */
 declare function createEventBus<T extends EventMap>(): EventBus<T>;
+/**
+ * Function type for getting an EventBus for a specific entity.
+ * Returns undefined if the entity has no event bus.
+ *
+ * @typeParam T - Event map type
+ * @param world - The ECS world
+ * @param eid - The entity ID
+ * @returns The entity's EventBus, or undefined if none exists
+ *
+ * @example
+ * ```typescript
+ * import { createEventBus, type GetEntityEventBus } from 'blecsd';
+ *
+ * const entityBuses = new Map<Entity, EventBus<MyEvents>>();
+ * const getEventBus: GetEntityEventBus<MyEvents> = (world, eid) => entityBuses.get(eid);
+ * ```
+ */
+type GetEntityEventBus<T extends EventMap> = (world: World, eid: Entity) => EventBus<T> | undefined;
+/**
+ * Store for entity event buses.
+ * Maps entity IDs to their event buses.
+ *
+ * @typeParam T - Event map type
+ */
+interface EntityEventBusStore<T extends EventMap> {
+    /** Gets the event bus for an entity */
+    get(world: World, eid: Entity): EventBus<T> | undefined;
+    /** Gets or creates an event bus for an entity */
+    getOrCreate(world: World, eid: Entity): EventBus<T>;
+    /** Sets the event bus for an entity */
+    set(world: World, eid: Entity, eventBus: EventBus<T>): void;
+    /** Checks if an entity has an event bus */
+    has(world: World, eid: Entity): boolean;
+    /** Removes the event bus for an entity */
+    delete(world: World, eid: Entity): boolean;
+    /** Clears all event buses */
+    clear(): void;
+}
+/**
+ * Creates a simple entity event bus store using a Map.
+ * Provides a centralized way to manage EventBus instances per entity.
+ *
+ * @typeParam T - Event map type
+ * @returns A new EntityEventBusStore instance
+ *
+ * @example
+ * ```typescript
+ * import { createEntityEventBusStore, createEventBus } from 'blecsd';
+ *
+ * interface MyEvents {
+ *   click: { x: number; y: number };
+ *   focus: Record<string, never>;
+ * }
+ *
+ * const store = createEntityEventBusStore<MyEvents>();
+ *
+ * // Get or create a bus for an entity
+ * const bus = store.getOrCreate(world, entityId);
+ * bus.on('click', (e) => console.log('clicked at', e.x, e.y));
+ *
+ * // Check if entity has a bus
+ * if (store.has(world, entityId)) {
+ *   const existingBus = store.get(world, entityId);
+ * }
+ * ```
+ */
+declare function createEntityEventBusStore<T extends EventMap>(): EntityEventBusStore<T>;
 
-export { type EventBus as E, type ScreenEventMap as S, type UIEventMap as U, type EventHandler as a, type EventMap as b, createEventBus as c };
+export { type EntityEventBusStore as E, type GetEntityEventBus as G, type ScreenEventMap as S, type UIEventMap as U, type EventBus as a, type EventHandler as b, type EventMap as c, createEntityEventBusStore as d, createEventBus as e };

package/dist/game/index.d.ts

@@ -1,13 +1,13 @@
 import { z } from 'zod';
-import { I as InputEventBufferData, a as InputState, B as BoxConfig, T as TextConfig, b as ButtonConfig, c as InputConfig, d as TextareaConfig, e as TextboxConfig, C as CheckboxConfig, R as RadioButtonConfig, f as RadioSetConfig, S as SelectConfig, g as SliderConfig, P as ProgressBarConfig, L as ListConfig, F as FormConfig, A as ActionBinding } from '../inputActions-CefRUBuT.js';
-import { G as GameLoop, L as LoopStats } from '../gameLoop-BIPW7-OY.js';
-import { W as World, E as Entity, U as Unsubscribe, L as LoopPhase, S as System } from '../types-BcsvoKzf.js';
-import { M as MouseEvent } from '../mouseParser-Cfrbn3AX.js';
+import { W as World, E as Entity, U as Unsubscribe, L as LoopPhase, S as System } from '../types-CPB4CpbH.js';
+import { I as InputEventBufferData, a as InputState, B as BoxConfig, T as TextConfig, b as ButtonConfig, c as InputConfig, d as TextareaConfig, e as TextboxConfig, C as CheckboxConfig, R as RadioButtonConfig, f as RadioSetConfig, S as SelectConfig, g as SliderConfig, P as ProgressBarConfig, L as ListConfig, F as FormConfig, A as ActionBinding } from '../inputActions-Fyw14_Gm.js';
+import { G as GameLoop, L as LoopStats } from '../gameLoop-CSTb7e0L.js';
+import { K as KeyName } from '../keyParser-m7fWto6g.js';
+import { M as MouseEvent } from '../mouseParser-B7p5ow7K.js';
 import { K as KeyEvent } from '../program-BZaKqDKH.js';
-import { K as KeyName } from '../keyParser-Bwm8-l7v.js';
-import '../border-D_Jb4ZJV.js';
-import '../scheduler-DcfoFuum.js';
 import 'bitecs';
+import '../border-DGNDfT6T.js';
+import '../scheduler-DeeZleia.js';
 import 'node:stream';
 
 /**
@@ -384,7 +384,7 @@ interface Game {
      * @example
      * ```typescript
      * game.registerSystem(LoopPhase.UPDATE, movementSystem);
-     * game.registerSystem(LoopPhase.PHYSICS, collisionSystem);
+     * game.registerSystem(LoopPhase.ANIMATION, collisionSystem);
      * ```
      */
     registerSystem(phase: LoopPhase, system: System): Unsubscribe;

package/dist/game/index.js

@@ -1 +1 @@
-export{a as GameConfigSchema,b as createGame}from'../chunk-2UBBZFE4.js';import'../chunk-4X4N4HNQ.js';import'../chunk-H2YAOJDW.js';import'../chunk-P6CJO3BC.js';import'../chunk-KFAK4A3G.js';import'../chunk-BCADUCOZ.js';import'../chunk-KD55INV7.js';import'../chunk-PSXXMBVJ.js';import'../chunk-LCN2ZITE.js';import'../chunk-FYEBZAWN.js';import'../chunk-W5OU7Z6J.js';import'../chunk-Z4EZERNE.js';import'../chunk-WNG4A3K7.js';import'../chunk-SHUC6JWA.js';import'../chunk-G7GIWWLE.js';import'../chunk-PXXGH3BV.js';import'../chunk-5PELJRUQ.js';
+export{a as GameConfigSchema,b as createGame}from'../chunk-KTVEMB2I.js';import'../chunk-OMU5BSAS.js';import'../chunk-NPNUUSIB.js';import'../chunk-DMBMCCLN.js';import'../chunk-5N3O25O7.js';import'../chunk-R3ICZOE4.js';import'../chunk-DSKQ5J4R.js';import'../chunk-LI4Y7TBZ.js';import'../chunk-6XWY6GB7.js';import'../chunk-DQTVJITR.js';import'../chunk-ZPGJCHXH.js';import'../chunk-735KKTP3.js';import'../chunk-APKUNIMB.js';import'../chunk-NPDPBAW6.js';import'../chunk-GJ3RS2VG.js';import'../chunk-Z4EZERNE.js';import'../chunk-P3ZLIQJP.js';import'../chunk-5PELJRUQ.js';

package/dist/{gameLoop-BIPW7-OY.d.ts → gameLoop-CSTb7e0L.d.ts}

@@ -1,5 +1,5 @@
-import { S as Scheduler } from './scheduler-DcfoFuum.js';
-import { W as World, S as System } from './types-BcsvoKzf.js';
+import { S as Scheduler } from './scheduler-DeeZleia.js';
+import { W as World, S as System } from './types-CPB4CpbH.js';
 
 /**
  * Game loop with input priority and lifecycle management.

package/dist/{index-zSGJ2eUk.d.ts → index-DBS5Uefn.d.ts}

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { W as World, E as Entity, S as System } from './types-BcsvoKzf.js';
+import { W as World, E as Entity, S as System } from './types-CPB4CpbH.js';
 import { A as Animation3DConfig, C as Camera3DConfig, M as Material3DConfig, a as MouseInteraction3DConfig, T as Transform3DConfig, V as Viewport3DConfig, b as Animation3DConfigSchema, c as Camera3DConfigSchema, d as Material3DConfigSchema, e as MouseInteraction3DConfigSchema, f as Transform3DConfigSchema, g as Viewport3DConfigSchema, h as Viewport3DWidgetConfig, i as Viewport3DWidgetConfigSchema } from './viewport3d-xI33-_wq.js';
 
 /**
@@ -1019,7 +1019,7 @@ interface MeshData {
     /** Number of triangles (indices.length / 3) */
     readonly triangleCount: number;
     /** Optional vertex normals: [nx0, ny0, nz0, nx1, ny1, nz1, ...] */
-    readonly normals?: Float32Array;
+    readonly normals?: Float32Array | undefined;
 }
 /**
  * Register mesh geometry data and return an ID.