projview 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wikus Bergh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# projview
+
+ephemeral local previewer for **markdown** + **mermaid** files. run it in any
+directory, get a soft-dark cartoonish localhost view of every `.md` / `.mmd`
+under it, close it and nothing's left behind.
+
+## install
+
+```bash
+npm i -g projview     # global CLI
+# or run without installing:
+npx projview
+```
+
+## usage
+
+```bash
+# try it on the bundled sample docs (no setup needed)
+projview --demo
+
+# from the directory you want to browse
+projview
+
+# or point it somewhere
+projview ./docs --port 5000
+projview /path/to/notes --no-open
+```
+
+## what it does
+
+| step | detail |
+| --- | --- |
+| walk | recursively finds `.md` / `.mmd`, skips `node_modules`, `dist`, dot-dirs |
+| index | builds an in-memory tree (nothing written to disk) |
+| serve | spawns a localhost site + opens your browser |
+| live | edits to files reload in the browser automatically |
+
+> ctrl-c and it's gone - "indexing" is never persisted.
+
+see [samples/architecture.md](samples/architecture.md) for a mermaid demo.

package/bin/projview.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { startServer } from '../src/server.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DEMO_DIR = path.join(__dirname, '..', 'docs');   // bundled sample docs
+
+function parseArgs(argv) {
+  const opts = {
+    root: process.cwd(),
+    port: Number(process.env.PORT) || 4321,
+    host: process.env.HOST || '127.0.0.1',
+    open: true
+  };
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    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 === '--help' || arg === '-h') opts.help = true;
+    else rest.push(arg);
+  }
+  if (rest[0]) opts.root = path.resolve(process.cwd(), rest[0]);
+  if (opts.demo) opts.root = DEMO_DIR;
+  return opts;
+}
+
+function openBrowser(url) {
+  const cmd = process.platform === 'darwin' ? 'open'
+    : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+  try {
+    spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
+  } catch { /* no browser, just print the url */ }
+}
+
+const HELP = `projview - ephemeral previewer for markdown + mermaid
+
+usage:
+  projview [path] [options]
+
+arguments:
+  path              directory to index (default: current directory)
+
+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
+  -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;
+  }
+
+  const { port, close } = await startServer(opts.root, { port: opts.port, host: opts.host });
+  const url = `http://${opts.host}:${port}`;
+
+  console.log(`\n  projview  ->  ${url}`);
+  console.log(`  indexing  ->  ${opts.root}`);
+  console.log(`  (ctrl-c to stop - nothing is persisted)\n`);
+
+  if (opts.open) openBrowser(url);
+
+  const shutdown = async () => {
+    await close();
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+main().catch((err) => {
+  console.error('projview failed to start:', err.message);
+  process.exit(1);
+});

package/docs/README.md

@@ -0,0 +1,28 @@
+# projview test docs
+
+a deliberately mixed doc set - **most of it should render perfectly**, and a
+few files contain **intentional breakage** so we can test how projview handles
+faults. use this tree while iterating on the tool.
+
+## index
+
+| area | doc | what it exercises |
+| --- | --- | --- |
+| 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 |
+| guides | [troubleshooting](guides/troubleshooting.md) | a link to a file that doesn't exist |
+| diagrams | [architecture](diagrams/architecture.mmd) | standalone valid flowchart |
+| diagrams | [sequence](diagrams/sequence.mmd) | standalone valid sequence |
+| diagrams | [broken diagram](diagrams/broken-diagram.mmd) | **invalid mermaid** - error card test |
+| reference | [api](reference/api.md) | long doc - TOC + scroll-spy |
+| reference | [glossary](reference/glossary.md) | cross-links + external links |
+| edge | [syntax stress](edge-cases/syntax-stress.md) | gnarly markdown + inline broken fence |
+| edge | [faulty refs](edge-cases/faulty-refs.md) | **several dead links** on purpose |
+| edge | [buried file](edge-cases/deep/nested/buried.md) | deep nesting - indentation + auto-expand |
+
+## intentional faults (should NOT crash the app)
+
+- a dead link right here: [this file is missing](does-not-exist.md)
+- an external link: [anthropic](https://www.anthropic.com)
+- a link to a missing anchor: [no such section](#nope)

package/docs/diagrams/architecture.mmd

@@ -0,0 +1,9 @@
+flowchart LR
+  subgraph cli[projview CLI]
+    walk[walk fs] --> tree[in-mem tree]
+  end
+  tree --> server[http server]
+  server -->|/api/tree| browser
+  server -->|/api/file| browser
+  server -. SSE .-> browser
+  browser --> render[rendered view]

package/docs/diagrams/broken-diagram.mmd

@@ -0,0 +1,5 @@
+flowchart LR
+  A[start] --> B{missing closing brace
+  B --> C[this will never parse]
+  C -->|no arrow target
+  %% intentionally broken mermaid to exercise the inline error card

package/docs/diagrams/sequence.mmd

@@ -0,0 +1,13 @@
+sequenceDiagram
+  autonumber
+  participant U as user
+  participant C as CLI
+  participant B as browser
+  U->>C: projview ./docs
+  C->>C: walk + index
+  C->>B: open localhost
+  B->>C: GET /api/tree
+  C-->>B: tree json
+  B->>C: GET /api/file?p=...
+  C-->>B: rendered html
+  Note over C,B: edit a file -> SSE -> live reload

package/docs/edge-cases/deep/nested/buried.md

@@ -0,0 +1,11 @@
+# buried file
+
+I live at `edge-cases/deep/nested/buried.md` - four levels deep.
+
+Use me to check:
+
+- the indent guides clearly show how deep this is
+- navigating here via a link auto-expands `edge-cases → deep → nested`
+- the breadcrumb at the top shows the full path
+
+[back up to the index](../../../README.md)

package/docs/edge-cases/faulty-refs.md

@@ -0,0 +1,23 @@
+# faulty refs
+
+Every internal link here is broken on purpose. None should crash the app;
+each should land on the "not found" state (for files) or no-op (for anchors).
+
+## dead file links
+
+- [sibling that doesn't exist](nonexistent.md)
+- [up into a missing folder](../../way/up/gone.md)
+- [a missing .mmd](missing-diagram.mmd)
+
+## dead anchors
+
+- [missing anchor on this page](#not-a-real-heading)
+
+## non-previewable (should be ignored, not navigated)
+
+- [an image link](../assets/picture.png)
+- [a pdf link](../assets/manual.pdf)
+
+## one valid link for contrast
+
+- [back to the index](../README.md)

package/docs/edge-cases/syntax-stress.md

@@ -0,0 +1,48 @@
+# syntax stress
+
+Gnarly-but-valid markdown, plus one broken inline fence.
+
+## nested everything
+
+> blockquote
+> > nested blockquote
+> > > triple nested
+
+1. ordered
+   1. nested ordered
+      - mixed bullet
+        ```js
+        const deep = "code in a list";
+        ```
+2. back to top level
+
+## inline html
+
+<details>
+<summary>click to expand (raw html)</summary>
+
+Hidden content with a <kbd>Ctrl</kbd>+<kbd>K</kbd> hint.
+
+</details>
+
+## a table with code + pipes
+
+| token | meaning |
+| --- | --- |
+| `a \| b` | escaped pipe |
+| `` `code` `` | literal backticks |
+
+## broken mermaid fence (inline)
+
+The diagram below is malformed - it should become an error card, and the rest
+of the page must still render fine:
+
+```mermaid
+flowchart TD
+  X[ no closing bracket
+  X --> Y -->
+```
+
+## after the broken fence
+
+This paragraph proves rendering continued past the broken diagram.

package/docs/getting-started.md

@@ -0,0 +1,66 @@
+# getting started
+
+a kitchen-sink markdown file. the TOC on the right should list **only** the
+h1/h2/h3 headings below - the h4/h5/h6 ones must be ignored.
+
+## section one - text
+
+Some prose with **bold (peach)**, _italic_, `inline code`, and a
+[link back to the index](README.md). Also a [jump to section three](#section-three---a-diagram).
+
+### subsection 1a
+
+A nested heading - should appear in the TOC.
+
+#### h4 should be hidden
+
+##### h5 should be hidden
+
+###### h6 should be hidden
+
+## section two - code + tables
+
+```js
+// javascript, highlighted
+export function add(a, b) {
+  return a + b;
+}
+```
+
+```bash
+# a shell block
+npx projview ./docs --port 4500
+```
+
+```python
+def greet(name: str) -> str:
+    return f"hello {name}"
+```
+
+| col a | col b | col c |
+| --- | --- | --- |
+| 1 | two | three |
+| 4 | five | six |
+
+### subsection 2a - lists
+
+- bullet one
+- bullet two
+  - nested bullet
+    - deeper
+- [ ] unchecked task
+- [x] checked task
+
+## section three - a diagram
+
+```mermaid
+flowchart TD
+  A[start] --> B{valid?}
+  B -->|yes| C[render]
+  B -->|no| D[error card]
+  C --> E[done]
+  D --> E
+```
+
+> if the diagram above rendered and the TOC shows three h2s + two h3s (no h4-h6),
+> this file passes.

package/docs/guides/configuration.md

@@ -0,0 +1,29 @@
+# configuration
+
+Tests explicit `{#id}` heading anchors and a link to a **missing** anchor.
+
+## ports {#ports}
+
+projview picks a free port starting at 4321. Jump target: [#ports](#ports).
+
+## env overrides {#env-overrides}
+
+Set `PROJVIEW_PORT` to pin a port. This heading has an explicit id so
+`configuration.md#env-overrides` resolves to it.
+
+## a valid diagram
+
+```mermaid
+sequenceDiagram
+  participant CLI
+  participant Server
+  CLI->>Server: start(root, port)
+  Server-->>CLI: listening
+```
+
+## broken anchor link
+
+This link points at an anchor that doesn't exist on this page - it should
+no-op gracefully (no jump, no crash): [go nowhere](#this-anchor-is-missing).
+
+Back to [installation](installation.md).

package/docs/guides/installation.md

@@ -0,0 +1,22 @@
+# installation
+
+Tests relative links that go **up** and **sideways** in the tree.
+
+## prerequisites
+
+- node 18+
+- a directory with `.md` / `.mmd` files
+
+## steps
+
+1. see the [project index](../README.md) (up one level)
+2. then read [configuration](configuration.md) (same folder)
+3. if stuck, the [troubleshooting guide](troubleshooting.md) (same folder)
+4. jump straight to [a config anchor](configuration.md#env-overrides) (cross-doc anchor)
+
+## a deliberately dead link
+
+This one points at a file that does not exist - clicking it should show a
+friendly "not found" state, not a blank screen:
+
+[missing page](./does-not-exist.md)

package/docs/guides/troubleshooting.md

@@ -0,0 +1,17 @@
+# troubleshooting
+
+## diagram won't render?
+
+Check the browser console - a malformed diagram shows an inline error card
+instead of taking down the page. See [the broken diagram](../diagrams/broken-diagram.mmd).
+
+## link goes nowhere?
+
+Internal links to files that don't exist show a "not found" state. Example of a
+link to a file in a folder that doesn't even exist:
+
+[ghost doc](../nope/ghost.md)
+
+## still stuck?
+
+Open an issue (external): [github](https://github.com/anthropics/claude-code/issues).

package/docs/reference/api.md

@@ -0,0 +1,82 @@
+# api reference
+
+A long document on purpose - enough h2/h3 sections to test the right-side TOC
+and scroll-spy (the active section should track as you scroll).
+
+## overview
+
+projview exposes a tiny HTTP surface. Everything is read-only and in-memory.
+
+## endpoints
+
+### GET /api/tree
+
+Returns the in-memory file tree as JSON.
+
+### GET /api/file
+
+Renders a single file to HTML on demand. Query param `p` is the relative path.
+
+### GET /api/events
+
+Server-sent events stream for live reload.
+
+## the walker
+
+### ignored directories
+
+`node_modules`, `dist`, `build`, dot-dirs, and friends are skipped.
+
+### previewable extensions
+
+`.md` and `.mmd` for now. Images and mdx are deferred.
+
+## the renderer
+
+### markdown
+
+markdown-it with highlight.js for fenced code.
+
+### mermaid fences
+
+A ```` ```mermaid ```` fence becomes a div the client renders.
+
+### heading anchors
+
+Every heading gets a slug id; explicit `{#id}` wins when present.
+
+## the server
+
+### static assets
+
+The SPA shell plus vendored mermaid + hljs css.
+
+### path safety
+
+Requested paths are resolved and confined to the root.
+
+## the client
+
+### tree nav
+
+Collapsible dirs, filter box, auto-expand on navigate.
+
+### viewer
+
+On-demand fetch + render, in-app link routing, anchor jumps.
+
+### live reload
+
+A chokidar watcher broadcasts change/tree events over SSE.
+
+## performance notes
+
+Indexing is just a directory walk - no persistence, no cache files.
+
+## limitations
+
+No auth, localhost only, single root per process. By design.
+
+## wrap up
+
+If the TOC tracked your scroll position through these sections, scroll-spy works.

package/docs/reference/glossary.md

@@ -0,0 +1,16 @@
+# glossary
+
+Cross-links plus external links.
+
+## terms
+
+- **index** - the in-memory file tree. See [the api](api.md#the-walker).
+- **previewable** - a `.md` or `.mmd` file. See [extensions](api.md#previewable-extensions).
+- **live reload** - SSE-driven refresh. See [events](api.md#get-apievents).
+
+## see also
+
+- [getting started](../getting-started.md)
+- [configuration](../guides/configuration.md#env-overrides)
+- external: [markdown-it](https://github.com/markdown-it/markdown-it)
+- external: [mermaid](https://mermaid.js.org)

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "projview",
+  "version": "0.1.0",
+  "description": "Ephemeral local previewer for markdown + mermaid files in any directory",
+  "type": "module",
+  "bin": {
+    "projview": "bin/projview.js"
+  },
+  "scripts": {
+    "start": "node bin/projview.js",
+    "demo": "node bin/projview.js --demo",
+    "test": "node --test"
+  },
+  "files": [
+    "bin",
+    "src",
+    "public",
+    "docs"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "markdown",
+    "mermaid",
+    "preview",
+    "docs",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "Wikus Bergh (https://github.com/vikingsearth)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vikingsearth/projview.git"
+  },
+  "homepage": "https://github.com/vikingsearth/projview#readme",
+  "bugs": {
+    "url": "https://github.com/vikingsearth/projview/issues"
+  },
+  "dependencies": {
+    "chokidar": "^4.0.3",
+    "highlight.js": "^11.11.1",
+    "markdown-it": "^14.1.0"
+  }
+}

package/public/breadcrumb.js

@@ -0,0 +1,39 @@
+/* clickable path breadcrumb at the top of the viewer */
+
+import { $ } from './dom.js';
+import { state } from './store.js';
+import { revealDir } from './tree.js';
+
+const breadcrumbEl = $('breadcrumb');
+
+export function renderBreadcrumb(p) {
+  if (!p) { breadcrumbEl.hidden = true; return; }
+  breadcrumbEl.hidden = false;
+  const parts = p.split('/');
+  const frag = document.createDocumentFragment();
+
+  const root = document.createElement('span');
+  root.className = 'crumb root';
+  root.textContent = state.rootName;
+  frag.appendChild(root);
+
+  let acc = '';
+  parts.forEach((seg, i) => {
+    const sep = document.createElement('span');
+    sep.className = 'crumb-sep';
+    sep.textContent = '/';
+    frag.appendChild(sep);
+
+    acc = acc ? `${acc}/${seg}` : seg;
+    const isFile = i === parts.length - 1;
+    const crumb = document.createElement(isFile ? 'span' : 'button');
+    crumb.className = 'crumb' + (isFile ? ' current' : ' dir');
+    crumb.textContent = seg;
+    if (!isFile) {
+      const dirPath = acc;
+      crumb.addEventListener('click', () => revealDir(dirPath));
+    }
+    frag.appendChild(crumb);
+  });
+  breadcrumbEl.replaceChildren(frag);
+}

package/public/dom.js

@@ -0,0 +1,11 @@
+/* tiny DOM helpers shared across modules */
+
+export const $ = (id) => document.getElementById(id);
+
+export function esc(s) {
+  return s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
+}
+
+export function cssEsc(s) {
+  return (window.CSS && CSS.escape) ? CSS.escape(s) : s.replace(/"/g, '\\"');
+}

package/public/icons.js

@@ -0,0 +1,7 @@
+/* small monochrome inline icons (inherit currentColor) - shared by tree + palette */
+
+export const SVG_FOLDER = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M3 7a2 2 0 0 1 2-2h3.6l2 2H19a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/></svg>`;
+export const SVG_FILE = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8z"/><path d="M14 3v5h5"/></svg>`;
+export const SVG_DIAGRAM = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="18" cy="5" r="2.6"/><circle cx="6" cy="12" r="2.6"/><circle cx="18" cy="19" r="2.6"/><line x1="8.4" y1="10.7" x2="15.6" y2="6.3"/><line x1="8.4" y1="13.3" x2="15.6" y2="17.7"/></svg>`;
+
+export const fileIcon = (ext) => (ext === '.mmd' ? SVG_DIAGRAM : SVG_FILE);