[shanerbaner82]

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

<column @navigate.morph('/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.morph>…</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 morph navigation, and only
then. 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

After merging main (see the update below): Pest 2123 passed, 0 failed, 5 skipped,
4 risky. The tests for this feature are in tests/Unit/Edge/MorphTransitionTest.php.
Pint and PHPStan are 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. That was before
the merge and the rename, which haven't been run on a device yet.

Update: merged with main and renamed

Simon merged main into this branch and renamed the modifier. Two commits:

040d662, the merge. Conflicts in NativeElementCollector (main's border and
variant prop builders sit next to buildHeroProps) and SwiftUINodeRenderer.
Main's #576 now skips modifiers a node doesn't use, so the hero and identity
modifiers are wired in through a new .ref decoration. Nodes without a ref no
longer each observe HeroFlightStore.

Main's #580 (a11y labels on containers) changed things under this branch
without a conflict, and two fixes were needed:

• iOS: NodeIdentityModifier now sits outside NodeAccessibilityModifier and
  only sets the identifier when that modifier has already made the node one
  element. Before, a labelled pressable with a ref lost one or the other.
• Android: the ref test tag moved outside nodeAccessibility. Its
  clearAndSetSemantics dropped the tag whenever the node had an a11y-label.

9969bdb, the rename. @navigate.viewTransition is now @navigate.morph,
Transition::ViewTransition is Transition::Morph, and the wire value is
morph. Nothing shipped with the old name, so there's no alias.

The same commit stops Android morphing under other transitions. Its
SharedTransitionLayout wrapped every screen swap, so matching refs morphed
during plain slides too, while iOS only flies elements for this transition. The
shared transition scope is now only handed down when the pending transition is
morph.

Worth knowing: a push between two screens that both have native chrome of the
same kind (stack to stack, or tab to tab) doesn't morph on either platform. The
NavigationStack / native stack renderer animates those itself and the router
swap never runs. Tabs to stack and screens without chrome do morph. This is
documented rather than fixed.

Docs: NativePHP/nativephp.com#569.

🤖 Generated with Claude Code