@embedpdf/engine-core 3.0.0-next.0

package/dist/conformance.d.ts

@@ -0,0 +1,530 @@
+import { An as HighlightDraft, Cc as InkList, Ec as PdfPoint, Oc as PdfRect, Tc as LinePoints, Vc as DocumentMetadata, n as AnnotationListSnapshotAllPages, t as AnnotationListPageSnapshot } from "./AnnotationListSnapshot-W0RCsyDE.js";
+import { t as Engine } from "./Engine-B7Oe7f5i.js";
+//#region src/conformance/runMetadataConformance.d.ts
+interface ConformanceTestRunner {
+  describe(name: string, fn: () => void): void;
+  test(name: string, fn: () => void | Promise<void>): void;
+  beforeAll(fn: () => void | Promise<void>): void;
+  afterAll(fn: () => void | Promise<void>): void;
+  expect: ConformanceExpect;
+}
+interface ConformanceExpect {
+  (actual: unknown): {
+    toBe(expected: unknown): void;
+    toBeNull(): void;
+    toEqual(expected: unknown): void;
+    toHaveLength(expected: number): void;
+    toMatch(re: RegExp): void;
+    toMatchObject(shape: Record<string, unknown>): void;
+    toBeInstanceOf(ctor: Function): void;
+    toBeTruthy(): void;
+    rejects: {
+      toBeInstanceOf(ctor: Function): Promise<void>;
+      toMatchObject(shape: Record<string, unknown>): Promise<void>;
+    };
+    resolves: {
+      toMatchObject(shape: Record<string, unknown>): Promise<void>;
+      toEqual(expected: unknown): Promise<void>;
+    };
+  };
+}
+interface ConformanceFixture {
+  /** Stable id used for the local engine; cloud uses its own id. */
+  id: string;
+  /** Bytes for the local engine. */
+  bytes: () => Uint8Array | Promise<Uint8Array>;
+  /** Override the cloud-side id. Defaults to `id`. */
+  cloudId?: string;
+  /** The expected document metadata. Used for parity assertions. */
+  expected: Partial<DocumentMetadata>;
+}
+interface ConformanceOptions {
+  label: string;
+  /** Build a fresh engine for this suite. Suite tears it down at the end. */
+  makeEngine: () => Promise<Engine> | Engine;
+  /** Sample fixture for the happy-path metadata read. */
+  fixture: ConformanceFixture;
+  /** Engine 'kind' for opening: 'bytes' for local, 'id' for cloud. */
+  openKind: 'bytes' | 'id';
+}
+/**
+ * The conformance harness is transport-agnostic. It takes the test runner as
+ * a parameter so engine-core has no dependency on vitest/jest/node:test.
+ */
+declare function runMetadataConformance(runner: ConformanceTestRunner, opts: ConformanceOptions): void;
+//#endregion
+//#region src/conformance/runAnnotationReadConformance.d.ts
+/**
+ * Expected per-fixture annotation knowledge. The harness asserts against
+ * these without locking the exact wire content, so different fixtures can
+ * be added by suites without rewriting the harness.
+ */
+interface AnnotationReadConformanceFixture extends ConformanceFixture {
+  /** PDF object number of the page used by the annotation tests. */
+  pageObjectNumber: number;
+  /** The total annotation count expected on that page (across all subtypes). */
+  expectedAnnotationCount: number;
+  /** At least this many `'highlight'` annotations on the page. */
+  minHighlightCount: number;
+  /** At least this many `'unsupported'` annotations on the page. */
+  minUnsupportedCount: number;
+  /** At least this many `'circle'` annotations on the page. Defaults to 0. */
+  minCircleCount?: number;
+  /** At least this many `'square'` annotations on the page. Defaults to 0. */
+  minSquareCount?: number;
+  /** At least this many `'polygon'` annotations on the page. Defaults to 0. */
+  minPolygonCount?: number;
+  /** At least this many `'polyline'` annotations on the page. Defaults to 0. */
+  minPolylineCount?: number;
+  /** At least this many `'line'` annotations on the page. Defaults to 0. */
+  minLineCount?: number;
+  /** At least this many `'ink'` annotations on the page. Defaults to 0. */
+  minInkCount?: number;
+  /** At least this many `'free-text'` annotations on the page. Defaults to 0. */
+  minFreeTextCount?: number;
+  /** At least this many `'caret'` annotations on the page. Defaults to 0. */
+  minCaretCount?: number;
+  /**
+   * `true` if the fixture has at least one weak annotation (no /NM, direct
+   * object). Drives the weak-ref + revision tests.
+   */
+  expectsWeakAnnotation: boolean;
+}
+interface AnnotationConformanceOptions extends Omit<ConformanceOptions, 'fixture'> {
+  fixture: AnnotationReadConformanceFixture;
+}
+declare function runAnnotationReadConformance(runner: ConformanceTestRunner, opts: AnnotationConformanceOptions): void;
+//#endregion
+//#region src/conformance/runActionsConformance.d.ts
+interface ActionsConformanceFixtures {
+  document: ConformanceFixture;
+  page: ConformanceFixture;
+  annotation: ConformanceFixture;
+  field: ConformanceFixture;
+  /** A page whose only annotation is a Link with a `/S /JavaScript` action.
+   *  Optional: the javascript-link classification test skips without it. */
+  javascriptLink?: ConformanceFixture;
+}
+interface ActionsConformanceOptions {
+  label: string;
+  makeEngine: () => Promise<Engine> | Engine;
+  fixtures: ActionsConformanceFixtures;
+  openKind: 'bytes' | 'id';
+}
+/** Action extraction parity. These tests assert data only; no script executes. */
+declare function runActionsConformance(runner: ConformanceTestRunner, opts: ActionsConformanceOptions): void;
+//#endregion
+//#region src/conformance/runAnnotationMutationConformance.d.ts
+/**
+ * Per-fixture knowledge the mutation harness needs. The shared fixture
+ * fields (id, bytes, etc.) come from `ConformanceFixture`; the bits below
+ * pin the test page. The harness asserts behaviour, not exact wire
+ * content, so the same fixture can run against both local (WASM) and
+ * cloud (native via @cloudpdf/server) engines.
+ */
+interface AnnotationMutationConformanceFixture extends ConformanceFixture {
+  /** PDF object number of the page used by the mutation tests. */
+  pageObjectNumber: number;
+  /** Page already has at least one weak annotation (no /NM, direct object). */
+  expectsWeakAnnotation: boolean;
+  /**
+   * QuadPoints to use for the create() smoke test. Coordinates are in
+   * PDF user space; pick a small rectangle that fits anywhere on the
+   * fixture page so we don't flake on different page sizes.
+   */
+  createQuad?: HighlightDraft['quadPoints'];
+  /**
+   * `/Rect` to use for the shape (circle/square) create tests. PDF user
+   * space; pick a small box that fits anywhere on the fixture page.
+   */
+  createShapeRect?: PdfRect;
+  /**
+   * `/Vertices` to use for the polygon/polyline create tests. PDF user
+   * space; must fit inside `createShapeRect` (the rect the engine bakes
+   * the appearance into). Defaults to a small triangle.
+   */
+  createVertices?: PdfPoint[];
+  /**
+   * `/L` endpoints to use for the line create test. PDF user space; must
+   * fit inside `createShapeRect`. Defaults to the rect's diagonal.
+   */
+  createLinePoints?: LinePoints;
+  /**
+   * `/InkList` strokes to use for the ink create test. PDF user space; must
+   * fit inside `createShapeRect`. Defaults to a single short stroke.
+   */
+  createInkList?: InkList;
+}
+interface AnnotationMutationConformanceOptions extends Omit<ConformanceOptions, 'fixture'> {
+  fixture: AnnotationMutationConformanceFixture;
+  /**
+   * `true` for engines that expose the raw RGBA appearance rasters
+   * (`renderAppearances`). When set, the shape-create test additionally
+   * asserts that creating a shape produces a baked `/AP` the appearance
+   * reader can rasterize. The cloud engine ships encoded images instead
+   * and leaves this `false`.
+   */
+  supportsAppearanceRasters?: boolean;
+}
+/**
+ * Mutation conformance suite. Mirrors the read suite: tests are written
+ * once and run against any engine that satisfies the public API
+ * surface. Both local (worker host + WASM) and cloud (HTTP +
+ * @cloudpdf/server) implementations must pass identically.
+ *
+ * The locked rules being verified here:
+ *   - `create` is append-only: PDFium drops the new annotation at
+ *     `index = previousCount`, so no existing index shifts. Treated
+ *     as non-invalidating — revisions do NOT bump and weak refs
+ *     captured before the create remain valid.
+ *   - `update` is non-structural; revisions do NOT bump.
+ *   - Opportunistic /NM stamp upgrades a weak annotation's ref to
+ *     `kind: 'nm'` on update; an already-durable annotation's /NM is
+ *     NEVER touched.
+ *   - `delete` and `move` are the only index-shifting ops. They bump
+ *     the per-page revision and, on a page that had weak refs before
+ *     the mutation, surface `shouldRefetch: 'weakRefsInvalidated'`.
+ *   - Abort propagates as `AbortError` even before the worker
+ *     responds.
+ */
+declare function runAnnotationMutationConformance(runner: ConformanceTestRunner, opts: AnnotationMutationConformanceOptions): void;
+//#endregion
+//#region src/conformance/runFormConformance.d.ts
+/**
+ * The three fixtures the forms suite needs. Shapes (names, object numbers,
+ * values) match the pdf-runtime fork's test resources:
+ *
+ * - `toggleFields` — toggle_fields.pdf: text field `maxlen_text`
+ *   (/MaxLen 5, value "abc"), radio `ntto_radio` (NoToggleToOff, /DV x,
+ *   widgets x/y), radio `unison_radio` (RadiosInUnison), checkbox
+ *   `opt_check` (/Opt "Alpha", on-state "On"), hierarchical text field
+ *   `billing.name`.
+ * - `orphanWidgets` — orphan_widgets.pdf: `linked_text` in /AcroForm
+ *   /Fields plus RECOVERED `orphan_check` and `orphan_radio`.
+ * - `choiceFields` — listbox_form.pdf: `Listbox_MultiSelect` (options
+ *   Apple..), `Listbox_SingleSelect`.
+ */
+interface FormConformanceFixtures {
+  /** toggle_fields.pdf; `pageObjectNumber` = its single page (object 3). */
+  toggleFields: ConformanceFixture & {
+    pageObjectNumber: number;
+  };
+  orphanWidgets: ConformanceFixture;
+  choiceFields: ConformanceFixture;
+  /**
+   * A second, independent copy of `toggleFields` used as the XFDF import
+   * target. Required for `openKind: 'id'` (cloud) — id-opened documents are
+   * server-side state, so the suite cannot mint a copy by re-opening the
+   * same bytes under a suffixed id the way the bytes transport does.
+   */
+  importTarget?: ConformanceFixture;
+}
+interface FormConformanceOptions extends Omit<ConformanceOptions, 'fixture'> {
+  fixtures: FormConformanceFixtures;
+}
+declare function runFormConformance(runner: ConformanceTestRunner, opts: FormConformanceOptions): void;
+//#endregion
+//#region src/conformance/runAnnotationAppearanceConformance.d.ts
+/**
+ * Per-fixture knowledge for the annotation appearance conformance suite. The
+ * harness asserts thresholds (not exact wire content) so the same suite runs
+ * unchanged against the local and cloud engines and proves they emit the same
+ * set of appearances — including weak (index-only) annotations.
+ */
+interface AnnotationAppearanceConformanceFixture extends ConformanceFixture {
+  /** PDF object number of the page whose appearances are rendered. */
+  pageObjectNumber: number;
+  /** At least this many `/AP` appearances are expected on that page. */
+  minAppearanceCount: number;
+  /**
+   * `true` when the page has at least one weak (index-only) annotation that
+   * carries an appearance stream. The whole point of this suite: that weak
+   * appearance must still be emitted (it used to be dropped on the wire).
+   */
+  expectsWeakAppearance: boolean;
+}
+interface AnnotationAppearanceConformanceOptions extends Omit<ConformanceOptions, 'fixture'> {
+  fixture: AnnotationAppearanceConformanceFixture;
+  /**
+   * `true` for engines that expose the raw RGBA rasters (`renderAppearances`).
+   * The local engine's encoder needs a browser Canvas, so under node it can
+   * only be exercised via the raw rasters; the cloud engine ships encoded
+   * images (`renderAppearanceImages`) and leaves this `false`.
+   */
+  supportsRawRasters?: boolean;
+}
+declare function runAnnotationAppearanceConformance(runner: ConformanceTestRunner, opts: AnnotationAppearanceConformanceOptions): void;
+//#endregion
+//#region src/conformance/runPageReorderConformance.d.ts
+/**
+ * Per-fixture knowledge for the page-reorder suite. The test pages must
+ * be addressable by indirect `pageObjectNumber` (every page in our
+ * fixtures is). The fixture is expected to have at least 3 pages so the
+ * harness can exercise reorder permutations meaningfully.
+ */
+interface PageReorderConformanceFixture extends ConformanceFixture {
+  /** Stable, durable PONs of (at least) three distinct pages. Order
+   *  here is the *intended caller-visible* order, not the on-disk
+   *  order; the suite reads `pages.list()` first and works in document
+   *  order. */
+  ponsForReorderTest?: number[];
+  /**
+   * Page used for the weak-ref-survival assertion. Defaults to the
+   * first PON in `ponsForReorderTest`. The fixture page must already
+   * have at least one weak annotation (no /NM, direct object) so the
+   * harness can capture an `index`-kind ref before the page move and
+   * re-use it after.
+   */
+  weakRefHostPon?: number;
+  /** Quad to use for the `create()` step that produces a stable ref
+   *  the suite uses. */
+  createQuad?: HighlightDraft['quadPoints'];
+}
+interface PageReorderConformanceOptions extends Omit<ConformanceOptions, 'fixture'> {
+  fixture: PageReorderConformanceFixture;
+}
+/**
+ * Page reorder conformance suite. Verifies the architectural invariants
+ * locked with the user, do NOT loosen these without re-reading
+ * `PageMoveResult` and `DocumentPagesMutator`:
+ *
+ *   1. `pages.list()` returns every page in display order, addressed
+ *      by indirect `pageObjectNumber`.
+ *   2. `pages.move()` returns the full new order + geometry via
+ *      `result.layout` (the same shape `pages.list()` returns). There is
+ *      no document-level revision; the wire never asks the caller for one.
+ *   3. Index-based annotation refs survive a page reorder. This is the
+ *      whole reason per-page revisions stay put across a move: a user
+ *      shuffling pages mid-edit must not lose a pending highlight. (The
+ *      "move never bumps a RevisionToken" invariant is asserted directly
+ *      in the annotation mutation suite, where revision liveness lives.)
+ *   4. Invalid inputs (duplicate PONs, unknown PONs, out-of-range
+ *      `destIndex`) reject with `InvalidArg`.
+ *   5. Abort propagates as `AbortError`.
+ *
+ * Both local (worker host + WASM) and cloud (HTTP + @cloudpdf/server)
+ * implementations must pass identically.
+ */
+declare function runPageReorderConformance(runner: ConformanceTestRunner, opts: PageReorderConformanceOptions): void;
+//#endregion
+//#region src/conformance/runPageRotateConformance.d.ts
+/**
+ * Page rotate conformance suite. Verifies the architectural invariants —
+ * do NOT loosen these without re-reading `PageRotateResult`:
+ *
+ *   1. Rotation is ABSOLUTE and idempotent: `rotate(pons, 90)` twice is
+ *      `rotate(pons, 90)` once. The wire never speaks "turn by".
+ *   2. Rotation is presentation metadata over NORMALIZED content: the
+ *      layout's `width`/`height` stay un-rotated, order and identity are
+ *      untouched, and per-page `RevisionToken`s survive (an index-based
+ *      annotation ref captured before the rotate works after it).
+ *   3. The result returns the full new `layout`; a subsequent `list()`
+ *      agrees with it.
+ *   4. Invalid inputs (bad rotation value, duplicate PONs, unknown PONs)
+ *      reject with `InvalidArg` / `NotFound`.
+ *   5. Abort propagates as `AbortError`.
+ *
+ * Both local (worker host + WASM) and cloud (HTTP + @cloudpdf/server)
+ * implementations must pass identically.
+ */
+declare function runPageRotateConformance(runner: ConformanceTestRunner, opts: ConformanceOptions): void;
+//#endregion
+//#region src/conformance/runPageDeleteConformance.d.ts
+/**
+ * Page delete conformance suite. Verifies the architectural invariants —
+ * do NOT loosen these without re-reading `PageDeleteResult`:
+ *
+ *   1. `pages.delete()` removes exactly the listed pages and returns the
+ *      full surviving layout; a subsequent `list()` agrees.
+ *   2. Deleted PONs are RETIRED: addressing a deleted page afterwards is a
+ *      clean `NotFound` (an API-level error, never native-memory danger).
+ *   3. SURVIVING pages keep identity and `RevisionToken`s — an index-based
+ *      annotation ref on an unrelated page survives a neighbour's deletion.
+ *   4. Deleting every page is rejected (`InvalidArg`) — a document keeps at
+ *      least one page.
+ *   5. Duplicate / unknown PONs reject with `InvalidArg` / `NotFound`;
+ *      abort propagates as `AbortError`.
+ *
+ * Both local (worker host + WASM) and cloud (HTTP + @cloudpdf/server)
+ * implementations must pass identically.
+ */
+declare function runPageDeleteConformance(runner: ConformanceTestRunner, opts: ConformanceOptions): void;
+//#endregion
+//#region src/conformance/runPageFlattenConformance.d.ts
+/** Transport-neutral coverage for the content + annotation flatten rail. */
+declare function runPageFlattenConformance(runner: ConformanceTestRunner, opts: ConformanceOptions): void;
+//#endregion
+//#region src/conformance/runRedactionApplyConformance.d.ts
+/**
+ * Transport-neutral coverage for the destructive redaction-apply rail.
+ * Runs against a fixture page with NO pre-existing annotations so the
+ * collateral counts are exact. Content-removal fidelity itself is pinned by
+ * the native embeddertests; this suite pins the transport contract: scopes,
+ * statuses, counts, revision bumps, events, and preflight rejection.
+ */
+declare function runRedactionApplyConformance(runner: ConformanceTestRunner, opts: ConformanceOptions): void;
+//#endregion
+//#region src/conformance/runPageExtractConformance.d.ts
+/**
+ * Page extract conformance suite. `pages.extract?` is OPTIONAL on the
+ * contract (the `downloadLayer?` pattern) — the suite runs only when the
+ * implementation provides it, so a cloud engine that has not shipped the
+ * server endpoint yet skips cleanly instead of failing.
+ *
+ * Invariants:
+ *   1. `pages.extract([pon])` returns standalone PDF bytes (magic header).
+ *   2. The SOURCE document is untouched: identical layout before/after,
+ *      and page revisions do not bump (extract is a read).
+ *   3. Caller order is preserved and page geometry survives the copy
+ *      (asserted by re-opening the extracted bytes — bytes-open engines
+ *      only, since a cloud engine cannot re-open loose bytes).
+ *   4. Empty / duplicate PONs reject `InvalidArg`; unknown PONs reject
+ *      `NotFound` (or `InvalidArg`); abort propagates as `AbortError`.
+ */
+declare function runPageExtractConformance(runner: ConformanceTestRunner, opts: ConformanceOptions): void;
+//#endregion
+//#region src/conformance/runAttachmentConformance.d.ts
+/**
+ * Attachment conformance suite. Fixture requirement: a document whose
+ * `/EmbeddedFiles` name tree contains AT LEAST ONE embedded file.
+ *
+ * Both attachment surfaces are OPTIONAL on the contract (the
+ * `downloadLayer?` pattern), probed independently and skipped cleanly:
+ *   - `doc.attachments?` — document-level EmbeddedFiles (list/download)
+ *   - `page.annotations.downloadFile?` — annotation-level file bytes
+ *
+ * Invariants:
+ *   1. `list()` reflects the name tree: positional indices, non-empty
+ *      names, and repeated calls agree (a read).
+ *   2. `download(index)` round-trips the listed metadata and returns
+ *      exactly `size` decoded bytes when the fixture declares one.
+ *   3. Unknown indices reject with an `EngineError`.
+ *   4. A created file-attachment annotation round-trips its file:
+ *      metadata inline on the DTO (never bytes), bytes byte-identical
+ *      through `downloadFile(ref)`.
+ *   5. A created text (sticky-note) annotation round-trips icon + color.
+ */
+declare function runAttachmentConformance(runner: ConformanceTestRunner, opts: ConformanceOptions): void;
+//#endregion
+//#region src/conformance/runPageInsertConformance.d.ts
+/**
+ * Page insert conformance. `pages.insert?` is optional only until the cloud
+ * endpoint ships (it is slated REQUIRED-parity — a cloud viewer must be able
+ * to add pages); the suite runs wherever the implementation exists.
+ *
+ * Invariants:
+ *   1. Every page of the source bytes is COPIED in at `destIndex` (omitted →
+ *      append), in source order; the result lists the fresh PONs in
+ *      insertion order and they agree with the returned layout.
+ *   2. Pre-existing pages keep their identity: same PONs before and after,
+ *      in the expected positions (an insert never invalidates neighbours).
+ *   3. The mutation persists through save → re-open (bytes engines only).
+ *   4. Empty bytes / malformed bytes / out-of-range destIndex reject with
+ *      InvalidArg / MalformedPdf, leaving the document untouched.
+ */
+declare function runPageInsertConformance(runner: ConformanceTestRunner, opts: ConformanceOptions): void;
+//#endregion
+//#region src/conformance/runPieceInfoConformance.d.ts
+/**
+ * `/PieceInfo` conformance (doc + page level). The service is OPTIONAL on
+ * the contract (`downloadLayer?` pattern) — the suite runs only where the
+ * implementation provides it, so an engine that has not shipped it yet
+ * skips cleanly.
+ *
+ * Invariants:
+ *   1. The full value vocabulary round-trips at both levels: string,
+ *      number, boolean, name, string-array — read back with the same tags.
+ *   2. Writes PERSIST: download() → re-open → identical read (bytes-open
+ *      engines only, since cloud cannot re-open loose bytes).
+ *   3. `null` deletes a key; sibling keys and sibling applications
+ *      survive both key deletes and whole-entry clears.
+ *   4. An absent application reads as `null`; `applications()` enumerates
+ *      what is present; every write refreshes `lastModified`.
+ */
+declare function runPieceInfoConformance(runner: ConformanceTestRunner, opts: ConformanceOptions): void;
+//#endregion
+//#region src/conformance/runDocumentEventsConformance.d.ts
+/**
+ * Document event stream conformance suite. Verifies the invariants the
+ * collaboration design rests on — do NOT loosen these without re-reading
+ * `DocumentEvent`:
+ *
+ *   1. EXACTLY ONCE: every confirmed mutation produces exactly one event,
+ *      in mutation order, regardless of engine (local worker or cloud HTTP).
+ *   2. GROUND TRUTH: a failed mutation publishes nothing; events fire only
+ *      after confirmation.
+ *   3. RESULTS RIDE VERBATIM: each event embeds the result the caller
+ *      received, deep-equal field for field.
+ *   4. PROVENANCE: own mutations are `origin.kind: 'local'` with a stable
+ *      per-engine-instance `sessionId`.
+ *   5. Unsubscribe stops delivery.
+ *
+ * Both local (worker host + WASM) and cloud (HTTP + @cloudpdf/server)
+ * implementations must pass identically.
+ */
+declare function runDocumentEventsConformance(runner: ConformanceTestRunner, opts: ConformanceOptions): void;
+//#endregion
+//#region src/conformance/runPageTextConformance.d.ts
+/**
+ * Per-fixture expectations for the text-extraction harness. Concrete
+ * suites supply the page identity + a substring the harness asserts
+ * exists in the extracted text. The harness deliberately avoids
+ * locking the exact string so different fixtures (or PDFium upgrades
+ * that change whitespace handling) don't require harness edits.
+ */
+interface PageTextConformanceFixture extends ConformanceFixture {
+  /** PDF indirect object number of the page used by the text tests. */
+  pageObjectNumber: number;
+  /**
+   * Substring guaranteed to appear in the extracted text. The harness
+   * uses `.includes(needle)`; suites should pick something distinctive
+   * but not whitespace-sensitive.
+   */
+  expectedSubstring: string;
+  /** Minimum char count the harness expects (sanity floor). */
+  minCharCount: number;
+}
+interface PageTextConformanceOptions extends Omit<ConformanceOptions, 'fixture'> {
+  fixture: PageTextConformanceFixture;
+}
+declare function runPageTextConformance(runner: ConformanceTestRunner, opts: PageTextConformanceOptions): void;
+//#endregion
+//#region src/conformance/runSearchConformance.d.ts
+/**
+ * Per-fixture expectations for the search harness. Suites supply a
+ * literal known to be on a specific page, one known to be nowhere, and a
+ * regex with a predictable hit — the harness asserts behavior (offsets,
+ * rects, snippets, cursor mechanics, dialect rejection), never exact
+ * match counts, so PDFium text-extraction tweaks don't require edits.
+ */
+interface SearchConformanceFixture extends ConformanceFixture {
+  /** Literal present in the document at least once. */
+  presentLiteral: string;
+  /** A page (pon) guaranteed to carry a `presentLiteral` match. */
+  presentPageObjectNumber: number;
+  /** Literal guaranteed to match nowhere. */
+  absentLiteral: string;
+  /** Dialect-valid regex with at least one match in the document. */
+  presentRegex: string;
+}
+interface SearchConformanceOptions extends Omit<ConformanceOptions, 'fixture'> {
+  fixture: SearchConformanceFixture;
+}
+declare function runSearchConformance(runner: ConformanceTestRunner, opts: SearchConformanceOptions): void;
+//#endregion
+//#region src/conformance/diffAnnotationListSnapshot.d.ts
+/**
+ * Returns a list of human-readable difference strings between two
+ * snapshots. Empty array means parity. Used by `engine-node.ts` to assert
+ * that local and cloud emit identical annotations for the same fixture.
+ *
+ * `RevisionToken.docSessionId` is intentionally NOT compared — sessions
+ * are disjoint. We do compare `pageObjectNumber` and `generation` (which
+ * should be 0 for fresh reads on both sides). Page order is no longer part
+ * of `PageState`; it lives in `PageLayout.index` (see `pages.list()`).
+ */
+declare function diffAnnotationListSnapshot(a: AnnotationListPageSnapshot, b: AnnotationListPageSnapshot): string[];
+declare function diffAnnotationListSnapshotAll(a: AnnotationListSnapshotAllPages, b: AnnotationListSnapshotAllPages): string[];
+//#endregion
+export { type ActionsConformanceFixtures, type ActionsConformanceOptions, type AnnotationAppearanceConformanceFixture, type AnnotationAppearanceConformanceOptions, type AnnotationConformanceOptions, type AnnotationMutationConformanceFixture, type AnnotationMutationConformanceOptions, type AnnotationReadConformanceFixture, type ConformanceExpect, type ConformanceFixture, type ConformanceOptions, type ConformanceTestRunner, type FormConformanceFixtures, type FormConformanceOptions, type PageReorderConformanceFixture, type PageReorderConformanceOptions, type PageTextConformanceFixture, type PageTextConformanceOptions, type SearchConformanceFixture, type SearchConformanceOptions, diffAnnotationListSnapshot, diffAnnotationListSnapshotAll, runActionsConformance, runAnnotationAppearanceConformance, runAnnotationMutationConformance, runAnnotationReadConformance, runAttachmentConformance, runDocumentEventsConformance, runFormConformance, runMetadataConformance, runPageDeleteConformance, runPageExtractConformance, runPageFlattenConformance, runPageInsertConformance, runPageReorderConformance, runPageRotateConformance, runPageTextConformance, runPieceInfoConformance, runRedactionApplyConformance, runSearchConformance };
+//# sourceMappingURL=conformance.d.ts.map