pdf-probe 0.0.0-stage → 0.1.0

package/LICENSE-APACHE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/LICENSE-MIT

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 The pdf-probe authors
+
+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

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# pdf-probe
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+How many pages does an untrusted PDF have, and how big is each page? A small reader that answers only those two questions, and **fails closed**: a file it cannot read with confidence is reported as a failure, never guessed at. It does not render, extract text or decode images.
+
+> **Status: version 0.1, pre-1.0.** The parser matches pdf.js on pdf.js's own 987 test PDFs (983 identical, 4 intended differences that are all refusals, 0 different answers), but it is young, has not been independently audited, and the API may change. See the [project README](https://github.com/polybot-platform/pdf-probe#readme) for the evidence and what is not done.
+
+```js
+import { createProbe } from 'pdf-probe'
+
+const probe = await createProbe() // once: loading is the expensive part
+const result = probe.check(bytes, { maxPages: 200 }) // bytes: a Uint8Array or Buffer
+
+switch (result.status) {
+  case 'ok': // result.pages, result.sizes: [[width, height], ...] in points (1/72 inch)
+  case 'tooManyPages': // result.pages
+  case 'empty': // well-formed, no pages
+  case 'unparseable': // result.reason: damaged, unsupported or password-protected
+  case 'limitExceeded': // result.limit: 'inputBytes', 'work', 'objects', 'xrefSections' or 'decompressed'
+}
+```
+
+A damaged or password-protected PDF is a **result**, not an exception, and so is a limit. `check` throws only for a bad call (a wrong argument type, an option out of range, a closed probe).
+
+## Engines
+
+Two engines give the same answers, byte for byte, on the whole test corpus.
+
+| | Where | Memory in Bun (measured locally) |
+|---|---|---|
+| `native` | Bun only, through `bun:ffi` | about +3 MB at idle |
+| `wasm` | Bun, Node 20+, Deno, browsers, workers (no browser run yet) | about +15 MB at idle in Bun |
+
+`createProbe()` uses `engine: 'auto'`: the native library under Bun when one is found, WebAssembly otherwise. **This package ships WebAssembly only**; the native library is built from the [repository](https://github.com/polybot-platform/pdf-probe) and passed in by path. Ask for one with `{ engine: 'native' }` or `{ engine: 'wasm' }`; `native` throws a clear error if it cannot be loaded.
+
+**No native library is included.** Build one with `cargo build --release -p pdf-probe-ffi` and give its path with the `nativeLibrary` option or `PDF_PROBE_NATIVE_LIBRARY`; the package also looks in `native/<platform>-<arch>/` next to itself. Anywhere without one, `auto` uses WebAssembly.
+
+## `bun build --compile`
+
+A compiled binary has no `node_modules` on disk, so embed the engine files and pass their paths:
+
+```js
+import { createProbe } from 'pdf-probe'
+import wasmFile from 'pdf-probe/pdf_probe.wasm' with { type: 'file' }
+const probe = await createProbe({ wasm: wasmFile })
+```
+
+This was tried with a binary built from the installed package and run from another directory. A native library you built yourself can be embedded the same way and passed as `nativeLibrary`.
+
+## Things to know
+
+- **Passwords.** Only an empty user password is tried (RC4, AES-128, AES-256). A file that needs a password is `unparseable`.
+- **Page cap.** `maxPages` (default 10,000, at most 1,000,000) bounds the work and the answer. More pages than that is `tooManyPages`.
+- **Input size.** `maxInputBytes` (default 10 MiB, at most 4,294,967,295) is checked first: a larger input is `limitExceeded` (`inputBytes`) before anything is parsed.
+- **Work budget.** `maxWork` (default about 1.07 billion units, roughly a second) bounds the total work of one call; running out is `limitExceeded` (`work`). A unit is about a nanosecond of work, but the count is deterministic: the same input costs the same everywhere. It catches work that is large only in total, such as one object re-parsed for every page (a 1 MB file can cost minutes without it). It is rounded up to a multiple of one million.
+- **Other limits.** Object count, cross-reference chain length and decompressed size are bounded inside the library with fixed defaults; hitting one is `limitExceeded` naming it. They are not options.
+- **A panic** cannot take the host down: the native library catches it at its boundary and reports `panic`; the WebAssembly engine sees a trap, discards the instance and reports `panic`. None has been found by fuzzing so far.
+- **WebAssembly memory only grows.** The WebAssembly engine replaces its instance when its memory passes `recycleAboveBytes` (default 32 MiB).
+- **Page sizes** are the effective size: MediaBox intersected with CropBox, with `/Rotate` and `/UserUnit` applied. A size limit is your policy, not the library's.
+
+## Licence
+
+MIT OR Apache-2.0.

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+export type PageSize = [width: number, height: number]
+
+export type ProbeResult =
+  | { status: 'ok'; pages: number; sizes: PageSize[] }
+  | { status: 'unparseable'; reason: string }
+  | { status: 'empty' }
+  | { status: 'tooManyPages'; pages: number }
+  | { status: 'limitExceeded'; limit: LimitName }
+  | { status: 'panic'; reason: string }
+
+/** Which limit was hit. */
+export type LimitName = 'inputBytes' | 'work' | 'objects' | 'xrefSections' | 'decompressed'
+
+/** `auto` uses the native library under Bun when one is found for this platform, and WebAssembly otherwise. */
+export type Engine = 'auto' | 'native' | 'wasm'
+
+export interface CreateOptions {
+  engine?: Engine
+  /** A path to the native shared library. Default: `PDF_PROBE_NATIVE_LIBRARY`, then the package's own `native/`. */
+  nativeLibrary?: string
+  /** The WebAssembly module: bytes, a compiled module, a URL or a path. Default: the file shipped in the package. */
+  wasm?: BufferSource | WebAssembly.Module | URL | string
+  /** WebAssembly memory only grows; above this many bytes the instance is replaced. Default 32 MiB. */
+  recycleAboveBytes?: number
+}
+
+export interface CheckOptions {
+  /** More pages than this is reported as `tooManyPages`. At most 1,000,000. Default 10,000. */
+  maxPages?: number
+  /**
+   * The largest input accepted, in bytes. A larger one is `limitExceeded` (`inputBytes`) before anything is
+   * parsed. At most 4,294,967,295. Default 10 MiB.
+   */
+  maxInputBytes?: number
+  /**
+   * A budget of work units for the call; running out is `limitExceeded` (`work`). A unit is roughly a
+   * nanosecond of work on a modern core, and the count is the same on every machine, so the same input always
+   * costs the same. Rounded up to a multiple of one million. Default about 1.07 billion (roughly a second).
+   * It catches work that is large only in total, such as one object re-parsed for every page.
+   */
+  maxWork?: number
+}
+
+export interface Probe {
+  /** The engine in use. */
+  readonly engine: 'native' | 'wasm'
+  /**
+   * Reads the page count and each page's size, in points. A damaged, encrypted or otherwise unreadable PDF is
+   * a result (`unparseable`, `empty`, `tooManyPages`, `limitExceeded`), not an exception. It throws only for
+   * a bad call.
+   */
+  check(pdf: Uint8Array | ArrayBuffer, options?: CheckOptions): ProbeResult
+  /** Releases the native library. A probe cannot be used afterwards. */
+  close(): void
+}
+
+/** Creates a probe. Do it once and reuse it: loading is the expensive part, and checks are fast. */
+export function createProbe(options?: CreateOptions): Promise<Probe>

package/dist/index.js

@@ -0,0 +1,231 @@
+// src/index.ts
+import { fileURLToPath } from "node:url";
+
+// ../bindings/result.ts
+var ABI_VERSION = 2;
+var HEADER = 16;
+var STATUS = ["ok", "unparseable", "empty", "tooManyPages", "panic", "limitExceeded"];
+function bufferSizeFor(maxPages) {
+  return HEADER + 16 * Math.min(maxPages, 1e4) + 256;
+}
+function decodeResult(buf, length) {
+  const view = new DataView(buf.buffer, buf.byteOffset, length);
+  const code = view.getUint32(0, true);
+  const status = STATUS[code];
+  const pages = view.getUint32(4, true);
+  const count = view.getUint32(8, true);
+  const reasonLength = view.getUint32(12, true);
+  const reason = () => new TextDecoder().decode(buf.subarray(HEADER + 16 * count, HEADER + 16 * count + reasonLength));
+  switch (status) {
+    case "ok": {
+      const sizes = [];
+      for (let i = 0;i < count; i++) {
+        sizes.push([view.getFloat64(HEADER + 16 * i, true), view.getFloat64(HEADER + 16 * i + 8, true)]);
+      }
+      return { status, pages, sizes };
+    }
+    case "unparseable":
+    case "panic":
+      return { status, reason: reason() };
+    case "tooManyPages":
+      return { status, pages };
+    case "limitExceeded":
+      return { status, limit: reason() };
+    case "empty":
+      return { status };
+    default:
+      throw new Error(`unknown status ${code}`);
+  }
+}
+
+// ../bindings/bun.ts
+async function libraryFileName() {
+  const { suffix } = await import("bun:ffi");
+  return `${suffix === "dll" ? "" : "lib"}pdf_probe_ffi.${suffix}`;
+}
+async function defaultLibraryPath() {
+  return new URL(`../target/release/${await libraryFileName()}`, import.meta.url).pathname;
+}
+async function loadPdfProbe(path) {
+  const { dlopen, FFIType, ptr } = await import("bun:ffi");
+  const lib = dlopen(path ?? await defaultLibraryPath(), {
+    pdf_probe_abi_version: { args: [], returns: FFIType.u32 },
+    pdf_probe_check: {
+      args: [FFIType.ptr, FFIType.u64, FFIType.u32, FFIType.u32, FFIType.u32, FFIType.ptr, FFIType.u64],
+      returns: FFIType.i32
+    }
+  });
+  const version = lib.symbols.pdf_probe_abi_version();
+  if (version !== ABI_VERSION)
+    throw new Error(`pdf-probe ABI ${version}, expected ${ABI_VERSION}`);
+  let out = new Uint8Array(HEADER + 256);
+  function check(bytes, maxPages, maxInputBytes = 0, maxWorkMillions = 0) {
+    const want = bufferSizeFor(maxPages);
+    if (out.length < want)
+      out = new Uint8Array(want);
+    const call = () => lib.symbols.pdf_probe_check(bytes.length ? ptr(bytes) : null, bytes.length, maxPages, maxInputBytes, maxWorkMillions, ptr(out), out.length);
+    let needed = call();
+    if (needed > out.length) {
+      out = new Uint8Array(needed);
+      needed = call();
+    }
+    if (needed < 0)
+      throw new Error(`pdf_probe_check failed with ${needed}`);
+    return decodeResult(out, needed);
+  }
+  return { check, close: () => lib.close() };
+}
+
+// ../bindings/wasm.ts
+function loadPdfProbeWasm(wasm, options = {}) {
+  const recycleAboveBytes = options.recycleAboveBytes ?? 32 * 1024 * 1024;
+  const module = wasm instanceof WebAssembly.Module ? wasm : new WebAssembly.Module(wasm);
+  const instantiate = () => {
+    const x = new WebAssembly.Instance(module, {}).exports;
+    if (x.pdf_probe_abi_version() !== ABI_VERSION)
+      throw new Error("pdf-probe wasm ABI mismatch");
+    return x;
+  };
+  let x = instantiate();
+  let recycles = 0;
+  function check(bytes, maxPages, maxInputBytes = 0, maxWorkMillions = 0) {
+    let outCap = bufferSizeFor(maxPages);
+    let inPtr = 0;
+    let outPtr = 0;
+    try {
+      inPtr = x.pdf_probe_alloc(bytes.length);
+      new Uint8Array(x.memory.buffer, inPtr, bytes.length).set(bytes);
+      outPtr = x.pdf_probe_alloc(outCap);
+      let needed = x.pdf_probe_check(inPtr, bytes.length, maxPages, maxInputBytes, maxWorkMillions, outPtr, outCap);
+      if (needed > outCap) {
+        x.pdf_probe_free(outPtr, outCap);
+        outCap = needed;
+        outPtr = x.pdf_probe_alloc(outCap);
+        needed = x.pdf_probe_check(inPtr, bytes.length, maxPages, maxInputBytes, maxWorkMillions, outPtr, outCap);
+      }
+      if (needed < 0)
+        throw new Error(`pdf_probe_check failed with ${needed}`);
+      const result = decodeResult(new Uint8Array(x.memory.buffer, outPtr, needed).slice(), needed);
+      x.pdf_probe_free(outPtr, outCap);
+      x.pdf_probe_free(inPtr, bytes.length);
+      if (x.memory.buffer.byteLength > recycleAboveBytes) {
+        x = instantiate();
+        recycles++;
+      }
+      return result;
+    } catch (error) {
+      if (error instanceof WebAssembly.RuntimeError) {
+        x = instantiate();
+        return { status: "panic", reason: error.message };
+      }
+      throw error;
+    }
+  }
+  return {
+    check,
+    memoryBytes: () => x.memory.buffer.byteLength,
+    recycleCount: () => recycles,
+    exports: () => x
+  };
+}
+
+// src/index.ts
+var DEFAULT_MAX_PAGES = 1e4;
+var MAX_PAGES_CEILING = 1e6;
+var U32_MAX = 4294967295;
+var isBun = () => typeof globalThis.Bun !== "undefined";
+var isNodeLike = () => typeof process !== "undefined" && typeof process.versions?.node === "string";
+function prepare(pdf, options) {
+  const bytes = pdf instanceof Uint8Array ? pdf : pdf instanceof ArrayBuffer ? new Uint8Array(pdf) : undefined;
+  if (!bytes)
+    throw new TypeError("pdf must be a Uint8Array (a Buffer is one) or an ArrayBuffer");
+  const maxPages = options?.maxPages ?? DEFAULT_MAX_PAGES;
+  if (!Number.isInteger(maxPages) || maxPages < 0 || maxPages > MAX_PAGES_CEILING) {
+    throw new RangeError(`maxPages must be an integer from 0 to ${MAX_PAGES_CEILING}`);
+  }
+  const maxInputBytes = options?.maxInputBytes ?? 0;
+  if (!Number.isInteger(maxInputBytes) || maxInputBytes < 0 || maxInputBytes > U32_MAX || options?.maxInputBytes !== undefined && maxInputBytes < 1) {
+    throw new RangeError(`maxInputBytes must be an integer from 1 to ${U32_MAX}`);
+  }
+  const maxWork = options?.maxWork;
+  if (maxWork !== undefined && (!Number.isInteger(maxWork) || maxWork < 1 || Math.ceil(maxWork / 1e6) > U32_MAX)) {
+    throw new RangeError("maxWork must be an integer of at least 1 (and at most about 4.29e15)");
+  }
+  return [bytes, maxPages, maxInputBytes, maxWork === undefined ? 0 : Math.ceil(maxWork / 1e6)];
+}
+function wrap(engine, run, release) {
+  let closed = false;
+  return {
+    engine,
+    check(pdf, options) {
+      if (closed)
+        throw new Error("this probe is closed");
+      return run(...prepare(pdf, options));
+    },
+    close() {
+      if (!closed)
+        release();
+      closed = true;
+    }
+  };
+}
+async function findNativeLibrary(explicit) {
+  const bun = globalThis.Bun;
+  const candidates = [
+    explicit,
+    process.env.PDF_PROBE_NATIVE_LIBRARY,
+    fileURLToPath(new URL(`../native/${process.platform}-${process.arch}/${await libraryFileName()}`, import.meta.url))
+  ];
+  for (const path of candidates) {
+    if (path && await bun?.file(path).exists())
+      return path;
+    if (path && path === explicit)
+      return path;
+  }
+  return;
+}
+async function wasmSource(source) {
+  if (source instanceof WebAssembly.Module)
+    return source;
+  if (source && typeof source === "object" && !(source instanceof URL))
+    return source;
+  const url = source instanceof URL ? source : typeof source === "string" ? /^[a-z][a-z0-9+.-]*:/i.test(source) && !/^[a-z]:[\\/]/i.test(source) ? new URL(source) : undefined : new URL("./pdf_probe.wasm", import.meta.url);
+  if (isNodeLike() && (url === undefined || url.protocol === "file:")) {
+    const { readFile } = await import("node:fs/promises");
+    return await readFile(url ? fileURLToPath(url) : source);
+  }
+  const response = await fetch(url);
+  if (!response.ok)
+    throw new Error(`could not load the WebAssembly module: ${response.status} ${response.statusText}`);
+  return await response.arrayBuffer();
+}
+async function createProbe(options = {}) {
+  const engine = options.engine ?? "auto";
+  if (engine !== "auto" && engine !== "native" && engine !== "wasm") {
+    throw new TypeError(`engine must be 'auto', 'native' or 'wasm', not ${String(engine)}`);
+  }
+  if (engine !== "wasm") {
+    if (!isBun()) {
+      if (engine === "native")
+        throw new Error("the 'native' engine needs Bun (it loads the library with bun:ffi)");
+    } else {
+      const path = await findNativeLibrary(options.nativeLibrary);
+      if (path) {
+        try {
+          const lib = await loadPdfProbe(path);
+          return wrap("native", lib.check, lib.close);
+        } catch (cause) {
+          if (engine === "native")
+            throw new Error(`could not load the native library at ${path}`, { cause });
+        }
+      } else if (engine === "native") {
+        throw new Error(`no native library for ${process.platform}-${process.arch}: set nativeLibrary or PDF_PROBE_NATIVE_LIBRARY`);
+      }
+    }
+  }
+  const wasm = loadPdfProbeWasm(await wasmSource(options.wasm), { recycleAboveBytes: options.recycleAboveBytes });
+  return wrap("wasm", wasm.check, () => {});
+}
+export {
+  createProbe
+};

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "pdf-probe",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A small, fail-closed reader that answers two questions about an untrusted PDF: how many pages, and how big is each page? WebAssembly, for Node, Bun and browsers.",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/polybot-platform/pdf-probe.git"
+  },
+  "keywords": [
+    "pdf",
+    "page-count",
+    "page-size",
+    "wasm",
+    "ffi",
+    "untrusted-input"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./pdf_probe.wasm": "./dist/pdf_probe.wasm",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE-MIT",
+    "LICENSE-APACHE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "bun run build.ts"
+  },
+  "homepage": "https://github.com/polybot-platform/pdf-probe#readme",
+  "bugs": {
+    "url": "https://github.com/polybot-platform/pdf-probe/issues"
+  }
+}