Upload folder using huggingface_hub

hf_space/streamlit_app.py

@@ -1353,9 +1353,11 @@ def _workflow_run_id(paper_input: str) -> str:
 
 
 def _mount_graph_shell(graph_slot) -> None:
-    """Mount the persistent graph canvas once (constant HTML → Streamlit reuses it)."""
+    """Mount the graph canvas shell (st.iframe HTML srcdoc + tree layout JS)."""
     if graph_slot is None:
         return
+    # Call-time import; avoid importlib.reload so identical shell HTML can be
+    # reused across Streamlit runs instead of forcing a fresh iframe each time.
     from workflow_graph import render_graph_shell
 
     render_graph_shell(graph_slot)
@@ -3212,19 +3214,24 @@ def _render_annotation_process_view(
                     courier_slot=courier_slot,
                 )
             # Keep the same demo selected after finish; do not advance to Paper 2.
+            # No st.rerun() here: the stream already painted the final work panel,
+            # overview metrics, and graph via placeholders/courier. A full rerun
+            # remounts the page (and graph iframe) and looks like a refresh.
             if not live_run_mode and paper_input.strip():
-                _set_demo_paper(paper_input.strip())
-            st.rerun()
+                st.session_state["live_run_mode"] = False
+                st.session_state["selected_demo_url"] = paper_input.strip()
 
     with tabs[1]:
         paper_dir, discovery, contributions, payload = _load_result_bundle(
             st.session_state.get("paper_input", "")
+            or st.session_state.get("selected_demo_url", "")
         )
         _render_clusters_tab(discovery, contributions)
 
     with tabs[2]:
         paper_dir, discovery, contributions, payload = _load_result_bundle(
             st.session_state.get("paper_input", "")
+            or st.session_state.get("selected_demo_url", "")
         )
         _render_claims_tab(payload)
 

hf_space/workflow_graph.py

@@ -1,8 +1,9 @@
 """Evolving SciPaths workflow graph (Neo4j-backed).
 
-Visual formatting follows Mina Brain's knowledge-graph canvas strictly:
-filled circle + white inner stroke + colored ring, 25-char labels with white
-halo, expanding write-pulse rings, #fafbfd stage, click detail card.
+Visual formatting follows Mina Brain's node chrome (filled circle + white
+inner stroke + colored ring, 25-char labels, write-pulse rings, #fafbfd
+stage, click detail card) but lays nodes out as a strict top-down n-ary
+tree: Target → Citing → Theme → Claim → Ingredient → Prior study.
 """
 
 from __future__ import annotations
@@ -93,8 +94,8 @@ KIND_META = {
     },
 }
 
-# Category order + compact per-kind palette the canvas shell + rail consume.
-_KIND_ORDER = ["target", "claim", "ingredient", "cluster", "study", "citing"]
+# Category order (top-down tree levels) + palette the canvas shell / rail consume.
+_KIND_ORDER = ["target", "citing", "cluster", "claim", "ingredient", "study"]
 _KIND_META_JS = {
     k: {"fill": v["fill"], "ring": v["ring"], "text": v["text"], "label": v["type_label"]}
     for k, v in KIND_META.items()
@@ -518,12 +519,11 @@ def build_graph_model(
     }
 
 
-def _graph_payload(model: dict[str, Any]) -> dict[str, Any]:
-    """Serialize a graph model into the payload the canvas shell consumes."""
-    nodes_in = model.get("nodes") or []
-    edges_in = model.get("edges") or []
-
-    nodes_js = []
+def _nodes_edges_payload(
+    nodes_in: list[dict[str, Any]], edges_in: list[dict[str, Any]]
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """Serialize nodes/edges for the canvas shell."""
+    nodes_js: list[dict[str, Any]] = []
     for n in nodes_in:
         kind = str(n.get("kind") or "citing")
         meta = KIND_META.get(kind, KIND_META["citing"])
@@ -542,7 +542,7 @@ def _graph_payload(model: dict[str, Any]) -> dict[str, Any]:
                 "typeLabel": n.get("type_label") or meta["type_label"],
             }
         )
-    edges_js = []
+    edges_js: list[dict[str, Any]] = []
     for e in edges_in:
         edges_js.append(
             {
@@ -553,12 +553,28 @@ def _graph_payload(model: dict[str, Any]) -> dict[str, Any]:
                 "muted": bool(e.get("muted")),
             }
         )
-    return {
+    return nodes_js, edges_js
+
+
+def _graph_payload(model: dict[str, Any]) -> dict[str, Any]:
+    """Serialize a graph model into the payload the canvas shell consumes."""
+    nodes_js, edges_js = _nodes_edges_payload(
+        list(model.get("nodes") or []), list(model.get("edges") or [])
+    )
+    out: dict[str, Any] = {
         "nodes": nodes_js,
         "edges": edges_js,
         "kindMeta": _KIND_META_JS,
         "kindOrder": _KIND_ORDER,
+        "frameKey": str(model.get("frame_key") or ""),
     }
+    frame = model.get("frame")
+    if isinstance(frame, dict) and frame.get("nodes"):
+        f_nodes, f_edges = _nodes_edges_payload(
+            list(frame.get("nodes") or []), list(frame.get("edges") or [])
+        )
+        out["frame"] = {"nodes": f_nodes, "edges": f_edges}
+    return out
 
 
 def courier_html(payload: dict[str, Any]) -> str:
@@ -583,19 +599,23 @@ def courier_html(payload: dict[str, Any]) -> str:
     )
 
 
+# Bump when canvas JS changes so Streamlit remounts the component iframe.
+_GRAPH_SHELL_VERSION = "tree-v4"
+
+
 def graph_shell_html(height: int = 520) -> str:
-    """Stable, model-free canvas shell. Data arrives via postMessage (incremental).
+    """Model-free canvas shell. Data arrives via postMessage (incremental).
 
-    The HTML is constant for a given height, so Streamlit reuses the same iframe
-    across reruns instead of remounting it. The graph is populated / grown by
-    ``courier_html`` messages.
+    HTML includes ``_GRAPH_SHELL_VERSION`` so layout/code updates remount the
+    iframe. The graph is populated / grown by ``courier_html`` messages.
     """
     payload = json.dumps(
         {"nodes": [], "edges": [], "kindMeta": _KIND_META_JS, "kindOrder": _KIND_ORDER}
     )
     row_h = max(300, height - 30)
+    ver = _GRAPH_SHELL_VERSION
     return f"""<!DOCTYPE html>
-<html>
+<html data-scipaths-shell="{ver}">
 <head>
   <meta charset="utf-8" />
   <link rel="preconnect" href="https://fonts.googleapis.com" />
@@ -670,7 +690,7 @@ def graph_shell_html(height: int = 520) -> str:
 </head>
 <body>
   <div class="wrap">
-    <div class="kicker">Workflow</div>
+    <div class="kicker">Workflow tree</div>
     <div class="row">
       <aside class="rail">
         <div class="rail-head">Graph controls</div>
@@ -701,7 +721,7 @@ def graph_shell_html(height: int = 520) -> str:
           <div class="card-title" id="cardTitle"></div>
           <p class="card-detail" id="cardDetail"></p>
         </div>
-        <div class="hint">Drag to move · scroll to zoom · click a node for details</div>
+        <div class="hint">Top-down tree · scroll to zoom · drag canvas to pan · click a node</div>
       </div>
     </div>
   </div>
@@ -729,8 +749,16 @@ def graph_shell_html(height: int = 520) -> str:
     resize();
     window.addEventListener('resize', () => {{ resize(); }});
 
-    // ── Position memory across reruns (Mina keeps xy so the graph grows, not jumps).
-    const memKey = 'scipaths-mina-pos';
+    // Semantic depth bands (visual tree levels — not edge hop count).
+    const KIND_LEVEL = {{ target: 0, citing: 1, cluster: 2, claim: 3, ingredient: 4, study: 5 }};
+    const KIND_SIBLING_ORDER = {{ citing: 0, cluster: 1, claim: 2, ingredient: 3, study: 4, target: -1 }};
+    const ROW_GAP = 108;
+    const TOP_Y = 52;
+    const MIN_GAP = 78;
+    const levelOf = (n) => (KIND_LEVEL[n.kind] != null ? KIND_LEVEL[n.kind] : 1);
+
+    // Position memory for spawn animation only (tree slots are recomputed).
+    const memKey = 'scipaths-tree-pos-v1';
     let saved = {{}};
     try {{ saved = JSON.parse(sessionStorage.getItem(memKey) || '{{}}'); }} catch (e) {{ saved = {{}}; }}
 
@@ -739,6 +767,10 @@ def graph_shell_html(height: int = 520) -> str:
     const byId = new Map();
     let edges = [];
     let target = null;
+    let fitPending = false;
+    // Camera locked to the final tree frame so zoom stays fixed while the graph grows.
+    let cameraLocked = false;
+    let lockedFrameKey = '';
 
     // ── Filter / search state ──
     const hiddenKinds = new Set();
@@ -754,11 +786,10 @@ def graph_shell_html(height: int = 520) -> str:
     let pulseEdgeIds = new Set();
     let pulseStart = 0;
 
-    // ── View transform (zoom + pan), Mina-style ──
+    // ── View transform (zoom + pan) ──
     let zoom = 0.95;
     let panX = (W / 2) * (1 - zoom);
-    let panY = (H / 2) * (1 - zoom);
-    let alpha = 1;
+    let panY = 18;
     const toWorld = (px, py) => ({{ x: (px - panX) / zoom, y: (py - panY) / zoom }});
 
     let dragNode = null, panning = false, moved = false;
@@ -771,6 +802,82 @@ def graph_shell_html(height: int = 520) -> str:
       try {{ sessionStorage.setItem(memKey, JSON.stringify(out)); }} catch (e) {{}}
     }}
 
+    function parentNode(n, edgeList) {{
+      const list = edgeList || edges;
+      let best = null, bestLvl = -Infinity;
+      for (const e of list) {{
+        if (e.target !== n.id) continue;
+        const p = byId.get(e.source);
+        if (!p) continue;
+        const pl = levelOf(p);
+        if (pl < levelOf(n) && pl >= bestLvl) {{ best = p; bestLvl = pl; }}
+      }}
+      if (!best && n.id !== 'target') best = byId.get('target') || null;
+      return best;
+    }}
+
+    function layoutTree() {{
+      if (!nodes.length) return;
+      // Always assign depth; pack only visible nodes so filters reflow cleanly.
+      nodes.forEach(n => {{ n.ty = TOP_Y + levelOf(n) * ROW_GAP; }});
+      const vis = nodes.filter(isVisible);
+      if (!vis.length) return;
+      const children = new Map();
+      const visibleParent = (n) => {{
+        let p = parentNode(n);
+        while (p && !isVisible(p)) p = parentNode(p);
+        return p;
+      }};
+      vis.forEach(n => {{
+        const p = visibleParent(n);
+        n._parentId = p ? p.id : null;
+        if (!p) return;
+        if (!children.has(p.id)) children.set(p.id, []);
+        children.get(p.id).push(n);
+      }});
+      for (const kids of children.values()) {{
+        kids.sort((a, b) => {{
+          const oa = KIND_SIBLING_ORDER[a.kind] != null ? KIND_SIBLING_ORDER[a.kind] : 9;
+          const ob = KIND_SIBLING_ORDER[b.kind] != null ? KIND_SIBLING_ORDER[b.kind] : 9;
+          if (oa !== ob) return oa - ob;
+          return String(a.id).localeCompare(String(b.id));
+        }});
+      }}
+      const leafGap = (n) => Math.max(MIN_GAP, (n.r || 14) * 2 + 36);
+      const subtreeWidth = (n) => {{
+        const kids = children.get(n.id) || [];
+        if (!kids.length) return leafGap(n);
+        let w = 0;
+        kids.forEach(k => {{ w += subtreeWidth(k); }});
+        return Math.max(leafGap(n), w);
+      }};
+      const place = (n, centerX) => {{
+        n.tx = centerX;
+        n.ty = TOP_Y + levelOf(n) * ROW_GAP;
+        const kids = children.get(n.id) || [];
+        if (!kids.length) return;
+        const widths = kids.map(subtreeWidth);
+        const total = widths.reduce((s, w) => s + w, 0);
+        let x = centerX - total / 2;
+        kids.forEach((k, i) => {{
+          const w = widths[i];
+          place(k, x + w / 2);
+          x += w;
+        }});
+      }};
+      const roots = vis.filter(n => !n._parentId);
+      const orderedRoots = roots.length ? roots : [vis[0]];
+      orderedRoots.sort((a, b) => String(a.id).localeCompare(String(b.id)));
+      const widths = orderedRoots.map(subtreeWidth);
+      const total = widths.reduce((s, w) => s + w, 0);
+      let x = -total / 2;
+      orderedRoots.forEach((r, i) => {{
+        const w = widths[i];
+        place(r, x + w / 2);
+        x += w;
+      }});
+    }}
+
     function nodeAt(px, py) {{
       const w = toWorld(px, py);
       for (let i = nodes.length - 1; i >= 0; i--) {{
@@ -785,12 +892,13 @@ def graph_shell_html(height: int = 520) -> str:
 
     canvas.addEventListener('mousedown', (ev) => {{
       const p = getPos(ev); const n = nodeAt(p.x, p.y); moved = false;
-      if (n) {{ dragNode = n; alpha = Math.max(alpha, 0.4); }} else {{ panning = true; }}
+      // Nodes snap back to tree slots — drag is for temporary peek only; prefer pan.
+      if (n && ev.shiftKey) {{ dragNode = n; }} else {{ panning = true; }}
       last = p; canvas.classList.add('dragging');
     }});
     canvas.addEventListener('mousemove', (ev) => {{
       const p = getPos(ev);
-      if (dragNode) {{ const w = toWorld(p.x, p.y); dragNode.x = w.x; dragNode.y = w.y; dragNode.vx = 0; dragNode.vy = 0; moved = true; }}
+      if (dragNode) {{ const w = toWorld(p.x, p.y); dragNode.x = w.x; dragNode.y = w.y; moved = true; }}
       else if (panning) {{ panX += p.x - last.x; panY += p.y - last.y; moved = true; }}
       else {{ canvas.style.cursor = nodeAt(p.x, p.y) ? 'pointer' : 'grab'; }}
       last = p;
@@ -806,7 +914,6 @@ def graph_shell_html(height: int = 520) -> str:
           card.classList.add('open');
         }} else {{ selected = null; card.classList.remove('open'); }}
       }}
-      if (dragNode) persist();
       dragNode = null; panning = false; canvas.classList.remove('dragging');
     }});
     canvas.addEventListener('wheel', (ev) => {{
@@ -817,61 +924,65 @@ def graph_shell_html(height: int = 520) -> str:
       panX = p.x - before.x * zoom; panY = p.y - before.y * zoom;
     }}, {{ passive: false }});
 
-    // ── Force layout — Mina model: inverse-square repulsion + springs +
-    //    center gravity + collision relaxation + annealing alpha (looser). ──
+    // ── Top-down tree layout: recompute slots, ease nodes into place. ──
     function tick() {{
-      const N = nodes.length;
-      for (let i = 0; i < N; i++) {{
-        for (let j = i + 1; j < N; j++) {{
-          const a = nodes[i], b = nodes[j];
-          let dx = b.x - a.x, dy = b.y - a.y;
-          let d2 = dx * dx + dy * dy; if (d2 < 1) d2 = 1;
-          const d = Math.sqrt(d2);
-          const force = (5600 * alpha) / d2;
-          dx /= d; dy /= d;
-          if (a !== dragNode && !a.fixed) {{ a.vx -= dx * force; a.vy -= dy * force; }}
-          if (b !== dragNode && !b.fixed) {{ b.vx += dx * force; b.vy += dy * force; }}
-        }}
-      }}
-      edges.forEach(e => {{
-        const a = byId.get(e.source), b = byId.get(e.target);
-        if (!a || !b) return;
-        const ideal = 155;
-        let dx = b.x - a.x, dy = b.y - a.y;
-        const d = Math.max(1, Math.sqrt(dx * dx + dy * dy));
-        const force = ((d - ideal) / d) * 0.045 * alpha;
-        dx *= force; dy *= force;
-        if (!a.fixed && a !== dragNode) {{ a.vx += dx; a.vy += dy; }}
-        if (!b.fixed && b !== dragNode) {{ b.vx -= dx; b.vy -= dy; }}
-      }});
-      const cx = W / 2, cy = H / 2;
+      layoutTree();
       nodes.forEach(n => {{
-        if (n.fixed || n === dragNode) return;
-        n.vx += (cx - n.x) * 0.0042 * alpha;
-        n.vy += (cy - n.y) * 0.0042 * alpha;
-        n.vx *= 0.86; n.vy *= 0.86;
-        n.x += n.vx; n.y += n.vy;
+        if (n === dragNode) return;
+        if (n.tx == null || n.ty == null) return;
+        n.x += (n.tx - n.x) * 0.22;
+        n.y += (n.ty - n.y) * 0.28;
+        if (Math.abs(n.tx - n.x) < 0.15) n.x = n.tx;
+        if (Math.abs(n.ty - n.y) < 0.15) n.y = n.ty;
       }});
-      // Hard collision relaxation so nothing overlaps (with label breathing room).
-      for (let i = 0; i < N; i++) {{
-        for (let j = i + 1; j < N; j++) {{
-          const a = nodes[i], b = nodes[j];
-          const dx = b.x - a.x, dy = b.y - a.y;
-          const min = a.r + b.r + 18;
-          const d = Math.sqrt(dx * dx + dy * dy) || 0.01;
-          if (d < min) {{
-            const push = (min - d) / d;
-            const ox = dx * push * 0.5, oy = dy * push * 0.5;
-            if (a !== dragNode && !a.fixed) {{ a.x -= ox; a.y -= oy; }}
-            if (b !== dragNode && !b.fixed) {{ b.x += ox; b.y += oy; }}
-          }}
-        }}
+      if (fitPending && !cameraLocked) {{
+        const settled = nodes.every(n => n.tx == null || (Math.abs(n.tx - n.x) < 1.5 && Math.abs(n.ty - n.y) < 1.5));
+        if (settled || nodes.length <= 1) {{ fitView({{ topBias: true }}); fitPending = false; }}
+      }} else if (fitPending && cameraLocked) {{
+        fitPending = false;
       }}
-      if (target) {{ target.x = cx; target.y = cy; target.vx = 0; target.vy = 0; }}
-      alpha = Math.max(0.02, alpha * 0.9955);
       for (const n of nodes) saved[n.id] = {{ x: n.x, y: n.y }};
     }}
 
+    function frameIsReady(frame) {{
+      if (!frame || !frame.nodes || !frame.nodes.length) return false;
+      // Prefer locking once the final annotation trunk exists; else a wide citing row.
+      return frame.nodes.some(n => n.kind === 'cluster' || n.kind === 'claim' || n.kind === 'study' || n.kind === 'ingredient')
+        || frame.nodes.filter(n => n.kind === 'citing').length >= 3;
+    }}
+
+    function lockCameraFromFrame(model, force) {{
+      const frame = model && model.frame;
+      const key = (model && model.frameKey) || '';
+      if (!frameIsReady(frame)) return;
+      if (!force && cameraLocked && key && key === lockedFrameKey) return;
+      const prevNodes = nodes.slice();
+      const prevEdges = edges.slice();
+      const prevHidden = new Set(hiddenKinds);
+      nodes.length = 0;
+      byId.clear();
+      (frame.nodes || []).forEach(n => {{
+        const nd = Object.assign({{}}, n, {{ x: 0, y: TOP_Y, tx: 0, ty: TOP_Y }});
+        nodes.push(nd);
+        byId.set(nd.id, nd);
+      }});
+      edges = (frame.edges || []).filter(e => byId.get(e.source) && byId.get(e.target));
+      hiddenKinds.clear();
+      layoutTree();
+      nodes.forEach(n => {{ if (n.tx != null) {{ n.x = n.tx; n.y = n.ty; }} }});
+      fitView({{ topBias: true }});
+      cameraLocked = true;
+      lockedFrameKey = key;
+      fitPending = false;
+      // Restore the live (possibly partial) graph; camera stays put.
+      nodes.length = 0;
+      byId.clear();
+      prevNodes.forEach(n => {{ nodes.push(n); byId.set(n.id, n); }});
+      edges = prevEdges;
+      hiddenKinds.clear();
+      prevHidden.forEach(k => hiddenKinds.add(k));
+    }}
+
     function draw() {{
       tick();
       ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
@@ -963,32 +1074,37 @@ def graph_shell_html(height: int = 520) -> str:
     setTimeout(persist, 900);
 
     // ── Fit / reset view ──
-    function fitView() {{
+    function fitView(opts) {{
+      const topBias = !!(opts && opts.topBias);
       const vis = nodes.filter(isVisible);
       if (!vis.length) return;
       let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
-      vis.forEach(n => {{ minX = Math.min(minX, n.x - n.r); minY = Math.min(minY, n.y - n.r);
-        maxX = Math.max(maxX, n.x + n.r + 20); maxY = Math.max(maxY, n.y + n.r + 20); }});
+      vis.forEach(n => {{
+        const x = n.tx != null ? n.tx : n.x, y = n.ty != null ? n.ty : n.y;
+        minX = Math.min(minX, x - n.r); minY = Math.min(minY, y - n.r);
+        maxX = Math.max(maxX, x + n.r + 20); maxY = Math.max(maxY, y + n.r + 28);
+      }});
       const gw = Math.max(1, maxX - minX), gh = Math.max(1, maxY - minY);
-      zoom = Math.max(0.3, Math.min(1.6, Math.min((W - 40) / gw, (H - 40) / gh)));
+      zoom = Math.max(0.28, Math.min(1.55, Math.min((W - 48) / gw, (H - 56) / gh)));
       panX = W / 2 - ((minX + maxX) / 2) * zoom;
-      panY = H / 2 - ((minY + maxY) / 2) * zoom;
+      panY = topBias ? (28 - minY * zoom) : (H / 2 - ((minY + maxY) / 2) * zoom);
     }}
-    document.getElementById('fitBtn').onclick = fitView;
+    document.getElementById('fitBtn').onclick = () => {{
+      // Manual fit is allowed; keep lock so later step updates still won't auto-zoom.
+      fitView({{ topBias: true }});
+    }};
     document.getElementById('resetBtn').onclick = () => {{
       hiddenKinds.clear(); query = ''; document.getElementById('q').value = '';
       document.getElementById('qClr').style.display = 'none';
       selected = null; card.classList.remove('open');
       try {{ sessionStorage.removeItem(memKey); }} catch (e) {{}}
-      alpha = 1; renderCats();
-      const cx = W / 2, cy = H / 2;
-      nodes.forEach((n, i) => {{
-        const a = (i / Math.max(nodes.length, 1)) * Math.PI * 2;
-        n.x = n.id === 'target' ? cx : cx + Math.cos(a) * (90 + Math.random() * 70);
-        n.y = n.id === 'target' ? cy : cy + Math.sin(a) * (90 + Math.random() * 70);
-        n.vx = 0; n.vy = 0;
-      }});
-      zoom = 0.95; panX = (W / 2) * (1 - zoom); panY = (H / 2) * (1 - zoom);
+      saved = {{}};
+      layoutTree();
+      nodes.forEach(n => {{ if (n.tx != null) {{ n.x = n.tx; n.y = n.ty; }} }});
+      // Re-apply final-frame camera when available; otherwise fit current nodes.
+      if (lastFrameModel) lockCameraFromFrame(lastFrameModel, true);
+      else fitView({{ topBias: true }});
+      renderCats();
     }};
 
     // ── Search ──
@@ -1020,34 +1136,43 @@ def graph_shell_html(height: int = 520) -> str:
           '<span class="cnt">' + (c[k] || 0) + '</span>';
         btn.onclick = () => {{
           if (hiddenKinds.has(k)) hiddenKinds.delete(k); else hiddenKinds.add(k);
-          alpha = Math.max(alpha, 0.3); renderCats();
+          if (!cameraLocked) fitPending = true;
+          renderCats();
         }};
         host.appendChild(btn);
       }});
     }}
-    document.getElementById('allBtn').onclick = () => {{ hiddenKinds.clear(); alpha = Math.max(alpha, 0.3); renderCats(); }};
+    document.getElementById('allBtn').onclick = () => {{
+      hiddenKinds.clear();
+      if (!cameraLocked) fitPending = true;
+      renderCats();
+    }};
     document.getElementById('noneBtn').onclick = () => {{
       Object.keys(counts()).forEach(k => hiddenKinds.add(k)); renderCats();
     }};
     renderCats();
 
-    // ── Incremental model merge (Mina reveal): add new nodes near a neighbor,
-    //    keep existing positions, pulse writes, drop nodes no longer present. ──
+    // ── Incremental model merge: spawn under parent, expand tree downward. ──
     let lastSig = '';
+    let lastFrameModel = null;
     function applyModel(model) {{
       if (!model) return;
+      if (model.kindMeta) Object.assign(KM, model.kindMeta);
+      if (model.kindOrder) payload.kindOrder = model.kindOrder;
+      if (model.frame) lastFrameModel = {{ frame: model.frame, frameKey: model.frameKey || '' }};
+      // Lock zoom/pan to the final tree before merging visible nodes.
+      lockCameraFromFrame(model);
+
       const inNodes = model.nodes || [];
       const inEdges = model.edges || [];
       const sig = inNodes.map(n => n.id + (n.pulse ? '*' : '')).join(',') + '|' + inEdges.map(e => e.id).join(',');
       if (sig === lastSig) return;
       lastSig = sig;
-      if (model.kindMeta) Object.assign(KM, model.kindMeta);
-      if (model.kindOrder) payload.kindOrder = model.kindOrder;
       const incIds = new Set(inNodes.map(n => n.id));
-      const adj = {{}};
-      inEdges.forEach(e => {{ (adj[e.source] = adj[e.source] || []).push(e.target); (adj[e.target] = adj[e.target] || []).push(e.source); }});
       const pN = new Set(), pE = new Set();
       let added = false;
+      // Edges first so parent lookups work while spawning.
+      const pendingEdges = inEdges.map(e => Object.assign({{}}, e));
       inNodes.forEach(n => {{
         let nd = byId.get(n.id);
         if (nd) {{
@@ -1055,28 +1180,46 @@ def graph_shell_html(height: int = 520) -> str:
           nd.text = n.text; nd.r = n.r; nd.typeLabel = n.typeLabel; nd.fullTitle = n.fullTitle; nd.detail = n.detail;
           if (n.pulse) pN.add(n.id);
         }} else {{
+          // Temporary register for parent resolution against in-flight nodes.
+          nd = Object.assign({{}}, n, {{ x: 0, y: TOP_Y, tx: 0, ty: TOP_Y }});
+          nodes.push(nd); byId.set(n.id, nd);
+          let x = 0, y = TOP_Y;
           const prev = saved[n.id];
-          let x, y;
+          const parent = (() => {{
+            let best = null, bestLvl = -Infinity;
+            for (const e of pendingEdges) {{
+              if (e.target !== n.id) continue;
+              const p = byId.get(e.source);
+              if (!p) continue;
+              const pl = levelOf(p);
+              if (pl < levelOf(nd) && pl >= bestLvl) {{ best = p; bestLvl = pl; }}
+            }}
+            return best || byId.get('target');
+          }})();
           if (prev) {{ x = prev.x; y = prev.y; }}
-          else {{
-            const nb = (adj[n.id] || []).map(id => byId.get(id)).find(Boolean);
-            const base = nb ? {{ x: nb.x, y: nb.y }} : {{ x: W / 2, y: H / 2 }};
-            const a = Math.random() * Math.PI * 2, rr = 70 + Math.random() * 60;
-            x = base.x + Math.cos(a) * rr; y = base.y + Math.sin(a) * rr;
+          else if (parent) {{
+            x = parent.x;
+            y = parent.y + Math.max(36, (levelOf(nd) - levelOf(parent)) * ROW_GAP * 0.55);
+          }} else {{
+            x = 0; y = TOP_Y;
           }}
-          nd = Object.assign({{}}, n, {{ x, y, vx: 0, vy: 0, fixed: n.id === 'target' }});
-          nodes.push(nd); byId.set(n.id, nd); added = true; pN.add(n.id);
+          nd.x = x; nd.y = y; nd.tx = x; nd.ty = y;
+          added = true; pN.add(n.id);
         }}
       }});
       for (let i = nodes.length - 1; i >= 0; i--) {{
         if (!incIds.has(nodes[i].id)) {{ byId.delete(nodes[i].id); nodes.splice(i, 1); }}
       }}
-      edges = inEdges.filter(e => byId.get(e.source) && byId.get(e.target)).map(e => Object.assign({{}}, e));
+      edges = pendingEdges.filter(e => byId.get(e.source) && byId.get(e.target));
       edges.forEach(e => {{ if (e.pulse) pE.add(e.id); }});
       pulseNodeIds = pN; pulseEdgeIds = pE;
-      if (pN.size || pE.size || added) {{ pulseStart = performance.now(); alpha = Math.max(alpha, 0.55); }}
-      target = byId.get('target'); if (target) target.fixed = true;
+      if (pN.size || pE.size || added) {{ pulseStart = performance.now(); }}
+      target = byId.get('target');
+      layoutTree();
+      // Only auto-fit before the final-frame camera is locked.
+      if (!cameraLocked && (added || pN.size)) fitPending = true;
       renderCats();
+      persist();
     }}
     window.addEventListener('message', (e) => {{
       const d = e.data;
@@ -1157,11 +1300,24 @@ def build_synced_model(
         visible_step=visible,
         pulse_step=pulse,
     )
-    return sync_and_load_graph(run_id or "default", model)
+    # Final tree used only to lock camera zoom/pan from the first reveal.
+    frame = build_graph_model(
+        paper_dir=paper_dir,
+        payload=payload,
+        visible_step=8,
+        pulse_step=0,
+    )
+    model["frame"] = {"nodes": frame.get("nodes") or [], "edges": frame.get("edges") or []}
+    model["frame_key"] = run_id or "default"
+    synced = sync_and_load_graph(run_id or "default", model)
+    # Keep frame on the payload even if Neo4j sync rewrites node chrome.
+    synced["frame"] = model["frame"]
+    synced["frame_key"] = model["frame_key"]
+    return synced
 
 
 def render_graph_shell(placeholder, *, height: int = 520) -> None:
-    """Mount the persistent, model-free canvas shell (constant HTML → no remount)."""
+    """Mount the canvas shell. Streamlit 1.60+ embeds HTML strings via srcdoc."""
     html = graph_shell_html(height)
     if placeholder is None:
         st.iframe(html, height=height)