typescript-visual-regression-pagination-drift

Answer

Root cause. PAG-001/002 added cursor pagination to /trees (page size 50). With 3600+ seeded trees the demo tree (demo-forest) is on page ~15, so selectFirstTree's label lookup against page 1 returns undefined and the helper falls back to option[0] — the newest empty tree. Every golden capture of a tree select then renders the empty tree's state (~33% of the snapshot tree), silently drifting goldens (VREG-001).

Durable fix, three parts:

1. Tree select: fetch active tree by id and prepend it

The select always hydrates page 1 of /trees, but additionally resolves the active tree by id (GET /trees/:id) and prepends it — deduped by id — so the active tree is present regardless of its pagination position.

// src/features/trees/api.ts
export interface Tree { id: string; label: string; createdAt: string; parentId: string | null }
export interface TreePage { items: Tree[]; nextCursor: string | null; total: number }

const TREES = "/trees";

export async function getTreeById(id: string, signal?: AbortSignal): Promise<Tree | null> {
  const res = await fetch(`${TREES}/${encodeURIComponent(id)}`, { signal });
  if (res.status === 404) return null;                 // stale id: caller falls back
  if (!res.ok) throw new Error(`getTreeById ${id}: ${res.status}`);
  return res.json();
}

export async function fetchTreePage(cursor?: string, signal?: AbortSignal): Promise<TreePage> {
  const params = new URLSearchParams({ limit: "50" });
  if (cursor) params.set("cursor", cursor);            // PAG-001/002 cursor contract
  const res = await fetch(`${TREES}?${params}`, { signal });
  if (!res.ok) throw new Error(`fetchTreePage: ${res.status}`);
  return res.json();
}

export async function searchTrees(label: string, signal?: AbortSignal): Promise<Tree[]> {
  const res = await fetch(`${TREES}?search=${encodeURIComponent(label)}&limit=20`, { signal });
  if (!res.ok) throw new Error(`searchTrees: ${res.status}`);
  return (await res.json()).items;
}

// Pure: prepend active tree, dedupe by id (unit-testable).
export function mergeOptions(byId: Tree | null, pageItems: Tree[]): Tree[] {
  if (!byId) return pageItems;
  return [byId, ...pageItems.filter((t) => t.id !== byId.id)];
}

// src/components/TreeSelect.tsx
export function TreeSelect({ activeTreeId, onSelect }: Props) {
  const [options, setOptions] = useState<Tree[]>([]);
  const [cursor, setCursor] = useState<string | null>(null);

  useEffect(() => {
    const ac = new AbortController();
    (async () => {
      // Active tree by id FIRST so label lookup never depends on page 1 (VREG-001).
      const [byId, page] = await Promise.all([
        activeTreeId ? getTreeById(activeTreeId, ac.signal) : Promise.resolve(null),
        fetchTreePage(undefined, ac.signal),
      ]);
      setOptions(mergeOptions(byId, page.items));
      setCursor(page.nextCursor);
    })();
    return () => ac.abort();
  }, [activeTreeId]);

  return (
    <Combobox
      aria-label="tree-select"
      options={options}
      onSelect={(t) => onSelect(t.id)}
      onLoadMore={cursor ? () => fetchTreePage(cursor) : undefined}
    />
  );
}

2. Rail fallback: /trees?search=<label> when no id is persisted

When the rail has only a known label (no stored id, or the stored id 404s), resolve via search and prefer the exact label match.

// src/features/rail/activeTree.ts
export function pickBest(matches: Tree[], label: string): Tree | null {
  return matches.find((t) => t.label === label) ?? matches[0] ?? null;
}

export async function resolveActiveTree(knownLabel?: string): Promise<Tree | null> {
  const stored = readStoredActiveTreeId();              // localStorage "tree.activeTree"
  if (stored) {
    const byId = await getTreeById(stored);
    if (byId) return byId;                              // exact, no search needed
  }
  if (knownLabel) return pickBest(await searchTrees(knownLabel), knownLabel);
  return null;                                          // honest fallback: page 1, no crash
}

3. Test: API search + localStorage preselect + reload

The test no longer assumes the demo tree is on page 1. It resolves the tree via the API, preselects it in localStorage before app scripts run, reloads so the select hydrates with the prepended active tree, then does the label lookup.

// e2e/vreg/selectFirstTree.ts
import { request } from "../request";

export async function selectFirstTree(page: Page, label = "demo-forest") {
  // 1. Resolve via API search — pagination-agnostic (3600+ trees).
  const trees = await request.get(`/trees?search=${encodeURIComponent(label)}`).json<{ items: Tree[] }>();
  const tree = trees.items.find((t) => t.label === label);
  if (!tree) throw new Error(`demo tree "${label}" not resolvable via API search`);

  // 2. Preselect before app boot so TreeSelect prepends it by id.
  await page.addInitScript(({ id, label }) => {
    localStorage.setItem("tree.activeTree", JSON.stringify({ id, label }));
  }, tree);

  // 3. Reload: select hydrates with active tree prepended; lookup now succeeds.
  await page.reload();
  await page.getByRole("combobox", { name: "tree-select" }).click();
  await page.getByRole("option", { name: label, exact: true }).click();
  await expect(page.getByRole("combobox", { name: "tree-select" })).toHaveValue(label);
}

4. Golden refresh (UI-10 / UI-REL-001)

Goldens predating the UI evolution are invalid; refresh with captures verified to show real content (the demo label, not the empty tree):

UPDATE_VISUAL_GOLDENS=1 npm run test:vreg -- --grep selectFirstTree
node scripts/verify-captures.mjs --expect-label demo-forest   # fail if capture is blank/empty-tree

verify-captures asserts each rewritten golden contains the demo label text and a non-trivial pixel diff (>0), guaranteeing captures are real content before committing.