@elabs-ai/components-viewer 4.0.0

package/src/core/highlight-resolve.test.ts

@@ -0,0 +1,208 @@
+import { normalizeQuoteTextWithOffsets, type DocumentAddress } from "@elabs-ai/components-ui";
+import { describe, expect, it } from "vitest";
+
+import type { DocumentHighlight, HighlightSupport } from "./highlight";
+import { locateQuote, resolveHighlights, type HighlightResolveContext } from "./highlight-resolve";
+
+const DOCUMENT = "Revenue rose 12% in Q3.\nCosts fell.\nRevenue rose again in Q4.";
+
+const ALL_KINDS: HighlightSupport = ["quote", "range", "rect"];
+
+function context(overrides: Partial<HighlightResolveContext> = {}): HighlightResolveContext {
+  return {
+    normalized: normalizeQuoteTextWithOffsets(DOCUMENT),
+    textLength: DOCUMENT.length,
+    supported: ALL_KINDS,
+    ...overrides,
+  };
+}
+
+function cite(id: string, address: DocumentAddress): DocumentHighlight {
+  return { id, address };
+}
+
+describe("locateQuote", () => {
+  const normalized = normalizeQuoteTextWithOffsets(DOCUMENT);
+
+  it("finds a passage whose whitespace and case do not match the file", () => {
+    // What a model actually emits: re-wrapped, re-cased, re-typed.
+    const range = locateQuote(normalized, { kind: "quote", text: "  COSTS\n  fell " });
+    expect(range && DOCUMENT.slice(range[0], range[1])).toBe("Costs fell");
+  });
+
+  it("finds a passage whose quote glyphs do not match the file", () => {
+    const file = normalizeQuoteTextWithOffsets(`He said "no" — twice`);
+    const range = locateQuote(file, { kind: "quote", text: "“no” – twice" });
+    expect(range && `He said "no" — twice`.slice(range[0], range[1])).toBe(`"no" — twice`);
+  });
+
+  it("takes the first occurrence by default", () => {
+    const range = locateQuote(normalized, { kind: "quote", text: "Revenue rose" });
+    expect(range?.[0]).toBe(0);
+  });
+
+  it("takes the occurrence the caller asked for", () => {
+    const range = locateQuote(normalized, {
+      kind: "quote",
+      text: "Revenue rose",
+      occurrence: 2,
+    });
+    expect(range?.[0]).toBe(DOCUMENT.lastIndexOf("Revenue rose"));
+  });
+
+  it("misses rather than falling back when the occurrence does not exist", () => {
+    // Quietly marking the first would be a confidently wrong citation.
+    expect(
+      locateQuote(normalized, { kind: "quote", text: "Revenue rose", occurrence: 9 }),
+    ).toBeUndefined();
+  });
+
+  it("uses `near.offset` to pick between repeats", () => {
+    const range = locateQuote(normalized, {
+      kind: "quote",
+      text: "Revenue rose",
+      near: { offset: DOCUMENT.length },
+    });
+    expect(range?.[0]).toBe(DOCUMENT.lastIndexOf("Revenue rose"));
+  });
+
+  it("still finds a passage that is nowhere near the hint", () => {
+    // `near` disambiguates; it does not restrict.
+    const range = locateQuote(normalized, {
+      kind: "quote",
+      text: "Costs fell",
+      near: { offset: 0 },
+    });
+    expect(range && DOCUMENT.slice(range[0], range[1])).toBe("Costs fell");
+  });
+
+  it("returns nothing for an absent or empty passage", () => {
+    expect(locateQuote(normalized, { kind: "quote", text: "profit" })).toBeUndefined();
+    expect(locateQuote(normalized, { kind: "quote", text: "   " })).toBeUndefined();
+  });
+});
+
+describe("resolveHighlights", () => {
+  it("reports a kind the adapter never declared as a capability gap", () => {
+    // Not a failure and not retryable — the file is fine, this build simply
+    // cannot draw a box on a Word document.
+    const [resolved] = resolveHighlights(
+      [cite("a", { kind: "rect", page: 1, rects: [{ x: 0, y: 0, width: 1, height: 1 }] })],
+      context({ supported: ["quote"] }),
+    );
+    expect(resolved?.status).toBe("unsupported");
+  });
+
+  it("tells 'not in the document' apart from 'past what we previewed'", () => {
+    const address: DocumentAddress = { kind: "quote", text: "nowhere" };
+    expect(resolveHighlights([cite("a", address)], context())[0]).toMatchObject({
+      status: "not-found",
+      reason: "absent",
+    });
+    expect(resolveHighlights([cite("a", address)], context({ truncated: true }))[0]).toMatchObject({
+      status: "not-found",
+      reason: "truncated",
+    });
+  });
+
+  it("clamps a range to the projection, and calls an emptied one a miss", () => {
+    const [clamped] = resolveHighlights(
+      [cite("a", { kind: "range", start: 5, end: 5000 })],
+      context(),
+    );
+    expect(clamped).toMatchObject({ status: "resolved", range: [5, DOCUMENT.length] });
+
+    // Offsets computed against a LONGER projection than the one we have: the
+    // clamp collapses them, and a zero-width mark would point at nothing.
+    const [collapsed] = resolveHighlights(
+      [cite("b", { kind: "range", start: 900, end: 950 })],
+      context(),
+    );
+    expect(collapsed?.status).toBe("not-found");
+  });
+
+  it("never lets a producer's page HINT stand in for where the passage landed", () => {
+    // The regression this locks: `page` was copied off the address, and the PDF
+    // renderer prefers `ResolvedHighlight.page` over its own index — so a stale
+    // hint turned the reader to a blank page while the mark sat somewhere else.
+    // Both fields are documented as hints; only `rect` may say where it is.
+    const [byRange] = resolveHighlights(
+      [cite("a", { kind: "range", start: 0, end: 5, page: 99 })],
+      context(),
+    );
+    expect(byRange).toMatchObject({ status: "resolved", range: [0, 5] });
+    expect(byRange?.page).toBeUndefined();
+
+    const [byQuote] = resolveHighlights(
+      [cite("b", { kind: "quote", text: "Costs fell", near: { page: 99 } })],
+      context(),
+    );
+    expect(byQuote?.status).toBe("resolved");
+    expect(byQuote?.page).toBeUndefined();
+  });
+
+  it("passes a rect straight through — geometry needs no text", () => {
+    const rects = [{ x: 0.1, y: 0.2, width: 0.3, height: 0.05 }];
+    const [resolved] = resolveHighlights(
+      [cite("a", { kind: "rect", page: 3, rects })],
+      context({ normalized: undefined, textLength: undefined }),
+    );
+    expect(resolved).toMatchObject({ status: "resolved", page: 3, rects });
+  });
+
+  it("orders by position in the DOCUMENT, not by the order asked for", () => {
+    // "Next match" has to mean the next one down the page; an app listing
+    // citations by relevance would otherwise send the reader backwards.
+    const resolved = resolveHighlights(
+      [cite("late", { kind: "quote", text: "Q4" }), cite("early", { kind: "quote", text: "Q3" })],
+      context(),
+    );
+    expect(resolved.map((highlight) => highlight.id)).toEqual(["early", "late"]);
+  });
+
+  it("numbers per source, so the find count never includes citations", () => {
+    const resolved = resolveHighlights(
+      [
+        cite("c1", { kind: "quote", text: "Revenue" }),
+        { id: "f1", source: "search", address: { kind: "range", start: 24, end: 29 } },
+        { id: "f2", source: "search", address: { kind: "range", start: 35, end: 42 } },
+      ],
+      context(),
+    );
+    const byId = new Map(resolved.map((highlight) => [highlight.id, highlight]));
+    expect(byId.get("c1")?.index).toBe(1);
+    expect(byId.get("f1")?.index).toBe(1);
+    expect(byId.get("f2")?.index).toBe(2);
+  });
+
+  it("does not let a miss consume a number the reader is counting through", () => {
+    const resolved = resolveHighlights(
+      [
+        cite("hit", { kind: "quote", text: "Revenue rose 12%" }),
+        cite("miss", { kind: "quote", text: "profit" }),
+        cite("hit2", { kind: "quote", text: "Q4" }),
+      ],
+      context(),
+    );
+    const byId = new Map(resolved.map((highlight) => [highlight.id, highlight]));
+    expect(byId.get("hit")?.index).toBe(1);
+    expect(byId.get("hit2")?.index).toBe(2);
+    expect(byId.get("miss")?.index).toBeUndefined();
+  });
+
+  it("flags exactly the active one", () => {
+    const resolved = resolveHighlights(
+      [cite("a", { kind: "quote", text: "Q3" }), cite("b", { kind: "quote", text: "Q4" })],
+      context({ activeId: "b" }),
+    );
+    expect(resolved.filter((highlight) => highlight.active).map((h) => h.id)).toEqual(["b"]);
+  });
+
+  it("keeps the request on a miss, so the chrome has something to name", () => {
+    const [resolved] = resolveHighlights(
+      [{ id: "a", label: "Q2 guidance", address: { kind: "quote", text: "nowhere" } }],
+      context(),
+    );
+    expect(resolved).toMatchObject({ label: "Q2 guidance", address: { kind: "quote" } });
+  });
+});

package/src/core/highlight-resolve.ts

@@ -0,0 +1,191 @@
+/**
+ * Turning a request into a location — the LOCATE step, and the only step that
+ * runs outside the adapter.
+ *
+ * The funnel is three stages with three homes. **Locate** (here) answers "where
+ * in the text projection is this?" and produces character offsets. **Map** (the
+ * adapter's renderer) turns those offsets into its own model — block 14, page 3,
+ * cell B7. **Paint** (also the renderer) draws it and scrolls to it.
+ *
+ * Locate lives in the shell rather than in each adapter because its OUTCOME is
+ * chrome state, not pixels: "3 of 12", "we couldn't find that passage", "this
+ * build can't locate a box in a Word file". Every adapter would otherwise write
+ * that logic again, slightly differently, and the shell would have no way to
+ * count what it is showing. It is also pure — no DOM, no engine — so it is
+ * testable without jsdom.
+ */
+
+import {
+  normalizeQuoteText,
+  type MatchRange,
+  type NormalizedText,
+  type QuoteAddress,
+} from "@elabs-ai/components-ui";
+
+import type { DocumentHighlight, HighlightSupport, ResolvedHighlight } from "./highlight";
+
+/**
+ * Find a quoted passage in a normalized projection and map it back to raw
+ * offsets.
+ *
+ * Both sides are folded first (whitespace, quote glyphs, case), because a
+ * citation is re-typed by a model or extracted by a different tool and will
+ * essentially never be byte-identical to what our parser produced.
+ *
+ * Ambiguity is resolved by the caller's own hints and never guessed at: an
+ * explicit `occurrence` wins, then proximity to `near.offset`, then the first
+ * match. Returning the first match silently would put a citation on the wrong
+ * paragraph of a document that repeats a heading.
+ */
+export function locateQuote(
+  normalized: NormalizedText,
+  address: QuoteAddress,
+): MatchRange | undefined {
+  const needle = normalizeQuoteText(address.text);
+  if (needle.length === 0) return undefined;
+
+  const starts: number[] = [];
+  for (let at = normalized.text.indexOf(needle); at !== -1; ) {
+    starts.push(at);
+    // Step by one, not by the needle's length: overlapping occurrences of a
+    // repeated phrase ("na na na") are still distinct places in the document.
+    at = normalized.text.indexOf(needle, at + 1);
+  }
+  if (starts.length === 0) return undefined;
+
+  const toRange = (start: number): MatchRange => [
+    normalized.offsets[start] as number,
+    normalized.offsets[start + needle.length] as number,
+  ];
+
+  if (address.occurrence !== undefined) {
+    const chosen = starts[address.occurrence - 1];
+    // An out-of-range occurrence is a miss, not a fallback to the first: the
+    // caller asked for the fourth of three, and quietly marking the first would
+    // be a confidently wrong citation.
+    return chosen === undefined ? undefined : toRange(chosen);
+  }
+
+  const near = address.near?.offset;
+  if (near !== undefined) {
+    let best = starts[0] as number;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const start of starts) {
+      const distance = Math.abs((normalized.offsets[start] as number) - near);
+      if (distance < bestDistance) {
+        bestDistance = distance;
+        best = start;
+      }
+    }
+    return toRange(best);
+  }
+
+  return toRange(starts[0] as number);
+}
+
+export interface HighlightResolveContext {
+  /**
+   * The document's text projection, folded once with its offset map. Absent
+   * when the format has no text projection at all.
+   *
+   * Pre-folded rather than raw because find-in-document re-resolves on every
+   * keystroke, and folding a 2 MB projection per keystroke is what turns a
+   * search box into a stutter.
+   */
+  normalized?: NormalizedText;
+  /** Length of the RAW projection, for clamping `range` addresses. */
+  textLength?: number;
+  /** Whether that projection is capped, which changes what a miss MEANS. */
+  truncated?: boolean;
+  /** Which address kinds this document's adapter honours. */
+  supported: HighlightSupport;
+  /** The highlight the viewer is currently pointed at. */
+  activeId?: string | null;
+}
+
+/** Sort key: where in the document this landed. Unresolved sorts last. */
+function positionOf(highlight: ResolvedHighlight): number {
+  if (highlight.range) return highlight.range[0];
+  if (highlight.page !== undefined) return highlight.page;
+  return Number.POSITIVE_INFINITY;
+}
+
+function resolveOne(
+  highlight: DocumentHighlight,
+  context: HighlightResolveContext,
+): ResolvedHighlight {
+  const source = highlight.source ?? "citation";
+  const address = highlight.address;
+  const base = { id: highlight.id, label: highlight.label, source, address, active: false };
+
+  // The load-bearing contract: match only the kinds this adapter DECLARED, and
+  // report the rest. No exhaustive switch, no `never` fallthrough — that is
+  // what lets a fourth address kind be added later without breaking every
+  // consumer that predates it.
+  if (!context.supported.includes(address.kind)) {
+    return { ...base, status: "unsupported" };
+  }
+
+  if (address.kind === "rect") {
+    // Geometry needs no text and cannot fail to "locate" — whether the page
+    // exists is the renderer's business, since only it knows the page count.
+    return { ...base, status: "resolved", page: address.page, rects: address.rects };
+  }
+
+  const miss = (): ResolvedHighlight => ({
+    ...base,
+    status: "not-found",
+    reason: context.truncated ? "truncated" : "absent",
+  });
+
+  if (address.kind === "range") {
+    const length = context.textLength;
+    if (length === undefined) return miss();
+    const start = Math.max(0, Math.min(address.start, length));
+    const end = Math.max(start, Math.min(address.end, length));
+    // A range clamped to nothing is a miss, not a zero-width mark: the offsets
+    // were computed against a longer projection than the one we have.
+    if (end === start) return miss();
+    // No `page`. A producer's page number is a hint, and a wrong one used as an
+    // instruction turns the pager to a blank page while the mark sits elsewhere.
+    // Where the range actually landed is knowable from the adapter's own index,
+    // so that is what navigation uses; `page` stays authoritative only for
+    // `rect`, which has no range to derive it from.
+    return { ...base, status: "resolved", range: [start, end] };
+  }
+
+  if (!context.normalized) return miss();
+  const range = locateQuote(context.normalized, address);
+  if (!range) return miss();
+  return { ...base, status: "resolved", range };
+}
+
+/**
+ * Resolve every request, in document order, numbered per source.
+ *
+ * Document order rather than the caller's, because "next match" has to mean the
+ * next one down the page — an app listing citations in relevance order would
+ * otherwise send the reader jumping backwards. Numbering is per `source` so the
+ * find box's "3 of 12" counts search matches only, and never the citations
+ * painted beside them.
+ */
+export function resolveHighlights(
+  highlights: readonly DocumentHighlight[],
+  context: HighlightResolveContext,
+): ResolvedHighlight[] {
+  const resolved = highlights
+    .map((highlight) => resolveOne(highlight, context))
+    .sort((a, b) => positionOf(a) - positionOf(b));
+
+  const counters = new Map<string, number>();
+  return resolved.map((highlight) => {
+    const next =
+      highlight.status === "resolved" ? (counters.get(highlight.source) ?? 0) + 1 : undefined;
+    if (next !== undefined) counters.set(highlight.source, next);
+    return {
+      ...highlight,
+      index: next,
+      active: context.activeId != null && context.activeId === highlight.id,
+    };
+  });
+}

package/src/core/highlight.ts

@@ -0,0 +1,125 @@
+/**
+ * What the viewer is pointed AT — the vocabulary shared by citations and
+ * find-in-document.
+ *
+ * A {@link DocumentHighlight} is what a caller asks for; a
+ * {@link ResolvedHighlight} is what the viewer worked out and what an adapter's
+ * `Renderer` is handed. Keeping the two apart is what lets "we could not find
+ * that passage" be a rendered STATE rather than a silent no-op: the request
+ * survives even when the location does not, so the chrome still has something
+ * to name.
+ *
+ * The address vocabulary itself lives in `@elabs-ai/components-ui`
+ * (`DocumentAddress`) because the producer of a citation and this consumer are
+ * sibling packages that may not import each other. Everything here is
+ * adapter-protocol detail and stays in this package.
+ */
+
+import type {
+  DocumentAddress,
+  DocumentAddressKind,
+  DocumentRect,
+  MatchRange,
+} from "@elabs-ai/components-ui";
+
+/**
+ * Where a highlight came from. Both paint identically — only which one is
+ * ACTIVE differs — but the origin decides who owns the list: citations are a
+ * controlled prop the app supplies, search matches are the viewer's own.
+ */
+export type HighlightSource = "citation" | "search";
+
+/** A request to point the viewer at part of the open document. */
+export interface DocumentHighlight {
+  /**
+   * Stable per highlight. It is what `activeHighlightId` names and what React
+   * keys on, so a list that renumbers between renders must not renumber ids.
+   */
+  id: string;
+  /** Which part of the document. */
+  address: DocumentAddress;
+  /**
+   * Short human label — the answer's claim, the source's title. Announced when
+   * this highlight becomes active, so prefer something a listener can act on
+   * over "Citation 3".
+   */
+  label?: string;
+  /** Defaults to `"citation"`. */
+  source?: HighlightSource;
+}
+
+/**
+ * How a request turned out.
+ *
+ * `unsupported` is a CAPABILITY GAP, not a failure — the same distinction the
+ * error panel already draws. "This build can't locate a rect in a Word file"
+ * is news about what we shipped; it is not the reader's mistake, and it is not
+ * retryable.
+ */
+export type HighlightStatus = "pending" | "resolved" | "not-found" | "unsupported";
+
+/** Why a passage was not found — the two are genuinely different news. */
+export type HighlightMissReason =
+  /** Searched the whole projection; the passage is not in it. */
+  | "absent"
+  /** The projection is capped, and the passage may lie past the cap. */
+  | "truncated";
+
+/** A request, plus where it landed. What every adapter `Renderer` receives. */
+export interface ResolvedHighlight {
+  id: string;
+  label?: string;
+  source: HighlightSource;
+  status: HighlightStatus;
+  /** The original request, so a renderer can honour a kind the shell cannot. */
+  address: DocumentAddress;
+  /** Whether the viewer is currently pointed at this one. */
+  active: boolean;
+  /**
+   * 1-based position among the highlights of the same `source` that resolved —
+   * the "3" in "3 of 12". Absent when this one did not resolve, so a miss never
+   * silently consumes a number the reader is counting through.
+   */
+  index?: number;
+  /** Offsets into `document.text`, once located. */
+  range?: MatchRange;
+  /**
+   * 1-based page, set only for a `rect` address — the one kind with no range to
+   * derive a position from.
+   *
+   * A `quote` or `range` deliberately leaves this empty even when the caller
+   * supplied a page hint: where the passage actually landed is knowable from the
+   * adapter's own index, and a stale hint used as an instruction would page the
+   * reader somewhere the mark is not.
+   */
+  page?: number;
+  /** Geometry, for a `rect` address. */
+  rects?: readonly DocumentRect[];
+  /** Only on `not-found`. */
+  reason?: HighlightMissReason;
+}
+
+/**
+ * The most matches find-in-document will paint.
+ *
+ * A one-letter query against a 2 MB log matches hundreds of thousands of times;
+ * every one of those is a DOM element. The cap keeps typing responsive, and the
+ * chrome says so rather than quietly showing a wrong total.
+ */
+export const FIND_MATCH_LIMIT = 2000;
+
+/** Prefix reserved for the viewer's own search matches. */
+const FIND_ID_PREFIX = "find:";
+
+/** The id for the nth (0-based) find match. */
+export function findMatchId(index: number): string {
+  return `${FIND_ID_PREFIX}${String(index)}`;
+}
+
+/** Whether an id belongs to find-in-document rather than to a caller. */
+export function isFindMatchId(id: string): boolean {
+  return id.startsWith(FIND_ID_PREFIX);
+}
+
+/** Which address kinds an adapter honours. Absent means none — the safe default. */
+export type HighlightSupport = readonly DocumentAddressKind[];