chore: polish — tooling, rustdoc, CI, changelog (#71)

* chore: add rust-toolchain and justfile for consistent dev tooling

rust-toolchain.toml pins every contributor and CI invocation to the
same stable toolchain with rustfmt, clippy, and the
wasm32-unknown-unknown target. Previously CI used
dtolnay/rust-toolchain@stable while contributors installed their own;
minor version drift between them could produce clippy lint
discrepancies at merge time.

justfile captures the common build / test / lint commands documented
in CLAUDE.md as executable recipes. `just` (no args) prints the full
list, and the common flows (build, test, check, fmt, clean-all) are
one step each so local iteration matches the pre-commit chain.

* chore(async): stop force-enabling signatures/validation on core

paperjam-async currently only reaches into paperjam_core::render, yet
its manifest force-enabled the signatures and validation features on
paperjam-core for every consumer. Downstream crates that need those
features (paperjam-py does, explicitly) keep working unchanged;
lightweight async consumers no longer drag in the x509-parser / cms /
rsa / p256 / sha1 / pkcs8 / spki / ureq / rustls / roxmltree tree.

* docs: crate-level rustdoc across the workspace

Every library crate now has a `//!` summary describing its scope,
its entry points, and how it fits into the broader paperjam
ecosystem. Uniform style: plain prose, no intra-doc links in
crate-level summaries (simpler to maintain, no rustdoc link
warnings to manage).

Also fixes two pre-existing rustdoc warnings uncovered along the
way: an `[OPTIONAL]` literal in signature/tsa.rs that rustdoc was
parsing as an intra-doc link, and a bare URL in model/annotations.rs
flagged for auto-linking. The PyO3 `PyDocument` and `PyPage` classes
get class-level docs that clarify they are the native layer beneath
the pure-Python `paperjam.Document` / `paperjam.Page` wrappers.

After this commit `cargo doc --workspace --no-deps` produces zero
warnings.

* chore(ci): run docs workflow on PRs and install wasm-opt

The docs workflow previously fired only on pushes to main, so docs
regressions (broken wasm builds, Docusaurus compile errors, bad
links) were invisible until after merge. Now PRs with matching
paths run the full build (without deploying) so problems surface in
the PR check run.

Also installs binaryen, whose wasm-opt binary wasm-pack invokes
automatically when present on PATH. Release-mode WASM bundles
shrink by 20-30% with no code changes.

Concurrency group is keyed on ref so PR builds and deploy builds
don't cancel each other; the deploy job is skipped on pull_request
events to preserve production pages behaviour.

* docs(changelog): record [Unreleased] entries since 0.2.0

Document the audit-driven work that has landed on main but hasn't
been cut into a release yet: the ZIP-entry and MCP sandbox security
hardening (#69), the panic-surface cleanup in the PDF engine (#70),
the form-bindings stub sync and metadata / docs refresh (#68), plus
the tooling, docs, and paperjam-async feature adjustments from this
polish branch.

* fix(ci): install pinned binaryen release instead of apt binaryen

Ubuntu's apt-shipped binaryen is ~v108, which predates the default
enablement of bulk-memory and sign-extension instructions in rustc
output. The result is wasm-pack invoking /usr/bin/wasm-opt on a
valid modern wasm module and wasm-opt rejecting it with
"[wasm-validator error] Bulk memory operation (bulk memory is
disabled)" — observed on the PR #71 run.

Download and install a pinned binaryen release tarball from the
upstream GitHub releases page. version_119 is known-good against
the current rustc and supports all default features. Future bumps
change one env var.

* chore(ci): verify binaryen tarball checksum and cache across runs

Harden the binaryen install step that landed in the previous commit:

- SHA256-pin the downloaded tarball (value verified against a local
  download of version_119). Guards against upstream tampering or an
  accidental silent swap.
- Split the version-check into a dedicated Verify step so the log
  shows the installed wasm-opt version unambiguously.
- Wrap the install in actions/cache keyed on the pinned version so
  subsequent runs skip the download. Saves ~3-5s per run.

* fix(wasm): tell wasm-pack to enable bulk-memory and sign-ext in wasm-opt

rustc 1.82+ emits bulk-memory and sign-extension instructions in its
default wasm output. wasm-pack's baseline wasm-opt invocation ("-O")
does not pass --enable-bulk-memory / --enable-sign-ext, so even a
modern binaryen rejects the module with "Bulk memory operations
require bulk memory [--enable-bulk-memory]" during validation.

Configure the flags in paperjam-wasm's Cargo.toml metadata block so
wasm-pack invokes wasm-opt with the right feature set. This is what
was blocking CI #71 even after installing a modern binaryen.

* fix(wasm): extend wasm-opt feature set to the full rustc default list

Rust 1.87 / LLVM 20 enabled bulk-memory and nontrapping-fptoint in
the default wasm32-unknown-unknown feature set, alongside the
previously-defaulted multivalue, mutable-globals, reference-types,
and sign-ext. wasm-pack's baseline "-O" invocation of wasm-opt does
not pass any of them, so the optimiser rejects a perfectly valid
rustc-emitted module.

The previous commit only enabled bulk-memory and sign-ext, which
exposed a follow-on validator error on `i32.trunc_sat_f64_s`
(nontrapping-fptoint). Rather than re-play whack-a-mole for each
feature, pass the full list that matches the rustc default set
documented in the wasm32-unknown-unknown platform-support page.

Ref: https://doc.rust-lang.org/rustc/platform-support/wasm32-unknown-unknown.html

Author: pratyush618

.github/workflows/docs.yml

@@ -7,6 +7,12 @@ on:
       - "docs-site/**"
       - "crates/paperjam-wasm/**"
       - ".github/workflows/docs.yml"
+  pull_request:
+    branches: [main]
+    paths:
+      - "docs-site/**"
+      - "crates/paperjam-wasm/**"
+      - ".github/workflows/docs.yml"
   workflow_dispatch:
 
 permissions:
@@ -15,7 +21,7 @@ permissions:
   id-token: write
 
 concurrency:
-  group: pages
+  group: pages-${{ github.ref }}
   cancel-in-progress: false
 
 jobs:
@@ -35,6 +41,38 @@ jobs:
       - name: Install wasm-pack
         run: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
 
+      # wasm-pack invokes wasm-opt automatically when it is on PATH.
+      # Ubuntu's apt-packaged binaryen (~v108) is too old to validate
+      # modern rustc output — rustc 1.95+ emits bulk-memory and
+      # sign-extension instructions by default, which that wasm-opt
+      # rejects. We install a pinned upstream release, verify its
+      # SHA256, and cache it across runs.
+      - name: Cache binaryen
+        id: cache-binaryen
+        uses: actions/cache@v4
+        env:
+          BINARYEN_VERSION: version_119
+        with:
+          path: /usr/local/bin/wasm-opt
+          key: binaryen-${{ env.BINARYEN_VERSION }}-x86_64-linux
+
+      - name: Install binaryen (wasm-opt)
+        if: steps.cache-binaryen.outputs.cache-hit != 'true'
+        env:
+          BINARYEN_VERSION: version_119
+          BINARYEN_SHA256: 716bcf9f5f36a6f466239fbb09a925eeaf54c46411ccefac979ec649e7c06d2d
+        run: |
+          set -euo pipefail
+          tarball="binaryen-${BINARYEN_VERSION}-x86_64-linux.tar.gz"
+          url="https://github.com/WebAssembly/binaryen/releases/download/${BINARYEN_VERSION}/${tarball}"
+          curl -fsSL "$url" -o "/tmp/${tarball}"
+          echo "${BINARYEN_SHA256}  /tmp/${tarball}" | sha256sum --check --strict
+          tar -xzf "/tmp/${tarball}" -C /tmp
+          sudo install -m 0755 "/tmp/binaryen-${BINARYEN_VERSION}/bin/wasm-opt" /usr/local/bin/wasm-opt
+
+      - name: Verify wasm-opt
+        run: wasm-opt --version
+
       - name: Build WASM
         run: wasm-pack build crates/paperjam-wasm --target web --release --out-dir ../../docs-site/static/wasm
 
@@ -52,12 +90,14 @@ jobs:
         run: cd docs-site && npm run build
 
       - name: Upload Pages artifact
+        if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
         uses: actions/upload-pages-artifact@v5
         with:
           path: docs-site/build
 
   deploy:
     needs: build
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
     environment:
       name: github-pages

CHANGELOG.md

@@ -7,6 +7,64 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### Security
+
+- Bound ZIP entry reads in EPUB, PPTX, and DOCX parsers. A crafted archive
+  declaring a tiny compressed size could previously expand to multi-GB on
+  decompression; entries are now rejected when the declared or observed
+  decompressed size exceeds a per-entry cap.
+- Cap `Vec::with_capacity` preallocations in XLSX sheet parsing and PPTX
+  slide parsing at reasonable ceilings so attacker-controlled counts can
+  no longer trigger large allocations up front.
+- `paperjam-mcp`: resolved paths are now sandboxed to the configured
+  working directory by default. Absolute paths and `..` traversal that
+  escape the working dir are rejected with a structured error. Operators
+  can opt out with `--allow-absolute-paths` (or
+  `ServerConfig::allow_absolute_paths`).
+
+### Fixed
+
+- Replace panic-prone `f64::partial_cmp(..).unwrap()` in table detection
+  (`table/{grid,lattice,stream}.rs`) with `total_cmp`, so malformed PDFs
+  producing NaN coordinates no longer crash the parser.
+- Replace `get_object_mut().unwrap()` / `as_dict_mut().unwrap()` /
+  `from_utf8().unwrap()` across the stamp, watermark, bookmarks, and
+  PDF/UA validation modules with structured `PdfError` returns. Malformed
+  PDFs now surface typed errors instead of panicking the process.
+- Stub drift: add `modify_form_field`, `add_form_field`, and the
+  `fill_form.generate_appearances` parameter to `_paperjam.pyi` so mypy
+  sees the full PyO3 surface.
+
+### Added
+
+- Crate-level `//!` rustdoc summaries on every workspace crate.
+- `rust-toolchain.toml` pins the contributor toolchain to stable with
+  `rustfmt`, `clippy`, and the `wasm32-unknown-unknown` target.
+- `justfile` with shortcuts for common build / test / lint tasks.
+- `[profile.release]` with thin LTO, `codegen-units = 1`, and symbol
+  strip. Adds a `release-with-debug` profile for profiling.
+
+### Changed
+
+- `paperjam-async` no longer force-enables `signatures` and `validation`
+  on `paperjam-core`. Consumers that need them (e.g. `paperjam-py`)
+  continue to enable them explicitly; lightweight async users no longer
+  drag in the full signing / validation stack.
+- Docs site CI now builds on pull requests (without deploying) so docs
+  regressions are caught pre-merge. Binaryen's `wasm-opt` is installed
+  so release WASM bundles are size-optimized.
+
+### Docs
+
+- README: CLI examples now use the correct `pj` binary name and accurate
+  flags; removed the nonexistent `extract tables --format csv` flag.
+- `docs-site/docs/getting-started/installation.md`: replace leftover
+  Sphinx build instructions with the Docusaurus workflow, fix the
+  clone org, expand the feature-flag table.
+- `pyproject.toml`: fill in multi-format description, `readme`,
+  `project.urls`, and extra classifiers/keywords so the PyPI page is
+  populated. Drop the stale Sphinx `[docs]` extra.
+
 ## [0.2.0] — 2026-04-04
 
 ### Added

crates/paperjam-async/Cargo.toml

@@ -6,7 +6,12 @@ license.workspace = true
 description = "Async wrappers for paperjam operations via tokio::spawn_blocking"
 
 [dependencies]
-paperjam-core = { path = "../paperjam-core", features = ["render", "signatures", "validation"] }
+# paperjam-async currently only uses `paperjam_core::render`, so we enable
+# that feature here but leave `signatures`/`validation` to be opted in by
+# the downstream crate that actually needs them (paperjam-py does this
+# explicitly). Keeps the async surface lightweight for callers that only
+# want basic document operations.
+paperjam-core = { path = "../paperjam-core", features = ["render"] }
 paperjam-model = { path = "../paperjam-model" }
 paperjam-convert = { path = "../paperjam-convert", optional = true }
 tokio = { workspace = true }

crates/paperjam-async/src/lib.rs

@@ -1,3 +1,11 @@
+//! Tokio-native async wrappers around paperjam's blocking operations.
+//!
+//! Each heavy operation (`open`, `save`, `render`, `to_markdown`,
+//! `merge`, `redact_text`, ...) is re-exposed as an `async fn` that runs
+//! the blocking work on `tokio::spawn_blocking`. This is what powers the
+//! `paperjam.aopen` / `paperjam.arender_*` / `paperjam.amerge` helpers on
+//! the Python side.
+
 pub mod document;
 pub mod generic;
 pub mod page;

crates/paperjam-convert/src/lib.rs

@@ -1,3 +1,11 @@
+//! Cross-format document conversion.
+//!
+//! Orchestrates conversion between every pair of formats supported by the
+//! paperjam workspace (PDF, DOCX, XLSX, PPTX, HTML, EPUB, Markdown). Each
+//! format crate is an optional dependency so consumers only pay for the
+//! formats they want; features named after the source and target crates
+//! gate those conversions in and out.
+
 pub mod convert;
 pub mod detect;
 pub mod error;

crates/paperjam-core/src/lib.rs

@@ -1,3 +1,23 @@
+//! Pure-Rust PDF engine: parsing, text and table extraction, page
+//! manipulation, form fields, digital signatures, encryption, rendering,
+//! and PDF/A / PDF/UA validation.
+//!
+//! `paperjam-core` is the PDF-specific implementation behind the
+//! `paperjam` library. Non-PDF formats live in sibling crates
+//! (`paperjam-docx`, `paperjam-xlsx`, `paperjam-pptx`, `paperjam-html`,
+//! `paperjam-epub`); cross-format operations go through `paperjam-convert`.
+//!
+//! Heavy optional pieces are feature-gated:
+//!
+//! | Feature      | Enables                                                  |
+//! |--------------|----------------------------------------------------------|
+//! | `render`     | page-to-image rasterisation via pdfium                   |
+//! | `signatures` | sign / verify / inspect digital signatures               |
+//! | `ltv`        | long-term validation (TSA, OCSP, CRL embedding)          |
+//! | `validation` | PDF/A and PDF/UA conformance checks                      |
+//! | `parallel`   | rayon-based parallel processing (default on)             |
+//! | `mmap`       | memory-mapped file access for large documents            |
+
 pub mod annotations;
 pub mod bookmarks;
 #[cfg(feature = "validation")]

crates/paperjam-core/src/signature/tsa.rs

@@ -54,7 +54,7 @@ pub fn build_timestamp_request(signature_value: &[u8]) -> Result<Vec<u8>> {
 
 /// Parse an RFC 3161 timestamp response and extract the TimeStampToken.
 ///
-/// The response is: SEQUENCE { status PKIStatusInfo, timeStampToken [OPTIONAL] }
+/// The response is: `SEQUENCE { status PKIStatusInfo, timeStampToken [OPTIONAL] }`
 /// We check the status integer and return the token bytes.
 pub fn parse_timestamp_response(resp_bytes: &[u8]) -> Result<Vec<u8>> {
     // Minimal DER parsing: skip the outer SEQUENCE, read PKIStatusInfo, extract token

crates/paperjam-docx/src/lib.rs

@@ -1,3 +1,11 @@
+//! DOCX (Office Open XML word-processing) support for the paperjam
+//! ecosystem.
+//!
+//! Reads and writes `.docx` files and exposes text, tables, and metadata
+//! through the `DocumentTrait` implementation on `DocxDocument`. Body
+//! parsing is delegated to `docx-rs`; an internal size-capped ZIP reader
+//! handles the metadata parts the upstream API does not expose.
+
 mod document;
 mod error;
 mod image;

crates/paperjam-epub/src/lib.rs

@@ -1,3 +1,12 @@
+//! EPUB document support for the paperjam ecosystem.
+//!
+//! Parses EPUB archives (container.xml → OPF → spine) and exposes each
+//! chapter as an `HtmlDocument`, delegating per-chapter rendering to
+//! `paperjam-html`. Implements `DocumentTrait` so EPUB files participate
+//! in the shared model (chapter → page).
+//!
+//! Archive reads are size-capped internally to mitigate zip-bomb attacks.
+
 mod document;
 mod error;
 mod image;

crates/paperjam-html/src/lib.rs

@@ -1,3 +1,10 @@
+//! HTML document support for the paperjam ecosystem.
+//!
+//! Parses HTML bytes via `scraper`, extracts text and tables, and
+//! implements `DocumentTrait` so HTML documents share the same API
+//! surface as the office formats. Also used by `paperjam-epub` for
+//! chapter content (EPUB spine entries are XHTML).
+
 mod document;
 mod error;
 pub mod image;