@elabs-ai/components-viewer 4.0.0

package/src/core/registry.test.ts

@@ -0,0 +1,172 @@
+import type { FileCategory } from "@elabs-ai/components-ui";
+import { describe, expect, it, vi } from "vitest";
+
+import { isViewerError, ViewerError } from "./errors";
+import { createRegistry, scoreManifest } from "./registry";
+import { PROTOCOL_VERSION, type AdapterManifest, type AdapterModule } from "./types";
+
+const manifest = (over: Partial<AdapterManifest> & { id: string }): AdapterManifest => ({
+  protocol: PROTOCOL_VERSION,
+  ...over,
+});
+
+const moduleFor = (m: AdapterManifest): AdapterModule => ({
+  manifest: m,
+  create: () => ({ load: () => Promise.resolve({ kind: m.id }) }),
+  Renderer: () => null,
+});
+
+const kind = (extension: string, mediaType: string, category: FileCategory = "text") => ({
+  extension,
+  mediaType,
+  category,
+});
+
+describe("scoreManifest", () => {
+  it("ranks extension above exact MIME above MIME prefix above category", () => {
+    const file = kind("csv", "text/csv", "data");
+    expect(scoreManifest(manifest({ id: "a", extensions: ["csv"] }), file)).toBeGreaterThan(
+      scoreManifest(manifest({ id: "b", mediaTypes: ["text/csv"] }), file),
+    );
+    expect(scoreManifest(manifest({ id: "b", mediaTypes: ["text/csv"] }), file)).toBeGreaterThan(
+      scoreManifest(manifest({ id: "c", mediaTypes: ["text/"] }), file),
+    );
+    expect(scoreManifest(manifest({ id: "c", mediaTypes: ["text/"] }), file)).toBeGreaterThan(
+      scoreManifest(manifest({ id: "d", categories: ["data"] }), file),
+    );
+  });
+
+  it("scores zero when nothing matches", () => {
+    expect(scoreManifest(manifest({ id: "a", extensions: ["pdf"] }), kind("csv", "text/csv"))).toBe(
+      0,
+    );
+  });
+
+  it("treats a trailing slash as a prefix and nothing else as exact", () => {
+    const png = kind("png", "image/png", "image");
+    expect(scoreManifest(manifest({ id: "a", mediaTypes: ["image/"] }), png)).toBeGreaterThan(0);
+    // "image" without the slash must NOT match "image/png".
+    expect(scoreManifest(manifest({ id: "b", mediaTypes: ["image"] }), png)).toBe(0);
+  });
+});
+
+describe("registry — registration", () => {
+  it("rejects an adapter built against another protocol", () => {
+    const registry = createRegistry();
+    expect(() =>
+      registry.register({ id: "old", protocol: PROTOCOL_VERSION + 1 }, () =>
+        Promise.resolve(moduleFor(manifest({ id: "old" }))),
+      ),
+    ).toThrow(ViewerError);
+  });
+
+  it("replaces an entry with the same id, and drops its cached module", async () => {
+    const registry = createRegistry();
+    const first = manifest({ id: "x", extensions: ["x"] });
+    registry.register(first, () => Promise.resolve(moduleFor(first)));
+    await registry.load("x");
+
+    const second = manifest({ id: "x", extensions: ["x"] });
+    const secondLoader = vi.fn().mockResolvedValue(moduleFor(second));
+    registry.register(second, secondLoader);
+
+    await registry.load("x");
+    expect(secondLoader).toHaveBeenCalledTimes(1);
+    expect(registry.manifests()).toHaveLength(1);
+  });
+});
+
+describe("registry — detect", () => {
+  it("picks the most specific claim at equal priority", () => {
+    const registry = createRegistry();
+    const broad = manifest({ id: "text", categories: ["data"] });
+    const exact = manifest({ id: "csv", extensions: ["csv"] });
+    registry.register(broad, () => Promise.resolve(moduleFor(broad)));
+    registry.register(exact, () => Promise.resolve(moduleFor(exact)));
+
+    expect(registry.detectByName("rows.csv")?.id).toBe("csv");
+  });
+
+  it("lets a higher priority beat a more specific claim — that IS the override", () => {
+    const registry = createRegistry();
+    const builtin = manifest({ id: "csv", extensions: ["csv"] });
+    const override = manifest({ id: "mine", categories: ["data"], priority: 10 });
+    registry.register(builtin, () => Promise.resolve(moduleFor(builtin)));
+    registry.register(override, () => Promise.resolve(moduleFor(override)));
+
+    expect(registry.detectByName("rows.csv")?.id).toBe("mine");
+  });
+
+  it("returns undefined when nothing claims the file", () => {
+    const registry = createRegistry();
+    const only = manifest({ id: "img", categories: ["image"] });
+    registry.register(only, () => Promise.resolve(moduleFor(only)));
+    expect(registry.detectByName("notes.txt")).toBeUndefined();
+  });
+});
+
+describe("registry — load", () => {
+  it("caches the module, not the instance, so documents cannot share state", async () => {
+    const registry = createRegistry();
+    const m = manifest({ id: "x" });
+    const loader = vi.fn().mockResolvedValue(moduleFor(m));
+    registry.register(m, loader);
+
+    const [a, b] = await Promise.all([registry.load("x"), registry.load("x")]);
+    expect(loader).toHaveBeenCalledTimes(1);
+    expect(a).toBe(b);
+    expect(a.create()).not.toBe(b.create());
+  });
+
+  it("accepts a default export or a namespace export", async () => {
+    const registry = createRegistry();
+    const named = manifest({ id: "named" });
+    const defaulted = manifest({ id: "defaulted" });
+    registry.register(named, () => Promise.resolve(moduleFor(named)));
+    registry.register(defaulted, () => Promise.resolve({ default: moduleFor(defaulted) }));
+
+    expect((await registry.load("named")).manifest.id).toBe("named");
+    expect((await registry.load("defaulted")).manifest.id).toBe("defaulted");
+  });
+
+  it("reports an unknown id as unsupported-format", async () => {
+    const registry = createRegistry();
+    await expect(registry.load("nope")).rejects.toMatchObject({ code: "unsupported-format" });
+  });
+
+  it("turns a missing optional peer into parser-missing, naming the packages", async () => {
+    const registry = createRegistry();
+    const m = manifest({ id: "csv", requires: ["papaparse"] });
+    registry.register(m, () => Promise.reject(new Error("Cannot find module 'papaparse'")));
+
+    await expect(registry.load("csv")).rejects.toMatchObject({
+      code: "parser-missing",
+      packages: ["papaparse"],
+    });
+  });
+
+  it("does not cache a failed load — installing the peer later must work", async () => {
+    const registry = createRegistry();
+    const m = manifest({ id: "csv", requires: ["papaparse"] });
+    const loader = vi
+      .fn()
+      .mockRejectedValueOnce(new Error("Cannot find module 'papaparse'"))
+      .mockResolvedValueOnce(moduleFor(m));
+    registry.register(m, loader);
+
+    await expect(registry.load("csv")).rejects.toBeDefined();
+    expect((await registry.load("csv")).manifest.id).toBe("csv");
+    expect(loader).toHaveBeenCalledTimes(2);
+  });
+
+  it("rejects a module whose manifest disagrees with the registered protocol", async () => {
+    const registry = createRegistry();
+    const m = manifest({ id: "x" });
+    registry.register(m, () =>
+      Promise.resolve(moduleFor({ ...m, protocol: PROTOCOL_VERSION + 1 })),
+    );
+
+    const error = await registry.load("x").catch((e: unknown) => e);
+    expect(isViewerError(error) && error.code).toBe("protocol-mismatch");
+  });
+});

package/src/core/registry.ts

@@ -0,0 +1,188 @@
+/**
+ * The adapter registry — how a file finds its renderer.
+ *
+ * Architecture adapted from [anyview](https://github.com/harshpreet931/anyview)
+ * (MIT). Four properties are what make it work, and all four are deliberate:
+ *
+ * 1. **Eager manifests, lazy loaders.** Routing and capability questions are
+ *    answered from plain data; the parser is fetched only when a file of that
+ *    kind is actually opened.
+ * 2. **Priority override.** A consumer replaces a built-in by registering a
+ *    higher priority — no fork, no patch.
+ * 3. **A fresh adapter per document.** The module (and its parser) is cached;
+ *    the instance is not, so per-document state cannot leak between files.
+ * 4. **A protocol guard.** A mismatched adapter fails with a named error at
+ *    registration, not with an undefined property at render.
+ */
+
+import { type FileKind, resolveFileKind } from "@elabs-ai/components-ui";
+
+import { ViewerError, isModuleNotFound, parserMissingError, toViewerError } from "./errors";
+import {
+  type AdapterLoader,
+  type AdapterManifest,
+  type AdapterModule,
+  PROTOCOL_VERSION,
+} from "./types";
+
+/**
+ * How specifically a manifest claimed a file. Higher is more specific.
+ * A plain object rather than a `const enum` — the repo builds with
+ * `isolatedModules`, which cannot inline one.
+ */
+const MatchScore = {
+  None: 0,
+  Category: 1,
+  MediaTypePrefix: 2,
+  MediaType: 3,
+  Extension: 4,
+} as const;
+
+type MatchScore = (typeof MatchScore)[keyof typeof MatchScore];
+
+interface Entry {
+  manifest: AdapterManifest;
+  loader: AdapterLoader;
+}
+
+/** A registry of file adapters. Create with {@link createRegistry}. */
+export interface ViewerRegistry {
+  /**
+   * Add an adapter, or replace one with the same `id`.
+   *
+   * Replacement is by id and unconditional — the caller asked for it. Priority
+   * governs which of several DIFFERENT adapters wins a file, not whether a
+   * registration takes effect.
+   *
+   * @throws {ViewerError} `protocol-mismatch` if the manifest targets another protocol.
+   */
+  register(manifest: AdapterManifest, loader: AdapterLoader): void;
+  /**
+   * Every registered manifest, highest priority first. Not the routing order —
+   * specificity is per-file, so only {@link detect} can rank for a given file.
+   */
+  manifests(): AdapterManifest[];
+  /** The manifest that should open this file, or `undefined` if none claims it. */
+  detect(kind: FileKind): AdapterManifest | undefined;
+  /** Convenience over {@link detect} for a name + MIME. */
+  detectByName(name: string, mediaType?: string): AdapterManifest | undefined;
+  /**
+   * Fetch an adapter module by id, caching the MODULE (never an instance).
+   *
+   * @throws {ViewerError} `unsupported-format` when the id is unknown,
+   * `parser-missing` when the module's optional peer is not installed,
+   * `protocol-mismatch` when the loaded module disagrees with its manifest.
+   */
+  load(id: string): Promise<AdapterModule>;
+}
+
+/** How well `manifest` claims `kind`. `MatchScore.None` means "not mine". */
+export function scoreManifest(manifest: AdapterManifest, kind: FileKind): MatchScore {
+  if (kind.extension && manifest.extensions?.includes(kind.extension)) {
+    return MatchScore.Extension;
+  }
+  for (const declared of manifest.mediaTypes ?? []) {
+    if (declared.endsWith("/")) {
+      if (kind.mediaType.startsWith(declared)) return MatchScore.MediaTypePrefix;
+    } else if (declared === kind.mediaType) {
+      return MatchScore.MediaType;
+    }
+  }
+  if (manifest.categories?.includes(kind.category)) return MatchScore.Category;
+  return MatchScore.None;
+}
+
+/** Unwrap `export default` vs named exports, so an adapter can use either. */
+function unwrap(loaded: AdapterModule | { default: AdapterModule }): AdapterModule {
+  return "default" in loaded && loaded.default ? loaded.default : (loaded as AdapterModule);
+}
+
+function assertProtocol(manifest: AdapterManifest, where: string): void {
+  if (manifest.protocol !== PROTOCOL_VERSION) {
+    throw new ViewerError(
+      "protocol-mismatch",
+      `Adapter "${manifest.id}" targets viewer protocol ${String(manifest.protocol)}, but this build speaks ${String(PROTOCOL_VERSION)} (${where}).`,
+    );
+  }
+}
+
+/**
+ * Create an empty registry.
+ *
+ * Empty on purpose: the built-ins live in `createDefaultRegistry()`
+ * (`src/adapters`), so a consumer who wants only their own adapters — or only
+ * images — never pulls in the rest.
+ */
+export function createRegistry(): ViewerRegistry {
+  const entries = new Map<string, Entry>();
+  const modules = new Map<string, Promise<AdapterModule>>();
+
+  function ordered(): Entry[] {
+    return [...entries.values()].sort(
+      (a, b) => (b.manifest.priority ?? 0) - (a.manifest.priority ?? 0),
+    );
+  }
+
+  function detect(kind: FileKind): AdapterManifest | undefined {
+    let best: { manifest: AdapterManifest; score: MatchScore; priority: number } | undefined;
+    for (const { manifest } of entries.values()) {
+      const score = scoreManifest(manifest, kind);
+      if (score === MatchScore.None) continue;
+      const priority = manifest.priority ?? 0;
+      // Priority is the consumer's explicit override, so it outranks how
+      // specifically an adapter happened to claim the file.
+      const wins =
+        !best || priority > best.priority || (priority === best.priority && score > best.score);
+      if (wins) best = { manifest, score, priority };
+    }
+    return best?.manifest;
+  }
+
+  return {
+    register(manifest, loader) {
+      assertProtocol(manifest, "registration");
+      entries.set(manifest.id, { manifest, loader });
+      // A replaced id must not keep serving the old module.
+      modules.delete(manifest.id);
+    },
+
+    manifests() {
+      return ordered().map((entry) => entry.manifest);
+    },
+
+    detect,
+
+    detectByName(name, mediaType) {
+      return detect(resolveFileKind(name, mediaType));
+    },
+
+    async load(id) {
+      const entry = entries.get(id);
+      if (!entry) {
+        throw new ViewerError("unsupported-format", `No adapter is registered for "${id}".`);
+      }
+
+      let pending = modules.get(id);
+      if (!pending) {
+        pending = entry
+          .loader()
+          .then((loaded) => {
+            const adapterModule = unwrap(loaded);
+            assertProtocol(adapterModule.manifest, `module "${id}"`);
+            return adapterModule;
+          })
+          .catch((error: unknown) => {
+            // Not cached: an optional peer installed later, or a transient
+            // chunk-load failure, must be retryable without a page reload.
+            modules.delete(id);
+            if (isModuleNotFound(error)) {
+              throw parserMissingError(id, entry.manifest.requires ?? [], { cause: error });
+            }
+            throw toViewerError(error, "parse-failed");
+          });
+        modules.set(id, pending);
+      }
+      return pending;
+    },
+  };
+}

package/src/core/scroll-host.ts

@@ -0,0 +1,42 @@
+/**
+ * Finding the element a renderer actually scrolls inside.
+ *
+ * `FileViewerContent` is THE scroll boundary (`viewer-components.md`), and now
+ * that page and zoom chrome lives in the shell (ADR 0026) even the PDF adapter
+ * no longer has fixed controls of its own to justify a second viewport. But a
+ * renderer still has to MEASURE that box — a fit-to-width scale is a function of
+ * the viewport's width, and a virtualized page list is a function of its height.
+ *
+ * Resolved from the DOM rather than passed as a prop because a renderer may be
+ * mounted anywhere: inside the shell, inside a consumer's own frame, or bare in
+ * a test. Same shape as extend-hq/ui's `resolveScrollAreaViewport`.
+ */
+
+/** The `data-slot` the shell's scrolling pane carries. */
+export const SCROLL_HOST_SELECTOR = '[data-slot="file-viewer-content"]';
+
+/**
+ * The nearest scrolling ancestor of `node`.
+ *
+ * Prefers the shell's pane by its stable `data-slot`; falls back to the first
+ * ancestor whose computed overflow actually scrolls, so a renderer composed into
+ * someone else's frame still measures the right box. `null` when nothing
+ * scrolls — the caller should then fall back to its own element.
+ */
+export function findScrollHost(node: Element | null | undefined): HTMLElement | null {
+  if (!node) return null;
+  const shell = node.closest<HTMLElement>(SCROLL_HOST_SELECTOR);
+  if (shell) return shell;
+
+  const view = node.ownerDocument?.defaultView;
+  if (!view) return null;
+  let current = node.parentElement;
+  while (current) {
+    const { overflowY, overflowX } = view.getComputedStyle(current);
+    if (/(auto|scroll|overlay)/.test(overflowY) || /(auto|scroll|overlay)/.test(overflowX)) {
+      return current;
+    }
+    current = current.parentElement;
+  }
+  return null;
+}

package/src/core/text-index.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from "vitest";
+
+import { createTextIndexBuilder, spanAt, spansForRange } from "./text-index";
+
+/** Three blocks, the shape every text-bearing adapter builds. */
+function blocks() {
+  const builder = createTextIndexBuilder<number>();
+  builder.push("first block", 0);
+  builder.push("second", 1);
+  builder.push("third one", 2);
+  return builder.build();
+}
+
+describe("createTextIndexBuilder", () => {
+  it("produces the projection AND its map from the same pass", () => {
+    // The point of the builder: the text an adapter reports and the offsets it
+    // maps back cannot disagree, because one is built out of the other.
+    const index = blocks();
+    expect(index.text).toBe("first block\nsecond\nthird one");
+    for (const span of index.spans) {
+      expect(index.text.slice(span.start, span.end)).not.toBe("");
+    }
+    expect(index.text.slice(11, 12)).toBe("\n");
+  });
+
+  it("gives the separator to nobody, so no highlight spans a joint", () => {
+    const index = blocks();
+    // The gap between block 0's end and block 1's start is the separator.
+    expect(index.spans[0]?.end).toBe(11);
+    expect(index.spans[1]?.start).toBe(12);
+    expect(spanAt(index, 11)).toBeUndefined();
+  });
+
+  it("skips an empty chunk rather than emitting a span that matches nothing", () => {
+    const builder = createTextIndexBuilder<string>();
+    builder.push("a", "kept");
+    builder.push("", "dropped");
+    builder.push("b", "kept-too");
+    const index = builder.build();
+    expect(index.text).toBe("a\nb");
+    expect(index.spans.map((span) => span.ref)).toEqual(["kept", "kept-too"]);
+  });
+
+  it("honours a custom separator", () => {
+    const builder = createTextIndexBuilder<number>({ separator: "\n\n" });
+    builder.push("a", 0);
+    builder.push("b", 1);
+    expect(builder.build().text).toBe("a\n\nb");
+  });
+
+  it("builds an empty index from no chunks at all", () => {
+    expect(createTextIndexBuilder<number>().build()).toEqual({ text: "", spans: [] });
+  });
+});
+
+describe("spansForRange", () => {
+  it("clips the overlap to each chunk's OWN offsets", () => {
+    // What a renderer needs: not "812–847 of the document" but "characters 6–11
+    // of block 0", which is the only thing it can pass to its own markup.
+    const index = blocks();
+    expect(spansForRange(index, [6, 11])).toEqual([{ span: index.spans[0], start: 6, end: 11 }]);
+  });
+
+  it("splits a range that crosses a block boundary", () => {
+    const index = blocks();
+    const overlaps = spansForRange(index, [6, 15]);
+    expect(overlaps.map((overlap) => overlap.span.ref)).toEqual([0, 1]);
+    expect(overlaps[0]).toMatchObject({ start: 6, end: 11 });
+    // Block 1 starts at 12; the range reaches 15, so three of its characters.
+    expect(overlaps[1]).toMatchObject({ start: 0, end: 3 });
+  });
+
+  it("returns nothing for an empty or inverted range", () => {
+    const index = blocks();
+    expect(spansForRange(index, [5, 5])).toEqual([]);
+    expect(spansForRange(index, [9, 4])).toEqual([]);
+  });
+
+  it("returns nothing for a range past the end", () => {
+    expect(spansForRange(blocks(), [500, 600])).toEqual([]);
+  });
+});
+
+describe("spanAt", () => {
+  it("finds the chunk an offset lands in", () => {
+    const index = blocks();
+    expect(spanAt(index, 0)?.ref).toBe(0);
+    expect(spanAt(index, 12)?.ref).toBe(1);
+    expect(spanAt(index, 27)?.ref).toBe(2);
+  });
+
+  it("is undefined past the last chunk", () => {
+    expect(spanAt(blocks(), 999)).toBeUndefined();
+  });
+});

package/src/core/text-index.ts

@@ -0,0 +1,159 @@
+/**
+ * The map from a document's flat text projection back into its own model.
+ *
+ * `AdapterDocument.text` is the address space every text-based highlight is
+ * expressed in — but a renderer does not draw a flat string. It draws Word
+ * blocks, PDF pages, spreadsheet cells, code lines. So "characters 812–847 of
+ * the projection" has to become "the second half of block 14" before anything
+ * can be painted, and only the adapter knows how.
+ *
+ * That translation is the same bookkeeping every time — running offsets, a
+ * separator between chunks, a lookup by position — so it is written once here
+ * and each adapter supplies only its own `ref` type: a block index, a page
+ * number, a `{ sheet, row, column }` triple. The builder is what guarantees the
+ * projection and the index can never disagree, because the projection is its
+ * output rather than a second thing assembled by hand.
+ */
+
+import type { MatchRange } from "@elabs-ai/components-ui";
+
+/** One chunk of the projection, and what it came from. */
+export interface TextSpan<TRef> {
+  /** Half-open `[start, end)` into the projection's text. */
+  start: number;
+  end: number;
+  /** The adapter's own pointer back into its model. */
+  ref: TRef;
+}
+
+/** A flat text projection plus the way back into the model that produced it. */
+export interface TextIndex<TRef> {
+  text: string;
+  /** Sorted by `start`, non-overlapping. Gaps are the separators between chunks. */
+  spans: readonly TextSpan<TRef>[];
+}
+
+export interface TextIndexBuilderOptions {
+  /**
+   * Written between chunks and owned by no span, so a highlight can never be
+   * reported as covering the joint between two blocks. `"\n"` by default.
+   */
+  separator?: string;
+}
+
+export interface TextIndexBuilder<TRef> {
+  /**
+   * Append a chunk. Empty chunks are skipped — an empty span matches nothing.
+   *
+   * `separator` overrides the builder's default for THIS joint only, which is
+   * how a multi-level projection stays one index: a workbook joins cells with a
+   * tab, rows with a newline and sheets with a blank line, and stitching three
+   * separate indexes together afterwards is exactly the offset bookkeeping this
+   * module exists to do once.
+   */
+  push(chunk: string, ref: TRef, separator?: string): void;
+  build(): TextIndex<TRef>;
+}
+
+/** Assemble a projection and its index together, so they cannot drift apart. */
+export function createTextIndexBuilder<TRef>(
+  options: TextIndexBuilderOptions = {},
+): TextIndexBuilder<TRef> {
+  const fallback = options.separator ?? "\n";
+  const parts: string[] = [];
+  const spans: TextSpan<TRef>[] = [];
+  let cursor = 0;
+
+  return {
+    push(chunk, ref, separator = fallback) {
+      if (chunk.length === 0) return;
+      if (parts.length > 0) {
+        parts.push(separator);
+        cursor += separator.length;
+      }
+      parts.push(chunk);
+      spans.push({ start: cursor, end: cursor + chunk.length, ref });
+      cursor += chunk.length;
+    },
+    build() {
+      return { text: parts.join(""), spans };
+    },
+  };
+}
+
+/** A span a range touches, with the overlap expressed in the CHUNK's own offsets. */
+export interface SpanOverlap<TRef> {
+  span: TextSpan<TRef>;
+  /** Offset into the chunk, not into the projection. */
+  start: number;
+  end: number;
+}
+
+/** Index of the first span ending after `offset`, or `spans.length`. */
+function lowerBound<TRef>(spans: readonly TextSpan<TRef>[], offset: number): number {
+  let lo = 0;
+  let hi = spans.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if ((spans[mid] as TextSpan<TRef>).end <= offset) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
+
+/**
+ * Every chunk a projection range touches, clipped to that chunk.
+ *
+ * Binary search rather than a scan: a highlighted sentence in a 5,000-cell
+ * spreadsheet touches one or two spans, and walking all 5,000 to find them —
+ * once per highlight, on every render — is what makes a find-as-you-type box
+ * stutter.
+ */
+export function spansForRange<TRef>(
+  index: TextIndex<TRef>,
+  [start, end]: MatchRange,
+): SpanOverlap<TRef>[] {
+  if (end <= start) return [];
+  const out: SpanOverlap<TRef>[] = [];
+  for (let i = lowerBound(index.spans, start); i < index.spans.length; i += 1) {
+    const span = index.spans[i] as TextSpan<TRef>;
+    if (span.start >= end) break;
+    out.push({
+      span,
+      start: Math.max(start, span.start) - span.start,
+      end: Math.min(end, span.end) - span.start,
+    });
+  }
+  return out;
+}
+
+/**
+ * Where the `index`-th part of a joined string begins, given where the join
+ * begins.
+ *
+ * The counterpart of pushing a whole row as one chunk: the REF can be the row
+ * while the MARK is still the character, because a cell's offset is the sum of
+ * the cells before it plus their separators. Used by every renderer that draws
+ * one chunk in several pieces — a Word table row, a spreadsheet row, a
+ * paragraph's styled runs. `undefined` in, `undefined` out, so a caller with no
+ * index does not need a branch.
+ */
+export function chunkOffset(
+  parts: readonly string[],
+  index: number,
+  start: number | undefined,
+  separator: string,
+): number | undefined {
+  if (start === undefined) return undefined;
+  let offset = start;
+  for (let i = 0; i < index; i += 1) {
+    offset += (parts[i]?.length ?? 0) + separator.length;
+  }
+  return offset;
+}
+
+/** The chunk containing `offset`, or `undefined` when it lands on a separator. */
+export function spanAt<TRef>(index: TextIndex<TRef>, offset: number): TextSpan<TRef> | undefined {
+  const span = index.spans[lowerBound(index.spans, offset)];
+  return span && span.start <= offset ? span : undefined;
+}