shifathosn
/
pdfcraft
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
pdfcraft/CLAUDE.md

4.3 KiB
Raw Blame History

PrintCraft — instructions for agents

PrintCraft is a clean-room, open-source, Rust-native PDF application targeting Adobe Acrobat Pro parity. It runs natively on macOS, Windows and Linux, and on the web via WASM. It is the sibling of ../photocraft (a Photoshop-class editor) and follows the same conventions.

Start every session here

  1. Read plan/STATUS.md: the current milestone, the next unchecked task and any blockers. ROADMAP.md holds the milestone estimates and progress; update its table and log at the end of every session.
  2. Read that task in plan/execution-plan.md §3, the relevant section of plan/architecture.md, and the README of the crate you're touching.
  3. Follow the autonomous operation protocol in plan/execution-plan.md §7 (orient → plan → implement + test → verify → record → commit). Don't stop to ask unless §7 lists the decision as the user's.

plan/ is gitignored (local-only, like PhotoCraft). The machine-readable parity checklist lives in parity/ (committed).

Non-negotiables

  • Assets: read AGENTS.md §1 before adding or showing any icon, image, font or document. No assets from Adobe products, ever. Only openly licensed or contributor-original assets are allowed, each with an entry in ATTRIBUTION.toml. cargo xtask assets enforces this. AGENTS.md overrides this file.
  • Clean-room.
    • Never read, disassemble or copy anything inside the Acrobat bundle (names and listings only). Never open Contents/Resources/JavaScripts/.
    • Behaviour comes from public docs, specs (ISO 32000-2, the Arlington model) and black-box observation (plan/acrobat/).
    • Never copy GPL/AGPL code. MuPDF, Ghostscript, Poppler, veraPDF and DSS run only as external oracle processes.
    • See plan/README.md §Clean-room and plan/adr/0001.
  • Privacy. When observing Acrobat, use synthetic fixtures only. Never capture the Home view, recent files or account info. Capture by window id (plan/acrobat/tools/). Never commit Acrobat outputs, corpus files or personal data.
  • Layering. Nothing below L7 depends on egui/winit/eframe/rfd (plan/architecture.md §3). cos/filters/crypt/arlington stay standalone.
  • Fidelity. The PDF object graph is the model. Preserve unknown data. Saves are incremental unless a full rewrite is required. Never silently drop or repair data without recording it.
  • Rust only in the product and build (xtask). No handwritten JS/TS.
  • Quality gates before every commit: cargo fmt --check, cargo clippy --workspace -- -D warnings, cargo test --workspace, and the wasm check once xtask ci exists (M0).
  • Commits: one task id per commit (e.g. M1.4: xref stream reader). Commit only green states. End messages with the attribution line required by the environment.

Running and looking at the app

  • cargo run -p printcraft -- <file.pdf> opens the desktop app.
  • cargo run -p printcraft-cli -- run --script steps.json --root DIR drives the engine headlessly through the automation tools (printcraft-cli tools lists them). Use it, together with page_render, to check engine changes. printcraft-cli mcp is the opt-in MCP server (AGENTS.md §3).
  • cargo xtask fuzz --time 300 mutation-fuzzes open/render/edit/save in child processes. Findings land in fuzz-out/findings/ (git-ignored; never commit corpus-derived files). Turn every real finding into a small synthetic regression test before fixing it.
  • cargo xtask parity [--partial] reports Acrobat-parity progress from parity/acrobat-features.toml. Update the entry when a feature ships.
  • cargo xtask demo-pdf builds dist/demo/printcraft-showcase.pdf (needs Chrome) for visual checks.
  • For UI work, look at the result. Either launch printcraft --control FILE doc.pdf and use printcraft-cli ui --control FILE screenshot --out x.png (plus inspect, click, key, type, command, set), or take a headless shot with cargo run -p printcraft-ui-egui --example shot. Compare against plan/acrobat/02-ui-ux.md. Control-channel tests use kittest (crates/ui-egui/tests/control.rs).
  • Parallel agents: use a separate CARGO_TARGET_DIR per agent and separate git worktrees.

Current bootstrap debt (tracked in STATUS.md)

  • printcraft-render renders through the hayro crate directly and inspects documents through lopdf. Both get replaced by cos / model / the DisplayList device (M1–M2, ADR-0004).