dsh-live-trace 0.1.0

package/src/cli/screen.js

@@ -0,0 +1,270 @@
+/**
+ * Terminal control: the alternate screen, size, raw input, and frame painting.
+ *
+ * This is the only module in the viewer that touches the TTY, so every other
+ * piece of the dashboard stays unit-testable.
+ *
+ * @module dsh-live-trace/screen
+ */
+
+/** Sequences the alternate-screen painter emits. */
+export const SEQUENCE = {
+  altEnter: '\u001b[?1049h',
+  altLeave: '\u001b[?1049l',
+  hideCursor: '\u001b[?25l',
+  showCursor: '\u001b[?25h',
+  home: '\u001b[H',
+  clearToEnd: '\u001b[J',
+  clearLine: '\u001b[K',
+  /** Begin synchronized output (DEC 2026); ignored by terminals without it. */
+  syncBegin: '\u001b[?2026h',
+  syncEnd: '\u001b[?2026l',
+  /** Button-event reporting plus SGR coordinates, so the wheel is unambiguous. */
+  mouseEnter: '\u001b[?1000h\u001b[?1006h',
+  mouseLeave: '\u001b[?1000l\u001b[?1006l'
+}
+
+/**
+ * Decode one SGR mouse report body (`b;x;y`) into a key the dashboard handles.
+ *
+ * @param {number} button
+ * @param {number} x 1-based column
+ * @param {number} y 1-based row
+ * @returns {string | { type: 'click', x: number, y: number } | null}
+ */
+function mouseEvent(button, x, y, released) {
+  if (button >= 64) {
+    switch (button) {
+      case 64:
+        return 'wheel-up'
+      case 65:
+        return 'wheel-down'
+      case 66:
+        return 'wheel-left'
+      case 67:
+        return 'wheel-right'
+      default:
+        return null
+    }
+  }
+  // Bit 5 marks pointer motion, which a dashboard has nothing to do with.
+  if ((button & 32) !== 0) return null
+  // Low two bits give the button. A release carries no new information, and
+  // only the left button opens something.
+  if (released) return null
+  return (button & 3) === 0 ? { type: 'click', x, y } : null
+}
+
+/**
+ * Parse raw terminal input into named keys.
+ *
+ * Escape sequences arrive split across reads often enough that the parser
+ * buffers a partial sequence instead of treating its prefix as keystrokes.
+ *
+ * @returns {(chunk: string) => string[]}
+ */
+export function createKeyParser() {
+  const sequences = [
+    ['\u001b[1;5A', 'ctrl-up'],
+    ['\u001b[1;5B', 'ctrl-down'],
+    ['\u001b[A', 'up'],
+    ['\u001b[B', 'down'],
+    ['\u001b[C', 'right'],
+    ['\u001b[D', 'left'],
+    ['\u001bOA', 'up'],
+    ['\u001bOB', 'down'],
+    ['\u001b[5~', 'page-up'],
+    ['\u001b[6~', 'page-down'],
+    ['\u001b[H', 'home'],
+    ['\u001b[F', 'end'],
+    ['\u001b[1~', 'home'],
+    ['\u001b[4~', 'end']
+  ]
+  let pending = ''
+  const parser = (chunk) => {
+    pending += chunk
+    const keys = []
+    for (;;) {
+      if (pending.length === 0) break
+      if (pending[0] !== '\u001b') {
+        keys.push(pending[0])
+        pending = pending.slice(1)
+        continue
+      }
+      // SGR mouse reports are self-delimiting: ESC [ < b;x;y M|m
+      if (pending.startsWith('\u001b[<')) {
+        const terminator = pending.search(/[Mm]/)
+        if (terminator === -1) break
+        const fields = pending.slice(3, terminator).split(';')
+        const released = pending[terminator] === 'm'
+        pending = pending.slice(terminator + 1)
+        const [button, x, y] = fields.map((value) => Number.parseInt(value, 10))
+        const event = mouseEvent(button, x, y, released)
+        if (event !== null) keys.push(event)
+        continue
+      }
+      // A lone ESC may still be the prefix of an arrow key.
+      if (pending.length === 1) break
+      const match = sequences.find(([sequence]) => pending.startsWith(sequence))
+      if (match !== undefined) {
+        keys.push(match[1])
+        pending = pending.slice(match[0].length)
+        continue
+      }
+      const couldExtend = sequences.some(([sequence]) => sequence.startsWith(pending))
+      if (couldExtend) break
+      // Unknown escape: consume the ESC and re-examine the rest.
+      pending = pending.slice(1)
+    }
+    if (pending.length > 64) pending = ''
+    return keys
+  }
+  parser.pending = () => pending
+  parser.takePending = () => {
+    const held = pending
+    pending = ''
+    return held
+  }
+  return parser
+}
+
+export class Screen {
+  /**
+   * @param {{ stdout?: NodeJS.WriteStream, stdin?: NodeJS.ReadStream, altScreen?: boolean, color?: boolean, mouse?: boolean }} [options]
+   */
+  constructor(options = {}) {
+    this.stdout = options.stdout ?? process.stdout
+    this.stdin = options.stdin ?? process.stdin
+    this.altScreen = options.altScreen !== false
+    this.mouse = options.mouse !== false
+    this.entered = false
+    this.rawWasSet = false
+    this.listeners = { key: new Set(), resize: new Set() }
+    this.onStdinData = null
+    this.onStdoutResize = null
+  }
+
+  /** @returns {{ cols: number, rows: number }} */
+  size() {
+    return {
+      cols: Math.max(20, this.stdout.columns ?? 80),
+      rows: Math.max(6, this.stdout.rows ?? 24)
+    }
+  }
+
+  /** Enter the alternate screen, hide the cursor, and start reading raw keys. */
+  enter() {
+    if (this.entered) return
+    this.entered = true
+    if (this.altScreen) this.stdout.write(SEQUENCE.altEnter)
+    this.stdout.write(SEQUENCE.hideCursor)
+    // Wheel events arrive as arrow keys in many terminals, which is reported as
+    // a plain keypress and cannot be distinguished from one. Claiming the mouse
+    // makes scrolling exact; Shift+drag still selects text.
+    if (this.mouse !== false) this.stdout.write(SEQUENCE.mouseEnter)
+
+    if (this.stdin.isTTY === true) {
+      try {
+        this.stdin.setRawMode(true)
+        this.rawWasSet = true
+      } catch {
+        /* not a real TTY; key handling stays off */
+      }
+    }
+    this.stdin.resume?.()
+    this.stdin.setEncoding?.('utf8')
+
+    const parseKeys = createKeyParser()
+    let escapeTimer = null
+    const flushEscape = () => {
+      escapeTimer = null
+      // A lone ESC never completes into an arrow key, so it must eventually be
+      // delivered as the Escape key rather than held forever.
+      if (parseKeys.takePending() === '\u001b') this.emitKey('escape')
+    }
+    this.onStdinData = (chunk) => {
+      for (const key of parseKeys(String(chunk))) {
+        if (key === '\u0003') {
+          this.emitKey('quit')
+          continue
+        }
+        this.emitKey(key)
+      }
+      if (escapeTimer !== null) clearTimeout(escapeTimer)
+      if (parseKeys.pending() === '\u001b' && !/^\u001b\[<$/.test(parseKeys.pending())) {
+        escapeTimer = setTimeout(flushEscape, 40)
+        escapeTimer.unref?.()
+      }
+    }
+    this.escapeTimer = () => escapeTimer
+    this.stdin.on('data', this.onStdinData)
+
+    this.onStdoutResize = () => this.emitResize()
+    this.stdout.on('resize', this.onStdoutResize)
+  }
+
+  /** Restore the terminal, whatever happened. */
+  leave() {
+    if (!this.entered) return
+    this.entered = false
+    if (typeof this.escapeTimer === 'function') {
+      const timer = this.escapeTimer()
+      if (timer !== null) clearTimeout(timer)
+    }
+    if (this.onStdinData !== null) this.stdin.off('data', this.onStdinData)
+    if (this.onStdoutResize !== null) this.stdout.off('resize', this.onStdoutResize)
+    this.onStdinData = null
+    this.onStdoutResize = null
+    if (this.rawWasSet) {
+      try {
+        this.stdin.setRawMode(false)
+      } catch {
+        /* the TTY may already be gone */
+      }
+      this.rawWasSet = false
+    }
+    this.stdin.pause?.()
+    const mouseOff = this.mouse === false ? '' : SEQUENCE.mouseLeave
+    this.stdout.write(`${mouseOff}${SEQUENCE.showCursor}${this.altScreen ? SEQUENCE.altLeave : '\n'}`)
+  }
+
+  /**
+   * Paint exactly `lines`, one per row, without a full-screen clear flicker.
+   * @param {string[]} lines
+   */
+  paint(lines) {
+    const { rows } = this.size()
+    let out = `${SEQUENCE.syncBegin}${SEQUENCE.home}`
+    for (let index = 0; index < rows; index += 1) {
+      out += `${lines[index] ?? ''}${SEQUENCE.clearLine}`
+      if (index < rows - 1) out += '\r\n'
+    }
+    out += SEQUENCE.clearToEnd + SEQUENCE.syncEnd
+    this.stdout.write(out)
+  }
+
+  /** @param {string} message a message printed after leaving the alternate screen */
+  writeLine(message) {
+    this.stdout.write(`${message}\n`)
+  }
+
+  /** @param {(key: string) => void} listener */
+  onKey(listener) {
+    this.listeners.key.add(listener)
+    return () => this.listeners.key.delete(listener)
+  }
+
+  /** @param {() => void} listener */
+  onResize(listener) {
+    this.listeners.resize.add(listener)
+    return () => this.listeners.resize.delete(listener)
+  }
+
+  emitKey(key) {
+    for (const listener of this.listeners.key) listener(key)
+  }
+
+  emitResize() {
+    for (const listener of this.listeners.resize) listener()
+  }
+}

package/src/cli/theme.js

@@ -0,0 +1,221 @@
+/**
+ * The dashboard's visual vocabulary: one color and one treatment per event tag.
+ *
+ * Colors are 256-color SGR parameters rather than truecolor so the board looks
+ * right in the widest range of terminals, and every value collapses to an empty
+ * style when color is disabled (`NO_COLOR`, `--no-color`, or a non-TTY).
+ *
+ * @module dsh-live-trace/theme
+ */
+
+/**
+ * @typedef {object} Theme
+ * @property {boolean} color
+ * @property {Record<string, string>} tag        style per {@link import('../../lib/normalize.js').TAG}
+ * @property {Record<string, string>} level      style per entry level
+ * @property {Record<string, string>} ui         chrome styles
+ * @property {Record<string, string>} md         markdown palette for markdown.js
+ * @property {Record<string, string>} syn        syntax palette for highlight.js
+ * @property {Record<string, string>} scene      palette for the desk scene
+ */
+
+/**
+ * Build a theme.
+ * @param {{ color?: boolean }} [options]
+ * @returns {Theme}
+ */
+export function createTheme(options = {}) {
+  const color = options.color !== false
+  const sgr = (code) => (color ? code : '')
+
+  const tag = {
+    session: sgr('1;38;5;141'),
+    turn: sgr('1;38;5;39'),
+    step: sgr('38;5;44'),
+    user: sgr('1;38;5;255'),
+    assistant: sgr('38;5;42'),
+    tool: sgr('1;38;5;220'),
+    result: sgr('38;5;40'),
+    error: sgr('1;38;5;203'),
+    approval: sgr('1;38;5;214'),
+    meta: sgr('38;5;245')
+  }
+
+  const level = {
+    info: sgr('38;5;252'),
+    success: sgr('38;5;42'),
+    warn: sgr('38;5;214'),
+    error: sgr('1;38;5;203'),
+    muted: sgr('38;5;243')
+  }
+
+  const ui = {
+    border: sgr('38;5;238'),
+    title: sgr('1;38;5;45'),
+    label: sgr('38;5;246'),
+    value: sgr('1;38;5;253'),
+    dim: sgr('38;5;240'),
+    headerBg: sgr('48;5;235'),
+    footerBg: sgr('48;5;235'),
+    statusRunning: sgr('1;38;5;42'),
+    statusTool: sgr('1;38;5;220'),
+    statusIdle: sgr('38;5;245'),
+    statusApproval: sgr('1;38;5;214'),
+    statusError: sgr('1;38;5;203'),
+    stream: sgr('3;38;5;246'),
+    scrollHint: sgr('38;5;245'),
+    hint: sgr('38;5;240'),
+    ok: sgr('38;5;42'),
+    fail: sgr('38;5;203'),
+    // View chrome
+    cursor: sgr('1;38;5;45'),
+    cursorBg: sgr('48;5;237'),
+    selected: sgr('1;38;5;255'),
+    panelTitle: sgr('1;38;5;45'),
+    added: sgr('38;5;42'),
+    removed: sgr('38;5;203'),
+    addedBg: sgr('48;5;22'),
+    removedBg: sgr('48;5;52'),
+    hunkHeader: sgr('38;5;141'),
+    gutter: sgr('38;5;240'),
+    command: sgr('38;5;252'),
+    output: sgr('38;5;246'),
+    exitOk: sgr('38;5;42'),
+    exitFail: sgr('1;38;5;203')
+  }
+
+  // Markdown and syntax palettes are handed to `markdown.js` / `highlight.js`,
+  // which never hard-code a colour of their own.
+  const md = {
+    heading: sgr('1;38;5;45'),
+    heading2: sgr('1;38;5;44'),
+    bold: sgr('1'),
+    italic: sgr('3'),
+    strike: sgr('9'),
+    link: sgr('4;38;5;39'),
+    inlineCode: sgr('38;5;180'),
+    bullet: sgr('38;5;39'),
+    quote: sgr('38;5;245'),
+    rule: sgr('38;5;238'),
+    code: sgr('38;5;252'),
+    fenceBorder: sgr('38;5;238'),
+    fenceLang: sgr('38;5;245'),
+    more: sgr('38;5;245')
+  }
+
+  const syn = {
+    keyword: sgr('38;5;170'),
+    string: sgr('38;5;114'),
+    number: sgr('38;5;180'),
+    comment: sgr('3;38;5;243'),
+    function: sgr('38;5;39'),
+    type: sgr('38;5;80'),
+    operator: sgr('38;5;210'),
+    punctuation: sgr('38;5;245'),
+    variable: sgr('38;5;252'),
+    property: sgr('38;5;117'),
+    tag: sgr('38;5;170'),
+    attribute: sgr('38;5;180'),
+    added: sgr('38;5;42'),
+    removed: sgr('38;5;203'),
+    meta: sgr('38;5;141')
+  }
+
+  // The desk scene owns its own palette: wood, plastic, paper and a bright red
+  // telephone against the same blues as the mascot.
+  const scene = {
+    body: sgr('38;5;69'),
+    // A shade off the body: enough to read the limb as a limb, not enough to
+    // look like a different animal.
+    flipper: sgr('38;5;75'),
+    outline: sgr('38;5;25'),
+    belly: sgr('38;5;231'),
+    spout: sgr('38;5;245'),
+    accent: sgr('38;5;222'),
+    desk: sgr('38;5;137'),
+    deskDark: sgr('38;5;94'),
+    keyboard: sgr('38;5;238'),
+    key: sgr('38;5;246'),
+    phone: sgr('38;5;160'),
+    phoneDark: sgr('38;5;88'),
+    page: sgr('38;5;255'),
+    pageShade: sgr('38;5;250'),
+    pageDark: sgr('38;5;243'),
+    windowEdge: sgr('38;5;110'),
+    // The sky colour is rewritten every frame from the in-game clock; this is
+    // only the fallback for a caller that does not provide one.
+    sky: sgr('38;5;24'),
+    // All four are rewritten every frame from the in-game clock and weather.
+    skyLow: sgr('38;5;31'),
+    landscape: sgr('38;5;236'),
+    glow: sgr('38;5;230'),
+    starDim: sgr('38;5;245'),
+    windowFrame: sgr('38;5;180'),
+    wall: sgr('38;5;145'),
+    wallShade: sgr('38;5;102'),
+    skirting: sgr('38;5;60'),
+    floor: sgr('38;5;236'),
+    // The z's sit on the wall, so they cannot be another mid grey.
+    sleepZ: sgr('38;5;255'),
+    tree: sgr('38;5;22'),
+    ground: sgr('38;5;58'),
+    cloud: sgr('38;5;252'),
+    sun: sgr('38;5;220'),
+    moon: sgr('38;5;253'),
+    star: sgr('38;5;255'),
+    rain: sgr('38;5;111'),
+    snow: sgr('38;5;255'),
+    fog: sgr('38;5;246'),
+    windowFill: sgr('38;5;234'),
+    bookGreen: sgr('38;5;65'),
+    bookYellow: sgr('38;5;179'),
+    bookCyan: sgr('38;5;73'),
+    bubble: sgr('38;5;250'),
+    bubbleFill: sgr('38;5;236'),
+    text: sgr('38;5;253')
+  }
+
+  return { color, tag, level, ui, md, syn, scene }
+}
+
+/**
+ * Wide-character-safe status glyph.
+ * @param {'idle' | 'running' | 'tool' | 'waiting-approval' | 'error'} status
+ * @param {number} frame rotating frame index
+ * @returns {string}
+ */
+export function statusGlyph(status, frame) {
+  switch (status) {
+    case 'running':
+      return ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'][frame % 10]
+    case 'tool':
+      return ['◐', '◓', '◑', '◒'][frame % 4]
+    case 'waiting-approval':
+      return '▲'
+    case 'error':
+      return '✖'
+    default:
+      return '●'
+  }
+}
+
+/**
+ * Style for a status value.
+ * @param {Theme} theme
+ * @param {string} status
+ * @returns {string}
+ */
+export function statusStyle(theme, status) {
+  switch (status) {
+    case 'running':
+      return theme.ui.statusRunning
+    case 'tool':
+      return theme.ui.statusTool
+    case 'waiting-approval':
+      return theme.ui.statusApproval
+    case 'error':
+      return theme.ui.statusError
+    default:
+      return theme.ui.statusIdle
+  }
+}