Repository navigation
feat(app-kit): let built-in shell code step aside for the window host - #37454
Conversation
|
Seam lane Decisions taken in this lane, for the reviewer:
|
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing to check. The diff adds no control, label or string a user sees. It only changes when the desktop shell opens or closes app windows, and only for adopted app records that no user has yet. So the missing screenshots leave no gap. [UX-REVIEWED] d6c20f3 Description read[DESCRIPTION-READ] 5345b43066372634e41bdf850a160f3bfd75be363354fbe8a0e1ee635080ad1a That sha256 names everything this verdict read: the PR description, plus the 3 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 |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: both stand-down rules key on the gateway record rather than an app name, and no record in production has a Notes
[DESIGN-REVIEWED] d6c20f3 Description read[DESCRIPTION-READ] 9bb0f00c8efc4a72cc6a0ad13cb5804a9a71b802914831b1f73fac0ca83876d1 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, but one item reverses the documented rule that an app's window closes when the app is disabled, and it does so for every host-served app. Today no app in the repo reaches that path. Notes
What this change shipsInventory (8 items) — 6 justifiedIntent: let built-in Mochi and Crew Companion be adopted without doubled windows, and keep a remote crew's pet once the local copy is off. ADDITION.
[FIRST-PRINCIPLES-REVIEWED] d6c20f3 Description read[DESCRIPTION-READ] e528641e82fba15a4d8ec8f723b55b88e48ce98ae690a9fad8912e19411704ff That sha256 names the PR description this verdict read. 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: |
Code change approver recommendation: A person should decideWhy: the decider thinks the change is probably fine but estimates a 15% chance that this change introduces a defect, above the 12% limit for approving on its own. I'm approving this PR. Nothing blocks it. The stand-down rule (
Serving an app that is switched off here is limited the way the PR says:
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 |
46808b3 to
17e9c90
Compare
|
Replies to the four review findings, all on head 17e9c90 (rebased on main, still one commit). 1. Docs still promised enabled-only serving: fixed. 2. A non-answer could still open the other 3. Untested branches: fixed.
4. The stood-down Mochi keeps its chord reservation: deferred to #37457 ( Gates on this head: |
17e9c90 to
0b8f804
Compare
|
self-added: yes
|
The desktop window host gave an app fixed manifest accelerators and no per-machine state, so a desktop pet could not move onto it: its users rebind its global shortcuts, its defaults differ per platform, its shell code reserves its chords even while disabled, and the crew it shows plus the rebinds live in a shell store a window page cannot read (#36349 left the shortcut gap under "Not a goal"). Generically, with the app id as data: - desktop.shortcuts[].platformAccelerators: a per-platform default, held to the same chord rules (gateway and shell); seam level 8. - The host binds the user's chord per app per machine, and a page's shortcuts() / setShortcut() (bridge level 3) lists and rebinds only the app's declared shortcuts, only right after a press in that window, and onto a chord other than the declared default only when the user pressed that chord there. The new chord is registered before the binding moves, so a refused rebind or reset keeps the chord the app held and never frees it for another app. - A shell owner that is an app's own shell code may reserve { app: true } so the host serving that app id may bind those chords. Mochi keeps a plain reservation until its built-in steps aside (#37454), so the two never register the same chords. One binding is one chord whatever its spelling, so a respelled rebind keeps the chord with its holder. For Mochi, its own shell code (mochi/hostHandOff.js, called from initMochi before the host is created) copies the crew the pet shows and the user's rebinds from mochi-machine.json into the host's gateway choice and bindings for mochi, recording what it copied. It copies again only while the host still holds that value, so a change in the built-in before adoption carries over and a choice made through the host is never overwritten. It leaves core with Mochi's shell code. Built-ins behave as before: no built-in declares a desktop block, so the host serves none of them yet. Part of #26967
The desktop window host gave an app fixed manifest accelerators and no per-machine state, so a desktop pet could not move onto it: its users rebind its global shortcuts, its defaults differ per platform, its shell code reserves its chords even while disabled, and the crew it shows plus the rebinds live in a shell store a window page cannot read (#36349 left the shortcut gap under "Not a goal"). Generically, with the app id as data: - desktop.shortcuts[].platformAccelerators: a per-platform default, held to the same chord rules (gateway and shell); seam level 8. - The host binds the user's chord per app per machine, and a page's shortcuts() / setShortcut() (bridge level 3) lists and rebinds only the app's declared shortcuts, only right after a press in that window, and onto a chord other than the declared default only when the user pressed that chord there. The new chord is registered before the binding moves, so a refused rebind or reset keeps the chord the app held and never frees it for another app. - A shell owner that is an app's own shell code may reserve { app: true } so the host serving that app id may bind those chords. Mochi keeps a plain reservation until its built-in steps aside (#37454), so the two never register the same chords. One binding is one chord whatever its spelling, so a respelled rebind keeps the chord with its holder. For Mochi, its own shell code (mochi/hostHandOff.js, called from initMochi before the host is created) copies the crew the pet shows and the user's rebinds from mochi-machine.json into the host's gateway choice and bindings for mochi, recording what it copied. It copies again only while the host still holds that value, so a change in the built-in before adoption carries over and a choice made through the host is never overwritten. It leaves core with Mochi's shell code. Built-ins behave as before: no built-in declares a desktop block, so the host serves none of them yet. Part of #26967
The desktop window host gave an app fixed manifest accelerators and no per-machine state, so a desktop pet could not move onto it: its users rebind its global shortcuts, its defaults differ per platform, its shell code reserves its chords even while disabled, and the crew it shows plus the rebinds live in a shell store a window page cannot read (#36349 left the shortcut gap under "Not a goal"). Generically, with the app id as data: - desktop.shortcuts[].platformAccelerators: a per-platform default, held to the same chord rules (gateway and shell); seam level 8. - The host binds the user's chord per app per machine, and a page's shortcuts() / setShortcut() (bridge level 3) lists and rebinds only the app's declared shortcuts, only right after a press in that window, and onto a chord other than the declared default only when the user pressed that chord there. The new chord is registered before the binding moves, so a refused rebind or reset keeps the chord the app held and never frees it for another app. - A shell owner that is an app's own shell code may reserve { app: true } so the host serving that app id may bind those chords. Mochi keeps a plain reservation until its built-in steps aside (#37454), so the two never register the same chords. One binding is one chord whatever its spelling, so a respelled rebind keeps the chord with its holder. For Mochi, its own shell code (mochi/hostHandOff.js, called from initMochi before the host is created) copies the crew the pet shows and the user's rebinds from mochi-machine.json into the host's gateway choice and bindings for mochi, recording what it copied. It copies again only while the host still holds that value, so a change in the built-in before adoption carries over and a choice made through the host is never overwritten. It leaves core with Mochi's shell code. Built-ins behave as before: no built-in declares a desktop block, so the host serves none of them yet. Part of #26967
The desktop window host served only apps enabled on this computer's gateway, while Mochi's built-in pet keeps showing a remote crew's Mochi after the local copy is switched off. And the built-in shell code read its /api/apps row by name alone, so an adopted record declaring a `desktop` block would have drawn both the built-in windows and the host's. Two generic rules, naming no app: - hostOwnsAppWindows(rows, name) answers whether a gateway's record for an app carries a manifest `desktop` block. Mochi's and Crew Companion's shell code ask it and stand down on true (Mochi takes its full teardown, a remote pet included). Built-in records declare no block, so nothing changes for a current user. - The host lists apps switched off here too and serves one only from the crew its gatewayChoice points at, while that crew answers that the app is on there. A non-answer keeps the windows still open and holds the app for that tick, so none of its windows is created; a definite no closes them. An app without gatewayChoice declared and approved here is served nothing. Specs: app-kit-platform section 35, mochi.md, electron README, the app-author manifest reference and the desktop_capabilities docstring. Part of #26967
0b8f804 to
d6c20f3
Compare
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
I reviewed head d6c20f3. I read the stand-down rule (hostOwnsAppWindows) and its callers in the Mochi and Crew Companion shell code. I also checked the off-here serving path in the window host: servedDeclarations, the holding set, the createWindow refusal and the deferred background respawn. The window host and rules tests, the Mochi gate tests and the companion stand-down tests all pass. Removing the createWindow hold or the holding mark fails the new off-here tests, so they exercise the new code. An app that is off here is served only from a chosen crew where it is enabled, with that crew's approvals intersected with this computer's, and no shipped record carries a desktop block yet. Nothing blocks.
Problem / Motivation
Goal: A desktop app served by the window host shows exactly one set of windows, and keeps showing from the crew the user chose for it after its copy on this computer is switched off, as Mochi's built-in pet does today.
Two gaps stand between the built-in desktop apps and their adopted copies (#26967):
website/electron/mochi/andwebsite/electron/crew-companion/reads its/api/appsrow by name alone. An adopted record that declares a manifestdesktopblock would get both the built-in windows and the window host's.Why it matters
Mochi and Crew Companion cannot be adopted while either gap stands: every desktop user with them on would see a doubled pet, and a user who runs Mochi on a remote crew with the local copy off would lose the pet on the first start after adoption.
Not a goal
adoption-pins.jsonor the catalog, or deleting any built-in.desktop-host-prefs).What changed (motivation → approach → change)
Approach: two generic rules in the shell's window host, keyed on the gateway's record and naming no app. The built-ins' own shell code calls the first one, so nothing app-specific moves into the host.
app-window-host-rules.js:hostOwnsAppWindows(rows, name)answerstruewhen that gateway's record for the app has a manifestdesktopblock, on or off, even one this shell's rules refuse, andnullfor a body it cannot read.desktopDeclarationstakes{disabledToo}and marks each declarationenabledHere.hosted(read byinstanceGate.localMochiState) and the reconcile takes its full teardown, a remote pet included. A remote whose record the host owns is a definite no for the built-in pet. Crew Companion's probe reads such a record asreleased, beside its check of a non-builtinorigin, and closes its windows on or off.app-window-host.js:servedDeclarationsserves an app that is off here only from the crew itsgatewayChoicepoints at, while that crew answers that the app is on there. A non-answer keeps the windows still open, or a background page waiting to be reopened, and holds the app for that tick, socreateWindowcreates none of its windows (noopenOnEnablewindow, shortcut press,open()or background reopen). The tick that answers yes reopens a waiting background page; a definite no closes the windows and drops it. WithoutgatewayChoicedeclared and approved here, nothing is served.website/electron/README.md. App-author docs:docs/app-kit/manifest-reference.mdand theapps/desktop_capabilities.pydocstring now say that an app switched off here keeps the windows, shortcuts and capabilities a chosen crew still serves it.Backwards compatibility
Compatible: built-in records declare no
desktopblock, so both built-ins serve their apps exactly as on main, and an app that is enabled here is served as before. Old shell with new gateway: a stable shell before this one has no window host, so it never draws both. A 0.13.0 pre-release shell has the host and could, so adopting a built-in that has shell code waits for the release carrying this rule. New shell with old gateway: such a gateway sends nodesktopblock, so the built-in serves as before.APP_SDK_LEVELand the bridgelevelare unchanged: no grammar, gateway or bridge call is added.Removes nothing: no window, route, key or handler is removed. A built-in only stands down for a record that does not exist for any user today.
Tests
test/app-window-host.test.js: an app off here gets its windows from its chosen crew while the app is on there, and they close on a definite no. A non-answer keeps an open window and never creates one, nor brings one back once it has closed. With one of three windows still open, a non-answer from the crew or from core's check of a reused target opens no otheropenOnEnablewindow, and a shortcut press,open()or background reopen opens none either. Once the crew answers, both come back from it. A background page that is the app's last window and dies during a silent tick survives a second silent tick, comes back once the crew answers yes, and stays gone after a no. A local switch-off keeps a crew's windows, and choosing this computer closes them. NEGATIVE: an app off here whosegatewayChoiceis undeclared, staged or missing from the grant gets nothing, and no crew is even asked. One with nodesktopblock, or one skipped at boot, gets nothing either.test/app-window-host-rules.test.js:hostOwnsAppWindows(on/off/refused block true, no block or no row false, unreadable null).disabledToolists only off apps with a valid block.mochi/test/instanceGate.test.js,mochi/test/instanceSwitchRules.test.js,crew-companion/test/hostStandDown.test.js: a host-owned record stands each built-in down.localMochiStateanswershostedfor this computer's record, on or off, even with a refused block. The built-in record keeps its states.test/app-window-host-independence.test.js: every app-owned shell directory askshostOwnsAppWindows.respawnDueclause inservedDeclarationsreverted, the background-page test fails. Each of these mutations fails a test too: dropping the confirm-path non-answer mark, the hold increateWindow, the held background reopen, and thehostedbranch oflocalMochiState.node --testovertest/,mochi/test/,crew-companion/test/): 3862 pass, 0 fail on the first head. This head, run on a host withoutnode_modules: the host, rules, span, Mochi and companion files give 441 pass and 1 fail,mochi/test/petOverlays.test.js(Cannot find module 'electron'), which this diff does not touch. No sleep or port, and one injected clock: hosts are driven tick by tick with injected fetch.app-window-host.test.jsandhostStandDown.test.jsran 10 times in a row, 0 fail; Node 22's runner has no shuffle flag, so the new test also ran alone (--test-name-pattern), green.test_flake_pattern_ratchet.py,test_app_manifest_desktop.py,test_app_desktop_capabilities.pyand the tests that readmanifest-reference.mdpass.Proof: not provable -- frontend test (prove.py runs Python only)
Manual verification
N/A — not run against a live desktop here. The host, the Mochi gate and the companion probe are pure or are driven through their exported functions with Electron stubbed, as the existing suites do.
Screenshots / video
N/A — no rendered surface changes. The diff touches shell window lifecycle only, with no watched
website/src/path.Related Issues
Part of #26967
Authority: owner ruling #26967 (comment) (desktop-shell seam; no app code in the Electron main process; users' normal use unaffected), building on ruling item 5 of #26967 (comment) (the desktop window host).
Overlaps:
origin) has merged; this branch sits on it andprobeEnabledkeeps both checks, each answeringreleased. No shared helper is duplicated: this PR ownshostOwnsAppWindows.desktop-host-prefs(feat(app-kit): keep desktop app shortcuts and prefs per machine #37457: app shortcuts, per-machine prefs, and the stood-down built-in's chord reservation, handed to the host serving that same app) andapp-chat-slot-create. This PR leavesmochi/shortcuts.jsandshell-shortcut-reservations.jsalone; feat(app-kit): keep desktop app shortcuts and prefs per machine #37457 and this PR both edit §35, mochi.md, the README, the window-host files and the manifest reference, so whichever lands second rebases.Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)