@doccloak/core 0.12.1 → 0.14.0

package/dist/pdf/raster.js

@@ -0,0 +1,405 @@
+/**
+ * @doccloak/core/pdf - page rasterization fallback (T212).
+ *
+ * A page whose text cannot be edited safely is rendered to pixels by pdf.js
+ * and the redacted rectangles are painted black IN THE PIXELS, on the same
+ * canvas, after the render: the PNG never contains what was under a box.
+ * The caller (writer) replaces the page contents with this image and
+ * reports the page in `rasterizedPages`.
+ *
+ * Scan pages with an OCR text layer (T235) are rendered the same way at the
+ * scan's resolution, but each redacted value is covered in paper colour and
+ * its placeholder label is painted in its place, along the baseline and
+ * within the value's width (`rasterizeScanPage`).
+ */
+/**
+ * Map a user-space rectangle to canvas pixels through the pdf.js viewport
+ * transform [a b c d e f] (x' = a*x + c*y + e, y' = b*x + d*y + f). The four
+ * corners are transformed (rotation may swap axes) and their bounding box is
+ * returned, expanded outwards to whole pixels. No padding is applied here.
+ */
+export function userRectToPixels(viewportTransform, rect) {
+    const [a, b, c, d, e, f] = viewportTransform;
+    const xs = [rect.x0, rect.x1, rect.x0, rect.x1];
+    const ys = [rect.y0, rect.y0, rect.y1, rect.y1];
+    let minX = Infinity;
+    let minY = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    for (let i = 0; i < 4; i++) {
+        const px = a * xs[i] + c * ys[i] + e;
+        const py = b * xs[i] + d * ys[i] + f;
+        if (px < minX)
+            minX = px;
+        if (px > maxX)
+            maxX = px;
+        if (py < minY)
+            minY = py;
+        if (py > maxY)
+            maxY = py;
+    }
+    // Round to whole pixels outwards; tolerate float noise (1224.0000001 stays 1224).
+    const EPS = 1e-6;
+    const x = Math.floor(minX + EPS);
+    const y = Math.floor(minY + EPS);
+    const x1 = Math.ceil(maxX - EPS);
+    const y1 = Math.ceil(maxY - EPS);
+    return { x, y, w: Math.max(0, x1 - x), h: Math.max(0, y1 - y) };
+}
+/** Pad a pixel box by `pad` on every side and clamp it to the canvas. Empty when the box lies outside. */
+export function padAndClamp(box, pad, widthPx, heightPx) {
+    const x0 = Math.max(0, box.x - pad);
+    const y0 = Math.max(0, box.y - pad);
+    const x1 = Math.min(widthPx, box.x + box.w + pad);
+    const y1 = Math.min(heightPx, box.y + box.h + pad);
+    if (x1 <= x0 || y1 <= y0)
+        return { x: 0, y: 0, w: 0, h: 0 };
+    return { x: x0, y: y0, w: x1 - x0, h: y1 - y0 };
+}
+/** Pixels of padding around every box (covers anti-aliased glyph edges). */
+const BOX_PAD_PX = 1;
+/**
+ * Render page `index` at `options.dpi` (pdf.js applies /Rotate as a viewer
+ * would), paint every `boxes` rectangle black on the rendered pixels, and
+ * encode the canvas as PNG.
+ */
+export async function rasterizePage(doc, index, boxes, options) {
+    if (!(options.dpi > 0) || !Number.isFinite(options.dpi))
+        throw new RangeError(`invalid dpi ${options.dpi}`);
+    const scale = options.dpi / 72;
+    const page = await doc.render(index, scale, options.canvasFactory);
+    const ctx = page.canvas.context;
+    // pdf.js leaves its own transform / composite state on the context: draw
+    // in plain device pixels with an opaque black brush.
+    ctx.save();
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.globalAlpha = 1;
+    ctx.globalCompositeOperation = 'source-over';
+    ctx.fillStyle = '#000000';
+    for (const box of boxes) {
+        const px = padAndClamp(userRectToPixels(page.transform, box), BOX_PAD_PX, page.widthPx, page.heightPx);
+        if (px.w === 0 || px.h === 0)
+            continue;
+        ctx.fillRect(px.x, px.y, px.w, px.h);
+    }
+    ctx.restore();
+    const png = await page.canvas.toPng();
+    return {
+        png,
+        widthPx: page.widthPx,
+        heightPx: page.heightPx,
+        widthPt: page.widthPt,
+        heightPt: page.heightPt,
+    };
+}
+/**
+ * Cover extent around a value, in em of its font size: along the baseline, and below and above
+ * it when the picture shows no ink to measure. The OCR layer's font size is only a hint (layers
+ * often stretch it to the line height), so the cover's height and the label's size come from
+ * the ink itself (see inkRows), within INK_REACH_BELOW / INK_REACH_ABOVE of the baseline; the
+ * cover always holds the core band COVER_CORE_BELOW..COVER_CORE_ABOVE.
+ */
+const COVER_PAD_ALONG = 0.12;
+const COVER_BELOW = 0.32;
+const COVER_ABOVE = 0.92;
+const COVER_CORE_BELOW = 0.15;
+const COVER_CORE_ABOVE = 0.6;
+const INK_REACH_BELOW = 0.45;
+const INK_REACH_ABOVE = 1.1;
+/**
+ * OCR layers place words well but size letters from their own font, so a value's ink can run
+ * past the layer's ends. A cover grows along the baseline to the end of the ink it touches: the
+ * search starts this far inside the value, stops at a blank gap of WORD_GAP (a word space is
+ * about 0.28 em, gaps between letters stay under about 0.12 em) and never grows by more than
+ * MAX_GROWTH; ink is looked for in the band of the letters' bodies only, so the lines above and
+ * below do not count. All in em of the value's font size.
+ */
+const INK_SEARCH_INSIDE = 0.25;
+const WORD_GAP = 0.16;
+const MAX_GROWTH = 1;
+const INK_BAND_BELOW = 0.12;
+const INK_BAND_ABOVE = 0.68;
+/** A pixel is ink when its luminance is below this fraction of the paper's. */
+const INK_LUMINANCE = 0.65;
+/**
+ * Label size: the value's ink height (capitals and ascenders reach about 0.72 em) gives the
+ * label's em; without ink the OCR font size does, times LABEL_SIZE. The label is squeezed
+ * horizontally down to LABEL_MIN_SQUEEZE to fit the value's width, then shrunk.
+ */
+const INK_TOP_EM = 0.76;
+const LABEL_SIZE = 0.8;
+const LABEL_MIN_SQUEEZE = 0.6;
+const LABEL_FONT = '"Liberation Sans", Arial, Helvetica, sans-serif';
+/**
+ * Render page `index` at `options.dpi`, cover every mark in the paper colour
+ * around it and paint its label in the value's place: the baseline the OCR
+ * layer gives, the value's width (the label is squeezed, then shrunk, to fit;
+ * a shorter label leaves the rest of the width blank). Every cover is painted
+ * before any label, so a cover on the next line never clips a label above it.
+ * Returns the pixels, in gray when the page is gray (a scan usually is), so
+ * the writer can embed them losslessly at a size close to the original scan.
+ */
+export async function rasterizeScanPage(doc, index, marks, options) {
+    if (!(options.dpi > 0) || !Number.isFinite(options.dpi))
+        throw new RangeError(`invalid dpi ${options.dpi}`);
+    const page = await doc.render(index, options.dpi / 72, options.canvasFactory);
+    const ctx = page.canvas.context;
+    const before = page.canvas.getImageData();
+    const [a, b, c, d, e, f] = page.transform;
+    const toPx = (x, y) => [a * x + c * y + e, b * x + d * y + f];
+    // Measure every cover on the untouched pixels first.
+    const covers = marks.map((m) => {
+        const at = (along, up) => toPx(m.x + m.ux * along + m.vx * up, m.y + m.uy * along + m.vy * up);
+        const pad = COVER_PAD_ALONG * m.size;
+        const paper = paperColour(before, page.widthPx, page.heightPx, quadOf(at, -pad, m.length + pad, -COVER_BELOW * m.size, COVER_ABOVE * m.size));
+        const inkBelow = luminance(paper) * INK_LUMINANCE;
+        const along = inkExtent(before, page.widthPx, page.heightPx, at, m, inkBelow);
+        const start = Math.min(0, along.start) - pad;
+        const end = Math.max(m.length, along.end) + pad;
+        const rows = inkRows(before, page.widthPx, page.heightPx, at, m, start, end, inkBelow);
+        const onePx = 1 / (Math.hypot(...sub(at(0, 1), at(0, 0))) || 1);
+        const bottom = rows ? Math.min(-COVER_CORE_BELOW * m.size, rows.bottom - 1.5 * onePx) : -COVER_BELOW * m.size;
+        const top = rows ? Math.max(COVER_CORE_ABOVE * m.size, rows.top + 1.5 * onePx) : COVER_ABOVE * m.size;
+        const ink = rows ? inkColour(before, page.widthPx, page.heightPx, at, start, end, rows.bottom, rows.top, inkBelow) : null;
+        return { mark: m, at, start, end, bottom, top, inkTop: rows ? rows.top : null, paper, ink };
+    });
+    ctx.save();
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.globalAlpha = 1;
+    ctx.globalCompositeOperation = 'source-over';
+    for (const cv of covers) {
+        const quad = quadOf(cv.at, cv.start, cv.end, cv.bottom, cv.top);
+        const fill = `rgb(${cv.paper[0]}, ${cv.paper[1]}, ${cv.paper[2]})`;
+        ctx.fillStyle = fill;
+        ctx.strokeStyle = fill;
+        ctx.lineWidth = 2; // the stroke grows the cover by a pixel on every side (anti-aliased glyph edges)
+        ctx.beginPath();
+        ctx.moveTo(quad[0][0], quad[0][1]);
+        for (let i = 1; i < 4; i++)
+            ctx.lineTo(quad[i][0], quad[i][1]);
+        ctx.closePath();
+        ctx.fill();
+        ctx.stroke();
+    }
+    for (const cv of covers) {
+        const m = cv.mark;
+        if (!m.label)
+            continue;
+        const pad = COVER_PAD_ALONG * m.size;
+        const [x0, y0] = cv.at(cv.start + pad, 0);
+        const [x1, y1] = cv.at(cv.start + pad + 1, 0);
+        const [xu, yu] = cv.at(cv.start + pad, 1);
+        const pxPerUnit = Math.hypot(x1 - x0, y1 - y0);
+        const pxPerUnitUp = Math.hypot(xu - x0, yu - y0);
+        const available = (cv.end - cv.start - 2 * pad) * pxPerUnit;
+        const em = cv.inkTop !== null && cv.inkTop > 0 ? cv.inkTop / INK_TOP_EM : LABEL_SIZE * m.size;
+        let fontPx = Math.min(em, 1.2 * m.size) * pxPerUnitUp;
+        if (!(fontPx > 0) || !(available > 0))
+            continue;
+        ctx.font = `${fontPx}px ${LABEL_FONT}`;
+        const natural = ctx.measureText(m.label).width;
+        let squeeze = natural > available ? available / natural : 1;
+        if (squeeze < LABEL_MIN_SQUEEZE) {
+            fontPx *= squeeze / LABEL_MIN_SQUEEZE;
+            squeeze = LABEL_MIN_SQUEEZE;
+            ctx.font = `${fontPx}px ${LABEL_FONT}`;
+        }
+        ctx.save();
+        ctx.translate(x0, y0);
+        ctx.rotate(Math.atan2(y1 - y0, x1 - x0));
+        ctx.scale(squeeze, 1);
+        ctx.fillStyle = cv.ink !== null ? `rgb(${cv.ink}, ${cv.ink}, ${cv.ink})` : luminance(cv.paper) > 0.45 ? '#000000' : '#ffffff';
+        ctx.textAlign = 'left';
+        ctx.textBaseline = 'alphabetic';
+        ctx.fillText(m.label, 0, 0);
+        ctx.restore();
+    }
+    ctx.restore();
+    const rgba = page.canvas.getImageData();
+    const { pixels, channels } = packPixels(rgba);
+    return { pixels, channels, widthPx: page.widthPx, heightPx: page.heightPx, widthPt: page.widthPt, heightPt: page.heightPt };
+}
+function sub(p, q) {
+    return [p[0] - q[0], p[1] - q[1]];
+}
+/** Pixel corners of the box [lo, hi] along the baseline by [bottom, top] across it. */
+function quadOf(at, lo, hi, bottom, top) {
+    return [at(lo, bottom), at(hi, bottom), at(hi, top), at(lo, top)];
+}
+/** Luminance (0..1) of the pixel under a baseline-frame point, or null off canvas. */
+function lumAt(rgba, width, height, p) {
+    const px = Math.round(p[0]);
+    const py = Math.round(p[1]);
+    if (px < 0 || py < 0 || px >= width || py >= height)
+        return null;
+    const i = (py * width + px) * 4;
+    return (0.2126 * rgba[i] + 0.7152 * rgba[i + 1] + 0.0722 * rgba[i + 2]) / 255;
+}
+/**
+ * Vertical extent of the value's ink (user units from the baseline): the block of inked rows
+ * across [start, end] that holds the letters' bodies, grown up and down until a blank row (the
+ * leading between lines), within INK_REACH_BELOW / INK_REACH_ABOVE. Null when no ink is there.
+ */
+export function inkRows(rgba, width, height, at, m, start, end, inkBelow) {
+    const pxAlong = Math.hypot(...sub(at(1, 0), at(0, 0)));
+    const pxUp = Math.hypot(...sub(at(0, 1), at(0, 0)));
+    if (!(pxAlong > 0) || !(pxUp > 0))
+        return null;
+    const stepAlong = 1 / pxAlong;
+    const stepUp = 1 / pxUp;
+    const rowHasInk = (up) => {
+        for (let along = start; along <= end; along += stepAlong) {
+            const lum = lumAt(rgba, width, height, at(along, up));
+            if (lum !== null && lum < inkBelow)
+                return true;
+        }
+        return false;
+    };
+    // Seed in the letters' bodies (every letter has ink between the baseline and the x-height).
+    let seed = null;
+    for (let up = 0.1 * m.size; up <= 0.45 * m.size; up += stepUp) {
+        if (rowHasInk(up)) {
+            seed = up;
+            break;
+        }
+    }
+    if (seed === null)
+        return null;
+    let top = seed;
+    for (let up = seed; up <= INK_REACH_ABOVE * m.size && rowHasInk(up); up += stepUp)
+        top = up;
+    let bottom = seed;
+    for (let up = seed; up >= -INK_REACH_BELOW * m.size && rowHasInk(up); up -= stepUp)
+        bottom = up;
+    return { bottom, top };
+}
+/**
+ * How far the ink of a value really reaches along its baseline (user units from the mark's
+ * start; `start` <= 0 and `end` >= length when the ink runs past the OCR layer's ends). Walks
+ * outwards pixel by pixel from inside the value and stops at the first blank gap of a word
+ * space, or after MAX_GROWTH.
+ */
+export function inkExtent(rgba, width, height, at, m, inkBelow) {
+    const [ox, oy] = at(0, 0);
+    const [ax, ay] = at(1, 0);
+    const pxPerUnit = Math.hypot(ax - ox, ay - oy);
+    if (!(pxPerUnit > 0))
+        return { start: 0, end: m.length };
+    const step = 1 / pxPerUnit; // one pixel along the baseline, in user units
+    const [bx, by] = at(0, INK_BAND_BELOW * -m.size);
+    const [tx, ty] = at(0, INK_BAND_ABOVE * m.size);
+    const bandPx = Math.max(1, Math.ceil(Math.hypot(tx - bx, ty - by)));
+    const isInk = (along) => {
+        for (let k = 0; k <= bandPx; k++) {
+            const up = -INK_BAND_BELOW * m.size + (k / bandPx) * (INK_BAND_ABOVE + INK_BAND_BELOW) * m.size;
+            const lum = lumAt(rgba, width, height, at(along, up));
+            if (lum !== null && lum < inkBelow)
+                return true;
+        }
+        return false;
+    };
+    const inside = Math.min(INK_SEARCH_INSIDE * m.size, m.length / 2);
+    const gap = WORD_GAP * m.size;
+    const reach = (from, dir, limit) => {
+        let last = from;
+        for (let along = from; dir > 0 ? along <= limit : along >= limit; along += dir * step) {
+            if (isInk(along))
+                last = along;
+            else if (Math.abs(along - last) >= gap)
+                break;
+        }
+        return last + dir * step;
+    };
+    return {
+        start: Math.min(0, reach(inside, -1, -MAX_GROWTH * m.size)),
+        end: Math.max(m.length, reach(m.length - inside, 1, m.length + MAX_GROWTH * m.size)),
+    };
+}
+/**
+ * Gray level (0..255) of the ink in the box [start, end] x [bottom, top]: the median luminance of
+ * its ink pixels, without their hue (a label never repeats the colour a value was printed in).
+ * Null without ink.
+ */
+function inkColour(rgba, width, height, at, start, end, bottom, top, inkBelow) {
+    const stepAlong = 1 / (Math.hypot(...sub(at(1, 0), at(0, 0))) || 1);
+    const stepUp = 1 / (Math.hypot(...sub(at(0, 1), at(0, 0))) || 1);
+    const levels = [];
+    for (let up = bottom; up <= top; up += stepUp) {
+        for (let along = start; along <= end; along += stepAlong) {
+            const [x, y] = at(along, up);
+            const px = Math.round(x);
+            const py = Math.round(y);
+            if (px < 0 || py < 0 || px >= width || py >= height)
+                continue;
+            const i = (py * width + px) * 4;
+            const level = 0.2126 * rgba[i] + 0.7152 * rgba[i + 1] + 0.0722 * rgba[i + 2];
+            if (level / 255 < inkBelow)
+                levels.push(level);
+        }
+    }
+    if (levels.length === 0)
+        return null;
+    return Math.round(levels.sort((p, q) => p - q)[levels.length >> 1]);
+}
+/**
+ * The paper colour around a cover: per-channel median of the pixels on a ring
+ * three pixels outside the quad's bounding box (mostly background, whatever
+ * text the ring crosses is a minority). White when the ring is off canvas.
+ */
+export function paperColour(rgba, width, height, quad) {
+    const xs = quad.map((p) => p[0]);
+    const ys = quad.map((p) => p[1]);
+    const left = Math.floor(Math.min(...xs)) - 3;
+    const right = Math.ceil(Math.max(...xs)) + 3;
+    const top = Math.floor(Math.min(...ys)) - 3;
+    const bottom = Math.ceil(Math.max(...ys)) + 3;
+    const channels = [[], [], []];
+    const take = (x, y) => {
+        if (x < 0 || y < 0 || x >= width || y >= height)
+            return;
+        const i = (y * width + x) * 4;
+        channels[0].push(rgba[i]);
+        channels[1].push(rgba[i + 1]);
+        channels[2].push(rgba[i + 2]);
+    };
+    for (let x = left; x <= right; x++) {
+        take(x, top);
+        take(x, bottom);
+    }
+    for (let y = top + 1; y < bottom; y++) {
+        take(left, y);
+        take(right, y);
+    }
+    if (channels[0].length === 0)
+        return [255, 255, 255];
+    const median = (v) => v.sort((p, q) => p - q)[v.length >> 1];
+    return [median(channels[0]), median(channels[1]), median(channels[2])];
+}
+function luminance(rgb) {
+    return (0.2126 * rgb[0] + 0.7152 * rgb[1] + 0.0722 * rgb[2]) / 255;
+}
+/** RGBA canvas pixels to gray (every pixel has R = G = B) or RGB bytes; alpha is dropped (pdf.js paints an opaque page). */
+export function packPixels(rgba) {
+    const n = rgba.length >> 2;
+    let gray = true;
+    for (let i = 0; i < n; i++) {
+        const r = rgba[i * 4];
+        if (r !== rgba[i * 4 + 1] || r !== rgba[i * 4 + 2]) {
+            gray = false;
+            break;
+        }
+    }
+    if (gray) {
+        const pixels = new Uint8Array(n);
+        for (let i = 0; i < n; i++)
+            pixels[i] = rgba[i * 4];
+        return { pixels, channels: 1 };
+    }
+    const pixels = new Uint8Array(n * 3);
+    for (let i = 0; i < n; i++) {
+        pixels[i * 3] = rgba[i * 4];
+        pixels[i * 3 + 1] = rgba[i * 4 + 1];
+        pixels[i * 3 + 2] = rgba[i * 4 + 2];
+    }
+    return { pixels, channels: 3 };
+}

package/dist/pdf/read.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @doccloak/core/pdf - readPdf (T213/T215).
+ *
+ * Parses a PDF, extracts its text with glyph geometry, cross-checks every
+ * page against pdf.js and returns the extraction hosts run detection on.
+ * The extraction keeps the input bytes; the writer re-extracts from them so
+ * a stale extraction can never be applied to different bytes.
+ */
+import type { GlyphRun, PdfAssetPaths, PdfPageInfo, PdfReadOptions, RemovedPart } from './types.js';
+import type { UnredactablePart } from '../dom/errors.js';
+export interface PdfExtraction {
+    /** Flat text detection runs on. */
+    plainText: string;
+    pageCount: number;
+    pages: PdfPageInfo[];
+    /** Glyph runs in flat-text order (internal geometry, exposed for hosts that draw previews). */
+    runs: GlyphRun[];
+    /** Parts that cannot be redacted (scanned pages, undecodable text); gate the export like docx. */
+    unredactable: UnredactablePart[];
+    /** Parts the writer will drop from the output. */
+    removed: RemovedPart[];
+    warnings: string[];
+    /** True when no readable text was found. */
+    empty: boolean;
+    /** 0-based pages whose text came from pdf.js because our decoder disagreed (edits rasterize them). */
+    rasterOnlyPages: number[];
+    /** Input bytes (the writer's source of truth). */
+    bytes: Uint8Array;
+    assets?: PdfAssetPaths;
+    password?: string;
+}
+export type PdfInput = Blob | ArrayBuffer | Uint8Array;
+export declare function toPdfBytes(input: PdfInput): Promise<Uint8Array>;
+export declare function readPdf(input: PdfInput, options?: PdfReadOptions): Promise<PdfExtraction>;
+/** True for names ending in .pdf (case-insensitive). */
+export declare function isPdfFile(filename: string): boolean;

package/dist/pdf/read.js

@@ -0,0 +1,65 @@
+/**
+ * @doccloak/core/pdf - readPdf (T213/T215).
+ *
+ * Parses a PDF, extracts its text with glyph geometry, cross-checks every
+ * page against pdf.js and returns the extraction hosts run detection on.
+ * The extraction keeps the input bytes; the writer re-extracts from them so
+ * a stale extraction can never be applied to different bytes.
+ */
+import { DEFAULT_MAX_BYTES, extractPdf } from "./extract.js";
+import { UnsupportedDocumentError } from "../dom/errors.js";
+import { openWithOracle } from "./oracle.js";
+export async function toPdfBytes(input) {
+    if (input instanceof Uint8Array)
+        return input;
+    if (input instanceof ArrayBuffer)
+        return new Uint8Array(input);
+    if (typeof input.arrayBuffer === 'function')
+        return new Uint8Array(await input.arrayBuffer());
+    // Older Blob implementations (jsdom): go through FileReader.
+    return new Promise((resolve, reject) => {
+        const reader = new FileReader();
+        reader.onerror = () => reject(reader.error ?? new Error('could not read the file'));
+        reader.onload = () => resolve(new Uint8Array(reader.result));
+        reader.readAsArrayBuffer(input);
+    });
+}
+export async function readPdf(input, options = {}) {
+    const bytes = await toPdfBytes(input);
+    // Size cap before anything parses the file (pdf.js would otherwise read all of it first).
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    if (bytes.length > maxBytes) {
+        throw new UnsupportedDocumentError('too-large', `PDF is ${bytes.length} bytes; the limit is ${maxBytes}`, [String(bytes.length)]);
+    }
+    const oracle = await openWithOracle(bytes, options.assets, options.password);
+    try {
+        const res = await extractPdf(bytes, {
+            maxBytes: options.maxBytes,
+            maxPages: options.maxPages,
+            maxGlyphs: options.maxGlyphs,
+            password: options.password,
+            oracle,
+        });
+        return {
+            plainText: res.plainText,
+            pageCount: res.pages.length,
+            pages: res.pages,
+            runs: res.runs,
+            unredactable: res.unredactable,
+            removed: res.removed,
+            warnings: res.warnings,
+            empty: res.empty,
+            rasterOnlyPages: res.model.pages.filter((p) => p.oracleText).map((p) => p.index),
+            bytes,
+            assets: options.assets,
+            password: options.password,
+        };
+    }
+    finally {
+        await oracle.close();
+    }
+}
+/** True for names ending in .pdf (case-insensitive). */
+export function isPdfFile(filename) {
+    return /\.pdf$/i.test(filename.trim());
+}

package/dist/pdf/serializer.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @doccloak/core/pdf - content stream serializer (T206).
+ *
+ * Writes operators back to bytes. Operators that still carry their source
+ * range are copied verbatim from the original stream (so nothing we did not
+ * touch changes by even a byte); synthesized or edited operators are emitted
+ * from their operands. New strings are always written as hex strings, which
+ * is binary-safe for every font encoding.
+ */
+import type { ContentOp, Operand } from './lexer.js';
+export declare function formatNumber(value: number): string;
+export declare function hexOf(bytes: Uint8Array): string;
+export declare function serializeOperand(operand: Operand): string;
+/** Serialize one operator from its operands (ignores the source range). */
+export declare function serializeOp(op: ContentOp): string;
+/**
+ * Serialize a whole operator list. `source` is the original stream: an op
+ * whose [start, end) range is present is copied from it byte-for-byte.
+ */
+export declare function serializeOps(ops: readonly ContentOp[], source?: Uint8Array): Uint8Array;
+export declare function latin1Bytes(text: string): Uint8Array;

package/dist/pdf/serializer.js

@@ -0,0 +1,106 @@
+/**
+ * @doccloak/core/pdf - content stream serializer (T206).
+ *
+ * Writes operators back to bytes. Operators that still carry their source
+ * range are copied verbatim from the original stream (so nothing we did not
+ * touch changes by even a byte); synthesized or edited operators are emitted
+ * from their operands. New strings are always written as hex strings, which
+ * is binary-safe for every font encoding.
+ */
+export function formatNumber(value) {
+    if (!Number.isFinite(value))
+        return '0';
+    if (Number.isInteger(value))
+        return Math.abs(value) < 1e21 ? String(value) : BigInt(value).toString();
+    // Shortest round-trip form keeps the source precision; PDF has no exponent syntax.
+    let s = String(value);
+    if (/e/i.test(s) || (s.split('.')[1]?.length ?? 0) > 5)
+        s = value.toFixed(5);
+    s = s.replace(/(\.\d*?)0+$/, '$1').replace(/\.$/, '');
+    if (s === '-0' || s === '')
+        s = '0';
+    return s;
+}
+function escapeName(value) {
+    let out = '/';
+    for (let i = 0; i < value.length; i++) {
+        const c = value.charCodeAt(i);
+        const ch = value[i];
+        if (c < 0x21 || c > 0x7e || '()<>[]{}/%#'.includes(ch)) {
+            out += '#' + c.toString(16).padStart(2, '0').toUpperCase();
+        }
+        else {
+            out += ch;
+        }
+    }
+    return out;
+}
+export function hexOf(bytes) {
+    let s = '<';
+    for (let i = 0; i < bytes.length; i++)
+        s += bytes[i].toString(16).padStart(2, '0').toUpperCase();
+    return s + '>';
+}
+export function serializeOperand(operand) {
+    switch (operand.kind) {
+        case 'number': return formatNumber(operand.value);
+        case 'name': return escapeName(operand.value);
+        case 'string': return hexOf(operand.bytes);
+        case 'bool': return operand.value ? 'true' : 'false';
+        case 'null': return 'null';
+        case 'array': return '[' + operand.items.map(serializeOperand).join(' ') + ']';
+        case 'dict': {
+            const parts = [];
+            for (const [k, v] of operand.entries)
+                parts.push(escapeName(k) + ' ' + serializeOperand(v));
+            return '<<' + parts.join(' ') + '>>';
+        }
+    }
+}
+/** Serialize one operator from its operands (ignores the source range). */
+export function serializeOp(op) {
+    if (op.op === 'BI' || op.op === '') {
+        return op.raw ? latin1Of(op.raw) : '';
+    }
+    const parts = op.operands.map(serializeOperand);
+    parts.push(op.op);
+    return parts.join(' ');
+}
+function latin1Of(bytes) {
+    let s = '';
+    for (let i = 0; i < bytes.length; i++)
+        s += String.fromCharCode(bytes[i]);
+    return s;
+}
+/**
+ * Serialize a whole operator list. `source` is the original stream: an op
+ * whose [start, end) range is present is copied from it byte-for-byte.
+ */
+export function serializeOps(ops, source) {
+    const chunks = [];
+    let total = 0;
+    const push = (u) => { chunks.push(u); total += u.length; };
+    const NL = Uint8Array.of(0x0a);
+    for (const op of ops) {
+        if (source && op.start !== undefined && op.end !== undefined) {
+            push(source.subarray(op.start, op.end));
+        }
+        else {
+            push(latin1Bytes(serializeOp(op)));
+        }
+        push(NL);
+    }
+    const out = new Uint8Array(total);
+    let p = 0;
+    for (const c of chunks) {
+        out.set(c, p);
+        p += c.length;
+    }
+    return out;
+}
+export function latin1Bytes(text) {
+    const out = new Uint8Array(text.length);
+    for (let i = 0; i < text.length; i++)
+        out[i] = text.charCodeAt(i) & 0xff;
+    return out;
+}

package/dist/pdf/standard-metrics.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @doccloak/core/pdf - metrics of the standard 14 fonts (T209).
+ *
+ * Fonts that are not embedded and carry no /Widths (the standard 14 and their
+ * common aliases: Arial, Times New Roman, Courier New) get their advance
+ * widths from the AFM metrics vendored by @cantoo/pdf-lib.
+ */
+export type StandardFontName = 'Courier' | 'Courier-Bold' | 'Courier-Oblique' | 'Courier-BoldOblique' | 'Helvetica' | 'Helvetica-Bold' | 'Helvetica-Oblique' | 'Helvetica-BoldOblique' | 'Times-Roman' | 'Times-Bold' | 'Times-Italic' | 'Times-BoldItalic' | 'Symbol' | 'ZapfDingbats';
+/**
+ * Map a /BaseFont to a standard 14 font, or undefined. Handles the aliases
+ * from the PDF 1.7 implementation notes (Arial, TimesNewRoman, CourierNew)
+ * and the ",Bold" / "-BoldItalic" / "PS-BoldMT" style suffixes.
+ */
+export declare function standardFontFor(baseFont: string): StandardFontName | undefined;
+export interface StandardMetrics {
+    name: StandardFontName;
+    /** Advance width of a glyph by name, in 1/1000 text space units; undefined when the font has no such glyph. */
+    widthOfGlyph(glyphName: string): number | undefined;
+    /** Glyph names present in the AFM (for encodability of placeholders in a non-embedded font). */
+    hasGlyph(glyphName: string): boolean;
+    /** Built-in encoding of the AFM (code -> glyph name), for Symbol and ZapfDingbats. */
+    builtinEncoding(): ReadonlyArray<string | undefined>;
+    ascender: number;
+    descender: number;
+    capHeight: number;
+}
+export declare function loadStandardMetrics(name: StandardFontName): StandardMetrics;