projview 0.8.0 → 0.8.2

package/README.md

@@ -34,6 +34,9 @@ and exit (no server, no browser), so an agent or script can query your docs:
 ```bash
 projview search "<query>" [path]   # ranked: filename matches + in-content hits w/ line snippets
 projview tree [path]               # the file tree as JSON
+projview comment add <file> "…"    # leave a comment (--heading <id> to anchor a section)
+projview comments [file]           # list comments as JSON
+projview usage [path]              # views + searches recorded by the viewer
 projview search "mermaid" --demo   # quick test on the bundled docs
 ```
 
@@ -53,9 +56,19 @@ projview search "mermaid" --demo   # quick test on the bundled docs
 | index | builds an in-memory tree (nothing written to disk by default) |
 | serve | spawns a localhost site + opens your browser |
 | live | edits to files reload in the browser automatically |
+| comment | leave notes on a file, a section, or a text selection (browser or CLI) |
 
 > ephemeral by default - ctrl-c and it's gone. opt into persistence below.
 
+## comments
+
+Leave notes on a whole file, a heading/section, or a selected passage - from the
+viewer (the 💬 button, bottom-right) or via the CLI / HTTP API. Text comments
+**re-anchor** as the doc changes and only flag themselves *orphaned* if the quoted
+text truly disappears. Comments persist when you opt into a store
+(`--persist` / `--store-url`); writes are **localhost-only** (an exposed instance
+is read-only).
+
 ## persistence (opt-in)
 
 By default the index is in-memory and nothing is written to disk. Opt in for a

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

@@ -67,7 +67,7 @@ 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, 45 tests)
+npm test                     # run the test suite (node:test, 49 tests)
 ```
 
 See the [project README](README.md) for the architecture and the

package/docs/reference/api.md

@@ -12,15 +12,36 @@ state it records is its own usage events (views / searches) into the store.
 
 ### GET /api/tree
 
-Returns the in-memory file tree as JSON.
+Returns the in-memory file tree as JSON, plus the `version` and a `writable`
+flag (false when projview is exposed on a non-loopback host).
 
 ### GET /api/file
 
 Renders a single file to HTML on demand. Query param `p` is the relative path.
+Records a `view` usage event.
 
 ### GET /api/events
 
-Server-sent events stream for live reload.
+Server-sent events stream: `change` / `tree` for live reload, `comments` when a
+comment is created/edited/deleted.
+
+### GET /api/comments
+
+Lists comments as JSON. Optional `?file=<path>` filters to a single file.
+
+### POST /api/comments
+
+Creates a comment from `{ file, body, anchor?, author? }`. **Loopback only** -
+returns `403` when bound to a non-loopback host. Author defaults to the server's
+git/OS user when omitted.
+
+### PATCH /api/comments/:id · DELETE /api/comments/:id
+
+Resolve/edit (`{ resolved?, body? }`) or delete a comment. Loopback only.
+
+### GET /api/usage
+
+Aggregated usage: `{ total, byType, topFiles[], recentSearches[] }`.
 
 ## machine interface (CLI)
 
@@ -115,6 +136,13 @@ On-demand fetch + render, in-app link routing, anchor jumps.
 
 A chokidar watcher broadcasts change/tree events over SSE.
 
+### comments
+
+A drawer (the 💬 button, bottom-right) lists comments for the open file. Add one
+by selecting text, hovering a heading, or "+ note". Text anchors re-anchor on
+each render and paint via the CSS Custom Highlight API; create/resolve/delete
+controls hide when the server isn't writable.
+
 ## stores (persistence)
 
 The index - plus **comments** and **usage events** - is in-memory by default

package/package.json

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

package/public/comments.js

@@ -29,7 +29,14 @@ const cre = (tag, cls, html) => {
   return e;
 };
 
-const fab = cre('button', 'cmt-fab', '💬<span class="cmt-badge" hidden>0</span>');
+const FAB_ICON =
+  `<svg class="cmt-fab-ico" viewBox="0 0 24 24" width="23" height="23" fill="none" aria-hidden="true">
+     <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" stroke="currentColor" stroke-width="1.9" stroke-linecap="round" stroke-linejoin="round"/>
+     <circle cx="8" cy="10" r="1.05" fill="currentColor"/>
+     <circle cx="12" cy="10" r="1.05" fill="currentColor"/>
+     <circle cx="16" cy="10" r="1.05" fill="currentColor"/>
+   </svg>`;
+const fab = cre('button', 'cmt-fab', `${FAB_ICON}<span class="cmt-badge" hidden>0</span>`);
 fab.title = 'comments';
 fab.hidden = true;