npm - @polycode-projects/seonix - Versions diffs - 0.2.1 → 0.4.0 - Mend

@polycode-projects/seonix 0.2.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

package/src/viz.mjs CHANGED Viewed

@@ -25,6 +25,8 @@ 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";
+import { winkBrowserBundle } from "./nlp-bundle.mjs";
 const here = dirname(fileURLToPath(import.meta.url));
 const execFileP = promisify(execFile);
@@ -134,7 +136,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 +144,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,
   };
@@ -201,12 +204,24 @@ const inlineJson = (v) => JSON.stringify(v).replace(/</g, "\\u003c");
  * silently produce incomplete answers, which this project's honesty contract
  * doesn't allow (see the file-level comment's "ONE viewer, three data channels" —
  * this is a fourth, for the same one-viewer-many-modes reason).
+ *
+ * The OPTIONAL wink-nlp lemma tier (ask-nlp.mjs's browser twin, from nlp-bundle.mjs)
+ * reaches the chat two ways: `nlpInline` inlines the ~4 MB bundle as its own <script>
+ * so it registers `window.__seonixNlp` at page load (portable `viz --nlp`); `nlpPath`
+ * points the page at a same-origin sibling asset the chat LAZY-loads on first ask
+ * (the SITE build). Neither is present in the default local single-file — that viewer
+ * stays lemma-off and fetches nothing, exactly as before, preserving its
+ * no-external-fetch guarantee. ask() picks up whatever `window.__seonixNlp` is set,
+ * or degrades to the adapter-less tiers when it's absent.
  */
-export function renderViewerHtml({ cytoscape, askEngine = "", embedData = null, dataPath = null, askData = null, askDataPath = null } = {}) {
+export function renderViewerHtml({ cytoscape, askEngine = "", embedData = null, dataPath = null, askData = null, askDataPath = null, nlpInline = null, nlpPath = null } = {}) {
   const embedded = embedData ? `<script type="application/json" id="seonix-data">${inlineJson(embedData)}</script>\n` : "";
   const askEmbedded = askData ? `<script type="application/json" id="seonix-ask-data">${inlineJson(askData)}</script>\n` : "";
-  const cfgObj = { ...(dataPath ? { data: dataPath } : {}), ...(askDataPath ? { ask: askDataPath } : {}) };
+  const cfgObj = { ...(dataPath ? { data: dataPath } : {}), ...(askDataPath ? { ask: askDataPath } : {}), ...(nlpPath ? { nlp: nlpPath } : {}) };
   const cfg = Object.keys(cfgObj).length ? `<script type="application/json" id="seonix-cfg">${inlineJson(cfgObj)}</script>\n` : "";
+  // Inline bundle: escape any literal </script inside the wink model data so the
+  // block can't be closed early (harmless inside JS strings, impossible outside them).
+  const nlpEmbedded = nlpInline ? `<script>${String(nlpInline).replace(/<\/script/gi, "<\\/script")}</script>\n` : "";
   return `<!doctype html><html><head><meta charset="utf-8"><title>seon code-map</title>
 <!-- generated by: seonix viz (see packages/seonix/src/viz.mjs) — one viewer, data loaded at runtime -->
 <style>
@@ -219,18 +234,25 @@ 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}
-  #side{position:absolute;top:0;right:0;width:300px;bottom:0;background:#16161e;border-left:1px solid #2a2e42;padding:14px;overflow:auto;box-sizing:border-box}
+  /* Graph on top (full width, generous height); the chat + node-detail ride a
+     full-width row BENEATH it (chat grows, detail a compact fixed column). On a
+     narrow screen #below stacks so the body never scrolls sideways. */
+  #main{flex:1 1 auto;display:flex;flex-direction:column;min-height:0}
+  #cy{flex:1 1 auto;position:relative;min-height:260px}
+  #below{flex:0 0 auto;display:flex;background:#16161e;border-top:1px solid #2a2e42;max-height:46vh;box-sizing:border-box}
+  #ask{flex:1 1 auto;min-width:0;padding:14px 16px;overflow:auto;box-sizing:border-box;display:flex;flex-direction:column}
+  #detail{flex:0 0 300px;padding:14px;overflow:auto;border-left:1px solid #2a2e42;box-sizing:border-box}
+  @media(max-width:720px){#below{flex-direction:column;max-height:58vh;overflow:auto}#detail{flex:0 0 auto;border-left:0;border-top:1px solid #2a2e42}}
   .lg{white-space:nowrap;cursor:pointer;user-select:none;color:#a9b1d6}.lg i{display:inline-block;width:10px;height:10px;border-radius:2px;margin-right:4px;vertical-align:middle}.lg input{vertical-align:middle;margin:0 3px 0 0}
   .lg .cnt{color:#565f89;margin-left:3px;font-size:11px;font-variant-numeric:tabular-nums}
   select{background:#1a1b26;color:#c0caf5;border:1px solid #2a2e42;border-radius:4px;font:inherit}
-  #side h3{margin:2px 0 8px;color:#c0caf5;font-size:15px;word-break:break-all}
+  #detail h3{margin:2px 0 8px;color:#c0caf5;font-size:15px;word-break:break-all}
+  #ask h4{margin:0 0 8px;color:#a9b1d6;font-size:11px;text-transform:uppercase;letter-spacing:.04em}
   .badge{display:inline-flex;align-items:center;gap:6px;padding:2px 9px;border:1px solid #2a2e42;border-radius:10px;font-size:11px;color:#a9b1d6}
   .badge i{width:8px;height:8px;border-radius:50%;display:inline-block}
   #detail dl{display:grid;grid-template-columns:auto 1fr;gap:2px 12px;margin:10px 0;font-size:12px;color:#c0caf5}
@@ -241,32 +263,34 @@ export function renderViewerHtml({ cytoscape, askEngine = "", embedData = null,
   .hint{color:#565f89;font-size:11px;margin-top:10px}
   .empty{color:#a9b1d6;font-size:12px;line-height:1.7}
   code{color:#9aa5ce;word-break:break-all}
-  #ask{padding-bottom:12px;margin-bottom:12px;border-bottom:1px solid #2a2e42}
   .askrow{display:flex;gap:6px}
-  #askq{flex:1;min-width:0;background:#1a1b26;color:#c0caf5;border:1px solid #2a2e42;border-radius:4px;padding:4px 8px;font:inherit}
+  #askq{flex:1;min-width:0;background:#1a1b26;color:#c0caf5;border:1px solid #2a2e42;border-radius:4px;padding:7px 10px;font:inherit;font-size:13px}
   #askq:focus{outline:none;border-color:#7aa2f7}
-  .askresult{margin-top:8px;font-size:12px;line-height:1.6;color:#c0caf5}
+  .askresult{margin-top:10px;flex:1 1 auto;font-size:12.5px;line-height:1.6;color:#c0caf5;overflow:auto}
   .askresult.miss{color:#a9b1d6;font-style:italic}
   .askresult .askq-echo{color:#565f89;margin-bottom:4px;font-style:normal}
 </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>
 <div id="legend"></div>
 <div id="main">
   <div id="cy"></div>
-  <div id="side">
+  <div id="below">
     <div id="ask">
+      <h4>Ask the graph</h4>
       <div class="askrow"><input id="askq" type="text" autocomplete="off" placeholder='ask e.g. "what calls this"'><button class="btn" id="asksubmit">ask</button></div>
       <div id="askresult" class="askresult"></div>
     </div>
@@ -275,7 +299,7 @@ export function renderViewerHtml({ cytoscape, askEngine = "", embedData = null,
 </div>
 ${embedded}${askEmbedded}${cfg}<script>${cytoscape}</script>
 <script>${askEngine}</script>
-<script>
+${nlpEmbedded}<script>
 // Type palette (see the CVD note in viz.mjs) — viewer styling, identical for every repo.
 const COLORS={Module:'#3987e5',Class:'#c98500',Function:'#008300',Method:'#d55181',Attribute:'#9085e9',GlobalVariable:'#d95926',Commit:'#199e70'};
 const $=id=>document.getElementById(id);
@@ -318,22 +342,53 @@ function loadAskData(){
   })();
   return _askGraphPromise;
 }
+// The OPTIONAL wink-nlp lemma adapter (window.__seonixNlp — see nlp-bundle.mjs).
+// An inlined bundle registers it at page load; the site build ships it as a
+// same-origin sibling this injects LAZILY on the first ask (never at boot), so the
+// ~4 MB model is only paid for when the chat is actually used. With neither present
+// (the default local single-file) this resolves to undefined and the chat runs
+// adapter-less — ask() then falls back to its curated + fuzzy tiers, exactly as
+// before, and NOTHING is fetched, keeping the no-external-fetch guarantee intact.
+let _nlpPromise=null;
+function loadNlp(){
+  if(window.__seonixNlp) return Promise.resolve(window.__seonixNlp);
+  if(_nlpPromise) return _nlpPromise;
+  const cfgEl=document.getElementById('seonix-cfg');
+  const url=cfgEl?JSON.parse(cfgEl.textContent).nlp:null;
+  if(!url) return Promise.resolve(undefined);
+  _nlpPromise=new Promise(res=>{
+    const s=document.createElement('script');
+    s.src=url;
+    s.onload=()=>res(window.__seonixNlp);
+    s.onerror=()=>res(undefined); // a failed asset degrades to lemma-off, never a broken chat
+    document.head.appendChild(s);
+  });
+  return _nlpPromise;
+}
 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 +410,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 +479,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.
@@ -504,8 +607,10 @@ function init(G){
       return;
     }
     out.textContent='thinking…';
-    loadAskData().then(askGraph=>{
-      const {content,seonix_ask}=ask(askGraph,query,{contextId:selId});
+    // Load the graph and (if configured) the wink lemma adapter together, then run
+    // the mechanical ask. An undefined nlp makes ask() degrade to its adapter-less tiers.
+    Promise.all([loadAskData(),loadNlp()]).then(([askGraph,nlp])=>{
+      const {content,seonix_ask}=ask(askGraph,query,{contextId:selId,nlp});
       const total=(seonix_ask.matches||[]).length;
       const shown=total?highlightAsk(seonix_ask.matches.map(m=>m.id)):0;
       out.classList.toggle('miss',!!seonix_ask.miss);
@@ -587,11 +692,15 @@ function resolveFocus(graph, focusArg) {
  * code browser rides along at `/code-browser.html` (alias `/browser`) with a live
  * temporal payload — the local equivalent of the site's browser section.
  */
-export async function startVizServer({ values, cytoscape, askEngine = "", log = () => {} }) {
+export async function startVizServer({ values, cytoscape, askEngine = "", nlpBundle = null, log = () => {} }) {
   const port = Math.max(0, parseInt(values.port, 10) || 0);
   const repoUrl = values["repo-url"] || (await repoUrlFromGit(process.cwd()));
-  const viewer = renderViewerHtml({ cytoscape, askEngine });
+  // With --nlp the local live view gets the same lemma tier as the site: the bundle
+  // is served in-process at /seonix-nlp.js and the viewer lazy-loads it on first ask.
+  const viewer = renderViewerHtml({ cytoscape, askEngine, nlpPath: nlpBundle ? "/seonix-nlp.js" : null });
   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 +711,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 +729,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 +750,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" });
@@ -666,6 +795,9 @@ export async function startVizServer({ values, cytoscape, askEngine = "", log =
         res.writeHead(500, { "content-type": "application/json" });
         res.end(JSON.stringify({ error: String(err.message || err) }));
       }
+    } else if (path === "/seonix-nlp.js" && nlpBundle) {
+      res.writeHead(200, { "content-type": "text/javascript; charset=utf-8" });
+      res.end(nlpBundle);
     } else {
       res.writeHead(404, { "content-type": "text/plain" });
       res.end("not found");
@@ -693,17 +825,28 @@ 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" },
+      // Include the OPTIONAL wink-nlp lemma tier in the chat (see nlp-bundle.mjs).
+      // Site mode (--data-out): written as a same-origin sibling the page lazy-loads.
+      // Portable/serve mode: inlined (single-file) / served in-process. Off by default,
+      // so the local single-file stays lean and lemma-off exactly as before.
+      nlp: { type: "boolean", default: false },
     },
     allowPositionals: false,
   });
   const cytoscape = await cytoscapeSource();
   const askEngine = await askSource();
+  // Build the wink lemma bundle once, only when --nlp asked for it (~4 MB; skip the
+  // work entirely otherwise). Wired below as a sibling asset (site) or inline (portable).
+  const nlpBundle = values.nlp ? await winkBrowserBundle() : null;
   if (values.serve) {
-    await startVizServer({ values, cytoscape, askEngine, log: (s) => process.stderr.write(s) });
+    await startVizServer({ values, cytoscape, askEngine, nlpBundle, log: (s) => process.stderr.write(s) });
     return; // keeps serving until Ctrl-C
   }
   const { config, graph, raw } = await loadGraph(values);
@@ -721,13 +864,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,
@@ -736,55 +896,85 @@ export async function runVizCli(argv) {
     const rel = relative(dirname(out), dataOut) || "seonix-graph-data.json";
     const askDataOut = resolve(dirname(out), "seonix-ask-data.json");
     const askRel = relative(dirname(out), askDataOut) || "seonix-ask-data.json";
+    // Site build: the wink lemma bundle rides the same sibling-asset convention as
+    // the data files — a same-origin ./seonix-nlp.js the page lazy-loads on first ask.
+    let nlpPath = null;
+    if (nlpBundle) {
+      const nlpOut = resolve(dirname(out), "seonix-nlp.js");
+      await writeFile(nlpOut, nlpBundle);
+      nlpPath = "./seonix-nlp.js";
+    }
     await Promise.all([writeFile(dataOut, JSON.stringify(data)), writeFile(askDataOut, JSON.stringify(raw))]);
     await writeFile(out, renderViewerHtml({
       cytoscape, askEngine,
       dataPath: rel === "seonix-graph-data.json" ? null : rel,
       askDataPath: askRel === "seonix-ask-data.json" ? null : askRel,
+      nlpPath,
     }));
     process.stderr.write(
       `seonix viz: ${subgraph.nodes.length} nodes, ${subgraph.edges.length} edges around "${focus.label}" ` +
-        `(depth ${values.depth})${subgraph.truncated ? " [capped]" : ""} → ${out} + ${dataOut} + ${askDataOut}\n`,
+        `(depth ${values.depth})${subgraph.truncated ? " [capped]" : ""} → ${out} + ${dataOut} + ${askDataOut}` +
+        `${nlpPath ? ` + ${resolve(dirname(out), "seonix-nlp.js")} (wink lemma tier)` : ""}\n`,
     );
   } else {
-    // portable mode: one self-contained file, both channels embedded
-    await writeFile(out, renderViewerHtml({ cytoscape, askEngine, embedData: data, askData: raw }));
+    // portable mode: one self-contained file, both channels embedded (+ inline wink
+    // bundle when --nlp; otherwise lemma-off, no external fetch, exactly as before)
+    await writeFile(out, renderViewerHtml({ cytoscape, askEngine, embedData: data, askData: raw, nlpInline: nlpBundle }));
     process.stderr.write(
       `seonix viz: ${subgraph.nodes.length} nodes, ${subgraph.edges.length} edges around "${focus.label}" ` +
         `(depth ${values.depth})${subgraph.truncated ? " [capped]" : ""} → ${out}\n`,
     );
   }
-  // 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`);
     }
   }
 }