ansimax 1.0.0 → 1.1.0

package/examples/01-cli-installer.ts

@@ -0,0 +1,96 @@
+// ─────────────────────────────────────────────
+//  EXAMPLE 1 — CLI installer with hierarchical tasks
+//
+//  Demonstrates a realistic project setup flow:
+//   - Banner intro with theme gradient
+//   - Hierarchical tasks (parent + subtasks with rollup)
+//   - Status indicators with custom icons
+//   - Box for final summary
+//
+//  Run:
+//    npx ts-node examples/01-cli-installer.ts
+// ─────────────────────────────────────────────
+
+import {
+  ascii,
+  themes,
+  loader,
+  components,
+  configure,
+  sleep,
+} from '../dist/index.js';
+
+// Configure global defaults
+configure({
+  theme: 'dracula',
+  animationSpeed: 'fast',
+});
+
+// Simulated work
+const work = (ms: number, fail = false) => async (): Promise<string> => {
+  await sleep(ms);
+  if (fail) throw new Error('Simulated failure');
+  return 'ok';
+};
+
+const main = async (): Promise<void> => {
+  // ── Intro banner ──────────────────────────────
+  console.log();
+  console.log(themes.banner('CREATE-APP', { font: 'small' }));
+  console.log();
+  console.log(components.section(themes.primary('Initializing project'), { width: 60 }));
+  console.log();
+
+  // ── Hierarchical task list ────────────────────
+  const results = await loader.tasks([
+    {
+      text: 'Setup environment',
+      fn: work(300),
+      subtasks: [
+        { text: 'Detect Node version',  fn: work(150) },
+        { text: 'Verify npm registry',  fn: work(200) },
+        { text: 'Create project dir',   fn: work(100) },
+      ],
+    },
+    {
+      text: 'Install dependencies',
+      fn: work(400),
+      subtasks: [
+        { text: 'Resolve package tree', fn: work(250) },
+        { text: 'Download tarballs',    fn: work(500) },
+        { text: 'Build native modules', fn: work(300) },
+      ],
+    },
+    {
+      text: 'Run post-install hooks',
+      fn: work(200),
+      subtasks: [
+        { text: 'Generate types',  fn: work(150) },
+        { text: 'Lint workspace',  fn: work(180) },
+      ],
+    },
+  ]);
+
+  // ── Final summary box ─────────────────────────
+  console.log();
+  const succeeded = results.filter((r) => r.success).length;
+  const failed = results.length - succeeded;
+
+  const summary = [
+    components.status('success', `${succeeded} steps completed`),
+    failed > 0
+      ? components.status('error',  `${failed} steps failed`)
+      : components.status('info',   'No errors'),
+    '',
+    themes.muted('Next steps:'),
+    '  ' + themes.accent('cd my-app && npm run dev'),
+  ].join('\n');
+
+  console.log(components.box(summary, { borderStyle: 'rounded', padding: 1 }));
+  console.log();
+};
+
+main().catch((err) => {
+  console.error(themes.error('✗ ' + err.message));
+  process.exit(1);
+});

package/examples/02-live-dashboard.ts

@@ -0,0 +1,152 @@
+// ─────────────────────────────────────────────
+//  EXAMPLE 2 — Real-time dashboard with live updates
+//
+//  Demonstrates:
+//   - frames.live() for sticky bottom-of-screen UI
+//   - components.progressBar with gradient
+//   - components.table for data display
+//   - onResize listener for responsive layout
+//   - throttle for rate-limited updates
+//   - AbortSignal cleanup
+//
+//  Run:
+//    npx ts-node examples/02-live-dashboard.ts
+// ─────────────────────────────────────────────
+
+import {
+  themes,
+  components,
+  frames,
+  onResize,
+  throttle,
+  termSize,
+  sleep,
+  cursor,
+  screen,
+  write,
+} from '../dist/index.js';
+
+interface Stat {
+  service: string;
+  status:  'up' | 'down' | 'pending';
+  latency: number;
+  load:    number; // 0..100
+}
+
+// Simulated metrics that drift over time
+const stats: Stat[] = [
+  { service: 'api-gateway',  status: 'up',      latency: 14, load: 32 },
+  { service: 'auth-service', status: 'up',      latency: 22, load: 58 },
+  { service: 'database',     status: 'pending', latency: 0,  load: 0  },
+  { service: 'cdn-edge',     status: 'up',      latency: 8,  load: 18 },
+  { service: 'cache-layer',  status: 'up',      latency: 3,  load: 71 },
+];
+
+const drift = (): void => {
+  for (const s of stats) {
+    if (s.status === 'pending') {
+      // Pending services come online randomly
+      if (Math.random() < 0.1) {
+        s.status = 'up';
+        s.latency = 10 + Math.floor(Math.random() * 30);
+      }
+    } else if (s.status === 'up') {
+      // Slight load + latency wander
+      s.load = Math.max(0, Math.min(100, s.load + (Math.random() - 0.5) * 8));
+      s.latency = Math.max(1, s.latency + (Math.random() - 0.5) * 3);
+      // Tiny chance of going down
+      if (Math.random() < 0.005) s.status = 'down';
+    }
+  }
+};
+
+const renderFrame = (): string => {
+  const { cols } = termSize();
+  const innerWidth = Math.max(40, Math.min(cols - 4, 80));
+
+  // ── Header with theme gradient ──
+  const title = themes.banner('STATUS', { font: 'small', perCharColor: false });
+
+  // ── Service rows ──
+  const rows: string[][] = [
+    ['Service', 'Status', 'Latency', 'Load'],
+    ...stats.map((s) => {
+      const statusIcon =
+        s.status === 'up'      ? themes.accent('● up')
+      : s.status === 'down'    ? themes.error('● down')
+                               : themes.warning('● pending');
+
+      const latencyStr = s.status === 'up'
+        ? (s.latency < 20 ? themes.accent : s.latency < 50 ? themes.warning : themes.error)
+            (`${s.latency.toFixed(0)}ms`)
+        : themes.muted('—');
+
+      const loadBar = s.status === 'up'
+        ? components.progressBar(s.load, {
+            width: 20,
+            gradient: ['#00ff88', '#fdcb6e', '#ff6b6b'],
+            showPercentage: true,
+          })
+        : themes.muted('—');
+
+      return [s.service, statusIcon, latencyStr, loadBar];
+    }),
+  ];
+
+  const table = components.table(rows, { borderStyle: 'rounded', maxColWidth: innerWidth / 4 });
+
+  // ── Footer ──
+  const upCount   = stats.filter((s) => s.status === 'up').length;
+  const downCount = stats.filter((s) => s.status === 'down').length;
+  const footer = themes.muted(
+    `${upCount} up · ${downCount} down · ${stats.length} total · ` +
+    `${cols}×${termSize().rows} terminal · Ctrl+C to exit`,
+  );
+
+  return [title, '', table, '', footer].join('\n');
+};
+
+const main = async (): Promise<void> => {
+  // Hide cursor while live UI runs
+  write(cursor.hide());
+
+  // Throttled resize redraw — coalesce rapid resize events into one render
+  const onAnyResize = throttle(() => {
+    // Frame engine will pick up the new size on its next tick
+  }, 100);
+  const offResize = onResize(onAnyResize);
+
+  // Start live engine at 4 fps (smooth but not CPU-hungry)
+  const live = frames.live({ fps: 4, autoStart: true });
+
+  // Drift loop
+  const ctrl = new AbortController();
+  process.on('SIGINT', () => {
+    ctrl.abort();
+    live.stop({ clear: false });
+    offResize();
+    write(cursor.show());
+    write('\n');
+    console.log(themes.muted('Dashboard stopped.'));
+    process.exit(0);
+  });
+
+  try {
+    while (!ctrl.signal.aborted) {
+      drift();
+      live.update(renderFrame());
+      await sleep(250, { signal: ctrl.signal });
+    }
+  } catch {
+    // Aborted — fall through to cleanup
+  } finally {
+    live.stop({ clear: false });
+    offResize();
+    write(cursor.show());
+  }
+};
+
+main().catch((err) => {
+  console.error(themes.error('✗ ' + (err as Error).message));
+  process.exit(1);
+});

package/examples/03-pixel-art-game.ts

@@ -0,0 +1,170 @@
+// ─────────────────────────────────────────────
+//  EXAMPLE 3 — Pixel art game loop
+//
+//  Demonstrates:
+//   - Canvas with dirty-region rendering for FPS
+//   - Sprite drawing with alpha blending
+//   - Gradient backgrounds with Bayer dithering
+//   - Frame-rate locked game loop (drift-corrected)
+//   - Braille mode for high-resolution detail
+//
+//  A bouncing rocket on a sunset gradient with a star field.
+//
+//  Run:
+//    npx ts-node examples/03-pixel-art-game.ts
+// ─────────────────────────────────────────────
+
+import {
+  createCanvas,
+  images,
+  themes,
+  cursor,
+  screen,
+  write,
+  sleep,
+  termSize,
+  type RGBA,
+} from '../dist/index.js';
+
+const WIDTH  = 60;
+const HEIGHT = 30;
+
+// ── Build static background once ───────────────
+const buildBackground = (): ReturnType<typeof createCanvas> => {
+  const canvas = createCanvas(WIDTH, HEIGHT);
+
+  // Sunset gradient with Bayer dithering for smooth bands
+  const gradStr = images.gradientRect({
+    width: WIDTH,
+    height: HEIGHT,
+    colors: ['#1a1a2e', '#16213e', '#fd7272', '#f9ca24'],
+    style: 'vertical',
+    dither: 'bayer',
+  });
+  // gradientRect returns rendered text; instead we build pixels manually
+  // so we can composite sprites on top.
+  for (let y = 0; y < HEIGHT; y++) {
+    for (let x = 0; x < WIDTH; x++) {
+      // Simple vertical sunset
+      const t = y / (HEIGHT - 1);
+      const r = Math.round(0x1a + (0xf9 - 0x1a) * t);
+      const g = Math.round(0x1a + (0xca - 0x1a) * t);
+      const b = Math.round(0x2e + (0x24 - 0x2e) * t);
+      canvas.set(x, y, { r, g, b });
+    }
+  }
+
+  // Star field — random white dots in upper half
+  for (let i = 0; i < 30; i++) {
+    const x = Math.floor(Math.random() * WIDTH);
+    const y = Math.floor(Math.random() * (HEIGHT / 2));
+    const brightness = 150 + Math.floor(Math.random() * 100);
+    canvas.set(x, y, { r: brightness, g: brightness, b: brightness });
+  }
+
+  return canvas;
+};
+
+// ── Rocket sprite (5×5) with alpha edges for soft blending ──
+const ROCKET = [
+  [null,  null,  { r: 255, g: 255, b: 255 }, null,  null ],
+  [null,  { r: 255, g: 100, b: 100 }, { r: 255, g: 200, b: 200 }, { r: 255, g: 100, b: 100 }, null ],
+  [{ r: 200, g: 50, b: 50, a: 0.7 } as RGBA, { r: 255, g: 100, b: 100 }, { r: 255, g: 150, b: 150 }, { r: 255, g: 100, b: 100 }, { r: 200, g: 50, b: 50, a: 0.7 } as RGBA],
+  [null,  { r: 255, g: 200, b: 50 }, { r: 255, g: 240, b: 100 }, { r: 255, g: 200, b: 50 }, null ],
+  [null,  null,  { r: 255, g: 150, b: 50, a: 0.6 } as RGBA, null,  null ],
+];
+
+// ── Main loop ──────────────────────────────────
+const main = async (): Promise<void> => {
+  const { rows } = termSize();
+  if (rows < HEIGHT + 5) {
+    console.log(themes.error(`Terminal too small. Needs at least ${HEIGHT + 5} rows.`));
+    process.exit(1);
+  }
+
+  write(screen.clear());
+  write(cursor.hide());
+  write(cursor.to(1, 1));
+  console.log(themes.banner('ROCKET', { font: 'small' }));
+
+  const bg = buildBackground();
+
+  let rocketX = WIDTH / 2;
+  let rocketY = HEIGHT - 8;
+  let vx = 0.4;
+  let vy = -0.25;
+
+  const ctrl = new AbortController();
+  process.on('SIGINT', () => {
+    ctrl.abort();
+    write(cursor.show());
+    write(cursor.to(1, HEIGHT + 8));
+    console.log(themes.muted('\nGame stopped.'));
+    process.exit(0);
+  });
+
+  // Frame loop — drift-corrected via wall clock
+  const FRAME_MS = 60; // ~16 FPS
+  const startTime = Date.now();
+  let frame = 0;
+
+  const FPS_HIST: number[] = [];
+  let lastFrameTime = Date.now();
+
+  while (!ctrl.signal.aborted) {
+    // Clone background to a frame canvas (so sprites don't mutate the bg)
+    const frameCanvas = createCanvas(WIDTH, HEIGHT);
+    for (let y = 0; y < HEIGHT; y++) {
+      for (let x = 0; x < WIDTH; x++) {
+        frameCanvas.set(x, y, bg.get(x, y));
+      }
+    }
+
+    // Update rocket physics
+    rocketX += vx;
+    rocketY += vy;
+    if (rocketX <= 2 || rocketX >= WIDTH - 5) vx = -vx;
+    if (rocketY <= 2 || rocketY >= HEIGHT - 5) vy = -vy;
+
+    // Draw the rocket with alpha blending
+    frameCanvas.drawSprite(Math.round(rocketX), Math.round(rocketY), ROCKET);
+
+    // FPS calc
+    const now = Date.now();
+    const delta = now - lastFrameTime;
+    lastFrameTime = now;
+    if (delta > 0) {
+      FPS_HIST.push(1000 / delta);
+      if (FPS_HIST.length > 30) FPS_HIST.shift();
+    }
+    const avgFps = FPS_HIST.reduce((s, n) => s + n, 0) / Math.max(1, FPS_HIST.length);
+
+    // Render
+    write(cursor.to(1, 7));
+    write(frameCanvas.render());
+    write(cursor.to(1, HEIGHT + 8));
+    write(themes.muted(
+      `Frame ${frame.toString().padStart(4)} · ` +
+      `${avgFps.toFixed(1)} fps · ` +
+      `Ctrl+C to exit`,
+    ));
+
+    // Drift-correct sleep
+    frame++;
+    const targetTime = startTime + frame * FRAME_MS;
+    const waitMs = Math.max(0, targetTime - Date.now());
+    try {
+      await sleep(waitMs, { signal: ctrl.signal });
+    } catch {
+      break;
+    }
+  }
+
+  write(cursor.show());
+};
+
+main().catch((err) => {
+  write(cursor.show());
+  console.error(themes.error('✗ ' + (err as Error).message));
+  process.exit(1);
+});

package/examples/04-interactive-deploy.ts

@@ -0,0 +1,163 @@
+// ─────────────────────────────────────────────
+//  EXAMPLE 4 — Interactive prompt with menu + multi-loader
+//
+//  Demonstrates:
+//   - components.menu (interactive arrow-key navigation)
+//   - MENU_CANCELLED handling
+//   - loader.multi() — concurrent named operations
+//   - configure() side effects + onConfigChange
+//   - Theme switching at runtime
+//   - createTheme() for isolated theme instances
+//
+//  Walks the user through choosing a theme, then runs parallel
+//  "deployment" operations under a multi-loader.
+//
+//  Run:
+//    npx ts-node examples/04-interactive-deploy.ts
+// ─────────────────────────────────────────────
+
+import {
+  components,
+  loader,
+  themes,
+  createTheme,
+  configure,
+  onConfigChange,
+  sleep,
+  MENU_CANCELLED,
+} from '../dist/index.js';
+
+const main = async (): Promise<void> => {
+  // ── Subscribe to config changes globally ──
+  const offChange = onConfigChange((c) => {
+    // Each time the theme changes, the global `themes` follows automatically
+    // thanks to configure() side effects. We just log it.
+    console.log(themes.muted(`  [config] theme=${c.theme} colorMode=${c.colorMode}`));
+  });
+
+  // ── Step 1: Banner ─────────────────────────────
+  console.log();
+  console.log(themes.banner('DEPLOY', { font: 'small' }));
+  console.log(components.section(themes.primary('Configure deployment'), { width: 60 }));
+  console.log();
+
+  // ── Step 2: Pick a theme via menu ─────────────
+  console.log(themes.text('Select a theme for the output:'));
+  console.log();
+
+  const themeChoices = ['dracula', 'nord', 'monokai', 'matrix', 'cyberpunk'];
+  const choice = await components.menu(themeChoices, {
+    title: '  Available themes',
+    pointer: '▸',
+  });
+
+  if (choice === MENU_CANCELLED) {
+    console.log();
+    console.log(themes.warning('⚠ Cancelled by user'));
+    offChange();
+    return;
+  }
+
+  const themeName = themeChoices[choice as number]!;
+  configure({ theme: themeName });
+  console.log();
+  console.log(themes.accent(`✓ Theme set to ${themeName}`));
+  console.log();
+
+  // ── Step 3: Pick deployment regions (multi-select) ──
+  const regionChoices = ['us-east-1', 'us-west-2', 'eu-west-1', 'ap-south-1', 'sa-east-1'];
+  console.log(themes.text('Select target regions (Space to toggle, Enter to confirm):'));
+  console.log();
+
+  const regions = await components.menu(regionChoices, {
+    title: '  Regions',
+    pointer: '▸',
+    multiSelect: true,
+  });
+
+  if (regions === MENU_CANCELLED) {
+    console.log();
+    console.log(themes.warning('⚠ Cancelled by user'));
+    offChange();
+    return;
+  }
+
+  const selectedRegions = (regions as number[]).map((i) => regionChoices[i]!);
+  if (selectedRegions.length === 0) {
+    console.log(themes.warning('⚠ No regions selected — aborting'));
+    offChange();
+    return;
+  }
+
+  console.log();
+  console.log(components.box(
+    themes.primary('Plan:') + '\n' +
+    selectedRegions.map((r) => `  • ${r}`).join('\n'),
+    { borderStyle: 'rounded', padding: 1 },
+  ));
+  console.log();
+
+  // ── Step 4: Multi-loader for parallel deployments ──
+  console.log(themes.text('Starting parallel deployments...'));
+  console.log();
+
+  const m = loader.multi();
+  const items = selectedRegions.map((region) => {
+    const item = m.add(`Deploying to ${region}`, { color: '#48dbfb' });
+    return { region, item };
+  });
+
+  // Run each region in parallel
+  await Promise.all(items.map(async ({ region, item }) => {
+    // Stage 1: build
+    item.update(`[${region}] Building image...`);
+    await sleep(400 + Math.random() * 600);
+
+    // Stage 2: upload
+    item.update(`[${region}] Uploading...`);
+    await sleep(600 + Math.random() * 800);
+
+    // Stage 3: switch
+    item.update(`[${region}] Switching traffic...`);
+    await sleep(300 + Math.random() * 400);
+
+    // Random failure chance for one region
+    if (Math.random() < 0.15) {
+      item.fail(`[${region}] Failed: health check timeout`);
+    } else {
+      item.succeed(`[${region}] Live`);
+    }
+  }));
+
+  // Wait for the multi-loader to settle (final renders)
+  await sleep(150);
+
+  // ── Step 5: Multi-tenant theme demo ───────────
+  // Create an isolated theme instance for the summary
+  // (does not affect global state)
+  const summary = createTheme('matrix');
+
+  console.log();
+  console.log(components.section(summary.primary('Deployment summary'), { width: 60 }));
+  console.log();
+
+  console.log(components.timeline(
+    selectedRegions.map((r) => ({
+      label: `Deployed to ${r}`,
+      time: new Date().toLocaleTimeString(),
+      done: true,
+    })),
+  ));
+
+  console.log();
+  console.log(summary.muted('Global theme remains: ' + themes.current().name));
+  console.log(summary.muted('Isolated summary theme: ' + summary.current().name));
+  console.log();
+
+  offChange();
+};
+
+main().catch((err) => {
+  console.error(themes.error('✗ ' + (err as Error).message));
+  process.exit(1);
+});