@elabs-ai/components-viewer 4.0.0

package/dist/index.d.ts

@@ -0,0 +1,1353 @@
+import * as react from 'react';
+import { ComponentType, ReactNode, HTMLAttributes, RefObject } from 'react';
+import { DocumentAddress, MatchRange, DocumentRect, DocumentAddressKind, FileCategory, ResolvedFileSource, ProseHeadingLevel, FileKind, FileSource, NormalizedText, QuoteAddress } from '@elabs-ai/components-ui';
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+type HighlightSource = "citation" | "search";
+/** A request to point the viewer at part of the open document. */
+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.
+ */
+type HighlightStatus = "pending" | "resolved" | "not-found" | "unsupported";
+/** Why a passage was not found — the two are genuinely different news. */
+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. */
+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.
+ */
+declare const FIND_MATCH_LIMIT = 2000;
+/** The id for the nth (0-based) find match. */
+declare function findMatchId(index: number): string;
+/** Whether an id belongs to find-in-document rather than to a caller. */
+declare function isFindMatchId(id: string): boolean;
+/** Which address kinds an adapter honours. Absent means none — the safe default. */
+type HighlightSupport = readonly DocumentAddressKind[];
+
+/**
+ * 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.
+ */
+
+/** One chunk of the projection, and what it came from. */
+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. */
+interface TextIndex<TRef> {
+    text: string;
+    /** Sorted by `start`, non-overlapping. Gaps are the separators between chunks. */
+    spans: readonly TextSpan<TRef>[];
+}
+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;
+}
+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. */
+declare function createTextIndexBuilder<TRef>(options?: TextIndexBuilderOptions): TextIndexBuilder<TRef>;
+/** A span a range touches, with the overlap expressed in the CHUNK's own offsets. */
+interface SpanOverlap<TRef> {
+    span: TextSpan<TRef>;
+    /** Offset into the chunk, not into the projection. */
+    start: number;
+    end: number;
+}
+/**
+ * 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.
+ */
+declare function spansForRange<TRef>(index: TextIndex<TRef>, [start, end]: MatchRange): SpanOverlap<TRef>[];
+/**
+ * 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.
+ */
+declare function chunkOffset(parts: readonly string[], index: number, start: number | undefined, separator: string): number | undefined;
+/** The chunk containing `offset`, or `undefined` when it lands on a separator. */
+declare function spanAt<TRef>(index: TextIndex<TRef>, offset: number): TextSpan<TRef> | undefined;
+
+/**
+ * The adapter protocol — what a format plugin declares, what it produces, and
+ * what renders it.
+ *
+ * ## The two halves, and why they are split
+ *
+ * A registry entry is an eager {@link AdapterManifest} plus a lazy loader. The
+ * manifest is plain data available the moment the registry is created, so the
+ * chrome can decide which controls to show and whether a file is openable at all
+ * **without downloading a parser**. The loader is a `() => import(…)` that pulls
+ * the parser AND its renderer together, only once a file of that kind is opened.
+ *
+ * ## Adapters emit DATA, not HTML (ADR 0024 §3)
+ *
+ * An adapter's `load()` returns an {@link AdapterDocument} — a model — and ships
+ * a `Renderer` that draws it with brand-ui components. No adapter returns an
+ * HTML string, so no adapter can smuggle a colour, a font or a border past the
+ * token layer. This is the single decision that keeps the viewer themeable.
+ */
+
+/**
+ * The adapter protocol version. Bumped only when the shapes below change in a
+ * way an existing adapter would not survive; an adapter declaring a different
+ * version is rejected with a named error rather than crashing at render.
+ */
+declare const PROTOCOL_VERSION = 1;
+/**
+ * A quarter-turn clockwise rotation applied to the whole document.
+ *
+ * Document-level, not per-page: turning one page of a scan and leaving the rest
+ * is an AUTHORING act (it changes the file), and this package reads files.
+ */
+type DocumentRotation = 0 | 90 | 180 | 270;
+/** Scale the content to a dimension of the viewport instead of to a fixed number. */
+type ZoomFit = "fit-width" | "fit-page";
+/** One page's size at scale 1, in CSS pixels. */
+interface PageSize {
+    width: number;
+    height: number;
+}
+/**
+ * What the chrome asks a renderer to draw at.
+ *
+ * A fit mode is a REQUEST, not a scale: only the renderer knows how wide its own
+ * viewport is and how big the page is, so it resolves the request and reports the
+ * number back through {@link AdapterRendererProps.onZoomResolved}. Resolving it
+ * in the provider would mean the shell measuring a box it does not own.
+ */
+type ZoomLevel = number | ZoomFit;
+/** What the chrome may offer for a format, known before any parser is fetched. */
+interface AdapterCapabilities {
+    /** The document is paginated — show the pager. */
+    pages?: boolean;
+    /** The rendered content can be scaled — show the zoom control. */
+    zoom?: boolean;
+    /** The rendered content can be rotated. */
+    rotate?: boolean;
+    /**
+     * The document exposes text that can be searched.
+     *
+     * An OVERRIDE, not the source of truth: the shell offers find-in-document
+     * whenever a format has both a text projection and a text-based
+     * {@link AdapterCapabilities.highlight} kind, and reads this only when an
+     * adapter says otherwise. Left as the source of truth it would deny the find
+     * box to PDF — the format readers most expect it on — purely because that
+     * manifest predates the feature and never declared the flag.
+     *
+     * It overrides in the OFF direction only, so a declared `true` is inert: it
+     * cannot grant find to a format with no text or no range-painting renderer,
+     * because the box would then have nothing to show for a match.
+     */
+    search?: boolean;
+    /**
+     * Which {@link DocumentAddress} kinds this adapter's `Renderer` can actually
+     * paint. Absent means none.
+     *
+     * On the EAGER manifest on purpose: an app can decide whether to show a
+     * "jump to the cited passage" affordance before it downloads pdf.js.
+     *
+     * It is a promise the renderer has to keep — `pnpm viewer-highlight:check`
+     * fails a manifest that declares a kind its adapter never exercises.
+     */
+    highlight?: readonly DocumentAddressKind[];
+    /** The document has an outline/table of contents for the sidebar. */
+    outline?: boolean;
+    /** The document can produce page thumbnails for the sidebar. */
+    thumbnails?: boolean;
+    /** A plain-text projection exists — enables the raw/source toggle and copy. */
+    text?: boolean;
+}
+/**
+ * What an adapter can open. At least one of `extensions` / `mediaTypes` /
+ * `categories` must be present, or nothing will ever route to it.
+ */
+interface AdapterManifest {
+    /**
+     * Stable identity and the OVERRIDE key: registering a different loader under
+     * an existing id replaces it, which is how a consumer swaps a built-in.
+     */
+    id: string;
+    /** Must equal {@link PROTOCOL_VERSION}. */
+    protocol: number;
+    /**
+     * Tie-break when several adapters claim the same file. Built-ins are `0`;
+     * register above it to win, below it to act only as a fallback.
+     */
+    priority?: number;
+    /** Extensions claimed, lowercase and without the dot. The most specific match. */
+    extensions?: string[];
+    /** MIME types claimed. A trailing slash makes it a prefix (`"image/"`). */
+    mediaTypes?: string[];
+    /** Coarse categories claimed. The broadest match — a catch-all fallback. */
+    categories?: FileCategory[];
+    /** Which chrome controls apply. Absent keys are `false`. */
+    capabilities?: AdapterCapabilities;
+    /**
+     * Optional peer packages this adapter dynamically imports. Purely
+     * informational to the registry — it is what the "install this to open that"
+     * message names when the import fails to resolve.
+     */
+    requires?: string[];
+}
+/**
+ * An adapter's parsed output. Adapters EXTEND this with their own payload; the
+ * fields here are the parts the shell itself understands, so it can drive the
+ * pager, the search box and the raw toggle without knowing the format.
+ */
+interface AdapterDocument {
+    /** Adapter-defined discriminant, matched by that adapter's own `Renderer`. */
+    readonly kind: string;
+    /** Page count for a paginated document. Omit for single-surface formats. */
+    readonly pageCount?: number;
+    /**
+     * Each page's size at scale 1, in document order.
+     *
+     * What lets a continuously-scrolling renderer reserve the right height for a
+     * page it has not drawn yet, so the scrollbar means something from the first
+     * frame instead of growing as pages arrive. May be SHORTER than
+     * {@link AdapterDocument.pageCount} — measuring 900 pages up front costs 900
+     * round-trips to a worker, so an adapter is free to describe the pages it
+     * already touched and let the renderer assume the rest match.
+     */
+    readonly pageSizes?: readonly PageSize[];
+    /** Plain-text projection, when the format has one. Powers search, copy and the raw view. */
+    readonly text?: string;
+    /**
+     * Whether {@link AdapterDocument.text} is CAPPED rather than complete.
+     *
+     * Changes what "we couldn't find that passage" means: absent from the whole
+     * document, or simply past the part we previewed. Those deserve different
+     * sentences, and only the adapter knows which one is true.
+     */
+    readonly textTruncated?: boolean;
+    /**
+     * The map from {@link AdapterDocument.text} back into this adapter's own
+     * model, so a character range can become a block, a page or a cell.
+     *
+     * The `ref` type is the adapter's business — its own `Renderer` is the only
+     * thing that reads it, which is why it is `unknown` here.
+     */
+    readonly textIndex?: TextIndex<unknown>;
+}
+/** Everything an adapter is given while loading a document. */
+interface AdapterLoadContext {
+    /** Cancels the load — always honour it; a stale parse must not win a race. */
+    signal?: AbortSignal;
+    /** Report determinate progress in `0..1` where the format allows it. */
+    onProgress?: (fraction: number) => void;
+}
+/** A parser instance. One per document — adapters may hold per-document state. */
+interface FileAdapter {
+    load(source: ResolvedFileSource, context: AdapterLoadContext): Promise<AdapterDocument>;
+    /** Release anything the document holds (workers, object URLs, decoded buffers). */
+    dispose?(): void;
+}
+/** Props every adapter `Renderer` receives. */
+interface AdapterRendererProps {
+    /** The value this adapter's own `load()` returned — narrow it by `kind`. */
+    document: AdapterDocument;
+    /** The source, for identity, `alt` text and download actions. */
+    source: ResolvedFileSource;
+    className?: string;
+    /**
+     * The heading rung a document's own top-level heading renders at.
+     *
+     * A viewed file carries its OWN heading tree, and that tree has to be
+     * relative to the page hosting it: a README's `#` inside an app that already
+     * has an `<h1>` would otherwise put two `h1`s in a screen reader's flat
+     * heading list. `FileViewerContent` passes the provider's value; an adapter
+     * that renders headings offsets by it (`clampHeadingLevel(own + base - 1)`),
+     * and one that renders none ignores it. Same seam as
+     * `@elabs-ai/components-ai`'s `MarkdownView baseHeadingLevel`.
+     *
+     * Optional, so adding it is not a `PROTOCOL_VERSION` change.
+     */
+    baseHeadingLevel?: ProseHeadingLevel;
+    /**
+     * The parts of the document to mark, already located — citations from the
+     * app and the viewer's own find-in-document matches, in document order.
+     *
+     * The shell has done LOCATE (a quote is now a character range); the renderer
+     * does MAP and PAINT, because only it knows that offsets 812–847 are the
+     * second half of block 14. An adapter renders only the entries whose `status`
+     * is `"resolved"` and whose `address.kind` it declared, and ignores the rest
+     * — the shell is what tells the reader about a miss.
+     *
+     * Optional, so adding it is not a `PROTOCOL_VERSION` change.
+     */
+    highlights?: readonly ResolvedHighlight[];
+    /**
+     * Which highlight the viewer is pointed at. The renderer scrolls it into
+     * view, pages to it if the format paginates, and draws it distinctly.
+     *
+     * Also present as `active` on the entry itself; this is the shortcut for a
+     * renderer that only needs to know whether anything changed.
+     */
+    activeHighlightId?: string | null;
+    /**
+     * Which page the reader is on, 1-based — the provider's, not the renderer's.
+     *
+     * Page, zoom and rotation are PROVIDER state (ADR 0026) so a control can live
+     * anywhere: the shell's own toolbar, an app's page header, a deep link. While
+     * these were `useState` inside each renderer nothing outside the canvas could
+     * read or drive them.
+     *
+     * Uncontrolled when absent — a renderer used outside a `FileViewerProvider`
+     * keeps its own page, so it still works standalone. Optional, so adding it is
+     * not a `PROTOCOL_VERSION` change.
+     */
+    pageNumber?: number;
+    /**
+     * Report a page the RENDERER navigated to on its own — turning to a cited
+     * page, or (once pages scroll continuously) the page scrolled into view. The
+     * provider is what keeps the pager's number honest.
+     */
+    onPageChange?: (page: number) => void;
+    /** The scale, or a fit mode to resolve. Absent means the renderer's own default. */
+    zoom?: ZoomLevel;
+    /**
+     * Report the scale a {@link ZoomFit} actually resolved to.
+     *
+     * Only a renderer knows this — it is the one measuring its viewport. Without
+     * it the chrome cannot show a percentage for a fitted page, and the reader's
+     * next "zoom in" would step from the last fixed stop rather than from what is
+     * on screen. A renderer that never resolves a fit mode never calls it.
+     */
+    onZoomResolved?: (scale: number) => void;
+    /** Quarter-turns clockwise. Ignored by renderers whose manifest omits `rotate`. */
+    rotation?: DocumentRotation;
+}
+/**
+ * What an adapter module exports. `manifest` is re-declared here so the registry
+ * can verify the loaded module is the one the eager manifest promised.
+ */
+interface AdapterModule {
+    manifest: AdapterManifest;
+    /** Fresh instance per document — never a shared singleton. */
+    create(): FileAdapter;
+    Renderer: ComponentType<AdapterRendererProps>;
+}
+/** A lazy adapter loader. Always `() => import("…")` so nothing heavy is eager. */
+type AdapterLoader = () => Promise<AdapterModule | {
+    default: AdapterModule;
+}>;
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+declare const MatchScore: {
+    readonly None: 0;
+    readonly Category: 1;
+    readonly MediaTypePrefix: 2;
+    readonly MediaType: 3;
+    readonly Extension: 4;
+};
+type MatchScore = (typeof MatchScore)[keyof typeof MatchScore];
+/** A registry of file adapters. Create with {@link createRegistry}. */
+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". */
+declare function scoreManifest(manifest: AdapterManifest, kind: FileKind): MatchScore;
+/**
+ * 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.
+ */
+declare function createRegistry(): ViewerRegistry;
+
+interface FileViewerProviderProps {
+    /** The file to show. `undefined` is the empty state, not an error. */
+    source?: FileSource;
+    /**
+     * Adapters available to this viewer. Defaults to the built-ins.
+     * Pass your own to add a format, drop one, or override a built-in.
+     */
+    registry?: ViewerRegistry;
+    /**
+     * Force the not-ready state while a parent fetches the source itself.
+     * ORed with the viewer's own loading — a parent can add loading, never remove it.
+     */
+    loading?: boolean;
+    /**
+     * The rung a viewed document's own top-level heading renders at. Default `2`.
+     *
+     * A file carries its OWN heading tree, and that tree is only correct relative
+     * to the page hosting it: a README's `#` rendered as an `<h1>` inside an app
+     * that already has one puts two `h1`s in a screen reader's flat heading list,
+     * and the frame's `<section aria-label>` does not fix that — most screen
+     * readers list headings flat, not per landmark. The default assumes the
+     * common case, a viewer embedded BELOW the page's own heading; pass `1` when
+     * the viewer genuinely is the page.
+     *
+     * Adapters that render no headings ignore it. Same seam as
+     * `@elabs-ai/components-ai`'s `MarkdownView baseHeadingLevel`.
+     */
+    baseHeadingLevel?: ProseHeadingLevel;
+    /**
+     * The parts of the document to point at — an answer's citations, a search
+     * result's context, anything the app already knows about the file.
+     *
+     * A PROP rather than provider-only state because citations originate outside
+     * the viewer entirely: the chat pane that produced them usually lives in
+     * another route, and it owns which one the reader clicked. Pass
+     * `defaultHighlights` instead to let the viewer own them.
+     */
+    highlights?: readonly DocumentHighlight[];
+    /** Uncontrolled initial citations. Ignored when `highlights` is supplied. */
+    defaultHighlights?: readonly DocumentHighlight[];
+    onHighlightsChange?: (highlights: readonly DocumentHighlight[]) => void;
+    /**
+     * Which citation the viewer is pointed at. `null` is "none" explicitly;
+     * `undefined` is what selects uncontrolled mode, so the two are not
+     * interchangeable here.
+     */
+    activeHighlightId?: string | null;
+    defaultActiveHighlightId?: string | null;
+    onActiveHighlightChange?: (id: string | null) => void;
+    /**
+     * Which page the viewer is on, 1-based — controlled.
+     *
+     * A trio (`component-api.md`) rather than provider-only state because the page
+     * is routinely something the APP owns: a deep link to page 7, a URL the reader
+     * can share, a position restored from a "continue reading" record. Clamped to
+     * the document on read, so an out-of-range value degrades to the nearest real
+     * page instead of blanking the canvas.
+     */
+    pageNumber?: number;
+    /** Uncontrolled initial page. Ignored when `pageNumber` is supplied. */
+    defaultPageNumber?: number;
+    onPageNumberChange?: (page: number) => void;
+    /**
+     * The scale to draw at, or a fit mode — controlled. Persisting a reader's
+     * preferred zoom across files and sessions is the reason this is a prop.
+     */
+    zoom?: ZoomLevel;
+    /**
+     * Uncontrolled initial zoom. Ignored when `zoom` is supplied.
+     *
+     * Defaults to `"fit-width"`, not `1`: a viewer's job on open is to show the
+     * document, and a 4000px scan or an A4 page at 100% in a 600px pane shows its
+     * top-left corner. Every reader-facing PDF viewer opens fitted for the same
+     * reason. Pass `1` for true 100%.
+     */
+    defaultZoom?: ZoomLevel;
+    onZoomChange?: (zoom: ZoomLevel) => void;
+    /** Quarter-turns clockwise — controlled. */
+    rotation?: DocumentRotation;
+    /** Uncontrolled initial rotation. Ignored when `rotation` is supplied. Default `0`. */
+    defaultRotation?: DocumentRotation;
+    onRotationChange?: (rotation: DocumentRotation) => void;
+    children: ReactNode;
+}
+declare function FileViewerProvider({ source, registry: registryProp, loading, baseHeadingLevel, highlights: highlightsProp, defaultHighlights, onHighlightsChange, activeHighlightId: activeHighlightIdProp, defaultActiveHighlightId, onActiveHighlightChange, pageNumber: pageNumberProp, defaultPageNumber, onPageNumberChange, zoom: zoomProp, defaultZoom, onZoomChange, rotation: rotationProp, defaultRotation, onRotationChange, children, }: FileViewerProviderProps): react.JSX.Element;
+type FileViewerFrameProps = HTMLAttributes<HTMLDivElement>;
+/**
+ * The bordered surface the toolbar and content sit in, and the scope of the
+ * viewer's find shortcut.
+ *
+ * Ctrl/Cmd+F is handled HERE rather than on `document`: a page may hold several
+ * viewers, or a viewer beside an editor that has its own find, and a
+ * document-level listener would let whichever mounted last win. Bound to the
+ * frame, the shortcut belongs to whichever viewer the reader is actually inside,
+ * and the browser's own find is untouched everywhere else on the page.
+ */
+declare const FileViewerFrame: react.ForwardRefExoticComponent<FileViewerFrameProps & react.RefAttributes<HTMLDivElement>>;
+interface FileViewerToolbarProps extends HTMLAttributes<HTMLDivElement> {
+    /** Extra controls, placed after the built-in actions. */
+    actions?: ReactNode;
+}
+/**
+ * The identity row: glyph, name, actions.
+ *
+ * No `role="toolbar"` — that role promises roving-tabindex arrow-key navigation,
+ * which this row does not implement. The same decision `ViewToolbar` made, and
+ * the reason the P1 `Toolbar` primitive exists (ADR 0024 §5a).
+ *
+ * With no file it renders NOTHING: a row holding a generic glyph and a blank
+ * name reads as a broken render, not as chrome. A screen that needs a permanent
+ * header composes its own row around `FileViewerFrame` — that is what the parts
+ * are for.
+ */
+declare const FileViewerToolbar: react.ForwardRefExoticComponent<FileViewerToolbarProps & react.RefAttributes<HTMLDivElement>>;
+type FileViewerHighlightStatusProps = HTMLAttributes<HTMLDivElement>;
+/**
+ * "We couldn't find that passage."
+ *
+ * A citation that fails to locate must not fail SILENTLY: the reader clicked a
+ * source link and got a document that looks untouched, with no way to tell
+ * whether the viewer is broken, the passage moved, or they mis-clicked. The
+ * request survives resolution precisely so this line has something to say.
+ *
+ * Three different pieces of news, three sentences:
+ * - `not-found` / `absent` — searched the whole projection; it is not in it.
+ * - `not-found` / `truncated` — the projection is capped, so it may lie past it.
+ * - `unsupported` — a CAPABILITY GAP: this build cannot point at part of that
+ *   format. Not the reader's fault and not retryable, same call the error panel
+ *   already makes for `unsupported-format`.
+ *
+ * Search misses are excluded: the find bar already counts its own matches, and
+ * "No matches" there says it better than a second line here would.
+ */
+declare const FileViewerHighlightStatus: react.ForwardRefExoticComponent<FileViewerHighlightStatusProps & react.RefAttributes<HTMLDivElement>>;
+/**
+ * A layout-shaped skeleton, not a spinner: it occupies the box the real content
+ * will, so nothing shifts when the file arrives (`loading-states.md`).
+ * `aria-hidden` because `Skeleton` is decorative — the single live region on the
+ * wrapper is what AT hears.
+ */
+declare const FileViewerSkeleton: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
+declare const FileViewerError: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
+declare const FileViewerEmpty: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
+type FileViewerContentProps = HTMLAttributes<HTMLDivElement>;
+/**
+ * The state switch: empty · loading · error · the adapter's own renderer.
+ *
+ * The adapter supplies its `Renderer` alongside its parser, so this component
+ * never grows a per-format `switch` — that is what keeps formats additive.
+ *
+ * **This is THE scroll boundary** for any adapter that does not manage its own
+ * viewport. Two nested `overflow-auto` boxes do not compose: the inner one clips
+ * while the outer one's padding stays put, so a long document ends flush against
+ * a band of whitespace and reads as a failed render rather than as "scroll for
+ * more". Adapters whose content simply flows (text, code, markdown, Word) let
+ * this scroll; the ones with a fixed sub-control and a scrolling body of their
+ * own — PDF pages, PowerPoint slides, a sheet under its tab bar — keep theirs
+ * and label it the same way.
+ *
+ * It is also a **focusable, named region**: a pane that scrolls but contains
+ * nothing focusable cannot be reached from a keyboard at all (WCAG 2.1.1), and
+ * a plain-text file contains nothing focusable by definition.
+ */
+declare const FileViewerContent: react.ForwardRefExoticComponent<FileViewerContentProps & react.RefAttributes<HTMLDivElement>>;
+interface FileViewerProps extends Omit<FileViewerProviderProps, "children">, Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /** Replace the default composition. Rendered inside the provider AND the frame. */
+    children?: ReactNode;
+}
+/**
+ * The default composition — provider + frame + toolbar + content.
+ *
+ * Reach for the parts when you need a different arrangement; this covers the
+ * common case in one element.
+ */
+declare const FileViewer: react.ForwardRefExoticComponent<FileViewerProps & react.RefAttributes<HTMLDivElement>>;
+
+/** Whether a keyboard event is the platform's find shortcut. */
+declare function isFindShortcut(event: {
+    key: string;
+    metaKey: boolean;
+    ctrlKey: boolean;
+}): boolean;
+type FileViewerFindProps = HTMLAttributes<HTMLDivElement>;
+/**
+ * The search row. Renders nothing until `actions.openFind()` (or Ctrl/Cmd+F on
+ * the frame) opens it, and nothing at all for a document whose adapter cannot
+ * paint a range — an affordance that could never highlight anything is worse
+ * than no affordance at all.
+ */
+declare const FileViewerFind: react.ForwardRefExoticComponent<FileViewerFindProps & react.RefAttributes<HTMLDivElement>>;
+
+type FileViewerPagerProps = HTMLAttributes<HTMLDivElement>;
+declare const FileViewerPager: react.ForwardRefExoticComponent<FileViewerPagerProps & react.RefAttributes<HTMLDivElement>>;
+
+type FileViewerZoomProps = HTMLAttributes<HTMLDivElement>;
+/**
+ * Zoom out · the current level · zoom in.
+ *
+ * The middle control is a `Select` rather than a read-out because the stops are
+ * the API: a reader who wants 200% should not have to press "+" four times, and
+ * the two fit modes have no number to press towards at all.
+ *
+ * Not a `role="toolbar"` — see `FileViewerPager`. It sits in the same row, and
+ * one row that is half roving-tabindex and half ordinary tab stops is worse for
+ * a keyboard reader than one that is consistently ordinary.
+ */
+declare const FileViewerZoom: react.ForwardRefExoticComponent<FileViewerZoomProps & react.RefAttributes<HTMLDivElement>>;
+type FileViewerRotateProps = HTMLAttributes<HTMLButtonElement>;
+/**
+ * One button, one quarter-turn clockwise.
+ *
+ * Document-level and clockwise-only on purpose: a counter-clockwise button is a
+ * second control for something three presses of this one already do, and
+ * per-page rotation would change the file, which is authoring rather than
+ * viewing. `actions.rotate(-1)` is there for an app that wants the other one.
+ */
+declare const FileViewerRotate: react.ForwardRefExoticComponent<FileViewerRotateProps & react.RefAttributes<HTMLButtonElement>>;
+
+/**
+ * Typed failures, so the UI can decide what to SHOW without string-matching a
+ * message.
+ *
+ * The `message` on these errors is developer-facing — it goes to the console and
+ * to bug reports. Everything the user reads is looked up from {@link ViewerErrorCode}
+ * through `t()` (ADR 0017), which is why the code, not the prose, is the contract.
+ */
+/** Why a file could not be shown. */
+type ViewerErrorCode = 
+/** No registered adapter claims this file. */
+"unsupported-format"
+/** An adapter was built against a different registry protocol. */
+ | "protocol-mismatch"
+/** The adapter exists but its optional peer dependency is not installed. */
+ | "parser-missing"
+/** The bytes could not be obtained (network, permissions, a revoked blob). */
+ | "read-failed"
+/** The bytes arrived but the parser rejected them. */
+ | "parse-failed"
+/** The load was cancelled — a new source, or an unmounted view. */
+ | "aborted";
+interface ViewerErrorOptions extends ErrorOptions {
+    /** The file this is about, for the developer-facing message. */
+    fileName?: string;
+    /** For `parser-missing`: the packages a consumer has to install. */
+    packages?: string[];
+}
+/** A failure a `FileViewer` can render, carrying a machine-readable {@link ViewerErrorCode}. */
+declare class ViewerError extends Error {
+    readonly code: ViewerErrorCode;
+    readonly fileName?: string;
+    readonly packages?: string[];
+    constructor(code: ViewerErrorCode, message: string, options?: ViewerErrorOptions);
+}
+/** True for a {@link ViewerError}, without relying on `instanceof` across bundles. */
+declare function isViewerError(value: unknown): value is ViewerError;
+/** True when the failure is a cancellation rather than something to report. */
+declare function isAbort(value: unknown): boolean;
+/**
+ * Wrap an unknown throw as a {@link ViewerError}, preserving an existing one and
+ * mapping an abort to the `aborted` code so callers do not report cancellations
+ * as failures.
+ */
+declare function toViewerError(value: unknown, fallbackCode: ViewerErrorCode, options?: ViewerErrorOptions): ViewerError;
+/**
+ * A dynamic `import()` of an OPTIONAL peer that is not installed.
+ *
+ * Bundlers and Node report this differently (`ERR_MODULE_NOT_FOUND`,
+ * `Cannot find module`, `Failed to resolve module specifier`, Vite's
+ * `Failed to fetch dynamically imported module`), so match on the shapes rather
+ * than one runtime's wording. A false positive here is cheap — the user is told
+ * to install a package instead of seeing a raw parse error — and a false
+ * negative is the anyview failure mode this exists to avoid: an unhelpful
+ * module-resolution stack trace where a "install papaparse to open CSV files"
+ * message belongs.
+ */
+declare function isModuleNotFound(value: unknown): boolean;
+/**
+ * The `parser-missing` error, worded the same wherever the peer turns out to be
+ * absent.
+ *
+ * There are TWO such places, which is why this is a function and not a literal
+ * at one call site. The registry catches it when the adapter MODULE cannot be
+ * fetched; `FileViewerProvider` catches it when the module loaded fine and the
+ * adapter's own `await import("mammoth")` — inside `load()`, where every parser
+ * engine is actually reached — rejects. Without the second, a consumer who
+ * skipped an optional peer was told their file was damaged and offered a retry
+ * that could never work.
+ */
+declare function parserMissingError(adapterId: string, packages: string[], options?: ViewerErrorOptions): ViewerError;
+
+/**
+ * Where a file is in its journey to the screen.
+ *
+ * `loading` means "no renderable content yet" — the canonical signal from
+ * `.claude/rules/loading-states.md`, rendered as a layout-shaped skeleton.
+ * There is no separate `isStreaming`: a file arrives settled or not at all.
+ */
+type FileViewerStatus = "empty" | "loading" | "ready" | "error";
+/**
+ * The LOAD half of the state — everything the fetch-and-parse effect owns.
+ *
+ * Split from the highlight half because the two have different lifetimes: this
+ * one is replaced wholesale each time a file is opened, while the citations
+ * pointing into it are a prop the app controls and outlive any single parse.
+ * Folding them together would mean every `setState` in the load effect had to
+ * remember to carry the highlights forward.
+ */
+interface FileViewerLoadState {
+    status: FileViewerStatus;
+    /** The resolved source, available as soon as there IS one — before any read. */
+    source?: ResolvedFileSource;
+    /** The adapter's parsed output. Only in `ready`. */
+    document?: AdapterDocument;
+    /** The adapter module that produced it, for its `Renderer`. Only in `ready`. */
+    adapter?: AdapterModule;
+    /** What the chrome may offer. Known from the manifest BEFORE the parser loads. */
+    capabilities: AdapterCapabilities;
+    /** Only in `error`. Always a `ViewerError`, so `code` can drive the message. */
+    error?: ViewerError;
+}
+/**
+ * How the open document is being LOOKED at — which page, at what scale, turned
+ * which way.
+ *
+ * Separate from the load state because it survives nothing and owns nothing: it
+ * is pure view, reset (page, rotation) or carried (zoom) when a new file opens.
+ * It lives in the provider rather than inside each adapter's `Renderer` so a
+ * control can sit anywhere — the shell toolbar, an app's own page header, a
+ * deep link — instead of only inside the canvas (ADR 0026).
+ */
+interface FileViewerViewState {
+    /** 1-based. `1` for a format that does not paginate. */
+    pageNumber: number;
+    /** `0` until a paginated document is ready, and for formats with no pages. */
+    pageCount: number;
+    /** What was ASKED for: a fixed scale, or a fit mode the renderer resolves. */
+    zoom: ZoomLevel;
+    /**
+     * What that resolved to, as a number — what the zoom control shows and what
+     * `zoomIn`/`zoomOut` step from. Equal to `zoom` whenever `zoom` is a number.
+     */
+    effectiveZoom: number;
+    /** Quarter-turns clockwise. Reset to `0` when a different file is opened. */
+    rotation: DocumentRotation;
+}
+interface FileViewerState extends FileViewerLoadState, FileViewerViewState {
+    /**
+     * The parts of the document to point at, as REQUESTED. What was actually
+     * located is `meta.resolvedHighlights` — the request survives a miss so the
+     * chrome can say "we couldn't find that passage" instead of showing nothing.
+     */
+    highlights: readonly DocumentHighlight[];
+    /** Which one the viewer is pointed at. `null` is "none", explicitly. */
+    activeHighlightId: string | null;
+    find: FileViewerFindState;
+}
+/** What find-in-document is doing right now. */
+interface FileViewerFindState {
+    /** Whether the search box is showing. */
+    open: boolean;
+    query: string;
+    caseSensitive: boolean;
+    /** How many matches the current query has. */
+    matches: number;
+    /** Whether that count hit `FIND_MATCH_LIMIT` and is therefore a floor. */
+    truncated: boolean;
+    /**
+     * Which match is current, 0-based — the "3" in "3 of 12", minus one.
+     *
+     * Deliberately NOT the same knob as `activeHighlightId`. Find is the viewer's
+     * own, and an app that controls `activeHighlightId` to drive citations would
+     * otherwise have to also honour every keystroke of a search it never asked
+     * for, or silently break next/previous.
+     */
+    activeIndex: number;
+}
+interface FileViewerActions {
+    /** Re-run the load. The retry action on the error state. */
+    reload: () => void;
+    /**
+     * Replace the citations. While `highlights` is controlled this writes no local
+     * state — but it still calls `onHighlightsChange`, so the owner can accept the
+     * request. Mirroring the platform: a controlled input reports, it does not
+     * self-update.
+     */
+    setHighlights: (highlights: readonly DocumentHighlight[]) => void;
+    /** Point the viewer at one highlight, or at none. */
+    setActiveHighlight: (id: string | null) => void;
+    /** Move to the next/previous CITATION in document order, wrapping around. */
+    nextHighlight: () => void;
+    previousHighlight: () => void;
+    openFind: () => void;
+    closeFind: () => void;
+    setFindQuery: (query: string) => void;
+    setFindCaseSensitive: (caseSensitive: boolean) => void;
+    /** Move to the next/previous SEARCH match, wrapping around. */
+    nextFindMatch: () => void;
+    previousFindMatch: () => void;
+    /**
+     * Turn to a page, 1-based. Clamped to the document — an out-of-range page is
+     * a caller's arithmetic slip, not a reason to blank the canvas.
+     */
+    goToPage: (page: number) => void;
+    /** Turn one page. Both stop at the ends rather than wrapping: a document is not a carousel. */
+    nextPage: () => void;
+    previousPage: () => void;
+    /** Draw at a fixed scale, or hand the renderer a fit mode to resolve. */
+    setZoom: (zoom: ZoomLevel) => void;
+    /**
+     * Step to the next stop above/below what is currently ON SCREEN — so zooming
+     * in from a fitted page continues from the fitted scale, not from wherever the
+     * fixed ladder was last parked.
+     */
+    zoomIn: () => void;
+    zoomOut: () => void;
+    setRotation: (rotation: DocumentRotation) => void;
+    /** Turn the document a quarter-turn: `1` clockwise, `-1` counter-clockwise. */
+    rotate: (quarterTurns: 1 | -1) => void;
+    /**
+     * The renderer's report channel for {@link FileViewerViewState.effectiveZoom}
+     * — not for app code. `FileViewerContent` wires it to the adapter's
+     * `onZoomResolved`, the same way `registerFind` is wired to a part rather than
+     * called by a consumer.
+     */
+    reportZoom: (scale: number) => void;
+    /**
+     * Tell the viewer a find part is mounted; call the returned function on
+     * unmount. `FileViewerFind` does this for you — it exists so the frame knows
+     * whether taking Ctrl/Cmd+F off the browser leads anywhere.
+     */
+    registerFind: () => () => void;
+}
+interface FileViewerContextValue {
+    state: FileViewerState;
+    actions: FileViewerActions;
+    registry: ViewerRegistry;
+    meta: {
+        /**
+         * The rung a viewed document's own top-level heading renders at. Passed to
+         * every adapter `Renderer`; see `AdapterRendererProps.baseHeadingLevel`.
+         */
+        baseHeadingLevel: ProseHeadingLevel;
+        /**
+         * Citations and find matches, LOCATED, in document order, numbered — what
+         * an adapter `Renderer` is handed and what the chrome counts.
+         */
+        resolvedHighlights: readonly ResolvedHighlight[];
+        /**
+         * Which highlight the viewer is EFFECTIVELY pointed at, and what an adapter
+         * `Renderer` receives as `activeHighlightId`.
+         *
+         * Not the same knob as `state.activeHighlightId`: that one is the citation
+         * the app controls, while the reader stepping through find matches is also
+         * "current". Find outranks the citation while its box is open and matching,
+         * so navigation and scrolling follow whichever the reader is actually moving.
+         */
+        currentHighlightId: string | null;
+        /** Which address kinds this document's adapter declared it can paint. */
+        highlightSupport: HighlightSupport;
+        /**
+         * Whether find-in-document applies to the open document. Derived, not read
+         * straight off the manifest — see `AdapterCapabilities.search`.
+         */
+        canFind: boolean;
+        /**
+         * Whether a `FileViewerFind` part is composed into this viewer.
+         *
+         * Separate from {@link canFind}, which only says the ADAPTER could paint a
+         * match. The frame needs both before it takes Ctrl/Cmd+F away from the
+         * browser: intercepting the shortcut with nowhere to type leaves a keyboard
+         * reader with no find at all.
+         */
+        hasFind: boolean;
+    };
+}
+/**
+ * Read the viewer state. Throws outside a provider — a part that silently
+ * rendered nothing would be far harder to diagnose than a named error.
+ */
+declare function useFileViewer(): FileViewerContextValue;
+
+/**
+ * The zoom vocabulary — the stops, and how the chrome moves between them.
+ *
+ * Lives in `core/` rather than in the PDF adapter (where the stops started)
+ * because zoom is now provider state: the shell's zoom control, the provider's
+ * `zoomIn`/`zoomOut` and every adapter that scales its content all have to agree
+ * on the same ladder, or "125%" in the toolbar and the scale the page rendered
+ * at drift apart.
+ */
+
+/**
+ * Zoom stops, in document scale.
+ *
+ * Discrete rather than continuous: a slider is imprecise with a pointer and
+ * impossible with a keyboard at this size, and "somewhere near 137%" is not a
+ * state a reader ever wants to be in. The ladder is the one from the original
+ * PDF pager, unchanged, so existing screens land on the same numbers.
+ */
+declare const VIEWER_ZOOM_STEPS: readonly [0.5, 0.75, 1, 1.25, 1.5, 2, 3];
+/** 100% — the scale a document opens at. */
+declare const DEFAULT_ZOOM = 1;
+/** Whether a zoom level is a fit mode rather than a fixed scale. */
+declare function isZoomFit(zoom: ZoomLevel): zoom is ZoomFit;
+/**
+ * The next stop above or below `from`.
+ *
+ * Takes an arbitrary scale, not an index, because a fit mode resolves to
+ * whatever the viewport made it (1.37, say) and the reader's next "zoom in" has
+ * to land on a real stop above that — an index-based pager would jump back to
+ * wherever the ladder was last parked.
+ */
+declare function stepZoom(from: number, delta: 1 | -1): number;
+/** Whether there is a stop left in that direction — what disables the button. */
+declare function canStepZoom(from: number, delta: 1 | -1): boolean;
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+declare function locateQuote(normalized: NormalizedText, address: QuoteAddress): MatchRange | undefined;
+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;
+}
+/**
+ * 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.
+ */
+declare function resolveHighlights(highlights: readonly DocumentHighlight[], context: HighlightResolveContext): ResolvedHighlight[];
+
+/**
+ * The MAP + PAINT half of the highlight funnel, for adapters whose document IS
+ * its own text projection — plain text, code, and anything else that renders
+ * `document.text` verbatim.
+ *
+ * The shell has already done LOCATE (every quote is now a character range). All
+ * that is left is to hand those ranges to `MatchHighlight` and say which one is
+ * current. An adapter with a richer model (pages, blocks, cells) maps the same
+ * ranges through its own `textIndex` instead and does not use this.
+ */
+
+/** What `MatchHighlight` takes: merged ranges, plus which merged mark is current. */
+interface MarkRanges {
+    /** Clamped, sorted and merged — the same ranges `MatchHighlight` will paint. */
+    readonly ranges: readonly MatchRange[];
+    /** Index into {@link MarkRanges.ranges}, or `-1` when none is current. */
+    readonly activeIndex: number;
+}
+/**
+ * Fold resolved highlights into the ranges a `<mark>` layer paints.
+ *
+ * Merging happens HERE rather than being left to `MatchHighlight`, because the
+ * two would otherwise disagree about what "the third mark" is: overlapping
+ * citations collapse into one mark, and an `activeIndex` counted against the
+ * unmerged list would then point at the wrong one — or past the end. The active
+ * entry is located by which merged range CONTAINS its start, so it stays right
+ * no matter how many requests collapsed into that mark.
+ *
+ * Non-`range` addresses and unresolved entries are skipped: an adapter paints
+ * what it can and the shell is what tells the reader about the rest.
+ */
+declare function toMarkRanges(highlights: readonly ResolvedHighlight[] | undefined, textLength: number): MarkRanges;
+/**
+ * Re-express document ranges relative to one slice of the document — a code
+ * token, a table cell, a block of prose.
+ *
+ * A renderer that draws its text in pieces cannot hand whole-document offsets to
+ * a `<mark>` layer that only knows about the piece in front of it. Ranges are
+ * clipped to the slice and rebased to 0; the ones that miss it entirely drop
+ * out, which is also how a caller learns there is nothing to mark here (an empty
+ * `ranges`). A range spanning several slices survives in each of them, so a
+ * citation crossing a line break stays one visual run.
+ */
+declare function localizeRanges({ ranges, activeIndex }: MarkRanges, start: number, end: number): MarkRanges;
+
+/**
+ * Bring the current highlight into view.
+ *
+ * Pointing at a passage is only half the job — a mark 4,000 lines down that
+ * nobody scrolls to is the same as no mark at all. Every text-ish renderer needs
+ * this, so it is written once here rather than per adapter.
+ *
+ * The current highlight is found by the stable `data-slot` selector its painter
+ * emits, not by a ref: both painters produce their elements from a list — marks
+ * inside `MatchHighlight`, boxes inside a page overlay — so the renderer has no
+ * handle on the individual element and should not grow one just for scrolling.
+ */
+
+/**
+ * How the current highlight identifies itself in the DOM, whichever way it was
+ * painted: a `<mark>` in flowing text, a box over a page raster, or a whole
+ * block plated because the format can only be addressed that coarsely.
+ */
+declare const ACTIVE_HIGHLIGHT_SELECTOR: string;
+/**
+ * Scroll the current highlight inside `containerRef` into view whenever the
+ * viewer is pointed somewhere new.
+ *
+ * `block: "center"` rather than `"nearest"`: a cited passage should land where a
+ * reader looks, with its surrounding context visible, not flush against the top
+ * edge of the pane. Smooth scrolling is skipped under a reduced-motion
+ * preference — an imperative scroll is invisible to the CSS media query, so the
+ * check has to be explicit.
+ *
+ * `paintKey` is anything whose change means the highlights were repainted — a
+ * page's box list, a re-tokenized document. A renderer that paints
+ * asynchronously (a PDF fetches the page's text after the raster) has no element
+ * to scroll to at the moment the active id changes, so it passes the thing it
+ * was waiting for and the scroll runs once that arrives.
+ */
+declare function useScrollActiveHighlightIntoView(containerRef: RefObject<HTMLElement | null>, activeHighlightId: string | null | undefined, paintKey?: unknown): void;
+
+/**
+ * Eager, data-only (see `image-manifest.ts`).
+ *
+ * Claims EXTENSIONS only — never the `code` category. That is what keeps the
+ * plain-text adapter as the backstop: a `.log`, a `.env` or an unknown
+ * extension still opens as text instead of failing to find a grammar, and a
+ * consumer who never installs Shiki loses highlighting rather than the file.
+ */
+declare const codeManifest: AdapterManifest;
+
+/**
+ * Eager, data-only (see `image-manifest.ts`).
+ *
+ * `requires` names the OPTIONAL peer this adapter dynamically imports. It is
+ * what the "install this to open that" message names when the import cannot
+ * resolve — the registry never installs anything itself.
+ */
+declare const csvManifest: AdapterManifest;
+
+/**
+ * Word documents. `.doc` (the pre-2007 binary format) is deliberately absent:
+ * mammoth reads OOXML only, and claiming an extension we cannot open would trade
+ * an honest "can't preview this file type" panel for a parse error.
+ */
+declare const docxManifest: AdapterManifest;
+
+/**
+ * Eager, data-only (see `image-manifest.ts`).
+ *
+ * `.mdx` is deliberately NOT claimed: it is JavaScript wearing markdown, and
+ * rendering it would mean evaluating a foreign file's code — the one thing a
+ * viewer must never do. An `.mdx` falls through to the plain-text adapter.
+ */
+declare const markdownManifest: AdapterManifest;
+
+/**
+ * Eager, data-only. Split from the adapter module so `createDefaultRegistry`
+ * can answer "can this be opened, and what controls apply" without pulling the
+ * renderer into the entry chunk.
+ */
+declare const imageManifest: AdapterManifest;
+
+/** Eager, data-only (see `image-manifest.ts`). */
+declare const jsonManifest: AdapterManifest;
+
+/**
+ * Eager, data-only.
+ *
+ * No `requires`: the browser is the decoder, so this adapter has no optional
+ * peer and can never report `parser-missing`. A codec the browser cannot play is
+ * a different failure — the `<video>` element's own `error` event — and it is
+ * reported where it happens, in the renderer.
+ */
+declare const mediaManifest: AdapterManifest;
+
+/**
+ * Eager, data-only. Split from the adapter module so `createDefaultRegistry`
+ * can answer "can this be opened, and what controls apply" without pulling
+ * pdf.js — a ~1 MB engine — into the entry chunk.
+ *
+ * `requires` is what the "install this" message names when `pdfjs-dist` is not
+ * present: the adapter is registered either way, so the reader is told what is
+ * missing instead of being told the file type is unsupported.
+ *
+ * The only adapter that declares `rect`: a PDF page has a fixed coordinate
+ * space, so a producer that knows where a passage sits on the page — an OCR
+ * pipeline, a layout-aware chunker — can address it geometrically and skip the
+ * text projection entirely.
+ */
+declare const pdfManifest: AdapterManifest;
+
+/**
+ * PowerPoint decks. `.ppt` (the pre-2007 binary format) is not a zip at all, so
+ * it is deliberately absent rather than claimed and then failed on.
+ *
+ * `requires: ["jszip"]` — the deck is unzipped here and the XML is parsed with
+ * the platform's own `DOMParser`, so there is no PowerPoint library to install.
+ */
+declare const pptxManifest: AdapterManifest;
+
+/**
+ * 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.
+ */
+declare const textManifest: AdapterManifest;
+
+/**
+ * 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.
+ */
+declare const xlsxManifest: AdapterManifest;
+
+/**
+ * The built-in adapters, and the registry that has them all.
+ *
+ * Every entry is `manifest` (eager, plain data) + `() => import(…)` (lazy). The
+ * manifests are imported statically ON PURPOSE — they are a few dozen bytes of
+ * data each and answer "can this be opened, and what controls apply" with no
+ * network. The parsers and renderers behind them are not.
+ *
+ * `pnpm heavy-deps:check` enforces the split: a static import of `papaparse`
+ * (or, from P1, `pdfjs-dist`) fails CI, because those are optional peers — a
+ * static edge does not merely bloat a chunk, it makes the package unresolvable
+ * for every consumer that did not install that parser.
+ */
+
+/**
+ * A registry with every built-in adapter registered.
+ *
+ * Call it per app (or per view) rather than sharing one module-level instance,
+ * so one screen's `register()` override cannot leak into another's.
+ */
+declare function createDefaultRegistry(): ViewerRegistry;
+
+/**
+ * The pdf.js seam — one place that knows the engine exists.
+ *
+ * Everything here is deliberately NOT React. Splitting the engine wiring from
+ * the renderer keeps two things true: the dynamic `import("pdfjs-dist")` has a
+ * single call site (so `heavy-deps:check` has one edge to police), and an app
+ * can configure the worker before any file is ever opened.
+ *
+ * ## Why a worker is not optional
+ *
+ * pdf.js parses and rasterizes on a worker thread; without one it falls back to
+ * doing that on the main thread, and a 40-page document freezes the tab. The
+ * default below resolves the worker that ships INSIDE `pdfjs-dist`, via
+ * `new URL(…, import.meta.url)` — the form every modern bundler understands, so
+ * it works with no configuration in Vite/webpack/Next.
+ *
+ * ## Why an app may still have to configure it
+ *
+ * A CSP without `worker-src blob:` — or a bundler that cannot see through the
+ * `new URL` form — needs the worker served as a real asset instead. Hence
+ * {@link configurePdfEngine}: set `workerSrc` to a URL your app serves, and the
+ * default is never consulted. `cMapUrl` / `standardFontDataUrl` are the same
+ * story for CJK text and non-embedded fonts, which pdf.js fetches on demand.
+ */
+/** Engine wiring an app can override. Every field is optional. */
+interface PdfEngineConfig {
+    /** URL of `pdf.worker.min.mjs`. Defaults to the copy inside `pdfjs-dist`. */
+    workerSrc?: string;
+    /** Directory of pdf.js `cmaps/`, for documents with CJK text. */
+    cMapUrl?: string;
+    /** Directory of pdf.js `standard_fonts/`, for documents that embed no fonts. */
+    standardFontDataUrl?: string;
+}
+/**
+ * Point the PDF adapter at your own copies of the pdf.js assets.
+ *
+ * Call once at app start, before a PDF is opened. Calling it later is harmless
+ * but only affects documents opened afterwards — pdf.js reads the worker
+ * setting when a document is created.
+ */
+declare function configurePdfEngine(next: PdfEngineConfig): void;
+/** What the adapter will actually use, after any {@link configurePdfEngine} call. */
+declare function getPdfEngineConfig(): Readonly<PdfEngineConfig>;
+
+export { ACTIVE_HIGHLIGHT_SELECTOR, type AdapterCapabilities, type AdapterDocument, type AdapterLoadContext, type AdapterLoader, type AdapterManifest, type AdapterModule, type AdapterRendererProps, DEFAULT_ZOOM, type DocumentHighlight, type DocumentRotation, FIND_MATCH_LIMIT, type FileAdapter, FileViewer, type FileViewerActions, FileViewerContent, type FileViewerContentProps, type FileViewerContextValue, FileViewerEmpty, FileViewerError, FileViewerFind, type FileViewerFindProps, type FileViewerFindState, FileViewerFrame, type FileViewerFrameProps, FileViewerHighlightStatus, type FileViewerHighlightStatusProps, type FileViewerLoadState, FileViewerPager, type FileViewerPagerProps, type FileViewerProps, FileViewerProvider, type FileViewerProviderProps, FileViewerRotate, type FileViewerRotateProps, FileViewerSkeleton, type FileViewerState, type FileViewerStatus, FileViewerToolbar, type FileViewerToolbarProps, type FileViewerViewState, FileViewerZoom, type FileViewerZoomProps, type HighlightMissReason, type HighlightResolveContext, type HighlightSource, type HighlightStatus, type HighlightSupport, type MarkRanges, PROTOCOL_VERSION, type PdfEngineConfig, type ResolvedHighlight, type SpanOverlap, type TextIndex, type TextIndexBuilder, type TextIndexBuilderOptions, type TextSpan, VIEWER_ZOOM_STEPS, ViewerError, type ViewerErrorCode, type ViewerErrorOptions, type ViewerRegistry, type ZoomFit, type ZoomLevel, canStepZoom, chunkOffset, codeManifest, configurePdfEngine, createDefaultRegistry, createRegistry, createTextIndexBuilder, csvManifest, docxManifest, findMatchId, getPdfEngineConfig, imageManifest, isAbort, isFindMatchId, isFindShortcut, isModuleNotFound, isViewerError, isZoomFit, jsonManifest, localizeRanges, locateQuote, markdownManifest, mediaManifest, parserMissingError, pdfManifest, pptxManifest, resolveHighlights, scoreManifest, spanAt, spansForRange, stepZoom, textManifest, toMarkRanges, toViewerError, useFileViewer, useScrollActiveHighlightIntoView, xlsxManifest };