Plan fast resilient portable presenter implementation and acceptance gates
This commit is contained in:
parent
fa8040c8a2
commit
e3bb8082aa
21
AGENTS.md
21
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.
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -4,4 +4,4 @@ version = 4
|
|||
|
||||
[[package]]
|
||||
name = "pdf-presenter"
|
||||
version = "0.1.1"
|
||||
version = "0.1.2"
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue