linecraft 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 EchoKit Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,111 @@
+# EchoKit
+
+High-performance terminal UI library for Node.js with Zig backend.
+
+EchoKit provides a friendly TypeScript API while leveraging Zig's speed and efficiency for terminal operations like diffing, ANSI cursor movement, buffering, and throttling.
+
+## Features
+
+- **High Performance**: Zig backend handles all performance-critical operations
+- **Automatic Batching**: Updates are automatically batched and throttled
+- **Dynamic Regions**: Regions expand automatically as you add lines
+- **Simple API**: Clean, intuitive TypeScript interface
+- **Components**: Built-in progress bars and spinners
+
+## Installation
+
+```bash
+pnpm install echokit
+```
+
+## Quick Start
+
+### Basic Progress Bar
+
+```typescript
+import { createRegion, createProgressBar } from 'echokit';
+
+const region = createRegion({ width: 80 });
+const progress = createProgressBar(region, 1, {
+  label: 'Installing packages',
+  width: 50,
+});
+
+for (let i = 0; i <= 100; i++) {
+  progress.update(i, 100);
+  await new Promise(resolve => setTimeout(resolve, 50));
+}
+
+progress.finish();
+region.destroy();
+```
+
+### Spinner
+
+```typescript
+import { createRegion, createSpinner } from 'echokit';
+
+const region = createRegion({ width: 80 });
+const spinner = createSpinner(region, 1);
+
+spinner.setText('Processing...');
+spinner.start();
+
+// Do work...
+await doWork();
+
+spinner.stop();
+region.destroy();
+```
+
+### Custom Layout
+
+```typescript
+import { createRegion } from 'echokit';
+
+const region = createRegion({ width: 80 });
+
+// Set individual lines (1-based)
+region.setLine(1, { text: 'Status:', style: { bold: true } });
+region.setLine(2, '  ✓ Connected');
+region.setLine(3, '  ⏳ Processing...');
+
+// Or set entire content at once
+region.set(`Status:
+  ✓ Connected
+  ⏳ Processing...
+  ✗ Error`);
+```
+
+## API
+
+### `createRegion(options?)`
+
+Creates a new terminal region.
+
+**Options:**
+- `x?: number` - X position (default: 0)
+- `y?: number` - Y position (default: 0)
+- `width?: number` - Width (default: terminal width)
+- `height?: number` - Initial height (default: 1, expands as needed)
+
+### `region.setLine(lineNumber, content)`
+
+Set a single line (1-based). Region expands automatically if needed.
+
+### `region.set(content)`
+
+Set entire content. Can be a string with `\n` separators or an array of `LineContent`.
+
+### `region.flush()`
+
+Force immediate render of pending updates (bypasses throttle).
+
+### `region.setThrottle(fps)`
+
+Set maximum render rate (default: 60 FPS).
+
+## License
+
+MIT
+

package/TESTING.md

@@ -0,0 +1,102 @@
+# Testing EchoKit
+
+## Running Tests
+
+### All Tests
+```bash
+zig build test
+# or
+pnpm test
+```
+
+### Individual Test Modules
+```bash
+# ANSI tests only
+zig build test:ansi
+
+# Throttle tests only
+zig build test:throttle
+
+# Buffer tests only
+zig build test:buffer
+
+# Diff tests only
+zig build test:diff
+
+# Region tests only
+zig build test:region
+```
+
+## Test Coverage
+
+### ANSI Module (`test_ansi.zig`)
+- ✅ `move_cursor_to` - Generates correct cursor positioning ANSI
+- ✅ `move_cursor_up` - Generates correct up movement ANSI
+- ✅ `move_cursor_down` - Generates correct down movement ANSI
+- ✅ ANSI constants - All constants verified
+- ✅ `move_cursor_to` with zero coordinates
+- ✅ `move_cursor_to` with large coordinates
+- ✅ `move_cursor_up` with zero
+
+### Throttle Module (`test_throttle.zig`)
+- ✅ Initialization - Creates throttle with correct FPS
+- ✅ `set_fps` - Changes FPS correctly
+- ✅ `should_render` - Allows first frame
+- ✅ `should_render` - Respects interval (blocks immediate second frame)
+- ✅ `time_until_next_frame` - Calculates remaining time correctly
+- ✅ Very high FPS (1000 FPS)
+- ✅ Very low FPS (1 FPS)
+
+### Buffer Module (`test_buffer.zig`)
+- ✅ Initialization - Creates empty buffer
+- ✅ `write` - Appends data correctly
+- ✅ `clear` - Clears buffer
+- ✅ `flush` - Writes to stdout and clears
+- ✅ Large content handling
+- ✅ Multiple writes and flush
+
+### Diff Module (`test_diff.zig`)
+- ✅ Identical frames - Returns no_change ops
+- ✅ Changed line - Detects line updates
+- ✅ Inserted line - Detects new lines
+- ✅ Deleted line - Detects removed lines
+- ✅ Multiple changes - Handles complex diffs
+- ✅ Empty frames
+- ✅ Completely different frames
+
+### Region Module (`test_region.zig`)
+- ✅ Initialization - Creates region with correct dimensions
+- ✅ `set_line` - Expands automatically when needed
+- ✅ `set_line` - Rejects line 0 (1-based indexing)
+- ✅ `set` - Splits content by newlines correctly
+- ✅ `expand_to` - Expands region height
+- ✅ `clear_line` - Clears individual lines
+- ✅ Throttle configuration - Sets FPS correctly
+- ✅ `set_line` with empty string
+- ✅ `set` with empty content
+- ✅ `set` with single line (no newline)
+- ✅ Multiple `set_line` calls
+- ✅ `clear` all lines
+
+### Integration Tests (`test_integration.zig`)
+- ✅ Region with diff and throttle together
+- ✅ Region expansion with multiple operations
+- ✅ `set` then `set_line` interaction
+
+## Test Output
+
+All tests print visible output to the console using `std.debug.print()`. Each test shows:
+- ✓ Checkmark for passed assertions
+- Test name and module
+- Relevant values being tested
+
+Example output:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Testing: ANSI Module
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  ✓ move_cursor_to(10, 5): [1b[5;10H
+  ✓ move_cursor_up(3): [1b[3A
+  ✓ All ANSI constants verified
+```
+

package/build.zig

@@ -0,0 +1,100 @@
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    // Create shared library for Node.js addon
+    // In Zig 0.15.x, target and optimize must be set in createModule
+    const lib = b.addLibrary(.{
+        .name = "echokit",
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/zig/renderer.zig"),
+            .target = target,
+            .optimize = optimize,
+        }),
+        .linkage = .dynamic, // Shared library for Node.js addon
+    });
+
+    // Link with libc (needed for N-API)
+    lib.linkLibC();
+
+    // Install the library (defaults to zig-out/lib/)
+    b.installArtifact(lib);
+
+    // Test all modules together
+    // Using addTest automatically discovers all test functions
+    const test_exe = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/zig/test_runner.zig"),
+            .target = target,
+            .optimize = optimize,
+        }),
+    });
+
+    const run_tests = b.addRunArtifact(test_exe);
+    run_tests.has_side_effects = true;
+    const test_step = b.step("test", "Run all Zig tests with visible console output");
+    test_step.dependOn(&run_tests.step);
+
+    // Individual test modules (can be run separately for focused testing)
+    const test_ansi = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/zig/test_ansi.zig"),
+            .target = target,
+            .optimize = optimize,
+        }),
+    });
+    const run_test_ansi = b.addRunArtifact(test_ansi);
+    run_test_ansi.has_side_effects = true;
+    const test_ansi_step = b.step("test:ansi", "Run ANSI tests only");
+    test_ansi_step.dependOn(&run_test_ansi.step);
+
+    const test_throttle = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/zig/test_throttle.zig"),
+            .target = target,
+            .optimize = optimize,
+        }),
+    });
+    const run_test_throttle = b.addRunArtifact(test_throttle);
+    run_test_throttle.has_side_effects = true;
+    const test_throttle_step = b.step("test:throttle", "Run Throttle tests only");
+    test_throttle_step.dependOn(&run_test_throttle.step);
+
+    const test_buffer = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/zig/test_buffer.zig"),
+            .target = target,
+            .optimize = optimize,
+        }),
+    });
+    const run_test_buffer = b.addRunArtifact(test_buffer);
+    run_test_buffer.has_side_effects = true;
+    const test_buffer_step = b.step("test:buffer", "Run Buffer tests only");
+    test_buffer_step.dependOn(&run_test_buffer.step);
+
+    const test_diff = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/zig/test_diff.zig"),
+            .target = target,
+            .optimize = optimize,
+        }),
+    });
+    const run_test_diff = b.addRunArtifact(test_diff);
+    run_test_diff.has_side_effects = true;
+    const test_diff_step = b.step("test:diff", "Run Diff tests only");
+    test_diff_step.dependOn(&run_test_diff.step);
+
+    const test_region = b.addTest(.{
+        .root_module = b.createModule(.{
+            .root_source_file = b.path("src/zig/test_region.zig"),
+            .target = target,
+            .optimize = optimize,
+        }),
+    });
+    const run_test_region = b.addRunArtifact(test_region);
+    run_test_region.has_side_effects = true;
+    const test_region_step = b.step("test:region", "Run Region tests only");
+    test_region_step.dependOn(&run_test_region.step);
+}

package/examples/basic-progress.ts

@@ -0,0 +1,21 @@
+import { createRegion, createProgressBar } from '../src/ts';
+
+async function main() {
+  const region = createRegion({ width: 80 });
+  const progress = createProgressBar(region, 1, {
+    label: 'Installing packages',
+    width: 50,
+  });
+
+  for (let i = 0; i <= 100; i++) {
+    progress.update(i, 100);
+    await new Promise(resolve => setTimeout(resolve, 50));
+  }
+
+  progress.finish();
+  await new Promise(resolve => setTimeout(resolve, 1000));
+  region.destroy();
+}
+
+main().catch(console.error);
+

package/examples/multi-lane.ts

@@ -0,0 +1,29 @@
+import { createRegion, createProgressBar } from '../src/ts/index.js';
+
+async function updateProgress(progress: ReturnType<typeof createProgressBar>, total: number) {
+  for (let i = 0; i <= total; i++) {
+    progress.update(i, total);
+    await new Promise(resolve => setTimeout(resolve, 20 + Math.random() * 30));
+  }
+}
+
+async function main() {
+  const region = createRegion({ width: 80 });
+
+  const download = createProgressBar(region, 1, { label: 'Downloading' });
+  const extract = createProgressBar(region, 2, { label: 'Extracting' });
+  const install = createProgressBar(region, 3, { label: 'Installing' });
+
+  // Update lanes concurrently
+  await Promise.all([
+    updateProgress(download, 100),
+    updateProgress(extract, 100),
+    updateProgress(install, 100),
+  ]);
+
+  await new Promise(resolve => setTimeout(resolve, 1000));
+  region.destroy();
+}
+
+main().catch(console.error);
+

package/examples/spinner.ts

@@ -0,0 +1,20 @@
+import { createRegion, createSpinner } from '../src/ts/index.js';
+
+async function main() {
+  const region = createRegion({ width: 80 });
+  const spinner = createSpinner(region, 1);
+
+  spinner.setText('Processing...');
+  spinner.start();
+
+  // Simulate work
+  await new Promise(resolve => setTimeout(resolve, 3000));
+
+  spinner.stop();
+  region.setLine(1, '✓ Done!');
+  await new Promise(resolve => setTimeout(resolve, 1000));
+  region.destroy();
+}
+
+main().catch(console.error);
+

package/examples/test-basic.ts

@@ -0,0 +1,23 @@
+// Simple test to verify the Node.js API works
+import { createRegion } from '../src/ts/index.js';
+
+console.log('Creating region...');
+const region = createRegion({ x: 0, y: 0, width: 80, height: 1 });
+
+console.log('Setting line 1...');
+region.setLine(1, 'Hello from EchoKit!');
+
+console.log('Setting line 2 (should expand)...');
+region.setLine(2, 'This is line 2');
+
+console.log('Setting multiple lines...');
+region.set('Line 1\nLine 2\nLine 3');
+
+console.log('Flushing...');
+region.flush();
+
+console.log('Cleaning up...');
+region.destroy();
+
+console.log('Test complete!');
+

package/lib/components/progress-bar.d.ts

@@ -0,0 +1,19 @@
+import { TerminalRegion } from '../region.js';
+import type { ProgressBarOptions } from '../types.js';
+export declare class ProgressBar {
+    private region;
+    private lineNumber;
+    private current;
+    private total;
+    private label;
+    private width;
+    private completeChar;
+    private incompleteChar;
+    private brackets;
+    constructor(region: TerminalRegion, lineNumber: number, options?: ProgressBarOptions);
+    update(current: number, total: number): void;
+    setLabel(label: string): void;
+    private render;
+    finish(): void;
+}
+//# sourceMappingURL=progress-bar.d.ts.map

package/lib/components/progress-bar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-bar.d.ts","sourceRoot":"","sources":["../../src/ts/components/progress-bar.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,OAAO,CAAa;IAC5B,OAAO,CAAC,KAAK,CAAe;IAC5B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAmB;gBAEvB,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB;IAUxF,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAM5C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAK7B,OAAO,CAAC,MAAM;IAad,MAAM,IAAI,IAAI;CAGf"}

package/lib/components/progress-bar.js

@@ -0,0 +1,43 @@
+export class ProgressBar {
+    region;
+    lineNumber; // 1-based
+    current = 0;
+    total = 100;
+    label;
+    width;
+    completeChar;
+    incompleteChar;
+    brackets;
+    constructor(region, lineNumber, options = {}) {
+        this.region = region;
+        this.lineNumber = lineNumber;
+        this.label = options.label || '';
+        this.width = options.width ?? 40;
+        this.completeChar = options.style?.complete ?? '█';
+        this.incompleteChar = options.style?.incomplete ?? '░';
+        this.brackets = options.style?.brackets ?? ['[', ']'];
+    }
+    update(current, total) {
+        this.current = current;
+        this.total = total;
+        this.render();
+    }
+    setLabel(label) {
+        this.label = label;
+        this.render();
+    }
+    render() {
+        const percentage = Math.min(100, Math.max(0, (this.current / this.total) * 100));
+        const filled = Math.floor((percentage / 100) * this.width);
+        const empty = this.width - filled;
+        const bar = this.completeChar.repeat(filled) + this.incompleteChar.repeat(empty);
+        const text = `${this.label} ${this.brackets[0]}${bar}${this.brackets[1]} ${percentage.toFixed(1)}%`;
+        // Just update the line - Zig handles batching and rendering
+        this.region.setLine(this.lineNumber, text);
+        // Optional: call flush() if you need immediate rendering
+    }
+    finish() {
+        this.update(this.total, this.total);
+    }
+}
+//# sourceMappingURL=progress-bar.js.map

package/lib/components/progress-bar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress-bar.js","sourceRoot":"","sources":["../../src/ts/components/progress-bar.ts"],"names":[],"mappings":"AAGA,MAAM,OAAO,WAAW;IACd,MAAM,CAAiB;IACvB,UAAU,CAAS,CAAC,UAAU;IAC9B,OAAO,GAAW,CAAC,CAAC;IACpB,KAAK,GAAW,GAAG,CAAC;IACpB,KAAK,CAAS;IACd,KAAK,CAAS;IACd,YAAY,CAAS;IACrB,cAAc,CAAS;IACvB,QAAQ,CAAmB;IAEnC,YAAY,MAAsB,EAAE,UAAkB,EAAE,UAA8B,EAAE;QACtF,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;QACjC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;QACjC,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,KAAK,EAAE,QAAQ,IAAI,GAAG,CAAC;QACnD,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,KAAK,EAAE,UAAU,IAAI,GAAG,CAAC;QACvD,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,KAAK,EAAE,QAAQ,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACxD,CAAC;IAED,MAAM,CAAC,OAAe,EAAE,KAAa;QACnC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM,EAAE,CAAC;IAChB,CAAC;IAED,QAAQ,CAAC,KAAa;QACpB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM,EAAE,CAAC;IAChB,CAAC;IAEO,MAAM;QACZ,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;QACjF,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,UAAU,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAC3D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC;QAElC,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACjF,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;QAEpG,4DAA4D;QAC5D,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QAC3C,yDAAyD;IAC3D,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IACtC,CAAC;CACF"}

package/lib/components/spinner.d.ts

@@ -0,0 +1,18 @@
+import { TerminalRegion } from '../region.js';
+import type { SpinnerOptions } from '../types.js';
+export declare class Spinner {
+    private region;
+    private lineNumber;
+    private frameIndex;
+    private text;
+    private interval?;
+    private isRunning;
+    private frames;
+    private intervalMs;
+    constructor(region: TerminalRegion, lineNumber: number, options?: SpinnerOptions);
+    start(): void;
+    stop(): void;
+    setText(text: string): void;
+    private render;
+}
+//# sourceMappingURL=spinner.d.ts.map

package/lib/components/spinner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.d.ts","sourceRoot":"","sources":["../../src/ts/components/spinner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD,qBAAa,OAAO;IAClB,OAAO,CAAC,MAAM,CAAiB;IAC/B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,IAAI,CAAc;IAC1B,OAAO,CAAC,QAAQ,CAAC,CAAiB;IAClC,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,UAAU,CAAS;gBAEf,MAAM,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB;IAOpF,KAAK,IAAI,IAAI;IASb,IAAI,IAAI,IAAI;IAUZ,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK3B,OAAO,CAAC,MAAM;CAQf"}

package/lib/components/spinner.js

@@ -0,0 +1,48 @@
+const DEFAULT_SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+export class Spinner {
+    region;
+    lineNumber; // 1-based
+    frameIndex = 0;
+    text = '';
+    interval;
+    isRunning = false;
+    frames;
+    intervalMs;
+    constructor(region, lineNumber, options = {}) {
+        this.region = region;
+        this.lineNumber = lineNumber;
+        this.frames = options.frames ?? DEFAULT_SPINNER_FRAMES;
+        this.intervalMs = options.interval ?? 100;
+    }
+    start() {
+        if (this.isRunning)
+            return;
+        this.isRunning = true;
+        this.interval = setInterval(() => {
+            this.render();
+            this.frameIndex = (this.frameIndex + 1) % this.frames.length;
+        }, this.intervalMs);
+    }
+    stop() {
+        if (!this.isRunning)
+            return;
+        this.isRunning = false;
+        if (this.interval) {
+            clearInterval(this.interval);
+        }
+        // Clear the spinner line
+        this.region.setLine(this.lineNumber, '');
+    }
+    setText(text) {
+        this.text = text;
+        this.render();
+    }
+    render() {
+        const frame = this.frames[this.frameIndex];
+        const line = `${frame} ${this.text}`;
+        // Just update the line - Zig handles batching and rendering
+        this.region.setLine(this.lineNumber, line);
+        // Spinner updates frequently, so Zig's throttling will handle smooth animation
+    }
+}
+//# sourceMappingURL=spinner.js.map

package/lib/components/spinner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.js","sourceRoot":"","sources":["../../src/ts/components/spinner.ts"],"names":[],"mappings":"AAGA,MAAM,sBAAsB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;AAElF,MAAM,OAAO,OAAO;IACV,MAAM,CAAiB;IACvB,UAAU,CAAS,CAAC,UAAU;IAC9B,UAAU,GAAW,CAAC,CAAC;IACvB,IAAI,GAAW,EAAE,CAAC;IAClB,QAAQ,CAAkB;IAC1B,SAAS,GAAY,KAAK,CAAC;IAC3B,MAAM,CAAW;IACjB,UAAU,CAAS;IAE3B,YAAY,MAAsB,EAAE,UAAkB,EAAE,UAA0B,EAAE;QAClF,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,sBAAsB,CAAC;QACvD,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,QAAQ,IAAI,GAAG,CAAC;IAC5C,CAAC;IAED,KAAK;QACH,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO;QAC3B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,WAAW,CAAC,GAAG,EAAE;YAC/B,IAAI,CAAC,MAAM,EAAE,CAAC;YACd,IAAI,CAAC,UAAU,GAAG,CAAC,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;QAC/D,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACtB,CAAC;IAED,IAAI;QACF,IAAI,CAAC,IAAI,CAAC,SAAS;YAAE,OAAO;QAC5B,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;QACvB,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC/B,CAAC;QACD,yBAAyB;QACzB,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED,OAAO,CAAC,IAAY;QAClB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,EAAE,CAAC;IAChB,CAAC;IAEO,MAAM;QACZ,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC3C,MAAM,IAAI,GAAG,GAAG,KAAK,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;QAErC,4DAA4D;QAC5D,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;QAC3C,+EAA+E;IACjF,CAAC;CACF"}

package/lib/index.d.ts

@@ -0,0 +1,12 @@
+export { TerminalRegion } from './region.js';
+export { ProgressBar } from './components/progress-bar.js';
+export { Spinner } from './components/spinner.js';
+export type { RegionOptions, LineContent, TextStyle, Color, ProgressBarOptions, SpinnerOptions, } from './types.js';
+import { TerminalRegion } from './region.js';
+import { ProgressBar } from './components/progress-bar.js';
+import { Spinner } from './components/spinner.js';
+import type { RegionOptions, ProgressBarOptions, SpinnerOptions } from './types.js';
+export declare function createRegion(options?: RegionOptions): TerminalRegion;
+export declare function createProgressBar(region: TerminalRegion, lineNumber: number, options?: ProgressBarOptions): ProgressBar;
+export declare function createSpinner(region: TerminalRegion, lineNumber: number, options?: SpinnerOptions): Spinner;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/ts/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,YAAY,EACV,aAAa,EACb,WAAW,EACX,SAAS,EACT,KAAK,EACL,kBAAkB,EAClB,cAAc,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEpF,wBAAgB,YAAY,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,cAAc,CAEpE;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,WAAW,CAEb;AAED,wBAAgB,aAAa,CAC3B,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAET"}

package/lib/index.js

@@ -0,0 +1,16 @@
+export { TerminalRegion } from './region.js';
+export { ProgressBar } from './components/progress-bar.js';
+export { Spinner } from './components/spinner.js';
+import { TerminalRegion } from './region.js';
+import { ProgressBar } from './components/progress-bar.js';
+import { Spinner } from './components/spinner.js';
+export function createRegion(options) {
+    return new TerminalRegion(options);
+}
+export function createProgressBar(region, lineNumber, options) {
+    return new ProgressBar(region, lineNumber, options);
+}
+export function createSpinner(region, lineNumber, options) {
+    return new Spinner(region, lineNumber, options);
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/ts/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAUlD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAGlD,MAAM,UAAU,YAAY,CAAC,OAAuB;IAClD,OAAO,IAAI,cAAc,CAAC,OAAO,CAAC,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,MAAsB,EACtB,UAAkB,EAClB,OAA4B;IAE5B,OAAO,IAAI,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,MAAsB,EACtB,UAAkB,EAClB,OAAwB;IAExB,OAAO,IAAI,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,CAAC;AAClD,CAAC"}

package/lib/native.d.ts

@@ -0,0 +1,12 @@
+export interface NativeRegion {
+    createRegion(x: number, y: number, width: number, height: number): number;
+    destroyRegion(handle: number): void;
+    setLine(handle: number, lineNumber: number, content: string): void;
+    set(handle: number, content: string): void;
+    clearLine(handle: number, lineNumber: number): void;
+    clearRegion(handle: number): void;
+    flush(handle: number): void;
+    setThrottleFps(handle: number, fps: number): void;
+}
+export declare const native: NativeRegion;
+//# sourceMappingURL=native.d.ts.map

package/lib/native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native.d.ts","sourceRoot":"","sources":["../src/ts/native.ts"],"names":[],"mappings":"AAiCA,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IAC1E,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACnE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACpD,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACnD;AAED,eAAO,MAAM,MAAM,EAAE,YAwCpB,CAAC"}