feat(spa): no-stats preview grid + elapsed timer while the buckaroo grid loads

While BuckarooDataPane waits on the WS session, fetch the first 200 rows from the data endpoint and render them in buckaroo's static DFViewer with summary_stats_data omitted, so the wait shows real rows instead of a bare spinner. An elapsed-seconds counter on the loading line makes a slow materialise read as progress, not a hang. Swaps to the live BuckarooEmbed once ws_url is ready; a preview miss (e.g. data endpoint 500) degrades silently to the spinner+timer.

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

Author: paddymul

packages/app/src/api.ts

@@ -5,6 +5,7 @@ import type {
   EntryCache,
   ActivityLog,
   SessionResult,
+  DataPage,
   NotebookFull,
   DiffData,
   ResultCache,
@@ -141,6 +142,9 @@ export const api = {
   session: (project: string, hash: string): Promise<SessionResult> =>
     get(`/${project}/api/session/${hash}`),
 
+  data: (project: string, hash: string, limit = 200): Promise<DataPage> =>
+    get(`/${project}/api/data/${hash}?limit=${limit}`),
+
   resultCache: (project: string): Promise<ResultCache> =>
     get(`/${project}/api/result_cache`),
 

packages/app/src/components/BuckarooEmbed.tsx

@@ -1,7 +1,9 @@
 import { useEffect, useRef, useState } from "react";
-import { BuckarooServerView } from "buckaroo-js-core";
+import { BuckarooServerView, DFViewer } from "buckaroo-js-core";
 import "buckaroo-js-core/style.css";
 import { api } from "../api";
+import type { CellValue } from "../types";
+import { buildPreviewConfig, columnsFromRows } from "../previewGrid";
 
 interface Props {
   wsUrl: string;
@@ -22,6 +24,18 @@ export function BuckarooEmbed({ wsUrl, autoHeight, className = "buckaroo-embed",
   );
 }
 
+/**
+ * Static, no-summary-stats grid rendered straight from a page of rows (the data
+ * endpoint), used as a fast preview while the live WS-backed session loads.
+ * Omitting `summary_stats_data` is what makes it a no-stats view. Returns null
+ * for an empty page so the caller can fall back to a plain spinner.
+ */
+export function PreviewGrid({ rows }: { rows: Record<string, CellValue>[] }) {
+  const columns = columnsFromRows(rows);
+  if (!columns.length) return null;
+  return <DFViewer df_data={rows} df_viewer_config={buildPreviewConfig(columns)} />;
+}
+
 interface LazyProps {
   hash: string;
   project: string;

packages/app/src/pages/CatalogPage.tsx

@@ -4,10 +4,10 @@ import { api } from "../api";
 import { useSSE } from "../SSEContext";
 import { recalcTarget } from "../recalcRefresh";
 import { CatalogSidebar } from "../components/CatalogSidebar";
-import { BuckarooEmbed } from "../components/BuckarooEmbed";
+import { BuckarooEmbed, PreviewGrid } from "../components/BuckarooEmbed";
 import { VegaChart } from "../components/VegaChart";
 import { linkifyRefs } from "../codeLinks";
-import type { Entry, AppError, EntryDetail, EntryCache, SessionResult } from "../types";
+import type { Entry, AppError, EntryDetail, EntryCache, SessionResult, CellValue } from "../types";
 
 // ── Error banner ──────────────────────────────────────────────────────────────
 
@@ -353,11 +353,25 @@ function CodeWithLinks({
 
 function BuckarooDataPane({ project, hash, totalRows }: { project: string; hash: string; totalRows: number }) {
   const [result, setResult] = useState<SessionResult | null>(null);
+  const [preview, setPreview] = useState<Record<string, CellValue>[] | null>(null);
+  const [elapsed, setElapsed] = useState(0);
   const [attempt, setAttempt] = useState(0);
 
   useEffect(() => {
     let cancelled = false;
     setResult(null);
+    setPreview(null);
+    // Fill the wait with a quick, no-summary-stats peek at the first rows read
+    // straight off the baked snapshot, while the live WS session spins up in
+    // parallel. Best-effort: a preview miss just leaves the bare spinner.
+    api
+      .data(project, hash, 200)
+      .then((d) => {
+        if (!cancelled) setPreview(d.data);
+      })
+      .catch(() => {
+        /* preview is optional */
+      });
     api
       .session(project, hash)
       .then((d) => {
@@ -372,10 +386,30 @@ function BuckarooDataPane({ project, hash, totalRows }: { project: string; hash:
     };
   }, [project, hash, attempt]);
 
+  // Count up while the session loads so a slow materialise reads as progress,
+  // not a hang. performance.now keeps it monotonic across wall-clock changes.
+  useEffect(() => {
+    if (result !== null) return;
+    const start = performance.now();
+    const id = window.setInterval(() => setElapsed((performance.now() - start) / 1000), 100);
+    return () => window.clearInterval(id);
+  }, [result, attempt]);
+
   if (result === null) {
+    const hasPreview = preview !== null && preview.length > 0;
     return (
-      <div className="buckaroo-loading">
-        <span className="spinner" /> loading data…
+      <div className="buckaroo-loading-wrap">
+        <div className="buckaroo-loading">
+          <span className="spinner" /> loading data… {elapsed.toFixed(1)}s
+          {hasPreview && (
+            <span className="meta"> · preview, no summary stats — first {preview!.length} rows</span>
+          )}
+        </div>
+        {hasPreview && (
+          <div className="buckaroo-preview">
+            <PreviewGrid rows={preview!} />
+          </div>
+        )}
       </div>
     );
   }

packages/app/src/previewGrid.ts

@@ -0,0 +1,35 @@
+// Minimal Buckaroo DFViewer config for the no-summary-stats preview grid shown
+// while the live (WS-backed) session spins up. Every column gets the generic
+// "obj" displayer: the preview is a quick peek at the first rows off the baked
+// snapshot, not the typed/formatted view with summary stats that the real
+// BuckarooServerView delivers once it connects.
+import type { CellValue } from "./types";
+
+export interface PreviewColumnConfig {
+  col_name: string;
+  header_name: string;
+  displayer_args: { displayer: "obj" };
+}
+
+export interface PreviewViewerConfig {
+  pinned_rows: never[];
+  left_col_configs: never[];
+  column_config: PreviewColumnConfig[];
+}
+
+/** Column names from the first row, or [] when there are no rows. */
+export function columnsFromRows(rows: Record<string, CellValue>[]): string[] {
+  return rows.length ? Object.keys(rows[0]) : [];
+}
+
+export function buildPreviewConfig(columns: string[]): PreviewViewerConfig {
+  return {
+    pinned_rows: [],
+    left_col_configs: [],
+    column_config: columns.map((col_name) => ({
+      col_name,
+      header_name: col_name,
+      displayer_args: { displayer: "obj" },
+    })),
+  };
+}

packages/app/src/styles.css

@@ -538,7 +538,9 @@ table.cache-table .muted { color: var(--muted); }
 @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-loading { color: var(--muted); display: flex; align-items: center; gap: 8px; flex-wrap: wrap; }
+.buckaroo-loading-wrap { display: flex; flex-direction: column; gap: 8px; min-height: 120px; }
+.buckaroo-preview { width: 100%; height: 60vh; min-height: 240px; opacity: 0.72; }
 .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; }

packages/app/src/types.ts

@@ -224,6 +224,17 @@ export interface SessionResult {
   detail: string;
 }
 
+/** A JSON cell value as returned by the data endpoint. */
+export type CellValue = string | number | boolean | null | CellValue[] | { [key: string]: CellValue };
+
+/** One page of an entry's rows, from GET /{project}/api/data/{hash}. */
+export interface DataPage {
+  data: Record<string, CellValue>[];
+  offset: number;
+  limit: number;
+  total: number;
+}
+
 export interface LogEvent {
   ts: string;
   kind: "build_ok" | "build_error" | "alias_set" | "buckaroo" | string;