craft-libs/crates/print/README.md

# craft-print

Submit a print-ready PDF to the system spooler. Used by PdfCraft and DesignCraft;
there are no dependencies on either app or on a UI framework. Requires Rust 1.95.

```rust,no_run
let job = craft_print::Job { title: "Report".into(), ..Default::default() };
let receipt = craft_print::submit(&pdf_bytes, &job)?;
```

The caller generates the PDF, checks document permissions, and handles page selection,
imposition, marks and bleed. This crate discovers printers, exposes CUPS driver options,
opens Windows printer preferences, takes a Windows driver's own settings for one job, and
submits jobs with copies, collation, duplex and color.
`command_preview` returns diagnostics without creating files or starting a process.

- **macOS/Linux:** CUPS `lpstat`, `lpoptions` and `lp`. Jobs stream through stdin. Exact-size
  sheets use `fit-to-page=false`; shrink-to-fit uses IPP `print-scaling=auto-fit`.
- **macOS paper tray:** a job whose options name no `InputSlot` also sends `AP_D_InputSlot=`,
  the system Print dialog's Paper Feed: Auto Select. Without it CUPS uses the PPD's default
  tray, and a printer whose default tray is empty holds the job while CUPS reports it completed
  (storytold/pdfcraft#3752). A tray the job names wins, as does one in the user's `lpoptions`
  defaults, which `lp` adds to every job. `apply_queue_defaults` puts the same choice in the
  driver's tray option: `AUTO_SELECT` (an empty keyword, which `lp_args` never sends), labelled
  "Auto Select", first and as the default unless the user's defaults name another tray. Apps
  may show their own translation of the label. Other CUPS builds don't know `AP_D_InputSlot`,
  so Linux jobs are unchanged.
- **Flatpak:** the Freedesktop runtime has libcups but not `lpstat`/`lp`/`lpoptions`, so the app
  bundles them (the apps' manifests build them from CUPS as a `cups-client` module). What each
  piece is for:
  - `lpstat` and `--socket=cups`: the printer list. Without either it is empty, and a missing
    `lpstat` is logged.
  - `--system-talk-name=org.freedesktop.Avahi`: driverless network printers (`lpstat -e`).
    Without it the list keeps the spooler's queues and loses only those.
  - `lp`: submitting jobs.
  - Driver options (`printer_options`) come from the queue's PPD in `/etc/cups/ppd`; `lpoptions`
    only marks which choices are current. Flatpak reserves `/etc`, so the host's PPDs, and with
    them these options, are out of reach in a Flatpak whether or not `lpoptions` is there.
  - `--filesystem=~/.cups:ro`: the user's default printer and saved options, and a server named
    in their `client.conf`. A network server also needs `--share=network`. A server named only
    in the host's `/etc/cups/client.conf` is invisible in the sandbox, as is all of `/etc`;
    `flatpak override --user --env=CUPS_SERVER=host:port <app-id>` names it for that one app.
  - A socket path in `client.conf`: Flatpak mounts the socket it chooses at
    `/var/run/cups/cups.sock`, so the manifests' wrapper around the tools points CUPS there when
    CUPS' socket is the one Flatpak chose, and fails when it isn't rather than reach another
    server. Server names and `CUPS_SERVER` are left alone.
- **Windows:** in this process, with no PowerShell, script or other program started, so
  printing works where App Control for Business or AppLocker enforce script rules. Printers
  come from `EnumPrinters` (local queues and `\\server\queue` connections) and the default from
  `GetDefaultPrinter`. `printers` also reads each driver's PrintCapabilities to report two-sided
  support, which can wait on the device (a networked printer in power save); `printer_queues`
  lists the same queues without asking any driver, so a Print dialog's list never waits on a
  device, and `two_sided(name)` asks the driver of just the printer picked. A job asks the
  driver too before it is sent; `submit_cancellable` with a
  `Cancel` token lets the app stop a job still waiting on it, and a cancelled job is never
  sent. A job is drawn as vectors by the in-box `Windows.Data.Pdf` with Direct2D
  into the XPS print API (the `winprint` crate), and copies, collation, duplex, colour, paper,
  orientation and "no scaling" travel in a PrintTicket that the driver validates first; a
  driver that would change the paper, orientation or scaling is refused before anything is
  sent. Paper is the driver's own option for the sheet's size (to 0.25 mm), preferring the one
  named like the standard size ("ARCH D" over a custom 24 × 36 in entry). Windows' ticket merge
  renames a driver's vendor namespace prefix (`brpsk` to `ns0000`) once the ticket uses one of
  its names, and a Brother driver then fails every page with `0x80040003`; the validated ticket
  is given the prefixes of the driver's own default ticket back (`ticket::respell`). This backend
  comes from storytold/pdfcraft#599 and #1132.
  A job has one ticket, so one paper and orientation. Sheets of the other orientation are
  turned back with `/Rotate`, so portrait and landscape sheets still print as one job. Exact
  size refuses sheets of different sizes and paper the driver lacks. Shrink-to-fit uses the
  driver's matching paper, else its default paper, and puts every sheet on it: a sheet that
  doesn't fit inside the paper's widest hardware margin is shrunk, a smaller one keeps its
  size, and both are centred. Both are done by appending an incremental update to the PDF
  (new versions of the pages that need it, the original bytes untouched); the crate reads
  only cross-reference sections, object streams and the page tree for this, leniently and
  with every size bounded. Encrypted PDFs can be turned but not reframed. Annotations on a
  reframed page are dropped; print-ready PDFs have them flattened. Nondefault or invalid
  `/UserUnit` is refused because the native renderer does not reliably honor physical units.
  Parsing caps cumulative cross-reference/object-stream records at 500,000, decoded streams
  at 16 MiB each and 32 MiB per job, and parsed nodes/tokens at 250,000/16 MiB per job and
  32,000/1 MiB per object. Files exceeding these limits return a clear error.
  Long-edge duplex is `TwoSidedLongEdge` and short-edge `TwoSidedShortEdge`.
  Explicit bindings use `JobDuplexAllDocumentsContiguously` when it offers the requested standard option,
  otherwise `DocumentDuplex` when that feature offers that exact binding. Discovery and selection
  resolve option names against their in-scope namespaces, including the default namespace. Validation accepts either
  scope and rejects missing, changed or conflicting bindings before submission.
  `duplex: None` leaves duplex out of the ticket. Driver-specific defaults remain in Windows printer
  preferences (`rundll32 printui.dll`, the one process this crate starts, and only when asked).
- **Browser/other targets:** discovery is empty and submission reports an unsupported
  platform; callers can offer PDF export instead.

Windows jobs briefly use a file in a private temporary folder (random name, this user's only),
named after the job's title because the spooler shows it as the document name; the folder is
removed once the spooler has the job, on success and failure. Failed and canceled terminal
package statuses are errors, including failures received after every sheet was processed.
A missing completion notification times out after two minutes after the native print control
is closed and requests cancellation. Calls into a driver and interactive output-file dialogs
are not covered by this notification timeout. Windows answers when the job is in
the queue ("spooled 3 sheet(s)"): a paused queue or an offline printer keeps it there. CUPS jobs
never use a PDF temporary file. Printing is synchronous; UI callers should submit on a worker.
`submit_with_progress` reports `(processed, sheets)` before the first Windows sheet and after
each sheet is successfully added to the native print job. These are source PDF sheets, excluding
copies and duplex; the events describe sheet processing, and do not confirm physical output.
The callback runs on the thread calling submission, can capture non-`Send` state, and should
return promptly. It is never retained. Keep waiting for the final `Result` even at full progress:
the job can still fail. `submit_cancellable` can cancel a job only until it starts reaching
the spooler (on Windows after craft-print's driver queries and preflight DEVMODE conversion;
with CUPS before `lp` starts); a job already being sent completes. On Windows, winprint repeats
the DEVMODE conversion after that boundary. Cancellation is already unavailable during this
repeat, so a driver that stalls there can still block submission. CUPS reports no progress.
UI callers must forward events to their own progress state; adopting the API alone does not
change an application's UI.
Receipts are backend messages, not portable job IDs. `Job::duplex = None` preserves the queue's
duplex default; `Some(Duplex::Off)` forces simplex. `Job::scaling` defaults to `Scaling::Exact`;
callers exporting arbitrary document sizes can choose `Scaling::ShrinkToFit`. Exact mode reports
a driver paper-size mismatch. On Windows `command_preview` describes the in-process job
(`xps-print`, then the printer and options as `key=value`) instead of a command line. The crate
does not provide PostScript output, separations, trapping or colour-managed device rendering.

Windows shrink-to-fit refuses pages with annotations when their geometry needs fitting.
Callers must flatten annotation appearances into page content first. Exact-size printing and
rotation retain the annotations. This avoids losing printed comments, forms or other marks.
The Windows renderer uses viewer visibility. Native submission therefore accepts only plain
visible printable annotation flags (`F=4`); annotations without Print, with NoView, or with
other visibility/rotation flags require caller flattening. This prevents printing comments
that were marked nonprinting or omitting print-only marks. A visible Square appearance with
`F=4` was rendered in the Windows qualification fixture; other appearance types still need
their own fidelity checks.

Native Windows PDF submission checks the driver's validated copy count and explicit
simplex/duplex and grayscale requests before sending. Collation must be retained when both
the page count and copy count exceed one. A driver that offers one of these options and drops
or changes it is refused; select supported options or flatten grayscale into the print-ready
page content. A driver without the feature, per its PrintCapabilities, is accepted when it can
only do what was asked: one-sided on a queue with no two-sided feature, grayscale on one with no
colour option, uncollated copies on one that can't collate. Two-sided on such a queue is
refused. Windows doesn't document collating for a driver that can't collate, so collated copies
on one are a single job of one copy that holds the document's pages once per copy; on two-sided
paper an odd page count gets a blank page after each copy but the last, so every copy starts on
a sheet of its own. Where one job would print the copies wrongly or can't hold them (pages with
annotations, an encrypted PDF, a very large job, a queue set to several pages per sheet, binding,
stapling or a two-sided option outside the Print Schema's), each copy is a job of its own.
Without an explicit duplex request, the queue default applies. Without a grayscale request the
ticket names no colour, so the colour in the user's printing preferences (Properties…, or
Windows Settings) applies, black and white included. Single-page or single-copy jobs have no
collating order to check.

`driver_settings_dialog(&mut job, parent)` opens the job printer's driver dialog
([`DocumentProperties`](https://learn.microsoft.com/en-us/windows/win32/printdocs/documentproperties)),
modal to the `parent` window handle, for that one job: options craft-print does not set, such
as media type, print quality and the driver's own options. The dialog opens on the job's
earlier choices in it for the same printer, without the ones the job decides (below), when the
driver still reads them, else on the settings the driver gives a new job; either way with the
job's copies and collation. OK stores the settings in `Job::driver_settings` for that printer.
Cancel leaves the job unchanged, and so do settings the dialog returns exactly as it opened on
them: some drivers return OK from Cancel with the settings they were given. Earlier settings
the driver can no longer read are replaced even then. Some drivers read settings that set no
fields (a DEVMODE whose [`dmFields`](https://learn.microsoft.com/en-us/windows/win32/api/wingdi/ns-wingdi-devmodew) is 0
and that has no private section) without an error instead of refusing them; such settings stay
on the job after Cancel, and after OK with nothing changed. craft-print keeps the settings in
the job only and does not save them as the printer's defaults (`open_printer_preferences` does
that). When the job is printed, Windows converts the settings to a PrintTicket
([`PTConvertDevModeToPrintTicket`](https://learn.microsoft.com/en-us/windows/win32/api/prntvpt/nf-prntvpt-ptconvertdevmodetoprintticket)),
craft-print removes from it what the job's own ticket decides, and merges the job's ticket
after it. The dialog's copies, collation, paper, orientation and scaling are removed, and so
are its pages per sheet, binding (booklets included) and poster features. Its two-sided choice
is removed when `duplex` is `Some`, and its color when grayscale is on. The dialog does not
open on the job's two-sided or grayscale choice, so when the job later leaves that choice open,
the dialog's settings decide it. The driver's other options, vendor options and private
settings included, are kept, so a driver that also keeps pages per sheet in its private
settings can still apply it from there. The dialog's borderless choice is kept too, and on a
driver that enlarges the page for borderless printing it changes the printed size. The checks
above still run on the ticket the driver validates; they read the validated ticket, not the
driver's private settings. The job is refused when the driver replaces the dialog's media type,
resolution or print quality while it validates the job's ticket, which it can do when one
conflicts with the job's paper. Settings are used only on the printer whose name they were
chosen for: Windows may replace settings meant for another printer with defaults.
`command_preview` marks them as not used when the job, or the default printer for a job that
names none, is another printer. It does not ask the driver to read them, and it lists two-sided
printing and color that the job leaves open as the dialog's settings or the default. An error
names the step that failed: the printer, reading the driver's settings, the dialog (a driver
without one), the driver refusing the settings, or the driver replacing one of them.
`HAS_DRIVER_SETTINGS_DIALOG` is false and the call returns an error on other platforms, and CUPS
jobs ignore `driver_settings`. `examples/driver_settings_dialog.rs` opens the dialog for a
printer named on the command line and prints a one-page test sheet with the settings chosen.

`cargo test -p craft-print` tests CUPS transport (including pipe-sized jobs and refusal),
printer parsing, PPD options and argument mapping, and on every platform the Windows pieces that
need no printer: the PrintTicket, what is removed from the driver dialog's settings, the
dialog's Cancel, the checks on the driver's validated ticket and capabilities,
paper matching, job file names, and the PDF sheet reader and its update (classic and compressed
cross-references, turning, reframing, refusal, and thousands of truncated and corrupted files
that must fail without a panic). On Windows it also submits a mixed-orientation exact-size job
and a shrink-to-fit job to a temporary paused queue (inbox "Generic / Text Only" driver on
`LPT1:`) and checks each arrives as one job with all its sheets. The queue portion explicitly
skips if the driver or administrative rights are absent. Windows CI installs the inbox test
driver and sets `CRAFT_PRINT_REQUIRE_QUEUE=1`, making queue preparation/submission mandatory on
its runner. Ignored tests check a real printer by hand: `an_installed_driver_validates_the_ticket`
and `the_driver_dialogs_settings_leave_the_jobs_own_options` (`CRAFT_PRINT_TEST_PRINTER`; send no
job) and `an_installed_printer_prints_a_file`
(`CRAFT_PRINT_TEST_PRINTER`, `CRAFT_PRINT_TEST_FILE`, optional `CRAFT_PRINT_TEST_SCALING=shrink`
and `CRAFT_PRINT_TEST_DUPLEX=long`). Physical printer fidelity remains a hardware check.

The cross-platform GitHub Actions workflow is defined in `.github/workflows/print.yml`.
It runs formatting, Clippy and this crate's own tests on Windows, Linux and macOS when print
code changes, and supports manual runs. The Windows job executes the spooler regression above;
physical printer fidelity still requires hardware verification.

Windows discovery reports driver duplex support in `Printer::two_sided` (a two-sided option in
the driver's PrintCapabilities); CUPS leaves it unknown. Explicit simplex/duplex choices that the driver
drops are refused before submission.

Windows dependencies: the maintained [`winprint` fork](https://github.com/storytold/winprint.rs)
(BSD-3-Clause, pinned to an immutable Git revision, its PDFium-downloading `pdfium` feature off) and `winsafe` (MIT) hold every Win32 and WinRT call, so the crate keeps `unsafe` forbidden;
`roxmltree` reads PrintTickets and `miniz_oxide` inflates PDF streams. `winprint` 0.2.1 lists
reqwest (with rustls) and sigstore crates as non-optional build-dependencies, used only by its
`pdfium` feature: they compile into its build script on Windows but not into the library. Apps
running `cargo deny` need a licence exception for `webpki-root-certs` (CDLA-Permissive-2.0, CA
list data reqwest brings) and an advisory ignore for RUSTSEC-2024-0370 (`proc-macro-error`
unmaintained, a compile-time proc macro of winprint's `fmt-derive`).

`craft_print::rgb` exposes the safe `craft-winprint-gdi` API for native driver settings,
printable geometry, RGB pages and caller-composed vector strokes. Applications retain ICC
conversion, document layout, labels and print-mark composition. The shared transport validates
single-copy DEVMODE settings before emitting manual copies and checks GDI errors. Color policy
is explicit: application-managed/unmanaged RGB disables DC and old-style halftone correction
with `ICM_DONE_OUTSIDEDC`, reapplied after `StartPage`; driver-managed RGB uses `ICM_OFF`.
Vendor driver automatic color correction remains a driver setting and requires qualification.
Other platforms return `rgb::PrintError::Unsupported`. The Windows PDF backend and its existing
completion dependency pin are independent of this additional MIT OR Apache-2.0 API.