@elabs-ai/components-viewer 4.0.0

package/src/adapters/text/text-adapter.tsx

@@ -0,0 +1,117 @@
+"use client";
+
+/**
+ * Plain-text adapter — the fallback for anything readable as UTF-8.
+ *
+ * Deliberately does NOT do SYNTAX highlighting — that is the separate `code`
+ * adapter, registered at a higher priority for code extensions. Keeping them
+ * apart means a 40 MB log file never drags a tokenizer into the bundle, and a
+ * consumer can drop the tokenizer without losing plain text. (Citation and
+ * find-in-document marks are a different thing entirely and DO render here.)
+ *
+ * Large files are truncated at load, not at render: putting ten million
+ * characters into one `<pre>` locks the main thread with no way back. The cut is
+ * reported so the UI can say so rather than silently lying about the content.
+ */
+
+import { useMemo, useRef } from "react";
+
+import { MatchHighlight, cn, useLocale } from "@elabs-ai/components-ui";
+import type { ResolvedFileSource } from "@elabs-ai/components-ui";
+
+import { toViewerError } from "../../core/errors";
+import { toMarkRanges } from "../../core/highlight-marks";
+import { useScrollActiveHighlightIntoView } from "../../core/use-highlight-scroll";
+import type {
+  AdapterDocument,
+  AdapterLoadContext,
+  AdapterModule,
+  AdapterRendererProps,
+  FileAdapter,
+} from "../../core/types";
+import { textManifest } from "./text-manifest";
+
+/**
+ * Characters kept before truncation. ~2M is comfortably past any file a person
+ * reads in a preview pane and still renders in one frame.
+ */
+export const TEXT_CHARACTER_LIMIT = 2_000_000;
+
+export interface TextDocument extends AdapterDocument {
+  kind: "text";
+  text: string;
+  /** Total characters in the file, when more than what is shown. */
+  totalCharacters?: number;
+}
+
+class TextAdapter implements FileAdapter {
+  async load(source: ResolvedFileSource, context: AdapterLoadContext): Promise<TextDocument> {
+    let raw: string;
+    try {
+      raw = await source.text(context.signal);
+    } catch (error) {
+      throw toViewerError(error, "read-failed", { fileName: source.name });
+    }
+
+    if (raw.length <= TEXT_CHARACTER_LIMIT) return { kind: "text", text: raw };
+    return {
+      kind: "text",
+      text: raw.slice(0, TEXT_CHARACTER_LIMIT),
+      totalCharacters: raw.length,
+      // So a passage the shell cannot find is reported as "past the part we
+      // previewed" rather than "not in this document" — different news.
+      textTruncated: true,
+    };
+  }
+}
+
+function TextRenderer({
+  document: doc,
+  className,
+  highlights,
+  activeHighlightId,
+}: AdapterRendererProps) {
+  const text = doc as TextDocument;
+  const { t, formatNumber } = useLocale();
+  const container = useRef<HTMLDivElement>(null);
+  const { ranges, activeIndex } = useMemo(
+    () => toMarkRanges(highlights, text.text.length),
+    [highlights, text.text.length],
+  );
+  useScrollActiveHighlightIntoView(container, activeHighlightId);
+
+  return (
+    // No `overflow-auto` here: `FileViewerContent` is the scroll boundary, and
+    // nesting a second one clips the text above the outer pane's own padding.
+    <div ref={container} className={cn("flex flex-col gap-2", className)}>
+      {text.totalCharacters !== undefined && (
+        // Not an error — the file is fine, we are showing part of it. A status
+        // region, so AT hears it once rather than on every scroll.
+        <p role="status" className="text-meta text-muted-foreground">
+          {t("viewer.text.truncated", {
+            shown: formatNumber(text.text.length),
+            total: formatNumber(text.totalCharacters),
+          })}
+        </p>
+      )}
+      <pre className="text-code font-mono break-words whitespace-pre-wrap">
+        {ranges.length === 0 ? (
+          text.text
+        ) : (
+          // `MatchHighlight` renders the WHOLE string with the matches wrapped,
+          // so nothing is lost when a highlight is present — a screen reader
+          // still reads the file continuously.
+          <MatchHighlight text={text.text} ranges={ranges} activeIndex={activeIndex} />
+        )}
+      </pre>
+    </div>
+  );
+}
+
+const adapterModule: AdapterModule = {
+  manifest: textManifest,
+  create: () => new TextAdapter(),
+  Renderer: TextRenderer,
+};
+
+export default adapterModule;

package/src/adapters/text/text-manifest.ts

@@ -0,0 +1,19 @@
+import type { AdapterManifest } from "../../core/types";
+import { PROTOCOL_VERSION } from "../../core/types";
+
+/**
+ * Eager, data-only (see `image-manifest.ts`).
+ *
+ * Claims only broad CATEGORIES, so any adapter naming an extension or an exact
+ * MIME outranks it automatically — this is the "readable as text" backstop.
+ */
+export const textManifest: AdapterManifest = {
+  id: "text",
+  protocol: PROTOCOL_VERSION,
+  categories: ["text", "code", "data", "unknown"],
+  mediaTypes: ["text/"],
+  // `rect` is absent on purpose: a plain-text file has no geometry to point at,
+  // and a manifest that claimed it would let an app offer an affordance the
+  // renderer can never honour.
+  capabilities: { text: true, search: true, highlight: ["quote", "range"] },
+};

package/src/adapters/xlsx/xlsx-adapter.test.tsx

@@ -0,0 +1,159 @@
+import { normalizeFileSource } from "@elabs-ai/components-ui";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it } from "vitest";
+
+import type { ResolvedHighlight } from "../../core/highlight";
+import { SAMPLE_XLSX_BASE64 } from "../office-fixture";
+import xlsxModule, { type XlsxDocument } from "./xlsx-adapter";
+
+const MEDIA_TYPE = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+
+function fixtureSource(name = "quarter.xlsx") {
+  const bytes = Uint8Array.from(atob(SAMPLE_XLSX_BASE64), (char) => char.charCodeAt(0));
+  return normalizeFileSource({
+    kind: "buffer",
+    buffer: bytes.buffer as ArrayBuffer,
+    name,
+    mediaType: MEDIA_TYPE,
+  });
+}
+
+const load = () => xlsxModule.create().load(fixtureSource(), {}) as Promise<XlsxDocument>;
+
+describe("xlsx adapter — a real workbook through SheetJS", () => {
+  it("reads every sheet, keeping the tab names the author gave them", async () => {
+    const doc = await load();
+    expect(doc.sheets.map((sheet) => sheet.name)).toEqual(["Revenue", "Headcount"]);
+    expect(doc.pageCount).toBe(2);
+  });
+
+  it("takes the first row as headers and the rest as rows", async () => {
+    const [revenue] = (await load()).sheets;
+    expect(revenue?.columns).toEqual(["Region", "Revenue", "Closed"]);
+    expect(revenue?.rows[0]?.slice(0, 2)).toEqual(["EMEA", "4200000"]);
+    expect(revenue?.rows).toHaveLength(3);
+  });
+
+  it("shows a date as a date, not as Excel's serial day number", async () => {
+    const [revenue] = (await load()).sheets;
+    // Without `cellDates` this cell reads "46112", which means nothing to a reader.
+    expect(revenue?.rows[0]?.[2]).toBe("2026-03-31");
+  });
+
+  it("does not claim truncation when every row fits", async () => {
+    for (const sheet of (await load()).sheets) expect(sheet.totalRows).toBeUndefined();
+  });
+
+  it("projects the whole workbook to text so search and copy cross sheets", async () => {
+    const doc = await load();
+    expect(doc.text).toContain("Headcount");
+    expect(doc.text).toContain("Engineering\t34");
+  });
+
+  it("reports a file that is not a workbook as parse-failed", async () => {
+    const source = normalizeFileSource({
+      kind: "text",
+      text: "not a workbook",
+      name: "broken.xlsx",
+      mediaType: MEDIA_TYPE,
+    });
+    await expect(xlsxModule.create().load(source, {})).rejects.toMatchObject({
+      code: "parse-failed",
+    });
+  });
+});
+
+describe("xlsx renderer", () => {
+  it("renders a real table, and offers the sheets as tabs", async () => {
+    const doc = await load();
+    render(<xlsxModule.Renderer document={doc} source={fixtureSource()} />);
+
+    expect(screen.getByRole("tablist", { name: "Sheets" })).toBeInTheDocument();
+    expect(screen.getByRole("columnheader", { name: "Region" })).toBeInTheDocument();
+    expect(screen.getByRole("cell", { name: "4200000" })).toBeInTheDocument();
+  });
+
+  it("switches sheets without reloading the file", async () => {
+    const doc = await load();
+    render(<xlsxModule.Renderer document={doc} source={fixtureSource()} />);
+
+    await userEvent.click(screen.getByRole("tab", { name: "Headcount" }));
+    expect(await screen.findByRole("columnheader", { name: "Team" })).toBeInTheDocument();
+  });
+
+  it("drops the tab strip for a single-sheet workbook — chrome that decides nothing", async () => {
+    const doc = await load();
+    const single: XlsxDocument = { ...doc, sheets: doc.sheets.slice(0, 1), pageCount: 1 };
+    render(<xlsxModule.Renderer document={single} source={fixtureSource()} />);
+
+    expect(screen.queryByRole("tablist")).not.toBeInTheDocument();
+    expect(screen.getByRole("table")).toBeInTheDocument();
+  });
+});
+
+describe("xlsx renderer — highlighting", () => {
+  const cite = (id: string, range: [number, number], active = false): ResolvedHighlight => ({
+    id,
+    source: "citation",
+    status: "resolved",
+    address: { kind: "range", start: range[0], end: range[1] },
+    active,
+    range,
+  });
+
+  /** Offsets of a passage in the workbook's own projection. */
+  const rangeOf = (doc: XlsxDocument, passage: string): [number, number] => {
+    const start = doc.text?.indexOf(passage) ?? -1;
+    expect(start).toBeGreaterThanOrEqual(0);
+    return [start, start + passage.length];
+  };
+
+  const renderWith = async (
+    pick: (doc: XlsxDocument) => ResolvedHighlight[],
+    activeHighlightId?: string,
+  ) => {
+    const doc = await load();
+    return render(
+      <xlsxModule.Renderer
+        document={doc}
+        source={fixtureSource()}
+        highlights={pick(doc)}
+        activeHighlightId={activeHighlightId}
+      />,
+    );
+  };
+
+  it("declares the address kinds it can actually honour", () => {
+    expect(xlsxModule.manifest.capabilities?.highlight).toEqual(["quote", "range"]);
+  });
+
+  it("marks one cell of the sheet on screen", async () => {
+    const { container } = await renderWith((doc) => [cite("a", rangeOf(doc, "4200000"))]);
+    const marks = Array.from(container.querySelectorAll("mark"));
+    expect(marks).toHaveLength(1);
+    expect(marks[0]?.closest("td")?.textContent).toBe("4200000");
+  });
+
+  it("turns to the cited SHEET, the way the PDF turns to the cited page", async () => {
+    // "Engineering" is on Headcount, which is not the tab that opens.
+    const { container } = await renderWith(
+      (doc) => [cite("a", rangeOf(doc, "Engineering"), true)],
+      "a",
+    );
+    expect(await screen.findByRole("columnheader", { name: "Team" })).toBeInTheDocument();
+    expect(container.querySelector("mark")?.textContent).toBe("Engineering");
+  });
+
+  it("flags the current passage for assistive tech, not by colour alone", async () => {
+    const { container } = await renderWith((doc) => [cite("a", rangeOf(doc, "EMEA"), true)], "a");
+    const active = container.querySelector('mark[data-active][data-slot="match-highlight-mark"]');
+    expect(active?.getAttribute("aria-current")).toBe("true");
+    expect(active?.textContent).toBe("EMEA");
+  });
+
+  it("draws nothing when no highlight is passed", async () => {
+    const { container } = await renderWith(() => []);
+    expect(container.querySelectorAll("mark")).toHaveLength(0);
+  });
+});

package/src/adapters/xlsx/xlsx-adapter.tsx

@@ -0,0 +1,250 @@
+"use client";
+
+/**
+ * Spreadsheet adapter — a workbook becomes sheets of rows, and rows become a
+ * real `Table`.
+ *
+ * SheetJS is only ever asked for the DATA. Its `sheet_to_html` helper exists and
+ * is not used: it returns a markup string with its own inline styling, which is
+ * exactly the "adapter emits HTML" failure this package was built to avoid
+ * (ADR 0024 §3). `sheet_to_json({ header: 1 })` gives raw cell values, which the
+ * shared `SheetTable` renders with brand-ui components — so a spreadsheet
+ * inherits the theme, the density dial and the keyboard semantics.
+ *
+ * **`xlsx` is an optional peer with two known advisories.** The npm build
+ * (`0.18.5`) carries a prototype-pollution and a ReDoS advisory, both fixed only
+ * in SheetJS's self-hosted CDN builds, which are not published to npm. That is a
+ * documented, deliberate trade (`docs/CONSUMING.md` §6): a consumer who never
+ * opens a spreadsheet never installs it and is never exposed. Treat any workbook
+ * opened here as untrusted input.
+ */
+
+import type { ResolvedFileSource } from "@elabs-ai/components-ui";
+import { cn, Tabs, TabsContent, TabsList, TabsTrigger, useLocale } from "@elabs-ai/components-ui";
+import { useEffect, useMemo, useState } from "react";
+
+import { gridToText, type GridRef } from "../../components/grid-text";
+import { SheetTable } from "../../components/sheet-table";
+import { ViewerError, toViewerError } from "../../core/errors";
+import { toMarkRanges } from "../../core/highlight-marks";
+import { spanAt, type TextIndex } from "../../core/text-index";
+import type {
+  AdapterDocument,
+  AdapterLoadContext,
+  AdapterModule,
+  AdapterRendererProps,
+  FileAdapter,
+} from "../../core/types";
+import { xlsxManifest } from "./xlsx-manifest";
+
+/**
+ * Rows rendered per sheet before truncation. Same bound, same reason, as the CSV
+ * adapter: a preview pane is for looking, and a real analysis grid is
+ * `DataTable` in `@elabs-ai/components-data`.
+ */
+export const XLSX_ROW_LIMIT = 5_000;
+
+export interface SheetModel {
+  /** The tab's own name, as authored in the workbook. */
+  name: string;
+  /** Header cells, taken from the sheet's first row. */
+  columns: string[];
+  /** Body rows, already capped at {@link XLSX_ROW_LIMIT}. */
+  rows: string[][];
+  /** Total body rows in the sheet, when more than what is shown. */
+  totalRows?: number;
+}
+
+export interface XlsxDocument extends AdapterDocument {
+  kind: "xlsx";
+  sheets: SheetModel[];
+  /** Which sheet and row each stretch of `text` came from. */
+  textIndex?: TextIndex<GridRef>;
+}
+
+/**
+ * Does this look like a workbook container at all?
+ *
+ * SheetJS sniffs its input and will happily read arbitrary text as a one-column
+ * CSV — so a damaged `.xlsx` comes back as a sheet holding one junk cell instead
+ * of failing. That is worse than an error: it looks like the file opened. Both
+ * containers this adapter claims have a fixed signature — OOXML/ODS is a zip
+ * (`PK\x03\x04`), legacy `.xls` is a CFB compound file — so anything else is
+ * rejected before SheetJS gets a chance to be helpful.
+ */
+export function looksLikeWorkbook(bytes: Uint8Array): boolean {
+  const zip = [0x50, 0x4b, 0x03, 0x04];
+  const cfb = [0xd0, 0xcf, 0x11, 0xe0];
+  return [zip, cfb].some((signature) => signature.every((byte, index) => bytes[index] === byte));
+}
+
+/** SheetJS returns whatever the cell held — a date, a number, a formula result. */
+function toCellText(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  if (value instanceof Date) return value.toISOString().slice(0, 10);
+  return String(value);
+}
+
+class XlsxAdapter implements FileAdapter {
+  async load(source: ResolvedFileSource, context: AdapterLoadContext): Promise<XlsxDocument> {
+    let buffer: ArrayBuffer;
+    try {
+      buffer = await source.bytes(context.signal);
+    } catch (error) {
+      throw toViewerError(error, "read-failed", { fileName: source.name });
+    }
+
+    const bytes = new Uint8Array(buffer);
+    if (!looksLikeWorkbook(bytes)) {
+      throw new ViewerError("parse-failed", "The file is not a spreadsheet container.", {
+        fileName: source.name,
+      });
+    }
+
+    // Dynamic: the ONLY edge to the optional peer (heavy-deps:check).
+    const XLSX = await import("xlsx");
+
+    try {
+      // `cellDates` so a date column reads as a date rather than as Excel's
+      // serial day number, which is meaningless to a person looking at it.
+      const workbook = XLSX.read(bytes, { type: "array", cellDates: true });
+      const sheets = workbook.SheetNames.map((name) => {
+        const sheet = workbook.Sheets[name];
+        const grid: unknown[][] = sheet
+          ? XLSX.utils.sheet_to_json(sheet, { header: 1, blankrows: false, defval: "" })
+          : [];
+        const [header = [], ...body] = grid;
+        const columns = header.map(toCellText);
+        const rows = body.slice(0, XLSX_ROW_LIMIT).map((row) => row.map(toCellText));
+        return body.length > XLSX_ROW_LIMIT
+          ? { name, columns, rows, totalRows: body.length }
+          : { name, columns, rows };
+      });
+
+      if (sheets.length === 0) {
+        throw new ViewerError("parse-failed", "The workbook contains no sheets.", {
+          fileName: source.name,
+        });
+      }
+
+      // The projection is built by the shared grid builder rather than joined by
+      // hand, so the text a citation is addressed against and the map back into
+      // the cells cannot drift apart (`core/text-index.ts`).
+      const textIndex = gridToText(sheets);
+      return {
+        kind: "xlsx",
+        sheets,
+        pageCount: sheets.length,
+        text: textIndex.text,
+        textIndex,
+      };
+    } catch (error) {
+      throw toViewerError(error, "parse-failed", { fileName: source.name });
+    }
+  }
+}
+
+function XlsxRenderer({
+  document: doc,
+  className,
+  highlights,
+  activeHighlightId,
+}: AdapterRendererProps) {
+  const workbook = doc as XlsxDocument;
+  const { t } = useLocale();
+  const [first] = workbook.sheets;
+
+  const marks = useMemo(
+    () => toMarkRanges(highlights, workbook.text?.length ?? 0),
+    [highlights, workbook.text],
+  );
+
+  // Where each row of each sheet begins in the projection. Built once per
+  // document rather than per tab, because switching sheets must not re-walk the
+  // spans of every OTHER sheet to answer a question about this one.
+  const starts = useMemo(() => {
+    const bySheet = new Map<number, Map<number, number>>();
+    for (const span of workbook.textIndex?.spans ?? []) {
+      let rows = bySheet.get(span.ref.sheet);
+      if (!rows) {
+        rows = new Map<number, number>();
+        bySheet.set(span.ref.sheet, rows);
+      }
+      rows.set(span.ref.row, span.start);
+    }
+    return bySheet;
+  }, [workbook.textIndex]);
+  const rowStartFor = (sheet: number) => (row: number) => starts.get(sheet)?.get(row);
+
+  // Turning to the cited SHEET is this format's half of "take me there" — the
+  // row scroll inside it belongs to `SheetTable`. Keyed on the sheet NAME, so a
+  // reader who switches tabs while the same citation stays active is not
+  // dragged back (the PDF pager makes the same trade).
+  const activeSheet = useMemo(() => {
+    const active = highlights?.find((highlight) => highlight.id === activeHighlightId);
+    if (!active || active.status !== "resolved" || !active.range || !workbook.textIndex) {
+      return undefined;
+    }
+    return spanAt(workbook.textIndex, active.range[0])?.ref.sheet;
+  }, [highlights, activeHighlightId, workbook.textIndex]);
+  const activeSheetName =
+    activeSheet === undefined ? undefined : workbook.sheets[activeSheet]?.name;
+
+  const [pinned, setPinned] = useState<string>();
+  useEffect(() => {
+    if (activeSheetName !== undefined) setPinned(activeSheetName);
+  }, [activeSheetName]);
+
+  // A one-sheet workbook is the common case, and a tab strip holding a single
+  // tab is chrome that decides nothing — so it is not rendered.
+  if (!first) return null;
+  if (workbook.sheets.length === 1) {
+    return (
+      <SheetTable
+        columns={first.columns}
+        rows={first.rows}
+        totalRows={first.totalRows}
+        className={className}
+        marks={marks}
+        rowStart={rowStartFor(0)}
+        activeHighlightId={activeHighlightId}
+      />
+    );
+  }
+
+  return (
+    <Tabs
+      value={pinned ?? first.name}
+      onValueChange={setPinned}
+      className={cn("flex h-full min-h-0 flex-col gap-2", className)}
+    >
+      <TabsList aria-label={t("viewer.sheet.tabs")} className="shrink-0 self-start">
+        {workbook.sheets.map((sheet) => (
+          <TabsTrigger key={sheet.name} value={sheet.name}>
+            {sheet.name}
+          </TabsTrigger>
+        ))}
+      </TabsList>
+      {workbook.sheets.map((sheet, index) => (
+        <TabsContent key={sheet.name} value={sheet.name} className="mt-0 min-h-0 flex-1">
+          <SheetTable
+            columns={sheet.columns}
+            rows={sheet.rows}
+            totalRows={sheet.totalRows}
+            marks={marks}
+            rowStart={rowStartFor(index)}
+            activeHighlightId={activeHighlightId}
+          />
+        </TabsContent>
+      ))}
+    </Tabs>
+  );
+}
+
+const adapterModule: AdapterModule = {
+  manifest: xlsxManifest,
+  create: () => new XlsxAdapter(),
+  Renderer: XlsxRenderer,
+};
+
+export default adapterModule;

package/src/adapters/xlsx/xlsx-manifest.ts

@@ -0,0 +1,26 @@
+import { type AdapterManifest, PROTOCOL_VERSION } from "../../core/types";
+
+/**
+ * Excel workbooks. Data-only, eager — see `core/types.ts` for why the manifest
+ * and the loader are split.
+ *
+ * `.csv` is deliberately NOT claimed here even though SheetJS can read it: the
+ * `csv` adapter is a better answer for a delimited text file (it detects the
+ * delimiter and needs a far smaller parser), and claiming it would make which
+ * adapter wins depend on registration order.
+ */
+export const xlsxManifest: AdapterManifest = {
+  id: "xlsx",
+  protocol: PROTOCOL_VERSION,
+  extensions: ["xlsx", "xlsm", "xls", "ods"],
+  mediaTypes: [
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "application/vnd.ms-excel",
+    "application/vnd.oasis.opendocument.spreadsheet",
+  ],
+  // Addressed against the same grid projection the CSV adapter uses
+  // (`gridToText`), so a citation resolves the same way in a workbook and in the
+  // CSV export of one sheet. No `rect`: a cell has no page geometry.
+  capabilities: { pages: true, text: true, highlight: ["quote", "range"] },
+  requires: ["xlsx"],
+};

package/src/components/grid-text.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+
+import { chunkOffset } from "../core/text-index";
+import { GRID_CELL_SEPARATOR, GRID_HEAD_ROW, GRID_NAME_ROW, gridToText } from "./grid-text";
+
+/** `[the text this span covers, what it points at]` — the pair every test reads. */
+const mapped = ({ text, spans }: ReturnType<typeof gridToText>) =>
+  spans.map((span) => [text.slice(span.start, span.end), span.ref]);
+
+describe("gridToText", () => {
+  it("projects one nameless sheet as a header row and body rows", () => {
+    const index = gridToText([{ columns: ["Region", "Revenue"], rows: [["EMEA", "4.2M"]] }]);
+
+    expect(index.text).toBe("Region\tRevenue\nEMEA\t4.2M");
+    expect(mapped(index)).toEqual([
+      ["Region\tRevenue", { sheet: 0, row: GRID_HEAD_ROW }],
+      ["EMEA\t4.2M", { sheet: 0, row: 0 }],
+    ]);
+  });
+
+  it("separates sheets with a blank line and names each one", () => {
+    const index = gridToText([
+      { name: "Q3", columns: ["a"], rows: [["1"]] },
+      { name: "Q4", columns: ["b"], rows: [["2"]] },
+    ]);
+
+    expect(index.text).toBe("Q3\na\n1\n\nQ4\nb\n2");
+    expect(mapped(index)).toEqual([
+      ["Q3", { sheet: 0, row: GRID_NAME_ROW }],
+      ["a", { sheet: 0, row: GRID_HEAD_ROW }],
+      ["1", { sheet: 0, row: 0 }],
+      ["Q4", { sheet: 1, row: GRID_NAME_ROW }],
+      ["b", { sheet: 1, row: GRID_HEAD_ROW }],
+      ["2", { sheet: 1, row: 0 }],
+    ]);
+  });
+
+  it("puts the blank line before whatever the next sheet's FIRST line is", () => {
+    // The second sheet has no name, so the separator lands on its header.
+    const index = gridToText([
+      { columns: ["a"], rows: [] },
+      { columns: ["b"], rows: [] },
+    ]);
+    expect(index.text).toBe("a\n\nb");
+  });
+
+  it("skips a sheet with nothing in it rather than shifting every offset after it", () => {
+    const index = gridToText([
+      { columns: ["a"], rows: [] },
+      { columns: [], rows: [] },
+      { columns: ["b"], rows: [] },
+    ]);
+    expect(index.text).toBe("a\n\nb");
+    expect(index.spans.map((span) => span.ref.sheet)).toEqual([0, 2]);
+  });
+
+  it("keeps an empty cell in its row, so the cells after it stay put", () => {
+    const index = gridToText([{ columns: ["a", "b", "c"], rows: [["1", "", "3"]] }]);
+    const row = index.spans[1];
+
+    expect(index.text.slice(row?.start, row?.end)).toBe("1\t\t3");
+    // The third cell is where the projection says it is — an empty cell is a
+    // separator, not a hole (this is why rows, not cells, are the finest ref).
+    expect(chunkOffset(["1", "", "3"], 2, row?.start, GRID_CELL_SEPARATOR)).toBe(
+      index.text.indexOf("3"),
+    );
+  });
+});