projview 0.1.0

package/public/viewer.js

@@ -0,0 +1,83 @@
+/* the document viewer: fetch + render a file, anchors, search highlight */
+
+import { $, esc, cssEsc } from './dom.js';
+import { state } from './store.js';
+import { revealInTree } from './tree.js';
+import { renderBreadcrumb } from './breadcrumb.js';
+import { runMermaid } from './mermaid.js';
+import { buildToc } from './toc.js';
+import { toast } from './toast.js';
+
+const contentEl = $('content');
+const viewerEl = $('viewer');
+
+export async function openFile(p, fragment, highlight) {
+  state.currentPath = p;
+  location.hash = encodeURIComponent(p);
+  revealInTree(p);
+  renderBreadcrumb(p);
+
+  let res;
+  try {
+    res = await fetch(`/api/file?p=${encodeURIComponent(p)}`);
+  } catch {
+    res = null;
+  }
+  if (!res || !res.ok) {
+    showNotFound(p);
+    return;
+  }
+  const { html } = await res.json();
+  contentEl.innerHTML = html;
+  await runMermaid();
+  buildToc();
+  if (fragment) scrollToFragment(fragment);
+  else if (highlight) highlightInContent(highlight);
+  else viewerEl.scrollTop = 0;
+}
+
+export function scrollToFragment(frag) {
+  const el = document.getElementById(frag);
+  // instant, not smooth: smooth scrollIntoView is a no-op on this overflow container
+  if (el) el.scrollIntoView({ block: 'start' });
+  else toast(`no section "#${frag}" on this page`);
+}
+
+// Find the first occurrence of a search term in the rendered content, briefly
+// highlight it, and scroll it into view. Used when opening from a content match.
+function highlightInContent(term) {
+  if (!term) { viewerEl.scrollTop = 0; return; }
+  const t = term.trim().toLowerCase();
+  const candidates = [t, ...t.split(/\s+/)].filter(Boolean);
+  const walker = document.createTreeWalker(contentEl, NodeFilter.SHOW_TEXT);
+  let node;
+  while ((node = walker.nextNode())) {
+    const hay = node.nodeValue.toLowerCase();
+    for (const needle of candidates) {
+      const idx = hay.indexOf(needle);
+      if (idx === -1) continue;
+      const range = document.createRange();
+      range.setStart(node, idx);
+      range.setEnd(node, idx + needle.length);
+      const mark = document.createElement('mark');
+      mark.className = 'search-hit';
+      try { range.surroundContents(mark); } catch { viewerEl.scrollTop = 0; return; }
+      mark.scrollIntoView({ block: 'center' });
+      setTimeout(() => {
+        const parent = mark.parentNode;
+        if (parent) { parent.replaceChild(document.createTextNode(mark.textContent), mark); parent.normalize(); }
+      }, 3000);
+      return;
+    }
+  }
+  viewerEl.scrollTop = 0;   // nothing matched in the rendered text
+}
+
+function showNotFound(p) {
+  contentEl.innerHTML =
+    `<div class="empty-state"><div class="empty-emoji">🤷</div>` +
+    `<p>can't find <code>${esc(p)}</code></p>` +
+    `<p class="muted">the link may be broken, or the file was renamed / removed</p></div>`;
+  buildToc();
+  toast(`not found: ${p}`);
+}

package/src/render.js

@@ -0,0 +1,95 @@
+import MarkdownIt from 'markdown-it';
+import hljs from 'highlight.js';
+
+function escapeHtml(str) {
+  return str
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+const md = new MarkdownIt({
+  html: true,
+  linkify: true,
+  typographer: true,
+  highlight(code, lang) {
+    if (lang && hljs.getLanguage(lang)) {
+      try {
+        return `<pre class="hljs"><code>${hljs.highlight(code, { language: lang }).value}</code></pre>`;
+      } catch { /* fall through */ }
+    }
+    return `<pre class="hljs"><code>${escapeHtml(code)}</code></pre>`;
+  }
+});
+
+// Intercept ```mermaid fences -> emit a div the client lib renders.
+// Everything else keeps the default (highlighted) fence rendering.
+const defaultFence = md.renderer.rules.fence.bind(md.renderer.rules);
+md.renderer.rules.fence = (tokens, idx, options, env, self) => {
+  const info = tokens[idx].info.trim().toLowerCase();
+  if (info === 'mermaid') {
+    return `<div class="mermaid">${escapeHtml(tokens[idx].content)}</div>\n`;
+  }
+  return defaultFence(tokens, idx, options, env, self);
+};
+
+// kebab-case slug from heading text, stripped of punctuation.
+function slugify(text) {
+  return text
+    .trim()
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/[\s_]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'section';
+}
+
+const EXPLICIT_ID = /\s*\{#([\w-]+)\}\s*$/;
+
+// Give every heading a stable id so #fragment links can target it.
+// Honors an explicit trailing {#id}, otherwise slugs the heading text.
+md.core.ruler.push('heading_anchors', (state) => {
+  const used = Object.create(null);
+  const tokens = state.tokens;
+  for (let i = 0; i < tokens.length; i++) {
+    if (tokens[i].type !== 'heading_open') continue;
+    const inline = tokens[i + 1];
+    if (!inline || inline.type !== 'inline') continue;
+
+    let id;
+    const explicit = inline.content.match(EXPLICIT_ID);
+    if (explicit) {
+      id = explicit[1];
+      inline.content = inline.content.replace(EXPLICIT_ID, '');
+      // strip the visible {#id} from the rendered text token too
+      const kids = inline.children || [];
+      for (let j = kids.length - 1; j >= 0; j--) {
+        if (kids[j].type === 'text' && EXPLICIT_ID.test(kids[j].content)) {
+          kids[j].content = kids[j].content.replace(EXPLICIT_ID, '');
+          break;
+        }
+      }
+    } else {
+      id = slugify(inline.content);
+    }
+
+    let unique = id;
+    let n = 1;
+    while (used[unique]) unique = `${id}-${n++}`;
+    used[unique] = true;
+    tokens[i].attrSet('id', unique);
+  }
+});
+
+export function renderMarkdown(content) {
+  return md.render(content);
+}
+
+// A standalone .mmd file is one whole diagram.
+export function renderMermaid(content) {
+  return `<div class="mermaid">${escapeHtml(content)}</div>\n`;
+}
+
+export function renderFile(ext, content) {
+  return ext === '.mmd' ? renderMermaid(content) : renderMarkdown(content);
+}

package/src/search.js

@@ -0,0 +1,101 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { buildTree } from './walk.js';
+
+// In-memory index: relPath -> { path, name, content, lower }. Rebuilt per run,
+// kept fresh by the watcher. Nothing is persisted to disk.
+const index = new Map();
+let theRoot = null;
+
+function flattenFiles(nodes, acc = []) {
+  for (const n of nodes) {
+    if (n.type === 'dir') flattenFiles(n.children, acc);
+    else acc.push(n);
+  }
+  return acc;
+}
+
+function addToIndex(rel, content) {
+  index.set(rel, { path: rel, name: rel.split('/').pop(), content, lower: content.toLowerCase() });
+}
+
+// Read + index every previewable file under root.
+export async function buildIndex(root) {
+  theRoot = root;
+  index.clear();
+  const files = flattenFiles(buildTree(root));
+  await Promise.all(files.map(async (f) => {
+    try { addToIndex(f.path, await fsp.readFile(path.join(root, f.path), 'utf8')); }
+    catch { /* unreadable - skip */ }
+  }));
+}
+
+export async function updateFile(rel) {
+  if (!theRoot) return;
+  try { addToIndex(rel, await fsp.readFile(path.join(theRoot, rel), 'utf8')); }
+  catch { /* gone between event and read - ignore */ }
+}
+
+export function removeFile(rel) { index.delete(rel); }
+
+// Subsequence fuzzy match. null if `q` isn't a subsequence of `text`, else a
+// score where contiguous runs and word-boundary hits are rewarded.
+export function fuzzyScore(text, q) {
+  if (!q) return 0;
+  let ti = 0, score = 0, run = 0, prev = -2;
+  for (let qi = 0; qi < q.length; qi++) {
+    const c = q[qi];
+    let found = -1;
+    while (ti < text.length) { if (text[ti] === c) { found = ti; break; } ti++; }
+    if (found === -1) return null;
+    if (found === prev + 1) { run++; score += 4 + run; } else { run = 0; score += 1; }
+    if (found === 0 || /[\/\-_. ]/.test(text[found - 1])) score += 5;   // word boundary
+    prev = found;
+    ti = found + 1;
+  }
+  if (text.includes(q)) score += 12;                                    // exact substring
+  score += Math.max(0, 8 - Math.floor((text.length - q.length) / 4));   // prefer concise
+  return score;
+}
+
+export function search(q, { maxFiles = 8, maxContent = 10, snippetsPerFile = 3 } = {}) {
+  const query = (q || '').trim();
+  if (!query) return { query: '', files: [], content: [] };
+  const ql = query.toLowerCase();
+  const terms = ql.split(/\s+/).filter(Boolean);
+
+  // --- filename: fuzzy, ranked ---
+  const files = [];
+  for (const item of index.values()) {
+    const s = fuzzyScore(item.name.toLowerCase(), ql);
+    const sp = fuzzyScore(item.path.toLowerCase(), ql);
+    const score = Math.max(s ?? -1, sp ?? -1);
+    if (score >= 0) files.push({ path: item.path, name: item.name, score });
+  }
+  files.sort((a, b) => b.score - a.score);
+
+  // --- contents: every term must appear (AND), ranked by frequency ---
+  const content = [];
+  for (const item of index.values()) {
+    if (!terms.every((t) => item.lower.includes(t))) continue;
+    const lines = item.content.split(/\r?\n/);
+    const snippets = [];
+    let freq = 0;
+    for (let i = 0; i < lines.length; i++) {
+      const ll = lines[i].toLowerCase();
+      let lineHas = false;
+      for (const t of terms) {
+        let idx = 0;
+        while ((idx = ll.indexOf(t, idx)) !== -1) { freq++; idx += t.length; lineHas = true; }
+      }
+      if (lineHas && snippets.length < snippetsPerFile) {
+        snippets.push({ line: i + 1, text: lines[i].trim().slice(0, 160) });
+      }
+    }
+    const nameBonus = item.name.toLowerCase().includes(ql) ? 6 : 0;
+    content.push({ path: item.path, name: item.name, score: freq + nameBonus, count: freq, snippets });
+  }
+  content.sort((a, b) => b.score - a.score);
+
+  return { query, files: files.slice(0, maxFiles), content: content.slice(0, maxContent) };
+}

package/src/server.js

@@ -0,0 +1,160 @@
+import http from 'node:http';
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import chokidar from 'chokidar';
+
+import { buildTree, isIgnoredDir, isPreviewable } from './walk.js';
+import { renderFile } from './render.js';
+import { buildIndex, updateFile, removeFile, search } from './search.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PUBLIC_DIR = path.join(__dirname, '..', 'public');
+// vendored client libs (mermaid bundle, hljs theme) live in public/vendor/ and
+// are served by the static handler below - no node_modules resolution needed.
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8'
+};
+
+function sendFile(res, filePath, type) {
+  fs.readFile(filePath, (err, data) => {
+    if (err) {
+      res.writeHead(404).end('Not found');
+      return;
+    }
+    res.writeHead(200, { 'Content-Type': type || MIME[path.extname(filePath)] || 'application/octet-stream' });
+    res.end(data);
+  });
+}
+
+function sendJson(res, obj, status = 200) {
+  res.writeHead(status, { 'Content-Type': MIME['.json'] });
+  res.end(JSON.stringify(obj));
+}
+
+// Resolve a client-supplied relative path safely inside root.
+function resolveInRoot(root, relPath) {
+  const abs = path.resolve(root, relPath);
+  const rel = path.relative(root, abs);
+  if (rel.startsWith('..') || path.isAbsolute(rel)) return null;
+  return abs;
+}
+
+export async function startServer(root, { port = 4321, host = '127.0.0.1' } = {}) {
+  const sseClients = new Set();
+
+  function broadcast(event, payload) {
+    const frame = `event: ${event}\ndata: ${JSON.stringify(payload || {})}\n\n`;
+    for (const res of sseClients) res.write(frame);
+  }
+
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url, 'http://localhost');
+    const pathname = url.pathname;
+
+    // --- live-reload stream ---
+    if (pathname === '/api/events') {
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        Connection: 'keep-alive'
+      });
+      res.write('event: ready\ndata: {}\n\n');
+      sseClients.add(res);
+      req.on('close', () => sseClients.delete(res));
+      return;
+    }
+
+    // --- file tree ---
+    if (pathname === '/api/tree') {
+      sendJson(res, { root: path.basename(root) || root, tree: buildTree(root) });
+      return;
+    }
+
+    // --- search (fuzzy filenames + full-text contents) ---
+    if (pathname === '/api/search') {
+      sendJson(res, search(url.searchParams.get('q') || ''));
+      return;
+    }
+
+    // --- rendered file contents ---
+    if (pathname === '/api/file') {
+      const rel = url.searchParams.get('p') || '';
+      const abs = resolveInRoot(root, rel);
+      if (!abs || !isPreviewable(abs)) {
+        sendJson(res, { error: 'invalid path' }, 400);
+        return;
+      }
+      try {
+        const content = await fsp.readFile(abs, 'utf8');
+        sendJson(res, { path: rel, ext: path.extname(abs).toLowerCase(), html: renderFile(path.extname(abs).toLowerCase(), content) });
+      } catch {
+        sendJson(res, { error: 'not found' }, 404);
+      }
+      return;
+    }
+
+    // --- static SPA assets (incl. /vendor/*) ---
+    const assetName = pathname === '/' ? 'index.html' : pathname.slice(1);
+    const assetPath = resolveInRoot(PUBLIC_DIR, assetName);
+    if (assetPath && fs.existsSync(assetPath) && fs.statSync(assetPath).isFile()) {
+      sendFile(res, assetPath);
+      return;
+    }
+
+    res.writeHead(404).end('Not found');
+  });
+
+  // --- file watcher -> live reload ---
+  const watcher = chokidar.watch(root, {
+    ignoreInitial: true,
+    ignored: (p) => p.split(path.sep).some(isIgnoredDir)
+  });
+  const rel = (p) => path.relative(root, p).split(path.sep).join('/');
+  watcher
+    .on('change', (p) => {
+      if (!isPreviewable(p)) return;
+      updateFile(rel(p));
+      broadcast('change', { path: rel(p) });
+    })
+    .on('add', (p) => { if (isPreviewable(p)) { updateFile(rel(p)); broadcast('tree'); } })
+    .on('unlink', (p) => { if (isPreviewable(p)) { removeFile(rel(p)); broadcast('tree'); } })
+    .on('addDir', () => broadcast('tree'))
+    .on('unlinkDir', () => broadcast('tree'));
+
+  await buildIndex(root);   // in-memory content index for search
+  const listenPort = await listenWithRetry(server, port, host);
+
+  const close = () => new Promise((resolve) => {
+    watcher.close();
+    for (const res of sseClients) res.end();
+    server.close(() => resolve());
+  });
+
+  return { server, port: listenPort, close };
+}
+
+// Try `port`, then climb until one is free (give up after a sane range).
+function listenWithRetry(server, port, host = '127.0.0.1', attempts = 20) {
+  return new Promise((resolve, reject) => {
+    let current = port;
+    let left = attempts;
+    const tryListen = () => {
+      server.once('error', (err) => {
+        if (err.code === 'EADDRINUSE' && left-- > 0) {
+          current += 1;
+          tryListen();
+        } else {
+          reject(err);
+        }
+      });
+      server.listen(current, host, () => resolve(current));
+    };
+    tryListen();
+  });
+}

package/src/walk.js

@@ -0,0 +1,57 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Directories we never descend into - noise or huge.
+const IGNORED_DIRS = new Set([
+  'node_modules', 'dist', 'build', 'out', 'coverage',
+  '.cache', '.turbo', 'vendor', '.venv', '__pycache__'
+]);
+
+export const PREVIEWABLE_EXTS = new Set(['.md', '.mmd']);
+
+// True if a path segment should stop the walk (ignored name or any dot-dir).
+export function isIgnoredDir(name) {
+  return IGNORED_DIRS.has(name) || name.startsWith('.');
+}
+
+export function isPreviewable(filePath) {
+  return PREVIEWABLE_EXTS.has(path.extname(filePath).toLowerCase());
+}
+
+// Dirs first, then files, each alphabetical (case-insensitive).
+function byNameDirsFirst(a, b) {
+  if (a.isDirectory() !== b.isDirectory()) return a.isDirectory() ? -1 : 1;
+  return a.name.localeCompare(b.name, undefined, { sensitivity: 'base' });
+}
+
+// Recursively build a tree of only the dirs that (transitively) contain
+// previewable files. Returns the root's children array.
+export function buildTree(root) {
+  function walk(absDir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(absDir, { withFileTypes: true });
+    } catch {
+      return [];
+    }
+    const nodes = [];
+    for (const entry of entries.sort(byNameDirsFirst)) {
+      const abs = path.join(absDir, entry.name);
+      const rel = path.relative(root, abs).split(path.sep).join('/');
+      if (entry.isDirectory()) {
+        if (isIgnoredDir(entry.name)) continue;
+        const children = walk(abs);
+        if (children.length) nodes.push({ name: entry.name, path: rel, type: 'dir', children });
+      } else if (entry.isFile() && isPreviewable(entry.name)) {
+        nodes.push({ name: entry.name, path: rel, type: 'file', ext: path.extname(entry.name).toLowerCase() });
+      }
+    }
+    return nodes;
+  }
+  return walk(root);
+}
+
+// Flat count of file nodes in a tree (for the boot summary).
+export function countFiles(nodes) {
+  return nodes.reduce((n, node) => n + (node.type === 'file' ? 1 : countFiles(node.children)), 0);
+}