@ijfw/memory-server 1.4.1 → 1.4.4

package/src/dashboard-aggregator.js

@@ -0,0 +1,165 @@
+/**
+ * dashboard-aggregator.js — IJFW v1.4.3 W9-C (B19)
+ *
+ * Server-side aggregation of ~/.ijfw/state/permission-events.jsonl for the
+ * dashboard's per-tool audit charts. Reads only the last TAIL_CHUNK bytes
+ * (same 2MB cap as the events endpoint) so this is bounded-memory even
+ * across rotations.
+ *
+ * Cache: 60s OR until the events file mtime changes, whichever first.
+ * Malformed JSONL lines are dropped silently — never crash the dashboard
+ * on a partial write.
+ *
+ * Returned shape:
+ *   {
+ *     hourly:        { [hourISO]: count },
+ *     by_extension:  { [ext]:    { allowed: number, denied: number } },
+ *     by_tool_denied:{ [tool]:   count }
+ *   }
+ *
+ * Helper `computeWarnBashBypass(manifest)` implements ARCH-M-01: an extension
+ * with `tool:bash` or `tool:exec` in writes AND a strict files/bytes quota
+ * declared in the manifest gets a warning chip in the dashboard. The chip is
+ * an information channel — quota enforcement still applies, but bash content
+ * bypasses per-file accounting at the API surface.
+ */
+
+import { existsSync, statSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// Match dashboard-server's TAIL_CHUNK. Kept here so this module is
+// self-contained for the test harness.
+export const TAIL_CHUNK = 2 * 1024 * 1024; // 2MB
+const CACHE_TTL_MS = 60_000;
+
+// Module-level cache. Key = canonical path; value = { mtimeMs, builtAt, result }.
+const _cache = new Map();
+
+export function _resetAggregatorCacheForTest() {
+  _cache.clear();
+}
+
+function _readTailLines(eventsPath) {
+  if (!existsSync(eventsPath)) return { lines: [], mtimeMs: 0 };
+  let st;
+  try { st = statSync(eventsPath); } catch { return { lines: [], mtimeMs: 0 }; }
+  if (!st.size) return { lines: [], mtimeMs: st.mtimeMs };
+  let buf;
+  try { buf = readFileSync(eventsPath); } catch { return { lines: [], mtimeMs: st.mtimeMs }; }
+  const slice = buf.subarray(Math.max(0, buf.length - TAIL_CHUNK));
+  let lines = slice.toString('utf8').split('\n').filter(Boolean);
+  // If we sliced mid-line, drop the partial leading element.
+  if (buf.length > TAIL_CHUNK) lines = lines.slice(1);
+  return { lines, mtimeMs: st.mtimeMs };
+}
+
+function _hourBucket(tsMs) {
+  const d = new Date(tsMs);
+  d.setUTCMinutes(0, 0, 0);
+  return d.toISOString();
+}
+
+/**
+ * Aggregate permission events within `windowMs` of `now`.
+ *
+ * @param {string} eventsPath  absolute path to permission-events.jsonl
+ * @param {{ windowMs?: number, now?: number }} [opts]
+ */
+export async function aggregateEvents(eventsPath, opts = {}) {
+  const windowMs = (opts && typeof opts.windowMs === 'number') ? opts.windowMs : 24 * 3600 * 1000;
+  const now      = (opts && typeof opts.now      === 'number') ? opts.now      : Date.now();
+
+  const { lines, mtimeMs } = _readTailLines(eventsPath);
+
+  const cached = _cache.get(eventsPath);
+  if (cached
+      && cached.mtimeMs === mtimeMs
+      && (now - cached.builtAt) < CACHE_TTL_MS
+      && cached.windowMs === windowMs) {
+    return cached.result;
+  }
+
+  const cutoff = now - windowMs;
+  const hourly         = Object.create(null);
+  const byExt          = Object.create(null);
+  const byToolDenied   = Object.create(null);
+
+  for (const line of lines) {
+    let obj;
+    try { obj = JSON.parse(line); } catch { continue; }
+    if (!obj || typeof obj !== 'object') continue;
+    const t = typeof obj.ts === 'string' ? Date.parse(obj.ts) : (typeof obj.ts === 'number' ? obj.ts : NaN);
+    if (!Number.isFinite(t)) continue;
+    if (t < cutoff) continue;
+
+    const ext     = (typeof obj.extension === 'string' && obj.extension) ? obj.extension : '<unknown>';
+    const tool    = (typeof obj.tool === 'string' && obj.tool) ? obj.tool : (typeof obj.action === 'string' ? obj.action : '<unknown>');
+    const allowed = obj.allowed !== false; // anything other than explicit false is allowed.
+
+    // hourly
+    const hk = _hourBucket(t);
+    hourly[hk] = (hourly[hk] || 0) + 1;
+
+    // by_extension
+    if (!byExt[ext]) byExt[ext] = { allowed: 0, denied: 0 };
+    if (allowed) byExt[ext].allowed += 1;
+    else         byExt[ext].denied  += 1;
+
+    // by_tool_denied
+    if (!allowed) {
+      byToolDenied[tool] = (byToolDenied[tool] || 0) + 1;
+    }
+  }
+
+  const result = { hourly, by_extension: byExt, by_tool_denied: byToolDenied };
+  _cache.set(eventsPath, { mtimeMs, builtAt: now, windowMs, result });
+  return result;
+}
+
+/**
+ * ARCH-M-01: compute whether an extension's manifest combines a bash/exec
+ * write permission with a strict files/bytes quota.
+ *
+ * Returns true iff:
+ *   manifest.permissions.writes includes "tool:bash" or "tool:exec"
+ *   AND (quotas.max_files_written OR quotas.max_bytes_written is set)
+ */
+export function computeWarnBashBypass(manifest) {
+  if (!manifest || typeof manifest !== 'object') return false;
+  const perms = manifest.permissions || {};
+  const writes = Array.isArray(perms.writes) ? perms.writes : [];
+  const hasBashOrExec = writes.some((w) => w === 'tool:bash' || w === 'tool:exec');
+  if (!hasBashOrExec) return false;
+  const q = manifest.quotas || {};
+  const hasStrictQuota =
+    (typeof q.max_files_written === 'number' && Number.isFinite(q.max_files_written)) ||
+    (typeof q.max_bytes_written === 'number' && Number.isFinite(q.max_bytes_written));
+  return Boolean(hasStrictQuota);
+}
+
+/**
+ * Resolve `<scope>/<name>/manifest.json` and read it. Returns the parsed
+ * manifest object or `null` if the file is missing/unreadable/malformed.
+ *
+ * Scope→path map mirrors `active-extension-writer.js`:
+ *   project: <projectRoot>/.ijfw/extensions/<name>/manifest.json
+ *   org:     <home>/.ijfw/extensions-org/<name>/manifest.json
+ *   user:    <home>/.ijfw/extensions-user/<name>/manifest.json
+ */
+export function readActiveManifest({ scope, name, home, projectRoot }) {
+  if (!scope || !name) return null;
+  let path = null;
+  if (scope === 'project' && projectRoot) {
+    path = join(projectRoot, '.ijfw', 'extensions', name, 'manifest.json');
+  } else if (scope === 'org' && home) {
+    path = join(home, '.ijfw', 'extensions-org', name, 'manifest.json');
+  } else if (scope === 'user' && home) {
+    path = join(home, '.ijfw', 'extensions-user', name, 'manifest.json');
+  }
+  if (!path) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}

package/src/dashboard-charts.js

@@ -0,0 +1,239 @@
+/**
+ * dashboard-charts.js — IJFW v1.4.3 W9-C (B19)
+ *
+ * Pure-JS canvas/DOM chart helpers for the dashboard. No external libs.
+ * Theme-aware: reads CSS custom properties `--ijfw-chart-fg`,
+ * `--ijfw-chart-bg`, `--ijfw-chart-warning` from the element's computed
+ * style. Falls back to sane defaults if the host page hasn't set them.
+ *
+ * All helpers are defensive against malformed input so a bad payload from
+ * the API can never throw inside the dashboard render loop.
+ */
+
+const DEFAULTS = {
+  fg: '#9ad2ff',
+  bg: 'rgba(154,210,255,0.18)',
+  warning: '#ff9b3a',
+  text: '#cfd6dd',
+};
+
+function _readTheme(el) {
+  // Both `canvas` and plain `div` go through `getComputedStyle`. In the test
+  // environment the element is a hand-rolled mock that doesn't reach the DOM
+  // — guard so we don't blow up if `getComputedStyle` is unavailable.
+  let cs = null;
+  try {
+    if (el && typeof globalThis.getComputedStyle === 'function') {
+      cs = globalThis.getComputedStyle(el);
+    }
+  } catch { cs = null; }
+  const read = (prop, fallback) => {
+    if (!cs || typeof cs.getPropertyValue !== 'function') return fallback;
+    const v = cs.getPropertyValue(prop);
+    return (v && v.trim()) ? v.trim() : fallback;
+  };
+  return {
+    fg:      read('--ijfw-chart-fg',      DEFAULTS.fg),
+    bg:      read('--ijfw-chart-bg',      DEFAULTS.bg),
+    warning: read('--ijfw-chart-warning', DEFAULTS.warning),
+    text:    read('--ijfw-chart-text',    DEFAULTS.text),
+  };
+}
+
+function _safeNum(v, def = 0) {
+  return (typeof v === 'number' && Number.isFinite(v)) ? v : def;
+}
+
+/**
+ * lineChart(canvas, points, opts)
+ *   points: [{ x: number, y: number }, ...] OR [number, ...]
+ *   opts:   { xMin?, xMax?, yMax?, color?, fill? }
+ *
+ * Empty data renders nothing (clears the canvas) without throwing.
+ */
+export function lineChart(canvas, points, opts = {}) {
+  if (!canvas || typeof canvas.getContext !== 'function') return;
+  const ctx = canvas.getContext('2d');
+  if (!ctx) return;
+  const W = _safeNum(canvas.width, 200);
+  const H = _safeNum(canvas.height, 100);
+  const theme = _readTheme(canvas);
+  const color = opts.color || theme.fg;
+  const fill  = opts.fill === false ? null : theme.bg;
+
+  try { ctx.clearRect(0, 0, W, H); } catch {}
+
+  const pts = Array.isArray(points) ? points : [];
+  const norm = pts.map((p, i) => {
+    if (typeof p === 'number') return { x: i, y: _safeNum(p, 0) };
+    return { x: _safeNum(p && p.x, i), y: _safeNum(p && p.y, 0) };
+  }).filter((p) => Number.isFinite(p.x) && Number.isFinite(p.y));
+
+  if (norm.length === 0) return;
+
+  let xMin = _safeNum(opts.xMin, norm[0].x);
+  let xMax = _safeNum(opts.xMax, norm[norm.length - 1].x);
+  if (xMax === xMin) xMax = xMin + 1;
+  const yMax = _safeNum(opts.yMax, Math.max(1, ...norm.map((p) => p.y)));
+  const yScale = yMax > 0 ? yMax : 1;
+
+  const pad = 4;
+  const innerW = Math.max(1, W - pad * 2);
+  const innerH = Math.max(1, H - pad * 2);
+
+  const px = (x) => pad + ((x - xMin) / (xMax - xMin)) * innerW;
+  const py = (y) => pad + (1 - (Math.max(0, y) / yScale)) * innerH;
+
+  // Filled area
+  if (fill) {
+    try {
+      ctx.beginPath();
+      ctx.moveTo(px(norm[0].x), H - pad);
+      for (const p of norm) ctx.lineTo(px(p.x), py(p.y));
+      ctx.lineTo(px(norm[norm.length - 1].x), H - pad);
+      ctx.closePath();
+      ctx.fillStyle = fill;
+      ctx.fill();
+    } catch {}
+  }
+
+  // Line stroke
+  try {
+    ctx.beginPath();
+    ctx.moveTo(px(norm[0].x), py(norm[0].y));
+    for (let i = 1; i < norm.length; i++) ctx.lineTo(px(norm[i].x), py(norm[i].y));
+    ctx.strokeStyle = color;
+    ctx.lineWidth   = 1.5;
+    ctx.stroke();
+  } catch {}
+}
+
+/**
+ * barChart(canvas, bars, opts)
+ *   bars: [{ label: string, value: number, color?: string }, ...]
+ *   opts: { horizontal?: boolean, color?: string, maxValue?: number }
+ *
+ * Zero-value bars render as empty rails. Negative values are clamped to 0.
+ */
+export function barChart(canvas, bars, opts = {}) {
+  if (!canvas || typeof canvas.getContext !== 'function') return;
+  const ctx = canvas.getContext('2d');
+  if (!ctx) return;
+  const W = _safeNum(canvas.width, 200);
+  const H = _safeNum(canvas.height, 100);
+  const theme = _readTheme(canvas);
+  const defaultColor = opts.color || theme.fg;
+  const horizontal = Boolean(opts.horizontal);
+
+  try { ctx.clearRect(0, 0, W, H); } catch {}
+
+  const rows = Array.isArray(bars) ? bars.filter((b) => b && typeof b === 'object') : [];
+  if (rows.length === 0) return;
+
+  const values = rows.map((b) => Math.max(0, _safeNum(b.value, 0)));
+  const maxVal = _safeNum(opts.maxValue, Math.max(1, ...values));
+  const scale = maxVal > 0 ? maxVal : 1;
+
+  const pad = 4;
+  const labelGutter = horizontal ? 80 : 14;
+  const innerW = Math.max(1, W - pad * 2 - (horizontal ? labelGutter : 0));
+  const innerH = Math.max(1, H - pad * 2 - (horizontal ? 0 : labelGutter));
+  const slot = (horizontal ? innerH : innerW) / rows.length;
+  const barW = Math.max(1, slot * 0.7);
+
+  for (let i = 0; i < rows.length; i++) {
+    const b = rows[i];
+    const v = values[i];
+    const color = b.color || defaultColor;
+    if (horizontal) {
+      const y = pad + i * slot + (slot - barW) / 2;
+      const len = (v / scale) * innerW;
+      try {
+        ctx.fillStyle = theme.bg;
+        ctx.fillRect(pad + labelGutter, y, innerW, barW);
+        ctx.fillStyle = color;
+        ctx.fillRect(pad + labelGutter, y, len, barW);
+        ctx.fillStyle = theme.text;
+        ctx.fillText(String(b.label || ''), pad, y + barW * 0.75);
+      } catch {}
+    } else {
+      const x = pad + i * slot + (slot - barW) / 2;
+      const len = (v / scale) * innerH;
+      try {
+        ctx.fillStyle = theme.bg;
+        ctx.fillRect(x, pad, barW, innerH);
+        ctx.fillStyle = color;
+        ctx.fillRect(x, pad + (innerH - len), barW, len);
+        ctx.fillStyle = theme.text;
+        ctx.fillText(String(b.label || '').slice(0, 8), x, H - pad);
+      } catch {}
+    }
+  }
+}
+
+/**
+ * progressBar(div, data)
+ *   data: { current: number, limit: number | null, label?: string, warning?: boolean }
+ *
+ * Mutates `div` in place. Renders an "unlimited" placeholder when limit is
+ * null. Applies a warning class when `warning` is truthy.
+ */
+export function progressBar(div, data = {}) {
+  if (!div) return;
+  const theme = _readTheme(div);
+  const cur = Math.max(0, _safeNum(data.current, 0));
+  const lim = (data.limit === null || data.limit === undefined) ? null : _safeNum(data.limit, null);
+  const label = typeof data.label === 'string' ? data.label : '';
+  const warn = Boolean(data.warning);
+
+  // Clear children.
+  try {
+    while (div.firstChild) div.removeChild(div.firstChild);
+  } catch {
+    // Some test mocks omit firstChild/removeChild. Skip cleanup.
+  }
+
+  const setClass = (extra) => {
+    try {
+      div.className = ['ijfw-progress', extra, warn ? 'ijfw-progress--warn' : '']
+        .filter(Boolean).join(' ');
+    } catch {}
+  };
+
+  // Helper to create child elements safely.
+  function appendEl(tag, opts) {
+    try {
+      if (typeof div.ownerDocument === 'object' && div.ownerDocument && typeof div.ownerDocument.createElement === 'function') {
+        const el = div.ownerDocument.createElement(tag);
+        if (opts && opts.text) el.textContent = opts.text;
+        if (opts && opts.style) el.setAttribute('style', opts.style);
+        if (opts && opts.cls) el.className = opts.cls;
+        if (typeof div.appendChild === 'function') div.appendChild(el);
+        return el;
+      }
+    } catch {}
+    return null;
+  }
+
+  if (lim === null) {
+    setClass('ijfw-progress--unlimited');
+    appendEl('span', { cls: 'ijfw-progress-label', text: label });
+    appendEl('span', { cls: 'ijfw-progress-val',   text: cur + ' / unlimited' });
+    return;
+  }
+
+  setClass('');
+  const denom = lim > 0 ? lim : 1;
+  const pct = Math.max(0, Math.min(100, (cur / denom) * 100));
+  appendEl('span', { cls: 'ijfw-progress-label', text: label });
+  const rail = appendEl('span', { cls: 'ijfw-progress-rail', style: 'background:' + theme.bg + ';display:inline-block;height:6px;width:120px;border-radius:3px;overflow:hidden;vertical-align:middle;margin:0 6px' });
+  if (rail) {
+    try {
+      const fill = (rail.ownerDocument || div.ownerDocument).createElement('span');
+      fill.className = 'ijfw-progress-fill';
+      fill.setAttribute('style', 'display:block;height:100%;width:' + pct.toFixed(1) + '%;background:' + (warn ? theme.warning : theme.fg));
+      rail.appendChild(fill);
+    } catch {}
+  }
+  appendEl('span', { cls: 'ijfw-progress-val', text: cur + ' / ' + lim });
+}

package/src/dashboard-client-planning.html

@@ -0,0 +1,273 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>IJFW · Planning Docs</title>
+<style>
+  :root { color-scheme: light dark; }
+  * { box-sizing: border-box; }
+  body { margin: 0; font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: #fafafa; color: #222; }
+  header { padding: 12px 20px; border-bottom: 1px solid #ddd; background: #fff; }
+  header h1 { margin: 0; font-size: 18px; font-weight: 600; }
+  header .sub { color: #777; font-size: 12px; margin-top: 4px; }
+  main { padding: 20px; max-width: 900px; margin: 0 auto; }
+  .path-input { width: 100%; padding: 8px 10px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 13px; border: 1px solid #ccc; border-radius: 4px; }
+  .roots { color: #777; font-size: 12px; margin: 8px 0 16px; }
+  .roots code { background: #eee; padding: 1px 5px; border-radius: 3px; }
+  .doc { background: #fff; padding: 24px 28px; border: 1px solid #ddd; border-radius: 6px; min-height: 300px; }
+  .doc h1 { font-size: 22px; margin: 0 0 12px; }
+  .doc h2 { font-size: 18px; margin: 24px 0 10px; padding-bottom: 4px; border-bottom: 1px solid #eee; }
+  .doc h3 { font-size: 15px; margin: 20px 0 8px; }
+  .doc pre { background: #f4f4f4; padding: 12px; border-radius: 4px; overflow-x: auto; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; }
+  .doc code { background: #f4f4f4; padding: 1px 4px; border-radius: 3px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; }
+  .doc pre code { background: transparent; padding: 0; }
+  .doc table { border-collapse: collapse; margin: 12px 0; }
+  .doc th, .doc td { border: 1px solid #ddd; padding: 6px 10px; text-align: left; font-size: 13px; }
+  .doc th { background: #f4f4f4; }
+  .doc blockquote { border-left: 3px solid #ccc; padding-left: 12px; color: #666; margin: 12px 0; }
+  .err { color: #c00; font-style: italic; }
+  .hint { color: #777; font-style: italic; }
+  @media (prefers-color-scheme: dark) {
+    body { background: #1a1a1a; color: #ddd; }
+    header { background: #222; border-color: #333; }
+    .doc, .path-input { background: #222; border-color: #333; color: #ddd; }
+    .doc pre, .doc code, .roots code, .doc th { background: #2a2a2a; }
+  }
+</style>
+</head>
+<body>
+<header>
+  <h1>IJFW · Planning Docs</h1>
+  <div class="sub">Browse .planning/, .ijfw/memory/, and .ijfw/wave-*/ docs from this project.</div>
+</header>
+<main>
+  <input type="text" id="path" class="path-input" placeholder=".planning/1.4.4/HANDOFF-1.4.4.md" autofocus>
+  <div class="roots">Allowed roots: .planning/ · .ijfw/memory/ · .ijfw/wave-*/STATE.md · .ijfw/wave-*/SUMMARY.md</div>
+  <div id="doc" class="doc"></div>
+</main>
+<script>
+  // Tiny markdown shim — produces a safe DOMFragment via DOMParser, no innerHTML.
+  // Renders the subset used in IJFW planning docs: headings, paragraphs, code blocks,
+  // inline code/bold/italic, links, lists, blockquotes, tables. Not a full CommonMark.
+
+  function setText(el, text) {
+    while (el.firstChild) el.removeChild(el.firstChild);
+    el.appendChild(document.createTextNode(text));
+  }
+  function setStatus(el, text, cls) {
+    while (el.firstChild) el.removeChild(el.firstChild);
+    const div = document.createElement('div');
+    div.className = cls;
+    div.textContent = text;
+    el.appendChild(div);
+  }
+
+  function makeNode(tag, text) {
+    const el = document.createElement(tag);
+    if (text !== undefined) el.appendChild(document.createTextNode(text));
+    return el;
+  }
+
+  // Renders a single line of markdown-inline content into an array of DOM nodes.
+  // Handles `code`, **bold**, *italic*, [text](url). All text is added via
+  // createTextNode — no HTML parsing of user content.
+  function renderInlineToNodes(s) {
+    const nodes = [];
+    let i = 0;
+    while (i < s.length) {
+      // Code span: `...`
+      if (s[i] === '`') {
+        const end = s.indexOf('`', i + 1);
+        if (end !== -1) {
+          nodes.push(makeNode('code', s.slice(i + 1, end)));
+          i = end + 1;
+          continue;
+        }
+      }
+      // Bold: **...**
+      if (s[i] === '*' && s[i + 1] === '*') {
+        const end = s.indexOf('**', i + 2);
+        if (end !== -1) {
+          nodes.push(makeNode('strong', s.slice(i + 2, end)));
+          i = end + 2;
+          continue;
+        }
+      }
+      // Italic: *...*
+      if (s[i] === '*') {
+        const end = s.indexOf('*', i + 1);
+        if (end !== -1 && end - i > 1) {
+          nodes.push(makeNode('em', s.slice(i + 1, end)));
+          i = end + 1;
+          continue;
+        }
+      }
+      // Link: [text](url)
+      if (s[i] === '[') {
+        const close = s.indexOf(']', i + 1);
+        if (close !== -1 && s[close + 1] === '(') {
+          const urlEnd = s.indexOf(')', close + 2);
+          if (urlEnd !== -1) {
+            const a = document.createElement('a');
+            a.textContent = s.slice(i + 1, close);
+            // r13-L-01: tightened URL guard.
+            // ALLOW: http://, https://, and same-origin relative paths (no protocol).
+            // BLOCK: javascript:, data:, mailto:, vbscript:, file:, AND protocol-relative
+            //        URLs starting with `//` (would open cross-origin without scheme).
+            const url = s.slice(close + 2, urlEnd);
+            const isAllowed = (
+              /^https?:\/\//.test(url) ||                  // explicit http/https
+              (!url.startsWith('//') && !/^[^:/?#]+:/.test(url))   // relative, no protocol, no `//`
+            );
+            if (isAllowed) {
+              a.href = url;
+              a.target = '_blank';
+              a.rel = 'noopener';
+            }
+            nodes.push(a);
+            i = urlEnd + 1;
+            continue;
+          }
+        }
+      }
+      // Plain text — accumulate until next special marker
+      let j = i;
+      while (j < s.length && !'`*['.includes(s[j])) j++;
+      if (j === i) j = i + 1;
+      nodes.push(document.createTextNode(s.slice(i, j)));
+      i = j;
+    }
+    return nodes;
+  }
+
+  function renderMarkdownToFragment(md) {
+    const frag = document.createDocumentFragment();
+    const lines = md.split('\n');
+    let i = 0;
+    while (i < lines.length) {
+      const line = lines[i];
+      // Fenced code block
+      if (/^```/.test(line)) {
+        const buf = [];
+        i++;
+        while (i < lines.length && !/^```/.test(lines[i])) { buf.push(lines[i]); i++; }
+        i++;
+        const pre = document.createElement('pre');
+        const code = document.createElement('code');
+        code.textContent = buf.join('\n');
+        pre.appendChild(code);
+        frag.appendChild(pre);
+        continue;
+      }
+      // Headings
+      const h = line.match(/^(#{1,6})\s+(.*)$/);
+      if (h) {
+        const tag = 'h' + h[1].length;
+        const el = document.createElement(tag);
+        for (const n of renderInlineToNodes(h[2])) el.appendChild(n);
+        frag.appendChild(el);
+        i++;
+        continue;
+      }
+      // Table: header row + separator row + rows
+      if (/^\s*\|/.test(line) && i + 1 < lines.length && /^\s*\|?\s*-/.test(lines[i + 1])) {
+        const tbl = document.createElement('table');
+        const head = line.split('|').slice(1, -1).map((c) => c.trim());
+        const tr = document.createElement('tr');
+        for (const c of head) {
+          const th = document.createElement('th');
+          for (const n of renderInlineToNodes(c)) th.appendChild(n);
+          tr.appendChild(th);
+        }
+        tbl.appendChild(tr);
+        i += 2;
+        while (i < lines.length && /^\s*\|/.test(lines[i])) {
+          const cells = lines[i].split('|').slice(1, -1).map((c) => c.trim());
+          const row = document.createElement('tr');
+          for (const c of cells) {
+            const td = document.createElement('td');
+            for (const n of renderInlineToNodes(c)) td.appendChild(n);
+            row.appendChild(td);
+          }
+          tbl.appendChild(row);
+          i++;
+        }
+        frag.appendChild(tbl);
+        continue;
+      }
+      // Bullet list
+      if (/^\s*[-*]\s+/.test(line)) {
+        const ul = document.createElement('ul');
+        while (i < lines.length && /^\s*[-*]\s+/.test(lines[i])) {
+          const li = document.createElement('li');
+          for (const n of renderInlineToNodes(lines[i].replace(/^\s*[-*]\s+/, ''))) li.appendChild(n);
+          ul.appendChild(li);
+          i++;
+        }
+        frag.appendChild(ul);
+        continue;
+      }
+      // Blockquote
+      if (/^>\s?/.test(line)) {
+        const bq = document.createElement('blockquote');
+        let first = true;
+        while (i < lines.length && /^>\s?/.test(lines[i])) {
+          if (!first) bq.appendChild(document.createElement('br'));
+          for (const n of renderInlineToNodes(lines[i].replace(/^>\s?/, ''))) bq.appendChild(n);
+          first = false;
+          i++;
+        }
+        frag.appendChild(bq);
+        continue;
+      }
+      // Blank
+      if (line.trim() === '') { i++; continue; }
+      // Paragraph
+      const p = document.createElement('p');
+      const buf = [line];
+      i++;
+      while (i < lines.length && lines[i].trim() !== '' && !/^(#{1,6}\s|```|>|\s*[-*]\s|\s*\|)/.test(lines[i])) {
+        buf.push(lines[i]);
+        i++;
+      }
+      for (const n of renderInlineToNodes(buf.join(' '))) p.appendChild(n);
+      frag.appendChild(p);
+    }
+    return frag;
+  }
+
+  async function load(path) {
+    const doc = document.getElementById('doc');
+    setStatus(doc, 'Loading…', 'hint');
+    try {
+      const r = await fetch('/api/planning?path=' + encodeURIComponent(path));
+      if (!r.ok) {
+        const err = await r.json().catch(() => ({ error: 'unknown' }));
+        setStatus(doc, r.status + ': ' + (err.error || 'failed'), 'err');
+        return;
+      }
+      const j = await r.json();
+      while (doc.firstChild) doc.removeChild(doc.firstChild);
+      doc.appendChild(renderMarkdownToFragment(j.body || ''));
+    } catch (e) {
+      setStatus(doc, e.message, 'err');
+    }
+  }
+
+  // Initial hint
+  setStatus(document.getElementById('doc'),
+    'Enter a relative path above (e.g. .planning/1.4.4/HANDOFF-1.4.4.md) and press Enter.',
+    'hint');
+
+  const input = document.getElementById('path');
+  input.addEventListener('keydown', (e) => {
+    if (e.key === 'Enter' && input.value.trim()) load(input.value.trim());
+  });
+  // Auto-load if ?path= in URL
+  const params = new URLSearchParams(location.search);
+  const init = params.get('path');
+  if (init) { input.value = init; load(init); }
+</script>
+</body>
+</html>