Repository navigation
feat(app-kit): span a desktop overlay across displays, add background windows - #36338
Conversation
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS No design-level concerns: the desktop seams are additive, manifest-declared and shown on the trust prompt, and the companion's moved helpers are a faithful extraction. Notes
[DESIGN-REVIEWED] c2a477c Description read[DESCRIPTION-READ] d48b1e02e36fff1fbb137d49c682ccf403ec696cdb47a9ae5282b77ae38c018c That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. Each item is a manifest-declared App Kit seam that the companion's move out of core (#26967) needs, as AGENTS.md "No built-in apps" requires. Duplicated placement and dashboard-session code is merged, not copied. Notes
What this change shipsInventory (9 items) — 9 justifiedIntent: let an app float one avatar across all displays and run a hidden notification page from its manifest, so Crew Companion can leave core. ADDITION.
[FIRST-PRINCIPLES-REVIEWED] c2a477c Description read[DESCRIPTION-READ] ccacd958e954f4a248e818c46492f91afba34fb1b3b7ae3a27ac4b1e09ef6c67 That sha256 names the PR description this verdict read. Recompute it with |
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing blocks. The new desktop box only describes what the app asks for. The screenshots show all five of its lines, and the blind reader understood each one. Notes
[UX-REVIEWED] c2a477c Description read[DESCRIPTION-READ] 6cd5188a0c28d033e5ad487c698e7e6ed800a11f5e6b45ecc0eb725e4453e513 That sha256 names everything this verdict read: the PR description, plus the 7 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
23cdfa4 to
1f27a2a
Compare
|
span=6102ff5ef8d9 fixed in 1f27a2a
|
|
span=904770182ef4 fixed in 1f27a2a
|
|
span=425976e6ecb7 fixed in 1f27a2a
|
|
span=92a7cf73bc95 fixed in 1f27a2a
|
c91066c to
33b61f3
Compare
|
span=425976e6ecb7 fixed in 33b61f3
|
|
span=425976e6ecb7 fixed in 33b61f3
|
33b61f3 to
1e93f3a
Compare
|
self-added: yes
|
Code change approver recommendation: A person should decideWhy: the decider thinks the change is probably fine but estimates a 20% chance that this change introduces a defect, above the 12% limit for approving on its own. The PR adds a spanning overlay (
An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit |
1e93f3a to
fee9959
Compare
|
self-added: yes
|
fee9959 to
b86ff5c
Compare
|
CI red on fee9959: |
b9518b5 to
15f0cb9
Compare
|
self-added: no
|
15f0cb9 to
1f0f26f
Compare
|
self-added: yes
|
1f0f26f to
8de3735
Compare
|
self-added: yes
|
|
self-added: yes
|
… windows The desktop window host can now serve what Crew Companion's main-process code does, generically and only as an app's manifest declares it, so the companion can move to its own repository with no shell code of its own (owner ruling on #26967, comment 6841699202, item 3). An overlay declared `displays: "all"` gets a copy on every display with the app's avatar on exactly one; the shell follows a drag across a display edge and hands the avatar over, and remembers the display. A `background` window is a page that is never shown and is reopened at once if it dies, for work that must outlive any one display. An app's windows can message each other through the host, hear when another opens or closes, open a panel beside a box (a panel `gutter` leaves its transparent margin out of the placement), raise the dashboard on a session and open an https link. Nothing reaches another app's windows, and only a window the user is acting in (the pointer over an overlay's regions, a focused panel) may raise the dashboard or open a link; a background page may do neither and opens windows without focus. The trust prompt lists the window shapes a manifest declares. The bridge is level 2 and the manifest grammar is App Kit seam level 7. No app declares a desktop block today and the built-in companion keeps its own windows until its repository copy is adopted, so nothing changes for a user. The companion's dashboard-routing check moves to a shared module the kirocrew:// deep link also uses.
8de3735 to
c2a477c
Compare
|
Status on c2a477c: every check green,
|
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Approving. The review on this head read the full diff and the head code around every changed path: window record lifecycle, every new IPC handler, app-window-span.js, the preload bridge, dashboard-session.js and its callers, the Python and JS manifest grammars, and the trust prompt feed sites. The PR's Electron test files and the companion's tests pass on this head (195 tests). Spot mutations on the press gate, background refusal, auto-repeat, https check and broadcast app scope each red a test. Nothing is already on main, and no open PR duplicates this one.
Security: the new channels resolve the sender by its own window and document, and act only on that app's declared windows, so nothing crosses apps. Messages are copied, size capped and queue capped. openExternal is https only and goes through openExternalSafely, and showSession reuses the foreign-origin refusal. Background windows are never shown, have content protection and take no focus. showSession, openExternal and drag start need a native Electron input-event press, which page script cannot fake, with one request per press.
Done well: the companion's dashboard-session and placement logic moved into shared modules unchanged, so its foreign-origin guarantees now live in one copy.
Optional:
app-window-span.js:346: the drag safety timeout is the only recovery from a lost release, and nothing tests it, because thefakeTimers()fake dropssetTimeout. Recording timeouts the way it records intervals would let one test pin it.scripts/adoption_pin.py:147: the spec says a pin declaringdisplays: "all", abackgroundwindow or agutterneedsminAppSdkLevel7, but_seam_level_usesdoes not map these keys yet.## Backwards compatibilitycould also list the panel changes: a focused reveal now callsfocus(),keepHostInDock()now runs for panels, and reopening an open panel brings it forward.
Problem / Motivation
Goal: An app can float one avatar across every display and keep a hidden notification page running, declared in its manifest and served by the desktop shell, so Crew Companion can leave core with no main-process code and behave exactly as it does today.
Crew Companion's desktop behaviour lives in
website/electron/crew-companion/(main-process code): one avatar shared across all displays with drag hand-off, a hidden window that owns notifications and relays them to the avatar, a panel opened beside the avatar, a gallery, opening a session in the dashboard, opening an https link, and turning itself off. The generic desktop window host (#32654) offers only an overlay on the display under the cursor and fixed-position panels, so the companion cannot move onto it. The owner ruling on #26967 (comment 6841699202, item 3: "decide directly; users' normal use must not be affected; grant what is needed") asks for these as generic, manifest-declared seams shown at install.Why it matters
Without them Crew Companion cannot leave core (#26967), and every built-in that ships main-process shell code is code the Electron shell runs for one app. With them, an app repository can ship the companion as a plain App Kit app whose windows the shell hosts, with no app code in the main process.
Not a goal
website/electron/crew-companion/are separate changes. The built-in keeps its own windows until its copy is adopted.POLICY ∩ PROFILE: the window shapes are declared in the existingdesktopblock, reach nothing outside the app's own windows, and are shown on the trust prompt.What changed (motivation → approach → change)
Goal: every shell behaviour the companion's main-process code gives it, as generic, manifest-declared host features. Approach: extend the existing
desktopblock and window host rather than add a second seam, keep each new mechanism in its own app-agnostic module, and keep the companion's exact geometry and timing.apps/desktop_manifest.py, mirrored inapp-window-host-rules.js): an overlay may declaredisplays: "all"; a newbackgroundwindow kind; a panelgutter(0 to 48). At most one spanning overlay and one background window per app. Defaults are omitted fromto_dict, so existing declarations sign the same.app-window-span.js): a copy per display, one active; drag hand-off following the global cursor at 16 ms, the drag alone deciding every copy's pointer until the release, settling on a copy still loading when it is ready; remembered display (0600 file in the shell's data dir); display hot-plug and removal; messages to the window go to the active copy and follow it.send,broadcast,onMessage,onWindowChange,close(id),closeAll(),open(id, {anchor})placing a panel beside a box (app-window-placement.js, the companion's placement maths),onPlaced. Never across apps.showSession(slotKey)(raises the dashboard on/chat?sid=, viadashboard-session.js, the companion's check, now shared with the kirocrew:// deep link) andopenExternal(https only). Answered only within 2 s of a mouse or key press the shell itself saw start in the window (Electron'sinput-event), one request per press, never from a background page. A drag start needs the same press, so a page's timer can do neither.desktopblock (registry_pipeline/manifests.py), and a desktop box lists the declared shapes (TrustAppDesktopBox.tsx), fed fromAppDetailPage.tsxanduseAppActions.ts; six keys inen.manual.jsonand the 11 translation catalogs,en-XA.jsonregenerated.desktopWindowTarget.ts); manifest grammar joins App Kit seam level 7, whichagentReadOnlyDirs(feat(app-kit): let an app's manifest fence its own dirs from agent writes #33589) already raised; level 7 is shared by the seams of Move every built-in app out to KiroCrewApps and forbid built-in apps #26967 (ruling: comment 6844003956), so the level lists inapi-reference.mdandapp-kit-platform.mdgain a row and an app feature-detects thedisplayskey, never the level alone. Lane desktop-mochi touches the same host files and rebases on whichever lands first.app-kit-platform.md§32 and §35,manifest-reference.md,api-reference.md,website/electron/README.md.Backwards compatibility
Compatible: the manifest grammar only gains optional keys and a kind; every declaration main accepts parses to the same window (plus the spelled-out defaults the shell keeps internally) and signs the same; no shipped app or catalog entry declares a
desktopblock, and the built-in companion is untouched in behaviour.Removes nothing: every manifest, bridge call and export that works on main works the same;
crew-companion/index.jskeeps exportinghostsDashboardandopenDashboardSession(now thin wrappers overdashboard-session.js), and the only shape change is that a transparent panel no longer gets a native shadow, which no app declares.Tests
website/electron/test/app-window-host-span.test.js(new, two-display fake): one copy per display with the cursor's active; the remembered display wins; a drag hands the avatar over at the crossing point, every copy takes the release, the display is remembered 0600; a display with no copy keeps the avatar clamped; only the avatar's copy takes the pointer; messages wait for the avatar's copy and follow the hand-off; a closed spanning window drops messages; nothing reaches another app or an undeclared window or passes the size cap; broadcast reaches every other window of the app only; a background page is never shown and is reopened at once, but a crash loop runs at tick cadence; an anchored panel's card goes beside the anchor with its gutter outside, re-opening re-places it, and an oversize one is no bigger than its work area with its card inside the placement margin; late-loading pages hear which windows are open;closeAll; display removal hands the avatar to a survivor, and removing the only display a copy was on (an undock) moves the window instead of closing it; a copy plugged in mid-drag takes the release; a drag released over a copy still loading settles the avatar there once that copy is ready; a copy that clears its regions mid-drag still takes the release when the avatar comes back; an on-demand background page that dies twice at once is reopened by the next tick unless closed on purpose; only a window the user just pressed in may raise the dashboard or open an https link, one request per press, a click's release or a key repeat is not another press, and a page cannot start a drag or pass as acted in without one; a background page opens windows without focus or an anchor.app-window-host-rules.test.js,test/test_app_manifest_desktop.py: the new grammar parses and round-trips, and each refusal (unknown span, span on a panel or background, gutter on an overlay or past 48, two spanning overlays, two background windows) is refused on both sides.app-window-preload.test.js: the bridge exposes exactly the level 2 calls and each event passes only well-formed arguments.test/test_apps_registry_coverage_manifests.py: a registry row carries thedesktopblock.website/src/test/TrustAppModalDesktop.test.tsx: the box lists exactly the declared shapes, is absent without a block, and the Library carries the request.--sequence.shuffle, seeds 7 and 91); the Python file passes 3 serial runs and under-n 4. No sleeps, clocks are injected (now, drag timers), no ports.npm run i18n:check,tsc -p tsconfig.app.json, black, flake8, mypy, comment-history, brand and line-cap gates: green.Proof: not provable -- frontend test
Manual verification
The shell itself was not run against a live multi-display desktop here; the two-display Electron stand-in drives every window, IPC and screen call the host makes. The trust prompt box was rendered with the real modal (screenshots below).
Screenshots / video
Trust prompt, an app with a spanning overlay, a background page and a panel (dark, light, German), and one with an overlay and a shortcut:
More
Related Issues
Part of #26967
Owner ruling: #26967 (comment)
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.