@scanmate/merge 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eduardo Russo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+![scanmate merge](./scanmate-merge.svg)
+
+# `@scanmate/merge`
+
+PDFs, images and rasters into one PDF, in the order given and mixed freely.
+
+```ts
+import { mergeDocuments } from '@scanmate/merge'
+
+// What a person uploaded, page by page, as one document:
+const { pdf, pages } = await mergeDocuments(['page-1.jpg', 'page-2.jpg', 'annex.pdf'])
+
+// A pipeline's aligned pages as one evidence file:
+const evidence = await mergeDocuments(
+  aligned.map(p => ({ raster: p.aligned.raster, dpi: p.original.dpi })),
+  { metadata: { title: 'Aligned scan' } },
+)
+```
+
+## What goes in, and how
+
+| Source | Result |
+|---|---|
+| PDF (path or bytes) | Pages copied, never re-rendered: text layer, vectors and signatures stay intact. Encrypted PDFs are refused with a clear error. |
+| JPEG, upright, RGB or grey | Embedded as its own bytes, so it is never compressed twice. |
+| PNG | Pixels carried over losslessly. |
+| JPEG needing EXIF rotation, CMYK JPEG, TIFF (every page), WebP, HEIF, AVIF, GIF | Decoded (rotation applied, transparency flattened onto white), then encoded once. |
+| `Raster`, or `{ raster, dpi, image? }`, i.e. any `PageImage` | Its `image` bytes are embedded when they are PNG or JPEG; otherwise the raster is encoded. |
+
+The type of each source is detected from its content, not its name. A single PDF on its own comes back byte for byte (`passedThrough: true`), unless `metadata` asks for a new file.
+
+## Page size
+
+By default each image page is the image at its resolution. A 2480 × 3508 scan at 300 dpi becomes an A4 page, so a reader that divides pixels by page inches, as `@scanmate/extract` does, gets the scan's real resolution back. Resolution comes from the caller, then the file (if it records at least 100 dpi; 72 and 96 are software defaults), then `imageDpi`. `pageSize: 'a4' | 'letter' | { width, height }` fits the image on paper instead: centred, turned landscape for a landscape image, with an optional `margin`.
+
+| Option | Default | |
+|---|---|---|
+| `pageSize` | `'image'` | Or `'a4'`, `'letter'`, `{ width, height }` in points. |
+| `imageDpi` | `150` | For images that record no resolution, or 72/96. |
+| `encoding` | `'png'` | For images that must be re-encoded; `'jpeg'` is much smaller. |
+| `quality` | `92` | JPEG quality. |
+| `passThrough` | `true` | Return a lone PDF unchanged. |
+| `metadata` | none | Title, author, subject, keywords, creator. The producer is always `@scanmate/merge`. |
+
+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`.
+
+Measured on real scans: three 120-dpi page JPEGs plus a 7-page PDF merged in 20 ms (0.73 MB). Seven aligned pages made a 3.3 MB PNG or 0.74 MB JPEG evidence file.
+
+PDF writing uses `@cantoo/pdf-lib`, the maintained fork of pdf-lib, which is pure JavaScript with nothing to install on the host.

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./src/index.js";

package/dist/index.esm.js

@@ -0,0 +1,357 @@
+import { PDFDocument, EncryptedPDFError } from '@cantoo/pdf-lib';
+import { isRaster, decodeImage, readImageMetadata, encodeImage } from '@scanmate/ink';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * How big an image's page is, and where on it the image goes.
+ *
+ * By default a page is the image at its resolution: a 2480 x 3508 scan at 300
+ * dpi becomes an A4 page, and a downstream reader that divides pixels by page
+ * inches gets the scan's real resolution back - which is exactly what
+ * `@scanmate/extract` does to decide how to render. A fixed paper size instead
+ * fits the image inside it, centred, turning the page landscape for a landscape
+ * image.
+ *
+ * Resolution comes from, in order: what the caller says; what the file records,
+ * if it is at least {@link MIN_RECORDED_DPI}; the `imageDpi` fallback. The floor
+ * is there because 72 and 96 are what cameras and editors write when they know
+ * nothing - a phone photo "at 72 dpi" would make a page over a metre tall.
+ */
+const PAPER = {
+  a4: {
+    width: 595.28,
+    height: 841.89
+  },
+  letter: {
+    width: 612,
+    height: 792
+  }
+};
+/** Recorded densities below this are software defaults, not a scan's resolution. */
+const MIN_RECORDED_DPI = 100;
+function resolveDpi(given, recorded, fallback) {
+  if (given !== undefined && given !== null && given > 0) return given;
+  if (recorded !== null && recorded >= MIN_RECORDED_DPI) return recorded;
+  return fallback;
+}
+function placeImage(pixelWidth, pixelHeight, dpi, pageSize, margin = 0) {
+  const width = pixelWidth / dpi * 72;
+  const height = pixelHeight / dpi * 72;
+  if (pageSize === 'image') return {
+    pageWidth: width,
+    pageHeight: height,
+    x: 0,
+    y: 0,
+    width,
+    height
+  };
+  const paper = typeof pageSize === 'string' ? PAPER[pageSize] : pageSize;
+  const landscape = pixelWidth > pixelHeight;
+  const pageWidth = landscape ? Math.max(paper.width, paper.height) : Math.min(paper.width, paper.height);
+  const pageHeight = landscape ? Math.min(paper.width, paper.height) : Math.max(paper.width, paper.height);
+  const scale = Math.min((pageWidth - 2 * margin) / width, (pageHeight - 2 * margin) / height);
+  const fitted = {
+    width: width * scale,
+    height: height * scale
+  };
+  return {
+    pageWidth,
+    pageHeight,
+    x: (pageWidth - fitted.width) / 2,
+    y: (pageHeight - fitted.height) / 2,
+    ...fitted
+  };
+}
+
+/** A source that could not be used, and which one it was. */
+class MergeSourceError extends Error {
+  index;
+  /**
+   * @param index - Zero-based position of the source in the list given.
+   * @param message - What is wrong with it.
+   */
+  constructor(index, message) {
+    super(`source ${index + 1}: ${message}`);
+    this.index = index;
+    this.name = 'MergeSourceError';
+  }
+}
+
+/** A PDF may carry junk before its header; readers look for it in the first kilobyte. */
+const PDF_HEADER = [0x25, 0x50, 0x44, 0x46, 0x2D]; // %PDF-
+const HEADER_WINDOW = 1024;
+async function readSource(source, index) {
+  if (isRaster(source)) return {
+    kind: 'raster',
+    raster: source,
+    dpi: null,
+    bytes: null
+  };
+  if (isImageWithResolution(source)) return {
+    kind: 'raster',
+    raster: source.raster,
+    dpi: source.dpi ?? null,
+    bytes: source.image ?? null
+  };
+  const bytes = await readBytes(source, index);
+  if (bytes.byteLength === 0) throw new MergeSourceError(index, 'it is empty');
+  return isPdf(bytes) ? {
+    kind: 'pdf',
+    bytes
+  } : {
+    kind: 'image',
+    bytes,
+    dpi: null
+  };
+}
+function isPdf(bytes) {
+  const end = Math.min(bytes.length - PDF_HEADER.length, HEADER_WINDOW);
+  for (let start = 0; start <= end; start++) if (PDF_HEADER.every((b, i) => bytes[start + i] === b)) return true;
+  return false;
+}
+function isImageWithResolution(source) {
+  return typeof source === 'object' && source !== null && 'raster' in source && isRaster(source.raster);
+}
+async function readBytes(source, index) {
+  try {
+    if (typeof source === 'string') return new Uint8Array(await readFile(source));
+    if (source instanceof URL) return new Uint8Array(await readFile(fileURLToPath(source)));
+    if (source instanceof ArrayBuffer) return new Uint8Array(source);
+    if (ArrayBuffer.isView(source)) return new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
+  } catch (error) {
+    throw new MergeSourceError(index, `it could not be read (${error instanceof Error ? error.message : String(error)})`);
+  }
+  throw new MergeSourceError(index, 'expected a path, a file URL, bytes, a raster or { raster, dpi }');
+}
+
+/**
+ * Many files in, one PDF out: PDFs, images and rasters, in the order given,
+ * mixed freely.
+ *
+ * A PDF's pages are copied, not re-rendered, so their text layer, vectors and
+ * any signatures stay as they were. A JPEG with no EXIF rotation, in RGB or
+ * grey, is embedded as its own bytes, so a scan is not compressed a second
+ * time; a PNG's pixels are carried over losslessly (the PDF holds them deflated,
+ * not as the PNG file). Anything else is decoded - EXIF rotation applied,
+ * transparency flattened onto white, every page of a multi-page TIFF - and
+ * encoded once. The upload a person scanned page by page
+ * becomes one document in upload order, and a pipeline's aligned or enhanced
+ * pages become one evidence file.
+ */
+async function mergeDocuments(sources, options = {}) {
+  const {
+    pageSize = 'image',
+    margin = 0,
+    imageDpi = 150,
+    encoding = 'png',
+    quality = 92,
+    passThrough = true,
+    metadata,
+    onProgress
+  } = options;
+  if (sources.length === 0) throw new RangeError('nothing to merge');
+  const resolved = [];
+  for (const [index, source] of sources.entries()) resolved.push(await readSource(source, index));
+  const context = {
+    merged: await PDFDocument.create(),
+    pages: [],
+    pageSize,
+    margin,
+    imageDpi,
+    encoding,
+    quality
+  };
+  for (const [index, source] of resolved.entries()) {
+    const started = Date.now();
+    onProgress?.({
+      stage: 'merge',
+      phase: 'start',
+      page: index + 1,
+      index: index + 1,
+      total: resolved.length
+    });
+    const before = context.pages.length;
+    if (source.kind === 'pdf') await appendPdf(context, source.bytes, index);else if (source.kind === 'image') await appendImageFile(context, source.bytes, index);else await appendRaster(context, source, index);
+    onProgress?.({
+      stage: 'merge',
+      phase: 'done',
+      page: index + 1,
+      index: index + 1,
+      total: resolved.length,
+      durationMs: Date.now() - started,
+      detail: {
+        kind: source.kind,
+        pages: context.pages.length - before
+      }
+    });
+  }
+  const [first] = resolved;
+  if (passThrough && metadata === undefined && resolved.length === 1 && first.kind === 'pdf') return {
+    pdf: first.bytes,
+    pageCount: context.pages.length,
+    pages: context.pages,
+    passedThrough: true
+  };
+  const {
+    merged
+  } = context;
+  merged.setProducer('@scanmate/merge');
+  if (metadata?.title !== undefined) merged.setTitle(metadata.title);
+  if (metadata?.author !== undefined) merged.setAuthor(metadata.author);
+  if (metadata?.subject !== undefined) merged.setSubject(metadata.subject);
+  if (metadata?.keywords !== undefined) merged.setKeywords(metadata.keywords);
+  if (metadata?.creator !== undefined) merged.setCreator(metadata.creator);
+  return {
+    pdf: await merged.save(),
+    pageCount: context.pages.length,
+    pages: context.pages,
+    passedThrough: false
+  };
+}
+async function appendPdf(context, bytes, index) {
+  const source = await loadPdf(bytes, index);
+  const copied = await context.merged.copyPages(source, source.getPageIndices());
+  for (const [i, page] of copied.entries()) {
+    context.merged.addPage(page);
+    const {
+      width,
+      height
+    } = page.getSize();
+    context.pages.push({
+      page: context.pages.length + 1,
+      source: index + 1,
+      sourcePage: i + 1,
+      kind: 'pdf',
+      embedding: 'pdf-page',
+      width,
+      height,
+      dpi: null
+    });
+  }
+}
+async function loadPdf(bytes, index) {
+  try {
+    return await PDFDocument.load(bytes, {
+      updateMetadata: false
+    });
+  } catch (error) {
+    if (error instanceof EncryptedPDFError) throw new MergeSourceError(index, 'it is an encrypted PDF, which cannot be copied without its password');
+    throw new MergeSourceError(index, `it is not a readable PDF (${error instanceof Error ? error.message : String(error)})`);
+  }
+}
+async function appendImageFile(context, bytes, index) {
+  const meta = await imageMetadata(bytes, index);
+  const dpi = resolveDpi(undefined, meta.density, context.imageDpi);
+  const upright = (meta.orientation ?? 1) === 1;
+  const asJpeg = meta.format === 'jpeg' && upright && (meta.space === 'srgb' || meta.space === 'b-w');
+  const asPng = meta.format === 'png' && upright;
+  if (meta.pages === 1 && (asJpeg || asPng)) {
+    const image = asJpeg ? await context.merged.embedJpg(bytes) : await context.merged.embedPng(bytes);
+    place(context, image, meta.width, meta.height, dpi, {
+      index,
+      sourcePage: 1,
+      kind: 'image',
+      embedding: asJpeg ? 'jpeg' : 'png'
+    });
+    return;
+  }
+  for (let page = 0; page < meta.pages; page++) {
+    const raster = await decodeImage(bytes, {
+      page
+    });
+    const {
+      image,
+      embedding
+    } = await encodeAndEmbed(context, raster);
+    place(context, image, raster.width, raster.height, dpi, {
+      index,
+      sourcePage: page + 1,
+      kind: 'image',
+      embedding
+    });
+  }
+}
+async function imageMetadata(bytes, index) {
+  try {
+    return await readImageMetadata(bytes);
+  } catch {
+    throw new MergeSourceError(index, 'it is neither a PDF nor an image that can be read');
+  }
+}
+async function appendRaster(context, source, index) {
+  const {
+    raster,
+    bytes
+  } = source;
+  const dpi = resolveDpi(source.dpi, null, context.imageDpi);
+  const format = bytes === null ? null : embeddableFormat(bytes);
+  if (bytes !== null && format !== null) {
+    const image = format === 'jpeg' ? await context.merged.embedJpg(bytes) : await context.merged.embedPng(bytes);
+    place(context, image, raster.width, raster.height, dpi, {
+      index,
+      sourcePage: 1,
+      kind: 'raster',
+      embedding: format
+    });
+    return;
+  }
+  const {
+    image,
+    embedding
+  } = await encodeAndEmbed(context, raster);
+  place(context, image, raster.width, raster.height, dpi, {
+    index,
+    sourcePage: 1,
+    kind: 'raster',
+    embedding
+  });
+}
+async function encodeAndEmbed(context, raster) {
+  if (context.encoding === 'jpeg') {
+    const jpeg = await encodeImage(raster, {
+      format: 'jpeg',
+      quality: context.quality
+    });
+    return {
+      image: await context.merged.embedJpg(jpeg),
+      embedding: 'encoded-jpeg'
+    };
+  }
+  const png = await encodeImage(raster, {
+    format: 'png'
+  });
+  return {
+    image: await context.merged.embedPng(png),
+    embedding: 'encoded-png'
+  };
+}
+function place(context, image, pixelWidth, pixelHeight, dpi, origin) {
+  const placement = placeImage(pixelWidth, pixelHeight, dpi, context.pageSize, context.margin);
+  const page = context.merged.addPage([placement.pageWidth, placement.pageHeight]);
+  page.drawImage(image, {
+    x: placement.x,
+    y: placement.y,
+    width: placement.width,
+    height: placement.height
+  });
+  context.pages.push({
+    page: context.pages.length + 1,
+    source: origin.index + 1,
+    sourcePage: origin.sourcePage,
+    kind: origin.kind,
+    embedding: origin.embedding,
+    width: placement.pageWidth,
+    height: placement.pageHeight,
+    dpi
+  });
+}
+/** PNG or JPEG by signature - the two formats a PDF takes as they are. */
+function embeddableFormat(bytes) {
+  if (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4E && bytes[3] === 0x47) return 'png';
+  if (bytes[0] === 0xFF && bytes[1] === 0xD8 && bytes[2] === 0xFF) return 'jpeg';
+  return null;
+}
+
+export { MIN_RECORDED_DPI, MergeSourceError, PAPER, isPdf, mergeDocuments, placeImage, readSource, resolveDpi };
+//# sourceMappingURL=index.esm.js.map

package/dist/src/document-merge/index.d.ts

@@ -0,0 +1,4 @@
+/** Many PDFs, images and rasters into one PDF. */
+export { mergeDocuments } from './merge-documents.use-case.js';
+export type { Embedding, MergedPage, MergeOptions, MergeResult } from './merge-result.contract.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/document-merge/merge-documents.use-case.d.ts

@@ -0,0 +1,18 @@
+import type { MergeSource } from '../source-reading/index.js';
+import type { MergeOptions, MergeResult } from './merge-result.contract.js';
+/**
+ * Many files in, one PDF out: PDFs, images and rasters, in the order given,
+ * mixed freely.
+ *
+ * A PDF's pages are copied, not re-rendered, so their text layer, vectors and
+ * any signatures stay as they were. A JPEG with no EXIF rotation, in RGB or
+ * grey, is embedded as its own bytes, so a scan is not compressed a second
+ * time; a PNG's pixels are carried over losslessly (the PDF holds them deflated,
+ * not as the PNG file). Anything else is decoded - EXIF rotation applied,
+ * transparency flattened onto white, every page of a multi-page TIFF - and
+ * encoded once. The upload a person scanned page by page
+ * becomes one document in upload order, and a pipeline's aligned or enhanced
+ * pages become one evidence file.
+ */
+export declare function mergeDocuments(sources: readonly MergeSource[], options?: MergeOptions): Promise<MergeResult>;
+//# sourceMappingURL=merge-documents.use-case.d.ts.map

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

@@ -0,0 +1,64 @@
+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 {
+    /** 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`. */
+    margin?: number;
+    /** Resolution for an image that does not say, or says 72 or 96. Default `150`. */
+    imageDpi?: number;
+    /**
+     * How to encode an image that cannot be embedded as it is - any format but
+     * JPEG and PNG, a JPEG that needs its EXIF rotation applied, a raster.
+     * `'png'` (the default) is lossless: a scan should not gain compression
+     * artefacts on its way into evidence. `'jpeg'` is a fraction of the size.
+     */
+    encoding?: 'png' | 'jpeg';
+    /** JPEG quality, 1-100, when `encoding` is `'jpeg'`. Default `92`. */
+    quality?: number;
+    /**
+     * A single PDF on its own comes back byte for byte - stored exactly as
+     * scanned, signatures and all. Default `true`. Setting `metadata` turns it
+     * off, since that means writing a new file.
+     */
+    passThrough?: boolean;
+    /** Information dictionary for the merged file. The producer is always `@scanmate/merge`. */
+    metadata?: {
+        title?: string;
+        author?: string;
+        subject?: string;
+        keywords?: string[];
+        creator?: string;
+    };
+    onProgress?: ProgressCallback;
+}
+/** How a page got into the merged file. */
+export type Embedding = 'pdf-page' | 'jpeg' | 'png' | 'encoded-png' | 'encoded-jpeg';
+export interface MergedPage {
+    /** One-based, in the merged file. */
+    page: number;
+    /** One-based position of the source it came from, in the list given. */
+    source: number;
+    /** One-based page within that source - above one for a PDF or a multi-page TIFF. */
+    sourcePage: number;
+    kind: SourceKind;
+    /**
+     * `'jpeg'` is the source's own bytes and `'png'` its pixels, losslessly; the
+     * `encoded-` ones were decoded and encoded again.
+     */
+    embedding: Embedding;
+    /** Page size in points. */
+    width: number;
+    height: number;
+    /** Resolution the image was placed at; `null` for a PDF page. */
+    dpi: number | null;
+}
+export interface MergeResult {
+    pdf: Uint8Array;
+    pageCount: number;
+    pages: MergedPage[];
+    /** The single PDF given was returned unchanged. */
+    passedThrough: boolean;
+}
+//# sourceMappingURL=merge-result.contract.d.ts.map

package/dist/src/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `@scanmate/merge` - PDFs, images and rasters into one PDF.
+ *
+ * ```ts
+ * import { mergeDocuments } from '@scanmate/merge'
+ *
+ * // What a person uploaded, page by page, as one document:
+ * const { pdf } = await mergeDocuments(['page-1.jpg', 'page-2.jpg', 'annex.pdf'])
+ *
+ * // A pipeline's aligned pages as one evidence file:
+ * const evidence = await mergeDocuments(aligned.map(p => ({ raster: p.aligned.raster, dpi: p.original.dpi })))
+ * ```
+ *
+ * PDF pages are copied, never re-rendered. A JPEG goes in as its own bytes and
+ * a PNG's pixels losslessly; everything else - TIFF (every page), WebP, HEIF,
+ * AVIF, rasters - is decoded and encoded once, losslessly by default. A single
+ * PDF on its own comes back byte for byte.
+ *
+ * PDF writing is `@cantoo/pdf-lib`, the maintained fork of pdf-lib: pure
+ * JavaScript, nothing to install on the host. Image decoding is `@scanmate/ink`.
+ */
+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 type { ImageWithResolution, MergeSource, SourceKind } from './source-reading/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';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,4 @@
+/** Page size and image position for each image page. */
+export { MIN_RECORDED_DPI, PAPER, placeImage, resolveDpi } from './page-placement.policy.js';
+export type { PageSize, Placement } from './page-placement.policy.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/page-placement/page-placement.policy.d.ts

@@ -0,0 +1,44 @@
+/**
+ * How big an image's page is, and where on it the image goes.
+ *
+ * By default a page is the image at its resolution: a 2480 x 3508 scan at 300
+ * dpi becomes an A4 page, and a downstream reader that divides pixels by page
+ * inches gets the scan's real resolution back - which is exactly what
+ * `@scanmate/extract` does to decide how to render. A fixed paper size instead
+ * fits the image inside it, centred, turning the page landscape for a landscape
+ * image.
+ *
+ * Resolution comes from, in order: what the caller says; what the file records,
+ * if it is at least {@link MIN_RECORDED_DPI}; the `imageDpi` fallback. The floor
+ * is there because 72 and 96 are what cameras and editors write when they know
+ * nothing - a phone photo "at 72 dpi" would make a page over a metre tall.
+ */
+/** `'image'`: the image's own size at its resolution. Otherwise a paper size, or `{ width, height }` in points. */
+export type PageSize = 'image' | 'a4' | 'letter' | {
+    width: number;
+    height: number;
+};
+export declare const PAPER: {
+    readonly a4: {
+        readonly width: 595.28;
+        readonly height: 841.89;
+    };
+    readonly letter: {
+        readonly width: 612;
+        readonly height: 792;
+    };
+};
+/** Recorded densities below this are software defaults, not a scan's resolution. */
+export declare const MIN_RECORDED_DPI = 100;
+/** In PDF points, from the page's bottom-left corner - PDF's own frame. */
+export interface Placement {
+    pageWidth: number;
+    pageHeight: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export declare function resolveDpi(given: number | null | undefined, recorded: number | null, fallback: number): number;
+export declare function placeImage(pixelWidth: number, pixelHeight: number, dpi: number, pageSize: PageSize, margin?: number): Placement;
+//# sourceMappingURL=page-placement.policy.d.ts.map

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

@@ -0,0 +1,6 @@
+/** Turning each thing handed to merge - a path, bytes, pixels - into a PDF, an image or a raster. */
+export { MergeSourceError } from './merge-source.contract.js';
+export type { ImageWithResolution, MergeSource, SourceKind } from './merge-source.contract.js';
+export { isPdf, readSource } from './read-source.use-case.js';
+export type { ResolvedSource } from './read-source.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/source-reading/merge-source.contract.d.ts

@@ -0,0 +1,32 @@
+import type { Raster } from '@scanmate/ink';
+/**
+ * Anything that can become pages of the merged PDF.
+ *
+ * - a path (`string` or file `URL`) or bytes (`Uint8Array`, `ArrayBuffer`) -
+ *   a PDF or any image libvips reads, told apart by content, not by name;
+ * - a decoded {@link Raster};
+ * - an image with its resolution, `{ raster, dpi }` - which is what every
+ *   `PageImage` in the pipeline is, so an aligned or enhanced page goes in as it
+ *   is. When it also carries its encoded `image`, those bytes are embedded
+ *   rather than encoding the raster again.
+ */
+export type MergeSource = string | URL | Uint8Array | ArrayBuffer | Raster | ImageWithResolution;
+export interface ImageWithResolution {
+    raster: Raster;
+    /** Pixels per inch, which sets the page size; `null` or absent when unknown. */
+    dpi?: number | null;
+    /** The raster already encoded - PNG or JPEG bytes are embedded as they are. */
+    image?: Uint8Array | null;
+}
+/** What a source turned out to be. */
+export type SourceKind = 'pdf' | 'image' | 'raster';
+/** A source that could not be used, and which one it was. */
+export declare class MergeSourceError extends Error {
+    readonly index: number;
+    /**
+     * @param index - Zero-based position of the source in the list given.
+     * @param message - What is wrong with it.
+     */
+    constructor(index: number, message: string);
+}
+//# sourceMappingURL=merge-source.contract.d.ts.map

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

@@ -0,0 +1,23 @@
+import type { Raster } from '@scanmate/ink';
+import type { MergeSource } from './merge-source.contract.js';
+/**
+ * A source resolved to what merging needs: its bytes and what they are, or its
+ * pixels. Content decides, never the file name - a scanner that saves a PDF as
+ * `scan.jpg` still gives a PDF.
+ */
+export type ResolvedSource = {
+    kind: 'pdf';
+    bytes: Uint8Array;
+} | {
+    kind: 'image';
+    bytes: Uint8Array;
+    dpi: null;
+} | {
+    kind: 'raster';
+    raster: Raster;
+    dpi: number | null;
+    bytes: Uint8Array | null;
+};
+export declare function readSource(source: MergeSource, index: number): Promise<ResolvedSource>;
+export declare function isPdf(bytes: Uint8Array): boolean;
+//# sourceMappingURL=read-source.use-case.d.ts.map

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@scanmate/merge",
+  "version": "0.0.2",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/russoedu/scanmate.git",
+    "directory": "packages/merge"
+  },
+  "homepage": "https://github.com/russoedu/scanmate/tree/main/packages/merge#readme",
+  "bugs": {
+    "url": "https://github.com/russoedu/scanmate/issues"
+  },
+  "keywords": [
+    "pdf",
+    "merge",
+    "images",
+    "tiff",
+    "scan",
+    "document"
+  ],
+  "type": "module",
+  "main": "./dist/index.esm.js",
+  "module": "./dist/index.esm.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/index.esm.js",
+      "default": "./dist/index.esm.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo",
+    "!**/*.d.ts.map",
+    "!**/*.js.map"
+  ],
+  "dependencies": {
+    "@cantoo/pdf-lib": "^2.11.1",
+    "@scanmate/ink": "^0.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "sharp": "^0.35.4"
+  }
+}