feat(visualize): provenance tree (document → concepts) as the default view

The radial 1-hop view wasn't a real tree. Replace it with the wiki's
actual hierarchy, rendered as a collapsible indented outline:
- each ingested document (summary page) is a root; under it, the
  concepts/entities it produced — resolved from each concept's `sources`
  frontmatter (stripping the .md so "summaries/x.md" matches node id
  "summaries/x"); a concept appears under every document it came from
- roots ordered by how many concepts they produced; type-colored dots;
  fold/unfold per row; click a row to inspect (panel with description,
  sources, links); search and legend filter the outline live
- DOM outline (not canvas) → crisp text, scrollable, no legibility issues
- a TREE ⇄ 3D GRAPH toggle keeps the force layout for the visual overview;
  the spacing slider only shows in graph mode
Removes the rejected radial mind-map mode.

Author: KylinMountain

openkb/templates/graph.html

@@ -123,6 +123,32 @@
 .controls .rst:hover{background:rgba(255,255,255,.08);color:var(--ink)}
 .controls .sepc{width:1px;height:18px;background:var(--line)}
 
+/* ---- provenance tree (outline) ---- */
+.tree{
+  position:fixed;left:0;top:60px;right:0;bottom:70px;z-index:3;
+  overflow:auto;padding:14px 30px 30px;
+  font:13px/1.65 var(--mono);color:var(--soft);
+}
+.tree .t-row{
+  display:flex;align-items:center;gap:8px;padding:3px 9px;border-radius:7px;
+  cursor:pointer;white-space:nowrap;transition:background .12s ease,color .12s ease;
+}
+.tree .t-row:hover{background:var(--glass);color:var(--ink)}
+.tree .t-caret{width:11px;flex:none;color:var(--mut);font-size:.62rem;text-align:center;transition:transform .15s ease}
+.tree .t-dot{width:9px;height:9px;border-radius:50%;flex:none;
+  background:rgb(var(--c,148,163,184));box-shadow:0 0 7px rgba(var(--c,148,163,184),.55)}
+.tree .t-ic{flex:none;opacity:.85}
+.tree .t-ct{margin-left:9px;color:var(--mut);font-size:.7rem}
+.tree .t-doc{color:var(--ink);font-weight:600}
+.tree .t-leaf{color:var(--soft)}
+.tree .t-children{margin-left:15px;padding-left:9px;border-left:1px solid var(--line)}
+.tree .t-group.collapsed > .t-children{display:none}
+.tree .t-group.collapsed > .t-row .t-caret{transform:rotate(-90deg)}
+.tree .t-docgroup{margin:9px 0}
+.tree .t-empty{color:var(--mut);padding:24px}
+.tree::-webkit-scrollbar{width:9px}
+.tree::-webkit-scrollbar-thumb{background:rgba(255,255,255,.12);border-radius:8px}
+
 /* ---- glass inspector panel ---- */
 .panel{
   position:fixed;top:0;right:0;z-index:6;width:360px;max-width:88vw;height:100%;
@@ -173,6 +199,7 @@
 <div class="grain"></div>
 <div class="vignette"></div>
 <canvas id="c"></canvas>
+<div class="tree" id="tree"></div>
 
 <div class="brand">openkb<small>knowledge graph</small></div>
 
@@ -190,7 +217,7 @@
 <div class="controls">
   <button class="rst" id="mode" title="switch between mind-map and 3D graph">3D graph</button>
   <span class="sepc"></span>
-  <label>spacing <input id="spread" type="range" min="0.5" max="3" step="0.1" value="1"></label>
+  <label id="spacingCtl">spacing <input id="spread" type="range" min="0.5" max="3" step="0.1" value="1"></label>
   <button class="rst" id="reset" title="reset view, spacing &amp; focus">reset</button>
 </div>
 
@@ -226,8 +253,7 @@
   r: 3.5 + Math.min(7, ((n.in || 0) + (n.out || 0)) * 0.42),   // small crisp nodes, scaled by degree
   col: colorOf(n.type),                               // cached color → no per-frame lookup
   alpha: 1,                                            // per-node fade (legend toggle)
-  sx:0, sy:0, rz:0, pp:1, hl:1, pinned:false,          // projection cache + smoothed highlight + pinned (drag to pull out)
-  tx:0, ty:0, mapShow:true                              // mind-map: radial target position + whether shown in current focus
+  sx:0, sy:0, rz:0, pp:1, hl:1, pinned:false           // projection cache + smoothed highlight + pinned (drag to pull out)
 }));
 const byId = Object.fromEntries(nodes.map(n => [n.id, n]));
 const edges = GRAPH.edges.filter(e => byId[e.source] && byId[e.target]);
@@ -248,13 +274,10 @@
 let scale = DEF_SCALE, panX = 0, panY = 0;
 let yaw = DEF_YAW, pitch = DEF_PITCH;    // 3D orbit angles — drag the background to rotate
 let orbiting = false, oStartX = 0, oStartY = 0, yawStart = 0, pitchStart = 0;
-let panOrigX = 0, panOrigY = 0;  // bg-drag pan origin (mind-map mode)
 let didDrag = false;
 let alpha = 1;                   // simulated-annealing "temperature"; cools to 0 so motion stops
 let spread = 1;                  // spacing knob: >1 spreads nodes apart, <1 packs them tighter
-let mode = "map";                // "map" = radial mind-map (focus + neighbors), "graph" = 3D force layout
-let focusId = null;              // centered node in mind-map mode
-let pendingFocus = null;         // node pressed in map mode, awaiting click-release
+let mode = "tree";               // "tree" = provenance outline (default), "graph" = 3D force layout
 
 document.getElementById("ncount").textContent = nodes.length;
 document.getElementById("ecount").textContent = edges.length;
@@ -280,9 +303,8 @@
 
 /* ===================== physics (adapted from okf-spec.html step()) ===================== */
 const VMAX = 9;   // per-frame speed cap → no violent swings, even on a dense hub
-const alphaTarget = n => (typeVisible(n.type) && (mode === "graph" || n.mapShow)) ? 1 : 0;
+const alphaTarget = n => typeVisible(n.type) ? 1 : 0;
 function step(){
-  if(mode === "map"){ stepMap(); return; }
   for(let i=0;i<nodes.length;i++){
     const a = nodes[i];
     if(!visible(a)) continue;
@@ -322,66 +344,82 @@
   alpha += (0 - alpha) * 0.02;                    // anneal: forces fade → the layout settles and stops
 }
 
-/* ===================== mind-map (radial focus layout) ===================== */
-// Place the focus node at the origin and fan its direct neighbours out on 1–2 rings.
-// Only focus + neighbours are shown; everything else fades out. Clicking a neighbour re-focuses.
-function layoutMap(){
-  const f = byId[focusId];
-  if(!f){ return; }
-  nodes.forEach(n => { n.mapShow = false; });
-  f.mapShow = true; f.tx = 0; f.ty = 0;
-  const nbrs = [...adj[focusId]].filter(id => byId[id] && typeVisible(byId[id].type));
-  const N = nbrs.length;
-  const twoRings = N > 18;
-  const split = twoRings ? Math.ceil(N * 0.42) : N;   // inner-ring count
-  nbrs.forEach((id, i) => {
-    const ring = (twoRings && i >= split) ? 1 : 0;
-    const start = ring === 0 ? 0 : split;
-    const count = ring === 0 ? Math.min(split, N) : (N - split);
-    const idx = i - start;
-    const R = (ring === 0 ? 215 : 380) * (0.7 + 0.3 * spread);   // spacing slider stretches the rings too
-    const ang = (idx / Math.max(1, count)) * TAU - Math.PI / 2 + ring * 0.5;
-    const nb = byId[id];
-    nb.mapShow = true;
-    nb.tx = Math.cos(ang) * R;
-    nb.ty = Math.sin(ang) * R;
+/* ===================== provenance tree (document → summary → concept/entity) ===================== */
+// The wiki's real hierarchy lives in the frontmatter: each summary's `sources` is its origin
+// document (full_text), and each concept/entity's `sources` are the summaries it was drawn from.
+// Render that as a collapsible indented outline — a true tree, not the dense wikilink mesh.
+const treeEl = document.getElementById("tree");
+const spacingCtl = document.getElementById("spacingCtl");
+let treeQuery = "";
+
+// concept/entity `sources` look like "summaries/foo.md"; summary node ids are "summaries/foo" → strip .md
+const resolveSrc = s => {
+  const id = String(s).replace(/\.md$/i, "");
+  return (byId[id] && byId[id].id.startsWith("summaries/")) ? id : null;
+};
+function buildTree(){
+  const childrenOf = {};                 // summaryId → [concept/entity node]
+  nodes.forEach(n => { if(n.id.startsWith("summaries/")) childrenOf[n.id] = []; });
+  const unlinked = [];                   // concepts/entities with no resolvable summary parent
+  nodes.forEach(n => {
+    if(n.id.startsWith("summaries/")) return;
+    const parents = [...new Set((n.sources || []).map(resolveSrc).filter(Boolean))];
+    if(parents.length) parents.forEach(p => childrenOf[p].push(n));
+    else unlinked.push(n);
   });
-}
-function stepMap(){
-  for(const n of nodes){
-    n.alpha += (alphaTarget(n) - n.alpha) * 0.14;
-    if(n.mapShow){                       // ease toward radial target (flat: z→0)
-      n.x += (n.tx - n.x) * 0.16;
-      n.y += (n.ty - n.y) * 0.16;
-      n.z += (0 - n.z) * 0.16;
-    }
+
+  const q = treeQuery.toLowerCase();
+  const matches = n => (!q || n.label.toLowerCase().includes(q) || n.id.toLowerCase().includes(q)) && typeVisible(n.type);
+  const byLabel = (a, b) => a.label.localeCompare(b.label);
+  const leafRow = n => matches(n)
+    ? `<div class="t-row t-leaf" data-id="${esc(n.id)}" style="--c:${colorOf(n.type)}"><span class="t-dot"></span>${esc(n.label)}</div>`
+    : "";
+
+  // each summary = one ingested document (root); ordered by how many concepts it produced
+  const summaries = nodes.filter(n => n.id.startsWith("summaries/"))
+    .sort((a, b) => (childrenOf[b.id].length - childrenOf[a.id].length) || byLabel(a, b));
+  let html = "";
+  summaries.forEach(s => {
+    const kids = (childrenOf[s.id] || []).slice().sort(byLabel);
+    const kidRows = kids.map(leafRow).filter(Boolean).join("");
+    if(!(matches(s) || kidRows)) return;
+    html += `<div class="t-group t-docgroup"><div class="t-row t-doc" data-id="${esc(s.id)}" style="--c:${colorOf(s.type)}">`
+      + `<span class="t-caret">▾</span><span class="t-ic">📄</span>${esc(s.label)}<span class="t-ct">${kids.length}</span></div>`
+      + `<div class="t-children">${kidRows}</div></div>`;
+  });
+  const ul = unlinked.slice().sort(byLabel).map(leafRow).filter(Boolean).join("");
+  if(ul){
+    html += `<div class="t-group t-docgroup"><div class="t-row t-doc">`
+      + `<span class="t-caret">▾</span><span class="t-ic">○</span>unsourced<span class="t-ct">${unlinked.length}</span></div>`
+      + `<div class="t-children">${ul}</div></div>`;
   }
-  alpha += (0 - alpha) * 0.02;           // reuse the anneal gate as a "still animating" timer
-}
-function setFocus(id){
-  if(!byId[id]) return;
-  focusId = id;
-  layoutMap();
-  openPanel(byId[id]);                   // show the centered node's details + links
-  alpha = 1;                             // animate the re-layout
+  treeEl.innerHTML = html || '<div class="t-empty">Nothing to show.</div>';
+
+  treeEl.querySelectorAll(".t-caret").forEach(c => c.onclick = e => {
+    e.stopPropagation();
+    c.closest(".t-group").classList.toggle("collapsed");
+  });
+  treeEl.querySelectorAll(".t-row").forEach(r => r.onclick = () => {
+    const id = r.dataset.id;
+    if(id && byId[id]) openPanel(byId[id]);                 // real node → inspect
+    else { const g = r.closest(".t-group"); if(g) g.classList.toggle("collapsed"); }  // doc row → fold
+  });
 }
 function setMode(m){
   mode = m;
-  if(m === "map"){
-    yaw = 0; pitch = 0; scale = 1.0; panX = 0; panY = 0;
-    if(!focusId) focusId = byDeg[0];
-    layoutMap();
-  } else {
-    yaw = DEF_YAW; pitch = DEF_PITCH; scale = DEF_SCALE; panX = 0; panY = 0;
-    closePanel(); seed();                // fresh 3D sphere
-  }
-  hover = null; alpha = 1;
-  modeBtn.textContent = (m === "map") ? "3D graph" : "mind-map";
+  const tree = (m === "tree");
+  canvas.style.display = tree ? "none" : "block";
+  treeEl.style.display = tree ? "block" : "none";
+  spacingCtl.style.display = tree ? "none" : "flex";        // spacing only affects the force layout
+  hover = null; closePanel();
+  if(tree){ buildTree(); }
+  else { yaw = DEF_YAW; pitch = DEF_PITCH; scale = DEF_SCALE; panX = 0; panY = 0; seed(); alpha = 1; }
+  modeBtn.textContent = tree ? "3D graph" : "tree";
   updateHint();
 }
 function updateHint(){
-  hintEl.innerHTML = (mode === "map")
-    ? '<kbd>click</kbd> focus &amp; expand &nbsp; <kbd>drag bg</kbd> pan &nbsp; <kbd>scroll</kbd> zoom'
+  hintEl.innerHTML = (mode === "tree")
+    ? '<kbd>click ▾</kbd> fold / unfold &nbsp; <kbd>click row</kbd> details'
     : '<kbd>scroll</kbd> zoom &nbsp; <kbd>drag bg</kbd> rotate &nbsp; <kbd>click</kbd> inspect<br>'
       + '<kbd>drag node</kbd> pull out &amp; pin &nbsp; <kbd>dbl-click</kbd> release';
 }
@@ -442,8 +480,6 @@
 
 /* ===================== rendering ===================== */
 function drawEdge(e, t){
-  // mind-map: draw only the spokes radiating from the focus node (a clean tree, not the mesh)
-  if(mode === "map" && focusId && e.source !== focusId && e.target !== focusId) return;
   const a = byId[e.source], b = byId[e.target];
   const al = Math.min(a.alpha, b.alpha);
   if(al < 0.02) return;
@@ -514,7 +550,7 @@
   ctx.shadowBlur = 0;
   // (flat discs — no glossy core highlight)
   // label — declutter: hubs at rest; hovered node + neighbors; selection; zoomed in; near depth only
-  const showLabel = (mode === "map") || (scale > 1.4) || (n.id === selected) || (hover ? hl > 0.55 : labelIds.has(n.id));
+  const showLabel = (scale > 1.4) || (n.id === selected) || (hover ? hl > 0.55 : labelIds.has(n.id));
   if(showLabel && fog > 0.55){
     ctx.fillStyle = `rgba(238,242,247,${0.4 + 0.55*hl})`;
     ctx.font = `600 11px ui-monospace,monospace`;
@@ -527,19 +563,21 @@
 }
 
 function frame(t){
-  if(alpha > 0.005) step();   // once cooled, stop integrating — the graph holds still
-  project();                  // 3D → screen coords for this frame
-  // ease each node's highlight toward its target so hover brightens/dims smoothly (no flash)
-  const focus = hover || selected;   // hovering OR an open inspector keeps that node's connections lit
-  for(const n of nodes){
-    const near = !focus || n.id===focus || adj[focus].has(n.id);
-    n.hl += ((near ? 1 : 0.22) - n.hl) * 0.12;
+  if(mode === "graph"){       // tree mode is DOM — the canvas idles
+    if(alpha > 0.005) step();   // once cooled, stop integrating — the graph holds still
+    project();                  // 3D → screen coords for this frame
+    // ease each node's highlight toward its target so hover brightens/dims smoothly (no flash)
+    const focus = hover || selected;   // hovering OR an open inspector keeps that node's connections lit
+    for(const n of nodes){
+      const near = !focus || n.id===focus || adj[focus].has(n.id);
+      n.hl += ((near ? 1 : 0.22) - n.hl) * 0.12;
+    }
+    ctx.setTransform(DPR,0,0,DPR,0,0);
+    ctx.clearRect(0,0,W(),H());
+    edges.forEach(e => drawEdge(e, t));
+    // draw nodes far → near so nearer discs occlude farther ones (painter's algorithm)
+    nodes.filter(visible).sort((a,b) => b.rz - a.rz).forEach(n => drawNode(n, t));
   }
-  ctx.setTransform(DPR,0,0,DPR,0,0);
-  ctx.clearRect(0,0,W(),H());
-  edges.forEach(e => drawEdge(e, t));
-  // draw nodes far → near so nearer discs occlude farther ones (painter's algorithm)
-  nodes.filter(visible).sort((a,b) => b.rz - a.rz).forEach(n => drawNode(n, t));
   requestAnimationFrame(frame);
 }
 
@@ -554,14 +592,9 @@
     alpha = Math.max(alpha, 0.5);   // reheat so neighbors re-settle around the dragged node
     return;
   }
-  if(orbiting){
-    if(mode === "map"){                          // flat map → drag background to pan
-      panX = panOrigX + (e.offsetX - oStartX);
-      panY = panOrigY + (e.offsetY - oStartY);
-    } else {                                     // 3D → drag background to orbit
-      yaw = yawStart + (e.offsetX - oStartX) * 0.0045;
-      pitch = Math.max(-1.45, Math.min(1.45, pitchStart - (e.offsetY - oStartY) * 0.0045));
-    }
+  if(orbiting){                                  // 3D → drag background to orbit
+    yaw = yawStart + (e.offsetX - oStartX) * 0.0045;
+    pitch = Math.max(-1.45, Math.min(1.45, pitchStart - (e.offsetY - oStartY) * 0.0045));
     didDrag = true; return;
   }
   const n = pick(e.offsetX, e.offsetY);
@@ -570,21 +603,14 @@
 canvas.addEventListener("mousedown", e => {
   const n = pick(e.offsetX, e.offsetY);
   didDrag = false;
-  oStartX = e.offsetX; oStartY = e.offsetY;   // press origin — for the drag threshold and for orbit/pan
-  if(mode === "map"){
-    if(n){ pendingFocus = n; hover = n.id; }
-    else { orbiting = true; panOrigX = panX; panOrigY = panY; canvas.style.cursor = "grabbing"; }
-    return;
-  }
+  oStartX = e.offsetX; oStartY = e.offsetY;   // press origin — for the drag threshold and for orbit
   if(n){ drag = n; hover = n.id; canvas.style.cursor = "grabbing"; }
   else { orbiting = true; yawStart = yaw; pitchStart = pitch; canvas.style.cursor = "grabbing"; }
 });
 window.addEventListener("mouseup", e => {
-  if(mode === "map"){
-    if(pendingFocus && !didDrag) setFocus(pendingFocus.id);        // click a node → re-center on it
-  } else if(drag && !didDrag){ openPanel(drag); }                  // click (no drag) → inspect
+  if(drag && !didDrag){ openPanel(drag); }                         // click (no drag) → inspect
   else if(drag && didDrag){ drag.pinned = true; alpha = Math.max(alpha, 0.5); }  // pulled out → pin it
-  drag = null; orbiting = false; pendingFocus = null;
+  drag = null; orbiting = false;
   canvas.style.cursor = "grab";
 });
 canvas.addEventListener("dblclick", e => {
@@ -621,8 +647,8 @@
   panel.querySelectorAll("[data-n]").forEach(a => a.onclick = () => {
     const m = byId[a.dataset.n];
     if(!m) return;
-    if(mode === "map"){ setFocus(m.id); }              // navigate the mind-map by clicking a link
-    else { hover = m.id; centerOn(m); openPanel(m); }
+    if(mode === "graph"){ hover = m.id; centerOn(m); }   // graph: fly to the node
+    openPanel(m);                                        // both modes: show its details
   });
 }
 function closePanel(){ panel.classList.remove("open"); selected = null; }
@@ -640,14 +666,17 @@
   row.onclick = () => {
     row.classList.toggle("off");
     if(hiddenTypes.has(t)) hiddenTypes.delete(t); else hiddenTypes.add(t);
-    alpha = Math.max(alpha, 0.4);   // reheat so the remaining nodes re-pack into the freed space
+    if(mode === "tree") buildTree();                              // re-filter the outline
+    else alpha = Math.max(alpha, 0.4);   // reheat so the remaining nodes re-pack into the freed space
   };
   legend.appendChild(row);
 });
 
 /* ===================== search ===================== */
 search.addEventListener("input", e => {
-  const q = e.target.value.toLowerCase().trim();
+  const raw = e.target.value.trim();
+  if(mode === "tree"){ treeQuery = raw; buildTree(); return; }   // filter the outline
+  const q = raw.toLowerCase();
   if(!q){ hover = null; return; }
   const m = nodes.find(n => n.label.toLowerCase().includes(q))
          || nodes.find(n => n.id.toLowerCase().includes(q));
@@ -661,32 +690,29 @@
 });
 
 /* ===================== controls (mode toggle + spacing slider + reset) ===================== */
-modeBtn.addEventListener("click", () => setMode(mode === "map" ? "graph" : "map"));
+modeBtn.addEventListener("click", () => setMode(mode === "tree" ? "graph" : "tree"));
 
 const spreadEl = document.getElementById("spread");
 spreadEl.addEventListener("input", e => {
   spread = parseFloat(e.target.value) || 1;
-  if(mode === "map") layoutMap();   // spacing stretches the rings
   alpha = Math.max(alpha, 0.6);     // reheat so the layout re-settles at the new spacing
 });
 document.getElementById("reset").addEventListener("click", () => {
-  spread = 1; spreadEl.value = "1";
   hover = null; closePanel();
-  if(mode === "map"){
-    scale = 1.0; panX = 0; panY = 0; focusId = byDeg[0]; layoutMap();        // back to the top hub
+  if(mode === "tree"){
+    treeQuery = ""; search.value = ""; buildTree(); treeEl.scrollTop = 0;    // collapse-all back to top
   } else {
+    spread = 1; spreadEl.value = "1";
     scale = DEF_SCALE; panX = 0; panY = 0; yaw = DEF_YAW; pitch = DEF_PITCH;  // view
     nodes.forEach(n => n.pinned = false);                                    // release pinned
+    alpha = Math.max(alpha, 0.9);   // re-settle from the reset state
   }
-  alpha = Math.max(alpha, 0.9);   // re-settle from the reset state
 });
 
 /* ===================== boot ===================== */
 window.addEventListener("resize", size);
-size();
-focusId = byDeg[0]; layoutMap();   // open on the most-connected node as the mind-map root
-modeBtn.textContent = "3D graph";  // button switches TO the other mode
-updateHint();
+size(); seed();          // seed positions so a later switch to 3D has a layout to settle
+setMode("tree");         // open on the readable provenance outline
 requestAnimationFrame(frame);
 </script>
 </body>