Define hard dual-screen and speed requirements for PDF Presenter
This commit is contained in:
parent
4fb3333cf5
commit
fa8040c8a2
13
AGENTS.md
13
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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -4,4 +4,4 @@ version = 4
|
|||
|
||||
[[package]]
|
||||
name = "pdf-presenter"
|
||||
version = "0.1.0"
|
||||
version = "0.1.1"
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -8,9 +8,10 @@
|
|||
<img src="https://assets.dandaedre.com/coverage/idle-org/pdf-presenter/main/coverage.svg" alt="Line coverage">
|
||||
</p>
|
||||
|
||||
**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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
Loading…
Reference in New Issue