perf(studio): virtualize wide workbook columns

Extends the large-workbook preview spec with horizontal virtualization, merge-aware row and column windows, and keyboard scrolling to off-screen coordinates. The change keeps ArtifactView generic and adds a 256-column browser regression.

Validated with the Node 24 Studio build and 40-file/243-test Vitest suite, 36 Playwright tests, focused oxlint, and the Homology cross-repository Studio verifier.

Co-authored-by: Codex (GPT 5.6 Sol) <codex@openai.com>

Author: phodal

docs/specs/2026-08-24-studio-pdf-fbx-and-large-workbook-previews.md

@@ -11,17 +11,17 @@ Artifact View already dispatches through server-owned adapter and surface bindin
 
 - ArtifactView remains a renderer-agnostic dispatcher. It must not inspect PDF, FBX, Office, or Canvas payload details.
 - PDF is a Studio-owned, read-only data surface. The adapter binds the exact catalog revision, exposes only the PDF bytes plus bounded page metadata, and the browser renders pages with PDF.js. PDF JavaScript, form actions, attachments, and external network access are not executed.
-- FBX is a Provider-owned external-hosted surface. The Homology Provider binds the exact catalog revision, parses it with `@homology/diagram-fbx`, and owns the rendered document. Better Harness only validates and mounts the common opaque hosted surface.
-- XLSX remains a Studio-owned read-only data surface. The projection may expose up to the existing populated-cell budget, and the client virtualizes rows so a large sparse worksheet does not create one DOM row for every worksheet row.
+- FBX is a Provider-owned external-hosted surface. The Homology Provider binds the exact catalog revision, parses it with `@homology/diagram-fbx`, and owns the precompiled WebGL document and interaction runtime. Better Harness only validates and mounts the common opaque hosted surface.
+- XLSX remains a Studio-owned read-only data surface. The projection may expose up to the existing populated-cell budget, and the client virtualizes rows and columns so a large sparse worksheet does not create one DOM cell for every worksheet coordinate.
 - Revision, adapter, renderer, hosted-runtime, provider fingerprint, capability, and security-profile identity continue to decide surface retention. Late data from an older revision must not replace the current view.
 
 ## Acceptance criteria
 
 1. A real multipage PDF appears as a native Artifact View with page count, page navigation, zoom, keyboard operation, and virtualized page mounting.
 2. PDF bytes are served only from an immutable revision resource URI. Oversized files, excessive page counts, malformed files, password-protected files, and revision drift fail closed with a browser-safe diagnostic.
-3. A real ASCII or binary FBX appears through the existing external-hosted iframe lane, includes mesh/vertex/polygon metadata, and remains usable without adding an FBX branch to `ArtifactView.tsx` or the Studio surface registry.
+3. A real ASCII or binary FBX appears as an interactive WebGL model through the existing external-hosted iframe lane, includes mesh/vertex/polygon metadata, and remains usable without adding an FBX branch to `ArtifactView.tsx` or the Studio surface registry.
 4. FBX provider activation is explicit and receipt-bound. Ordinary TSX/JSX, Canvas TSX, diagrams, notebooks, Office files, and unknown files retain their existing resolution rules.
-5. XLSX retains populated cells beyond row 200, renders only the visible row window plus overscan, preserves sheet and cell selection across compatible revisions, and supports keyboard navigation to an off-screen row.
+5. XLSX retains populated cells beyond row 200 and column 64, renders only visible row/column windows plus overscan, expands a window when required to preserve a merged cell, preserves revision-scoped sheet/cell state, and supports keyboard navigation to off-screen coordinates.
 6. Unit tests cover model validation, catalog resolution, exact-revision resource reads, fail-closed inputs, provider receipts, and renderer selection. Browser tests cover wide, compact, and narrow layouts with no page errors, console errors, or unintended horizontal page overflow.
 
 ## Limits and non-goals
@@ -32,7 +32,7 @@ Artifact View already dispatches through server-owned adapter and surface bindin
 
 ## Verification
 
-- Better Harness Node 24 generated-code check, Harness build/Vitest (19 files, 162 tests), Studio build/Vitest (40 files, 243 tests), Playwright (35 tests), and package verification passed.
-- Homology `diagram-fbx` build and integration Provider check passed (4 files, 13 tests; pack 1,851,262 bytes / 6,056,207 bytes unpacked / 11 entries), plus the cross-repository `verify:studio` route check.
-- A real three-page PDF, binary FBX, and generated 420-row XLSX returned exact-revision snapshots/resources; PDF and XLSX used native bindings, while FBX used the receipt-bound opaque hosted Provider.
-- Browser inspection at 1440x900, 1024x768, and 390x844 found zero page overflow and zero final console warning/error. PDF rendered real canvases and navigated to page 2; XLSX mounted 37 visible rows and materialized A420 only near the bottom; FBX pan/zoom controls changed scale from 1.0 to 1.2.
+- Better Harness Node 24 Harness build/Vitest (19 files, 162 tests), Studio build/Vitest (40 files, 243 tests), Playwright (36 tests), and package verification passed.
+- Homology integration Provider check passed (4 files, 13 tests; pack 2,014,441 bytes / 6,687,943 bytes unpacked / 12 entries), plus the cross-repository `verify:studio` route check.
+- A real three-page PDF, binary FBX, and generated 420-row by 256-column XLSX returned exact-revision snapshots/resources; PDF and XLSX used native bindings, while FBX used the receipt-bound opaque hosted Provider.
+- Browser inspection at 1440x900, 1024x768, and 390x844 found zero page overflow and zero final console warning/error. PDF rendered real canvases and navigated to page 2; XLSX mounted bounded row/column windows and materialized IV4 only at the far horizontal edge; FBX created one WebGL mesh, used the normalized-scene fallback for the minimal binary fixture, and changed its interaction counter after Reset.

packages/harness-studio/src/app/artifacts/xlsx/XlsxArtifactView.tsx

@@ -67,20 +67,61 @@ function XlsxGrid(props: {
     estimateSize: (index) => rowHeight(props.sheet, index + 1),
     overscan: 8,
   });
-  const rows = rowVirtualizer.getVirtualItems();
-  const topSpacer = rows[0]?.start ?? 0;
-  const bottomSpacer = rows.length === 0 ? 0 : rowVirtualizer.getTotalSize() - rows[rows.length - 1]!.end;
+  const columnVirtualizer = useVirtualizer({
+    count: props.sheet.columnCount,
+    getScrollElement: () => props.scrollElement,
+    estimateSize: (index) => columnWidth(props.sheet, index + 1),
+    horizontal: true,
+    overscan: 4,
+  });
+  const rowItems = rowVirtualizer.getVirtualItems();
+  const columnItems = columnVirtualizer.getVirtualItems();
+  const rowOffsets = useMemo(
+    () => dimensionOffsets(props.sheet.rowCount, (index) => rowHeight(props.sheet, index)),
+    [props.sheet],
+  );
+  const columnOffsets = useMemo(
+    () => dimensionOffsets(props.sheet.columnCount, (index) => columnWidth(props.sheet, index)),
+    [props.sheet],
+  );
+  const rowWindow = expandMergedWindow(
+    rowItems[0]?.index === undefined ? 1 : rowItems[0].index + 1,
+    rowItems.at(-1)?.index === undefined ? Math.min(1, props.sheet.rowCount) : rowItems.at(-1)!.index + 1,
+    props.sheet.mergedRanges,
+    "row",
+  );
+  const columnWindow = expandMergedWindow(
+    columnItems[0]?.index === undefined ? 1 : columnItems[0].index + 1,
+    columnItems.at(-1)?.index === undefined ? Math.min(1, props.sheet.columnCount) : columnItems.at(-1)!.index + 1,
+    props.sheet.mergedRanges,
+    "column",
+  );
+  const rows = integerRange(rowWindow.start, rowWindow.end);
+  const columns = integerRange(columnWindow.start, columnWindow.end);
+  const topSpacer = rowOffsets[rowWindow.start - 1] ?? 0;
+  const bottomSpacer = (rowOffsets.at(-1) ?? 0) - (rowOffsets[rowWindow.end] ?? 0);
+  const leftSpacer = columnOffsets[columnWindow.start - 1] ?? 0;
+  const rightSpacer = (columnOffsets.at(-1) ?? 0) - (columnOffsets[columnWindow.end] ?? 0);
+  const physicalColumnCount = 1 + columns.length + Number(leftSpacer > 0) + Number(rightSpacer > 0);
   return <table className="xlsx-grid" role="grid" aria-rowcount={props.sheet.rowCount} aria-colcount={props.sheet.columnCount}>
-    <colgroup><col className="xlsx-row-number-column" />{Array.from({ length: props.sheet.columnCount }, (_, index) => <col key={index} style={{ width: `${columnWidth(props.sheet, index + 1)}px` }} />)}</colgroup>
-    <thead><tr><th aria-hidden="true" />{Array.from({ length: props.sheet.columnCount }, (_, index) => <th key={index} scope="col">{columnLabel(index + 1)}</th>)}</tr></thead>
+    <colgroup>
+      <col className="xlsx-row-number-column" />
+      {leftSpacer > 0 && <col className="xlsx-column-spacer" style={{ width: `${leftSpacer}px` }} />}
+      {columns.map((column) => <col key={column} style={{ width: `${columnWidth(props.sheet, column)}px` }} />)}
+      {rightSpacer > 0 && <col className="xlsx-column-spacer" style={{ width: `${rightSpacer}px` }} />}
+    </colgroup>
+    <thead><tr>
+      <th aria-hidden="true" />
+      {leftSpacer > 0 && <th className="xlsx-column-spacer" aria-hidden="true" />}
+      {columns.map((column) => <th key={column} scope="col">{columnLabel(column)}</th>)}
+      {rightSpacer > 0 && <th className="xlsx-column-spacer" aria-hidden="true" />}
+    </tr></thead>
     <tbody>
-      {topSpacer > 0 && <tr className="xlsx-virtual-spacer" aria-hidden="true"><td colSpan={props.sheet.columnCount + 1} style={{ height: `${topSpacer}px` }} /></tr>}
-      {rows.map((virtualRow) => {
-      const row = virtualRow.index + 1;
-      return <tr key={row} data-index={virtualRow.index} ref={rowVirtualizer.measureElement} style={{ height: `${rowHeight(props.sheet, row)}px` }}>
+      {topSpacer > 0 && <tr className="xlsx-virtual-spacer" aria-hidden="true"><td colSpan={physicalColumnCount} style={{ height: `${topSpacer}px` }} /></tr>}
+      {rows.map((row) => <tr key={row} data-index={row - 1} ref={rowVirtualizer.measureElement} style={{ height: `${rowHeight(props.sheet, row)}px` }}>
         <th scope="row">{row}</th>
-        {Array.from({ length: props.sheet.columnCount }, (_, columnOffset) => {
-          const column = columnOffset + 1;
+        {leftSpacer > 0 && <td className="xlsx-column-spacer" aria-hidden="true" />}
+        {columns.map((column) => {
           const key = coordinateKey(row, column);
           if (model.covered.has(key)) return undefined;
           const cell = model.cells.get(key);
@@ -108,16 +149,55 @@ function XlsxGrid(props: {
               props.sheet.columnCount,
               props.onSelect,
               (index, options) => rowVirtualizer.scrollToIndex(index, options),
+              (index, options) => columnVirtualizer.scrollToIndex(index, options),
             )}
           >{cell?.display ?? ""}</td>;
         })}
-      </tr>;
-      })}
-      {bottomSpacer > 0 && <tr className="xlsx-virtual-spacer" aria-hidden="true"><td colSpan={props.sheet.columnCount + 1} style={{ height: `${bottomSpacer}px` }} /></tr>}
+        {rightSpacer > 0 && <td className="xlsx-column-spacer" aria-hidden="true" />}
+      </tr>)}
+      {bottomSpacer > 0 && <tr className="xlsx-virtual-spacer" aria-hidden="true"><td colSpan={physicalColumnCount} style={{ height: `${bottomSpacer}px` }} /></tr>}
     </tbody>
   </table>;
 }
 
+function dimensionOffsets(count: number, size: (index: number) => number): number[] {
+  const offsets = Array.from({ length: count + 1 }, () => 0);
+  for (let index = 1; index <= count; index += 1) offsets[index] = offsets[index - 1]! + size(index);
+  return offsets;
+}
+
+function expandMergedWindow(
+  start: number,
+  end: number,
+  merges: readonly XlsxMergedRange[],
+  axis: "column" | "row",
+): { start: number; end: number } {
+  let nextStart = start;
+  let nextEnd = end;
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const merge of merges) {
+      const mergeStart = axis === "row" ? merge.startRow : merge.startColumn;
+      const mergeEnd = axis === "row" ? merge.endRow : merge.endColumn;
+      if (mergeEnd < nextStart || mergeStart > nextEnd) continue;
+      if (mergeStart < nextStart) {
+        nextStart = mergeStart;
+        changed = true;
+      }
+      if (mergeEnd > nextEnd) {
+        nextEnd = mergeEnd;
+        changed = true;
+      }
+    }
+  }
+  return { start: nextStart, end: nextEnd };
+}
+
+function integerRange(start: number, end: number): number[] {
+  return end < start ? [] : Array.from({ length: end - start + 1 }, (_, index) => start + index);
+}
+
 function gridModel(sheet: XlsxWorksheetSnapshot): {
   cells: Map<string, XlsxCellSnapshot>;
   merges: Map<string, XlsxMergedRange>;
@@ -146,6 +226,7 @@ function handleCellKeyDown(
   columnCount: number,
   onSelect: (address: string) => void,
   scrollToRow: (index: number, options?: { align?: "auto" | "center" | "end" | "start" }) => void,
+  scrollToColumn: (index: number, options?: { align?: "auto" | "center" | "end" | "start" }) => void,
 ): void {
   if (event.key === "Enter" || event.key === " ") {
     event.preventDefault();
@@ -175,6 +256,7 @@ function handleCellKeyDown(
     const address = `${columnLabel(column)}${row}`;
     onSelect(address);
     scrollToRow(row - 1, { align: "auto" });
+    scrollToColumn(column - 1, { align: "auto" });
     globalThis.requestAnimationFrame?.(() => {
       target = grid?.querySelector<HTMLElement>(`[role='gridcell'][data-row='${row}'][data-column='${column}']`);
       target?.focus();

packages/harness-studio/src/app/styles/workbench.css

@@ -1355,6 +1355,7 @@
 .xlsx-grid td.selected { position: relative; z-index: 1; outline: 2px solid var(--color-primary); outline-offset: -2px; }
 .xlsx-grid td:focus-visible { outline: 2px solid var(--color-focus); outline-offset: -2px; }
 .xlsx-grid .xlsx-virtual-spacer td { height: 0; padding: 0; border: 0; }
+.xlsx-grid .xlsx-column-spacer { min-width: 0; padding: 0; border-right: 0; background: var(--color-document-paper); }
 .xlsx-sheet-tabs { min-width: 0; padding: 0 var(--space-sm); display: flex; align-items: end; gap: 1px; overflow-x: auto; border-top: 1px solid var(--color-border); background: var(--color-panel); }
 .xlsx-sheet-tabs button { height: calc(var(--pane-header-height) - 4px); min-width: 72px; padding: 0 var(--space-md); border: 0; border-top: 2px solid transparent; color: var(--color-text-muted); background: transparent; font: inherit; font-size: var(--type-meta-size); white-space: nowrap; }
 .xlsx-sheet-tabs button:hover { color: var(--color-text); background: var(--color-surface-hover); }

packages/harness-studio/test/browser/artifact-host.spec.mjs

@@ -615,6 +615,31 @@ test("renders a read-only XLSX snapshot with sheets, formulas, merges, and style
   expect(failures).toEqual([]);
 });
 
+test("virtualizes wide XLSX columns and keeps the far edge selectable", async ({ page }) => {
+  const failures = watchFailures(page);
+  await page.setViewportSize({ width: 1024, height: 768 });
+  try {
+    await writeFile(join(artifactDirectory, "workbook.xlsx"), createXlsxFixture({ farColumn: 256 }));
+    await openArtifacts(page);
+    await page.getByRole("button", { name: /workbook\.xlsx/ }).click();
+    const viewer = page.locator(".xlsx-artifact-viewer");
+    await viewer.getByRole("button", { name: "Summary" }).click();
+    await expect(viewer.locator(".xlsx-column-spacer").first()).toBeVisible();
+    expect(await viewer.getByRole("gridcell").count()).toBeLessThan(100);
+    await viewer.locator(".xlsx-grid-scroll").evaluate((element) => {
+      element.scrollLeft = element.scrollWidth;
+      element.dispatchEvent(new Event("scroll"));
+    });
+    const farCell = viewer.locator('[data-address="IV4"]');
+    await expect(farCell).toBeVisible();
+    await farCell.click();
+    await expect(viewer.locator(".xlsx-formula-bar strong")).toHaveText("IV4");
+  } finally {
+    await writeFile(join(artifactDirectory, "workbook.xlsx"), createXlsxFixture());
+  }
+  expect(failures).toEqual([]);
+});
+
 test("resets XLSX sheet and cell state to the new snapshot default", async ({ page }, testInfo) => {
   const failures = watchFailures(page);
   await page.setViewportSize({ width: 1440, height: 900 });

packages/harness-studio/test/xlsx-fixture.ts

@@ -5,6 +5,7 @@ export interface XlsxFixtureOptions {
   workbookRelationshipTarget?: string;
   formulaResult?: number;
   farRow?: number;
+  farColumn?: number;
 }
 
 /** Produces real ZIP/OPC XLSX bytes with two sheets, formulas, merges, and styles. */
@@ -82,7 +83,7 @@ export function createXlsxFixture(options: XlsxFixtureOptions = {}): Uint8Array
         <x:sheetData>
           <x:row r="1" ht="30" customHeight="1"><x:c r="A1" s="1" t="str"><x:v>Studio XLSX Fixture</x:v></x:c><x:c r="B1" s="1"/></x:row>
           <x:row r="3"><x:c r="A3" t="str"><x:v>Planned</x:v></x:c><x:c r="B3" s="4" t="n"><x:f>SUM('Data'!B2:B3)</x:f><x:v>${formulaResult}</x:v></x:c></x:row>
-          <x:row r="4"><x:c r="A4" t="str"><x:v>Completion</x:v></x:c><x:c r="B4" s="2" t="n"><x:v>0.75</x:v></x:c></x:row>
+          <x:row r="4"><x:c r="A4" t="str"><x:v>Completion</x:v></x:c><x:c r="B4" s="2" t="n"><x:v>0.75</x:v></x:c>${options.farColumn === undefined ? "" : `<x:c r="${xlsxColumnLabel(options.farColumn)}4" t="str"><x:v>Virtualized column</x:v></x:c>`}</x:row>
           ${options.farRow === undefined ? "" : `<x:row r="${options.farRow}"><x:c r="A${options.farRow}" t="str"><x:v>Virtualized row</x:v></x:c><x:c r="B${options.farRow}" t="n"><x:v>${options.farRow}</x:v></x:c></x:row>`}
         </x:sheetData>
         <x:mergeCells count="1"><x:mergeCell ref="A1:B1"/></x:mergeCells>
@@ -97,3 +98,13 @@ export function createXlsxFixture(options: XlsxFixtureOptions = {}): Uint8Array
       </x:worksheet>`),
   });
 }
+
+function xlsxColumnLabel(column: number): string {
+  let value = column;
+  let label = "";
+  while (value > 0) {
+    label = String.fromCharCode(65 + (value - 1) % 26) + label;
+    value = Math.floor((value - 1) / 26);
+  }
+  return label;
+}