{"_id":"@agent-wiki/graph-viewer","_rev":"2-38e02cfed6e882a0e347fad5b94ab03a","name":"@agent-wiki/graph-viewer","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.1":{"name":"@agent-wiki/graph-viewer","version":"0.1.1","keywords":["agent-wiki","knowledge-graph","3d","visualization"],"author":{"name":"Xinhua Chen"},"license":"MIT","_id":"@agent-wiki/graph-viewer@0.1.1","maintainers":[{"name":"xinhua_berlin","email":"xinhua.gu@gmail.com"}],"homepage":"https://github.com/xinhuagu/agent-wiki/tree/main/graph-viewer#readme","bugs":{"url":"https://github.com/xinhuagu/agent-wiki/issues"},"bin":{"agent-wiki-graph":"dist/cli.js"},"dist":{"shasum":"a3e7d50de85a1de009e0b1af6ec99af73254b8b3","tarball":"https://registry.npmjs.org/@agent-wiki/graph-viewer/-/graph-viewer-0.1.1.tgz","fileCount":29,"integrity":"sha512-DOkFG4gVYDLDvOnTunORr+ixdcq4D+eTgDjruOG3jwWRUDMztUMhdOZ/fI7p09lpqJ3HGp7fhlgejlvGs/rrKw==","signatures":[{"sig":"MEYCIQDDmIOwP6/0G+Xg6wpI8cdQ3kkc8S2hIfUb/Bk2+20dBwIhAL8auIFnurn6HFBv6kVQ1KcbA1Je1zqu032ldbmGCEs1","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@agent-wiki%2fgraph-viewer@0.1.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":68803},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20.19.0 || >=22.13.0 || >=24"},"gitHead":"ddf6d441ae0f69afab8949407ad5b8196850b825","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","start":"node dist/cli.js"},"_npmUser":{"name":"xinhua_berlin","email":"xinhua.gu@gmail.com"},"repository":{"url":"git+https://github.com/xinhuagu/agent-wiki.git","type":"git","directory":"graph-viewer"},"_npmVersion":"10.9.7","description":"Realtime 3D knowledge graph viewer for agent-wiki. Standalone — zero runtime dependency on core.","directories":{},"_nodeVersion":"22.22.2","dependencies":{"gray-matter":"^4.0.3"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.2","typescript":"^5.8.3","@types/node":"^22.15.3"},"_npmOperationalInternal":{"tmp":"tmp/graph-viewer_0.1.1_1776875722278_0.48165458839593134","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@agent-wiki/graph-viewer","version":"0.1.2","description":"Realtime 3D knowledge graph viewer for agent-wiki. Standalone — zero runtime dependency on core.","type":"module","bin":{"agent-wiki-graph":"dist/cli.js"},"main":"./dist/index.js","types":"./dist/index.d.ts","scripts":{"build":"tsc","dev":"tsc --watch","test":"vitest run","start":"node dist/cli.js"},"keywords":["agent-wiki","knowledge-graph","3d","visualization"],"author":{"name":"Xinhua Chen"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/xinhuagu/agent-wiki.git","directory":"graph-viewer"},"homepage":"https://github.com/xinhuagu/agent-wiki/tree/main/graph-viewer#readme","bugs":{"url":"https://github.com/xinhuagu/agent-wiki/issues"},"publishConfig":{"access":"public"},"engines":{"node":">=20.19.0 || >=22.13.0 || >=24"},"dependencies":{"gray-matter":"^4.0.3"},"devDependencies":{"@types/node":"^22.15.3","typescript":"^5.8.3","vitest":"^4.1.2"},"_id":"@agent-wiki/graph-viewer@0.1.2","gitHead":"7bce57400c54fa616e19ee5b32c5a80230f2b773","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-tdOb47g1Ci5BZrPIm64T597/nI7wTDy9uruGyo2ds9cOUxIBfNOdIBoX4QrI18hBGNiSXXLPInG87UmJrcM58Q==","shasum":"a01bdf78f6d1a88e4ed34bf97eec0b091a4f626f","tarball":"https://registry.npmjs.org/@agent-wiki/graph-viewer/-/graph-viewer-0.1.2.tgz","fileCount":29,"unpackedSize":70254,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@agent-wiki%2fgraph-viewer@0.1.2","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCHPA47ISAU0R2F2ICrUUXEgOJts80R1rMiP7EYJKFgtgIhAPWZIRidLJOtUfViubt8NdvYxxezufH2Yj6gTkcSuv4I"}]},"_npmUser":{"name":"xinhua_berlin","email":"xinhua.gu@gmail.com"},"directories":{},"maintainers":[{"name":"xinhua_berlin","email":"xinhua.gu@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/graph-viewer_0.1.2_1776982481807_0.32330688580853684"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-22T16:35:22.206Z","modified":"2026-04-23T22:14:42.222Z","0.1.1":"2026-04-22T16:35:22.415Z","0.1.2":"2026-04-23T22:14:41.949Z"},"bugs":{"url":"https://github.com/xinhuagu/agent-wiki/issues"},"author":{"name":"Xinhua Chen"},"license":"MIT","homepage":"https://github.com/xinhuagu/agent-wiki/tree/main/graph-viewer#readme","keywords":["agent-wiki","knowledge-graph","3d","visualization"],"repository":{"type":"git","url":"git+https://github.com/xinhuagu/agent-wiki.git","directory":"graph-viewer"},"description":"Realtime 3D knowledge graph viewer for agent-wiki. Standalone — zero runtime dependency on core.","maintainers":[{"name":"xinhua_berlin","email":"xinhua.gu@gmail.com"}],"readme":"# @agent-wiki/graph-viewer\n\nStandalone realtime 3D knowledge graph viewer for an agent-wiki workspace.\nEdit a `.md` file — the graph updates live.\n\n## Zero coupling with core\n\nThis package is **physically and functionally independent** from\n`@agent-wiki/mcp-server`:\n\n- Core `agent-wiki` does not import, require, or depend on this package.\n- This package reads a wiki directory as plain Markdown (frontmatter +\n  `[[wikilinks]]`).\n- Removing the `graph-viewer/` directory leaves core MCP / CLI / search / lint\n  / raw behavior unchanged.\n- Heavy rendering libraries (`3d-force-graph`, `three.js`) are loaded in the\n  browser from a CDN and never ship with the core server.\n\n## Quick start\n\nAfter publishing, three equivalent ways to launch:\n\n```bash\n# 1. Through the core CLI (thin handoff — installs nothing in core, resolves\n#    and spawns this package at runtime). Needs both packages installed.\nnpm install -g @agent-wiki/mcp-server @agent-wiki/graph-viewer\nagent-wiki web --wiki-path ./wiki --open\n\n# 2. Standalone binary, after installing this package:\nnpm install -g @agent-wiki/graph-viewer\nagent-wiki-graph -w ./wiki\n\n# 3. Zero install:\nnpx @agent-wiki/graph-viewer --wiki-path /path/to/wiki --open\n```\n\nFrom this repo before publishing, once the package is built:\n\n```bash\nnode graph-viewer/dist/cli.js -w ./wiki --port 4711 --open\n```\n\nThen open http://localhost:4711. Editing any Markdown file under the wiki\ndirectory pushes an incremental graph update over SSE.\n\n### CLI flags\n\n| flag | alias | default | description |\n| --- | --- | --- | --- |\n| `--wiki-path <dir>` | `-w` | — (required) | path to the wiki directory |\n| `--port <n>` | `-p` | `4711` | HTTP port |\n| `--host <host>` | | `127.0.0.1` | bind host |\n| `--open` | | off | open the browser on startup |\n| `--help` | `-h` | | show help |\n\n## Visual language\n\n- **Nodes** are small pastel dots — one per `.md` page. Size grows gently with\n  degree. Color is deterministic from topic (first-level directory), primary\n  tag, or frontmatter `type`, selectable in the top bar.\n- **Index hubs** (`index.md` at root or any `topic/index.md`) render about 2×\n  the size of regular pages with a brighter topic-tinted shade so each topic\n  cluster has a visible anchor. The root index uses a warm-white tone.\n- **Links** are GPU hairlines — a quiet network backdrop that never dominates.\n  Hovering or clicking a node lifts the 2-hop neighborhood's edges into a soft\n  lavender; edges outside the neighborhood are slightly darkened but **not**\n  wiped out, so the rest of the graph is still readable.\n- **Selection**: clicked node turns bright yellow. Non-neighborhood nodes keep\n  their original colors — no screen-wide \"gray flash.\"\n- **Broken links** are soft red ghost nodes (a link to a `.md` that doesn't\n  exist). **Orphan** pages (no incoming links) are muted grey.\n- **Edit pulse**: when SSE pushes a change, every node whose content actually\n  changed — plus any new node — flashes cyan for ~1.2 s. Saves surface as\n  visual motion where the change happened, not just in the status bar.\n\n## Interactions\n\n| input | effect |\n| --- | --- |\n| hover a node | highlight its 2-hop neighborhood edges |\n| single-click | select + open side panel, **no** camera motion |\n| double-click (same node within 400 ms) | `zoomToFit` onto the 2-hop neighborhood |\n| drag a node | force simulation responds, node released on drop |\n| background click / `Esc` | clear selection |\n| toolbar `−` / `+` / `-` / `=` key | zoom out / in |\n| toolbar `home` / `f` or `h` key | clear selection and `zoomToFit` the graph |\n| search box | filter nodes by title or slug |\n| `color by` select | recolor palette by topic / tag / type |\n| hide orphans / hide broken | filter toggles |\n\n## Side panel\n\nClicking a node opens a right-side panel with:\n\n- title, type, topic, tags, sources, degree\n- outgoing and incoming link lists (each item is click-to-select)\n- resolved absolute file path for the Markdown file, for easy copy/paste\n\n## Status bar\n\nThe top-right status reflects the SSE stream:\n\n- `connecting…` — handshake in progress\n- `live · N nodes` — steady state\n- `live · N nodes (+k)` / `(-k)` — transient, shown for 2.5 s after node\n  count changes\n- `live · N nodes · updated` — transient, shown when content changed but the\n  node count stayed the same\n- `disconnected — retrying` — SSE dropped; it retries automatically\n- Uncaught errors or module load failures surface here too (red), so a blank\n  page never stays silent.\n\n## Architecture\n\n```\nwiki dir (*.md)\n      │\n      ├─ parse.ts       gray-matter + [[link]] regex → ParsedPage[]\n      │                 recursive .md walk\n      │\n      ├─ graph.ts       ParsedPage[] → { nodes, edges }\n      │                 slug / basename link resolution\n      │                 orphan + broken flags, self-loop drop\n      │\n      ├─ server.ts      node:http\n      │                 GET  /api/graph    current graph JSON\n      │                 GET  /api/events   SSE (graph + error channels)\n      │                 POST /api/open     resolve page path\n      │                 static /*          public/ assets\n      │                 fs.watch(recursive) + debounce → rebuild + broadcast\n      │\n      └─ public/app.js  ES module, imports 3d-force-graph & three from esm.sh\n                        force-directed layout + custom pull-to-origin force\n                        edit-pulse via rAF, selection highlights, side panel\n```\n\n## Development\n\n```bash\ncd graph-viewer\nnpm install\nnpm run build     # tsc → dist/\nnpm test          # vitest: parse + graph + http/SSE smoke (19 tests)\nnpm run dev       # tsc --watch\n```\n\nThe server disables browser caching (`Cache-Control: no-store`) so editing\n`public/app.js` or `public/style.css` is a hard-refresh away — no restart\nneeded.\n\n## Removal\n\nDelete the `graph-viewer/` directory. Nothing under `src/` in the core\npackage imports it. Core build, tests, and MCP server behavior are\nunaffected.\n","readmeFilename":"README.md"}