@embedpdf/engine-services 3.0.0-next.4 → 3.0.0-next.5

package/dist/index.d.cts

@@ -633,23 +633,26 @@ declare class RedactionApplier {
 //#region src/features/text/PageTextReader.d.ts
 /**
  * Per-page slow-path text reader. Acquires a `pagePtr` from the
- * `PagePtrPool`, opens a PDFium text page (`FPDFText_LoadPage`),
- * extracts the full UTF-16 buffer with `FPDFText_GetText`, decodes,
- * and releases everything in reverse order.
+ * `PagePtrPool`, opens a PDFium text page (`FPDFText_LoadPage`), extracts
+ * the page text, and releases everything in reverse order.
  *
- * Memory model:
- *   - `count` is in UTF-16 code units (FPDFText's "char").
- *   - The buffer needs `(count + 1) * 2` bytes (PDFium writes a
- *     trailing NUL terminator).
- *   - `mem.readU16String` walks the buffer up to the NUL and decodes
- *     to a JS string, faithfully preserving surrogate pairs.
+ * Index spaces (see engine-core `text/charmap.ts`): `charCount` is the
+ * CHARACTER space (`FPDFText_CountChars` — the space geometry runs tile);
+ * `text` is the TEXT projection. The two diverge when a character
+ * contributes zero text units (non-printing) or two (supplementary plane);
+ * `charMap` anchors encode exactly those deviations.
  *
- * Errors:
- *   - `EPDFDoc_LoadPageByObjectNumber` returning 0 is `NotFound`
- *     (raised by `PagePtrPool.acquire`).
- *   - `FPDFText_LoadPage` returning 0 is `RuntimeUnavailable` — should
- *     not happen on a healthy page; treat it as a runtime bug rather
- *     than user error.
+ * Both come from the fork's batched extension calls, which share one
+ * encoding authority (`FX_UTF16Encode`) so text and map can never
+ * disagree:
+ *
+ *   - `EPDFText_GetTextFull` — true UTF-16LE extraction; supplementary
+ *     characters arrive as surrogate pairs instead of being silently
+ *     dropped by `FPDFText_GetText`'s UCS-2 encoder. Called once with an
+ *     upper-bound buffer (2 units per character + NUL), so no measure
+ *     round-trip.
+ *   - `EPDFText_GetCharToTextMap` — the anchors, measure-then-fill. Zero
+ *     anchors is the common (identity) page and skips the fill call.
  */
 declare class PageTextReader {
   private readonly runtime;

package/dist/index.d.ts

@@ -633,23 +633,26 @@ declare class RedactionApplier {
 //#region src/features/text/PageTextReader.d.ts
 /**
  * Per-page slow-path text reader. Acquires a `pagePtr` from the
- * `PagePtrPool`, opens a PDFium text page (`FPDFText_LoadPage`),
- * extracts the full UTF-16 buffer with `FPDFText_GetText`, decodes,
- * and releases everything in reverse order.
+ * `PagePtrPool`, opens a PDFium text page (`FPDFText_LoadPage`), extracts
+ * the page text, and releases everything in reverse order.
  *
- * Memory model:
- *   - `count` is in UTF-16 code units (FPDFText's "char").
- *   - The buffer needs `(count + 1) * 2` bytes (PDFium writes a
- *     trailing NUL terminator).
- *   - `mem.readU16String` walks the buffer up to the NUL and decodes
- *     to a JS string, faithfully preserving surrogate pairs.
+ * Index spaces (see engine-core `text/charmap.ts`): `charCount` is the
+ * CHARACTER space (`FPDFText_CountChars` — the space geometry runs tile);
+ * `text` is the TEXT projection. The two diverge when a character
+ * contributes zero text units (non-printing) or two (supplementary plane);
+ * `charMap` anchors encode exactly those deviations.
  *
- * Errors:
- *   - `EPDFDoc_LoadPageByObjectNumber` returning 0 is `NotFound`
- *     (raised by `PagePtrPool.acquire`).
- *   - `FPDFText_LoadPage` returning 0 is `RuntimeUnavailable` — should
- *     not happen on a healthy page; treat it as a runtime bug rather
- *     than user error.
+ * Both come from the fork's batched extension calls, which share one
+ * encoding authority (`FX_UTF16Encode`) so text and map can never
+ * disagree:
+ *
+ *   - `EPDFText_GetTextFull` — true UTF-16LE extraction; supplementary
+ *     characters arrive as surrogate pairs instead of being silently
+ *     dropped by `FPDFText_GetText`'s UCS-2 encoder. Called once with an
+ *     upper-bound buffer (2 units per character + NUL), so no measure
+ *     round-trip.
+ *   - `EPDFText_GetCharToTextMap` — the anchors, measure-then-fill. Zero
+ *     anchors is the common (identity) page and skips the fill call.
  */
 declare class PageTextReader {
   private readonly runtime;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { AbortError, EMPTY_TRANSFER, EngineError, EngineErrorCode, NO_ANNOTATION_FLAGS, PDF_SUBTYPE_TO_CODE, PdfAnnotationSubtypeCode, UNKNOWN_WEAK_ANNOTATION_STATE, appearanceImpactOf, buildPageTextLayout, buildSnippet, foldOptionsFor, foldText, invalidatesWeakIndexRefs, isValidPageObjectNumber, knownWeakAnnotationState, matchLiteral, matchRegex, normalizePdfRect, pdfQuadBounds, revisionTokensEqual, serializeError, shiftsExistingAnnotationIndices, sniffBinaryMetadata, subtypeFromCode, textSegmentsForRange, validateSearchQuery, wirePack } from "@embedpdf/engine-core/runtime";
+import { AbortError, EMPTY_TRANSFER, EngineError, EngineErrorCode, NO_ANNOTATION_FLAGS, PDF_SUBTYPE_TO_CODE, PdfAnnotationSubtypeCode, UNKNOWN_WEAK_ANNOTATION_STATE, appearanceImpactOf, buildPageTextLayout, buildSnippet, charMapViolation, charRangeForTextOffsets, foldOptionsFor, foldText, invalidatesWeakIndexRefs, isValidPageObjectNumber, knownWeakAnnotationState, matchLiteral, matchRegex, normalizePdfRect, pdfQuadBounds, revisionTokensEqual, serializeError, shiftsExistingAnnotationIndices, sniffBinaryMetadata, subtypeFromCode, textSegmentsForRange, validateSearchQuery, wirePack } from "@embedpdf/engine-core/runtime";
 import { NULL_PTR } from "@embedpdf/engine-runtime";
 //#region src/runtime/lifecycle/bootstrap.ts
 const initialized = /* @__PURE__ */ new WeakSet();
@@ -7061,23 +7061,26 @@ var RedactionApplier = class {
 //#region src/features/text/PageTextReader.ts
 /**
 * Per-page slow-path text reader. Acquires a `pagePtr` from the
-* `PagePtrPool`, opens a PDFium text page (`FPDFText_LoadPage`),
-* extracts the full UTF-16 buffer with `FPDFText_GetText`, decodes,
-* and releases everything in reverse order.
+* `PagePtrPool`, opens a PDFium text page (`FPDFText_LoadPage`), extracts
+* the page text, and releases everything in reverse order.
 *
-* Memory model:
-*   - `count` is in UTF-16 code units (FPDFText's "char").
-*   - The buffer needs `(count + 1) * 2` bytes (PDFium writes a
-*     trailing NUL terminator).
-*   - `mem.readU16String` walks the buffer up to the NUL and decodes
-*     to a JS string, faithfully preserving surrogate pairs.
+* Index spaces (see engine-core `text/charmap.ts`): `charCount` is the
+* CHARACTER space (`FPDFText_CountChars` — the space geometry runs tile);
+* `text` is the TEXT projection. The two diverge when a character
+* contributes zero text units (non-printing) or two (supplementary plane);
+* `charMap` anchors encode exactly those deviations.
 *
-* Errors:
-*   - `EPDFDoc_LoadPageByObjectNumber` returning 0 is `NotFound`
-*     (raised by `PagePtrPool.acquire`).
-*   - `FPDFText_LoadPage` returning 0 is `RuntimeUnavailable` — should
-*     not happen on a healthy page; treat it as a runtime bug rather
-*     than user error.
+* Both come from the fork's batched extension calls, which share one
+* encoding authority (`FX_UTF16Encode`) so text and map can never
+* disagree:
+*
+*   - `EPDFText_GetTextFull` — true UTF-16LE extraction; supplementary
+*     characters arrive as surrogate pairs instead of being silently
+*     dropped by `FPDFText_GetText`'s UCS-2 encoder. Called once with an
+*     upper-bound buffer (2 units per character + NUL), so no measure
+*     round-trip.
+*   - `EPDFText_GetCharToTextMap` — the anchors, measure-then-fill. Zero
+*     anchors is the common (identity) page and skips the fill call.
 */
 var PageTextReader = class {
 	constructor(runtime, session) {
@@ -7086,7 +7089,7 @@ var PageTextReader = class {
 	}
 	read(pageObjectNumber, signal) {
 		throwIfAborted(signal);
-		const { fn, mem } = this.runtime;
+		const { fn } = this.runtime;
 		const pool = this.session.pagePool();
 		const pagePtr = pool.acquire(pageObjectNumber);
 		try {
@@ -7095,10 +7098,18 @@ var PageTextReader = class {
 			if (!textPagePtr) throw new EngineError(EngineErrorCode.RuntimeUnavailable, `FPDFText_LoadPage returned null for page object ${pageObjectNumber}`);
 			try {
 				throwIfAborted(signal);
-				const charCount = fn.FPDFText_CountChars(textPagePtr);
-				return {
-					text: readPageText(fn, mem, textPagePtr, charCount),
-					charCount: Math.max(charCount, 0)
+				const charCount = Math.max(fn.FPDFText_CountChars(textPagePtr), 0);
+				const text = readTextFull(this.runtime, textPagePtr, charCount);
+				const charMap = readCharMap(this.runtime, textPagePtr, pageObjectNumber);
+				const violation = charMapViolation(charCount, text.length, charMap);
+				if (violation !== null) throw new EngineError(EngineErrorCode.RuntimeUnavailable, `char map invariant violated for page object ${pageObjectNumber}: ${violation}`);
+				return charMap.length > 0 ? {
+					text,
+					charCount,
+					charMap
+				} : {
+					text,
+					charCount
 				};
 			} finally {
 				fn.FPDFText_ClosePage(textPagePtr);
@@ -7108,11 +7119,43 @@ var PageTextReader = class {
 		}
 	}
 };
-function readPageText(fn, mem, textPagePtr, charCount) {
+/**
+* Full-fidelity page text in one call: the buffer is sized at the maximum
+* possible expansion (every character a surrogate pair, plus the NUL), so
+* the returned requirement always fits and the measure round-trip is
+* skipped. The return value counts UTF-16 units INCLUDING the terminator.
+*/
+function readTextFull(runtime, textPagePtr, charCount) {
 	if (charCount <= 0) return "";
-	return withScratch(mem, (charCount + 1) * 2, (buf) => {
-		if (fn.FPDFText_GetText(textPagePtr, 0, charCount, buf) <= 0) return "";
-		return mem.readU16String(buf);
+	const { fn, mem } = runtime;
+	const bufUnits = charCount * 2 + 1;
+	return withScratch(mem, bufUnits * 2, (buf) => {
+		const written = fn.EPDFText_GetTextFull(textPagePtr, buf, bufUnits);
+		if (written <= 1) return "";
+		return decodeUtf16Le(mem.readBytes(buf, (written - 1) * 2));
+	});
+}
+function decodeUtf16Le(bytes) {
+	const units = new Uint16Array(bytes.buffer, bytes.byteOffset, bytes.byteLength >> 1);
+	let out = "";
+	const CHUNK = 8192;
+	for (let i = 0; i < units.length; i += CHUNK) out += String.fromCharCode(...units.subarray(i, Math.min(i + CHUNK, units.length)));
+	return out;
+}
+/** Anchor struct layout: two little-endian i32s (see EPDF_CHAR_MAP_ANCHOR). */
+const ANCHOR_BYTES = 8;
+function readCharMap(runtime, textPagePtr, pageObjectNumber) {
+	const { fn, mem } = runtime;
+	const count = fn.EPDFText_GetCharToTextMap(textPagePtr, NULL_PTR, 0);
+	if (count < 0) throw new EngineError(EngineErrorCode.RuntimeUnavailable, `EPDFText_GetCharToTextMap failed for page object ${pageObjectNumber}`);
+	if (count === 0) return [];
+	return withScratch(mem, count * ANCHOR_BYTES, (buf) => {
+		fn.EPDFText_GetCharToTextMap(textPagePtr, buf, count);
+		const bytes = mem.readBytes(buf, count * ANCHOR_BYTES);
+		const words = new Int32Array(bytes.buffer, bytes.byteOffset, count * 2);
+		const anchors = new Array(count);
+		for (let i = 0; i < count; i++) anchors[i] = [words[i * 2], words[i * 2 + 1]];
+		return anchors;
 	});
 }
 //#endregion
@@ -8753,7 +8796,7 @@ function emptyResult(index, status) {
 //#endregion
 //#region src/features/search/internal/pageCorpusCache.ts
 /**
-* Per-session, per-page search corpus: the page's extracted text plus its
+* Per-session, per-page search corpus: the page's text snapshot plus its
 * DEFAULT fold (the one literal queries with default options search).
 * This is the local engine's in-memory equivalent of the server's corpus
 * artifacts — same fold version, same shape, built lazily on first search
@@ -8778,19 +8821,20 @@ function acquirePageCorpus(runtime, session, pageObjectNumber, signal) {
 		cache.set(session, pages);
 	}
 	const hit = pages.get(pageObjectNumber);
-	if (hit && hit.seq === seq) return hit.folded;
-	const text = new PageTextReader(runtime, session).read(pageObjectNumber, signal).text;
-	const folded = foldText(text);
-	pages.delete(pageObjectNumber);
-	pages.set(pageObjectNumber, {
+	if (hit && hit.seq === seq) return hit;
+	const snapshot = new PageTextReader(runtime, session).read(pageObjectNumber, signal);
+	const entry = {
 		seq,
-		folded
-	});
+		folded: foldText(snapshot.text),
+		snapshot
+	};
+	pages.delete(pageObjectNumber);
+	pages.set(pageObjectNumber, entry);
 	if (pages.size > MAX_CACHED_PAGES) {
 		const oldest = pages.keys().next().value;
 		if (oldest !== void 0) pages.delete(oldest);
 	}
-	return folded;
+	return entry;
 }
 //#endregion
 //#region src/features/search/internal/searchCursor.ts
@@ -8899,19 +8943,23 @@ var SearchReader = class {
 			throwIfAborted(signal);
 			const pon = order[scanned].pageObjectNumber;
 			const corpus = acquirePageCorpus(this.runtime, this.session, pon, signal);
+			const text = corpus.snapshot.text;
 			let ranges;
-			if (query.regex) ranges = matchRegex(corpus.original, query);
-			else if (query.matchCase || query.matchDiacritics) ranges = matchLiteral(foldText(corpus.original, foldOptionsFor(query)), query);
-			else ranges = matchLiteral(corpus, query);
+			if (query.regex) ranges = matchRegex(text, query);
+			else if (query.matchCase || query.matchDiacritics) ranges = matchLiteral(foldText(text, foldOptionsFor(query)), query);
+			else ranges = matchLiteral(corpus.folded, query);
 			if (ranges.length > 0) {
 				const layout = buildPageTextLayout(new PageGeometryReader(this.runtime, this.session).read(pon, signal));
-				for (const range of ranges) matches.push({
-					pageObjectNumber: pon,
-					charStart: range.start,
-					charCount: range.length,
-					segments: textSegmentsForRange(layout, range.start, range.length),
-					...mode === "full" ? { snippet: buildSnippet(corpus.original, range) } : {}
-				});
+				for (const range of ranges) {
+					const chars = charRangeForTextOffsets(corpus.snapshot, range.start, range.start + range.length);
+					matches.push({
+						pageObjectNumber: pon,
+						charStart: chars.start,
+						charCount: chars.end - chars.start,
+						segments: textSegmentsForRange(layout, chars.start, chars.end - chars.start),
+						...mode === "full" ? { snippet: buildSnippet(text, range) } : {}
+					});
+				}
 			}
 			scanned++;
 			pagesThisSlice++;