Shared-element view transitions (ref + @navigate.viewTransition)

[shanerbaner82]

Elements that morph between screens — the native analogue of the CSS View
Transitions API — on iOS and Android.

<column @navigate.viewTransition('/album/3')>
    <column ref="album-3" class="w-16 h-16 rounded-xl">…</column>
</column>

{{-- destination --}}
<column ref="album-3" class="w-full h-80">…</column>

<row @navigate.back.viewTransition>…</row>

Two elements sharing a ref across two screens morph between them. Motion is
shaped by three optional props: morph="frame|position|size|none",
morph-duration (ms) and morph-easing
(linear|ease-in|ease-out|ease-in-out|spring).

Why ref

ref already existed as a per-element name, used as a test-targeting handle.
Two screens naming an element the same thing is exactly what a shared element
is, so there is no second naming concept to learn. id was rejected because
it is already the node's numeric wire identity and what event dispatch routes
on; key was rejected because it is scoped to a parent key-path and the docs
encourage domain ids, so key="3" on unrelated things would pair constantly.

Consequence worth reviewing: a ref that exists only as a test handle and
repeats across two screens will now morph under a view_transition. The opt-out
is morph="none".

ref costs nothing extra on the wire — the node-level field is dropped by
npui_serialize_node, so only the generic prop is transmitted, and it replaced
transition_name.

How it works, per platform

Android — SharedTransitionLayout wraps the screen-swapping
AnimatedContent; Compose matches refs across panes and animates the bounds
itself. Scopes reach the recursive NodeView through composition locals.

iOS — SwiftUI has no equivalent. matchedGeometryEffect only slaves one
view's frame to another's, and both stay inside their own screen layer, so a
hero travelling while the screens cross-fade is progressively occluded ("moves
most of the way, then fades"). Instead a FLIP overlay renders a copy of each
travelling element above both screens: frames are reported continuously, the
swap snapshots them, and the copy animates between them while both real
elements stay hidden.

Known parity gap

morph="position" / "size" are exact on iOS (the rect is interpolated
directly) but fall back to a full-bounds morph on Android — Compose's
shared-element API always animates the full bounds and exposes no equivalent.
Documented in NodeHeroMorph.kt rather than approximated.

Also in here

• ref reaches UI drivers on both platforms: an accessibilityIdentifier on
  iOS (nothing read ref at all before) and testTagsAsResourceId on Android
  (a Compose test tag is otherwise invisible to UiAutomator). On iOS this needs
  .accessibilityElement(children: .contain), or naming a container collapses
  its descendants out of the tree — which hid content from screen readers too,
  not just tests.
• ref sets testTag only on Android, not contentDescription — writing an
  internal handle there made TalkBack announce "photo-1" in place of the
  element's real description.
• ref and the morph props now survive the streaming builtin path, which
  bypasses applyStyle/applyCallbacks and dropped them silently. Unit tests
  could not catch this; they use the Element path.

Testing

Pest 58 passed / 0 failed (3041 assertions), including a new
tests/Unit/Edge/ViewTransitionTest.php. Pint clean.

Verified frame-by-frame from screen recordings on an iPhone 14 simulator and a
Pixel 9 emulator across twelve demo screens, forward and back — automated flows
prove taps land and destinations render, never that a morph played.

Pre-existing CI note: PHPStan reports 17 errors in
src/Commands/Concerns/* (native:watch argument/option signatures). They
are untouched by this branch and present on main.

🤖 Generated with Claude Code