@session-link/viewer 0.1.0 → 0.2.1

package/RunViewer.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useEffect, useMemo, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import {
   Bot,
   Braces,
@@ -711,7 +711,9 @@ function TreeRow({
     <div
       id={`rv-row-${span.id}`}
       role="button"
-      tabIndex={0}
+      // Not a tab stop: the scroll container is the single keyboard surface,
+      // so focus can never strand on a row that scrolls out of the window.
+      tabIndex={-1}
       title={
         span.started_at
           ? `${spanLabel(span)} · ${new Date(span.started_at).toLocaleTimeString()}${Number.isFinite(dur) ? ` · ${fmtDur(dur)}` : ""}`
@@ -729,7 +731,8 @@ function TreeRow({
         display: "flex",
         alignItems: "center",
         gap: 6,
-        padding: "7px 12px 7px 0",
+        height: ROW_H,
+        padding: "0 12px 0 0",
         paddingLeft: 10 + depth * 14,
         cursor: "pointer",
         background: selected ? "rgba(14,111,92,0.08)" : "transparent",
@@ -739,6 +742,9 @@ function TreeRow({
       {hasKids ? (
         <button
           aria-label={open ? "Collapse" : "Expand"}
+          // Not a tab stop — a focused chevron unmounting with its windowed
+          // row would strand focus; the scroll container is the tab stop.
+          tabIndex={-1}
           onClick={(e) => {
             e.stopPropagation();
             onToggle();
@@ -830,23 +836,307 @@ function TreeRow({
 
 /* ------------------------------------------------------------- component */
 
-export function RunViewer({ run }: { run: Run }) {
+/**
+ * Renders a session/v0 document. Two ways in:
+ *   run — the parsed document, inlined by the caller (local `slink open`,
+ *         bundled examples, small sessions).
+ *   src — a URL to fetch it from. The hosted site uses this for big
+ *         sessions so the run's bytes travel once, gzipped, instead of
+ *         being serialized into both the SSR markup and the hydration
+ *         payload (an 11.8MB run made a 17.6MB page that way).
+ */
+export function RunViewer({ run, src }: { run?: Run; src?: string }) {
+  const [fetched, setFetched] = useState<Run | null>(null);
+  const [loadError, setLoadError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (run || !src) return;
+    // A changed src must never show the previous run or a stale error.
+    setFetched(null);
+    setLoadError(null);
+    let alive = true;
+    fetch(src)
+      .then(async (r) => {
+        if (!r.ok) throw new Error(`the server answered ${r.status}`);
+        return (await r.json()) as Run;
+      })
+      .then((data) => {
+        if (alive) setFetched(data);
+      })
+      .catch((e: unknown) => {
+        if (alive) setLoadError(e instanceof Error ? e.message : String(e));
+      });
+    return () => {
+      alive = false;
+    };
+  }, [run, src]);
+
+  const resolved = run ?? fetched;
+  if (!resolved) {
+    return (
+      <div
+        className="rv"
+        style={{
+          fontFamily: T.mono,
+          fontSize: 12,
+          color: loadError ? T.error : T.faint,
+          border: `1px solid ${T.line}`,
+          borderRadius: 10,
+          background: T.panel,
+          padding: "48px 24px",
+          textAlign: "center",
+        }}
+      >
+        {loadError ? (
+          <>
+            couldn&apos;t load this session — {loadError}
+            {src && (
+              <>
+                {" · "}
+                <a href={src} style={{ color: T.ink }}>
+                  raw JSON
+                </a>
+              </>
+            )}
+          </>
+        ) : (
+          "loading session…"
+        )}
+      </div>
+    );
+  }
+  return <LoadedViewer run={resolved} />;
+}
+
+/** Every visible tree row is exactly this tall — the invariant the
+ *  windowing math depends on, enforced by an explicit height on the row. */
+const ROW_H = 30;
+const OVERSCAN = 12;
+/** The list's cosmetic top padding — rows sit at PAD_TOP + i*ROW_H in
+ *  content coordinates, so every scroll computation must include it. */
+const PAD_TOP = 6;
+
+/**
+ * The left column: header, counts, and the windowed span list. Scroll state
+ * lives HERE on purpose — a scroll frame re-renders these ~40 rows and
+ * never the span-detail panel next door.
+ */
+function TreeColumn({
+  idx,
+  sel,
+  closed,
+  onSelect,
+  onSetClosed,
+}: {
+  idx: RunIndex;
+  sel: string | null;
+  closed: Set<string>;
+  onSelect: (id: string) => void;
+  onSetClosed: React.Dispatch<React.SetStateAction<Set<string>>>;
+}) {
+  /* The visible tree, flattened. Thousands of rows are normal for real
+     agent traces, so only the window around the scroll position mounts —
+     this array is cheap (plain objects), the DOM is what's rationed. */
+  const rows = useMemo(() => {
+    const out: Array<{ span: Span; depth: number }> = [];
+    const walk = (list: Span[], depth: number) => {
+      for (const s of list) {
+        out.push({ span: s, depth });
+        if (!closed.has(s.id)) walk(idx.children.get(s.id) ?? [], depth + 1);
+      }
+    };
+    walk(idx.roots, 0);
+    return out;
+  }, [idx, closed]);
+
+  const treeRef = useRef<HTMLDivElement | null>(null);
+  const [scrollTop, setScrollTop] = useState(0);
+  const [viewH, setViewH] = useState(760);
+  useEffect(() => {
+    const el = treeRef.current;
+    if (!el || typeof ResizeObserver === "undefined") return;
+    const update = () => setViewH(el.clientHeight || 760);
+    update();
+    const ro = new ResizeObserver(update);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+
+  /* Scroll a row index into the window — the windowed replacement for
+     scrollIntoView, which can't target a row that isn't mounted. */
+  const ensureVisible = (i: number) => {
+    const el = treeRef.current;
+    if (!el || i < 0) return;
+    const top = PAD_TOP + i * ROW_H;
+    if (top < el.scrollTop) el.scrollTop = top;
+    else if (top + ROW_H > el.scrollTop + el.clientHeight)
+      el.scrollTop = top + ROW_H - el.clientHeight;
+  };
+
+  /* Scroll to the selection only when the SELECTION changes (deep link,
+     keyboard, click) — never when rows change identity, or expanding a
+     chevron 800 rows away from the selection would yank the viewport back
+     to it. No-op when already visible or hidden under a collapsed parent. */
+  const lastSel = useRef<string | null>(null);
+  useEffect(() => {
+    if (sel === lastSel.current) return;
+    lastSel.current = sel;
+    ensureVisible(rows.findIndex((r) => r.span.id === sel));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [sel, rows]);
+
+  const { typeCounts, errorCount } = useMemo(() => {
+    const counts: Array<[string, number]> = [];
+    let errors = 0;
+    for (const s of idx.byId.values()) {
+      if (s.status === "error") errors++;
+      const entry = counts.find(([t]) => t === s.type);
+      if (entry) entry[1]++;
+      else counts.push([s.type, 1]);
+    }
+    return { typeCounts: counts, errorCount: errors };
+  }, [idx]);
+
+  /* keyboard: ↑/↓ move through visible rows, ←/→ collapse/expand. The
+     handler lives on the scroll container (which is focusable — a focused
+     row can unmount when it scrolls out of the window). */
+  const onTreeKey = (e: React.KeyboardEvent) => {
+    if (e.key === "ArrowDown" || e.key === "ArrowUp") {
+      e.preventDefault();
+      const at = rows.findIndex((r) => r.span.id === sel);
+      // Selection hidden under a collapsed ancestor: don't teleport to row 0.
+      if (at === -1) return;
+      const ni = Math.min(rows.length - 1, Math.max(0, at + (e.key === "ArrowDown" ? 1 : -1)));
+      const next = rows[ni];
+      if (next) {
+        onSelect(next.span.id);
+        ensureVisible(ni);
+        treeRef.current?.focus({ preventScroll: true });
+      }
+    } else if ((e.key === "ArrowRight" || e.key === "ArrowLeft") && sel) {
+      e.preventDefault();
+      onSetClosed((prev) => {
+        const next = new Set(prev);
+        if (e.key === "ArrowRight") next.delete(sel);
+        else next.add(sel);
+        return next;
+      });
+    }
+  };
+
+  /* the window: which slice of rows is actually in the DOM. scrollTop is
+     clamped so rows shrinking under a deep scroll (collapse-all) can't
+     produce an empty slice while the browser catches up. */
+  const top = Math.min(scrollTop, Math.max(0, rows.length * ROW_H - viewH));
+  const first = Math.max(0, Math.floor((top - PAD_TOP) / ROW_H) - OVERSCAN);
+  const last = Math.min(rows.length, Math.ceil((top - PAD_TOP + viewH) / ROW_H) + OVERSCAN);
+
+  return (
+    <div className="rv-tree">
+      <div
+        style={{
+          display: "flex",
+          justifyContent: "space-between",
+          alignItems: "baseline",
+          padding: "12px 12px 8px",
+          borderBottom: `1px solid ${T.line}`,
+        }}
+      >
+        <Eyebrow>trace</Eyebrow>
+        <span
+          style={{
+            display: "inline-flex",
+            alignItems: "center",
+            gap: 10,
+            fontFamily: T.mono,
+            fontSize: 11,
+            color: T.faint,
+          }}
+        >
+          {typeCounts.map(([type, n]) => (
+            <span
+              key={type}
+              title={`${n} ${type} span${n === 1 ? "" : "s"}`}
+              style={{ display: "inline-flex", alignItems: "center", gap: 4 }}
+            >
+              <span
+                style={{
+                  width: 7,
+                  height: 7,
+                  borderRadius: 2,
+                  background: HUES[type] ?? HUES.custom,
+                }}
+              />
+              {n}
+            </span>
+          ))}
+          {errorCount > 0 && (
+            <span style={{ color: T.error, fontWeight: 600 }} title={`${errorCount} error span${errorCount === 1 ? "" : "s"}`}>
+              {errorCount} err
+            </span>
+          )}
+        </span>
+      </div>
+      {/* Windowed: rows are fixed-height, so visibility is arithmetic.
+          A spacer keeps the scrollbar honest; only [first, last) mount. */}
+      <div
+        ref={treeRef}
+        tabIndex={0}
+        aria-label="Trace spans"
+        onKeyDown={onTreeKey}
+        onScroll={(e) => setScrollTop(e.currentTarget.scrollTop)}
+        style={{ padding: `${PAD_TOP}px 0`, overflowY: "auto", maxHeight: "min(72vh, 760px)" }}
+      >
+        <div style={{ height: rows.length * ROW_H, position: "relative" }}>
+          <div style={{ position: "absolute", top: first * ROW_H, left: 0, right: 0 }}>
+            {rows.slice(first, last).map(({ span, depth }) => (
+              <TreeRow
+                key={span.id}
+                span={span}
+                depth={depth}
+                idx={idx}
+                selected={sel === span.id}
+                hasKids={(idx.children.get(span.id) ?? []).length > 0}
+                open={!closed.has(span.id)}
+                onToggle={() => {
+                  onSetClosed((prev) => {
+                    const next = new Set(prev);
+                    if (next.has(span.id)) next.delete(span.id);
+                    else next.add(span.id);
+                    return next;
+                  });
+                  // Keep focus on the keyboard surface: a click focuses the
+                  // row/chevron, which may unmount when it scrolls out of
+                  // the window — stranding focus on <body> and killing
+                  // arrow-key nav.
+                  treeRef.current?.focus({ preventScroll: true });
+                }}
+                onSelect={() => {
+                  onSelect(span.id);
+                  treeRef.current?.focus({ preventScroll: true });
+                }}
+              />
+            ))}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function LoadedViewer({ run }: { run: Run }) {
   const idx = useMemo(() => indexRun(run), [run]);
   const [sel, setSel] = useState<string | null>(idx.roots[0]?.id ?? null);
   const [closed, setClosed] = useState<Set<string>>(new Set());
   const [raw, setRaw] = useState(false);
   const [copied, setCopied] = useState(false);
 
-  /* deep link: read #span=<id> on mount, write it on select */
+  /* deep link: read #span=<id> on mount, write it on select. TreeColumn's
+     selection effect scrolls it into the window once it renders. */
   useEffect(() => {
     try {
       const m = window.location.hash.match(/span=([\w.-]+)/);
-      if (m && idx.byId.has(m[1])) {
-        setSel(m[1]);
-        document
-          .getElementById(`rv-row-${m[1]}`)
-          ?.scrollIntoView({ block: "nearest" });
-      }
+      if (m && idx.byId.has(m[1])) setSel(m[1]);
     } catch {
       /* sandboxed embeds may not expose location — fine */
     }
@@ -877,54 +1167,9 @@ export function RunViewer({ run }: { run: Run }) {
     window.setTimeout(() => setCopied(false), 1400);
   };
 
-  const rows: Array<{ span: Span; depth: number }> = [];
-  const walk = (list: Span[], depth: number) => {
-    for (const s of list) {
-      rows.push({ span: s, depth });
-      if (!closed.has(s.id)) walk(idx.children.get(s.id) ?? [], depth + 1);
-    }
-  };
-  walk(idx.roots, 0);
-
   const selected = sel ? idx.byId.get(sel) : undefined;
   const created = new Date(run.created_at);
 
-  const typeCounts: Array<[string, number]> = [];
-  let errorCount = 0;
-  for (const s of run.spans) {
-    if (s.status === "error") errorCount++;
-    const entry = typeCounts.find(([t]) => t === s.type);
-    if (entry) entry[1]++;
-    else typeCounts.push([s.type, 1]);
-  }
-
-  /* keyboard: ↑/↓ move through visible rows, ←/→ collapse/expand. The
-     handler lives on the rows container so it fires while a row has focus. */
-  const onTreeKey = (e: React.KeyboardEvent) => {
-    if (e.key === "ArrowDown" || e.key === "ArrowUp") {
-      e.preventDefault();
-      const at = rows.findIndex((r) => r.span.id === sel);
-      const next =
-        rows[
-          Math.min(rows.length - 1, Math.max(0, at + (e.key === "ArrowDown" ? 1 : -1)))
-        ];
-      if (next) {
-        select(next.span.id);
-        const el = document.getElementById(`rv-row-${next.span.id}`);
-        el?.scrollIntoView({ block: "nearest" });
-        el?.focus();
-      }
-    } else if ((e.key === "ArrowRight" || e.key === "ArrowLeft") && sel) {
-      e.preventDefault();
-      setClosed((prev) => {
-        const next = new Set(prev);
-        if (e.key === "ArrowRight") next.delete(sel);
-        else next.add(sel);
-        return next;
-      });
-    }
-  };
-
   return (
     <div className="rv" style={{ fontFamily: T.sans, color: T.ink }}>
       <style>{`
@@ -1031,79 +1276,13 @@ export function RunViewer({ run }: { run: Run }) {
 
       {/* ---------------------------------------------------- two panels */}
       <div className="rv-cols">
-        <div className="rv-tree">
-          <div
-            style={{
-              display: "flex",
-              justifyContent: "space-between",
-              alignItems: "baseline",
-              padding: "12px 12px 8px",
-              borderBottom: `1px solid ${T.line}`,
-            }}
-          >
-            <Eyebrow>trace</Eyebrow>
-            <span
-              style={{
-                display: "inline-flex",
-                alignItems: "center",
-                gap: 10,
-                fontFamily: T.mono,
-                fontSize: 11,
-                color: T.faint,
-              }}
-            >
-              {typeCounts.map(([type, n]) => (
-                <span
-                  key={type}
-                  title={`${n} ${type} span${n === 1 ? "" : "s"}`}
-                  style={{ display: "inline-flex", alignItems: "center", gap: 4 }}
-                >
-                  <span
-                    style={{
-                      width: 7,
-                      height: 7,
-                      borderRadius: 2,
-                      background: HUES[type] ?? HUES.custom,
-                    }}
-                  />
-                  {n}
-                </span>
-              ))}
-              {errorCount > 0 && (
-                <span style={{ color: T.error, fontWeight: 600 }} title={`${errorCount} error span${errorCount === 1 ? "" : "s"}`}>
-                  {errorCount} err
-                </span>
-              )}
-            </span>
-          </div>
-          {/* NOTE: virtualize this list (e.g. react-virtuoso) before real
-              agent traces arrive — thousands of rows are normal. */}
-          <div
-            onKeyDown={onTreeKey}
-            style={{ padding: "6px 0", overflowY: "auto", maxHeight: "min(72vh, 760px)" }}
-          >
-            {rows.map(({ span, depth }) => (
-              <TreeRow
-                key={span.id}
-                span={span}
-                depth={depth}
-                idx={idx}
-                selected={sel === span.id}
-                hasKids={(idx.children.get(span.id) ?? []).length > 0}
-                open={!closed.has(span.id)}
-                onToggle={() =>
-                  setClosed((prev) => {
-                    const next = new Set(prev);
-                    if (next.has(span.id)) next.delete(span.id);
-                    else next.add(span.id);
-                    return next;
-                  })
-                }
-                onSelect={() => select(span.id)}
-              />
-            ))}
-          </div>
-        </div>
+        <TreeColumn
+          idx={idx}
+          sel={sel}
+          closed={closed}
+          onSelect={select}
+          onSetClosed={setClosed}
+        />
 
         <div style={{ flex: 1, minWidth: 0, padding: "16px 20px 24px" }}>
           {selected ? (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@session-link/viewer",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "The session.link viewer — renders a session/v0 document as an interactive trace tree. React component; consume with a bundler that transpiles the package (e.g. Next transpilePackages).",
   "homepage": "https://session.link",
   "license": "MIT",