blecsd 0.1.0

package/dist/errors/index.d.ts

@@ -0,0 +1,1110 @@
+import { core } from 'zod';
+
+/**
+ * Error code constants for the BlECSd library.
+ *
+ * Error codes follow the pattern: `<CATEGORY>_<SPECIFIC_ERROR>`
+ * where CATEGORY matches the BlECSdErrorKind.
+ *
+ * @module errors/codes
+ */
+/**
+ * Validation error codes for input/config validation failures.
+ */
+declare const ValidationErrorCode: {
+    /** Generic validation failure */
+    readonly INVALID_INPUT: "VALIDATION_INVALID_INPUT";
+    /** Invalid hex color format */
+    readonly INVALID_HEX_COLOR: "VALIDATION_INVALID_HEX_COLOR";
+    /** Invalid hex color length */
+    readonly INVALID_HEX_LENGTH: "VALIDATION_INVALID_HEX_LENGTH";
+    /** Invalid color object */
+    readonly INVALID_COLOR_OBJECT: "VALIDATION_INVALID_COLOR_OBJECT";
+    /** Invalid color value */
+    readonly INVALID_COLOR_VALUE: "VALIDATION_INVALID_COLOR_VALUE";
+    /** Invalid palette index */
+    readonly INVALID_PALETTE_INDEX: "VALIDATION_INVALID_PALETTE_INDEX";
+    /** Invalid color cube index */
+    readonly INVALID_CUBE_INDEX: "VALIDATION_INVALID_CUBE_INDEX";
+    /** Invalid grayscale index */
+    readonly INVALID_GRAYSCALE_INDEX: "VALIDATION_INVALID_GRAYSCALE_INDEX";
+    /** Invalid dimension value */
+    readonly INVALID_DIMENSION: "VALIDATION_INVALID_DIMENSION";
+    /** Invalid buffer dimensions */
+    readonly INVALID_BUFFER_DIMENSIONS: "VALIDATION_INVALID_BUFFER_DIMENSIONS";
+    /** Invalid surrogate pair */
+    readonly INVALID_SURROGATE_PAIR: "VALIDATION_INVALID_SURROGATE_PAIR";
+    /** Schema validation failed */
+    readonly SCHEMA_VALIDATION_FAILED: "VALIDATION_SCHEMA_FAILED";
+    /** Required field missing */
+    readonly REQUIRED_FIELD_MISSING: "VALIDATION_REQUIRED_FIELD_MISSING";
+    /** Value out of range */
+    readonly VALUE_OUT_OF_RANGE: "VALIDATION_VALUE_OUT_OF_RANGE";
+};
+type ValidationErrorCodeType = (typeof ValidationErrorCode)[keyof typeof ValidationErrorCode];
+/**
+ * Terminal error codes for terminal I/O and capability failures.
+ */
+declare const TerminalErrorCode: {
+    /** Generic terminal error */
+    readonly TERMINAL_ERROR: "TERMINAL_ERROR";
+    /** Terminal not initialized */
+    readonly NOT_INITIALIZED: "TERMINAL_NOT_INITIALIZED";
+    /** Terminal already initialized */
+    readonly ALREADY_INITIALIZED: "TERMINAL_ALREADY_INITIALIZED";
+    /** Terminfo file not found */
+    readonly TERMINFO_NOT_FOUND: "TERMINAL_TERMINFO_NOT_FOUND";
+    /** Capability negotiation not started */
+    readonly NEGOTIATION_NOT_STARTED: "TERMINAL_NEGOTIATION_NOT_STARTED";
+    /** Capability negotiation already started */
+    readonly NEGOTIATION_ALREADY_STARTED: "TERMINAL_NEGOTIATION_ALREADY_STARTED";
+    /** Capability not supported */
+    readonly CAPABILITY_NOT_SUPPORTED: "TERMINAL_CAPABILITY_NOT_SUPPORTED";
+    /** Terminal write failed */
+    readonly WRITE_FAILED: "TERMINAL_WRITE_FAILED";
+    /** Terminal read failed */
+    readonly READ_FAILED: "TERMINAL_READ_FAILED";
+    /** Terminal cleanup failed */
+    readonly CLEANUP_FAILED: "TERMINAL_CLEANUP_FAILED";
+};
+type TerminalErrorCodeType = (typeof TerminalErrorCode)[keyof typeof TerminalErrorCode];
+/**
+ * System error codes for ECS system and game loop failures.
+ */
+declare const SystemErrorCode: {
+    /** Generic system error */
+    readonly SYSTEM_ERROR: "SYSTEM_ERROR";
+    /** Game loop already running */
+    readonly LOOP_ALREADY_RUNNING: "SYSTEM_LOOP_ALREADY_RUNNING";
+    /** Game loop not running */
+    readonly LOOP_NOT_RUNNING: "SYSTEM_LOOP_NOT_RUNNING";
+    /** Cannot change world while running */
+    readonly CANNOT_CHANGE_WORLD: "SYSTEM_CANNOT_CHANGE_WORLD";
+    /** System execution failed */
+    readonly SYSTEM_EXECUTION_FAILED: "SYSTEM_EXECUTION_FAILED";
+    /** Phase not found */
+    readonly PHASE_NOT_FOUND: "SYSTEM_PHASE_NOT_FOUND";
+    /** Phase already exists */
+    readonly PHASE_ALREADY_EXISTS: "SYSTEM_PHASE_ALREADY_EXISTS";
+    /** Invalid phase order */
+    readonly INVALID_PHASE_ORDER: "SYSTEM_INVALID_PHASE_ORDER";
+    /** Scheduler not initialized */
+    readonly SCHEDULER_NOT_INITIALIZED: "SYSTEM_SCHEDULER_NOT_INITIALIZED";
+};
+type SystemErrorCodeType = (typeof SystemErrorCode)[keyof typeof SystemErrorCode];
+/**
+ * Entity error codes for ECS entity management failures.
+ */
+declare const EntityErrorCode: {
+    /** Generic entity error */
+    readonly ENTITY_ERROR: "ENTITY_ERROR";
+    /** Entity not found */
+    readonly NOT_FOUND: "ENTITY_NOT_FOUND";
+    /** Entity already exists (e.g., singleton violation) */
+    readonly ALREADY_EXISTS: "ENTITY_ALREADY_EXISTS";
+    /** Screen entity already exists */
+    readonly SCREEN_ALREADY_EXISTS: "ENTITY_SCREEN_ALREADY_EXISTS";
+    /** Invalid entity ID */
+    readonly INVALID_ID: "ENTITY_INVALID_ID";
+    /** Entity missing required component */
+    readonly MISSING_COMPONENT: "ENTITY_MISSING_COMPONENT";
+    /** Entity hierarchy error */
+    readonly HIERARCHY_ERROR: "ENTITY_HIERARCHY_ERROR";
+};
+type EntityErrorCodeType = (typeof EntityErrorCode)[keyof typeof EntityErrorCode];
+/**
+ * Component error codes for ECS component failures.
+ */
+declare const ComponentErrorCode: {
+    /** Generic component error */
+    readonly COMPONENT_ERROR: "COMPONENT_ERROR";
+    /** Component not found on entity */
+    readonly NOT_FOUND: "COMPONENT_NOT_FOUND";
+    /** Component already exists on entity */
+    readonly ALREADY_EXISTS: "COMPONENT_ALREADY_EXISTS";
+    /** Invalid component data */
+    readonly INVALID_DATA: "COMPONENT_INVALID_DATA";
+    /** Component store not initialized */
+    readonly STORE_NOT_INITIALIZED: "COMPONENT_STORE_NOT_INITIALIZED";
+};
+type ComponentErrorCodeType = (typeof ComponentErrorCode)[keyof typeof ComponentErrorCode];
+/**
+ * Input error codes for input handling failures.
+ */
+declare const InputErrorCode: {
+    /** Generic input error */
+    readonly INPUT_ERROR: "INPUT_ERROR";
+    /** Invalid key sequence */
+    readonly INVALID_KEY_SEQUENCE: "INPUT_INVALID_KEY_SEQUENCE";
+    /** Invalid mouse event */
+    readonly INVALID_MOUSE_EVENT: "INPUT_INVALID_MOUSE_EVENT";
+    /** Input handler not registered */
+    readonly HANDLER_NOT_REGISTERED: "INPUT_HANDLER_NOT_REGISTERED";
+    /** Input buffer overflow */
+    readonly BUFFER_OVERFLOW: "INPUT_BUFFER_OVERFLOW";
+};
+type InputErrorCodeType = (typeof InputErrorCode)[keyof typeof InputErrorCode];
+/**
+ * Render error codes for rendering failures.
+ */
+declare const RenderErrorCode: {
+    /** Generic render error */
+    readonly RENDER_ERROR: "RENDER_ERROR";
+    /** Buffer not initialized */
+    readonly BUFFER_NOT_INITIALIZED: "RENDER_BUFFER_NOT_INITIALIZED";
+    /** Invalid cell coordinates */
+    readonly INVALID_COORDINATES: "RENDER_INVALID_COORDINATES";
+    /** Screen buffer overflow */
+    readonly BUFFER_OVERFLOW: "RENDER_BUFFER_OVERFLOW";
+    /** Render cycle timeout */
+    readonly CYCLE_TIMEOUT: "RENDER_CYCLE_TIMEOUT";
+};
+type RenderErrorCodeType = (typeof RenderErrorCode)[keyof typeof RenderErrorCode];
+/**
+ * Config error codes for configuration failures.
+ */
+declare const ConfigErrorCode: {
+    /** Generic config error */
+    readonly CONFIG_ERROR: "CONFIG_ERROR";
+    /** Invalid game config */
+    readonly INVALID_GAME_CONFIG: "CONFIG_INVALID_GAME_CONFIG";
+    /** Invalid screen config */
+    readonly INVALID_SCREEN_CONFIG: "CONFIG_INVALID_SCREEN_CONFIG";
+    /** Invalid widget config */
+    readonly INVALID_WIDGET_CONFIG: "CONFIG_INVALID_WIDGET_CONFIG";
+    /** Missing required config */
+    readonly MISSING_REQUIRED: "CONFIG_MISSING_REQUIRED";
+};
+type ConfigErrorCodeType = (typeof ConfigErrorCode)[keyof typeof ConfigErrorCode];
+/**
+ * Internal error codes for library internal failures.
+ * These indicate bugs in the library itself.
+ */
+declare const InternalErrorCode: {
+    /** Generic internal error */
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    /** Unexpected state */
+    readonly UNEXPECTED_STATE: "INTERNAL_UNEXPECTED_STATE";
+    /** Assertion failed */
+    readonly ASSERTION_FAILED: "INTERNAL_ASSERTION_FAILED";
+    /** Not implemented */
+    readonly NOT_IMPLEMENTED: "INTERNAL_NOT_IMPLEMENTED";
+    /** Unreachable code path */
+    readonly UNREACHABLE: "INTERNAL_UNREACHABLE";
+};
+type InternalErrorCodeType = (typeof InternalErrorCode)[keyof typeof InternalErrorCode];
+/**
+ * All BlECSd error codes combined.
+ */
+declare const BlECSdErrorCode: {
+    /** Generic internal error */
+    readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+    /** Unexpected state */
+    readonly UNEXPECTED_STATE: "INTERNAL_UNEXPECTED_STATE";
+    /** Assertion failed */
+    readonly ASSERTION_FAILED: "INTERNAL_ASSERTION_FAILED";
+    /** Not implemented */
+    readonly NOT_IMPLEMENTED: "INTERNAL_NOT_IMPLEMENTED";
+    /** Unreachable code path */
+    readonly UNREACHABLE: "INTERNAL_UNREACHABLE";
+    /** Generic config error */
+    readonly CONFIG_ERROR: "CONFIG_ERROR";
+    /** Invalid game config */
+    readonly INVALID_GAME_CONFIG: "CONFIG_INVALID_GAME_CONFIG";
+    /** Invalid screen config */
+    readonly INVALID_SCREEN_CONFIG: "CONFIG_INVALID_SCREEN_CONFIG";
+    /** Invalid widget config */
+    readonly INVALID_WIDGET_CONFIG: "CONFIG_INVALID_WIDGET_CONFIG";
+    /** Missing required config */
+    readonly MISSING_REQUIRED: "CONFIG_MISSING_REQUIRED";
+    /** Generic render error */
+    readonly RENDER_ERROR: "RENDER_ERROR";
+    /** Buffer not initialized */
+    readonly BUFFER_NOT_INITIALIZED: "RENDER_BUFFER_NOT_INITIALIZED";
+    /** Invalid cell coordinates */
+    readonly INVALID_COORDINATES: "RENDER_INVALID_COORDINATES";
+    /** Screen buffer overflow */
+    readonly BUFFER_OVERFLOW: "RENDER_BUFFER_OVERFLOW";
+    /** Render cycle timeout */
+    readonly CYCLE_TIMEOUT: "RENDER_CYCLE_TIMEOUT";
+    /** Generic input error */
+    readonly INPUT_ERROR: "INPUT_ERROR";
+    /** Invalid key sequence */
+    readonly INVALID_KEY_SEQUENCE: "INPUT_INVALID_KEY_SEQUENCE";
+    /** Invalid mouse event */
+    readonly INVALID_MOUSE_EVENT: "INPUT_INVALID_MOUSE_EVENT";
+    /** Input handler not registered */
+    readonly HANDLER_NOT_REGISTERED: "INPUT_HANDLER_NOT_REGISTERED";
+    /** Generic component error */
+    readonly COMPONENT_ERROR: "COMPONENT_ERROR";
+    /** Component not found on entity */
+    readonly NOT_FOUND: "COMPONENT_NOT_FOUND";
+    /** Component already exists on entity */
+    readonly ALREADY_EXISTS: "COMPONENT_ALREADY_EXISTS";
+    /** Invalid component data */
+    readonly INVALID_DATA: "COMPONENT_INVALID_DATA";
+    /** Component store not initialized */
+    readonly STORE_NOT_INITIALIZED: "COMPONENT_STORE_NOT_INITIALIZED";
+    /** Generic entity error */
+    readonly ENTITY_ERROR: "ENTITY_ERROR";
+    /** Screen entity already exists */
+    readonly SCREEN_ALREADY_EXISTS: "ENTITY_SCREEN_ALREADY_EXISTS";
+    /** Invalid entity ID */
+    readonly INVALID_ID: "ENTITY_INVALID_ID";
+    /** Entity missing required component */
+    readonly MISSING_COMPONENT: "ENTITY_MISSING_COMPONENT";
+    /** Entity hierarchy error */
+    readonly HIERARCHY_ERROR: "ENTITY_HIERARCHY_ERROR";
+    /** Generic system error */
+    readonly SYSTEM_ERROR: "SYSTEM_ERROR";
+    /** Game loop already running */
+    readonly LOOP_ALREADY_RUNNING: "SYSTEM_LOOP_ALREADY_RUNNING";
+    /** Game loop not running */
+    readonly LOOP_NOT_RUNNING: "SYSTEM_LOOP_NOT_RUNNING";
+    /** Cannot change world while running */
+    readonly CANNOT_CHANGE_WORLD: "SYSTEM_CANNOT_CHANGE_WORLD";
+    /** System execution failed */
+    readonly SYSTEM_EXECUTION_FAILED: "SYSTEM_EXECUTION_FAILED";
+    /** Phase not found */
+    readonly PHASE_NOT_FOUND: "SYSTEM_PHASE_NOT_FOUND";
+    /** Phase already exists */
+    readonly PHASE_ALREADY_EXISTS: "SYSTEM_PHASE_ALREADY_EXISTS";
+    /** Invalid phase order */
+    readonly INVALID_PHASE_ORDER: "SYSTEM_INVALID_PHASE_ORDER";
+    /** Scheduler not initialized */
+    readonly SCHEDULER_NOT_INITIALIZED: "SYSTEM_SCHEDULER_NOT_INITIALIZED";
+    /** Generic terminal error */
+    readonly TERMINAL_ERROR: "TERMINAL_ERROR";
+    /** Terminal not initialized */
+    readonly NOT_INITIALIZED: "TERMINAL_NOT_INITIALIZED";
+    /** Terminal already initialized */
+    readonly ALREADY_INITIALIZED: "TERMINAL_ALREADY_INITIALIZED";
+    /** Terminfo file not found */
+    readonly TERMINFO_NOT_FOUND: "TERMINAL_TERMINFO_NOT_FOUND";
+    /** Capability negotiation not started */
+    readonly NEGOTIATION_NOT_STARTED: "TERMINAL_NEGOTIATION_NOT_STARTED";
+    /** Capability negotiation already started */
+    readonly NEGOTIATION_ALREADY_STARTED: "TERMINAL_NEGOTIATION_ALREADY_STARTED";
+    /** Capability not supported */
+    readonly CAPABILITY_NOT_SUPPORTED: "TERMINAL_CAPABILITY_NOT_SUPPORTED";
+    /** Terminal write failed */
+    readonly WRITE_FAILED: "TERMINAL_WRITE_FAILED";
+    /** Terminal read failed */
+    readonly READ_FAILED: "TERMINAL_READ_FAILED";
+    /** Terminal cleanup failed */
+    readonly CLEANUP_FAILED: "TERMINAL_CLEANUP_FAILED";
+    /** Generic validation failure */
+    readonly INVALID_INPUT: "VALIDATION_INVALID_INPUT";
+    /** Invalid hex color format */
+    readonly INVALID_HEX_COLOR: "VALIDATION_INVALID_HEX_COLOR";
+    /** Invalid hex color length */
+    readonly INVALID_HEX_LENGTH: "VALIDATION_INVALID_HEX_LENGTH";
+    /** Invalid color object */
+    readonly INVALID_COLOR_OBJECT: "VALIDATION_INVALID_COLOR_OBJECT";
+    /** Invalid color value */
+    readonly INVALID_COLOR_VALUE: "VALIDATION_INVALID_COLOR_VALUE";
+    /** Invalid palette index */
+    readonly INVALID_PALETTE_INDEX: "VALIDATION_INVALID_PALETTE_INDEX";
+    /** Invalid color cube index */
+    readonly INVALID_CUBE_INDEX: "VALIDATION_INVALID_CUBE_INDEX";
+    /** Invalid grayscale index */
+    readonly INVALID_GRAYSCALE_INDEX: "VALIDATION_INVALID_GRAYSCALE_INDEX";
+    /** Invalid dimension value */
+    readonly INVALID_DIMENSION: "VALIDATION_INVALID_DIMENSION";
+    /** Invalid buffer dimensions */
+    readonly INVALID_BUFFER_DIMENSIONS: "VALIDATION_INVALID_BUFFER_DIMENSIONS";
+    /** Invalid surrogate pair */
+    readonly INVALID_SURROGATE_PAIR: "VALIDATION_INVALID_SURROGATE_PAIR";
+    /** Schema validation failed */
+    readonly SCHEMA_VALIDATION_FAILED: "VALIDATION_SCHEMA_FAILED";
+    /** Required field missing */
+    readonly REQUIRED_FIELD_MISSING: "VALIDATION_REQUIRED_FIELD_MISSING";
+    /** Value out of range */
+    readonly VALUE_OUT_OF_RANGE: "VALIDATION_VALUE_OUT_OF_RANGE";
+};
+type BlECSdErrorCodeType = ValidationErrorCodeType | TerminalErrorCodeType | SystemErrorCodeType | EntityErrorCodeType | ComponentErrorCodeType | InputErrorCodeType | RenderErrorCodeType | ConfigErrorCodeType | InternalErrorCodeType;
+
+/**
+ * BlECSd Error Type System
+ *
+ * Provides a discriminated union type system for all library errors.
+ * Uses plain data objects and factory functions per FP requirements.
+ *
+ * @module errors/types
+ */
+
+/**
+ * Discriminated error kinds for BlECSd errors.
+ */
+type BlECSdErrorKind = 'validation' | 'terminal' | 'system' | 'entity' | 'component' | 'input' | 'render' | 'config' | 'internal';
+/**
+ * Context data that can be attached to any error.
+ */
+interface ErrorContext {
+    /** The entity ID involved (if applicable) */
+    readonly entityId?: number;
+    /** The component name involved (if applicable) */
+    readonly componentName?: string;
+    /** The system name involved (if applicable) */
+    readonly systemName?: string;
+    /** The file path involved (if applicable) */
+    readonly filePath?: string;
+    /** The function name where error occurred */
+    readonly functionName?: string;
+    /** Additional data for debugging */
+    readonly data?: Readonly<Record<string, unknown>>;
+    /** Zod validation issues (for validation errors) */
+    readonly zodIssues?: readonly core.$ZodIssue[];
+}
+/**
+ * Base error data common to all BlECSd errors.
+ */
+interface BlECSdErrorBase<K extends BlECSdErrorKind, C extends BlECSdErrorCodeType> {
+    /** Discriminant for error kind */
+    readonly kind: K;
+    /** Error code for programmatic handling */
+    readonly code: C;
+    /** Human-readable error message */
+    readonly message: string;
+    /** Timestamp when error was created */
+    readonly timestamp: number;
+    /** Original cause (if wrapping another error) */
+    readonly cause?: Error;
+    /** Additional context for debugging */
+    readonly context?: ErrorContext;
+}
+/**
+ * Validation error for input/config validation failures.
+ */
+interface ValidationError extends BlECSdErrorBase<'validation', ValidationErrorCodeType> {
+    readonly kind: 'validation';
+}
+/**
+ * Terminal error for terminal I/O and capability failures.
+ */
+interface TerminalError extends BlECSdErrorBase<'terminal', TerminalErrorCodeType> {
+    readonly kind: 'terminal';
+}
+/**
+ * System error for ECS system and game loop failures.
+ */
+interface SystemError extends BlECSdErrorBase<'system', SystemErrorCodeType> {
+    readonly kind: 'system';
+}
+/**
+ * Entity error for ECS entity management failures.
+ */
+interface EntityError extends BlECSdErrorBase<'entity', EntityErrorCodeType> {
+    readonly kind: 'entity';
+}
+/**
+ * Component error for ECS component failures.
+ */
+interface ComponentError extends BlECSdErrorBase<'component', ComponentErrorCodeType> {
+    readonly kind: 'component';
+}
+/**
+ * Input error for input handling failures.
+ */
+interface InputError extends BlECSdErrorBase<'input', InputErrorCodeType> {
+    readonly kind: 'input';
+}
+/**
+ * Render error for rendering failures.
+ */
+interface RenderError extends BlECSdErrorBase<'render', RenderErrorCodeType> {
+    readonly kind: 'render';
+}
+/**
+ * Config error for configuration failures.
+ */
+interface ConfigError extends BlECSdErrorBase<'config', ConfigErrorCodeType> {
+    readonly kind: 'config';
+}
+/**
+ * Internal error for library internal failures.
+ * These indicate bugs in the library itself.
+ */
+interface InternalError extends BlECSdErrorBase<'internal', InternalErrorCodeType> {
+    readonly kind: 'internal';
+}
+/**
+ * Union of all BlECSd error types.
+ * Use type guards to narrow to specific error types.
+ */
+type BlECSdError = ValidationError | TerminalError | SystemError | EntityError | ComponentError | InputError | RenderError | ConfigError | InternalError;
+/**
+ * Symbol used to attach BlECSdError data to native Error instances.
+ */
+declare const BLECSD_ERROR_SYMBOL: unique symbol;
+/**
+ * Native Error with attached BlECSdError data.
+ * Used for throw/catch interop with native try/catch.
+ */
+interface NativeBlECSdError extends Error {
+    readonly [BLECSD_ERROR_SYMBOL]: BlECSdError;
+}
+
+/**
+ * Error Factory Functions
+ *
+ * Factory functions for creating BlECSd errors.
+ * All errors are immutable plain objects per FP requirements.
+ *
+ * @module errors/factories
+ */
+
+/**
+ * Options for creating errors.
+ */
+interface ErrorOptions {
+    /** Original cause (if wrapping another error) */
+    readonly cause?: Error;
+    /** Additional context for debugging */
+    readonly context?: ErrorContext;
+}
+/**
+ * Options for validation errors with Zod issues.
+ */
+interface ValidationErrorOptions extends ErrorOptions {
+    /** Zod validation issues */
+    readonly zodIssues?: readonly core.$ZodIssue[];
+}
+/**
+ * Creates a validation error.
+ *
+ * @param code - The error code
+ * @param message - Human-readable error message
+ * @param options - Additional options
+ * @returns A ValidationError object
+ *
+ * @example
+ * ```typescript
+ * import { createValidationError, ValidationErrorCode } from 'blecsd/errors';
+ *
+ * const error = createValidationError(
+ *   ValidationErrorCode.INVALID_HEX_COLOR,
+ *   'Invalid hex color format: #xyz',
+ *   { context: { data: { input: '#xyz' } } }
+ * );
+ * ```
+ */
+declare function createValidationError(code: ValidationErrorCodeType, message: string, options?: ValidationErrorOptions): ValidationError;
+/**
+ * Creates a terminal error.
+ *
+ * @param code - The error code
+ * @param message - Human-readable error message
+ * @param options - Additional options
+ * @returns A TerminalError object
+ *
+ * @example
+ * ```typescript
+ * import { createTerminalError, TerminalErrorCode } from 'blecsd/errors';
+ *
+ * const error = createTerminalError(
+ *   TerminalErrorCode.TERMINFO_NOT_FOUND,
+ *   'Terminfo file not found for terminal: xterm-256color'
+ * );
+ * ```
+ */
+declare function createTerminalError(code: TerminalErrorCodeType, message: string, options?: ErrorOptions): TerminalError;
+/**
+ * Creates a system error.
+ *
+ * @param code - The error code
+ * @param message - Human-readable error message
+ * @param options - Additional options
+ * @returns A SystemError object
+ *
+ * @example
+ * ```typescript
+ * import { createSystemError, SystemErrorCode } from 'blecsd/errors';
+ *
+ * const error = createSystemError(
+ *   SystemErrorCode.LOOP_ALREADY_RUNNING,
+ *   'Cannot start game loop: already running',
+ *   { context: { systemName: 'GameLoop' } }
+ * );
+ * ```
+ */
+declare function createSystemError(code: SystemErrorCodeType, message: string, options?: ErrorOptions): SystemError;
+/**
+ * Creates an entity error.
+ *
+ * @param code - The error code
+ * @param message - Human-readable error message
+ * @param options - Additional options
+ * @returns An EntityError object
+ *
+ * @example
+ * ```typescript
+ * import { createEntityError, EntityErrorCode } from 'blecsd/errors';
+ *
+ * const error = createEntityError(
+ *   EntityErrorCode.NOT_FOUND,
+ *   'Entity not found: 42',
+ *   { context: { entityId: 42 } }
+ * );
+ * ```
+ */
+declare function createEntityError(code: EntityErrorCodeType, message: string, options?: ErrorOptions): EntityError;
+/**
+ * Creates a component error.
+ *
+ * @param code - The error code
+ * @param message - Human-readable error message
+ * @param options - Additional options
+ * @returns A ComponentError object
+ *
+ * @example
+ * ```typescript
+ * import { createComponentError, ComponentErrorCode } from 'blecsd/errors';
+ *
+ * const error = createComponentError(
+ *   ComponentErrorCode.NOT_FOUND,
+ *   'Component Position not found on entity 42',
+ *   { context: { entityId: 42, componentName: 'Position' } }
+ * );
+ * ```
+ */
+declare function createComponentError(code: ComponentErrorCodeType, message: string, options?: ErrorOptions): ComponentError;
+/**
+ * Creates an input error.
+ *
+ * @param code - The error code
+ * @param message - Human-readable error message
+ * @param options - Additional options
+ * @returns An InputError object
+ *
+ * @example
+ * ```typescript
+ * import { createInputError, InputErrorCode } from 'blecsd/errors';
+ *
+ * const error = createInputError(
+ *   InputErrorCode.INVALID_KEY_SEQUENCE,
+ *   'Unrecognized escape sequence'
+ * );
+ * ```
+ */
+declare function createInputError(code: InputErrorCodeType, message: string, options?: ErrorOptions): InputError;
+/**
+ * Creates a render error.
+ *
+ * @param code - The error code
+ * @param message - Human-readable error message
+ * @param options - Additional options
+ * @returns A RenderError object
+ *
+ * @example
+ * ```typescript
+ * import { createRenderError, RenderErrorCode } from 'blecsd/errors';
+ *
+ * const error = createRenderError(
+ *   RenderErrorCode.INVALID_COORDINATES,
+ *   'Cell coordinates out of bounds: (100, 50)',
+ *   { context: { data: { x: 100, y: 50 } } }
+ * );
+ * ```
+ */
+declare function createRenderError(code: RenderErrorCodeType, message: string, options?: ErrorOptions): RenderError;
+/**
+ * Creates a config error.
+ *
+ * @param code - The error code
+ * @param message - Human-readable error message
+ * @param options - Additional options
+ * @returns A ConfigError object
+ *
+ * @example
+ * ```typescript
+ * import { createConfigError, ConfigErrorCode } from 'blecsd/errors';
+ *
+ * const error = createConfigError(
+ *   ConfigErrorCode.INVALID_GAME_CONFIG,
+ *   'Invalid game configuration: width must be positive'
+ * );
+ * ```
+ */
+declare function createConfigError(code: ConfigErrorCodeType, message: string, options?: ErrorOptions): ConfigError;
+/**
+ * Creates an internal error.
+ *
+ * @param code - The error code
+ * @param message - Human-readable error message
+ * @param options - Additional options
+ * @returns An InternalError object
+ *
+ * @example
+ * ```typescript
+ * import { createInternalError, InternalErrorCode } from 'blecsd/errors';
+ *
+ * const error = createInternalError(
+ *   InternalErrorCode.ASSERTION_FAILED,
+ *   'Assertion failed: expected x > 0'
+ * );
+ * ```
+ */
+declare function createInternalError(code: InternalErrorCodeType, message: string, options?: ErrorOptions): InternalError;
+/**
+ * Converts a BlECSdError to a native Error for throw/catch.
+ *
+ * The returned Error has the BlECSdError attached via symbol,
+ * allowing recovery with `fromNativeError()`.
+ *
+ * @param error - The BlECSdError to convert
+ * @returns A native Error with the BlECSdError attached
+ *
+ * @example
+ * ```typescript
+ * import { createValidationError, toNativeError, ValidationErrorCode } from 'blecsd/errors';
+ *
+ * const blecsdError = createValidationError(
+ *   ValidationErrorCode.INVALID_HEX_COLOR,
+ *   'Invalid hex color'
+ * );
+ * throw toNativeError(blecsdError);
+ * ```
+ */
+declare function toNativeError(error: BlECSdError): NativeBlECSdError;
+/**
+ * Extracts a BlECSdError from a native Error (if it was created with `toNativeError()`).
+ *
+ * @param error - The caught error (unknown type from catch block)
+ * @returns The BlECSdError if present, null otherwise
+ *
+ * @example
+ * ```typescript
+ * import { fromNativeError } from 'blecsd/errors';
+ *
+ * try {
+ *   someFunction();
+ * } catch (e) {
+ *   const blecsdError = fromNativeError(e);
+ *   if (blecsdError) {
+ *     console.log('BlECSd error:', blecsdError.code);
+ *   } else {
+ *     console.log('Unknown error:', e);
+ *   }
+ * }
+ * ```
+ */
+declare function fromNativeError(error: unknown): BlECSdError | null;
+/**
+ * Wraps an unknown error as a BlECSdError.
+ *
+ * If the error is already a BlECSdError (via toNativeError), returns it.
+ * Otherwise, wraps it in an InternalError.
+ *
+ * @param error - The unknown error
+ * @param fallbackCode - Error code to use if not a BlECSdError
+ * @param fallbackMessage - Message prefix to use if not a BlECSdError
+ * @returns A BlECSdError
+ *
+ * @example
+ * ```typescript
+ * import { wrapError, InternalErrorCode } from 'blecsd/errors';
+ *
+ * try {
+ *   riskyOperation();
+ * } catch (e) {
+ *   const error = wrapError(
+ *     e,
+ *     InternalErrorCode.UNEXPECTED_STATE,
+ *     'Unexpected error in riskyOperation'
+ *   );
+ *   // error is always a BlECSdError
+ * }
+ * ```
+ */
+declare function wrapError(error: unknown, fallbackCode: InternalErrorCodeType, fallbackMessage: string): BlECSdError;
+
+/**
+ * Type Guards for BlECSd Errors
+ *
+ * Type guards for narrowing BlECSdError union types.
+ *
+ * @module errors/guards
+ */
+
+/**
+ * Checks if an error is a ValidationError.
+ *
+ * @param error - The error to check
+ * @returns True if the error is a ValidationError
+ *
+ * @example
+ * ```typescript
+ * import { isValidationError } from 'blecsd/errors';
+ *
+ * if (isValidationError(error)) {
+ *   // error is narrowed to ValidationError
+ *   console.log(error.context?.zodIssues);
+ * }
+ * ```
+ */
+declare function isValidationError(error: BlECSdError): error is ValidationError;
+/**
+ * Checks if an error is a TerminalError.
+ *
+ * @param error - The error to check
+ * @returns True if the error is a TerminalError
+ */
+declare function isTerminalError(error: BlECSdError): error is TerminalError;
+/**
+ * Checks if an error is a SystemError.
+ *
+ * @param error - The error to check
+ * @returns True if the error is a SystemError
+ */
+declare function isSystemError(error: BlECSdError): error is SystemError;
+/**
+ * Checks if an error is an EntityError.
+ *
+ * @param error - The error to check
+ * @returns True if the error is an EntityError
+ */
+declare function isEntityError(error: BlECSdError): error is EntityError;
+/**
+ * Checks if an error is a ComponentError.
+ *
+ * @param error - The error to check
+ * @returns True if the error is a ComponentError
+ */
+declare function isComponentError(error: BlECSdError): error is ComponentError;
+/**
+ * Checks if an error is an InputError.
+ *
+ * @param error - The error to check
+ * @returns True if the error is an InputError
+ */
+declare function isInputError(error: BlECSdError): error is InputError;
+/**
+ * Checks if an error is a RenderError.
+ *
+ * @param error - The error to check
+ * @returns True if the error is a RenderError
+ */
+declare function isRenderError(error: BlECSdError): error is RenderError;
+/**
+ * Checks if an error is a ConfigError.
+ *
+ * @param error - The error to check
+ * @returns True if the error is a ConfigError
+ */
+declare function isConfigError(error: BlECSdError): error is ConfigError;
+/**
+ * Checks if an error is an InternalError.
+ *
+ * @param error - The error to check
+ * @returns True if the error is an InternalError
+ */
+declare function isInternalError(error: BlECSdError): error is InternalError;
+/**
+ * Checks if an error is of a specific kind.
+ *
+ * @param error - The error to check
+ * @param kind - The kind to check for
+ * @returns True if the error is of the specified kind
+ *
+ * @example
+ * ```typescript
+ * import { isErrorKind } from 'blecsd/errors';
+ *
+ * if (isErrorKind(error, 'validation')) {
+ *   // error is narrowed to ValidationError
+ * }
+ * ```
+ */
+declare function isErrorKind<K extends BlECSdErrorKind>(error: BlECSdError, kind: K): error is Extract<BlECSdError, {
+    kind: K;
+}>;
+/**
+ * Checks if an error has a specific code.
+ *
+ * @param error - The error to check
+ * @param code - The code to check for
+ * @returns True if the error has the specified code
+ *
+ * @example
+ * ```typescript
+ * import { hasErrorCode, ValidationErrorCode } from 'blecsd/errors';
+ *
+ * if (hasErrorCode(error, ValidationErrorCode.INVALID_HEX_COLOR)) {
+ *   // Handle specific error case
+ * }
+ * ```
+ */
+declare function hasErrorCode(error: BlECSdError, code: string): boolean;
+/**
+ * Checks if an unknown value is a BlECSdError (via NativeBlECSdError).
+ *
+ * @param value - The value to check
+ * @returns True if the value contains a BlECSdError
+ *
+ * @example
+ * ```typescript
+ * import { isBlECSdError } from 'blecsd/errors';
+ *
+ * try {
+ *   someFunction();
+ * } catch (e) {
+ *   if (isBlECSdError(e)) {
+ *     // e contains a BlECSdError
+ *   }
+ * }
+ * ```
+ */
+declare function isBlECSdError(value: unknown): value is {
+    [BLECSD_ERROR_SYMBOL]: BlECSdError;
+};
+/**
+ * Checks if an unknown value looks like a BlECSdError object (duck typing).
+ *
+ * This checks the shape of the object rather than the symbol.
+ * Useful for deserializing errors or cross-realm scenarios.
+ *
+ * @param value - The value to check
+ * @returns True if the value has the shape of a BlECSdError
+ */
+declare function hasBlECSdErrorShape(value: unknown): value is BlECSdError;
+/**
+ * Checks if an error has context data.
+ *
+ * @param error - The error to check
+ * @returns True if the error has context
+ */
+declare function hasContext(error: BlECSdError): error is BlECSdError & {
+    context: NonNullable<BlECSdError['context']>;
+};
+/**
+ * Checks if an error has a cause.
+ *
+ * @param error - The error to check
+ * @returns True if the error has a cause
+ */
+declare function hasCause(error: BlECSdError): error is BlECSdError & {
+    cause: Error;
+};
+/**
+ * Checks if an error has Zod issues in its context.
+ *
+ * @param error - The error to check
+ * @returns True if the error has Zod issues
+ */
+declare function hasZodIssues(error: BlECSdError): error is BlECSdError & {
+    context: NonNullable<BlECSdError['context']> & {
+        zodIssues: NonNullable<BlECSdError['context']>['zodIssues'];
+    };
+};
+
+/**
+ * Result Type for Recoverable Operations
+ *
+ * A discriminated union type for representing success or failure.
+ * Inspired by Rust's Result<T, E> type.
+ *
+ * @module errors/result
+ */
+
+/**
+ * Successful result containing a value.
+ */
+interface ResultOk<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+/**
+ * Failed result containing an error.
+ */
+interface ResultErr<E> {
+    readonly ok: false;
+    readonly error: E;
+}
+/**
+ * Result type representing either success (Ok) or failure (Err).
+ *
+ * @typeParam T - The success value type
+ * @typeParam E - The error type (defaults to BlECSdError)
+ *
+ * @example
+ * ```typescript
+ * import { Result, ok, err, unwrapOr } from 'blecsd/errors';
+ *
+ * function divide(a: number, b: number): Result<number, string> {
+ *   if (b === 0) {
+ *     return err('Division by zero');
+ *   }
+ *   return ok(a / b);
+ * }
+ *
+ * const result = divide(10, 2);
+ * const value = unwrapOr(result, 0); // 5
+ * ```
+ */
+type Result<T, E = BlECSdError> = ResultOk<T> | ResultErr<E>;
+/**
+ * Creates a successful Result containing a value.
+ *
+ * @param value - The success value
+ * @returns A Result with ok: true
+ *
+ * @example
+ * ```typescript
+ * import { ok } from 'blecsd/errors';
+ *
+ * const result = ok(42);
+ * // result: { ok: true, value: 42 }
+ * ```
+ */
+declare function ok<T>(value: T): ResultOk<T>;
+/**
+ * Creates a failed Result containing an error.
+ *
+ * @param error - The error value
+ * @returns A Result with ok: false
+ *
+ * @example
+ * ```typescript
+ * import { err, createValidationError, ValidationErrorCode } from 'blecsd/errors';
+ *
+ * const result = err(createValidationError(
+ *   ValidationErrorCode.INVALID_INPUT,
+ *   'Invalid input'
+ * ));
+ * ```
+ */
+declare function err<E>(error: E): ResultErr<E>;
+/**
+ * Checks if a Result is Ok (successful).
+ *
+ * @param result - The Result to check
+ * @returns True if the Result is Ok
+ *
+ * @example
+ * ```typescript
+ * import { isOk, ok, err } from 'blecsd/errors';
+ *
+ * isOk(ok(42));        // true
+ * isOk(err('error'));  // false
+ * ```
+ */
+declare function isOk<T, E>(result: Result<T, E>): result is ResultOk<T>;
+/**
+ * Checks if a Result is Err (failed).
+ *
+ * @param result - The Result to check
+ * @returns True if the Result is Err
+ *
+ * @example
+ * ```typescript
+ * import { isErr, ok, err } from 'blecsd/errors';
+ *
+ * isErr(ok(42));        // false
+ * isErr(err('error'));  // true
+ * ```
+ */
+declare function isErr<T, E>(result: Result<T, E>): result is ResultErr<E>;
+/**
+ * Extracts the value from an Ok Result, or throws if Err.
+ *
+ * @param result - The Result to unwrap
+ * @returns The success value
+ * @throws Error if the Result is Err
+ *
+ * @example
+ * ```typescript
+ * import { unwrap, ok, err } from 'blecsd/errors';
+ *
+ * unwrap(ok(42));        // 42
+ * unwrap(err('error'));  // throws Error
+ * ```
+ */
+declare function unwrap<T, E>(result: Result<T, E>): T;
+/**
+ * Extracts the value from an Ok Result, or returns a default value if Err.
+ *
+ * @param result - The Result to unwrap
+ * @param defaultValue - The value to return if Err
+ * @returns The success value or the default value
+ *
+ * @example
+ * ```typescript
+ * import { unwrapOr, ok, err } from 'blecsd/errors';
+ *
+ * unwrapOr(ok(42), 0);        // 42
+ * unwrapOr(err('error'), 0);  // 0
+ * ```
+ */
+declare function unwrapOr<T, E>(result: Result<T, E>, defaultValue: T): T;
+/**
+ * Extracts the value from an Ok Result, or computes a default value if Err.
+ *
+ * @param result - The Result to unwrap
+ * @param fn - Function to compute the default value (receives the error)
+ * @returns The success value or the computed default value
+ *
+ * @example
+ * ```typescript
+ * import { unwrapOrElse, ok, err } from 'blecsd/errors';
+ *
+ * unwrapOrElse(ok(42), () => 0);                    // 42
+ * unwrapOrElse(err('error'), (e) => e.length);      // 5
+ * ```
+ */
+declare function unwrapOrElse<T, E>(result: Result<T, E>, fn: (error: E) => T): T;
+/**
+ * Maps a function over the Ok value, leaving Err unchanged.
+ *
+ * @param result - The Result to map
+ * @param fn - Function to apply to the Ok value
+ * @returns A new Result with the mapped value
+ *
+ * @example
+ * ```typescript
+ * import { map, ok, err } from 'blecsd/errors';
+ *
+ * map(ok(42), (x) => x * 2);        // ok(84)
+ * map(err('error'), (x) => x * 2);  // err('error')
+ * ```
+ */
+declare function map<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;
+/**
+ * Maps a function over the Err error, leaving Ok unchanged.
+ *
+ * @param result - The Result to map
+ * @param fn - Function to apply to the Err error
+ * @returns A new Result with the mapped error
+ *
+ * @example
+ * ```typescript
+ * import { mapError, ok, err } from 'blecsd/errors';
+ *
+ * mapError(ok(42), (e) => new Error(e));        // ok(42)
+ * mapError(err('oops'), (e) => new Error(e));   // err(Error('oops'))
+ * ```
+ */
+declare function mapError<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F>;
+/**
+ * Chains Result-returning functions, short-circuiting on Err.
+ *
+ * @param result - The Result to chain
+ * @param fn - Function that returns a Result
+ * @returns The Result from the function, or the original Err
+ *
+ * @example
+ * ```typescript
+ * import { flatMap, ok, err, Result } from 'blecsd/errors';
+ *
+ * function sqrt(x: number): Result<number, string> {
+ *   return x >= 0 ? ok(Math.sqrt(x)) : err('negative number');
+ * }
+ *
+ * flatMap(ok(16), sqrt);   // ok(4)
+ * flatMap(ok(-1), sqrt);   // err('negative number')
+ * flatMap(err('x'), sqrt); // err('x')
+ * ```
+ */
+declare function flatMap<T, U, E>(result: Result<T, E>, fn: (value: T) => Result<U, E>): Result<U, E>;
+
+export { BLECSD_ERROR_SYMBOL, type BlECSdError, type BlECSdErrorBase, BlECSdErrorCode, type BlECSdErrorCodeType, type BlECSdErrorKind, type ComponentError, ComponentErrorCode, type ComponentErrorCodeType, type ConfigError, ConfigErrorCode, type ConfigErrorCodeType, type EntityError, EntityErrorCode, type EntityErrorCodeType, type ErrorContext, type ErrorOptions, type InputError, InputErrorCode, type InputErrorCodeType, type InternalError, InternalErrorCode, type InternalErrorCodeType, type NativeBlECSdError, type RenderError, RenderErrorCode, type RenderErrorCodeType, type Result, type ResultErr, type ResultOk, type SystemError, SystemErrorCode, type SystemErrorCodeType, type TerminalError, TerminalErrorCode, type TerminalErrorCodeType, type ValidationError, ValidationErrorCode, type ValidationErrorCodeType, type ValidationErrorOptions, createComponentError, createConfigError, createEntityError, createInputError, createInternalError, createRenderError, createSystemError, createTerminalError, createValidationError, err, flatMap, fromNativeError, hasBlECSdErrorShape, hasCause, hasContext, hasErrorCode, hasZodIssues, isBlECSdError, isComponentError, isConfigError, isEntityError, isErr, isErrorKind, isInputError, isInternalError, isOk, isRenderError, isSystemError, isTerminalError, isValidationError, map, mapError, ok, toNativeError, unwrap, unwrapOr, unwrapOrElse, wrapError };