Plan fast resilient portable presenter implementation and acceptance gates

This commit is contained in:
Dandaedre 2026-11-19 14:40:17 +01:00
parent fa8040c8a2
commit e3bb8082aa
10 changed files with 400 additions and 34 deletions

View File

@ -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.

View File

@ -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)

2
Cargo.lock generated
View File

@ -4,4 +4,4 @@ version = 4
[[package]]
name = "pdf-presenter"
version = "0.1.1"
version = "0.1.2"

View File

@ -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"

View File

@ -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

View File

@ -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

View File

@ -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.

View File

@ -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.

View File

@ -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

129
docs/development/tasks.md Normal file
View File

@ -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.