perf(showcase-dashboard): order-safe concurrent paged initial status fetch + loading state (CopilotKit#5256)

## Summary
The coverage dashboard's initial load was slow and briefly rendered
misleading data. Root cause: `useLiveStatus` fetched the entire
(growing) PocketBase `status` collection via a single `getFullList`,
which PocketBase serial-paginates at perPage≤500 — ~5 sequential
blocking round-trips before first paint. During that window the grid
rendered authoritative `D0` cells and `✓0 ~0 ✗0` column tallies (not a
loading state), and a transient amber-D5/D6 toggle flash appeared
pre-hydration.

## Changes
- **perf:** concurrent paged fetch — page 1 then `Promise.all` over
pages 2..N, merged by array index (deterministic regardless of
resolution order), with a stable `sort: "id"` on every page so
concurrent requests share one ordering. Initial `setRows` wrapped in
`startTransition` to avoid a synchronous full-matrix re-render.
Best-effort snapshot; the live SSE subscription reconciles anything
created in the brief fetch→subscribe window (PocketBase `id` is random,
not monotonic — no growth-completeness claim).
- **fix:** `connecting` + empty-map now renders a loading affordance
instead of authoritative zeros (the §5.3 "no stale-green/fake-zero lie"
guarantee); `loading` made required on the tally type; fail-safe
undefined-tally fallback defaults to loading rather than zeros.

## Test plan
- [x] Order-safety: pages merge deterministically even when page 1
resolves last (out-of-order resolution)
- [x] Stable sort forwarded to every page request (behavioral — mock
sorts before slicing)
- [x] Loading-state quadrants on both `computeColumnTally` and
`computeColumnTallyDetail` (connecting+empty → loading; connecting+rows
→ authoritative; live+empty → authoritative; error → offline)
- [x] `OverlayColumnHeader` renders loading/offline affordance, not zero
glyphs
- [x] Full dashboard suite: 827 passed / 1 skipped; tsc clean; next
build green

Author: jpr5

showcase/shell-dashboard/src/components/__tests__/compute-tally-detail.test.tsx

@@ -91,9 +91,79 @@ describe("computeColumnTallyDetail", () => {
       amber: [],
       red: [],
       unknown: true,
+      loading: false,
     });
   });
 
+  // A4 regression: the connecting+empty initial-load branch in
+  // `computeColumnTallyDetail` (mirroring `computeColumnTally`). While the
+  // first PocketBase fetch is in flight the live-status map is empty AND the
+  // connection is "connecting". Returning authoritative empty buckets in that
+  // window reads as "every cell is at depth 0" — a lie. The detail must surface
+  // `loading: true` (a subset of `unknown`) instead, never authoritative
+  // emptiness, until the first rows land.
+  it("returns loading: true (unknown, not authoritative empty) while connecting with no rows", () => {
+    const integration = makeIntegration("test-int", ["feat-1"]);
+    const features = [makeFeature("feat-1", "Feature 1")];
+    const liveStatus: LiveStatusMap = new Map();
+
+    const result = computeColumnTallyDetail(
+      integration,
+      features,
+      liveStatus,
+      "connecting",
+    );
+
+    expect(result).toEqual({
+      green: [],
+      amber: [],
+      red: [],
+      unknown: true,
+      loading: true,
+    });
+  });
+
+  it("does NOT treat connecting-with-rows as loading (data already arrived)", () => {
+    const integration = makeIntegration("test-int", ["feat-a"]);
+    const features = [makeFeature("feat-a", "Feature A")];
+    // A delta arrived during a transient reconnect: rows are present, so the
+    // detail is authoritative even though the connection is mid-reconnect.
+    const liveStatus: LiveStatusMap = new Map([
+      ["e2e:test-int/feat-a", makeRow("e2e:test-int/feat-a", "e2e", "red")],
+    ]);
+
+    const result = computeColumnTallyDetail(
+      integration,
+      features,
+      liveStatus,
+      "connecting",
+    );
+
+    expect(result.loading).toBe(false);
+    expect(result.unknown).toBe(false);
+    expect(result.red).toEqual([
+      { label: "Feature A", dimension: "e2e", featureId: "feat-a" },
+    ]);
+  });
+
+  it("live with no rows is NOT loading — authoritative empty result", () => {
+    const integration = makeIntegration("test-int", ["feat-1"]);
+    const features = [makeFeature("feat-1", "Feature 1")];
+
+    const result = computeColumnTallyDetail(
+      integration,
+      features,
+      new Map(),
+      "live",
+    );
+
+    expect(result.loading).toBe(false);
+    expect(result.unknown).toBe(false);
+    expect(result.green).toEqual([]);
+    expect(result.amber).toEqual([]);
+    expect(result.red).toEqual([]);
+  });
+
   it("green D6 cells land in green bucket", () => {
     // Use feature IDs with a D5 mapping (agentic-chat, tool-rendering) so the
     // verification ladder is contiguous to D5. Green requires an intact

showcase/shell-dashboard/src/components/__tests__/dashboard-color-matrix.test.tsx

@@ -803,7 +803,13 @@ describe("(6) edges + rollup precedence", () => {
       // subagents → no rows → gray (excluded)
     ]);
     const tally = computeColumnTally(integration, features, live, "live");
-    expect(tally).toEqual({ green: 1, amber: 0, red: 1, unknown: false });
+    expect(tally).toEqual({
+      green: 1,
+      amber: 0,
+      red: 1,
+      unknown: false,
+      loading: false,
+    });
   });
 
   it("column tally returns unknown=true when connection is error", () => {
@@ -818,7 +824,13 @@ describe("(6) edges + rollup precedence", () => {
       mapOf([]),
       "error",
     );
-    expect(tally).toEqual({ green: 0, amber: 0, red: 0, unknown: true });
+    expect(tally).toEqual({
+      green: 0,
+      amber: 0,
+      red: 0,
+      unknown: true,
+      loading: false,
+    });
   });
 });
 

showcase/shell-dashboard/src/components/feature-grid.test.tsx

@@ -10,6 +10,8 @@ import { describe, it, expect } from "vitest";
 import { render } from "@testing-library/react";
 import { LiveIndicator, computeColumnTally, FeatureGrid } from "./feature-grid";
 import type { CellContext, CellRenderer } from "./feature-grid";
+import { OverlayColumnHeader } from "./overlay-column-header";
+import type { Overlay } from "@/lib/overlay-types";
 import { urlsFor } from "./cell-pieces";
 import { getIntegrations } from "@/lib/registry";
 import { starterIsSupported, STARTER_LEVELS } from "@/lib/live-status";
@@ -145,7 +147,13 @@ describe("computeColumnTally", () => {
     live.set("e2e:i1/f2", row("e2e:i1/f2", "e2e", "green"));
     const t = computeColumnTally(integration, features, live);
     // D6-ceiling: D3-only green with no D5/D6 → gray → not counted
-    expect(t).toEqual({ green: 0, amber: 0, red: 0, unknown: false });
+    expect(t).toEqual({
+      green: 0,
+      amber: 0,
+      red: 0,
+      unknown: false,
+      loading: false,
+    });
   });
 
   it("red D3 → red chip, green D3 without D5/D6 → gray", () => {
@@ -156,15 +164,27 @@ describe("computeColumnTally", () => {
     live.set("e2e:i1/f2", row("e2e:i1/f2", "e2e", "green"));
     const t = computeColumnTally(integration, features, live);
     // f1 red (gate fail), f2 gray (no D5/D6)
-    expect(t).toEqual({ green: 0, amber: 0, red: 1, unknown: false });
+    expect(t).toEqual({
+      green: 0,
+      amber: 0,
+      red: 1,
+      unknown: false,
+      loading: false,
+    });
   });
 
   it("health row alone does not contribute to tally", () => {
     const live: LiveStatusMap = new Map();
     live.set("health:i1", row("health:i1", "health", "red"));
     const t = computeColumnTally(integration, features, live);
     // No D3 rows → all cells gray → nothing counted
-    expect(t).toEqual({ green: 0, amber: 0, red: 0, unknown: false });
+    expect(t).toEqual({
+      green: 0,
+      amber: 0,
+      red: 0,
+      unknown: false,
+      loading: false,
+    });
   });
 
   it("features without demos are gray (unwired), not counted", () => {
@@ -178,7 +198,13 @@ describe("computeColumnTally", () => {
     };
     const t = computeColumnTally(partialInt, features, live);
     // f1: wired + D3=green but no D5/D6 → gray; f2: unwired → gray
-    expect(t).toEqual({ green: 0, amber: 0, red: 0, unknown: false });
+    expect(t).toEqual({
+      green: 0,
+      amber: 0,
+      red: 0,
+      unknown: false,
+      loading: false,
+    });
   });
 
   it("not_supported_features are gray, not counted", () => {
@@ -191,7 +217,13 @@ describe("computeColumnTally", () => {
     };
     const t = computeColumnTally(unsupportedInt, features, live);
     // f1: D3=green but no D5/D6 → gray; f2: unsupported → gray
-    expect(t).toEqual({ green: 0, amber: 0, red: 0, unknown: false });
+    expect(t).toEqual({
+      green: 0,
+      amber: 0,
+      red: 0,
+      unknown: false,
+      loading: false,
+    });
   });
 
   it("returns unknown=true when connection is error", () => {
@@ -205,7 +237,49 @@ describe("computeColumnTally", () => {
 
   it("returns zeros with unknown=false when no rows", () => {
     const t = computeColumnTally(integration, features, new Map());
-    expect(t).toEqual({ green: 0, amber: 0, red: 0, unknown: false });
+    expect(t).toEqual({
+      green: 0,
+      amber: 0,
+      red: 0,
+      unknown: false,
+      loading: false,
+    });
+  });
+
+  // Regression: while the initial PocketBase fetch is still in flight the
+  // live-status map is empty AND the connection is "connecting". Returning
+  // authoritative ✓0 ~0 ✗0 in that window reads as "everything is at depth 0",
+  // which is a lie — the data simply hasn't arrived yet. The header must show a
+  // loading/unknown state instead, NEVER zeros, until the first rows land.
+  it("returns loading=true (unknown, not authoritative zeros) while connecting with no rows", () => {
+    const t = computeColumnTally(
+      integration,
+      features,
+      new Map(),
+      "connecting",
+    );
+    expect(t.loading).toBe(true);
+    expect(t.unknown).toBe(true);
+    expect(t.green).toBe(0);
+    expect(t.amber).toBe(0);
+    expect(t.red).toBe(0);
+  });
+
+  it("does NOT treat connecting-with-rows as loading (data already arrived)", () => {
+    const live: LiveStatusMap = new Map();
+    live.set("e2e:i1/f1", row("e2e:i1/f1", "e2e", "red"));
+    // A delta arrived during a transient reconnect: rows are present, so the
+    // tally is authoritative even though the connection is mid-reconnect.
+    const t = computeColumnTally(integration, features, live, "connecting");
+    expect(t.loading).toBe(false);
+    expect(t.unknown).toBe(false);
+    expect(t.red).toBe(1);
+  });
+
+  it("live with no rows is NOT loading — it is an authoritative empty result", () => {
+    const t = computeColumnTally(integration, features, new Map(), "live");
+    expect(t.loading).toBe(false);
+    expect(t.unknown).toBe(false);
   });
 
   it("amber chip when D5=green but D6 absent", () => {
@@ -236,7 +310,13 @@ describe("computeColumnTally", () => {
     );
     const t = computeColumnTally(mappedInt, mappedFeatures, mappedLive);
     // D3=green, D4=green, D5=green → amber (D6 not yet green)
-    expect(t).toEqual({ green: 0, amber: 1, red: 0, unknown: false });
+    expect(t).toEqual({
+      green: 0,
+      amber: 1,
+      red: 0,
+      unknown: false,
+      loading: false,
+    });
   });
 });
 
@@ -340,3 +420,75 @@ describe("FeatureGrid — Starter row-group", () => {
     expect(cell.textContent).toContain("~");
   });
 });
+
+/* ------------------------------------------------------------------ */
+/*  OverlayColumnHeader — loading / offline rendering (spec §5.3, A5)   */
+/*                                                                      */
+/*  The core §5.3 guarantee: during the initial-load window the header   */
+/*  must NOT render authoritative ✓0 ~0 ✗0 (which reads as "every cell   */
+/*  at depth 0" — a lie). It shows a "… loading" affordance while the    */
+/*  first signal is in flight, and "? offline" when the stream is down.  */
+/* ------------------------------------------------------------------ */
+
+describe("OverlayColumnHeader — loading / offline rendering (§5.3)", () => {
+  const integration: Integration = {
+    slug: "i1",
+    name: "Integration One",
+    category: "c",
+    language: "ts",
+    description: "",
+    repo: "",
+    backend_url: "https://x",
+    deployed: true,
+    features: ["f1"],
+    demos: [{ id: "f1", name: "f1", description: "", tags: [] }],
+  };
+
+  const HEALTH: Set<Overlay> = new Set<Overlay>(["health"]);
+
+  it("loading tally → '… loading' affordance, NOT authoritative zero counts", () => {
+    const { getByText, queryByText } = render(
+      <OverlayColumnHeader
+        integration={integration}
+        tally={{ green: 0, amber: 0, red: 0, unknown: true, loading: true }}
+        overlays={HEALTH}
+      />,
+    );
+    // The loading affordance renders.
+    expect(getByText(/loading/)).toBeDefined();
+    // The authoritative zero glyphs must NOT render during loading.
+    expect(queryByText(/✓\s*0/)).toBeNull(); // ✓ 0
+    expect(queryByText(/✗\s*0/)).toBeNull(); // ✗ 0
+    expect(queryByText(/^~\s*0$/)).toBeNull(); // ~ 0
+  });
+
+  it("unknown (offline) tally → '? offline' affordance, NOT authoritative zero counts", () => {
+    const { getByText, queryByText } = render(
+      <OverlayColumnHeader
+        integration={integration}
+        tally={{ green: 0, amber: 0, red: 0, unknown: true, loading: false }}
+        overlays={HEALTH}
+      />,
+    );
+    // The offline affordance renders.
+    expect(getByText(/offline/)).toBeDefined();
+    // The authoritative zero glyphs must NOT render while offline.
+    expect(queryByText(/✓\s*0/)).toBeNull(); // ✓ 0
+    expect(queryByText(/✗\s*0/)).toBeNull(); // ✗ 0
+    expect(queryByText(/^~\s*0$/)).toBeNull(); // ~ 0
+  });
+
+  it("authoritative (not loading, not unknown) tally → renders the count glyphs", () => {
+    const { getByText, queryByText } = render(
+      <OverlayColumnHeader
+        integration={integration}
+        tally={{ green: 2, amber: 1, red: 3, unknown: false, loading: false }}
+        overlays={HEALTH}
+      />,
+    );
+    // Counts render; neither loading nor offline affordance is shown.
+    expect(getByText(/✓/)).toBeDefined(); // ✓
+    expect(queryByText(/loading/)).toBeNull();
+    expect(queryByText(/offline/)).toBeNull();
+  });
+});