bdtui 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+# bdtui
+
+Fast blessed-based terminal UI for the [`bd`](https://github.com/gastownhall/beads) beads issue tracker.
+
+## Requirements
+
+- Node ≥ 20
+- `bd` installed and on `$PATH`
+- A project with a `.beads/` database (created by `bd init`)
+
+## Install
+
+First install `bd`:
+
+```bash
+brew install beads          # macOS / Linux
+npm install -g @beads/bd    # via Node.js
+```
+
+Then install bdtui:
+
+```bash
+npm install -g bdtui
+```
+
+## Usage
+
+```bash
+bdtui              # use current directory
+bdtui .            # explicit current directory
+bdtui ~/www/myapp  # explicit project path
+```
+
+## Layout
+
+```
+┌─[ready  open  in_progress  all]────────────────────────────┐
+│ list (40%)            │ detail (60%)                        │
+│ > be-12 P1 in_prog …  │ be-12 — Some bead title             │
+│   be-13 P2 open    …  │ Status: in_progress  Priority: P1   │
+│                       │ Type:   feature      Owner: —        │
+│                       │ …                                   │
+├───────────────────────┴─────────────────────────────────────┤
+│ ● Ready  │  ? help · q quit                                 │
+└─────────────────────────────────────────────────────────────┘
+```
+
+Beads with parent–child dependencies are shown as a tree inside the active filter:
+
+```
+be-10  P1 open    E    Epic title
+be-11  P2 open    T  ├ Child task
+be-12  P2 ready   T  └ Another child
+```
+
+## Keybindings
+
+| Key | Action |
+|-----|--------|
+| `j` / `↓` | Move down |
+| `k` / `↑` | Move up |
+| `g` / `G` | Jump to top / bottom |
+| `Enter` / `l` | Focus detail pane |
+| `h` / `Esc` | Back to list |
+| `f` | Cycle filter: ready → open → in_progress → all |
+| `r` | Reload current filter |
+| `/` | In-memory title filter |
+| `s` | Change status |
+| `c` | Close with reason |
+| `C` | Claim (in_progress + assign self) |
+| `o` | Reopen |
+| `p` | Change priority |
+| `D` | Dependency menu (add / remove) |
+| `y` | Yank bead ID to clipboard |
+| `?` | Help overlay |
+| `q` / `Ctrl-C` | Quit |
+
+## Author
+
+[JSIOVN](https://github.com/jsiovn)
+
+## License
+
+MIT

package/bin/bdtui.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import path from 'path';
+
+const arg = process.argv[2];
+const cwd = arg ? path.resolve(arg) : process.cwd();
+process.chdir(cwd);
+
+const { run } = await import('../src/app.js');
+await run(cwd);

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "bdtui",
+  "version": "0.1.0",
+  "description": "Terminal UI for the bd beads issue tracker",
+  "type": "module",
+  "bin": { "bdtui": "bin/bdtui.js" },
+  "files": ["bin", "src", "README.md"],
+  "author": "JSIOVN",
+  "license": "MIT",
+  "engines": { "node": ">=20" },
+  "dependencies": {
+    "blessed": "^0.1.81"
+  }
+}

package/src/app.js

@@ -0,0 +1,324 @@
+import blessed from 'blessed';
+import { execFile } from 'child_process';
+import { state, loadList, loadDetail, applyMutation } from './state.js';
+import { createList, renderList } from './views/list.js';
+import { createDetail, renderDetail } from './views/detail.js';
+import { statusPicker, priorityPicker, textPrompt, depMenu } from './views/modals.js';
+import { showHelp } from './keys.js';
+import { bdUpdate, bdClose, bdClaim, bdReopen, bdDepAdd, bdDepRemove } from './bd.js';
+
+const FILTERS = ['ready', 'open', 'in_progress', 'all'];
+
+export async function run(cwd) {
+  state.cwd = cwd;
+
+  const screen = blessed.screen({ smartCSR: true, title: 'bdtui', fullUnicode: true });
+
+  const tabBar = blessed.box({
+    parent: screen,
+    top: 0, left: 0,
+    width: '100%', height: 1,
+    content: '', tags: true,
+    style: { bg: 'black', fg: 'white' },
+  });
+
+  const statusBar = blessed.box({
+    parent: screen,
+    bottom: 0, left: 0,
+    width: '100%', height: 1,
+    content: ' Loading… | {gray-fg}? help{/}',
+    tags: true,
+    style: { bg: 'black', fg: 'white' },
+  });
+
+  const list = createList(screen);
+  const detail = createDetail(screen);
+
+  let debounceTimer = null;
+
+  function setStatus(msg, isError = false) {
+    const icon = isError ? '{red-fg}✗{/}' : '{green-fg}●{/}';
+    const text = isError ? `{red-fg}${msg}{/}` : msg;
+    statusBar.setContent(` ${icon} ${text}  {gray-fg}? help · q quit{/}`);
+    screen.render();
+  }
+
+  function renderTabBar() {
+    const tabs = FILTERS.map((f) => {
+      return f === state.filter
+        ? `{blue-bg}{white-fg}{bold} ${f} {/bold}{/}`
+        : `{gray-fg} ${f} {/}`;
+    });
+    const count = state.listOrder.length;
+    const info  = count > 0 ? `{gray-fg}  │  ${count} beads{/}` : '';
+    tabBar.setContent(tabs.join('{gray-fg}│{/}') + info);
+  }
+
+  function setFocusBorder(focused) {
+    if (focused === 'list') {
+      list.style.border.fg   = 'cyan';
+      detail.style.border.fg = 'gray';
+    } else {
+      list.style.border.fg   = 'gray';
+      detail.style.border.fg = 'cyan';
+    }
+  }
+
+  function render() {
+    renderTabBar();
+    renderList(list);
+    renderDetail(detail);
+    screen.render();
+  }
+
+  // When list selection changes, update selectedId and debounce detail fetch
+  function onNav() {
+    setImmediate(() => {
+      const idx = list.selected;
+      const id = state.listOrder[idx];
+      if (!id || id === state.selectedId) return;
+      state.selectedId = id;
+      renderDetail(detail);
+      screen.render();
+
+      clearTimeout(debounceTimer);
+      debounceTimer = setTimeout(async () => {
+        try {
+          await loadDetail(id);
+          renderDetail(detail);
+          screen.render();
+        } catch (err) {
+          setStatus(err.message, true);
+        }
+      }, 80);
+    });
+  }
+
+  // Capture all keypresses on the list to detect navigation
+  list.on('keypress', onNav);
+
+  // Focus border highlighting
+  list.on('focus',   () => { setFocusBorder('list');   screen.render(); });
+  detail.on('focus', () => { setFocusBorder('detail'); screen.render(); });
+
+  async function refresh() {
+    setStatus('Refreshing…');
+    try {
+      await loadList();
+      if (state.selectedId && !state.listOrder.includes(state.selectedId)) {
+        state.selectedId = state.listOrder[0] || null;
+      }
+      if (state.selectedId) await loadDetail(state.selectedId);
+      render();
+      setStatus('Ready');
+    } catch (err) {
+      setStatus(err.message, true);
+    }
+  }
+
+  async function cycleFilter() {
+    const idx = FILTERS.indexOf(state.filter);
+    state.filter = FILTERS[(idx + 1) % FILTERS.length];
+    setStatus(`Filter: ${state.filter} — loading…`);
+    try {
+      await loadList();
+      state.selectedId = state.listOrder[0] || null;
+      if (state.selectedId) await loadDetail(state.selectedId);
+      render();
+      setStatus(`Filter: ${state.filter}`);
+    } catch (err) {
+      setStatus(err.message, true);
+    }
+  }
+
+  // ── Global keys ────────────────────────────────────────────────────────────
+
+  screen.key(['q', 'C-c'], () => { screen.destroy(); process.exit(0); });
+
+  screen.key(['r'], refresh);
+  screen.key(['f'], cycleFilter);
+
+  screen.key(['?'], () => showHelp(screen, () => { list.focus(); screen.render(); }));
+
+  screen.key(['enter', 'l'], () => {
+    if (screen.focused === list) { setFocusBorder('detail'); detail.focus(); screen.render(); }
+  });
+
+  screen.key(['h', 'escape'], () => {
+    if (screen.focused !== list) { setFocusBorder('list'); list.focus(); screen.render(); }
+  });
+
+  screen.key(['g'], () => {
+    if (screen.focused !== list) return;
+    list.select(0);
+    onNav();
+    screen.render();
+  });
+
+  screen.key(['G'], () => {
+    if (screen.focused !== list) return;
+    list.select(state.listOrder.length - 1);
+    onNav();
+    screen.render();
+  });
+
+  screen.key(['/'], async () => {
+    if (screen.focused !== list) return;
+    try {
+      const query = await textPrompt(screen, 'Filter by title');
+      list.focus();
+      if (!query) { render(); return; }
+      const q = query.toLowerCase();
+      state.listOrder = state.listOrder.filter((id) => {
+        const b = state.beadsById.get(id);
+        return b?.title?.toLowerCase().includes(q);
+      });
+      state.selectedId = state.listOrder[0] || null;
+      renderList(list);
+      renderDetail(detail);
+      screen.render();
+      setStatus(`"${query}" — ${state.listOrder.length} results | r to reset`);
+    } catch {
+      list.focus();
+    }
+  });
+
+  // ── Mutation keys (list focus only) ────────────────────────────────────────
+
+  screen.key(['s'], async () => {
+    if (screen.focused !== list || !state.selectedId) return;
+    const id = state.selectedId;
+    try {
+      const newStatus = await statusPicker(screen);
+      list.focus();
+      const oldStatus = state.beadsById.get(id)?.status;
+      setStatus(`${id}: ${oldStatus} → ${newStatus}…`);
+      await applyMutation(id, () => bdUpdate(id, { status: newStatus }, state.cwd));
+      renderList(list);
+      renderDetail(detail);
+      screen.render();
+      setStatus(`${id}: ${oldStatus} → ${newStatus}`);
+    } catch (err) {
+      list.focus();
+      if (err.message !== 'cancelled') setStatus(err.message, true);
+    }
+  });
+
+  screen.key(['c'], async () => {
+    if (screen.focused !== list || !state.selectedId) return;
+    const id = state.selectedId;
+    try {
+      const reason = await textPrompt(screen, 'Close reason');
+      list.focus();
+      setStatus(`Closing ${id}…`);
+      await applyMutation(id, () => bdClose(id, reason, state.cwd));
+      await loadList();
+      render();
+      setStatus(`Closed ${id}`);
+    } catch (err) {
+      list.focus();
+      if (err.message !== 'cancelled') setStatus(err.message, true);
+    }
+  });
+
+  screen.key(['C'], async () => {
+    if (screen.focused !== list || !state.selectedId) return;
+    const id = state.selectedId;
+    setStatus(`Claiming ${id}…`);
+    try {
+      await applyMutation(id, () => bdClaim(id, state.cwd));
+      renderList(list);
+      renderDetail(detail);
+      screen.render();
+      setStatus(`Claimed ${id}`);
+    } catch (err) {
+      setStatus(err.message, true);
+    }
+  });
+
+  screen.key(['o'], async () => {
+    if (screen.focused !== list || !state.selectedId) return;
+    const id = state.selectedId;
+    setStatus(`Reopening ${id}…`);
+    try {
+      await applyMutation(id, () => bdReopen(id, state.cwd));
+      await loadList();
+      render();
+      setStatus(`Reopened ${id}`);
+    } catch (err) {
+      setStatus(err.message, true);
+    }
+  });
+
+  screen.key(['p'], async () => {
+    if (screen.focused !== list || !state.selectedId) return;
+    const id = state.selectedId;
+    try {
+      const priority = await priorityPicker(screen);
+      list.focus();
+      setStatus(`Setting priority ${priority} on ${id}…`);
+      await applyMutation(id, () => bdUpdate(id, { priority }, state.cwd));
+      renderList(list);
+      renderDetail(detail);
+      screen.render();
+      setStatus(`${id}: priority → ${priority}`);
+    } catch (err) {
+      list.focus();
+      if (err.message !== 'cancelled') setStatus(err.message, true);
+    }
+  });
+
+  screen.key(['D'], async () => {
+    if (screen.focused !== list || !state.selectedId) return;
+    const id = state.selectedId;
+    try {
+      const result = await depMenu(screen);
+      list.focus();
+      if (result.action === 'add') {
+        setStatus(`Adding dep: ${id} → ${result.targetId} [${result.type}]…`);
+        await applyMutation(id, () => bdDepAdd(id, result.targetId, result.type, state.cwd));
+        setStatus(`Added: ${id} → ${result.targetId} [${result.type}]`);
+      } else {
+        setStatus(`Removing dep: ${id} → ${result.targetId}…`);
+        await applyMutation(id, () => bdDepRemove(id, result.targetId, state.cwd));
+        setStatus(`Removed dep: ${id} → ${result.targetId}`);
+      }
+      renderDetail(detail);
+      screen.render();
+    } catch (err) {
+      list.focus();
+      if (err.message !== 'cancelled') setStatus(err.message, true);
+    }
+  });
+
+  screen.key(['y'], () => {
+    const id = state.selectedId;
+    if (!id) return;
+    const write = (cmd, args) => new Promise((res) => {
+      const p = execFile(cmd, args, res);
+      p.stdin?.end(id);
+    });
+    write('wl-copy', [])
+      .catch(() => write('xclip', ['-selection', 'clipboard']))
+      .catch(() => write('xsel', ['--clipboard', '--input']))
+      .catch(() => write('pbcopy', []))
+      .then((err) => {
+        setStatus(err ? `${id} (clipboard unavailable)` : `Copied ${id}`);
+      });
+  });
+
+  // ── Boot ───────────────────────────────────────────────────────────────────
+
+  setFocusBorder('list');
+  list.focus();
+  setStatus('Loading…');
+  try {
+    await loadList();
+    state.selectedId = state.listOrder[0] || null;
+    if (state.selectedId) await loadDetail(state.selectedId);
+  } catch (err) {
+    setStatus(err.message, true);
+  }
+  render();
+  setStatus('Ready | ? help');
+}

package/src/bd.js

@@ -0,0 +1,68 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+
+const execFileP = promisify(execFile);
+
+async function runBd(args, cwd) {
+  try {
+    const { stdout } = await execFileP('bd', args, { cwd });
+    return JSON.parse(stdout);
+  } catch (err) {
+    throw new Error(err.stderr?.trim() || err.message);
+  }
+}
+
+export const bdList = (filter, cwd) => {
+  if (filter === 'ready') return runBd(['ready', '--json'], cwd);
+  const args = ['list', '--json'];
+  if (filter === 'all') args.push('--all');
+  else if (filter) args.push('--status', filter);
+  return runBd(args, cwd);
+};
+
+export const bdShow = async (id, cwd) => {
+  const res = await runBd(['show', id, '--json'], cwd);
+  return Array.isArray(res) ? res[0] : res;
+};
+
+export const bdDeps = async (id, cwd) => {
+  const [down, up] = await Promise.all([
+    runBd(['dep', 'list', id, '--json'], cwd).catch(() => []),
+    runBd(['dep', 'list', id, '--direction=up', '--json'], cwd).catch(() => []),
+  ]);
+  return { down: Array.isArray(down) ? down : [], up: Array.isArray(up) ? up : [] };
+};
+
+export const bdDepListDown = async (id, cwd) => {
+  const res = await runBd(['dep', 'list', id, '--json'], cwd).catch(() => []);
+  return Array.isArray(res) ? res : [];
+};
+
+export const bdUpdate = (id, opts, cwd) => {
+  const args = ['update', id];
+  if (opts.status) args.push('--status', opts.status);
+  if (opts.priority !== undefined) args.push('--priority', String(opts.priority));
+  return runBd([...args, '--json'], cwd);
+};
+
+export const bdClose = (id, reason, cwd) => {
+  const args = ['close', id];
+  if (reason) args.push('--reason', reason);
+  return runBd([...args, '--json'], cwd);
+};
+
+export const bdClaim = (id, cwd) => runBd(['update', id, '--claim', '--json'], cwd);
+
+export const bdReopen = (id, cwd) => runBd(['reopen', id, '--json'], cwd);
+
+export const bdDepAdd = (child, parent, type, cwd) => {
+  const args = ['dep', 'add', child, parent];
+  if (type && type !== 'blocks') args.push('--type', type);
+  return runBd(args, cwd);
+};
+
+export const bdDepRemove = (child, parent, cwd) =>
+  runBd(['dep', 'remove', child, parent], cwd);
+
+// Returns all children of an epic (all statuses — bd children includes closed by default)
+export const bdChildren = (id, cwd) => runBd(['children', id, '--json'], cwd);

package/src/keys.js

@@ -0,0 +1,69 @@
+import blessed from 'blessed';
+
+export const HELP_TEXT = [
+  '',
+  '  Navigation',
+  '  ──────────────────────────────────────',
+  '  j / ↓       Move down in list',
+  '  k / ↑       Move up in list',
+  '  g           Jump to top',
+  '  G           Jump to bottom',
+  '  Enter / l   Focus detail pane',
+  '  h / Esc     Back to list',
+  '',
+  '  Filters & refresh',
+  '  ──────────────────────────────────────',
+  '  f           Cycle filter (ready/open/in_progress/all)',
+  '  r           Reload current filter from bd',
+  '  /           In-memory title filter',
+  '',
+  '  Mutations',
+  '  ──────────────────────────────────────',
+  '  s           Change status',
+  '  c           Close with reason',
+  '  C           Claim bead (in_progress + assign self)',
+  '  o           Reopen',
+  '  p           Change priority',
+  '  D           Dependency menu (add / remove)',
+  '',
+  '  Other',
+  '  ──────────────────────────────────────',
+  '  y           Yank bead ID to clipboard',
+  '  ?           Toggle this help',
+  '  q / Ctrl-C  Quit',
+  '',
+  '  Press ? q or Esc to close',
+].join('\n');
+
+export function showHelp(screen, onClose) {
+  const box = blessed.box({
+    parent: screen,
+    label: ' Keybindings ',
+    border: { type: 'line' },
+    top: 'center',
+    left: 'center',
+    width: '55%',
+    height: '80%',
+    content: HELP_TEXT,
+    tags: false,
+    keys: true,
+    scrollable: true,
+    alwaysScroll: true,
+    scrollbar: { ch: '│' },
+    style: {
+      border: { fg: 'cyan' },
+      label: { fg: 'cyan', bold: true },
+    },
+  });
+
+  box.focus();
+  screen.render();
+
+  const close = () => {
+    box.destroy();
+    screen.render();
+    onClose?.();
+  };
+
+  box.key(['?', 'q', 'escape', 'h'], close);
+}

package/src/state.js

@@ -0,0 +1,99 @@
+import { bdList, bdShow, bdDeps, bdDepListDown } from './bd.js';
+
+export const state = {
+  beadsById: new Map(),
+  listOrder: [],
+  treeMeta: new Map(), // id -> { depth: 0|1, isLast: bool }
+  selectedId: null,
+  filter: 'ready',
+  cwd: process.cwd(),
+};
+
+function buildTreeOrder(beads, parentOf) {
+  const byId = new Map(beads.map((b) => [b.id, b]));
+  const childrenOf = new Map();
+
+  for (const b of beads) {
+    const pid = parentOf.get(b.id);
+    if (pid && byId.has(pid)) {
+      if (!childrenOf.has(pid)) childrenOf.set(pid, []);
+      childrenOf.get(pid).push(b);
+    }
+  }
+
+  for (const children of childrenOf.values()) {
+    children.sort((a, b) => (a.priority ?? 2) - (b.priority ?? 2) || a.id.localeCompare(b.id));
+  }
+
+  const childIds = new Set([...childrenOf.values()].flat().map((b) => b.id));
+  const roots = beads.filter((b) => !childIds.has(b.id));
+
+  const ordered = [];
+  for (const root of roots) {
+    ordered.push({ id: root.id, depth: 0, isLast: false });
+    const children = childrenOf.get(root.id) || [];
+    children.forEach((child, i) => {
+      ordered.push({ id: child.id, depth: 1, isLast: i === children.length - 1 });
+    });
+  }
+
+  return ordered;
+}
+
+export async function loadList() {
+  const beads = await bdList(state.filter, state.cwd);
+  const byId = new Map(beads.map((b) => [b.id, b]));
+
+  // Build parent-child map from real bd deps (dependency_type === 'parent-child').
+  // Fetch only for non-epic beads — epics don't have epic parents in this model.
+  const candidates = beads.filter((b) => b.issue_type !== 'epic');
+  const depLists = await Promise.all(
+    candidates.map((b) => bdDepListDown(b.id, state.cwd))
+  );
+
+  const parentOf = new Map();
+  candidates.forEach((b, i) => {
+    const pc = depLists[i].find((d) => d.dependency_type === 'parent-child');
+    if (pc?.id) parentOf.set(b.id, pc.id);
+  });
+
+  // Bring in parent epics that aren't already in the filtered list so the tree
+  // can root under them. Only add the epic itself, NOT its other children —
+  // that's what caused closed beads to leak into ready/open filters.
+  if (state.filter !== 'all') {
+    const missingParents = [...new Set(parentOf.values())].filter((id) => !byId.has(id));
+    const fetched = await Promise.all(
+      missingParents.map((id) => bdShow(id, state.cwd).catch(() => null))
+    );
+    for (const p of fetched) {
+      if (p && p.id && !byId.has(p.id)) {
+        beads.push(p);
+        byId.set(p.id, p);
+      }
+    }
+  }
+
+  const treeItems = buildTreeOrder(beads, parentOf);
+  state.listOrder = treeItems.map((t) => t.id);
+  state.treeMeta = new Map(treeItems.map((t) => [t.id, { depth: t.depth, isLast: t.isLast }]));
+
+  for (const b of beads) {
+    state.beadsById.set(b.id, { ...state.beadsById.get(b.id), ...b });
+  }
+  return beads;
+}
+
+export async function loadDetail(id) {
+  const [bead, deps] = await Promise.all([
+    bdShow(id, state.cwd),
+    bdDeps(id, state.cwd),
+  ]);
+  const merged = { ...bead, depsDown: deps.down, depsUp: deps.up };
+  state.beadsById.set(id, merged);
+  return merged;
+}
+
+export async function applyMutation(id, mutatorFn) {
+  await mutatorFn();
+  return loadDetail(id);
+}

package/src/views/detail.js

@@ -0,0 +1,137 @@
+import blessed from 'blessed';
+import { state } from '../state.js';
+
+const STATUS_COLOR = {
+  open: 'white', in_progress: 'cyan', blocked: 'red',
+  deferred: 'yellow', closed: 'gray',
+};
+const PRIORITY_COLOR  = ['red', 'yellow', 'green', 'cyan', 'gray'];
+const PRIORITY_LABEL  = ['Critical', 'High', 'Normal', 'Low', 'Trivial'];
+
+function t(color, text)  { return `{${color}-fg}${text}{/}`; }
+function bold(text)      { return `{bold}${text}{/bold}`; }
+function fmtDate(iso)    { return iso ? iso.slice(0, 10) : '—'; }
+
+function field(label, value, labelWidth = 10) {
+  return `${t('gray', (label + ':').padEnd(labelWidth))} ${value}`;
+}
+
+function sectionHeader(title) {
+  return `\n${bold(t('cyan', title))}\n${t('gray', '─'.repeat(44))}`;
+}
+
+function depLine(dep, arrow, color) {
+  const id    = dep.id || String(dep);
+  const type  = dep.dep_type || dep.type || 'blocks';
+  const title = dep.title ? ` ${t('gray', '— ' + dep.title)}` : '';
+  return `  ${t(color, arrow)} {bold}${id}{/bold} ${t('gray', `[${type}]`)}${title}`;
+}
+
+function renderDescription(lines, text) {
+  for (const l of text.split('\n')) {
+    if (l.startsWith('## '))      lines.push(`  ${bold(t('cyan', l.slice(3)))}`);
+    else if (l.startsWith('# '))  lines.push(`  ${bold(t('white', l.slice(2)))}`);
+    else if (l.match(/^[-*] /))   lines.push(`  ${t('gray', '•')} ${l.slice(2)}`);
+    else                          lines.push(`  ${l}`);
+  }
+}
+
+let lastId = null;
+
+export function createDetail(screen) {
+  return blessed.box({
+    parent: screen,
+    top: 1,
+    left: '40%',
+    width: '60%',
+    bottom: 1,
+    border: { type: 'line' },
+    label: ' Detail ',
+    tags: true,
+    scrollable: true,
+    alwaysScroll: true,
+    keys: true,
+    mouse: true,
+    scrollbar: { ch: ' ', track: { bg: 'black' }, style: { bg: 'cyan' } },
+    style: {
+      border: { fg: 'gray' },
+      label: { fg: 'white', bold: true },
+    },
+  });
+}
+
+export function renderDetail(box) {
+  const id = state.selectedId;
+  if (!id) { box.setContent(t('gray', 'No bead selected.')); return; }
+
+  const b = state.beadsById.get(id);
+  if (!b) { box.setContent(t('gray', `Loading ${id}…`)); return; }
+
+  const resetScroll = id !== lastId;
+  lastId = id;
+
+  const prio       = b.priority ?? 2;
+  const prioColor  = PRIORITY_COLOR[prio] || 'white';
+  const prioLabel  = PRIORITY_LABEL[prio] || String(prio);
+  const statColor  = STATUS_COLOR[b.status] || 'white';
+
+  const lines = [];
+
+  // ── Header ─────────────────────────────────────────────────────────────────
+  lines.push(`{bold}{white-fg}${b.id}{/} {gray-fg}—{/} ${b.title || ''}`);
+  lines.push(t('gray', '═'.repeat(50)));
+  lines.push('');
+
+  // ── Fields ─────────────────────────────────────────────────────────────────
+  lines.push(
+    field('Status',   `{${statColor}-fg}{bold}${b.status || '—'}{/bold}{/}`) +
+    '    ' +
+    field('Priority', `{${prioColor}-fg}{bold}P${prio} ${prioLabel}{/bold}{/}`)
+  );
+  lines.push(
+    field('Type',     t('white', b.issue_type || '—')) +
+    '    ' +
+    field('Owner',    t('white', b.owner || '—'))
+  );
+  lines.push(
+    field('Created',  t('gray', fmtDate(b.created_at))) +
+    '    ' +
+    field('Updated',  t('gray', fmtDate(b.updated_at)))
+  );
+
+  if (b.labels?.length > 0) {
+    lines.push(field('Labels', b.labels.map((l) => t('blue', l)).join('  ')));
+  }
+
+  // ── Dependencies ───────────────────────────────────────────────────────────
+  if (b.depsDown?.length > 0) {
+    lines.push(sectionHeader(`Depends on (${b.depsDown.length})`));
+    for (const d of b.depsDown) lines.push(depLine(d, '→', 'yellow'));
+  }
+  if (b.depsUp?.length > 0) {
+    lines.push(sectionHeader(`Needed by (${b.depsUp.length})`));
+    for (const d of b.depsUp) lines.push(depLine(d, '←', 'green'));
+  }
+
+  // ── Description ────────────────────────────────────────────────────────────
+  if (b.description) {
+    lines.push(sectionHeader('Description'));
+    lines.push('');
+    renderDescription(lines, b.description);
+  }
+
+  if (b.acceptance) {
+    lines.push(sectionHeader('Acceptance'));
+    lines.push('');
+    renderDescription(lines, b.acceptance);
+  }
+
+  if (b.notes) {
+    lines.push(sectionHeader('Notes'));
+    lines.push('');
+    renderDescription(lines, b.notes);
+  }
+
+  box.setContent(lines.join('\n'));
+  if (resetScroll) box.scrollTo(0);
+}

package/src/views/list.js

@@ -0,0 +1,83 @@
+import blessed from 'blessed';
+import { state } from '../state.js';
+
+const STATUS_SHORT = {
+  open:        'open   ',
+  in_progress: 'in_prog',
+  blocked:     'blocked',
+  deferred:    'deferrd',
+  closed:      'closed ',
+};
+
+const PRIORITY_COLOR = ['red', 'yellow', 'green', 'cyan', 'gray'];
+const STATUS_COLOR = {
+  open: 'white', in_progress: 'cyan', blocked: 'red',
+  deferred: 'yellow', closed: 'gray',
+};
+
+const TYPE_BADGE = {
+  epic:    '{magenta-fg}E{/}',
+  task:    '{blue-fg}T{/}',
+  chore:   '{gray-fg}C{/}',
+  bug:     '{red-fg}B{/}',
+  story:   '{cyan-fg}S{/}',
+  feature: '{green-fg}F{/}',
+};
+
+function t(color, text) {
+  return `{${color}-fg}${text}{/}`;
+}
+
+function formatRow(bead, depth = 0, isLast = false) {
+  const id   = bead.id.padEnd(14);
+  const p    = `P${bead.priority ?? 2}`;
+  const stat = bead.status || 'open';
+  const s    = (STATUS_SHORT[stat] || stat.slice(0, 7)).padEnd(7);
+  const badge = TYPE_BADGE[bead.issue_type] ?? t('gray', '?');
+  const prefix = depth > 0 ? t('gray', isLast ? ' └ ' : ' ├ ') : '   ';
+  const title = bead.title || '';
+
+  const idCol = t('gray', id);
+  const pCol  = t(PRIORITY_COLOR[bead.priority ?? 2] ?? 'white', p);
+  const sCol  = t(STATUS_COLOR[stat] ?? 'white', s);
+
+  return `${idCol} ${pCol} ${sCol} ${badge}${prefix}${title}`;
+}
+
+export function createList(screen) {
+  return blessed.list({
+    parent: screen,
+    top: 1,
+    left: 0,
+    width: '40%',
+    bottom: 1,
+    border: { type: 'line' },
+    label: ' Beads ',
+    tags: true,
+    keys: true,
+    vi: true,
+    mouse: true,
+    scrollbar: { ch: ' ', track: { bg: 'black' }, style: { bg: 'cyan' } },
+    style: {
+      selected: { bg: 'blue', fg: 'white', bold: true },
+      border: { fg: 'gray' },
+      label: { fg: 'white', bold: true },
+    },
+  });
+}
+
+export function renderList(list) {
+  const items = state.listOrder.map((id) => {
+    const b = state.beadsById.get(id);
+    const { depth = 0, isLast = false } = state.treeMeta.get(id) ?? {};
+    return b ? formatRow(b, depth, isLast) : t('gray', id);
+  });
+
+  const selIdx = state.selectedId
+    ? Math.max(0, state.listOrder.indexOf(state.selectedId))
+    : 0;
+
+  list.setLabel(` Beads ${t('gray', `(${state.listOrder.length})`)} `);
+  list.setItems(items);
+  if (state.listOrder.length > 0) list.select(selIdx);
+}

package/src/views/modals.js

@@ -0,0 +1,112 @@
+import blessed from 'blessed';
+
+function listPicker(screen, label, items, borderColor = 'cyan') {
+  return new Promise((resolve, reject) => {
+    const height = Math.min(items.length + 4, 20);
+    const picker = blessed.list({
+      parent: screen,
+      label: ` ${label} `,
+      border: { type: 'line' },
+      top: 'center',
+      left: 'center',
+      width: 36,
+      height,
+      items,
+      keys: true,
+      vi: true,
+      tags: true,
+      style: {
+        selected: { bg: 'blue', fg: 'white', bold: true },
+        border: { fg: borderColor },
+        label: { fg: borderColor, bold: true },
+      },
+    });
+
+    picker.focus();
+    screen.render();
+
+    picker.once('select', (item) => {
+      picker.destroy();
+      screen.render();
+      resolve(item.content.trim());
+    });
+
+    picker.key(['escape', 'q', 'h'], () => {
+      picker.destroy();
+      screen.render();
+      reject(new Error('cancelled'));
+    });
+  });
+}
+
+export function statusPicker(screen) {
+  return listPicker(
+    screen,
+    'Change Status',
+    ['open', 'in_progress', 'blocked', 'deferred', 'closed'],
+    'cyan',
+  );
+}
+
+export function priorityPicker(screen) {
+  return listPicker(
+    screen,
+    'Change Priority',
+    ['0 — Critical', '1 — High', '2 — Normal', '3 — Low', '4 — Trivial'],
+    'yellow',
+  ).then((val) => parseInt(val[0], 10));
+}
+
+export function textPrompt(screen, label, defaultVal = '') {
+  return new Promise((resolve, reject) => {
+    const prompt = blessed.prompt({
+      parent: screen,
+      border: 'line',
+      height: 'shrink',
+      width: '60%',
+      top: 'center',
+      left: 'center',
+      label: ` ${label} `,
+      tags: true,
+      keys: true,
+      vi: true,
+      style: {
+        border: { fg: 'green' },
+        label: { fg: 'green', bold: true },
+      },
+    });
+
+    prompt.input(`${label}:`, defaultVal, (err, value) => {
+      prompt.destroy();
+      screen.render();
+      if (err || value == null) return reject(new Error('cancelled'));
+      resolve(value.trim());
+    });
+
+    screen.render();
+  });
+}
+
+const DEP_TYPES = [
+  'blocks', 'tracks', 'related', 'relates-to',
+  'validates', 'caused-by', 'parent-child',
+];
+
+export async function depMenu(screen) {
+  const action = await listPicker(
+    screen,
+    'Dependency',
+    ['Add dep', 'Remove dep'],
+    'magenta',
+  );
+
+  const targetId = await textPrompt(screen, 'Target bead ID');
+  if (!targetId) throw new Error('cancelled');
+
+  if (action === 'Add dep') {
+    const type = await listPicker(screen, 'Dep type', DEP_TYPES, 'magenta');
+    return { action: 'add', targetId, type };
+  }
+
+  return { action: 'remove', targetId };
+}