Deckstride/docs/development/native-implementation.md

12 KiB

Native implementation — 0.1.12 and 0.1.13

The HTML approval is implemented in the native executable. This record supersedes starting-stack proposals in implementation.md; historical acceptance budgets still apply. The user guide describes actual controls and limitations.

Implemented

  • Real PDF and picture-folder loading, natural filename ordering, source preservation, separate annotation/sidecar/global notes extraction after a usable frame exists.
  • Presenter current/previous/next previews, fitted notes, elapsed/HH:MM widgets, independent visibility/sizes, project/global saves and hidden-bar recovery.
  • Digit+Enter jumps; independent windowed, virtualized slide browser with preview sizing, selected/current distinction, explicit Show selected and optional click-live.
  • N-monitor role groups, mirroring, group swap, fullscreen defaults, standard-location global preferences, missing-monitor fallback and runtime operator-screen privacy hold.
  • Independent presentation process with acknowledged frame submission, blanking, neighbour preloading, heartbeat supervision and bounded blanked restarts. Last frame survives presenter failure. Slow work is isolated from both native event loops.
  • Same-executable workers for rendering, notes, dialogs, config and frame reads; bounded pipes and deadlines, source generations, foreground supersession, corruption checks and atomic cache/settings writes. Frame memory and image decodes are bounded.
  • Process-scoped keepawake leases; X11 screensaver/DPMS fallback with explicit partial support reporting. Idle scheduling avoids unconditional frame rendering.

Implementation choices

Hayro 0.9 is bundled as the PDF renderer instead of the initially proposed PDFium. Image 0.25 provides the enabled codecs. No external renderer, fonts download or runtime extraction/install step is needed. egui 0.34 controls are composed through egui_software_backend/softbuffer, using cached meshes/textures and damage handling. The minimal output process only receives raw frames and display/blank state, never operator notes or menus. This establishes a software rendering baseline; it does not claim GPU-level throughput at every resolution.

0.1.13 replaces neighbour-only caching with whole-deck preparation and RAM residency. A cold 512-pixel preview precedes screen-sized frames; warm verified full-size cache hits skip that preview. Two workers fill the complete deck, and the independent output acknowledges its own complete RAM buffer before READY. Small-screen outputs share the largest screen-sized variant (4096-pixel cap). Progress, cache reuse, RAM usage, approximate ETA and memory-pressure pause are explicit in the presenter. No application slide-file reads, decoding or rasterization occur on prepared navigation. OS paging can still occur; configuring enough available physical RAM remains necessary.

The default decoded budget is 1024 MiB per process, adjustable in Menu. Insufficient capacity pauses rather than evicts and never reports READY. Worker/texture memory is additional. See cache, settings and private IPC.

The original single-process mock remains available through --display-proof for window-management comparison. It is not the default native presenter.

Validation evidence, 2026-11-19

Local Linux/X11, kernel 7.3.1-1-cachyos, Intel i5-8500, rustc 1.100.0. Checks include real synthetic PDF pages/annotations and picture folders, notes precedence and errors, settings round trips/invalid versions, checksum corruption/regeneration, stale/failed loads, a deliberately stuck worker terminated and replaced, native presenter/browser smoke, and an independent output host displaying two frames, blanking and exiting. Headless egui checks cover widget visibility/sizing, notes, menus and virtualized grids. A regression prevents operator-screen loss from moving notes onto a previous output.

Formatting, warnings-denied Clippy/rustdoc, workspace tests and Python helper tests pass (33 Rust tests and 10 Python tests). Whole-application line coverage is 84.30%, above the 75% floor. No production code is excluded. Xvfb is unavailable here, so native checks used the available X11 session; the existing CI wrapper still requires Xvfb. These tests do not establish physical monitor placement or projector acceptance.

Release builds for Linux x86_64 and Windows x86_64 GNU succeed. macOS aarch64 passes cross-target cargo check; this is not a macOS linked binary or runtime test. Windows import inspection lists only OS DLLs, with no separate PDF/codec/runtime DLL. Linux ELF imports libc, libm, libgcc_s and the loader; X11/Wayland client libraries are loaded as platform services. Offline clean-machine checks remain a release gate. --licenses embeds dependency/font notices generated by scripts/notices.py.

A single release-worker timing sample on a local 3-page PDF (114985 bytes, SHA-256 349a1307cef3f475c28ab269d9ddbebec8d88b1a2dfbab6815e876b027afc88b):

Operation Worker round trip
Open/identify 5.1 ms
First page, 1280 edge, empty cache 53.2 ms
First page refinement, 2560 edge 114.8 ms
Next page, 1280 edge 33.3 ms
Warm cached first page, 1280 edge 38.7 ms

This includes pipe transfer to the measurement process, not optical display latency. One sample under concurrent build load is diagnostic evidence, not a p95/worst-case benchmark or comparison against Pympress. The source PDF remains untracked and unchanged.

Remaining acceptance and hardening

  • User physical Windows/macOS/Linux X11/Wayland matrix: routing, swap, mixed DPI, negative coordinates, mirror groups, browser destination, hotplug and compositor policies. Identical monitor names currently use occurrence-based identity.
  • Repeated cold/warm startup and optical input-to-visible latency, complex/large PDF fidelity, low memory/slow/full disk, maximum-resolution/multi-output stress.
  • Idle-timeout, AC/battery, blank-state and crash-release sleep checks on each OS.
  • Automatic reconnect to an orphan output host; Windows worker memory job limits; per-output process isolation where one display driver can stall a shared host.
  • Automatic disk cache quota/eviction and an unwritable-cache memory fallback. Current disk cache needs manual cleanup while closed; failures retain prior output.
  • Explicit slide/notes-region cropping for notes-page PDFs, broader bundled CJK font coverage and pathological notes-layout latency. Current PDF notes are annotation Contents, not inferred speaker text embedded as page graphics.
  • Clean-machine portable package, platform minimum-version, signing/notarization and macOS native build/runtime validation. No new binaries have been published remotely.

These remain visible release gates; native workflow implementation is not a claim that the hard multiscreen/performance requirements have already been accepted.

0.1.13 preparation regression evidence

New tests prepare eight slides, reopen the same persistent cache without rewriting artifacts or generating an unnecessary 512-pixel preview, then delete both source and processed files before random navigation. Both the presenter-state test and the independent native output-host test continue from resident frames. Additional tests cover resolution-generation invalidation, output acknowledgment readiness, budget pause/resume without eviction and backward-compatible settings defaults. This is application I/O evidence, not an optical latency or OS-page-locking claim.

Validation for 0.1.13: 37 Rust tests (including native window/output tests), 10 Python helper tests, formatting and warnings-denied Clippy/rustdoc pass. The whole-application coverage is 84.42% (75% floor), with no production exclusions. Linux and Windows release artifacts are rebuilt, and macOS aarch64 is compile-checked. The native presenter was visually inspected with the local PDF and showed all three slides buffered in RAM. Navigating the previous buffered show while a new load fails is also regression-tested.

0.1.14 presenter workflow

Menu is an anchored dropdown with Appearance and Preferences submenus. Displays uses numbered screen cards and direct role selection. The independent windowed slide browser requests topmost placement/focus; reopening restores/focuses it. Output is enabled by default on successful document open, with a globally saved opt-out. Emergency/topology blanking still applies, and NO OUTPUT DISPLAYED is explicit even with a hidden footer. Appearance contains all 20 Canvas Pilot built-in palettes and System/English/French. Additional languages and external packs remain unimplemented; worker/OS diagnostics are preserved verbatim. This repository remains standalone.

Validation on the available Linux/X11 desktop: real pointer clicks opened All slides, its Close control, the compact dropdown and display cards. A separate release run loaded persisted French/Corporate Light preferences and auto_show=false, showing the red output indicator and translated warning. The test harness had to raise its app before synthetic pointer delivery; input sent to another foreground window was not an application failure. Temporary preferences/cache and owned test processes were cleaned up. This is local GUI evidence, not acceptance of the multi-OS physical matrix.

41 Rust tests, including native smoke/output and new pointer-dispatch/default-output regressions, and 10 Python tests pass. Formatting, Clippy/rustdoc with warnings denied, and macOS aarch64 compile-check pass. Whole-application coverage is 82.73% (75% floor), without production exclusions. Linux and Windows x86_64 release builds succeed. Windows/macOS runtime validation remains open.

0.1.15 Windows chooser correction

The reported Windows dialog was unowned because rfd ran in a worker without the presenter's HWND. Repeated Open actions were also admitted into the four-entry worker queue. The worker now receives the active presenter HWND and uses it as the common dialog owner, retaining the killable-worker design. A shared outstanding-request guard prevents queuing, and native completion restores owner input/focus even after timeout.

44 Rust tests and 10 Python tests pass. The new controlled-transport regression sends 100 alternating PDF/folder requests, verifies exactly one admission and no delayed reopening after cancellation, then tests explicit retry, selection, worker error, timeout and submission failure. Windows x86_64 release compilation and macOS aarch64 compile-check pass; Windows fullscreen/modal placement requires user runtime retest. Formatting and warnings-denied Clippy/rustdoc pass. Whole-app coverage is 82.88% with no production exclusions. An initial coverage run failed to merge a corrupted worker profile; a fresh full run passed. Linux release is rebuilt for the shared admission fix.

0.1.16 output lifecycle correction

The output Close handler previously only blanked, even after the presenter pipe closed. The native host now observes receiver disconnection and accepts Close/Escape as exit when orphaned, while retaining crash-time last-frame preservation until then. Normal presenter exit, event-loop errors and OutputLink destruction all shut down the owned host. A separate shared process handle permits termination/reaping even when the supervisor is blocked writing a large state into an unread pipe.

Regression tests fill a fake output's pipe and verify both shutdown and Drop reap it within two seconds. Native Linux/X11 tests create real output windows, disconnect the parent pipe, verify the process remains alive, then send WM_DELETE_WINDOW or Escape and verify clean exit without force-kill. Test guards kill only on failure or cleanup. These checks do not establish Windows/macOS physical acceptance.

46 Rust tests and 10 Python tests pass, including the native window/output tests. Formatting, warnings-denied Clippy/rustdoc and macOS aarch64 compilation pass. Whole-application coverage is 83.97%, with no production exclusions. Linux and Windows x86_64 release builds succeed. Runtime retesting on Windows remains necessary for the reported platform behavior.