Deckstride/docs/interfaces/process-protocol.md

14 KiB
Raw Blame History

Private same-executable process protocol

0.1.12 uses anonymous stdin/stdout pipes, with no listening ports or public endpoint. Roles are --worker, --presentation-host, --keep-awake; only the parent-created pipe handles connect them. They must use the same executable build. This is an internal unversioned wire protocol, not a stable external API; mixed builds are unsupported. Persistent disk representations have independent version contracts.

Messages are little-endian u32 byte length followed by UTF-8 JSON (16 MiB maximum). Worker replies declare bytes; frame pixels follow as raw RGBA8, at most 64 MiB, validated against returned dimensions. No payload is allowed without frame metadata. Open/render carry generation epochs; supervisor completions retain generation and job tags so stale results cannot replace a newer document. Notes are requested separately. Settings, file pickers and cached-frame reads also run in workers.

Supervisors bound command/result queues, kill/reap on deadlines, and recreate failed workers on the next job. Foreground/background deadlines are 30 s, settings/cache reads 10 s, native chooser 300 s. Linux workers die with the parent; Unix workers attempt a 3 GiB address-space limit. Windows memory job limits remain outstanding. No worker I/O or process wait is performed in a rendering/input callback.

Presentation HostState contains sequence, page, verified frame paths, neighbour preloads, monitor IDs, fullscreen and blank flags. It contains no notes or operator UI text. ACKs report only frames submitted successfully to all active output windows; this is not optical proof that a projector displayed a frame. Heartbeats detect a stopped host after 8 s; at most three starts, recovery preserves the presenter’s output visibility. A presenter crash leaves the independent host displaying its last frame. Normal exit sends quit and allows bounded shutdown outside the UI loop. Reconnection to an orphan is pending.

Whole-deck buffering in 0.1.13

Preview requests first check the verified target-resolution artifact, falling back to 512 only on a miss. Replies identify the actual requested render edge and cache-hit status. The two workers prepare the remaining deck concurrently with foreground navigation able to supersede outstanding work.

HostState now carries a document/resolution generation, decoded RAM budget and the currently resident target-frame preload list. Since 0.1.19 the host mirrors this working set, retires evicted entries and discards stale read completions. It can free distant cached frames to admit a replacement while protecting the displayed and requested frames. Its acknowledgment counts actual resident entries for that generation, rather than all previously processed slides. READY requires both presenter and host counts to reach the deck total. Stale acknowledgments cannot mark another resolution ready. The bounded JSON envelope and raw-frame limits remain unchanged. This protocol still requires the same executable build at both ends.

File chooser ownership and admission, 0.1.15

Pick carries folder and optional owner (a signed native Windows HWND integer; null on other platforms). This identifier belongs to the parent presenter process, is never dereferenced as worker memory, and is passed to the Windows common dialog as its owner. Only the active presenter (or first available presenter) supplies it; an audience window is never the owner. Windows requests without an owner fail clearly. The protocol remains private and requires matching executable builds.

The shared Studio admits exactly one outstanding chooser job, including across mirrored presenters and alternating PDF/folder requests. Repeated Open actions are ignored and the corresponding menu controls are disabled until a completion arrives. Success, cancellation, worker error and the existing 300-second deadline all release the guard; submission failure never sets it. The native host re-enables presenter input and restores owner focus after completion, including a worker killed while the common dialog had disabled its owner. Existing slide-browser windows temporarily lose topmost status while the chooser is active. Rendering/output stay independent.

Output shutdown and lost presenter, 0.1.16

No wire fields change. EOF/failed input drops the host command sender; the native host detects receiver disconnection instead of treating it as an empty queue forever. An established output keeps its last frame after unexpected connection loss, while Close or Escape requests exit on the next event-loop tick. A disconnected host with no windows exits immediately. B still blanks. With a live presenter, output Close retains emergency blanking, but Escape never blanks (since 0.1.72). It can still revert a pending display trial. Focus-transfer synthetic key presses are ignored.

Normal presenter shutdown signals the supervisor and allows 500 ms for graceful completion, then terminates/reaps the owned child through a separate shared process handle. The handle is never locked during pipe writes, so a blocked writer cannot prevent termination. A further one-second manager completion wait is bounded. Event-loop errors and OutputLink destruction use this cleanup path as well. OS process termination/reaping still relies on OS responsiveness; these bounds are not a promise against kernel/driver failure. Unexpected presenter death deliberately does not use parent-death termination for the audience, to preserve the last usable frame.

Display setup recovery, 0.1.21

HostState adds default-false setup_controls and optional route_trial (u64 trial identifier). Startup controls allow an output-side right-click swap only before the first explicit navigation/show action; a pending trial always exposes minimal Keep/Revert controls. Output ACKs can carry display_action (Swap, Keep, Revert) and route_trial. The parent validates startup eligibility and trial identity; stale confirmations cannot commit a later trial. The parent owns the 15-second monotonic deadline and does not persist routes/fullscreen flags until confirmed. A late Keep is treated as rollback. Host EOF clears recovery controls so orphan Escape/Close remains available. Notes, source paths and operator layout data are still absent from this control payload. Private same-build IPC only.

Slide background colors, 0.1.26

HostState carries slide_colors with page_background and fit_padding RGB byte triples (default white/black). Color updates use the existing state sequence and repaint existing textures without changing buffer generation or reading slide files. Blank output remains black. Same-executable protocol only.

Output visibility in 0.1.51

Ack.request_blank is a boolean, default false for older messages. Only explicit output keyboard blank/close actions set it; diagnostic status messages never change output visibility. The presenter sends fresh state after host failure, including its current blank flag. Fullscreen/routing trials, confirmation, rollback and monitor topology changes preserve that flag. Missing outputs and operator privacy holds still suppress unavailable windows; no presenter content is sent to the output host.

Editable notes in 0.1.52

PrepareNotes {path, cache, source_sha} and SaveNotes {path, cache, source_sha, revision, page, text} run through the dedicated notes bridge. page is zero-based, source_sha identifies the loaded PDF/slide list, and revision is the notes file SHA-256 observed when editing began. A successful Reply.notes contains {path, revision, notes} with all resolved notes in slide order. Errors use the existing error field. The presenter ignores stale-generation completions and late background extraction after an editor snapshot has been accepted. The current page draft survives save failure. None of this payload enters output IPC.

Notes import in 0.1.53

PickNotes {owner} uses the existing owned, supervised file chooser with TXT/MD filters. PreviewNotesImport {path, cache, source_sha, import} returns Reply.notes_import {path, revision, sections, total}: destination sidecar path, optional existing-file SHA, parsed strings and total slide count. It writes nothing. ApplyNotesImport {path, cache, source_sha, preview} revalidates identity/revision, merges notes and writes atomically, returning the existing Reply.notes snapshot. Both notes jobs use the dedicated 30-second bridge, bounded JSON messages and source generations. Notes picker results carry the source generation too. These messages are private same-executable presenter/worker traffic, never output-host traffic.

Shared zoom in 0.1.54

HostState adds zoom {enabled, view {scale, center}, epoch, serial} and zoom_only (false by default). Scale is bounded to 1–8 and center is normalized page UV coordinates, clamped to keep the full crop inside the page. Disabled or invalid views normalize to a complete fitted page. Since 0.1.55, zoom also carries keep_fitted_area (missing defaults false). The default preserves page proportions while expanding into each viewport, clipping overflow with bounded UVs and geometry. True retains the original fitted rectangle. Visible crop/edge clamping is local to each viewport; scale and page center are shared. No higher-resolution request, texture upload or image buffer is created by zoom. Large crops split into disjoint clip bands on a pool capped at four CPU threads; scanline interpolation uses O(viewport width) scratch memory.

Presenter gestures, enable/disable and slide changes advance epoch, reset serial to zero and invalidate prior output gestures. Output gestures increment serial within that epoch, sharing the crop immediately among output mirrors. Ack adds optional zoom and boolean zoom_slow; crop ACKs include generation and page. Presenter accepts only current-generation/current-page/current-epoch newer serials. The output retains newer local serials against delayed presenter states. Pending output changes retry at most every 33 ms until the presenter echoes the crop; pipe queues remain bounded and the latest absolute crop replaces intermediate gestures.

Zoom-only messages contain only crop/page/generation metadata and must not replace frame, preload, monitor, fullscreen or visibility state. Coalescing retains queued full state and merges same-page zoom metadata. The host validates page/generation before applying a lightweight update, without touching its RAM cache or textures. Full state also carries zoom for recovery. Notes and other operator data remain absent. No zoom state is persisted except the opt-in boolean in settings.

The performance watcher counts three consecutive zoomed window draws above 33 ms, including software drawing/presentation. The presenter shows the warning locally; output hosts report only a boolean. It does not alter visibility or navigation.

Bounded presentation overlays in 0.1.67

HostState adds overlay and default-false overlay_only. The overlay contains an optional normalized page-coordinate pointer and at most 64 normalized straight arrow/highlighter marks with RGB color and bounded logical width. Invalid points are dropped, coordinates and widths are clamped, and excess marks are discarded. No notes, source paths or operator UI text enter this payload.

Overlay-only messages carry page/generation identity and absolute current overlay state. They share the two-slot presenter queue with zoom updates: coalescing merges same-page overlay and zoom fields into a pending full state without replacing frame, preload, routing, fullscreen or visibility data. The host rejects stale page or generation updates. Full state carries the overlay for host recovery. Drawing uses the existing buffered texture plus bounded vector shapes; it performs no PDF render, image decode, texture upload or slide-file access. This remains private same-build IPC.

Since 0.1.60, output heartbeats may include viewport {monitor, size, fullscreen}. size is the actual reference output window’s physical client size [width, height]. The reference is the first connected presentation route. This transient metadata lets the current preview use that aspect ratio, without transferring image data. Missing/zero dimensions or a route/fullscreen mismatch fall back to the connected monitor size. Reports are refreshed by the existing one-second heartbeat, and are not persisted. Outputs with different aspect ratios still use their own viewport.

Cache maintenance — 0.1.70

CleanCache {path, policy: {max_mib, max_days}, protected: [project_key], manual} runs on a dedicated 30-second supervised worker, one outstanding job per presenter. The reply adds optional cleanup with unsigned removed_bytes, remaining_bytes, removed_files, and skipped_files. Errors use the existing error field. No frame payload is transferred. The same-build private protocol requires no migration.

The optional full HostState field blank_picture: FrameInfo | null (0.1.77) identifies the managed blank image by path, dimensions and content SHA256. Lightweight updates retain it. A separate supervised worker reads it; the output validates identity before accepting the pixels. It is never acknowledged as a slide, and a failed read leaves blank output black. Worker requests PickBlankPicture { owner } and BlankPicture { source, path } select and import/load the asset; source null loads the stored copy. See blank picture for bounds.

Per-screen window mode — 0.1.87

HostState adds screen_fullscreen, a monitor-ID-to-boolean map containing the resolved mode for each assigned Slides monitor (at most 32 route entries). Missing entries fall back to the existing fullscreen role-wide boolean. The presenter resolves saved or trial overrides before sending; the map contains no presenter layout, notes or paths. Placement and OutputViewport acknowledgments use the same per-monitor value. Full state updates replace the map; lightweight zoom/overlay updates preserve it. Values round-trip through JSON; both processes must still run the same executable build.

Quit confirmation — 0.1.88

ACK adds optional boolean request_quit (default false). Escape/Ctrl+Q on a connected output requests the shared operator-only quit dialog; it does not blank or stop the output. No confirmation text or notes are sent to the audience host. Only a confirmed presenter-side quit triggers existing shutdown. Escape retains priority for display-trial rollback; an orphan output can still close directly.