@scanmate/merge 0.7.1 → 0.9.0

package/README.md

@@ -51,6 +51,7 @@ By default each image page is the image at its resolution. A 2480 × 3508 scan a
 | `quality` | `92` | JPEG quality. |
 | `passThrough` | `true` | Return a lone PDF unchanged. |
 | `metadata` | none | Title, author, subject, keywords, creator. The producer is always `@scanmate/merge`. |
+| `password` | none | Opens an encrypted PDF source that needs a password to be read. A signed or permission-restricted PDF - locked with an owner password alone - needs none. Tried on every encrypted source; one it does not open is tried with no password instead, so it cannot lock out a source that needed nothing. |
 
 Each entry in `pages` says which source and source page it came from, how it was embedded, and its size. A source that cannot be used raises a `MergeSourceError` carrying its `index`.
 
@@ -58,6 +59,24 @@ Measured on real scans: three 120-dpi page JPEGs plus a 7-page PDF merged in 20
 
 PDF writing uses `@cantoo/pdf-lib`, the maintained fork of pdf-lib, which is pure JavaScript with nothing to install on the host.
 
+## Drawing on a PDF, not just assembling one
+
+The other thing this package writes is marks. `markPages` draws a set of regions on a PDF as vector rectangles, each with its bleed dashed around it, and hands the PDF back:
+
+```ts
+import { markPages } from '@scanmate/merge'
+
+const { pdf, drawn, warnings } = await markPages('issued.pdf', [
+  { page: 1, id: 'signature', x: 120, y: 577, width: 262, height: 22 },
+], { bleedTop: 2, bleedBottom: 12 })
+```
+
+It exists to check that the regions a validation will measure are where the document's fields actually are - most people reach it as `Scanmate.mark` in `@scanmate/scan`, whose README has a worked example on the W-9.
+
+**Signed documents open as they are.** They usually arrive encrypted - an owner password restricting editing, none needed to read - which pdf-lib refuses by default. They are decrypted as they are read, with nothing to pass; `password` is only for a PDF that needs one to be read at all.
+
+Two things it gets right that a naive version would not. **Rotation and crop box:** a region is in points from the top-left of the page *as displayed*, which is how `@scanmate/extract` reports text, while pdf-lib draws from the bottom-left of the unrotated media box. The conversion between the two is pdf.js's own page transform, ported line for line and inverted, and its spec pins it to values read off real pdf.js for every quarter turn, with and without an offset crop box. **Bleed:** it is resolved by `resolveBleed` from `@scanmate/ink`, the same function the pixel comparison uses, so the band drawn is the band measured.
+
 ## How it decides
 
 [`documentation/algorithms.md`](./documentation/algorithms.md) has the algorithms in full: what each step measures, the decision flows, every constant with the measurement behind it, and what the package deliberately does not do.

package/dist/index.esm.js

@@ -1,5 +1,5 @@
-import { PDFDocument, EncryptedPDFError } from '@cantoo/pdf-lib';
-import { isRaster, decodeImage, readImageMetadata, encodeImage } from '@scanmate/ink';
+import { PDFDocument, rgb, StandardFonts, degrees } from '@cantoo/pdf-lib';
+import { isRaster, decodeImage, readImageMetadata, encodeImage, resolveBleed, hasBleed, growBy } from '@scanmate/ink';
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 
@@ -125,6 +125,60 @@ async function readBytes(source, index) {
   throw new MergeSourceError(index, 'expected a path, a file URL, bytes, a raster or { raster, dpi }');
 }
 
+/** A PDF that needs a password to open, which was not given or did not work. */
+class PdfPasswordError extends Error {
+  /** Whether a password was given at all - wrong, or missing. */
+  given;
+  constructor(given) {
+    super(given ? 'this PDF is encrypted, and the password given does not open it' : 'this PDF is encrypted with a password it needs to be opened - pass `password`');
+    this.name = 'PdfPasswordError';
+    this.given = given;
+  }
+}
+/**
+ * Opens a PDF for writing, decrypting it if it is encrypted.
+ *
+ * Signed documents usually arrive encrypted: an owner password restricting
+ * what may be done with them, and no password needed to read them. pdf-lib
+ * refuses those outright, and its own error suggests `ignoreEncryption: true`.
+ * That is not taken here, because it is measured to be wrong for anything that
+ * writes: the document loads and saves and still opens, with its text intact,
+ * but whatever was drawn on it is silently missing - written unencrypted into a
+ * file that still declares itself encrypted, so a viewer "decrypts" it into
+ * nothing. A helper that draws marks would hand back a clean PDF with no marks
+ * and no error.
+ *
+ * Decrypting instead is correct, and costs a caller nothing in the common case:
+ * the empty password opens an owner-password-only document. Only a PDF that
+ * needs a password to be read at all needs one given.
+ *
+ * Nor is the document loaded for incremental update, which would keep the
+ * original bytes intact and with them an existing digital signature. That is
+ * measured too: on an encrypted document the original page content does not
+ * survive it. A marked copy is for looking at; it is not the signed document,
+ * and does not pretend to be.
+ */
+async function openPdf(bytes, {
+  password
+} = {}) {
+  // The password given first, then none. A caller's password is for the document
+  // that needs one; tried alone it would lock out the owner-password-only PDF that
+  // needed nothing - which is what happened when one password was applied to every
+  // source of a merge. The empty password opens only what anyone may read anyway.
+  const attempts = password === undefined || password === '' ? [''] : [password, ''];
+  for (const attempt of attempts) try {
+    // An empty password changes nothing for a document that is not encrypted.
+    return await PDFDocument.load(bytes, {
+      password: attempt,
+      updateMetadata: false
+    });
+  } catch (error) {
+    // pdf-lib reports these as plain errors: "NEEDS PASSWORD", "Password incorrect".
+    if (!(error instanceof Error) || !/password/i.test(error.message)) throw error;
+  }
+  throw new PdfPasswordError(password !== undefined);
+}
+
 /**
  * Many files in, one PDF out: PDFs, images and rasters, in the order given,
  * mixed freely.
@@ -148,6 +202,7 @@ async function mergeDocuments(sources, options = {}) {
     quality = 92,
     passThrough = true,
     metadata,
+    password,
     onProgress
   } = options;
   if (sources.length === 0) throw new RangeError('nothing to merge');
@@ -160,7 +215,8 @@ async function mergeDocuments(sources, options = {}) {
     margin,
     imageDpi,
     encoding,
-    quality
+    quality,
+    password
   };
   for (const [index, source] of resolved.entries()) {
     const started = Date.now();
@@ -210,7 +266,7 @@ async function mergeDocuments(sources, options = {}) {
   };
 }
 async function appendPdf(context, bytes, index) {
-  const source = await loadPdf(bytes, index);
+  const source = await loadPdf(bytes, index, context.password);
   const copied = await context.merged.copyPages(source, source.getPageIndices());
   for (const [i, page] of copied.entries()) {
     context.merged.addPage(page);
@@ -230,13 +286,18 @@ async function appendPdf(context, bytes, index) {
     });
   }
 }
-async function loadPdf(bytes, index) {
+/**
+ * A source PDF, decrypted if it is encrypted - an owner-password-only document,
+ * the usual signed or restricted PDF, needs nothing given. The merged document
+ * is a new one, so it comes out unencrypted whatever went in.
+ */
+async function loadPdf(bytes, index, password) {
   try {
-    return await PDFDocument.load(bytes, {
-      updateMetadata: false
+    return await openPdf(bytes, {
+      password
     });
   } catch (error) {
-    if (error instanceof EncryptedPDFError) throw new MergeSourceError(index, 'it is an encrypted PDF, which cannot be copied without its password');
+    if (error instanceof PdfPasswordError) throw new MergeSourceError(index, error.given ? 'it is an encrypted PDF, and `password` does not open it' : 'it is an encrypted PDF that needs a password to open - pass `password`');
     throw new MergeSourceError(index, `it is not a readable PDF (${error instanceof Error ? error.message : String(error)})`);
   }
 }
@@ -353,5 +414,204 @@ function embeddableFormat(bytes) {
   return null;
 }
 
-export { MIN_RECORDED_DPI, MergeSourceError, PAPER, isPdf, mergeDocuments, placeImage, readSource, resolveDpi };
+/**
+ * The page as a reader sees it, and the way back to the PDF's own coordinates.
+ *
+ * A mark is measured the way `@scanmate/extract` reports text: from the top-left
+ * of the page as displayed, in points, with the page's `/Rotate` and crop box
+ * already applied. pdf-lib draws in the PDF's own user space instead: from the
+ * bottom-left of the media box, before any rotation.
+ *
+ * Getting from one to the other is the whole difficulty of drawing a mark in
+ * the right place, and doing it approximately would defeat the purpose - a
+ * helper for checking positions that is wrong on rotated or cropped pages gives
+ * false confidence on exactly the pages that most need checking.
+ *
+ * So this is pdf.js's own `PageViewport` transform at scale 1, ported line for
+ * line rather than re-derived, and inverted. The text a mark was measured from
+ * and the box drawn for it then go through the same arithmetic in opposite
+ * directions.
+ */
+/** User space to what a reader sees - pdf.js's `PageViewport` at scale 1. */
+function viewportTransform({
+  view,
+  rotation
+}) {
+  const centerX = (view[2] + view[0]) / 2;
+  const centerY = (view[3] + view[1]) / 2;
+  const [a, b, c, d] = rotationOf(rotation);
+  const quarter = a === 0;
+  const offsetX = quarter ? Math.abs(centerY - view[1]) : Math.abs(centerX - view[0]);
+  const offsetY = quarter ? Math.abs(centerX - view[0]) : Math.abs(centerY - view[1]);
+  return [a, b, c, d, offsetX - a * centerX - c * centerY, offsetY - b * centerX - d * centerY];
+}
+/** How large the page is as a reader sees it: a quarter turn swaps width and height. */
+function viewportSize({
+  view,
+  rotation
+}) {
+  const [a] = rotationOf(rotation);
+  const across = view[2] - view[0];
+  const down = view[3] - view[1];
+  return a === 0 ? {
+    width: down,
+    height: across
+  } : {
+    width: across,
+    height: down
+  };
+}
+/** A point a reader sees, back in the PDF's own coordinates. */
+function toUserSpace([a, b, c, d, e, f], x, y) {
+  const det = a * d - b * c;
+  const dx = x - e;
+  const dy = y - f;
+  // `+ 0` turns a negative zero positive: harmless to draw at, noisy to read back.
+  return {
+    x: (d * dx - c * dy) / det + 0,
+    y: (-b * dx + a * dy) / det + 0
+  };
+}
+/**
+ * pdf.js's rotation matrix for a page turned by `rotation` degrees.
+ *
+ * Only quarter turns are legal in a PDF; anything else is refused here exactly
+ * as pdf.js refuses it, rather than drawn somewhere plausible.
+ */
+function rotationOf(rotation) {
+  const matrix = ROTATIONS.get((rotation % 360 + 360) % 360);
+  if (matrix === undefined) throw new RangeError(`a page may only be rotated by a multiple of 90 degrees, and is rotated by ${rotation}`);
+  return matrix;
+}
+/** pdf.js's `rotateA` to `rotateD`, by quarter turn. */
+const ROTATIONS = new Map([[0, [1, 0, 0, -1]], [90, [0, 1, 1, 0]], [180, [-1, 0, 0, 1]], [270, [0, -1, -1, 0]]]);
+
+/**
+ * The colours of the audit's evidence page, so the two read the same way: the
+ * region in blue, its bleed in magenta.
+ */
+const REGION = rgb(0, 23 / 255, 252 / 255);
+const BLEED = rgb(245 / 255, 0, 252 / 255);
+const LABEL_SIZE = 7;
+/**
+ * Draws each mark on the original, with its bleed around it, and hands the PDF
+ * back - a way to see whether the positions a validation will use are where
+ * the fields actually are, before anything is measured with them.
+ *
+ * Drawn on the document itself, as vectors: the page is not re-rendered, so it
+ * stays sharp at any zoom and the boxes sit exactly where their coordinates
+ * say. Nothing is aligned or adjusted, because there is nothing to align - this
+ * is the original, and the marks were measured against it.
+ */
+async function markPages(pdf, marks, options = {}) {
+  const source = await readSource(pdf, 0);
+  if (source.kind !== 'pdf') throw new TypeError('marks are drawn on a PDF, and this is not one');
+  // Decrypted if encrypted, as a signed document usually is - see `openPdf` for
+  // why that and not `ignoreEncryption`, which would silently drop every mark.
+  const document = await openPdf(source.bytes, {
+    password: options.password
+  });
+  const font = options.labels === false ? null : await document.embedFont(StandardFonts.Helvetica);
+  const bleed = resolveBleed(options);
+  const pages = document.getPages();
+  const warnings = [];
+  let drawn = 0;
+  for (const mark of marks) {
+    const name = mark.id ?? `mark ${drawn + warnings.length + 1}`;
+    const page = pages[mark.page - 1];
+    if (page === undefined) {
+      warnings.push(`${name} is on page ${mark.page}, and the document has ${pages.length}`);
+      continue;
+    }
+    const geometry = geometryOf(page);
+    const size = viewportSize(geometry);
+    if (mark.x < 0 || mark.y < 0 || mark.x + mark.width > size.width || mark.y + mark.height > size.height) warnings.push(`${name} reaches past the edge of page ${mark.page}, which is ${round(size.width)} x ${round(size.height)} pt`);
+    // The band first, so the region's own outline draws over it where they meet.
+    if (hasBleed(bleed)) draw(page, geometry, growBy(mark, bleed), {
+      colour: BLEED,
+      dashed: true
+    });
+    draw(page, geometry, mark, {
+      colour: REGION,
+      dashed: false
+    });
+    if (font !== null && mark.id !== undefined) label(page, geometry, font, mark);
+    drawn++;
+  }
+  return {
+    pdf: await document.save(),
+    drawn,
+    warnings
+  };
+}
+/** The page's visible box and rotation, as pdf.js would read them. */
+function geometryOf(page) {
+  const crop = page.getCropBox();
+  return {
+    view: [crop.x, crop.y, crop.x + crop.width, crop.y + crop.height],
+    rotation: page.getRotation().angle
+  };
+}
+/**
+ * A rectangle measured as displayed, drawn in the PDF's own coordinates.
+ *
+ * A quarter turn keeps a rectangle a rectangle, so its corners are taken back
+ * to user space and their extent is the box to draw.
+ */
+function draw(page, geometry, rect, style) {
+  const {
+    x,
+    y,
+    width,
+    height
+  } = userBox(geometry, rect);
+  page.drawRectangle({
+    x,
+    y,
+    width,
+    height,
+    borderColor: style.colour,
+    borderWidth: style.dashed ? 0.6 : 0.9,
+    borderDashArray: style.dashed ? [2.5, 1.5] : undefined,
+    opacity: 0,
+    borderOpacity: 1
+  });
+}
+/**
+ * The id inside the box's top-left corner, upright to the reader however the
+ * page is turned.
+ *
+ * Inside rather than above: on the original a field is empty, so the corner is
+ * free, while the space above it is usually the printed line before - and a
+ * label written over that would obscure the very edge being checked.
+ */
+function label(page, geometry, font, mark) {
+  const at = toUserSpace(viewportTransform(geometry), mark.x + 2, mark.y + LABEL_SIZE);
+  page.drawText(mark.id ?? '', {
+    x: at.x,
+    y: at.y,
+    size: LABEL_SIZE,
+    font,
+    color: REGION,
+    // Text is laid in user space; turning it with the page keeps it readable.
+    rotate: degrees(geometry.rotation)
+  });
+}
+function userBox(geometry, rect) {
+  const transform = viewportTransform(geometry);
+  const corners = [toUserSpace(transform, rect.x, rect.y), toUserSpace(transform, rect.x + rect.width, rect.y + rect.height)];
+  const xs = corners.map(corner => corner.x);
+  const ys = corners.map(corner => corner.y);
+  return {
+    x: Math.min(...xs),
+    y: Math.min(...ys),
+    width: Math.abs(xs[1] - xs[0]),
+    height: Math.abs(ys[1] - ys[0])
+  };
+}
+function round(value) {
+  return Math.round(value * 10) / 10;
+}
+
+export { MIN_RECORDED_DPI, MergeSourceError, PAPER, PdfPasswordError, isPdf, markPages, mergeDocuments, openPdf, placeImage, readSource, resolveDpi, toUserSpace, viewportSize, viewportTransform };
 //# sourceMappingURL=index.esm.js.map

package/dist/src/document-merge/merge-result.contract.d.ts

@@ -2,6 +2,13 @@ import type { ProgressCallback } from '@scanmate/ink';
 import type { PageSize } from '../page-placement/index.js';
 import type { SourceKind } from '../source-reading/index.js';
 export interface MergeOptions {
+    /**
+     * Opens an encrypted PDF source that needs a password to be read. The usual
+     * encrypted PDF - a signed or permission-restricted document, locked with an
+     * owner password alone - needs none and is decrypted as it is copied. The
+     * same password is tried on every encrypted source.
+     */
+    password?: string;
     /** Size of each image page: the image at its resolution (`'image'`, the default), or a paper size to fit it in. */
     pageSize?: PageSize;
     /** Points of white kept around an image on a paper-size page. Default `0`. */

package/dist/src/index.d.ts

@@ -21,11 +21,16 @@
  */
 export { mergeDocuments } from './document-merge/index.js';
 export type { Embedding, MergedPage, MergeOptions, MergeResult } from './document-merge/index.js';
-export { MergeSourceError } from './source-reading/index.js';
+export { MergeSourceError, openPdf, PdfPasswordError } from './source-reading/index.js';
+export type { OpenPdfOptions } from './source-reading/index.js';
 export type { SourceKind } from './source-reading/index.js';
+export { markPages } from './page-marking/index.js';
+export type { MarkOptions, MarkResult, PageMark } from './page-marking/index.js';
 export type { PageSize } from './page-placement/index.js';
 export { MIN_RECORDED_DPI, PAPER, placeImage, resolveDpi } from './page-placement/index.js';
 export type { Placement } from './page-placement/index.js';
 export { isPdf, readSource } from './source-reading/index.js';
 export type { ResolvedSource } from './source-reading/index.js';
+export { toUserSpace, viewportSize, viewportTransform } from './page-marking/index.js';
+export type { Affine, PageGeometry } from './page-marking/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/page-marking/index.d.ts

@@ -0,0 +1,6 @@
+/** Drawing expected regions on the original, to see whether they are where the fields are. */
+export { markPages } from './mark-pages.use-case.js';
+export type { MarkOptions, MarkResult, PageMark } from './page-mark.contract.js';
+export { toUserSpace, viewportSize, viewportTransform } from './page-viewport.policy.js';
+export type { Affine, PageGeometry } from './page-viewport.policy.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/page-marking/mark-pages.use-case.d.ts

@@ -0,0 +1,14 @@
+import type { ScanmateBinarySource } from '@scanmate/ink';
+import type { MarkOptions, MarkResult, PageMark } from './page-mark.contract.js';
+/**
+ * Draws each mark on the original, with its bleed around it, and hands the PDF
+ * back - a way to see whether the positions a validation will use are where
+ * the fields actually are, before anything is measured with them.
+ *
+ * Drawn on the document itself, as vectors: the page is not re-rendered, so it
+ * stays sharp at any zoom and the boxes sit exactly where their coordinates
+ * say. Nothing is aligned or adjusted, because there is nothing to align - this
+ * is the original, and the marks were measured against it.
+ */
+export declare function markPages(pdf: ScanmateBinarySource, marks: readonly PageMark[], options?: MarkOptions): Promise<MarkResult>;
+//# sourceMappingURL=mark-pages.use-case.d.ts.map

package/dist/src/page-marking/page-mark.contract.d.ts

@@ -0,0 +1,46 @@
+import type { Bleed, ScanmateRect } from '@scanmate/ink';
+/**
+ * One region to draw, where the document's own fields are expected to be.
+ *
+ * In points, from the top-left of the page as displayed - the same coordinates
+ * `@scanmate/extract` reports text in, and the same shape as `@scanmate/diff`'s
+ * `ExpectedChange`. So the array about to be handed to an audit can be drawn
+ * as it is, and what is checked visually is exactly what will be measured.
+ */
+export interface PageMark extends ScanmateRect {
+    /** One-based page number. */
+    page: number;
+    /** Written beside the box, so a reviewer can tell which field is which. */
+    id?: string;
+}
+/**
+ * How the marks are drawn. The bleed - `bleed`, and `bleedTop`, `bleedRight`,
+ * `bleedBottom`, `bleedLeft` to override a side - is drawn as a dashed band
+ * around each mark, and is the same rule the pixel comparison measures with. A
+ * mark checked here with a given bleed is checked against the region an audit
+ * with that bleed will actually claim. Default 6 points on every side.
+ */
+export interface MarkOptions extends Bleed {
+    /** Write each mark's `id` beside it. Default `true`. */
+    labels?: boolean;
+    /**
+     * Opens a PDF encrypted with a password it needs to be read. A signed or
+     * permission-restricted document, locked with an owner password alone, needs
+     * none: it is decrypted as it is read, and the marks are drawn on it.
+     */
+    password?: string;
+}
+export interface MarkResult {
+    /** The original, with the marks drawn on it. Nothing else about it changes. */
+    pdf: Uint8Array;
+    /** How many marks were drawn. */
+    drawn: number;
+    /**
+     * What could not be drawn, or was drawn somewhere it cannot be right: a mark
+     * on a page the document does not have, or one that reaches past the edge of
+     * its page. The second is itself a positioning error, and exactly the kind
+     * this exists to catch.
+     */
+    warnings: string[];
+}
+//# sourceMappingURL=page-mark.contract.d.ts.map

package/dist/src/page-marking/page-viewport.policy.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The page as a reader sees it, and the way back to the PDF's own coordinates.
+ *
+ * A mark is measured the way `@scanmate/extract` reports text: from the top-left
+ * of the page as displayed, in points, with the page's `/Rotate` and crop box
+ * already applied. pdf-lib draws in the PDF's own user space instead: from the
+ * bottom-left of the media box, before any rotation.
+ *
+ * Getting from one to the other is the whole difficulty of drawing a mark in
+ * the right place, and doing it approximately would defeat the purpose - a
+ * helper for checking positions that is wrong on rotated or cropped pages gives
+ * false confidence on exactly the pages that most need checking.
+ *
+ * So this is pdf.js's own `PageViewport` transform at scale 1, ported line for
+ * line rather than re-derived, and inverted. The text a mark was measured from
+ * and the box drawn for it then go through the same arithmetic in opposite
+ * directions.
+ */
+/** A two-dimensional affine transform, `[a, b, c, d, e, f]` as PDF writes them. */
+export type Affine = readonly [number, number, number, number, number, number];
+/** The page's visible box, `[x0, y0, x1, y1]` in user space, and its rotation. */
+export interface PageGeometry {
+    view: readonly [number, number, number, number];
+    rotation: number;
+}
+/** User space to what a reader sees - pdf.js's `PageViewport` at scale 1. */
+export declare function viewportTransform({ view, rotation }: PageGeometry): Affine;
+/** How large the page is as a reader sees it: a quarter turn swaps width and height. */
+export declare function viewportSize({ view, rotation }: PageGeometry): {
+    width: number;
+    height: number;
+};
+/** A point a reader sees, back in the PDF's own coordinates. */
+export declare function toUserSpace([a, b, c, d, e, f]: Affine, x: number, y: number): {
+    x: number;
+    y: number;
+};
+//# sourceMappingURL=page-viewport.policy.d.ts.map

package/dist/src/source-reading/index.d.ts

@@ -2,5 +2,7 @@
 export { MergeSourceError } from './merge-source.contract.js';
 export type { SourceKind } from './merge-source.contract.js';
 export { isPdf, readSource } from './read-source.use-case.js';
+export { openPdf, PdfPasswordError } from './open-pdf.use-case.js';
+export type { OpenPdfOptions } from './open-pdf.use-case.js';
 export type { ResolvedSource } from './read-source.use-case.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/source-reading/open-pdf.use-case.d.ts

@@ -0,0 +1,42 @@
+import { PDFDocument } from '@cantoo/pdf-lib';
+/** A PDF that needs a password to open, which was not given or did not work. */
+export declare class PdfPasswordError extends Error {
+    /** Whether a password was given at all - wrong, or missing. */
+    readonly given: boolean;
+    constructor(given: boolean);
+}
+export interface OpenPdfOptions {
+    /**
+     * The password that opens the document, for a PDF encrypted with one.
+     *
+     * Not needed for the usual encrypted PDF - a signed or permission-restricted
+     * document, locked with an owner password and nothing else - which opens with
+     * no password at all and is decrypted as it is read.
+     */
+    password?: string;
+}
+/**
+ * Opens a PDF for writing, decrypting it if it is encrypted.
+ *
+ * Signed documents usually arrive encrypted: an owner password restricting
+ * what may be done with them, and no password needed to read them. pdf-lib
+ * refuses those outright, and its own error suggests `ignoreEncryption: true`.
+ * That is not taken here, because it is measured to be wrong for anything that
+ * writes: the document loads and saves and still opens, with its text intact,
+ * but whatever was drawn on it is silently missing - written unencrypted into a
+ * file that still declares itself encrypted, so a viewer "decrypts" it into
+ * nothing. A helper that draws marks would hand back a clean PDF with no marks
+ * and no error.
+ *
+ * Decrypting instead is correct, and costs a caller nothing in the common case:
+ * the empty password opens an owner-password-only document. Only a PDF that
+ * needs a password to be read at all needs one given.
+ *
+ * Nor is the document loaded for incremental update, which would keep the
+ * original bytes intact and with them an existing digital signature. That is
+ * measured too: on an encrypted document the original page content does not
+ * survive it. A marked copy is for looking at; it is not the signed document,
+ * and does not pretend to be.
+ */
+export declare function openPdf(bytes: Uint8Array, { password }?: OpenPdfOptions): Promise<PDFDocument>;
+//# sourceMappingURL=open-pdf.use-case.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scanmate/merge",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Merge PDFs, images and rasters into one PDF: PDF pages copied as they are, JPEGs embedded without recompression, every page of a TIFF.",
   "license": "MIT",
   "author": "Eduardo Russo",
@@ -41,7 +41,7 @@
   ],
   "dependencies": {
     "@cantoo/pdf-lib": "^2.11.1",
-    "@scanmate/ink": "^0.7.1"
+    "@scanmate/ink": "^0.9.0"
   },
   "publishConfig": {
     "access": "public"