@embedpdf/engine-core 3.0.0-next.0 → 3.0.0-next.10

package/dist/conformance.d.cts

@@ -1,5 +1,5 @@
-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.cjs";
-import { t as Engine } from "./Engine-D9loFZc1.cjs";
+import { An as HighlightDraft, Ss as CharMapAnchor, al as LinePoints, cl as PdfRect, n as AnnotationListSnapshotAllPages, ol as PdfPoint, rl as InkList, t as AnnotationListPageSnapshot, xl as DocumentMetadata } from "./AnnotationListSnapshot-DDxHpJQU.cjs";
+import { t as Engine } from "./Engine-D9je6GdU.cjs";
 //#region src/conformance/runMetadataConformance.d.ts
 interface ConformanceTestRunner {
   describe(name: string, fn: () => void): void;
@@ -408,9 +408,9 @@ declare function runAttachmentConformance(runner: ConformanceTestRunner, opts: C
 //#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.
+ * Page insert conformance. `pages.insert` is a REQUIRED member — this suite
+ * runs unconditionally on every engine, so an implementation that loses the
+ * verb fails loudly instead of being skipped past.
  *
  * Invariants:
  *   1. Every page of the source bytes is COPIED in at `destIndex` (omitted →
@@ -424,6 +424,26 @@ declare function runAttachmentConformance(runner: ConformanceTestRunner, opts: C
  */
 declare function runPageInsertConformance(runner: ConformanceTestRunner, opts: ConformanceOptions): void;
 //#endregion
+//#region src/conformance/runPageInsertBlankConformance.d.ts
+/**
+ * Blank-page insert conformance. `pages.insertBlank` is a REQUIRED member —
+ * the suite runs unconditionally on every engine (no fixture bytes are
+ * needed at all, which is the point of the verb), so an implementation that
+ * loses the verb fails loudly instead of being skipped past.
+ *
+ * Invariants:
+ *   1. `count` blank pages of exactly `size` appear at `destIndex` (omitted
+ *      → append), rotation 0; the result lists their 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. Non-positive size / count outside [1, PAGE_INSERT_BLANK_MAX_COUNT] /
+ *      out-of-range destIndex reject with InvalidArg, leaving the document
+ *      untouched.
+ */
+declare function runPageInsertBlankConformance(runner: ConformanceTestRunner, opts: ConformanceOptions): void;
+//#endregion
 //#region src/conformance/runPieceInfoConformance.d.ts
 /**
  * `/PieceInfo` conformance (doc + page level). The service is OPTIONAL on
@@ -489,6 +509,102 @@ interface PageTextConformanceOptions extends Omit<ConformanceOptions, 'fixture'>
 }
 declare function runPageTextConformance(runner: ConformanceTestRunner, opts: PageTextConformanceOptions): void;
 //#endregion
+//#region src/conformance/runTextDivergenceConformance.d.ts
+/**
+ * Index-space divergence conformance: the cases where a page's CHARACTER
+ * space (what geometry tiles and selection/search ranges address) and its
+ * extracted TEXT differ — and the `charMap` contract that bridges them.
+ *
+ * Fixtures pin EXACT values (text, charCount, anchors) verified against the
+ * wasm runtime, so both engines must produce byte-identical snapshots:
+ *
+ *   - a non-printing character occupying a character slot with no text unit
+ *     (`bug_1139.pdf` — every text offset shifts by one);
+ *   - `/ActualText` replacement (`bug_384770169.pdf` — synthetic `kPiece`
+ *     characters in lockstep with the text, identity map, real segments);
+ *   - supplementary-plane text via a ToUnicode surrogate pair
+ *     (`embedpdf_astral_tounicode.pdf` — two lockstep surrogate entries,
+ *     identity map, astral content SURVIVES extraction).
+ *
+ * The search probe closes the loop: a hit's `charStart`/`charCount` must be
+ * CHARACTER-space (segments join geometry), and slicing the snapshot by the
+ * hit's range must reproduce the matched text exactly — the law that makes
+ * select-this-match and copy compose.
+ */
+interface TextDivergenceConformanceFixture extends ConformanceFixture {
+  /** PDF indirect object number of the probed page. */
+  pageObjectNumber: number;
+  /** The EXACT extracted text (UTF-16 faithful). */
+  exactText: string;
+  /** The character-space size (may differ from `exactText.length`). */
+  expectedCharCount: number;
+  /** Expected anchors; null asserts identity (no `charMap` on the wire). */
+  expectedCharMap: ReadonlyArray<CharMapAnchor> | null;
+  /** Char-space slice expectations (half-open). */
+  slices?: ReadonlyArray<{
+    from: number;
+    to: number;
+    text: string;
+  }>;
+  /** Literal search probe with expected CHARACTER-space hit range. */
+  search?: {
+    query: string;
+    charStart: number;
+    charCount: number;
+    matchedText: string;
+  };
+}
+interface TextDivergenceConformanceOptions extends Omit<ConformanceOptions, 'fixture'> {
+  fixture: TextDivergenceConformanceFixture;
+}
+declare function runTextDivergenceConformance(runner: ConformanceTestRunner, opts: TextDivergenceConformanceOptions): void;
+/** One divergence case, minus the per-suite bytes/id wiring. */
+type TextDivergenceCase = Omit<TextDivergenceConformanceFixture, 'id' | 'bytes' | 'expected'> & {
+  /** Fixture file name under the fork's `testing/resources/`. */
+  resource: string;
+};
+/**
+ * THE pinned divergence cases — one table, consumed by both engines' suites
+ * so expected values cannot drift. Values verified against the wasm runtime
+ * (see each case). All fixtures are single-page; the page's indirect object
+ * number is 3 in each.
+ */
+declare const TEXT_DIVERGENCE_CASES: Readonly<Record<string, TextDivergenceCase>>;
+//#endregion
+//#region src/conformance/runPageGeometryOrientationConformance.d.ts
+/**
+ * Per-fixture expectations for the oriented-text geometry harness. One
+ * fixture per call, mirroring the other conformance suites; the fixture
+ * declares what its dominant text orientation must read back as.
+ */
+interface PageGeometryOrientationFixture extends ConformanceFixture {
+  /** PDF indirect object number of the page under test. */
+  pageObjectNumber: number;
+  expectation: {
+    /** Every run is the upright variant; no glyph carries oriented cells. */
+    kind: 'upright';
+  } | {
+    /** The page loads and every glyph is degenerate (zeroed + empty flag). */
+    kind: 'empty-only';
+  } | {
+    kind: 'rotated';
+    /** Baseline angles (radians, CCW, PDF y-up) rotated runs may carry. */
+    rotations: number[];
+    ascentFlip: boolean;
+    /**
+     * Assert sheared cells: with `rotations` ≈ [0], a non-zero start-edge
+     * x-offset proves the parallelogram (an AABB could not express it).
+     */
+    sheared?: boolean;
+    /** Minimum number of rotated runs the page must produce (default 1). */
+    minRotatedRuns?: number;
+  };
+}
+interface PageGeometryOrientationOptions extends Omit<ConformanceOptions, 'fixture'> {
+  fixture: PageGeometryOrientationFixture;
+}
+declare function runPageGeometryOrientationConformance(runner: ConformanceTestRunner, opts: PageGeometryOrientationOptions): void;
+//#endregion
 //#region src/conformance/runSearchConformance.d.ts
 /**
  * Per-fixture expectations for the search harness. Suites supply a
@@ -522,9 +638,11 @@ declare function runSearchConformance(runner: ConformanceTestRunner, opts: Searc
  * 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()`).
+ * `auditHead` is likewise not compared: it is a cloud-only reconciliation
+ * cursor, absent on local snapshots by design.
  */
 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 };
+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 PageGeometryOrientationFixture, type PageGeometryOrientationOptions, type PageReorderConformanceFixture, type PageReorderConformanceOptions, type PageTextConformanceFixture, type PageTextConformanceOptions, type SearchConformanceFixture, type SearchConformanceOptions, TEXT_DIVERGENCE_CASES, type TextDivergenceCase, type TextDivergenceConformanceFixture, type TextDivergenceConformanceOptions, diffAnnotationListSnapshot, diffAnnotationListSnapshotAll, runActionsConformance, runAnnotationAppearanceConformance, runAnnotationMutationConformance, runAnnotationReadConformance, runAttachmentConformance, runDocumentEventsConformance, runFormConformance, runMetadataConformance, runPageDeleteConformance, runPageExtractConformance, runPageFlattenConformance, runPageGeometryOrientationConformance, runPageInsertBlankConformance, runPageInsertConformance, runPageReorderConformance, runPageRotateConformance, runPageTextConformance, runPieceInfoConformance, runRedactionApplyConformance, runSearchConformance, runTextDivergenceConformance };
 //# sourceMappingURL=conformance.d.cts.map

package/dist/conformance.d.ts

@@ -1,5 +1,5 @@
-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";
+import { An as HighlightDraft, Ss as CharMapAnchor, al as LinePoints, cl as PdfRect, n as AnnotationListSnapshotAllPages, ol as PdfPoint, rl as InkList, t as AnnotationListPageSnapshot, xl as DocumentMetadata } from "./AnnotationListSnapshot-DDxHpJQU.js";
+import { t as Engine } from "./Engine-DOoVem7_.js";
 //#region src/conformance/runMetadataConformance.d.ts
 interface ConformanceTestRunner {
   describe(name: string, fn: () => void): void;
@@ -408,9 +408,9 @@ declare function runAttachmentConformance(runner: ConformanceTestRunner, opts: C
 //#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.
+ * Page insert conformance. `pages.insert` is a REQUIRED member — this suite
+ * runs unconditionally on every engine, so an implementation that loses the
+ * verb fails loudly instead of being skipped past.
  *
  * Invariants:
  *   1. Every page of the source bytes is COPIED in at `destIndex` (omitted →
@@ -424,6 +424,26 @@ declare function runAttachmentConformance(runner: ConformanceTestRunner, opts: C
  */
 declare function runPageInsertConformance(runner: ConformanceTestRunner, opts: ConformanceOptions): void;
 //#endregion
+//#region src/conformance/runPageInsertBlankConformance.d.ts
+/**
+ * Blank-page insert conformance. `pages.insertBlank` is a REQUIRED member —
+ * the suite runs unconditionally on every engine (no fixture bytes are
+ * needed at all, which is the point of the verb), so an implementation that
+ * loses the verb fails loudly instead of being skipped past.
+ *
+ * Invariants:
+ *   1. `count` blank pages of exactly `size` appear at `destIndex` (omitted
+ *      → append), rotation 0; the result lists their 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. Non-positive size / count outside [1, PAGE_INSERT_BLANK_MAX_COUNT] /
+ *      out-of-range destIndex reject with InvalidArg, leaving the document
+ *      untouched.
+ */
+declare function runPageInsertBlankConformance(runner: ConformanceTestRunner, opts: ConformanceOptions): void;
+//#endregion
 //#region src/conformance/runPieceInfoConformance.d.ts
 /**
  * `/PieceInfo` conformance (doc + page level). The service is OPTIONAL on
@@ -489,6 +509,102 @@ interface PageTextConformanceOptions extends Omit<ConformanceOptions, 'fixture'>
 }
 declare function runPageTextConformance(runner: ConformanceTestRunner, opts: PageTextConformanceOptions): void;
 //#endregion
+//#region src/conformance/runTextDivergenceConformance.d.ts
+/**
+ * Index-space divergence conformance: the cases where a page's CHARACTER
+ * space (what geometry tiles and selection/search ranges address) and its
+ * extracted TEXT differ — and the `charMap` contract that bridges them.
+ *
+ * Fixtures pin EXACT values (text, charCount, anchors) verified against the
+ * wasm runtime, so both engines must produce byte-identical snapshots:
+ *
+ *   - a non-printing character occupying a character slot with no text unit
+ *     (`bug_1139.pdf` — every text offset shifts by one);
+ *   - `/ActualText` replacement (`bug_384770169.pdf` — synthetic `kPiece`
+ *     characters in lockstep with the text, identity map, real segments);
+ *   - supplementary-plane text via a ToUnicode surrogate pair
+ *     (`embedpdf_astral_tounicode.pdf` — two lockstep surrogate entries,
+ *     identity map, astral content SURVIVES extraction).
+ *
+ * The search probe closes the loop: a hit's `charStart`/`charCount` must be
+ * CHARACTER-space (segments join geometry), and slicing the snapshot by the
+ * hit's range must reproduce the matched text exactly — the law that makes
+ * select-this-match and copy compose.
+ */
+interface TextDivergenceConformanceFixture extends ConformanceFixture {
+  /** PDF indirect object number of the probed page. */
+  pageObjectNumber: number;
+  /** The EXACT extracted text (UTF-16 faithful). */
+  exactText: string;
+  /** The character-space size (may differ from `exactText.length`). */
+  expectedCharCount: number;
+  /** Expected anchors; null asserts identity (no `charMap` on the wire). */
+  expectedCharMap: ReadonlyArray<CharMapAnchor> | null;
+  /** Char-space slice expectations (half-open). */
+  slices?: ReadonlyArray<{
+    from: number;
+    to: number;
+    text: string;
+  }>;
+  /** Literal search probe with expected CHARACTER-space hit range. */
+  search?: {
+    query: string;
+    charStart: number;
+    charCount: number;
+    matchedText: string;
+  };
+}
+interface TextDivergenceConformanceOptions extends Omit<ConformanceOptions, 'fixture'> {
+  fixture: TextDivergenceConformanceFixture;
+}
+declare function runTextDivergenceConformance(runner: ConformanceTestRunner, opts: TextDivergenceConformanceOptions): void;
+/** One divergence case, minus the per-suite bytes/id wiring. */
+type TextDivergenceCase = Omit<TextDivergenceConformanceFixture, 'id' | 'bytes' | 'expected'> & {
+  /** Fixture file name under the fork's `testing/resources/`. */
+  resource: string;
+};
+/**
+ * THE pinned divergence cases — one table, consumed by both engines' suites
+ * so expected values cannot drift. Values verified against the wasm runtime
+ * (see each case). All fixtures are single-page; the page's indirect object
+ * number is 3 in each.
+ */
+declare const TEXT_DIVERGENCE_CASES: Readonly<Record<string, TextDivergenceCase>>;
+//#endregion
+//#region src/conformance/runPageGeometryOrientationConformance.d.ts
+/**
+ * Per-fixture expectations for the oriented-text geometry harness. One
+ * fixture per call, mirroring the other conformance suites; the fixture
+ * declares what its dominant text orientation must read back as.
+ */
+interface PageGeometryOrientationFixture extends ConformanceFixture {
+  /** PDF indirect object number of the page under test. */
+  pageObjectNumber: number;
+  expectation: {
+    /** Every run is the upright variant; no glyph carries oriented cells. */
+    kind: 'upright';
+  } | {
+    /** The page loads and every glyph is degenerate (zeroed + empty flag). */
+    kind: 'empty-only';
+  } | {
+    kind: 'rotated';
+    /** Baseline angles (radians, CCW, PDF y-up) rotated runs may carry. */
+    rotations: number[];
+    ascentFlip: boolean;
+    /**
+     * Assert sheared cells: with `rotations` ≈ [0], a non-zero start-edge
+     * x-offset proves the parallelogram (an AABB could not express it).
+     */
+    sheared?: boolean;
+    /** Minimum number of rotated runs the page must produce (default 1). */
+    minRotatedRuns?: number;
+  };
+}
+interface PageGeometryOrientationOptions extends Omit<ConformanceOptions, 'fixture'> {
+  fixture: PageGeometryOrientationFixture;
+}
+declare function runPageGeometryOrientationConformance(runner: ConformanceTestRunner, opts: PageGeometryOrientationOptions): void;
+//#endregion
 //#region src/conformance/runSearchConformance.d.ts
 /**
  * Per-fixture expectations for the search harness. Suites supply a
@@ -522,9 +638,11 @@ declare function runSearchConformance(runner: ConformanceTestRunner, opts: Searc
  * 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()`).
+ * `auditHead` is likewise not compared: it is a cloud-only reconciliation
+ * cursor, absent on local snapshots by design.
  */
 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 };
+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 PageGeometryOrientationFixture, type PageGeometryOrientationOptions, type PageReorderConformanceFixture, type PageReorderConformanceOptions, type PageTextConformanceFixture, type PageTextConformanceOptions, type SearchConformanceFixture, type SearchConformanceOptions, TEXT_DIVERGENCE_CASES, type TextDivergenceCase, type TextDivergenceConformanceFixture, type TextDivergenceConformanceOptions, diffAnnotationListSnapshot, diffAnnotationListSnapshotAll, runActionsConformance, runAnnotationAppearanceConformance, runAnnotationMutationConformance, runAnnotationReadConformance, runAttachmentConformance, runDocumentEventsConformance, runFormConformance, runMetadataConformance, runPageDeleteConformance, runPageExtractConformance, runPageFlattenConformance, runPageGeometryOrientationConformance, runPageInsertBlankConformance, runPageInsertConformance, runPageReorderConformance, runPageRotateConformance, runPageTextConformance, runPieceInfoConformance, runRedactionApplyConformance, runSearchConformance, runTextDivergenceConformance };
 //# sourceMappingURL=conformance.d.ts.map