feat(desktop,web,server,node): virtual displays, and the helper in both assistants by theogravity · Pull Request #465 · subshell-ai/subshell

theogravity · 2026-10-27T22:55:55Z

Changes

Make virtual displays accessible from both desktop assistants and fix web previews that lose styles, images, or development-server requests behind Subshell's proxy. Add optional preview configuration saved per user, node, host, protocol, and port. New previews use those settings while retaining the opaque browser sandbox and target authorization.

Gate display providers by the selected node's OS and readiness, explain launch refusals beside the display control, and keep availability badges consistent with permissions.
Rewrite supported app URLs, styles, module imports, import maps, redirects, and common browser requests. Compressed transforms have size and concurrency bounds. Next.js and Vite hot reload are covered by browser checks. Target CSP, browser storage, service workers, and some app routing remain compatibility limits.
Verify installed Display Helper signatures before reuse, preserve executable permissions, safely embed its bundled HTML, and restrict the native webview bridge to the bundled main frame. Ship helper version 1.0.1 with clearer consent, permissions, sign-in, and quit messages in both desktop apps.
Bound terminal WebSocket payloads and outstanding input per connection and across the server. Dispatched writes retain their budget until completion; disconnecting drops queued retries.
Recheck sharing permissions by closing non-owner terminal connections when shares change, including pending attachments. Tests cover downgrades, removal, late retries, and attachment races.
Keep SSH setup scripts and credential-bearing installer URLs out of child-process arguments by using stdin and a short-lived setup-key environment variable. Refuse older installers that cannot accept this input.
Preserve terminal text selection and preferences when browser storage is unavailable, and drain sustained resize updates without retaining a promise chain.

Compatibility: node protocol 25 requires servers and connecting nodes to be upgraded together. Explicit CLI --key still exposes that argument to process inspection; copied setup commands can remain in shell history. macOS permission grants remain machine-specific.

Documentation and screenshots

Web previews & screens now has its own sidebar section: prerequisites, web app previews, browser watching, Linux virtual displays, macOS virtual displays, and agent workflows. Platform installation, configuration, usage, and screenshots live together. Node pages link to those procedures; existing routes and bookmarks are preserved, and app, desktop, helper, and website help links point to the new pages.

Update /concepts/security for preview response rewriting and settings, live sharing revocation, terminal input bounds, enrollment credentials, and helper signature verification. Retain the SSH bulletin analysis and documented trust boundaries.

Refresh the assistant and helper screenshots from the shipped UI with sample states, including a running helper with both required permissions granted. The preview guides also include the website, configuration dialog, and virtual-display screenshots.

Validation

Preview/security implementation: 4,895 API tests and 3,143 web tests; compiled transform smoke check; real Next.js/Vite hot reload and computed-import browser scenarios; browser isolation and sharing-revocation scenarios.
Documentation/copy updates: 184 docs tests, 41 helper-panel tests, 429 client UI tests, 458 server UI tests, and 50 focused web component tests. Native helper compilation, app typecheck, and consent/protocol/disabled-RPC tests passed on the Mac node.
Fresh docs production build and export verification for all 135 pages, 55 fragment links, and 20 legacy bookmarks. Desktop and phone navigation reviewed; affected screenshots regenerated and inspected.
Type, lint, prose, design-token, and license checks passed. The dependency audit retains two already-patched tooling advisories; dependency-security regressions passed.
Independent security, documentation, and helper-copy reviews completed with findings corrected and re-reviewed. No full monorepo suite was repeated for the final prose and screenshot changes.

The menu-bar door proved undiscoverable, so the macOS display helper gets a standing rail section in each assistant window: the enablement steps the menu item never showed, one button opening the helper's own panel, and a link to the setup guide. The section is the rail's only platform fact and drops off where no helper exists; a deep link asking for it elsewhere answers with that machine's own journey.

…roviders A node that cannot serve previews now reads gold when the reason is the Web previews & screens switch, which an owner can turn on, with a link to the guide; an offline or outdated node stays muted because no setting fixes that. The launch form, a preset, and the node's provider list drop a virtual display provider the selected machine's OS cannot run, using one rule in subshell-protocol rather than three copies of it.

…'s output A slow or loaded Linux node answered launch-with-screen with a bare 'not answering within 5000ms' and then reaped the pane dir that held Xvfb.log and x11vnc.log, leaving nothing to diagnose. The refusal now names which of the three readiness gates was still shut (Xvfb socket, rfb bind, listener ownership), the provider logs both children's tails to the daemon journal before the teardown, and the budget is 10s since the launch command has 60s on the wire anyway.

The create failure rendered in one form-level slot under 'Save as preset' no matter which control caused it. screenLaunchRemedy now always names the node's refusal word (bare form included) and the switch preflight carries preview-node-off, so the dashboard can match them (isDisplayLaunchRefusal) and route the refusal into the Virtual display field's own error slot, wired into the checkbox. Everything else keeps the form-level line.

verify() passed -R a bare requirement string; codesign treats an unprefixed -R value as a FILE to load from, so every 'Open Display Helper settings' press died with '<the whole requirement>: No such file or directory' and 'invalid requirement specification' before the helper could install or open. The value must start with = to be a literal spec. The module is macOS-only, which is how it survived review uncompiled on Linux CI; the new test pins the prefix in both debug and release shapes.

codesign shows CDHash= only from -dvvv; at -dvv it exits 0 without the line, so the same-or-older-copy digest comparison answered 'Couldn't verify the display helper's code identity' on every settings press that found an installed helper. First install escaped it only because the missing-copy branch never reaches the hash. macOS-only module; verified on the M5.

…ndow HelperConsent's default argument was UserDefaults(suiteName: bundleID) with the app's OWN bundle id: Foundation rejects that (it logs 'does not make sense and will not work') and returns nil, so the force-unwrap raised EXC_BREAKPOINT inside DisplayHelperApp.init. open exited 0, so the desktop app reported success while the helper died instantly and no panel appeared. The default is .standard, which for the bundled helper already IS its own domain; consent still reaches the daemon over the helper's socket. The test now exercises the DEFAULT initializer against the standard domain, which the old code failed.

build_support::build() rewrote src-tauri/resources/Subshell Display Helper.app every time the build script ran, and tauri dev watches src-tauri - so one edit under native/display-helper put bun run dev:desktop-client into an endless 'File ... changed. Rebuilding application...' loop. The bundle is now built and signed in OUT_DIR, synced into resources only when bytes differ, and gated by a content fingerprint kept outside the watched tree. The script's own tests run from a shim test target (cargo never tests build scripts).

…refused The missing list could not distinguish 'no helper at all' from 'helper enabled, permissions on, BetterDisplay lookup empty', and that distinction decides whether the fault is the helper, BetterDisplay, or the caller.

The launch refusal is raised by the runtime wrapper around the provider, so the allocation-site log never fired. Both gates now say what the helper actually answered.

A pane whose app started a port nobody saved, or that has a screen or a browser watch sitting there, looked identical to an empty one. The count comes from the picker's own reads (same query keys), and the rule is a pure function: discovered ports minus Saved services rows, plus the screen and the browser watch when offered. The trigger's aria-label carries the number.

…name the exits The settings panel was raw AppKit: default fonts on a system background, a title that did not say the product, and no way to get out of the window except closing it. It now draws the dashboard's own palette (Theme.swift converts the oklch tokens from styles.css rather than retyping hexes, and the helper test pins them), uses the heading/label/body/detail roles, calls itself Subshell virtual display helper, and offers Minimize helper next to Quit helper in the panel and the menu bar. The menu bar icon now says when the machine is being looked at: a live capture tints it gold and adds a dot, the tooltip names the viewer count, and the panel carries the same line in gold. Runtime announces capture start and end so the badge tracks the truth instead of the 2s poll.

Pointer control posts real cursor events onto the virtual display, so when that screen goes away mid-session (pane closed, display discarded, helper quit) the local user is left with a pointer parked off every visible display. Measured on the M5, where it cost them the cursor entirely. The helper now restores a stranded pointer to the built-in display when a capture session ends, when it quits, and when the provider discards the screen it was on. The stranding test is pure, so it runs in the helper suite.

420pt wide instead of 620, one measurement column, standard push buttons (the old bezelColor-on-regularSquare controls rendered as mismatched tall boxes), the two permission states aligned in a grid, secondary actions and the exits grouped at the foot, and prose trimmed to what a person reads.

@theme

The colours were copied into each surface's stylesheet and a checker compared the copies, which is how the assistant once shipped six near-miss values under Dreamframe's names. They now live in packages/assistant/tokens.css and the three CSS surfaces @import it. packages/, not apps/server/, is deliberate: the macOS display helper's panel (Apache, under native/) must be able to import the same file, and the AGPL boundary runs through apps/server/. Type roles stay literal in each @theme block because var() indirection does not work there; lint:design names any surface that re-declares a shared value differently, and the client's parity test now proves the import, the roles, and the absence of a local shadow. Docs and the auto-loaded rule tell people where a token goes now.

The native AppKit layout kept arriving at the Mac looking wrong: boxed controls of mismatched height, rows clipped by the window, and a mirrored copy of the palette nothing checked. It is now a local page in packages/helper-panel, built on packages/assistant/tokens.css, and the helper hosts it in a web view behind the same HelperSettings API. The page holds no authority. It loads with loadFileURL scoped to its own directory, from a non-persistent data store, cannot open a window or navigate off-bundle, and every act it posts is re-checked in Swift. What follows from that: - lint:design scans the package under the assistant rules, and a test pins the registration, because a scan root that silently matches nothing is the same hole as no scan root. - lint:prose sweeps its string literals: consent copy is shipped text. - The Swift Theme keeps only the three colours and one type role the native chrome still paints, and AccessReport loses the panel line the page now owns. - build_support.rs stages dist into Contents/Resources/panel, before the signature, and prunes hashed assets a previous build left behind. A release refuses to bundle without the page; a debug build carries a placeholder naming the command, since the CI Rust lanes have no node_modules to build it from. - Both desktop apps take @internal/helper-panel as a devDependency, so turbo builds it before either bundles the helper.

The SDK declares the delegate methods unisolated and the properties they hand us main-actor, so the first cut of the bridge read `message.body` and `navigationAction.request` off main and produced two warnings. A Task where the work may wait a runloop turn, and `assumeIsolated` where WebKit has to have the answer synchronously.

The web view opened white. The page was fine; its two assets were not. `loadFileURL` gives the document an opaque origin, so vite's `<script type="module" crossorigin>` and `<link rel="stylesheet" crossorigin>` are CORS requests from a null origin that WebKit refuses: the document arrived, nothing it needed did, and the empty main element showed the web view's own ground. The build now folds the stylesheet and the bundle into index.html (cssCodeSplit off, iife output), and refuses to produce anything else: a missing tag, a leftover ./assets/ reference, or module-only syntax in a classic script all fail the build, because each of those is the same white window by another route. `dist/` holds one 8 KB file, which is also one signed file to check.

Measured at the panel's own 420px in a browser, not by eye at a desk: - Buttons now wear the assistant's `Button` variants rather than my own shapes: min-height 36 at px-4, rounded-md, strong at body size, the sunk plum gradient for the primary. The primary had been a flat --primary, which is the token the palette keeps bright for links and glows. - The primary was stretching to the card's full width (a flex child's default), which reads as a progress bar. It sizes to its label now. - Two dividers became one: sections bring only their `FormSectionTitle` rule, and the bar top is the window's single hairline. The section borders were mine. - The bar's right group ran to x=435 in a 420px document and its last button was cut off. The bar wraps between the two groups instead of inside their labels, since `whitespace-nowrap` on a button is the rule. - The refusal moved above the card, where the assistant's frame puts its problem line: it is why the screen still looks like this, so it has to be read before the failed button is pressed again. - A granted permission offers no "Allow…" button. A prompt that cannot appear looks like a hang. - The login item got its own row and its sentence moved there, so `stateLine` states the state and one line says where to fix approval. - `.panel` no longer sets `min-height: 100vh`, which made the height the page reports to the window depend on the window. The five `--button-primary-*` values move to packages/assistant/tokens.css, which is where the design system says to add a colour once: the SPA and both desktop assistants declared the same five, and the panel needs them too.

The bottom row mixed a plum text link with two buttons that have no outline until you hover them, so it read as three unrelated things that wandered in from other screens. macOS puts a window's help at the bottom left and its exits at the bottom right, and that is where they sit now, all four controls in the card wearing the same shape except the one primary. The window went from 420 to 520, which is what the row of labels needs and what stops a status line from wrapping beside the control that fixes it. The number lives in the page's stylesheet and the window follows the box the document reports, so it is declared once; the container's old width constraint would have fought that and clipped the page.

The state word carries the decision now: "Not allowed" in gold, the role the design system reserves for "the owner can fix this here", and "Allowed" in the page's own ink, because a settled fact should not compete for attention with the row that still needs a click. The button says "Allow" and nothing more, since the row already names the permission; its accessible label keeps the whole phrase, where two buttons called "Allow" would be indistinguishable in a list of controls. Label and value also stay together on the left, with only the control pushed to the right edge. Space-between with three children had put "Allowed" a hand-span away from the permission it answers for.

The bar item is an icon, so the menu it opens now says "Subshell virtual display helper" at the top: a person who clicked it without hovering the tooltip had nothing telling them which helper they were in. Minimize helper was greyed out in front of an open window because the menu is built once, at launch, before show() has ever run, and nothing rebuilt it when the panel appeared. HelperSettings now reports visibility changes (show, minimize, and the red button's willClose, observed rather than delegated so the SDK's actor isolation on NSWindowDelegate is not something we have to assume), and the app rebuilds the menu from them.

"Starts at sign-in with macOS." is already true, so it wears the page's own ink; "Needs approval in System Settings under Login Items." still waits on the person, so it wears gold. That is the same split the permission rows use, and one row of each colour was the tell that the login item had been left reading as metadata. The row's own API took the shape that makes this legible: a label, a state value, and an optional control, so a settled fact simply has no control instead of the caller reaching for a spare element.

Whether the helper comes back after a sign-in is macOS's launch bookkeeping, not part of the person's consent to be captured, so it reads better under its own heading than as the last row of Access. The heading also lets the enable note drop "and starts at sign-in": one fact, said once. The section appears only while the helper is enabled, because a disabled helper has registered nothing to approve and a heading over an empty row is how a panel starts lying about itself.

theogravity

Nine reviewers each covered one slice of the 327-file diff, and every finding below was
re-verified against the head commit by hand. No MAJOR. 19 MINOR, plus non-blocking nits listed
above. The strongest candidates for a fix before merge are the preview Location regression, the
pipe-writer guard that cannot reach its threshold, the missing cursor rescue on a lost capture,
the input budget closing a non-offending socket, the resync verdict reading the previous
connection's base, and the committed docs hero rendering /tmp/subshell-pr465-review as a pane's
working directory.

Two notes on method. PR #463 was merged into this branch rather than into main, so this diff
legitimately carries the pane self-heal work and its changesets; nothing is duplicated on
release. And Swift here is not unchecked: native/display-helper/test.sh compiles every source
but main.swift under -warnings-as-errors and adds a -typecheck pass that covers it, though
the file early-exits off Darwin, so the macOS lane is the only thing that reads it.

Non-blocking nits

packages/helper-panel/src/main.ts:202: every state push rebuilds the open quit dialog and
refocuses Cancel, so a viewer joining mid-Tab makes the red Confirm hard to reach by keyboard.
Build once, update the body text, focus only on creation.
packages/helper-panel/src/strings.ts:104: stateLine has no all-granted wording, so a fully
armed helper reads "Capture and input still require both macOS permissions below." directly
above two rows saying Allowed. Every other line in the file distinguishes its states.
apps/server/web/src/hooks/use-pane-diagnostics.ts:27: useState(false) where its model,
use-pane-copy-mode, uses a lazy initializer, so the HUD renders closed for one frame on mount.
apps/server/api/src/db/types/index.ts:36: previewProxySettings is declared inline with
uncommented properties and a plain string protocol, where every other table has a
*.db-types.ts file, per-property JSDoc and a union.
apps/server/api/src/api/subshells/views-open.route.ts:144: the settings route gates on
web-previews only, so a display-only node cannot read or save preview prefs, which the create
path explicitly supports.
apps/client/desktop/ui/src/__tests__/tokens-match-spa.test.ts:29: the ten colour roles are
restated instead of importing COLOR_ROLES from scripts/design-tokens.ts, so the two guards
can drift when a role is added.
packages/helper-panel/src/... NITs and native/display-helper/main.swift:172: the comment now
under-describes what checks that file, since test.sh:25 added a -typecheck pass that
includes main.swift.
e2e/verify-preview-compat.ts: writes preview-website-mobile.png and
preview-settings-mobile.png, referenced by no page.
scripts/design-tokens.ts:513: readSurfaceCss is exported and called by nothing, so it can
drift from the real merge order unnoticed.

theogravity · 2026-10-28T09:27:36Z

Review findings whose anchor line is unchanged context in this PR's diff, so they could not be posted inline on the review. Each heading gives path:line at head 188b978; bodies are verbatim from the review.