Deckstride/docs/development/tasks.md

176 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Implementation task list
0.1.12 implements the approved native workflow; see [implementation evidence and
remaining acceptance](native-implementation.md). The historical tasks below include
broader production hardening and release gates. Unchecked items may be partially
implemented; they are not claims that the native app is absent. Physical acceptance
is deliberately separate from code completion.
Implemented portions: T02 native/mirrored roles and independent output; T05 leases;
T06 bundled renderer/codecs (Hayro replaces PDFium); T07 bounded pipes; T08 real PDFs;
T08a folders; T09 priorities; T10 worker deadlines; T11/T12 verified atomic caches;
T13 bounded decoded cache; T14 software composition; T16 approved presenter/browser
workflow; T17 asynchronous annotation/sidecar notes; T18 last-frame crash hold and
blanked output-host restart. T01 full latency instrumentation, T15 disk quota,
T17 explicit notes-region crop, T18 reconnect, platform acceptance and clean-machine
release checks remain open. Do not mark their broader acceptance from this code alone.
0.1.13 adds whole-deck processed-frame reuse and RAM preparation to T09/T12/T13:
two workers, screen-derived resolution, cache-first opening, retained complete buffers,
explicit preparation progress/ETA and memory-pressure pause. T01's full optical
latency matrix and T15's persistent disk quota remain open.
0.1.19 replaces the memory-pressure pause with bounded rolling eviction, while
retaining full RAM residency when the deck fits. Processed-page progress is separate
from current residency; cached slides reload through workers after eviction.
## 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.
Default both roles to fullscreen; retain explicit windowed rehearsal.
Support several monitors per role (e.g. presenter 1+2, presentation 3, or vice versa).
One role per monitor; shared slide/blank/navigation state across mirrored views.
Preserve surviving assignments and isolate each output's rendering/backpressure.
- [ ] 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.
- [ ] 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.
- [ ] 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.
Let the speaker independently show/hide and resize previous/current/next previews, notes,
elapsed time and local HH:MM time. Hidden widgets reclaim space.
Header/footer can be hidden independently and recovered by edge hover or right-click;
persist pinned visibility with project/global layouts, not temporary reveals.
Provide explicit project and all-project saves; project layouts override the global
default, with an action to remove the current project override. Keep complete
notes fitted, and persist layout visibility/sizes in the global settings contract.
Review the [interactive layout concept](../design/presenter-menu.html) before implementation.
Add digit-buffer + Enter direct slide navigation (1-based), with visible pending
number, Backspace editing, Escape cancellation and range checks; preserve blanking.
Add a separate windowed all-slides browser with adjustable thumbnail size and
Change on click disabled by default. Selection and live slide are separate; provide
explicit Show selected. Place it on a chosen monitor or presenter by default,
falling back to presenter if missing. Bound/virtualize thumbnail loading.
- [ ] T17: Extract available notes asynchronously and support explicit notes-page
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.
- [ ] 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.