diff --git a/AGENTS.md b/AGENTS.md index 8003792..ed6b74d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,7 +14,9 @@ The current executable reports bootstrap status; do not describe it as a PDF vie - `docs/development/`: architecture decisions, implementation plan and CI setup. - `docs/interfaces/`: persistent-format contracts when formats are introduced. -Keep a single-member workspace. Do not depend on sibling repositories. Reliable +Keep the build standalone; do not depend on sibling repositories. Crate count, +compilation time and package size are not priorities. Add dependencies or split +workspace crates where runtime resilience, performance or maintainability benefits. Reliable selectable presenter/audience displays on Windows, macOS and Linux are a HARD requirement. Prove this first and iterate with the user on physical testing until it works. Presentation speed is the primary performance goal: prioritize first-page @@ -27,6 +29,23 @@ another window host are acceptable when they satisfy reliability and speed. Keep rendering, document state and display/window management separate without speculative abstractions. Do not copy Pympress or PowerPoint code/assets without license review. +Implementation follows `docs/development/tasks.md` and the decisions in +`docs/development/implementation.md`. Fast startup and responsive controls are hard +gates. Keep PDF/native blocking work in killable worker processes; never perform +blocking disk, renderer, portal or IPC waits on UI/input paths. Bound queues, memory, +retries, cancellation and shutdown. Keep output independent of presenter failures. +Automatically inhibit idle display/system sleep throughout an armed presentation, +including blank/paused states; report partial support and release owned leases at end. +Native APIs and measured OS tweaks are authorized; prefer session-scoped reversible +changes with recovery tests. Never claim immunity to OS/hardware faults. + +Portable distribution is a hard release gate: one launchable executable per target, +all required non-system dependencies bundled, no runtime downloads/installers or +user-installed PDF backend/toolchain. Re-exec the same binary for internal process +roles. Prefer static linkage; embed and automatically extract unavoidable runtime +assets safely, testing cold startup and read-only executable locations. See the +implementation choices for target packaging and clean-machine acceptance. + ## Presentation safety Open source PDFs read-only. Never rewrite a document as a side effect of presenting. diff --git a/AGENT_DOCUMENTATION.md b/AGENT_DOCUMENTATION.md index 6074c5c..8b15449 100644 --- a/AGENT_DOCUMENTATION.md +++ b/AGENT_DOCUMENTATION.md @@ -8,3 +8,6 @@ - [Interface policy](docs/interfaces/README.md) - [Artwork provenance](docs/development/icon-prompts.json) - [Changelog](docs/changelog.md) + +- [Ordered implementation tasks](docs/development/tasks.md) +- [Implementation choices and performance budgets](docs/development/implementation.md) diff --git a/Cargo.lock b/Cargo.lock index f1b6cd9..498ccf2 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4,4 +4,4 @@ version = 4 [[package]] name = "pdf-presenter" -version = "0.1.1" +version = "0.1.2" diff --git a/Cargo.toml b/Cargo.toml index 4754757..abd40c8 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,7 +4,7 @@ default-members = ["crates/pdf-presenter"] resolver = "3" [workspace.package] -version = "0.1.1" +version = "0.1.2" edition = "2024" license = "MIT" repository = "https://proxy.dandaedre.com/gitea/idle-org/pdf-presenter" diff --git a/README.md b/README.md index 0f1a1ba..3730dac 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,8 @@ **Repository foundation — not yet a usable PDF presenter.** The goal is a blazingly fast Pympress-style PDF presenter: selectable presenter and audience displays on Windows, macOS and Linux, progressive rendering with reusable image caches, and current/next previews with notes when extractable. -Reliable dual-screen operation on all three OSes is a hard requirement. It is independent of those projects. +Reliable dual-screen operation on all three OSes is a hard requirement. Releases +will be portable executables with all non-system dependencies bundled. It is independent of those projects. The initial Rust core tests page navigation and audience blanking. PDF loading, rendering, presenter UI and display selection are planned. Build status badges diff --git a/docs/changelog.md b/docs/changelog.md index c9b8edc..9aaf92b 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -2,6 +2,15 @@ ## Unreleased +### 0.1.2 + +- Added an ordered implementation task list and concrete runtime choices: isolated + PDF workers/audience host, progressive image caches, bounded recovery, native sleep + inhibition and measured latency budgets. Dependency/build/package size constraints + do not take precedence over fast startup and resilience. Require portable executables + with bundled non-system dependencies and offline clean-machine tests. Choices are researched; + desktop implementation and physical acceptance remain pending. + ### 0.1.1 - Established selectable dual-screen operation on Windows/macOS/Linux as a hard diff --git a/docs/development/README.md b/docs/development/README.md index 0b48739..005561e 100644 --- a/docs/development/README.md +++ b/docs/development/README.md @@ -13,3 +13,10 @@ and measured presentation speed; sharing Canvas Pilot's UI stack is optional. Run `cargo run --locked -p pdf-presenter` for the bootstrap status executable. No PDF opening, GUI, installation bundle or presentation output exists yet. + +- [Ordered implementation tasks](tasks.md) +- [Implementation choices and performance budgets](implementation.md) + +Release target: a portable executable for each supported OS/architecture, bundling +all non-system dependencies. Runtime installation/downloads are not acceptable; +see implementation choices and task T25 for packaging and clean-machine tests. diff --git a/docs/development/implementation.md b/docs/development/implementation.md new file mode 100644 index 0000000..867fc12 --- /dev/null +++ b/docs/development/implementation.md @@ -0,0 +1,212 @@ +# Implementation choices + +Status: implementation direction selected 2026-11-19; no desktop/PDF implementation +exists yet. The [task list](tasks.md) owns execution order and evidence. Choices below +are engineering decisions to validate, not measured claims about an existing app. + +## Optimization priorities + +Correct dual-screen output, fast startup, bounded input latency and resilience are +release requirements. Dependency count, compilation time and binary/package size +are not optimization goals. Add crates, native code and bundled dependencies when +they improve runtime behavior. Use separate workspace crates where they establish +useful ownership or testing boundaries; process boundaries matter more than crate +count. Do not delay the first visible frame for an update check, network request, +full-deck scan, full hash, notes extraction, cache cleanup or renderer warmup. + +## Portable distribution is a hard requirement + +Ship one launchable executable per supported OS/architecture, carrying every required +non-system dependency. No installed Rust/Python/Node, system PDFium, codec package, +package-manager step, network access or first-run download may be required. Native OS +libraries, window services and graphics drivers are platform prerequisites and their +minimum supported versions must be documented. Build tools do not belong on user +machines. Copy-and-run from an arbitrary directory must work without installation. + +Prefer statically linked PDFium and other runtime libraries. Where static linking is +not viable on a target, embed the required library/assets in the executable and +extract automatically to a versioned writable user-cache directory using atomic +writes and integrity validation. Load only the explicit extracted path, never an +uncontrolled current-directory library. A read-only executable directory must work. +Extraction must not scan/download dependencies or delay shell startup; benchmark +first launch with an empty cache as well as subsequent launches. Report an unwritable +cache as an actionable failure. Do not claim strict in-memory single-file execution +if embedded runtime materialization is used. + +Bundle required fonts, icons and native-library notices/resources; document optional +system-font substitutions and test a minimal machine. Preserve all license obligations. +Use the same executable's internal audience/worker modes for process isolation, via +an absolute executable path and private IPC bootstrap token. Internal modes are not +a user setup step. Workers must run on offline clean machines with the same bundle. +macOS may additionally ship a conventional signed .app wrapper for normal desktop +launching; it must contain everything and require no installer. A wrapper does not +justify fetching or depending on separately installed libraries. + +## Chosen starting stack + +| Area | Choice | Reason and proof required | +| --- | --- | --- | +| Native windows | Rust + winit, with native platform adapters | Explicit window/display lifecycle; prove both display roles on each OS before building the rest. | +| Presenter controls | egui through egui-winit and egui-wgpu | Practical UI; retain direct ownership of the event loop and window management. | +| Audience drawing | Minimal wgpu texture compositor in its own process | No UI, PDF interpreter, notes or file picker on the audience path; independent from presenter failures. | +| GPU fallback | softbuffer CPU image presentation | Predecoded slide buffers remain usable without successful GPU initialization; validate separately on every OS. | +| PDF rasterization | Bundled, pinned PDFium through pdfium-render, isolated workers | Consistent backend across OSes, replaceable workers and no runtime dependency downloads. | +| Work scheduling | Bounded process pool, bounded channels, explicit priorities/deadlines | Never let background extraction starve an interactive slide request. | +| Durable page cache | Lossless PNG baseline, versioned JSON manifest, SHA-256 source identity | Portable artifacts; benchmark LZ4/raw BGRA alternatives before choosing faster storage. | +| Hot cache | Decoded CPU buffers plus GPU textures for current/next/previous | Prepared navigation performs no PDF rendering, image decode or file reads. | +| Platform integration | windows bindings, objc2/IOKit bindings, Linux D-Bus via zbus/ashpd | Direct control and observable errors; version-pin a compatible set during implementation. | +| Measurement | tracing with bounded asynchronous logs and monotonic timestamps | Separate startup, queue, render, decode, upload and visible-frame measurements. | + +Exact compatible crate versions and PDFium binary checksums belong in lockfiles and +packaging manifests when introduced. More dependencies are acceptable; do not select +an old or incompatible release merely to satisfy this document. Build PDFium for each +promised target or use verified pinned artifacts with notices. Keep JS/XFA features +disabled unless a demonstrated PDF requirement justifies them. + +winit documents platform differences in window positioning and fullscreen. Treat its +API as an implementation tool, not proof that all compositors honor placement. On +Wayland validate selected-output fullscreen and presenter assignment separately; a +manual placement/reassignment flow must actually meet the user workflow on tested +compositors. Do not silently mark the hard requirement complete after testing only +X11. [winit window API](https://docs.rs/winit/latest/winit/window/struct.Window.html) + +PDFium calls cannot safely be parallelized merely by adding threads: pdfium-render's +thread-safe mode serializes access. Use one PDFium instance per worker process and +one PDFium call at a time per worker. Progressive PDFium rendering may yield useful +partial work, but cannot replace a process deadline for all parsing/render failures. +[pdfium-render](https://docs.rs/pdfium-render/latest/pdfium_render/), +[PDFium progressive API](https://pdfium.googlesource.com/pdfium/+/refs/heads/main/public/fpdf_progressive.h) + +## Process ownership and fault containment + +Start with one workspace package producing a single executable with presenter, +audience-host and PDF-worker modes; split crates when implementation benefits. Do not +build an abstract plugin framework. The presenter opens immediately; PDF/GPU workers +start asynchronously. The audience host owns its native event loop, slide buffers, +output assignment, local emergency blank/escape controls and presentation sleep guard. + +The audience host owns the last successfully displayed page and acknowledges its +generation/page/quality to the presenter. Distinguish requested, prepared and displayed +state. The presenter must not label an unacknowledged slide as already on air. Include +document generation and request sequence on every reply; discard stale results. +If the presenter exits or stalls, the audience holds the last confirmed slide or +operator-selected blank state and keeps its emergency controls and inhibition alive. +Reconnecting the presenter must read audience state before issuing new commands. + +The presenter supervises audience and worker processes using nonblocking IPC and +bounded queues. A health response must reflect actual event-loop progress; a heartbeat +thread alone cannot prove the UI is responsive. Never interpret a long PDF task as a +healthy worker merely because its IPC thread still answers. Track job progress and +deadlines separately. An unresponsive audience process is restarted with a safe blank +surface, then restored only after its display identity and cached frame are verified. +A restart may create a visible interruption; record it as a failure, not seamless +recovery. A full GPU/compositor/OS hang cannot be guaranteed recoverable by this app. + +Control messages use a versioned, length-bounded local IPC protocol. Transfer large +frames through bounded shared-memory slots or mapped temporary artifacts, not JSON +base64 or control queues. Validate dimensions, stride, byte length, format and slot +lifetime before use. Acknowledge ownership before reusing buffers. Never allow a +slow reader to block presentation control. Define and test the protocol before use. + +Renderer crashes, deadlocks and memory exhaustion kill only the worker. Limit process +memory where available (Windows Job Objects, Unix resource limits where applicable), +validate allocation sizes everywhere, cap the pool by available memory and CPU, and +reserve capacity for foreground work. Start with one foreground worker and at most +two background workers; tune from measurements. On cancellation ask politely first, +then terminate/reap an overdue worker and replace it. Do not attempt to kill a Rust +thread stuck inside a native PDF call. Limit retries per page/document, back off and +surface persistent failure in the presenter; avoid restart storms. + +Use separate foreground and background queues. Priority order: emergency controls, +requested slide, next slide, previous slide, other previews, notes, distant slides. +Reserve upload/decode budgets so a large texture cannot monopolize a frame. Coalesce +obsolete navigation requests but preserve emergency blanking and the final requested +page. Keep the existing audience frame while preparation runs; explicitly show the +pending request in the presenter. Never show an unrelated placeholder as a slide. + +## Startup and image pipeline + +Show the presenter shell without synchronously initializing PDFium or enumerating +files. Start monitor discovery/power services with bounded operations. Initialize +GPU work without blocking the shell; exercise a CPU-first startup path if GPU startup +violates budget. softbuffer offers direct software image display; its suitability +for this app's resolution and latency is still to be measured. +[softbuffer documentation](https://docs.rs/softbuffer/latest/softbuffer/) + +Render the requested page at a useful preview resolution first, then refine it to +the target display resolution in the background. Replace the image atomically, keep +aspect ratio and crop/rotation fixed, and never delay a ready preview for a full-deck +operation. Notes and thumbnail generation have lower priority. Large source reads, +slow disks and network-mounted PDFs must not stall either window: isolate I/O with +workers, offer cancellation and copy to local storage progressively when helpful. +Opening some PDFs may require seeking or a complete read; first-page speed remains +a measured goal, not a promise that every damaged or remote PDF opens instantly. + +Persist lossless prepared pages and reuse them only after source/render-settings +validation. Full source hashing runs independently; until complete, render the current +source rather than display unverified stale cache. Immutable memory-mapped blobs or +shared buffers may reduce copies after measurement. Keep bounded CPU and GPU LRUs; +pin the visible slide and immediate neighbors. Background extraction pauses under +memory pressure or foreground demand. Persist cache entries atomically, resume partial +extractions and regenerate corrupt entries. See the [cache requirements](../interfaces/extraction-cache.md). + +wgpu surfaces require handling acquisition/configuration and device failure. Do not +spin/retry forever or recreate a GPU device on every frame. Attempt bounded recovery, +then switch to the validated CPU output path. A blocked driver call may require +restarting the audience host; process isolation reduces the blast radius, not kernel +failure risk. [wgpu surface API](https://docs.rs/wgpu/latest/wgpu/struct.Surface.html) + +## Keep-awake policy + +Acquire display-idle and system-idle inhibition automatically when presentation is +armed, before activating audience output. Hold it through blanking, paused navigation, +notes reading and recovery; a deliberately black slide is still an active presentation. +Release on explicit End Presentation or host exit. The audience host owns the live +lease so a presenter crash does not drop it. Rehearsal may opt in separately. Show +acquired/partial/unavailable status only in the presenter and reacquire after wake, +session/backend restart or lost connection. Every system call/IPC operation needs a +bounded asynchronous path; a broken power service must not freeze the presentation. + +| OS | Implementation | Validation and limits | +| --- | --- | --- | +| Windows | Dedicated owner thread calls SetThreadExecutionState with ES_CONTINUOUS, ES_DISPLAY_REQUIRED and ES_SYSTEM_REQUIRED; clear on the same thread. Handle SC_SCREENSAVE/SC_MONITORPOWER in native window integration where allowed during the session. | Execution-state requests do not themselves stop screensavers. Verify both idle display/system sleep and screensaver behavior; managed security policy or explicit sleep may override. | +| macOS | IOPMAssertionCreateWithName display/system idle-sleep assertions, scoped ownership and explicit release. Observe sleep/wake; add a scoped NSProcessInfo activity for App Nap behavior if measured necessary. | Test visible and blanked output and battery/AC. Forced sleep, lid closure, thermal or low-battery intervention cannot be promised away. | +| Linux | XDG desktop portal Inhibit with idle+suspend flags through an async request. If unavailable, use supported session ScreenSaver inhibition for idle and logind sleep inhibition for suspend. Track each lease separately. | Portal backends vary. A logind sleep lock alone is not proof of screen-idle inhibition. Validate GNOME/KDE on Wayland/X11; add compositor/native adapters only where a tested gap requires them. | + +These API choices follow [Microsoft execution-state documentation](https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-setthreadexecutionstate), +[Windows system commands](https://learn.microsoft.com/en-us/windows/win32/menurc/wm-syscommand), +[Apple sleep assertions](https://developer.apple.com/library/archive/qa/qa1340/_index.html), +[XDG Inhibit](https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.Inhibit.html), +[session idle inhibition](https://specifications.freedesktop.org/idle-inhibit/latest/), +and [logind inhibitors](https://www.freedesktop.org/software/systemd/man/latest/org.freedesktop.login1.html). + +Prefer process/session-scoped requests over permanent OS changes. Additional tuning +is authorized when useful: benchmark foreground scheduling, background I/O priority, +GPU adapter selection and compositor-specific integration. Keep any configuration +change explicit, reversible, recorded and limited to the presentation. Avoid realtime +scheduling that can starve input or the compositor. Do not blindly disable system +services, security locks, updates or global power settings: that is not evidence of +resilience. A further invasive tweak needs a concrete reproduced problem and a tested +restore path, not a speculative performance claim. + +## Initial performance and recovery budgets + +These are proposed engineering gates to measure on declared reference hardware and +representative local decks, not user-approved measurements or universal PDF guarantees. +Record p50/p95/worst, cold/warm OS cache, app cache state, resolution and deck identity. + +| Operation | Initial target | +| --- | --- | +| Launch to interactive presenter shell | p95 <= 500 ms; renderer/cache scans are excluded from the critical path, not from reported end-to-end startup. | +| Cold local PDF to usable first page | p95 <= 2 s on the baseline corpus; report outliers and renderer failures separately. | +| Warm prepared adjacent-slide navigation | p95 <= 50 ms input-to-visible at 60 Hz; also report input-to-submit and refresh rate. | +| Blank/unblank with prepared surface | p95 <= 50 ms even under render/cache stress. | +| UI event work | No application-controlled blocking I/O or waits; aim for <= 4 ms handler slices, report stalls > 50 ms. | +| Stuck foreground render | Progress deadline initially 2 s; cancel/restart independently, keep controls live; complexity may require a visible longer render attempt. | +| Dead audience host | Detect missing event-loop progress within 1 s under stress; attempt blanked recovery within 2 s on reference hardware. | +| End presentation | Release sleep leases promptly; no wait for full-deck extraction or cache completion. | + +Do not improve reported latency by hiding dropped requests, stale slides, failed opens +or recovery interruptions. When a target fails, retain the evidence and fix the cause +or explicitly review the target with the user. No silent relaxation. Validate long +soak behavior and fault injection as seriously as the fast path. diff --git a/docs/development/plan.md b/docs/development/plan.md index 7c619b1..25e5349 100644 --- a/docs/development/plan.md +++ b/docs/development/plan.md @@ -32,6 +32,11 @@ OS, compositor, GPU or disconnected monitor cannot fail. Handle failures explici keep presenter content private, and make output recovery possible without restarting or losing the selected slide. Do not silently demote an affected OS to unsupported. +Portable distribution is also mandatory: one launchable executable per target with +all required non-system dependencies bundled. No runtime downloads, dependency +installation or separately installed PDF backend. See implementation choices for +static linking, embedded assets and clean-machine acceptance. + ## Completed foundation — 0.1.0 Independent workspace, source license, app/repository icon, agent instructions, @@ -40,35 +45,16 @@ zero-based navigation and audience blanking, with output initially blanked. The executable only identifies the project's current status. No PDF renderer or native windows have been implemented; no physical-display acceptance is recorded. -## Implementation order +## Implementation work -1. Prove two independently assigned windows on Windows, macOS and Linux first. - Enumerate displays, identify them visibly, select presenter/audience destinations, - swap roles, and enter/leave audience fullscreen. Rust is the foundation; egui is - a candidate, not a constraint. Evaluate platform APIs or another host if needed. - On Linux, test X11 and Wayland separately: investigate placement/fullscreen - constraints and provide an explicit operator placement flow where needed. A - limitation must be resolved and tested, not hidden behind automatic placement. -2. Integrate a real PDF backend into those two windows. Render the requested page - first, display it immediately when ready, then prepare next/previous pages ahead - of more distant pages. Prioritize interactive jumps over background extraction, - cancel obsolete work, and keep UI/input handling independent of rendering. - Evaluate backend licensing, packaging, rotation/crop fidelity and all three OSes. -3. Add reusable extraction and bounded memory/GPU caches. Warm presentation should - use prepared images/textures rather than synchronously re-rendering the PDF on - each slide change. Avoid decode, disk I/O and texture-upload stalls on the input - path. Use bounded parallelism and measured prefetch, not unbounded whole-deck RAM. - Start displaying without waiting for the complete deck or its source hash; only - reuse persistent extraction after validating its identity and render settings. - See [cache design requirements](../interfaces/extraction-cache.md). -4. Finish presenter controls: current/next slide previews, keyboard navigation, - direct selection and blank/unblank. Extract available notes asynchronously; use - current/next-only mode if unavailable. Support explicit notes-page layout/cropping - when needed; do not assume every PDF carries structured speaker notes. -5. Iterate on real-machine display and performance failures with the user until the - acceptance gates below pass. Package each OS with the chosen renderer dependencies, - app artwork, license notices and reproducible build instructions. FreeBSD remains - the CI host, not a substitute for Windows/macOS/Linux desktop testing. +The ordered [task list](tasks.md) owns implementation and completion tracking. +[Implementation choices](implementation.md) specify the stack, process isolation, +cache pipeline, keep-awake APIs and initial performance/recovery budgets. + +Dependency count, build time and package size are not priorities. Fast startup, +responsive controls and resilience are. Automatically inhibit idle display/system +sleep during presentation, including blanked and paused output, to the extent the OS +allows. Native integration and measured, reversible OS tuning are authorized. ## Display acceptance gate @@ -98,8 +84,8 @@ Measure time to first visible page, time to presentation-ready dual windows, and input-to-visible slide latency (median, p95 and worst case). Include rapid next/back, uncached random jumps, notes extraction and background cache work. Record peak RAM, GPU memory when measurable, disk-cache size and extraction time. Distinguish actual -visible-output timing from CPU submission timing. Establish numerical budgets from -initial measurements and user testing; none have been agreed yet. No claims of +visible-output timing from CPU submission timing. Use the proposed numerical budgets in the implementation choices as initial +engineering gates; validate them against reference hardware and user testing. No claims of "blazingly fast" acceptance without recorded measurements and user validation. ## Scope after the core requirements diff --git a/docs/development/tasks.md b/docs/development/tasks.md new file mode 100644 index 0000000..fb412a6 --- /dev/null +++ b/docs/development/tasks.md @@ -0,0 +1,129 @@ +# Implementation task list + +All tasks below are pending. Completed bootstrap work remains in the [plan](plan.md). +The [implementation choices](implementation.md) define the selected direction and +initial budgets. A checkbox means code, relevant tests and evidence exist, not just +that an API was identified. Do not mark physical acceptance from unit tests. + +## P0 — Instrumentation and two-display proof + +- [ ] T01: Add monotonic startup/input/frame markers, bounded logs and a benchmark + recipe. Establish reference machines/decks and baseline Pympress timings with the + user. Record refresh rates, OS/GPU/backend versions and cold/warm conditions. +- [ ] T02: Build a native presenter shell and separate minimal audience process. + No PDF dependency on shell startup. Implement monitor enumeration/identification, + explicit presenter and audience selection, swapping, fullscreen and emergency blank. +- [ ] T03: Test both assignments on Windows and macOS, then Linux X11 and Wayland + (GNOME/KDE). Add native adapters where required. Verify actual output placement; + an unsupported placement call is a defect, not a completed task. +- [ ] T04: Test mixed DPI, portrait, negative coordinates, differing resolutions, + focus/keyboard operation, reconnect, primary-display changes, sleep/wake and missing + displays. Keep operator content private during every failure and recovery. +- [ ] T05: Implement session-scoped keep-awake leases on all three OSes. Cover idle + system/display sleep and screensaver handling, partial support and error status. + Hold protection while blanked/paused; release after ending presentation and crashes. + +Exit gate: user verifies both roles on all three OSes, with remaining bugs recorded; +no known selection/isolation failure may be called supported. Keep-awake tests must +exceed the configured idle timeout without mouse/keyboard input, with slides visible +and blanked, on AC and battery where available. Test normal sleep resumes after exit. + +## P1 — Bounded workers and first real PDF + +Depends on T02; display testing continues in parallel with implementation work. + +- [ ] T06: Pin compatible GUI/native crates and PDFium builds for Windows/macOS/Linux; + verify checksums, licenses and architecture support. Statically link non-system + dependencies where possible; embed any required runtime assets otherwise. Use the + same executable for internal audience/worker modes, with no runtime downloads. Crate count/build time/package size are not gates. +- [ ] T07: Define/test versioned bounded IPC, frame-buffer ownership and generation + IDs. Build worker startup, cancellation, exit detection, termination/reaping and + retry limits. Prevent stdout/log pipe saturation from blocking a child. +- [ ] T08: Render a first PDF page in a worker; display a preview immediately and + refine to target resolution. Add rotated/cropped/mixed-size synthetic PDF fixtures. + Confirm source files remain byte-for-byte unchanged and failed loads retain the show. +- [ ] T09: Add foreground/neighbor/background priority queues and bounded worker + concurrency. Obsolete jobs must not delay the newest request. Isolate slow storage, + image decoding, notes and cache writes from both native event loops. +- [ ] T10: Add memory/allocation limits, progress deadlines, worker replacement and + backoff. Inject a worker hang, crash, malformed reply and oversized image. Verify + presenter navigation and emergency audience blank remain responsive throughout. + +Exit gate: real PDF opens on all three OSes; first-page and input timing captured; +renderer failures cannot hang either window or silently replace the working slide. + +## P2 — Prepared slides and persistent cache + +Depends on T07–T10; build the format contract before writing persistent cache files. + +- [ ] T11: Specify extraction.json version, SHA-256 identity, renderer/settings keys, + per-page artifacts, geometry and readiness/integrity fields. Add versioned examples + and round-trip/invalid-manifest tests to the interface documentation. +- [ ] T12: Implement progressive lossless extraction, atomic commits, partial-resume, + read-only-sidecar fallback and corrupt-cache regeneration. Hash in background; + never display stale unverified pages to make warm startup look faster. +- [ ] T13: Implement bounded decoded-frame/GPU-texture caches with visible and neighbor + pages pinned. Prepare textures before a slide advance, pause background work under + pressure, and benchmark PNG versus LZ4/raw BGRA and mapped/shared buffers. +- [ ] T14: Add GPU initialization/device/surface failure handling and a validated + softbuffer fallback. Inject failures and verify display assignment survives recovery; + log visible interruptions and cold CPU fallback startup time. +- [ ] T15: Measure rapid next/back, random jumps, large decks, background extraction, + low memory, slow/full disk and missing cache artifacts. Verify bounded resource use, + no busy loops, and cache cleanup touches only owned files. + +Exit gate: prepared navigation and blanking meet the initial budgets on reference +hardware. Record cold first page and warm cache-validation costs honestly. Do not +exclude large/complex deck outliers from results. + +## P3 — Presenter workflow and host recovery + +Depends on usable PDF output and acknowledged displayed-slide state. + +- [ ] T16: Show current/next previews, page selection and keyboard controls. Distinguish + requested/preparing/displayed slides and blank state; keep every dialog on presenter. +- [ ] T17: Extract available notes asynchronously and support explicit notes-page + interpretation/cropping. Validate note-free fallback; never send notes to audience. +- [ ] T18: Preserve audience output and sleep leases when presenter crashes. Reconnect + to the actual displayed state. Detect audience event-loop hangs, restart blanked, + verify destination, then restore prepared content only when safe. +- [ ] T19: Define settings/recovery contracts before persisting display preferences. + Restore state without silently activating a different monitor; handle changed + topology and stale device identities explicitly. +- [ ] T20: Test shutdown/cancel during PDF parsing, hashing, disk writes, portal calls, + worker failure and GPU recovery. No indefinite joins; reap processes and release + owned resources within bounded shutdown paths. + +Exit gate: ordinary presenter work remains responsive under injected faults. Audience +never displays controls, notes or another document due to a late reply or restart. + +## P4 — Performance, resilience and release acceptance + +- [ ] T21: Run at least an eight-hour presentation soak, repeated open/close and + thousands of slide changes, plus long paused/blanked sessions exceeding sleep + timeouts. Track memory/handles, child processes, cache growth and power-lease cleanup. +- [ ] T22: Run fault matrix: stuck PDF calls, unavailable portal, dead D-Bus connection, + GPU loss, full disk, corrupt cache, unplug/replug, suspend/resume, presenter crash, + audience crash and saturation of IPC/log queues. Record recovery time and output. +- [ ] T23: Compare cold/warm startup and visible slide latency against Pympress on + the same corpus/hardware. Fix misses against proposed budgets; review changes with + the user instead of quietly weakening the requirement. +- [ ] T24: Benchmark targeted OS/scheduler/I/O/GPU tweaks only for reproduced issues. + Record before/after numbers, lifetime, privileges, restoration and failed experiments. + Keep useful changes scoped to the presentation and test abnormal-exit restoration. +- [ ] T25: Package runnable artifacts for all three OSes, include icon/backend notices, + verify offline startup on a clean machine and document supported OS/backend versions. + Require a portable executable per OS/architecture with every non-system dependency + bundled: no runtime installer or separately installed PDFium/fonts/toolchain. Audit + dynamic dependencies on each target. Test empty-cache first run, read-only executable + directory, arbitrary paths (spaces/non-ASCII), unavailable extraction cache and copied + binary launch. Verify workers find the executable/assets without relying on cwd. + Include signing/notarization and bundled-library loading checks for macOS; test an + optional .app wrapper as well as the documented portable launch path. + Keep the FreeBSD CI helper/core gates while adding target builds and native checks; + inability to run the GUI on FreeBSD must not remove production coverage silently. +- [ ] T26: Write the user workflow and acceptance record. User retests every unresolved + display, responsiveness and sleep defect. No readiness claim until required OS + matrices, latency evidence and resilience results are recorded. + +Optional later work remains in the plan; it must not displace these release blockers.