@dunkinfrunkin/mdcat 0.1.0

package/README.md

@@ -0,0 +1,141 @@
+# mdcat
+
+**View markdown files beautifully in your terminal.**
+
+[![npm version](https://img.shields.io/npm/v/mdcat.svg)](https://www.npmjs.com/package/mdcat)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+`mdcat` is a terminal pager for Markdown. It renders GitHub-Flavoured Markdown with full colour, syntax-highlighted code blocks, clickable hyperlinks (OSC 8), and a keyboard-driven TUI — all with zero configuration. Pipe a file into it or open one directly; it just works.
+
+---
+
+## What it looks like
+
+- **H1** headings render in a purple Unicode box
+- **H2** headings render in bold blue with an underline bar
+- **H3–H6** headings use green → yellow → cyan → dim
+- **Code blocks** get a bordered box with a language tag and syntax highlighting
+- **Blockquotes** get an amber `▌` bar with dim italic text
+- **Lists** use `●` / `○` / `‣` bullets; task lists use `☑` / `☐`
+- **Tables** render with full Unicode box-drawing borders
+- **Links** are blue and underlined, clickable in iTerm2 / Kitty / WezTerm
+
+The top chrome bar shows the filename and file type. The bottom bar shows key hints and scroll percentage. Press `/` to search — matching lines get a gold `▶` gutter marker.
+
+---
+
+## Install
+
+**Zero-install (recommended for one-off use):**
+
+```sh
+npx mdcat README.md
+```
+
+**Global install via npm:**
+
+```sh
+npm install -g mdcat
+```
+
+**macOS via Homebrew:**
+
+```sh
+brew install frankchan/tap/mdcat
+```
+
+---
+
+## Usage
+
+```sh
+# Open a file
+mdcat README.md
+
+# Pipe from stdin
+cat CHANGELOG.md | mdcat
+
+# Read from curl
+curl -s https://raw.githubusercontent.com/user/repo/main/README.md | mdcat
+
+# Check version
+mdcat --version
+
+# Help
+mdcat --help
+```
+
+---
+
+## Keyboard shortcuts
+
+| Key            | Action                          |
+|----------------|---------------------------------|
+| `q`            | Quit                            |
+| `j` / `k`      | Scroll down / up one line       |
+| `↑` / `↓`      | Scroll up / down one line       |
+| `Space` / `b`  | Page down / page up             |
+| `d` / `u`      | Half-page down / up             |
+| `g` / `G`      | Jump to top / bottom            |
+| `/`            | Enter search mode               |
+| `n` / `N`      | Next / previous search match    |
+| `Esc`          | Cancel search or clear matches  |
+| Mouse wheel    | Scroll up / down three lines    |
+
+---
+
+## Features
+
+- Renders all GitHub-Flavoured Markdown (GFM) elements
+- Syntax-highlighted code blocks via `cli-highlight` / highlight.js
+- One Dark colour palette — easy on the eyes in dark terminals
+- OSC 8 clickable hyperlinks (iTerm2, Kitty, WezTerm, foot, …)
+- Full mouse wheel support
+- Incremental search with `/` — highlights all matches, jumps to each
+- Respects terminal width — long lines and tables are truncated cleanly
+- Works with pipes: `curl … | mdcat`
+- No configuration files, no dependencies to configure
+
+---
+
+## Supported Markdown
+
+| Element          | Rendering                                      |
+|------------------|------------------------------------------------|
+| H1–H6 headings   | Coloured by level; H1 gets a Unicode box       |
+| Paragraphs       | Word-wrapped to terminal width                 |
+| **Bold**         | Bold white                                     |
+| _Italic_         | Italic                                         |
+| ~~Strikethrough~~| Strikethrough + dim                            |
+| `inline code`    | Amber text on dark background                  |
+| Fenced code      | Bordered box + syntax highlighting             |
+| Blockquotes      | Amber `▌` bar with dim italic text             |
+| Unordered lists  | `●` / `○` / `‣` bullets at increasing depth   |
+| Ordered lists    | Cyan numbers                                   |
+| Task lists       | `☑` / `☐` with green / dim colouring          |
+| Tables           | Box-drawing borders; respects column alignment |
+| Links            | Blue underline + OSC 8 clickable               |
+| Images           | `🖼  alt-text` in dim                          |
+| Horizontal rules | Full-width dim `─` line                        |
+| HTML entities    | Decoded (`&`, `<`, `>`, …)           |
+
+---
+
+## Contributing
+
+Contributions are welcome! Please open an issue to discuss a feature or bug before sending a PR. The codebase is small and deliberately dependency-light — keep it that way.
+
+```sh
+git clone https://github.com/frankchan/mdcat
+cd mdcat
+npm install
+npm test
+```
+
+Please make sure `npm test` passes before submitting.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@dunkinfrunkin/mdcat",
+  "version": "0.1.0",
+  "description": "View markdown files beautifully in your terminal",
+  "type": "module",
+  "bin": {
+    "mdcat": "src/cli.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "start": "node src/cli.js",
+    "test": "node --test test/index.js"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "cli-highlight": "^2.1.11",
+    "marked": "^14.0.0",
+    "wrap-ansi": "^10.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "markdown",
+    "cli",
+    "terminal",
+    "viewer",
+    "cat"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dunkinfrunkin/mdcat.git"
+  }
+}

package/src/cli.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import { readFileSync } from "fs";
+import { resolve, basename } from "path";
+import { marked } from "marked";
+import { renderTokens } from "./render.js";
+import { launch } from "./tui.js";
+
+marked.use({ gfm: true });
+
+const args = process.argv.slice(2);
+
+if (args[0] === "--help" || args[0] === "-h") {
+  console.log("Usage: mdcat <file.md>");
+  console.log("       cat file.md | mdcat");
+  console.log("\nKeys: q quit  j/k or ↑↓ scroll  space/b page  d/u half-page  g/G top/bottom");
+  process.exit(0);
+}
+
+if (args[0] === "--version" || args[0] === "-v") {
+  const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+const MAX_COLS = 100; // browser-like reading width cap
+
+function run(title, content) {
+  const cols = Math.min(process.stdout.columns || 80, MAX_COLS);
+  const tokens = marked.lexer(content);
+  const lines = renderTokens(tokens, cols);
+  launch(title, lines);
+}
+
+// Piped input: cat file.md | mdcat
+if (!process.stdin.isTTY && args.length === 0) {
+  let input = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (chunk) => (input += chunk));
+  process.stdin.on("end", () => run("stdin", input));
+} else if (args.length === 0) {
+  console.error("Usage: mdcat <file.md>");
+  process.exit(1);
+} else {
+  const filePath = resolve(args[0]);
+  let content;
+  try {
+    content = readFileSync(filePath, "utf8");
+  } catch (err) {
+    console.error(`mdcat: ${args[0]}: ${err.code === "ENOENT" ? "No such file" : err.message}`);
+    process.exit(1);
+  }
+  run(basename(filePath), content);
+}

package/src/render.js

@@ -0,0 +1,507 @@
+import { Chalk } from "chalk";
+import wrapAnsi from "wrap-ansi";
+import { highlight as cliHighlight } from "cli-highlight";
+
+const chalk = new Chalk({ level: 3 });
+
+// ─── One Dark palette ──────────────────────────────────────────────────────────
+const c = {
+  // Headings
+  h1:       chalk.hex("#c678dd").bold,          // purple
+  h2:       chalk.hex("#61afef").bold,          // blue
+  h3:       chalk.hex("#98c379").bold,          // green
+  h4:       chalk.hex("#e5c07b").bold,          // yellow
+  h5:       chalk.hex("#56b6c2"),               // cyan
+  h6:       chalk.dim,
+  // Inline
+  strong:   chalk.bold.white,
+  em:       chalk.italic,
+  del:      chalk.strikethrough.dim,
+  code:     chalk.hex("#e5c07b").bgHex("#2a2a2a"), // amber on dark bg
+  link:     chalk.hex("#61afef").underline,
+  image:    chalk.dim,
+  // Code block
+  border:   chalk.dim,
+  codeLang: chalk.hex("#e5c07b").dim,
+  // Blockquote
+  bqBar:    chalk.hex("#e5c07b"),
+  bqText:   chalk.dim.italic,
+  // Lists
+  bullet0:  chalk.hex("#61afef"),              // blue ● depth 0
+  bullet1:  chalk.dim,                         // dim ○ depth 1
+  bullet2:  chalk.dim,                         // very dim ‣ depth 2+
+  ordered:  chalk.hex("#56b6c2"),              // cyan number
+  taskDone: chalk.hex("#98c379"),              // green ☑
+  taskTodo: chalk.dim,                         // dim ☐
+  // Table
+  tableBorder: chalk.dim,
+  tableHead:   chalk.hex("#61afef").bold,
+  tableCell:   chalk.reset,
+  // HR
+  hr:       chalk.dim,
+  // Paragraph text
+  fg:       chalk.reset,
+};
+
+const MARGIN = "  "; // 2-space left margin
+
+// ─── Visual width helpers ───────────────────────────────────────────────────────
+
+/** Strip all ANSI SGR sequences and OSC 8 hyperlinks to measure visual width. */
+function vlen(s) {
+  return s
+    .replace(/\x1B\]8;;.*?\x1B\\/gs, "")
+    .replace(/\x1B\[[0-9;]*m/g, "")
+    .length;
+}
+
+/**
+ * ANSI-safe truncation. Walks the string character by character, skipping
+ * escape sequences when counting visual width. Appends reset + ellipsis when
+ * the string is truncated.
+ */
+function vtrunc(s, maxW) {
+  if (vlen(s) <= maxW) return s;
+  let vis = 0;
+  let i = 0;
+  while (i < s.length && vis < maxW) {
+    // OSC 8 hyperlink: ESC ] 8 ; ... ST  (ST = ESC \)
+    if (s[i] === "\x1B" && s[i + 1] === "]") {
+      const end = s.indexOf("\x1B\\", i + 2);
+      if (end !== -1) { i = end + 2; continue; }
+    }
+    // CSI SGR sequence: ESC [ ... m
+    if (s[i] === "\x1B" && s[i + 1] === "[") {
+      const end = s.indexOf("m", i + 2);
+      if (end !== -1) { i = end + 1; continue; }
+    }
+    vis++;
+    i++;
+  }
+  return s.slice(0, i) + "\x1B[0m…";
+}
+
+/** Pad string to visual width n. */
+function vpad(s, n) {
+  return s + " ".repeat(Math.max(0, n - vlen(s)));
+}
+
+// ─── HTML entity decoder ────────────────────────────────────────────────────────
+
+function htmlDecode(s) {
+  return s
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&nbsp;/g, " ");
+}
+
+// ─── Inline renderer ───────────────────────────────────────────────────────────
+
+function inline(tokens) {
+  if (!tokens?.length) return "";
+  return tokens
+    .map((tok) => {
+      switch (tok.type) {
+        case "text":
+          return tok.tokens ? inline(tok.tokens) : htmlDecode(tok.text ?? "");
+        case "strong":
+          return c.strong(inline(tok.tokens));
+        case "em":
+          return c.em(inline(tok.tokens));
+        case "del":
+          return c.del(inline(tok.tokens));
+        case "codespan":
+          return c.code(" " + (tok.text ?? "") + " ");
+        case "link": {
+          const href = tok.href ?? "";
+          // Badge pattern: link whose only child is a single image (e.g. shields.io)
+          // Render as a compact [alt] text tag instead of a broken image icon.
+          if (tok.tokens?.length === 1 && tok.tokens[0].type === "image") {
+            const alt = tok.tokens[0].text || tok.tokens[0].alt || "";
+            if (alt) {
+              const badge = chalk.dim("[") + chalk.hex("#abb2bf")(alt) + chalk.dim("]");
+              return `\x1B]8;;${href}\x1B\\${badge}\x1B]8;;\x1B\\`;
+            }
+          }
+          const label = tok.tokens?.length ? inline(tok.tokens) : href;
+          // OSC 8 clickable hyperlink (iTerm2, Kitty, WezTerm, foot, …)
+          return `\x1B]8;;${href}\x1B\\${c.link(label)}\x1B]8;;\x1B\\`;
+        }
+        case "image":
+          return c.image(`🖼  ${tok.text || tok.alt || "image"}`);
+        case "br":
+          return "\n";
+        case "escape":
+          return tok.text ?? "";
+        case "html":
+          return "";
+        default:
+          return tok.raw ?? "";
+      }
+    })
+    .join("");
+}
+
+// ─── Block renderers ───────────────────────────────────────────────────────────
+
+function heading(tok, w) {
+  const text = inline(tok.tokens);
+  const lines = [""];
+
+  switch (tok.depth) {
+    case 1: {
+      // Purple box with Unicode border
+      const label = text.toUpperCase();
+      const safeLabel = vlen(label) > w - 4 ? vtrunc(label, w - 4) : label;
+      const tlen = vlen(safeLabel);
+      const innerW = tlen + 2; // 1 space padding each side
+      const topBot = "═".repeat(innerW);
+      lines.push(MARGIN + c.h1("╔" + topBot + "╗"));
+      lines.push(MARGIN + c.h1("║") + " " + c.h1(safeLabel) + " " + c.h1("║"));
+      lines.push(MARGIN + c.h1("╚" + topBot + "╝"));
+      break;
+    }
+    case 2: {
+      lines.push(MARGIN + c.h2(text));
+      const barLen = Math.min(vlen(text) + 1, w);
+      lines.push(MARGIN + c.h2("─".repeat(barLen)));
+      break;
+    }
+    case 3:
+      lines.push(MARGIN + c.h3(text));
+      break;
+    case 4:
+      lines.push(MARGIN + c.h4(text));
+      break;
+    case 5:
+      lines.push(MARGIN + c.h5(text));
+      break;
+    case 6:
+      lines.push(MARGIN + c.h6(text));
+      break;
+    default:
+      lines.push(MARGIN + text);
+  }
+
+  lines.push("");
+  return lines;
+}
+
+function paragraph(tok, w) {
+  const text = inline(tok.tokens);
+  const wrapped = wrapAnsi(text, w, { hard: true, trim: false });
+  return [...wrapped.split("\n").map((l) => MARGIN + c.fg(l)), ""];
+}
+
+function code(tok, w) {
+  // First word of lang only, e.g. "js {1}" → "js"
+  const lang = (tok.lang ?? "").split(/\s/)[0].trim();
+  // Expand tabs to 2 spaces
+  const rawText = (tok.text ?? "").replace(/\t/g, "  ");
+
+  // innerW = content width between borders (1 space padding each side)
+  const innerW = w - 2;
+  // borderW = total inner span for the box (includes the 1px padding each side)
+  const borderW = innerW + 2;
+
+  let rawLines;
+  if (rawText === "") {
+    rawLines = [""];
+  } else {
+    rawLines = rawText.split("\n");
+  }
+
+  let highlighted;
+  try {
+    if (lang) {
+      const h = cliHighlight(rawText || " ", {
+        language: lang,
+        ignoreIllegals: true,
+      });
+      highlighted = h.split("\n").map((l) => l + "\x1B[0m");
+      // Trim to match source line count (cli-highlight may add a trailing empty)
+      if (
+        highlighted.length > rawLines.length &&
+        vlen(highlighted[highlighted.length - 1]) === 0
+      ) {
+        highlighted.pop();
+      }
+    } else {
+      highlighted = rawLines;
+    }
+  } catch {
+    highlighted = rawLines;
+  }
+
+  // Pad to same length just in case highlight produced different line count
+  while (highlighted.length < rawLines.length) highlighted.push("");
+
+  const lines = [""];
+
+  // Top border: ┌─ lang ─────┐ or ┌──────────────┐
+  let top;
+  if (lang) {
+    const langTag = " " + c.codeLang(lang) + " ";
+    const langTagLen = 1 + lang.length + 1; // visual chars
+    const fill = Math.max(0, borderW - langTagLen - 1); // -1 for leading "─"
+    top =
+      c.border("┌─") +
+      langTag +
+      c.border("─".repeat(fill)) +
+      c.border("┐");
+  } else {
+    top = c.border("┌" + "─".repeat(borderW) + "┐");
+  }
+  lines.push(MARGIN + top);
+
+  // Content lines
+  for (const hline of highlighted) {
+    const truncated =
+      vlen(hline) > innerW ? vtrunc(hline, innerW) : hline;
+    const pad = Math.max(0, innerW - vlen(truncated));
+    lines.push(
+      MARGIN +
+        c.border("│") +
+        " " +
+        truncated +
+        " ".repeat(pad) +
+        " " +
+        c.border("│")
+    );
+  }
+
+  // Bottom border
+  lines.push(MARGIN + c.border("└" + "─".repeat(borderW) + "┘"));
+  lines.push("");
+  return lines;
+}
+
+function blockquote(tok, w) {
+  // Render inner tokens at reduced width
+  const innerLines = tok.tokens.flatMap((t) => {
+    try {
+      return token(t, w - 4);
+    } catch {
+      return [""];
+    }
+  });
+
+  const prefix = MARGIN + c.bqBar("▌") + " ";
+  const out = [""];
+  for (const l of innerLines) {
+    const stripped = l.replace(/^[ \t]*/, ""); // strip leading indent from inner render
+    out.push(prefix + c.bqText(stripped));
+  }
+  out.push("");
+  return out;
+}
+
+function list(tok, w, depth) {
+  const pad = "  ".repeat(depth);
+  const lines = [];
+
+  tok.items.forEach((item, i) => {
+    // Bullet / number
+    let bullet;
+    if (item.task) {
+      // Task list: handled below after building firstLine
+      bullet = "  "; // placeholder width
+    } else if (tok.ordered) {
+      const num = String((tok.start ?? 1) + i);
+      bullet = c.ordered(num + ".");
+    } else {
+      if (depth === 0) bullet = c.bullet0("●");
+      else if (depth === 1) bullet = c.bullet1("○");
+      else bullet = c.bullet2("‣");
+    }
+
+    let firstLine = "";
+    const extraLines = [];
+
+    for (const t of item.tokens) {
+      if (t.type === "text") {
+        firstLine += inline(t.tokens ?? [{ type: "text", text: t.text ?? "" }]);
+      } else if (t.type === "paragraph") {
+        firstLine += inline(t.tokens);
+      } else if (t.type === "list") {
+        extraLines.push(...list(t, w - 2, depth + 1));
+      } else {
+        try {
+          const inner = token(t, w - 2);
+          // Skip blank separator lines within loose lists
+          inner.forEach((l) => {
+            if (l !== "") extraLines.push(l);
+          });
+        } catch {
+          // skip
+        }
+      }
+    }
+
+    // Task list overlay
+    if (item.task) {
+      const box = item.checked
+        ? c.taskDone("☑")
+        : c.taskTodo("☐");
+      bullet = box;
+    }
+
+    const prefix = MARGIN + pad + bullet + " ";
+    const textIndent = MARGIN + pad + " ".repeat(vlen(bullet) + 1);
+    const wrapW = Math.max(20, w - vlen(MARGIN + pad + " ") - vlen(bullet));
+    const wrapped = wrapAnsi(firstLine, wrapW, { hard: true });
+    const wrappedLines = wrapped.split("\n");
+    lines.push(prefix + wrappedLines[0]);
+    wrappedLines.slice(1).forEach((l) => lines.push(textIndent + l));
+    lines.push(...extraLines);
+  });
+
+  return lines;
+}
+
+function table(tok, w) {
+  const headers = tok.header.map((h) => inline(h.tokens ?? []));
+  const rows = tok.rows.map((row) =>
+    row.map((cell) => inline(cell.tokens ?? []))
+  );
+  const aligns = tok.align ?? [];
+
+  // Natural column widths
+  const colWidths = headers.map((h, i) => {
+    const maxCell = rows.reduce(
+      (m, r) => Math.max(m, vlen(r[i] ?? "")),
+      0
+    );
+    return Math.max(vlen(h), maxCell, 1);
+  });
+
+  // Total table width: borders (cols+1) + 2 padding per col + content
+  const totalW =
+    colWidths.length + 1 + colWidths.reduce((s, cw) => s + cw + 2, 0);
+  const marginLen = vlen(MARGIN);
+
+  // If table overflows, shrink columns proportionally
+  if (totalW + marginLen > w) {
+    const available = w - marginLen - (colWidths.length + 1) - colWidths.length * 2;
+    const naturalTotal = colWidths.reduce((s, cw) => s + cw, 0);
+    if (naturalTotal > 0 && available > 0) {
+      let allocated = 0;
+      const minW = 3; // minimum column width to show "…"
+      for (let i = 0; i < colWidths.length; i++) {
+        const share = Math.max(
+          minW,
+          Math.floor((colWidths[i] / naturalTotal) * available)
+        );
+        colWidths[i] = share;
+        allocated += share;
+      }
+      // Distribute rounding remainder to last column
+      const remainder = available - allocated;
+      if (remainder > 0) colWidths[colWidths.length - 1] += remainder;
+    }
+  }
+
+  const D = c.tableBorder;
+  const top = D("┌" + colWidths.map((cw) => "─".repeat(cw + 2)).join("┬") + "┐");
+  const mid = D("├" + colWidths.map((cw) => "─".repeat(cw + 2)).join("┼") + "┤");
+  const bot = D("└" + colWidths.map((cw) => "─".repeat(cw + 2)).join("┴") + "┘");
+  const sep = D("│");
+
+  function alignCell(cell, cw, align) {
+    const cellLen = vlen(cell);
+    const truncated = cellLen > cw ? vtrunc(cell, cw) : cell;
+    const tlen = vlen(truncated);
+    if (align === "right") {
+      return " ".repeat(Math.max(0, cw - tlen)) + truncated;
+    }
+    if (align === "center") {
+      const total = Math.max(0, cw - tlen);
+      const left = Math.floor(total / 2);
+      const right = total - left;
+      return " ".repeat(left) + truncated + " ".repeat(right);
+    }
+    // left / default
+    return vpad(truncated, cw);
+  }
+
+  const headerRow =
+    sep +
+    headers
+      .map(
+        (h, i) =>
+          " " + c.tableHead(alignCell(h, colWidths[i], aligns[i])) + " " + sep
+      )
+      .join("");
+
+  const dataRows = rows.map(
+    (row) =>
+      sep +
+      row
+        .map(
+          (cell, i) =>
+            " " +
+            c.tableCell(alignCell(cell ?? "", colWidths[i], aligns[i])) +
+            " " +
+            sep
+        )
+        .join("")
+  );
+
+  return [
+    "",
+    ...[top, headerRow, mid, ...dataRows, bot].map((l) => MARGIN + l),
+    "",
+  ];
+}
+
+function hr(w) {
+  return [MARGIN + c.hr("─".repeat(Math.max(1, w))), ""];
+}
+
+// ─── Token dispatcher ──────────────────────────────────────────────────────────
+
+function token(tok, w) {
+  try {
+    switch (tok.type) {
+      case "heading":
+        return heading(tok, w);
+      case "paragraph":
+        return paragraph(tok, w);
+      case "code":
+        return code(tok, w);
+      case "blockquote":
+        return blockquote(tok, w);
+      case "list":
+        return ["", ...list(tok, w, 0), ""];
+      case "table":
+        return table(tok, w);
+      case "hr":
+        return hr(w);
+      case "space":
+      case "html":
+      case "def":
+        return [];
+      default:
+        return [];
+    }
+  } catch {
+    return [""];
+  }
+}
+
+// ─── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Render an array of marked tokens to an array of ANSI-coloured terminal lines.
+ *
+ * @param {import("marked").Token[]} tokens  - Output of `marked.lexer()`
+ * @param {number} cols                      - Terminal width (default 80)
+ * @returns {string[]}
+ */
+export function renderTokens(tokens, cols = 80) {
+  const w = Math.max(20, cols - MARGIN.length * 2);
+  return tokens.flatMap((tok) => token(tok, w));
+}

package/src/tui.js

@@ -0,0 +1,346 @@
+const ESC = "\x1B";
+const ALT_ON    = `${ESC}[?1049h`;
+const ALT_OFF   = `${ESC}[?1049l`;
+const HIDE_CUR  = `${ESC}[?25l`;
+const SHOW_CUR  = `${ESC}[?25h`;
+const MOUSE_ON  = `${ESC}[?1000h${ESC}[?1006h`;
+const MOUSE_OFF = `${ESC}[?1000l${ESC}[?1006l`;
+const HOME      = `${ESC}[H`;
+const ERASE_L   = `${ESC}[2K`;
+const RESET     = `${ESC}[0m`;
+const move      = (r, c) => `${ESC}[${r};${c}H`;
+
+// One Dark-aligned color palette (24-bit ANSI)
+const C = {
+  chromeBg:    `${ESC}[48;2;33;37;43m`,    // #21252b  — top/bottom chrome bg
+  badge:       `${ESC}[38;2;198;120;221m`,  // #c678dd  — purple badge
+  titleFg:     `${ESC}[97m`,                // bright white — filename
+  dimFg:       `${ESC}[38;2;92;99;112m`,   // #5c6370  — dim hints / app name
+  accentFg:    `${ESC}[38;2;97;175;239m`,  // #61afef  — blue search prompt
+  matchFg:     `${ESC}[38;2;229;192;123m`, // #e5c07b  — gold current match
+  greenFg:     `${ESC}[38;2;152;195;121m`, // #98c379  — match count
+  redFg:       `${ESC}[38;2;224;108;117m`, // #e06c75  — no matches
+  otherMatchFg:`${ESC}[38;2;92;99;112m`,   // #5c6370  — other match gutter
+  bold:        `${ESC}[1m`,
+  dim:         `${ESC}[2m`,
+  italic:      `${ESC}[3m`,
+  rev:         `${ESC}[7m`,
+  revOff:      `${ESC}[27m`,
+};
+
+// Strip ANSI from a line to get searchable plain text
+const STRIP_SGR = /\x1B\[[0-9;]*m/g;
+const STRIP_OSC = /\x1B\]8;;.*?\x1B\\/gs;
+function plain(line) {
+  return line.replace(STRIP_OSC, "").replace(STRIP_SGR, "");
+}
+
+// Visual width of a plain string (already stripped)
+function plen(s) { return s.replace(/\x1B\[[0-9;]*m/g, "").length; }
+
+// Highlight all occurrences of `query` within an ANSI-coloured line.
+// Walks the string char-by-char so ANSI escape sequences don't shift offsets.
+const HL_MATCH   = `${ESC}[48;2;62;68;82m${ESC}[38;2;229;192;123m`; // other matches
+const HL_CURRENT = `${ESC}[48;2;229;192;123m${ESC}[38;2;0;0;0m`;    // current match
+const HL_OFF     = `${ESC}[49m${ESC}[39m`;
+
+function highlightInLine(line, query, isCurrent) {
+  if (!query) return line;
+  const p = plain(line).toLowerCase();
+  const q = query.toLowerCase();
+
+  // Collect all [start, end) ranges in plain-text coordinates
+  const ranges = [];
+  let pos = 0;
+  while ((pos = p.indexOf(q, pos)) !== -1) {
+    ranges.push([pos, pos + q.length]);
+    pos++;
+  }
+  if (!ranges.length) return line;
+
+  const ON = isCurrent ? HL_CURRENT : HL_MATCH;
+
+  let out = "";
+  let vis = 0;  // visual position in plain text
+  let ri  = 0;  // current range index
+  let hl  = false;
+  let i   = 0;  // byte index into line
+
+  while (i < line.length) {
+    // Close highlight when we exit the current range
+    if (hl && ri < ranges.length && vis >= ranges[ri][1]) {
+      out += HL_OFF;
+      hl = false;
+      ri++;
+    }
+    // Open highlight when we enter the next range
+    if (!hl && ri < ranges.length && vis >= ranges[ri][0]) {
+      out += ON;
+      hl = true;
+    }
+
+    // OSC 8 hyperlink: ESC ] 8 ; ; url ESC \  — skip, no visual width
+    if (line[i] === "\x1B" && line[i + 1] === "]") {
+      const end = line.indexOf("\x1B\\", i + 2);
+      if (end !== -1) { out += line.slice(i, end + 2); i = end + 2; continue; }
+    }
+    // CSI SGR: ESC [ … m — skip, no visual width
+    if (line[i] === "\x1B" && line[i + 1] === "[") {
+      const end = line.indexOf("m", i + 2);
+      if (end !== -1) { out += line.slice(i, end + 1); i = end + 1; continue; }
+    }
+
+    out += line[i];
+    vis++;
+    i++;
+  }
+
+  if (hl) out += HL_OFF;
+  return out;
+}
+
+export function launch(title, lines) {
+  // Viewport state
+  let offset = 0;
+
+  // Search state
+  let mode        = "normal";   // "normal" | "search" | "matches"
+  let searchQuery = "";
+  let matchLines  = [];         // sorted array of line indices with matches
+  let matchSet    = new Set();  // for O(1) gutter lookup
+  let matchIdx    = 0;
+
+  const rows    = () => process.stdout.rows    || 24;
+  const cols    = () => process.stdout.columns || 80;
+  const visible = () => Math.max(1, rows() - 2); // top bar + bottom bar
+  const maxOff  = () => Math.max(0, lines.length - visible());
+
+  // ─── Search helpers ────────────────────────────────────────────────────────
+
+  function computeMatches() {
+    if (!searchQuery) {
+      matchLines = []; matchSet = new Set(); matchIdx = 0;
+      return;
+    }
+    const q = searchQuery.toLowerCase();
+    matchLines = lines.reduce((acc, line, i) => {
+      if (plain(line).toLowerCase().includes(q)) acc.push(i);
+      return acc;
+    }, []);
+    matchSet = new Set(matchLines);
+    matchIdx = 0;
+    if (matchLines.length > 0) scrollToMatch(0);
+  }
+
+  function scrollToMatch(idx) {
+    matchIdx = ((idx % matchLines.length) + matchLines.length) % matchLines.length;
+    const target = matchLines[matchIdx];
+    if (target !== undefined) {
+      offset = Math.max(0, Math.min(target - Math.floor(visible() / 2), maxOff()));
+    }
+  }
+
+  // ─── Draw ──────────────────────────────────────────────────────────────────
+
+  function draw() {
+    const h = rows();
+    const w = cols();
+    const out = [HOME];
+
+    // Row 1: top chrome bar
+    out.push(move(1, 1) + ERASE_L + topBar(title, w));
+
+    // Rows 2..h-1: content with optional gutter + search highlighting
+    const slice = lines.slice(offset, offset + visible());
+    for (let i = 0; i < visible(); i++) {
+      const absLine = offset + i;
+      const gutter  = gutterFor(absLine);
+      let   content = slice[i] ?? "";
+      if (searchQuery && matchSet.has(absLine)) {
+        content = highlightInLine(content, searchQuery, matchLines[matchIdx] === absLine);
+      }
+      out.push(move(i + 2, 1) + ERASE_L + gutter + content);
+    }
+
+    // Row h: status / search bar
+    out.push(move(h, 1) + ERASE_L + statusBar(w));
+
+    // Show cursor only in search mode (for the text input)
+    out.push(mode === "search" ? SHOW_CUR : HIDE_CUR);
+
+    process.stdout.write(out.join(""));
+  }
+
+  // ─── Chrome helpers ────────────────────────────────────────────────────────
+
+  function topBar(title, w) {
+    const ext   = /\.(md|markdown|mdx)$/i.test(title) ? "md" : "~";
+    const badge = `${C.badge}[${ext}]${RESET}${C.chromeBg}`;
+    const left  = ` ${badge} ${C.bold}${C.titleFg}${title}${RESET}${C.chromeBg}`;
+    const right = `${C.dimFg}mdcat ${RESET}`;
+    const leftW = 1 + ext.length + 2 + 1 + title.length + 1;
+    const rightW = "mdcat ".length;
+    const gap   = Math.max(0, w - leftW - rightW);
+    return `${C.chromeBg}${left}${C.dimFg}${" ".repeat(gap)}${right}${RESET}`;
+  }
+
+  function gutterFor(absLine) {
+    if (mode === "normal" || !searchQuery) return "  ";
+    if (matchLines[matchIdx] === absLine)   return `${C.matchFg}▶${RESET} `;
+    if (matchSet.has(absLine))              return `${C.otherMatchFg}›${RESET} `;
+    return "  ";
+  }
+
+  function statusBar(w) {
+    if (mode === "search") {
+      const prompt  = `${C.accentFg}/${RESET}`;
+      const cursor  = `${C.rev} ${C.revOff}`;
+      const qText   = searchQuery + cursor;
+      const count   = matchLines.length > 0
+        ? `  ${C.greenFg}${matchLines.length} match${matchLines.length !== 1 ? "es" : ""}${RESET}`
+        : searchQuery
+        ? `  ${C.redFg}no matches${RESET}`
+        : "";
+      const hints   = `${C.dim}  Esc cancel  Enter jump${RESET}`;
+      const left    = ` ${prompt} ${qText}${count}`;
+      const leftW   = 3 + searchQuery.length + 1 + plain(count).length;
+      const hintsW  = "  Esc cancel  Enter jump".length;
+      const gap     = Math.max(1, w - leftW - hintsW - 1);
+      return `${C.chromeBg}${left}${" ".repeat(gap)}${hints} ${RESET}`;
+    }
+
+    if (mode === "matches") {
+      const q      = `${C.matchFg}"${searchQuery}"${RESET}`;
+      const pos    = `${C.dimFg}match ${matchIdx + 1} / ${matchLines.length}${RESET}`;
+      const hints  = `${C.dim}  n next  N prev  Esc clear${RESET}`;
+      const left   = `  ${q}  ${pos}`;
+      const leftW  = 2 + searchQuery.length + 2 + 2 + `match ${matchIdx + 1} / ${matchLines.length}`.length;
+      const hintsW = "  n next  N prev  Esc clear".length;
+      const gap    = Math.max(1, w - leftW - hintsW - 1);
+      return `${C.chromeBg}${left}${" ".repeat(gap)}${hints} ${RESET}`;
+    }
+
+    // Normal mode
+    const end   = Math.min(offset + visible(), lines.length);
+    const pct   = lines.length === 0 ? "100%" : Math.round((end / lines.length) * 100) + "%";
+    const hints = `${C.dim} q  /  j k  ↑↓  space  g G${RESET}`;
+    const right = `${C.dimFg} ${pct} ${RESET}`;
+    const hintsW = " q  /  j k  ↑↓  space  g G".length;
+    const rightW = ` ${pct} `.length;
+    const gap    = Math.max(0, w - hintsW - rightW);
+    return `${C.chromeBg}${hints}${" ".repeat(gap)}${right}${RESET}`;
+  }
+
+  // ─── Cleanup ───────────────────────────────────────────────────────────────
+
+  function cleanup() {
+    process.stdout.write(MOUSE_OFF + ALT_OFF + SHOW_CUR + RESET);
+    process.stdin.setRawMode?.(false);
+    process.exit(0);
+  }
+
+  // ─── Input ─────────────────────────────────────────────────────────────────
+
+  process.stdin.on("data", (raw) => {
+    const s = raw.toString();
+
+    // Mouse SGR events: \x1B[<btn;col;rowm
+    // SGR mouse: ESC[<btn;col;rowM (press) or ESC[<btn;col;rowm (release)
+    // Scroll wheel sends press events (M), so match both m and M
+    const mouse = s.match(/\x1B\[<(\d+);\d+;\d+[mM]/);
+    if (mouse) {
+      const btn = parseInt(mouse[1]);
+      if (btn === 64) { offset = Math.max(offset - 3, 0);        draw(); }
+      if (btn === 65) { offset = Math.min(offset + 3, maxOff()); draw(); }
+      return;
+    }
+
+    // Search mode — intercept all keystrokes
+    if (mode === "search") {
+      if (s === "\x1B" || s === "\x03") {
+        mode = "normal"; searchQuery = ""; matchLines = []; matchSet = new Set();
+        draw(); return;
+      }
+      if (s === "\r" || s === "\n") {
+        mode = matchLines.length > 0 ? "matches" : "normal";
+        if (mode === "normal") searchQuery = "";
+        draw(); return;
+      }
+      if (s === "\x7f" || s === "\x08") {
+        searchQuery = searchQuery.slice(0, -1);
+        computeMatches(); draw(); return;
+      }
+      if (s.length === 1 && s >= " ") {
+        searchQuery += s;
+        computeMatches(); draw(); return;
+      }
+      return;
+    }
+
+    // Normal / matches mode
+    let changed = true;
+    switch (s) {
+      case "q":
+      case "\x03":
+        return cleanup();
+
+      case "j": case "\x1B[B":
+        offset = Math.min(offset + 1, maxOff()); break;
+      case "k": case "\x1B[A":
+        offset = Math.max(offset - 1, 0); break;
+
+      case " ": case "f": case "\x1B[6~":
+        offset = Math.min(offset + visible(), maxOff()); break;
+      case "b": case "\x1B[5~":
+        offset = Math.max(offset - visible(), 0); break;
+
+      case "d":
+        offset = Math.min(offset + Math.floor(visible() / 2), maxOff()); break;
+      case "u":
+        offset = Math.max(offset - Math.floor(visible() / 2), 0); break;
+
+      case "g": offset = 0;        break;
+      case "G": offset = maxOff(); break;
+
+      case "/": case "\x06": // Ctrl+F
+        mode = "search"; searchQuery = ""; matchLines = []; matchSet = new Set();
+        draw(); return;
+
+      case "n":
+        if (matchLines.length > 0) { scrollToMatch(matchIdx + 1); } else changed = false;
+        break;
+      case "N":
+        if (matchLines.length > 0) { scrollToMatch(matchIdx - 1); } else changed = false;
+        break;
+
+      case "\x1B": // Esc — clear search from matches mode
+        if (mode === "matches") {
+          mode = "normal"; searchQuery = ""; matchLines = []; matchSet = new Set();
+        } else { changed = false; }
+        break;
+
+      default:
+        changed = false;
+    }
+
+    if (changed) draw();
+  });
+
+  // ─── Boot ──────────────────────────────────────────────────────────────────
+
+  process.stdout.write(ALT_ON + HIDE_CUR + MOUSE_ON);
+  if (process.stdin.setRawMode) {
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+  }
+
+  draw();
+
+  process.stdout.on("resize", () => {
+    offset = Math.min(offset, maxOff());
+    draw();
+  });
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+}