@jhizzard/termdeck 0.10.4 → 0.12.0

package/packages/client/public/graph-controls.js

@@ -0,0 +1,217 @@
+/* TermDeck — Knowledge Graph view-controls (Sprint 43 T1)
+ *
+ * Pure functions for filtering and laying out the D3 force-directed graph.
+ * Extracted from graph.js so the filter logic can be unit-tested under
+ * `node --test` without a bundler.
+ *
+ * Dual-export pattern: in Node, `module.exports` returns the API object; in
+ * the browser, the same API attaches to `window.GraphControls`. graph.html
+ * loads this file with a plain <script> tag BEFORE graph.js so the IIFE in
+ * graph.js can read `window.GraphControls.applyControls(...)`.
+ *
+ * The four user-visible controls are:
+ *   1. hide-isolated  — drop nodes with degree 0
+ *   2. min-degree     — keep nodes with degree >= N (N ∈ {0,1,2,3,5})
+ *   3. time-window    — keep nodes with createdAt within last N days
+ *   4. layout         — 'force' (default) | 'hierarchical' | 'radial'
+ *
+ * Filter precedence inside applyControls:
+ *   time-window ⇒ degree.  Time-window first because dropping nodes by age
+ *   also drops their edges, which changes the degree count for the survivors.
+ */
+
+(function (root) {
+  'use strict';
+
+  const WINDOW_DAYS = { '7d': 7, '30d': 30, '90d': 90 };
+  const LAYOUTS = ['force', 'hierarchical', 'radial'];
+  const VALID_WINDOWS = ['all', '7d', '30d', '90d'];
+
+  function edgeEndpointId(end) {
+    return (end && typeof end === 'object') ? end.id : end;
+  }
+
+  function computeDegrees(nodes, edges) {
+    const deg = new Map();
+    for (const n of nodes) deg.set(n.id, 0);
+    for (const e of edges) {
+      const sId = edgeEndpointId(e.source);
+      const tId = edgeEndpointId(e.target);
+      // Only count edges where BOTH endpoints are in the node set; a half-known
+      // edge is "broken" and shouldn't bump the survivor's degree.
+      if (!deg.has(sId) || !deg.has(tId)) continue;
+      deg.set(sId, deg.get(sId) + 1);
+      deg.set(tId, deg.get(tId) + 1);
+    }
+    return deg;
+  }
+
+  function windowMinTime(windowKey, now) {
+    const days = WINDOW_DAYS[windowKey];
+    if (!days) return null;
+    const ref = (typeof now === 'number' && Number.isFinite(now)) ? now : Date.now();
+    return ref - days * 86_400_000;
+  }
+
+  function filterEdgesByNodeSet(edges, idSet) {
+    const out = [];
+    for (const e of edges) {
+      const sId = edgeEndpointId(e.source);
+      const tId = edgeEndpointId(e.target);
+      if (idSet.has(sId) && idSet.has(tId)) out.push(e);
+    }
+    return out;
+  }
+
+  function applyControls(nodes, edges, controls, now) {
+    const c = controls || {};
+    let outNodes = Array.isArray(nodes) ? nodes.slice() : [];
+    let outEdges = Array.isArray(edges) ? edges.slice() : [];
+
+    const minTime = windowMinTime(c.window, now);
+    if (minTime != null) {
+      outNodes = outNodes.filter((n) => {
+        if (!n.createdAt) return false;
+        const t = Date.parse(n.createdAt);
+        return Number.isFinite(t) && t >= minTime;
+      });
+      outEdges = filterEdgesByNodeSet(outEdges, new Set(outNodes.map((n) => n.id)));
+    }
+
+    const minDegreeRaw = Number.isFinite(c.minDegree) ? c.minDegree : 0;
+    const minDegree = Math.max(0, Math.floor(minDegreeRaw));
+    const hideIsolated = !!c.hideIsolated;
+    const threshold = Math.max(minDegree, hideIsolated ? 1 : 0);
+
+    if (threshold > 0) {
+      const deg = computeDegrees(outNodes, outEdges);
+      outNodes = outNodes.filter((n) => (deg.get(n.id) || 0) >= threshold);
+      outEdges = filterEdgesByNodeSet(outEdges, new Set(outNodes.map((n) => n.id)));
+    }
+
+    return { nodes: outNodes, edges: outEdges };
+  }
+
+  function defaultControls() {
+    return { hideIsolated: false, minDegree: 0, window: 'all', layout: 'force' };
+  }
+
+  function normalizeControls(c) {
+    const def = defaultControls();
+    const out = Object.assign({}, def, c || {});
+    out.hideIsolated = !!out.hideIsolated;
+    const md = Number(out.minDegree);
+    out.minDegree = Number.isFinite(md) && md > 0 ? Math.max(0, Math.floor(md)) : 0;
+    if (!VALID_WINDOWS.includes(out.window)) out.window = 'all';
+    if (!LAYOUTS.includes(out.layout)) out.layout = 'force';
+    return out;
+  }
+
+  function encodeControls(qs, controls) {
+    const c = normalizeControls(controls);
+    if (c.hideIsolated) qs.set('hideIsolated', '1');
+    else qs.delete('hideIsolated');
+    if (c.minDegree > 0) qs.set('minDegree', String(c.minDegree));
+    else qs.delete('minDegree');
+    if (c.window !== 'all') qs.set('window', c.window);
+    else qs.delete('window');
+    if (c.layout !== 'force') qs.set('layout', c.layout);
+    else qs.delete('layout');
+    return qs;
+  }
+
+  function decodeControls(qs) {
+    const out = defaultControls();
+    if (qs.get('hideIsolated') === '1') out.hideIsolated = true;
+    const md = parseInt(qs.get('minDegree'), 10);
+    if (Number.isFinite(md) && md > 0) out.minDegree = md;
+    const win = qs.get('window');
+    if (win && VALID_WINDOWS.includes(win)) out.window = win;
+    const lay = qs.get('layout');
+    if (lay && LAYOUTS.includes(lay)) out.layout = lay;
+    return out;
+  }
+
+  // Hierarchical layering — assigns each node a "level" by BFS from roots
+  // (nodes with no incoming `supersedes` / `caused_by` edges). Used by the
+  // hierarchical layout to map level → y position. Falls back to a single
+  // level when no directional edges are present.
+  function computeHierarchyLevels(nodes, edges) {
+    const directional = new Set(['supersedes', 'caused_by', 'blocks']);
+    const incoming = new Map();
+    const outgoing = new Map();
+    for (const n of nodes) {
+      incoming.set(n.id, []);
+      outgoing.set(n.id, []);
+    }
+    for (const e of edges) {
+      if (!directional.has(e.kind)) continue;
+      const sId = edgeEndpointId(e.source);
+      const tId = edgeEndpointId(e.target);
+      if (incoming.has(tId)) incoming.get(tId).push(sId);
+      if (outgoing.has(sId)) outgoing.get(sId).push(tId);
+    }
+    const levels = new Map();
+    const roots = [];
+    for (const n of nodes) {
+      if ((incoming.get(n.id) || []).length === 0) {
+        roots.push(n.id);
+        levels.set(n.id, 0);
+      }
+    }
+    if (roots.length === 0) {
+      for (const n of nodes) levels.set(n.id, 0);
+      return levels;
+    }
+    const queue = roots.slice();
+    while (queue.length) {
+      const id = queue.shift();
+      const cur = levels.get(id) || 0;
+      for (const next of (outgoing.get(id) || [])) {
+        const prev = levels.get(next);
+        const candidate = cur + 1;
+        if (prev == null || candidate > prev) {
+          levels.set(next, candidate);
+          queue.push(next);
+        }
+      }
+    }
+    for (const n of nodes) {
+      if (!levels.has(n.id)) levels.set(n.id, 0);
+    }
+    return levels;
+  }
+
+  // Radial radius helper — high degree → small radius (center). Returns a
+  // function that takes a node and returns a target radius (0 < r ≤ rMax).
+  function radialRadiusFn(degreesMap, rMax) {
+    let maxDeg = 0;
+    for (const v of degreesMap.values()) if (v > maxDeg) maxDeg = v;
+    if (maxDeg === 0) return () => rMax * 0.5;
+    return (n) => {
+      const deg = degreesMap.get(n.id) || 0;
+      const t = 1 - (deg / maxDeg);
+      return rMax * (0.15 + 0.75 * t);
+    };
+  }
+
+  const api = {
+    LAYOUTS,
+    VALID_WINDOWS,
+    computeDegrees,
+    windowMinTime,
+    applyControls,
+    defaultControls,
+    normalizeControls,
+    encodeControls,
+    decodeControls,
+    computeHierarchyLevels,
+    radialRadiusFn,
+  };
+
+  if (typeof module !== 'undefined' && module.exports) {
+    module.exports = api;
+  } else {
+    root.GraphControls = api;
+  }
+})(typeof window !== 'undefined' ? window : globalThis);

package/packages/client/public/graph.html

@@ -42,6 +42,41 @@
 
   <div class="graph-filters" id="graphFilters" role="toolbar" aria-label="Edge type filters"></div>
 
+  <div class="graph-filters graph-filters-row2" id="graphControls" role="toolbar" aria-label="Graph view controls">
+    <label class="graph-control graph-control-toggle" title="Drop nodes with zero edges">
+      <input type="checkbox" id="ctlHideIsolated">
+      <span>hide isolated</span>
+    </label>
+    <label class="graph-control" title="Keep nodes with at least N edges">
+      <span>min degree</span>
+      <select id="ctlMinDegree">
+        <option value="0">all</option>
+        <option value="1">≥ 1</option>
+        <option value="2">≥ 2</option>
+        <option value="3">≥ 3</option>
+        <option value="5">≥ 5</option>
+      </select>
+    </label>
+    <label class="graph-control" title="Keep nodes created within window">
+      <span>window</span>
+      <select id="ctlWindow">
+        <option value="all">all time</option>
+        <option value="7d">last 7 days</option>
+        <option value="30d">last 30 days</option>
+        <option value="90d">last 90 days</option>
+      </select>
+    </label>
+    <label class="graph-control" title="Force algorithm used to position nodes">
+      <span>layout</span>
+      <select id="ctlLayout">
+        <option value="force">force-directed</option>
+        <option value="hierarchical">hierarchical</option>
+        <option value="radial">radial</option>
+      </select>
+    </label>
+    <span class="graph-control-stat" id="ctlVisibleStat" aria-live="polite"></span>
+  </div>
+
   <main class="graph-stage" id="graphStage">
     <div class="graph-loading" id="graphLoading">
       <div class="graph-loading-spinner" aria-hidden="true"></div>
@@ -100,6 +135,7 @@
   </main>
 
   <script src="https://cdn.jsdelivr.net/npm/d3@7"></script>
+  <script src="graph-controls.js"></script>
   <script src="graph.js" defer></script>
 </body>
 </html>

package/packages/client/public/graph.js

@@ -76,14 +76,19 @@
 
   // -------- State ----------------------------------------------------------
 
+  const GC = (typeof window !== 'undefined' && window.GraphControls) || null;
+
   const state = {
     mode: 'project', // 'project' | 'memory'
     project: null,
     memoryId: null,
     depth: 2,
-    nodes: [],
-    edges: [],
+    nodes: [],          // raw nodes from /api/graph/* — unfiltered
+    edges: [],          // raw edges from /api/graph/* — unfiltered
+    visibleNodes: [],   // post-filter, what the simulation sees
+    visibleEdges: [],
     activeKinds: new Set(Object.keys(EDGE_COLORS)),
+    controls: GC ? GC.defaultControls() : { hideIsolated: false, minDegree: 0, window: 'all', layout: 'force' },
     selectedNodeId: null,
     hoverNodeId: null,
     searchTerm: '',
@@ -172,6 +177,7 @@
       state.mode = 'project';
       state.project = project;
     }
+    if (GC) state.controls = GC.decodeControls(qs);
   }
 
   function writeUrlState() {
@@ -182,6 +188,7 @@
     } else if (state.project) {
       qs.set('project', state.project);
     }
+    if (GC) GC.encodeControls(qs, state.controls);
     const url = qs.toString() ? `?${qs.toString()}` : window.location.pathname;
     window.history.replaceState(null, '', url);
   }
@@ -259,6 +266,8 @@
     // node render all paint over each other after a mode/project switch.
     hideEmpty();
     clearGraphSvg();
+    state.rawNodes = [];
+    state.rawEdges = [];
     state.nodes = [];
     state.edges = [];
     setLoading('Loading graph…');
@@ -267,18 +276,18 @@
       if (state.mode === 'project' && state.project === '__all__') {
         data = await api('/api/graph/all');
         if (data.enabled === false) return showDisabled(data);
-        state.nodes = data.nodes || [];
-        state.edges = data.edges || [];
+        state.rawNodes = data.nodes || [];
+        state.rawEdges = data.edges || [];
         if (data.truncated) {
           showToast(
-            `Showing ${state.nodes.length} most-recent of ${data.totalAvailable} memories — narrow by project to see specific clusters.`,
+            `Showing ${state.rawNodes.length} most-recent of ${data.totalAvailable} memories — narrow by project to see specific clusters.`,
           );
         }
       } else if (state.mode === 'memory') {
         data = await api(`/api/graph/memory/${encodeURIComponent(state.memoryId)}?depth=${state.depth}`);
         if (data.enabled === false) return showDisabled(data);
-        state.nodes = data.nodes || [];
-        state.edges = data.edges || [];
+        state.rawNodes = data.nodes || [];
+        state.rawEdges = data.edges || [];
         // Use the root memory's project as the view's "current project" for
         // the legend / drawer / fallback color when nodes span projects.
         if (data.root && data.root.project) state.project = data.root.project;
@@ -287,19 +296,17 @@
         state.project = name;
         data = await api(`/api/graph/project/${encodeURIComponent(name)}`);
         if (data.enabled === false) return showDisabled(data);
-        state.nodes = data.nodes || [];
-        state.edges = data.edges || [];
+        state.rawNodes = data.nodes || [];
+        state.rawEdges = data.edges || [];
       }
       writeUrlState();
       hideLoading();
-      if (state.nodes.length === 0) {
+      if (state.rawNodes.length === 0) {
         showEmpty();
         return;
       }
       hideEmpty();
-      renderFilters();
-      renderGraph();
-      updateStats();
+      applyControlsAndRender();
     } catch (err) {
       // Even on error, drop the empty-state overlay so the failure message
       // shows alone instead of stacking on top of "No memories yet".
@@ -308,6 +315,35 @@
     }
   }
 
+  // Sprint 43 T1 — re-derive state.nodes/state.edges from the raw API result
+  // and the four user controls, then drive the existing render pipeline.
+  // Called after every fetch and after any control change.
+  function applyControlsAndRender() {
+    const raw = { nodes: state.rawNodes || [], edges: state.rawEdges || [] };
+    let visible;
+    if (GC) {
+      visible = GC.applyControls(raw.nodes, raw.edges, state.controls);
+    } else {
+      visible = { nodes: raw.nodes.slice(), edges: raw.edges.slice() };
+    }
+    state.nodes = visible.nodes;
+    state.edges = visible.edges;
+    renderFilters();
+    renderGraph();
+    updateStats();
+    updateControlStat(raw.nodes.length, visible.nodes.length);
+  }
+
+  function updateControlStat(total, visible) {
+    const el = document.getElementById('ctlVisibleStat');
+    if (!el) return;
+    if (total === visible) {
+      el.textContent = '';
+    } else {
+      el.textContent = `${visible} of ${total} visible`;
+    }
+  }
+
   // -------- Render --------------------------------------------------------
 
   function setLoading(msg) {
@@ -417,6 +453,48 @@
     svg().setAttribute('height', state.height);
   }
 
+  // Sprint 43 T1 — apply layout-specific forces to the simulation.
+  //   force        — forceCenter at midpoint (default).
+  //   hierarchical — forceY from BFS levels over directional edges (supersedes /
+  //                  caused_by / blocks). Roots float top, leaves drift down.
+  //   radial       — forceRadial centered at midpoint, radius from inverse
+  //                  degree (high degree → near center).
+  function applyLayoutForces(sim, nodes, links) {
+    const cx = state.width / 2;
+    const cy = state.height / 2;
+    const layout = (state.controls && state.controls.layout) || 'force';
+
+    sim.force('center', null);
+    sim.force('hier-y', null);
+    sim.force('hier-x', null);
+    sim.force('radial', null);
+
+    if (layout === 'hierarchical' && GC) {
+      const levels = GC.computeHierarchyLevels(state.nodes, state.edges);
+      let maxLevel = 0;
+      for (const v of levels.values()) if (v > maxLevel) maxLevel = v;
+      const denom = Math.max(1, maxLevel);
+      const top = state.height * 0.10;
+      const bottom = state.height * 0.90;
+      sim.force('hier-y', window.d3.forceY((d) => {
+        const lvl = levels.get(d.id) || 0;
+        return top + (lvl / denom) * (bottom - top);
+      }).strength(0.65));
+      sim.force('hier-x', window.d3.forceX(cx).strength(0.04));
+      return;
+    }
+
+    if (layout === 'radial' && GC) {
+      const deg = GC.computeDegrees(state.nodes, state.edges);
+      const rMax = Math.min(state.width, state.height) * 0.42;
+      const radiusFn = GC.radialRadiusFn(deg, rMax);
+      sim.force('radial', window.d3.forceRadial(radiusFn, cx, cy).strength(0.55));
+      return;
+    }
+
+    sim.force('center', window.d3.forceCenter(cx, cy));
+  }
+
   function renderGraph() {
     if (!window.d3) {
       setLoading('D3.js failed to load (CDN blocked?)');
@@ -441,10 +519,11 @@
     const sim = window.d3.forceSimulation(nodes)
       .force('link', window.d3.forceLink(links).id((d) => d.id).distance((l) => 60 + (1 - (l.weight ?? 0.5)) * 40))
       .force('charge', window.d3.forceManyBody().strength(-260))
-      .force('center', window.d3.forceCenter(state.width / 2, state.height / 2))
       .force('collide', window.d3.forceCollide().radius((d) => nodeRadius(d) + 4))
       .alphaDecay(0.02);
 
+    applyLayoutForces(sim, nodes, links);
+
     state.sim = sim;
 
     const rootSel = window.d3.select(root());
@@ -742,6 +821,41 @@
     });
     $('graphFit').addEventListener('click', () => fitToView());
 
+    // Sprint 43 T1 — graph view-controls. Hydrate input values from state, then
+    // wire change handlers that mutate state.controls + URL + re-render from
+    // the cached raw fetch so toggling is fast (no API round-trip).
+    const ctlHide = $('ctlHideIsolated');
+    const ctlMin = $('ctlMinDegree');
+    const ctlWin = $('ctlWindow');
+    const ctlLay = $('ctlLayout');
+    if (ctlHide) ctlHide.checked = !!state.controls.hideIsolated;
+    if (ctlMin) ctlMin.value = String(state.controls.minDegree || 0);
+    if (ctlWin) ctlWin.value = state.controls.window || 'all';
+    if (ctlLay) ctlLay.value = state.controls.layout || 'force';
+
+    function onControlChange() {
+      state.controls = (GC ? GC.normalizeControls(state.controls) : state.controls);
+      writeUrlState();
+      if ((state.rawNodes || []).length === 0) return;
+      applyControlsAndRender();
+    }
+    if (ctlHide) ctlHide.addEventListener('change', () => {
+      state.controls.hideIsolated = !!ctlHide.checked;
+      onControlChange();
+    });
+    if (ctlMin) ctlMin.addEventListener('change', () => {
+      state.controls.minDegree = parseInt(ctlMin.value, 10) || 0;
+      onControlChange();
+    });
+    if (ctlWin) ctlWin.addEventListener('change', () => {
+      state.controls.window = ctlWin.value;
+      onControlChange();
+    });
+    if (ctlLay) ctlLay.addEventListener('change', () => {
+      state.controls.layout = ctlLay.value;
+      onControlChange();
+    });
+
     $('gdClose').addEventListener('click', closeDrawer);
     $('gdExpand').addEventListener('click', () => {
       if (!state.selectedNodeId) return;
@@ -763,7 +877,9 @@
     window.addEventListener('resize', () => {
       sizeStage();
       if (state.sim) {
-        state.sim.force('center', window.d3.forceCenter(state.width / 2, state.height / 2));
+        // Re-apply layout-specific forces with the new dimensions; this
+        // handles all three layouts (force / hierarchical / radial).
+        applyLayoutForces(state.sim, null, null);
         state.sim.alpha(0.3).restart();
       }
     });

package/packages/client/public/index.html

@@ -62,6 +62,7 @@
       <button id="btn-config">config</button>
       <button id="btn-sprint" title="Define and kick off a 4+1 sprint">sprint</button>
       <button id="btn-graph" title="Open the knowledge-graph view (memory_items + memory_relationships, force-directed)" onclick="window.open('/graph.html','_blank','noopener')">graph</button>
+      <button id="btn-flashback-history" title="Audit dashboard: every Flashback fire, dismiss/click-through funnel" onclick="window.open('/flashback-history.html','_blank','noopener')">flashback history</button>
       <button id="btn-how" title="Walkthrough of every TermDeck feature">how this works</button>
       <button id="btn-help" title="Open the TermDeck documentation" onclick="window.open('https://termdeck-docs.vercel.app','_blank','noopener')">help</button>
     </div>
@@ -135,6 +136,7 @@
       <option value="">no project</option>
     </select>
     <button class="prompt-add-project" id="btnAddProject" title="Add a new project">+</button>
+    <button class="prompt-remove-project" id="btnRemoveProject" title="Remove a project (files on disk are untouched)">−</button>
     <button class="prompt-preview-project" id="btnPreviewProject" title="Preview orchestration scaffolding for the selected project" disabled>preview</button>
     <button class="prompt-launch" id="promptLaunch">launch</button>
   </div>
@@ -169,6 +171,29 @@
     </div>
   </div>
 
+  <!-- Remove-project modal (Sprint 42 T4). Hidden by default. -->
+  <div class="remove-project-modal" id="removeProjectModal" role="dialog" aria-modal="true" aria-labelledby="rpmTitle">
+    <div class="remove-project-backdrop"></div>
+    <div class="remove-project-card">
+      <h3 id="rpmTitle">Remove a project</h3>
+      <p class="rpm-help">
+        This unregisters the project from <code>~/.termdeck/config.yaml</code>.
+        <strong>Files on disk are untouched</strong> — your source code, git history,
+        and everything at the project's path stay exactly where they are.
+      </p>
+      <label>
+        <span>Project to remove</span>
+        <select id="rpmSelect"><option value="">— pick a project —</option></select>
+      </label>
+      <div class="rpm-warning" id="rpmWarning" hidden></div>
+      <div class="rpm-status" id="rpmStatus"></div>
+      <div class="rpm-actions">
+        <button class="rpm-cancel" id="rpmCancel">cancel</button>
+        <button class="rpm-confirm" id="rpmConfirm" disabled>remove project</button>
+      </div>
+    </div>
+  </div>
+
   <!-- Orchestration-preview modal (Sprint 37 T3). Hidden by default. -->
   <div class="preview-project-modal" id="previewProjectModal" role="dialog" aria-modal="true" aria-labelledby="ppmTitle">
     <div class="preview-project-backdrop"></div>