Skip to content

craft-ui: a network-printer destination with a two-phase job - #117

Closed
b1tninja wants to merge 4 commits into
storytold:mainfrom
b1tninja:craft-ui-printing-network
Closed

b1tninja wants to merge 4 commits into
storytold:mainfrom
b1tninja:craft-ui-printing-network

Conversation

@b1tninja

@b1tninja b1tninja commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

craft-ui: a network-printer destination with a two-phase job

Based on storytold/craft-libs main (457a078).
This is slice 3 of 3 (print backend, WS-Print, then this). A reviewer sees four commits that describe one
change: f0c516b adds the destination, 1043040 reworks its job model so that "sent", "accepted" and "finished"
are different states, 93e71b1 makes the sheet total optional end to end (the owner's request after the pdfcraft
adoption), and cd1ee76 covers the Photo quality choice and adds Quality::from_token. Review the branch at its head.

What

A new submodule craft_ui::printing::network beside the existing queue controls:

  • Draft, the pure model: the typed address, the query result, copies, sides, orientation and quality limited to
    what the printer lists, a per-job confirmation, the job view, and Block, the reasons Print is disabled.
  • Light, backend-free types: PrinterSummary, Caps, Request, Report, Failure, Outcome, Stage, Progress,
    JobUpdate, JobView.
  • State with host-supplied QueryPrinter and SendJob workers (they return mpsc receivers; a job also carries a
    cancel closure), poll, start_query, start_job, cancel_job and show, and Host { validate, query, sheets_ok, formats }.
  • The two-phase job: the worker sends the document (JobView::Running), sends JobUpdate::Accepted when the printer
    has it (JobView::Accepted, with a Stage of Accepted, Waiting, Held, Printing or Stopped, optional sheet counters
    and the printer's notes), sends JobUpdate::Status as it learns more, and finishes on the result receiver.
    Outcome::AcceptedUnknown is "sent, outcome unknown" for a printer that cannot report; it is neither a failure nor a
    claim that the job printed. A worker that stops after Accepted is shown the same way.
  • Optional sheet totals. Progress::sheets_total is an Option, as printers often report sheets done and no total.
    While it is unknown the accepted phase shows the count ("N sheets", the existing Labels::sheets) and no bar that
    could never fill; once known it shows the determinate bar. The app can supply one: Draft::expected_pages (the
    document's page count, set before start_job) goes to the host in the new Request::expected_pages (a craft-print
    worker passes it as JobOptions::expected_pages) and, as an estimated sheet total (Draft::expected_sheets: halved
    and rounded up for a two-sided job, times the copies, fixed when the job starts), fills a missing or zero total of every
    Accepted/Status update. A total the printer reports always wins. Progress gained fraction() and
    with_expected_total(). I chose "N sheets" over a custom indeterminate bar because egui 0.36's ProgressBar has no
    indeterminate mode and the count says what is known.
  • Photo quality. Quality (Draft, Normal, High, Photo; ALL, token()) already had Photo and a Labels::photo
    label from the first commit, so nothing was missing in this crate for pdfcraft's --quality photo to reach the dialog:
    what refused it was craft-print's Quality, fixed in slice 1. cd1ee76 adds Quality::from_token (for a host that
    maps a printer's token, ASCII case ignored) and tests: the token round trip, the label, Photo offered and requested
    only for a printer that lists it (a vendor value is not a choice), and the choice dropped when the next printer does not
    list it.
  • A Failure can say the request may have reached the printer (outcome_unknown); the UI then asks the person to
    check the printer before sending again.

Why

Apps that print to a network printer by address need the same dialog behaviour: validate the address, ask the printer
what it supports, offer only that, require a confirmation for this job, and show a job that takes time without
blocking the UI thread. The model and rules are UI logic with no print client in them, so they belong here once rather
than in each app.

How

  • Additive. State, Settings, Labels and the other existing items in printing are unchanged; WordCraft and
    GridCraft are untouched. The module is new.
  • No print dependency. The crate depends on neither craft-print nor craft-wsd. The host maps its client's results
    into the light types; the README describes how a worker built on craft-print maps Submitted to Accepted, each
    JobStatus to Status and its WatchOutcome to the Report.
  • Rules kept by the model. Only options the printer lists are offered and sent. The confirmation is never on by
    default and is cleared when the address changes, the printer is queried again, a job starts and the dialog opens.
    Answers for an older query or another address are dropped. Print is blocked until the typed address was queried, the
    printer takes one of the host's formats, there is something to print and the box is ticked.
  • No network work while drawing. Everything arrives over receivers drained once per frame by poll (called inside
    show). Dropping a result receiver cancels nothing; cancel works in both phases and the host is told once.
  • The app supplies labels and localisation (including the confirmation wording), the address validator and the
    worker closures. The Print button, document generation and the attestation flow stay in the app.
  • Workers that send no updates behave as they did at the first commit.

How verified

As run at cd1ee76 (after cargo clean -p craft-ui), on Windows:

  • cargo fmt --check, cargo clippy --workspace --all-targets -- -D warnings, cargo test --workspace (285 passed, 4
    ignored), RUSTDOCFLAGS=-D warnings cargo doc -p craft-ui --no-deps and
    cargo check -p craft-ui --target wasm32-unknown-unknown pass.
  • cargo test -p craft-ui: 115 tests pass (109 lib tests of which 31 are in printing::network; the two Photo tests of
    cd1ee76 are the last of them). At 93e71b1 it was 107 lib tests, 29 in printing::network (24 before that commit; the 5 new
    ones cover the model: indeterminate fraction, estimated sheets from pages, duplex and copies, the page count in
    Request, a reported total winning over the estimate; and the egui accesskit rendering: "Blatt: 3" without a bar for an
    unknown total, no text for zero sheets, "1 von 4" from the expected total, "1 von 8" when the printer reports 8). The
    integration suites docking_workflows (1) and visual_regression (5) pass unchanged.

Not verified:

  • Nothing was exercised against a real printer: all tests use in-memory fakes or loopback.
  • The egui rendering has not been looked at by eye; only the accesskit tests cover it.
  • The UI model tests do not run a real print.
  • The craftrules standards repository could not be read (404), so only the rules in AGENTS.md were checked.

Breaking changes (new module only)

JobHandle is #[non_exhaustive] (build it with JobHandle::new), and Labels gained 8 fields for the accepted
phase. This breaks only a host that builds them literally. The module is new and unmerged, so no released API is
affected. The optional-totals commit is additive on top of that: Request gained expected_pages (use
..Default::default() if you construct a Request), Draft gained expected_pages and expected_sheets(), and
Progress gained two methods; Labels, JobHandle, JobUpdate and State::start_job are unchanged. cd1ee76 is
additive (Quality::from_token).

The pdfcraft-facing rule for quality: map craft_ui::printing::network::Quality to craft_print::Quality one to one
(Draft, Normal, High, Photo) once slice 1 is in; a printer that does not list Photo never gets it offered or sent.

Boundaries

  • No discovery and no multicast code; the crate opens no socket.
  • Windows spooler code and unsafe are not involved.
  • PDF generation stays in apps.
  • No new dependencies.

Consumers

pdfcraft adopts slices 1-3: CLI print --wsd, a print_wsd tool, a destination in the Print dialog, a parity entry
and i18n, behind the app feature network-print (default on).

Review order

This slice has no code dependency on slices 1 and 2 and can be reviewed independently. The mapping described in the
README assumes the craft-print types from slice 1 (#116), including JobId and JobOptions.

🤖 Generated with Claude Code

b1tninja and others added 2 commits October 14, 2026 06:36
printing::network is a new submodule beside the existing queue controls; State, Settings,
Labels and the other existing items are unchanged, so WordCraft and GridCraft are unaffected.

- Draft is the pure model: the typed address, the query result, copies, sides, orientation and
  quality limited to what the printer lists, a per-job confirmation that is cleared when the
  address changes, the printer is queried again, a job starts or the dialog opens, the job view,
  and the reasons that block Print. Answers for an older query or another address are dropped.
- It has its own light types and depends on no print client; the host maps its client's results
  into them.
- State adds host-supplied QueryPrinter and SendJob workers returning mpsc receivers (a job
  also carries a cancel closure), poll, start_query, start_job (which re-checks every block and
  spends the confirmation), cancel_job (the host is told once) and show.
- show draws the address field with the host validator's inline error, the Query button, the
  printer name, state and reasons, the options the printer lists, the confirmation checkbox, a
  spinner with Cancel while a job runs and the result text. All wording comes from Labels.
- The Print button, document generation, the attestation flow and translations stay in the app.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…he network printer destination

A SendJob worker can now report that the printer accepted the document and what the printer says afterwards, without blocking the UI thread: JobHandle gains an optional updates receiver that State::poll drains each frame before the result. JobView gets an Accepted state with a Stage (accepted, waiting, held, printing, stopped), optional sheet counters and the printer's notes; Outcome gets AcceptedUnknown for a printer that cannot report (sent, outcome unknown), and a worker that stops after the acceptance is shown that way instead of as a failure. A Failure can say the request may have reached the printer, and the UI then asks the person to check the printer before sending again. Cancel works in both phases and the host is told once.

Workers that send no updates behave as before. JobHandle is built with JobHandle::new, and Labels has new fields for the accepted phase.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
b1tninja and others added 2 commits October 14, 2026 10:13
A printer that reports sheets done and no total now shows the count without a bar, and the app's page count (Draft::expected_pages) becomes an estimated sheet total that makes the bar determinate; a total the printer reports wins. Request carries the page count to the host, Progress gains fraction and with_expected_total, and JobHandle, JobUpdate, State::start_job and Labels are unchanged.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…etwork printer destination

Photo was already a quality choice of the destination; it is now covered end to end (token round
trip, label, offered and requested only for a printer that lists it, dropped on a printer that does
not) and Quality gains from_token for hosts that map printer tokens.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@b1tninja

Copy link
Copy Markdown
Contributor Author

Folded into #112: the network-printer destination (printing::network, the three-state capability work included) is now part of the single craft-ui pull request.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant