@genee/omp-opsx-addon 0.1.0

package/lib/usage-render.ts

@@ -0,0 +1,526 @@
+import { visibleWidth, truncateToWidth } from "@oh-my-pi/pi-tui";
+import { resolveUsedFraction, getProviderDefinition, type UsageLimit, type UsageReport } from "@oh-my-pi/pi-ai";
+import { summarizeReport, quotaPolicyFor } from "./usage-resolver.js";
+
+// Hardcoded ANSI retained for `ansiPainter` — the RPC/print fallback path and
+// the legacy `render.test.ts` baseline. The interactive component-factory path
+// swaps them for the host theme via `themePainter(theme)`.
+const R = "\x1b[0m", G = "\x1b[32m", Y = "\x1b[33m", X = "\x1b[31m", D = "\x1b[2m";
+const BLUE = "\x1b[34m", PURPLE = "\x1b[35m", CYAN = "\x1b[36m", WHITE = "\x1b[37m";
+const BOLD = "\x1b[1m";
+const c = (s: string, t: string): string => `${s}${t}${R}`;
+
+// The subset of the host `ThemeColor` union the widget actually paints with.
+// Keeping it narrow lets widget tests inject a mock theme that only implements
+// `fg` instead of the full `Theme` surface (the host passes a real `Theme`,
+// which is structurally assignable thanks to `PainterColor ⊆ ThemeColor`).
+export type PainterColor = "success" | "warning" | "error" | "dim" | "accent" | "text";
+
+/** Minimal theme surface the rendering painter consumes (`host Theme.fg`). */
+export interface PainterTheme {
+    fg(color: PainterColor, text: string): string;
+}
+
+/**
+ * Decouples "which ANSI/theme color wraps a span" from the validated flex-wrap
+ * layout brain. `ansiPainter` reproduces the pre-refactor hardcoded ANSI; a
+ * `themePainter(theme)` routes every status color through the host theme so the
+ * widget follows the active palette. Provider brand identity colors stay raw
+ * ANSI under both painters (the host theme exposes no arbitrary-hue token — see
+ * the design trade-off), using `accent` only as the header fallback when a
+ * provider has no curated brand color.
+ */
+export interface Painter {
+    /** Used-fraction percentage, threshold-colored. */
+    pct(p: number): string;
+    /** Exhausted-window marker text, error-colored. */
+    exhausted(text: string): string;
+    /** Inter-column separator, already dyed incl. flanking spaces (3 cells). */
+    sep: string;
+    /** Provider header. `brandAnsi` is a raw brand-color SGR (or "" when none). */
+    header(label: string, brandAnsi: string): string;
+    /** Numeric balance text (e.g. "余额 ¥18.06"), text-colored. */
+    balance(text: string): string;
+    /** Foreground-color an arbitrary span with a named color (waveform cells). */
+    fg(color: PainterColor, text: string): string;
+}
+
+const pctValue = (p: number): string => `${Math.round(p * 100)}%`;
+const pctColor = (p: number): PainterColor => (p >= 0.85 ? "error" : p >= 0.6 ? "warning" : "success");
+
+/** Pre-refactor hardcoded ANSI — the RPC/print fallback and the test baseline. */
+export const ansiPainter: Painter = {
+    pct: (p) => {
+        const col = pctColor(p);
+        return c(col === "error" ? X : col === "warning" ? Y : G, pctValue(p));
+    },
+    exhausted: (text) => c(X, text),
+    sep: ` ${D}│${R} `,
+    header: (label, brandAnsi) => c(brandAnsi ? BOLD + brandAnsi : BOLD, label),
+    balance: (text) => c(WHITE, text),
+    fg: (color, text) => c(color === "error" ? X : color === "warning" ? Y : color === "success" ? G : color === "dim" ? D : color === "accent" ? CYAN : WHITE, text),
+};
+
+/** Status colors via the active host theme; brand headers keep raw ANSI. */
+export function themePainter(theme: PainterTheme): Painter {
+    return {
+        pct: (p) => theme.fg(pctColor(p), pctValue(p)),
+        exhausted: (text) => theme.fg("error", text),
+        sep: ` ${theme.fg("dim", "│")} `,
+        header: (label, brandAnsi) => (brandAnsi ? c(brandAnsi, label) : theme.fg("accent", label)),
+        balance: (text) => theme.fg("text", text),
+        fg: (color, text) => theme.fg(color, text),
+    };
+}
+
+// Curated short labels + brand colors for providers whose registry `name` is too
+// verbose for a compact status widget (e.g. "Z.AI (GLM Coding Plan · Sign in)").
+// Unknown providers fall back to the omp registry display name, then the raw id.
+const PROVIDER: Record<string, { label: string; color: string }> = {
+    "zhipu-coding-plan": { label: "智谱",    color: PURPLE },
+    zai:                 { label: "智谱",    color: PURPLE },
+    "kimi-code":         { label: "Kimi",    color: CYAN },
+    "minimax-code-cn":   { label: "MiniMax", color: X },
+    deepseek:            { label: "DeepSeek",color: BLUE },
+    cursor:              { label: "Cursor",  color: CYAN },
+    "opencode-go":       { label: "OpenCode",color: G },
+    moonshot:            { label: "Moonshot",color: G },
+};
+
+const providerLabel = (id: string): { label: string; color: string } => {
+    const known = PROVIDER[id];
+    if (known) return known;
+    const reg = getProviderDefinition(id);
+    if (reg?.name) return { label: reg.name, color: "" };
+    return { label: id, color: "" };
+};
+
+const WL: Record<string, string> = { "5h": "5h", "rolling-5h": "5h", "1d": "日", "1w": "周", weekly: "周", "1mo": "月", monthly: "月" };
+
+// ── helpers ──────────────────────────────────────────────────────────
+
+const pad2 = (n: number): string => String(n).padStart(2, "0");
+
+/** Fixed-width reset countdown, e.g. "00d03h12m05s"; "即将重置" once elapsed. */
+const resetIn = (resetsAt: number): string => {
+    const diffMs = resetsAt - Date.now();
+    if (diffMs <= 0) return "即将重置";
+    const totalSec = Math.floor(diffMs / 1_000);
+    const d = Math.floor(totalSec / 86_400);
+    const h = Math.floor((totalSec % 86_400) / 3_600);
+    const m = Math.floor((totalSec % 3_600) / 60);
+    const s = totalSec % 60;
+    return `${pad2(d)}d${pad2(h)}h${pad2(m)}m${pad2(s)}s`;
+};
+
+function isQuotaFull(l: UsageLimit): boolean {
+    if (l.status === "exhausted") return true;
+    const pct = resolveUsedFraction(l);
+    return typeof pct === "number" && pct >= 1;
+}
+
+function resetAtOf(l: UsageLimit, report?: UsageReport): number | undefined {
+    if (l.window?.resetsAt) return l.window.resetsAt;
+    return report?.limits.find((x) => x.window?.resetsAt)?.window?.resetsAt;
+}
+
+/** Exhausted / 100% text (uncolored); the painter wraps it in the error color. */
+const exhaustedText = (l: UsageLimit, report?: UsageReport): string => {
+    const at = resetAtOf(l, report);
+    return at !== undefined ? resetIn(at) : "耗尽";
+};
+
+/** Recovery countdown when the provider is unusable.
+ *  - conjunctive / balance (智谱、OpenCode、DeepSeek…): latest reset — full
+ *    recovery waits for the last blocking window.
+ *  - bucket (Cursor): soonest reset — any revived bucket unblocks usage.
+ *  Falls back to any sibling resetsAt / `耗尽` when no exhausted window has one.
+ */
+const providerExhaustedText = (report: UsageReport): string => {
+    const preferLatest = quotaPolicyFor(report.provider) !== "bucket";
+    const pick = (a: number, b: number): number => (preferLatest ? Math.max(a, b) : Math.min(a, b));
+
+    let chosen: number | undefined;
+    // Prefer each exhausted window's own resetsAt — do NOT inherit a sibling's
+    // timestamp here, or "latest/soonest among dead windows" gets skewed.
+    for (const l of report.limits) {
+        if (!isQuotaFull(l)) continue;
+        const at = l.window?.resetsAt;
+        if (typeof at !== "number") continue;
+        chosen = chosen === undefined ? at : pick(chosen, at);
+    }
+    if (chosen === undefined) {
+        for (const l of report.limits) {
+            const at = l.window?.resetsAt;
+            if (typeof at !== "number") continue;
+            chosen = chosen === undefined ? at : pick(chosen, at);
+        }
+    }
+    return chosen !== undefined ? resetIn(chosen) : "耗尽";
+};
+
+const cursorWinLabel = (l: UsageLimit): string | undefined => {
+    const hay = `${l.id ?? ""} ${l.label ?? ""} ${l.window?.id ?? ""}`.toLowerCase();
+    if (hay.includes("ondemand") || hay.includes("on-demand") || hay.includes("spendlimit") || hay.includes("按需")) return "按需";
+    if (hay.includes("builtin") || hay.includes("cursor models") || hay.includes("planusage") || hay.includes("autopercent") || hay.includes("内置")) return "内置";
+    if (hay.includes("other") || hay.includes("named") || hay.includes("apipercent") || hay.includes("其他")) return "其他";
+    return undefined;
+};
+
+const winLabel = (l: UsageLimit): string => {
+    const cursor = cursorWinLabel(l);
+    if (cursor) return cursor;
+    const w = l.window;
+    if (!w) return l.label || "?";
+    if (WL[w.id]) return WL[w.id];
+    if (w.durationMs === 18_000_000) return "5h";
+    if (w.durationMs === 86_400_000) return "日";
+    if (w.durationMs === 604_800_000) return "周";
+    if (w.durationMs === 2_592_000_000) return "月";
+    if (w.id === "default") return l.label === "Total quota" ? "总" : l.label;
+    return w.label || w.id;
+};
+
+const windowSortKey = (l: UsageLimit): number => {
+    const cursor = cursorWinLabel(l);
+    if (cursor === "内置") return 4;
+    if (cursor === "其他") return 5;
+    if (cursor === "按需") return 7;
+    const w = l.window;
+    if (!w) return 50;
+    if (w.id === "5h") return 0;
+    if (w.id === "1d") return 1;
+    if (w.id === "1w") return 2;
+    if (w.id === "1mo") return 3;
+    // Cursor dashboard order: Cursor Models（内置）→ Other Models（其他）→ On-demand（按需）.
+    if (w.id === "builtin" || w.id === "auto") return 4;
+    if (w.id === "other" || w.id === "api") return 5;
+    if (w.id === "ondemand") return 7;
+    if (w.durationMs === 18_000_000) return 0;
+    if (w.durationMs === 86_400_000) return 1;
+    if (w.durationMs === 604_800_000) return 2;
+    if (w.durationMs === 2_592_000_000) return 3;
+    if (w.id === "default" || l.label === "Total quota") return 100;
+    return 50;
+};
+
+/** Right-align a cell: pad short lines; leave ≥-width lines intact (colWidth = max). */
+const padRight = (s: string, width: number): string => {
+    const v = visibleWidth(s);
+    if (v >= width) return s;
+    return s + " ".repeat(width - v);
+};
+
+// ── column builder ───────────────────────────────────────────────────
+
+/**
+ * Render a single provider as a compact 2-line column:
+ *   line 0 — provider name
+ *   line 1 — either horizontal window chips (`5h 0% · 周 70%`) or a single
+ *            reset countdown when the provider is unusable.
+ *
+ * Exhaustion follows `summarizeReport` policy:
+ *   - conjunctive (智谱 / Kimi / MiniMax / OpenCode): any required window dead
+ *     → whole body becomes the latest exhausted-window reset countdown
+ *   - bucket (Cursor): still usable while any bucket has quota → keep every
+ *     window chip; dead windows show `100%` without a countdown. Fully dead →
+ *     soonest reset countdown (any revived bucket unblocks).
+ *   - balance (DeepSeek): remaining ≤ 0 → countdown / `耗尽`
+ *
+ * `undefined` when there is nothing to show. Natural widths only —
+ * `renderUsageReports` owns multi-column alignment, `ProviderCard` owns
+ * per-card truncation.
+ */
+export const buildColumn = (r: UsageReport, painter: Painter = ansiPainter, loading = false): string[] | undefined => {
+    if (r.limits.length === 0) return;
+    const { label, color } = providerLabel(r.provider);
+    const header = painter.header(loading ? `${label}⟳` : label, color);
+    const health = summarizeReport(r);
+
+    // Balance / non-window providers (DeepSeek CNY, etc.).
+    if (!r.limits.some((l) => Boolean(l.window?.id))) {
+        const l = r.limits[0];
+        let val: string;
+        if (health.exhausted || isQuotaFull(l)) {
+            val = painter.exhausted(exhaustedText(l, r));
+        } else if (typeof l.amount.remaining === "number") {
+            const sym = (l.amount.unit as string) === "CNY" ? "¥" : "$";
+            const text = r.provider === "deepseek" ? `余额 ${sym}${l.amount.remaining}` : `${sym}${l.amount.remaining}`;
+            val = painter.balance(text);
+        } else {
+            const pct = resolveUsedFraction(l);
+            val = typeof pct === "number" ? painter.pct(pct) : "?";
+        }
+        return [header, val];
+    }
+
+    // Provider-level dead → single countdown (no mixed % chips).
+    if (health.exhausted) {
+        return [header, painter.exhausted(providerExhaustedText(r))];
+    }
+
+    // Still usable → horizontal chips. Dead windows keep a % / 耗尽 marker
+    // (Cursor partial exhaustion) but never a reset countdown.
+    // Cursor: only show 内置/其他/按需. Unclassified monthly leftovers
+    // (Personal Usage / legacy request-count buckets that fall back to "月")
+    // are noise and are hidden.
+    const sorted = [...r.limits].sort((a, b) => windowSortKey(a) - windowSortKey(b));
+    const parts: string[] = [];
+    const isCursor = r.provider === "cursor";
+    for (const l of sorted) {
+        if (isCursor && !cursorWinLabel(l)) continue;
+        const wl = winLabel(l);
+        let val: string;
+        if (isQuotaFull(l)) {
+            const pct = resolveUsedFraction(l);
+            val = typeof pct === "number" ? painter.pct(Math.min(pct, 1)) : painter.exhausted("耗尽");
+        } else {
+            const pct = resolveUsedFraction(l);
+            val = typeof pct === "number" ? painter.pct(pct) : "?";
+        }
+        parts.push(`${wl} ${val}`);
+    }
+    if (parts.length === 0) {
+        // e.g. Cursor only returned unclassified monthly leftovers — keep the
+        // column visible rather than dropping a logged-in provider.
+        return isCursor ? [header, painter.balance("—")] : undefined;
+    }
+    return [header, parts.join(" · ")];
+};
+
+/**
+ * Render a logged-in provider that has no report yet as a header + a single
+ * placeholder row (`—`). Placeholder identity is always carried by an explicit id
+ * (see `renderUsageReports` `placeholderIds`); it is NEVER inferred from an empty
+ * `limits` array, so a real fetch that returns no windows is not mistaken for a
+ * logged-in-but-unfetched provider.
+ */
+export const buildPlaceholderColumn = (provider: string, painter: Painter = ansiPainter, loading = false): string[] => {
+    const { label, color } = providerLabel(provider);
+    // Loading placeholder: body shows ⟳ (fetch in flight) instead of the idle —.
+    return [painter.header(loading ? `${label}⟳` : label, color), painter.balance(loading ? "⟳" : "—")];
+}
+
+// ── flex-wrap table layout ───────────────────────────────────────────
+
+const SEP_VISUAL = 3;
+
+
+export function renderUsageReports(
+    reports: UsageReport[],
+    maxWidth = 120,
+    painter: Painter = ansiPainter,
+    placeholderIds?: readonly string[],
+    loadingProviders?: ReadonlySet<string>,
+    consumptionTracks?: Map<string, ConsumptionTrack>,
+    usageEstimates?: Map<string, string>,
+): string[] {
+    // Placeholder providers are logged-in but unfetched this round. Their ids are
+    // explicit (never inferred from `limits.length === 0`); dedupe against reports
+    // so a provider present in both doesn't render twice.
+    const reportedIds = new Set((reports ?? []).map((r) => r.provider));
+    const placeholders = (placeholderIds ?? []).filter((id) => !reportedIds.has(id));
+    if (!reports?.length && placeholders.length === 0) return [];
+    const loading = loadingProviders ?? new Set<string>();
+
+    // Build each provider column (header + usage / placeholder). Waveforms are
+    // appended AFTER the uniform block width is known so every provider's
+    // mini chart is the same width.
+    interface ProviderColumn { provider: string; col: string[] }
+    const cols: ProviderColumn[] = (reports ?? []).map((r) => {
+        const col = r.limits.length === 0
+            ? buildPlaceholderColumn(r.provider, painter, loading.has(r.provider))
+            : buildColumn(r, painter, loading.has(r.provider));
+        if (!col) return { provider: r.provider, col: [] };
+        // Second-level estimate override replaces the usage line (balance style).
+        const est = usageEstimates?.get(r.provider);
+        if (est && col.length >= 2) col[1] = painter.balance(est);
+        return { provider: r.provider, col };
+    });
+    for (const id of placeholders) {
+        cols.push({ provider: id, col: buildPlaceholderColumn(id, painter, loading.has(id)) });
+    }
+    const valid = cols.filter((c) => c.col.length > 0);
+    if (valid.length === 0) return [];
+
+    // Uniform block width: every provider block is padded to the widest column,
+    // so usage columns align in a clean grid (no ragged per-provider widths).
+    const natural = valid.map((c) => Math.max(...c.col.map((l) => visibleWidth(l))));
+    const blockWidth = Math.max(...natural);
+    const waveCols = Math.min(WAVEFORM_COLS, blockWidth);
+
+    // Multiple providers: pad every row to the uniform block width so the grid
+    // aligns (a lone provider keeps its natural width — nothing to align with).
+    const pad = valid.length > 1;
+    for (const c of valid) {
+        // Equal-width per-provider consumption waveform (same char count for
+        // all). A track that exists but has no samples renders as a blank
+        // placeholder strip, keeping the column height stable.
+        if (consumptionTracks) {
+            const track = consumptionTracks.get(c.provider);
+            if (track) c.col.push(...renderConsumptionLines(track.samples, painter, waveCols));
+        }
+        if (pad) c.col = c.col.map((l) => padRight(l, blockWidth));
+    }
+    // Single row, never wrapped: every provider block sits on one line at its
+    // natural uniform width — the row extends beyond `maxWidth` rather than
+    // squeezing content or breaking to a second line (user preference:
+    // roomy over compact).
+    const n = Math.max(...valid.map((c) => c.col.length));
+    const out: string[] = [];
+    for (let line = 0; line < n; line++) {
+        const cells = valid.map((c) => {
+            const t = line < c.col.length ? c.col[line] : "";
+            return pad ? padRight(t, blockWidth) : t;
+        });
+        out.push(cells.join(painter.sep));
+    }
+    return out;
+}
+// ── token consumption waveform (Braille, design Decision 5) ─────────
+
+/** Fixed waveform width in Braille columns (2 px each → 40 px). */
+export const WAVEFORM_COLS = 20;
+
+/** Clamp consumption (0..1) to an 8-pixel column height, rounded. */
+export function braillePixelHeight(consumption: number): number {
+    const clamped = Math.max(0, Math.min(1, consumption));
+    return Math.round(clamped * 8);
+}
+
+/** Single-column dot bitmask for `rows` pixels lit from the bottom (0..4). */
+const LEFT_DOTS = [0x00, 0x40, 0x44, 0x46, 0x47];
+const RIGHT_DOTS = [0x00, 0x80, 0xA0, 0xB0, 0xB8];
+
+export function sideDots(rows: number, side: "left" | "right"): number {
+    const r = Math.max(0, Math.min(4, rows));
+    return side === "left" ? LEFT_DOTS[r] : RIGHT_DOTS[r];
+}
+
+/** Compose a Braille cell (U+2800 | left | right) from two column heights. */
+export function composeChar(leftRows: number, rightRows: number): string {
+    const code = 0x2800 | sideDots(leftRows, "left") | sideDots(rightRows, "right");
+    return String.fromCharCode(code);
+}
+
+/** Named-color band for a stock consumption level (`1 - remaining`): remaining ≥ 50% → success, ≥ 20% → warning, else error. */
+export function consumptionColor(c: number): PainterColor {
+    if (c <= 0.5) return "success";
+    if (c <= 0.8) return "warning";
+    return "error";
+}
+
+/** One provider's consumption track feeding its embedded mini chart. */
+export interface ConsumptionTrack {
+    /** Per-interval consumption increments (raw values), newest last. */
+    samples: readonly number[];
+}
+
+/**
+ * Render the consumption waveform as a fixed 2-line Braille strip.
+ *
+ * Samples are per-second consumption INCREMENTS, one per second, aligned
+ * 1px-per-sample (right-aligned — newest hugs the right edge, older scroll
+ * left). The strip is drawn as a smooth polyline — every pixel's height is a
+ * PIECEWISE-LINEAR interpolation of the (right-aligned) sample points,
+ * endpoints held — so sparse zero increments connect into a continuous
+ * envelope instead of isolated full bars with gaps. Dynamic scale maps the
+ * window's largest increment to the full 8-pixel bar; once the window is
+ * FULL (≥8 samples), a 3-point weighted moving average smooths single-second
+ * zero gaps into the envelope so quiet seconds don't punch blank columns.
+ * The strip ALWAYS renders `cols` wide: an empty buffer or an all-zero
+ * window yields a blank placeholder strip, never `undefined`, so every
+ * provider column keeps a stable chart area and the layout never jumps.
+ *
+ * Color is bound to RATE INTENSITY (image-scaling blend, not quota severity —
+ * quota urgency already reads in the usage text, e.g. "5h 0%", balance). Each
+ * Braille character takes the MEAN of its two half-column interpolated
+ * intensities, mapped via consumptionColor (low→green, mid→yellow, high→red),
+ * so consecutive chars blend smoothly and never hard-switch. The newest column
+ * keeps accent.
+ *
+ * Geometry unchanged: 1px per sample (half-char step), right-aligned; each
+ * character merges its two half-column samples with max and renders both
+ * columns at that height; bottom 4 pixels on line 2, top 4 on line 1, width
+ * cols.
+ */
+export function renderConsumptionLines(
+    samples: readonly number[],
+    painter: Painter = ansiPainter,
+    cols: number = WAVEFORM_COLS,
+): string[] {
+    const n = samples.length;
+    const totalPx = cols * 2;
+    const win = n > totalPx ? samples.slice(n - totalPx) : samples;
+    const m = win.length;
+    const winMax = Math.max(...(m > 0 ? win : [0]));
+    // Blank placeholder strip: no data (or nothing but zeros) still occupies
+    // the chart area, so the per-provider column height stays constant.
+    if (!(winMax > 0)) {
+        const blank = composeChar(0, 0).repeat(cols);
+        return [blank, blank];
+    }
+    // Curve smoothing (window FULL only): a 3-point weighted moving average
+    // (1-2-1) softens single-second zero gaps and spikes into a continuous
+    // envelope, so seconds with no consumption no longer punch blank columns
+    // through the line. Skipped while the window is still filling or too
+    // short (≥8 samples) — the live right edge keeps its exact per-second
+    // shape during warm-up.
+    const plot = m >= totalPx && m >= 8
+        ? (() => {
+            const s = new Array<number>(m);
+            s[0] = (win[0] + win[1]) / 2;
+            for (let i = 1; i < m - 1; i++) s[i] = (win[i - 1] + 2 * win[i] + win[i + 1]) / 4;
+            s[m - 1] = (win[m - 2] + win[m - 1]) / 2;
+            return s;
+        })()
+        : [...win];
+    // Dynamic scale over the SMOOTHED window keeps "largest increment = full
+    // bar" after averaging trims the raw peak.
+    const max = Math.max(...plot);
+    const xOf = (i: number): number => (m === 1 ? totalPx - 1 : totalPx - m + i);
+    const intensityAt = (p: number): number => {
+        if (p < xOf(0)) return 0; // left padding stays empty
+        if (p >= xOf(m - 1)) return plot[m - 1] / max;
+        let prevX = xOf(0);
+        let prevV = plot[0];
+        for (let i = 1; i < m; i++) {
+            const x = xOf(i);
+            if (p <= x) {
+                const span = x - prevX || 1;
+                const frac = (p - prevX) / span;
+                return (prevV * (1 - frac) + plot[i] * frac) / max;
+            }
+            prevX = x;
+            prevV = plot[i];
+        }
+        return plot[m - 1] / max;
+    };
+
+    // Each half-column keeps its OWN interpolated height (two samples share one
+    // char, possibly at different heights — the pair-into-one-char geometry);
+    // only COLOR is blended (terminals can't half-tint a char, so the char
+    // takes the mean intensity of its two half-columns).
+    const accentChar = Math.floor((totalPx - 1) / 2);
+    // Two-line strip: full scale = 8px (2 Braille rows × 4 dot rows). Each
+    // half-column keeps its OWN interpolated height; only COLOR is blended
+    // (terminals can't half-tint a char, so the char takes the mean intensity).
+    const rows = 2;
+    const lines = new Array<string>(rows).fill("");
+    for (let c = 0; c < cols; c++) {
+        const l = intensityAt(2 * c);
+        const r = intensityAt(2 * c + 1);
+        if (l === 0 && r === 0) {
+            const blank = composeChar(0, 0);
+            for (let li = 0; li < rows; li++) lines[li] += blank;
+            continue;
+        }
+        const hL = Math.round(8 * l);
+        const hR = Math.round(8 * r);
+        const color = c === accentChar ? "accent" : consumptionColor((l + r) / 2);
+        // Row 0 = top (px 4..8), row 1 = bottom (px 0..4) of each column.
+        lines[0] += painter.fg(color, composeChar(Math.max(0, hL - 4), Math.max(0, hR - 4)));
+        lines[1] += painter.fg(color, composeChar(Math.min(4, hL), Math.min(4, hR)));
+    }
+    return lines;
+}