@vzn/vx 0.0.650 → 0.0.651

package/src/ui/live-region.ts

@@ -0,0 +1,363 @@
+// The live region: a block of lines redrawn in place under the log, with
+// clear-line / cursor-up and no alternate screen (NOT a TUI). The writer is
+// the serialization point for ALL of a screen's output: every ordinary write
+// erases the region first, writes its content, then redraws, so the region
+// never interleaves with what scrolls above it.
+
+import { dumbTerminal } from './theme.js'
+
+/** Erase the current line and return the cursor to column 0. */
+const CLEAR = '\x1b[2K\r'
+
+export interface StatusStream {
+  write(chunk: string): unknown
+  isTTY?: boolean
+  /**
+   * Terminal width in columns. Read fresh on every draw — `process.stdout`
+   * updates it on SIGWINCH, so a mid-run resize is picked up. Absent (not a
+   * TTY) means the region is never drawn anyway.
+   */
+  columns?: number
+  /** Terminal height in rows, read per draw as `columns` is. */
+  rows?: number
+}
+
+/** A region's lines, or what builds them when it is drawn. */
+export type Region = readonly string[] | (() => readonly string[])
+
+export interface OutputWriter {
+  /** True only when the stream is a TTY and the run isn't CI. */
+  readonly enabled: boolean
+  /** Serialized content write: erase status → content → redraw. */
+  write(chunk: string): void
+  /**
+   * The same, to another stream on the same terminal (stderr): the region
+   * on this one is erased first and redrawn after.
+   */
+  writeTo(target: StatusStream, chunk: string): void
+  /**
+   * Replace the status line's content. Redraws are throttled to
+   * `minRedrawMs` unless `force` (task start/finish) is set.
+   */
+  setStatus(line: string, opts?: { force?: boolean }): void
+  /**
+   * Replace the multi-line status region. Same throttle contract as
+   * `setStatus`; the two share one display slot. A function is called
+   * when the region is next drawn, once: a set the throttle coalesces
+   * builds nothing.
+   */
+  setRegion(lines: Region, opts?: { force?: boolean }): void
+  /** Hand over what `coalesce` holds and write straight through from now on. */
+  settle(): void
+  /** Permanently remove the status display; later set* is a no-op. */
+  clearStatus(): void
+  /**
+   * Erase the status display and draw none until the returned release:
+   * a prompt on the terminal (a secret's) waits for its answer there.
+   */
+  hold(): () => void
+}
+
+export interface OutputWriterOptions {
+  /** Master switch on top of the TTY check (false in CI). */
+  enabled?: boolean
+  /** Minimum interval between unforced redraws. */
+  minRedrawMs?: number
+  /**
+   * Floor between FORCED redraws. Task events force a redraw each; a
+   * 3,270-task warm run produced 6,540 forced redraws ≈ 6.7 MB of
+   * ANSI to the terminal. A forced set inside the floor marks the
+   * content dirty and ONE trailing draw lands the final state when
+   * the floor expires. 0 disables (tests asserting synchronously).
+   */
+  forceFloorMs?: number
+  /** Injectable clock for tests. */
+  now?: () => number
+  /**
+   * Off a TTY, hold writes and hand them to the stream once per turn of
+   * the event loop until `settle()`. A warm 476-package run wrote each of
+   * its 952 task lines as its own syscall (item 753). Off by default: a
+   * caller reading its stream right after a write sees it.
+   */
+  coalesce?: boolean
+}
+
+export function createOutputWriter(
+  stream: StatusStream,
+  opts: OutputWriterOptions = {},
+): OutputWriter {
+  const enabled = (opts.enabled ?? true) && stream.isTTY === true && !dumbTerminal()
+  const minRedrawMs = opts.minRedrawMs ?? 100
+  const forceFloorMs = opts.forceFloorMs ?? 30
+  const now = opts.now ?? Date.now
+  // The coalesced writes not yet handed over; null once settled or when
+  // not coalescing.
+  let held: string[] | null = !enabled && opts.coalesce === true ? [] : null
+  let flushQueued = false
+  const flushHeld = (): void => {
+    flushQueued = false
+    if (held === null || held.length === 0) return
+    const text = held.join('')
+    held.length = 0
+    stream.write(text)
+  }
+
+  let current: Region | null = null
+  let shown = false
+  // PHYSICAL rows the shown region occupies, not logical lines — see
+  // `regionRows`.
+  let shownRows = 0
+  let dead = false
+  let holds = 0
+  let lastDraw = -Infinity
+  // Trailing draw scheduled when a forced set lands inside the floor.
+  let trailing: ReturnType<typeof setTimeout> | null = null
+  // Streamed task output (focused mode) can end mid-line; redrawing
+  // the status display would wipe the partial line, so we hold off
+  // until a write restores column 0.
+  let atLineStart = true
+
+  const cancelTrailing = (): void => {
+    if (trailing !== null) {
+      clearTimeout(trailing)
+      trailing = null
+    }
+  }
+
+  /**
+   * How many PHYSICAL terminal rows `lines` occupies. The terminal wraps
+   * any line wider than the viewport, so a region of N logical lines can
+   * cover more than N rows — and erasing by the logical count moves the
+   * cursor up too few rows, leaving the top of the region on screen. It
+   * accumulates, because every redraw is short by the same amount.
+   *
+   * Both triggers are ordinary: the summary section is a fixed 62 visible
+   * columns (narrower terminal ⇒ every bar row wraps), and a task id is
+   * deliberately never truncated (long id ⇒ the worker row wraps at any
+   * width). Width is read per draw so a mid-run resize is handled. Width
+   * must be VISIBLE width — these lines carry ANSI, which occupies no
+   * column.
+   *
+   * Unknown width falls back to the logical count, which is a KNOWN
+   * residual rather than a guarantee: a wrapped line then under-erases
+   * exactly as it did before this function existed. It is deliberate,
+   * because the alternatives are worse — guessing a width over-erases on a
+   * wider terminal, and `ESC[J` clears to end of SCREEN, so over-erasing
+   * destroys output above the region instead of merely leaving junk below
+   * it. Reachable only on a TTY whose winsize ioctl fails, since a non-TTY
+   * disables the region outright.
+   */
+  // A line's rows, memoized per width: most of a frame's lines are the
+  // last frame's, and measuring each one again was the most of a redraw's
+  // CPU (a 2,000-task run's profile).
+  let rowsWidth = -1
+  const rowsOf = new Map<string, number>()
+  const lineRows = (line: string): number => {
+    const cols = stream.columns
+    if (cols === undefined || cols <= 0) return 1
+    if (cols !== rowsWidth || rowsOf.size > 4096) {
+      rowsWidth = cols
+      rowsOf.clear()
+    }
+    let rows = rowsOf.get(line)
+    if (rows === undefined) {
+      rows = Math.max(1, Math.ceil(Bun.stringWidth(line) / cols))
+      rowsOf.set(line, rows)
+    }
+    return rows
+  }
+  const regionRows = (lines: readonly string[]): number => {
+    let rows = 0
+    for (const line of lines) rows += lineRows(line)
+    return rows
+  }
+
+  /**
+   * The leading lines that fit the terminal's height, one row spared.
+   * Cursor-up stops at the top of the screen, and a row that scrolled into
+   * the scrollback is out of the erase's reach: a region taller than the
+   * terminal left its top behind on every redraw, one stacked block per tick
+   * (VS Code's short panel, 2026-10-14). The first line always shows.
+   */
+  const fitted = (lines: readonly string[]): readonly string[] => {
+    const height = stream.rows
+    if (height === undefined || height <= 0) return lines
+    let rows = 0
+    let n = 0
+    for (const line of lines) {
+      rows += lineRows(line)
+      if (n > 0 && rows > height - 1) break
+      n++
+    }
+    return n === lines.length ? lines : lines.slice(0, n)
+  }
+
+  // Erase sequence for whatever is currently shown. A single row keeps
+  // the exact legacy bytes (ESC[2K\r); anything taller moves to its
+  // top row and clears to end of screen.
+  const eraseSeq = (): string => (shownRows > 1 ? `\r\x1b[${shownRows - 1}A\x1b[J` : CLEAR)
+
+  // Content written since the last frame, drawn with it: one write per
+  // frame, the region erased and redrawn once around all of it. Each row
+  // used to be three writes (erase, row, region) and a whole region
+  // redraw: 2,000 rows wrote 8.5 MB.
+  const pending: string[] = []
+  // The region's text as last written: a frame that would write the same
+  // bytes writes nothing.
+  let shownText = ''
+
+  /** Write what is pending and, where it may show, the region: one write. */
+  const draw = (): void => {
+    cancelTrailing()
+    let text = ''
+    const content = pending.length > 0
+    if (content) {
+      text = (shown ? eraseSeq() : '') + pending.join('')
+      pending.length = 0
+      shown = false
+      shownRows = 0
+    }
+    if (!dead && current !== null && atLineStart && holds === 0) {
+      // Built here, not at the set: a warm run's task events set the
+      // region hundreds of times inside one floor, and each build was a
+      // forecast pass and a summary render no frame showed (200 hits on a
+      // terminal: run graph 62 → 9 ms). Kept built: a write redraws it.
+      if (typeof current === 'function') current = current()
+      const lines = fitted(current!)
+      const region = lines.join('\n')
+      if (shown && region === shownText) {
+        if (text !== '') stream.write(text)
+        lastDraw = now()
+        return
+      }
+      text += (shown ? eraseSeq() : CLEAR) + region
+      shown = true
+      shownRows = regionRows(lines)
+      shownText = region
+    }
+    if (text !== '') stream.write(text)
+    lastDraw = now()
+  }
+  /**
+   * The next frame: now if the floor has passed since the last one, else
+   * once it does. A timer holding content keeps the process open until it
+   * lands; one that only redraws the region never does.
+   */
+  const frame = (): void => {
+    const since = now() - lastDraw
+    if (since >= forceFloorMs) {
+      draw()
+      return
+    }
+    if (trailing === null) {
+      trailing = setTimeout(() => {
+        trailing = null
+        draw()
+      }, forceFloorMs - since)
+      if (pending.length === 0) trailing.unref?.()
+    } else if (pending.length > 0) trailing.ref?.()
+  }
+  const set = (lines: Region, o: { force?: boolean }): void => {
+    if (!enabled || dead) return
+    current = lines
+    if (!atLineStart || holds > 0) return
+    if (o.force) {
+      // A burst coalesces: `current` is already the latest state, so one
+      // frame at the floor's expiry lands it.
+      frame()
+      return
+    }
+    const since = now() - lastDraw
+    if (since >= minRedrawMs) draw()
+  }
+
+  return {
+    enabled,
+    write(chunk) {
+      if (!enabled) {
+        if (held === null) {
+          stream.write(chunk)
+          return
+        }
+        held.push(chunk)
+        if (!flushQueued) {
+          flushQueued = true
+          setImmediate(flushHeld)
+        }
+        return
+      }
+      if (chunk.length > 0) atLineStart = chunk.endsWith('\n')
+      pending.push(chunk)
+      // A held terminal (a prompt waits on it) or a dead region takes the
+      // write now: nothing will draw a frame for it.
+      if (holds > 0 || dead) draw()
+      else frame()
+    },
+    writeTo(target, chunk) {
+      if (target === stream) return this.write(chunk)
+      // Held stdout is older than this chunk.
+      flushHeld()
+      if (!enabled) {
+        target.write(chunk)
+        return
+      }
+      // What this stream holds is older than the chunk: it lands first,
+      // with the region erased, and the region returns after the chunk.
+      let text = pending.join('')
+      pending.length = 0
+      if (shown) {
+        text = eraseSeq() + text
+        shown = false
+        shownRows = 0
+      }
+      if (text !== '') stream.write(text)
+      target.write(chunk)
+      if (!dead && current !== null && atLineStart && holds === 0) draw()
+    },
+    setStatus(line, o = {}) {
+      set([line], o)
+    },
+    setRegion(lines, o = {}) {
+      set(lines, o)
+    },
+    settle() {
+      flushHeld()
+      held = null
+    },
+    clearStatus() {
+      if (!enabled || dead) return
+      dead = true
+      current = null
+      cancelTrailing()
+      // Content still waiting for a frame lands now, over the erased region.
+      let text = pending.join('')
+      pending.length = 0
+      if (shown) {
+        text = eraseSeq() + text
+        shown = false
+        shownRows = 0
+      }
+      if (text !== '') stream.write(text)
+    },
+    hold() {
+      if (!enabled || dead) return () => undefined
+      holds++
+      cancelTrailing()
+      let text = pending.join('')
+      pending.length = 0
+      if (shown) {
+        text = eraseSeq() + text
+        shown = false
+        shownRows = 0
+      }
+      if (text !== '') stream.write(text)
+      let released = false
+      return () => {
+        if (released) return
+        released = true
+        holds--
+        if (holds === 0 && !dead && current !== null && atLineStart) draw()
+      }
+    },
+  }
+}

package/src/{util/refusal-notice.ts → ui/refusal.ts}

@@ -2,9 +2,10 @@
 // carries, a config refusal's frame, or a plain message laid out a fact a
 // line. The flat message stays what `--format json` and logs carry.
 
-import { configRefusal } from './config-frame.js'
-import type { RefusalParts } from './errors.js'
-import { notice, print, type Block, type Inline, type Tone } from './ui.js'
+import { configRefusal, type RefusalParts } from '../util/index.js'
+import { notice, type Block, type Inline } from './components.js'
+import { print } from './terminal.js'
+import type { Tone } from './theme.js'
 
 // A sentence break before a capital, a backtick or a paren: vx joins
 // its facts with these.
@@ -14,7 +15,8 @@ const SEE = /\s*\(see `([^`]+)`\)/
 // `(did you mean --concurrency?)`, `. Did you mean build?`: the fix.
 const MEANT = /\s*(?:\(did you mean ([^?]+)\?\)|(?:^|[.;—]\s*)[Dd]id you mean ([^?]+)\?)/
 
-const bare = (s: string): string => s.trim().replace(/[.:]$/, '')
+// A trailing `...` is the text's own (a `--filter a...`), not a full stop.
+const bare = (s: string): string => s.trim().replace(/(?<!\.)[.:]$/, '')
 
 /** A plain message in parts: its first sentence heads, each later one is a line. */
 export function messageParts(message: string): RefusalParts {
@@ -54,7 +56,7 @@ export function refusalNotice(
 ): Block {
   const c = parts === undefined ? configRefusal(message, opts.cwd ?? process.cwd()) : undefined
   if (c !== undefined) {
-    const what: Inline[] = [{ style: 'bold', text: c.where }, c.problem]
+    const what: Inline[] = [{ style: 'strong', text: c.where }, c.problem]
     return notice({
       tone: 'error',
       verb,

package/src/ui/terminal.ts

@@ -0,0 +1,51 @@
+// Where output leaves vx: the only file outside the live region that writes
+// to a stream. A screen is blocks (`print`), a line said mid-run (`say`), or
+// data a program reads (`data`: JSON, a completion script, a file's bytes),
+// which no component may restyle.
+
+import { inline, render, tagged, wrap, type Block, type Inline } from './components.js'
+import { detectColors, INDENT, type Tone } from './theme.js'
+
+export type StreamName = 'out' | 'err'
+
+const streamOf = (s: StreamName): NodeJS.WriteStream =>
+  s === 'out' ? process.stdout : process.stderr
+
+/** Write the blocks to stdout (`out`) or stderr (`err`), coloured for that stream. */
+export function print(stream: StreamName, ...blocks: Block[]): void {
+  const s = streamOf(stream)
+  s.write(render(blocks, detectColors(s)))
+}
+
+/** `tagged` on a stream (stderr unless told), coloured for it. */
+export function say(t: Tone, line: string, stream: StreamName = 'err'): void {
+  const s = streamOf(stream)
+  s.write(`${tagged(t, line, detectColors(s))}\n`)
+}
+
+/**
+ * Bytes a program reads, written as they are: `--format json`, a
+ * completion script, a file `vx show` prints. Never a sentence for a person.
+ */
+export function data(stream: StreamName, bytes: string): void {
+  streamOf(stream).write(bytes)
+}
+
+/** Whether a stream paints. */
+export function colorsOf(stream: StreamName): ReturnType<typeof detectColors> {
+  return detectColors(streamOf(stream))
+}
+
+/**
+ * A line that stands while something runs and then goes (`vx init`'s
+ * package install), on stdout's terminal only: piped, it is not written.
+ * Wrapped, never cut. Returns the call that takes it back.
+ */
+export function transient(line: Inline): () => void {
+  const s = process.stdout
+  if (s.isTTY !== true) return () => {}
+  const c = detectColors(s)
+  const rows = wrap(`${INDENT}${inline(line, c)} …`, s.columns ?? 80)
+  s.write(`\n${rows.join('\n')}`)
+  return () => void s.write(`\r\x1b[2K${'\x1b[1A\x1b[2K'.repeat(rows.length - 1)}\x1b[1A`)
+}

package/src/ui/theme.ts

@@ -0,0 +1,224 @@
+// The design tokens: every colour, glyph and spacing vx prints. Nothing
+// outside src/ui names a hue or writes an escape byte
+// (tests/ui-only-output.unsafe.test.ts); a component asks for a style.
+
+/** Whether a stream paints, and how wide it is. */
+export interface ColorSupport {
+  enabled: boolean
+  /** The terminal's width, read live; none off a terminal. Bars and rules fit it. */
+  readonly columns?: number | undefined
+}
+
+/**
+ * A style every component and inline token draws with, by the level of
+ * what it marks. Five levels, each one look, brightest first:
+ *
+ *   1 outcome   how a thing went: a tone (`ok` `warn` `error` `info`,
+ *               `aborted`, `notRun`), its glyph and status word bold
+ *   2 name      what it is about: a title (`heading`), an id's hues, a
+ *               command or path to type (`strong`, `term`), where a
+ *               cache answer came from (`local`, `remote`)
+ *   3 value     the fact itself: a field's value, a table cell, a
+ *               sentence (`value`, a soft light grey: no line of vx
+ *               reads plain white)
+ *   4 meta      what frames a fact: a label, a unit, a hint, a count
+ *               (`muted`, `label`)
+ *   5 chrome    rules and separators (`border`)
+ *
+ * A component picks the level; a plain string takes the level of where it
+ * sits (a value in a field, meta in a title's count).
+ */
+export type Style =
+  | 'ok'
+  | 'warn'
+  | 'error'
+  | 'info'
+  | 'aborted'
+  | 'notRun'
+  | 'local'
+  | 'remote'
+  | 'heading'
+  | 'term'
+  | 'value'
+  | 'muted'
+  | 'strong'
+  | 'label'
+  | 'border'
+  | 'plain'
+
+/** How a status went: the four a notice or a status line can be. */
+export type Tone = 'ok' | 'warn' | 'error' | 'info'
+
+const HUE: Record<Style, string> = {
+  ok: '#22c55e', // green-500
+  warn: '#eab308', // yellow-500
+  error: '#ef4444', // red-500
+  info: '#06b6d4', // cyan-500
+  aborted: '#f97316', // orange-500: red's neighbour, not a failure
+  notRun: '#a855f7', // purple-500: stopped before it began
+  local: '#38bdf8', // sky-400
+  remote: '#2563eb', // blue-600
+  heading: '#a78bfa', // violet-400: the brand's first stop
+  term: '#22d3ee', // cyan-400: a flag, a selector, an example to type
+  value: '#cbd5e1', // slate-300: the fact, one step under a name
+  muted: '',
+  strong: '',
+  label: '',
+  border: '#6e7681', // a panel's rule: quiet, never a tone
+  plain: '',
+}
+
+/** A tone's mark: the one glyph a status, a notice or a card opens with. */
+export const SYMBOL: Record<Tone, string> = { ok: '✓', warn: '!', error: '✗', info: '›' }
+
+/** Content sits this far in under its section or card head. */
+export const INDENT = '  '
+/** A field label's column: 8 wide, wider only if a label is. */
+export const LABEL_MIN = 8
+/** A meter's widest, and the label column beside it (2 indent + 8 label + 2 gap). */
+const BAR_MAX = 50
+const BAR_LABEL = 12
+
+/**
+ * Identity hues for the two halves of a `project#task` id, never a status
+ * colour: one name, one hue, in every run, list and row (2026-10-15).
+ */
+const IDENTITY = [
+  '#a78bfa', // violet-400
+  '#60a5fa', // blue-400
+  '#e879f9', // fuchsia-400
+  '#818cf8', // indigo-400
+  '#c084fc', // purple-400
+  '#93c5fd', // blue-300
+  '#f472b6', // pink-400
+] as const
+
+/** A name's identity hue: a fold of the name into the palette. */
+export function identityHue(name: string): string {
+  let h = 0
+  for (let i = 0; i < name.length; i++) h = (h * 31 + name.charCodeAt(i)) >>> 0
+  return IDENTITY[h % IDENTITY.length]!
+}
+
+/**
+ * Standard env precedence:
+ *   NO_COLOR non-empty          → off (overrides FORCE_COLOR)
+ *   FORCE_COLOR=0 or =false     → off, even on a TTY
+ *   FORCE_COLOR any other value → on (the empty string too)
+ *   any CI (`onCi`)             → on: a CI log looks like the terminal
+ *   else: on iff the stream is a TTY that is not `TERM=dumb`.
+ * `0` and `false` are the convention's "off" (supports-color, chalk,
+ * Node); reading every non-empty value as on painted a piped CI log that
+ * set `FORCE_COLOR=0` (nx#35292's bug).
+ */
+export function detectColors(stream: NodeJS.WriteStream = process.stdout): ColorSupport {
+  const force = process.env['FORCE_COLOR']
+  const enabled = process.env['NO_COLOR']
+    ? false
+    : force !== undefined
+      ? force !== '0' && force !== 'false'
+      : onCi() || (stream.isTTY === true && !dumbTerminal())
+  return {
+    enabled,
+    get columns() {
+      return stream.isTTY === true ? stream.columns : undefined
+    },
+  }
+}
+
+/**
+ * The variables a CI sets, each on when non-empty and not `0`/`false`:
+ * the generic `CI` most set, and the ones of CIs that set no `CI` (Azure
+ * Pipelines' `TF_BUILD`, Jenkins' `JENKINS_URL`, TeamCity's
+ * `TEAMCITY_VERSION`). A CI log gets the same colours as a terminal; one
+ * whose viewer shows raw escapes is turned off with `NO_COLOR`.
+ */
+const CI_VARS = [
+  'CI',
+  'GITHUB_ACTIONS',
+  'GITLAB_CI',
+  'BUILDKITE',
+  'CIRCLECI',
+  'TF_BUILD',
+  'JENKINS_URL',
+  'TEAMCITY_VERSION',
+] as const
+
+function onCi(): boolean {
+  return CI_VARS.some((name) => {
+    const v = process.env[name]
+    return v !== undefined && v !== '' && v !== '0' && v.toLowerCase() !== 'false'
+  })
+}
+
+/** `TERM=dumb` can neither paint nor move the cursor: vx prints to it as off a terminal. */
+export function dumbTerminal(): boolean {
+  return process.env['TERM'] === 'dumb'
+}
+
+export const RESET = '\x1b[0m'
+const BOLD = '\x1b[1m'
+const DIM = '\x1b[2m'
+const UNDERLINE = '\x1b[4m'
+
+// Bun.color('red', 'ansi') emits the colour number as a raw byte, so vx
+// paints 24-bit. Bun.color is FFI work per call; a run paints the same
+// handful of hues thousands of times, so each is converted once.
+const ansiCache = new Map<string, string>()
+function ansiFor(hex: string): string {
+  let v = ansiCache.get(hex)
+  if (v === undefined) ansiCache.set(hex, (v = Bun.color(hex, 'ansi-16m') ?? ''))
+  return v
+}
+
+export interface PaintOptions {
+  bold?: boolean
+  dim?: boolean
+  underline?: boolean
+}
+
+/** `text` in a raw hue (an identity, a gradient stop) and modifiers. Inside src/ui only. */
+export function paintHex(
+  hex: string,
+  text: string,
+  c: ColorSupport,
+  opts: PaintOptions = {},
+): string {
+  // Empty text paints nothing: an escape pair around no text is bytes and no mark.
+  if (!c.enabled || text === '') return text
+  let prefix = ''
+  if (opts.bold) prefix += BOLD
+  if (opts.dim) prefix += DIM
+  if (opts.underline) prefix += UNDERLINE
+  if (hex) prefix += ansiFor(hex)
+  return prefix === '' ? text : `${prefix}${text}${RESET}`
+}
+
+/** `text` in a style; `bold` adds weight to a hue. */
+export function paint(style: Style, text: string, c: ColorSupport, bold = false): string {
+  switch (style) {
+    case 'plain':
+      return text
+    case 'muted':
+      return paintHex('', text, c, { dim: true })
+    case 'strong':
+      return paintHex('', text, c, { bold: true })
+    case 'heading':
+      return paintHex(HUE.heading, text, c, { bold: true })
+    case 'label':
+      return paintHex('', text, c, { dim: true, underline: true })
+    default:
+      return paintHex(HUE[style], text, c, bold ? { bold: true } : {})
+  }
+}
+
+/** A meter's cells: 50, or fewer so the bar fits a narrower terminal. */
+export function barWidth(c: ColorSupport): number {
+  const columns = c.columns
+  return columns === undefined ? BAR_MAX : Math.max(10, Math.min(BAR_MAX, columns - BAR_LABEL))
+}
+
+/** A rule's width: flush with the bars beside their labels. */
+export function ruleWidth(c: ColorSupport): number {
+  return BAR_LABEL + barWidth(c)
+}