@sean.holung/minicode 0.3.6 → 0.3.7

package/README.md

@@ -1,6 +1,6 @@
 # minicode
 
-> Now supports connecting to [OpenRouter](https://openrouter.ai/) account via minicode UI. Sign in with OpenRouter account. Use for free with compatible free tier OpenRouter hosted models from MiniMax, Nvidia, Qwen, Google, etc.
+> Now supports connecting to [OpenRouter](https://openrouter.ai/) account via minicode UI. Sign in with OpenRouter account. Use for free with compatible [free tier OpenRouter hosted models](https://openrouter.ai/models?q=free) from MiniMax, Nvidia, Qwen, Google, etc.
 
 A graph-native coding agent and code exploration environment built around structural context optimization that leverages symbol-aware retrieval, dependency graphs, and targeted context. It started as a way to make local models viable under tighter context budgets, and it now also works well with hosted frontier models through the same runtime, web UI, and OpenAI-compatible serve mode. 
 
@@ -199,6 +199,7 @@ Nothing is written inside your workspace; config and cache live under `~/.minico
 | `COMMAND_DENYLIST`      | No              | none                       | Optional JSON array or comma-separated regex patterns appended to the built-in destructive-command denylist                         |
 | `MAX_STEPS`             | No              | `50`                       | Max agent loop iterations per user turn                                                                                               |
 | `MAX_TOKENS`            | No              | `4096`                     | Max model output tokens per model call                                                                                                |
+| `MODEL_TIMEOUT_SECONDS` | No              | `60`                       | Timeout waiting for a model API call to start responding before aborting and surfacing an error                                       |
 | `MAX_CONTEXT_TOKENS`    | No              | `32000`                    | Approximate session history trimming target. For small models (e.g. 8k context), set lower (e.g. `6000`) to leave room for responses. |
 | `MAX_TOOL_OUTPUT_CHARS` | No              | `8000`                     | Max chars per tool result before truncation. Set to `0` to disable.                                                                   |
 | `WORKSPACE_ROOT`        | No              | current working directory  | Root directory tools are allowed to access (set at runtime, not typically configured)                                                  |

package/dist/scripts/run-benchmarks.js

@@ -99,6 +99,7 @@ export function buildConfig(options = {}) {
         model,
         maxSteps: getNumberSetting(getShellOverride("MAX_STEPS"), fileConfig.maxSteps, 50),
         maxTokens: getNumberSetting(getShellOverride("MAX_TOKENS"), fileConfig.maxTokens, 4096),
+        modelTimeoutSeconds: getNumberSetting(getShellOverride("MODEL_TIMEOUT_SECONDS"), fileConfig.modelTimeoutSeconds, 60),
         maxContextTokens: getNumberSetting(getShellOverride("MAX_CONTEXT_TOKENS"), fileConfig.maxContextTokens, 32000),
         workspaceRoot: repoRoot,
         commandTimeoutMs: getNumberSetting(getShellOverride("COMMAND_TIMEOUT_MS"), fileConfig.commandTimeoutMs, 30000),

package/dist/src/agent/config.js

@@ -16,6 +16,7 @@ export function formatConfigForDisplay(config) {
         "model: " + config.model,
         "maxSteps: " + config.maxSteps,
         "maxTokens: " + config.maxTokens,
+        "modelTimeoutSeconds: " + config.modelTimeoutSeconds,
         "maxContextTokens: " + config.maxContextTokens,
         "commandTimeoutMs: " + config.commandTimeoutMs,
         "maxFileSizeBytes: " + config.maxFileSizeBytes,
@@ -230,6 +231,7 @@ export async function loadAgentConfig(cwd = process.cwd(), options = {}) {
         model: env.MODEL ?? "",
         maxSteps: parseNumber(env.MAX_STEPS, 50),
         maxTokens: parseNumber(env.MAX_TOKENS, 4096),
+        modelTimeoutSeconds: parseNumber(env.MODEL_TIMEOUT_SECONDS, 60),
         maxContextTokens: parseNumber(env.MAX_CONTEXT_TOKENS, 32_000),
         workspaceRoot,
         commandTimeoutMs: parseNumber(env.COMMAND_TIMEOUT_MS, 30_000),

package/dist/src/agent/editable-config.js

@@ -34,6 +34,12 @@ export const EDITABLE_CONFIG_DEFINITIONS = [
         type: "number",
         description: "Maximum completion tokens per model response",
     },
+    {
+        key: "modelTimeoutSeconds",
+        envVar: "MODEL_TIMEOUT_SECONDS",
+        type: "number",
+        description: "Maximum time to wait for a model API call to start responding",
+    },
     {
         key: "maxContextTokens",
         envVar: "MAX_CONTEXT_TOKENS",

package/dist/src/serve/mcp-server.js

@@ -11,6 +11,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { z } from "zod";
 import { getSymbolDisplayName } from "../indexer/symbol-names.js";
 import { formatAmbiguousSymbolMatches, resolveSymbolInput, } from "../shared/symbol-resolution.js";
+import { searchSymbols } from "../shared/symbol-search.js";
 /** Active transports keyed by session ID. */
 const transports = new Map();
 /**
@@ -157,22 +158,27 @@ function createMcpServer(bridge, emit) {
         kind: z.string().optional().describe("Filter by kind: function, class, interface, type, variable, method"),
     }, async ({ query, kind }) => {
         return wrapToolCall("search_code_map", { query, kind }, async () => {
-            const symbols = bridge.getSymbols();
-            const queryLower = query.toLowerCase();
-            let matches = symbols.filter((s) => {
-                const nameMatch = s.name.toLowerCase().includes(queryLower) ||
-                    s.qualifiedName.toLowerCase().includes(queryLower);
-                return nameMatch;
-            });
-            if (kind) {
-                matches = matches.filter((s) => s.kind === kind);
-            }
-            matches = matches.slice(0, 30);
-            if (matches.length === 0) {
+            const result = searchSymbols(bridge.getSymbols().map((symbol) => ({
+                symbol,
+                record: {
+                    name: symbol.name,
+                    qualifiedName: symbol.qualifiedName,
+                    kind: symbol.kind,
+                    filePath: symbol.filePath,
+                    startLine: symbol.startLine,
+                    exported: symbol.exported,
+                },
+                lookupNames: [symbol.name, symbol.qualifiedName],
+            })), query, { kind, limit: 30 });
+            if (result.total === 0) {
                 return { content: [{ type: "text", text: `No symbols matching "${query}"${kind ? ` (kind: ${kind})` : ""}.` }] };
             }
+            const matches = result.matches;
+            const heading = result.mode === "similar"
+                ? `No exact substring matches for "${query}"${kind ? ` (kind: ${kind})` : ""}. Showing ${matches.length} similar symbol(s):`
+                : `Found ${matches.length} symbol(s) matching "${query}":`;
             const lines = [
-                `Found ${matches.length} symbol(s) matching "${query}":`,
+                heading,
                 ...matches.map((s) => `  - ${s.name} (${s.kind}) — ${s.filePath}:${s.startLine} — qualified: ${s.qualifiedName}${s.signature ? `\n    ${s.signature}` : ""}`),
             ];
             return { content: [{ type: "text", text: lines.join("\n") }] };

package/dist/src/serve/server.js

@@ -30,6 +30,19 @@ function sendJson(res, status, body) {
     res.writeHead(status, { "Content-Type": "application/json" });
     res.end(JSON.stringify(body));
 }
+function resolveWorkspaceFilePath(workspaceRoot, requestedPath) {
+    const trimmedPath = requestedPath.trim();
+    if (trimmedPath.length === 0) {
+        return null;
+    }
+    const root = path.resolve(workspaceRoot);
+    const absolutePath = path.resolve(root, trimmedPath);
+    const relativePath = path.relative(root, absolutePath);
+    if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+        return null;
+    }
+    return { absolutePath, relativePath };
+}
 function readBody(req) {
     return new Promise((resolve, reject) => {
         const chunks = [];
@@ -423,6 +436,22 @@ export function createRequestHandler(bridge, emit, options = {}) {
                 }
                 return;
             }
+            if (pathname === "/api/file-source" && method === "GET") {
+                const requestedPath = url.searchParams.get("path") ?? "";
+                const resolved = resolveWorkspaceFilePath(config.workspaceRoot, requestedPath);
+                if (!resolved) {
+                    sendJson(res, 403, { error: "Invalid workspace file path" });
+                    return;
+                }
+                try {
+                    const source = await readFile(resolved.absolutePath, "utf8");
+                    sendJson(res, 200, { filePath: resolved.relativePath, source });
+                }
+                catch {
+                    sendJson(res, 404, { error: `Could not read file: ${resolved.relativePath}` });
+                }
+                return;
+            }
             if (pathname === "/api/code-map" && method === "GET") {
                 const budgetParam = url.searchParams.get("budget");
                 const budget = budgetParam ? Number(budgetParam) : undefined;

package/dist/src/shared/symbol-search.js

@@ -0,0 +1,156 @@
+const MIN_SIMILARITY_QUERY_LENGTH = 3;
+const MIN_SIMILARITY_SCORE = 0.62;
+function normalizeSearchText(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, "");
+}
+function tokenizeSearchText(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean);
+}
+function levenshteinDistance(a, b) {
+    if (a === b) {
+        return 0;
+    }
+    if (a.length === 0) {
+        return b.length;
+    }
+    if (b.length === 0) {
+        return a.length;
+    }
+    const previous = new Array(b.length + 1);
+    const current = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j += 1) {
+        previous[j] = j;
+    }
+    for (let i = 1; i <= a.length; i += 1) {
+        current[0] = i;
+        for (let j = 1; j <= b.length; j += 1) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            current[j] = Math.min(current[j - 1] + 1, previous[j] + 1, previous[j - 1] + cost);
+        }
+        for (let j = 0; j <= b.length; j += 1) {
+            previous[j] = current[j];
+        }
+    }
+    return previous[b.length];
+}
+function diceCoefficient(a, b) {
+    if (a === b) {
+        return 1;
+    }
+    if (a.length < 2 || b.length < 2) {
+        return 0;
+    }
+    const bigrams = new Map();
+    for (let i = 0; i < a.length - 1; i += 1) {
+        const bigram = a.slice(i, i + 2);
+        bigrams.set(bigram, (bigrams.get(bigram) ?? 0) + 1);
+    }
+    let matches = 0;
+    for (let i = 0; i < b.length - 1; i += 1) {
+        const bigram = b.slice(i, i + 2);
+        const count = bigrams.get(bigram) ?? 0;
+        if (count > 0) {
+            bigrams.set(bigram, count - 1);
+            matches += 1;
+        }
+    }
+    return (2 * matches) / ((a.length - 1) + (b.length - 1));
+}
+function computeSimilarityScore(pattern, candidate) {
+    const normalizedPattern = normalizeSearchText(pattern);
+    const normalizedCandidate = normalizeSearchText(candidate);
+    if (!normalizedPattern || !normalizedCandidate) {
+        return 0;
+    }
+    if (normalizedPattern === normalizedCandidate) {
+        return 1;
+    }
+    const maxLength = Math.max(normalizedPattern.length, normalizedCandidate.length, 1);
+    const lengthPenalty = Math.abs(normalizedCandidate.length - normalizedPattern.length) / maxLength;
+    let bestScore = 0;
+    if (normalizedCandidate.startsWith(normalizedPattern) ||
+        normalizedPattern.startsWith(normalizedCandidate)) {
+        bestScore = Math.max(bestScore, 0.93 - (lengthPenalty * 0.2));
+    }
+    const tokens = tokenizeSearchText(candidate);
+    if (tokens.some((token) => token.startsWith(normalizedPattern) || normalizedPattern.startsWith(token))) {
+        bestScore = Math.max(bestScore, 0.88 - (lengthPenalty * 0.15));
+    }
+    const editDistance = levenshteinDistance(normalizedPattern, normalizedCandidate);
+    const maxDistance = Math.max(1, Math.ceil(normalizedPattern.length * 0.34));
+    if (editDistance <= maxDistance) {
+        const editSimilarity = 1 - (editDistance / maxLength);
+        bestScore = Math.max(bestScore, 0.62 + (editSimilarity * 0.3));
+    }
+    const dice = diceCoefficient(normalizedPattern, normalizedCandidate);
+    if (dice >= 0.5) {
+        bestScore = Math.max(bestScore, 0.45 + (dice * 0.35));
+    }
+    return bestScore;
+}
+function compareSubstringCandidates(pattern, a, b) {
+    const lowerPattern = pattern.toLowerCase();
+    const aExact = Number(a.lookupNames.some((value) => value.toLowerCase() === lowerPattern));
+    const bExact = Number(b.lookupNames.some((value) => value.toLowerCase() === lowerPattern));
+    if (aExact !== bExact) {
+        return bExact - aExact;
+    }
+    return Number(b.record.exported ?? false) - Number(a.record.exported ?? false) ||
+        a.record.name.localeCompare(b.record.name) ||
+        a.record.filePath.localeCompare(b.record.filePath) ||
+        a.record.startLine - b.record.startLine ||
+        a.record.qualifiedName.localeCompare(b.record.qualifiedName);
+}
+function compareSimilarCandidates(a, b) {
+    return b.score - a.score ||
+        Number(b.candidate.record.exported ?? false) - Number(a.candidate.record.exported ?? false) ||
+        a.candidate.record.name.localeCompare(b.candidate.record.name) ||
+        a.candidate.record.filePath.localeCompare(b.candidate.record.filePath) ||
+        a.candidate.record.startLine - b.candidate.record.startLine ||
+        a.candidate.record.qualifiedName.localeCompare(b.candidate.record.qualifiedName);
+}
+export function searchSymbols(candidates, pattern, options = {}) {
+    const lowerPattern = pattern.toLowerCase();
+    const normalizedKind = options.kind?.trim().toLowerCase();
+    const skip = Math.max(0, options.skip ?? 0);
+    const limit = Math.max(1, options.limit ?? 30);
+    const filtered = candidates.filter((candidate) => {
+        if (normalizedKind && candidate.record.kind.toLowerCase() !== normalizedKind) {
+            return false;
+        }
+        return true;
+    });
+    const substringMatches = filtered
+        .filter((candidate) => candidate.lookupNames.some((value) => value.toLowerCase().includes(lowerPattern)))
+        .sort((a, b) => compareSubstringCandidates(pattern, a, b));
+    if (substringMatches.length > 0) {
+        return {
+            matches: substringMatches.slice(skip, skip + limit).map((candidate) => candidate.symbol),
+            mode: "substring",
+            total: substringMatches.length,
+        };
+    }
+    const normalizedPattern = normalizeSearchText(pattern);
+    if (normalizedPattern.length < MIN_SIMILARITY_QUERY_LENGTH) {
+        return { matches: [], mode: "none", total: 0 };
+    }
+    const similarMatches = filtered
+        .map((candidate) => ({
+        candidate,
+        score: Math.max(...candidate.lookupNames.map((value) => computeSimilarityScore(pattern, value))),
+    }))
+        .filter((entry) => entry.score >= MIN_SIMILARITY_SCORE)
+        .sort(compareSimilarCandidates);
+    if (similarMatches.length === 0) {
+        return { matches: [], mode: "none", total: 0 };
+    }
+    return {
+        matches: similarMatches.slice(skip, skip + limit).map((entry) => entry.candidate.symbol),
+        mode: "similar",
+        total: similarMatches.length,
+    };
+}

package/dist/src/tools/search-code-map.js

@@ -1,26 +1,7 @@
 import { expectNonEmptyString, expectOptionalNumber } from "@minicode/agent-sdk";
 import { getSymbolDisplayName, getSymbolLookupNames } from "../indexer/symbol-names.js";
+import { searchSymbols } from "../shared/symbol-search.js";
 const DEFAULT_LIMIT = 30;
-function compareMatchedSymbols(pattern, a, b) {
-    const lowerPattern = pattern.toLowerCase();
-    const aDisplay = getSymbolDisplayName(a).toLowerCase();
-    const bDisplay = getSymbolDisplayName(b).toLowerCase();
-    const aExact = Number(aDisplay === lowerPattern || a.qualifiedName.toLowerCase() === lowerPattern || a.name.toLowerCase() === lowerPattern);
-    const bExact = Number(bDisplay === lowerPattern || b.qualifiedName.toLowerCase() === lowerPattern || b.name.toLowerCase() === lowerPattern);
-    if (aExact !== bExact) {
-        return bExact - aExact;
-    }
-    return Number(b.exported) - Number(a.exported) ||
-        aDisplay.localeCompare(bDisplay) ||
-        a.filePath.localeCompare(b.filePath) ||
-        a.startLine - b.startLine ||
-        a.qualifiedName.localeCompare(b.qualifiedName);
-}
-function matchesPattern(text, pattern) {
-    const lowerText = text.toLowerCase();
-    const lowerPattern = pattern.toLowerCase();
-    return lowerText.includes(lowerPattern);
-}
 export function createSearchCodeMapTool(projectIndex) {
     return {
         name: "search_code_map",
@@ -58,28 +39,39 @@ export function createSearchCodeMapTool(projectIndex) {
                 : undefined;
             const limit = Math.max(1, Math.min(100, expectOptionalNumber(input, "limit") ?? DEFAULT_LIMIT));
             const skip = Math.max(0, expectOptionalNumber(input, "skip") ?? 0);
-            const symbols = [...projectIndex.symbols.values()];
-            const matches = symbols.filter((sym) => {
-                const lookupNames = getSymbolLookupNames(sym);
-                if (!lookupNames.some((candidate) => matchesPattern(candidate, pattern))) {
-                    return false;
-                }
-                if (kind && sym.kind !== kind) {
-                    return false;
-                }
-                return true;
-            }).sort((a, b) => compareMatchedSymbols(pattern, a, b));
-            const shown = matches.slice(skip, skip + limit);
+            const result = searchSymbols([...projectIndex.symbols.values()].map((sym) => ({
+                symbol: sym,
+                record: {
+                    name: getSymbolDisplayName(sym),
+                    qualifiedName: sym.qualifiedName,
+                    kind: sym.kind,
+                    filePath: sym.filePath,
+                    startLine: sym.startLine,
+                    exported: sym.exported,
+                },
+                lookupNames: getSymbolLookupNames(sym),
+            })), pattern, { kind, limit, skip });
+            const shown = result.matches;
             const lines = shown.map((s) => `- ${getSymbolDisplayName(s)} (${s.kind}) — ${s.filePath}:${s.startLine} — qualified: ${s.qualifiedName}`);
-            const remaining = matches.length - skip - shown.length;
+            const remaining = result.total - skip - shown.length;
             const footer = remaining > 0
                 ? `\n... and ${remaining} more (use skip: ${skip + limit}, limit: ${limit} for next page)`
                 : "";
-            if (matches.length === 0) {
+            if (result.total === 0) {
                 return `No symbols matching "${pattern}"${kind ? ` (kind: ${kind})` : ""}. Try a shorter or different pattern.`;
             }
+            if (result.mode === "similar") {
+                return [
+                    `# No exact substring matches for "${pattern}"${kind ? ` (kind: ${kind})` : ""}`,
+                    "",
+                    `Showing similar symbols instead (${result.total} total):`,
+                    "",
+                    ...lines,
+                    footer,
+                ].join("\n");
+            }
             return [
-                `# Symbols matching "${pattern}" (${matches.length} total)`,
+                `# Symbols matching "${pattern}" (${result.total} total)`,
                 "",
                 ...lines,
                 footer,

package/dist/src/web/app.js

@@ -2,6 +2,22 @@ var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
 
+// src/web/modal-state.ts
+function syncBodyModalOpenState() {
+  const anyModalOpen = [...document.querySelectorAll(".modal")].some((modal) => !modal.classList.contains("hidden"));
+  document.body.classList.toggle("modal-open", anyModalOpen);
+}
+function openModal(modal) {
+  modal.classList.remove("hidden");
+  modal.setAttribute("aria-hidden", "false");
+  syncBodyModalOpenState();
+}
+function closeModal(modal) {
+  modal.classList.add("hidden");
+  modal.setAttribute("aria-hidden", "true");
+  syncBodyModalOpenState();
+}
+
 // node_modules/marked/lib/marked.esm.js
 function M() {
   return { async: false, breaks: false, extensions: null, gfm: true, hooks: null, pedantic: false, renderer: null, silent: false, tokenizer: null, walkTokens: null };
@@ -1660,6 +1676,8 @@ var analysisReport = null;
 var activeAnalysisFindingId = null;
 var activeAnalysisFilter = "all";
 var analysisExplanationCache = /* @__PURE__ */ new Map();
+var filePreviewModalInitialized = false;
+var latestFilePreviewRequestId = 0;
 var LAYOUT_OPTIONS = {
   name: "cose",
   nodeRepulsion: function() {
@@ -1685,6 +1703,7 @@ async function initGraph() {
   initialized = true;
   const cyEl = document.getElementById("cy");
   const detailEl = document.getElementById("symbol-detail");
+  setupFilePreviewModal();
   try {
     const [graphRes, symbolsRes, focusRes] = await Promise.all([
       fetch("/api/graph"),
@@ -1823,6 +1842,78 @@ function focusFileInGraph(filePath) {
   refreshAnalysisGraphState();
   runLayout();
 }
+function getFilePreviewLanguage(filePath) {
+  const ext = filePath.split(".").pop()?.toLowerCase() || "";
+  const langMap = {
+    ts: "typescript",
+    tsx: "typescript",
+    js: "javascript",
+    jsx: "javascript",
+    json: "json",
+    md: "markdown",
+    css: "css",
+    html: "xml"
+  };
+  return langMap[ext] || "plaintext";
+}
+function closeFilePreview() {
+  const modal = document.getElementById("file-preview-modal");
+  if (!modal) return;
+  closeModal(modal);
+}
+function setupFilePreviewModal() {
+  if (filePreviewModalInitialized) return;
+  filePreviewModalInitialized = true;
+  const modal = document.getElementById("file-preview-modal");
+  const backdrop = document.getElementById("file-preview-backdrop");
+  const closeBtn = document.getElementById("file-preview-close");
+  if (!modal || !backdrop || !closeBtn) {
+    return;
+  }
+  backdrop.addEventListener("click", () => closeFilePreview());
+  closeBtn.addEventListener("click", () => closeFilePreview());
+  document.addEventListener("keydown", (event) => {
+    if (event.key === "Escape" && !modal.classList.contains("hidden")) {
+      closeFilePreview();
+    }
+  });
+}
+async function openFilePreview(filePath) {
+  const modal = document.getElementById("file-preview-modal");
+  const pathEl = document.getElementById("file-preview-path");
+  const codeEl = document.getElementById("file-preview-code");
+  if (!modal || !pathEl || !codeEl) {
+    return;
+  }
+  latestFilePreviewRequestId += 1;
+  const requestId = latestFilePreviewRequestId;
+  pathEl.textContent = filePath;
+  codeEl.className = "file-preview-code";
+  codeEl.textContent = "Loading...";
+  openModal(modal);
+  try {
+    const res = await fetch(`/api/file-source?path=${encodeURIComponent(filePath)}`);
+    if (!res.ok) {
+      codeEl.textContent = "(file unavailable)";
+      return;
+    }
+    const data = await res.json();
+    if (requestId !== latestFilePreviewRequestId) {
+      return;
+    }
+    pathEl.textContent = data.filePath;
+    codeEl.className = `file-preview-code language-${getFilePreviewLanguage(data.filePath)}`;
+    codeEl.textContent = data.source;
+    if (typeof hljs !== "undefined") {
+      hljs.highlightElement(codeEl);
+    }
+  } catch {
+    if (requestId !== latestFilePreviewRequestId) {
+      return;
+    }
+    codeEl.textContent = "(file unavailable)";
+  }
+}
 async function focusSymbolInGraph(symbolId, options = {}) {
   await focusSymbolsInGraph([symbolId], options);
 }
@@ -2349,7 +2440,7 @@ async function showDetail(node, detailEl) {
       <span class="detail-name">${escapeHtml(data.label)}</span>
       <span class="detail-kind-badge" style="background:${kindColor}20;color:${kindColor}">${kind}</span>
     </div>
-    <div class="detail-file">${escapeHtml(data.file || "unknown")}${data.startLine ? ":" + data.startLine : ""}</div>
+    <div class="detail-file">${data.file ? `<button type="button" class="detail-file-link" data-file="${escapeHtml(data.file)}">${escapeHtml(data.file)}${data.startLine ? ":" + data.startLine : ""}</button>` : "unknown"}</div>
   `;
   html += `<div class="detail-actions">`;
   html += `<button class="detail-pin header-btn" data-name="${escapeHtml(data.qualifiedName)}">${isPinned ? "Unpin" : "Pin to focus"}</button>`;
@@ -2391,6 +2482,12 @@ async function showDetail(node, detailEl) {
     const name = pinBtn.dataset.name || "";
     await togglePin(name, node, pinBtn);
   });
+  const fileLink = detailEl.querySelector(".detail-file-link");
+  fileLink?.addEventListener("click", () => {
+    const filePath = fileLink.dataset.file || "";
+    if (!filePath) return;
+    void openFilePreview(filePath);
+  });
   const explainBtn = detailEl.querySelector(".detail-explain-btn");
   explainBtn.addEventListener("click", () => {
     const name = explainBtn.dataset.name || "";
@@ -2599,6 +2696,7 @@ function setupToolbar() {
         dropdown.classList.add("hidden");
         if (type === "file") {
           focusFileInGraph(id);
+          void openFilePreview(id);
           return;
         }
         void focusSymbolInGraph(id, {
@@ -3170,16 +3268,6 @@ function closeHeaderMenus() {
   modelDropdown.classList.add("hidden");
   sessionDropdown.classList.add("hidden");
 }
-function isSettingsModalOpen() {
-  return !settingsModal.classList.contains("hidden");
-}
-function isOpenRouterConnectModalOpen() {
-  return !openRouterConnectModal.classList.contains("hidden");
-}
-function syncModalOpenState() {
-  const anyModalOpen = isSettingsModalOpen() || isOpenRouterConnectModalOpen();
-  document.body.classList.toggle("modal-open", anyModalOpen);
-}
 function formatSettingsValue(value) {
   return value === null ? "(unset)" : String(value);
 }
@@ -3394,30 +3482,22 @@ function updateSettingsActions() {
 }
 function openSettings() {
   closeHeaderMenus();
-  settingsModal.classList.remove("hidden");
-  settingsModal.setAttribute("aria-hidden", "false");
-  syncModalOpenState();
+  openModal(settingsModal);
   void loadSettings();
 }
 function closeSettings() {
-  settingsModal.classList.add("hidden");
-  settingsModal.setAttribute("aria-hidden", "true");
-  syncModalOpenState();
+  closeModal(settingsModal);
   clearSettingsBanner();
 }
 function openOpenRouterConnectModal() {
   closeHeaderMenus();
-  openRouterConnectModal.classList.remove("hidden");
-  openRouterConnectModal.setAttribute("aria-hidden", "false");
+  openModal(openRouterConnectModal);
   openRouterPersistCheckbox.checked = false;
   openRouterConnectContinueBtn.disabled = false;
-  syncModalOpenState();
 }
 function closeOpenRouterConnectModal() {
-  openRouterConnectModal.classList.add("hidden");
-  openRouterConnectModal.setAttribute("aria-hidden", "true");
+  closeModal(openRouterConnectModal);
   openRouterConnectContinueBtn.disabled = false;
-  syncModalOpenState();
 }
 chatForm.addEventListener("submit", (e) => {
   e.preventDefault();

package/dist/src/web/index.html

@@ -235,6 +235,22 @@ MODEL=your-model-name</pre>
     </section>
   </div>
 
+  <div id="file-preview-modal" class="modal hidden" aria-hidden="true">
+    <div id="file-preview-backdrop" class="modal-backdrop"></div>
+    <section class="modal-panel modal-panel-file-preview" role="dialog" aria-modal="true" aria-labelledby="file-preview-title">
+      <div class="modal-header">
+        <div>
+          <h2 id="file-preview-title">File preview</h2>
+          <p id="file-preview-path" class="modal-subtitle">Loading…</p>
+        </div>
+        <button id="file-preview-close" class="header-btn" type="button">Close</button>
+      </div>
+      <div class="file-preview-body">
+        <pre id="file-preview-code" class="file-preview-code">Loading...</pre>
+      </div>
+    </section>
+  </div>
+
   <script type="module" src="app.js"></script>
 </body>
 </html>