codebase-onboarder 0.1.0

package/public/js/atlas.js

@@ -0,0 +1,98 @@
+// The atlas view: a scrollable catalogue of every map, and the card that opens.
+//
+// Two things make this view unlike the others. It is a document rather than a
+// diagram, so it opts out of the canvas's pan and zoom (`atlas-mode`, which
+// diagramPane.js checks before it swallows a drag or a wheel). And a card, once
+// opened, *becomes* another view: the canvas draws the card's diagram and the AI
+// draft button borrows that view's fact sheet. Which is why `atlasOpen` holds
+// the whole item and not just an index.
+//
+// Deciding what is in the list and drawing one card are both pure, and live in
+// shared/diagram/atlas.js with tests. What is left here is the DOM.
+
+import { atlasSpecs, atlasDiagram, filterAtlasItems } from '/shared/diagram/atlas.js';
+import { escapeHtml } from './html.js';
+import { state, focusFile, focusFolder, clearFocus } from './state.js';
+
+let host = null;      // #canvasContent — the pannable layer inside the canvas
+let canvas = null;    // #canvas — the viewport, which is what fixes the list's size
+let hooks = {
+  onSyncInspector: () => {},
+  onRender: () => {},
+  onHome: () => {},
+};
+
+export function initAtlas(options) {
+  host = options.host;
+  canvas = options.canvas;
+  hooks = { ...hooks, ...options };
+}
+
+// Built once per repo and kept: the catalogue is a function of the scan, and the
+// scan does not change while it is loaded. `unloadRepo` resets the flag.
+function specs() {
+  if (!state.atlas.built) {
+    const { scan, facts, manifest, patterns } = state;
+    state.atlas = { built: true, items: atlasSpecs(scan, facts, manifest, patterns) };
+  }
+  return state.atlas.items;
+}
+
+export function renderAtlasList() {
+  const items = filterAtlasItems(specs(), state.filters);
+  host.classList.add('atlas-mode');
+  hooks.onHome(); // the list is a document — never inherit a diagram's zoom
+
+  const list = document.createElement('div');
+  list.className = 'atlas-list';
+  // Exact viewport fit, because the list scrolls itself rather than being panned.
+  list.style.width = canvas.clientWidth + 'px';
+  list.style.height = canvas.clientHeight + 'px';
+
+  const head = document.createElement('p');
+  head.className = 'atlas-head';
+  head.textContent = `${items.length} maps, drawn from the import graph — no AI involved. `
+    + `Open one; if it doesn't satisfy you, the AI draft button redraws it.`;
+  list.appendChild(head);
+
+  const grid = document.createElement('div');
+  grid.className = 'atlas-grid';
+  for (const it of items) {
+    const card = document.createElement('div');
+    card.className = 'atlas-card';
+    card.innerHTML = `
+      <div class="atlas-card-top">
+        <span class="atlas-kind is-${escapeHtml(it.kind)}">${escapeHtml(it.kind)}</span>
+        <span class="atlas-title" title="${escapeHtml(it.path || it.title)}">${escapeHtml(it.title)}</span>
+      </div>
+      <div class="atlas-sub">${escapeHtml(it.sub)}</div>
+    `;
+    card.addEventListener('click', () => openAtlasItem(it));
+    grid.appendChild(card);
+  }
+  list.appendChild(grid);
+
+  host.innerHTML = '';
+  host.appendChild(list);
+}
+
+// Opening a card points the rest of the app at the same subject, so the sidebar,
+// the inspector and the breadcrumbs agree with the picture on the canvas.
+function openAtlasItem(item) {
+  state.atlasOpen = item;
+  if (item.kind === 'file') focusFile(item.path);
+  else if (item.kind === 'folder') focusFolder(item.path);
+  else clearFocus();
+
+  hooks.onSyncInspector();
+  hooks.onRender();
+}
+
+// The diagram for whichever card is open, drawn fresh on each canvas render.
+// Fresh matters: a Mermaid source carries its own palette, so a cached one keeps
+// the theme it was born under. The old atlas stored the source on the item and
+// an opened card stayed light after switching to dark.
+export function openCardDiagram() {
+  const { scan, facts, manifest, patterns } = state;
+  return atlasDiagram(state.atlasOpen, { scan, facts, manifest, patterns });
+}

package/public/js/blameView.js

@@ -0,0 +1,41 @@
+export function initBlameView(container) {
+  return function renderBlame(blameData, options = {}) {
+    if (!blameData || !blameData.lines) {
+      container.hidden = true;
+      return;
+    }
+    container.hidden = false;
+    container.innerHTML = '';
+    
+    // Hash author to color
+    function getAuthorColor(author) {
+      let hash = 0;
+      for (let i = 0; i < author.length; i++) hash = author.charCodeAt(i) + ((hash << 5) - hash);
+      return `hsl(${Math.abs(hash) % 360}, 60%, 50%)`;
+    }
+
+    blameData.lines.forEach(line => {
+      const div = document.createElement('div');
+      div.className = 'blame-line';
+      div.style.backgroundColor = getAuthorColor(line.author || 'Unknown');
+      
+      const tooltip = document.createElement('div');
+      tooltip.className = 'blame-tooltip';
+      tooltip.textContent = `${line.author} - ${line.date || ''} (${(line.sha || '').substring(0, 7)})`;
+      
+      div.appendChild(tooltip);
+      container.appendChild(div);
+    });
+  };
+}
+
+export async function fetchBlame(scanId, path) {
+  try {
+    const res = await fetch(`/api/blame?scan=${encodeURIComponent(scanId)}&path=${encodeURIComponent(path)}`);
+    if (!res.ok) return null;
+    return await res.json();
+  } catch (err) {
+    console.error('Failed to fetch blame:', err);
+    return null;
+  }
+}

package/public/js/codeTab.js

@@ -0,0 +1,256 @@
+// The Code tab: one file at a time, with its imports as chips you can click.
+//
+// Two viewers, one behind the other. Monaco is loaded from the app's own
+// `vendor/` folder and used if it comes up; if it does not, a hand-rolled
+// highlighter takes over for the rest of the session. Neither is required for
+// the page to be useful — the header, the facts and the import chips are drawn
+// from the graph before any file text arrives.
+//
+// The back/forward stack and the "which file should I show" decision live in
+// state.js, where they are pure and tested. What is left here is DOM.
+
+import { roleOf } from '/shared/analyzer/graph.js';
+import { escapeHtml } from './html.js';
+import { highlightCode, langOf } from './highlight.js';
+import { initViewer, showInViewer, monacoLangOf, revealLineInViewer } from './codeViewer.js';
+import { fetchBlame, initBlameView } from './blameView.js';
+import {
+  state, focusFile, defaultCodePath, pushCodeHistory, codeHistoryTarget,
+} from './state.js';
+import { readRepoFile } from './repoFiles.js';
+
+const MAX_FALLBACK_LINES = 3000;
+
+let host = null;
+let renderBlameGutter = null;
+let hooks = {
+  onSyncInspector: () => {},
+  onRenderSidebar: () => {},
+  onOpenFile: () => {},
+  onToast: () => {},
+  getTheme: () => 'light',
+  blameGutter: null,
+};
+
+let codeSeq = 0;          // render generations — a slow read never overwrites a newer one
+let viewerFailed = false; // Monaco failed to load → hand-rolled fallback
+let pendingReveal = null; // a line a search result asked for, waiting for its file
+
+// A search result knows which line it matched. The reveal has to wait until the
+// text is on screen, and it must not leak onto the *next* file you open — which
+// is why it is taken once, at the top of `renderCode`, rather than living in
+// `state` where it would outlive the file it was meant for.
+export function revealLineInCode(line) {
+  const target = Math.floor(Number(line));
+  pendingReveal = Number.isFinite(target) && target > 0 ? target : null;
+}
+
+// Monaco is the real answer; without it, the fallback is a single scrolling
+// `<pre>`, so the best we can do is put the line near the top. Approximate, and
+// honest about being approximate — the file is still the right file.
+function applyReveal(alt, line) {
+  if (!line) return;
+  if (!viewerFailed) {
+    revealLineInViewer(line);
+    return;
+  }
+  const shell = alt.querySelector('.code-shell');
+  if (!shell) return;
+  const gutter = shell.querySelector('.code-gutter');
+  const total = gutter ? (gutter.textContent || '').split('\n').length : 0;
+  if (!total) return;
+  const perLine = shell.scrollHeight / total;
+  shell.scrollTop = Math.max(0, (line - 2) * perLine);
+}
+
+export function initCodeTab(options) {
+  host = options.host;
+  hooks = { ...hooks, ...options };
+  if (options.blameGutter) {
+    renderBlameGutter = initBlameView(options.blameGutter);
+  }
+
+  host.addEventListener('click', (event) => {
+    const b = event.target.closest('button');
+    if (!b) return;
+    if (b.dataset.codeopen) return openCodeFile(b.dataset.codeopen);
+    if (b.dataset.codenav) return codeNav(Number(b.dataset.codenav));
+    if (b.dataset.codedive !== undefined) return (hooks.onDeepDive || hooks.onOpenFile)(state.code.path); // empty attribute is falsy — test undefined
+    if (b.dataset.codeblame !== undefined) {
+      if (!hooks.blameGutter) return;
+      if (!hooks.blameGutter.hidden) {
+        hooks.blameGutter.hidden = true;
+        b.classList.remove('is-active');
+      } else {
+        hooks.onToast('Fetching git blame...');
+        fetchBlame(state.scanId, state.code.path).then((data) => {
+          if (data && data.lines && data.lines.length) {
+            renderBlameGutter(data);
+            hooks.blameGutter.hidden = false;
+            b.classList.add('is-active');
+            hooks.onToast(`Blame loaded for ${data.lines.length} lines`);
+          } else {
+            hooks.onToast(data?.reason || 'No blame available for this file.');
+          }
+        });
+      }
+      return;
+    }
+    if (b.dataset.codecopy !== undefined) {
+      const text = state.code.cache[state.code.path];
+      if (text !== undefined) {
+        navigator.clipboard.writeText(text)
+          .then(() => hooks.onToast('Copied to the clipboard.'))
+          .catch(() => hooks.onToast('Could not copy to the clipboard.'));
+      }
+    }
+  });
+}
+
+// In-tab navigation (the import chips) keeps the sidebar and inspector in step,
+// so the rest of the app follows along rather than pointing at the old file.
+function openCodeFile(path) {
+  state.code.path = path;
+  focusFile(path);
+  hooks.onSyncInspector();
+  hooks.onRenderSidebar();
+  renderCode();
+}
+
+function codeNav(delta) {
+  const path = codeHistoryTarget(delta);
+  if (path) openCodeFile(path);
+}
+
+export async function renderCode() {
+  const seq = ++codeSeq;
+  const path = defaultCodePath();
+  // Taken once and cleared, so a reveal belongs only to the render that followed
+  // the request for it — never to the next file you happen to open.
+  const revealLine = pendingReveal;
+  pendingReveal = null;
+  if (!path) {
+    host.innerHTML = '<div class="code-empty">Nothing to preview — this repo has no readable files.</div>';
+    return;
+  }
+  state.code.path = path;
+  pushCodeHistory(path);
+
+  // The shell is built once: the Monaco container must persist across file
+  // switches, or the editor instance would be destroyed on every render.
+  if (!host.querySelector('.code-page')) {
+    host.innerHTML = `<div class="code-page">
+      <div class="code-head" id="codeHead"></div>
+      <div id="codeLinks"></div>
+      <div class="code-monaco" id="codeMonaco" hidden></div>
+      <div id="codeAlt"></div>
+    </div>`;
+  }
+  const headEl = host.querySelector('#codeHead');
+  const linksEl = host.querySelector('#codeLinks');
+  const monacoEl = host.querySelector('#codeMonaco');
+  const alt = host.querySelector('#codeAlt');
+
+  let text = state.code.cache[path];
+  if (text === undefined) {
+    monacoEl.hidden = true;
+    alt.innerHTML = '<div class="code-empty">Reading ' + escapeHtml(path) + '…</div>';
+    try {
+      text = await readRepoFile(path);
+    } catch (err) {
+      if (seq !== codeSeq) return;
+      alt.innerHTML = '<div class="code-empty">Could not read that file: ' + escapeHtml(err.message) + '</div>';
+      return;
+    }
+    if (seq !== codeSeq) return;
+    state.code.cache[path] = text;
+  }
+
+  const { facts } = state;
+  const parsed = facts.fanIn[path] !== undefined;
+  const name = path.split('/').pop();
+  const ext = (name.match(/\.([A-Za-z0-9]+)$/) || [, ''])[1].toLowerCase();
+  const isBinary = text.slice(0, 8000).includes('\0');
+
+  renderHead(headEl, { path, name, ext, text, parsed, isBinary });
+  linksEl.innerHTML = parsed ? importChips(path) : '';
+
+  if (isBinary) {
+    monacoEl.hidden = true;
+    alt.innerHTML = '<div class="code-empty">Binary file — nothing to preview.</div>';
+    return;
+  }
+
+  // Monaco first; the hand-rolled highlighter stands by if it can't load.
+  if (!viewerFailed) {
+    monacoEl.hidden = false;
+    const ok = await initViewer(monacoEl, hooks.getTheme());
+    if (seq !== codeSeq) return;
+    if (ok) {
+      alt.innerHTML = '';
+      showInViewer(text, monacoLangOf(path), hooks.getTheme());
+      applyReveal(alt, revealLine);
+      return;
+    }
+    viewerFailed = true;
+    monacoEl.hidden = true;
+  }
+  renderFallback(alt, text, path);
+  applyReveal(alt, revealLine);
+}
+
+// Navigation, identity, actions.
+function renderHead(headEl, { path, name, ext, text, parsed, isBinary }) {
+  const { facts } = state;
+  const canBack = state.code.idx > 0;
+  const canFwd = state.code.idx < state.code.history.length - 1;
+  const meta = [
+    (ext || 'text').toUpperCase(),
+    `${text.split('\n').length.toLocaleString()} lines`,
+    `${(new Blob([text]).size / 1024).toFixed(1)} KB`,
+    parsed ? `${roleOf(path, facts)} · ${facts.fanIn[path]} dependents · pulls in ${facts.fanOut[path]}` : 'not parsed',
+  ].join(' · ');
+
+  headEl.innerHTML = `
+    <div class="code-nav">
+      <button class="code-navbtn" data-codenav="-1" ${canBack ? '' : 'disabled'} title="Previous file">←</button>
+      <button class="code-navbtn" data-codenav="1" ${canFwd ? '' : 'disabled'} title="Next file">→</button>
+    </div>
+    <div class="code-title">
+      <h2>${escapeHtml(name)}</h2>
+      <div class="code-path">${escapeHtml(path)}</div>
+      <div class="code-meta">${escapeHtml(meta)}</div>
+    </div>
+    <div class="code-actions">
+      <button class="code-navbtn" data-codeblame ${isBinary ? 'disabled' : ''} title="Toggle Git blame annotations">Blame</button>
+      <button class="code-navbtn" data-codecopy ${isBinary ? 'disabled' : ''}>Copy</button>
+      <button class="code-navbtn" data-codedive>Deep-dive →</button>
+    </div>`;
+}
+
+// The file's neighbours, both directions, as one-click jumps.
+function importChips(path) {
+  const { facts } = state;
+  const chip = (p) => `<button class="code-chip" data-codeopen="${escapeHtml(p)}" title="${escapeHtml(p)}">${escapeHtml(p.split('/').pop())}</button>`;
+  const pulls = (facts.importsOf[path] || []).map(chip).join('');
+  const leans = (facts.importers[path] || []).map(chip).join('');
+  if (!pulls && !leans) return '';
+  return '<div class="code-links">'
+    + (pulls ? `<span class="code-links-label">pulls in</span>${pulls}` : '')
+    + (leans ? `<span class="code-links-label">leaned on by</span>${leans}` : '')
+    + '</div>';
+}
+
+// Without Monaco: a gutter, a highlighted body, and a cap, because pasting a
+// 40,000-line bundle into innerHTML locks the tab.
+function renderFallback(alt, text, path) {
+  const all = text.split('\n');
+  const capped = all.length > MAX_FALLBACK_LINES;
+  const lines = capped ? all.slice(0, MAX_FALLBACK_LINES) : all;
+  const gutter = lines.map((_, i) => i + 1).join('\n');
+  const note = capped
+    ? `<div class="code-note">Showing the first ${MAX_FALLBACK_LINES.toLocaleString()} of ${all.length.toLocaleString()} lines.</div>`
+    : '';
+  alt.innerHTML = `${note}<div class="code-shell"><pre class="code-gutter">${gutter}</pre>`
+    + `<pre class="code-body"><code>${highlightCode(lines.join('\n'), langOf(path))}</code></pre></div>`;
+}

package/public/js/codeViewer.js

@@ -0,0 +1,184 @@
+// Monaco Editor wrapper: lazy-loads the vendored AMD build, defines themes
+// that match the app's palette, and exposes a tiny read-only viewer API.
+// The module itself is import-safe in Node (nothing runs until initViewer);
+// only the language mapper is used there.
+
+// Extension → monaco language id. Anything unmapped renders as plaintext.
+const MONACO_LANGS = {
+  js: 'javascript', mjs: 'javascript', cjs: 'javascript', jsx: 'javascript',
+  ts: 'typescript', tsx: 'typescript', mts: 'typescript',
+  py: 'python', pyi: 'python',
+  go: 'go', java: 'java', kt: 'kotlin', kts: 'kotlin', scala: 'scala',
+  c: 'c', h: 'c', cpp: 'cpp', cc: 'cpp', cxx: 'cpp', hpp: 'cpp',
+  cs: 'csharp', rs: 'rust', rb: 'ruby', php: 'php', swift: 'swift',
+  m: 'objective-c', mm: 'objective-c', dart: 'dart', lua: 'lua', r: 'r',
+  pl: 'perl', pm: 'perl', ex: 'elixir', exs: 'elixir', clj: 'clojure',
+  fs: 'fsharp', vb: 'vb', ps1: 'powershell', sh: 'shell', bash: 'shell',
+  zsh: 'shell', fish: 'shell', bat: 'bat', cmd: 'bat',
+  json: 'json', jsonc: 'json', yaml: 'yaml', yml: 'yaml', toml: 'ini',
+  ini: 'ini', env: 'ini', cfg: 'ini', xml: 'xml', svg: 'xml', xsl: 'xml',
+  html: 'html', htm: 'html', css: 'css', scss: 'scss', less: 'less',
+  md: 'markdown', markdown: 'markdown', mdx: 'markdown',
+  sql: 'sql', mysql: 'mysql', pgsql: 'pgsql', graphql: 'graphql',
+  dockerfile: 'dockerfile', tf: 'hcl', hcl: 'hcl', proto: 'protobuf',
+  sol: 'solidity', tcl: 'tcl', jl: 'julia', coffee: 'coffeescript',
+};
+
+export function monacoLangOf(path) {
+  const name = path.split('/').pop().toLowerCase();
+  if (name === 'dockerfile' || name.startsWith('dockerfile.')) return 'dockerfile';
+  if (name === 'makefile' || name === 'gnumakefile') return 'makefile';
+  if (name === 'cmakelists.txt') return 'cmake';
+  const ext = (name.match(/\.([a-z0-9]+)$/) || [, ''])[1];
+  return MONACO_LANGS[ext] || 'plaintext';
+}
+
+// Themes mirroring styles.css: same paper/ink/accent, same token colors.
+function defineThemes(monaco) {
+  monaco.editor.defineTheme('ob-light', {
+    base: 'vs',
+    inherit: true,
+    rules: [
+      { token: 'comment', foreground: '8a8578', fontStyle: 'italic' },
+      { token: 'string', foreground: '2f5d3f' },
+      { token: 'keyword', foreground: '9a3b2e', fontStyle: 'bold' },
+      { token: 'number', foreground: '1f5f8b' },
+      { token: 'type', foreground: '6b4fa0' },
+    ],
+    colors: {
+      'editor.background': '#fdfbf6',
+      'editor.foreground': '#1c1a16',
+      'editorLineNumber.foreground': '#a8a296',
+      'editorLineNumber.activeForeground': '#6b675c',
+      'editor.lineHighlightBackground': '#f1ede2',
+      'editorCursor.foreground': '#1c1a16',
+      'editor.selectionBackground': '#d8e4d2',
+      'editorIndentGuide.background1': '#e5e0d3',
+    },
+  });
+  monaco.editor.defineTheme('ob-dark', {
+    base: 'vs-dark',
+    inherit: true,
+    rules: [
+      { token: 'comment', foreground: '6f6a5e', fontStyle: 'italic' },
+      { token: 'string', foreground: '8fc7a0' },
+      { token: 'keyword', foreground: 'e08a6d', fontStyle: 'bold' },
+      { token: 'number', foreground: '7fb3d9' },
+      { token: 'type', foreground: 'b49ae0' },
+    ],
+    colors: {
+      'editor.background': '#232019',
+      'editor.foreground': '#e8e2d4',
+      'editorLineNumber.foreground': '#5c574b',
+      'editorLineNumber.activeForeground': '#a8a296',
+      'editor.lineHighlightBackground': '#2b2720',
+      'editorCursor.foreground': '#e8e2d4',
+      'editor.selectionBackground': '#3d4a38',
+      'editorIndentGuide.background1': '#343026',
+    },
+  });
+}
+
+let editor = null;
+let loadPromise = null;
+
+// Loads Monaco once and creates the single reusable editor instance.
+// Resolves false when the vendored build is unavailable — callers fall back
+// to the hand-rolled highlighter.
+export function initViewer(container, theme) {
+  if (editor) return Promise.resolve(true);
+  if (loadPromise) return loadPromise;
+
+  loadPromise = new Promise((resolve) => {
+    if (typeof window.require !== 'function') return resolve(false);
+    window.require.config({ paths: { vs: '/vendor/monaco/vs' } });
+    self.MonacoEnvironment = {
+      // Language workers are AMD modules — they boot through worker-boot.js,
+      // which loads the AMD loader inside the worker first.
+      getWorkerUrl: (workerId, label) => {
+        const boot = '/vendor/monaco/worker-boot.js';
+        if (label === 'typescript' || label === 'javascript') return `${boot}?vs/language/typescript/tsWorker`;
+        if (label === 'json') return `${boot}?vs/language/json/jsonWorker`;
+        if (label === 'css' || label === 'scss' || label === 'less') return `${boot}?vs/language/css/cssWorker`;
+        if (label === 'html' || label === 'handlebars' || label === 'razor') return `${boot}?vs/language/html/htmlWorker`;
+        return '/vendor/monaco/vs/base/worker/workerMain.js'; // standalone editor worker
+      },
+    };
+    const fail = setTimeout(() => resolve(false), 8000); // never wedge the tab
+    window.require(['vs/editor/editor.main'], () => {
+      clearTimeout(fail);
+      defineThemes(monaco);
+      editor = monaco.editor.create(container, {
+        value: '',
+        language: 'plaintext',
+        theme: theme === 'dark' ? 'ob-dark' : 'ob-light',
+        readOnly: true,
+        domReadOnly: true,
+        automaticLayout: true,
+        minimap: { enabled: false },
+        scrollBeyondLastLine: false,
+        renderLineHighlight: 'none',
+        occurrencesHighlight: 'off',
+        folding: true,
+        wordWrap: 'off',
+        contextmenu: false,
+        fontSize: 12.5,
+        fontFamily: "'IBM Plex Mono', 'SF Mono', ui-monospace, Menlo, Consolas, monospace",
+        lineNumbersMinChars: 4,
+        padding: { top: 12, bottom: 12 },
+        scrollbar: { verticalScrollbarSize: 10, horizontalScrollbarSize: 10 },
+      });
+      resolve(true);
+    }, () => { clearTimeout(fail); resolve(false); });
+  });
+  return loadPromise;
+}
+
+// The TS/JS language service loads lazily on the first such model. Once it
+// exists, turn validation off: a read-only preview should never draw red
+// squiggles for imports the standalone worker cannot resolve.
+let tsTamed = false;
+function tameTypeScript() {
+  if (tsTamed) return;
+  const t0 = Date.now();
+  const iv = setInterval(() => {
+    if (window.monaco?.languages?.typescript) {
+      const diag = { noSemanticValidation: true, noSyntaxValidation: true };
+      monaco.languages.typescript.typescriptDefaults.setDiagnosticsOptions(diag);
+      monaco.languages.typescript.javascriptDefaults.setDiagnosticsOptions(diag);
+      tsTamed = true;
+      clearInterval(iv);
+    } else if (Date.now() - t0 > 5000) {
+      clearInterval(iv);
+    }
+  }, 200);
+}
+
+export function showInViewer(text, lang, theme) {
+  if (!editor) return;
+  monaco.editor.setTheme(theme === 'dark' ? 'ob-dark' : 'ob-light');
+  const model = editor.getModel();
+  editor.setValue(text);
+  monaco.editor.setModelLanguage(model, lang);
+  if (lang === 'javascript' || lang === 'typescript') tameTypeScript();
+  editor.setScrollTop(0);
+  editor.setScrollLeft(0);
+}
+
+export function setViewerTheme(theme) {
+  if (editor) monaco.editor.setTheme(theme === 'dark' ? 'ob-dark' : 'ob-light');
+}
+
+// Put the viewer on a line and leave the cursor there. Used when a search result
+// knows where it matched — opening the right file at line 1 is only half an
+// answer, and the other half is the reason a content hit is worth showing.
+export function revealLineInViewer(line) {
+  if (!editor) return;
+  const target = Math.floor(Number(line));
+  if (!Number.isFinite(target) || target < 1) return;
+  const model = editor.getModel();
+  if (!model) return;
+  const clamped = Math.min(target, model.getLineCount());
+  editor.revealLineInCenter(clamped);
+  editor.setPosition({ lineNumber: clamped, column: 1 });
+}

package/public/js/components/FileChip.js

@@ -0,0 +1,102 @@
+export class FileChip extends HTMLElement {
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+  }
+
+  static get observedAttributes() {
+    return ['path', 'lang', 'risk'];
+  }
+
+  connectedCallback() {
+    this.render();
+    this.addEventListener('click', () => {
+      this.dispatchEvent(new CustomEvent('file-select', {
+        detail: { path: this.getAttribute('path') },
+        bubbles: true,
+        composed: true
+      }));
+    });
+  }
+
+  attributeChangedCallback(name, oldValue, newValue) {
+    if (oldValue !== newValue) {
+      this.render();
+    }
+  }
+
+  getRiskColor(risk) {
+    const score = parseInt(risk, 10) || 0;
+    if (score <= 33) return 'rgb(76, 175, 80)';
+    if (score <= 66) return 'rgb(255, 193, 7)';
+    return 'rgb(244, 67, 54)';
+  }
+
+  render() {
+    const path = this.getAttribute('path') || '';
+    const lang = this.getAttribute('lang') || 'txt';
+    const risk = this.getAttribute('risk') || '0';
+    
+    const basename = path.split('/').pop();
+    const riskColor = this.getRiskColor(risk);
+    
+    // Hash for lang color
+    let hash = 0;
+    for (let i = 0; i < lang.length; i++) hash = lang.charCodeAt(i) + ((hash << 5) - hash);
+    const langHue = Math.abs(hash) % 360;
+
+    this.shadowRoot.innerHTML = `
+      <style>
+        :host {
+          display: inline-flex;
+          align-items: center;
+          padding: 4px 8px;
+          border-radius: 16px;
+          background: rgba(128, 128, 128, 0.1);
+          border: 1px solid rgba(128, 128, 128, 0.2);
+          cursor: pointer;
+          font-family: sans-serif;
+          font-size: 12px;
+          transition: background 0.2s;
+        }
+        :host(:hover) {
+          background: rgba(128, 128, 128, 0.2);
+        }
+        .lang-icon {
+          width: 16px;
+          height: 16px;
+          border-radius: 50%;
+          background: hsl(${langHue}, 70%, 50%);
+          color: white;
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          font-size: 8px;
+          font-weight: bold;
+          margin-right: 6px;
+          text-transform: uppercase;
+        }
+        .name {
+          flex: 1;
+          white-space: nowrap;
+          overflow: hidden;
+          text-overflow: ellipsis;
+          max-width: 150px;
+        }
+        .risk-dot {
+          width: 8px;
+          height: 8px;
+          border-radius: 50%;
+          background: ${riskColor};
+          margin-left: 6px;
+        }
+      </style>
+      <div class="lang-icon" title="${lang}">${lang.substring(0, 2)}</div>
+      <div class="name" title="${path}">${basename}</div>
+      <div class="risk-dot" title="Risk: ${risk}"></div>
+    `;
+    this.title = path;
+  }
+}
+
+customElements.define('file-chip', FileChip);