galaxy/specs/qr-code/TECH.md

Shared session QR code — Tech Spec

Product spec: specs/qr-code/PRODUCT.md

Context

PRODUCT.md defines the user-visible behavior for adding a QR-code affordance to the live-session sharing dialog. The implementation should extend the existing session sharing dialog rather than adding another sharing surface. The relevant current code paths are:

• app/src/drive/sharing/mod.rs:34 defines ShareableObject::Session, carrying a terminal view handle, SessionId, and started_at.
• app/src/drive/sharing/mod.rs:45 implements ShareableObject::link; the session branch returns join_link(session_id), which should be the sole source of truth for QR payloads.
• app/src/terminal/shared_session/mod.rs:285 implements join_link, including staging/native-intent and preview-channel behavior.
• app/src/terminal/view/shared_session/view_impl.rs:591 sets the pane header shareable object to ShareableObject::Session when a share starts and opens the sharing dialog unless the flow explicitly skips it.
• app/src/terminal/view/shared_session/view_impl.rs:408 refreshes the same shareable object from active shared-session state when roles or session state change.
• app/src/workspace/view.rs:4281 listens for ManagerEvent::StartedShare, copies the remote-control link, and shows the Remote control link copied. toast.
• app/src/terminal/shared_session/manager.rs:135 emits ManagerEvent::StartedShare with the new shared-session id and window id.
• app/src/drive/sharing/dialog/mod.rs:69 defines the generic SharingDialog state and UiStateHandles.
• app/src/drive/sharing/dialog/mod.rs:149 defines SharingDialogAction; it currently has CopyLink and permission actions but no QR actions.
• app/src/drive/sharing/dialog/mod.rs:332 resets the dialog target through set_target.
• app/src/drive/sharing/dialog/mod.rs:368 exposes has_shared_session_target, which already distinguishes session targets from other shareable object types.
• app/src/drive/sharing/dialog/mod.rs:428 treats sessions as editable so the sharing dialog opens for session targets.
• app/src/drive/sharing/dialog/mod.rs:905 copies the target URL and sends CopiedSharedSessionLink telemetry for session targets.
• app/src/drive/sharing/dialog/mod.rs:2372 renders the footer link and Copy link button in render_object_link.
• app/src/drive/sharing/dialog/mod.rs:2505 composes the full dialog in render.
• app/src/drive/sharing/style.rs:15 contains sharing-dialog layout constants and color helpers.
• crates/warpui_core/src/platform/file_picker.rs:127 defines SaveFilePickerConfiguration, and crates/warpui_core/src/core/view/context.rs:311 exposes open_save_file_picker for save-file flows.
• crates/warpui_core/src/clipboard.rs:29 defines ClipboardContent, which the existing link-copy action already uses for plain-text URLs. The app icon inventory now exposes the QR flow controls used by this surface, including Icon::Download, Icon::Copy, and Icon::QrCode, with the QR asset mapped alongside the other share/link icons.

Proposed changes

1. Add the toast entry point shown in the mocks

Extend the existing shared-session start toast in app/src/workspace/view.rs so it renders:

• message: Remote control link copied.
• inline action: View QR code The action should carry the new SessionId from ManagerEvent::StartedShare and route back to the matching shared terminal view. Add a workspace action dedicated to opening the QR flow for that session id instead of relying on whichever pane is currently focused. Add a lookup helper on the shared-session manager that resolves a shared session id back to its terminal view. From there, dispatch into the terminal/pane-header sharing flow so the right pane opens its existing sharing overlay in QR mode. If the standard live-session sharing dialog is already open, switch that existing overlay into QR mode. If it is closed, open it directly in QR mode. Back should always return to the access-management panel for the same session target.

2. Add QR mode to SharingDialog

Add a dialog mode enum in app/src/drive/sharing/dialog/mod.rs, for example:

• SharingDialogMode::Access
• SharingDialogMode::QrCode Store it on SharingDialog, defaulting to Access. Reset it to Access in set_target so a recycled dialog does not show QR content for a different target. Extend UiStateHandles with mouse states for:
• the footer QR button;
• the QR dialog back button;
• the QR dialog copy-link button;
• the QR dialog download button. Extend SharingDialogAction with:
• ShowQrCode
• BackToAccessDialog
• DownloadQrCode Keep SharingDialogAction::Close behavior unchanged: it should still close the overlay and reset editable state.

3. Render the QR entry point only for session targets

Extract a small helper such as target_link(&self, app: &AppContext) -> Option<String> so render_object_link, copy, and QR actions all use the same URL lookup. Modify render_object_link so that when self.target is Some(ShareableObject::Session { .. }), the footer row includes an icon-only QR button between the link field and the existing Copy link button. For non-session targets, keep the current link + copy button layout. The QR button should:

• use the same button/style system as the existing footer controls;
• dispatch SharingDialogAction::ShowQrCode;
• be disabled or omitted when target_link returns None;
• show a tooltip equivalent to Show QR code. Add a bundled QR icon if needed:
• Add the SVG asset under the existing bundled SVG asset location.
• Add a variant such as Icon::QrCode.
• Map it to the bundled path near the other share/link icons.

4. Render the QR-code view inside SharingDialog

In View for SharingDialog, branch on self.mode:

• Access renders the existing dialog contents.
• QrCode renders a compact QR view for session targets. Keep the same outer Dismiss behavior and border/background styling so the QR view remains part of the pane-header sharing overlay. Use the Figma dimensions as targets rather than introducing a new modal system:
• width around 400px;
• header height around 48px;
• body centered around a 192px QR card;
• two 32px icon buttons beneath the QR card. The QR branch must preserve the sharing dialog's compact intrinsic overlay layout. Render it with minimum-height column sizing rather than max-height stretching so opening QR mode replaces the dialog contents instead of producing a workspace-height panel. The QR view should render:
• a header row with back button, Share session QR code, ESC, and close button;
• a QR code card;
• copy-link and download-image icon buttons. If self.target is no longer a session target or target_link is missing, render a compact error body with the same header and a message equivalent to Unable to create QR code for this session link.

5. Generate QR data with a small pure helper

Add a small QR helper module, for example app/src/drive/sharing/qr_code.rs, with pure functions:

• qr_matrix_for_url(url: &str) -> Result<QrMatrix, QrCodeError>
• qr_png_for_url(url: &str, pixel_size: u32) -> Result<Vec<u8>, QrCodeError> Add a workspace dependency on a QR encoder crate such as qrcode in the root Cargo.toml and app/Cargo.toml. Prefer a dependency that can produce a boolean module matrix without pulling in a large image stack; use the existing workspace image crate for PNG encoding because it is already present. Use the same QR helper for on-screen rendering and PNG generation so scanning behavior cannot drift between the two paths. For on-screen rendering, prefer drawing the QR matrix directly with Warp UI rectangles rather than feeding a generated PNG back through the image cache. This keeps the view deterministic, avoids temporary files, and makes sizing straightforward. The helper should expose module count and module values; the view computes cell size and quiet-zone padding inside the 160px visual target. For PNG export, generate a black-on-white PNG with a quiet zone. Use a larger export size than the on-screen display, such as 512px or 1024px, so downloaded images remain scannable when printed or projected.

6. Copy the session link from QR mode

Wire the QR dialog's copy button to the existing SharingDialogAction::CopyLink behavior so it:

• resolves target_link;
• writes the same plain session URL that the access dialog footer copies;
• preserves the existing shared-session link-copy telemetry and toast feedback;
• behaves consistently across platforms without depending on image clipboard support.

7. Download QR image

Implement SharingDialogAction::DownloadQrCode by:

• generating the same PNG bytes;
• opening ctx.open_save_file_picker with SaveFilePickerConfiguration::new().with_default_filename(default_qr_filename(...));
• writing the bytes to the selected path on the background executor or through an existing async file-write helper;
• showing a success toast when the file is written;
• showing a failure toast on write or generation errors;
• doing nothing when the picker returns None. Default filename suggestion: warp-session-qr-code-<session-id>.png for session targets. If the session id is unavailable in a future target shape, fall back to warp-session-qr-code.png. The download action can be compiled only for local filesystem builds if needed. If save-file picker or filesystem writes are unavailable for a target platform, disable or hide the download button there rather than showing a broken control.

8. Preserve existing sharing behavior

Do not change:

• ShareableObject::Session.link;
• join_link;
• SharingDialogAction::CopyLink;
• ACL update actions;
• session invite flow;
• pane-header sharing dialog toggling. The QR flow should be additive. Existing tests for session permissions and link-copy behavior should keep passing without expected-output changes except where snapshots explicitly include the new QR button.

9. Telemetry

Keep existing link-copy telemetry unchanged. Add telemetry only if the product/event taxonomy already has an appropriate place for it:

• OpenedSharedSessionQrCode
• DownloadedSharedSessionQrCode If new telemetry is added, include the same action source where available or derive it from the sharing dialog context. Avoid error-level logs for QR generation or export failures; use user-visible toasts and at most warn-level diagnostic logging.

Testing and validation

Map validation to PRODUCT.md behavior:

• Behavior 1-5: workspace/session tests verify the shared-session toast includes View QR code, that it targets the newly-started session id, that clicking it opens QR mode on the correct pane even when the access dialog was not already open, and that the QR state remains the same compact sharing overlay rather than a full-height panel.
• Behavior 5-7: unit or view tests verify that render_object_link includes the QR button only for ShareableObject::Session, and non-session targets still render the existing footer.
• Behavior 9-12: view/action tests verify ShowQrCode, BackToAccessDialog, Close, and Escape transition between access mode, QR mode, and closed overlay as expected.
• Behavior 13, 15, 18, 29: pure QR helper tests verify that the generated matrix/PNG encodes the exact URL passed in and does not add extra query parameters or payload data.
• Behavior 14: screenshot or integration verification compares the QR view against the Figma layout in dark theme, including header, centered QR card, and copy/download buttons.
• Behavior 16-17: tests update the target/session link while QR mode is active and verify the rendered/exported QR payload follows the current ShareableObject::link result; missing links render the error state.
• Behavior 19-21: clipboard tests verify the QR dialog copy button routes through the plain-link copy path and does not attempt image clipboard writes.
• Behavior 22-24: save-file tests cover default filename, cancel behavior, successful write, and write failure.
• Behavior 25: existing CopyLink tests or new targeted tests verify plain link copying and toast behavior remain unchanged.
• Behavior 26: manual verification confirms the QR view copy/download icon buttons show the expected tooltips.
• Behavior 28: unit tests construct two session targets with different ids and verify each QR helper call uses that target's own link. Suggested targeted commands after implementation:
• cargo nextest run --no-fail-fast --workspace drive::sharing::dialog
• cargo nextest run --no-fail-fast --workspace drive::sharing::qr_code
• cargo check If the implementation changes Rust files, follow the repository convention of adding tests in a sibling _tests.rs file and importing it with a #[cfg(test)] directive from the implementation module.

Parallelization

Do not split this implementation across parallel agents. The work is concentrated in the sharing dialog, icon plumbing, QR generation helper, and adjacent tests; parallel edits would likely collide in the same files and add coordination overhead.

Risks and mitigations

• QR scan reliability: mitigate by keeping black-on-white rendering, including a quiet zone, and validating with an actual phone camera during manual QA.
• Platform clipboard differences: mitigate by reusing the existing plain-link clipboard path shared by supported platforms.
• Platform save-file differences: mitigate by using the existing open_save_file_picker abstraction and hiding/disabling download where local filesystem support is unavailable.
• Link drift: mitigate by deriving all QR payloads from ShareableObject::link at action/render time rather than storing a separate URL string.