@doccloak/core 0.12.1 → 0.14.0

package/dist/pdf/textstate.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @doccloak/core/pdf - graphics/text state machine (T210).
+ *
+ * Tracks the subset of the graphics state that positions glyphs (ISO 32000-1
+ * 8.4, 9.3, 9.4): CTM, text state parameters, text matrix and line matrix,
+ * fill colour (to spot white-on-white text), constant alpha from ExtGState
+ * (to spot fully transparent text, a common OCR layer), and the q/Q stack. The same
+ * class is used by the extractor (to compute glyph origins) and by the
+ * surgery (to know the state at any operator).
+ */
+import type { ContentOp, Operand } from './lexer.js';
+import type { Matrix } from './types.js';
+import type { LoadedFont } from './fonts.js';
+export declare const IDENTITY: Matrix;
+/** a × b in PDF row-vector convention: apply a first, then b. */
+export declare function mul(a: Matrix, b: Matrix): Matrix;
+export declare function translate(tx: number, ty: number): Matrix;
+export declare function apply(m: Matrix, x: number, y: number): [number, number];
+export declare function invert(m: Matrix): Matrix | null;
+export declare function matrixFromOperands(ops: Operand[]): Matrix | null;
+export interface TextState {
+    font: LoadedFont | null;
+    fontName: string;
+    fontSize: number;
+    charSpacing: number;
+    wordSpacing: number;
+    /** Tz / 100 */
+    hscale: number;
+    leading: number;
+    rise: number;
+    renderMode: number;
+}
+export interface GraphicsState {
+    ctm: Matrix;
+    text: TextState;
+    /** Approximate fill luminance 0..1, or null when unknown (patterns, ICC spaces). */
+    fillLuminance: number | null;
+    /** Stroke luminance, for render modes that only stroke. */
+    strokeLuminance: number | null;
+    /** Constant alpha (ExtGState /ca) for filling, 0..1. */
+    fillAlpha: number;
+    /** Constant alpha (ExtGState /CA) for stroking, 0..1. */
+    strokeAlpha: number;
+}
+/** The alpha entries of a named ExtGState (absent when the dictionary does not set them). */
+export interface ExtGStateAlpha {
+    fillAlpha?: number;
+    strokeAlpha?: number;
+}
+export declare function initialState(ctm?: Matrix): GraphicsState;
+/**
+ * Walks operators and keeps the state current. Text-showing operators are
+ * NOT advanced here (the caller computes glyph advances, since they depend
+ * on the font); call `advanceText(tx)` after showing.
+ */
+export declare class StateMachine {
+    state: GraphicsState;
+    private stack;
+    /** Text matrix and line matrix; only meaningful inside BT..ET. */
+    tm: Matrix;
+    tlm: Matrix;
+    inText: boolean;
+    /** Fill colour space family for sc/scn interpretation. */
+    private fillSpace;
+    private strokeSpace;
+    /** Nesting depth of q without Q (for diagnostics). */
+    get depth(): number;
+    constructor(initial: GraphicsState);
+    /**
+     * Apply one operator's effect on the state. `resolveFont` maps a resource
+     * name to a LoadedFont (undefined when unknown); `resolveGState` maps an
+     * ExtGState resource name to its alpha entries (without it `gs` is ignored).
+     * Text-showing operators are not handled here (caller handles them).
+     */
+    update(op: ContentOp, resolveFont: (name: string) => LoadedFont | undefined, resolveGState?: (name: string) => ExtGStateAlpha | undefined): void;
+    nextLine(): void;
+    /** Move the text matrix by an unscaled text-space advance (already includes Tfs, Tc, Tw, Th). */
+    advanceText(tx: number): void;
+    /** Text rendering matrix for the current glyph: [Tfs*Th 0 0 Tfs 0 Ts] × Tm × CTM. */
+    trm(): Matrix;
+}
+/**
+ * Advance of one glyph in unscaled text space (9.4.4): ((w0 - adj/1000) * Tfs + Tc + Tw?) * Th.
+ * `w0` in 1/1000 units; `adj` is the TJ number preceding the glyph (already applied by caller).
+ */
+export declare function glyphAdvance(t: TextState, w0: number, isSpaceCode: boolean): number;
+/** Displacement of a TJ adjustment number in unscaled text space: -adj/1000 * Tfs * Th. */
+export declare function adjustmentAdvance(t: TextState, adj: number): number;

package/dist/pdf/textstate.js

@@ -0,0 +1,293 @@
+/**
+ * @doccloak/core/pdf - graphics/text state machine (T210).
+ *
+ * Tracks the subset of the graphics state that positions glyphs (ISO 32000-1
+ * 8.4, 9.3, 9.4): CTM, text state parameters, text matrix and line matrix,
+ * fill colour (to spot white-on-white text), constant alpha from ExtGState
+ * (to spot fully transparent text, a common OCR layer), and the q/Q stack. The same
+ * class is used by the extractor (to compute glyph origins) and by the
+ * surgery (to know the state at any operator).
+ */
+export const IDENTITY = [1, 0, 0, 1, 0, 0];
+/** a × b in PDF row-vector convention: apply a first, then b. */
+export function mul(a, b) {
+    return [
+        a[0] * b[0] + a[1] * b[2],
+        a[0] * b[1] + a[1] * b[3],
+        a[2] * b[0] + a[3] * b[2],
+        a[2] * b[1] + a[3] * b[3],
+        a[4] * b[0] + a[5] * b[2] + b[4],
+        a[4] * b[1] + a[5] * b[3] + b[5],
+    ];
+}
+export function translate(tx, ty) {
+    return [1, 0, 0, 1, tx, ty];
+}
+export function apply(m, x, y) {
+    return [m[0] * x + m[2] * y + m[4], m[1] * x + m[3] * y + m[5]];
+}
+export function invert(m) {
+    const det = m[0] * m[3] - m[1] * m[2];
+    if (!Number.isFinite(det) || Math.abs(det) < 1e-12)
+        return null;
+    const a = m[3] / det;
+    const b = -m[1] / det;
+    const c = -m[2] / det;
+    const d = m[0] / det;
+    const e = -(m[4] * a + m[5] * c);
+    const f = -(m[4] * b + m[5] * d);
+    return [a, b, c, d, e, f];
+}
+export function matrixFromOperands(ops) {
+    if (ops.length < 6)
+        return null;
+    const n = [];
+    for (let i = ops.length - 6; i < ops.length; i++) {
+        const o = ops[i];
+        if (o.kind !== 'number' || !Number.isFinite(o.value))
+            return null;
+        n.push(o.value);
+    }
+    return [n[0], n[1], n[2], n[3], n[4], n[5]];
+}
+function cloneState(s) {
+    return { ctm: s.ctm, text: { ...s.text }, fillLuminance: s.fillLuminance, strokeLuminance: s.strokeLuminance, fillAlpha: s.fillAlpha, strokeAlpha: s.strokeAlpha };
+}
+export function initialState(ctm = IDENTITY) {
+    return {
+        ctm,
+        text: { font: null, fontName: '', fontSize: 0, charSpacing: 0, wordSpacing: 0, hscale: 1, leading: 0, rise: 0, renderMode: 0 },
+        fillLuminance: 0,
+        strokeLuminance: 0,
+        fillAlpha: 1,
+        strokeAlpha: 1,
+    };
+}
+function num(o, fallback = 0) {
+    return o && o.kind === 'number' && Number.isFinite(o.value) ? o.value : fallback;
+}
+function luminanceOf(values, space) {
+    if (space === 'gray' && values.length >= 1)
+        return clamp01(values[0]);
+    if (space === 'rgb' && values.length >= 3)
+        return clamp01(0.2126 * values[0] + 0.7152 * values[1] + 0.0722 * values[2]);
+    if (space === 'cmyk' && values.length >= 4) {
+        const k = values[3];
+        const r = (1 - values[0]) * (1 - k);
+        const g = (1 - values[1]) * (1 - k);
+        const b = (1 - values[2]) * (1 - k);
+        return clamp01(0.2126 * r + 0.7152 * g + 0.0722 * b);
+    }
+    return null;
+}
+function clamp01(v) {
+    return Math.max(0, Math.min(1, v));
+}
+/**
+ * Walks operators and keeps the state current. Text-showing operators are
+ * NOT advanced here (the caller computes glyph advances, since they depend
+ * on the font); call `advanceText(tx)` after showing.
+ */
+export class StateMachine {
+    /** Nesting depth of q without Q (for diagnostics). */
+    get depth() {
+        return this.stack.length;
+    }
+    constructor(initial) {
+        this.stack = [];
+        /** Text matrix and line matrix; only meaningful inside BT..ET. */
+        this.tm = IDENTITY;
+        this.tlm = IDENTITY;
+        this.inText = false;
+        /** Fill colour space family for sc/scn interpretation. */
+        this.fillSpace = 'gray';
+        this.strokeSpace = 'gray';
+        this.state = initial;
+    }
+    /**
+     * Apply one operator's effect on the state. `resolveFont` maps a resource
+     * name to a LoadedFont (undefined when unknown); `resolveGState` maps an
+     * ExtGState resource name to its alpha entries (without it `gs` is ignored).
+     * Text-showing operators are not handled here (caller handles them).
+     */
+    update(op, resolveFont, resolveGState) {
+        const s = this.state;
+        const o = op.operands;
+        switch (op.op) {
+            case 'q':
+                this.stack.push(cloneState(s));
+                if (this.stack.length > 256)
+                    this.stack.shift();
+                break;
+            case 'Q': {
+                const prev = this.stack.pop();
+                if (prev)
+                    this.state = prev;
+                break;
+            }
+            case 'cm': {
+                const m = matrixFromOperands(o);
+                if (m)
+                    s.ctm = mul(m, s.ctm);
+                break;
+            }
+            case 'BT':
+                this.tm = IDENTITY;
+                this.tlm = IDENTITY;
+                this.inText = true;
+                break;
+            case 'ET':
+                this.inText = false;
+                break;
+            case 'Tc':
+                s.text.charSpacing = num(o[0]);
+                break;
+            case 'Tw':
+                s.text.wordSpacing = num(o[0]);
+                break;
+            case 'Tz':
+                s.text.hscale = num(o[0], 100) / 100;
+                break;
+            case 'TL':
+                s.text.leading = num(o[0]);
+                break;
+            case 'Ts':
+                s.text.rise = num(o[0]);
+                break;
+            case 'Tr':
+                s.text.renderMode = Math.trunc(num(o[0]));
+                break;
+            case 'Tf': {
+                const nameOp = o[0];
+                s.text.fontName = nameOp && nameOp.kind === 'name' ? nameOp.value : '';
+                s.text.fontSize = num(o[1]);
+                s.text.font = s.text.fontName ? resolveFont(s.text.fontName) ?? null : null;
+                break;
+            }
+            case 'Td': {
+                this.tlm = mul(translate(num(o[0]), num(o[1])), this.tlm);
+                this.tm = this.tlm;
+                break;
+            }
+            case 'TD': {
+                s.text.leading = -num(o[1]);
+                this.tlm = mul(translate(num(o[0]), num(o[1])), this.tlm);
+                this.tm = this.tlm;
+                break;
+            }
+            case 'Tm': {
+                const m = matrixFromOperands(o);
+                if (m) {
+                    this.tlm = m;
+                    this.tm = m;
+                }
+                break;
+            }
+            case 'T*':
+                this.nextLine();
+                break;
+            case "'":
+                this.nextLine();
+                break;
+            case '"':
+                s.text.wordSpacing = num(o[0]);
+                s.text.charSpacing = num(o[1]);
+                this.nextLine();
+                break;
+            case 'g':
+                s.fillLuminance = luminanceOf([num(o[0])], 'gray');
+                this.fillSpace = 'gray';
+                break;
+            case 'G':
+                s.strokeLuminance = luminanceOf([num(o[0])], 'gray');
+                this.strokeSpace = 'gray';
+                break;
+            case 'rg':
+                s.fillLuminance = luminanceOf(o.map((x) => num(x)), 'rgb');
+                this.fillSpace = 'rgb';
+                break;
+            case 'RG':
+                s.strokeLuminance = luminanceOf(o.map((x) => num(x)), 'rgb');
+                this.strokeSpace = 'rgb';
+                break;
+            case 'k':
+                s.fillLuminance = luminanceOf(o.map((x) => num(x)), 'cmyk');
+                this.fillSpace = 'cmyk';
+                break;
+            case 'K':
+                s.strokeLuminance = luminanceOf(o.map((x) => num(x)), 'cmyk');
+                this.strokeSpace = 'cmyk';
+                break;
+            case 'cs':
+                this.fillSpace = spaceFamily(o[0]);
+                s.fillLuminance = this.fillSpace ? 0 : null;
+                break;
+            case 'CS':
+                this.strokeSpace = spaceFamily(o[0]);
+                s.strokeLuminance = this.strokeSpace ? 0 : null;
+                break;
+            case 'sc':
+            case 'scn': {
+                const nums = o.filter((x) => x.kind === 'number').map((x) => num(x));
+                s.fillLuminance = this.fillSpace && nums.length === o.length ? luminanceOf(nums, this.fillSpace) : null;
+                break;
+            }
+            case 'SC':
+            case 'SCN': {
+                const nums = o.filter((x) => x.kind === 'number').map((x) => num(x));
+                s.strokeLuminance = this.strokeSpace && nums.length === o.length ? luminanceOf(nums, this.strokeSpace) : null;
+                break;
+            }
+            case 'gs': {
+                const nameOp = o[0];
+                const alpha = nameOp && nameOp.kind === 'name' ? resolveGState?.(nameOp.value) : undefined;
+                if (alpha?.fillAlpha !== undefined)
+                    s.fillAlpha = clamp01(alpha.fillAlpha);
+                if (alpha?.strokeAlpha !== undefined)
+                    s.strokeAlpha = clamp01(alpha.strokeAlpha);
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    nextLine() {
+        this.tlm = mul(translate(0, -this.state.text.leading), this.tlm);
+        this.tm = this.tlm;
+    }
+    /** Move the text matrix by an unscaled text-space advance (already includes Tfs, Tc, Tw, Th). */
+    advanceText(tx) {
+        this.tm = mul(translate(tx, 0), this.tm);
+    }
+    /** Text rendering matrix for the current glyph: [Tfs*Th 0 0 Tfs 0 Ts] × Tm × CTM. */
+    trm() {
+        const t = this.state.text;
+        return mul(mul([t.fontSize * t.hscale, 0, 0, t.fontSize, 0, t.rise], this.tm), this.state.ctm);
+    }
+}
+function spaceFamily(o) {
+    if (!o || o.kind !== 'name')
+        return null;
+    switch (o.value) {
+        case 'DeviceGray':
+        case 'CalGray':
+        case 'G': return 'gray';
+        case 'DeviceRGB':
+        case 'CalRGB':
+        case 'RGB': return 'rgb';
+        case 'DeviceCMYK':
+        case 'CMYK': return 'cmyk';
+        default: return null; // ICCBased / Indexed / Separation / Pattern: unknown luminance
+    }
+}
+/**
+ * Advance of one glyph in unscaled text space (9.4.4): ((w0 - adj/1000) * Tfs + Tc + Tw?) * Th.
+ * `w0` in 1/1000 units; `adj` is the TJ number preceding the glyph (already applied by caller).
+ */
+export function glyphAdvance(t, w0, isSpaceCode) {
+    return ((w0 / 1000) * t.fontSize + t.charSpacing + (isSpaceCode ? t.wordSpacing : 0)) * t.hscale;
+}
+/** Displacement of a TJ adjustment number in unscaled text space: -adj/1000 * Tfs * Th. */
+export function adjustmentAdvance(t, adj) {
+    return (-adj / 1000) * t.fontSize * t.hscale;
+}

package/dist/pdf/types.d.ts

@@ -0,0 +1,206 @@
+/**
+ * @doccloak/core/pdf - shared types (T206).
+ *
+ * PDF redaction that keeps the text layer: the redacted glyphs are cut out of
+ * the content streams, a placeholder is written back as real text (in the
+ * document's own font when it can show the placeholder, else in a matched
+ * fallback face), everything else on the page stays live text. Pages that
+ * cannot be edited safely are rasterized and reported, never shipped with a
+ * box drawn over live text.
+ */
+import type { UnredactablePart } from '../dom/errors.js';
+/**
+ * Runtime assets the host serves. Everything is optional: in Node tests the
+ * fallback fonts are injected through `loadFont` and pdf.js runs without a
+ * worker; browsers pass same-origin URLs (no CDN, see the hosting CSP).
+ */
+export interface PdfAssetPaths {
+    /** URL of the pdf.js worker module (pdf.worker.mjs). Omit to run pdf.js on the calling thread. */
+    pdfjsWorkerUrl?: string;
+    /** Base URL of the pdf.js binary CMaps (bcmap files), trailing slash. */
+    cMapUrl?: string;
+    /** Base URL of the pdf.js standard font files, trailing slash. */
+    standardFontDataUrl?: string;
+    /** Base URL of the pdf.js wasm decoders (openjpeg.wasm, jbig2.wasm, qcms_bg.wasm), trailing slash; needed to rasterize pages with JPX/JBIG2 images. */
+    wasmUrl?: string;
+    /** Base URL of the Liberation TTFs (`${fontsUrl}LiberationSans-Regular.ttf`), trailing slash. */
+    fontsUrl?: string;
+    /** Alternative to fontsUrl: load a fallback font file by its file name. */
+    loadFont?: (fileName: string) => Promise<Uint8Array>;
+}
+/** Broad family class used to pick a fallback face. */
+export type FontFamilyClass = 'sans' | 'serif' | 'mono';
+/** Style facts derived from a font dictionary, enough to pick a fallback face. */
+export interface FontStyle {
+    family: FontFamilyClass;
+    bold: boolean;
+    italic: boolean;
+}
+/** Axis-aligned rectangle in PDF user space (points, origin bottom-left). */
+export interface Rect {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+/** 2D affine matrix [a b c d e f] as in the PDF `cm` / `Tm` operators. */
+export type Matrix = readonly [number, number, number, number, number, number];
+/** One shown glyph with its geometry in user space. */
+export interface Glyph {
+    /** Character code as encoded in the string operand. */
+    code: number;
+    /** Number of bytes the code occupies in the operand (1..4). */
+    codeLength: number;
+    /** Unicode text of the glyph ('' when the font maps it to nothing). May be several code units (ligatures). */
+    unicode: string;
+    /** Glyph-space width from the font metrics, in 1/1000 text space units (Type3: already scaled by FontMatrix * 1000). */
+    width: number;
+    /** Horizontal displacement applied after this glyph, in unscaled text space units (font size, Tc, Tw, Tz, TJ adjustment included). */
+    advance: number;
+    /** Origin of the glyph in user space. */
+    x: number;
+    y: number;
+    /** Effective font size in user space (Tfs scaled by Tm and CTM), for fitting placeholders. */
+    fontSize: number;
+    /** Index of the operand item (for TJ arrays) this glyph came from; 0 for Tj / ' / ". */
+    item: number;
+    /** Byte offset of the code inside its string item. */
+    byteOffset: number;
+}
+/** One text-showing operator (Tj, TJ, ', ") and every glyph it painted. */
+export interface GlyphRun {
+    /** 0-based page index. */
+    page: number;
+    /** Identifies the content stream: 'p<page>:c<index>' for page contents, 'x<objnum>' for a form XObject. */
+    streamKey: string;
+    /** Operator index within that stream (as returned by the lexer). */
+    opIndex: number;
+    /** Resource name of the font (as used with Tf) and its loaded model key. */
+    fontName: string;
+    fontKey: string;
+    glyphs: Glyph[];
+    /** Text render mode at the time of showing (3 and 7 paint nothing: invisible OCR layers). */
+    renderMode: number;
+    /** True when the run is not visible (render mode 3/7, white, fully transparent, tiny, or painted under an opaque image). */
+    hidden: boolean;
+    /**
+     * Hidden text over an image: an OCR layer, the reading of what a scanned picture shows. A
+     * redaction that touches it is painted into the picture (the page is exported as an image).
+     */
+    ocr?: boolean;
+    /** Flat-text offset of each glyph's first character (parallel to glyphs). */
+    textOffsets: number[];
+    /** User-space vector of one em (1000 glyph units) along the baseline, at this run's transform. */
+    emX: readonly [number, number];
+    /** User-space vector of one em upwards. */
+    emY: readonly [number, number];
+    /**
+     * Stream-local text state at the operator, for content-stream surgery
+     * (independent of the CTM at which a shared form XObject was drawn).
+     */
+    local: RunLocalState;
+    /** True for runs that came from the pdf.js oracle on a raster-only page (no stream to edit). */
+    oracle?: boolean;
+    /**
+     * Set for text that lives in a tiling pattern cell or an ExtGState soft-mask group: its
+     * user-space geometry is that of the cell/group, not of the page, so it never shares a line
+     * with page text and cannot be blacked out by a raster (a pattern is tiled over its fill area).
+     */
+    space?: string;
+    /** Oracle run of a vertical (top-to-bottom) pdf.js item: glyphs advance along emX = (c, d), the item width lies along emY. */
+    vertical?: boolean;
+    /** Flat-text range covered by the run (inserted separators excluded from glyph coverage but inside the range). */
+    textStart: number;
+    textEnd: number;
+}
+/** Text state captured at a text-showing operator, in the coordinates of its own stream. */
+export interface RunLocalState {
+    /** CTM inside the stream (identity for a page stream at top level, the form's accumulated cm inside a form). */
+    ctm: Matrix;
+    /** Text matrix before the first glyph and the line matrix. */
+    tm: Matrix;
+    tlm: Matrix;
+    fontSize: number;
+    charSpacing: number;
+    wordSpacing: number;
+    /** Tz / 100 */
+    hscale: number;
+    leading: number;
+    rise: number;
+    /** Accumulated advance (unscaled text-space x, already including Tc/Tw/Tz) before each glyph. */
+    advances: number[];
+}
+export interface PdfPageInfo {
+    index: number;
+    /** MediaBox-derived size in points, after /Rotate is ignored (rotation is reported separately). */
+    width: number;
+    height: number;
+    rotate: number;
+    hasImages: boolean;
+    /** True when the page shows images but no glyph at all (scanned page). */
+    imageOnly: boolean;
+    /**
+     * True when hidden text lies over an image on the page (a scan with an OCR text layer).
+     * Redacted values in it are painted over in the picture, and the page is exported as an image.
+     */
+    ocrText: boolean;
+    /** Flat-text range of the page. */
+    textStart: number;
+    textEnd: number;
+}
+/** A document part the writer drops instead of redacting (reported to the user). */
+export interface RemovedPart {
+    kind: 'annotations' | 'form-fields' | 'outlines' | 'attachments' | 'javascript' | 'metadata' | 'structure-tree' | 'page-labels' | 'named-destinations' | 'optional-content' | 'signatures';
+    label: string;
+    count?: number;
+}
+/** Kinds of unredactable parts specific to PDF, in addition to the shared ones. */
+export type PdfUnredactableKind = UnredactablePart['kind'];
+export interface PdfReadOptions {
+    assets?: PdfAssetPaths;
+    /** Byte cap for the input; default 50 MB (browser heap). */
+    maxBytes?: number;
+    /** Page cap; default 500. */
+    maxPages?: number;
+    /** Cap on glyphs in the whole document (default 1.5 million; each glyph costs memory in the host). */
+    maxGlyphs?: number;
+    /** User password for encrypted files. Without it an encrypted file is refused. */
+    password?: string;
+}
+export interface PlaceholderFit {
+    /** Lowest font-size ratio (placeholder size / original size) before condensing kicks in. Default 0.65. */
+    minSizeRatio?: number;
+    /** Lowest horizontal scaling (Tz / 100) before the rest of the line is shifted. Default 0.8. */
+    minHorizontalScale?: number;
+    /** Let the placeholder overflow into the following text instead of shifting the line. Default false. */
+    allowOverflow?: boolean;
+}
+export interface PdfWriteOptions {
+    assets?: PdfAssetPaths;
+    /** Export even though the file holds parts DocCloak cannot redact (images with text). Default false. */
+    allowUnredactable?: boolean;
+    /** Placeholder fitting policy. */
+    fit?: PlaceholderFit;
+    /** Rasterize pages whose text cannot be edited safely instead of refusing the file. Default true. Scan pages are always rendered. */
+    rasterizeUnsafePages?: boolean;
+    /** DPI for rasterized pages. Default 150; scan pages use the scan's own resolution (at least this, at most 300). */
+    rasterDpi?: number;
+    /** Skip the post-write verification (tests only; never in hosts). */
+    skipVerify?: boolean;
+}
+export interface PdfWriteResult {
+    blob: Blob;
+    /** Writer notes the host must show, one line each. */
+    warnings: string[];
+    /** Parts dropped from the output (annotations, forms, ...). */
+    removed: RemovedPart[];
+    /** 0-based indexes of pages that were rasterized because their text could not be edited safely (black boxes). */
+    rasterizedPages: number[];
+    /**
+     * 0-based indexes of scan pages with an OCR text layer whose values were painted over in the
+     * picture (placeholder labels at the values' places); each is exported as an image.
+     */
+    scanPages: number[];
+    /** Placeholders whose fit needed a line shift (informational). */
+    shiftedLines: number;
+}

package/dist/pdf/types.js

@@ -0,0 +1,11 @@
+/**
+ * @doccloak/core/pdf - shared types (T206).
+ *
+ * PDF redaction that keeps the text layer: the redacted glyphs are cut out of
+ * the content streams, a placeholder is written back as real text (in the
+ * document's own font when it can show the placeholder, else in a matched
+ * fallback face), everything else on the page stays live text. Pages that
+ * cannot be edited safely are rasterized and reported, never shipped with a
+ * box drawn over live text.
+ */
+export {};

package/dist/pdf/verify.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @doccloak/core/pdf - post-write verification (T213).
+ *
+ * The output is re-read by two independent extractors (ours and pdf.js) and
+ * scanned byte-wise; any surviving needle refuses the export. Nothing this
+ * module reports is advisory: the writer throws on a non-empty finding list.
+ */
+import type { OracleDocument } from './oracle.js';
+export interface VerifyFinding {
+    pass: 'own-extractor' | 'oracle' | 'stream-bytes' | 'string-bytes' | 'code-sequence';
+    needle: string;
+    where: string;
+}
+export declare class PdfVerifyError extends Error {
+    readonly findings: VerifyFinding[];
+    constructor(findings: VerifyFinding[]);
+}
+export interface VerifyInput {
+    bytes: Uint8Array;
+    /** Original values that must not survive (case-insensitive, whitespace-insensitive in text passes). */
+    needles: string[];
+    /** Original code byte sequences removed from content streams, per edited font key (searched in content streams only). */
+    removedSequences?: Array<{
+        bytes: Uint8Array;
+        codeLength?: number;
+    }>;
+    oracle?: OracleDocument;
+    /** Placeholder texts written into the output: a value found only inside one of them ("We" in "[WE]") is not a trace. */
+    placeholders?: string[];
+}
+/** Run every pass; returns the findings (empty when clean). */
+export declare function verifyPdf(input: VerifyInput): Promise<VerifyFinding[]>;
+export declare function indexOfBytes(hay: Uint8Array, needle: Uint8Array, from?: number): number;