From 173d7521904c4ae5162d67007c7f57e7f23b0891 Mon Sep 17 00:00:00 2001
From: Dandaedre
Date: Thu, 19 Nov 2026 16:09:11 +0100
Subject: [PATCH] Default both views to fullscreen and plan image-folder notes
---
AGENTS.md | 6 +++-
AGENT_DOCUMENTATION.md | 2 ++
Cargo.lock | 2 +-
Cargo.toml | 2 +-
README.md | 8 +++---
crates/pdf-presenter/src/main.rs | 4 +--
crates/pdf-presenter/src/paint.rs | 2 +-
crates/pdf-presenter/src/poc.rs | 6 ++--
crates/pdf-presenter/tests/poc.rs | 15 +++++-----
docs/changelog.md | 11 ++++++++
docs/development/dual-screen-poc.md | 11 ++++----
docs/development/implementation.md | 16 +++++++++++
docs/development/plan.md | 12 ++++++--
docs/development/tasks.md | 12 +++++++-
docs/interfaces/README.md | 2 ++
docs/interfaces/picture-folders.md | 44 +++++++++++++++++++++++++++++
16 files changed, 126 insertions(+), 29 deletions(-)
create mode 100644 docs/interfaces/picture-folders.md
diff --git a/AGENTS.md b/AGENTS.md
index 4ab0254..a27c433 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -27,7 +27,11 @@ it works. Presentation speed is the primary performance goal: prioritize first-p
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
+notes when extractable, with a current/next-only fallback. Both windows default to
+fullscreen. Also support picture folders in natural filename order, matching `.txt`
+notes or global `notes.json`/`notes.toml`. Always fit the full presenter notes to the
+available pane using wrapping and font sizing; recompute on resize/DPI/content changes.
+These folder/notes requirements remain planned, not implemented in the mock proof. 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
diff --git a/AGENT_DOCUMENTATION.md b/AGENT_DOCUMENTATION.md
index 04e58ad..24da6f8 100644
--- a/AGENT_DOCUMENTATION.md
+++ b/AGENT_DOCUMENTATION.md
@@ -13,3 +13,5 @@
- [Implementation choices and performance budgets](docs/development/implementation.md)
- [Dual-screen proof: run, controls and acceptance](docs/development/dual-screen-poc.md)
+
+- [Picture folders and notes requirements](docs/interfaces/picture-folders.md) (planned).
diff --git a/Cargo.lock b/Cargo.lock
index 1f24ecc..44b7e4e 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -921,7 +921,7 @@ dependencies = [
[[package]]
name = "pdf-presenter"
-version = "0.1.4"
+version = "0.1.5"
dependencies = [
"font8x8",
"softbuffer",
diff --git a/Cargo.toml b/Cargo.toml
index ca50389..f4de6b0 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -4,7 +4,7 @@ default-members = ["crates/pdf-presenter"]
resolver = "3"
[workspace.package]
-version = "0.1.4"
+version = "0.1.5"
edition = "2024"
license = "MIT"
repository = "https://proxy.dandaedre.com/gitea/idle-org/pdf-presenter"
diff --git a/README.md b/README.md
index dcf9ac0..5fbaed0 100644
--- a/README.md
+++ b/README.md
@@ -8,10 +8,10 @@
-**Dual-screen proof of concept:** native presenter controls and fullscreen mock
-slides on the secondary display. With one display it opens two windowed rehearsal
-views. PDF loading, notes, sleep inhibition and production fault isolation are not
-implemented yet.
+**Dual-screen proof of concept:** both windows start fullscreen, with presenter
+controls on the primary display and mock slides on the secondary. Use `--windowed`
+for single-display rehearsal (otherwise the views overlap). PDF/image-folder loading,
+notes, sleep inhibition and production fault isolation are not implemented yet.
```sh
cargo run --locked -p pdf-presenter
diff --git a/crates/pdf-presenter/src/main.rs b/crates/pdf-presenter/src/main.rs
index fd0edad..6f4a64f 100644
--- a/crates/pdf-presenter/src/main.rs
+++ b/crates/pdf-presenter/src/main.rs
@@ -14,8 +14,8 @@ fn main() {
Usage: pdf-presenter [--presenter N] [--audience N] [--windowed]\n\
pdf-presenter --list-monitors\n\
pdf-presenter --smoke-test\n\
-Default: presenter on primary, fullscreen mock output on secondary.\n\
-One display: two windowed rehearsal views. Display numbers start at 1.\n\
+Default: both fullscreen; presenter on primary, mock output on secondary.\n\
+One display: views overlap; use --windowed for rehearsal. Display numbers start at 1.\n\
Keys: arrows/space slides, B blank, S swap, P/A cycle displays,\n\
F audience fullscreen, V presenter fullscreen, Esc safe windowed mode,\n\
R refresh displays, Q quit. No PDF loading or sleep inhibition yet.",
diff --git a/crates/pdf-presenter/src/paint.rs b/crates/pdf-presenter/src/paint.rs
index 4d249c9..beff4a7 100644
--- a/crates/pdf-presenter/src/paint.rs
+++ b/crates/pdf-presenter/src/paint.rs
@@ -225,7 +225,7 @@ pub fn draw(
let message = if model.disconnected {
"DISPLAY CHANGE: OUTPUT HIDDEN. R TO REFRESH."
} else if model.displays.len() == 1 {
- "ONE DISPLAY: WINDOWED REHEARSAL ONLY"
+ "ONE DISPLAY: BOTH VIEWS SHARE THIS DISPLAY"
} else if model.blanked {
"AUDIENCE BLANKED - B TO SHOW MOCK SLIDE"
} else {
diff --git a/crates/pdf-presenter/src/poc.rs b/crates/pdf-presenter/src/poc.rs
index ae6cd04..8b7d740 100644
--- a/crates/pdf-presenter/src/poc.rs
+++ b/crates/pdf-presenter/src/poc.rs
@@ -82,7 +82,7 @@ impl Model {
if displays.len() > 1 && presenter == audience {
return Err("Choose different presenter and audience displays.".into());
}
- let fullscreen = !windowed && displays.len() > 1;
+ let fullscreen = !windowed;
Ok(Self {
displays,
presenter,
@@ -90,7 +90,7 @@ impl Model {
page: 0,
blanked: false,
fullscreen,
- presenter_fullscreen: false,
+ presenter_fullscreen: fullscreen,
disconnected: false,
})
}
@@ -186,7 +186,7 @@ pub struct Options {
pub presenter: Option,
/// Audience display override.
pub audience: Option,
- /// Keep the audience window decorated instead of fullscreen.
+ /// Keep both windows decorated instead of fullscreen.
pub windowed: bool,
/// Exercise the real native windows and exit automatically.
pub smoke: bool,
diff --git a/crates/pdf-presenter/tests/poc.rs b/crates/pdf-presenter/tests/poc.rs
index 8ab93ab..29130b5 100644
--- a/crates/pdf-presenter/tests/poc.rs
+++ b/crates/pdf-presenter/tests/poc.rs
@@ -30,16 +30,15 @@ fn model() -> Model {
fn defaults_use_primary_and_a_distinct_secondary() {
let m = model();
assert_eq!((m.presenter, m.audience), (1, 0));
- assert!(m.fullscreen);
+ assert!(m.fullscreen && m.presenter_fullscreen);
assert!(!m.blanked); // Explicit mock-output launch; real PDF activation remains separate.
let one = Model::new(vec![displays()[0].clone()], 0, None, None, false).unwrap();
- assert!(!one.fullscreen);
+ assert!(one.fullscreen && one.presenter_fullscreen);
assert_eq!((one.presenter, one.audience), (0, 0));
- assert!(
- !Model::new(displays(), 0, Some(2), Some(1), true)
- .unwrap()
- .fullscreen
- );
+ let windowed = Model::new(displays(), 0, Some(2), Some(1), true).unwrap();
+ assert!(!windowed.fullscreen && !windowed.presenter_fullscreen);
+ let one_windowed = Model::new(vec![displays()[0].clone()], 0, None, None, true).unwrap();
+ assert!(!one_windowed.fullscreen && !one_windowed.presenter_fullscreen);
assert_eq!(
Model::new(displays(), 99, None, None, false)
.unwrap()
@@ -82,6 +81,8 @@ fn controls_bound_navigation_and_keep_display_roles_separate() {
m.apply(Action::Fullscreen);
assert!(!m.fullscreen);
m.apply(Action::PresenterFullscreen);
+ assert!(!m.presenter_fullscreen);
+ m.apply(Action::PresenterFullscreen);
assert!(m.presenter_fullscreen);
m.apply(Action::Escape);
assert!(m.blanked && !m.fullscreen && !m.presenter_fullscreen);
diff --git a/docs/changelog.md b/docs/changelog.md
index 3a9bd26..af5086a 100644
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -2,6 +2,17 @@
## Unreleased
+### 0.1.5
+
+- Default both presenter and audience windows to fullscreen on every platform;
+ `--windowed` keeps both decorated, including single-display rehearsal.
+- Record planned picture-folder slides in natural filename order, sidecar/global
+ JSON/TOML notes, and complete notes fitted to the available presenter pane.
+ Folder loading and notes layout remain unimplemented in this display proof.
+- Validation: 16 Rust tests including native smoke, formatting, Clippy/rustdoc,
+ 10 Python tests, 88.92% whole-application coverage and Linux release build.
+ Physical dual-screen startup verification remains pending.
+
### 0.1.4
- Narrow Linux/X11 fix for mock-window swap/fullscreen transitions: stop resetting
diff --git a/docs/development/dual-screen-poc.md b/docs/development/dual-screen-poc.md
index 054d33c..78b5960 100644
--- a/docs/development/dual-screen-poc.md
+++ b/docs/development/dual-screen-poc.md
@@ -1,8 +1,8 @@
-# Dual-screen proof of concept — 0.1.3
+# Dual-screen proof of concept — 0.1.5
This is a runnable native-window test with mock slides. It opens the presenter on
-the primary/default display and a borderless fullscreen audience window on a distinct
-secondary display. Nothing is loaded from a PDF. Launching this specific test
+the primary/default display and the audience on a distinct secondary display.
+Both windows start fullscreen by default; `--windowed` disables fullscreen for both. Nothing is loaded from a PDF. Launching this specific test
explicitly activates mock output; the production document model still starts blanked.
## Run and test
@@ -23,7 +23,8 @@ cargo run --locked -p pdf-presenter -- --presenter 1 --audience 2
cargo run --locked -p pdf-presenter -- --windowed
```
-With one detected display, both views open side-by-side in windowed rehearsal mode.
+With one detected display, fullscreen views overlap. Use `--windowed` to open
+both views side-by-side for rehearsal, or Escape to leave fullscreen and blank output.
That is not a successful two-display acceptance test. With multiple displays, choosing
the same one for both roles is rejected. When the backend has no primary-display
concept (notably Wayland), the first enumerated display is the default; use explicit
@@ -52,7 +53,7 @@ position or resolution suspends/hides output until refresh. Polling happens ever
## Physical acceptance to perform
On Windows, macOS and Linux, connect two displays in extended-desktop mode. Confirm
-the presenter appears on primary and the audience fullscreen on secondary. Advance,
+both views start fullscreen, presenter on primary and audience on secondary. Advance,
blank/unblank, swap roles, then explicitly select each destination. Verify focus,
Escape, return to fullscreen, and exit. Repeat with mixed DPI and portrait/negative
coordinates. Unplug/replug the secondary display and test R to recover. Record OS,
diff --git a/docs/development/implementation.md b/docs/development/implementation.md
index 3a56798..abfcc49 100644
--- a/docs/development/implementation.md
+++ b/docs/development/implementation.md
@@ -6,6 +6,22 @@ to validate native window behavior. PDF rendering and the production architectur
below remain pending. The [task list](tasks.md) owns execution order and evidence. Choices below
are engineering decisions to validate, not measured claims about an existing app.
+## Image folders and presenter notes
+
+Accept picture folders alongside PDFs, feeding the same bounded slide pipeline.
+Enumerate and naturally sort filenames in a worker; decode the first ordered image
+before decoding the rest. Do not progressively reorder a live deck as enumeration
+finishes. Keep folder enumeration, decoding and notes reads off both UI event loops.
+Use bundled codecs; see the [planned input contract](../interfaces/picture-folders.md).
+
+For presenter notes, measure wrapped text in the actual available pane and choose the
+largest font size that fits all content in both dimensions. Break long unbroken words
+when necessary. Recompute on slide/text, pane size, font or DPI changes; cache layouts
+by those inputs. Never truncate, clip or require scrolling to read the complete note.
+Use bounded layout search and asynchronous preparation for large notes so navigation
+stays responsive. A zero-area pane cannot show text: retain notes and recompute as
+soon as space is available. No notes implementation exists in the mock proof yet.
+
## Optimization priorities
Correct dual-screen output, fast startup, bounded input latency and resilience are
diff --git a/docs/development/plan.md b/docs/development/plan.md
index bfc66a9..54a6278 100644
--- a/docs/development/plan.md
+++ b/docs/development/plan.md
@@ -9,8 +9,8 @@ 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
+ for the audience presentation. Both roles start fullscreen by default, with an
+ explicit windowed mode for rehearsal/troubleshooting. 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.
@@ -25,7 +25,13 @@ these capabilities already exist.
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.
+ leak notes onto the audience output. Always fit all presenter notes to the available
+ notes pane, recalculating wrapping and font size on content, pane and DPI changes.
+4. **Picture folders are also slide sources.** Order images by natural filename
+ ordering (for example, slide_2 before slide_10). Support matching `.txt` notes
+ (such as `slide_01.txt`) and global `notes.json` or `notes.toml`. The planned
+ [folder and notes contract](../interfaces/picture-folders.md) defines the direction;
+ folder loading and notes layout are not implemented in the mock proof.
The hard reliability requirement is an acceptance gate, not an assertion that an
OS, compositor, GPU or disconnected monitor cannot fail. Handle failures explicitly,
diff --git a/docs/development/tasks.md b/docs/development/tasks.md
index b9a53ad..0a3c944 100644
--- a/docs/development/tasks.md
+++ b/docs/development/tasks.md
@@ -15,6 +15,7 @@ that an API was identified. Do not mark physical acceptance from unit tests.
- [ ] 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.
+ Default both roles to fullscreen; retain explicit windowed rehearsal.
- [ ] 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.
@@ -44,6 +45,10 @@ Depends on T02; display testing continues in parallel with implementation work.
- [ ] 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.
+- [ ] T08a: Add picture-folder sources with natural filename ordering and progressive
+ worker decoding. Finalize the [folder contract](../interfaces/picture-folders.md)
+ with fixtures for numeric names, ties, unsupported/corrupt images and slow storage.
+ Share the PDF slide pipeline, cancellation, caches and portable codec requirements.
- [ ] 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.
@@ -85,7 +90,12 @@ 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.
+ interpretation/cropping. Load image sidecar `.txt` notes and global `notes.json` or
+ `notes.toml`; test precedence, invalid files and missing notes. Always word-wrap and
+ size the complete notes to fit their pane without clipping or requiring scrolling.
+ Test long notes, long unbroken words, Unicode, resize and mixed DPI; keep layout
+ responsive and bundle required fonts. 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.
diff --git a/docs/interfaces/README.md b/docs/interfaces/README.md
index 97ef8bc..85cad06 100644
--- a/docs/interfaces/README.md
+++ b/docs/interfaces/README.md
@@ -11,3 +11,5 @@ 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.
+
+- [Picture folders and notes requirements](picture-folders.md) (planned).
diff --git a/docs/interfaces/picture-folders.md b/docs/interfaces/picture-folders.md
new file mode 100644
index 0000000..a474cfc
--- /dev/null
+++ b/docs/interfaces/picture-folders.md
@@ -0,0 +1,44 @@
+# Picture folders and notes — planned input contract
+
+Status: requirements and initial implementation choices, not an implemented format.
+Finalize schemas, examples and validation tests before shipping folder loading.
+
+## Slides
+
+Read supported pictures from the selected folder without changing source files.
+Initially use its immediate files, not recursive traversal. Natural filename ordering
+is mandatory: compare digit runs numerically (`slide_2` before `slide_10`), without
+integer overflow. Use deterministic, locale-independent text comparison and an exact
+filename tie-break for equal numeric values (`slide_1`, `slide_01`). Specify case and
+Unicode rules and supported bundled codecs in the final contract and fixtures.
+
+Freeze the ordered file list before showing its first slide; decode images
+progressively in bounded workers. Folder scans must not block input. Failed imports
+retain the working deck; corrupt/missing images must never silently renumber slides.
+Preserve filenames and source bytes. Define source identity/cache invalidation for
+folder images independently of the PDF extraction manifest before implementing caches.
+
+## Notes
+
+Support UTF-8 matching-stem sidecars: `slide_01.png` uses `slide_01.txt`.
+Also support one folder-level `notes.json` or `notes.toml`, keyed by exact image
+filename rather than slide number, so natural sorting does not change associations.
+Initial choice: a present sidecar overrides the global entry, including an empty
+sidecar intentionally clearing that slide's notes. Missing entries mean no notes.
+If both global formats exist, require an explicit selection instead of silently
+combining conflicting files. Malformed notes produce a presenter-only diagnostic;
+notes parsing must not prevent showing a valid slide. Finalize the global schema,
+size/encoding validation and ambiguous matching-stem behavior with examples/tests.
+
+Always fit the complete current note inside the available presenter notes area using
+wrapping and automatic font sizing, updating on content, resize and DPI changes.
+Do not silently truncate, clip or require scrolling. Keep layout work bounded and
+responsive. Notes and their errors must never reach the audience output.
+
+## Acceptance
+
+Test natural ordering (including leading zeros and very long digit runs), Unicode
+names, both global formats, sidecar precedence, empty/missing/invalid notes, corrupt
+images and read-only/slow folders. Test short/long notes, unbroken strings and pane
+resize/DPI changes. Verify first-image latency and navigation while remaining images
+and notes load, and confirm original files remain unchanged.