Skip to content

feat(app-kit): span a desktop overlay across displays, add background windows - #36338

Merged
bolichen97 merged 1 commit into
mainfrom
feat/w5-desktop-companion
Nov 13, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
feat/w5-desktop-companion

Conversation

@bolichen97

@bolichen97 bolichen97 commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

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

  • Moving Crew Companion itself: its repository copy, its adoption pin and deleting website/electron/crew-companion/ are separate changes. The built-in keeps its own windows until its copy is adopted.
  • Mochi's desktop seams (screen capture, local files, gateway choice): lane desktop-mochi.
  • Any new grant family or change to POLICY ∩ PROFILE: the window shapes are declared in the existing desktop block, 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 desktop block 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.

  • Manifest (apps/desktop_manifest.py, mirrored in app-window-host-rules.js): an overlay may declare displays: "all"; a new background window kind; a panel gutter (0 to 48). At most one spanning overlay and one background window per app. Defaults are omitted from to_dict, so existing declarations sign the same.
  • One avatar across displays (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.
  • Background window: never shown, never throttled, invisible to capture, reopened at once if its page dies (at most once per tick interval).
  • Between an app's windows: 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.
  • Shell asks: showSession(slotKey) (raises the dashboard on /chat?sid=, via dashboard-session.js, the companion's check, now shared with the kirocrew:// deep link) and openExternal (https only). Answered only within 2 s of a mouse or key press the shell itself saw start in the window (Electron's input-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.
  • Trust prompt: a registry row now carries the manifest's desktop block (registry_pipeline/manifests.py), and a desktop box lists the declared shapes (TrustAppDesktopBox.tsx), fed from AppDetailPage.tsx and useAppActions.ts; six keys in en.manual.json and the 11 translation catalogs, en-XA.json regenerated.
  • Levels: bridge level 2 (typed, optional, in desktopWindowTarget.ts); manifest grammar joins App Kit seam level 7, which agentReadOnlyDirs (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 in api-reference.md and app-kit-platform.md gain a row and an app feature-detects the displays key, never the level alone. Lane desktop-mochi touches the same host files and rebases on whichever lands first.
  • Specs: 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 desktop block, 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.js keeps exporting hostsDashboard and openDashboardSession (now thin wrappers over dashboard-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 the desktop block.
  • website/src/test/TrustAppModalDesktop.test.tsx: the box lists exactly the declared shapes, is absent without a block, and the Library carries the request.
  • Mutation check: removing each of 20 new behaviours (hand-off, background refusal, respawn, respawn rate, broadcast scope, acting-sender gate for an overlay and for a panel, background focus, https check, gutter, inactive drag, inbox flush, size cap, late-loader notice, re-placement notice, inactive click-through, bring-forward, remembered display on transfer, closed-span drop, drag-end click-through) fails at least one test.
  • Determinism: the four host test files pass 10 repeats in a row; the vitest file passes shuffled (--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.
  • Full Electron suite: 3743 pass, 0 fail. Related vitest groups (trust modal, app detail, apps page, i18n, desktop window): green. 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:

spanning dark

spanning light

More

shortcut dark

spanning dark de

Related Issues

Part of #26967

Owner ruling: #26967 (comment)

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of c2a477c31207b5917b343c9cd81a3fccd8a84fad — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of c2a477c31207b5917b343c9cd81a3fccd8a84fad — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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

  • Item 1 — zero consumers today: "no shipped app or catalog entry declares a desktop block". The only planned consumer is the companion app repository, which is a separate change. Subtraction: none needed now, but if that adoption stalls, delete displays: "all", background and gutter rather than carry them unused.

What this change ships

Inventory (9 items) — 9 justified

Intent: 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.

  1. Manifest overlay may span every display (displays: "all"), with drag hand-off and a remembered display — justified
  2. New background window kind: hidden, never throttled, reopened if it dies — justified
  3. Panel gutter key (0–48) — justified
  4. An app's windows can message, close and open one another, and place a panel beside an anchor; never across apps — justified
  5. Pages may ask to show a dashboard session or open an https link, only right after a real user press — justified
  6. Trust prompt lists the declared desktop shapes; registry row carries the desktop block — justified
  7. Companion placement maths and dashboard-session check now each have one shared copy (app-window-placement.js, dashboard-session.js) — justified
  8. A transparent panel no longer gets a native shadow — justified
  9. Bridge level 2, seam level 7 rows, six i18n keys, capture fixture — justified

[FIRST-PRINCIPLES-REVIEWED] c2a477c

Description read

[DESCRIPTION-READ] ccacd958e954f4a248e818c46492f91afba34fb1b3b7ae3a27ac4b1e09ef6c67

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of c2a477c31207b5917b343c9cd81a3fccd8a84fad — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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

  • The box sits right under "Trusting the app grants all three… cannot limit it to less", and the blind reader "can't tell whether its items are extra powers on top of 'all three'". Change the desktop_heading wording so it says these windows come in addition to the three grants, or that they are how the app appears on screen.
  • The blind reader also couldn't tell whether desktop_background ("A hidden page that keeps running…") and the existing "Keep a program… running… in the background" are one thing or two. Reword one of them so the difference is clear.
  • In the German screenshot (shot-04), the heading wraps onto two lines and the Monitor icon centres between them. In TrustAppDesktopBox.tsx, use items-start on the heading row and nudge the icon down slightly so it lines up with the first line.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed c2a477c31207b5917b343c9cd81a3fccd8a84fad — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] c2a477c

Verdict parsed from the review's SHA-scoped output markers for commit c2a477c31207b5917b343c9cd81a3fccd8a84fad.

False positive or not applicable? A repository writer can comment:
/ai-review override fable c2a477c31207b5917b343c9cd81a3fccd8a84fad false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Nov 13, 2026
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of c2a477c31207b5917b343c9cd81a3fccd8a84fad and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] c2a477c

False positive or not applicable? A repository writer can comment:
/ai-review override gpt c2a477c31207b5917b343c9cd81a3fccd8a84fad false-positive: <reason, 20 to 500 characters>

@bolichen97
bolichen97 force-pushed the feat/w5-desktop-companion branch from 23cdfa4 to 1f27a2a Compare November 13, 2026 03:38
@bolichen97

Copy link
Copy Markdown
Contributor Author

span=6102ff5ef8d9 fixed in 1f27a2a

  • Spanning overlay dropped when its only display goes

fixed: displaysChanged now opens copies for the displays that exist before it closes those whose display went, so an undock moves the window instead of closing it; the copy that inherits the avatar is told so.
pinned by removing the only display a spanning overlay was on moves it to the display that remains (fails with the old order).
self-added: yes

@bolichen97

Copy link
Copy Markdown
Contributor Author

span=904770182ef4 fixed in 1f27a2a

  • Registry installs omit the desktop disclosure

fixed: registry_pipeline/manifests.py now carries desktop under the registry row's manifest, so the trust prompt shows it on a registry install.
pinned by TestMergeManifest.test_the_desktop_declaration_reaches_the_trust_prompt.
self-added: no

@bolichen97

Copy link
Copy Markdown
Contributor Author

span=425976e6ecb7 fixed in 1f27a2a

  • Rate-limited recovery loses on-demand background pages

fixed: a background page that dies again inside the respawn window is marked due and the next tick reopens it whether or not it is openOnEnable; a purposeful close drops the mark.
pinned by a background page opened on demand that dies twice at once is reopened by the next tick.
self-added: yes

@bolichen97

Copy link
Copy Markdown
Contributor Author

span=92a7cf73bc95 fixed in 1f27a2a

  • Hot-plugged copies click-through during a drag

fixed (downgraded, but two lines): a copy created mid-drag takes the pointer at once, and hears onDrag("start") when its page is ready.
pinned by a copy plugged in mid-drag takes the pointer and hears the drag start.
self-added: yes

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 13, 2026
@bolichen97
bolichen97 force-pushed the feat/w5-desktop-companion branch 2 times, most recently from c91066c to 33b61f3 Compare November 13, 2026 04:28
@bolichen97

Copy link
Copy Markdown
Contributor Author

span=425976e6ecb7 fixed in 33b61f3

  • closeAll leaves pending background recovery armed

fixed: closeApp now also drops the app's due background reopens, which have no live record to close.
pinned by the closeAll step of a background page opened on demand that dies twice at once is reopened by the next tick.
self-added: yes

@bolichen97

Copy link
Copy Markdown
Contributor Author

span=425976e6ecb7 fixed in 33b61f3

  • Anchored panels bypass work-area size limits

fixed: anchoredPanel clamps the panel to the work area it opens on, as panelBounds does, before placing the card.
pinned by an anchored panel is no bigger than the work area it opens on.
self-added: yes

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes

  • A late-loading display copy loses the drag's drop position span=92a7cf73bc95

fixed in 1e93f3a: stopDrag keeps the settled point on the span when the copy hosting the avatar is not ready yet, and that copy's activation carries it ({active: true, x, y}) once its page says ready; a new drag or a change of active display drops it.
class swept: the only positioned send skipped for a not-ready copy that nothing later replays is the drag end; a mid-drag hand-off or move is already replayed by sendActiveState's live-drag branch.
pinned by a drag released over a copy still loading settles the avatar there once it is ready (red on 33b61f3, green on 1e93f3a).

@KiroCrewCaptain

KiroCrewCaptain commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: 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 (displays: "all"), a background window kind, a panel gutter, messages between an app's own windows, and two shell requests gated on a real user press (showSession and https-only openExternal). It also lists the declared desktop shapes on the trust prompt.

  • Manifest rules: the Python and JS grammars agree on what they accept and refuse, and signing is unchanged for existing manifests.
  • Lifecycle: the background window is reopened only after a crash or self-close, rate-limited, and never after a deliberate close, disable, suspend or stop. The closedHandled guard prevents double handling of a close.
  • Spanning overlay: span state is dropped before its copies close, display changes open new copies before closing old ones, and inactive copies stay click-through.
  • Trust: showSession and openExternal need native mouse-down or key-down input within 2 s, one request per press, and never from a background page. External links must be https and still pass through openExternalSafely. Messages stay inside the sending app's declaration.
  • Extraction: the dashboard-session and placement code moved out of the companion is a f

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 c2a477c312 · 3136 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@bolichen97
bolichen97 force-pushed the feat/w5-desktop-companion branch from 1e93f3a to fee9959 Compare November 13, 2026 05:55
@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: a spanning copy's pointer state had two writers during a drag (the span drag and the host's hit-region handler)
resolution: removed the second writer -- while a drag runs only app-window-span.js writes a spanning copy's pointer state; the host's hit-region poll and handler both defer through one predicate, dragOwnsPointer

  • Hit-region updates disable release capture during a spanning drag span=425976e6ecb7

fixed in fee9959: the hit-region handler no longer turns a spanning copy click-through while its drag runs, so a page that clears its regions after losing the avatar still takes the release when the avatar comes back; stopDrag returns every copy to click-through and the poll resumes from the stored regions.
class swept: every host-side setIgnore call in app-window-host.js; the poll already deferred to the drag, the handler was the one other writer; blank() hides the page and createWindow's default is overridden by spans.open mid-drag.
pinned by a copy that clears its regions mid-drag still takes the release when the avatar comes back (red on 1e93f3a, green on fee9959).

@bolichen97
bolichen97 force-pushed the feat/w5-desktop-companion branch from fee9959 to b86ff5c Compare November 13, 2026 06:58
@bolichen97

Copy link
Copy Markdown
Contributor Author

CI red on fee9959: Frontend Tests (3) failed src/i18n/style/hiStyle.test.ts > hi register (style/hi.md §4) > [changed-values] addresses the reader as तुम, never आप on three of this PR's Hindi strings (trustAppModal.desktop_heading, desktop_overlay, desktop_panel). Fixed in b86ff5c by moving them to the तुम register (तुम्हारे / तुम / तुम्हारी); all 13 locale style tests pass locally with I18N_BASE_REF=origin/main. Rebased onto origin/main in the same push. GPT and Opus had cleared fee9959.

@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased onto origin/main, which now carries #36504 (the RFC index row that turned main's docs-lint red); docs-lint is green locally on b9518b5. No code change since 1a9eda6, which GPT, Opus, Design, First Principles and UX all passed.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 13, 2026
@bolichen97
bolichen97 force-pushed the feat/w5-desktop-companion branch from b9518b5 to 15f0cb9 Compare November 13, 2026 09:54
@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: no

  • A page's timer-started drag passes the "user is acting" check span=6102ff5ef8d9

fixed in 15f0cb9: the hit poll alone writes a new pointerOver flag (the pointer over the regions a ready overlay reported, on the avatar's copy for a spanning one); beginDrag starts a drag only while it is true, and actingSender reads it instead of lastIgnore, so a drag no copy's pointer started cannot open a link, raise the dashboard, or make every display take the pointer.
a copy the avatar left mid-drag is refused too (spans.isActive), since the poll does not re-read a spanning copy while its drag runs.
pinned by a page cannot start a drag, or pass as acted in, without the pointer over its avatar (red on b9518b5; each of its three gates fails alone when reverted).

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 13, 2026
@bolichen97
bolichen97 force-pushed the feat/w5-desktop-companion branch from 15f0cb9 to 1f0f26f Compare November 13, 2026 10:41
@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: the "user is acting" gates read state the page can set (reported hit regions via pointerOver, a panel's focus)
resolution: removed pointerOver and the isFocused branch; one native-input reading replaces both

  • Acting-sender gate passable by the overlay page alone span=3238aa15c920

fixed in 1f0f26f: each window records Electron input-event mouseDown/mouseUp/rawKeyDown/keyDown (which page script cannot synthesize); openExternal and showSession are answered only within 2 s of such a press and consume it, and beginDrag and a focused open need the same press, so hit regions or focus a page sets count for nothing.
pinned by a page cannot start a drag or pass as acted in without a press the shell saw (full-screen regions, no press: no drag, no link, no session; one press, one request; a press over 2 s old refused) and a window opened by a background page or a page's timer does not take the user's focus; each of the five gates fails a test when reverted alone.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 13, 2026
@bolichen97
bolichen97 force-pushed the feat/w5-desktop-companion branch from 1f0f26f to 8de3735 Compare November 13, 2026 10:55
@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: native-input authorization for the acting gates
resolution: narrowed -- only a press start counts (mouseDown, rawKeyDown, never an auto-repeat); its release no longer re-arms it

  • One mouse click authorizes two privileged shell requests span=425976e6ecb7

fixed in 8de3735: USER_INPUT_TYPES is mouseDown and rawKeyDown only, and an isAutoRepeat key event is ignored, so one physical press arms exactly one openExternal or showSession, which actingSender then consumes.
pinned in a page cannot start a drag or pass as acted in without a press the shell saw: after the press is spent, the same click's mouseUp and a repeating rawKeyDown both leave the next link refused (red with mouseUp back in the set, red without the repeat check).

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: the focus gate on open (added at 15f0cb9) that left an already-open panel unplaced
resolution: removed -- focus no longer authorizes anything (the acting gates read native input), so an overlay or panel opener takes focus as on main and re-places the panel; a background page's anchor is dropped, since its page is never on screen

  • Unfocused panel reopens discard the new anchor span=425976e6ecb7

fixed in 8de3735: a non-background opener opens with focus again, so a reopen with a new anchor always reaches bringForward and its onPlaced; a background page opens without focus and without an anchor, because a box in a hidden 16 px page names no place on screen.
pinned by a background page opens a window without taking the user's focus, and without an anchor (red when its anchor is kept) and a panel opened beside an anchor places its card there and says which side (the reopen re-places).

… 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.
@bolichen97
bolichen97 force-pushed the feat/w5-desktop-companion branch from 8de3735 to c2a477c Compare November 13, 2026 12:27
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/app-kit-platform.md, website/src/i18n/locales/*.json (12 catalogs), src/kiro_crew/apps/routes_enable.py and its tests since this head went green (ca95636 -> 9d0fb32); CI re-running.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 13, 2026
@bolichen97

Copy link
Copy Markdown
Contributor Author

Status on c2a477c: every check green, PR Readiness passed, GPT 6.1 and Opus 5.5 both clean on this head, Design / First Principles / UX PASS; auto-merge (squash) armed, waiting on a maintainer approval.

green_age.py reports main +10 commits (9d0fb32 -> 1ca713c) in files this PR shares, almost all of it the i18n catalogs (hub files that move every hour). Instead of a second re-sync, the merged tree was proven locally: git merge-tree of this head with origin/main 1ca713c is clean, and on that merged tree npm run i18n:check, the i18n + trust-modal vitest files (79 files, 1238 tests, I18N_BASE_REF=origin/main), the app-window host Electron tests, docs-lint and the related pytest files (183) all pass.

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 the fakeTimers() fake drops setTimeout. Recording timeouts the way it records intervals would let one test pin it.
  • scripts/adoption_pin.py:147: the spec says a pin declaring displays: "all", a background window or a gutter needs minAppSdkLevel 7, but _seam_level_uses does not map these keys yet.
  • ## Backwards compatibility could also list the panel changes: a focused reveal now calls focus(), keepHostInDock() now runs for panels, and reopening an open panel brings it forward.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants