@guneriu/pi-files 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Uğur Güneri (guneriu)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# @guneriu/pi-files
+
+Shows the files the agent edited this session in a compact widget above the
+input bar, and opens an interactive, gitignore-aware project tree on demand.
+
+## Features
+
+- **Compact widget** above the editor: `+` new / `M` modified, capped rows with
+  `… +N more` overflow so a big change set never swamps the terminal.
+- **Idle hint** when nothing is edited yet (toggle off in settings).
+- **`/pi-files`** — full-screen tree overlay with keyboard navigation;
+  auto-expands to your edited files on open.
+  - **`Enter`** opens the selected file in your OS default app.
+  - **`Space`** opens a scrollable, syntax-highlighted in-TUI peek (Quick Look style).
+  - **Type anything** to filter all project files instantly — no prefix needed.
+- **`/pi-files-settings`** — interactive settings menu to toggle the widget,
+  collapse it for the session, adjust the row cap, set the peek size limit, and more.
+- Respects `.gitignore` via `git ls-files`; falls back to a filesystem walk
+  outside git repos.
+
+## Install
+
+```bash
+pi install npm:@guneriu/pi-files
+# or the whole mono:
+pi install git:github.com/guneriu/pi-extension-mono
+```
+
+## Commands & shortcuts
+
+### Slash commands
+
+| Command | Description |
+|---|---|
+| `/pi-files` | Open the interactive project tree overlay |
+| `/pi-files-settings` | Open the settings menu |
+
+### Inside the project tree (`/pi-files`)
+
+| Key | Action |
+|---|---|
+| `↑` / `↓` | Move selection |
+| `Enter` | **Open file in OS default app** — expands a directory |
+| `Space` | **Peek** — in-TUI syntax-highlighted preview (toggle: same key closes) |
+| `→` | Expand a directory |
+| `←` | Collapse a directory — or jump to its parent if already collapsed |
+| `Esc` | Close the overlay (clears filter first if one is active) |
+| *any printable char* | **Filter** — type to search all project files instantly |
+| `Backspace` | Remove last filter character; empty filter returns to tree view |
+
+### Type-to-filter search
+
+Start typing anywhere in the tree — no prefix key needed. The view switches to
+a flat filtered list of **all** project files (including inside collapsed
+directories) whose path contains your query (case-insensitive).
+
+- The header shows `/ query▌  N results  esc clear` while filtering.
+- Matched portion of each path is highlighted.
+- `↑/↓`, `Enter`, and `Space` (peek) all work on filter results.
+- `Esc` clears the filter and returns to the tree. `Esc` again closes the overlay.
+- `Backspace` removes one character at a time; empties = back to tree.
+- `→` / `←` expand/collapse are inactive while filtering.
+
+### Opening files
+
+- **`Enter`** launches the file with your OS default application (`open` on
+  macOS, `xdg-open` on Linux, `start` on Windows). On a headless/SSH box with
+  no GUI handler you'll get a notification instead.
+- **`Space`** opens a scrollable, syntax-highlighted preview *inside* pi — no
+  need to leave the terminal. Press `Space` again (or `Esc`/`q`) to close.
+  - Scroll with `↑/↓`, page with `PgUp/PgDn`, jump to top/bottom with `g`/`G`.
+  - Markdown files get structural highlighting (headings, code blocks, lists,
+    links) via a built-in pure ANSI renderer — no extra tools required.
+  - Files larger than **Max peek size** (default 512 KB) are refused with a
+    hint to open them externally instead.
+  - Binary files are detected and refused (open them externally).
+
+### Inside the settings menu (`/pi-files-settings`)
+
+| Key | Action |
+|---|---|
+| `↑` / `↓` | Move between items |
+| `Space` or `Enter` | Toggle a boolean setting |
+| `←` / `→` | Decrease / increase a number setting |
+| `Esc` or `q` | Close the menu |
+
+## Settings
+
+Settings can be changed interactively via `/pi-files-settings` or by editing
+`<agent-dir>/extensions/pi-files/settings.json` directly.
+
+| Key | Default | Meaning | Persists? |
+|---|---|---|---|
+| `enabled` | `true` | Master on/off for the widget | ✅ yes |
+| `maxWidgetRows` | `6` | Max file rows shown in the compact widget | ✅ yes |
+| `showIdleHint` | `true` | Show a one-line hint when no files have been edited yet | ✅ yes |
+| `maxPeekBytes` | `524288` | Largest file (bytes) the in-TUI peek will render | ✅ yes |
+
+In the settings menu, **Max widget rows** is adjusted with `←/→` (range 1–20)
+and **Max peek size (KB)** in 64 KB steps (range 64 KB–8 MB).
+
+### Session collapse
+
+The settings menu also offers **Collapse this session** — a temporary hide that
+lasts only until you close pi. Unlike `enabled`, it is never written to disk, so
+the widget always comes back on the next session start without any manual action.
+
+Use it when you want to free up screen space mid-session without permanently
+disabling the feature.

package/extensions/pi-files.ts

@@ -0,0 +1,754 @@
+/**
+ * pi-files (@guneriu/pi-files)
+ *
+ * Compact widget above the input bar listing files the agent edited this
+ * session, plus an on-demand interactive project tree (/pi-files, /files).
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getAgentDir, isToolCallEventType } from "@earendil-works/pi-coding-agent";
+import { matchesKey, Key, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, relative, resolve } from "node:path";
+import {
+  ancestorsOf,
+  applyInlineMarkdown,
+  buildOpenCommand,
+  buildTree,
+  buildWidgetLines,
+  classifyEdit,
+  detectLanguageFromPath,
+  extractEditsFromBranch,
+  filterFiles,
+  flattenVisible,
+  highlightMarkdown,
+  isPreviewable,
+  listProjectFiles,
+  looksBinary,
+  statusGlyph,
+  type EditStatus,
+  type EditedFile,
+} from "../src/core";
+
+// ─── Settings ───────────────────────────────────────────────────────────────
+interface Settings {
+  enabled: boolean;
+  maxWidgetRows: number;
+  showIdleHint: boolean;
+  maxPeekBytes: number;
+}
+const DEFAULTS: Settings = {
+  enabled: true,
+  maxWidgetRows: 6,
+  showIdleHint: true,
+  maxPeekBytes: 524288, // 512 KB
+};
+
+function getSettingsFile(): string {
+  const dir = `${getAgentDir()}/extensions/pi-files`;
+  mkdirSync(dir, { recursive: true });
+  return `${dir}/settings.json`;
+}
+function loadSettings(): Settings {
+  try {
+    return { ...DEFAULTS, ...JSON.parse(readFileSync(getSettingsFile(), "utf-8")) };
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+
+function saveSettings(s: Settings): void {
+  try {
+    writeFileSync(getSettingsFile(), JSON.stringify(s, null, 2), "utf-8");
+  } catch {
+    // non-fatal
+  }
+}
+
+const WIDGET_ID = "pi-files";
+
+export default function (pi: ExtensionAPI) {
+  // absPath -> status, insertion-ordered (oldest first; rendered newest-first).
+  const edited = new Map<string, EditStatus>();
+  // toolCallId -> pre-execution context, committed on success (S1).
+  const pending = new Map<
+    string,
+    { abs: string; kind: "write" | "edit"; existsBefore: boolean }
+  >();
+  // Loaded once per session, not on every tool call (S2).
+  let settings: Settings = loadSettings();
+  // Session-only collapse flag — never written to disk, resets on session_start.
+  let collapsed = false;
+
+  function updateSettings(fn: (s: Settings) => void, ctx: any): void {
+    fn(settings);
+    saveSettings(settings);
+    renderWidget(ctx);
+  }
+
+  function toEditedFiles(cwd: string): EditedFile[] {
+    // Newest-first so the compact widget shows the most recent edits (C1).
+    return [...edited.entries()].reverse().map(([abs, status]) => ({
+      relPath: relative(cwd, abs) || abs,
+      status,
+    }));
+  }
+
+  function renderWidget(ctx: any) {
+    if (ctx.mode !== "tui") return;
+    if (!settings.enabled || collapsed) {
+      ctx.ui.setWidget(WIDGET_ID, undefined);
+      return;
+    }
+    const cwd = ctx.sessionManager.getCwd();
+    const files = toEditedFiles(cwd);
+
+    if (files.length === 0) {
+      if (settings.showIdleHint) {
+        ctx.ui.setWidget(WIDGET_ID, (_tui: any, theme: any) => ({
+          render: () => [theme.fg("dim", "📁 /files — file tree")],
+          invalidate: () => {},
+        }));
+      } else {
+        ctx.ui.setWidget(WIDGET_ID, undefined);
+      }
+      return;
+    }
+
+    const w = buildWidgetLines(files, settings.maxWidgetRows);
+    const shown = files.slice(0, settings.maxWidgetRows);
+    ctx.ui.setWidget(WIDGET_ID, (_tui: any, theme: any) => ({
+      render: () => {
+        const lines: string[] = [];
+        if (w.header) {
+          lines.push(theme.fg("accent", w.header) + theme.fg("dim", "  ·  /files"));
+        }
+        for (const f of shown) {
+          const color = f.status === "new" ? "success" : "warning";
+          lines.push(theme.fg(color, statusGlyph(f.status) + " ") + theme.fg("muted", f.relPath));
+        }
+        if (w.overflow) lines.push(theme.fg("dim", w.overflow));
+        return lines;
+      },
+      invalidate: () => {},
+    }));
+  }
+
+  function rebuildFromHistory(ctx: any) {
+    edited.clear();
+    const branch = ctx.sessionManager.getBranch();
+    for (const e of extractEditsFromBranch(branch)) {
+      const abs = resolve(ctx.sessionManager.getCwd(), e.path);
+      // Reconstruction cannot know the pre-write filesystem state, so we treat
+      // history-derived edits as "modified" (existsBefore = true). Live
+      // tool_call tracking provides accurate new/modified during the session.
+      const status = classifyEdit(e.kind, true, edited.get(abs));
+      edited.set(abs, status);
+    }
+  }
+
+  pi.on("session_start", async (_event, ctx) => {
+    if (ctx.mode !== "tui") return;
+    settings = loadSettings();
+    collapsed = false; // session collapse always resets on fresh session
+    rebuildFromHistory(ctx);
+    renderWidget(ctx);
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    edited.clear();
+    pending.clear();
+    if (ctx?.mode === "tui") ctx.ui.setWidget(WIDGET_ID, undefined); // N1
+  });
+
+  // Capture pre-execution state on tool_call (fires before the tool runs), so
+  // existsSync reflects the pre-write filesystem (new vs modified).
+  pi.on("tool_call", async (event, ctx) => {
+    if (ctx.mode !== "tui") return;
+    let kind: "write" | "edit" | undefined;
+    if (isToolCallEventType("write", event)) kind = "write";
+    else if (isToolCallEventType("edit", event)) kind = "edit";
+    if (!kind) return;
+    const rawPath = (event.input as { path?: string }).path;
+    if (!rawPath) return;
+    const abs = resolve(ctx.sessionManager.getCwd(), rawPath);
+    pending.set(event.toolCallId, { abs, kind, existsBefore: existsSync(abs) });
+  });
+
+  // Commit only on success (S1): a failed write/edit must not appear as edited.
+  pi.on("tool_execution_end", async (event, ctx) => {
+    if (ctx.mode !== "tui") return;
+    const p = pending.get(event.toolCallId);
+    if (!p) return;
+    pending.delete(event.toolCallId);
+    if (event.isError) return;
+    const prev = edited.get(p.abs);   // read BEFORE delete so sticky-new survives
+    edited.delete(p.abs);             // re-insert so the newest edit sorts last
+    edited.set(p.abs, classifyEdit(p.kind, p.existsBefore, prev));
+    renderWidget(ctx);
+  });
+
+  registerTreeCommands(pi, edited, () => settings);
+  registerSettingsCommand(
+    pi,
+    () => settings,
+    (fn, ctx) => updateSettings(fn, ctx),
+    () => collapsed,
+    (v, ctx) => { collapsed = v; renderWidget(ctx); },
+  );
+}
+
+// ─── Settings menu ──────────────────────────────────────────────────────────
+
+function registerSettingsCommand(
+  pi: ExtensionAPI,
+  getSettings: () => Settings,
+  updateSettings: (fn: (s: Settings) => void, ctx: any) => void,
+  getCollapsed: () => boolean,
+  setCollapsed: (v: boolean, ctx: any) => void,
+) {
+  pi.registerCommand("pi-files-settings", {
+    description: "Open pi-files settings menu",
+    handler: async (_args, ctx) => {
+      if (ctx.mode !== "tui") {
+        ctx.ui.notify("/pi-files-settings requires TUI mode", "error");
+        return;
+      }
+
+      let selected = 0;
+
+      type ToggleItem = {
+        kind: "toggle";
+        label: string;
+        hint?: string;
+        get: () => boolean;
+        toggle: () => void;
+      };
+      type NumberItem = {
+        kind: "number";
+        label: string;
+        get: () => number;
+        inc: () => void;
+        dec: () => void;
+        min: number;
+        max: number;
+      };
+      type MenuItem = ToggleItem | NumberItem;
+
+      const items: MenuItem[] = [
+        {
+          kind: "toggle",
+          label: "Widget enabled",
+          hint: "persists across sessions",
+          get: () => getSettings().enabled,
+          toggle: () => updateSettings((s) => { s.enabled = !s.enabled; }, ctx),
+        },
+        {
+          kind: "toggle",
+          label: "Collapse this session",
+          hint: "resets when you restart pi",
+          get: () => getCollapsed(),
+          toggle: () => setCollapsed(!getCollapsed(), ctx),
+        },
+        {
+          kind: "number",
+          label: "Max widget rows",
+          get: () => getSettings().maxWidgetRows,
+          inc: () => updateSettings((s) => { s.maxWidgetRows = Math.min(20, s.maxWidgetRows + 1); }, ctx),
+          dec: () => updateSettings((s) => { s.maxWidgetRows = Math.max(1, s.maxWidgetRows - 1); }, ctx),
+          min: 1,
+          max: 20,
+        },
+        {
+          kind: "toggle",
+          label: "Show idle hint",
+          hint: "persists across sessions",
+          get: () => getSettings().showIdleHint,
+          toggle: () => updateSettings((s) => { s.showIdleHint = !s.showIdleHint; }, ctx),
+        },
+        {
+          kind: "number",
+          label: "Max peek size (KB)",
+          get: () => Math.round(getSettings().maxPeekBytes / 1024),
+          inc: () => updateSettings((s) => {
+            s.maxPeekBytes = Math.min(8192 * 1024, s.maxPeekBytes + 64 * 1024);
+          }, ctx),
+          dec: () => updateSettings((s) => {
+            s.maxPeekBytes = Math.max(64 * 1024, s.maxPeekBytes - 64 * 1024);
+          }, ctx),
+          min: 64,
+          max: 8192,
+        },
+      ];
+
+      await ctx.ui.custom(
+        (tui: any, theme: any, _kb: any, done: (v: null) => void) => {
+          const B = (s: string) => theme.fg("border", s);
+
+          const buildRow = (item: MenuItem, i: number, innerW: number): string => {
+            const isSelected = i === selected;
+            const gutter = isSelected ? theme.fg("accent", "›") : " ";
+
+            let rowContent: string;
+            if (item.kind === "toggle") {
+              const on = item.get();
+              // Dim the "Collapse" option when widget is fully disabled — it's a no-op.
+              const dimmed = item.label === "Collapse this session" && !getSettings().enabled;
+              const box = dimmed
+                ? theme.fg("dim", "[ ]")
+                : on
+                  ? theme.fg("success", "[●]")
+                  : theme.fg("dim", "[ ]");
+              const labelColor = dimmed ? "dim" : isSelected ? "accent" : "muted";
+              const label = theme.fg(labelColor, item.label);
+              const hintStr = item.hint ? theme.fg("dim", `  ${item.hint}`) : "";
+              rowContent = ` ${box} ${label}${hintStr}`;
+            } else {
+              const val = item.get();
+              const atMin = val <= item.min;
+              const atMax = val >= item.max;
+              const labelColor = isSelected ? "accent" : "muted";
+              const left  = atMin ? theme.fg("dim", "‹") : theme.fg("accent", "‹");
+              const right = atMax ? theme.fg("dim", "›") : theme.fg("accent", "›");
+              rowContent = `    ${theme.fg(labelColor, item.label)}: ${left} ${theme.fg("success", String(val))} ${right}`;
+            }
+
+            const full = gutter + rowContent;
+            const cell = truncateToWidth(full, innerW);
+            return B("│") + cell + " ".repeat(Math.max(0, innerW - visibleWidth(cell))) + B("│");
+          };
+
+          const build = (width: number): string[] => {
+            const innerW = width - 2;
+            const H = "─";
+            const lines: string[] = [];
+
+            lines.push(B("╭" + H.repeat(innerW) + "╮"));
+            const title = " ⚙  Agent Files Settings";
+            const hint  = "↑↓ move  spc/↵ toggle  ←→ adjust  esc close ";
+            const gap   = Math.max(1, innerW - visibleWidth(title) - visibleWidth(hint));
+            lines.push(
+              B("│") + theme.fg("accent", title) + " ".repeat(gap) + theme.fg("dim", hint) + B("│"),
+            );
+            lines.push(B("├" + H.repeat(innerW) + "┤"));
+
+            for (let i = 0; i < items.length; i++) {
+              lines.push(buildRow(items[i], i, innerW));
+            }
+
+            lines.push(B("╰" + H.repeat(innerW) + "╯"));
+            return lines;
+          };
+
+          return {
+            render: (w: number) => build(w),
+            invalidate: () => {},
+            handleInput: (data: string) => {
+              if (matchesKey(data, Key.escape) || data === "q") return done(null);
+              if (matchesKey(data, Key.up))   { selected = Math.max(0, selected - 1);              tui.requestRender(); return; }
+              if (matchesKey(data, Key.down)) { selected = Math.min(items.length - 1, selected + 1); tui.requestRender(); return; }
+
+              const item = items[selected];
+              if (!item) return;
+
+              if (item.kind === "toggle" && (data === " " || data === "\r")) {
+                item.toggle();
+                tui.requestRender();
+                return;
+              }
+              if (item.kind === "number") {
+                if (matchesKey(data, Key.right)) { item.inc(); tui.requestRender(); return; }
+                if (matchesKey(data, Key.left))  { item.dec(); tui.requestRender(); return; }
+              }
+            },
+          };
+        },
+        {
+          overlay: true,
+          overlayOptions: { width: "60%", maxWidth: 72, minWidth: 52, maxHeight: "50%", anchor: "center" },
+        },
+      );
+    },
+  });
+}
+
+// ─── Project tree ─────────────────────────────────────────────────────────────
+
+function registerTreeCommands(
+  pi: ExtensionAPI,
+  edited: Map<string, EditStatus>,
+  getSettings: () => Settings,
+) {
+  const openExternally = (ctx: any, absPath: string) => {
+    const { cmd, args } = buildOpenCommand(process.platform, absPath);
+    try {
+      const child = spawn(cmd, args, { detached: true, stdio: "ignore" });
+      child.on("error", () => {
+        ctx.ui.notify(`Could not open ${absPath}`, "error");
+      });
+      child.unref();
+    } catch {
+      ctx.ui.notify(`Could not open ${absPath}`, "error");
+    }
+  };
+
+  const peek = async (ctx: any, absPath: string) => {
+    const max = getSettings().maxPeekBytes;
+    let size = 0;
+    try {
+      size = statSync(absPath).size;
+    } catch {
+      ctx.ui.notify(`Cannot read ${basename(absPath)}`, "error");
+      return;
+    }
+    if (!isPreviewable(size, max)) {
+      const kb = (size / 1024).toFixed(0);
+      ctx.ui.notify(
+        `${basename(absPath)} too large to preview (${kb} KB) — press Enter to open externally`,
+        "warning",
+      );
+      return;
+    }
+
+    let raw: Buffer;
+    try {
+      raw = readFileSync(absPath);
+    } catch {
+      ctx.ui.notify(`Cannot read ${basename(absPath)}`, "error");
+      return;
+    }
+    if (looksBinary(raw.subarray(0, 4096))) {
+      ctx.ui.notify(
+        `${basename(absPath)} looks binary — press Enter to open externally`,
+        "warning",
+      );
+      return;
+    }
+
+    const text = raw.toString("utf-8");
+    const lang = detectLanguageFromPath(absPath);
+    let rendered: string;
+    if (lang === "markdown") {
+      // Built-in pure highlighter — zero deps, 16-color ANSI, works on every OS.
+      rendered = highlightMarkdown(text);
+    } else {
+      try {
+        // S4: force color so cli-highlight (chalk) emits ANSI under pi's managed,
+        // non-TTY stdout. Without this, peek shows uncolored plain text.
+        process.env.FORCE_COLOR ||= "3";
+        // B2: lazy + graceful — if cli-highlight is missing, fall back to plain
+        // text instead of crashing the whole extension at module load.
+        const mod = await import("cli-highlight").catch(() => undefined);
+        rendered = mod?.highlight
+          ? mod.highlight(text, { language: lang, ignoreIllegals: true })
+          : text;
+      } catch {
+        rendered = text; // never crash the peek on a highlight failure
+      }
+    }
+    // Tab-expand so widths are predictable; split into display lines.
+    const allLines = rendered.replace(/\t/g, "  ").split("\n");
+
+    let peekScroll = 0;
+    await ctx.ui.custom(
+      (tui: any, theme: any, _kb: any, done: (v: null) => void) => {
+        const B = (s: string) => theme.fg("border", s);
+        const bodyH = (): number => Math.max(1, Math.floor(tui.terminal.rows * 0.8) - 4);
+
+        const buildPeek = (width: number): string[] => {
+          const innerW = width - 2;
+          const h = bodyH();
+          const maxScroll = Math.max(0, allLines.length - h);
+          if (peekScroll > maxScroll) peekScroll = maxScroll;
+          if (peekScroll < 0) peekScroll = 0;
+          const H = "─";
+          const lines: string[] = [];
+          lines.push(B("╭" + H.repeat(innerW) + "╮"));
+          const title = ` 👁  ${basename(absPath)}`;
+          const pos = `${peekScroll + 1}-${Math.min(peekScroll + h, allLines.length)}/${allLines.length} `;
+          const hint = `↑↓ scroll  g/G ends  spc/esc close  ${pos}`;
+          const gap = Math.max(1, innerW - visibleWidth(title) - visibleWidth(hint));
+          lines.push(B("│") + theme.fg("accent", title) + " ".repeat(gap) +
+            theme.fg("dim", hint) + B("│"));
+          lines.push(B("├" + H.repeat(innerW) + "┤"));
+          const view = allLines.slice(peekScroll, peekScroll + h);
+          const rowsOut = view.length ? view : [theme.fg("dim", " (empty file)")];
+          for (const row of rowsOut) {
+            const cell = truncateToWidth(row, innerW);
+            // S5: append a hard reset so a multi-line highlight token (block
+            // comment, template literal) never bleeds color into the padding
+            // or right border of this or the next row.
+            const padded = cell + "\x1b[0m" + " ".repeat(Math.max(0, innerW - visibleWidth(cell)));
+            lines.push(B("│") + padded + B("│"));
+          }
+          lines.push(B("╰" + H.repeat(innerW) + "╯"));
+          return lines;
+        };
+
+        return {
+          render: (w: number) => buildPeek(w),
+          invalidate: () => {},
+          handleInput: (data: string) => {
+            const h = bodyH();
+            const maxScroll = Math.max(0, allLines.length - h);
+            if (matchesKey(data, Key.escape) || data === "q" || data === " ") return done(null);
+            if (matchesKey(data, Key.up))       { peekScroll = Math.max(0, peekScroll - 1);          tui.requestRender(); return; }
+            if (matchesKey(data, Key.down))     { peekScroll = Math.min(maxScroll, peekScroll + 1);   tui.requestRender(); return; }
+            if (matchesKey(data, Key.pageUp))   { peekScroll = Math.max(0, peekScroll - h);          tui.requestRender(); return; }
+            if (matchesKey(data, Key.pageDown)) { peekScroll = Math.min(maxScroll, peekScroll + h);  tui.requestRender(); return; }
+            if (data === "g") { peekScroll = 0;         tui.requestRender(); return; }
+            if (data === "G") { peekScroll = maxScroll; tui.requestRender(); return; }
+          },
+        };
+      },
+      {
+        overlay: true,
+        overlayOptions: { width: "85%", maxWidth: 120, minWidth: 50, maxHeight: "80%", anchor: "center" },
+      },
+    );
+  };
+
+  const open = async (ctx: any) => {
+    if (ctx.mode !== "tui") {
+      ctx.ui.notify("/pi-files requires TUI mode", "error");
+      return;
+    }
+    const cwd = ctx.sessionManager.getCwd();
+    const allFiles = listProjectFiles(cwd);
+    const root = buildTree(allFiles);
+
+    // Edited files as cwd-relative posix paths for highlight + auto-expand.
+    const toRel = (abs: string) => relative(cwd, abs).split("\\").join("/");
+    const editedStatus = new Map<string, EditStatus>();
+    for (const [abs, status] of edited.entries()) editedStatus.set(toRel(abs), status);
+
+    const expanded = new Set<string>();
+    for (const rel of editedStatus.keys()) {
+      for (const dir of ancestorsOf(rel)) expanded.add(dir);
+    }
+
+    let selected = 0;
+    let scroll = 0;
+    let searchQuery = "";
+    let treeSelected = 0; // tree cursor saved when search starts, restored on clear
+    let treeScroll = 0;
+
+    await ctx.ui.custom(
+      (tui: any, theme: any, _kb: any, done: (v: null) => void) => {
+        const B = (s: string) => theme.fg("border", s);
+
+        // Highlight the matched portion of a path in accent color.
+        const highlightMatch = (path: string, query: string): string => {
+          if (!query) return theme.fg("muted", path);
+          const lo = path.toLowerCase().indexOf(query.toLowerCase());
+          if (lo < 0) return theme.fg("muted", path);
+          return (
+            theme.fg("muted", path.slice(0, lo)) +
+            theme.fg("accent", path.slice(lo, lo + query.length)) +
+            theme.fg("muted", path.slice(lo + query.length))
+          );
+        };
+
+        const visibleBody = (): number => {
+          const max = Math.max(1, Math.floor(tui.terminal.rows * 0.8) - 4);
+          const total = searchQuery
+            ? Math.max(1, filterFiles(allFiles, searchQuery).length)
+            : Math.max(1, flattenVisible(root, expanded).length);
+          return Math.min(max, total);
+        };
+
+        const buildSearchBody = (innerW: number, bodyH: number): string[] => {
+          const results = filterFiles(allFiles, searchQuery);
+          if (selected >= results.length) selected = Math.max(0, results.length - 1);
+          if (selected < 0) selected = 0;
+          if (selected < scroll) scroll = selected;
+          if (selected >= scroll + bodyH) scroll = selected - bodyH + 1;
+          if (scroll < 0) scroll = 0;
+
+          return results.slice(scroll, scroll + bodyH).map((path, i) => {
+            const idx = scroll + i;
+            const isSelected = idx === selected;
+            const status = editedStatus.get(path);
+            const statusPart = status ? statusGlyph(status) + " " : "";
+            const gutter = isSelected ? theme.fg("accent", "›") : " ";
+            const prefix = status
+              ? theme.fg(status === "new" ? "success" : "warning", statusGlyph(status) + " ")
+              : "";
+            const pathStyled = highlightMatch(path, searchQuery);
+            // Use plain-text width for padding calculation
+            const pad = " ".repeat(Math.max(0, innerW - 1 - visibleWidth(` ${statusPart}${path}`)));
+            return gutter + " " + prefix + pathStyled + pad;
+          });
+        };
+
+        const buildBody = (innerW: number, bodyH: number): string[] => {
+          const rows = flattenVisible(root, expanded);
+          if (selected >= rows.length) selected = rows.length - 1;
+          if (selected < 0) selected = 0;
+          if (selected < scroll) scroll = selected;
+          if (selected >= scroll + bodyH) scroll = selected - bodyH + 1;
+          if (scroll < 0) scroll = 0;
+
+          return rows.slice(scroll, scroll + bodyH).map((n, i) => {
+            const idx = scroll + i;
+            const indent = "  ".repeat(n.depth);
+            const caret = n.isDir ? (expanded.has(n.path) ? "▾ " : "▸ ") : "  ";
+            const status = !n.isDir ? editedStatus.get(n.path) : undefined;
+
+            // S4: raw + styled share identical glyph prefixes so widths match.
+            const namePlain = status ? `${statusGlyph(status)} ${n.name}` : n.name;
+            const nameStyled = status
+              ? theme.fg(status === "new" ? "success" : "warning", namePlain)
+              : n.isDir
+                ? theme.fg("accent", n.name)
+                : theme.fg("muted", n.name);
+
+            // S3: reserve a 1-col cursor gutter; row content starts at column 2,
+            // so the selection marker never overwrites the caret/glyph.
+            const gutter = idx === selected ? theme.fg("accent", "›") : " ";
+            const contentPlain = ` ${indent}${caret}${namePlain}`;
+            const contentStyled = ` ${indent}${caret}${nameStyled}`;
+            const pad = " ".repeat(Math.max(0, innerW - 1 - visibleWidth(contentPlain)));
+            return gutter + contentStyled + pad;
+          });
+        };
+
+        const build = (width: number): string[] => {
+          const innerW = width - 2;
+          const bodyH = visibleBody();
+          const H = "─";
+          const lines: string[] = [];
+          lines.push(B("╭" + H.repeat(innerW) + "╮"));
+          const title = " 📁 Project files";
+          if (searchQuery) {
+            const count = filterFiles(allFiles, searchQuery).length;
+            const prompt = theme.fg("success", `/ ${searchQuery}▌`);
+            const info = theme.fg("dim", `  ${count} result${count !== 1 ? "s" : ""}  esc clear `);
+            const promptPlain = `/ ${searchQuery}▌`;
+            const infoPlain = `  ${count} result${count !== 1 ? "s" : ""}  esc clear `;
+            const gap = Math.max(1, innerW - visibleWidth(title) - visibleWidth(promptPlain) - visibleWidth(infoPlain));
+            lines.push(B("│") + theme.fg("accent", title) + " ".repeat(gap) + prompt + info + B("│"));
+          } else {
+            const hint = "↑↓ move  ↵ open  → expand  ← collapse  spc peek  type to filter  esc close ";
+            const gap = Math.max(1, innerW - visibleWidth(title) - visibleWidth(hint));
+            lines.push(B("│") + theme.fg("accent", title) + " ".repeat(gap) +
+              theme.fg("dim", hint) + B("│"));
+          }
+          lines.push(B("├" + H.repeat(innerW) + "┤"));
+          const body = searchQuery ? buildSearchBody(innerW, bodyH) : buildBody(innerW, bodyH);
+          const empty = searchQuery ? " (no matches)" : " (no files)";
+          const rowsOut = body.length ? body : [theme.fg("dim", empty)];
+          for (const row of rowsOut) {
+            const cell = truncateToWidth(row, innerW);
+            lines.push(B("│") + cell + " ".repeat(Math.max(0, innerW - visibleWidth(cell))) + B("│"));
+          }
+          lines.push(B("╰" + H.repeat(innerW) + "╯"));
+          return lines;
+        };
+
+        return {
+          render: (w: number) => build(w),
+          invalidate: () => {},
+          handleInput: (data: string) => {
+            // Esc: clear filter and restore tree cursor, or close when already clear
+            if (matchesKey(data, Key.escape)) {
+              if (searchQuery) { searchQuery = ""; selected = treeSelected; scroll = treeScroll; tui.requestRender(); }
+              else done(null);
+              return;
+            }
+
+            // Backspace: remove last filter char; restore tree cursor when emptied
+            if (data === "\x7f" || data === "\b") {
+              if (searchQuery.length > 0) {
+                searchQuery = searchQuery.slice(0, -1);
+                if (searchQuery.length === 0) { selected = treeSelected; scroll = treeScroll; }
+                else { selected = 0; scroll = 0; }
+                tui.requestRender();
+              }
+              return;
+            }
+
+            // Space: peek selected file (Quick Look — works in both modes)
+            if (data === " ") {
+              if (searchQuery) {
+                const path = filterFiles(allFiles, searchQuery)[selected];
+                if (path) void peek(ctx, resolve(cwd, path));
+              } else {
+                const rows = flattenVisible(root, expanded);
+                const node = rows[selected];
+                if (node && !node.isDir) void peek(ctx, resolve(cwd, node.path));
+                else if (node?.isDir) ctx.ui.notify("Space peeks files — press Enter or → to expand directories", "warning");
+              }
+              return;
+            }
+
+            // Up / Down: navigate
+            if (matchesKey(data, Key.up)) {
+              selected = Math.max(0, selected - 1); tui.requestRender(); return;
+            }
+            // Down: also uses pre-computed results if available to avoid extra call
+            if (matchesKey(data, Key.down)) {
+              const count = searchQuery
+                ? filterFiles(allFiles, searchQuery).length
+                : flattenVisible(root, expanded).length;
+              selected = Math.min(Math.max(0, count - 1), selected + 1);
+              tui.requestRender(); return;
+            }
+
+            // Enter: open selected
+            if (data === "\r") {
+              if (searchQuery) {
+                const path = filterFiles(allFiles, searchQuery)[selected];
+                if (path) openExternally(ctx, resolve(cwd, path));
+              } else {
+                const rows = flattenVisible(root, expanded);
+                const node = rows[selected];
+                if (!node) return;
+                if (node.isDir) { expanded.add(node.path); tui.requestRender(); }
+                else openExternally(ctx, resolve(cwd, node.path));
+              }
+              return;
+            }
+
+            // Tree-only keys: expand / collapse dirs (inactive while filtering)
+            if (!searchQuery) {
+              const rows = flattenVisible(root, expanded);
+              const node = rows[selected];
+              if (!node) return;
+              if (matchesKey(data, Key.right)) {
+                if (node.isDir) { expanded.add(node.path); tui.requestRender(); }
+                return;
+              }
+              if (matchesKey(data, Key.left)) {
+                if (node.isDir && expanded.has(node.path)) {
+                  expanded.delete(node.path);
+                } else {
+                  const parents = ancestorsOf(node.path);
+                  const parent = parents[parents.length - 1];
+                  if (parent) {
+                    const pIdx = flattenVisible(root, expanded).findIndex((n) => n.path === parent);
+                    if (pIdx >= 0) selected = pIdx;
+                  }
+                }
+                tui.requestRender(); return;
+              }
+            }
+
+            // Any printable char (excl. space): append to filter.
+            // Save tree cursor on first character so Esc/backspace can restore it.
+            if (data.length === 1 && data >= "!") {
+              if (!searchQuery) { treeSelected = selected; treeScroll = scroll; }
+              searchQuery += data; selected = 0; scroll = 0; tui.requestRender();
+            }
+          },
+        };
+      },
+      {
+        overlay: true,
+        overlayOptions: { width: "80%", maxWidth: 100, minWidth: 50, maxHeight: "80%", anchor: "center" },
+      },
+    );
+  };
+
+  pi.registerCommand("pi-files", { description: "Browse the project file tree (agent edits highlighted)", handler: (_a, ctx) => open(ctx) });
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@guneriu/pi-files",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Shows agent-edited files in a compact widget above the input bar, plus an on-demand interactive project tree (gitignore-aware)",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "files",
+    "tree",
+    "explorer",
+    "session"
+  ],
+  "author": "Uğur Güneri (guneriu)",
+  "license": "MIT",
+  "files": [
+    "extensions/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/guneriu/pi-extension-mono",
+    "directory": "packages/pi-files"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ],
+    "image": "https://raw.githubusercontent.com/guneriu/pi-extension-mono/main/assets/pi-files-preview.png"
+  },
+  "dependencies": {
+    "cli-highlight": "^2.1.11"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  }
+}

package/src/core.ts

@@ -0,0 +1,373 @@
+export type EditStatus = "new" | "modified";
+export type EditKind = "write" | "edit";
+
+/**
+ * Decide the status glyph for a write/edit.
+ * - "new" is sticky once set (the agent created the file this session).
+ * - write to a path that does not currently exist => "new".
+ * - everything else => "modified".
+ */
+export function classifyEdit(
+  kind: EditKind,
+  existsBefore: boolean,
+  previous: EditStatus | undefined,
+): EditStatus {
+  if (previous === "new") return "new";
+  if (kind === "write" && !existsBefore) return "new";
+  return "modified";
+}
+
+export interface EditedFile {
+  relPath: string;
+  status: EditStatus;
+}
+
+export interface WidgetLines {
+  header: string | undefined;
+  rows: string[];
+  overflow: string | undefined;
+}
+
+export function statusGlyph(status: EditStatus): string {
+  return status === "new" ? "+" : "M";
+}
+
+/**
+ * Build plain (unstyled) widget content; the extension applies theme colors.
+ * `files` MUST already be in display order (newest edit first) — the extension
+ * is responsible for ordering. We keep the first `maxRows` so the newest edits
+ * are shown and older ones fold into the overflow line.
+ */
+export function buildWidgetLines(files: EditedFile[], maxRows: number): WidgetLines {
+  if (files.length === 0) {
+    return { header: undefined, rows: [], overflow: undefined };
+  }
+  const shown = files.slice(0, maxRows);
+  const rows = shown.map((f) => `${statusGlyph(f.status)} ${f.relPath}`);
+  const hidden = files.length - shown.length;
+  return {
+    header: `Edited files (${files.length})`,
+    rows,
+    overflow: hidden > 0 ? `… +${hidden} more` : undefined,
+  };
+}
+
+export interface TreeNode {
+  name: string;       // basename
+  path: string;       // posix-style relative path from cwd
+  isDir: boolean;
+  depth: number;      // 0 for top-level entries
+  children: TreeNode[];
+}
+
+/** Parse `git ls-files` style newline output into clean relative paths. */
+export function parseGitFileList(out: string): string[] {
+  return out
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0);
+}
+
+/** All ancestor directory paths of a file, root-first. "docs/plans/x" -> ["docs","docs/plans"]. */
+export function ancestorsOf(relPath: string): string[] {
+  const parts = relPath.split("/");
+  const dirs: string[] = [];
+  for (let i = 0; i < parts.length - 1; i++) {
+    dirs.push(parts.slice(0, i + 1).join("/"));
+  }
+  return dirs;
+}
+
+/** Build a synthetic root node whose children are the top-level entries. */
+export function buildTree(relPaths: string[]): TreeNode {
+  const root: TreeNode = { name: "", path: "", isDir: true, depth: -1, children: [] };
+  for (const rel of relPaths) {
+    const parts = rel.split("/");
+    let node = root;
+    for (let i = 0; i < parts.length; i++) {
+      const name = parts[i];
+      const isDir = i < parts.length - 1;
+      const path = parts.slice(0, i + 1).join("/");
+      let child = node.children.find((c) => c.name === name && c.isDir === isDir);
+      if (!child) {
+        child = { name, path, isDir, depth: i, children: [] };
+        node.children.push(child);
+      }
+      node = child;
+    }
+  }
+  sortTree(root);
+  return root;
+}
+
+function sortTree(node: TreeNode): void {
+  node.children.sort((a, b) => {
+    if (a.isDir !== b.isDir) return a.isDir ? -1 : 1; // dirs first
+    return a.name.localeCompare(b.name);
+  });
+  for (const c of node.children) sortTree(c);
+}
+
+/** DFS over the tree, descending into a dir only when its path is in `expanded`. */
+export function flattenVisible(root: TreeNode, expanded: Set<string>): TreeNode[] {
+  const out: TreeNode[] = [];
+  const walk = (n: TreeNode) => {
+    for (const child of n.children) {
+      out.push(child);
+      if (child.isDir && expanded.has(child.path)) walk(child);
+    }
+  };
+  walk(root);
+  return out;
+}
+
+export interface BranchEdit {
+  path: string;
+  kind: EditKind;
+}
+
+/**
+ * Scan a session branch (ctx.sessionManager.getBranch()) for write/edit tool
+ * calls and return their target paths in order. Mirrors the toolCall shape used
+ * across pi sessions: assistant message -> content[] -> { type:"toolCall", name, arguments }.
+ */
+export function extractEditsFromBranch(branch: any[]): BranchEdit[] {
+  const edits: BranchEdit[] = [];
+  for (const entry of branch) {
+    if (entry?.type !== "message") continue;
+    if (entry.message?.role !== "assistant") continue;
+    for (const block of entry.message?.content ?? []) {
+      if (block?.type !== "toolCall") continue;
+      const kind = block.name;
+      if (kind !== "write" && kind !== "edit") continue;
+      const path = block.arguments?.path;
+      if (typeof path !== "string" || path.length === 0) continue;
+      edits.push({ path, kind });
+    }
+  }
+  return edits;
+}
+
+import { readdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+
+const ALWAYS_EXCLUDE = new Set([".git", "node_modules"]);
+
+/** Recursive readdir fallback returning posix-relative paths, excluding noise dirs. */
+export function walkDirRelative(cwd: string): string[] {
+  const out: string[] = [];
+  const walk = (absDir: string, relPrefix: string) => {
+    let entries: import("node:fs").Dirent[];
+    try {
+      entries = readdirSync(absDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.isDirectory() && ALWAYS_EXCLUDE.has(e.name)) continue;
+      const rel = relPrefix ? `${relPrefix}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        walk(`${absDir}/${e.name}`, rel);
+      } else if (e.isFile()) {
+        out.push(rel);
+      }
+    }
+  };
+  walk(cwd, "");
+  return out;
+}
+
+/**
+ * Preferred source: git ls-files (respects .gitignore exactly). Falls back to a
+ * filesystem walk when not a git repo or git is unavailable.
+ *
+ * Note: `git ls-files --cached` can report staged-but-deleted paths, so we drop
+ * entries that no longer exist on disk before building the tree.
+ */
+export function listProjectFiles(cwd: string): string[] {
+  try {
+    const out = execFileSync(
+      "git",
+      ["ls-files", "--cached", "--others", "--exclude-standard"],
+      { cwd, encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] },
+    );
+    const files = parseGitFileList(out).filter((rel) => existsSync(join(cwd, rel)));
+    return files; // trust git result even when empty — avoids surfacing gitignored files via fallback
+  } catch {
+    return walkDirRelative(cwd);
+  }
+}
+
+// ─── Open & Peek helpers ────────────────────────────────────────────────────
+
+export interface OpenCommand {
+  cmd: string;
+  args: string[];
+}
+
+/**
+ * Map a platform + absolute path to a spawnable OS "open with default app"
+ * command. Pure so it can be unit-tested without spawning anything.
+ * - darwin  -> `open <path>`
+ * - win32   -> `cmd /c start "" <path>`  (empty "" is the start window title)
+ * - other   -> `xdg-open <path>`         (linux, *bsd, incl. WSL)
+ */
+export function buildOpenCommand(
+  platform: NodeJS.Platform,
+  absPath: string,
+): OpenCommand {
+  if (platform === "darwin") return { cmd: "open", args: [absPath] };
+  if (platform === "win32") return { cmd: "cmd", args: ["/c", "start", "", absPath] };
+  return { cmd: "xdg-open", args: [absPath] };
+}
+
+/** Minimal extension -> cli-highlight language id map. Undefined => auto-detect. */
+const EXT_LANG: Record<string, string> = {
+  ts: "typescript",
+  tsx: "typescript",
+  js: "javascript",
+  jsx: "javascript",
+  mjs: "javascript",
+  cjs: "javascript",
+  json: "json",
+  md: "markdown",
+  markdown: "markdown",
+  css: "css",
+  scss: "scss",
+  html: "html",
+  xml: "xml",
+  yml: "yaml",
+  yaml: "yaml",
+  sh: "bash",
+  bash: "bash",
+  py: "python",
+  rs: "rust",
+  go: "go",
+  c: "c",
+  h: "c",
+  cpp: "cpp",
+  java: "java",
+  rb: "ruby",
+  toml: "ini",
+  sql: "sql",
+};
+
+/** Language id for cli-highlight from a file path, or undefined to auto-detect. */
+export function detectLanguageFromPath(path: string): string | undefined {
+  const base = path.split("/").pop() ?? path;
+  const dot = base.lastIndexOf(".");
+  if (dot <= 0) return undefined; // no ext, or dotfile like ".env"
+  const ext = base.slice(dot + 1).toLowerCase();
+  return EXT_LANG[ext];
+}
+
+/** Heuristic: a NUL byte in the sampled bytes means "binary". */
+export function looksBinary(buf: Buffer | Uint8Array): boolean {
+  for (let i = 0; i < buf.length; i++) {
+    if (buf[i] === 0) return true;
+  }
+  return false;
+}
+
+/** True when a file of `sizeBytes` is within the peek cap `maxBytes`. */
+export function isPreviewable(sizeBytes: number, maxBytes: number): boolean {
+  return sizeBytes <= maxBytes;
+}
+
+/**
+ * Case-insensitive substring filter over a flat file list.
+ * Empty query returns the full list unchanged.
+ */
+export function filterFiles(files: string[], query: string): string[] {
+  if (!query) return files;
+  const q = query.toLowerCase();
+  return files.filter((f) => f.toLowerCase().includes(q));
+}
+
+// ─── Markdown highlighter ───────────────────────────────────────────────────
+// Pure, zero-dependency, 16-color ANSI — works on macOS, Linux, Windows.
+// Uses only the base 16-color range so there is no truecolor/256-color
+// requirement; every terminal and Windows Terminal supports these codes.
+
+const _R   = "\x1b[0m";  // reset
+const _B   = "\x1b[1m";  // bold
+const _DIM = "\x1b[2m";  // dim
+const _IT  = "\x1b[3m";  // italic
+const _CYN = "\x1b[36m"; // cyan  — headings
+const _YLW = "\x1b[33m"; // yellow — code
+const _GRN = "\x1b[32m"; // green  — list markers
+const _MGT = "\x1b[35m"; // magenta — links
+const _BLU = "\x1b[94m"; // bright blue — blockquotes
+
+/**
+ * Apply inline markdown spans to a single string: inline code, bold, italic,
+ * links. Exported so it can be unit-tested independently.
+ */
+export function applyInlineMarkdown(text: string): string {
+  // Inline code first — everything inside backticks is literal.
+  text = text.replace(/`([^`\n]+)`/g, `${_YLW}\`$1\`${_R}`);
+  // Bold: **text** or __text__ — exclude spans that contain backticks (already code-styled)
+  text = text.replace(/\*\*([^*\n`]+)\*\*/g, `${_B}**$1**${_R}`);
+  text = text.replace(/__([^_\n`]+)__/g, `${_B}__$1__${_R}`);
+  // Italic: *text* or _text_ — lookbehind/lookahead on backtick prevents matching
+  // inside code spans whose replacement output still contains the ` char.
+  text = text.replace(/(?<![*_`])\*([^*\n`]+)\*(?![*`])/g, `${_IT}*$1*${_R}`);
+  text = text.replace(/(?<![_`])_([^_\n`]+)_(?![_`])/g, `${_IT}_$1_${_R}`);
+  // Links / images: [text](url)
+  text = text.replace(/!?\[([^\]]*)\]\(([^)]*)\)/g, `${_MGT}[$1]${_R}${_DIM}($2)${_R}`);
+  return text;
+}
+
+/**
+ * Syntax-highlight a full markdown document for terminal display.
+ * Processes line-by-line with stateful fenced-code-block tracking.
+ * Emits standard 16-color ANSI codes only — compatible with every terminal.
+ */
+export function highlightMarkdown(text: string): string {
+  let inFence = false;
+  return text
+    .split("\n")
+    .map((line) => {
+      // Fenced code block delimiter (``` or ~~~)
+      if (/^(`{3,}|~{3,})/.test(line)) {
+        inFence = !inFence;
+        return `${_DIM}${_YLW}${line}${_R}`;
+      }
+      // Inside a fenced code block — dim yellow, no further processing
+      if (inFence) return `${_YLW}${_DIM}${line}${_R}`;
+
+      // ATX headings: # … ######
+      const hm = line.match(/^(#{1,6})\s(.+)$/);
+      if (hm) {
+        const marks = hm[1];
+        const body  = applyInlineMarkdown(hm[2]);
+        if (marks.length === 1) return `${_B}${_CYN}${marks} ${_R}${_B}${body}${_R}`;
+        if (marks.length === 2) return `${_B}${_CYN}${marks} ${_R}${body}`;
+        return `${_DIM}${_CYN}${marks} ${_R}${body}`;
+      }
+
+      // Blockquote
+      if (/^>/.test(line)) return `${_BLU}${_DIM}${line}${_R}`;
+
+      // Horizontal rule (must come before setext-underline check)
+      if (/^(\*{3,}|-{3,}|_{3,})$/.test(line)) return `${_DIM}${line}${_R}`;
+
+      // Unordered list item: - / * / + (with optional indentation)
+      const ulm = line.match(/^(\s*)([-*+]) (.*)$/);
+      if (ulm) return `${ulm[1]}${_GRN}${ulm[2]}${_R} ${applyInlineMarkdown(ulm[3])}`;
+
+      // Ordered list item: 1. / 12. (with optional indentation)
+      const olm = line.match(/^(\s*)(\d+\.) (.*)$/);
+      if (olm) return `${olm[1]}${_GRN}${olm[2]}${_R} ${applyInlineMarkdown(olm[3])}`;
+
+      // Table separator row |---|---|
+      if (/^\|[-: |]+\|$/.test(line)) return `${_DIM}${line}${_R}`;
+      // Table data row — dim the pipe characters
+      if (/^\|/.test(line)) return line.replace(/\|/g, `${_DIM}|${_R}`);
+
+      // Plain paragraph text — apply inline spans only
+      return applyInlineMarkdown(line);
+    })
+    .join("\n");
+}