blecsd 0.1.0

package/dist/virtualizedLineStore-DwPEvPkk.d.ts

@@ -0,0 +1,297 @@
+import { z } from 'zod';
+
+/**
+ * Virtualized Line Store for Large Text Content
+ *
+ * High-performance data structure for storing and accessing millions of lines
+ * with O(1) random access. Optimized for read-only content with streaming append.
+ *
+ * @module utils/virtualizedLineStore
+ *
+ * @example
+ * ```typescript
+ * import { createLineStore, getLineAtIndex, getLineRange } from 'blecsd';
+ *
+ * // Create store from content
+ * const store = createLineStore(largeTextContent);
+ *
+ * // O(1) access to any line
+ * const line1000 = getLineAtIndex(store, 1000);
+ *
+ * // Get visible range for viewport
+ * const visibleLines = getLineRange(store, 1000, 1025);
+ * ```
+ */
+
+/**
+ * Schema for line index validation.
+ */
+declare const LineIndexSchema: z.ZodNumber;
+/**
+ * Schema for line range parameters.
+ */
+declare const LineRangeParamsSchema: z.ZodObject<{
+    startLine: z.ZodNumber;
+    endLine: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Schema for visible lines parameters.
+ */
+declare const VisibleLinesParamsSchema: z.ZodObject<{
+    firstVisible: z.ZodNumber;
+    visibleCount: z.ZodNumber;
+    overscanBefore: z.ZodDefault<z.ZodNumber>;
+    overscanAfter: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * Schema for trim parameters.
+ */
+declare const TrimParamsSchema: z.ZodObject<{
+    maxLines: z.ZodNumber;
+}, z.core.$strip>;
+/** Maximum lines before switching to chunked mode */
+declare const CHUNKED_THRESHOLD = 1000000;
+/**
+ * Statistics about a line store.
+ */
+interface LineStoreStats {
+    /** Total line count */
+    readonly lineCount: number;
+    /** Total byte size of content */
+    readonly byteSize: number;
+    /** Memory used by offset array */
+    readonly offsetArrayBytes: number;
+    /** Total memory estimate */
+    readonly totalMemoryBytes: number;
+    /** Average line length */
+    readonly avgLineLength: number;
+    /** Whether content is indexed */
+    readonly indexed: boolean;
+}
+/**
+ * A range of lines from the store.
+ */
+interface LineRange {
+    /** Lines in the range */
+    readonly lines: readonly string[];
+    /** Start line index (actual) */
+    readonly startLine: number;
+    /** End line index (exclusive) */
+    readonly endLine: number;
+    /** Time to extract in milliseconds */
+    readonly extractTimeMs: number;
+}
+/**
+ * Information about a single line.
+ */
+interface LineInfo {
+    /** Line content (without newline) */
+    readonly text: string;
+    /** Byte offset in buffer */
+    readonly offset: number;
+    /** Line length in bytes */
+    readonly length: number;
+    /** Line number (0-based) */
+    readonly lineNumber: number;
+}
+/**
+ * Immutable view of a virtualized line store.
+ */
+interface VirtualizedLineStore {
+    /** Raw content buffer */
+    readonly buffer: string;
+    /** Line start offsets (position of first char of each line) */
+    readonly offsets: Uint32Array;
+    /** Total line count */
+    readonly lineCount: number;
+    /** Total byte size */
+    readonly byteSize: number;
+    /** Whether offsets are computed */
+    readonly indexed: boolean;
+}
+/**
+ * Creates a virtualized line store from content.
+ *
+ * @param content - Text content (newline-separated lines)
+ * @returns New line store
+ *
+ * @example
+ * ```typescript
+ * import { createLineStore } from 'blecsd';
+ *
+ * const store = createLineStore('Line 1\nLine 2\nLine 3');
+ * console.log(store.lineCount); // 3
+ * ```
+ */
+declare function createLineStore(content?: string): VirtualizedLineStore;
+/**
+ * Creates a line store from an array of lines.
+ *
+ * @param lines - Array of line strings
+ * @returns New line store
+ *
+ * @example
+ * ```typescript
+ * import { createLineStoreFromLines } from 'blecsd';
+ *
+ * const store = createLineStoreFromLines(['Line 1', 'Line 2', 'Line 3']);
+ * ```
+ */
+declare function createLineStoreFromLines(lines: readonly string[]): VirtualizedLineStore;
+/**
+ * Creates an empty line store.
+ *
+ * @returns Empty line store
+ */
+declare function createEmptyLineStore(): VirtualizedLineStore;
+/**
+ * Gets a line at a specific index. O(1) operation.
+ *
+ * @param store - The line store
+ * @param index - Line index (0-based)
+ * @returns Line content or undefined if out of bounds
+ *
+ * @example
+ * ```typescript
+ * import { createLineStore, getLineAtIndex } from 'blecsd';
+ *
+ * const store = createLineStore('Line 1\nLine 2\nLine 3');
+ * console.log(getLineAtIndex(store, 1)); // 'Line 2'
+ * ```
+ */
+declare function getLineAtIndex(store: VirtualizedLineStore, index: number): string | undefined;
+/**
+ * Gets detailed information about a line.
+ *
+ * @param store - The line store
+ * @param index - Line index (0-based)
+ * @returns Line info or undefined if out of bounds
+ */
+declare function getLineInfo(store: VirtualizedLineStore, index: number): LineInfo | undefined;
+/**
+ * Gets a range of lines. Optimized for viewport extraction.
+ *
+ * @param store - The line store
+ * @param startLine - Start line index (inclusive)
+ * @param endLine - End line index (exclusive)
+ * @returns Line range result
+ *
+ * @example
+ * ```typescript
+ * import { createLineStore, getLineRange } from 'blecsd';
+ *
+ * const store = createLineStore(largeContent);
+ * const viewport = getLineRange(store, 1000, 1025);
+ * console.log(viewport.lines.length); // 25
+ * ```
+ */
+declare function getLineRange(store: VirtualizedLineStore, startLine: number, endLine: number): LineRange;
+/**
+ * Gets visible lines for a viewport with overscan.
+ *
+ * @param store - The line store
+ * @param firstVisible - First visible line index
+ * @param visibleCount - Number of visible lines
+ * @param overscanBefore - Extra lines to include before viewport
+ * @param overscanAfter - Extra lines to include after viewport
+ * @returns Line range with overscan
+ */
+declare function getVisibleLines(store: VirtualizedLineStore, firstVisible: number, visibleCount: number, overscanBefore?: number, overscanAfter?: number): LineRange;
+/**
+ * Appends content to the store, returning a new store.
+ * Optimized for streaming append (log viewers).
+ *
+ * @param store - The original store
+ * @param content - Content to append
+ * @returns New store with appended content
+ *
+ * @example
+ * ```typescript
+ * import { createLineStore, appendToStore } from 'blecsd';
+ *
+ * let store = createLineStore('Line 1');
+ * store = appendToStore(store, '\nLine 2\nLine 3');
+ * console.log(store.lineCount); // 3
+ * ```
+ */
+declare function appendToStore(store: VirtualizedLineStore, content: string): VirtualizedLineStore;
+/**
+ * Appends lines to the store.
+ *
+ * @param store - The original store
+ * @param lines - Lines to append
+ * @returns New store with appended lines
+ */
+declare function appendLines(store: VirtualizedLineStore, lines: readonly string[]): VirtualizedLineStore;
+/**
+ * Gets the line count.
+ *
+ * @param store - The line store
+ * @returns Total line count
+ */
+declare function getLineCount(store: VirtualizedLineStore): number;
+/**
+ * Gets the byte size of the content.
+ *
+ * @param store - The line store
+ * @returns Total byte size
+ */
+declare function getByteSize(store: VirtualizedLineStore): number;
+/**
+ * Checks if the store is empty.
+ *
+ * @param store - The line store
+ * @returns true if empty
+ */
+declare function isStoreEmpty(store: VirtualizedLineStore): boolean;
+/**
+ * Gets statistics about the store.
+ *
+ * @param store - The line store
+ * @returns Store statistics
+ */
+declare function getStoreStats(store: VirtualizedLineStore): LineStoreStats;
+/**
+ * Finds the line index for a byte offset.
+ * Uses binary search for O(log n) performance.
+ *
+ * @param store - The line store
+ * @param byteOffset - Byte offset in buffer
+ * @returns Line index containing the offset
+ */
+declare function getLineForOffset(store: VirtualizedLineStore, byteOffset: number): number;
+/**
+ * Gets the byte offset for a line.
+ *
+ * @param store - The line store
+ * @param lineIndex - Line index
+ * @returns Byte offset or -1 if out of bounds
+ */
+declare function getOffsetForLine(store: VirtualizedLineStore, lineIndex: number): number;
+/**
+ * Exports all content as a string.
+ *
+ * @param store - The line store
+ * @returns Full content
+ */
+declare function exportContent(store: VirtualizedLineStore): string;
+/**
+ * Exports a range of lines as a string.
+ *
+ * @param store - The line store
+ * @param startLine - Start line index
+ * @param endLine - End line index (exclusive)
+ * @returns Content of the line range
+ */
+declare function exportLineRange(store: VirtualizedLineStore, startLine: number, endLine: number): string;
+/**
+ * Creates a trimmed store with only the last N lines.
+ * Useful for keeping log buffers bounded.
+ *
+ * @param store - The line store
+ * @param maxLines - Maximum lines to keep
+ * @returns New store with at most maxLines
+ */
+declare function trimToLineCount(store: VirtualizedLineStore, maxLines: number): VirtualizedLineStore;
+
+export { CHUNKED_THRESHOLD as C, LineIndexSchema as L, TrimParamsSchema as T, type VirtualizedLineStore as V, LineRangeParamsSchema as a, type LineStoreStats as b, type LineInfo as c, type LineRange as d, VisibleLinesParamsSchema as e, appendLines as f, appendToStore as g, createEmptyLineStore as h, createLineStore as i, createLineStoreFromLines as j, exportContent as k, exportLineRange as l, getByteSize as m, getLineAtIndex as n, getLineForOffset as o, getLineInfo as p, getLineCount as q, getLineRange as r, getVisibleLines as s, getOffsetForLine as t, getStoreStats as u, isStoreEmpty as v, trimToLineCount as w };

package/dist/widgets/bigText.d.ts

@@ -0,0 +1,230 @@
+import { z } from 'zod';
+import { E as Entity, W as World } from '../types-BcsvoKzf.js';
+import { BitmapFont } from './fonts/index.js';
+import 'bitecs';
+
+/**
+ * BigText Widget
+ *
+ * Renders large ASCII art text using bitmap fonts.
+ *
+ * @module widgets/bigText
+ */
+
+/**
+ * Dimension value that can be a number, percentage string, or 'auto'.
+ */
+type DimensionValue = number | `${number}%` | 'auto';
+/**
+ * Position value that can be a number, percentage string, or keyword.
+ */
+type PositionValue = number | `${number}%` | 'center' | 'left' | 'right' | 'top' | 'bottom';
+/**
+ * Bitmap font definition for BigText.
+ */
+type FontDefinition = BitmapFont;
+/**
+ * Configuration for creating a BigText widget.
+ */
+interface BigTextConfig {
+    /** Left position (absolute or percentage) */
+    readonly left?: PositionValue;
+    /** Top position (absolute or percentage) */
+    readonly top?: PositionValue;
+    /** Right position (absolute or percentage) */
+    readonly right?: PositionValue;
+    /** Bottom position (absolute or percentage) */
+    readonly bottom?: PositionValue;
+    /** Width (absolute, percentage, or 'auto') - defaults to 'auto' */
+    readonly width?: DimensionValue;
+    /** Height (absolute, percentage, or 'auto') - defaults to 'auto' */
+    readonly height?: DimensionValue;
+    /** Foreground color (hex string or packed number) */
+    readonly fg?: string | number;
+    /** Background color (hex string or packed number) */
+    readonly bg?: string | number;
+    /** Text content */
+    readonly text: string;
+    /** Font name (built-in), path, or font definition */
+    readonly font?: string | FontDefinition;
+    /** Whether to shrink to content size (default: true) */
+    readonly shrink?: boolean;
+}
+/**
+ * BigText widget interface providing chainable methods.
+ */
+interface BigTextWidget {
+    /** The underlying entity ID */
+    readonly eid: Entity;
+    /** Shows the widget */
+    show(): BigTextWidget;
+    /** Hides the widget */
+    hide(): BigTextWidget;
+    /** Moves the widget by dx, dy */
+    move(dx: number, dy: number): BigTextWidget;
+    /** Sets the absolute position */
+    setPosition(x: number, y: number): BigTextWidget;
+    /** Sets the text content */
+    setText(text: string): BigTextWidget;
+    /** Gets the text content */
+    getText(): string;
+    /** Focuses the widget */
+    focus(): BigTextWidget;
+    /** Blurs the widget */
+    blur(): BigTextWidget;
+    /** Checks if the widget is focused */
+    isFocused(): boolean;
+    /** Appends a child entity to this widget */
+    append(child: Entity): BigTextWidget;
+    /** Gets all direct children of this widget */
+    getChildren(): Entity[];
+    /** Destroys the widget and removes it from the world */
+    destroy(): void;
+}
+/**
+ * Zod schema for BigText widget configuration.
+ */
+declare const BigTextConfigSchema: z.ZodObject<{
+    left: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodEnum<{
+        left: "left";
+        top: "top";
+        right: "right";
+        bottom: "bottom";
+        center: "center";
+    }>]>>;
+    top: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodEnum<{
+        left: "left";
+        top: "top";
+        right: "right";
+        bottom: "bottom";
+        center: "center";
+    }>]>>;
+    right: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodEnum<{
+        left: "left";
+        top: "top";
+        right: "right";
+        bottom: "bottom";
+        center: "center";
+    }>]>>;
+    bottom: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodEnum<{
+        left: "left";
+        top: "top";
+        right: "right";
+        bottom: "bottom";
+        center: "center";
+    }>]>>;
+    width: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodLiteral<"auto">]>>;
+    height: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodLiteral<"auto">]>>;
+    fg: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    bg: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    text: z.ZodString;
+    font: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        size: z.ZodNumber;
+        weight: z.ZodEnum<{
+            bold: "bold";
+            normal: "normal";
+        }>;
+        charWidth: z.ZodNumber;
+        charHeight: z.ZodNumber;
+        chars: z.ZodRecord<z.ZodString, z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            bitmap: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodLiteral<0>, z.ZodLiteral<1>]>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>]>>;
+    shrink: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * BigText component marker for identifying BigText entities.
+ */
+declare const BigText: {
+    /** Tag indicating this is a BigText widget (1 = yes) */
+    isBigText: Uint8Array<ArrayBuffer>;
+};
+/**
+ * Loads a bitmap font definition from a JSON file path.
+ *
+ * @param path - Path to the font JSON file
+ * @returns Loaded font definition
+ *
+ * @example
+ * ```typescript
+ * import { loadFontFromPath } from 'blecsd/widgets/bigText';
+ *
+ * const font = loadFontFromPath('./fonts/terminus-14-bold.json');
+ * ```
+ */
+declare function loadFontFromPath(path: string): FontDefinition;
+/** @deprecated Use `loadFontFromPath` instead */
+declare const loadFont: typeof loadFontFromPath;
+/**
+ * Creates a BigText widget with the given configuration.
+ *
+ * Returns a Promise because font data is loaded lazily to avoid bundling
+ * ~3.2 MB of font JSON into the main entry point.
+ *
+ * @param world - The ECS world
+ * @param entity - The entity to wrap
+ * @param config - Widget configuration
+ * @returns Promise resolving to the BigText widget instance
+ *
+ * @example
+ * ```typescript
+ * import { createWorld, addEntity } from '../core/ecs';
+ * import { createBigText } from 'blecsd/widgets';
+ *
+ * const world = createWorld();
+ * const eid = addEntity(world);
+ *
+ * const bigText = await createBigText(world, eid, {
+ *   text: 'HELLO',
+ *   font: 'terminus-14-bold',
+ * });
+ * ```
+ */
+declare function createBigText(world: World, entity: Entity, config: BigTextConfig): Promise<BigTextWidget>;
+/**
+ * Sets the text content of a BigText entity.
+ *
+ * Uses the cached font if available (synchronous), otherwise falls back
+ * to async font loading. For best performance, pre-load fonts with
+ * `loadFont()` from `blecsd/widgets/fonts` before calling this.
+ *
+ * @param world - The ECS world
+ * @param eid - The entity ID
+ * @param text - The text content
+ * @param font - Optional font override (name, path, or font definition)
+ *
+ * @example
+ * ```typescript
+ * import { setText } from 'blecsd/widgets';
+ *
+ * setText(world, bigTextEntity, 'NEW TEXT');
+ * ```
+ */
+declare function setText(world: World, eid: Entity, text: string, font?: string | FontDefinition): void;
+/**
+ * Checks if an entity is a BigText widget.
+ *
+ * @param _world - The ECS world (unused, for API consistency)
+ * @param eid - The entity ID
+ * @returns true if the entity is a BigText widget
+ *
+ * @example
+ * ```typescript
+ * import { isBigText } from 'blecsd/widgets';
+ *
+ * if (isBigText(world, entity)) {
+ *   // Handle big text-specific logic
+ * }
+ * ```
+ */
+declare function isBigText(_world: World, eid: Entity): boolean;
+/**
+ * Resets the BigText component store. Useful for testing.
+ * @internal
+ */
+declare function resetBigTextStore(): void;
+
+export { BigText, type BigTextConfig, BigTextConfigSchema, type BigTextWidget, type DimensionValue, type FontDefinition, type PositionValue, createBigText, isBigText, loadFont, loadFontFromPath, resetBigTextStore, setText };

package/dist/widgets/bigText.js

@@ -0,0 +1 @@
+export{b as BigText,a as BigTextConfigSchema,e as createBigText,g as isBigText,d as loadFont,c as loadFontFromPath,h as resetBigTextStore,f as setText}from'../chunk-3EGGGI5J.js';import'../chunk-DNRXW56C.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';