Resolve selector/Element targets in animateView()

[mattgperry]

What

animateView() (the View Transitions integration in motion-dom) only ever animated the root layer and pre-named string layers. Targets other than "root" were never resolved to elements or assigned a view-transition-name, so selector/Element targets silently did nothing — the implementation carried three TODOs describing exactly this gap, with no E2E coverage.

This finishes non-root target resolution, adds the automatic view-transition-name management the docs already promise, and makes cross-aspect-ratio morphs look right out of the box.

API

• .add(selector | Element) — resolves matching elements and assigns each a unique, script-visible view-transition-name, in two passes (before the update → old snapshot; after → new snapshot) via a per-transition Map<Element, string>, so a persistent element keeps its name and morphs as a single group. Author-defined names are respected; auto/match-element are overridden because their generated name isn't exposed to script (so it can't be targeted for WAAPI animations). A bare .add() auto-enables the layout/morph — no explicit .layout() needed.
• .addName(name) — targets a pre-named layer (the former bare-string behaviour). Splitting this out from .add() removes the selector-vs-name ambiguity.
• .crop() — on by default: clips the morph (overflow: clip) + object-fit: cover so cross-aspect-ratio morphs don't distort or overflow (the UA default does), and animates per-corner border-radius from the old element's measured radii to the new element's. .crop(false) opts a subject out.
• Per-element stagger — a delay function resolves per resolved element across a selector.
• Inferred enter/exit from-values — .exit({ opacity: 0 }) animates from an inferred 1 rather than applying instantly (falsy targets like 0 are no longer skipped).
• Removed .get()/.new()/.old() — not part of the documented surface.

Generated names are removed in transition.finished.finally. The three TODOs in start.ts are gone.

Why not just rely on the platform?

Audited CSS View Transitions L1 and L2: neither offers a JS path for this, and view-transition-name: auto/match-element deliberately hides the generated name from script — which is exactly the handle our WAAPI engine needs to attach per-layer animations and read them back. So Motion must assign names it controls.

Testing

• Unit (assign-names.test.ts): unique-name generation, same-element reuse, author-name skip, auto/match-element override, cleanup, and the no-startViewTransition fallback with an Element target. Full motion-dom suite green (479 passed).
• E2E (tests/view/view-targets.spec.ts, Chromium + WebKit): Element target animates its new layer; a selector matching 3 elements → 3 distinct named layers; a pre-named .addName layer still works and is not auto-renamed (negative control); a bare .add() auto-enables a group morph; per-element stagger delays; default crop (clip + object-fit + animated radius); individual corner radii; .crop(false) opt-out; and .exit({ opacity: 0 }) animating from an inferred 1.
• Visual demos in dev/html/public/examples/ (Netflix card→modal, circular clip-path enter/leave, crop cover-vs-overflow explainer, stagger + auto-layout) for manual exploration.

Notes / follow-ups

• Element-scoped capture (animateView(element) + element.startViewTransition) is deferred to a follow-up. It's spec-aligned (Chrome/Edge 147+), but Playwright's pinned Chromium predates 147, so the subtree-scoped path can't be E2E-verified in CI and had accrued scoped-only morph/teardown bugs that need a real Chrome 147 dev loop. This PR is the fully-verified document-level surface.
• Positional sugar (.add(sel, keyframes, opts)) intentionally not added — keyframes are bucket-specific, so the explicit .enter()/.exit()/.layout() chaining is the surface for now.
• dev/html/src/imports/view.js is a small motion-dom-only fixture shim (the shared inc.js also imports framer-motion, which isn't needed here).

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

This PR completes the long-standing animateView() non-root target resolution: selector and Element targets are now resolved to DOM elements, each automatically assigned a unique script-visible view-transition-name across two passes (before and after the DOM update), and a new element.startViewTransition() overload scopes the transition to a subtree. The three original TODOs in start.ts are gone, backed by unit tests and Playwright E2E tests for all three target modes.

• assign-names.ts (new): resolves ElementOrSelector to elements, reuses the same generated name for persistent elements via a per-transition Map, respects author-defined names, overrides auto, and cleans up in transition.finished.finally.
• index.ts: adds add() / addName() API, a scope field for element-scoped transitions, and an overloaded animateView(element, update, options?) signature.
• start.ts: wires resolveLayers (called twice — before and after update()) into the transition lifecycle and routes layerTargets to the WAAPI animation loop.

Confidence Score: 3/5

The core two-pass name resolution logic is solid, but one edge case in the new assign-names.ts utility produces wrong behavior rather than a graceful fallback.

The match-element CSS keyword (View Transitions L2) is not excluded in the author-name guard alongside auto. An element carrying that keyword is returned as the literal string match-element, which then gets used as a pseudo-element selector so the WAAPI animation silently targets a nonexistent layer. The PR description explicitly calls out that auto and match-element both hide their generated names from script and must be overridden; the test suite covers auto but not match-element. The rest of the two-pass resolution, name registry, cleanup, and new API surface are well-structured.

packages/motion-dom/src/view/utils/assign-names.ts — the match-element gap; packages/motion-dom/src/view/start.ts — worth confirming the fallback path wires through to notifyReady.

Important Files Changed

Filename	Overview
packages/motion-dom/src/view/utils/assign-names.ts	New utility; contains the match-element keyword omission bug and a module-level counter that grows unboundedly.
packages/motion-dom/src/view/start.ts	Integration of name resolution into the view transition lifecycle looks correct; the no-startViewTransition fallback path warrants a check that notifyReady is reached.
packages/motion-dom/src/view/index.ts	Adds add(), addName(), scope, and resolveDefs; overloaded animateView() signature is clean and backwards-compatible.
packages/motion-dom/src/view/tests/assign-names.test.ts	Good coverage for unique names, reuse, author-name skip, and auto override; match-element override case is missing a test.
tests/view/view-targets.spec.ts	Playwright E2E specs cover Element, selector, and pre-named target paths with appropriate test.skip guards for unsupported browsers.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Caller
    participant ViewTransitionBuilder
    participant startViewAnimation
    participant assignViewTransitionNames
    participant browser as Browser / ViewTransition

    Caller->>ViewTransitionBuilder: animateView(update).add(el).enter(kf)
    ViewTransitionBuilder->>startViewAnimation: startViewAnimation(builder)
    startViewAnimation->>assignViewTransitionNames: resolveLayers() before update
    assignViewTransitionNames-->>startViewAnimation: layerTargets Map (name to target)
    Note over browser: old snapshot captured
    startViewAnimation->>browser: document.startViewTransition(callback)
    browser->>startViewAnimation: callback()
    startViewAnimation->>Caller: await update()
    startViewAnimation->>assignViewTransitionNames: resolveLayers() after update (reuse names)
    Note over browser: new snapshot captured
    browser-->>startViewAnimation: transition.ready
    startViewAnimation->>browser: NativeAnimation per layerTarget
    browser-->>startViewAnimation: transition.finished
    startViewAnimation->>assignViewTransitionNames: releaseViewTransitionNames(assigned)
    startViewAnimation-->>Caller: GroupAnimation resolved

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Caller
    participant ViewTransitionBuilder
    participant startViewAnimation
    participant assignViewTransitionNames
    participant browser as Browser / ViewTransition

    Caller->>ViewTransitionBuilder: animateView(update).add(el).enter(kf)
    ViewTransitionBuilder->>startViewAnimation: startViewAnimation(builder)
    startViewAnimation->>assignViewTransitionNames: resolveLayers() before update
    assignViewTransitionNames-->>startViewAnimation: layerTargets Map (name to target)
    Note over browser: old snapshot captured
    startViewAnimation->>browser: document.startViewTransition(callback)
    browser->>startViewAnimation: callback()
    startViewAnimation->>Caller: await update()
    startViewAnimation->>assignViewTransitionNames: resolveLayers() after update (reuse names)
    Note over browser: new snapshot captured
    browser-->>startViewAnimation: transition.ready
    startViewAnimation->>browser: NativeAnimation per layerTarget
    browser-->>startViewAnimation: transition.finished
    startViewAnimation->>assignViewTransitionNames: releaseViewTransitionNames(assigned)
    startViewAnimation-->>Caller: GroupAnimation resolved

Loading

_{Reviews (1): Last reviewed commit: "Resolve selector/Element targets in anim..." | Re-trigger Greptile}

[greptile-apps]

match-element keyword not excluded from author-name detection

The condition skips "none" and "auto" but not "match-element" (CSS View Transitions L2). An element whose view-transition-name is match-element falls into the name = current branch and returns the literal string "match-element". That string then becomes the pseudo-element selector ::view-transition-new(match-element), which targets the CSS keyword rather than any real layer — no WAAPI animation attaches and the element silently goes unanimated. The PR description explicitly calls out auto/match-element as cases that must be overridden.

Suggested change

	if (current && current !== "none" && current !== "auto") {
	/**
	* The author already named this layer - target it as-is and leave
	* it to them to clean up.
	*/
	name = current
	} else {
	if (
	current &&
	current !== "none" &&
	current !== "auto" &&
	current !== "match-element"
	) {

[greptile-apps]

Fallback path and notifyReady wiring

When document.startViewTransition is absent the function returns early before nameRegistry, assigned, and layerTargets are set up. The unit test confirms the update runs, but no assertion verifies that the builder then() settlement is reached via notifyReady. If addToQueue in queue.ts does not route the resolved GroupAnimation back to builder.notifyReady, callers using .add(el).enter(…).then(callback) would have their then callback silently stall in the fallback path. Does the queue mechanism in queue.ts pipe the Promise returned by startViewAnimation back to builder.notifyReady? If not, .then() on the builder silently stalls in the no-startViewTransition fallback.

[greptile-apps]

Module-level nameCount never resets across page lifetime

nameCount is a module singleton that increments for every generated name and is never reset. In a long-running SPA the counter grows indefinitely, and in tests order-dependence of numeric IDs can make snapshot values non-deterministic across test files. A per-transition counter or resetting after releaseViewTransitionNames would make this self-contained.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[mattgperry]

Thanks for the review — addressed in a3ce27a and e5e31104:

P1 — match-element not excluded (real bug, fixed). Correct catch — view-transition-name: match-element generates a name the browser keeps internal, exactly like auto, so treating it as an author name produced a dead ::view-transition-new(match-element) selector. Added it to the override condition and parametrized the unit test to cover both auto and match-element.

P2 — fallback / notifyReady wiring (verified, no change needed). Yes, the queue pipes it back: queue.ts start() does startViewAnimation(builder).then((animation) => builder.notifyReady(animation)), and the fallback resolves a GroupAnimation([]) through that same path. The fallback test awaits the builder — which can only resolve if notifyReady fires — and now also asserts the resolved value is defined, so a silent stall would fail the test.

P2 — module-level nameCount (keeping, by design). The global monotonic counter is intentional: names must be unique across concurrent transitions (the queue and element-scoped startViewTransition can overlap), and a per-transition counter reset to 0 would collide between two simultaneous transitions. It's a single integer (no memory growth), and the tests assert the motion-view-<n> shape + uniqueness via a Set rather than exact numbers, so there's no determinism issue.

Separately, this branch also migrates turbo.json from the pre-2.0 pipeline key to tasks — the repo pins turbo 2.9.14, so turbo run (and thus yarn build in the CircleCI setup job) was erroring on the old schema.