@mauroandre/velojs 0.0.38 → 0.0.40

package/agent/skills/velojs-project-graph/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: velojs-project-graph
+description: "Use `.velojs/graph.json` to understand the project's route tree and module dependency graph before reading any source files. Always consult the graph first when exploring a VeloJS codebase. Generate it with `velojs graph` if missing."
+---
+
+# Project Graph
+
+VeloJS can generate a structural snapshot of your project — the route tree hierarchy, module dependency graph, and convention exports — as a single JSON file at `.velojs/graph.json`. This file gives an AI agent (or any tool) a complete map of the codebase in a few KB, replacing dozens of exploratory file reads.
+
+## When to use
+
+Always. Before reading any source file in a VeloJS project, query `.velojs/graph.json` for the specific information you need. The full file can be large; use `jq` for targeted queries.
+
+## Generating the graph
+
+If `.velojs/graph.json` does not exist, generate it:
+
+```bash
+velojs graph
+```
+
+This runs a fast Babel-based crawl of `app/routes.tsx` and its transitive imports. No build. No Vite. Sub-second. Works even if the project does not compile.
+
+The graph is also regenerated automatically on every `velojs build` (via the `velo:graph` plugin) and on every file change during `velojs dev`.
+
+## Querying the graph
+
+The graph is a compact JSON file (no whitespace). Do not read it in full — use `jq` for targeted queries:
+
+```bash
+# A single module — what it exports, what it imports, who imports it
+jq '.modules["auth/Login"]' .velojs/graph.json
+
+# The route tree (hierarchy of layouts + pages with paths and middlewares)
+jq '.routes' .velojs/graph.json
+
+# All modules that export a loader
+jq '.modules | to_entries[] | select(.value.exports.hasLoader) | .key' .velojs/graph.json
+
+# Impact analysis: what breaks if I change this service?
+jq '.modules["modules/respondent/respondent.service"] | .importedBy' .velojs/graph.json
+
+# All actions in the project (module + action name)
+jq '.modules | to_entries[] | .key as $k | .value.exports.actions[] | "\($k): action_\(.)"' .velojs/graph.json
+
+# Modules imported by a specific page
+jq '.modules["admin/DepartmentDetail"].imports' .velojs/graph.json
+
+# Which pages use a shared component?
+jq -r '.modules["components/Inputs"].importedBy[]' .velojs/graph.json \
+  | while read id; do jq -r ".modules[\"$id\"].kind" .velojs/graph.json; done \
+  | sort | uniq -c
+```
+
+## Graph structure
+
+```typescript
+interface GraphJson {
+    routes: RouteTreeNode[];
+    modules: Record<string, ModuleInfo>;
+}
+
+interface RouteTreeNode {
+    moduleId: string | null;   // e.g. "pages/Home", null if no module
+    fullPath: string | null;   // e.g. "/admin/users/:id"
+    path: string | null;       // e.g. "/users/:id"
+    isRoot: boolean;           // root layout (renders <html>)
+    middlewares: string[];     // middleware identifiers
+    children: RouteTreeNode[];
+}
+
+interface ModuleInfo {
+    file: string;              // relative path from project root
+    kind: "root" | "layout" | "page" | "unknown";
+    exports: {
+        hasComponent: boolean;
+        hasLoader: boolean;
+        actions: string[];     // e.g. ["save", "delete"]
+        streams: string[];     // e.g. ["progress", "logs"]
+        sockets: string[];     // e.g. ["terminal"]
+    };
+    imports: string[];         // moduleIds this module depends on
+    importedBy: string[];      // moduleIds that depend on this module
+}
+```
+
+## Common queries
+
+### "Which routes use this loader?"
+
+1. Find the loader's module in `modules` → note its `moduleId`
+2. Search `routes` recursively for nodes where `moduleId` matches
+3. The matching node's ancestors are the layouts wrapping it
+
+### "What breaks if I change this file?"
+
+1. Find the module in `modules[moduleId]`
+2. Follow `importedBy` — these modules import it
+3. Transitively follow `importedBy` on those modules
+4. Filter to modules where `kind` is `"page"` to see which pages are affected
+
+### "What actions does this page expose?"
+
+1. Find the page in `modules[moduleId]`
+2. Read `exports.actions` — e.g. `["save", "delete"]`
+3. These are the `action_*` exports callable from the client
+
+### "Where is the auth middleware applied?"
+
+1. Search `routes` recursively for nodes where `middlewares` includes the auth middleware name
+2. The matching nodes and their children are protected
+
+### "Which modules have no tests?"
+
+Compare `modules` keys against the `tests/` directory. Modules with no corresponding test file are candidates for new tests.
+
+## Notes
+
+- External imports (`@mauroandre/velojs`, `preact`, `wouter-preact`) are recorded in `imports` but not crawled
+- `export function action_*` is NOT detected — only `export const action_*` (matches framework behavior)
+- Path-less layouts (no `path` property) have `fullPath: ""` and `path: ""`
+- The graph is regenerated on every build and on file changes during dev — never stale

package/dist/cli.js

@@ -1,43 +1,44 @@
-import { spawnSync as n } from "node:child_process";
-import { resolve as l } from "node:path";
-const i = process.argv.slice(2), c = i[0], d = (e, t = []) => {
-  const s = n(e, t, {
+import { spawnSync as c } from "node:child_process";
+import { join as n, resolve as u } from "node:path";
+import p from "node:fs";
+const o = process.argv.slice(2), a = o[0], v = (e, s = []) => {
+  const t = c(e, s, {
     stdio: "inherit",
     cwd: process.cwd()
   });
-  process.exit(s.status ?? 0);
-}, p = () => {
-  d("npx", ["vite", ...i.slice(1)]);
-}, u = (e) => {
-  const t = Date.now().toString(36), s = {
+  process.exit(t.status ?? 0);
+}, m = () => {
+  v("npx", ["vite", ...o.slice(1)]);
+}, j = (e) => {
+  const s = Date.now().toString(36), t = {
     ...process.env,
-    VELO_BUILD_HASH: t,
+    VELO_BUILD_HASH: s,
     ...e ? { VELO_STATIC: "1" } : {}
   };
   console.log("Building client...");
-  const o = n("npx", ["vite", "build"], {
+  const r = c("npx", ["vite", "build"], {
     stdio: "inherit",
     cwd: process.cwd(),
-    env: s
+    env: t
   });
-  o.status !== 0 && (console.error("Client build failed. Aborting."), process.exit(o.status ?? 1)), console.log("Building server...");
-  const r = n("npx", ["vite", "build", "--mode", "server"], {
+  r.status !== 0 && (console.error("Client build failed. Aborting."), process.exit(r.status ?? 1)), console.log("Building server...");
+  const i = c("npx", ["vite", "build", "--mode", "server"], {
     stdio: "inherit",
     cwd: process.cwd(),
-    env: s
+    env: t
   });
-  r.status !== 0 && (console.error("Server build failed. Aborting."), process.exit(r.status ?? 1)), console.log("Build complete!"), e && v();
-}, v = async () => {
+  i.status !== 0 && (console.error("Server build failed. Aborting."), process.exit(i.status ?? 1)), console.log("Build complete!"), e && b();
+}, b = async () => {
   process.env.NODE_ENV = "production", process.env.VELO_STATIC = "1";
-  const t = await import(l(process.cwd(), "dist/server.js")), s = t.default, o = t.routes;
-  (!s || !o) && (console.error("Failed to load app or routes from dist/server.js"), process.exit(1));
-  const { generateStatic: r } = await import("./static.js");
-  await r(s, o);
-}, m = () => {
+  const s = await import(u(process.cwd(), "dist/server.js")), t = s.default, r = s.routes;
+  (!t || !r) && (console.error("Failed to load app or routes from dist/server.js"), process.exit(1));
+  const { generateStatic: i } = await import("./static.js");
+  await i(t, r);
+}, f = () => {
   process.env.NODE_ENV = "production";
-  const e = l(process.cwd(), "dist/server.js");
-  d("node", [e]);
-}, a = () => {
+  const e = u(process.cwd(), "dist/server.js");
+  v("node", [e]);
+}, d = () => {
   console.log(`
 VeloJS CLI
 
@@ -50,6 +51,8 @@ Commands:
   build            Build for production (client + server)
   build --static   Build as static site (HTML + JSON)
   start            Start production server
+  graph [app-dir]   Generate .velojs/graph.json (route tree + dependency graph)
+  graph --view      Generate the graph and open an interactive viewer
 
 Examples:
   velojs init my-app
@@ -57,30 +60,43 @@ Examples:
   velojs build
   velojs build --static
   velojs start
+  velojs graph
+  velojs graph src/app
+  velojs graph --view
 `);
 };
-switch (c) {
+switch (a) {
   case "init": {
     const { runInit: e } = await import("./init.js");
-    await e(i[1]);
+    await e(o[1]);
     break;
   }
   case "dev":
-    p();
+    m();
     break;
   case "build": {
-    const e = i.includes("--static");
-    u(e);
+    const e = o.includes("--static");
+    j(e);
     break;
   }
   case "start":
-    m();
+    f();
+    break;
+  case "graph": {
+    const { buildGraph: e } = await import("./graph.js"), s = process.cwd(), t = o[1] && !o[1].startsWith("-") ? o[1] : null, r = n(s, t ?? "app"), i = e(r), l = n(s, ".velojs");
+    p.mkdirSync(l, { recursive: !0 });
+    const w = n(l, "graph.json");
+    if (p.writeFileSync(w, JSON.stringify(i)), console.log("Graph written to .velojs/graph.json"), o.includes("--view")) {
+      const { serveGraphViewer: g } = await import("./graph-viewer.js"), h = await g(s);
+      console.log(`Graph viewer running at ${h} (Ctrl+C to stop)`);
+    }
     break;
+  }
   case "help":
   case "--help":
   case "-h":
-    a();
+    d();
     break;
   default:
-    c && console.error(`Unknown command: ${c}`), a(), process.exit(1);
+    a && console.error(`Unknown command: ${a}`), d(), process.exit(1);
 }

package/dist/graph-viewer.d.ts

@@ -0,0 +1,13 @@
+/**
+ * VeloJS Graph Viewer
+ *
+ * Serves an interactive, self-contained HTML visualization of
+ * .velojs/graph.json — route tree + force-directed dependency graph.
+ * Plain node:http, no dependencies. The graph JSON is read from disk
+ * on every request so the view is always fresh.
+ */
+/**
+ * Starts the graph viewer server. Reads `.velojs/graph.json` from
+ * projectRoot on every request — always fresh. Returns the URL.
+ */
+export declare function serveGraphViewer(projectRoot: string): Promise<string>;

package/dist/graph-viewer.js

@@ -0,0 +1,378 @@
+import r from "node:http";
+import d from "node:fs";
+import l from "node:path";
+const s = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>VeloJS Graph</title>
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<style>
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; background: #0b0e14; color: #d7dde8; overflow: hidden; }
+  #topbar { display: flex; align-items: center; gap: 12px; padding: 10px 14px; background: #11151f; border-bottom: 1px solid #232a3a; }
+  #topbar h1 { font-size: 14px; font-weight: 600; color: #e8edf5; }
+  #topbar h1 span { color: #5b8def; }
+  .tab { padding: 5px 14px; border-radius: 6px; border: 1px solid #2a3247; background: transparent; color: #9aa5b8; font: inherit; font-size: 12px; cursor: pointer; }
+  .tab.active { background: #1d2740; color: #e8edf5; border-color: #3d5a99; }
+  #search { margin-left: auto; padding: 5px 10px; border-radius: 6px; border: 1px solid #2a3247; background: #0b0e14; color: #d7dde8; font: inherit; font-size: 12px; width: 220px; }
+  #search:focus { outline: none; border-color: #3d5a99; }
+  #canvas { display: block; cursor: grab; }
+  #panel { position: fixed; top: 46px; right: 0; width: 330px; bottom: 0; background: #11151f; border-left: 1px solid #232a3a; padding: 16px; overflow-y: auto; transform: translateX(100%); transition: transform .18s ease; font-size: 12px; }
+  #panel.open { transform: translateX(0); }
+  #panel h2 { font-size: 14px; color: #e8edf5; word-break: break-all; margin-bottom: 4px; }
+  #panel .file { color: #6b768c; font-size: 11px; margin-bottom: 12px; word-break: break-all; }
+  #panel h3 { font-size: 11px; text-transform: uppercase; letter-spacing: .06em; color: #6b768c; margin: 14px 0 6px; }
+  #panel li { list-style: none; padding: 3px 0; color: #aebad0; word-break: break-all; cursor: pointer; }
+  #panel li:hover { color: #5b8def; }
+  #panel li.ext { color: #6b768c; cursor: default; }
+  #panel li.ext:hover { color: #6b768c; }
+  .badge { display: inline-block; padding: 1px 7px; border-radius: 4px; font-size: 10px; margin-right: 5px; background: #1d2740; color: #9db8ef; border: 1px solid #2f3d5f; }
+  #legend { position: fixed; left: 14px; bottom: 14px; background: #11151fdd; border: 1px solid #232a3a; border-radius: 8px; padding: 10px 14px; font-size: 11px; color: #9aa5b8; }
+  #legend i { display: inline-block; width: 9px; height: 9px; border-radius: 50%; margin-right: 6px; }
+  #hint { position: fixed; left: 50%; transform: translateX(-50%); bottom: 14px; font-size: 11px; color: #55607a; }
+</style>
+</head>
+<body>
+<div id="topbar">
+  <h1>velo<span>js</span> graph</h1>
+  <button class="tab active" id="tab-routes">Route tree</button>
+  <button class="tab" id="tab-modules">Dependencies</button>
+  <input id="search" placeholder="filter modules... (/)">
+</div>
+<canvas id="canvas"></canvas>
+<div id="panel"></div>
+<div id="legend">
+  <div><i style="background:#f59e0b"></i>root</div>
+  <div><i style="background:#a78bfa"></i>layout</div>
+  <div><i style="background:#5b8def"></i>page</div>
+  <div><i style="background:#4b5565"></i>module</div>
+</div>
+<div id="hint">drag to pan · scroll to zoom · drag nodes · hover = impact highlight · / = search</div>
+<script>
+var KIND_COLORS = { root: "#f59e0b", layout: "#a78bfa", page: "#5b8def", unknown: "#4b5565" };
+
+var graph = null;
+var view = "routes";
+var cam = { x: 0, y: 0, k: 1 };
+var canvas = document.getElementById("canvas");
+var ctx = canvas.getContext("2d");
+var W = 0, H = 0;
+
+function resize() {
+  W = window.innerWidth; H = window.innerHeight;
+  canvas.width = W * devicePixelRatio; canvas.height = H * devicePixelRatio;
+  canvas.style.width = W + "px"; canvas.style.height = H + "px";
+  ctx.setTransform(devicePixelRatio, 0, 0, devicePixelRatio, 0, 0);
+}
+window.addEventListener("resize", resize); resize();
+
+// ---------- data ----------
+var modNodes = [], modEdges = [], modById = {};
+var routeNodes = [], routeEdges = [];
+
+function buildModuleGraph() {
+  var ids = Object.keys(graph.modules);
+  ids.forEach(function (id, i) {
+    var m = graph.modules[id];
+    modNodes.push({ id: id, kind: m.kind, exports: m.exports, imports: m.imports, importedBy: m.importedBy, file: m.file,
+      x: (Math.random() - 0.5) * 800, y: (Math.random() - 0.5) * 800, vx: 0, vy: 0 });
+  });
+  modNodes.forEach(function (n) { modById[n.id] = n; });
+  modNodes.forEach(function (n) {
+    n.imports.forEach(function (imp) {
+      if (modById[imp]) modEdges.push({ from: n, to: modById[imp] });
+    });
+  });
+}
+
+function buildRouteLayout() {
+  var leafCount = 0;
+  // tidy-ish: leaves get sequential x; parents sit at the midpoint of children
+  function layout(node, depth, parent) {
+    var rn = { data: node, depth: depth, x: 0, y: depth, parent: parent };
+    routeNodes.push(rn);
+    if (parent) routeEdges.push({ from: parent, to: rn });
+    if (!node.children.length) { rn.x = leafCount++; return rn; }
+    var xs = node.children.map(function (c) { return layout(c, depth + 1, rn).x; });
+    rn.x = (xs[0] + xs[xs.length - 1]) / 2;
+    return rn;
+  }
+  graph.routes.forEach(function (r) { layout(r, 0, null); });
+  var gapX = 210, gapY = 110;
+  var minX = Math.min.apply(null, routeNodes.map(function (n) { return n.x; }));
+  routeNodes.forEach(function (n) { n.px = (n.x - minX) * gapX + 80; n.py = n.y * gapY + 80; });
+}
+
+// ---------- camera helpers ----------
+function fitView(xs, ys) {
+  var minX = Math.min.apply(null, xs), maxX = Math.max.apply(null, xs);
+  var minY = Math.min.apply(null, ys), maxY = Math.max.apply(null, ys);
+  var w = Math.max(maxX - minX, 1), h = Math.max(maxY - minY, 1);
+  cam.k = Math.min((W - 120) / w, (H - 120) / h, 1.4);
+  cam.x = W / 2 - (minX + w / 2) * cam.k;
+  cam.y = H / 2 - (minY + h / 2) * cam.k;
+}
+function toScreen(x, y) { return [x * cam.k + cam.x, y * cam.k + cam.y]; }
+function toWorld(sx, sy) { return [(sx - cam.x) / cam.k, (sy - cam.y) / cam.k]; }
+
+// ---------- force simulation (modules) ----------
+var alpha = 1;
+function tick() {
+  if (view !== "modules" || alpha < 0.005) return;
+  alpha *= 0.995;
+  var i, j, n, m, dx, dy, d2, f;
+  for (i = 0; i < modNodes.length; i++) {
+    n = modNodes[i];
+    for (j = i + 1; j < modNodes.length; j++) {
+      m = modNodes[j];
+      dx = n.x - m.x; dy = n.y - m.y;
+      d2 = dx * dx + dy * dy + 0.01;
+      f = 2600 / d2 * alpha;
+      var d = Math.sqrt(d2);
+      n.vx += dx / d * f; n.vy += dy / d * f;
+      m.vx -= dx / d * f; m.vy -= dy / d * f;
+    }
+  }
+  modEdges.forEach(function (e) {
+    dx = e.to.x - e.from.x; dy = e.to.y - e.from.y;
+    var d = Math.sqrt(dx * dx + dy * dy) || 1;
+    f = (d - 110) * 0.02 * alpha;
+    e.from.vx += dx / d * f * d * 0.02; e.from.vy += dy / d * f * d * 0.02;
+    e.to.vx -= dx / d * f * d * 0.02; e.to.vy -= dy / d * f * d * 0.02;
+  });
+  modNodes.forEach(function (n) {
+    if (n === dragNode) return;
+    n.vx += -n.x * 0.002 * alpha; n.vy += -n.y * 0.002 * alpha;
+    n.vx *= 0.85; n.vy *= 0.85;
+    n.x += n.vx; n.y += n.vy;
+  });
+}
+
+// ---------- impact highlight ----------
+var hoverNode = null;
+var impactSet = null;
+function computeImpact(n) {
+  var set = {}, queue = [n.id];
+  set[n.id] = 2;
+  while (queue.length) {
+    var id = queue.shift();
+    var mod = graph.modules[id];
+    if (!mod) continue;
+    mod.importedBy.forEach(function (up) {
+      if (!(up in set)) { set[up] = 1; queue.push(up); }
+    });
+  }
+  return set;
+}
+
+// ---------- selection / panel ----------
+var selected = null;
+var panel = document.getElementById("panel");
+function showPanel(id) {
+  selected = id;
+  var m = graph.modules[id];
+  if (!m) { panel.className = ""; panel.innerHTML = ""; return; }
+  var b = [];
+  if (m.exports.hasComponent) b.push('<span class="badge">Component</span>');
+  if (m.exports.hasLoader) b.push('<span class="badge">loader</span>');
+  m.exports.actions.forEach(function (a) { b.push('<span class="badge">action_' + a + "</span>"); });
+  m.exports.streams.forEach(function (s) { b.push('<span class="badge">stream_' + s + "</span>"); });
+  m.exports.sockets.forEach(function (s) { b.push('<span class="badge">socket_' + s + "</span>"); });
+  var html = "<h2>" + id + '</h2><div class="file">' + m.file + " · " + m.kind + "</div><div>" + b.join("") + "</div>";
+  html += "<h3>imports (" + m.imports.length + ")</h3><ul>";
+  m.imports.forEach(function (i) {
+    html += modById[i] ? "<li data-id='" + i + "'>→ " + i + "</li>" : "<li class='ext'>→ " + i + "</li>";
+  });
+  html += "</ul><h3>imported by (" + m.importedBy.length + ")</h3><ul>";
+  m.importedBy.forEach(function (i) { html += "<li data-id='" + i + "'>← " + i + "</li>"; });
+  html += "</ul>";
+  panel.innerHTML = html;
+  panel.className = "open";
+  panel.querySelectorAll("li[data-id]").forEach(function (li) {
+    li.addEventListener("click", function () { showPanel(li.getAttribute("data-id")); focusModule(li.getAttribute("data-id")); });
+  });
+}
+function focusModule(id) {
+  var n = modById[id];
+  if (!n) return;
+  if (view !== "modules") setView("modules");
+  cam.x = W / 2 - n.x * cam.k; cam.y = H / 2 - n.y * cam.k;
+}
+
+// ---------- search ----------
+var query = "";
+document.getElementById("search").addEventListener("input", function (e) { query = e.target.value.toLowerCase(); });
+document.addEventListener("keydown", function (e) {
+  if (e.key === "/" && document.activeElement !== document.getElementById("search")) { e.preventDefault(); document.getElementById("search").focus(); }
+  if (e.key === "Escape") { panel.className = ""; selected = null; query = ""; document.getElementById("search").value = ""; }
+});
+
+// ---------- interaction ----------
+var dragNode = null, panning = false, lastX = 0, lastY = 0, moved = false;
+function nodeAt(sx, sy) {
+  var w = toWorld(sx, sy);
+  var list = view === "modules" ? modNodes : routeNodes;
+  for (var i = list.length - 1; i >= 0; i--) {
+    var n = list[i];
+    var nx = view === "modules" ? n.x : n.px, ny = view === "modules" ? n.y : n.py;
+    var dx = w[0] - nx, dy = w[1] - ny;
+    if (dx * dx + dy * dy < 14 * 14 / (cam.k * cam.k) + 36) return n;
+  }
+  return null;
+}
+canvas.addEventListener("mousedown", function (e) {
+  var n = nodeAt(e.clientX, e.clientY);
+  if (n && view === "modules") { dragNode = n; alpha = Math.max(alpha, 0.3); }
+  else panning = true;
+  lastX = e.clientX; lastY = e.clientY; moved = false;
+});
+canvas.addEventListener("mousemove", function (e) {
+  var dx = e.clientX - lastX, dy = e.clientY - lastY;
+  if (Math.abs(dx) + Math.abs(dy) > 3) moved = true;
+  if (dragNode) { var w = toWorld(e.clientX, e.clientY); dragNode.x = w[0]; dragNode.y = w[1]; dragNode.vx = dragNode.vy = 0; }
+  else if (panning) { cam.x += dx; cam.y += dy; }
+  else {
+    var n = nodeAt(e.clientX, e.clientY);
+    hoverNode = view === "modules" ? n : null;
+    impactSet = hoverNode ? computeImpact(hoverNode) : null;
+    canvas.style.cursor = n ? "pointer" : "grab";
+  }
+  lastX = e.clientX; lastY = e.clientY;
+});
+canvas.addEventListener("mouseup", function (e) {
+  if (!moved) {
+    var n = nodeAt(e.clientX, e.clientY);
+    if (view === "modules") showPanel(n ? n.id : null);
+    else if (n && n.data.moduleId) showPanel(n.data.moduleId);
+    else showPanel(null);
+  }
+  dragNode = null; panning = false;
+});
+canvas.addEventListener("wheel", function (e) {
+  e.preventDefault();
+  var k = Math.exp(-e.deltaY * 0.0012);
+  var w = toWorld(e.clientX, e.clientY);
+  cam.k *= k;
+  cam.x = e.clientX - w[0] * cam.k; cam.y = e.clientY - w[1] * cam.k;
+}, { passive: false });
+
+// ---------- rendering ----------
+function matches(id) { return !query || id.toLowerCase().indexOf(query) >= 0; }
+
+function drawRoutes() {
+  ctx.clearRect(0, 0, W, H);
+  ctx.strokeStyle = "#2a3247"; ctx.lineWidth = 1.2;
+  routeEdges.forEach(function (e) {
+    var a = toScreen(e.from.px, e.from.py), b = toScreen(e.to.px, e.to.py);
+    ctx.beginPath();
+    ctx.moveTo(a[0], a[1]);
+    ctx.bezierCurveTo(a[0], (a[1] + b[1]) / 2, b[0], (a[1] + b[1]) / 2, b[0], b[1]);
+    ctx.stroke();
+  });
+  routeNodes.forEach(function (n) {
+    var d = n.data;
+    var id = d.moduleId || "(wrapper)";
+    if (!matches(id)) return;
+    var p = toScreen(n.px, n.py);
+    var color = d.isRoot ? KIND_COLORS.root : (d.children.length ? KIND_COLORS.layout : KIND_COLORS.page);
+    var sel = selected === d.moduleId;
+    ctx.beginPath(); ctx.arc(p[0], p[1], sel ? 9 : 6, 0, 7);
+    ctx.fillStyle = color; ctx.fill();
+    if (sel) { ctx.strokeStyle = "#e8edf5"; ctx.lineWidth = 2; ctx.stroke(); }
+    ctx.fillStyle = "#d7dde8"; ctx.font = "11px ui-monospace, monospace"; ctx.textAlign = "center";
+    ctx.fillText(id.split("/").pop(), p[0], p[1] - 13);
+    ctx.fillStyle = "#55607a"; ctx.font = "10px ui-monospace, monospace";
+    var sub = d.fullPath || "";
+    if (d.middlewares.length) sub += "  ·  " + d.middlewares.join(", ");
+    ctx.fillText(sub, p[0], p[1] + 20);
+  });
+}
+
+function drawModules() {
+  ctx.clearRect(0, 0, W, H);
+  ctx.strokeStyle = "#232a3a"; ctx.lineWidth = 1;
+  modEdges.forEach(function (e) {
+    if (!matches(e.from.id) && !matches(e.to.id)) return;
+    var hot = impactSet && impactSet[e.from.id] && impactSet[e.to.id];
+    var a = toScreen(e.from.x, e.from.y), b = toScreen(e.to.x, e.to.y);
+    ctx.strokeStyle = hot ? "#f59e0b" : "#232a3a";
+    ctx.lineWidth = hot ? 1.8 : 1;
+    ctx.beginPath(); ctx.moveTo(a[0], a[1]); ctx.lineTo(b[0], b[1]); ctx.stroke();
+  });
+  modNodes.forEach(function (n) {
+    if (!matches(n.id)) return;
+    var p = toScreen(n.x, n.y);
+    var dim = impactSet && !impactSet[n.id];
+    var hot = impactSet && impactSet[n.id];
+    var r = n.kind === "unknown" ? 4 : 7;
+    ctx.globalAlpha = dim ? 0.15 : 1;
+    ctx.beginPath(); ctx.arc(p[0], p[1], selected === n.id ? r + 3 : r, 0, 7);
+    ctx.fillStyle = hot === 2 ? "#f59e0b" : KIND_COLORS[n.kind] || KIND_COLORS.unknown;
+    ctx.fill();
+    if (selected === n.id) { ctx.strokeStyle = "#e8edf5"; ctx.lineWidth = 2; ctx.stroke(); }
+    if (!dim) {
+      ctx.fillStyle = hot ? "#e8edf5" : "#9aa5b8";
+      ctx.font = "10px ui-monospace, monospace"; ctx.textAlign = "center";
+      ctx.fillText(n.id.split("/").pop(), p[0], p[1] - r - 5);
+    }
+    ctx.globalAlpha = 1;
+  });
+}
+
+function frame() {
+  tick();
+  if (view === "routes") drawRoutes(); else drawModules();
+  requestAnimationFrame(frame);
+}
+
+// ---------- tabs ----------
+function setView(v) {
+  view = v;
+  document.getElementById("tab-routes").className = "tab" + (v === "routes" ? " active" : "");
+  document.getElementById("tab-modules").className = "tab" + (v === "modules" ? " active" : "");
+  if (v === "routes") fitView(routeNodes.map(function (n) { return n.px; }), routeNodes.map(function (n) { return n.py; }));
+  else { alpha = Math.max(alpha, 0.4); fitView(modNodes.map(function (n) { return n.x; }), modNodes.map(function (n) { return n.y; })); }
+}
+document.getElementById("tab-routes").addEventListener("click", function () { setView("routes"); });
+document.getElementById("tab-modules").addEventListener("click", function () { setView("modules"); });
+
+// ---------- boot ----------
+fetch("/graph.json").then(function (r) { return r.json(); }).then(function (g) {
+  graph = g;
+  buildModuleGraph();
+  buildRouteLayout();
+  alpha = 1;
+  // pre-simulate so the first paint is already organized
+  for (var i = 0; i < 300 && alpha > 0.05; i++) tick();
+  setView("routes");
+  frame();
+});
+<\/script>
+</body>
+</html>`;
+async function f(o) {
+  const i = l.join(o, ".velojs", "graph.json"), a = r.createServer((n, e) => {
+    if (n.url === "/graph.json") {
+      let t;
+      try {
+        t = d.readFileSync(i, "utf-8");
+      } catch {
+        e.writeHead(404, { "Content-Type": "application/json" }), e.end(JSON.stringify({ error: "graph.json not found — run `velojs graph` first" }));
+        return;
+      }
+      e.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "no-store" }), e.end(t);
+      return;
+    }
+    e.writeHead(200, { "Content-Type": "text/html; charset=utf-8" }), e.end(s);
+  });
+  return await new Promise((n) => {
+    a.listen(0, "127.0.0.1", () => {
+      const e = a.address(), t = typeof e == "object" && e ? e.port : 0;
+      n(`http://127.0.0.1:${t}`);
+    });
+  });
+}
+export {
+  f as serveGraphViewer
+};

package/dist/graph.d.ts

@@ -0,0 +1,37 @@
+/**
+ * VeloJS Project Graph
+ *
+ * Builds a structural JSON snapshot of the project — route tree hierarchy,
+ * module dependency graph, and convention exports — from source code alone.
+ * No Vite, no dev server, no build. Used by `velojs graph` and by the
+ * `velo:graph` Vite plugin.
+ */
+export interface RouteTreeNode {
+    moduleId: string | null;
+    fullPath: string | null;
+    path: string | null;
+    isRoot: boolean;
+    middlewares: string[];
+    children: RouteTreeNode[];
+}
+export interface ModuleExports {
+    hasComponent: boolean;
+    hasLoader: boolean;
+    actions: string[];
+    streams: string[];
+    sockets: string[];
+}
+export interface ModuleInfo {
+    file: string;
+    kind: "root" | "layout" | "page" | "unknown";
+    exports: ModuleExports;
+    imports: string[];
+    importedBy: string[];
+}
+export interface GraphJson {
+    routes: RouteTreeNode[];
+    modules: Record<string, ModuleInfo>;
+}
+export declare function detectExports(filePath: string): ModuleExports;
+export declare function buildRouteTree(code: string): RouteTreeNode[];
+export declare function buildGraph(appDir: string): GraphJson;