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-TEMPLATE.md; for
reviewing and merging external contributor PRs see MERGE-TEMPLATE.md.
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 | Code landed; awaiting user verification | 1. Profile, 2. Repaint, 3. Logging, 4. Latency, 5. Metrics |
| 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 (concept) | (phases not yet written) |
| 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 (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 (phase plans pending) |
| 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 (concept) | (phases not yet written) |
| 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 |
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-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-23 | Macbook bug-report fixes | MOUSE_MODE wire format, client-mode re-request after guest reboot, and MULTI_MEDIA_TIME handler |
| 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-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-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. |
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 |