blecsd 0.1.0

package/dist/errors/index.js

@@ -0,0 +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';

package/dist/events-BbbxkgvX.d.ts

@@ -0,0 +1,125 @@
+import { U as Unsubscribe } from './types-BcsvoKzf.js';
+
+/**
+ * Typed EventEmitter implementation for type-safe event handling
+ * @module core/events
+ */
+
+/**
+ * Generic event handler type.
+ * Takes the event payload and returns nothing.
+ */
+type EventHandler<T> = (event: T) => void;
+/**
+ * Base event map type constraint.
+ * Any object type mapping event names to payload types satisfies this constraint.
+ * You don't need to explicitly extend this; any interface with string keys works.
+ *
+ * @example
+ * ```typescript
+ * // This works automatically:
+ * interface MyEvents {
+ *   'player:moved': { x: number; y: number };
+ *   'game:over': { score: number };
+ * }
+ * ```
+ */
+type EventMap = Record<string, any>;
+/**
+ * UI events emitted by interactive elements.
+ */
+interface UIEventMap {
+    click: {
+        x: number;
+        y: number;
+        button: number;
+    };
+    keypress: {
+        key: string;
+        ctrl: boolean;
+        meta: boolean;
+        shift: boolean;
+    };
+    focus: {
+        target: unknown;
+    };
+    blur: {
+        target: unknown;
+    };
+    mouseenter: {
+        x: number;
+        y: number;
+    };
+    mouseleave: {
+        x: number;
+        y: number;
+    };
+    mousemove: {
+        x: number;
+        y: number;
+    };
+    mousedown: {
+        x: number;
+        y: number;
+        button: number;
+    };
+    mouseup: {
+        x: number;
+        y: number;
+        button: number;
+    };
+    scroll: {
+        direction: 'up' | 'down';
+        amount: number;
+    };
+}
+/**
+ * Screen-level events.
+ */
+interface ScreenEventMap {
+    resize: {
+        width: number;
+        height: number;
+    };
+    render: {
+        frameTime: number;
+    };
+    destroy: Record<string, never>;
+}
+/**
+ * Type-safe EventBus interface.
+ *
+ * @typeParam T - Event map defining event names and payload types
+ */
+interface EventBus<T extends EventMap> {
+    on<K extends keyof T>(event: K, handler: EventHandler<T[K]>): Unsubscribe;
+    once<K extends keyof T>(event: K, handler: EventHandler<T[K]>): Unsubscribe;
+    off<K extends keyof T>(event: K, handler: EventHandler<T[K]>): EventBus<T>;
+    emit<K extends keyof T>(event: K, payload: T[K]): boolean;
+    removeAllListeners<K extends keyof T>(event?: K): EventBus<T>;
+    listenerCount<K extends keyof T>(event: K): number;
+    eventNames(): Array<keyof T>;
+    hasListeners<K extends keyof T>(event: K): boolean;
+}
+/**
+ * Create a new type-safe event bus.
+ *
+ * @typeParam T - Event map defining event names and payload types
+ * @returns A new EventBus instance
+ *
+ * @example
+ * ```typescript
+ * import { createEventBus } from 'blecsd';
+ *
+ * interface GameEvents {
+ *   'enemy:spawn': { type: string; x: number; y: number };
+ *   'player:death': { cause: string };
+ * }
+ *
+ * const events = createEventBus<GameEvents>();
+ * events.on('enemy:spawn', (e) => console.log(`${e.type} at ${e.x}, ${e.y}`));
+ * ```
+ */
+declare function createEventBus<T extends EventMap>(): EventBus<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 };

package/dist/game/index.d.ts

@@ -0,0 +1,486 @@
+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 { 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 'node:stream';
+
+/**
+ * High-level Game API for blECSd
+ *
+ * This module provides a simplified interface for creating terminal games.
+ * It wraps the ECS implementation with a more intuitive API.
+ *
+ * @module game
+ *
+ * @example
+ * ```typescript
+ * import { createGame } from 'blecsd';
+ *
+ * const game = createGame({
+ *   title: 'My Game',
+ *   width: 80,
+ *   height: 24,
+ * });
+ *
+ * // Create UI elements
+ * const box = game.createBox({ x: 5, y: 2, width: 20, height: 10 });
+ * const text = game.createText({ x: 6, y: 3, text: 'Hello World!' });
+ *
+ * // Handle input
+ * game.onKey('q', () => game.quit());
+ * game.onKey('space', () => console.log('Space pressed!'));
+ *
+ * // Game loop hooks
+ * game.onUpdate((dt) => {
+ *   // Game logic here
+ * });
+ *
+ * // Start the game
+ * game.start();
+ * ```
+ */
+
+/**
+ * Game configuration schema.
+ */
+declare const GameConfigSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    width: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    height: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    targetFPS: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    mouse: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    alternateScreen: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    hideCursor: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    fixedTimestep: z.ZodOptional<z.ZodObject<{
+        tickRate: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        maxUpdatesPerFrame: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        interpolate: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Game configuration type.
+ */
+type GameConfig = z.input<typeof GameConfigSchema>;
+/**
+ * Resolved game configuration with defaults applied.
+ */
+type ResolvedGameConfig = z.output<typeof GameConfigSchema>;
+/**
+ * Key event handler function.
+ */
+type KeyHandler = (event: KeyEvent) => void;
+/**
+ * Mouse event handler function.
+ */
+type MouseHandler = (event: MouseEvent) => void;
+/**
+ * Update callback function.
+ * @param deltaTime - Time since last frame in seconds
+ */
+type UpdateCallback = (deltaTime: number) => void;
+/**
+ * Fixed update callback function.
+ * @param deltaTime - Fixed delta time in seconds
+ * @param tick - Current tick number
+ */
+type FixedUpdateCallback = (deltaTime: number, tick: number) => void;
+/**
+ * Render callback function.
+ * @param alpha - Interpolation factor (0-1) for smooth rendering
+ */
+type RenderCallback = (alpha: number) => void;
+/**
+ * Game instance returned by createGame.
+ * Provides a high-level API for creating terminal games.
+ */
+interface Game {
+    /**
+     * The underlying ECS world.
+     * Use this for advanced ECS operations.
+     */
+    readonly world: World;
+    /**
+     * The game configuration.
+     */
+    readonly config: ResolvedGameConfig;
+    /**
+     * The root screen entity.
+     */
+    readonly screen: Entity;
+    /**
+     * The game loop instance.
+     */
+    readonly loop: GameLoop;
+    /**
+     * The input buffer for raw input events.
+     */
+    readonly inputBuffer: InputEventBufferData;
+    /**
+     * The input state tracker.
+     */
+    readonly inputState: InputState;
+    /**
+     * Creates a box entity.
+     *
+     * @param config - Box configuration
+     * @returns The created entity ID
+     *
+     * @example
+     * ```typescript
+     * const box = game.createBox({
+     *   x: 5, y: 2,
+     *   width: 20, height: 10,
+     *   border: { type: 1 },
+     *   style: { fg: 0xff0000ff }
+     * });
+     * ```
+     */
+    createBox(config?: BoxConfig): Entity;
+    /**
+     * Creates a text entity.
+     *
+     * @param config - Text configuration
+     * @returns The created entity ID
+     *
+     * @example
+     * ```typescript
+     * const text = game.createText({
+     *   x: 10, y: 5,
+     *   text: 'Hello World!',
+     *   style: { bold: true }
+     * });
+     * ```
+     */
+    createText(config?: TextConfig): Entity;
+    /**
+     * Creates a button entity.
+     *
+     * @param config - Button configuration
+     * @returns The created entity ID
+     *
+     * @example
+     * ```typescript
+     * const button = game.createButton({
+     *   x: 5, y: 10,
+     *   text: 'Click Me',
+     *   onPress: () => console.log('Pressed!')
+     * });
+     * ```
+     */
+    createButton(config?: ButtonConfig): Entity;
+    /**
+     * Creates a text input entity.
+     *
+     * @param config - Input configuration
+     * @returns The created entity ID
+     */
+    createInput(config?: InputConfig): Entity;
+    /**
+     * Creates a textarea entity.
+     *
+     * @param config - Textarea configuration
+     * @returns The created entity ID
+     */
+    createTextarea(config?: TextareaConfig): Entity;
+    /**
+     * Creates a textbox entity.
+     *
+     * @param config - Textbox configuration
+     * @returns The created entity ID
+     */
+    createTextbox(config?: TextboxConfig): Entity;
+    /**
+     * Creates a checkbox entity.
+     *
+     * @param config - Checkbox configuration
+     * @returns The created entity ID
+     */
+    createCheckbox(config?: CheckboxConfig): Entity;
+    /**
+     * Creates a radio button entity.
+     *
+     * @param config - Radio button configuration
+     * @returns The created entity ID
+     */
+    createRadioButton(config?: RadioButtonConfig): Entity;
+    /**
+     * Creates a radio set entity.
+     *
+     * @param config - Radio set configuration
+     * @returns The created entity ID
+     */
+    createRadioSet(config?: RadioSetConfig): Entity;
+    /**
+     * Creates a select dropdown entity.
+     *
+     * @param config - Select configuration
+     * @returns The created entity ID
+     */
+    createSelect(config?: SelectConfig): Entity;
+    /**
+     * Creates a slider entity.
+     *
+     * @param config - Slider configuration
+     * @returns The created entity ID
+     */
+    createSlider(config?: SliderConfig): Entity;
+    /**
+     * Creates a progress bar entity.
+     *
+     * @param config - Progress bar configuration
+     * @returns The created entity ID
+     */
+    createProgressBar(config?: ProgressBarConfig): Entity;
+    /**
+     * Creates a list entity.
+     *
+     * @param config - List configuration
+     * @returns The created entity ID
+     */
+    createList(config?: ListConfig): Entity;
+    /**
+     * Creates a form entity.
+     *
+     * @param config - Form configuration
+     * @returns The created entity ID
+     */
+    createForm(config?: FormConfig): Entity;
+    /**
+     * Registers a handler for a specific key.
+     *
+     * @param key - The key to listen for (e.g., 'q', 'escape', 'space')
+     * @param handler - The callback function
+     * @returns Function to unsubscribe the handler
+     *
+     * @example
+     * ```typescript
+     * const unsub = game.onKey('q', () => game.quit());
+     * const unsub2 = game.onKey('escape', () => showMenu());
+     * ```
+     */
+    onKey(key: KeyName | string, handler: KeyHandler): Unsubscribe;
+    /**
+     * Registers a handler for any key press.
+     *
+     * @param handler - The callback function
+     * @returns Function to unsubscribe the handler
+     *
+     * @example
+     * ```typescript
+     * game.onAnyKey((event) => {
+     *   console.log(`Key pressed: ${event.name}`);
+     * });
+     * ```
+     */
+    onAnyKey(handler: KeyHandler): Unsubscribe;
+    /**
+     * Registers a handler for mouse events.
+     *
+     * @param handler - The callback function
+     * @returns Function to unsubscribe the handler
+     *
+     * @example
+     * ```typescript
+     * game.onMouse((event) => {
+     *   console.log(`Mouse at ${event.x}, ${event.y}`);
+     * });
+     * ```
+     */
+    onMouse(handler: MouseHandler): Unsubscribe;
+    /**
+     * Defines input action mappings.
+     *
+     * @param bindings - Array of action bindings
+     *
+     * @example
+     * ```typescript
+     * game.defineActions([
+     *   { action: 'jump', keys: ['space', 'w'] },
+     *   { action: 'shoot', keys: ['f'], mouseButtons: ['left'] },
+     * ]);
+     *
+     * // Later, check action state
+     * if (game.isActionActive('jump')) {
+     *   player.jump();
+     * }
+     * ```
+     */
+    defineActions(bindings: readonly ActionBinding[]): void;
+    /**
+     * Checks if an action is currently active.
+     *
+     * @param action - The action name
+     * @returns true if the action is active
+     */
+    isActionActive(action: string): boolean;
+    /**
+     * Checks if a key is currently held down.
+     *
+     * @param key - The key to check
+     * @returns true if the key is held
+     */
+    isKeyDown(key: KeyName | string): boolean;
+    /**
+     * Registers an update callback.
+     * Called every frame with variable delta time.
+     *
+     * @param callback - The update function
+     * @returns Function to unsubscribe
+     *
+     * @example
+     * ```typescript
+     * game.onUpdate((dt) => {
+     *   player.x += player.velocity * dt;
+     * });
+     * ```
+     */
+    onUpdate(callback: UpdateCallback): Unsubscribe;
+    /**
+     * Registers a fixed update callback.
+     * Called at a fixed rate for deterministic physics.
+     * Only works when fixedTimestep is configured.
+     *
+     * @param callback - The fixed update function
+     * @returns Function to unsubscribe
+     *
+     * @example
+     * ```typescript
+     * game.onFixedUpdate((dt, tick) => {
+     *   physics.step(dt);
+     * });
+     * ```
+     */
+    onFixedUpdate(callback: FixedUpdateCallback): Unsubscribe;
+    /**
+     * Registers a render callback.
+     * Called after update with interpolation alpha.
+     *
+     * @param callback - The render function
+     * @returns Function to unsubscribe
+     *
+     * @example
+     * ```typescript
+     * game.onRender((alpha) => {
+     *   // Interpolate positions for smooth rendering
+     *   const x = lerp(prevX, currX, alpha);
+     *   drawSprite(x, y);
+     * });
+     * ```
+     */
+    onRender(callback: RenderCallback): Unsubscribe;
+    /**
+     * Registers a system to run at a specific loop phase.
+     *
+     * @param phase - The loop phase
+     * @param system - The system function
+     * @returns Function to unregister the system
+     *
+     * @example
+     * ```typescript
+     * game.registerSystem(LoopPhase.UPDATE, movementSystem);
+     * game.registerSystem(LoopPhase.PHYSICS, collisionSystem);
+     * ```
+     */
+    registerSystem(phase: LoopPhase, system: System): Unsubscribe;
+    /**
+     * Starts the game loop.
+     *
+     * @example
+     * ```typescript
+     * game.start();
+     * ```
+     */
+    start(): void;
+    /**
+     * Stops the game loop.
+     *
+     * @example
+     * ```typescript
+     * game.stop();
+     * ```
+     */
+    stop(): void;
+    /**
+     * Pauses the game loop.
+     * Input is still processed while paused.
+     *
+     * @example
+     * ```typescript
+     * game.pause();
+     * ```
+     */
+    pause(): void;
+    /**
+     * Resumes the game loop from pause.
+     *
+     * @example
+     * ```typescript
+     * game.resume();
+     * ```
+     */
+    resume(): void;
+    /**
+     * Quits the game and performs cleanup.
+     *
+     * @example
+     * ```typescript
+     * game.onKey('q', () => game.quit());
+     * ```
+     */
+    quit(): void;
+    /**
+     * Gets the current loop statistics.
+     *
+     * @returns Current FPS, frame time, etc.
+     *
+     * @example
+     * ```typescript
+     * const stats = game.getStats();
+     * console.log(`FPS: ${stats.fps}`);
+     * ```
+     */
+    getStats(): LoopStats;
+    /**
+     * Checks if the game is currently running.
+     */
+    isRunning(): boolean;
+    /**
+     * Checks if the game is currently paused.
+     */
+    isPaused(): boolean;
+}
+/**
+ * Creates a new game instance.
+ *
+ * @param config - Game configuration
+ * @returns A Game instance
+ *
+ * @example
+ * ```typescript
+ * import { createGame } from 'blecsd';
+ *
+ * const game = createGame({
+ *   title: 'My Game',
+ *   width: 80,
+ *   height: 24,
+ * });
+ *
+ * // Create widgets
+ * const box = game.createBox({ x: 0, y: 0, width: 80, height: 24 });
+ *
+ * // Handle input
+ * game.onKey('q', () => game.quit());
+ *
+ * // Start the game
+ * game.start();
+ * ```
+ */
+declare function createGame(config?: GameConfig): Game;
+
+export { type FixedUpdateCallback, type Game, type GameConfig, GameConfigSchema, type KeyHandler, type MouseHandler, type RenderCallback, type ResolvedGameConfig, type UpdateCallback, createGame };

package/dist/game/index.js

@@ -0,0 +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';