linecraft 0.1.0 → 0.2.0

package/TESTING.md

@@ -1,102 +0,0 @@
-# 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

@@ -1,100 +0,0 @@
-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

@@ -1,21 +0,0 @@
-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

@@ -1,29 +0,0 @@
-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

@@ -1,20 +0,0 @@
-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

@@ -1,23 +0,0 @@
-// 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/src/ts/components/progress-bar.ts

@@ -1,53 +0,0 @@
-import { TerminalRegion } from '../region.js';
-import type { ProgressBarOptions } from '../types.js';
-
-export class ProgressBar {
-  private region: TerminalRegion;
-  private lineNumber: number; // 1-based
-  private current: number = 0;
-  private total: number = 100;
-  private label: string;
-  private width: number;
-  private completeChar: string;
-  private incompleteChar: string;
-  private brackets: [string, string];
-
-  constructor(region: TerminalRegion, lineNumber: number, options: ProgressBarOptions = {}) {
-    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: number, total: number): void {
-    this.current = current;
-    this.total = total;
-    this.render();
-  }
-
-  setLabel(label: string): void {
-    this.label = label;
-    this.render();
-  }
-
-  private render(): void {
-    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(): void {
-    this.update(this.total, this.total);
-  }
-}
-

package/src/ts/components/spinner.ts

@@ -1,56 +0,0 @@
-import { TerminalRegion } from '../region.js';
-import type { SpinnerOptions } from '../types.js';
-
-const DEFAULT_SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
-
-export class Spinner {
-  private region: TerminalRegion;
-  private lineNumber: number; // 1-based
-  private frameIndex: number = 0;
-  private text: string = '';
-  private interval?: NodeJS.Timeout;
-  private isRunning: boolean = false;
-  private frames: string[];
-  private intervalMs: number;
-
-  constructor(region: TerminalRegion, lineNumber: number, options: SpinnerOptions = {}) {
-    this.region = region;
-    this.lineNumber = lineNumber;
-    this.frames = options.frames ?? DEFAULT_SPINNER_FRAMES;
-    this.intervalMs = options.interval ?? 100;
-  }
-
-  start(): void {
-    if (this.isRunning) return;
-    this.isRunning = true;
-    this.interval = setInterval(() => {
-      this.render();
-      this.frameIndex = (this.frameIndex + 1) % this.frames.length;
-    }, this.intervalMs);
-  }
-
-  stop(): void {
-    if (!this.isRunning) return;
-    this.isRunning = false;
-    if (this.interval) {
-      clearInterval(this.interval);
-    }
-    // Clear the spinner line
-    this.region.setLine(this.lineNumber, '');
-  }
-
-  setText(text: string): void {
-    this.text = text;
-    this.render();
-  }
-
-  private render(): void {
-    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
-  }
-}
-

package/src/ts/index.ts

@@ -1,37 +0,0 @@
-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 function createRegion(options?: RegionOptions): TerminalRegion {
-  return new TerminalRegion(options);
-}
-
-export function createProgressBar(
-  region: TerminalRegion,
-  lineNumber: number,
-  options?: ProgressBarOptions
-): ProgressBar {
-  return new ProgressBar(region, lineNumber, options);
-}
-
-export function createSpinner(
-  region: TerminalRegion,
-  lineNumber: number,
-  options?: SpinnerOptions
-): Spinner {
-  return new Spinner(region, lineNumber, options);
-}
-

package/src/ts/native.ts

@@ -1,86 +0,0 @@
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-import { Library } from 'ffi-napi';
-import ref from 'ref-napi';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// Determine the library path based on platform
-function getLibraryPath(): string {
-  const platform = process.platform;
-  
-  if (platform === 'darwin') {
-    return join(__dirname, '../../zig-out/lib/libechokit.dylib');
-  } else if (platform === 'win32') {
-    return join(__dirname, '../../zig-out/lib/echokit.dll');
-  } else {
-    return join(__dirname, '../../zig-out/lib/libechokit.so');
-  }
-}
-
-// Load the Zig library using FFI
-const lib = Library(getLibraryPath(), {
-  create_region: ['uint64', ['uint32', 'uint32', 'uint32', 'uint32']],
-  destroy_region: ['void', ['uint64']],
-  set_line: ['void', ['uint64', 'uint32', 'pointer', 'size_t']],
-  set: ['void', ['uint64', 'pointer', 'size_t']],
-  clear_line: ['void', ['uint64', 'uint32']],
-  clear_region: ['void', ['uint64']],
-  flush: ['void', ['uint64']],
-  set_throttle_fps: ['void', ['uint64', 'uint32']],
-});
-
-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; // 1-based
-  set(handle: number, content: string): void;
-  clearLine(handle: number, lineNumber: number): void; // 1-based
-  clearRegion(handle: number): void;
-  flush(handle: number): void;
-  setThrottleFps(handle: number, fps: number): void;
-}
-
-export const native: NativeRegion = {
-  createRegion: (x: number, y: number, width: number, height: number): number => {
-    return Number(lib.create_region(x, y, width, height));
-  },
-  
-  destroyRegion: (handle: number): void => {
-    lib.destroy_region(BigInt(handle));
-  },
-  
-  setLine: (handle: number, lineNumber: number, content: string): void => {
-    const buf = Buffer.from(content, 'utf8');
-    // Allocate a buffer and copy the string data
-    const ptr = ref.alloc(buf.length);
-    buf.copy(ptr);
-    lib.set_line(BigInt(handle), lineNumber, ptr, buf.length);
-  },
-  
-  set: (handle: number, content: string): void => {
-    const buf = Buffer.from(content, 'utf8');
-    // Allocate a buffer and copy the string data
-    const ptr = ref.alloc(buf.length);
-    buf.copy(ptr);
-    lib.set(BigInt(handle), ptr, buf.length);
-  },
-  
-  clearLine: (handle: number, lineNumber: number): void => {
-    lib.clear_line(BigInt(handle), lineNumber);
-  },
-  
-  clearRegion: (handle: number): void => {
-    lib.clear_region(BigInt(handle));
-  },
-  
-  flush: (handle: number): void => {
-    lib.flush(BigInt(handle));
-  },
-  
-  setThrottleFps: (handle: number, fps: number): void => {
-    lib.set_throttle_fps(BigInt(handle), fps);
-  },
-};
-

package/src/ts/region.ts

@@ -1,89 +0,0 @@
-import { native } from './native.js';
-import { applyStyle } from './utils/colors.js';
-import type { RegionOptions, LineContent, TextStyle } from './types.js';
-
-export class TerminalRegion {
-  private handle: number;
-  private _width: number;
-  private _height: number; // Current height (may expand)
-
-  constructor(options: RegionOptions = {}) {
-    const x = options.x ?? 0;
-    const y = options.y ?? 0;
-    this._width = options.width ?? (process.stdout.columns ?? 80);
-    this._height = options.height ?? 1; // Default to 1 line, expands as needed
-    this.handle = native.createRegion(x, y, this._width, this._height);
-  }
-
-  get width(): number {
-    return this._width;
-  }
-
-  get height(): number {
-    return this._height;
-  }
-
-  setLine(lineNumber: number, content: string | LineContent): void {
-    if (lineNumber < 1) {
-      throw new Error('Line numbers start at 1');
-    }
-
-    // Zig handles batching and expansion automatically
-    const text = typeof content === 'string' ? content : content.text;
-    // Apply styling if provided
-    const styled = applyStyle(text, typeof content === 'object' ? content.style : undefined);
-    native.setLine(this.handle, lineNumber, styled);
-    // Zig will:
-    //   - Convert to 0-based internally
-    //   - Expand region if lineNumber > current height
-    //   - Buffer this update in pending_frame
-    //   - Check throttle
-    //   - Schedule render if needed (or render immediately if throttle allows)
-
-    // Update our height tracking if Zig expanded
-    if (lineNumber > this._height) {
-      this._height = lineNumber;
-    }
-  }
-
-  set(content: string | LineContent[]): void {
-    if (typeof content === 'string') {
-      // Single string with \n line breaks
-      native.set(this.handle, content);
-      // Update height based on line count
-      this._height = content.split('\n').length;
-    } else {
-      // Array of LineContent
-      const lines = content.map(c => 
-        applyStyle(c.text, c.style)
-      ).join('\n');
-      native.set(this.handle, lines);
-      this._height = content.length;
-    }
-  }
-
-  clearLine(lineNumber: number): void {
-    if (lineNumber < 1) {
-      throw new Error('Line numbers start at 1');
-    }
-    native.clearLine(this.handle, lineNumber);
-  }
-
-  clear(): void {
-    native.clearRegion(this.handle);
-  }
-
-  flush(): void {
-    // Force immediate render of any pending updates (bypasses throttle)
-    native.flush(this.handle);
-  }
-
-  setThrottle(fps: number): void {
-    native.setThrottleFps(this.handle, fps);
-  }
-
-  destroy(): void {
-    native.destroyRegion(this.handle);
-  }
-}
-

package/src/ts/types/ffi-napi.d.ts

@@ -1,11 +0,0 @@
-declare module 'ffi-napi' {
-  export interface Library {
-    [key: string]: (...args: any[]) => any;
-  }
-  
-  export function Library(
-    path: string,
-    functions: Record<string, [string, string[]]>
-  ): Library;
-}
-

package/src/ts/types/ref-napi.d.ts

@@ -1,5 +0,0 @@
-declare module 'ref-napi' {
-  export function alloc(size: number): Buffer;
-  export function alloc(type: string, size: number): Buffer;
-}
-