@rol1n/pi-kit 0.0.0-stage → 0.1.0

package/extensions/tui-asr/index.ts

@@ -0,0 +1,181 @@
+/**
+ * tui-asr — Terminal streaming ASR voice dictation extension for Pi.
+ *
+ * Features:
+ *   1. Streaming ASR: Real-time recognition using Aliyun DashScope Paraformer WebSocket.
+ *   2. Visual metering: Animated braille volume level waveform (● ⣀⣄ listening…).
+ *   3. Native Pi auth: Resolves keys from `/login dashscope` (auth.json) or DASHSCOPE_API_KEY.
+ *   4. Model selector: Native Pi-style searchable TUI selector dialog (/asr model).
+ *   5. Input injection: Directly inserts text into active editor or clipboard.
+ *
+ * Keybindings:
+ *   - Alt+M: Start / Stop voice dictation
+ *   - Alt+N: Cancel current dictation
+ *
+ * Commands:
+ *   - /asr: Toggle voice dictation
+ *   - /asr model [name]: Interactive searchable model selector
+ */
+
+import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import { ALL_ASR_MODELS, resolveProviderApiKey, type AsrModelDefinition } from "./providers.ts";
+import { createDictationController } from "./dictation.ts";
+import { SearchableAsrModelSelectorComponent } from "./model-selector.ts";
+
+/** Default startup ASR model ID */
+const DEFAULT_ASR_MODEL = "paraformer-realtime-v2";
+
+/** Default shortcuts */
+const TOGGLE_SHORTCUTS = ["alt+m"];
+const CANCEL_SHORTCUTS = ["alt+n"];
+
+export default function (pi: ExtensionAPI) {
+  let activeModel = DEFAULT_ASR_MODEL;
+
+  // TUI state
+  let tuiHandle: any = null;
+  let removeInputListener: (() => void) | null = null;
+  let lastCtx: ExtensionContext | null = null;
+
+  const dictation = createDictationController(() => activeModel, () => tuiHandle);
+  const { startDictation, stopDictation, cancelDictation, toggleDictation, cleanup } = dictation;
+
+  // Key interception
+  const ensureTuiAttached = (ctx: ExtensionContext) => {
+    lastCtx = ctx;
+    if (ctx.mode === "tui" && !removeInputListener && typeof ctx.ui?.onTerminalInput === "function") {
+      removeInputListener = ctx.ui.onTerminalInput((keyData) => {
+        const matchesAny = (list: string[]) =>
+          list.some((s) => {
+            const raw = s.toLowerCase().trim();
+            if (raw === "alt+m" && (keyData === "\x1bm" || keyData === "µ")) return true;
+            if (raw === "alt+n" && (keyData === "\x1bn" || keyData === "Å")) return true;
+            return false;
+          });
+
+        if (matchesAny(TOGGLE_SHORTCUTS)) {
+          if (dictation.state === "idle") startDictation(ctx);
+          else if (dictation.state === "recording") stopDictation();
+          return true;
+        }
+
+        if (matchesAny(CANCEL_SHORTCUTS)) {
+          if (dictation.state !== "idle") {
+            cancelDictation();
+            return true;
+          }
+        }
+
+        return undefined;
+      });
+    }
+  };
+
+  pi.on("session_start", (_event, ctx) => {
+    ensureTuiAttached(ctx);
+    if (ctx.mode === "tui") {
+      ctx.ui.setWidget("tui-asr-handle", (tui: any) => {
+        tuiHandle = tui;
+        return {
+          render: () => [],
+          invalidate: () => {},
+          dispose: () => {
+            tuiHandle = null;
+          },
+        };
+      });
+    }
+  });
+
+  // Register shortcuts
+  pi.registerShortcut("alt+m", {
+    description: "Toggle voice dictation (tui-asr)",
+    handler: async (ctx) => {
+      ensureTuiAttached(ctx);
+      await toggleDictation(ctx);
+    },
+  });
+
+  pi.registerShortcut("alt+n", {
+    description: "Cancel voice dictation (tui-asr)",
+    handler: async (ctx) => {
+      ensureTuiAttached(ctx);
+      cancelDictation();
+    },
+  });
+
+  // Register command /asr
+  pi.registerCommand("asr", {
+    description: "Voice dictation control and model switching (/asr [model])",
+    getArgumentCompletions: (prefix: string): AutocompleteItem[] | null => {
+      const trimmed = prefix.trimStart();
+      if (!trimmed || "model".startsWith(trimmed)) {
+        return [{ value: "model", label: "model", description: "Select ASR voice model in TUI" }];
+      }
+      return null;
+    },
+    handler: async (args, ctx) => {
+      ensureTuiAttached(ctx);
+      const parts = args.trim().split(/\s+/).filter(Boolean);
+      const sub = parts[0]?.toLowerCase();
+
+      if (sub === "model") {
+        const modelArg = parts[1]?.toLowerCase();
+        if (modelArg) {
+          const matched = ALL_ASR_MODELS.find(
+            (m) =>
+              m.id.toLowerCase() === modelArg ||
+              m.name.toLowerCase() === modelArg ||
+              m.id.toLowerCase().includes(modelArg),
+          );
+          if (matched) {
+            activeModel = matched.id;
+            const isLogged = Boolean(await resolveProviderApiKey(matched.provider, ctx));
+            const extra = isLogged ? "" : ` (No key detected: please run /login ${matched.provider})`;
+            ctx.ui.notify(`ASR model switched to: ${matched.name} (${matched.id})${extra}`, "info");
+            return;
+          }
+        }
+
+        // Open searchable model selector TUI
+        const loginStatusMap = new Map<string, boolean>();
+        for (const item of ALL_ASR_MODELS) {
+          if (!loginStatusMap.has(item.provider)) {
+            const key = await resolveProviderApiKey(item.provider, ctx);
+            loginStatusMap.set(item.provider, Boolean(key));
+          }
+        }
+
+        const selected = await ctx.ui.custom<AsrModelDefinition | undefined>((tui, theme, _kb, done) => {
+          return new SearchableAsrModelSelectorComponent(
+            tui,
+            theme,
+            ALL_ASR_MODELS,
+            activeModel,
+            (model) => done(model),
+            () => done(undefined),
+            (provider) => loginStatusMap.get(provider) ?? false,
+          );
+        });
+
+        if (!selected) return;
+
+        activeModel = selected.id;
+        const isLogged = loginStatusMap.get(selected.provider);
+        const extra = isLogged ? "" : ` (No key detected: please run /login ${selected.provider})`;
+        ctx.ui.notify(`ASR model switched to: ${selected.name} (${selected.id})${extra}`, "info");
+        return;
+      }
+
+      // Default action: toggle dictation
+      await toggleDictation(ctx);
+    },
+  });
+
+  pi.on("session_shutdown", () => {
+    if (dictation.state !== "idle") cleanup();
+    removeInputListener?.();
+    removeInputListener = null;
+  });
+}

package/extensions/tui-asr/input.ts

@@ -0,0 +1,58 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { copyToClipboard } from "./clipboard.ts";
+
+interface EditorLike {
+  getText(): string;
+  setText(text: string): void;
+}
+
+type Target =
+  | { kind: "editor"; editor: EditorLike }
+  | { kind: "typable"; component: { handleInput(data: string): void } };
+
+const asEditorLike = (value: any): EditorLike | null =>
+  value && typeof value.getText === "function" && typeof value.setText === "function" ? value : null;
+
+function resolveTarget(tuiHandle: any): Target | null {
+  const focused = tuiHandle?.focusedComponent;
+  if (!focused) return null;
+  const editor = asEditorLike(focused) ?? asEditorLike(focused.editor);
+  if (editor) return { kind: "editor", editor };
+  if (typeof focused.handleInput === "function") return { kind: "typable", component: focused };
+  return null;
+}
+
+/** Insert a final transcript into the focused input, with editor and clipboard fallbacks. */
+export function insertTranscript(ctx: ExtensionContext, tuiHandle: any, text: string): void {
+  // 1. Fallback: append to main editor if no TUI handle
+  if (!tuiHandle) {
+    const current = ctx.ui.getEditorText() ?? "";
+    const sep = current && !/\s$/.test(current) ? " " : "";
+    ctx.ui.setEditorText(current + sep + text);
+    return;
+  }
+
+  // 2. Insert into focused editor or typable component
+  const target = resolveTarget(tuiHandle);
+  if (target?.kind === "editor") {
+    const current = target.editor.getText() ?? "";
+    const sep = current && !/\s$/.test(current) ? " " : "";
+    target.editor.setText(current + sep + text);
+    tuiHandle.requestRender?.();
+    return;
+  }
+
+  if (target?.kind === "typable") {
+    target.component.handleInput(text);
+    tuiHandle.requestRender?.();
+    return;
+  }
+
+  // 3. Fallback: copy to clipboard if no input focused
+  const copied = copyToClipboard(text);
+  if (copied) {
+    ctx.ui.notify("Dictated text copied to clipboard (no input focused)", "info");
+  } else {
+    ctx.ui.notify(`Dictated: ${text}`, "info");
+  }
+}

package/extensions/tui-asr/model-selector.ts

@@ -0,0 +1,163 @@
+import { Input, fuzzyFilter, getKeybindings } from "@earendil-works/pi-tui";
+import type { AsrModelDefinition } from "./providers.ts";
+
+export class SearchableAsrModelSelectorComponent {
+  private searchInput = new Input();
+  private selectedIndex = 0;
+  private filteredModels: AsrModelDefinition[] = [];
+  private _focused = true;
+  private cachedLines?: string[];
+  private cachedWidth = -1;
+
+  get focused() {
+    return this._focused;
+  }
+  set focused(value: boolean) {
+    this._focused = value;
+    this.searchInput.focused = value;
+  }
+
+  constructor(
+    private tui: any,
+    private theme: any,
+    private models: AsrModelDefinition[],
+    private currentModelId: string,
+    private onSelect: (model: AsrModelDefinition) => void,
+    private onCancel: () => void,
+    private getLoginStatus?: (provider: string) => boolean,
+  ) {
+    this.filteredModels = [...models];
+    const curIdx = models.findIndex((m) => m.id === currentModelId);
+    this.selectedIndex = curIdx >= 0 ? curIdx : 0;
+    this.searchInput.focused = true;
+  }
+
+  private refresh() {
+    this.cachedLines = undefined;
+    this.tui.requestRender?.();
+  }
+
+  filterModels(query: string) {
+    const q = query.trim().toLowerCase();
+    if (q) {
+      this.filteredModels = fuzzyFilter(
+        this.models,
+        q,
+        (m) => `${m.id} ${m.name} ${m.provider} ${m.description}`,
+      );
+    } else {
+      this.filteredModels = [...this.models];
+    }
+    this.selectedIndex = q ? 0 : Math.min(this.selectedIndex, Math.max(0, this.filteredModels.length - 1));
+    this.refresh();
+  }
+
+  render(width: number): string[] {
+    if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
+
+    const lines: string[] = [];
+    const border = this.theme.fg("accent", "─".repeat(Math.max(10, width)));
+
+    lines.push(border);
+    lines.push("");
+
+    // Scope & credentials status line (matching Pi native selector screenshot)
+    const scopeTitle = `${this.theme.fg("muted", "Scope: ")}${this.theme.fg("accent", "all")}${this.theme.fg("muted", " | dashscope")}`;
+    lines.push(`  ${scopeTitle}`);
+
+    if (this.getLoginStatus) {
+      const loggedIn = this.getLoginStatus("dashscope");
+      const authStatus = loggedIn
+        ? this.theme.fg("success", "✓ DashScope credentials: ready (via /login dashscope)")
+        : this.theme.fg("warning", "! DashScope credentials: not logged in (run /login dashscope)");
+      lines.push(`  ${authStatus}`);
+    }
+    lines.push("");
+
+    // Search input line (> █)
+    for (const l of this.searchInput.render(Math.max(1, width - 4))) {
+      lines.push(`  ${l}`);
+    }
+    lines.push("");
+
+    // Model list (<cursor><check><model-id> [<provider>] [badges])
+    if (this.filteredModels.length === 0) {
+      lines.push(`  ${this.theme.fg("warning", "No matching ASR models found")}`);
+    } else {
+      const maxVisible = 6;
+      const total = this.filteredModels.length;
+      const startIndex = Math.max(0, Math.min(this.selectedIndex - Math.floor(maxVisible / 2), total - maxVisible));
+      const endIndex = Math.min(startIndex + maxVisible, total);
+
+      for (let i = startIndex; i < endIndex; i++) {
+        const item = this.filteredModels[i];
+        const isSelected = i === this.selectedIndex;
+        const isCurrent = item.id === this.currentModelId;
+
+        const cursor = isSelected ? this.theme.fg("accent", "→ ") : "  ";
+        const check = isCurrent ? this.theme.fg("accent", "✓ ") : "  ";
+        const modelText = isSelected
+          ? (this.theme.bold ? this.theme.bold(this.theme.fg("accent", item.id)) : this.theme.fg("accent", item.id))
+          : this.theme.fg("text", item.id);
+        const providerBadge = this.theme.fg("muted", `[${item.provider}]`);
+        const currentBadge = isCurrent ? this.theme.fg("muted", " · current") : "";
+
+        lines.push(`  ${cursor}${check}${modelText} ${providerBadge}${currentBadge}`);
+      }
+
+      if (startIndex > 0 || endIndex < total) {
+        lines.push(`  ${this.theme.fg("muted", `(${this.selectedIndex + 1}/${total})`)}`);
+      }
+    }
+    lines.push("");
+
+    // Selected model detail
+    const selected = this.filteredModels[this.selectedIndex];
+    if (selected) {
+      lines.push(`  ${this.theme.fg("muted", "Model Name: ")}${selected.name}`);
+      lines.push(`  ${this.theme.fg("muted", "Description: ")}${selected.description}`);
+    }
+    lines.push("");
+
+    // Keybinding footer hints
+    lines.push(this.theme.fg("dim", "  Enter to select · Escape/Ctrl+C to cancel · ↑↓ to navigate"));
+    lines.push(border);
+
+    this.cachedLines = lines;
+    this.cachedWidth = width;
+    return lines;
+  }
+
+  invalidate() {
+    this.cachedLines = undefined;
+  }
+
+  handleInput(keyData: string) {
+    const kb = getKeybindings();
+    if (kb.matches(keyData, "tui.select.up") || keyData === "k") {
+      if (this.filteredModels.length === 0) return;
+      this.selectedIndex = this.selectedIndex === 0 ? this.filteredModels.length - 1 : this.selectedIndex - 1;
+      this.refresh();
+      return;
+    }
+    if (kb.matches(keyData, "tui.select.down") || keyData === "j") {
+      if (this.filteredModels.length === 0) return;
+      this.selectedIndex = this.selectedIndex === this.filteredModels.length - 1 ? 0 : this.selectedIndex + 1;
+      this.refresh();
+      return;
+    }
+    if (kb.matches(keyData, "tui.select.confirm") || keyData === "\n" || keyData === "\r") {
+      const selected = this.filteredModels[this.selectedIndex];
+      if (selected) {
+        this.onSelect(selected);
+      }
+      return;
+    }
+    if (kb.matches(keyData, "tui.select.cancel") || keyData === "\x1b" || keyData === "\x03") {
+      this.onCancel();
+      return;
+    }
+    this.searchInput.handleInput(keyData);
+    this.filterModels(this.searchInput.getValue());
+  }
+}

package/extensions/tui-asr/providers.ts

@@ -0,0 +1,25 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export { ALL_ASR_MODELS, createAsrProvider, type AsrModelDefinition, type StreamingAsrProvider } from "../custom-providers/asr/index.ts";
+
+export async function resolveProviderApiKey(provider: string, ctx?: ExtensionContext | null): Promise<string> {
+  if (ctx?.modelRegistry) {
+    const candidates = provider === "dashscope" ? ["dashscope", "aliyun"] : [provider];
+    for (const id of candidates) {
+      try {
+        const key = await ctx.modelRegistry.getApiKeyForProvider(id);
+        if (key?.trim()) return key.trim();
+      } catch {}
+      try {
+        const auth = await ctx.modelRegistry.getProviderAuth(id);
+        if (auth?.auth?.apiKey?.trim()) return auth.auth.apiKey.trim();
+      } catch {}
+    }
+  }
+  const envKey = process.env[`${provider.toUpperCase()}_API_KEY`];
+  if (envKey?.trim()) return envKey.trim();
+  if (provider === "dashscope") {
+    return process.env.ALIYUN_API_KEY?.trim() || "";
+  }
+  return "";
+}

package/extensions/tui-asr/status.ts

@@ -0,0 +1,79 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const BRAILLE_FRAMES = ["⠀", "⣀", "⣄", "⣤", "⣦", "⣶", "⣷", "⣿"];
+const METER_CELLS = 4;
+const METER_TICK_MS = 80;
+
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const SPINNER_INTERVAL_MS = 80;
+
+function rmsToBlock(rms: number): string {
+  const norm = Math.min(1, Math.max(0, rms / 8000));
+  const idx = Math.min(BRAILLE_FRAMES.length - 1, Math.floor(norm * BRAILLE_FRAMES.length));
+  return BRAILLE_FRAMES[idx];
+}
+
+/** Own animation timers for one dictation controller. */
+export function createStatusDisplay(getActiveContext: () => ExtensionContext | null) {
+  // Meter animation
+  let meter: number[] = new Array(METER_CELLS).fill(0);
+  let currentLevel = 0;
+  let meterTimer: NodeJS.Timeout | null = null;
+
+  // Spinner animation
+  let spinnerFrame = 0;
+  let spinnerTimer: NodeJS.Timeout | null = null;
+
+  const setStatus = (msg: string | undefined) => {
+    const activeCtx = getActiveContext();
+    if (!activeCtx) return;
+    activeCtx.ui.setStatus("tui-asr", msg);
+  };
+
+  const stopSpinner = () => {
+    if (spinnerTimer) {
+      clearInterval(spinnerTimer);
+      spinnerTimer = null;
+    }
+  };
+
+  const stopMeter = () => {
+    if (meterTimer) {
+      clearInterval(meterTimer);
+      meterTimer = null;
+    }
+  };
+
+  /** Start braille audio level meter animation */
+  const startMeter = () => {
+    stopMeter();
+    meter = new Array(METER_CELLS).fill(0);
+    currentLevel = 0;
+    const render = () => {
+      const dot = getActiveContext()?.ui.theme.fg("error", "●") ?? "●";
+      setStatus(`${dot} ${meter.map(rmsToBlock).join("")} listening…`);
+    };
+    render();
+    meterTimer = setInterval(() => {
+      meter.shift();
+      meter.push(currentLevel);
+      render();
+    }, METER_TICK_MS);
+  };
+
+  /** Start finalizing spinner */
+  const startSpinner = (suffix: string) => {
+    stopSpinner();
+    spinnerFrame = 0;
+    setStatus(`${SPINNER_FRAMES[0]} ${suffix}`);
+    spinnerTimer = setInterval(() => {
+      spinnerFrame = (spinnerFrame + 1) % SPINNER_FRAMES.length;
+      setStatus(`${SPINNER_FRAMES[spinnerFrame]} ${suffix}`);
+    }, SPINNER_INTERVAL_MS);
+  };
+
+  return {
+    setStatus, startMeter, stopMeter, startSpinner, stopSpinner,
+    setLevel(level: number) { currentLevel = level; },
+  };
+}

package/extensions/web-reach/README.md

@@ -0,0 +1,37 @@
+# web-reach
+
+Web search and page extraction tools for Pi. Registers `web_search` through Exa's public MCP endpoint and `web_fetch` for readable Markdown or raw responses.
+
+## Install
+
+```sh
+pi install npm:@rol1n/web-reach
+```
+
+Also included in `@rol1n/pi-kit`. Avoid enabling another extension that registers the same tool names unless overriding them is intentional.
+
+## Use
+
+```json
+{"query":"Pi coding agent package resource filtering"}
+```
+
+```json
+{"url":"https://example.com/docs","mode":"readable"}
+```
+
+The first object is for `web_search`; the second is for `web_fetch`. Fetch mode defaults to `readable` and also accepts `raw`. Extraction includes HTML-to-Markdown, JSON formatting, PDF handling, and a Jina Reader fallback for pages that need it. Returned text is limited to 35,000 characters.
+
+## Configuration
+
+| Environment variable | Default |
+|---|---|
+| `SRP_WEB_SEARCH_TIMEOUT_MS` | 60000 |
+| `SRP_WEB_FETCH_TIMEOUT_MS` | 20000 |
+| `SRP_WEB_FETCH_MAX_BYTES` | 4194304 (4 MiB) |
+
+No separate search API key is configured; availability and rate limits depend on the public Exa and Jina services. PDF extraction optionally imports `unpdf` if it is available. Without that package the implementation falls back to a basic text extraction path, with lower PDF text quality.
+
+## Source layout
+
+`index.ts` registers the tools and re-exports `searchWeb` and `fetchUrl`. `search.ts` handles Exa MCP requests and response parsing; `transport.ts` shares timeout, cancellation, environment, and truncation helpers. `page.ts` coordinates page fetching and extraction, using `rsc.ts` for Next.js data, `html.ts` for semantic Markdown, `pdf.ts` for optional PDF extraction, and `reader.ts` for the Jina Reader fallback.

package/extensions/web-reach/html.ts

@@ -0,0 +1,83 @@
+export function extractTitleFromHtml(html: string): string {
+  const match = html.match(/<title[^>]*>([^<]+)<\/title>/i);
+  return match?.[1]?.trim() ?? "";
+}
+
+export function isLikelyJSRendered(html: string): boolean {
+  const bodyMatch = html.match(/<body[^>]*>([\s\S]*?)<\/body>/i);
+  if (!bodyMatch) return false;
+  const textContent = bodyMatch[1]
+    .replace(/<script[\s\S]*?<\/script>/gi, "")
+    .replace(/<style[\s\S]*?<\/style>/gi, "")
+    .replace(/<[^>]+>/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+  const scriptCount = (html.match(/<script/gi) || []).length;
+  return textContent.length < 300 && scriptCount >= 2;
+}
+
+export function htmlToMarkdown(html: string): string {
+  let s = html.replace(/<(script|style|noscript|svg|canvas|form|nav|footer|header|aside)[\s\S]*?<\/\1>/gi, " ");
+  s = s.replace(/<!--[\s\S]*?-->/g, " ");
+
+  // Headings
+  s = s.replace(/<h1[^>]*>([\s\S]*?)<\/h1>/gi, "\n\n# $1\n\n");
+  s = s.replace(/<h2[^>]*>([\s\S]*?)<\/h2>/gi, "\n\n## $1\n\n");
+  s = s.replace(/<h3[^>]*>([\s\S]*?)<\/h3>/gi, "\n\n### $1\n\n");
+  s = s.replace(/<h4[^>]*>([\s\S]*?)<\/h4>/gi, "\n\n#### $1\n\n");
+  s = s.replace(/<h5[^>]*>([\s\S]*?)<\/h5>/gi, "\n\n##### $1\n\n");
+  s = s.replace(/<h6[^>]*>([\s\S]*?)<\/h6>/gi, "\n\n###### $1\n\n");
+
+  // Code blocks and inline code
+  s = s.replace(/<pre[^>]*><code[^>]*>([\s\S]*?)<\/code><\/pre>/gi, "\n```\n$1\n```\n");
+  s = s.replace(/<pre[^>]*>([\s\S]*?)<\/pre>/gi, "\n```\n$1\n```\n");
+  s = s.replace(/<code[^>]*>([\s\S]*?)<\/code>/gi, " `$1` ");
+
+  // Blockquotes and emphasis
+  s = s.replace(/<blockquote[^>]*>([\s\S]*?)<\/blockquote>/gi, "\n> $1\n");
+  s = s.replace(/<(strong|b)[^>]*>([\s\S]*?)<\/\1>/gi, "**$2**");
+  s = s.replace(/<(em|i)[^>]*>([\s\S]*?)<\/\1>/gi, "*$2*");
+
+  // Links
+  s = s.replace(/<a\s+[^>]*href=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/gi, (_, href, text) => {
+    const t = text.replace(/<[^>]*>/g, "").trim();
+    if (!t) return "";
+    if (href.startsWith("#") || href.startsWith("javascript:")) return t;
+    return `[${t}](${href})`;
+  });
+
+  // Lists
+  s = s.replace(/<li[^>]*>([\s\S]*?)<\/li>/gi, "\n- $1");
+  s = s.replace(/<\/(ul|ol)>/gi, "\n\n");
+
+  // Tables
+  s = s.replace(/<tr[^>]*>([\s\S]*?)<\/tr>/gi, "\n$1 |");
+  s = s.replace(/<t[dh][^>]*>([\s\S]*?)<\/t[dh]>/gi, " | $1");
+  s = s.replace(/<\/(table|thead|tbody)>/gi, "\n\n");
+
+  // Paragraphs and line breaks
+  s = s.replace(/<\/(p|div|section|article)>/gi, "\n\n");
+  s = s.replace(/<br\s*\/?>/gi, "\n");
+
+  // Strip remaining tags
+  s = s.replace(/<[^>]*>/g, " ");
+
+  // HTML entity decoding
+  s = s
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&hellip;/g, "…")
+    .replace(/&mdash;/g, "—")
+    .replace(/&ndash;/g, "–");
+
+  return s
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .filter((line, i, arr) => !(line === "" && arr[i - 1] === ""))
+    .join("\n")
+    .trim();
+}