Deckstride/docs/development/native-implementation.md

128 lines
8.0 KiB
Markdown

# 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](../user-guide.md) 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](../interfaces/extraction-cache.md),
[settings](../interfaces/settings.md) and [private IPC](../interfaces/process-protocol.md).
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.