claude-code-watcher 1.0.1

package/src/commands/start.mjs

@@ -0,0 +1,58 @@
+import { spawn } from 'node:child_process';
+import { SessionStore } from '../core/store.mjs';
+import { Renderer } from '../ui/renderer.mjs';
+import { Keyboard } from '../input/keyboard.mjs';
+
+if (!process.stdin.isTTY) {
+  console.error('Error: ccw requires an interactive terminal (TTY).');
+  console.error('Run this in a VS Code terminal tab or similar TTY environment.');
+  process.exit(1);
+}
+
+// Suppress EIO errors emitted on stdin during shutdown (expected when the TTY
+// handle is destroyed or the terminal tears down while reads are still pending).
+process.stdin.on('error', () => {});
+
+const store = new SessionStore();
+const keyboard = new Keyboard();
+const renderer = new Renderer(store, keyboard);
+
+// Guard flag prevents duplicate cleanup from concurrent signal paths
+let cleanedUp = false;
+function cleanup() {
+  if (cleanedUp) return;
+  cleanedUp = true;
+  renderer.stop();
+  keyboard.stop();
+  store.stop();
+}
+
+process.on('SIGINT', () => { cleanup(); process.exit(0); });
+process.on('SIGTERM', () => { cleanup(); process.exit(0); });
+
+keyboard.on('quit', () => { cleanup(); process.exit(0); });
+keyboard.on('respawn', () => {
+  if (cleanedUp) return;
+  cleanedUp = true;
+  renderer.stop();
+  store.stop();
+  // Restore raw mode but keep stdin open so the child can inherit it.
+  // unref() lets the event loop drain naturally instead of calling exit(),
+  // which avoids the EIO error the child would get if the parent closed fd 0 first.
+  if (process.stdin.isTTY) {
+    try { process.stdin.setRawMode(false); } catch { /* ignore */ }
+  }
+  process.stdin.removeAllListeners('data');
+  process.stdin.unref();
+  spawn(process.argv[0], process.argv.slice(1), { stdio: 'inherit' });
+});
+
+store.on('error', (err) => {
+  cleanup();
+  console.error('Store error:', err.message);
+  process.exit(1);
+});
+
+keyboard.start();
+store.start();
+renderer.start();

package/src/commands/status.mjs

@@ -0,0 +1,56 @@
+import { SessionStore } from '../core/store.mjs';
+import { BOLD, color, FG, RESET, visibleLength } from '../ui/ansi.mjs';
+import { formatStatus, truncate } from '../ui/format.mjs';
+
+const store = new SessionStore();
+store.start();
+store.stop();
+
+const sessions = store.getSessions();
+
+if (sessions.length === 0) {
+  console.log('No active Claude sessions.');
+  console.log(
+    `\nRun "ccw setup" to install hooks, then start a Claude Code session.`,
+  );
+  process.exit(0);
+}
+
+const colW = { project: 24, status: 12, message: 40, since: 6 };
+
+// Header
+console.log('');
+console.log(
+  `    ${BOLD}${color(FG.BRIGHT_WHITE, '#')} ` +
+    `${'Project'.padEnd(colW.project)} ` +
+    `${'Status'.padEnd(colW.status)} ` +
+    `${'Last Message'.padEnd(colW.message)} ` +
+    `${'Since'.padEnd(colW.since)}${RESET}`,
+);
+console.log(
+  '─'.repeat(
+    4 + 1 + colW.project + 1 + colW.status + 1 + colW.message + 1 + colW.since,
+  ),
+);
+
+sessions.forEach((session, i) => {
+  const num = String(i + 1).padEnd(4);
+  const project = truncate(session.displayName, colW.project).padEnd(
+    colW.project,
+  );
+  const msg = truncate(
+    session.message || session.lastResponse || '',
+    colW.message,
+  ).padEnd(colW.message);
+  const since = (session.sinceLabel || '').padEnd(colW.since);
+
+  const statusColored = formatStatus(session.status);
+  const statusPadded =
+    statusColored +
+    ' '.repeat(Math.max(0, colW.status - visibleLength(session.status)));
+
+  console.log(`${num} ${project} ${statusPadded} ${msg} ${since}`);
+});
+
+console.log('');
+console.log(`Total: ${sessions.length} session(s)`);

package/src/core/config.mjs

@@ -0,0 +1,26 @@
+import fs from 'node:fs';
+import { CONFIG_FILE } from './paths.mjs';
+
+const DEFAULTS = {
+  sounds: {
+    noti: 'Funk',
+    stop: 'Blow',
+  },
+};
+
+export function readConfig() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+    return {
+      ...DEFAULTS,
+      ...parsed,
+      sounds: { ...DEFAULTS.sounds, ...parsed.sounds },
+    };
+  } catch {
+    return { ...DEFAULTS, sounds: { ...DEFAULTS.sounds } };
+  }
+}
+
+export function writeConfig(config) {
+  fs.writeFileSync(CONFIG_FILE, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+}

package/src/core/paths.mjs

@@ -0,0 +1,12 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const HOME_DIR = homedir();
+export const CLAUDE_DIR = join(HOME_DIR, '.claude');
+export const DASHBOARD_DIR = join(CLAUDE_DIR, 'dashboard');
+export const ACTIVE_DIR = join(DASHBOARD_DIR, 'active');
+export const HOOKS_DIR = join(CLAUDE_DIR, 'hooks');
+export const SETTINGS_FILE = join(CLAUDE_DIR, 'settings.json');
+export const HOOK_SCRIPT_NAME = 'session-tracker.sh';
+export const HOOK_SCRIPT_PATH = join(HOOKS_DIR, HOOK_SCRIPT_NAME);
+export const CONFIG_FILE = join(DASHBOARD_DIR, 'config.json');

package/src/core/session.mjs

@@ -0,0 +1,107 @@
+export const STALE_THRESHOLD_MS = 10 * 60 * 1000; // 10 minutes
+
+/**
+ * Parse raw JSON data into a SessionRecord.
+ * Returns null if the data is invalid.
+ * @param {unknown} raw
+ * @param {string} filename
+ * @returns {SessionRecord|null}
+ */
+export function parseSession(raw, filename) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+
+  const sessionId = raw.session || filename.replace(/\.json$/, '');
+  if (!sessionId) return null;
+
+  return {
+    sessionId,
+    project: raw.project || 'unknown',
+    cwd: raw.cwd || '',
+    status: raw.status || 'waiting',
+    message: raw.message || '',
+    lastResponse: raw.lastResponse || '',
+    sessionName: raw.sessionName || '',
+    transcript: raw.transcript || '',
+    alertAt: raw.alertAt || '',
+    alertEvent: raw.alertEvent || '',
+    updated: raw.updated || '',
+    startedAt: raw.startedAt || '',
+    tty: raw.tty || '',
+    subagents: Array.isArray(raw.subagents) ? raw.subagents : [],
+  };
+}
+
+/**
+ * Add derived display fields to a SessionRecord.
+ * @param {SessionRecord} record
+ * @param {Date} now
+ * @returns {DerivedSession}
+ */
+export function deriveSession(record, now = new Date()) {
+  const updatedAt = parseDate(record.updated) || now;
+  const startedAt = parseDate(record.startedAt) || now;
+  const status = classifyStatus(record.status, updatedAt, now);
+
+  return {
+    ...record,
+    updatedAt,
+    startedAt,
+    status,
+    sinceLabel: formatClock(updatedAt),
+    displayName: buildDisplayName(record),
+  };
+}
+
+/**
+ * Classify session status, marking as stale if inactive for > STALE_THRESHOLD_MS.
+ * @param {string} status
+ * @param {Date} updatedAt
+ * @param {Date} now
+ * @returns {string}
+ */
+export function classifyStatus(status, updatedAt, now = new Date()) {
+  if (status === 'error') return 'error';
+
+  const sinceMs = now - updatedAt;
+  if (sinceMs > STALE_THRESHOLD_MS && status !== 'working' && status !== 'notification') return 'stale';
+
+  return status || 'waiting';
+}
+
+/**
+ * Parse a date string in the format "YYYY-MM-DD HH:MM:SS" or ISO 8601.
+ * @param {string} str
+ * @returns {Date|null}
+ */
+function parseDate(str) {
+  if (!str) return null;
+  // Handle "YYYY-MM-DD HH:MM:SS" format
+  const normalized = str.replace(' ', 'T');
+  const d = new Date(normalized);
+  return Number.isNaN(d.getTime()) ? null : d;
+}
+
+/**
+ * Build a human-readable display name, appending the TTY short name
+ * so multiple sessions in the same project can be told apart.
+ * e.g. "/dev/ttys003" → "my-project · s003"
+ */
+function buildDisplayName(record) {
+  const base = record.sessionName || record.project || record.sessionId;
+  if (!record.tty) return base;
+  // "/dev/ttys003" → "s003",  "/dev/pts/3" → "pts/3"
+  const short = record.tty.replace(/^\/dev\/(tty)?/, '');
+  return `[${short}] ${base}`;
+}
+
+/**
+ * Format a Date to HH:MM string (last-updated clock time).
+ * @param {Date} date
+ * @returns {string}
+ */
+function formatClock(date) {
+  if (!(date instanceof Date)) return '--:--';
+  const h = String(date.getHours()).padStart(2, '0');
+  const m = String(date.getMinutes()).padStart(2, '0');
+  return `${h}:${m}`;
+}

package/src/core/store.mjs

@@ -0,0 +1,153 @@
+import { EventEmitter } from 'node:events';
+import fs from 'node:fs';
+import { join } from 'node:path';
+import { ACTIVE_DIR } from './paths.mjs';
+import { deriveSession, parseSession } from './session.mjs';
+
+const POLL_INTERVAL_MS = 2000;
+
+export class SessionStore extends EventEmitter {
+  #sessions = new Map(); // sessionId -> SessionRecord
+  #watcher = null;
+  #pollTimer = null;
+  // Per-file debounce timers: filename -> TimeoutId
+  #pendingTimers = new Map();
+
+  start() {
+    fs.mkdirSync(ACTIVE_DIR, { recursive: true });
+    this.#loadAll();
+    this.#startWatching();
+  }
+
+  stop() {
+    if (this.#watcher) {
+      this.#watcher.close();
+      this.#watcher = null;
+    }
+    if (this.#pollTimer) {
+      clearInterval(this.#pollTimer);
+      this.#pollTimer = null;
+    }
+    for (const timer of this.#pendingTimers.values()) {
+      clearTimeout(timer);
+    }
+    this.#pendingTimers.clear();
+  }
+
+  getSessions() {
+    const now = new Date();
+    return Array.from(this.#sessions.values())
+      .map(s => deriveSession(s, now))
+      .sort((a, b) => (a.tty || '').localeCompare(b.tty || ''));
+  }
+
+  getSubagents(parentId) {
+    return this.#sessions.get(parentId)?.subagents ?? [];
+  }
+
+  reload() {
+    this.#loadAll();
+    this.emit('update', this.getSessions());
+  }
+
+  #loadAll() {
+    let files;
+    try {
+      files = fs.readdirSync(ACTIVE_DIR);
+    } catch {
+      return;
+    }
+
+    for (const file of files) {
+      if (!file.endsWith('.json')) continue;
+      this.#loadFile(join(ACTIVE_DIR, file), file);
+    }
+  }
+
+  #loadFile(filePath, filename) {
+    try {
+      const content = fs.readFileSync(filePath, 'utf8');
+      const raw = JSON.parse(content);
+      const record = parseSession(raw, filename);
+      if (!record) return;
+
+      // Auto-delete session files left by force-killed Claude Code.
+      // process.kill(pid, 0) checks existence without sending a signal.
+      if (raw.ppid) {
+        try {
+          process.kill(raw.ppid, 0);
+        } catch (err) {
+          if (err.code === 'ESRCH') {
+            // Process no longer exists — orphaned file, clean up.
+            try { fs.unlinkSync(filePath); } catch { /* already gone */ }
+            return;
+          }
+          // EPERM means process exists but we lack permission — still alive.
+        }
+      }
+
+      this.#sessions.set(record.sessionId, record);
+    } catch {
+      // Skip files with parse errors; will retry on next event
+    }
+  }
+
+  #startWatching() {
+    try {
+      this.#watcher = fs.watch(
+        ACTIVE_DIR,
+        { persistent: false },
+        (_, filename) => {
+          if (!filename || !filename.endsWith('.json')) return;
+
+          // Debounce per file: cancel previous timer for this file and reset
+          const existing = this.#pendingTimers.get(filename);
+          if (existing) clearTimeout(existing);
+
+          const timer = setTimeout(() => {
+            this.#pendingTimers.delete(filename);
+            const filePath = join(ACTIVE_DIR, filename);
+            const sessionId = filename.replace(/\.json$/, '');
+
+            try {
+              if (!fs.existsSync(filePath)) {
+                this.#sessions.delete(sessionId);
+              } else {
+                this.#loadFile(filePath, filename);
+              }
+              this.emit('update', this.getSessions());
+            } catch (err) {
+              this.emit('error', err);
+            }
+          }, 50);
+
+          this.#pendingTimers.set(filename, timer);
+        },
+      );
+
+      this.#watcher.on('error', err => {
+        // Close properly before falling back to polling
+        try {
+          this.#watcher.close();
+        } catch {
+          /* ignore */
+        }
+        this.#watcher = null;
+        this.#startPolling();
+      });
+    } catch {
+      this.#startPolling();
+    }
+  }
+
+  #startPolling() {
+    this.#pollTimer = setInterval(() => {
+      try {
+        this.#loadAll();
+        this.emit('update', this.getSessions());
+      } catch (err) {
+        this.emit('error', err);
+      }
+    }, POLL_INTERVAL_MS);
+  }
+}

package/src/input/keyboard.mjs

@@ -0,0 +1,126 @@
+import { EventEmitter } from 'node:events';
+
+export class Keyboard extends EventEmitter {
+  #wasRaw = false;
+  // Incomplete escape sequence buffered from a previous chunk
+  #escBuf = '';
+  #escTimer = null;
+  // How long to wait for the rest of an escape sequence before treating \x1b as bare ESC
+  static #ESC_TIMEOUT_MS = 30;
+
+  start() {
+    if (!process.stdin.isTTY) {
+      return;
+    }
+
+    this.#wasRaw = process.stdin.isRaw || false;
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding('utf8');
+
+    process.stdin.on('data', chunk => this.#handleChunk(chunk));
+  }
+
+  stop() {
+    if (this.#escTimer !== null) {
+      clearTimeout(this.#escTimer);
+      this.#escTimer = null;
+    }
+    if (process.stdin.isTTY) {
+      try {
+        process.stdin.setRawMode(this.#wasRaw);
+      } catch {
+        // ignore
+      }
+    }
+    // destroy() fully closes the handle so the event loop drains cleanly.
+    // pause() only stops reading but keeps the handle ref'd, causing EIO on exit.
+    process.stdin.destroy();
+  }
+
+  #handleChunk(chunk) {
+    // Combine with any buffered incomplete escape sequence from the previous chunk
+    if (this.#escBuf) {
+      chunk = this.#escBuf + chunk;
+      this.#escBuf = '';
+      clearTimeout(this.#escTimer);
+      this.#escTimer = null;
+    }
+
+    // If the chunk ends with a potentially incomplete escape sequence (\x1b or \x1b[),
+    // buffer the tail and wait for the next chunk to complete it.
+    const tail = chunk.endsWith('\x1b[') ? 2
+               : chunk.endsWith('\x1b')  ? 1
+               : 0;
+
+    if (tail > 0) {
+      const before = chunk.slice(0, -tail);
+      if (before) {
+        for (const key of parseKeys(before)) this.emit('key', key);
+      }
+      this.#escBuf = chunk.slice(-tail);
+      // After timeout, the user just pressed ESC alone — flush it
+      this.#escTimer = setTimeout(() => {
+        this.#escTimer = null;
+        const buf = this.#escBuf;
+        this.#escBuf = '';
+        if (buf === '\x1b') {
+          this.emit('key', { name: 'escape', ctrl: false, meta: false });
+        }
+        // '\x1b[' with no final byte: discard (unknown sequence)
+      }, Keyboard.#ESC_TIMEOUT_MS);
+      return;
+    }
+
+    for (const key of parseKeys(chunk)) {
+      this.emit('key', key);
+    }
+  }
+}
+
+/**
+ * Parse a raw terminal input chunk into zero or more key descriptors.
+ * A single chunk can contain multiple sequences when keys are pressed rapidly.
+ * @param {string} chunk
+ * @returns {Array<{ name: string, ctrl: boolean, meta: boolean }>}
+ */
+function parseKeys(chunk) {
+  const keys = [];
+  let i = 0;
+  while (i < chunk.length) {
+    const ch = chunk[i];
+
+    if (ch === '\x03') { // Ctrl+C
+      keys.push({ name: 'c', ctrl: true, meta: false });
+      i += 1;
+    } else if (ch === '\r' || ch === '\n') {
+      keys.push({ name: 'return', ctrl: false, meta: false });
+      i += 1;
+    } else if (ch === '\x1b') {
+      if (chunk[i + 1] === '[') {
+        if (chunk[i + 2] === 'A') {
+          keys.push({ name: 'up',   ctrl: false, meta: false });
+          i += 3;
+        } else if (chunk[i + 2] === 'B') {
+          keys.push({ name: 'down', ctrl: false, meta: false });
+          i += 3;
+        } else {
+          // Unknown CSI sequence — skip ESC and let next iteration handle '['
+          keys.push({ name: 'escape', ctrl: false, meta: false });
+          i += 1;
+        }
+      } else {
+        // Bare ESC (or ESC not followed by '[')
+        keys.push({ name: 'escape', ctrl: false, meta: false });
+        i += 1;
+      }
+    } else if (ch >= ' ') {
+      // Regular printable character (preserve case so callers can distinguish r vs R)
+      keys.push({ name: ch, ctrl: false, meta: false });
+      i += 1;
+    } else {
+      i += 1; // skip unknown control character
+    }
+  }
+  return keys;
+}

package/src/ui/ansi.mjs

@@ -0,0 +1,164 @@
+// ANSI escape code constants and helpers
+
+const ESC = '\x1b';
+const CSI = `${ESC}[`;
+const OSC = `${ESC}]`;
+
+export const RESET = `${CSI}0m`;
+export const BOLD = `${CSI}1m`;
+export const DIM = `${CSI}2m`;
+export const ITALIC = `${CSI}3m`;
+export const UNDERLINE = `${CSI}4m`;
+export const REVERSE = `${CSI}7m`;
+
+// Foreground colors
+export const FG = {
+  BLACK: `${CSI}30m`,
+  RED: `${CSI}31m`,
+  GREEN: `${CSI}32m`,
+  YELLOW: `${CSI}33m`,
+  BLUE: `${CSI}34m`,
+  MAGENTA: `${CSI}35m`,
+  CYAN: `${CSI}36m`,
+  WHITE: `${CSI}37m`,
+  BRIGHT_BLACK: `${CSI}90m`, // gray
+  BRIGHT_RED: `${CSI}91m`,
+  BRIGHT_GREEN: `${CSI}92m`,
+  BRIGHT_YELLOW: `${CSI}93m`,
+  BRIGHT_BLUE: `${CSI}94m`,
+  BRIGHT_MAGENTA: `${CSI}95m`,
+  BRIGHT_CYAN: `${CSI}96m`,
+  BRIGHT_WHITE: `${CSI}97m`,
+};
+
+// Background colors
+export const BG = {
+  BLACK: `${CSI}40m`,
+  RED: `${CSI}41m`,
+  GREEN: `${CSI}42m`,
+  YELLOW: `${CSI}43m`,
+  BLUE: `${CSI}44m`,
+  MAGENTA: `${CSI}45m`,
+  CYAN: `${CSI}46m`,
+  WHITE: `${CSI}47m`,
+  BRIGHT_BLACK: `${CSI}100m`,
+  BRIGHT_WHITE: `${CSI}107m`,
+};
+
+// Cursor control
+export const CURSOR_HOME = `${CSI}H`;
+export const CURSOR_HIDE = `${CSI}?25l`;
+export const CURSOR_SHOW = `${CSI}?25h`;
+export const CLEAR_SCREEN = `${CSI}2J`;
+export const CLEAR_LINE = `${CSI}K`;
+
+// Alternate screen buffer
+export const ALT_SCREEN_ON = `${CSI}?1049h`;
+export const ALT_SCREEN_OFF = `${CSI}?1049l`;
+
+// Auto-wrap mode (disable to prevent last-column wrapping artifacts)
+export const WRAP_OFF = `${CSI}?7l`;
+export const WRAP_ON = `${CSI}?7h`;
+
+/**
+ * Move cursor to row, col (1-indexed)
+ */
+export function moveTo(row, col) {
+  return `${CSI}${row};${col}H`;
+}
+
+/**
+ * Wrap text in ANSI color codes, reset at end.
+ */
+export function color(ansiCode, text) {
+  return `${ansiCode}${text}${RESET}`;
+}
+
+/**
+ * Create an OSC 8 hyperlink (clickable in supported terminals like VS Code)
+ * @param {string} url
+ * @param {string} text
+ */
+export function hyperlink(url, text) {
+  return `${OSC}8;;${url}\x07${text}${OSC}8;;\x07`;
+}
+
+/**
+ * Strip all ANSI escape sequences from a string (for length measurement)
+ */
+// RegExp constructor used intentionally: Biome noControlCharactersInRegex
+// does not check string arguments, only regex literals.
+const STRIP_ANSI_RE = /\x1b\[[0-9;]*[a-zA-Z]|\x1b\][^\x07]*\x07/g;
+
+export function stripAnsi(str) {
+  STRIP_ANSI_RE.lastIndex = 0;
+  return str.replace(STRIP_ANSI_RE, '');
+}
+
+/**
+ * Returns the terminal display width of a single Unicode code point.
+ * CJK/Hangul/fullwidth/emoji characters occupy 2 columns; most others occupy 1.
+ * Zero-width characters (ZWJ, variation selectors, combining marks) return 0.
+ */
+export function charDisplayWidth(cp) {
+  if (cp < 0x20 || (cp >= 0x7f && cp < 0xa0)) return 0; // control chars
+  if (cp === 0x200d) return 0; // ZWJ (Zero Width Joiner)
+  if (cp >= 0xfe00 && cp <= 0xfe0f) return 0; // variation selectors VS1–VS16
+  if (cp >= 0xe0100 && cp <= 0xe01ef) return 0; // variation selectors supplement
+  if (cp >= 0x300 && cp <= 0x36f) return 0; // combining diacritical marks
+  if (
+    (cp >= 0x1100 && cp <= 0x115f) || // Hangul Jamo
+    cp === 0x2329 ||
+    cp === 0x232a ||
+    (cp >= 0x2e80 && cp <= 0x303e) || // CJK Radicals
+    (cp >= 0x3040 && cp <= 0x33ff) || // Kana, Bopomofo, etc.
+    (cp >= 0x3400 && cp <= 0x4dbf) || // CJK Extension A
+    (cp >= 0x4e00 && cp <= 0xa4cf) || // CJK Unified Ideographs + Yi
+    (cp >= 0xa960 && cp <= 0xa97f) || // Hangul Jamo Extended-A
+    (cp >= 0xac00 && cp <= 0xd7ff) || // Hangul Syllables
+    (cp >= 0xf900 && cp <= 0xfaff) || // CJK Compatibility Ideographs
+    (cp >= 0xfe10 && cp <= 0xfe6f) || // CJK Compatibility Forms + Small Forms
+    (cp >= 0xff01 && cp <= 0xff60) || // Fullwidth Forms
+    (cp >= 0xffe0 && cp <= 0xffe6) || // Fullwidth Signs
+    (cp >= 0x1b000 && cp <= 0x1b0ff) || // Kana Supplement
+    (cp >= 0x1f1e0 && cp <= 0x1f1ff) || // Regional indicator symbols (flags)
+    (cp >= 0x1f300 && cp <= 0x1faff) || // Emoji: Misc Symbols, Transport, Supplemental, etc.
+    (cp >= 0x1fb00 && cp <= 0x1fbff) || // Symbols for Legacy Computing
+    (cp >= 0x20000 && cp <= 0x2fffd) || // CJK Extension B–F
+    (cp >= 0x30000 && cp <= 0x3fffd) // CJK Extension G+
+  )
+    return 2;
+  return 1;
+}
+
+// Module-level segmenter for grapheme cluster splitting (Node.js 16+)
+const _segmenter = new Intl.Segmenter();
+
+/**
+ * Returns the terminal display width of a grapheme cluster (one user-perceived character).
+ * Handles ZWJ sequences (👨‍👩‍👧‍👦), regional indicator pairs (🇰🇷), skin tone modifiers (👋🏽),
+ * and VS16 emoji presentation (❤️).
+ */
+export function graphemeDisplayWidth(segment) {
+  const cp = segment.codePointAt(0);
+  const w = charDisplayWidth(cp);
+  // A grapheme cluster containing VS16 (U+FE0F) forces emoji presentation → 2 columns
+  if (w === 1 && segment.includes('\uFE0F')) return 2;
+  return w;
+}
+
+/**
+ * Get the visible display width of a string (without ANSI codes).
+ * Uses grapheme cluster segmentation to correctly handle emoji sequences,
+ * ZWJ sequences, regional indicator pairs, and skin tone modifiers.
+ */
+export function visibleLength(str) {
+  const plain = stripAnsi(str);
+  let width = 0;
+  for (const { segment } of _segmenter.segment(plain)) {
+    width += graphemeDisplayWidth(segment);
+  }
+  return width;
+}
+
+export { _segmenter };