194 lines
12 KiB
Markdown
194 lines
12 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.
|
|
|
|
|
|
## 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.
|