projview 0.1.0 → 0.2.4

package/bin/projview.js

@@ -2,10 +2,12 @@
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { readFileSync } from 'node:fs';
 import { startServer } from '../src/server.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const DEMO_DIR = path.join(__dirname, '..', 'docs');   // bundled sample docs
+const VERSION = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')).version;
 
 function parseArgs(argv) {
   const opts = {
@@ -20,7 +22,9 @@ function parseArgs(argv) {
     if (arg === '--port' || arg === '-p') opts.port = Number(argv[++i]) || opts.port;
     else if (arg === '--no-open') opts.open = false;
     else if (arg === '--demo') opts.demo = true;
+    else if (arg === '--version' || arg === '-v') opts.version = true;
     else if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg.startsWith('-')) opts.unknown = arg;   // unrecognised flag -> error, don't treat as a path
     else rest.push(arg);
   }
   if (rest[0]) opts.root = path.resolve(process.cwd(), rest[0]);
@@ -49,15 +53,18 @@ options:
   -p, --port <n>    preferred port (default: 4321, climbs if taken)
       --demo        preview projview's bundled sample docs
       --no-open     do not auto-open the browser
+  -v, --version     print the version and exit
   -h, --help        show this help
 
 nothing is written to disk - ctrl-c and it's gone.`;
 
 async function main() {
   const opts = parseArgs(process.argv.slice(2));
-  if (opts.help) {
-    console.log(HELP);
-    return;
+  if (opts.help) { console.log(HELP); return; }
+  if (opts.version) { console.log(VERSION); return; }
+  if (opts.unknown) {
+    console.error(`projview: unknown option "${opts.unknown}"\nrun "projview --help" for usage.`);
+    process.exit(1);
   }
 
   const { port, close } = await startServer(opts.root, { port: opts.port, host: opts.host });

package/docs/README.md

@@ -8,6 +8,7 @@ faults. use this tree while iterating on the tool.
 
 | area | doc | what it exercises |
 | --- | --- | --- |
+| **setup** | [**how to set up**](how-to-set-up.md) | install / clone / use as a library + links to the repo & npm |
 | start | [getting started](getting-started.md) | headings h1-h6, code, tables, anchors, a valid diagram |
 | guides | [installation](guides/installation.md) | relative links up/down, one dead link |
 | guides | [configuration](guides/configuration.md) | explicit `{#id}` anchors, a missing-anchor link |

package/docs/how-to-set-up.md

@@ -0,0 +1,130 @@
+# how to set up projview
+
+Everything you need to **install, run, or hack on** projview - a tiny local
+previewer for markdown + mermaid files.
+
+- 📦 npm: <https://www.npmjs.com/package/projview>
+- 🐙 repo: <https://github.com/vikingsearth/projview>
+- 🐛 issues: <https://github.com/vikingsearth/projview/issues>
+
+## requirements
+
+| need | version |
+| --- | --- |
+| Node.js | **18+** |
+| npm | ships with Node |
+
+No build step, no database - indexing is in-memory and nothing is written to disk.
+
+## pick your path
+
+```mermaid
+flowchart TD
+  Q{what do you want to do?}
+  Q -->|just try it, zero install| A["npx projview --demo"]
+  Q -->|preview my own docs often| B["npm i -g projview"]
+  Q -->|modify it / contribute| C["clone the repo"]
+  A --> R[browser opens on a local port]
+  B --> R
+  C --> R
+```
+
+## 1. run instantly with npx (no install)
+
+```bash
+# preview the bundled sample docs (this very doc set)
+npx projview --demo
+
+# preview the current directory
+npx projview
+
+# point it somewhere, on a chosen port, without auto-opening the browser
+npx projview ./docs --port 5000 --no-open
+```
+
+`npx` downloads + runs the latest published version, then cleans up.
+
+## 2. install the CLI globally
+
+```bash
+npm i -g projview     # adds `projview` to your PATH
+projview --demo       # try the sample docs
+projview ~/notes      # preview any directory
+```
+
+To update later: `npm i -g projview@latest`. To remove: `npm rm -g projview`.
+
+## 3. clone the repo + run from source
+
+For hacking on projview itself, or running an unpublished build:
+
+```bash
+git clone https://github.com/vikingsearth/projview.git
+cd projview
+npm install
+
+npm run demo                 # preview the bundled docs/  (alias for --demo)
+npm start                    # index the current directory
+node bin/projview.js ./docs  # or call the CLI directly
+npm test                     # run the test suite (node:test, 23 tests)
+```
+
+See the [project README](README.md) for the architecture and the
+[api reference](reference/api.md) for the HTTP surface.
+
+## CLI reference
+
+| argument / flag | meaning |
+| --- | --- |
+| `[path]` | directory to index (default: current directory) |
+| `--demo` | preview projview's own bundled sample docs |
+| `-p`, `--port <n>` | preferred port (default `4321`, climbs if taken) |
+| `--no-open` | don't auto-open the browser |
+| `-h`, `--help` | show help |
+
+**Environment variables** (handy for containers / servers):
+
+| var | default | use |
+| --- | --- | --- |
+| `PORT` | `4321` | port to serve on |
+| `HOST` | `127.0.0.1` | interface to bind (`0.0.0.0` to expose) |
+
+## use the source directly (advanced)
+
+The server is a small ES module you can embed. There's no stable public API yet,
+so treat this as internal:
+
+```js
+import { startServer } from 'projview/src/server.js';
+
+const { port, close } = await startServer(process.cwd(), { port: 4321, host: '127.0.0.1' });
+console.log(`serving on http://127.0.0.1:${port}`);
+// ... later
+await close();
+```
+
+The client is plain ES modules under `public/` (`main.js` wires it together) -
+no bundler, so you can read and tweak it directly.
+
+## run it as a container (optional)
+
+The repo ships a `Dockerfile` that serves the demo docs on port `8080`:
+
+```bash
+docker build -t projview-demo .
+docker run -p 8080:8080 projview-demo   # then open http://localhost:8080
+```
+
+> Behind a TLS-intercepting proxy? Pass your corporate CA as a build secret:
+> `docker build --secret id=cacert,src=corp-ca.pem -t projview-demo .` - the
+> cert is used only during install and never written into an image layer.
+
+## links & references
+
+| | |
+| --- | --- |
+| repository | <https://github.com/vikingsearth/projview> |
+| npm package | <https://www.npmjs.com/package/projview> |
+| report a bug | <https://github.com/vikingsearth/projview/issues> |
+| license | MIT |
+| more docs | [getting started](getting-started.md) · [api reference](reference/api.md) · [glossary](reference/glossary.md) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "projview",
-  "version": "0.1.0",
+  "version": "0.2.4",
   "description": "Ephemeral local previewer for markdown + mermaid files in any directory",
   "type": "module",
   "bin": {

package/public/index.html

@@ -9,15 +9,24 @@
   <title>projview</title>
   <link rel="stylesheet" href="/vendor/hljs.css" />
   <link rel="stylesheet" href="/style.css" />
-  <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>📓</text></svg>" />
+  <link rel="icon" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none'><rect x='2' y='4.5' width='20' height='15' rx='4' stroke='%23b4befe' stroke-width='1.8'/><line x1='8.5' y1='4.5' x2='8.5' y2='19.5' stroke='%23b4befe' stroke-width='1.8'/><circle cx='13.4' cy='9.4' r='1.25' fill='%23cba6f7'/><circle cx='18' cy='9.4' r='1.25' fill='%23cba6f7'/><circle cx='15.7' cy='14.6' r='1.25' fill='%23cba6f7'/></svg>" />
 </head>
 <body class="toc-empty">
   <aside id="sidebar">
     <header id="brand">
-      <span class="logo">📓</span>
+      <span class="logo" aria-hidden="true">
+        <svg viewBox="0 0 24 24" width="26" height="26" fill="none">
+          <rect x="2" y="4.5" width="20" height="15" rx="4" stroke="#b4befe" stroke-width="1.8"/>
+          <line x1="8.5" y1="4.5" x2="8.5" y2="19.5" stroke="#b4befe" stroke-width="1.8"/>
+          <circle cx="13.4" cy="9.4" r="1.25" fill="#cba6f7"/>
+          <circle cx="18" cy="9.4" r="1.25" fill="#cba6f7"/>
+          <circle cx="15.7" cy="14.6" r="1.25" fill="#cba6f7"/>
+          <path d="M13.4 9.4 15.7 14.6 18 9.4" stroke="#cba6f7" stroke-width="1.3" stroke-linecap="round" stroke-linejoin="round"/>
+        </svg>
+      </span>
       <div class="brand-text">
-        <strong id="root-name">projview</strong>
-        <small id="live-status"><span class="dot"></span> live</small>
+        <strong class="wordmark"><span class="wm-proj">proj</span><span class="wm-view">view</span></strong>
+        <small id="version" class="version"></small>
       </div>
     </header>
     <button id="open-palette" class="open-palette" title="search (⌘K)">

package/public/live.js

@@ -5,7 +5,7 @@ import { state } from './store.js';
 import { loadTree } from './tree.js';
 import { openFile } from './viewer.js';
 
-const liveStatusEl = $('live-status');
+const versionEl = $('version');
 
 export function connectEvents() {
   const es = new EventSource('/api/events');
@@ -14,18 +14,12 @@ export function connectEvents() {
     if (path === state.currentPath) { pulse(); openFile(path); }
   });
   es.addEventListener('tree', async () => { pulse(); await loadTree(); });
-  es.onerror = () => setLive(false);
-  es.addEventListener('ready', () => setLive(true));
-}
-
-function setLive(on) {
-  liveStatusEl.classList.toggle('off', !on);
-  liveStatusEl.querySelector('.dot')?.classList.toggle('off', !on);
 }
 
+// brief flash of the version line as live-reload feedback
 let pulseTimer;
 function pulse() {
-  liveStatusEl.classList.add('pulse');
+  versionEl.classList.add('pulse');
   clearTimeout(pulseTimer);
-  pulseTimer = setTimeout(() => liveStatusEl.classList.remove('pulse'), 600);
+  pulseTimer = setTimeout(() => versionEl.classList.remove('pulse'), 700);
 }

package/public/style.css

@@ -58,40 +58,23 @@ body {
 #brand {
   display: flex;
   align-items: center;
-  gap: 12px;
-  padding: 18px 16px;
+  gap: 11px;
+  padding: 16px 16px;
   border-bottom: 2px solid var(--surface0);
 }
 
-#brand .logo {
-  font-size: 28px;
-  filter: drop-shadow(0 2px 4px rgba(0, 0, 0, 0.4));
-}
+#brand .logo svg { display: block; filter: drop-shadow(0 2px 4px rgba(0, 0, 0, 0.35)); }
 
-.brand-text { display: flex; flex-direction: column; line-height: 1.2; }
-.brand-text strong { font-size: 17px; color: var(--lavender); letter-spacing: 0.2px; }
+.brand-text { display: flex; flex-direction: column; line-height: 1.25; }
+.wordmark { font-size: 17px; font-weight: 800; letter-spacing: 0.2px; }
+.wordmark .wm-proj { color: var(--lavender); }
+.wordmark .wm-view { color: var(--mauve); }
 
-#live-status {
-  display: inline-flex;
-  align-items: center;
-  gap: 6px;
-  color: var(--green);
-  font-size: 12px;
-  font-weight: 600;
-}
-#live-status .dot {
-  width: 8px; height: 8px; border-radius: 50%;
-  background: var(--green);
-  box-shadow: 0 0 8px var(--green);
-  transition: background 0.2s, box-shadow 0.2s;
-}
-#live-status.off { color: var(--overlay); }
-#live-status .dot.off { background: var(--overlay); box-shadow: none; }
-#live-status.pulse .dot { animation: blip 0.6s ease; }
-@keyframes blip {
-  0% { transform: scale(1); }
-  40% { transform: scale(2.2); }
-  100% { transform: scale(1); }
+.version { color: var(--overlay); font-size: 11px; font-weight: 500; letter-spacing: 0.3px; }
+.version.pulse { animation: vpulse 0.7s ease; }
+@keyframes vpulse {
+  0% { color: var(--green); }
+  100% { color: var(--overlay); }
 }
 
 .open-palette {

package/public/toc.js

@@ -8,6 +8,11 @@ const viewerEl = $('viewer');
 const tocListEl = $('toc-list');
 
 let tocEntries = [];   // [{ id, el, link }]
+let spyLock = 0;       // timestamp until which scroll-spy yields to a click
+
+function setActive(current) {
+  for (const entry of tocEntries) entry.link.classList.toggle('active', entry === current);
+}
 
 export function buildToc() {
   const headings = [...contentEl.querySelectorAll('h1, h2, h3')].filter((h) => h.id);
@@ -23,22 +28,27 @@ export function buildToc() {
     const link = document.createElement('button');
     link.className = `toc-item lvl-${h.tagName.toLowerCase()}`;
     link.textContent = h.textContent;
-    link.addEventListener('click', () => scrollToFragment(h.id));
+    const entry = { id: h.id, el: h, link };
+    link.addEventListener('click', () => {
+      scrollToFragment(h.id);
+      setActive(entry);                       // clicked item wins immediately
+      spyLock = performance.now() + 700;      // and holds briefly against scroll-spy
+    });
     frag.appendChild(link);
-    tocEntries.push({ id: h.id, el: h, link });
+    tocEntries.push(entry);
   }
   tocListEl.replaceChildren(frag);
   updateScrollSpy();
 }
 
 function updateScrollSpy() {
-  if (!tocEntries.length) return;
+  if (!tocEntries.length || performance.now() < spyLock) return;   // a recent click wins
   const top = viewerEl.scrollTop + 90;
   let current = tocEntries[0];
   for (const entry of tocEntries) {
     if (entry.el.offsetTop <= top) current = entry; else break;
   }
-  for (const entry of tocEntries) entry.link.classList.toggle('active', entry === current);
+  setActive(current);
 }
 
 let spyRaf = 0;

package/public/tree.js

@@ -7,16 +7,16 @@ import { openFile } from './viewer.js';
 
 const treeEl = $('tree');
 const fileCountEl = $('file-count');
-const rootNameEl = $('root-name');
+const versionEl = $('version');
 let fileCount = 0;
 
 export async function loadTree() {
   const res = await fetch('/api/tree');
-  const { root, tree } = await res.json();
+  const { root, tree, version } = await res.json();
   state.treeData = tree;
   state.rootName = root;
-  rootNameEl.textContent = root;
   document.title = `${root} · projview`;
+  if (version) versionEl.textContent = `version ${version}`;
   renderTree();
 }
 

package/public/viewer.js

@@ -37,7 +37,9 @@ export async function openFile(p, fragment, highlight) {
 }
 
 export function scrollToFragment(frag) {
-  const el = document.getElementById(frag);
+  // headings are rendered with a "pv-" id prefix (collision-proof); try that
+  // first, then fall back to a raw id and an already-prefixed value (TOC).
+  const el = document.getElementById(`pv-${frag}`) || 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`);

package/src/render.js

@@ -77,7 +77,9 @@ md.core.ruler.push('heading_anchors', (state) => {
     let n = 1;
     while (used[unique]) unique = `${id}-${n++}`;
     used[unique] = true;
-    tokens[i].attrSet('id', unique);
+    // prefix so heading ids can never collide with the app's own element ids
+    // (e.g. a "## viewer" heading vs the <main id="viewer"> container)
+    tokens[i].attrSet('id', `pv-${unique}`);
   }
 });
 

package/src/server.js

@@ -11,6 +11,7 @@ import { buildIndex, updateFile, removeFile, search } from './search.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PUBLIC_DIR = path.join(__dirname, '..', 'public');
+const VERSION = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8')).version;
 // vendored client libs (mermaid bundle, hljs theme) live in public/vendor/ and
 // are served by the static handler below - no node_modules resolution needed.
 
@@ -72,7 +73,7 @@ export async function startServer(root, { port = 4321, host = '127.0.0.1' } = {}
 
     // --- file tree ---
     if (pathname === '/api/tree') {
-      sendJson(res, { root: path.basename(root) || root, tree: buildTree(root) });
+      sendJson(res, { root: path.basename(root) || root, tree: buildTree(root), version: VERSION });
       return;
     }