@kontextmind/kxm 0.7.39 → 0.7.43

package/packages/core/tui/src/tui/panelComponent.ts

@@ -0,0 +1,208 @@
+/**
+ * Pi TUI adapter for a KXM panel surface.
+ *
+ * The pure renderer produces lines; this class turns them into real components
+ * so the panel gets Pi's viewport, scrollbar, mouse, and differential
+ * rendering, and so the same code path works inside a Pi extension
+ * (`ctx.ui.custom`) and inside the standalone CLI.
+ *
+ * It owns only wiring: read the published surface, reduce a key into state and
+ * effects, run effects through the registry, then repaint. Configuration rules
+ * stay in the owning module, which is the whole point of publishing sections
+ * instead of centralising them.
+ */
+
+import { Box, HStack, ScrollView, Text, TruncatedText, VStack, type Component, type TuiMouseEvent, type TuiMouseEventResult, Key, matchesKey } from "@earendil-works/pi-tui";
+import type { KxmTuiSectionView } from "../types/surface.ts";
+import { fitText } from "./layout.ts";
+import {
+  initialKxmTuiPanelState,
+  reduceKxmTuiInput,
+  reconcileKxmTuiPanelState,
+  type KxmTuiEffect,
+  type KxmTuiPanelState,
+} from "./panel.ts";
+import { renderKxmTuiPanel } from "./render.ts";
+import type { KxmTuiRegistry } from "../services/registry.ts";
+import type { KxmTuiTheme } from "./theme.ts";
+
+export interface KxmTuiPanelComponentOptions {
+  readonly registry: KxmTuiRegistry;
+  readonly theme: KxmTuiTheme;
+  readonly title: string;
+  readonly breadcrumb?: string;
+  readonly helpLines?: readonly string[];
+  readonly requestRender: () => void;
+  readonly onQuit: () => void;
+  readonly getWidth?: () => number;
+  /** Extra footer text, e.g. a hub URL or a dirty-file warning. */
+  readonly statusText?: () => string | undefined;
+}
+
+export const KXM_TUI_PANEL_HELP: readonly string[] = Object.freeze([
+  "↑↓ move · ←→ or Tab panes · PgUp/PgDn section · enter edit or open list",
+  "type to filter a list · x clears a value · esc backs out · q quit · h help",
+]);
+
+function rowsComponent(): { stack: VStack; scroll: ScrollView; fill: (rows: string[]) => void } {
+  const stack = new VStack([], { gap: 0 });
+  const scroll = new ScrollView(stack, { primary: true, overscroll: "contain", scrollbar: "auto" });
+  const fill = (rows: string[]): void => {
+    stack.clear();
+    for (const row of rows) stack.addChild(new TruncatedText(row, 0, 0));
+  };
+  return { stack, scroll, fill };
+}
+
+export class KxmTuiPanelComponent implements Component {
+  readonly root = new VStack([], { gap: 0 });
+  private readonly options: KxmTuiPanelComponentOptions;
+  private readonly body = rowsComponent();
+  private sections: readonly KxmTuiSectionView[];
+  private state: KxmTuiPanelState;
+  private notice: string | undefined;
+  private unsubscribe: () => void;
+
+  constructor(options: KxmTuiPanelComponentOptions) {
+    this.options = options;
+    this.sections = options.registry.getSections();
+    this.state = initialKxmTuiPanelState(this.sections);
+    this.unsubscribe = options.registry.subscribe(() => this.refresh());
+    this.rebuild();
+  }
+
+  getState(): KxmTuiPanelState {
+    return this.state;
+  }
+
+  getSections(): readonly KxmTuiSectionView[] {
+    return this.sections;
+  }
+
+  /** Point the cursor at a field, e.g. after opening a named section. */
+  focus(sectionId: string, fieldId?: string): void {
+    const sectionIndex = this.sections.findIndex((section) => section.id === sectionId);
+    if (sectionIndex < 0) return;
+    const fields = this.sections[sectionIndex]?.fields ?? [];
+    const fieldIndex = fieldId ? Math.max(0, fields.findIndex((field) => field.id === fieldId)) : this.state.fieldIndex;
+    this.state = { ...this.state, pane: "fields", sectionIndex, fieldIndex };
+    this.rebuild();
+    this.options.requestRender();
+  }
+
+  setStatus(message: string | undefined): void {
+    this.notice = message;
+    this.rebuild();
+    this.options.requestRender();
+  }
+
+  refresh(): void {
+    const next = this.options.registry.getSections();
+    this.sections = next;
+    this.state = reconcileKxmTuiPanelState(this.state, next);
+    this.rebuild();
+    this.options.requestRender();
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.pageUp) || matchesKey(data, Key.ctrl("u"))) {
+      this.body.scroll.scrollBy(-(this.viewport() - 2));
+      this.options.requestRender();
+      return;
+    }
+    if (matchesKey(data, Key.pageDown) || matchesKey(data, Key.ctrl("d"))) {
+      this.body.scroll.scrollBy(this.viewport() - 2);
+      this.options.requestRender();
+      return;
+    }
+    const step = reduceKxmTuiInput(this.state, this.sections, data);
+    this.state = step.state;
+    for (const effect of step.effects) this.run(effect);
+    this.rebuild();
+    this.options.requestRender();
+  }
+
+  private viewport(): number {
+    const height = this.body.scroll.viewportHeight;
+    return height > 3 ? height : 10;
+  }
+
+  private run(effect: KxmTuiEffect): void {
+    if (effect.type === "quit") {
+      this.options.onQuit();
+      return;
+    }
+    if (effect.type === "notice") {
+      this.notice = effect.message;
+      return;
+    }
+    this.notice = undefined;
+    void this.options.registry.invoke(effect.invocation).then((result) => {
+      if (!result.ok) this.setStatus(result.message ?? "the owner refused that change");
+      else if (this.notice === undefined) this.setStatus(undefined);
+    });
+  }
+
+  private footer(): string {
+    const status = this.notice ?? this.options.statusText?.();
+    const base = "↑↓ · ←→ panes · enter edit · x clear · esc back · h help · q quit";
+    return status ? `${base}  ${status}` : base;
+  }
+
+  private rebuild(): void {
+    const theme = this.options.theme;
+    const width = this.options.getWidth?.() ?? 120;
+    const title = new Box(1, 0, theme.headerBg);
+    title.addChild(new HStack([
+      { component: new Text(theme.cursor(this.options.title), 0, 0), basis: 12, shrink: 1, minSize: 6 },
+      {
+        component: new Text(
+          this.options.breadcrumb ? theme.dim(fitText(this.options.breadcrumb, Math.max(4, width - 16))) : "",
+          0,
+          0,
+        ),
+        grow: 1,
+        shrink: 1,
+        minSize: 8,
+      },
+    ], { gap: 2 }));
+    this.body.fill(
+      renderKxmTuiPanel(this.sections, this.state, theme, {
+        title: this.options.title,
+        ...(this.options.breadcrumb ? { breadcrumb: this.options.breadcrumb } : {}),
+        helpLines: this.options.helpLines ?? KXM_TUI_PANEL_HELP,
+        footer: this.footer(),
+      }, width),
+    );
+    // No horizontal padding: the renderer already fits every row to the
+    // requested width, and a padded Box would push the last column over and
+    // make the row wrapper truncate the value it exists to show.
+    const panel = new Box(0, 0, theme.panelBg);
+    panel.addChild(this.body.scroll);
+    this.root.clear();
+    this.root.addChild(title, { basis: "auto", shrink: 0 });
+    this.root.addChild(panel, { basis: "auto", grow: 1, shrink: 1, minSize: 1 });
+  }
+
+  handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+    return this.root.handleMouse?.(event);
+  }
+
+  invalidate(): void {
+    this.root.invalidate();
+  }
+
+  render(width: number): string[] {
+    return this.root.render(width);
+  }
+
+  dispose(): void {
+    this.unsubscribe();
+    this.unsubscribe = () => undefined;
+  }
+}
+
+/** Build a panel component and its initial state for a non-TTY snapshot. */
+export function createKxmTuiPanelComponent(options: KxmTuiPanelComponentOptions): KxmTuiPanelComponent {
+  return new KxmTuiPanelComponent(options);
+}

package/packages/core/tui/src/tui/render.ts

@@ -0,0 +1,309 @@
+/**
+ * Pure renderer for KXM panel surfaces.
+ *
+ * Rendering is a function of (sections, state, width) returning lines, exactly
+ * like `renderMeshTui` for `kxm dash`. That is what makes a config surface
+ * testable in CI without a PTY and lets the same rows appear inside the Pi TUI,
+ * inside `kxm dash`, and in a plain-text audit dump.
+ *
+ * Every emitted line is fitted to `width`: one over-wide row corrupts the whole
+ * frame, so fitting happens here rather than in each caller. The edit caret is
+ * drawn as a text marker instead of a reverse-video block so a colourless theme
+ * stays free of escape codes.
+ */
+
+import {
+  groupedKxmTuiChoices,
+  type KxmTuiChoice,
+  type KxmTuiField,
+  type KxmTuiSectionView,
+  type KxmTuiStatus,
+  type KxmTuiStep,
+} from "../types/surface.ts";
+import { stripTerminalSequences } from "@earendil-works/pi-tui";
+import { KXM_TUI_MARKS, alignRight, fitText, formatAge, padRight, progressBar, wrapPlain } from "./layout.ts";
+import { pendingKey, visibleChoices, type KxmTuiPanelState, type KxmTuiPane } from "./panel.ts";
+import { createPlainKxmTuiTheme, type KxmTuiTheme } from "./theme.ts";
+
+const SECTION_PANE_RATIO = 1 / 3;
+const MIN_PANE_WIDTH = 16;
+const PROGRESS_WIDTH = 20;
+const OUTPUT_TAIL = 6;
+/** Below this, both panes would be unreadable, so only the focused one draws. */
+const SPLIT_MIN_WIDTH = 76;
+
+export interface KxmTuiRenderOptions {
+  readonly title: string;
+  readonly breadcrumb?: string;
+  readonly footer?: string;
+  readonly helpLines?: readonly string[];
+  readonly nowMs?: number;
+}
+
+function statusMark(status: KxmTuiStatus | undefined, theme: KxmTuiTheme, fallback: string): string {
+  switch (status) {
+    case "ready":
+      return theme.fg("success", KXM_TUI_MARKS.ready);
+    case "available":
+      return theme.fg("accent", KXM_TUI_MARKS.available);
+    case "blocked":
+      return theme.fg("error", KXM_TUI_MARKS.blocked);
+    default:
+      return theme.dim(fallback);
+  }
+}
+
+function cursorMark(active: boolean, theme: KxmTuiTheme): string {
+  return active ? theme.cursor(KXM_TUI_MARKS.cursor) : KXM_TUI_MARKS.blankCursor;
+}
+
+function paneSplit(width: number): { sections: number; fields: number } {
+  const third = Math.max(MIN_PANE_WIDTH, Math.floor(width * SECTION_PANE_RATIO));
+  const sections = Math.min(third, Math.max(MIN_PANE_WIDTH, Math.floor(width / 2)));
+  return { sections, fields: Math.max(MIN_PANE_WIDTH, width - sections - 1) };
+}
+
+function fieldIsPending(state: KxmTuiPanelState, section: KxmTuiSectionView, field: KxmTuiField): boolean {
+  return state.pending.includes(pendingKey({ source: section.source, sectionId: section.id, fieldId: field.id }));
+}
+
+function sectionRow(
+  section: KxmTuiSectionView,
+  focused: boolean,
+  pane: KxmTuiPane,
+  theme: KxmTuiTheme,
+  width: number,
+): string {
+  const cursor = cursorMark(focused && pane === "sections", theme);
+  const flag = section.notice ? theme.fg(section.noticeLevel === "error" ? "error" : "warning", "!") : " ";
+  const count = section.fields.length;
+  const unset = section.fields.filter((field) => field.kind !== "info" && field.value === undefined).length;
+  const right = unset > 0 ? `${unset} unset / ${count}` : `${count} field${count === 1 ? "" : "s"}`;
+  return fitText(alignRight(`${cursor} ${flag} ${section.title}`, right, width), width);
+}
+
+function choiceSuffix(choice: KxmTuiChoice): string {
+  const parts: string[] = [];
+  if (choice.detail) parts.push(choice.detail);
+  if (choice.statusText) parts.push(choice.statusText);
+  return parts.join(" · ");
+}
+
+function choiceRows(field: KxmTuiField, state: KxmTuiPanelState, theme: KxmTuiTheme, width: number): string[] {
+  const shown = visibleChoices(field, state.filter);
+  const lines: string[] = [];
+  if (state.filtering) {
+    lines.push(fitText(`   ${theme.dim(`filter: ${state.filter || "(type to filter · esc clears)"}`)}`, width));
+  }
+  if (shown.length === 0) {
+    lines.push(fitText(`   ${theme.dim("no match")}`, width));
+    return lines;
+  }
+  let position = -1;
+  for (const group of groupedKxmTuiChoices(field)) {
+    const filtered = shown.filter((choice) => (choice.group ?? "") === group.group);
+    if (filtered.length === 0) continue;
+    if (group.group) lines.push(fitText(`   ${theme.key(group.group.toUpperCase())}`, width));
+    for (const choice of filtered) {
+      position += 1;
+      lines.push(
+        fitText(
+          alignRight(
+            `${cursorMark(position === state.choiceIndex, theme)} ${statusMark(choice.status, theme, KXM_TUI_MARKS.pending)} ${choice.label}`,
+            choiceSuffix(choice),
+            width,
+          ),
+          width,
+        ),
+      );
+    }
+  }
+  return lines;
+}
+
+const STEP_MARKS: Record<KxmTuiStep["state"], string> = {
+  pending: "·",
+  satisfied: KXM_TUI_MARKS.passed,
+  running: KXM_TUI_MARKS.active,
+  done: KXM_TUI_MARKS.passed,
+  failed: KXM_TUI_MARKS.failed,
+};
+
+function stepColor(state: KxmTuiStep["state"], theme: KxmTuiTheme): (text: string) => string {
+  switch (state) {
+    case "running":
+      return (text) => theme.fg("accent", text);
+    case "done":
+      return (text) => theme.fg("success", text);
+    case "failed":
+      return (text) => theme.fg("error", text);
+    default:
+      return theme.dim;
+  }
+}
+
+function stepRows(steps: readonly KxmTuiStep[], theme: KxmTuiTheme, width: number): string[] {
+  return steps.map((step) => {
+    const paint = stepColor(step.state, theme);
+    return fitText(alignRight(`   ${paint(STEP_MARKS[step.state])} ${step.label}`, step.detail ?? "", width), width);
+  });
+}
+
+function progressRow(field: KxmTuiField, theme: KxmTuiTheme, width: number): string {
+  const progress = field.progress;
+  if (!progress) return "";
+  const ratio = progress.ratio;
+  const right = ratio === undefined ? "working" : `${Math.round(ratio * 100)}%`;
+  return fitText(alignRight(`   ${progress.label}`, `${progressBar(ratio, PROGRESS_WIDTH)} ${right}`, width), width);
+}
+
+function focusedFieldDetail(
+  field: KxmTuiField,
+  state: KxmTuiPanelState,
+  theme: KxmTuiTheme,
+  width: number,
+): string[] {
+  const lines: string[] = [];
+  if (field.keyPath) lines.push(fitText(`   ${theme.dim(`key: ${field.keyPath}`)}`, width));
+  for (const line of wrapPlain(field.detail ?? "", width - 3)) {
+    if (line) lines.push(fitText(`   ${theme.dim(line)}`, width));
+  }
+  for (const line of wrapPlain(field.statusText ?? "", width - 3)) {
+    if (line) lines.push(fitText(`   ${theme.fg("error", line)}`, width));
+  }
+  const progress = progressRow(field, theme, width);
+  if (progress) lines.push(progress);
+  if (field.steps?.length) lines.push(...stepRows(field.steps, theme, width));
+  if (field.output?.length) {
+    lines.push(...field.output.slice(-OUTPUT_TAIL).map((line) => fitText(`   ${theme.dim(line)}`, width)));
+  }
+  if (field.actions?.length) {
+    lines.push(fitText(`   ${theme.key(field.actions.map((action) => `${action.key} ${action.label}`).join(" · "))}`, width));
+  }
+  if (state.mode === "choices") lines.push(...choiceRows(field, state, theme, width));
+  if (state.mode === "edit" || field.awaitingInput) {
+    const draft = state.mode === "edit" ? `${state.draft.slice(0, state.caret)}|${state.draft.slice(state.caret)}` : "|";
+    lines.push(fitText(`   ${theme.dim("›")} ${draft}`, width));
+  }
+  return lines;
+}
+
+function fieldRows(
+  section: KxmTuiSectionView,
+  state: KxmTuiPanelState,
+  theme: KxmTuiTheme,
+  width: number,
+  nowMs: number,
+): string[] {
+  const lines: string[] = [];
+  section.fields.forEach((field, index) => {
+    const focused = state.pane === "fields" && state.fieldIndex === index;
+    if (field.kind === "info") {
+      lines.push(fitText(`   ${theme.dim(field.label)}  ${theme.dim(field.value ?? field.placeholder ?? "")}`, width));
+      return;
+    }
+    const pending = fieldIsPending(state, section, field);
+    const mark = statusMark(field.status, theme, pending ? "◌" : KXM_TUI_MARKS.pending);
+    const value = pending && field.value === undefined ? theme.dim("saving…") : field.value;
+    const shown = value ?? theme.dim(field.placeholder ?? "not set");
+    const age = field.updatedAt ? theme.dim(` (${formatAge(field.updatedAt, nowMs)})`) : "";
+    lines.push(fitText(`${cursorMark(focused, theme)} ${mark} ${alignRight(field.label, `${shown}${age}`, width - 4)}`, width));
+    if (focused) lines.push(...focusedFieldDetail(field, state, theme, width));
+  });
+  return lines;
+}
+
+function noticeRows(section: KxmTuiSectionView | undefined, theme: KxmTuiTheme, width: number): string[] {
+  if (!section?.notice) return [];
+  const token = section.noticeLevel === "error" ? "error" : "warning";
+  return wrapPlain(section.notice, width - 2).map((line) => fitText(theme.fg(token, line), width));
+}
+
+function singlePaneLines(
+  sections: readonly KxmTuiSectionView[],
+  state: KxmTuiPanelState,
+  theme: KxmTuiTheme,
+  width: number,
+  nowMs: number,
+): string[] {
+  const section = sections[state.sectionIndex];
+  if (state.pane === "fields" && section) {
+    return [
+      fitText(theme.headerBg(alignRight(` ${section.title}`, section.source, width)), width),
+      ...noticeRows(section, theme, width),
+      ...fieldRows(section, state, theme, width, nowMs),
+    ];
+  }
+  return [
+    fitText(theme.headerBg(alignRight(" SECTIONS", `${sections.length}`, width)), width),
+    ...sections.map((candidate, index) => sectionRow(candidate, index === state.sectionIndex, state.pane, theme, width)),
+  ];
+}
+
+function twoPaneLines(
+  sections: readonly KxmTuiSectionView[],
+  state: KxmTuiPanelState,
+  theme: KxmTuiTheme,
+  width: number,
+  nowMs: number,
+): string[] {
+  const split = paneSplit(width);
+  const left: string[] = [fitText(theme.key(" SECTIONS"), split.sections)];
+  sections.forEach((candidate, index) =>
+    left.push(sectionRow(candidate, index === state.sectionIndex, state.pane, theme, split.sections)),
+  );
+  const right: string[] = [];
+  const section = sections[state.sectionIndex];
+  if (section) {
+    right.push(fitText(alignRight(` ${section.title}`, section.source, split.fields), split.fields));
+    if (section.detail) right.push(fitText(` ${theme.dim(section.detail)}`, split.fields));
+    right.push(...noticeRows(section, theme, split.fields));
+    right.push(...fieldRows(section, state, theme, split.fields, nowMs));
+  } else {
+    right.push(fitText(theme.dim("no surface is published"), split.fields));
+  }
+  const rows: string[] = [];
+  for (let index = 0; index < Math.max(left.length, right.length); index += 1) {
+    rows.push(fitText(`${padRight(left[index] ?? "", split.sections)} ${right[index] ?? ""}`, width));
+  }
+  return rows;
+}
+
+/**
+ * Draw one frame.
+ *
+ * Narrow terminals collapse to the focused pane instead of shrinking both, which
+ * keeps a field label legible at 48 columns.
+ */
+export function renderKxmTuiPanel(
+  sections: readonly KxmTuiSectionView[],
+  state: KxmTuiPanelState,
+  theme: KxmTuiTheme,
+  options: KxmTuiRenderOptions,
+  width = 120,
+): string[] {
+  const nowMs = options.nowMs ?? Date.now();
+  const title = `${theme.cursor(options.title)}${options.breadcrumb ? `  ${theme.dim(options.breadcrumb)}` : ""}`;
+  const header = [fitText(title, width)];
+  if (state.help) {
+    const help = (options.helpLines ?? ["no help published"]).flatMap((line) => wrapPlain(line, Math.max(1, width - 2)));
+    return [...header, ...help.map((line) => fitText(line, width)), fitText(theme.dim("esc close help"), width)];
+  }
+  const body = width < SPLIT_MIN_WIDTH
+    ? singlePaneLines(sections, state, theme, width, nowMs)
+    : twoPaneLines(sections, state, theme, width, nowMs);
+  const footer = options.footer ? [fitText(theme.dim(options.footer), width)] : [];
+  return [...header, ...body, ...footer];
+}
+
+/** Render a frame to plain text, with all styling removed. */
+export function renderKxmTuiPanelText(
+  sections: readonly KxmTuiSectionView[],
+  state: KxmTuiPanelState,
+  options: KxmTuiRenderOptions,
+  width = 120,
+): string {
+  return `${renderKxmTuiPanel(sections, state, createPlainKxmTuiTheme(), options, width)
+    .map((line) => stripTerminalSequences(line))
+    .join("\n")}\n`;
+}

package/packages/core/tui/src/tui/theme.ts

@@ -0,0 +1,145 @@
+/**
+ * Colour seam for KXM terminal surfaces.
+ *
+ * Components ask for a semantic colour instead of emitting ANSI, so the same
+ * renderer works inside the Pi TUI (host theme), inside the standalone `kxm`
+ * CLI (this palette), and inside a test or a piped `--json` path (identity
+ * functions). The identity theme is load-bearing, not cosmetic: `kxm dash`
+ * asserts that a non-TTY snapshot contains no control sequences at all.
+ *
+ * The palette is the one `kxm dash` has always used, moved here so a second
+ * surface cannot drift to a different shade of "this row failed".
+ */
+
+export type KxmTuiForeground =
+  | "text"
+  | "accent"
+  | "muted"
+  | "dim"
+  | "success"
+  | "error"
+  | "warning"
+  | "border";
+
+/**
+ * A semantic palette. Every method takes text and returns styled text.
+ *
+ * `fg()` is the primitive; the named helpers exist because callers read better
+ * with `theme.error(msg)` than with a token string.
+ */
+export interface KxmTuiTheme {
+  /** False when the theme is a passthrough (non-TTY, `NO_COLOR`, tests). */
+  readonly colored: boolean;
+  fg(token: KxmTuiForeground, text: string): string;
+  accent(text: string): string;
+  success(text: string): string;
+  error(text: string): string;
+  warning(text: string): string;
+  muted(text: string): string;
+  dim(text: string): string;
+  label(text: string): string;
+  value(text: string): string;
+  key(text: string): string;
+  cursor(text: string): string;
+  headerBg(text: string): string;
+  panelBg(text: string): string;
+}
+
+const SGR: Readonly<Record<KxmTuiForeground, string>> = Object.freeze({
+  text: "37",
+  accent: "1;36",
+  muted: "2",
+  dim: "2",
+  success: "1;32",
+  error: "1;31",
+  warning: "1;33",
+  border: "90",
+});
+
+/** Identity theme: emits no escape codes at all. */
+export function createPlainKxmTuiTheme(): KxmTuiTheme {
+  const passthrough = (text: string): string => text;
+  return {
+    colored: false,
+    fg: (_token, text) => text,
+    accent: passthrough,
+    success: passthrough,
+    error: passthrough,
+    warning: passthrough,
+    muted: passthrough,
+    dim: passthrough,
+    label: passthrough,
+    value: passthrough,
+    key: passthrough,
+    cursor: passthrough,
+    headerBg: passthrough,
+    panelBg: passthrough,
+  };
+}
+
+/**
+ * SGR palette for the standalone `kxm` CLI, which has no Pi theme to borrow.
+ *
+ * `color: false` returns the identity theme, so a caller that already knows it
+ * is not on a TTY gets plain text without needing environment variables.
+ */
+export function createKxmTuiAnsiTheme(color: boolean): KxmTuiTheme {
+  if (!color) return createPlainKxmTuiTheme();
+  const fg = (token: KxmTuiForeground, text: string): string => `\u001b[${SGR[token]}m${text}\u001b[0m`;
+  return {
+    colored: true,
+    fg,
+    accent: (text) => fg("accent", text),
+    success: (text) => fg("success", text),
+    error: (text) => fg("error", text),
+    warning: (text) => fg("warning", text),
+    muted: (text) => fg("muted", text),
+    dim: (text) => fg("dim", text),
+    label: (text) => fg("text", text),
+    value: (text) => `\u001b[1m${text}\u001b[0m`,
+    key: (text) => fg("muted", text),
+    cursor: (text) => fg("accent", text),
+    headerBg: (text) => `\u001b[1;97;44m${text}\u001b[0m`,
+    panelBg: (text) => `\u001b[48;5;236m${text}\u001b[0m`,
+  };
+}
+
+/** Choose the CLI theme from the environment, honouring `NO_COLOR`. */
+export function createDefaultKxmTuiTheme(
+  env: Record<string, string | undefined> = process.env,
+): KxmTuiTheme {
+  return createKxmTuiAnsiTheme(!(env.NO_COLOR || env.KXM_TUI_NO_COLOR));
+}
+
+/** The slice of Pi's `Theme` this kit needs. */
+export interface PiThemeLike {
+  fg(token: string, text: string): string;
+  bg(token: string, text: string): string;
+}
+
+/**
+ * Adapt a Pi extension theme so kit components reuse the host's colours.
+ *
+ * `headerBg`/`panelBg` map onto Pi's selection background: Pi has no notion of
+ * a panel fill, and inventing one here would fight the user's theme.
+ */
+export function createKxmTuiThemeFromPi(theme: PiThemeLike, colored = true): KxmTuiTheme {
+  if (!colored) return createPlainKxmTuiTheme();
+  const fg = (token: KxmTuiForeground, text: string): string => theme.fg(token === "dim" ? "muted" : token, text);
+  return {
+    colored: true,
+    fg,
+    accent: (text) => fg("accent", text),
+    success: (text) => fg("success", text),
+    error: (text) => fg("error", text),
+    warning: (text) => fg("warning", text),
+    muted: (text) => fg("muted", text),
+    dim: (text) => fg("dim", text),
+    label: (text) => fg("text", text),
+    value: (text) => fg("accent", text),
+    key: (text) => fg("muted", text),
+    cursor: (text) => fg("accent", text),
+    headerBg: (text) => theme.bg("selectedBg", text),
+    panelBg: (text) => theme.bg("selectedBg", text),
+  };
+}