@mifort-solutions/qmetrix 1.0.0

package/src/dashboard/render/client.mjs

@@ -0,0 +1,178 @@
+/**
+ * Client-side scripts embedded verbatim into the report.
+ *
+ * These run in the browser, not in Node — they are exported as plain strings and
+ * dropped inside <script> tags by the template. Keep them self-contained (no
+ * server-side interpolation); the only data they read is the #graph-data JSON
+ * the template injects separately.
+ */
+
+/** Force-directed file-graph canvas (interactive: drag nodes, hover for path). */
+export const GRAPH_SCRIPT = `(function(){
+  const data = JSON.parse(document.getElementById('graph-data').textContent);
+  const canvas = document.getElementById('graph');
+  const dpr = window.devicePixelRatio || 1;
+  function size(){ canvas.width = canvas.clientWidth*dpr; canvas.height = canvas.clientHeight*dpr; }
+  size(); window.addEventListener('resize', size);
+  // The canvas lives inside a collapsed <details>; clientWidth is 0 until opened.
+  // Re-measure (and re-seed node positions once) the first time it's revealed.
+  (function(){ const det = canvas.closest('details'); if(!det) return;
+    let seeded=false;
+    det.addEventListener('toggle', ()=>{ if(!det.open) return; size();
+      if(seeded) return; seeded=true;
+      const cw=canvas.clientWidth||640;
+      for(let i=0;i<nodes.length;i++){ nodes[i].x=Math.cos(i/nodes.length*2*Math.PI)*220+cw/2; nodes[i].y=Math.sin(i/nodes.length*2*Math.PI)*180+230; nodes[i].vx=nodes[i].vy=0; }
+    });
+  })();
+  const ctx = canvas.getContext('2d');
+  const palette = ['#1377FE','#22c55e','#f59e0b','#a855f7','#ec4899','#06b6d4','#ef4444','#84cc16','#eab308'];
+  const groups = [...new Set(data.nodes.map(n=>n.group))];
+  const colorOf = g => palette[groups.indexOf(g)%palette.length];
+  document.getElementById('legend').innerHTML = groups.map(g=>'<span><i style="--c:'+colorOf(g)+'"></i>'+g+'</span>').join('');
+
+  const N = data.nodes.length;
+  const nodes = data.nodes.map((n,i)=>({...n,
+    x: Math.cos(i/N*2*Math.PI)*220 + (canvas.clientWidth/2),
+    y: Math.sin(i/N*2*Math.PI)*180 + 230, vx:0, vy:0,
+    r: 4 + Math.min(8, (n.fanIn||0))}));
+  const edges = data.edges;
+  let drag=null, mouse={x:0,y:0}, hover=null;
+
+  function tick(){
+    const cx=canvas.clientWidth/2, cy=230;
+    for(let i=0;i<N;i++){
+      const a=nodes[i]; a.vx += (cx-a.x)*0.0008; a.vy += (cy-a.y)*0.0008;
+      for(let j=i+1;j<N;j++){
+        const b=nodes[j]; let dx=a.x-b.x, dy=a.y-b.y; let d2=dx*dx+dy*dy||0.01;
+        const f=380/d2; const d=Math.sqrt(d2);
+        dx/=d; dy/=d; a.vx+=dx*f; a.vy+=dy*f; b.vx-=dx*f; b.vy-=dy*f;
+      }
+    }
+    for(const e of edges){
+      const a=nodes[e.source], b=nodes[e.target];
+      let dx=b.x-a.x, dy=b.y-a.y; const d=Math.sqrt(dx*dx+dy*dy)||0.01;
+      const f=(d-70)*0.01; dx/=d; dy/=d;
+      a.vx+=dx*f; a.vy+=dy*f; b.vx-=dx*f; b.vy-=dy*f;
+    }
+    for(const n of nodes){ if(n===drag)continue; n.vx*=0.86; n.vy*=0.86; n.x+=n.vx; n.y+=n.vy; }
+  }
+  function draw(){
+    ctx.save(); ctx.scale(dpr,dpr); ctx.clearRect(0,0,canvas.clientWidth,canvas.clientHeight);
+    ctx.lineWidth=0.6; ctx.strokeStyle='rgba(120,150,200,0.18)';
+    for(const e of edges){ const a=nodes[e.source], b=nodes[e.target];
+      ctx.beginPath(); ctx.moveTo(a.x,a.y); ctx.lineTo(b.x,b.y); ctx.stroke(); }
+    for(const n of nodes){
+      ctx.beginPath(); ctx.fillStyle=colorOf(n.group); ctx.globalAlpha = hover&&hover!==n?0.5:1;
+      ctx.arc(n.x,n.y,n.r,0,7); ctx.fill(); ctx.globalAlpha=1;
+    }
+    if(hover){ ctx.fillStyle='#e6edf7'; ctx.font='12px ui-monospace,monospace';
+      const t=hover.label+'  (in '+hover.fanIn+' / out '+hover.fanOut+')';
+      const w=ctx.measureText(t).width+12; let tx=hover.x+10, ty=hover.y-10;
+      if(tx+w>canvas.clientWidth) tx=hover.x-w-10;
+      ctx.fillStyle='rgba(10,18,36,.92)'; ctx.fillRect(tx,ty-13,w,18);
+      ctx.fillStyle='#e6edf7'; ctx.fillText(t,tx+6,ty); }
+    ctx.restore();
+  }
+  function loop(){ tick(); draw(); requestAnimationFrame(loop); } loop();
+
+  function at(mx,my){ let best=null,bd=144; for(const n of nodes){ const d=(n.x-mx)**2+(n.y-my)**2; if(d<bd){bd=d;best=n;} } return best; }
+  canvas.addEventListener('mousemove',ev=>{ const r=canvas.getBoundingClientRect(); mouse={x:ev.clientX-r.left,y:ev.clientY-r.top};
+    if(drag){ drag.x=mouse.x; drag.y=mouse.y; drag.vx=drag.vy=0; } else hover=at(mouse.x,mouse.y); });
+  canvas.addEventListener('mousedown',ev=>{ const r=canvas.getBoundingClientRect(); drag=at(ev.clientX-r.left,ev.clientY-r.top); canvas.style.cursor='grabbing'; });
+  window.addEventListener('mouseup',()=>{ drag=null; canvas.style.cursor='grab'; });
+})();`;
+
+/**
+ * Component composition — expand/collapse-all for the nested-rectangle view.
+ * The boxes themselves are static HTML (<details> per box); this only wires the
+ * two "Expand all / Collapse all" buttons to flip every box's metadata panel.
+ */
+export const COMPOSITION_SCRIPT = `(function(){
+  const btns = document.querySelectorAll('[data-comp-toggle]');
+  if(!btns.length) return;
+  btns.forEach(function(btn){
+    btn.addEventListener('click', function(){
+      const open = btn.getAttribute('data-comp-toggle') === 'open';
+      document.querySelectorAll('.comp-tree details.comp-card').forEach(function(d){ d.open = open; });
+    });
+  });
+})();`;
+
+/**
+ * Component composition — page-flow arrows. Draws an SVG cubic-bezier between the
+ * mini browser windows for every transition edge (indices into the .cflow-node
+ * list, injected as #comp-flow-data). Coordinates are taken from live layout
+ * (getBoundingClientRect relative to the #cflow box) and recomputed on resize, so
+ * the arrows stay glued to the nodes regardless of wrapping.
+ */
+export const COMPOSITION_FLOW_SCRIPT = `(function(){
+  const cflow = document.getElementById('cflow');
+  const svg = document.getElementById('cflow-svg');
+  const dataEl = document.getElementById('comp-flow-data');
+  if(!cflow || !svg || !dataEl) return;
+  let edges = [];
+  try { edges = JSON.parse(dataEl.textContent) || []; } catch(e){ return; }
+  const nodes = cflow.querySelectorAll('.cflow-node');
+  const NS = 'http://www.w3.org/2000/svg';
+  function draw(){
+    [].slice.call(svg.querySelectorAll('path.cflow-edge')).forEach(function(p){ p.remove(); });
+    const base = cflow.getBoundingClientRect();
+    svg.setAttribute('width', cflow.scrollWidth);
+    svg.setAttribute('height', cflow.scrollHeight);
+    edges.forEach(function(e){
+      const a = nodes[e[0]], b = nodes[e[1]];
+      if(!a || !b) return;
+      const ra = a.getBoundingClientRect(), rb = b.getBoundingClientRect();
+      const x1 = ra.left - base.left + ra.width/2;
+      const x2 = rb.left - base.left + rb.width/2;
+      let y1, y2, d;
+      const dy = Math.max(26, Math.abs((rb.top+rb.bottom)/2 - (ra.top+ra.bottom)/2)/2);
+      if(rb.top >= ra.bottom - 1){            // forward edge: bottom of a → top of b
+        y1 = ra.bottom - base.top; y2 = rb.top - base.top;
+        d = 'M'+x1+','+y1+' C'+x1+','+(y1+dy)+' '+x2+','+(y2-dy)+' '+x2+','+y2;
+      } else {                                 // back / same-layer edge: route around the side
+        y1 = ra.top - base.top; y2 = rb.bottom - base.top;
+        const bend = x2 >= x1 ? 70 : -70;
+        d = 'M'+x1+','+y1+' C'+(x1+bend)+','+(y1-dy)+' '+(x2+bend)+','+(y2+dy)+' '+x2+','+y2;
+      }
+      const path = document.createElementNS(NS, 'path');
+      path.setAttribute('d', d);
+      path.setAttribute('class', 'cflow-edge');
+      path.setAttribute('marker-end', 'url(#cflow-arrow)');
+      svg.appendChild(path);
+    });
+  }
+  draw();
+  window.addEventListener('resize', draw);
+  setTimeout(draw, 80);
+})();`;
+
+/** Dependency-table filter (segment buttons + checkboxes + search). */
+export const DEP_FILTER_SCRIPT = `(function(){
+  const table = document.getElementById('dep-rows');
+  if(!table) return;
+  const rows = [...table.querySelectorAll('tbody tr')];
+  const state = { type:'all', outdated:false, vuln:false, q:'' };
+  const count = document.getElementById('dep-count');
+  function apply(){
+    let shown=0;
+    for(const r of rows){
+      const ok = (state.type==='all' || r.dataset.type===state.type)
+        && (!state.outdated || r.dataset.outdated==='1')
+        && (!state.vuln || r.dataset.vuln==='1')
+        && (!state.q || r.dataset.name.includes(state.q));
+      r.style.display = ok ? '' : 'none';
+      if(ok) shown++;
+    }
+    if(count) count.textContent = 'showing '+shown+' of '+rows.length;
+  }
+  document.querySelectorAll('#dep-filters [data-ftype]').forEach(b=>b.addEventListener('click',()=>{
+    state.type=b.dataset.ftype;
+    document.querySelectorAll('#dep-filters [data-ftype]').forEach(x=>x.classList.toggle('on',x===b));
+    apply();
+  }));
+  const bind=(id,key)=>{ const e=document.getElementById(id); if(e) e.addEventListener('change',()=>{ state[key]=e.checked; apply(); }); };
+  bind('f-outdated','outdated'); bind('f-vuln','vuln');
+  const q=document.getElementById('f-q'); if(q) q.addEventListener('input',()=>{ state.q=q.value.trim().toLowerCase(); apply(); });
+  apply();
+})();`;

package/src/dashboard/render/components.mjs

@@ -0,0 +1,247 @@
+/** Reusable HTML fragment builders (cards, gauges, expandable trees, ER boxes). */
+import { esc, pct } from '../utils/format.mjs';
+
+const SEV_COLORS = {
+  critical: '#dc2626',
+  high: '#ea580c',
+  medium: '#d97706',
+  low: '#0891b2',
+  note: '#64748b',
+};
+
+export function sevBadges(sev) {
+  return (
+    Object.entries(SEV_COLORS)
+      .filter(([k]) => (sev[k] || 0) > 0)
+      .map(([k, c]) => `<span class="sev" style="--c:${c}">${sev[k]} ${k}</span>`)
+      .join(' ') || '<span class="sev" style="--c:#16a34a">0 findings</span>'
+  );
+}
+
+/** Per-finding "why it's flagged" list (Snyk/CodeQL/etc.), severity-led. */
+function findingsList(reports) {
+  const all = reports.flatMap((r) => r.findings || []);
+  if (!all.length) {
+    return '';
+  }
+  const rows = all
+    .map((f) => {
+      const c = SEV_COLORS[f.severity] || SEV_COLORS.note;
+      const where = f.where ? ` <code>${esc(f.where)}</code>` : '';
+      const detail = f.detail ? `<div class="fd muted">${esc(f.detail)}</div>` : '';
+      return `<li><span class="sev" style="--c:${c}">${esc(f.severity)}</span> <span class="fr">${esc(f.reason || f.rule || '—')}</span>${where}${detail}</li>`;
+    })
+    .join('');
+  return `<details open class="sec-findings"><summary>Why these are flagged (${all.length})</summary><ul class="findings">${rows}</ul></details>`;
+}
+
+export function scannerCard(s) {
+  let status, body;
+  if (s.reports && s.reports.length) {
+    const totals = { critical: 0, high: 0, medium: 0, low: 0, note: 0 };
+    let total = 0;
+    for (const r of s.reports) {
+      total += r.total || 0;
+      for (const k of Object.keys(totals)) {
+        totals[k] += r.sev?.[k] || 0;
+      }
+    }
+    status = `<span class="badge ok">local report · ${total} findings</span>`;
+    body = `
+      <div class="sevrow">${sevBadges(totals)}</div>
+      <table class="mini"><thead><tr><th>Artifact</th><th>Driver</th><th class="r">Findings</th></tr></thead><tbody>
+      ${s.reports.map((r) => `<tr><td><code>${esc(r.file)}</code></td><td>${esc(r.driver || '—')}</td><td class="r">${r.total}</td></tr>`).join('')}
+      </tbody></table>
+      ${findingsList(s.reports)}`;
+  } else if (s.report) {
+    status = `<span class="badge ok">local scan</span>`;
+    body = `<p class="muted">Project key <code>${esc(s.projectKey || '')}</code> — last local scan report found.</p>`;
+  } else {
+    status = `<span class="badge warn">configured · runs in CI</span>`;
+    body = `<p class="muted">No local SARIF artifact. This scanner runs server-side in GitHub Actions${
+      s.workflow ? '' : ' (workflow missing!)'
+    } and publishes to its dashboard. Download a run artifact next to this script to surface findings here.</p>`;
+  }
+  const links = [
+    s.ci ? `<a href="${s.ci}" target="_blank" rel="noopener">GitHub Security ↗</a>` : null,
+    s.dashboard
+      ? `<a href="${s.dashboard}" target="_blank" rel="noopener">Vendor dashboard ↗</a>`
+      : null,
+  ]
+    .filter(Boolean)
+    .join(' · ');
+  return `
+    <div class="card scanner">
+      <div class="card-h"><h3>${esc(s.name)}</h3>${status}</div>
+      <p class="tool">${esc(s.tool)}</p>
+      ${body}
+      <div class="links">${links}</div>
+    </div>`;
+}
+
+export function bar(label, value) {
+  const v = value == null ? 0 : value;
+  const c = v >= 80 ? '#16a34a' : v >= 50 ? '#d97706' : '#dc2626';
+  return `
+    <div class="gauge">
+      <div class="gauge-h"><span>${label}</span><strong>${pct(value)}</strong></div>
+      <div class="track"><div class="fill" style="width:${v}%;background:${c}"></div></div>
+    </div>`;
+}
+
+/* ── file relationship tree (grouped by folder, expandable) ── */
+export function fileTreeHtml(graphData) {
+  const { nodes, edges } = graphData;
+  const byId = new Map(nodes.map((n) => [n.id, n]));
+  const importsOf = new Map();
+  const importedByOf = new Map();
+  const push = (map, k, v) => (map.get(k) || map.set(k, []).get(k)).push(v);
+  for (const e of edges) {
+    push(importsOf, e.source, e.target);
+    push(importedByOf, e.target, e.source);
+  }
+
+  const root = { dirs: new Map(), files: [] };
+  for (const n of nodes) {
+    const parts = n.label.split('/');
+    parts.pop();
+    let cur = root;
+    for (const p of parts) {
+      if (!cur.dirs.has(p)) {
+        cur.dirs.set(p, { dirs: new Map(), files: [] });
+      }
+      cur = cur.dirs.get(p);
+    }
+    cur.files.push(n);
+  }
+  const count = (node) => {
+    let c = node.files.length;
+    for (const d of node.dirs.values()) {
+      c += count(d);
+    }
+    return c;
+  };
+  const labels = (ids) =>
+    (ids || [])
+      .map((id) => byId.get(id))
+      .filter(Boolean)
+      .sort((a, b) => a.label.localeCompare(b.label));
+  const fileRow = (n) => {
+    const fname = n.label.split('/').pop();
+    const badges = `<span class="fan in" title="imported by ${n.fanIn} module(s)">in ${n.fanIn}</span><span class="fan out" title="imports ${n.fanOut} module(s)">out ${n.fanOut}</span>`;
+    const imps = labels(importsOf.get(n.id));
+    const impd = labels(importedByOf.get(n.id));
+    if (!imps.length && !impd.length) {
+      return `<div class="tree-file"><span class="ico">📄</span><code>${esc(fname)}</code> ${badges}</div>`;
+    }
+    const rel = (head, arr) =>
+      arr.length
+        ? `<div class="rel"><span class="muted">${head}</span> ${arr.map((x) => `<code>${esc(x.label)}</code>`).join(' ')}</div>`
+        : '';
+    return `<details class="tree-file det"><summary><span class="ico">📄</span><code>${esc(fname)}</code> ${badges}</summary><div class="tree-body">${rel('imports →', imps)}${rel('imported by ←', impd)}</div></details>`;
+  };
+  const dirRow = (node, name, depth) => {
+    const inner =
+      [...node.dirs.entries()]
+        .sort((a, b) => a[0].localeCompare(b[0]))
+        .map(([dn, dnode]) => dirRow(dnode, dn, depth + 1))
+        .join('') +
+      node.files
+        .sort((a, b) => a.label.localeCompare(b.label))
+        .map(fileRow)
+        .join('');
+    if (name == null) {
+      return inner;
+    }
+    return `<details class="tree-dir"${depth < 1 ? ' open' : ''}><summary><span class="ico">📁</span>${esc(name)} <span class="muted">(${count(node)})</span></summary><div class="tree-body">${inner}</div></details>`;
+  };
+  return dirRow(root, null, 0);
+}
+
+/* ── Next.js routing tree (expandable) ── */
+export function routingHtml(routing) {
+  if (!routing.available) {
+    return `<p class="muted">No <code>src/app</code> directory found.</p>`;
+  }
+  const kindColor = {
+    page: '#22c55e',
+    layout: '#1377FE',
+    route: '#a855f7',
+    loading: '#06b6d4',
+    error: '#ef4444',
+    'global-error': '#ef4444',
+    'not-found': '#f59e0b',
+    template: '#64748b',
+    default: '#64748b',
+  };
+  const node = (n, depth, isRoot) => {
+    const segHtml = isRoot
+      ? `<span class="seg">app</span> <code class="url">/</code>`
+      : n.group
+        ? `<span class="seg group">${esc(n.seg)}</span>`
+        : n.dynamic
+          ? `<span class="seg dyn">${esc(n.seg)}</span>`
+          : `<span class="seg">${esc(n.seg)}</span>`;
+    const urlChip =
+      !isRoot && (n.kinds.includes('page') || n.kinds.includes('route'))
+        ? ` <code class="url">${esc(n.url || '/')}</code>`
+        : '';
+    const badges = n.kinds
+      .map((k) => `<span class="rt" style="--c:${kindColor[k] || '#64748b'}">${k}</span>`)
+      .join(' ');
+    const head = `${segHtml}${urlChip} ${badges}`;
+    if (!n.children.length) {
+      return `<div class="rt-leaf">${head}</div>`;
+    }
+    return `<details class="rt-dir"${depth < 2 ? ' open' : ''}><summary>${head}</summary><div class="tree-body">${n.children.map((c) => node(c, depth + 1, false)).join('')}</div></details>`;
+  };
+  return node(routing.root, 0, true);
+}
+
+/* ── data model / ER diagram ── */
+export function entitiesHtml(entities) {
+  if (!entities.available || (!entities.tables.length && !entities.buckets.length)) {
+    return `<p class="muted">No SQL migrations found under <code>supabase/migrations</code>.</p>`;
+  }
+  const keyBadge = (c) =>
+    c.pk
+      ? `<span class="kb pk" title="primary key">PK</span>`
+      : c.fk
+        ? `<span class="kb fk" title="references ${esc(c.fk.table)}">FK</span>`
+        : '';
+  const tableBox = (t) => `
+    <div class="er-table">
+      <div class="er-h">${esc(t.name)}${t.rls ? `<span class="er-rls" title="row level security enabled">RLS</span>` : ''}</div>
+      <table class="er-cols"><tbody>
+      ${t.columns
+        .map(
+          (c) => `<tr>
+        <td class="er-k">${keyBadge(c)}</td>
+        <td class="er-c">${esc(c.name)}${c.notnull && !c.pk ? '<span class="req" title="NOT NULL">*</span>' : ''}</td>
+        <td class="er-t">${esc(c.type)}</td>
+      </tr>`,
+        )
+        .join('')}
+      </tbody></table>
+      ${t.indexes.length ? `<div class="er-idx">${t.indexes.map((i) => `<span title="(${esc(i.cols)})">⚲ ${esc(i.name)}</span>`).join(' ')}</div>` : ''}
+    </div>`;
+  const bucketBox = (b) => `
+    <div class="er-table bucket">
+      <div class="er-h">🗄 ${esc(b.name)}<span class="er-rls ${b.public ? 'pub' : ''}">${b.public ? 'public' : 'private'}</span></div>
+      <div class="er-bk">storage bucket</div>
+    </div>`;
+  const rels = entities.tables.flatMap((t) =>
+    t.columns
+      .filter((c) => c.fk)
+      .map(
+        (c) =>
+          `<code>${esc(t.name)}.${esc(c.name)}</code> → <code>${esc(c.fk.table)}${c.fk.col ? '.' + esc(c.fk.col) : ''}</code>`,
+      ),
+  );
+  return `
+    <div class="er-canvas">
+      ${entities.tables.map(tableBox).join('')}
+      ${entities.buckets.map(bucketBox).join('')}
+    </div>
+    ${rels.length ? `<div class="er-rels"><span class="muted">Relationships:</span> ${rels.join(' · ')}</div>` : ''}`;
+}

package/src/dashboard/render/composition.mjs

@@ -0,0 +1,192 @@
+/**
+ * Component composition — browser-window pages + nested-rectangle containment.
+ *
+ * Three coordinated views from collectComposition():
+ *   1. Page flow — a compact layered graph of the app's pages (mini browser
+ *      windows keyed by URL) with arrows for the content navigation between them
+ *      (drawn client-side by COMPOSITION_FLOW_SCRIPT from the injected edge data).
+ *   2. Page composition — every page as a real browser window (chrome + address
+ *      bar) whose feature components are *physically* nested inside it, box-in-box.
+ *   3. Unattached — feature components no page reaches.
+ *
+ * The name + one-line description show always; props / state / events / public API
+ * live inside a <details> the visitor expands. Design-system widgets from
+ * src/common are not shown — see the collector header.
+ */
+import { esc, num } from '../utils/format.mjs';
+
+const ROLE_LABEL = {
+  page: 'page',
+  layout: 'layout',
+  app: 'app',
+  public: 'public',
+  internal: 'internal',
+};
+
+const trunc = (s, n) => (s.length > n ? s.slice(0, n - 1) + '…' : s);
+
+const locLabel = (d) =>
+  d.layer === 'app' ? d.rel.replace(/^src\//, '') : `features/${d.feature} · ${d.file}`;
+
+const LOCK = `<svg class="comp-lock" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><rect x="5" y="11" width="14" height="9" rx="2"/><path d="M8 11V7a4 4 0 0 1 8 0v4"/></svg>`;
+
+function metaHtml(d) {
+  const props = d.props.length
+    ? d.props
+        .map(
+          (p) =>
+            `<code>${esc(p.name)}</code>${p.type ? `<span class="comp-ty">: ${esc(trunc(p.type, 44))}</span>` : ''}`,
+        )
+        .join('<span class="comp-sep">,</span> ')
+    : '<span class="muted">none</span>';
+
+  const state = d.state.length
+    ? d.state
+        .map((s) => `<code>${esc(s.name)}</code><span class="comp-hk">${esc(s.hook)}</span>`)
+        .join(' ')
+    : '<span class="muted">stateless</span>';
+
+  const evParts = [
+    ...d.events.callbacks.map((c) => `<code>${esc(c)}</code>`),
+    ...d.events.tracked.map((t) => `<span class="comp-ev">${esc(t)}</span>`),
+  ];
+  const events = evParts.length ? evParts.join(' ') : '<span class="muted">none</span>';
+
+  let api;
+  if (d.layer === 'app') {
+    api = '<span class="muted">route · default export</span>';
+  } else {
+    const tag = d.public
+      ? '<span class="comp-ev">public · index.ts</span>'
+      : '<span class="muted">internal</span>';
+    const ex = d.exports.filter((e) => e !== 'default' && e !== d.name);
+    api = `${tag}${ex.length ? ` <span class="comp-ty">+ ${ex.map(esc).join(', ')}</span>` : ''}`;
+  }
+
+  const row = (k, v) =>
+    `<div class="comp-mrow"><span class="comp-mk">${k}</span><span class="comp-mv">${v}</span></div>`;
+  return `<div class="comp-meta">${row('Props', props)}${row('State', state)}${row('Events', events)}${row('Public&nbsp;API', api)}</div>`;
+}
+
+/**
+ * Compact page-flow graph: only the pages that take part in a transition are laid
+ * out as layered mini browser windows (BFS distance from `/`); pages no content
+ * link reaches are listed compactly below instead of stretching an empty row.
+ * Render order == DOM order of `.cflow-node` == the edge indices in the JSON data.
+ */
+function flowHtml(t, host) {
+  if (!t || !t.edges.length) {
+    return '';
+  }
+  const graphNodes = t.nodes.filter((n) => n.inCount + n.outCount > 0);
+  const orphans = t.nodes.filter((n) => n.inCount + n.outCount === 0);
+  const idToIdx = new Map(graphNodes.map((n, i) => [n.id, i]));
+  const layers = [];
+  graphNodes.forEach((n) => {
+    (layers[n.layer] ||= []).push(n);
+  });
+  const url = (route) => `${esc(host)}${esc(route === '/' ? '/' : route)}`;
+  const node = (n, i) =>
+    `<div class="cflow-node" data-idx="${i}">
+      <div class="cflow-chrome"><span class="cflow-dots"><i></i><i></i><i></i></span><span class="cflow-url">${url(n.route)}</span></div>
+      <div class="cflow-meta"><span class="cflow-comp">${esc(n.component)}</span><span class="cflow-deg">in ${n.inCount} · out ${n.outCount}</span></div>
+    </div>`;
+  const rows = layers
+    .filter(Boolean)
+    .map(
+      (row) =>
+        `<div class="cflow-row">${row.map((n) => node(n, idToIdx.get(n.id))).join('')}</div>`,
+    )
+    .join('');
+  const pairs = t.edges
+    .map((e) => [idToIdx.get(e.from), idToIdx.get(e.to)])
+    .filter((p) => p[0] != null && p[1] != null);
+  const data = JSON.stringify(pairs).replace(/</g, '\\u003c');
+  const svg = `<svg class="cflow-svg" id="cflow-svg" xmlns="http://www.w3.org/2000/svg"><defs><marker id="cflow-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="#3f6fb0"/></marker></defs></svg>`;
+  const orphanHtml = orphans.length
+    ? `<div class="cflow-orphans"><span class="muted">${orphans.length} page(s) with no content links (reached via global nav only):</span> ${orphans.map((n) => `<span class="cflow-orphan">${url(n.route)}</span>`).join('')}</div>`
+    : '';
+  return `<h3 class="comp-subh">Page flow <span class="muted">— ${t.edges.length} content transition(s)</span></h3>
+    <div class="cflow-wrap"><div class="cflow" id="cflow">${svg}<div class="cflow-layers">${rows}</div></div></div>
+    ${orphanHtml}
+    <script id="comp-flow-data" type="application/json">${data}</script>`;
+}
+
+export function compositionGraphHtml(comp) {
+  if (!comp || !comp.available) {
+    return `<p class="muted">No app routes or feature components found.</p>`;
+  }
+  const C = comp.components;
+  const host = comp.host || '';
+
+  const linksHtml = (d) =>
+    d.links && d.links.length
+      ? `<span class="comp-links">${d.links.map((l) => `<span class="comp-link">${esc(l)}</span>`).join('')}</span>`
+      : '';
+
+  const cardHtml = (d) => `<details class="comp-card">
+      <summary class="comp-sum">
+        <span class="comp-name">${esc(d.component || d.name)}</span>
+        <span class="comp-badge role-${esc(d.role)}">${ROLE_LABEL[d.role] || d.role}</span>
+        <span class="comp-loc">${esc(locLabel(d))}</span>
+        ${d.description ? `<span class="comp-desc">${esc(d.description)}</span>` : ''}
+        ${linksHtml(d)}
+      </summary>
+      ${metaHtml(d)}
+    </details>`;
+
+  // A page root → a browser window; its rendered components nest inside the body.
+  const winBox = (d, nest) => {
+    const url = `${host}${d.name === '/' ? '/' : d.name}`;
+    return `<div class="comp-box role-page comp-win" data-rid="${esc(d.id)}">
+      <div class="comp-winbar">
+        <span class="comp-dots"><i></i><i></i><i></i></span>
+        <span class="comp-addr">${LOCK}<span class="comp-addr-url">${esc(url)}</span></span>
+      </div>
+      <div class="comp-winbody">${cardHtml(d)}${nest}</div>
+    </div>`;
+  };
+
+  const box = (node) => {
+    const d = C[node.id];
+    if (!d) {
+      return '';
+    }
+    if (node.cycle) {
+      return `<div class="comp-box role-${esc(d.role)} is-cycle"><div class="comp-cyc"><span class="comp-name">${esc(d.component || d.name)}</span><span class="comp-tag">↺ shown above</span></div></div>`;
+    }
+    const kids = (node.children || []).map(box).join('');
+    const nest = kids ? `<div class="comp-nest">${kids}</div>` : '';
+    if (d.kind === 'page') {
+      return winBox(d, nest);
+    }
+    return `<div class="comp-box role-${esc(d.role)}">${cardHtml(d)}${nest}</div>`;
+  };
+
+  const s = comp.stats;
+  const summary = `<p class="muted">${s.pages} page(s) shown as browser windows, each physically nesting the feature components it renders (box-in-box) across ${s.features.length} feature(s) · ${num(s.boxes)} box(es). Arrows in <strong>Page flow</strong> trace content navigation between pages. Click a box for its props, state, events &amp; public API. Design-system widgets from <code>src/common</code> are omitted.</p>`;
+
+  const legend = `<div class="comp-legend">
+    <span class="sw"><i class="role-page"></i>page · browser window</span>
+    <span class="sw"><i class="role-layout"></i>layout</span>
+    <span class="sw"><i class="role-public"></i>feature public API</span>
+    <span class="sw"><i class="role-internal"></i>feature internal</span>
+    <span class="sw"><b class="comp-leg-arrow">→</b> page transition</span>
+  </div>`;
+
+  const controls = `<div class="comp-controls">
+    <button type="button" data-comp-toggle="open">Expand all</button>
+    <button type="button" data-comp-toggle="close">Collapse all</button>
+  </div>`;
+
+  const flow = flowHtml(comp.transitions, host);
+
+  const tree = `<h3 class="comp-subh">Page composition</h3><div class="comp-scroll"><div class="comp-tree">${comp.roots.map(box).join('')}</div></div>`;
+
+  const unattached = comp.unattached.length
+    ? `<details class="comp-unattached"><summary>${comp.unattached.length} feature component(s) not reached from any page</summary>
+       <div class="comp-scroll"><div class="comp-tree">${comp.unattached.map(box).join('')}</div></div></details>`
+    : '';
+
+  return `${summary}${legend}${flow}${controls}${tree}${unattached}`;
+}