Skip to content

fix(pwa): keep app windows out of shell fallback - #13205

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
Skymore:fix/app-window-sw-fallback
Sep 24, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
Skymore:fix/app-window-sw-fallback

Conversation

@Skymore

@Skymore Skymore commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

A macOS dogfood run with Mochi enabled on an external display left a full Dashboard page covering that display inside an always-on-top, non-focusable window. The window had no controls and could not be dismissed normally. Inspection showed that the Mochi overlay requested its standalone pet page, but the active Service Worker satisfied the failed navigation from the cached Dashboard shell. This latent behavior predates #12126; validating that merged fix made the failure visible.

Why it matters

Mochi and Crew Companion use frameless windows that cover an entire display. Showing the Dashboard shell or a browser error document inside one can make that display unusable until the overlay is destroyed or the app exits.

What changed

The Dashboard Service Worker in website/public/sw.js now leaves every /app-windows/ request to the browser instead of treating standalone window documents as SPA routes. Dashboard navigation fallback and the existing retry behavior for /assets/ and /vendor/ resources remain unchanged.

A shared Electron error-document latch now owns the HTTP status, transport failure, sub-frame, superseded-navigation, and blanked-window semantics used by Mochi and Crew Companion. Each host keeps its own visibility, credential delivery, retry cadence, target switching, and ownership lifecycle. No dependencies or lockfiles change; website/electron/package.json only includes the shared module in electron-builder's explicit packaging allowlist.

Crew Companion's host under website/electron/crew-companion/ uses that latch for both display overlays and its hidden notification owner. A main-frame 4xx/5xx response or transport failure immediately hides a display overlay, restores click-through input, and keeps an error document from becoming the notification owner. The existing enabled-state reconcile loop reloads only failed windows, and only after the gateway accepts the current credential.

docs/system-specs/modules/app-kit-platform.md and the remote/mobile cache guide now describe this boundary.

Pattern harvest

Rule candidate: every frameless full-display app window must bypass the Dashboard SPA shell fallback and fail closed before a non-successful main-frame navigation can reveal content or establish background ownership.

Tests

  • The new Service Worker regression test fails against the prior implementation because it intercepts /app-windows/ navigation, then passes with the exclusion.
  • serviceWorkerSkipRules.test.ts: 16/16 passed, including Dashboard fallback preservation and app-window asset retry coverage.
  • The shared latch plus Mochi and Crew Companion targeted tests: 104/104 passed.
  • Crew Companion tests: 68/68 passed, covering HTTP error documents, transport failure, immediate click-through, display-overlay and notification-owner recovery with an accepted credential, harmless sub-frame failures, and existing token/suspend behavior.
  • Full Electron test suite: 2,083 passed / 3 skipped, including the packaging allowlist guard.
  • TypeScript production build, targeted ESLint, documentation lint, and diff checks passed.
  • The repository change-scoped gate passed every applicable frontend, Electron, static, and documentation check. Its broad backend suite remains non-runnable on this restricted agent host and reproduces the same environment-only failures on a clean main; GitHub CI remains authoritative for that matrix.

Manual verification

The original failure was reproduced on Electron 43 and macOS 26 with an external display. WindowServer and Electron inspection identified the covering window as a live Mochi overlay whose pet-page request was served the cached Dashboard shell. The abnormal overlay was destroyed and rebuilt with the correct pet page without restarting the Dashboard session or gateway.

Related Issues

No linked issue: this latent cross-surface cache bug was discovered while validating post-merge feedback on #12126.

Checklist

  • One Conventional Commits change
  • Existing tests pass and regression tests cover the failure
  • Documentation updated in the same commit
  • No dependency or lockfile changes
  • No secrets, credentials, or internal-only references in the diff

@Skymore
Skymore requested review from a team and CrysisDeu September 23, 2026 23:11
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 23, 2026
@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5, fork) — ✅ PASS

UX-level review of 01cfebb38f21d3b9a6e8ed2461c786aab27ca95d via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Verify on a real multi-display run that a blanked Crew Companion overlay reappears within the reconcile cadence after gateway recovery — the author's manual repro covered Mochi, not Crew Companion.

[UX-REVIEWED] 01cfebb

@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of 01cfebb38f21d3b9a6e8ed2461c786aab27ca95d via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify rollout: an already-installed stale sw.js still serves the shell into overlays (a cached 200 defeats the latch) until clients pick up the update.

Suggestions

  • The rewritten shell-put test (/app-windows/mochi/panel.html → /artifacts) is sound — the skip rule now supersedes the old pin — but note that lineage in the test comment so a future reader doesn't read the swap as lost coverage.

[DESIGN-REVIEWED] 01cfebb

@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ✅ PASS

Premise-level review of 01cfebb38f21d3b9a6e8ed2461c786aab27ca95d via the fork AI-review pipeline — 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/CONCERNS are advisory.

First-Principles-Verdict: PASS

Verify the did-navigate/did-fail-load-before-did-finish-load ordering premise on Windows/Linux Electron — manual repro covered macOS only, and the reveal guard rests on it.

What this change ships

Inventory (8 items) — 8 justified

Intent: stop a failed standalone app-window navigation from filling a frameless full-display overlay with the cached Dashboard shell or an error document — a FIX, with regression test failing on base.

  1. Failed /app-windows/ navigations no longer get the cached Dashboard shell (service worker skips them) — justified
  2. Mochi's existing error-latch code moved into a shared Electron module, behavior unchanged — rides along; justified as the mechanism items 3–5 reuse
  3. Crew Companion display overlays now hide and release clicks on a 4xx/5xx or transport failure — rides along, declared; justified (full-display, non-focusable, undismissable harm named without the Mochi twin)
  4. Crew Companion's hidden notification owner no longer initializes on an error document — rides along, declared; justified
  5. Crew Companion's reconcile tick now reloads latched windows with the accepted credential — rides along, declared; justified (a latched window would otherwise stay hidden forever)
  6. App-window asset sub-resources keep the existing /assets/ retry — justified
  7. Shared module added to electron-builder packaging allowlist — justified
  8. Specs updated same-commit (app-kit-platform, remote-and-mobile) — justified (AGENTS.md mandate)

Checks run: base sw.js:137-155 confirms navigation fallback previously applied to app-window documents; frameless full-display hosts grepped (frame: false + display-bounds), count 2 (Mochi, Crew Companion pet overlays — both covered; panel/gallery/snip windows are small dismissable cards, different harm class); createAppWindowErrorLatch consumers: 2 production.

[FIRST-PRINCIPLES-REVIEWED] 01cfebb

@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed 01cfebb38f21d3b9a6e8ed2461c786aab27ca95d via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 01cfebb

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 23, 2026
@github-actions

github-actions Bot commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review (fork) — ✅ no blocking findings

Reviewed 01cfebb38f21d3b9a6e8ed2461c786aab27ca95d via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 01cfebb

@Skymore
Skymore force-pushed the fix/app-window-sw-fallback branch from e40a370 to a13135d Compare September 24, 2026 00:06
@Skymore

Skymore commented Sep 24, 2026

Copy link
Copy Markdown
Contributor Author

span=be25fce19271
self-added: yes
mechanism: one reconcile-owned failure latch for display overlays and the hidden notification owner

fixed
The hidden brain now latches main-frame HTTP and transport failures, skips owner initialization on error documents, and reloads only after the enabled-state probe accepts the current credential.
a13135d34 adds deterministic HTTP, transport, and owner-recovery coverage; Crew Companion is 68/68 and the full Electron suite passes.

@Skymore

Skymore commented Sep 24, 2026

Copy link
Copy Markdown
Contributor Author

span=fc1563beba2e
self-added: yes
mechanism: one reconcile-owned failure latch for display overlays and the hidden notification owner

fixed
The recovery path now includes the live brain window: failed owner documents stay inert and the accepted-credential reconcile reloads the brain together with any failed overlays, without an immediate retry loop.
a13135d34 verifies both HTTP and transport failures plus recovered owner initialization; Crew Companion is 68/68 and the full Electron suite passes.

@Skymore

Skymore commented Sep 24, 2026

Copy link
Copy Markdown
Contributor Author

span=3cd865fb85b6
self-added: yes
mechanism: keep runtime recovery exports separate from test-only latch inspection

fixed
hasBlankedOverlay is no longer a runtime export. Tests access it only through the _hasBlankedOverlay entry in the module's explicitly test-only export section; the runtime surface now exports only rearmBlankedCompanionWindows.
a13135d34 passes targeted ESLint and all 68 Crew Companion tests.

@Skymore
Skymore force-pushed the fix/app-window-sw-fallback branch from a13135d to c2c060f Compare September 24, 2026 00:36
@Skymore

Skymore commented Sep 24, 2026

Copy link
Copy Markdown
Contributor Author

span=f1b008c24e58
self-added: yes
mechanism: expose only runtime recovery and the test state that tests actually inspect

fixed
The unused _isOverlayErrorPage export is removed. The module now exposes only the runtime recovery function plus _hasBlankedOverlay, which the regression tests directly consume.
c2c060fe9 passes targeted ESLint and all 68 Crew Companion tests.

@Skymore

Skymore commented Sep 24, 2026

Copy link
Copy Markdown
Contributor Author

span=5a6f5c9634fc
self-added: yes
mechanism: keep app-specific lifecycle and credential ownership local while pinning the shared behavior contract

rebutted
Mochi and Crew Companion do not share one recovery state machine: Mochi switches local/remote targets and cookie/query credential delivery, while Crew Companion owns a separate hidden notification producer, bubble state, and display registry.
Extracting their small event predicates would add cross-app coupling without removing those distinct recovery paths. Each module independently pins HTTP status, transport failure, ERR_ABORTED, sub-frame, reveal, and reconcile behavior; the system spec states their shared contract.

@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 Sep 24, 2026
@Skymore
Skymore force-pushed the fix/app-window-sw-fallback branch from c2c060f to 7b4ff3a Compare September 24, 2026 01:19
@Skymore

Skymore commented Sep 24, 2026

Copy link
Copy Markdown
Contributor Author

span=7c01a9c496a7
self-added: yes
mechanism: one shared app-window error latch with app-owned visibility, credentials, and recovery

fixed
app-window-error-latch.js now owns HTTP status, transport failure, ERR_ABORTED, sub-frame, blanked-state, and rearm iteration semantics for both Mochi and Crew Companion.
Each host retains only its distinct window, authentication, target-switching, and owner lifecycle. Shared plus host tests pass 104/104; full Electron passes 2,083/3.

@Skymore

Skymore commented Sep 24, 2026

Copy link
Copy Markdown
Contributor Author

span=9164f7121eb4
self-added: yes
mechanism: centralize cross-host error classification and latch state

fixed
The duplicate predicates, abort code, WeakSet, handlers, and rearm iteration are replaced by app-window-error-latch.js; Mochi and Crew Companion compose separate latch instances with host-specific actions.
The shared module has direct unit coverage and both existing host suites remain green.

@Skymore

Skymore commented Sep 24, 2026

Copy link
Copy Markdown
Contributor Author

span=084fa6883c12
self-added: yes
mechanism: apply the shared failure latch to the hidden notification owner

rebutted
The owner loads the same standalone pet document as the overlays. Leaving its HTTP/transport error document live removes the companion's completion and approval subscriber for the remaining app lifetime, which both GPT and Opus independently reproduced from the call path.
Tests prove the failed owner stays inert and resumes ownership only after a healthy reload.

@Skymore

Skymore commented Sep 24, 2026

Copy link
Copy Markdown
Contributor Author

span=1fb8db357f2d
self-added: yes
mechanism: rearm failed windows only after the existing enabled-state probe accepts credentials

rebutted
Recovery is deliberately owned by the existing 5-second reconcile: an unknown or unauthorized probe returns before rearm, while an accepted credential reloads only latched windows. No failure event performs an immediate retry.
End-to-end tests fail both overlay and owner loads, complete a real successful probe, and verify both reload with that accepted credential; token reuse and suspend tests remain green.

@Skymore

Skymore commented Sep 24, 2026

Copy link
Copy Markdown
Contributor Author

span=f329890e9247
self-added: yes
mechanism: test shell-cache scope on a request the worker actually handles

fixed
The shell-cache ratchet now drives /artifacts, which the worker intercepts but isShellPath excludes. The app-window skip remains independently asserted through intercepts(...).
Removing isShellPath now changes the observed cache writes and fails the ratchet; all 16 Service Worker tests pass on 7b4ff3ad1.

Standalone app-window navigations are not SPA routes. Let the browser handle them so an offline shell cannot fill a frameless overlay.
@Skymore
Skymore force-pushed the fix/app-window-sw-fallback branch from 7b4ff3a to 01cfebb Compare September 24, 2026 01:38
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Sep 24, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) September 24, 2026 06:52

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Approving after an automated readiness screen against this head:

  • readiness: passed label present and the PR Readiness required status is green on this head
  • no failing, cancelled or pending required check on this head
  • mergeable with no conflict against current main
  • no live reviewer CHANGES_REQUESTED (GitHub reviewDecision is not CHANGES_REQUESTED)
  • every review-lane finding on this head is either PASS, withdrawn, disposed of by the author, or advisory-only — no unresolved blocking change request

Auto-merge (squash) is enabled; branch protection still gates the merge.

@bolichen97
bolichen97 merged commit 698e15e into kirodotdev:main Sep 24, 2026
97 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 24, 2026
wknight1 pushed a commit to wknight1/KiroCrew that referenced this pull request Oct 5, 2026
Standalone app-window navigations are not SPA routes. Let the browser handle them so an offline shell cannot fill a frameless overlay.

Co-authored-by: Rui Tao <ruit@amazon.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants