@mrclrchtr/supi-lsp 1.13.0 → 1.14.0

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/README.md

@@ -21,6 +21,7 @@ pnpm add @mrclrchtr/supi-core
 ## Package surfaces
 
 - `@mrclrchtr/supi-core/api` — reusable helpers for other packages and extensions
+- `@mrclrchtr/supi-core/report` — shared text/report rendering helpers for TUI and plain-text summaries
 
 ## What you get from the API
 
@@ -71,6 +72,14 @@ The built-in settings UI supports:
 - active-branch session helper: `getActiveBranchEntries()`
 - terminal helpers such as `formatTitle()`, `signalWaiting()`, and `signalDone()`
 
+### Report helpers
+
+- `clampReportWidth()` — enforce a minimum readable report width
+- `formatReportTitle()` / `formatSectionHeader()` — shared themed headers
+- `formatDimLine()` / `formatKeyValueLine()` — common summary rows
+- `formatOverflowHint()` — consistent preview-overflow hints
+- `wrapReportText()` — ANSI-aware wrapped report blocks with optional indentation
+
 ## Example
 
 ```ts
@@ -101,3 +110,4 @@ const message = wrapExtensionContext("my-extension", "hello", {
 - `src/config.ts` — shared config loading and writing
 - `src/config-settings.ts` — config-backed settings registration helper
 - `src/settings-ui.ts` — shared settings overlay
+- `src/report.ts` — shared text/report rendering helpers

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -48,6 +48,7 @@
     "./llm": "./src/llm.ts",
     "./package.json": "./package.json",
     "./path": "./src/path.ts",
+    "./report": "./src/report.ts",
     "./progress-widget": "./src/progress-widget.ts",
     "./project": "./src/project.ts",
     "./session": "./src/session.ts",

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/api.ts

@@ -21,6 +21,8 @@ export * from "./path.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./project.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./report.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./session.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./settings.ts";

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/index.ts

@@ -19,6 +19,8 @@ export * from "./path.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./project.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./report.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./session.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./settings.ts";

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/progress-widget.ts

@@ -8,16 +8,38 @@ import { CancellableLoader, Container, Text } from "@earendil-works/pi-tui";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
+/** What the reviewer is currently doing and on what. */
+export interface CurrentFocus {
+  /** Display label for the active tool (e.g. "Reading", "Searching", "Finding"). */
+  label: string;
+  /** Context detail (e.g. file path, search pattern, directory). */
+  detail: string;
+}
+
 /** Progress state for widget display, compatible with child-session updates. */
 export interface WidgetProgress {
   /** Number of agent turns completed. */
   turns: number;
   /** Number of tool executions started. */
   toolUses: number;
-  /** Human-readable active tool descriptions. */
-  activities: string[];
   /** Token usage stats, if available. */
-  tokens?: { input: number; output: number; total: number };
+  tokens?: {
+    input: number;
+    output: number;
+    total: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+  };
+  /** Per-tool execution counts keyed by short display label (e.g. "diffs", "reads", "greps"). */
+  toolCounts?: Record<string, number>;
+  /** Number of distinct files inspected so far (via read_snapshot_diff / read_snapshot_file). */
+  filesInspected?: number;
+  /** Total files in the review snapshot. */
+  filesTotal?: number;
+  /** Current tool + context for the progress narrative line. */
+  currentFocus?: CurrentFocus;
+  /** Elapsed time in milliseconds since the operation started. */
+  elapsedMs?: number;
 }
 
 // ── Widget ─────────────────────────────────────────────────────────────────
@@ -25,12 +47,12 @@ export interface WidgetProgress {
 /**
  * TUI progress widget for long-running operations.
  *
- * Shows an animated loader, turn count, tool uses, token count, and any active
- * tool descriptions while the child session or operation is running.
+ * Two-line layout: top line shows the narrative (current focus + file progress),
+ * bottom line shows stats (tokens, elapsed time, turns, tool counts).
  */
 export class ProgressWidget extends Container {
   private message: string;
-  private progress: WidgetProgress = { turns: 0, toolUses: 0, activities: [] };
+  private progress: WidgetProgress = { turns: 0, toolUses: 0 };
   private loader: CancellableLoader;
   private tui: { requestRender(): void };
   private theme: Theme;
@@ -79,30 +101,89 @@ export class ProgressWidget extends Container {
 
   private renderContent(): void {
     this.clear();
+    this.renderTopLine();
+    this.renderBottomLine();
+  }
 
-    const stats: string[] = [];
-    if (this.progress.turns > 0) stats.push(`⟳${this.progress.turns}`);
-    if (this.progress.toolUses > 0) stats.push(`${this.progress.toolUses} tool uses`);
-    if (this.progress.tokens) stats.push(`${formatTokens(this.progress.tokens.total)} tokens`);
+  private renderTopLine(): void {
+    const topParts: string[] = [];
 
-    const loaderMessage =
-      stats.length > 0 ? `${this.message} · ${stats.join(" · ")}` : this.message;
+    if (this.progress.currentFocus) {
+      const { label, detail } = this.progress.currentFocus;
+      topParts.push(detail ? `${label}: ${detail}` : label);
+    }
+
+    if (this.progress.filesTotal && this.progress.filesTotal > 0) {
+      const inspected = this.progress.filesInspected ?? 0;
+      topParts.push(`${inspected}/${this.progress.filesTotal} files`);
+    }
 
+    const loaderMessage =
+      topParts.length > 0 ? `${this.message} · ${topParts.join(" · ")}` : this.message;
     this.loader.setMessage(loaderMessage);
     this.addChild(this.loader);
+  }
+
+  private renderBottomLine(): void {
+    const stats: string[] = [];
+
+    this.appendTokenStats(stats);
+
+    if (this.progress.elapsedMs !== undefined && this.progress.elapsedMs >= 1000) {
+      stats.push(formatElapsed(this.progress.elapsedMs));
+    }
 
-    if (this.progress.activities.length > 0) {
-      this.addChild(
-        new Text(this.theme.fg("dim", `  ⎿  ${this.progress.activities.join(", ")}…`), 1, 0),
-      );
+    if (this.progress.turns > 0) {
+      stats.push(`⟳ ${this.progress.turns}`);
     }
+
+    if (this.progress.toolCounts) {
+      const parts = Object.entries(this.progress.toolCounts)
+        .filter(([, count]) => count > 0)
+        .sort(([, a], [, b]) => b - a)
+        .map(([label, count]) => `${count} ${label}`);
+      if (parts.length > 0) stats.push(parts.join(" · "));
+    }
+
+    if (stats.length > 0) {
+      this.addChild(new Text(this.theme.fg("dim", `  ${stats.join(" · ")}`), 1, 0));
+    }
+  }
+
+  private appendTokenStats(stats: string[]): void {
+    const tokens = this.progress.tokens;
+    if (!tokens) return;
+
+    stats.push(`↑ ${formatTokens(tokens.input)}`);
+    if (tokens.cacheRead !== undefined && tokens.cacheRead > 0) {
+      stats.push(`↲ ${formatTokens(tokens.cacheRead)}`);
+    }
+    if (tokens.cacheWrite !== undefined && tokens.cacheWrite > 0) {
+      stats.push(`↱ ${formatTokens(tokens.cacheWrite)}`);
+    }
+    stats.push(`↓ ${formatTokens(tokens.output)}`);
   }
 }
 
 // ── Helpers ────────────────────────────────────────────────────────────────
 
-function formatTokens(count: number): string {
+export function formatTokens(count: number): string {
   if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
   if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
   return String(count);
 }
+
+export function formatElapsed(ms: number): string {
+  const totalSec = Math.floor(ms / 1000);
+  const hours = Math.floor(totalSec / 3600);
+  const minutes = Math.floor((totalSec % 3600) / 60);
+  const seconds = totalSec % 60;
+
+  if (hours > 0) {
+    return `${hours}h ${minutes}m ${seconds}s`;
+  }
+  if (minutes > 0) {
+    return `${minutes}m ${seconds}s`;
+  }
+  return `${seconds}s`;
+}

package/node_modules/@mrclrchtr/supi-code-runtime/node_modules/@mrclrchtr/supi-core/src/report.ts

@@ -0,0 +1,121 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+/** Minimal theme surface required by the shared report helpers. */
+export type ReportTheme = Pick<Theme, "fg">;
+
+/** Color keys accepted by the report helpers. */
+export type ReportColor = Parameters<Theme["fg"]>[0];
+
+/** Options for rendering a themed key/value report row. */
+export interface KeyValueLineOptions {
+  /** The label shown on the left. */
+  label: string;
+  /** The value shown on the right. */
+  value: string;
+  /** Theme used for color formatting. */
+  theme: ReportTheme;
+  /** Maximum rendered width. */
+  width: number;
+  /** Left indentation in spaces. */
+  indent?: number;
+  /** Theme color applied to the label. Defaults to `"text"`. */
+  labelColor?: ReportColor;
+  /** Theme color applied to the value. Defaults to `"dim"`. */
+  valueColor?: ReportColor;
+  /** Separator placed between label and value. Defaults to `": "`. */
+  separator?: string;
+}
+
+/** Options for rendering a preview-overflow hint. */
+export interface OverflowHintOptions {
+  /** Optional follow-up hint such as `run /supi-context full`. */
+  hint?: string | null;
+  /** Left indentation in spaces. Defaults to `2`. */
+  indent?: number;
+}
+
+/** Ensure a report width never drops below the minimum readable width. */
+export function clampReportWidth(width: number, minWidth = 24): number {
+  return Math.max(minWidth, width);
+}
+
+/** Render a top-level report title line with theme color and truncation. */
+export function formatReportTitle(
+  title: string,
+  theme: ReportTheme,
+  width: number,
+  color: ReportColor = "accent",
+): string {
+  return truncateToWidth(theme.fg(color, title), width);
+}
+
+/**
+ * Render a section header with optional dimmed metadata.
+ *
+ * Example: `Usage by category  42.3k tokens`
+ */
+export function formatSectionHeader(
+  title: string,
+  meta: string | null,
+  theme: ReportTheme,
+  width: number,
+): string {
+  const left = theme.fg("text", title);
+  const content = meta ? `${left}${theme.fg("dim", `  ${meta}`)}` : left;
+  return truncateToWidth(content, width);
+}
+
+/** Render a single dimmed report line with optional left indentation. */
+export function formatDimLine(text: string, theme: ReportTheme, width: number, indent = 0): string {
+  const safeIndent = Math.max(0, indent);
+  return truncateToWidth(`${" ".repeat(safeIndent)}${theme.fg("dim", text)}`, width);
+}
+
+/** Render a dimmed preview-overflow hint such as `… and 3 more — run /foo full`. */
+export function formatOverflowHint(
+  hiddenCount: number,
+  theme: ReportTheme,
+  width: number,
+  options: OverflowHintOptions = {},
+): string {
+  const { hint = null, indent = 2 } = options;
+  const suffix = hint ? ` — ${hint}` : "";
+  return formatDimLine(`… and ${hiddenCount} more${suffix}`, theme, width, indent);
+}
+
+/** Render a single themed `label: value` row with truncation. */
+export function formatKeyValueLine(options: KeyValueLineOptions): string {
+  const {
+    label,
+    value,
+    theme,
+    width,
+    indent = 2,
+    labelColor = "text",
+    valueColor = "dim",
+    separator = ": ",
+  } = options;
+  const safeIndent = Math.max(0, indent);
+
+  return truncateToWidth(
+    `${" ".repeat(safeIndent)}${theme.fg(labelColor, label)}${separator}${theme.fg(valueColor, value)}`,
+    width,
+  );
+}
+
+/**
+ * Wrap a report text block to the available width and optionally prefix each line.
+ *
+ * This is useful for wrapped bullets or explanatory notes that should align
+ * under an existing report indent.
+ */
+export function wrapReportText(
+  text: string,
+  width: number,
+  options: { indent?: string } = {},
+): string[] {
+  const indent = options.indent ?? "";
+  const wrapped = wrapTextWithAnsi(text, Math.max(1, width - indent.length));
+  return indent ? wrapped.map((line) => `${indent}${line}`) : wrapped;
+}

package/node_modules/@mrclrchtr/supi-code-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-code-runtime",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "SuPi code-runtime — shared workspace context, capability contracts, and canonical types for the code-understanding stack",
   "license": "MIT",
   "repository": {
@@ -19,7 +19,7 @@
     "!__tests__"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "1.13.0"
+    "@mrclrchtr/supi-core": "1.14.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"

package/node_modules/@mrclrchtr/supi-core/README.md

@@ -21,6 +21,7 @@ pnpm add @mrclrchtr/supi-core
 ## Package surfaces
 
 - `@mrclrchtr/supi-core/api` — reusable helpers for other packages and extensions
+- `@mrclrchtr/supi-core/report` — shared text/report rendering helpers for TUI and plain-text summaries
 
 ## What you get from the API
 
@@ -71,6 +72,14 @@ The built-in settings UI supports:
 - active-branch session helper: `getActiveBranchEntries()`
 - terminal helpers such as `formatTitle()`, `signalWaiting()`, and `signalDone()`
 
+### Report helpers
+
+- `clampReportWidth()` — enforce a minimum readable report width
+- `formatReportTitle()` / `formatSectionHeader()` — shared themed headers
+- `formatDimLine()` / `formatKeyValueLine()` — common summary rows
+- `formatOverflowHint()` — consistent preview-overflow hints
+- `wrapReportText()` — ANSI-aware wrapped report blocks with optional indentation
+
 ## Example
 
 ```ts
@@ -101,3 +110,4 @@ const message = wrapExtensionContext("my-extension", "hello", {
 - `src/config.ts` — shared config loading and writing
 - `src/config-settings.ts` — config-backed settings registration helper
 - `src/settings-ui.ts` — shared settings overlay
+- `src/report.ts` — shared text/report rendering helpers

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -48,6 +48,7 @@
     "./llm": "./src/llm.ts",
     "./package.json": "./package.json",
     "./path": "./src/path.ts",
+    "./report": "./src/report.ts",
     "./progress-widget": "./src/progress-widget.ts",
     "./project": "./src/project.ts",
     "./session": "./src/session.ts",

package/node_modules/@mrclrchtr/supi-core/src/api.ts

@@ -21,6 +21,8 @@ export * from "./path.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./project.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./report.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./session.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./settings.ts";

package/node_modules/@mrclrchtr/supi-core/src/index.ts

@@ -19,6 +19,8 @@ export * from "./path.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./project.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./report.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./session.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./settings.ts";

package/node_modules/@mrclrchtr/supi-core/src/progress-widget.ts

@@ -8,16 +8,38 @@ import { CancellableLoader, Container, Text } from "@earendil-works/pi-tui";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
+/** What the reviewer is currently doing and on what. */
+export interface CurrentFocus {
+  /** Display label for the active tool (e.g. "Reading", "Searching", "Finding"). */
+  label: string;
+  /** Context detail (e.g. file path, search pattern, directory). */
+  detail: string;
+}
+
 /** Progress state for widget display, compatible with child-session updates. */
 export interface WidgetProgress {
   /** Number of agent turns completed. */
   turns: number;
   /** Number of tool executions started. */
   toolUses: number;
-  /** Human-readable active tool descriptions. */
-  activities: string[];
   /** Token usage stats, if available. */
-  tokens?: { input: number; output: number; total: number };
+  tokens?: {
+    input: number;
+    output: number;
+    total: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+  };
+  /** Per-tool execution counts keyed by short display label (e.g. "diffs", "reads", "greps"). */
+  toolCounts?: Record<string, number>;
+  /** Number of distinct files inspected so far (via read_snapshot_diff / read_snapshot_file). */
+  filesInspected?: number;
+  /** Total files in the review snapshot. */
+  filesTotal?: number;
+  /** Current tool + context for the progress narrative line. */
+  currentFocus?: CurrentFocus;
+  /** Elapsed time in milliseconds since the operation started. */
+  elapsedMs?: number;
 }
 
 // ── Widget ─────────────────────────────────────────────────────────────────
@@ -25,12 +47,12 @@ export interface WidgetProgress {
 /**
  * TUI progress widget for long-running operations.
  *
- * Shows an animated loader, turn count, tool uses, token count, and any active
- * tool descriptions while the child session or operation is running.
+ * Two-line layout: top line shows the narrative (current focus + file progress),
+ * bottom line shows stats (tokens, elapsed time, turns, tool counts).
  */
 export class ProgressWidget extends Container {
   private message: string;
-  private progress: WidgetProgress = { turns: 0, toolUses: 0, activities: [] };
+  private progress: WidgetProgress = { turns: 0, toolUses: 0 };
   private loader: CancellableLoader;
   private tui: { requestRender(): void };
   private theme: Theme;
@@ -79,30 +101,89 @@ export class ProgressWidget extends Container {
 
   private renderContent(): void {
     this.clear();
+    this.renderTopLine();
+    this.renderBottomLine();
+  }
 
-    const stats: string[] = [];
-    if (this.progress.turns > 0) stats.push(`⟳${this.progress.turns}`);
-    if (this.progress.toolUses > 0) stats.push(`${this.progress.toolUses} tool uses`);
-    if (this.progress.tokens) stats.push(`${formatTokens(this.progress.tokens.total)} tokens`);
+  private renderTopLine(): void {
+    const topParts: string[] = [];
 
-    const loaderMessage =
-      stats.length > 0 ? `${this.message} · ${stats.join(" · ")}` : this.message;
+    if (this.progress.currentFocus) {
+      const { label, detail } = this.progress.currentFocus;
+      topParts.push(detail ? `${label}: ${detail}` : label);
+    }
+
+    if (this.progress.filesTotal && this.progress.filesTotal > 0) {
+      const inspected = this.progress.filesInspected ?? 0;
+      topParts.push(`${inspected}/${this.progress.filesTotal} files`);
+    }
 
+    const loaderMessage =
+      topParts.length > 0 ? `${this.message} · ${topParts.join(" · ")}` : this.message;
     this.loader.setMessage(loaderMessage);
     this.addChild(this.loader);
+  }
+
+  private renderBottomLine(): void {
+    const stats: string[] = [];
+
+    this.appendTokenStats(stats);
+
+    if (this.progress.elapsedMs !== undefined && this.progress.elapsedMs >= 1000) {
+      stats.push(formatElapsed(this.progress.elapsedMs));
+    }
 
-    if (this.progress.activities.length > 0) {
-      this.addChild(
-        new Text(this.theme.fg("dim", `  ⎿  ${this.progress.activities.join(", ")}…`), 1, 0),
-      );
+    if (this.progress.turns > 0) {
+      stats.push(`⟳ ${this.progress.turns}`);
     }
+
+    if (this.progress.toolCounts) {
+      const parts = Object.entries(this.progress.toolCounts)
+        .filter(([, count]) => count > 0)
+        .sort(([, a], [, b]) => b - a)
+        .map(([label, count]) => `${count} ${label}`);
+      if (parts.length > 0) stats.push(parts.join(" · "));
+    }
+
+    if (stats.length > 0) {
+      this.addChild(new Text(this.theme.fg("dim", `  ${stats.join(" · ")}`), 1, 0));
+    }
+  }
+
+  private appendTokenStats(stats: string[]): void {
+    const tokens = this.progress.tokens;
+    if (!tokens) return;
+
+    stats.push(`↑ ${formatTokens(tokens.input)}`);
+    if (tokens.cacheRead !== undefined && tokens.cacheRead > 0) {
+      stats.push(`↲ ${formatTokens(tokens.cacheRead)}`);
+    }
+    if (tokens.cacheWrite !== undefined && tokens.cacheWrite > 0) {
+      stats.push(`↱ ${formatTokens(tokens.cacheWrite)}`);
+    }
+    stats.push(`↓ ${formatTokens(tokens.output)}`);
   }
 }
 
 // ── Helpers ────────────────────────────────────────────────────────────────
 
-function formatTokens(count: number): string {
+export function formatTokens(count: number): string {
   if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
   if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
   return String(count);
 }
+
+export function formatElapsed(ms: number): string {
+  const totalSec = Math.floor(ms / 1000);
+  const hours = Math.floor(totalSec / 3600);
+  const minutes = Math.floor((totalSec % 3600) / 60);
+  const seconds = totalSec % 60;
+
+  if (hours > 0) {
+    return `${hours}h ${minutes}m ${seconds}s`;
+  }
+  if (minutes > 0) {
+    return `${minutes}m ${seconds}s`;
+  }
+  return `${seconds}s`;
+}

package/node_modules/@mrclrchtr/supi-core/src/report.ts

@@ -0,0 +1,121 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+/** Minimal theme surface required by the shared report helpers. */
+export type ReportTheme = Pick<Theme, "fg">;
+
+/** Color keys accepted by the report helpers. */
+export type ReportColor = Parameters<Theme["fg"]>[0];
+
+/** Options for rendering a themed key/value report row. */
+export interface KeyValueLineOptions {
+  /** The label shown on the left. */
+  label: string;
+  /** The value shown on the right. */
+  value: string;
+  /** Theme used for color formatting. */
+  theme: ReportTheme;
+  /** Maximum rendered width. */
+  width: number;
+  /** Left indentation in spaces. */
+  indent?: number;
+  /** Theme color applied to the label. Defaults to `"text"`. */
+  labelColor?: ReportColor;
+  /** Theme color applied to the value. Defaults to `"dim"`. */
+  valueColor?: ReportColor;
+  /** Separator placed between label and value. Defaults to `": "`. */
+  separator?: string;
+}
+
+/** Options for rendering a preview-overflow hint. */
+export interface OverflowHintOptions {
+  /** Optional follow-up hint such as `run /supi-context full`. */
+  hint?: string | null;
+  /** Left indentation in spaces. Defaults to `2`. */
+  indent?: number;
+}
+
+/** Ensure a report width never drops below the minimum readable width. */
+export function clampReportWidth(width: number, minWidth = 24): number {
+  return Math.max(minWidth, width);
+}
+
+/** Render a top-level report title line with theme color and truncation. */
+export function formatReportTitle(
+  title: string,
+  theme: ReportTheme,
+  width: number,
+  color: ReportColor = "accent",
+): string {
+  return truncateToWidth(theme.fg(color, title), width);
+}
+
+/**
+ * Render a section header with optional dimmed metadata.
+ *
+ * Example: `Usage by category  42.3k tokens`
+ */
+export function formatSectionHeader(
+  title: string,
+  meta: string | null,
+  theme: ReportTheme,
+  width: number,
+): string {
+  const left = theme.fg("text", title);
+  const content = meta ? `${left}${theme.fg("dim", `  ${meta}`)}` : left;
+  return truncateToWidth(content, width);
+}
+
+/** Render a single dimmed report line with optional left indentation. */
+export function formatDimLine(text: string, theme: ReportTheme, width: number, indent = 0): string {
+  const safeIndent = Math.max(0, indent);
+  return truncateToWidth(`${" ".repeat(safeIndent)}${theme.fg("dim", text)}`, width);
+}
+
+/** Render a dimmed preview-overflow hint such as `… and 3 more — run /foo full`. */
+export function formatOverflowHint(
+  hiddenCount: number,
+  theme: ReportTheme,
+  width: number,
+  options: OverflowHintOptions = {},
+): string {
+  const { hint = null, indent = 2 } = options;
+  const suffix = hint ? ` — ${hint}` : "";
+  return formatDimLine(`… and ${hiddenCount} more${suffix}`, theme, width, indent);
+}
+
+/** Render a single themed `label: value` row with truncation. */
+export function formatKeyValueLine(options: KeyValueLineOptions): string {
+  const {
+    label,
+    value,
+    theme,
+    width,
+    indent = 2,
+    labelColor = "text",
+    valueColor = "dim",
+    separator = ": ",
+  } = options;
+  const safeIndent = Math.max(0, indent);
+
+  return truncateToWidth(
+    `${" ".repeat(safeIndent)}${theme.fg(labelColor, label)}${separator}${theme.fg(valueColor, value)}`,
+    width,
+  );
+}
+
+/**
+ * Wrap a report text block to the available width and optionally prefix each line.
+ *
+ * This is useful for wrapped bullets or explanatory notes that should align
+ * under an existing report indent.
+ */
+export function wrapReportText(
+  text: string,
+  width: number,
+  options: { indent?: string } = {},
+): string[] {
+  const indent = options.indent ?? "";
+  const wrapped = wrapTextWithAnsi(text, Math.max(1, width - indent.length));
+  return indent ? wrapped.map((line) => `${indent}${line}`) : wrapped;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-lsp",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "SuPi LSP extension — Language Server Protocol integration for pi",
   "license": "MIT",
   "repository": {
@@ -26,8 +26,8 @@
     "vscode-jsonrpc": "^9.0.0",
     "vscode-languageserver-protocol": "^3.17.5",
     "vscode-languageserver-types": "^3.17.5",
-    "@mrclrchtr/supi-code-runtime": "1.13.0",
-    "@mrclrchtr/supi-core": "1.13.0"
+    "@mrclrchtr/supi-code-runtime": "1.14.0",
+    "@mrclrchtr/supi-core": "1.14.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-code-runtime",