blecsd 0.1.1 → 0.3.0

package/dist/packedStore-BgvnEdE7.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Packed Store: Cache-friendly storage with stable handles
+ *
+ * Implements the three-vector pattern for O(1) add/remove operations
+ * with stable identifiers and cache-friendly iteration:
+ *
+ * - data[]: Dense contiguous storage for actual values
+ * - dataIndex[]: Maps handle index → position in data array
+ * - id[]: Maps position in data → handle index (inverse mapping)
+ * - generations[]: Tracks generation at each slot for stale handle detection
+ *
+ * @module core/storage/packedStore
+ */
+/**
+ * Handle to an element in a packed store.
+ * The combination of index and generation ensures handles
+ * become invalid after the element is removed.
+ */
+interface PackedHandle {
+    readonly index: number;
+    readonly gen: number;
+}
+/**
+ * Packed store state. All arrays are parallel structures
+ * that work together to provide stable handles with O(1) operations.
+ */
+interface PackedStore<T> {
+    /** Dense contiguous data array for cache-friendly iteration */
+    readonly data: T[];
+    /** Maps handle index → position in data array */
+    readonly dataIndex: Int32Array;
+    /** Maps data position → handle index (inverse of dataIndex) */
+    readonly id: Int32Array;
+    /** Generation counter for each slot (bumped on removal) */
+    readonly generations: Uint32Array;
+    /** Number of live elements */
+    size: number;
+    /** Total allocated capacity */
+    capacity: number;
+}
+/**
+ * Creates a new packed store with optional initial capacity.
+ *
+ * @param initialCapacity - Initial capacity hint (default 64)
+ * @returns Empty packed store
+ *
+ * @example
+ * ```typescript
+ * import { createPackedStore, addToStore } from 'blecsd';
+ *
+ * interface Particle { x: number; y: number; vx: number; vy: number; }
+ * const particles = createPackedStore<Particle>();
+ * const handle = addToStore(particles, { x: 0, y: 0, vx: 1, vy: 0 });
+ * ```
+ */
+declare function createPackedStore<T>(initialCapacity?: number): PackedStore<T>;
+/**
+ * Adds a value to the packed store and returns a stable handle.
+ *
+ * If there are freed slots from prior deletions, one is reused.
+ * Otherwise, capacity is expanded as needed.
+ *
+ * @param store - The packed store
+ * @param value - Value to add
+ * @returns Handle to the stored value
+ *
+ * @example
+ * ```typescript
+ * const handle = addToStore(store, { name: 'entity1' });
+ * // handle.index is stable even after other elements are removed
+ * ```
+ */
+declare function addToStore<T>(store: PackedStore<T>, value: T): PackedHandle;
+/**
+ * Checks if a handle is valid (points to a live element).
+ *
+ * @param store - The packed store
+ * @param handle - Handle to validate
+ * @returns True if the handle points to a live element
+ *
+ * @example
+ * ```typescript
+ * if (isValidHandle(store, handle)) {
+ *   const value = getFromStore(store, handle);
+ * }
+ * ```
+ */
+declare function isValidHandle<T>(store: PackedStore<T>, handle: PackedHandle): boolean;
+/**
+ * Gets the value associated with a handle.
+ *
+ * @param store - The packed store
+ * @param handle - Handle to the element
+ * @returns The value, or undefined if handle is invalid
+ *
+ * @example
+ * ```typescript
+ * const particle = getFromStore(particles, handle);
+ * if (particle) {
+ *   console.log(particle.x, particle.y);
+ * }
+ * ```
+ */
+declare function getFromStore<T>(store: PackedStore<T>, handle: PackedHandle): T | undefined;
+/**
+ * Sets (replaces) the value at a handle.
+ *
+ * @param store - The packed store
+ * @param handle - Handle to the element
+ * @param value - New value
+ * @returns True if successful, false if handle is invalid
+ */
+declare function setInStore<T>(store: PackedStore<T>, handle: PackedHandle, value: T): boolean;
+/**
+ * Removes an element from the packed store using swap-and-pop.
+ *
+ * The handle becomes invalid after removal. Any other handles
+ * remain valid (this is the key benefit of the three-vector pattern).
+ *
+ * @param store - The packed store
+ * @param handle - Handle to remove
+ * @returns True if removed, false if handle was invalid
+ *
+ * @example
+ * ```typescript
+ * removeFromStore(particles, handle);
+ * // handle is now invalid, but other handles remain valid
+ * ```
+ */
+declare function removeFromStore<T>(store: PackedStore<T>, handle: PackedHandle): boolean;
+/**
+ * Clears all elements from the store but retains capacity.
+ *
+ * @param store - The packed store to clear
+ */
+declare function clearStore<T>(store: PackedStore<T>): void;
+/**
+ * Iterates over all live elements in the store.
+ * Iteration is cache-friendly as it traverses the dense data array.
+ *
+ * @param store - The packed store
+ * @param fn - Callback for each element (receives value and handle)
+ *
+ * @example
+ * ```typescript
+ * forEachInStore(particles, (particle, handle) => {
+ *   particle.x += particle.vx;
+ *   particle.y += particle.vy;
+ * });
+ * ```
+ */
+declare function forEachInStore<T>(store: PackedStore<T>, fn: (value: T, handle: PackedHandle) => void): void;
+/**
+ * Maps over all live elements, producing a new array.
+ *
+ * @param store - The packed store
+ * @param fn - Transform function
+ * @returns Array of transformed values
+ */
+declare function mapStore<T, U>(store: PackedStore<T>, fn: (value: T, handle: PackedHandle) => U): U[];
+/**
+ * Returns the dense data array for direct iteration.
+ * This is the fastest way to iterate when you don't need handles.
+ *
+ * WARNING: Do not modify the array structure (push/pop/splice).
+ * The returned array is a view into internal storage.
+ *
+ * @param store - The packed store
+ * @returns Readonly view of the dense data array (length = store.size)
+ *
+ * @example
+ * ```typescript
+ * // Fastest iteration when handles aren't needed
+ * const data = getStoreData(particles);
+ * for (let i = 0; i < particles.size; i++) {
+ *   const p = data[i];
+ *   p.x += p.vx;
+ * }
+ * ```
+ */
+declare function getStoreData<T>(store: PackedStore<T>): readonly T[];
+/**
+ * Gets the current number of live elements.
+ */
+declare function getStoreSize<T>(store: PackedStore<T>): number;
+/**
+ * Gets the current capacity (including freed slots).
+ */
+declare function getStoreCapacity<T>(store: PackedStore<T>): number;
+
+export { type PackedStore as P, type PackedHandle as a, addToStore as b, clearStore as c, createPackedStore as d, getStoreCapacity as e, forEachInStore as f, getFromStore as g, getStoreData as h, getStoreSize as i, isValidHandle as j, mapStore as m, removeFromStore as r, setInStore as s };

package/dist/{renderable-jTMOA-GK.d.ts → renderable-CwqGwrEV.d.ts}

@@ -1,4 +1,4 @@
-import { W as World, E as Entity } from './types-BcsvoKzf.js';
+import { W as World, E as Entity } from './types-CPB4CpbH.js';
 
 /**
  * Renderable component for visual styling of entities.
@@ -61,21 +61,21 @@ declare const Renderable: {
  */
 interface StyleOptions {
     /** Foreground color (hex string or packed number) */
-    fg?: string | number;
+    fg?: string | number | undefined;
     /** Background color (hex string or packed number) */
-    bg?: string | number;
+    bg?: string | number | undefined;
     /** Bold text */
-    bold?: boolean;
+    bold?: boolean | undefined;
     /** Underlined text */
-    underline?: boolean;
+    underline?: boolean | undefined;
     /** Blinking text */
-    blink?: boolean;
+    blink?: boolean | undefined;
     /** Inverse colors */
-    inverse?: boolean;
+    inverse?: boolean | undefined;
     /** Transparent background */
-    transparent?: boolean;
+    transparent?: boolean | undefined;
     /** Opacity for alpha blending (0-1, where 1 = fully opaque) */
-    opacity?: number;
+    opacity?: number | undefined;
 }
 /**
  * Style data returned by getStyle.

package/dist/{scheduler-DcfoFuum.d.ts → scheduler-CMcYew9Z.d.ts}

@@ -1,10 +1,63 @@
-import { L as LoopPhase, S as System, W as World } from './types-BcsvoKzf.js';
+import { L as LoopPhase, S as System, W as World } from './types-CPB4CpbH.js';
 
 /**
  * System scheduler for ordered execution.
  * @module core/scheduler
  */
 
+/**
+ * Per-phase timing data for a single frame.
+ */
+interface PhaseTimingData {
+    /** Phase identifier */
+    readonly phase: LoopPhase;
+    /** Time spent in this phase in milliseconds */
+    duration: number;
+    /** Number of systems executed in this phase */
+    systemCount: number;
+}
+/**
+ * Frame telemetry data collected during scheduler execution.
+ */
+interface FrameTelemetry {
+    /** Per-phase timing data */
+    readonly phases: ReadonlyArray<PhaseTimingData>;
+    /** Total frame time in milliseconds */
+    totalFrameTime: number;
+    /** Frame number (increments each run) */
+    frameNumber: number;
+}
+/**
+ * Telemetry configuration options.
+ */
+interface TelemetryConfig {
+    /** Enable telemetry collection (default: false) */
+    enabled: boolean;
+    /** Maximum number of frames to keep in history (default: 0 = current frame only) */
+    historySize?: number;
+}
+/**
+ * Frame budget configuration for adaptive performance.
+ */
+interface AdaptiveFrameBudgetConfig {
+    /** Enable frame budget enforcement (default: false) */
+    enabled: boolean;
+    /** Target frame time in milliseconds (default: 16.67ms for 60fps) */
+    budgetMs?: number;
+    /** Phases that can be skipped when over budget (default: [ANIMATION]) */
+    skippablePhases?: ReadonlyArray<LoopPhase>;
+}
+/**
+ * Frame budget status for the current frame.
+ */
+interface AdaptiveFrameBudgetStatus {
+    /** Whether budget was exceeded this frame */
+    exceeded: boolean;
+    /** Phases that were skipped this frame */
+    skippedPhases: ReadonlyArray<LoopPhase>;
+    /** Time remaining in budget (negative if exceeded) */
+    remainingMs: number;
+}
 /**
  * Gets the current frame's delta time.
  * Call this from within a system to get the time elapsed since the last frame.
@@ -60,6 +113,15 @@ interface Scheduler {
     hasSystem(system: System): boolean;
     clearPhase(phase: LoopPhase): void;
     clearAllSystems(): void;
+    enableTelemetry(config?: TelemetryConfig): void;
+    disableTelemetry(): void;
+    getTelemetry(): FrameTelemetry | null;
+    getTelemetryHistory(): ReadonlyArray<FrameTelemetry>;
+    isTelemetryEnabled(): boolean;
+    enableFrameBudget(config?: AdaptiveFrameBudgetConfig): void;
+    disableFrameBudget(): void;
+    getAdaptiveFrameBudgetStatus(): AdaptiveFrameBudgetStatus | null;
+    isFrameBudgetEnabled(): boolean;
 }
 /**
  * Creates a new scheduler instance.
@@ -74,7 +136,7 @@ interface Scheduler {
  *
  * // Register systems
  * scheduler.registerSystem(LoopPhase.UPDATE, movementSystem);
- * scheduler.registerSystem(LoopPhase.PHYSICS, physicsSystem);
+ * scheduler.registerSystem(LoopPhase.ANIMATION, physicsSystem);
  * scheduler.registerSystem(LoopPhase.RENDER, renderSystem);
  *
  * // Run in game loop
@@ -83,4 +145,4 @@ interface Scheduler {
  */
 declare function createScheduler(): Scheduler;
 
-export { type Scheduler as S, createScheduler as c, getDeltaTime as g };
+export { type AdaptiveFrameBudgetConfig as A, type FrameTelemetry as F, type PhaseTimingData as P, type Scheduler as S, type TelemetryConfig as T, type AdaptiveFrameBudgetStatus as a, createScheduler as c, getDeltaTime as g };