Continuous motion for operator-mode navigation

[christse]

Background and Goal

Operator mode changed scenes by swapping DOM: a card opened by appearing, a stack closed by vanishing, and the dashboard jumped to a workspace. This PR gives every one of those navigations continuous motion without scaling live text or making layout part of playback.

Two mechanisms split the work:

• Choreo (glimmer-motion, vendored) tweens live geometry within a scene: stack reflow, the header handoff to the top bar, and the search sheet.
• Bitmap crossings (view transitions) handle navigation between scenes:
  • a preview becomes a stack card and returns to its tile;
  • a card expands and restores;
  • a search result opens;
  • a dashboard tile becomes the realm background and back.

A single service, HostMotionService, decides what may move at any moment. Everything moves on one ease-out curve.

docs/host-motion.md is the architecture reference; this description summarizes it.

Where to start

1. services/host-motion.ts: the policy.
   • begin(scene) arms one Choreo scene at a time.
   • cross() is the only entry for a bitmap crossing. It gates on tests, reduced motion and drag, owns the bitmap budget and the test waiter, and waits for the update to render before the new capture.
   • canCross() exposes the gate for callers that have their own fallback.
2. lib/bitmap-crossing.ts: the mechanism, crossfadeCardBitmap(crossing). The fields of BitmapCrossing (from, to, update, handoff, parent, scenes, companions, chrome) describe every layer a crossing captures. Anything in the updated document is a lookup function, called after the update and given the landing face.
3. components/operator-mode/interact-submode.gts (viewCard, close): the main callers. Read them for opening over a parent, returning into a tile, opening into a new stack with reflowStacks, and settling a right-stack card back into its tile while the other stacks morph.
4. lib/card-open-origin.ts: which preview a crossing starts from and returns to, including a card shown twice and a click beside a tile.
5. lib/workspace-open-origin.ts (workspaceEntry, workspaceExit): the dashboard ↔ workspace crossing, defined once for both directions.
6. services/operator-mode-state-service.ts: where the Choreo stack scene is armed (open, close, stack removal), and crossToDashboard, the single gate for the dashboard button and for closing the last card.

The remaining files are supporting pieces:

• stack-motion.gts, search-sheet/motion.gts and workspace-scene.gts: the Choreo regions.
• bitmap-shadow.ts: shadow layers.
• prerendered-placeholder.ts: the stand-in body while a card flies.
• inspect-host-motion.ts: instrumentation.
• The two dependency patches.

Key decisions and non-obvious mechanics

• Bitmaps for boundaries, live geometry for reflow. Crossing a card between two layouts as live DOM would either stretch text or re-lay out the card on every frame. Instead the live DOM sits at its final layout while two cropped raster faces morph. Choreo never scales a card; the only surfaces it scales are empty ones (the search sheet's and a header's).
• Navigation never depends on motion. A crossing's update always runs its navigation, even when a newer crossing has taken over, and a motion failure after it is logged rather than thrown. One canCross() decides everything a crossing implies, including whether to defer the card body and fetch its placeholder.
• A crossing owns the scene. While a crossing plays, Choreo scenes are refused and the stack region is held instant. There are two exceptions:
  • A card flying into a new stack (reflowStacks) leaves the existing stacks live, and they reflow with Choreo beneath it.
  • When a right-stack card returns to its tile, the remaining stacks move as morph layers at their natural size, so a widening stack is revealed rather than scaled.
• Origins are explicit, and so are return addresses.
  • A crossing starts from the preview that holds the click. A click beside a tile resolves to the nearest preview; otherwise a unique visible preview is used.
  • The chosen preview is remembered per parent. A buried parent hides every preview, and a card rendered twice would be ambiguous on the way back.
  • A card opened into its own stack keeps StackItem.returnTo, in memory only.
  • If a close can't resolve a tile, it doesn't guess: the card just fades.
• Dashboard ↔ workspace.
  • The tile's realm icon flies on its own to the first card's header. Naming it keeps it out of the tile bitmap, which would otherwise blow it up across the background.
  • The platter of cards scales and fades up from about the icon's size, centred on the growing background.
  • The return needs only the realm whose background is showing, so it also works after a reload, from a pasted URL, or with several stacks open.
  • When the header has no icon yet (a cold realm) or at all (no icon URL), the icon lands on a stand-in.
  • The dashboard no longer scrolls on open, so it stays still under a landing crossing.
• One curve. Every geometric motion uses motionEase (cubic-bezier 0.2, 0.8, 0.2, 1): it leaves at once, since the click has already waited for capture, and lands without overshoot. Motions that play together share a duration.
• Performance rules the code follows (nothing checks them automatically):
  • View-transition CSS is installed once, because any stylesheet change during motion restyles the whole document.
  • Shadow layers live in one persistent host element.
  • Crossings read every participant's styles before writing any.
  • Idle Choreo regions skip measurement.
  • A leaving card releases focus before capture.
  • The deferred card body mounts one paint after landing, with the prerendered isolated HTML standing in (up to 100 KB).
• Browser view-transition animations are replaced, not retimed. Chrome sampled a retimed CSSAnimation inconsistently, so layers lurched between two easing curves. The motion-dom patch copies their keyframes into WAAPI animations instead.
• Dependencies. glimmer-motion has no npm release yet, so it is vendored as a tarball. It and motion-dom carry pnpm patches, listed in vendor/glimmer-motion.md; both should move upstream.
• Tests and measurement.
  • All motion takes no time in tests, and crossings and deferred bodies hold waiters.
  • ?motionSpeed, ?motionTrace and ?motionInspect are opt-in review tools. motionInspect records every frame of every view-transition layer and flags reversals, spikes and long frames.
  • The remaining cost is structural: motion starts 50–80 ms after a click (old capture, update render, new capture).

🤖 Generated with Claude Code

[github-actions]

Preview deployments

• Host staging preview

• Host production preview

Host Test Results

    1 files  ±0      1 suites  ±0   1h 27m 39s ⏱️ - 4m 3s
5 153 tests +7  5 139 ✅ +7  14 💤 ±0  0 ❌ ±0 
5 168 runs  +7  5 154 ✅ +7  14 💤 ±0  0 ❌ ±0 

Results for commit bab0af9. ± Comparison against earlier commit 21cae06.

Realm Server Test Results

    1 files  ±  0    281 suites  +8   2h 9m 1s ⏱️ + 12m 39s
4 458 tests +169  4 458 ✅ +169  0 💤 ±0  0 ❌ ±0 
4 510 runs  +169  4 510 ✅ +169  0 💤 ±0  0 ❌ ±0 

Results for commit bab0af9. ± Comparison against earlier commit 21cae06.

[burieberry]

Bugs

1. A close or open can be lost. The stack change runs inside the crossing's update, and update exits early when another open or close has started since (interact-submode.gts:464, 661). If you close a card and quickly open another, the closed card stays on the stack, and a card in edit mode never finishes. Two quick opens drop the first card the same way.
2. Motion can stay off after a workspace portal. Some paths cancel the portal without clearing workspaceActive: enterWorkspace(..., portal=false), for example the AI open-workspace tool mid-portal, and WorkspaceScene torn down when switching to code mode. Stack, header and sheet motion then stay off until a later crossing, drag or portal calls finish() (operator-mode-state-service.ts:1598).
3. Reopening the chooser leaves no tile focused. Now that the chooser stays mounted, focusWhenSelected doesn't run again on reopen. Arrow keys and Enter do nothing until the user tabs in, and the old selection ring comes back (workspace-chooser/focus-when-selected.ts:38).
4. A search pick with no crossing keeps its tile alive. In the dock fallback (reduced motion, unsupported browser, a drag, and every test run), the whole origin, including the search-result element, goes onto StackItem.openingOrigin and is never cleared (submode-layout.gts:409-413). The detached result stays in memory for the card's lifetime, and StackMotion.measuring stays true, so the stack region measures on every render (stack-motion.gts:63). The other paths strip source; this one should too, and clear the origin once the dock motion is done.

Architecture

• Navigation depends on the animation. The check that cancels a stale animation also cancels the navigation, which is bug 1. The stack change should always run, and only the visuals should be skipped.
• Motion state lives in scattered flags. HostMotionService has seven flags set and cleared in different places, with no clear owner for resetting each one. Bug 2 comes from this, and an explicit state (idle / scene / crossing / portal / dragging) would prevent the whole class.
• Two gates disagree. viewCard decides to defer the body and fetch the placeholder before cross() decides whether a crossing can play. crossfadeCardBitmap also refuses when a modal is open, and canCross() doesn't know that. When they disagree, the user waits for a crossing that never plays. deferContent should come from the same canCross() call, and canCross() should include the modal check.
• Motion logic in the state service. Screen changes such as openWorkspace now go through motion-aware code and global DOM queries.
• Class-name lookups. Crossings find their layers through other components' classes (.chat-btn, .submode-layout-top-bar, …), so a rename silently drops a layer and no test would notice. workspaceHeaderIcon, headerIconStandIn and interact-submode.gts:574 take the first .stacks .operator-mode-stack … in the document, which is stack 0 when two are open. Keyed data-* hooks like [data-bitmap-entry] or component refs would fix both.
• CardHeader overrides. app.css:216-243 forces CardHeader's background, shadow and outline off with !important and repaints editing via its internal .is-editing class. That belongs in CardHeader's CSS variables.
• Durations are handled inconsistently. Crossings use their own isTesting() ? 0 : x instead of MotionTiming.duration().
• Errors after navigation reject the caller. Once update has run, a later motion error is rethrown, so viewCard, close and openWorkspace reject even though the navigation succeeded. Log it and swallow it instead.

Dependencies

• The vendored tarball can't be rebuilt. vendor/glimmer-motion.md says it was packed with uncommitted working changes, so it doesn't match any commit.
• Motion's copyright notice is missing. The tarball's VENDORED.md says gestures, reorder and features were copied word for word from Motion (MIT), but its LICENSE has only the Cardstack notice. MIT requires Motion's notice in the copy.
• Unused code in the host bundle. glimmer-motion has no sideEffects field, and its index imports film/* purely for side effects. The host likely ships film plus the gesture and reorder code it doesn't use: about 110 KB+ gzip before minification, not measured in a real build. Adding "sideEffects": false and giving film its own entry point would fix it.
• motion-dom patch:
  • It copies each view-transition animation's keyframes once. If Chrome returns the group's end state as a fixed value, the copy stops following the landing element, and the card jumps at the end whenever the landing moves mid-flight (placeholder fill-in, reflowStacks). I haven't confirmed this in a browser, but it matches a jump I saw near the end at slow speed. Dropping the offset-1 keyframe would let the end come from the live style.
  • The replacement animations use fill: "both", and the patch never cancels them. Only one host finally does (releaseFinishedViewAnimations).
  • It's declared as ^13.3.0 while the patch targets exactly 13.3.0. Pin it, via catalog: like the host's other dependencies.
  • supportsBitmapCrossing() should also check CSS.supports('view-transition-class', 'a'). Without it, Chrome 111–124 and Safari 18.0–18.1 crop incorrectly.

Tests

• Crossings are only tested in isolation. Fixtures call crossfadeCardBitmap directly, and canCross() is false under isTesting(), so viewCard/close, the placeholder fetch and workspaceActive never run with a crossing playing. None of bugs 1–3 can show up in CI. Routing crossing durations through MotionTiming would let a test set a non-zero duration and cover them.
• Hang risks. The bitmap tests await bitmapReady with no supportsBitmapCrossing() guard or deadline, and five while (!isMotionIdle()) loops have no deadline. A skipped transition or a regression hangs the shard instead of failing.
• Selectors and mocks. 39 test queries use classes or non-test data-* attributes, and four browser globals are monkey-patched.

Performance (questions)

• The deferred body. A heavy card is usable about 0.35s later than on main, because its body waits for the crossing to land. I understand why, but it's paid on the most frequent action. Is that settled, or worth weighing against a shorter open duration?
• The placeholder request. There's an extra _federated-search on every animated open from a preview (interact-submode.gts:437). It isn't aborted on landing, it's still sent when the crossing is skipped after the fact (see "Two gates disagree"), and it downloads the full response before checking the 100 KB cap. It also skips assertOwnRealmServer, which the other federated calls use.
• The hidden chooser. It stays mounted with only visibility: hidden, so every full-page style recalc includes the dashboard. content-visibility: hidden would keep its state and skip that work.

Accessibility

• Closing a card sends focus to <body>. The PR already records the element that opened the card, so focus can go back there.
• Tiles outside the render window can't be reached by screen readers or find-in-page (tile-window.gts:44).
• Minor: leaving cards can be reached with Tab while they animate out, and the buried card header only works with a mouse.

UI

• The search sheet's corners and shadow stretch as it opens, because width and height scale separately. A clip-path tween, like workspace-scene.gts uses, would avoid it.
• Opening the chooser no longer scrolls the selected tile into view, even with reduced motion or no view transitions, where nothing lands on it.
• Minor: there are two shadow systems on one screen, some baked shadow layers are too faint to see, and there's a deprecated -xxl radius token.
• For slow-motion review, use ?motionSpeed. The DevTools playback rate doesn't slow playbackSettled's wall-clock deadline, so a crossing snaps to its end at about 75–85% of the way through.

Description and doc

• "Choreo animates only positions, never scale" isn't the case: the sheet and header surfaces use scaleX/scaleY (lib/motion-transform.ts:40-57).
• "Performance rules are enforced in code": the code follows them, but nothing checks them.
• The rule that blocks scenes during a workspace portal isn't in the doc's policy list.
• The cross() example leaves out 'replace', and one close duration is wrong.

Reduced-motion support, the opt-in diagnostics and the single cross() entry point all look solid. The vendored tarball is otherwise clean: no install scripts, no network or eval calls, and its integrity matches the lockfile.

🤖 Drafted by Claude

[ef4]

1. We should use this branch as a high-fidelity spec for how the UX should look and feel.

2. We should not use this branch for illustrating how animation composition is defined and how the state is managed. Animation concerns are leaking all over the place, in a way that's not tenable for a system with end-user authored components.

   An example of this is all the places where existing components had to adapt their behavior by becoming aware of the motion service or (even worse) directly inspecting the DOM to see if animations are happening.

3. The bugs mentioned in @burieberry's review are real and significant. I think a major reason agents are struggling to write correct code in this area is that our stack state management has grown extremely messy. A starting point for "what to refactor" is "everything that touches a StackItem". This will pay dividends by making it much easier to land this kind of feature going forward.

4. The integration here doesn't follow the architecture we've been discussing. By the game engine analogy, we want objects in the world to go through their own state changes without interleaving animation logic. The animation engine is supposed to be a completely separate layer that reacts to state changes, and in particular never blocks them or break them if something goes wrong with animation.

   A concrete example of what's wrong is having imperative methods like hostMotion.cross(). We want to build cards that feel like physical objects and that retain that feeling in new environments. They need to carry their physicality with them at a much lower level (down in the components that implement card-api-level boundaries and also probably in some semantically-relevant UI toolkit components).

   Another concrete example (and source of correctness bugs) is a field like newItem.deferContent. The application logic shouldn't be sitting around waiting for animations to do anything.

5. There are some good ideas in the branch that could be extracted and landed on their own. For example, something like the TileWindow component (which provides lazy rendering based on an IntersectionObserver) would make sense as a primitive in the UI toolkit.

6. The inspection system with its ability to slow down animations is a tell that we're not consistently using the browser animation APIs. If we were, we wouldn't need our own inspection system. Chrome devtools can already slow and inspect browser animation APIs.

My recommended next actions are:

• have somebody work on cleaning up the stack state management
• pick a particular existing animation and do a one-to-one replacement with choreo, just in that one spot. This will create real design pressure on choreo so that we can make it work well within host, while keeping the scope reasonable for a first integration.
• the key piece of work that we've always wanted to do in boxel motion is simply not done yet and choreo doesn't move it forward: an animation engine that is purely reactive to UI changes, where low-level UI components have declarative semantics about how they could move, and screen-level UI components have declarative semantics for how possible changes should move, and behind it all the reactive animation engine manages all imperative control (deferring as much of that as possible to the browser's native animation loops).