Unwind the host-mode stack when navigating to a page you are already inside (CS-12434)

[burieberry]

CS-12434

Why

Host mode only ever pushes onto its stack, so following an in-page link back to a page you are already inside stacks a second copy of it instead of unwinding to it.

Found on the boxel.ai blog: from the index, opening a post pushes it correctly, but the post's "← Back to Boxel Blog" link then pushes the index on top of the post — index → post → index — rather than closing the post and returning to the root. It applies to any host-mode realm with an "up" link.

Cards are only ever handed viewCard; no pop or truncate is exposed to them, so realm content cannot work around it.

What

Opening a card already behind you in the trail is a navigation back to it, so unwind rather than push. Pushing stays correct for a card not yet on the trail:

• the card is the primary card → close the whole stack
• the card is somewhere in the stack → truncate everything above it
• otherwise → push

Applied to both stacks, which is the part worth reviewing. They are separate implementations and only the second one governs the published site:

• OperatorModeStateService#addToHostModeStack — host submode in the workbench (host-submode.gts → viewCard)
• HostModeStateService#pushCard — the published site (templates/index.gts → viewCard)

Dismiss had to move with it

The stack closed its top card on any click outside itself, which undid the unwind: the same click that unwound to a card also read as an outside-click and closed it. The trail emptied, serialize() returned undefined, hostModeStack dropped out of the URL and the whole stack unmounted.

Dismiss is now scoped to the scrim and ignores clicks landing inside a stack item (stack.gts). The breadcrumbs exception drops out — breadcrumbs render outside the scrim and never reached the handler.

Scope, since it affects how much of this needs scrutiny: only host mode was reachable. Submode drives the trail from stack items and breadcrumbs, so no outside-click existed there — verified by reverting the fix, where the submode test still passes while the host-mode one fails. And no visitor could hit it in either mode, because the scrim covers the primary card; only a synthetic click() reaches through. So this was a latent bug the new behaviour exposed, not a production break.

Testing

Run locally against the dev stack: host mode 26/26, host submode 40/40. lint:hbs, lint:types, eslint and prettier clean.

The ViewCardDemo fixtures are already cycles — index → secondary → tertiary → index, and 1 → 2 → 3 → 1 in submode — so the "up" link is genuine rather than contrived.

host-mode-test.gts

• viewing the primary card from deeper in the trail closes the stack — walks down two levels, clicks through to the root, asserts both stack items are gone
• viewing a card already in the trail unwinds to it — seeds [secondary, tertiary], views secondary, asserts tertiary closes and secondary stays on top
• viewing a card below it in the trail unwinds to that card — the same unwind by the route a visitor can actually take, clicking a stack item's own button
• clicking the scrim closes the top card of the trail — regression cover for the dismiss change

host-submode-test.gts — the unwind, and dismiss by scrim. That side had no unwind coverage at all, so addToHostModeStack was shipping untested.

One assertion fixed while here: the query-param check read window.location, which in an acceptance test is the test runner's own URL and never carries app params, so it passed regardless of behaviour. The new assertions read currentURL().

Notes

Not a regression. The behaviour has been push-only since the stack landed in #3361 and viewCard was wired to it in #3381; no commit has touched those function bodies since. So this is new behaviour rather than a revert — worth a glance at those PRs if there was original intent I have missed.

🤖 Generated with Claude Code

[github-actions]

Preview deployments

• Host staging preview

• Host production preview

Host Test Results

    1 files  ±0      1 suites  ±0   2h 12m 16s ⏱️ - 26m 10s
3 835 tests +8  3 821 ✅ + 9  14 💤 ±0  0 ❌ ±0 
3 854 runs  +8  3 840 ✅ +10  14 💤 ±0  0 ❌  - 1 

Results for commit 645d5cd. ± Comparison against earlier commit a5a4d31.

Realm Server Test Results

    1 files  ±0      1 suites  ±0   13m 45s ⏱️ -28s
2 064 tests ±0  2 064 ✅ ±0  0 💤 ±0  0 ❌ ±0 
2 143 runs  ±0  2 143 ✅ ±0  0 💤 ±0  0 ❌ ±0 

Results for commit 645d5cd. ± Comparison against earlier commit a5a4d31.