@polycode-projects/seonix 0.2.1 → 0.3.0

package/src/timeline.mjs

@@ -0,0 +1,117 @@
+// timeline.mjs — render the repo's commit timeline to a single, portable HTML
+// page from a seonix graph artifact. Third sibling of the viz viewer and the
+// Chronograph code browser: generated by `seonix viz` (--timeline-out, on by
+// default next to --out) and served live at /timeline.html by `viz --serve`.
+//
+// Data comes straight from the graph artifact: Commit individuals carry the full
+// sha (id), author, date, and message; each Module's `derived_from` lists the
+// commits that touched it (`git:<short sha>`), which gives per-commit churn.
+// Session individuals (chat sessions recorded by sessions.mjs) join the same
+// timeline as `type:"session"` entries at their started timestamp — a graph with
+// zero sessions renders exactly as before.
+
+const esc = (s) =>
+  String(s == null ? "" : s).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]));
+
+export function extractTimeline(graph) {
+  const commits = [];
+  const sessions = [];
+  const churnByShort = new Map(); // short sha -> modules touched
+  for (const ind of graph.individuals || []) {
+    const attr = (key) => ind.attributes?.find((a) => a.key === key)?.value || "";
+    if (ind.class === "Module") {
+      for (const ref of ind.derived_from || []) {
+        const short = ref.replace(/^git:/, "");
+        churnByShort.set(short, (churnByShort.get(short) || 0) + 1);
+      }
+    } else if (ind.class === "Commit") {
+      commits.push({
+        sha: ind.id.replace(/^commit:/, ""),
+        short: ind.label,
+        date: attr("date"),
+        author: attr("author"),
+        message: attr("message"),
+      });
+    } else if (ind.class === "Session") {
+      // chat sessions (sessions.mjs) enter the timeline at their started timestamp
+      sessions.push({
+        type: "session",
+        id: ind.id.replace(/^session:/, ""),
+        short: ind.label,
+        date: attr("started"),
+        turns: Number(attr("turns")) || 0,
+        touched: 0,
+      });
+    }
+  }
+  for (const c of commits) c.touched = churnByShort.get(c.short) || 0;
+  const entries = [...commits, ...sessions];
+  entries.sort((a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : 0));
+  return entries;
+}
+
+/** `nav` is the shared {name: href} nav object the viz CLI computes from the
+ *  actual sibling output paths — header links render ONLY from its entries, so
+ *  a page generated without siblings never carries dead links. */
+export function renderTimelineHtml({ commits, repoUrl = "", repoRef = "main", generatedAt = "", nav = null } = {}) {
+  const base = repoUrl.replace(/\/+$/, "");
+  const sessionCount = commits.filter((c) => c.type === "session").length;
+  const commitCount = commits.length - sessionCount;
+  const maxTouched = Math.max(1, ...commits.map((c) => c.touched));
+  // Bars run oldest→newest left to right; the list reads newest first. Chat
+  // sessions are the visually distinct entries (amber, fixed-height bars).
+  const bars = commits
+    .map((c, i) =>
+      c.type === "session"
+        ? `<a class="bar sess" href="#c${i}" title="chat session ${esc(c.short)} · ${esc(c.date.slice(0, 10))} — ${c.turns} turn(s)"><i style="height:10px"></i></a>`
+        : `<a class="bar" href="#c${i}" title="${esc(c.short)} · ${esc(c.date.slice(0, 10))} — ${esc(c.message)}"><i style="height:${Math.max(6, Math.round((c.touched / maxTouched) * 64))}px"></i></a>`,
+    )
+    .join("");
+  const rows = commits
+    .map((c, i) => {
+      if (c.type === "session") {
+        return `<li id="c${i}" class="sess"><span class="d">${esc(c.date.slice(0, 10))}</span> <code>${esc(c.short)}</code> <span class="m">chat session — ${c.turns} turn(s)</span></li>`;
+      }
+      const sha = base
+        ? `<a href="${base}/-/commit/${esc(c.sha)}" target="_blank" rel="noopener"><code>${esc(c.short)}</code></a>`
+        : `<code>${esc(c.short)}</code>`;
+      return `<li id="c${i}"><span class="d">${esc(c.date.slice(0, 10))}</span> ${sha} <span class="a">${esc(c.author)}</span> <span class="m">${esc(c.message)}</span> <span class="t" title="modules touched">${c.touched}⛁</span></li>`;
+    })
+    .reverse()
+    .join("\n");
+  const navLinks = nav
+    ? Object.entries(nav)
+        .map(([name, href]) => `<a href="${esc(href)}">${name === "home" ? "← home" : esc(name)}</a>`)
+        .join("\n  ")
+    : "";
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>seonix — commit timeline</title>
+<style>
+  html,body{margin:0;font:14px/1.5 system-ui,sans-serif;background:#1a1b26;color:#c0caf5}
+  header{padding:14px 20px;background:#16161e;border-bottom:1px solid #2a2e42;display:flex;gap:16px;align-items:baseline;flex-wrap:wrap}
+  header b{color:#7aa2f7} header a{color:#7aa2f7;text-decoration:none} header a:hover{text-decoration:underline}
+  header .meta{color:#565f89;font-size:12px;margin-left:auto}
+  #bars{display:flex;align-items:flex-end;gap:3px;padding:18px 20px 6px;overflow-x:auto}
+  .bar i{display:block;width:9px;background:#3d59a1;border-radius:2px 2px 0 0}
+  .bar:hover i{background:#7aa2f7}
+  ol{list-style:none;margin:6px 0 40px;padding:0 20px}
+  li{padding:6px 8px;border-bottom:1px solid #20222f;display:flex;gap:10px;align-items:baseline;flex-wrap:wrap}
+  li:target{background:#20253a;border-radius:4px}
+  .d{color:#565f89;font-variant-numeric:tabular-nums;white-space:nowrap}
+  code{color:#9ece6a} li a{text-decoration:none} li a:hover code{text-decoration:underline}
+  .a{color:#a9b1d6;white-space:nowrap} .m{flex:1 1 24ch} .t{color:#bb9af7;white-space:nowrap}
+  .bar.sess i{background:#8a6a2f;border-radius:5px} .bar.sess:hover i{background:#e0af68}
+  li.sess{border-left:3px solid #e0af68;padding-left:5px} li.sess code,li.sess .m{color:#e0af68}
+</style></head><body>
+<header>
+  <span><b>seonix</b> commit timeline — ${commitCount} commits${sessionCount ? ` · ${sessionCount} chat session(s)` : ""}</span>
+  ${navLinks}
+  ${base ? `<a href="${base}" target="_blank" rel="noopener">repository ↗</a>` : ""}
+  <span class="meta">bars = modules touched per commit · generated from the seonix graph artifact${generatedAt ? ` (${esc(generatedAt.slice(0, 10))})` : ""}</span>
+</header>
+<div id="bars">${bars}</div>
+<ol>
+${rows}
+</ol>
+</body></html>`;
+}

package/src/viz.mjs

@@ -25,6 +25,7 @@ import { parseEntities, resolveSymbol, relationKind, siteOf } from "./codegraph.
 import { loadConfig } from "./config.mjs";
 import * as source from "./source.mjs";
 import { buildTemporalGraph, buildBrowserData, gitCommitOrder, gitCommitParents, renderBrowserHtml } from "./browser.mjs";
+import { extractTimeline, renderTimelineHtml } from "./timeline.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const execFileP = promisify(execFile);
@@ -134,7 +135,7 @@ export function buildSubgraph(graph, { focusId, depth = 2, hubDegree = 40, maxNo
 
 /** The viewer's runtime payload — everything repo-specific lives here, nothing in
  *  the page. Pure; schema is part of the viewer contract (tests pin it). */
-export function buildViewerData(subgraph, { focusLabel, repoUrl = "", repoRef = "main", siteNav = false } = {}) {
+export function buildViewerData(subgraph, { focusLabel, repoUrl = "", repoRef = "main", siteNav = false, nav = null } = {}) {
   return {
     focusId: subgraph.focusId,
     focusLabel: focusLabel || subgraph.focusId,
@@ -142,7 +143,8 @@ export function buildViewerData(subgraph, { focusLabel, repoUrl = "", repoRef =
     maxDepth: subgraph.nodes.reduce((m, n) => Math.max(m, n.depth), 0),
     repoUrl: repoUrl.replace(/\/+$/, ""),
     repoRef,
-    siteNav: !!siteNav,
+    siteNav: !!siteNav, // legacy flag — stale deployed data keeps its absolute links
+    ...(nav ? { nav } : {}), // {name: href} — the viewer rebuilds #sitenav from this
     nodes: subgraph.nodes,
     edges: subgraph.edges,
   };
@@ -219,10 +221,10 @@ export function renderViewerHtml({ cytoscape, askEngine = "", embedData = null,
   #bar label,.lbl{color:#a9b1d6} #bar b{color:#7aa2f7}
   #bar button{background:#1a1b26;color:#c0caf5;border:1px solid #2a2e42;border-radius:4px;padding:2px 8px;cursor:pointer;font:inherit;line-height:1.2}
   #bar button:hover{border-color:#7aa2f7;color:#7aa2f7}
-  .seg{display:inline-flex;border:1px solid #2a2e42;border-radius:5px;overflow:hidden}
-  .seg .segb{border:0;border-radius:0;padding:2px 11px}
-  .seg .segb.on{background:#7aa2f7;color:#16161e;font-weight:600}
-  #hub{width:3.5em;background:#1a1b26;color:#c0caf5;border:1px solid #2a2e42;border-radius:4px;padding:1px 4px;font:inherit}
+  #bar button:disabled{opacity:.4;cursor:default}
+  #bar button:disabled:hover{border-color:#2a2e42;color:#c0caf5}
+  #depthval{min-width:1.2em;text-align:center;display:inline-block;cursor:help}
+  #hub,#beam{width:3.5em;background:#1a1b26;color:#c0caf5;border:1px solid #2a2e42;border-radius:4px;padding:1px 4px;font:inherit}
   #legend{padding:4px 12px 6px;background:#16161e;border-bottom:1px solid #2a2e42;display:flex;flex-wrap:wrap;gap:2px 12px;font-size:12px;flex:0 0 auto}
   #main{flex:1 1 auto;position:relative;min-height:0}
   #cy{position:absolute;top:0;left:0;right:300px;bottom:0}
@@ -251,14 +253,16 @@ export function renderViewerHtml({ cytoscape, askEngine = "", embedData = null,
 </style></head><body>
 <div id="bar">
   <span class="grp"><b>seon</b> focus: <b id="focuslabel">…</b></span>
-  <span class="grp"><span class="lbl">depth</span><span class="seg" id="depthseg"></span></span>
-  <span class="grp"><label title="hide nodes with more connections than this (hubs swamp the layout)"><input type="checkbox" id="hubon" checked> hide hubs deg&gt; <input id="hub" type="number" min="2" max="200" value="16"></label></span>
+  <span class="grp"><span class="lbl">depth</span><button id="depthdown" title="shallower">−</button><b id="depthval"></b><button id="depthup" title="deeper">+</button></span>
+  <span class="grp"><label title="hide nodes with more connections than this (hubs swamp the layout)"><input type="checkbox" id="hubon" checked> hide hubs deg&gt; <input id="hub" type="number" min="2" max="200" value="16"></label>
+  <label title="beam-prune from the focus: at each hop keep only the top-N neighbours by degree (margin+cap prune) — a degree-scored analogue of the ask engine's beam search, NOT the same scorer"><input type="checkbox" id="beamon"> beam <input id="beam" type="number" min="1" max="32" value="8"></label></span>
   <span class="grp"><label>labels <select id="verb"><option value="smart">smart</option><option value="name">all names</option><option value="site">name+site</option><option value="none">none</option></select></label>
   <label>layout <select id="layout"><option value="cose">cose</option><option value="breadthfirst">tree</option><option value="concentric">concentric</option></select></label></span>
   <span class="grp" id="view">
-    <button id="reset" title="fit the whole graph in view (Esc)">fit</button>
+    <button id="fit" title="fit the whole graph in view (Esc)">fit</button>
     <button id="zoomout" title="zoom out">−</button>
     <button id="zoomin" title="zoom in">+</button>
+    <button id="reset" title="restore the boot view: default filters, all types shown, original focus">reset</button>
   </span>
   <span class="grp nav" id="sitenav" hidden><a href="/">home</a><a href="/code-browser.html">browser</a><a href="/timeline.html">timeline</a></span>
 </div>
@@ -321,19 +325,27 @@ function loadAskData(){
 function init(G){
   document.title='seon code-map — '+G.focusLabel;
   $('focuslabel').textContent=G.focusLabel;
-  if(G.siteNav)$('sitenav').hidden=false;
-  // Legend doubles as a node-type filter: a checkbox chip per mgx type
-  // (Module/Class/Function/Method/Attribute/GlobalVariable/Commit) with a live
-  // visible/loaded count for the current depth + hub-degree filters.
-  $('legend').innerHTML=Object.entries(COLORS)
-    .map(([k,v])=>'<label class="lg" title="show/hide '+k+' nodes"><input type="checkbox" class="typechk" data-cls="'+k+'" checked><i style="background:'+v+'"></i>'+k+'<span class="cnt" data-cnt="'+k+'"></span></label>')
+  // nav rides the data payload ({name: href}, hrefs relative to THIS page);
+  // G.siteNav is the legacy flag — stale deployed data keeps its absolute links.
+  if(G.nav){$('sitenav').innerHTML=Object.entries(G.nav).map(([k,h])=>'<a href="'+esc(h)+'">'+esc(k)+'</a>').join('');$('sitenav').hidden=false;}
+  else if(G.siteNav)$('sitenav').hidden=false;
+  // Legend doubles as a node-type filter: a checkbox chip per type GROUP —
+  // Function/Method share a chip (legend-only merge; node fills stay distinct),
+  // with a live visible/loaded count summed across the group.
+  const GROUPS=[['Module'],['Class'],['Function','Method'],['Attribute'],['GlobalVariable'],['Commit']];
+  $('legend').innerHTML=GROUPS
+    .map(g=>'<label class="lg" title="show/hide '+g.join('/')+' nodes"><input type="checkbox" class="typechk" data-cls="'+g.join(',')+'" checked>'+g.map(k=>'<i style="background:'+COLORS[k]+'"></i>').join('')+g.join('/')+'<span class="cnt" data-cnt="'+g.join(',')+'"></span></label>')
     .join(' ');
-  // depth is a segmented control (no dead range beyond the data's max depth), default 2
-  const maxDepth=Math.max(2,G.maxDepth);
-  $('depthseg').innerHTML=Array.from({length:maxDepth},(_,i)=>i+1)
-    .map(d=>'<button class="segb'+(d===2?' on':'')+'" data-d="'+d+'">'+d+'</button>').join('');
+  // depth is a − [N] + stepper clamped to the DATA's max depth (no dead buttons), default 2
+  const maxDepth=Math.max(1,G.maxDepth);
+  let depthVal=Math.min(2,maxDepth);
+  $('depthval').title='captured to depth '+maxDepth+' — regenerate with --depth for more';
+  function syncDepthUi(){$('depthval').textContent=depthVal;$('depthdown').disabled=depthVal<=1;$('depthup').disabled=depthVal>=maxDepth;}
+  syncDepthUi();
+  const INITIAL_FOCUS=G.focusId;
   const cy=cytoscape({container:document.getElementById('cy'),
-    elements:[...G.nodes.map(n=>({data:{...n,color:COLORS[n.cls]||'#8a8f98'}})),...G.edges.map((e,i)=>({data:{id:'e'+i,...e}}))],
+    // depth0 caches the boot depth per node BEFORE any recentre mutates data('depth') — the reset button restores from it
+    elements:[...G.nodes.map(n=>({data:{...n,depth0:n.depth,color:COLORS[n.cls]||'#8a8f98'}})),...G.edges.map((e,i)=>({data:{id:'e'+i,...e}}))],
     style:[
       // black text outline keeps white labels readable over node fills and the dark canvas;
       // node size encodes degree (bounded) so hubs read as hubs at a glance.
@@ -355,26 +367,53 @@ function init(G){
   let selId=null;
   function enabledTypes(){
     const on=new Set();
-    document.querySelectorAll('.typechk').forEach(c=>{if(c.checked)on.add(c.dataset.cls);});
+    document.querySelectorAll('.typechk').forEach(c=>{if(c.checked)c.dataset.cls.split(',').forEach(t=>on.add(t));});
     return on;
   }
-  function curDepth(){return +document.querySelector('.segb.on').dataset.d;}
+  function curDepth(){return depthVal;}
   function curHub(){return $('hubon').checked ? +$('hub').value : Infinity;}
+  const NODE=new Map(G.nodes.map(n=>[n.id,n]));
+  // Beam mode: BFS from the focus over the loaded adjacency, pruning each node's
+  // candidate neighbours (those passing hub+type filters) to the top-width by
+  // DEGREE with margin deg >= best*0.5 — mirrors BEAM_MARGIN_FRAC=0.5 in
+  // codegraph.mjs, but degree-scored: an analogue of the ask engine's beam
+  // search, not the same scorer.
+  function beamSet(width,h,types){
+    const pass=id=>{const n=NODE.get(id);return !!n&&(id===G.focusId||n.degree<=h)&&types.has(n.cls);};
+    const seen=new Set([G.focusId]);
+    let frontier=[G.focusId];
+    while(frontier.length){
+      const next=[];
+      for(const id of frontier){
+        const cand=(ADJ[id]||[]).filter(nb=>!seen.has(nb)&&pass(nb))
+          .sort((a,b)=>NODE.get(b).degree-NODE.get(a).degree);
+        const best=cand.length?NODE.get(cand[0]).degree:0;
+        for(const nb of cand.slice(0,width)){
+          if(NODE.get(nb).degree>=best*0.5){seen.add(nb);next.push(nb);}
+        }
+      }
+      frontier=next;
+    }
+    return seen;
+  }
   function applyFilters(){
     const d=curDepth(), h=curHub(), types=enabledTypes();
+    const beam=$('beamon').checked?beamSet(Math.max(1,Math.min(32,+$('beam').value||8)),h,types):null;
     const vis={}, tot={};
     cy.batch(()=>cy.nodes().forEach(n=>{
       const cls=n.data('cls');
       tot[cls]=(tot[cls]||0)+1;
-      const v = n.data('depth')<=d && (n.id()===G.focusId || n.data('degree')<=h) && types.has(cls);
+      const v = beam ? beam.has(n.id())
+        : n.data('depth')<=d && (n.id()===G.focusId || n.data('degree')<=h) && types.has(cls);
       if(v) vis[cls]=(vis[cls]||0)+1;
       n.style('display', v?'element':'none');
     }));
-    // live per-type counts: visible/loaded under the current depth + hub filters
+    // live per-group counts: visible/loaded summed across the group's classes
     document.querySelectorAll('.cnt').forEach(s=>{
-      const k=s.dataset.cnt;
-      s.textContent=(vis[k]||0)+'/'+(tot[k]||0);
-      s.title=(vis[k]||0)+' visible of '+(tot[k]||0)+' loaded '+k+' node(s) at depth '+d+(isFinite(h)?', hide deg>'+h:'');
+      const ks=s.dataset.cnt.split(',');
+      const v=ks.reduce((a,k)=>a+(vis[k]||0),0), t=ks.reduce((a,k)=>a+(tot[k]||0),0);
+      s.textContent=v+'/'+t;
+      s.title=v+' visible of '+t+' loaded '+ks.join('/')+' node(s) at depth '+d+(isFinite(h)?', hide deg>'+h:'');
     });
     applyLabels();
   }
@@ -397,18 +436,39 @@ function init(G){
   }
   cy.on('mouseover','node',e=>{if($('verb').value==='smart')e.target.style('label',labelText(e.target,false));});
   cy.on('mouseout','node',e=>{if($('verb').value==='smart')applyLabels();});
-  document.querySelectorAll('.segb').forEach(b=>b.addEventListener('click',()=>{
-    document.querySelectorAll('.segb').forEach(x=>x.classList.remove('on'));b.classList.add('on');applyFilters();}));
+  const stepDepth=dir=>{const d=Math.min(maxDepth,Math.max(1,depthVal+dir));if(d===depthVal)return;depthVal=d;syncDepthUi();applyFilters();};
+  $('depthdown').addEventListener('click',()=>stepDepth(-1));
+  $('depthup').addEventListener('click',()=>stepDepth(1));
   $('hubon').addEventListener('change',applyFilters);
   $('hub').addEventListener('input',applyFilters);
+  $('beamon').addEventListener('change',applyFilters);
+  $('beam').addEventListener('input',applyFilters);
   document.querySelectorAll('.typechk').forEach(c=>c.addEventListener('change',applyFilters));
   $('verb').addEventListener('change',applyLabels);
   $('layout').addEventListener('change',()=>cy.layout({name:$('layout').value,animate:false}).run());
   const ZF=1.2;
   const zoomBy=(f)=>cy.zoom({level:cy.zoom()*f,renderedPosition:{x:cy.width()/2,y:cy.height()/2}});
-  $('reset').addEventListener('click',()=>{cy.fit(undefined,30);});
+  $('fit').addEventListener('click',()=>{cy.fit(undefined,30);});
   $('zoomin').addEventListener('click',()=>zoomBy(ZF));
   $('zoomout').addEventListener('click',()=>zoomBy(1/ZF));
+  // real reset: back to the boot view — defaults, all types on, depths from
+  // depth0 (the pre-recentre capture), focus ring on the boot focus.
+  $('reset').addEventListener('click',()=>{
+    if($('layout').value!=='cose'){$('layout').value='cose';cy.layout({name:'cose',animate:false}).run();}
+    $('verb').value='smart';
+    $('hubon').checked=true;$('hub').value=16;
+    $('beamon').checked=false;$('beam').value=8;
+    depthVal=Math.min(2,maxDepth);syncDepthUi();
+    document.querySelectorAll('.typechk').forEach(c=>{c.checked=true;});
+    cy.getElementById(G.focusId).removeClass('focus');
+    G.focusId=INITIAL_FOCUS;
+    cy.batch(()=>cy.nodes().forEach(n=>n.data('depth',n.data('depth0'))));
+    cy.getElementById(INITIAL_FOCUS).addClass('focus');
+    $('focuslabel').textContent=G.focusLabel;
+    applyFilters();
+    select(null);
+    cy.fit(undefined,30);
+  });
   // Deep link into the source host (GitLab URL layout) when the data carries a
   // repoUrl: Commit nodes -> /-/commit/<sha>, anything with a file site ->
   // /-/blob/<ref>/<path>#L<lines>, bare Modules -> the file blob.
@@ -592,6 +652,8 @@ export async function startVizServer({ values, cytoscape, askEngine = "", log =
   const repoUrl = values["repo-url"] || (await repoUrlFromGit(process.cwd()));
   const viewer = renderViewerHtml({ cytoscape, askEngine });
   const browserPage = await renderBrowserHtml({ cytoscape });
+  // nav = the routes this server itself serves; injected into every payload/page
+  const nav = { home: "/", graph: "/seonix-graph.html", browser: "/code-browser.html", timeline: "/timeline.html" };
   const buildData = async () => {
     const { graph } = await loadGraph(values);
     const focus = resolveFocus(graph, values.focus);
@@ -602,7 +664,7 @@ export async function startVizServer({ values, cytoscape, askEngine = "", log =
       hubDegree: Math.max(2, parseInt(values.hub, 10) || 40),
       maxNodes: Math.max(2, parseInt(values.max, 10) || 200),
     });
-    return buildViewerData(subgraph, { focusLabel: focus.label, repoUrl, repoRef: values.ref });
+    return buildViewerData(subgraph, { focusLabel: focus.label, repoUrl, repoRef: values.ref, nav });
   };
   // The chat panel's own channel — the FULL raw graph (not the depth-limited display
   // sub-graph above), rebuilt fresh per request so a re-index shows up without a
@@ -620,7 +682,17 @@ export async function startVizServer({ values, cytoscape, askEngine = "", log =
       gitCommitParents(process.cwd()), // P3 ghost-branch merges
     ]);
     const tg = buildTemporalGraph(raw, order, { scope: values.scope, parentsBySha });
-    return buildBrowserData(tg, { repoUrl, repoRef: values.ref, live: true, gitHead: await gitHeadOf(process.cwd()) });
+    return buildBrowserData(tg, { repoUrl, repoRef: values.ref, live: true, gitHead: await gitHeadOf(process.cwd()), nav });
+  };
+  const buildTimelinePage = async () => {
+    const { raw } = await loadGraph(values);
+    return renderTimelineHtml({
+      commits: extractTimeline(raw),
+      repoUrl,
+      repoRef: values.ref,
+      generatedAt: raw.generated_at || "",
+      nav,
+    });
   };
   await buildData(); // fail fast (missing graph, bad focus) before binding the port
   const server = createServer(async (req, res) => {
@@ -631,6 +703,16 @@ export async function startVizServer({ values, cytoscape, askEngine = "", log =
     } else if (path === "/browser" || path === "/code-browser.html") {
       res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
       res.end(browserPage);
+    } else if (path === "/timeline" || path === "/timeline.html") {
+      // rendered from a fresh graph load, same re-index-shows-on-refresh invariant
+      try {
+        const page = await buildTimelinePage();
+        res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+        res.end(page);
+      } catch (err) {
+        res.writeHead(500, { "content-type": "text/plain" });
+        res.end(`failed to render the timeline: ${String(err.message || err)}`);
+      }
     } else if (path === "/seonix-graph-data.json") {
       try {
         res.writeHead(200, { "content-type": "application/json" });
@@ -693,9 +775,12 @@ export async function runVizCli(argv) {
       "site-nav": { type: "boolean", default: false },
       serve: { type: "boolean", default: false },
       port: { type: "string", default: "0" },
-      // Chronograph (code browser) artifacts — see src/browser.mjs
+      // Chronograph (code browser) + timeline artifacts — generated next to --out
+      // by default; --graph-only suppresses both. See src/browser.mjs, src/timeline.mjs.
       "browser-out": { type: "string" },
       "browser-data-out": { type: "string" },
+      "timeline-out": { type: "string" },
+      "graph-only": { type: "boolean", default: false },
       scope: { type: "string", default: "product" },
     },
     allowPositionals: false,
@@ -721,13 +806,30 @@ export async function runVizCli(argv) {
     hubDegree: Math.max(2, parseInt(values.hub, 10) || 40),
     maxNodes: Math.max(2, parseInt(values.max, 10) || 200),
   });
+  const out = resolve(values.out);
+  // Siblings by default: the code browser and the commit timeline land next to
+  // --out unless --graph-only. Nav hrefs are computed from the ACTUAL output
+  // paths (filenames vary: seon-graph.html locally, seonix-graph.html on site);
+  // --site-nav additionally adds the site's absolute home entry.
+  const browserOut = values["graph-only"] ? null : resolve(values["browser-out"] || join(dirname(out), "code-browser.html"));
+  const timelineOut = values["graph-only"] ? null : resolve(values["timeline-out"] || join(dirname(out), "timeline.html"));
+  const relHref = (from, to) => {
+    const r = relative(dirname(from), to);
+    return r.startsWith(".") ? r : `./${r}`;
+  };
+  const navFor = (from) => ({
+    ...(values["site-nav"] ? { home: "/" } : {}),
+    graph: relHref(from, out),
+    browser: relHref(from, browserOut),
+    timeline: relHref(from, timelineOut),
+  });
   const data = buildViewerData(subgraph, {
     focusLabel: focus.label,
     repoUrl: values["repo-url"],
     repoRef: values.ref,
     siteNav: values["site-nav"],
+    nav: values["graph-only"] ? null : navFor(out),
   });
-  const out = resolve(values.out);
   if (values["data-out"]) {
     // site mode: viewer page + sibling data file (data updates don't touch the page).
     // The chat panel's full-graph channel rides the same sibling-file convention,
@@ -755,36 +857,55 @@ export async function runVizCli(argv) {
     );
   }
 
-  // Chronograph artifacts (the code browser) — same one-page/data-sibling pattern.
-  if (values["browser-out"]) {
-    const raw = await source.fetchEntities(config);
-    const commitIds = (raw.individuals || []).filter((i) => i.class === "Commit").map((i) => i.id);
-    const [order, parentsBySha] = await Promise.all([
-      gitCommitOrder(process.cwd(), commitIds),
-      gitCommitParents(process.cwd()), // P3 ghost-branch merges — static data, no polling here
-    ]);
-    const tg = buildTemporalGraph(raw, order, { scope: values.scope, parentsBySha });
-    const browserData = buildBrowserData(tg, {
-      repoUrl: values["repo-url"] || (await repoUrlFromGit(process.cwd())),
-      repoRef: values.ref,
-      siteNav: values["site-nav"],
-    });
-    const bOut = resolve(values["browser-out"]);
-    if (values["browser-data-out"]) {
-      const bDataOut = resolve(values["browser-data-out"]);
-      const rel = relative(dirname(bOut), bDataOut) || "code-browser-data.json";
-      await writeFile(bDataOut, JSON.stringify(browserData));
-      await writeFile(bOut, await renderBrowserHtml({ cytoscape, dataPath: rel === "code-browser-data.json" ? null : rel }));
-      process.stderr.write(
-        `seonix viz: chronograph ${tg.nodes.length} nodes, ${tg.edges.length} edges, ${tg.commits.length} commits ` +
-          `(scope ${values.scope}) → ${bOut} + ${bDataOut}\n`,
-      );
-    } else {
-      await writeFile(bOut, await renderBrowserHtml({ cytoscape, embedData: browserData }));
-      process.stderr.write(
-        `seonix viz: chronograph ${tg.nodes.length} nodes, ${tg.edges.length} edges, ${tg.commits.length} commits ` +
-          `(scope ${values.scope}) → ${bOut}\n`,
-      );
+  // Sibling artifacts (code browser + commit timeline) — best-effort: a missing
+  // git history (or any other failure here) warns but never kills the graph
+  // artifact already written above.
+  if (browserOut || timelineOut) {
+    try {
+      const repoUrl = values["repo-url"] || (await repoUrlFromGit(process.cwd()));
+      if (browserOut) {
+        const commitIds = (raw.individuals || []).filter((i) => i.class === "Commit").map((i) => i.id);
+        const [order, parentsBySha] = await Promise.all([
+          gitCommitOrder(process.cwd(), commitIds),
+          gitCommitParents(process.cwd()), // P3 ghost-branch merges — static data, no polling here
+        ]);
+        const tg = buildTemporalGraph(raw, order, { scope: values.scope, parentsBySha });
+        const browserData = buildBrowserData(tg, {
+          repoUrl,
+          repoRef: values.ref,
+          siteNav: values["site-nav"],
+          nav: navFor(browserOut),
+        });
+        if (values["browser-data-out"]) {
+          const bDataOut = resolve(values["browser-data-out"]);
+          const rel = relative(dirname(browserOut), bDataOut) || "code-browser-data.json";
+          await writeFile(bDataOut, JSON.stringify(browserData));
+          await writeFile(browserOut, await renderBrowserHtml({ cytoscape, dataPath: rel === "code-browser-data.json" ? null : rel }));
+          process.stderr.write(
+            `seonix viz: chronograph ${tg.nodes.length} nodes, ${tg.edges.length} edges, ${tg.commits.length} commits ` +
+              `(scope ${values.scope}) → ${browserOut} + ${bDataOut}\n`,
+          );
+        } else {
+          await writeFile(browserOut, await renderBrowserHtml({ cytoscape, embedData: browserData }));
+          process.stderr.write(
+            `seonix viz: chronograph ${tg.nodes.length} nodes, ${tg.edges.length} edges, ${tg.commits.length} commits ` +
+              `(scope ${values.scope}) → ${browserOut}\n`,
+          );
+        }
+      }
+      if (timelineOut) {
+        const commits = extractTimeline(raw);
+        await writeFile(timelineOut, renderTimelineHtml({
+          commits,
+          repoUrl,
+          repoRef: values.ref,
+          generatedAt: raw.generated_at || "",
+          nav: navFor(timelineOut),
+        }));
+        process.stderr.write(`seonix viz: timeline ${commits.length} commits → ${timelineOut}\n`);
+      }
+    } catch (err) {
+      process.stderr.write(`seonix viz: warning — sibling pages (browser/timeline) failed: ${String(err.message || err)}; the graph artifact is intact\n`);
     }
   }
 }