Deckstride/docs/development/implementation.md

17 KiB

Implementation choices

Status: implementation direction selected 2026-11-19. The 0.1.3 dual-screen proof now uses winit/softbuffer in one event loop to validate native window behavior. PDF rendering and the production architecture below remain pending. The task list 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.

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 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

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, PDFium progressive API

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

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.

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

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, Windows system commands, Apple sleep assertions, XDG Inhibit, session idle inhibition, and logind inhibitors.

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.