rcf-lite 0.0.1 → 0.7.1

package/src/view/live-client.js

@@ -0,0 +1,338 @@
+// Live-view client. Loaded by the server-rendered page as
+// `<script src="/live-client.js" defer>`. Handles the SSE `/events`
+// stream, in-place `innerHTML` swaps into `#rcf-live-content`, and
+// persists `<details>` open-set + main scrollTop to `localStorage`
+// across every swap and every full reload.
+//
+// Vanilla classic script (no ESM syntax) so the base HTML script tag
+// stays plain. The IIFE exposes its internals as `window.__rcfLiveClient`
+// so `test/view/live-client.test.js` can drive them via `node:vm` without
+// jsdom.
+//
+// Spec: projects/rcf-build-lite/specs/phase-3.8-live-view.md D12, D13a,
+// D13b, D14.
+
+(function () {
+  var STORAGE_NS = 'rcf-view:v1:';
+  var STORAGE_OPEN = STORAGE_NS + 'openDetails';
+  var STORAGE_SCROLL = STORAGE_NS + 'scrollTop';
+  var HEARTBEAT_STALE_MS = 45000;
+
+  // ---- state persistence ------------------------------------------------
+
+  function safeGetItem(storage, key) {
+    try { return storage.getItem(key); } catch (e) { return null; }
+  }
+
+  function safeSetItem(storage, key, value) {
+    try { storage.setItem(key, value); return true; } catch (e) { return false; }
+  }
+
+  function snapshotState(deps) {
+    var doc = deps.document;
+    var storage = deps.storage;
+    if (!doc || !storage) return;
+    try {
+      var open = [];
+      var nodes = doc.querySelectorAll('details[data-doc-id]');
+      for (var i = 0; i < nodes.length; i += 1) {
+        var el = nodes[i];
+        if (el.open) open.push(el.getAttribute('data-doc-id'));
+      }
+      safeSetItem(storage, STORAGE_OPEN, JSON.stringify(open));
+    } catch (e) { /* soft */ }
+    try {
+      var main = doc.querySelector('main');
+      var scrollTop = 0;
+      if (main && typeof main.scrollTop === 'number') scrollTop = main.scrollTop;
+      else if (deps.window && typeof deps.window.scrollY === 'number') scrollTop = deps.window.scrollY;
+      safeSetItem(storage, STORAGE_SCROLL, String(scrollTop));
+    } catch (e) { /* soft */ }
+  }
+
+  function loadOpenSet(storage) {
+    var raw = safeGetItem(storage, STORAGE_OPEN);
+    if (!raw) return [];
+    try {
+      var parsed = JSON.parse(raw);
+      if (Array.isArray(parsed)) return parsed.filter(function (id) { return typeof id === 'string'; });
+    } catch (e) { /* soft */ }
+    return [];
+  }
+
+  function cssEscape(id) {
+    return String(id).replace(/["\\]/g, function (c) { return '\\' + c; });
+  }
+
+  function restoreState(deps) {
+    var doc = deps.document;
+    var storage = deps.storage;
+    if (!doc || !storage) return { openedCount: 0, droppedIds: [], scrollTop: null };
+    var wanted = loadOpenSet(storage);
+    var opened = 0;
+    var dropped = [];
+    for (var i = 0; i < wanted.length; i += 1) {
+      var id = wanted[i];
+      var sel = 'details[data-doc-id="' + cssEscape(id) + '"]';
+      var el = null;
+      try { el = doc.querySelector(sel); } catch (e) { el = null; }
+      if (el) {
+        el.open = true;
+        opened += 1;
+      } else {
+        dropped.push(id);
+      }
+    }
+    if (dropped.length > 0) {
+      // Stale-key hygiene: rewrite the persisted set with only the ids
+      // that still exist. Silent - no console output for expected drift.
+      var kept = wanted.filter(function (id) { return dropped.indexOf(id) === -1; });
+      safeSetItem(storage, STORAGE_OPEN, JSON.stringify(kept));
+    }
+
+    var scrollTop = null;
+    var raw = safeGetItem(storage, STORAGE_SCROLL);
+    if (raw != null) {
+      var n = Number(raw);
+      if (isFinite(n)) {
+        scrollTop = n;
+        var main = doc.querySelector('main');
+        try {
+          if (main) main.scrollTop = n;
+          else if (deps.window && typeof deps.window.scrollTo === 'function') deps.window.scrollTo(0, n);
+        } catch (e) { /* soft */ }
+      }
+    }
+    return { openedCount: opened, droppedIds: dropped, scrollTop: scrollTop };
+  }
+
+  // ---- connection state machine -----------------------------------------
+
+  // Inputs: readyState of EventSource (CONNECTING=0, OPEN=1, CLOSED=2),
+  // ms since last heartbeat (any type of event resets this). Output is
+  // one of 'connected' | 'reconnecting' | 'disconnected'.
+  function classifyConnection(state) {
+    var rs = state.readyState;
+    var since = state.msSinceLastEvent;
+    if (rs === 2) return 'disconnected';
+    if (rs === 0) return 'reconnecting';
+    if (typeof since === 'number' && since > HEARTBEAT_STALE_MS) return 'reconnecting';
+    return 'connected';
+  }
+
+  // ---- version de-dup ---------------------------------------------------
+
+  function shouldApplyUpdate(currentVersion, nextVersion) {
+    if (typeof nextVersion !== 'number' || !isFinite(nextVersion)) return true;
+    if (currentVersion === null || currentVersion === undefined) return true;
+    return nextVersion > currentVersion;
+  }
+
+  // ---- browser boot ------------------------------------------------------
+
+  function bootBrowser(win) {
+    var doc = win.document;
+    var storage;
+    try { storage = win.localStorage; } catch (e) { storage = null; }
+    var deps = { document: doc, storage: storage || memoryStorage(), window: win };
+
+    // Inject the connection-status dot into the header. Kept out of the
+    // server-rendered HTML so the layout-regression baseline stays clean
+    // (only the wrapper + script tag + raw-json data-doc-id are the
+    // whitelisted deltas from Phase 3.6).
+    injectConnectionDot(doc);
+
+    // Restore prior state on initial load.
+    if (doc.readyState === 'loading') {
+      doc.addEventListener('DOMContentLoaded', function () { restoreState(deps); });
+    } else {
+      restoreState(deps);
+    }
+
+    var currentVersion = null;
+    var lastEventAt = Date.now();
+    var connState = 'reconnecting';
+
+    function setState(next) {
+      if (next === connState) return;
+      connState = next;
+      updateDot(doc, next);
+    }
+
+    // Snapshot on navigate-away / hide.
+    win.addEventListener('beforeunload', function () { snapshotState(deps); });
+    doc.addEventListener('visibilitychange', function () {
+      if (doc.visibilityState === 'hidden') snapshotState(deps);
+    });
+
+    var EventSourceCtor = win.EventSource;
+    if (typeof EventSourceCtor !== 'function') {
+      setState('disconnected');
+      return;
+    }
+    var source = new EventSourceCtor('/events');
+
+    source.onopen = function () {
+      lastEventAt = Date.now();
+      setState('connected');
+    };
+    source.onerror = function () {
+      // EventSource sets readyState internally. Native reconnect keeps
+      // trying while readyState is CONNECTING.
+      var rs = typeof source.readyState === 'number' ? source.readyState : 2;
+      setState(classifyConnection({ readyState: rs, msSinceLastEvent: Date.now() - lastEventAt }));
+    };
+
+    source.addEventListener('tree-update', function (ev) {
+      lastEventAt = Date.now();
+      var payload;
+      try { payload = JSON.parse(ev.data); } catch (e) { return; }
+      if (!shouldApplyUpdate(currentVersion, payload.version)) return;
+      snapshotState(deps);
+      var host = doc.querySelector('#rcf-live-content');
+      if (host && typeof payload.contentHtml === 'string') {
+        host.innerHTML = payload.contentHtml;
+      }
+      currentVersion = payload.version;
+      // Tab buttons live in the header (outside the swap wrapper) so
+      // their click handlers survive. But the swap serves every panel
+      // with the same `hidden` state Phase 3.6 renders (Overview
+      // visible, others hidden), so we resync visibility with the
+      // currently-selected tab and re-run Mermaid in it. Also re-run
+      // Mermaid inside the selected panel because .mermaid nodes in
+      // the payload have no `data-processed` yet.
+      resyncTabsAfterSwap(doc, win);
+      restoreState(deps);
+      setState('connected');
+    });
+
+    source.addEventListener('heartbeat', function () {
+      lastEventAt = Date.now();
+      setState('connected');
+    });
+
+    source.addEventListener('walker-error', function (ev) {
+      lastEventAt = Date.now();
+      // Errors also render inline via the next tree-update; nothing
+      // else to do client-side for now.
+      try {
+        var payload = JSON.parse(ev.data);
+        if (win.rcfPage) win.rcfPage._lastWalkerErrors = payload.errors;
+      } catch (e) { /* soft */ }
+    });
+
+    source.addEventListener('shutdown', function () {
+      setState('disconnected');
+      try { source.close(); } catch (e) { /* soft */ }
+    });
+
+    // Idle liveness check: if no event in the heartbeat-stale window,
+    // demote the dot to reconnecting even if the socket has not thrown
+    // an error yet.
+    var pollId = win.setInterval(function () {
+      var rs = typeof source.readyState === 'number' ? source.readyState : 1;
+      setState(classifyConnection({ readyState: rs, msSinceLastEvent: Date.now() - lastEventAt }));
+    }, 5000);
+    if (pollId && typeof pollId.unref === 'function') pollId.unref();
+  }
+
+  // After an SSE innerHTML swap, the tab bar in the header still shows
+  // the tab the user was on (its click handlers survived because the
+  // header was not replaced) but every freshly-inserted panel has the
+  // Overview-visible default from the server-rendered content. Bring
+  // the panels back in line with the aria-selected button and re-run
+  // Mermaid in the visible one.
+  function resyncTabsAfterSwap(doc, win) {
+    var TABS = ['overview', 'requirements', 'architecture', 'build'];
+    var selectedBtn = doc.querySelector('[role="tab"][aria-selected="true"]');
+    var selected = selectedBtn && selectedBtn.getAttribute ? selectedBtn.getAttribute('data-tab') : null;
+    if (!selected || TABS.indexOf(selected) === -1) selected = 'overview';
+    for (var i = 0; i < TABS.length; i += 1) {
+      var name = TABS[i];
+      var panel = doc.getElementById('tab-' + name);
+      if (!panel) continue;
+      if (name === selected) panel.removeAttribute('hidden');
+      else panel.setAttribute('hidden', '');
+    }
+    var visible = doc.getElementById('tab-' + selected);
+    try {
+      if (visible && win && win.mermaid && typeof win.mermaid.run === 'function') {
+        var pending = visible.querySelectorAll('.mermaid:not([data-processed="true"])');
+        if (pending.length > 0) {
+          win.mermaid.run({ nodes: Array.prototype.slice.call(pending) });
+        }
+      }
+    } catch (e) { /* soft */ }
+  }
+
+  function memoryStorage() {
+    var m = Object.create(null);
+    return {
+      getItem: function (k) { return Object.prototype.hasOwnProperty.call(m, k) ? m[k] : null; },
+      setItem: function (k, v) { m[k] = String(v); },
+      removeItem: function (k) { delete m[k]; },
+    };
+  }
+
+  function injectConnectionDot(doc) {
+    if (doc.getElementById('rcf-conn-dot')) return;
+    var style = doc.createElement('style');
+    style.textContent = [
+      '#rcf-conn-dot {',
+      '  position: fixed; top: 12px; right: 12px;',
+      '  width: 10px; height: 10px; border-radius: 50%;',
+      '  background: #999; opacity: 0.65; z-index: 9999;',
+      '  transition: background 120ms ease-in-out;',
+      '}',
+      '#rcf-conn-dot.connected { background: #4c9a2a; }',
+      '#rcf-conn-dot.reconnecting { background: #d68f00; }',
+      '#rcf-conn-dot.disconnected { background: #b03a2e; }',
+    ].join('\n');
+    doc.head.appendChild(style);
+    var dot = doc.createElement('span');
+    dot.id = 'rcf-conn-dot';
+    dot.className = 'reconnecting';
+    dot.setAttribute('role', 'status');
+    dot.setAttribute('aria-live', 'polite');
+    dot.title = 'Connecting to view server...';
+    doc.body.appendChild(dot);
+  }
+
+  function updateDot(doc, state) {
+    var dot = doc.getElementById('rcf-conn-dot');
+    if (!dot) return;
+    dot.className = state;
+    if (state === 'connected') dot.title = 'Connected - live updates on';
+    else if (state === 'reconnecting') dot.title = 'Reconnecting to view server...';
+    else dot.title = 'Disconnected from view server';
+  }
+
+  // ---- module exports (for node:vm tests) --------------------------------
+
+  var api = {
+    snapshotState: snapshotState,
+    restoreState: restoreState,
+    classifyConnection: classifyConnection,
+    shouldApplyUpdate: shouldApplyUpdate,
+    loadOpenSet: loadOpenSet,
+    memoryStorage: memoryStorage,
+    injectConnectionDot: injectConnectionDot,
+    updateDot: updateDot,
+    resyncTabsAfterSwap: resyncTabsAfterSwap,
+    STORAGE_OPEN: STORAGE_OPEN,
+    STORAGE_SCROLL: STORAGE_SCROLL,
+    HEARTBEAT_STALE_MS: HEARTBEAT_STALE_MS,
+    bootBrowser: bootBrowser,
+  };
+
+  if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+    window.__rcfLiveClient = api;
+    try { bootBrowser(window); } catch (e) {
+      // Never let a client-side boot fault break the page.
+      try { window.console && window.console.error && window.console.error('[rcf-live-client]', e); } catch (_e) { /* soft */ }
+    }
+  } else if (typeof globalThis !== 'undefined') {
+    // Non-browser context (e.g. node:vm test harness with no window/document).
+    globalThis.__rcfLiveClient = api;
+  }
+})();

package/src/view/mermaid-diagram.js

@@ -0,0 +1,178 @@
+// Mermaid diagram emission. Phase 3.6 removed the top-of-Overview-tab
+// diagram: at ~7 REQs it was already stacking vertically and the PRD
+// body already lists the requirement links inline. Per-requirement
+// subdiagrams (REQ -> US -> AC + FBS delivery) remain - they add
+// actual structural information per REQ. Click bindings anchor into
+// the hash-routed doc DOM (D5, D7).
+//
+// Node classes match the CSS palette in style.css. Broken nodes carry the
+// `broken` class (dashed border, distinct colour). FBS-to-AC edges are
+// dashed; FBS dependencies are dotted; FBS context (TAC / ADR) edges are
+// dotted-thick.
+
+const NODE_LABEL = {
+  prd: 'PRD',
+  req: 'REQ',
+  us: 'US',
+  ac: 'AC',
+  tad: 'TAD',
+  tac: 'TAC',
+  adr: 'ADR',
+  bs: 'BS',
+  fbs: 'FBS',
+};
+
+/**
+ * Mermaid is strict about id syntax: `-` is fine but parentheses, quotes
+ * and unicode chars are not. Document ids are already safe (e.g. "REQ-002");
+ * we just wrap labels in quotes.
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+function nodeId(id) {
+  return id;
+}
+
+function nodeLabel(id, model) {
+  const doc = model.byId.get(id);
+  const title = pickTitle(doc, id);
+  if (!title) return `"${id}"`;
+  const safe = title.replace(/"/g, "'").replace(/\n/g, ' ');
+  const trimmed = safe.length > 48 ? `${safe.slice(0, 45)}...` : safe;
+  return `"${id}<br/>${trimmed}"`;
+}
+
+function pickTitle(doc, id) {
+  if (!doc) return null;
+  if (typeof doc.title === 'string') return doc.title;
+  if (typeof doc.name === 'string') return doc.name;
+  if (typeof doc.productName === 'string') return doc.productName;
+  // Phase 10 (X2 CodeNode bridge): CN documents often carry no title, but
+  // `path` is the identity that matters visually - show it in preference to
+  // falling straight back to the bare id.
+  if (typeof doc.path === 'string') return doc.path;
+  if (typeof doc.description === 'string') return doc.description;
+  return id;
+}
+
+function classForId(id) {
+  if (id.startsWith('PRD-')) return 'prd';
+  if (id.startsWith('REQ-')) return 'req';
+  if (id.startsWith('US-')) return 'us';
+  if (id.startsWith('AC-')) return 'ac';
+  if (id.startsWith('TAD-')) return 'tad';
+  if (id.startsWith('TAC-')) return 'tac';
+  if (id.startsWith('ADR-')) return 'adr';
+  if (id.startsWith('BS-')) return 'bs';
+  if (id.startsWith('FBS-')) return 'fbs';
+  if (id.startsWith('TS-')) return 'ts';
+  if (id.startsWith('TC-')) return 'tc';
+  // Phase 10 (X2 CodeNode bridge, spec D12): CN cosmetic class.
+  if (id.startsWith('CN-')) return 'cn';
+  return 'unknown';
+}
+
+const CLASS_DEFS = `
+  classDef prd fill:#fde68a,stroke:#92400e,color:#1f2937;
+  classDef req fill:#bbf7d0,stroke:#065f46,color:#1f2937;
+  classDef us fill:#bae6fd,stroke:#0c4a6e,color:#1f2937;
+  classDef ac fill:#e0e7ff,stroke:#3730a3,color:#1f2937;
+  classDef tad fill:#fecaca,stroke:#991b1b,color:#1f2937;
+  classDef tac fill:#fed7aa,stroke:#9a3412,color:#1f2937;
+  classDef adr fill:#fbcfe8,stroke:#9d174d,color:#1f2937;
+  classDef bs fill:#ddd6fe,stroke:#5b21b6,color:#1f2937;
+  classDef fbs fill:#c7d2fe,stroke:#3730a3,color:#1f2937;
+  classDef ts fill:#99f6e4,stroke:#115e59,color:#1f2937;
+  classDef tc fill:#d9f99d,stroke:#3f6212,color:#1f2937;
+  classDef cn fill:#a5b4fc,stroke:#312e81,color:#1f2937;
+  classDef broken stroke:#dc2626,stroke-width:2px,stroke-dasharray:5 5,color:#7f1d1d;
+`.trim();
+
+function emitClick(id) {
+  return `  click ${nodeId(id)} "#${id}";`;
+}
+
+function emitClassAssignments(ids, model) {
+  const lines = [];
+  for (const id of ids) {
+    const cls = classForId(id);
+    if (cls !== 'unknown') {
+      lines.push(`  class ${nodeId(id)} ${cls};`);
+    }
+    if (model.brokenIds.has(id)) {
+      lines.push(`  class ${nodeId(id)} broken;`);
+    }
+  }
+  return lines;
+}
+
+/**
+ * Build a per-REQ subdiagram (`flowchart LR`).
+ *
+ * @param {import('./tree-model.js').BuiltTreeModel} model
+ * @param {object} req - the requirement document
+ * @returns {string}
+ */
+export function requirementSubdiagram(model, req) {
+  if (!req?.reqId) return 'flowchart LR\n  empty[No requirement provided]';
+  /** @type {string[]} */
+  const lines = ['flowchart LR'];
+  /** @type {Set<string>} */
+  const declared = new Set();
+  /** @type {Set<string>} */
+  const allIds = new Set();
+  const declare = (id) => {
+    if (declared.has(id)) return;
+    declared.add(id);
+    allIds.add(id);
+    lines.push(`  ${nodeId(id)}[${nodeLabel(id, model)}]`);
+  };
+
+  declare(req.reqId);
+  const stories = model.storiesByReqId.get(req.reqId) ?? [];
+  for (const us of stories) {
+    declare(us.usId);
+    lines.push(`  ${nodeId(req.reqId)} --> ${nodeId(us.usId)}`);
+    for (const ac of us.acceptanceCriteria ?? []) {
+      declare(ac.id);
+      lines.push(`  ${nodeId(us.usId)} --> ${nodeId(ac.id)}`);
+      const fbsList = model.fbsByAcId.get(ac.id) ?? [];
+      for (const f of fbsList) {
+        declare(f.fbsId);
+        // Edge direction reversed so LR layout places FBS to the right of
+        // its AC (reads "AC ... delivered by ... FBS"). Same relationship
+        // as the old FBS->AC edge; just laid out more naturally.
+        lines.push(`  ${nodeId(ac.id)} -.->|delivered by| ${nodeId(f.fbsId)}`);
+      }
+      // Phase 10 (X2 CodeNode bridge, spec D12): Code Nodes implementing
+      // this AC. Empty when no code-nodes/ dir exists, so a spec-only tree
+      // renders byte-identical to pre-Phase-10 output.
+      const cnList = model.cnByAcId?.get(ac.id) ?? [];
+      for (const cnId of cnList) {
+        declare(cnId);
+        lines.push(`  ${nodeId(ac.id)} -.->|implemented by| ${nodeId(cnId)}`);
+      }
+    }
+  }
+
+  for (const id of allIds) lines.push(emitClick(id));
+  lines.push(...emitClassAssignments([...allIds], model));
+  lines.push(CLASS_DEFS);
+  return lines.join('\n');
+}
+
+/**
+ * Build every per-REQ subdiagram, keyed by reqId.
+ *
+ * @param {import('./tree-model.js').BuiltTreeModel} model
+ * @returns {Map<string, string>}
+ */
+export function allRequirementSubdiagrams(model) {
+  const out = new Map();
+  for (const req of model.requirements) {
+    if (!req?.reqId) continue;
+    out.set(req.reqId, requirementSubdiagram(model, req));
+  }
+  return out;
+}