feat(#133): spinner + precise error + retry for the catalog data grid

The data tab loads the Buckaroo grid lazily: a spinner while the session resolves, the grid on success, and on timeout/error a panel with the reason, a retry button, and a pointer to buckaroo.log / the debug-tallyman skill. Metadata and code render immediately instead of blocking on Buckaroo.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: paddymul

packages/app/src/api.ts

@@ -3,6 +3,7 @@ import type {
   AppError,
   EntryDetail,
   EntryCache,
+  SessionResult,
   NotebookFull,
   DiffData,
   ResultCache,
@@ -124,7 +125,7 @@ export const api = {
       return r.json() as Promise<{ project: string; cleared: number }>;
     }),
 
-  session: (project: string, hash: string): Promise<{ ws_url: string | null }> =>
+  session: (project: string, hash: string): Promise<SessionResult> =>
     get(`/${project}/api/session/${hash}`),
 
   resultCache: (project: string): Promise<ResultCache> =>

packages/app/src/pages/CatalogPage.tsx

@@ -6,7 +6,7 @@ import { recalcTarget } from "../recalcRefresh";
 import { CatalogSidebar } from "../components/CatalogSidebar";
 import { BuckarooEmbed } from "../components/BuckarooEmbed";
 import { VegaChart } from "../components/VegaChart";
-import type { Entry, AppError, EntryDetail, EntryCache } from "../types";
+import type { Entry, AppError, EntryDetail, EntryCache, SessionResult } from "../types";
 
 // ── Error banner ──────────────────────────────────────────────────────────────
 
@@ -91,11 +91,16 @@ function EntryDetailPane({ project, hash }: { project: string; hash: string }) {
       .catch(() => setLoading(false));
   }, [project, hash]);
 
-  if (loading) return <div className="meta">loading…</div>;
+  if (loading)
+    return (
+      <div className="spinner-row">
+        <span className="spinner" /> loading…
+      </div>
+    );
   if (!detail) return <div className="meta">entry not found</div>;
 
   const { manifest, alias, version, forensic_history, prompt_history, chart_spec,
-    display_config, build_artifacts, total_rows, buckaroo_session, buckaroo_ws_base, code } = detail;
+    display_config, build_artifacts, total_rows, code } = detail;
   const diffProvenance = display_config?.diff_provenance;
 
   const handleSaveCode = async () => {
@@ -109,9 +114,6 @@ function EntryDetailPane({ project, hash }: { project: string; hash: string }) {
     }
   };
 
-  const wsUrl =
-    buckaroo_session && buckaroo_ws_base ? `${buckaroo_ws_base}/ws/${buckaroo_session}` : null;
-
   return (
     <div className="detail entry-detail">
       <div className="entry-header">
@@ -234,15 +236,7 @@ function EntryDetailPane({ project, hash }: { project: string; hash: string }) {
             {" "}matched
           </div>
         )}
-        {wsUrl ? (
-          <BuckarooEmbed wsUrl={wsUrl} className="buckaroo-embed" />
-        ) : (
-          <div className="meta">
-            {total_rows > 0
-              ? `${total_rows} rows (Buckaroo not available — run tallyman with --buckaroo)`
-              : "no rows"}
-          </div>
-        )}
+        <BuckarooDataPane project={project} hash={manifest.content_hash} totalRows={total_rows} />
       </div>
 
       {tab === "code" && (
@@ -306,6 +300,85 @@ function EntryDetailPane({ project, hash }: { project: string; hash: string }) {
   );
 }
 
+// ── Lazy Buckaroo grid: spinner → grid, or a precise error + retry (#133) ─────
+
+function BuckarooDataPane({ project, hash, totalRows }: { project: string; hash: string; totalRows: number }) {
+  const [result, setResult] = useState<SessionResult | null>(null);
+  const [attempt, setAttempt] = useState(0);
+
+  useEffect(() => {
+    let cancelled = false;
+    setResult(null);
+    api
+      .session(project, hash)
+      .then((d) => {
+        if (!cancelled) setResult(d);
+      })
+      .catch((e) => {
+        if (!cancelled)
+          setResult({ status: "error", ws_url: null, detail: e instanceof Error ? e.message : String(e) });
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [project, hash, attempt]);
+
+  if (result === null) {
+    return (
+      <div className="buckaroo-loading">
+        <span className="spinner" /> loading data…
+      </div>
+    );
+  }
+  if (result.status === "ok" && result.ws_url) {
+    return <BuckarooEmbed wsUrl={result.ws_url} className="buckaroo-embed" />;
+  }
+
+  const retry = () => setAttempt((n) => n + 1);
+
+  if (result.status === "unavailable" || result.status === "no_build") {
+    return (
+      <div className="meta">
+        {result.status === "no_build"
+          ? "no build for this entry"
+          : totalRows > 0
+            ? `${totalRows} rows (Buckaroo not available — run tallyman with --buckaroo)`
+            : "no rows"}
+        {result.status === "unavailable" && (
+          <>
+            {" · "}
+            <button type="button" className="link-btn" onClick={retry}>
+              retry
+            </button>
+          </>
+        )}
+      </div>
+    );
+  }
+
+  // timeout | error — surface what went wrong and a way out.
+  return (
+    <div className="buckaroo-error">
+      <strong>
+        {result.status === "timeout"
+          ? "Buckaroo timed out loading this entry."
+          : "Buckaroo couldn’t load this entry."}
+      </strong>
+      {result.detail && <div className="meta detail">{result.detail}</div>}
+      <div className="meta">
+        <button type="button" className="link-btn" onClick={retry}>
+          retry
+        </button>
+        {" · to debug, check "}
+        <code>~/.tallyman-notebooks/projects/{project}/buckaroo.log</code>
+        {" and the companion log, or run the "}
+        <code>debug-tallyman</code>
+        {" skill."}
+      </div>
+    </div>
+  );
+}
+
 // ── Per-expression cache footprint (metadata tab) ─────────────────────────────
 
 function ShareBar({ value, total }: { value: number; total: number }) {

packages/app/src/styles.css

@@ -534,6 +534,16 @@ table.cache-table .muted { color: var(--muted); }
 .danger-btn:hover:not(:disabled) { background: #7a2525; }
 .danger-btn:disabled { opacity: 0.4; cursor: default; }
 
+/* loading spinner + lazy Buckaroo grid states (#133) */
+@keyframes tm-spin { to { transform: rotate(360deg); } }
+.spinner { display: inline-block; width: 14px; height: 14px; border: 2px solid var(--line); border-top-color: var(--accent); border-radius: 50%; animation: tm-spin 0.7s linear infinite; vertical-align: -2px; }
+.spinner-row { color: var(--muted); display: flex; align-items: center; gap: 8px; padding: 8px 0; }
+.buckaroo-loading { color: var(--muted); display: flex; align-items: center; gap: 8px; min-height: 120px; }
+.buckaroo-error { background: #3a1e1e; border: 1px solid #7a3a3a; border-radius: 4px; padding: 12px; color: #ffd9d9; }
+.buckaroo-error .detail { color: #e8b4b8; margin: 4px 0; white-space: pre-wrap; }
+.buckaroo-error code { background: rgba(0, 0, 0, 0.25); padding: 1px 4px; border-radius: 3px; }
+.link-btn { background: none; border: none; color: var(--accent); cursor: pointer; font: inherit; padding: 0; text-decoration: underline; }
+
 /* per-expression cache metadata tab */
 .cache-meta { padding: 2px; }
 .cache-meta .cache-detail { font-size: 11px; white-space: normal; max-width: 420px; }

packages/app/src/types.ts

@@ -187,6 +187,12 @@ export interface EntryCache {
   total_formatted: string;
 }
 
+export interface SessionResult {
+  status: "ok" | "unavailable" | "no_build" | "timeout" | "error";
+  ws_url: string | null;
+  detail: string;
+}
+
 export interface Projects {
   active: string | null;
   available: string[];