From fa8040c8a2b71d8a04e32413922089c91d144dd6 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Thu, 19 Nov 2026 12:19:39 +0100 Subject: [PATCH] Define hard dual-screen and speed requirements for PDF Presenter --- AGENTS.md | 13 ++- AGENT_DOCUMENTATION.md | 1 + Cargo.lock | 2 +- Cargo.toml | 2 +- README.md | 7 +- docs/changelog.md | 8 ++ docs/development/README.md | 3 +- docs/development/plan.md | 133 ++++++++++++++++++++-------- docs/interfaces/README.md | 3 + docs/interfaces/extraction-cache.md | 33 +++++++ 10 files changed, 161 insertions(+), 44 deletions(-) create mode 100644 docs/interfaces/extraction-cache.md diff --git a/AGENTS.md b/AGENTS.md index 3fe03c5..8003792 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,9 +14,16 @@ 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. Rust/egui -is the starting desktop direction, following Canvas Pilot; validate multiwindow -behavior and renderer/platform support before choosing dependencies. Keep PDF +Keep a single-member workspace. Do not depend on sibling repositories. 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 +display, progressive preparation and measured cold/warm slide latency. Pre-rendered +images and a source-SHA extraction.json sidecar cache are authorized; define its +contract before implementation. Presenter mode requires current/next previews and +notes when extractable, with a current/next-only fallback. Read the plan for acceptance +gates. Rust/egui is a candidate, not a constraint: native APIs, renderer processes or +another window host are acceptable when they satisfy reliability and speed. Keep PDF rendering, document state and display/window management separate without speculative abstractions. Do not copy Pympress or PowerPoint code/assets without license review. diff --git a/AGENT_DOCUMENTATION.md b/AGENT_DOCUMENTATION.md index 713d04b..6074c5c 100644 --- a/AGENT_DOCUMENTATION.md +++ b/AGENT_DOCUMENTATION.md @@ -4,6 +4,7 @@ - [Development](docs/development/README.md) - [Implementation and acceptance plan](docs/development/plan.md) - [CI and Jenkins setup](docs/development/ci.md) +- [Extraction cache design requirements](docs/interfaces/extraction-cache.md) - [Interface policy](docs/interfaces/README.md) - [Artwork provenance](docs/development/icon-prompts.json) - [Changelog](docs/changelog.md) diff --git a/Cargo.lock b/Cargo.lock index d450173..f1b6cd9 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4,4 +4,4 @@ version = 4 [[package]] name = "pdf-presenter" -version = "0.1.0" +version = "0.1.1" diff --git a/Cargo.toml b/Cargo.toml index 3145489..4754757 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,7 +4,7 @@ default-members = ["crates/pdf-presenter"] resolver = "3" [workspace.package] -version = "0.1.0" +version = "0.1.1" edition = "2024" license = "MIT" repository = "https://proxy.dandaedre.com/gitea/idle-org/pdf-presenter" diff --git a/README.md b/README.md index d101f3b..0f1a1ba 100644 --- a/README.md +++ b/README.md @@ -8,9 +8,10 @@ Line coverage

-**Repository foundation — not yet a usable PDF presenter.** The intended application -pairs an operator view with fullscreen audience outputs, inspired by Pympress and -PowerPoint workflows. It is independent of those projects. +**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. 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 e42c303..c9b8edc 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -2,6 +2,14 @@ ## Unreleased +### 0.1.1 + +- Established selectable dual-screen operation on Windows/macOS/Linux as a hard + acceptance gate and presentation speed as the primary performance goal. Prioritized + progressive rendering, reusable source-SHA image caches and current/next previews + with extractable notes. Added physical-display and speed validation requirements; + cache schema and application behavior remain unimplemented. + ### 0.1.0 - Prepared the standalone PDF Presenter repository with a tested navigation/blanking diff --git a/docs/development/README.md b/docs/development/README.md index 0e21eb6..0b48739 100644 --- a/docs/development/README.md +++ b/docs/development/README.md @@ -3,7 +3,8 @@ This is a standalone, single-member Rust workspace. Install Rust with rustfmt, Clippy and llvm-tools-preview, plus Python 3.11+ for CI helpers. The foundation has no third-party Rust dependencies. The desktop and PDF renderer dependencies remain -to be selected and validated. +to be selected against the hard dual-screen requirement on Windows, macOS and Linux +and measured presentation speed; sharing Canvas Pilot's UI stack is optional. - [Implementation and acceptance plan](plan.md) - [Local checks and Jenkins](ci.md) diff --git a/docs/development/plan.md b/docs/development/plan.md index 4251c94..7c619b1 100644 --- a/docs/development/plan.md +++ b/docs/development/plan.md @@ -1,48 +1,111 @@ # Implementation and acceptance plan +## Product requirements — agreed 2026-11-19 + +The goal is a blazingly fast PDF presenter in the spirit of Pympress. Reliability +of the two display roles and presentation speed take precedence over matching the +Canvas Pilot technology stack. This is the implementation brief, not a claim that +these capabilities already exist. + +1. **Dual-screen operation is a hard requirement on Windows, macOS and Linux.** + The operator explicitly selects the display for the presenter view and the display + for the audience presentation. Both roles must work together, including fullscreen + audience output. This is foundational work, not a later enhancement or an optional + platform feature. The user will test iteratively until it works. Do not declare + the application ready with an unresolved display-placement failure on any of the + three operating systems. +2. **Presentation speed is the primary performance goal.** Show a usable first page + as soon as possible and prepare the rest progressively. Pre-rendering pages to + images and keeping them beside the PDF with an `extraction.json` containing source + SHA and extraction metadata is explicitly acceptable. Any practical implementation + technique may be considered for speed, including native platform code, background + workers, renderer subprocesses, disk caches, decoded-image caches, texture preloading + and lower-resolution previews followed by sharper images. Benchmark choices; + avoid committing to a stack solely for consistency with another tool. +3. **Presenter mode must show the current and next slides.** Include notes when they + can be extracted reliably; current/next previews are the required fallback when + notes are absent or unsupported. Notes extraction must not delay presentation or + leak notes onto the audience output. + +The hard reliability requirement is an acceptance gate, not an assertion that an +OS, compositor, GPU or disconnected monitor cannot fail. Handle failures explicitly, +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. + ## Completed foundation — 0.1.0 Independent workspace, source license, app/repository icon, agent instructions, Jenkins pipeline, badge helpers and tests. The presentation core has bounded zero-based navigation and audience blanking, with output initially blanked. -The executable only identifies the project's current status. +The executable only identifies the project's current status. No PDF renderer or +native windows have been implemented; no physical-display acceptance is recorded. -## Next implementation +## Implementation order -1. Validate a PDF renderer and native multiwindow host in a small vertical slice. - Rust/egui is the initial direction for consistency with Canvas Pilot. Evaluate - PDF backend licensing, deployment, text/vector fidelity, page rotation, - password handling, cancellation and availability on Windows, Linux and macOS. - FreeBSD is the existing Jenkins worker, not a promised desktop platform. -2. Load a PDF read-only, render a page, and replace the current document only after - successful loading. Bound image dimensions, prefetch and cache memory. Add small, - synthetic PDF fixtures and real rendering tests. -3. Build an operator window with current/next previews, slide selection, elapsed - timer and keyboard controls. Keep presenter notes private; PDF notes layouts - require an explicit interpretation choice rather than guessing. -4. Add one audience window on an explicitly chosen display, aspect-preserving fit, - fullscreen and blank/unblank. Prove operator/audience isolation. Then extend to - multiple audience displays, initially showing the same slide. -5. Handle display hotplug, mixed DPI and orientation, failed renderer work, changing - documents and orderly shutdown. Persist display preferences only after their - contract and fallback rules are documented. -6. Package each validated platform with app icons and required renderer dependencies, - licenses and reproducible build instructions. Add a user manual when usable - workflows exist; reserve only the pdf-presenter book namespace. +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. -## Decisions before extending scope +## Display acceptance gate -Independent content per display versus mirrored audience outputs, notes layout, -remote control, annotations, embedded media and transitions need separate scope. -PDF is the input target; native PowerPoint/PPTX playback is not implied. No external -network service or presentation-switcher integration is required for the first app. +Record OS/version, window backend (including Linux X11/Wayland), GPU, monitor setup, +app commit, reproduction, result and remaining defects. The user will provide +physical testing; automated tests and headless CI do not establish this acceptance. -## Acceptance still required +For each of Windows, macOS and Linux, verify explicit presenter and audience display +selection, both role assignments, swap, fullscreen exit/re-entry, focus and keyboard +navigation while both windows are active. Cover mixed DPI, differing resolutions, +portrait orientation, negative desktop coordinates and primary-display changes. +Exercise disconnect/reconnect, sleep/wake and missing saved displays. Never place +notes or operator controls on the audience display as a fallback. Keep selection +and blanking stable; report unavailable output and offer reassignment. With only one +available display, offer rehearsal and explain that dual-screen output is unavailable. +No unresolved hard-requirement failure is accepted as a finished implementation. -Unit tests verify navigation, invalid page rejection and blanking. They do not -verify rendered pixels or window placement. Before calling the app usable, run a -real PDF through the chosen backend and inspect rotated/cropped/mixed-size pages. -On every supported OS, exercise two and three displays, mixed DPI, fullscreen, -keyboard focus, output activation, blanking, monitor unplug/replug and load failure. -Record OS/backend versions and observed results. Confirm no operator content ever -appears on an audience output and no source PDF is modified. +## Speed acceptance gate + +Use fixed synthetic and user-approved decks, with simple/vector-heavy/image-heavy +pages, rotations and mixed sizes, plus large decks. Compare equivalent workloads +against Pympress on the same machine, resolution and cache conditions when available. +Record hardware, app/backend versions, deck SHA, display resolution, page count, +cold versus warm cache and test method. Do not infer speed from language choice. + +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 +"blazingly fast" acceptance without recorded measurements and user validation. + +## Scope after the core requirements + +Multiple audience outputs beyond the required pair of presenter/audience roles, +independent decks per display, remote control, annotations, embedded media and +transitions are later scope. Native PPTX playback is not implied. No network service +or presentation-switcher integration is required. Preserve source PDFs and never +show a wrong or stale slide to achieve a lower latency measurement. diff --git a/docs/interfaces/README.md b/docs/interfaces/README.md index 0bcba98..97ef8bc 100644 --- a/docs/interfaces/README.md +++ b/docs/interfaces/README.md @@ -8,3 +8,6 @@ Before introducing persistence, document its location, version, fields, units, precision, validation, omissions and round trips here. Add versioned examples and meaningful tests, and provide migration or explicit unsupported-version handling. Source PDFs always remain unchanged. + +[Extraction cache requirements](extraction-cache.md) describe the authorized +pre-rendered image/`extraction.json` direction; its schema is not implemented yet. diff --git a/docs/interfaces/extraction-cache.md b/docs/interfaces/extraction-cache.md new file mode 100644 index 0000000..dd5c29e --- /dev/null +++ b/docs/interfaces/extraction-cache.md @@ -0,0 +1,33 @@ +# Extraction cache design requirements + +Status: authorized implementation direction, not an implemented file format. +There is no serializer or compatibility promise yet. Before writing caches, specify +and test a versioned `extraction.json` schema with representative fixtures here. + +The user accepts pre-rendered page images stored alongside the PDF and an +`extraction.json` describing source SHA and extraction. Use a separate per-document +cache directory beside the source so unrelated PDFs and existing files cannot collide. +Preserve the PDF. Handle read-only locations with a writable application-cache fallback +and show where extraction is stored; do not make sidecar write access a prerequisite +for presenting. + +The eventual manifest must identify its schema version, source content SHA (prefer +SHA-256), source byte size, renderer/version, rendering settings and page count. +Page entries need source page index, artifact path, dimensions, rotation/crop/notes +interpretation, image format and readiness/integrity information. Define units, +numbering, validation, omissions and invalidation explicitly before implementation. +Source filename, size or modification time alone is not sufficient cache identity. +Render-resolution and backend changes must not accidentally reuse incompatible images. + +Display a newly rendered first page while source hashing/extraction continues. +Do not trust old cache entries until identity and settings validation completes. +Write artifacts and manifest updates atomically, publish only complete page entries, +and tolerate interrupted/partial extraction. Reject malformed manifests, unsupported +versions, unsafe paths and corrupt/missing artifacts; regenerate affected pages +without silently treating stale content as current. Bound disk, decode, RAM and GPU +usage. Priority changes must cancel or supersede obsolete background jobs. + +Cache contents may include document content and speaker notes. Keep them local and +out of Git. Future cleanup must only remove owned cache artifacts, never source PDFs +or unrelated neighboring files. Tests must cover invalidation, interrupted extraction, +read-only locations, collisions, corruption and safe regeneration.