scripter-x 1.0.0

package/src/ui/App.js

@@ -0,0 +1,101 @@
+// App — the root ink component that hosts the interactive shell and runs commands
+// inside the same ink tree (so prompts/menus are all cursor-driven).
+//
+// Screen state machine:
+//   'shell'   → the REPL prompt + command palette
+//   'prompts' → a sequence of TextField/SelectList/Confirm questions a command asks
+//   'run'     → the live extraction view (RunView)
+//   'output'  → scrollback lines a command printed (tables, results)
+import React, { useState, useEffect, useRef } from 'react';
+import { Box, Text, useApp } from 'ink';
+import { Shell } from './Shell.js';
+import { SelectList, Confirm, TextField } from './components.js';
+import { RunView } from './RunView.js';
+import { COLORS } from '../theme.js';
+import { useMouse } from './mouse.js';
+
+const h = React.createElement;
+
+export function App({ ctx }) {
+  const { exit } = useApp();
+  const [screen, setScreen] = useState('shell');
+  const [lines, setLines] = useState([]);       // scrollback (printed output)
+  const [prompt, setPrompt] = useState(null);   // active question
+  const [runController, setRunController] = useState(null);
+  const [busy, setBusy] = useState(false);
+  const [me, setMe] = useState({ username: ctx.username, server: ctx.server });
+  const [, forceTick] = useState(0);
+  const frameRef = useRef();
+  useMouse(); // enable click selection across the app
+
+  // track whether a live run is active, so prompts shown mid-run return to the run view
+  const runActive = useRef(false);
+  const afterPrompt = () => (runActive.current ? 'run' : 'shell');
+
+  // expose an "io" object commands use to print + ask, all rendering in-tree
+  const io = useRef(null);
+  if (!io.current) {
+    io.current = {
+      print: (line, color) => setLines((ls) => [...ls, { text: line, color }].slice(-200)),
+      clear: () => setLines([]),
+      ask: (message, opts = {}) => new Promise((resolve) => {
+        setScreen('prompts');
+        setPrompt({ kind: opts.mask ? 'secret' : 'text', message, mask: opts.mask, dflt: opts.dflt || '',
+          done: (v) => { setPrompt(null); setScreen(afterPrompt()); resolve(v || opts.dflt || ''); } });
+      }),
+      select: (message, items, opts = {}) => new Promise((resolve) => {
+        const norm = items.map((it) => (typeof it === 'string' ? { label: it, value: it } : it));
+        setScreen('prompts');
+        setPrompt({ kind: 'select', message, items: norm,
+          done: (v) => { setPrompt(null); setScreen(afterPrompt()); resolve(v); } });
+      }),
+      confirm: (message, dflt = true) => new Promise((resolve) => {
+        setScreen('prompts');
+        setPrompt({ kind: 'confirm', message, dflt,
+          done: (v) => { setPrompt(null); setScreen(afterPrompt()); resolve(v); } });
+      }),
+      // live run view: returns a controller; call .endRun() when done
+      startRun: (controller) => { runActive.current = true; setRunController(controller); setScreen('run'); forceTick((t) => t + 1); },
+      endRun: () => { runActive.current = false; setRunController(null); setScreen('shell'); },
+      setUser: (u) => setMe((m) => ({ ...m, username: u })),
+      exitApp: () => exit(),
+    };
+  }
+
+  async function runCommand(name) {
+    setBusy(true);
+    try {
+      await ctx.dispatch(name, io.current);
+    } catch (e) {
+      io.current.print(`  ✗ ${e.message}`, COLORS.danger);
+    } finally {
+      setBusy(false);
+      setScreen((s) => (s === 'run' ? s : 'shell'));
+    }
+  }
+
+  // scrollback (map semantic color names → theme hexes)
+  const colorMap = { accent: COLORS.accent, danger: COLORS.danger, success: COLORS.success, warn: COLORS.warn };
+  const scroll = h(Box, { flexDirection: 'column' },
+    lines.map((l, i) => h(Text, { key: i, color: colorMap[l.color] || l.color || undefined }, l.text)));
+
+  return h(Box, { flexDirection: 'column', ref: frameRef },
+    scroll,
+    screen === 'run' && runController ? h(RunView, { controller: runController, embedded: true }) : null,
+    screen === 'prompts' && prompt ? h(PromptView, { prompt, frameRef }) : null,
+    screen === 'shell' ? h(Shell, { username: me.username, server: me.server, busy, onRun: runCommand, frameRef }) : null,
+  );
+}
+
+function PromptView({ prompt, frameRef }) {
+  if (prompt.kind === 'select') {
+    return h(Box, { flexDirection: 'column' },
+      h(Text, { color: COLORS.accent }, '? ' + prompt.message),
+      h(SelectList, { items: prompt.items, frameRef, onSelect: (it) => prompt.done(it) }));
+  }
+  if (prompt.kind === 'confirm') {
+    return h(Confirm, { message: prompt.message, defaultValue: prompt.dflt, frameRef, onAnswer: (v) => prompt.done(v) });
+  }
+  return h(TextField, { message: prompt.message, mask: prompt.kind === 'secret', defaultValue: prompt.dflt,
+    onSubmit: (v) => prompt.done(v) });
+}

package/src/ui/RunView.js

@@ -0,0 +1,91 @@
+// The live run view — Claude-Code-style ink TUI: header, live slots, results, stats.
+// PROPERLY REACTIVE: the controller is an EventEmitter-like object; this component
+// subscribes and updates React state on every event, so slots/stats actually re-render.
+import React, { useState, useEffect } from 'react';
+import { Box, Text } from 'ink';
+import Spinner from 'ink-spinner';
+import { COLORS, STATUS, PHASE_LABEL, gradientChars } from '../theme.js';
+
+const h = React.createElement;
+
+function Header({ name, provider, succeeded, total }) {
+  return h(Box, { borderStyle: 'round', borderColor: COLORS.accent, paddingX: 1 },
+    h(Text, { color: COLORS.accent }, '◉ '),
+    h(Text, { bold: true }, name),
+    h(Text, { color: 'gray' }, `   ${provider}`),
+    h(Text, { color: COLORS.accent }, `    ${succeeded}/${total} JSONs`),
+  );
+}
+
+function SlotRow({ slot, mobile, phase, detail, wait }) {
+  const label = PHASE_LABEL[phase] || phase;
+  const color = phase === 'done' ? COLORS.success : (String(phase).includes('cancel') ? COLORS.warn : COLORS.accent);
+  const mob = mobile ? mobile.slice(-10) : '—';
+  return h(Box, null,
+    h(Box, { width: 5 }, h(Text, { color: 'gray' }, `#${slot}`)),
+    h(Box, { width: 13 }, h(Text, null, mob)),
+    h(Box, { width: 2 }, h(Text, { color }, h(Spinner, { type: 'dots' }))),
+    h(Box, { flexGrow: 1 }, h(Text, { color }, ` ${label}`), detail ? h(Text, { color: 'gray' }, `  ${detail}`) : null),
+    h(Box, { width: 7, justifyContent: 'flex-end' }, h(Text, { color: COLORS.warn }, wait ? `${wait}s` : '')),
+  );
+}
+
+function ResultRow({ status, mobile, detail, coupon, cost }) {
+  const st = STATUS[status] || STATUS.pending;
+  const mob = (mobile || '—').slice(-10) || '—';
+  const text = status === 'success' ? (coupon ? '₹100 coupon' : 'extracted') : (detail || '');
+  return h(Box, null,
+    h(Box, { width: 13 }, h(Text, null, mob)),
+    h(Box, { width: 13 }, h(Text, { color: st.color }, `${st.glyph} ${status}`)),
+    h(Box, { flexGrow: 1 }, h(Text, { color: 'gray' }, text)),
+    h(Box, { width: 7, justifyContent: 'flex-end' }, h(Text, { color: 'gray' }, cost ? `₹${cost}` : '')),
+  );
+}
+
+function Panel({ title, children, borderColor = 'gray' }) {
+  return h(Box, { flexDirection: 'column', borderStyle: 'round', borderColor, paddingX: 1 },
+    title ? h(Text, { bold: true }, title) : null, children);
+}
+
+export function RunView({ controller }) {
+  // mirror the controller's mutable state into React state via subscription
+  const [stats, setStats] = useState({ ...controller.stats });
+  const [slots, setSlots] = useState({ ...controller.slots });
+  const [rows, setRows] = useState([...controller.rows]);
+
+  useEffect(() => {
+    const onEvent = (kind) => {
+      // copy the latest controller state on EVERY event so React re-renders
+      if (kind === 'slot') setSlots({ ...controller.slots });
+      else if (kind === 'progress' || kind === 'done') setStats({ ...controller.stats });
+      else if (kind === 'row') setRows([...controller.rows]);
+    };
+    controller.subscribe(onEvent);
+    // also poll lightly so the spinner + countdown stay smooth between events
+    const id = setInterval(() => { setStats({ ...controller.stats }); setSlots({ ...controller.slots }); }, 200);
+    return () => { controller.unsubscribe(onEvent); clearInterval(id); };
+  }, [controller]);
+
+  const { name, provider, requested } = controller;
+  const slotList = Object.values(slots).sort((a, b) => a.slot - b.slot);
+  const lastRows = rows.slice(-8);
+
+  return h(Box, { flexDirection: 'column' },
+    h(Header, { name, provider, succeeded: stats.succeeded, total: requested }),
+    h(Panel, { title: 'live' },
+      slotList.length ? slotList.map((sl) => h(SlotRow, { key: sl.slot, ...sl }))
+        : h(Text, { color: 'gray' }, 'starting…')),
+    h(Panel, { title: 'results' },
+      lastRows.length ? lastRows.map((r, i) => h(ResultRow, { key: i, status: r.status, mobile: r.mobile, detail: r.detail, coupon: r.coupon_eligible, cost: r.cost }))
+        : h(Text, { color: 'gray' }, 'waiting for first result…')),
+    h(Box, { borderStyle: 'round', borderColor: COLORS.accent, paddingX: 1 },
+      h(Text, { color: COLORS.success }, `✓ ${stats.succeeded}`),
+      h(Text, { color: COLORS.danger }, `   ✗ ${stats.failed}`),
+      h(Text, { color: COLORS.warn }, `   ⊘ ${stats.cancelled}`),
+      h(Text, { color: 'gray' }, `   ◍ ${stats.generated} numbers`),
+      h(Text, { bold: true }, `   ₹${stats.charges} spent`),
+    ),
+  );
+}
+
+export function bannerChars() { return gradientChars('ScripterX'); }

package/src/ui/Shell.js

@@ -0,0 +1,114 @@
+// The interactive shell — Claude-Code-style REPL.
+//   • a welcome banner box
+//   • a `›` prompt; type to filter, `/` opens the command palette
+//   • ↑/↓ to move the cursor through commands, Enter/click-row to run, Esc to dismiss
+// Each command runs its own flow (which may itself use SelectList/Confirm/TextField),
+// then control returns to the prompt.
+import React, { useState } from 'react';
+import { Box, Text, useInput, useApp } from 'ink';
+import { COLORS, gradientChars } from '../theme.js';
+import { Clickable, isMouse, parseMouse } from './mouse.js';
+
+const h = React.createElement;
+
+export const COMMANDS = [
+  { name: 'run', desc: 'run an extraction' },
+  { name: 'campaigns', desc: 'list your campaigns' },
+  { name: 'export', desc: "download a campaign's sessions" },
+  { name: 'balance', desc: 'check provider balance' },
+  { name: 'creds', desc: 'manage saved provider credentials' },
+  { name: 'stop', desc: 'stop a running campaign' },
+  { name: 'delete', desc: 'delete a campaign' },
+  { name: 'whoami', desc: 'show the current user' },
+  { name: 'login', desc: 'sign in / switch account' },
+  { name: 'logout', desc: 'sign out' },
+  { name: 'config', desc: 'view / change settings' },
+  { name: 'help', desc: 'show all commands' },
+  { name: 'exit', desc: 'quit ScripterX' },
+];
+
+function WelcomeBox({ username, server, frameRef, onLogout }) {
+  const chars = gradientChars('ScripterX');
+  return h(Box, { borderStyle: 'round', borderColor: COLORS.accent, paddingX: 2, paddingY: 0, flexDirection: 'column' },
+    h(Box, null, chars.map((c, i) => h(Text, { key: i, color: c.color, bold: true }, c.char)),
+      h(Text, { color: 'gray' }, '   Flipkart session extractor')),
+    h(Box, null,
+      h(Text, { color: 'gray' }, username ? `◉ ${username}` : '○ not signed in'),
+      h(Text, { color: 'gray' }, `   ·   ${server}`),
+      // clickable logout affordance when signed in
+      username ? h(Clickable, { frameRef, onClick: onLogout },
+        h(Text, { color: COLORS.accent }, '    [ logout ]')) : null),
+    h(Text, { color: 'gray' }, "type a command, or / to browse — press 1-9 or ↑↓+enter to pick · 'exit' to quit"),
+  );
+}
+
+// The shell is a state machine: 'prompt' (typing) ↔ 'palette' (browsing commands).
+// When a command is picked it calls `onRun(name)`; the parent runs it (suspending the
+// ink tree), then calls back to resume the prompt.
+export function Shell({ username, server, onRun, busy, frameRef }) {
+  const { exit } = useApp();
+  const [query, setQuery] = useState('');
+  const [idx, setIdx] = useState(0);
+  const [paletteOpen, setPaletteOpen] = useState(false);
+
+  // commands filtered by what's typed after `/` (or the raw query)
+  const filterStr = query.startsWith('/') ? query.slice(1) : query;
+  const matches = COMMANDS.filter((c) => c.name.startsWith(filterStr.toLowerCase()) || c.desc.includes(filterStr.toLowerCase()));
+  const showPalette = (paletteOpen || query.startsWith('/')) && matches.length > 0;
+
+  useInput((input, key) => {
+    if (busy) return;
+    // Mouse clicks arrive here as input (ink strips the ESC). Handle them as clicks —
+    // parseMouse fires the clicked row's onClick via the registry — and NEVER type them.
+    if (isMouse(input)) { parseMouse(input); return; }
+    if (showPalette) {
+      // Number 1-9 = pick that visible row (no command name has a digit, so safe).
+      if (/^[1-9]$/.test(input)) {
+        const shown = matches.slice(0, 8);
+        const n = +input - 1;
+        if (n < shown.length) { setQuery(''); setPaletteOpen(false); setIdx(0); run(shown[n].name); }
+        return;
+      }
+      if (key.upArrow) { setIdx((i) => (i - 1 + matches.length) % matches.length); return; }
+      if (key.downArrow) { setIdx((i) => (i + 1) % matches.length); return; }
+      if (key.return) { const cmd = matches[Math.min(idx, matches.length - 1)]; setQuery(''); setPaletteOpen(false); setIdx(0); if (cmd) run(cmd.name); return; }
+      if (key.escape) { setPaletteOpen(false); setQuery(''); setIdx(0); return; }
+    }
+    if (key.return) {
+      const q = query.trim().replace(/^\//, '');
+      setQuery(''); setPaletteOpen(false); setIdx(0);
+      if (q) run(q);
+      return;
+    }
+    if (key.escape) { setQuery(''); setPaletteOpen(false); return; }
+    if (key.backspace || key.delete) { setQuery((v) => v.slice(0, -1)); setIdx(0); return; }
+    if (input === '/' && query === '') { setQuery('/'); setPaletteOpen(true); setIdx(0); return; }
+    if (input && !key.ctrl && !key.meta) { setQuery((v) => v + input); setIdx(0); }
+  });
+
+  function run(name) {
+    if (name === 'exit' || name === 'quit') { exit(); return; }
+    onRun(name);
+  }
+
+  return h(Box, { flexDirection: 'column' },
+    h(WelcomeBox, { username, server, frameRef, onLogout: () => run('logout') }),
+    h(Box, { marginTop: 1 },
+      h(Text, { color: COLORS.accent }, '› '),
+      h(Text, null, query || ''),
+      busy ? h(Text, { color: 'gray' }, ' …') : h(Text, { color: COLORS.accent }, '▏')),
+    showPalette ? h(Box, { flexDirection: 'column', marginTop: 0, marginLeft: 2 },
+      matches.slice(0, 8).map((c, i) => {
+        const active = i === Math.min(idx, matches.length - 1);
+        const row = h(Box, null,
+          h(Text, { color: active ? COLORS.accent : 'gray' }, active ? '▸ ' : '  '),
+          h(Text, { color: active ? COLORS.accent : 'gray', dimColor: !active }, `${i + 1} `),
+          h(Text, { color: active ? COLORS.accent : 'white', bold: active }, ('/' + c.name).padEnd(14)),
+          h(Text, { color: 'gray' }, ' ' + c.desc));
+        // hover → highlight this row; click → select + run it
+        return h(Clickable, { key: c.name, frameRef,
+          onHover: () => setIdx(i),
+          onClick: () => { setQuery(''); setPaletteOpen(false); setIdx(0); run(c.name); } }, row);
+      })) : null,
+  );
+}

package/src/ui/components.js

@@ -0,0 +1,84 @@
+// Reusable ink components: a cursor/arrow-key SelectList, a Confirm toggle, and a
+// TextField — the building blocks for the Claude-Code-style interactive shell.
+import React, { useState } from 'react';
+import { Box, Text, useInput } from 'ink';
+import { COLORS } from '../theme.js';
+import { Clickable, isMouse, parseMouse } from './mouse.js';
+
+const h = React.createElement;
+
+// SelectList — pick a row by NUMBER (1-9, the reliable fast path), or ↑/↓ (or j/k) +
+// Enter, or Esc to cancel. Click is best-effort (works when nothing has scrolled).
+export function SelectList({ items, onSelect, onCancel, label, frameRef }) {
+  const [idx, setIdx] = useState(0);
+  useInput((input, key) => {
+    if (isMouse(input)) { parseMouse(input); return; }      // best-effort click
+    if (/^[1-9]$/.test(input)) { const n = +input - 1; if (n < items.length) onSelect(items[n], n); return; }
+    if (key.upArrow || input === 'k') setIdx((i) => (i - 1 + items.length) % items.length);
+    else if (key.downArrow || input === 'j') setIdx((i) => (i + 1) % items.length);
+    else if (key.return) onSelect(items[idx], idx);
+    else if (key.escape && onCancel) onCancel();
+  });
+  return h(Box, { flexDirection: 'column' },
+    label ? h(Text, { color: 'gray' }, label) : null,
+    items.map((it, i) => {
+      const active = i === idx;
+      const title = typeof it === 'string' ? it : it.label;
+      const desc = typeof it === 'string' ? '' : (it.description || '');
+      const num = i < 9 ? `${i + 1}` : ' ';
+      const row = h(Box, null,
+        h(Text, { color: active ? COLORS.accent : 'gray' }, active ? ' ▸ ' : '   '),
+        h(Text, { color: active ? COLORS.accent : 'gray', dimColor: !active }, num + ' '),
+        h(Text, { color: active ? COLORS.accent : 'white', bold: active }, title.padEnd(14)),
+        desc ? h(Text, { color: 'gray' }, ' ' + desc) : null);
+      return h(Clickable, { key: i, frameRef,
+        onHover: () => setIdx((cur) => (cur === i ? cur : i)),
+        onClick: () => onSelect(it, i) }, row);
+    }),
+  );
+}
+
+// Confirm — Yes/No rendered as a two-row cursor menu so it's hover/click/number-
+// selectable like every other prompt (also y/n shortcut keys + ←/→/Enter).
+export function Confirm({ message, defaultValue = true, onAnswer, frameRef }) {
+  const [idx, setIdx] = useState(defaultValue ? 0 : 1); // 0=Yes, 1=No
+  useInput((input, key) => {
+    if (isMouse(input)) { parseMouse(input); return; }
+    if (input === 'y') { onAnswer(true); return; }
+    if (input === 'n') { onAnswer(false); return; }
+    if (key.upArrow || key.downArrow || key.leftArrow || key.rightArrow) setIdx((i) => (i === 0 ? 1 : 0));
+    else if (/^[12]$/.test(input)) onAnswer(input === '1');
+    else if (key.return) onAnswer(idx === 0);
+  });
+  const opts = [{ label: 'Yes', v: true }, { label: 'No', v: false }];
+  return h(Box, { flexDirection: 'column' },
+    h(Text, { color: COLORS.accent }, '? ' + message),
+    opts.map((o, i) => {
+      const active = i === idx;
+      const row = h(Box, null,
+        h(Text, { color: active ? COLORS.accent : 'gray' }, active ? ' ▸ ' : '   '),
+        h(Text, { color: active ? COLORS.accent : 'gray', dimColor: !active }, `${i + 1} `),
+        h(Text, { color: active ? COLORS.accent : 'white', bold: active }, o.label));
+      return h(Clickable, { key: i, frameRef, onHover: () => setIdx(i), onClick: () => onAnswer(o.v) }, row);
+    }),
+  );
+}
+
+// TextField — a single-line input with a prompt. Enter submits, Esc cancels.
+export function TextField({ message, mask = false, defaultValue = '', onSubmit, onCancel }) {
+  const [value, setValue] = useState(defaultValue);
+  useInput((input, key) => {
+    if (isMouse(input)) { parseMouse(input); return; } // swallow mouse, don't type it
+    if (key.return) onSubmit(value);
+    else if (key.escape && onCancel) onCancel();
+    else if (key.backspace || key.delete) setValue((v) => v.slice(0, -1));
+    else if (input && !key.ctrl && !key.meta) setValue((v) => v + input);
+  });
+  const shown = mask ? '•'.repeat(value.length) : value;
+  return h(Box, null,
+    h(Text, { color: COLORS.accent }, '? '),
+    h(Text, { bold: true }, message + ': '),
+    h(Text, null, shown),
+    h(Text, { color: COLORS.accent }, '▏'),
+  );
+}

package/src/ui/mouse.js

@@ -0,0 +1,95 @@
+// Mouse support for ink.
+//
+// THE KEY INSIGHT: ink owns stdin via its own `useInput`. A separate stdin listener
+// competes with it and loses (ink strips the ESC and the leftover `[<0;9;21M` leaks in
+// as typed text — the bug we saw). So instead we:
+//   1. enable SGR mouse mode (and re-enable it after every render, since ink's frame
+//      redraw can reset terminal modes),
+//   2. parse clicks INSIDE useInput via parseMouse(), where the sequence arrives as the
+//      `input` string (ESC already stripped by ink → it looks like `[<0;9;21M`).
+// A registry maps absolute terminal-Y → onClick. Clickable computes its own Y from the
+// ink/yoga layout (frame is bottom-anchored).
+import React, { useEffect, useRef, useLayoutEffect } from 'react';
+import { Box, useStdin } from 'ink';
+
+const h = React.createElement;
+const registry = new Map();      // absolute Y (1-based) → onClick fn
+const hoverRegistry = new Map(); // absolute Y (1-based) → onHover fn
+
+// Matches an SGR mouse event with OR without the leading ESC (ink strips it):
+//   (ESC)[<button;x;y(M|m)
+const MOUSE = /\x1b?\[<(\d+);(\d+);(\d+)([Mm])/g;
+
+// Is this input string (from useInput) a mouse sequence? Used to swallow it as non-text.
+export function isMouse(input) {
+  return !!input && /\x1b?\[<\d+;\d+;\d+[Mm]/.test(input);
+}
+
+// Parse mouse events from a useInput `input` string. Fires onClick on a left-button
+// release, and onHover for movement (the 32 bit = motion) so the row under the cursor
+// highlights. Returns true if any mouse event was handled.
+export function parseMouse(input) {
+  if (!input) return false;
+  let m, handled = false;
+  MOUSE.lastIndex = 0;
+  while ((m = MOUSE.exec(input)) !== null) {
+    handled = true;
+    const btn = parseInt(m[1], 10);
+    const y = parseInt(m[3], 10);
+    if (btn & 32) { const hf = hoverRegistry.get(y); if (hf) hf(); }       // motion → hover
+    else if (btn === 0 && m[4] === 'm') { const fn = registry.get(y); if (fn) fn(); } // click
+  }
+  return handled;
+}
+
+// Enable SGR mouse mode and keep it enabled (ink redraws can reset it).
+export function useMouse() {
+  const { setRawMode, isRawModeSupported } = useStdin();
+  useEffect(() => {
+    if (!isRawModeSupported) return undefined;
+    try { setRawMode(true); } catch { /* */ }
+    // 1000=button events, 1003=any-motion (for hover), 1006=SGR extended coords
+    const enable = () => process.stdout.write('\x1b[?1000h\x1b[?1003h\x1b[?1006h');
+    enable();
+    const id = setInterval(enable, 1000); // re-arm in case a redraw cleared it
+    return () => { clearInterval(id); process.stdout.write('\x1b[?1000l\x1b[?1003l\x1b[?1006l'); };
+  }, []);
+}
+
+function offsetWithinFrame(el, frameEl) {
+  let acc = 0;
+  let cur = el;
+  while (cur && cur !== frameEl && cur.yogaNode) {
+    acc += cur.yogaNode.getComputedTop();
+    cur = cur.parentNode;
+  }
+  return acc;
+}
+
+// Clickable — registers its absolute terminal Y so a click fires onClick and (optionally)
+// a hover over its line fires onHover (used to highlight the row under the cursor).
+export function Clickable({ frameRef, onClick, onHover, children }) {
+  const ref = useRef();
+  const claimed = useRef(null);
+  useLayoutEffect(() => {
+    const el = ref.current, frameEl = frameRef && frameRef.current;
+    if (!el || !frameEl || !frameEl.yogaNode || !el.yogaNode) return undefined;
+    try {
+      const frameH = frameEl.yogaNode.getComputedHeight();
+      const off = offsetWithinFrame(el, frameEl);
+      const termRows = process.stdout.rows || 40;
+      const y = termRows - (frameH - off);
+      if (claimed.current != null && claimed.current !== y) {
+        registry.delete(claimed.current); hoverRegistry.delete(claimed.current);
+      }
+      claimed.current = y;
+      registry.set(y, onClick);
+      if (onHover) hoverRegistry.set(y, onHover);
+    } catch { /* */ }
+    return undefined;
+  });
+  useEffect(() => () => {
+    if (claimed.current != null) { registry.delete(claimed.current); hoverRegistry.delete(claimed.current); }
+  }, []);
+  return h(Box, { ref }, children);
+}

package/src/util.js

@@ -0,0 +1,54 @@
+// Small shared helpers: colored console output + session export-to-file.
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { mkdirSync, writeFileSync, existsSync, statSync } from 'node:fs';
+import { COLORS } from './theme.js';
+
+// minimal ANSI for the non-TUI commands (login, lists, etc.)
+const c = (hex, s) => {
+  // map our hex accents to the nearest 256-color for plain stdout
+  const codes = { [COLORS.accent]: 38, [COLORS.success]: 78, [COLORS.warn]: 221, [COLORS.danger]: 210, gray: 245 };
+  const code = codes[hex] || 245;
+  return `\x1b[38;5;${code}m${s}\x1b[0m`;
+};
+
+export const paint = {
+  accent: (s) => c(COLORS.accent, s),
+  ok: (s) => c(COLORS.success, s),
+  warn: (s) => c(COLORS.warn, s),
+  err: (s) => c(COLORS.danger, s),
+  dim: (s) => c('gray', s),
+  bold: (s) => `\x1b[1m${s}\x1b[0m`,
+};
+
+export const log = {
+  info: (m) => console.log(`  ${paint.accent('◉')} ${m}`),
+  ok: (m) => console.log(`  ${paint.ok('✓')} ${m}`),
+  warn: (m) => console.log(`  ${paint.warn('!')} ${m}`),
+  err: (m) => console.log(`  ${paint.err('✗')} ${m}`),
+};
+
+// Resolve + write a campaign's sessions to a file. Returns {path, count} or null
+// (null when there are no extracted sessions). Mirrors the Python CLI's behavior:
+//   out=<file>  → that file;  out=<dir>/ → default name inside;  no out → ~/Downloads/scripterx/
+export async function saveSessions(api, cid, { campaignName, out } = {}) {
+  let name = (campaignName || cid.slice(0, 8)).replace(/[^A-Za-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || cid.slice(0, 8);
+  const accounts = await api.exportCampaign(cid);
+  const sessions = (accounts || []).map((a) => a.session).filter(Boolean);
+  if (!sessions.length) return null;
+
+  const defaultName = `${name}-${cid.slice(0, 8)}.json`;
+  let dest;
+  if (out) {
+    const expanded = out.startsWith('~') ? join(homedir(), out.slice(1)) : out;
+    const isDir = (existsSync(expanded) && statSync(expanded).isDirectory()) || /[/\\]$/.test(out);
+    dest = isDir ? join(expanded, defaultName) : expanded;
+  } else {
+    const downloads = join(homedir(), 'Downloads');
+    const base = existsSync(downloads) ? downloads : homedir();
+    dest = join(base, 'scripterx', defaultName);
+  }
+  mkdirSync(dirname(dest), { recursive: true });
+  writeFileSync(dest, JSON.stringify(sessions, null, 2));
+  return { path: dest, count: sessions.length };
+}