Plans index¶
This page summarises every planning document in chronological order. Master plans decompose work into numbered phases, each with its own detailed plan file. Standalone plans track issues, follow-ups, or design decisions that do not require phased execution.
New plans should follow the structure in PLAN-TEMPLATE.md at the repo
root. For pre-push audits of our own work see PUSH-AUDIT.md; for
reviewing and merging external contributor PRs see MERGE-TEMPLATE.md.
The Status column below uses exactly four values, so the index can be
skimmed for what is live. This vocabulary is for the index only — each
plan's own header and phase table describe their state in whatever detail
that plan needs.
| Status | Meaning |
|---|---|
| Complete | Every phase has landed and nothing is outstanding. |
| In progress | At least one phase is being worked, or has landed but is not yet verified. |
| Not started | Phases are written but none has been started. |
| Proposed | A concept: the intent is recorded but no phases are drafted. |
Where a plan is In progress for a reason the phase table does not make
obvious, that reason belongs in the plan itself rather than in this table.
Master plans¶
| Date | Plan | Intent | Status | Phases |
|---|---|---|---|---|
| 2026-04-01 | Initial porting plan | Port the ryll SPICE client from Python to Rust with egui | Complete | (design document) |
| 2026-04-01 | Capture mode | Protocol traffic pcap and display frame video capture for debugging | Complete | 1. Infrastructure, 2. Pcap, 3. Video |
| 2026-04-01 | Packaging | Cross-platform packaging for Debian, RPM, macOS, and Windows | Complete | 1. Portability, 2. CI, 3. Debian, 4. RPM, 5. macOS, 6. Windows, 7. Release |
| 2026-04-02 | USB redirection | USB device redirection via the SPICE usbredir channel | Complete | 1. VMC channel, 2. Parser, 3. Backend trait, 4. Real devices, 5. Connect, 6. Transfers, 7. Virtual MSC, 8. UI, 9. Interrupt, 10. Testing |
| 2026-04-03 | Cursor rendering | Render SPICE server-provided cursor as an egui overlay | Complete | 1. Parse, 2. Render |
| 2026-04-04 | Bug reports | Interactive bug reporting with protocol ring buffers and display region selection | Complete | 1. Ring buffer, 2. Channel state, 3. Zip output, 4. GUI button, 5. Region select, 6. Traffic viewer, 7. Docs |
| 2026-04-05 | USB UI | Interactive USB device management panel on the status bar | Complete | 1. Bus fix, 2. Wire tx, 3. Panel, 4. Enumerate, 5. Connect, 6. Add disk, 7. Polish, 8. Docs |
| 2026-04-06 | WebDAV | WebDAV folder sharing via the SPICE port channel | Complete | 1. Port channel, 2. Mux protocol, 3. WebDAV server, 4. Integration, 5. UI, 6. Testing |
| 2026-04-08 | Crate extraction | Extract compression, protocol, and usbredir crates for reuse | Complete | 1. Workspace, 2. Reserve names, 3. Compression, 4. Protocol, 5. Usbredir, 6. Client |
| 2026-04-19 | Screenshot and latency HUD | Add F8 screenshot capture and a latency sparkline in the stats panel | Complete | 1. Screenshot, 2. Latency sparkline, 3. Docs |
| 2026-04-19 | Idle CPU and latency | Investigate 6-core idle CPU usage; replace broken keystroke latency with PING/PONG-based measurement; demote noisy protocol logging; capture runtime metrics in bug reports | Complete | 1. Profile, 2. Repaint, 3. Logging, 4. Latency, 5. Metrics, 6. Push audit |
| 2026-04-21 | Display draw-op coverage | Fill out the SPICE display draw-op set (DRAW_FILL / OPAQUE / BLEND / BLACKNESS / WHITENESS / INVERS / TRANSPARENT / ALPHA_BLEND / COPY_BITS) so BIOS, GRUB, and kernel-console rendering works; add warn_once! + --pedantic bug-report-per-gap instrumentation on top |
Complete | 1. Plumbing, 2. DRAW_FILL, 3. Monochrome, 4. COPY_BITS, 5. Image rop, 6. Alpha, 7. Invers + warnings, 8. Pedantic, 9. Pedantic handles, 10. Docs (inline) |
| 2026-04-23 | Android APK port | Concept plan for a sideloadable Android APK of ryll, targeting the Google TV Streamer as a thin-client SPICE endpoint | Proposed | (phases 1-9 not yet written), 10. Push audit |
| 2026-04-23 | Bug-report trigger snapshot | Capture the display surface when the bug dialog opens, not at submit, so transient artefacts survive the form-filling delay | Complete | 1. Metadata, 2. Snapshot, 3. Region image, 4. Docs |
| 2026-04-25 | Paste-as-keystrokes fallback | Synthesise SPICE keystrokes for the contents of a string when no vdagent is available, so guests like uncalibrated-sextant can be driven without an in-guest agent | Complete | 1. Translator, 2. Channel + CLI, 3. GUI gesture, 4. Docs |
| 2026-04-25 | Hamburger menu | Replace the status-bar action-button row with a single hamburger menu so the row returns to glanceable state | Complete | 1. Migrate |
| 2026-04-25 | Notifications system | In-app notifications surface for protocol gaps, bug-report status, and SPICE_MSG_NOTIFY messages that ryll currently drops on the floor | Complete | 1. Store, 2. SPICE_MSG_NOTIFY, 3. Existing sources, 4. GUI, 5. Docs |
| 2026-04-27 | PR #31 follow-up | Tests, docs, and polish items deferred when landing PR 31 (UI improvements, reconnect, protocol fixes) | Complete | 1. Tests, 2. Docs, 3. Polish |
| 2026-04-28 | Connection properties | Connection properties dialog showing server endpoint, protocol version, channels, negotiated capabilities, and display surfaces | Not started | 1. Plumbing, 2. Dialog, 3. Cap names, 4. Docs, 5. Push audit (phase plans pending) |
| 2026-04-30 | Display window sizing | Track guest surface size on every SURFACE_CREATE (not just the first), with a hamburger toggle to opt out | Complete | 1. Always-fit, 2. Toggle, 3. Tests, 4. Docs, 5. Notify |
| 2026-05-01 | Web frontend | A --web mode of ryll that transcodes SPICE to a browser over WebRTC, so a desktop can be reached from any modern browser, with the goal of dogfooding ryll in place of Kasm + Apache Guacamole |
Complete | 0. Parity audit (complete; docs/multi-mode-parity.md), 1. Renderer extraction (complete), 2. Encoder (complete; H.264 path), 3. WebRTC (complete), 4. HTTP server + token (complete; synthetic source), 5. Inputs/cursor/audio (complete), 6. Reconnect + lifecycle (complete), 7. CI (complete), 8. Docs (complete) |
| 2026-05-07 | Video keeping up | Instrumentation and threading changes so a "video stream not keeping up" bug report can attribute the bottleneck to server, network, decode, render, or our own I/O backpressure. Spun out of session-001 item U1. | Complete | 1. Display instrumentation, 2. Pcap writer task, 3. Video encoder task, 4. Render-side latency |
| 2026-05-07 | macOS runtime metrics | Per-thread and process-level runtime metrics on macOS so bug reports from Mac clients carry the same CPU/RSS data as Linux. Spun out of session-001 item G1. | Complete | 1. Process-level, 2. Per-thread, 3. Integration + soak |
| 2026-05-08 | CI platform matrix | Lift CI smoke coverage to macOS and Windows so platform-specific runtime bugs (e.g. the rustls macOS CryptoProvider panic) are caught in CI rather than during dogfooding. |
Not started | 1. TLS handshake smoke, 2. web-smoke parity, 3. Smoke-test portability audit, 4. Release QA checklist, 5. Push audit (phase plans pending) |
| 2026-05-17 | egui / eframe 0.34 follow-up cleanup | Migrate ryll/src/app.rs off the egui 0.34 deprecated APIs (panel types and show, Frame::none(), Context::style(), InputState::screen_rect(), menu::menu_button) and delete the module-wide #![allow(deprecated)] the minimum-diff bump added, so the next deprecation in the crate's largest file is loud again |
Complete | (no separate phases; landed with the eframe 0.35 bump in PR #131) |
| 2026-05-17 | Stream caps and flap diagnostics | Advertise the four SPICE display capabilities ryll is missing (STREAM_REPORT, LZ4_COMPRESSION, MULTI_CODEC+CODEC_H264, PREF_COMPRESSION+PREF_VIDEO_CODEC_TYPE), replace the pure-Rust MJPEG decoder with per-platform best-of-breed (ImageIO / WIC / VA-API / libjpeg-turbo), audit and complete per-channel diagnostic surface (especially playback), surface the spice-server's stream-flapping behaviour in the UI, add a vdagent responsiveness probe, and remove the now-redundant spurious-PONG keepalive. Spun out of test sessions 002 and 002b; phase 4 added after sessions 002d/002e exposed a playback observability gap. |
In progress | 1. STREAM_REPORT, 2. LZ4, 3. Fast JPEG decode, 4. Channel diagnostics audit, 5. Auto-snapshot mode, 6. Multi-codec + H.264, 7. Preference messages, 8. Streaming indicator + flap notification, 9. Vdagent probe, 10. Docs (no separate plan; dispatched as a docs-audit catch-all), 11. Remove PONG keepalive, 12. Bounded image cache, 13. Investigate intermittent server-side streaming, 14. Status-bar pointer leak, 15. build_tcp_frame warn, 16. Guest-driver viability, 17. Patched libspice validation, 18. Push audit |
| 2026-05-21 | Streaming test automation | Replace the manual session-driven cadence with CI coverage of known-good streaming scenarios. Covers three complementary approaches: pcap replay (smallest first cut), input record-and-replay against a dedicated CI box (closer to real-world), and AT-SPI-based semantic replay (highest effort, dovetails with future MCP agent surfaces). Blocked on phase 13 of the stream-caps work finishing so we know which scenarios are deterministic enough to assert against. | Proposed | (phases not yet written; the last of them is a push audit) |
| 2026-07-19 | Pip-installable ryll | Ship ryll on PyPI so pip install ryll (typically via the client's [vdi] extra) puts a working ryll on PATH, the way pip install kerbside ships kerbside-proxy. Phase 3 of the cross-repo Shaken Fist VDI console tokens plan. A per-arch manylinux_2_28 maturin (bindings = "bin") wheel that embeds the compiled GUI binary — no runtime download — built natively for x86_64 and aarch64 and published to PyPI via OIDC Trusted Publishers |
Complete | maturin bin wheel, build/sign/publish jobs in release.yml, and docs (phases inline in this master) |
| 2026-08-04 | webrtc-rs 0.20 upgrade | Port shakenfist-spice-webrtc from webrtc-rs 0.17.1 to 0.20.x. 0.20 re-homes the crate on a sans-io rtc core behind a thin async layer, moving RTCPeerConnection's operations onto a trait, collapsing the per-object callbacks into a single PeerConnectionEventHandler, dropping gathering_complete_promise and connection_state, and requiring explicit UDP bind addresses. Deferred from Renovate PR #245, which was repurposed to carry the < 0.18 pin and this plan. |
Complete | 1. Pre-work on 0.17 (complete), 2. Atomic bump (complete), 3. Socket binding config (complete), 4. Soak and docs (complete) |
| 2026-08-09 | Two-stage CI | Split CI into a cheap smoke tier on pull_request (lint, Linux build + tests, supply-chain scanners) gating Can enqueue, and an expensive merge tier on merge_group (fuzz ×4, cross-platform builds ×4) gating Can merge, modelled on shakenfist/shakenfist's merge-queue scheme, so a failing cargo deny no longer wastes eight heavy builds. |
Complete | 1. Two-tier ci.yml, 2. Windows cross-check, 3. Merge queue enablement, 4. Docs |
Standalone plans¶
These plans track issues, follow-ups, or deferred work without phased execution.
| Date | Plan | Intent |
|---|---|---|
| 2026-04-01 | Remaining issues | Outstanding issues after the initial Rust port bring-up |
| 2026-04-08 | Display iteration follow-ups | Deferred work from display rendering, QUIC decode, and multi-monitor PRs |
| 2026-04-11 | PR #20 follow-up | Follow-up fixes from clipboard, MJPEG, and disconnect handling |
| 2026-04-11 | PR #23 follow-up | Follow-up fixes from audio playback channel integration |
| 2026-04-11 | Opus decoder | Replace the abandoned audiopus C-wrapper crate with the pure-Rust opus-decoder crate to drop the cmake build dep and remove an unmaintained supply-chain dependency. (Step-based; landed.) |
| 2026-04-18 | Supply-chain scanning | Deterministic scanners for dependencies, secrets, and Unicode-based attacks |
| 2026-04-18 | Supply-chain follow-ups | Tracked advisory ignores and unmaintained-crate debt surfaced when landing scanners |
| 2026-04-22 | Crate release | Publish the workspace's three sub-crates (shakenfist-spice-protocol, -compression, -usbredir) to crates.io alongside ryll on every tagged release. (Single-commit; landed at v0.1.4.) |
| 2026-04-23 | Macbook bug-report fixes | MOUSE_MODE wire format, client-mode re-request after guest reboot, and MULTI_MEDIA_TIME handler |
| 2026-06-01 | Open questions watch-list | Single review surface for symptoms seen in bug reports that we can't yet characterise. Entries link out to the phase plans that would action them. Reviewed at the start of each session closeout. |
| 2026-07-14 | Self-hosted runner migration | Move Linux x86_64 CI jobs onto self-hosted runners inside the devcontainer and mark the no-hardware platforms (macOS, Windows, aarch64 Linux) as audit-ok exceptions, resolving the workflow-standards consistency audit (issue #155). |
Consolidation plans¶
These plans collate deferred work from multiple sources into a single execution sequence.
| Date | Plan | Intent | Status | Phases |
|---|---|---|---|---|
| 2026-04-16 | Deferred debt | Pay down correctness bugs, robustness gaps, code quality, tests, and docs across all completed plans | Complete | 1. Display, 2. Audio, 3. Session, 4. Robustness, 5. Cleanup, 6. Tests, 7. Docs (inline) |
| 2026-05-07 | Session 001 feedback | Triage and execution of the dogfooding feedback from test session 001 on macOS against sf-4 (six bug-report zips + free-form notes). |
Complete | 1. Disconnect snapshot, 2. Reconnect, 3. Audio volume, 4. Region-select guard, 5. STREAM_DESTROY_ALL, 6. Channel rebalance, 7. Traffic Arc, 8. Ring segmentation, 9. Connection notifications, 10. Notification bug button |