tuimon 0.1.0

package/CLAUDE.md

@@ -0,0 +1,80 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Development Commands
+
+```bash
+npm run build          # tsc → dist/
+npm run dev            # tsc --watch
+npm test               # vitest run (single pass)
+npm run test:watch     # vitest (watch mode)
+npm run test:coverage  # vitest run --coverage
+npm run typecheck      # tsc --noEmit
+npm run lint           # eslint src --ext .ts
+npm run format         # prettier --write src
+```
+
+Run a single test file: `npx vitest run src/__tests__/router.test.ts`
+Run tests matching a pattern: `npx vitest run --grep "shortcut navigation"`
+
+## Architecture
+
+TuiMon renders HTML pages in a headless Chromium browser, screenshots them as PNG, and streams images to the terminal via Kitty/Sixel graphics protocols. Developers write dashboards as plain HTML/CSS/JS.
+
+### Startup Sequence (src/index.ts)
+
+`tuimon.start(options)` orchestrates everything in this order:
+
+1. **detect.ts** — probe terminal for Kitty/Sixel/iTerm2 support and pixel dimensions
+2. **server.ts** — spin up an HTTP server on localhost:7337+ serving HTML pages from a common root directory
+3. **browser.ts** — launch headless Chromium via Playwright, set viewport to terminal pixel dimensions
+4. **router.ts** — create navigation state machine wired to navigate/render/setKeys callbacks
+5. **keyhandler.ts** — enable stdin raw mode, forward raw key strings to router.handleKey
+6. **fkeybar.ts** — render F-key status bar on the terminal's last row
+
+### Render Pipeline
+
+```
+dash.render(data) → browser.pushData(data) → page.__tuimon_update__(data)
+  → setTimeout(renderDelay) → browser.screenshot() → encodeAndRender(png, protocol)
+```
+
+The encoder writes directly to stdout: Kitty uses base64 PNG chunked at 4096 bytes; Sixel uses sharp to convert to raw pixels then builds sixel bands.
+
+### Router State Machine (src/router.ts)
+
+Three states: `overview` → `detail` → `confirm-quit`. This is the navigation core:
+- **overview**: shortcut keys navigate to detail pages; ESC opens confirm-quit
+- **detail**: ESC returns to overview; shortcuts ignored
+- **confirm-quit**: Y exits, N/ESC returns to previous state; all F-keys ignored
+- **Ctrl+C**: immediate exit from any state
+
+F-key escape sequences are mapped in a lookup table (e.g., `\x1bOP` → F1, `\x1b[15~` → F5).
+
+### Client Bridge (client/tuimon-client.js)
+
+Auto-injected into served HTML pages by the server. Exposes `window.TuiMon.onUpdate(cb)` and `window.TuiMon.set(selector, value)`. Data attributes `data-tm-key` and `data-tm-label` on HTML elements get automatic shortcut badges.
+
+## TypeScript Rules
+
+- **Strict mode** with `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `noImplicitReturns`
+- **ESM only** — module: NodeNext, all imports use `.js` extension
+- All shared interfaces live in `src/types.ts` — modules import types from there
+- iterm2 protocol maps to kitty for encoding (only 'kitty' | 'sixel' reach the encoder)
+
+## Testing Patterns
+
+Tests live in `src/__tests__/`. Setup file (`setup.ts`) converts `process.stdout.columns/rows` to getter properties for `vi.spyOn` compatibility.
+
+- **Module mocking**: `vi.mock('../module.js', () => ({ ... }))` at file top
+- **Dynamic imports**: tests use `await import('../module.js')` after `vi.resetModules()` for env-dependent modules (detect, router)
+- **stdout capture**: `vi.spyOn(process.stdout, 'write').mockImplementation(() => true)` then collect calls
+- **stdin simulation**: create `EventEmitter` with `setRawMode`/`resume` stubs, mock `process.stdin`
+- **Server tests**: create real temp directories with `mkdirSync`, track handles for cleanup in `afterEach`
+
+Coverage thresholds: 80% lines/functions/statements, 75% branches. cli.ts is excluded.
+
+## Formatting
+
+No semicolons, single quotes, trailing commas, 100 char width, 2-space indent (see .prettierrc).

package/README.md

@@ -0,0 +1,153 @@
+# TuiMon
+
+> Render beautiful HTML dashboards directly in your terminal.
+
+## Terminal Requirements
+
+| Terminal   | Protocol | Status     |
+|-----------|----------|------------|
+| Kitty     | Kitty    | Supported  |
+| Ghostty   | Kitty    | Supported  |
+| WezTerm   | Kitty    | Supported  |
+| iTerm2    | iTerm2   | Supported  |
+| VSCode    | Sixel    | Supported* |
+| mlterm    | Sixel    | Supported  |
+
+\* Sixel support may vary by terminal version.
+
+## Quick Start
+
+```bash
+npx tuimon init
+npx tuimon check
+npx tuimon start
+```
+
+Or install globally:
+
+```bash
+npm install -g tuimon
+tuimon init && tuimon start
+```
+
+## How It Works
+
+TuiMon renders your HTML pages in a headless Chromium browser via Playwright, screenshots them as PNG, and streams the images to your terminal using the Kitty graphics protocol (or Sixel as fallback). You write dashboards as normal HTML/CSS/JS — any charting library works.
+
+## Multi-Page Navigation
+
+Define multiple pages with keyboard shortcuts:
+
+```typescript
+const dash = await tuimon.start({
+  pages: {
+    overview: {
+      html: './pages/overview.html',
+      default: true,
+      label: 'Overview',
+    },
+    cpu: {
+      html: './pages/cpu-detail.html',
+      shortcut: 'g',
+      label: 'CPU Detail',
+    },
+    memory: {
+      html: './pages/memory-detail.html',
+      shortcut: 'm',
+      label: 'Memory',
+    },
+  },
+})
+```
+
+- Press a shortcut key from the overview to jump to a detail page
+- Press **ESC** on a detail page to return to overview
+- Press **ESC** on overview to show quit confirmation
+- Press **Ctrl+C** anywhere to exit immediately
+
+Add shortcut badges to HTML panels with data attributes:
+
+```html
+<div class="panel" data-tm-key="g" data-tm-label="CPU Detail">
+  <!-- panel content -->
+</div>
+```
+
+## Per-Page F-Key Bindings
+
+Each page defines its own F-key actions:
+
+```typescript
+pages: {
+  overview: {
+    html: './pages/overview.html',
+    default: true,
+    keys: {
+      F5: { label: 'Refresh', action: async () => dash.render(await getData()) },
+      F10: { label: 'Quit', action: () => process.exit(0) },
+    },
+  },
+}
+```
+
+The F-key bar at the bottom always reflects the active page's bindings.
+
+## API Reference
+
+### `tuimon.start(options: TuiMonOptions): Promise<TuiMonDashboard>`
+
+```typescript
+interface TuiMonOptions {
+  pages: Record<string, PageConfig>
+  data?: () => Record<string, unknown> | Promise<Record<string, unknown>>
+  refresh?: number    // auto-render interval in ms
+  renderDelay?: number // delay after pushData before screenshot (default: 50)
+}
+
+interface PageConfig {
+  html: string           // path to HTML file
+  default?: boolean      // exactly one page must be default
+  shortcut?: string      // single lowercase letter
+  label?: string         // human-readable name
+  keys?: Partial<Record<FKey, KeyBinding>>
+}
+
+interface KeyBinding {
+  label: string
+  action: () => void | Promise<void>
+}
+```
+
+### `dash.render(data): Promise<void>`
+
+Push data to the current page and re-render.
+
+### `dash.stop(): Promise<void>`
+
+Gracefully shut down — restores terminal state.
+
+## Client Library
+
+In your HTML pages, use the injected `TuiMon` object:
+
+```javascript
+// Listen for data updates
+TuiMon.onUpdate(function(data) {
+  TuiMon.set('#cpu', data.cpu)
+  TuiMon.set('#memory', data.memory + '%')
+})
+
+// TuiMon.set(selector, value) — sets text content or applies styles
+// TuiMon.notify(message, duration) — dispatches a notification event
+```
+
+## Contributing
+
+- **TDD required** — write tests first, implementation second
+- Coverage thresholds: 80% lines, 80% functions, 75% branches
+- `npm test` must pass before any PR
+- Strict TypeScript — `strict: true`, no `any`
+
+## License
+
+MIT

package/client/tuimon-client.js

@@ -0,0 +1,44 @@
+;(function () {
+  'use strict'
+
+  window.__tuimon_ready__ = false
+
+  window.__tuimon_update__ = function (data) {
+    window.__tuimon_ready__ = false
+    window.dispatchEvent(new CustomEvent('tuimon:update', { detail: data }))
+    window.__tuimon_ready__ = true
+  }
+
+  window.TuiMon = {
+    onUpdate(callback) {
+      window.addEventListener('tuimon:update', function (e) { callback(e.detail) })
+    },
+
+    set(selector, value) {
+      var el = document.querySelector(selector)
+      if (!el) return
+      if (typeof value === 'string') el.textContent = value
+      else if (typeof value === 'number') el.textContent = value.toLocaleString()
+      else if (typeof value === 'object' && value !== null) Object.assign(el.style, value)
+    },
+
+    notify(message, duration) {
+      duration = duration || 2000
+      window.dispatchEvent(new CustomEvent('tuimon:notify', { detail: { message: message, duration: duration } }))
+    },
+  }
+
+  // Auto-add shortcut badges to panels with data-tm-key
+  document.addEventListener('DOMContentLoaded', function () {
+    document.querySelectorAll('[data-tm-key]').forEach(function (panel) {
+      var key = panel.getAttribute('data-tm-key')
+      var label = panel.getAttribute('data-tm-label') || ''
+      if (!key) return
+      var badge = document.createElement('div')
+      badge.style.cssText = 'position:absolute;top:8px;right:8px;background:rgba(0,0,0,0.6);color:#58a6ff;padding:2px 8px;border-radius:4px;font-size:12px;font-family:monospace;pointer-events:none;z-index:10;'
+      badge.textContent = '[' + key.toUpperCase() + ']' + (label ? ' ' + label : '')
+      panel.style.position = panel.style.position || 'relative'
+      panel.appendChild(badge)
+    })
+  })
+})()

package/dist/browser.d.ts

@@ -0,0 +1,7 @@
+import type { BrowserHandle } from './types.js';
+export declare function createBrowser({ url, width, height, }: {
+    url: string;
+    width: number;
+    height: number;
+}): Promise<BrowserHandle>;
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,wBAAsB,aAAa,CAAC,EAClC,GAAG,EACH,KAAK,EACL,MAAM,GACP,EAAE;IACD,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf,GAAG,OAAO,CAAC,aAAa,CAAC,CA8DzB"}

package/dist/browser.js

@@ -0,0 +1,57 @@
+import { chromium } from 'playwright';
+export async function createBrowser({ url, width, height, }) {
+    const browser = await chromium.launch({ headless: true });
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    await page.setViewportSize({ width, height });
+    await page.goto(url, { waitUntil: 'domcontentloaded' });
+    let crashCount = 0;
+    page.on('crash', async () => {
+        crashCount++;
+        if (crashCount > 3) {
+            process.stderr.write('[tuimon] page crashed repeatedly — giving up on reload\n');
+            return;
+        }
+        process.stderr.write(`[tuimon] page crashed (attempt ${crashCount}/3), reloading\n`);
+        try {
+            await page.reload();
+        }
+        catch {
+            // ignore reload failures
+        }
+    });
+    page.on('pageerror', (err) => {
+        process.stderr.write(`tuimon: page error: ${err.message}\n`);
+    });
+    return {
+        async screenshot() {
+            const buf = await page.screenshot({ type: 'png' });
+            return Buffer.from(buf);
+        },
+        async pushData(data) {
+            await page.evaluate((d) => {
+                const win = globalThis;
+                if (typeof win['__tuimon_update__'] === 'function') {
+                    ;
+                    win['__tuimon_update__'](d);
+                }
+            }, data);
+            try {
+                await page.waitForFunction(() => globalThis['__tuimon_ready__'] === true, { timeout: 2000 });
+            }
+            catch {
+                // timeout is acceptable — page may not have the client script yet
+            }
+        },
+        async navigate(newUrl) {
+            await page.goto(newUrl, { waitUntil: 'domcontentloaded' });
+        },
+        async resize(w, h) {
+            await page.setViewportSize({ width: w, height: h });
+        },
+        async close() {
+            await browser.close();
+        },
+    };
+}
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAGrC,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,EAClC,GAAG,EACH,KAAK,EACL,MAAM,GAKP;IACC,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAA;IACzD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,EAAE,CAAA;IAC1C,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,EAAE,CAAA;IAEpC,MAAM,IAAI,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAA;IAC7C,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,kBAAkB,EAAE,CAAC,CAAA;IAEvD,IAAI,UAAU,GAAG,CAAC,CAAA;IAClB,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;QAC1B,UAAU,EAAE,CAAA;QACZ,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;YACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,0DAA0D,CAAC,CAAA;YAChF,OAAM;QACR,CAAC;QACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,kCAAkC,UAAU,kBAAkB,CAAC,CAAA;QACpF,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,EAAE,CAAA;QACrB,CAAC;QAAC,MAAM,CAAC;YACP,yBAAyB;QAC3B,CAAC;IACH,CAAC,CAAC,CAAA;IAEF,IAAI,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,GAAG,EAAE,EAAE;QAC3B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,uBAAuB,GAAG,CAAC,OAAO,IAAI,CAAC,CAAA;IAC9D,CAAC,CAAC,CAAA;IAEF,OAAO;QACL,KAAK,CAAC,UAAU;YACd,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;YAClD,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QACzB,CAAC;QAED,KAAK,CAAC,QAAQ,CAAC,IAA6B;YAC1C,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC,CAA0B,EAAE,EAAE;gBACjD,MAAM,GAAG,GAAG,UAAqC,CAAA;gBACjD,IAAI,OAAO,GAAG,CAAC,mBAAmB,CAAC,KAAK,UAAU,EAAE,CAAC;oBACnD,CAAC;oBAAC,GAAG,CAAC,mBAAmB,CAA0C,CAAC,CAAC,CAAC,CAAA;gBACxE,CAAC;YACH,CAAC,EAAE,IAAI,CAAC,CAAA;YACR,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,eAAe,CACxB,GAAG,EAAE,CAAE,UAAsC,CAAC,kBAAkB,CAAC,KAAK,IAAI,EAC1E,EAAE,OAAO,EAAE,IAAI,EAAE,CAClB,CAAA;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,kEAAkE;YACpE,CAAC;QACH,CAAC;QAED,KAAK,CAAC,QAAQ,CAAC,MAAc;YAC3B,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,kBAAkB,EAAE,CAAC,CAAA;QAC5D,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,CAAS,EAAE,CAAS;YAC/B,MAAM,IAAI,CAAC,eAAe,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAA;QACrD,CAAC;QAED,KAAK,CAAC,KAAK;YACT,MAAM,OAAO,CAAC,KAAK,EAAE,CAAA;QACvB,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import path from 'node:path';
+import { existsSync, mkdirSync, cpSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { detectGraphicsSupport } from './detect.js';
+process.on('unhandledRejection', (reason) => {
+    console.error('[tuimon] Unhandled rejection:', reason);
+    process.exit(1);
+});
+process.on('uncaughtException', (error) => {
+    console.error('[tuimon] Uncaught exception:', error);
+    process.exit(1);
+});
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkgRoot = path.resolve(__dirname, '..');
+const program = new Command();
+program
+    .name('tuimon')
+    .description('Render beautiful HTML dashboards directly in your terminal.')
+    .version('0.1.0');
+program
+    .command('start')
+    .description('Start a TuiMon dashboard')
+    .option('-c, --config <path>', 'Path to config file', 'tuimon.config.ts')
+    .action(async (opts) => {
+    const configPath = path.resolve(process.cwd(), opts.config);
+    if (!existsSync(configPath)) {
+        console.error(`[tuimon] Config file not found: ${configPath}`);
+        console.error('[tuimon] Run "tuimon init" to create a starter project.');
+        process.exit(1);
+    }
+    // Dynamic import of the config — it self-starts
+    await import(configPath);
+});
+program
+    .command('init')
+    .description('Scaffold a starter TuiMon project in the current directory')
+    .action(() => {
+    const starterDir = path.resolve(pkgRoot, 'templates', 'starter');
+    const targetDir = process.cwd();
+    const pagesDir = path.join(targetDir, 'pages');
+    const configFile = path.join(targetDir, 'tuimon.config.ts');
+    if (existsSync(configFile)) {
+        console.error('[tuimon] tuimon.config.ts already exists. Aborting.');
+        process.exit(1);
+    }
+    mkdirSync(pagesDir, { recursive: true });
+    cpSync(path.join(starterDir, 'pages'), pagesDir, { recursive: true });
+    cpSync(path.join(starterDir, 'tuimon.config.ts'), configFile);
+    console.log('TuiMon project initialized!');
+    console.log('');
+    console.log('  Files created:');
+    console.log('    pages/overview.html');
+    console.log('    pages/cpu-detail.html');
+    console.log('    pages/memory-detail.html');
+    console.log('    tuimon.config.ts');
+    console.log('');
+    console.log('  Next steps:');
+    console.log('    npx tuimon start');
+});
+program
+    .command('check')
+    .description('Check terminal graphics support')
+    .action(async () => {
+    const support = await detectGraphicsSupport();
+    console.log('');
+    console.log('TuiMon Terminal Check');
+    console.log('\u2500'.repeat(21));
+    console.log(`Kitty protocol:  ${support.kitty ? '\u2713 supported' : '\u2717 not detected'}`);
+    console.log(`Sixel protocol:  ${support.sixel ? '\u2713 supported' : '\u2717 not detected'}`);
+    console.log(`iTerm2 protocol: ${support.iterm2 ? '\u2713 supported' : '\u2717 not detected'}`);
+    console.log('');
+    if (support.protocol) {
+        console.log(`\u2713 Will use: ${support.protocol}`);
+        const term = process.env['TERM_PROGRAM'] ?? process.env['TERM'] ?? 'unknown';
+        console.log(`  ${term}`);
+    }
+    else {
+        console.log('\u2717 No supported graphics protocol detected.');
+        console.log('  TuiMon requires Kitty, iTerm2, or Sixel graphics support.');
+    }
+    console.log('');
+    process.exit(support.protocol ? 0 : 1);
+});
+program.parse();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/detect.d.ts

@@ -0,0 +1,8 @@
+import type { GraphicsSupport, TerminalDimensions } from './types.js';
+export declare function detectGraphicsSupport(opts?: {
+    skipQuery?: boolean;
+}): Promise<GraphicsSupport>;
+export declare function getTerminalDimensions(opts?: {
+    skipQuery?: boolean;
+}): Promise<TerminalDimensions>;
+//# sourceMappingURL=detect.d.ts.map

package/dist/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAwGrE,wBAAsB,qBAAqB,CACzC,IAAI,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7B,OAAO,CAAC,eAAe,CAAC,CA2B1B;AAED,wBAAsB,qBAAqB,CACzC,IAAI,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7B,OAAO,CAAC,kBAAkB,CAAC,CAqB7B"}

package/dist/detect.js

@@ -0,0 +1,141 @@
+// ─── Env-based detection helpers ─────────────────────────────────────────────
+const KITTY_TERM_PROGRAMS = ['WezTerm', 'ghostty', 'Ghostty'];
+const ITERM2_TERM_PROGRAMS = ['iTerm.app', 'iTerm2'];
+function detectKittyEnv() {
+    const term = process.env.TERM ?? '';
+    const termProgram = process.env.TERM_PROGRAM ?? '';
+    if (term === 'xterm-kitty')
+        return true;
+    if (KITTY_TERM_PROGRAMS.includes(termProgram))
+        return true;
+    return false;
+}
+function detectIterm2Env() {
+    const termProgram = process.env.TERM_PROGRAM ?? '';
+    return ITERM2_TERM_PROGRAMS.includes(termProgram);
+}
+function detectSixelEnv() {
+    const term = process.env.TERM ?? '';
+    const termProgram = process.env.TERM_PROGRAM ?? '';
+    if (term === 'mlterm')
+        return true;
+    if (termProgram === 'vscode')
+        return true;
+    return false;
+}
+// ─── Terminal query helpers ──────────────────────────────────────────────────
+let queryLock = Promise.resolve();
+function queryKittySupport() {
+    return new Promise((resolve) => {
+        const timeout = setTimeout(() => {
+            cleanup();
+            resolve(false);
+        }, 500);
+        const onData = (data) => {
+            const str = data.toString();
+            if (str.includes('_G')) {
+                cleanup();
+                resolve(true);
+            }
+        };
+        const cleanup = () => {
+            clearTimeout(timeout);
+            process.stdin.removeListener('data', onData);
+            if (wasRaw !== undefined) {
+                try {
+                    process.stdin.setRawMode(wasRaw);
+                }
+                catch { }
+            }
+        };
+        let wasRaw;
+        try {
+            wasRaw = process.stdin.isRaw;
+            process.stdin.setRawMode(true);
+        }
+        catch { }
+        process.stdin.on('data', onData);
+        process.stdout.write('\x1b_Ga=q;\x1b\\');
+    });
+}
+function queryPixelDimensions() {
+    return new Promise((resolve) => {
+        const timeout = setTimeout(() => {
+            cleanup();
+            resolve(null);
+        }, 500);
+        const onData = (data) => {
+            const str = data.toString();
+            // Response format: \x1b[4;<height>;<width>t
+            const match = str.match(/\x1b\[4;(\d+);(\d+)t/);
+            if (match) {
+                cleanup();
+                resolve({ width: parseInt(match[2] ?? '0', 10), height: parseInt(match[1] ?? '0', 10) });
+            }
+        };
+        const cleanup = () => {
+            clearTimeout(timeout);
+            process.stdin.removeListener('data', onData);
+            if (wasRaw !== undefined) {
+                try {
+                    process.stdin.setRawMode(wasRaw);
+                }
+                catch { }
+            }
+        };
+        let wasRaw;
+        try {
+            wasRaw = process.stdin.isRaw;
+            process.stdin.setRawMode(true);
+        }
+        catch { }
+        process.stdin.on('data', onData);
+        process.stdout.write('\x1b[14t');
+    });
+}
+// ─── Public API ──────────────────────────────────────────────────────────────
+export async function detectGraphicsSupport(opts) {
+    const skipQuery = opts?.skipQuery ?? false;
+    // Start with environment-based detection
+    let kitty = detectKittyEnv();
+    const iterm2 = detectIterm2Env();
+    const sixel = detectSixelEnv();
+    // If not skipping queries and env didn't detect kitty, try querying (serialized)
+    if (!skipQuery && !kitty) {
+        await queryLock;
+        const p = queryKittySupport();
+        queryLock = p.catch(() => { });
+        kitty = await p;
+    }
+    // Determine protocol with priority: kitty > iterm2 > sixel
+    let protocol = null;
+    if (kitty) {
+        protocol = 'kitty';
+    }
+    else if (iterm2) {
+        protocol = 'iterm2';
+    }
+    else if (sixel) {
+        protocol = 'sixel';
+    }
+    return { kitty, sixel, iterm2, protocol };
+}
+export async function getTerminalDimensions(opts) {
+    const skipQuery = opts?.skipQuery ?? false;
+    const cols = process.stdout.columns ?? 80;
+    const rows = process.stdout.rows ?? 24;
+    let pixelWidth = 1600;
+    let pixelHeight = 900;
+    if (!skipQuery) {
+        await queryLock;
+        const p = queryPixelDimensions();
+        queryLock = p.catch(() => { });
+        const queried = await p;
+        if (queried) {
+            pixelWidth = queried.width;
+            pixelHeight = queried.height;
+        }
+    }
+    return { cols, rows, pixelWidth, pixelHeight };
+}
+//# sourceMappingURL=detect.js.map

package/dist/detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.js","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"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"}

package/dist/encoder.d.ts

@@ -0,0 +1,4 @@
+export declare function encodeAndRender(buffer: Buffer, opts: {
+    protocol: 'kitty' | 'sixel';
+}): Promise<void>;
+//# sourceMappingURL=encoder.d.ts.map

package/dist/encoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoder.d.ts","sourceRoot":"","sources":["../src/encoder.ts"],"names":[],"mappings":"AAKA,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE;IAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAA;CAAE,GACpC,OAAO,CAAC,IAAI,CAAC,CAMf"}