@superwall/cli 1.7.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (165) hide show
  1. package/README.md +192 -52
  2. package/dist/{setup-Bxj22rYi.js → apple-CkKlHBZ9.js} +82 -76
  3. package/dist/auth.d.ts +4 -19
  4. package/dist/auth.js +4 -2
  5. package/dist/{actions-B7ym3oVS.js → billing-XCZU_T46.js} +98 -28
  6. package/dist/{bind-YrJvuRF9.js → bind-drne__Ys.js} +38 -33
  7. package/dist/{build-DLoCW5Ri.js → build-Gpdq5QXP.js} +20 -26
  8. package/dist/{asc-Bf7zBbyS.js → client-BZ1UbpXz.js} +16 -15
  9. package/dist/client-DP6Rc0t_.js +176 -0
  10. package/dist/config-BO1Y87kV.js +105 -0
  11. package/dist/{notification-url-DuKF2659.js → create-BBrtgUgS.js} +235 -539
  12. package/dist/{create-pkANt1Gs.js → create-Cwc3SRWJ.js} +194 -168
  13. package/dist/create-Yvf2gStM.js +19 -0
  14. package/dist/doctor-C9ldpPFC.js +83 -0
  15. package/dist/{drivers-Qx9LxmRN.js → drivers-DNrx4LWA.js} +185 -172
  16. package/dist/entry.d.ts +0 -5
  17. package/dist/entry.js +28073 -1134
  18. package/dist/environment-DF1qKlny.js +58 -0
  19. package/dist/{existing-AVEfZu2A.js → existing-78LWSsqS.js} +12 -6
  20. package/dist/held-Cy8Wl4D1.js +1112 -0
  21. package/dist/held-Ddw1XSsr.js +16 -0
  22. package/dist/input-vi0bou04.js +42 -0
  23. package/dist/{integrate-brmhPG-S.js → integrate-DcJhpXy8.js} +277 -254
  24. package/dist/kinds-GFXB3sYu.js +11 -0
  25. package/dist/log-NVhVe_oe.js +62 -0
  26. package/dist/login-B2TsCE2H.js +53 -0
  27. package/dist/login-BoBe8Psl.js +16 -0
  28. package/dist/{login-Do4wFuLv.js → login-D0lh3_JI.js} +118 -55
  29. package/dist/lookup-D-nmmAbw.js +71 -0
  30. package/dist/migrate-Cfec564E.js +274 -0
  31. package/dist/notification-url-YDbq6FMA.js +100 -0
  32. package/dist/{open-studio-DOw-6ydc.js → open-Ba2vBl1_.js} +34 -43
  33. package/dist/org-D0g_q3mv.js +35 -0
  34. package/dist/output-Ggzq5_-t.js +122 -0
  35. package/dist/paths-DxSLdpOI.js +29 -0
  36. package/dist/playbook-DIeb7hne.js +53 -0
  37. package/dist/{asc-products-9JXtDxI4.js → products-DH_fK9tY.js} +6 -6
  38. package/dist/promote-COD4fYdz.js +91 -0
  39. package/dist/push-CncywhkQ.js +482 -0
  40. package/dist/push-CtD4FZQV.js +22 -0
  41. package/dist/registry-DSrosOYs.js +10228 -0
  42. package/dist/{reports-CfJqoava.js → reports-DdPq4blM.js} +7 -6
  43. package/dist/{resources-Bf9O1JNM.js → resources-Dqr01Dep.js} +150 -55
  44. package/dist/{run-DsVZ5snL.js → run-C9qg_QlC.js} +16 -22
  45. package/dist/scan-Cv5uOwVY.js +4 -0
  46. package/dist/{scan-zKsddO72.js → scan-DLrsrFS9.js} +48 -37
  47. package/dist/scope-V336uz8j.js +198 -0
  48. package/dist/screenshot-file-0UETadF8.js +16 -0
  49. package/dist/{selection-CxZoX4NT.js → selection-Rdw-ZUoG.js} +94 -51
  50. package/dist/send-BxD9yf6F.js +150 -0
  51. package/dist/{dev-DmB3XqaJ.js → server-D0tGG8C4.js} +82 -92
  52. package/dist/server-z1LH94R_.js +22 -0
  53. package/dist/session-1AV_Bs_d.js +6 -0
  54. package/dist/session-CFAmMhem.js +40 -0
  55. package/dist/session-D_nEWKXT.js +768 -0
  56. package/dist/skills/animate-onboarding/SKILL.md +467 -0
  57. package/dist/skills/animate-onboarding/references/engine.md +494 -0
  58. package/dist/skills/animate-onboarding/references/framework/Question.tsx +71 -0
  59. package/dist/skills/animate-onboarding/references/framework/README.md +40 -0
  60. package/dist/skills/animate-onboarding/references/framework/answers.ts +19 -0
  61. package/dist/skills/animate-onboarding/references/framework/flow.ts +80 -0
  62. package/dist/skills/animate-onboarding/references/framework/handoffs.ts +869 -0
  63. package/dist/skills/animate-onboarding/references/framework/layout.tsx +113 -0
  64. package/dist/skills/animate-onboarding/references/framework/motion.css +559 -0
  65. package/dist/skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
  66. package/dist/skills/animate-onboarding/references/handoffs.md +375 -0
  67. package/dist/skills/animate-onboarding/references/imageReady.ts +92 -0
  68. package/dist/skills/animate-onboarding/references/morphFrame.ts +356 -0
  69. package/dist/skills/animate-onboarding/references/performance.md +41 -0
  70. package/dist/skills/animate-onboarding/references/web-runtime/README.md +17 -0
  71. package/dist/skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
  72. package/dist/skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
  73. package/dist/skills/index.json +37 -0
  74. package/dist/skills/mobile-design/SKILL.md +447 -0
  75. package/dist/skills/mobile-design/references/responsive.md +162 -0
  76. package/dist/skills/onboarding-questions/SKILL.md +231 -0
  77. package/dist/skills/onboarding-questions/references/arpu-questions.md +139 -0
  78. package/dist/skills/onboarding-questions/references/craft.md +142 -0
  79. package/dist/skills/onboarding-questions/references/example-reflective.md +117 -0
  80. package/dist/skills/superwall/SKILL.md +82 -9
  81. package/dist/skills/superwall/references/api.md +153 -37
  82. package/dist/skills/superwall/references/apple-setup.md +316 -0
  83. package/dist/skills/superwall/references/asc.md +74 -38
  84. package/dist/skills/superwall/references/data-analytics.md +55 -21
  85. package/dist/skills/superwall/workflows/dashboard/playbook.md +3 -3
  86. package/dist/skills/superwall/workflows/dashboard/setup.md +8 -8
  87. package/dist/skills/superwall/workflows/migrate/adapty.md +6 -6
  88. package/dist/skills/superwall/workflows/migrate/playbook.md +4 -4
  89. package/dist/skills/superwall/workflows/migrate/qonversion.md +5 -5
  90. package/dist/skills/superwall/workflows/migrate/revenuecat.md +6 -6
  91. package/dist/skills/superwall/workflows/placements/android.md +2 -2
  92. package/dist/skills/superwall/workflows/placements/expo.md +2 -2
  93. package/dist/skills/superwall/workflows/placements/flutter.md +2 -2
  94. package/dist/skills/superwall/workflows/placements/ios.md +2 -2
  95. package/dist/skills/superwall/workflows/placements/playbook.md +2 -2
  96. package/dist/skills/superwall/workflows/placements/react-native.md +2 -2
  97. package/dist/skills/superwall/workflows/placements/strategy.md +2 -2
  98. package/dist/skills/superwall/workflows/review/playbook.md +1 -1
  99. package/dist/skills/superwall-editor/SKILL.md +61 -0
  100. package/dist/skills/superwall-editor/references/cli.md +135 -0
  101. package/dist/skills/superwall-editor/references/design.md +51 -0
  102. package/dist/skills/superwall-editor/references/native-elements.md +171 -0
  103. package/dist/skills/superwall-editor/references/workflow.md +65 -0
  104. package/dist/skills/superwall-editor/scripts/sw-editor.sh +662 -0
  105. package/dist/skills/superwall-framework/SKILL.md +78 -28
  106. package/dist/skills/superwall-framework/references/cli.md +58 -28
  107. package/dist/skills/superwall-framework/references/examples.md +4 -3
  108. package/dist/skills/superwall-framework/references/layout.md +30 -8
  109. package/dist/skills/superwall-framework/references/migrate-from-editor.md +1 -1
  110. package/dist/skills/superwall-framework/references/onboarding-state.md +245 -0
  111. package/dist/skills/wwdc/SKILL.md +22 -0
  112. package/dist/skills/wwdc/references/docs.md +52 -0
  113. package/dist/skills/wwdc/scripts/wwdc.sh +266 -0
  114. package/dist/{skills-DPzlnfCK.js → skills-BvFOa4y6.js} +99 -122
  115. package/dist/skills-DMG4bpKk.js +14 -0
  116. package/dist/{spawn-DSoTXy_j.js → spawn-DmmmHIP-.js} +14 -12
  117. package/dist/spinner-CneRK5rk.js +294 -0
  118. package/dist/storage-DYvmIOHa.d.ts +16 -0
  119. package/dist/storage-s2Dnz-yl.js +31 -0
  120. package/dist/storekit-DafAnGkM.js +16 -0
  121. package/dist/storekit-yY_kS2iR.js +47 -0
  122. package/dist/telemetry-DtG92m5O.js +56 -0
  123. package/dist/theme-DUsCh-Vd.js +25 -0
  124. package/dist/timing-BVxPrYq3.js +5 -0
  125. package/dist/{token-C0it-Xh7.js → token-DzRh7dI1.js} +6 -38
  126. package/dist/tools.d.ts +96 -0
  127. package/dist/tools.js +11178 -0
  128. package/dist/ui-D_qf3Gvw.js +53 -0
  129. package/dist/upgrade-Bt4Ouw1y.js +117 -0
  130. package/dist/upgrade-Cqy5orjb.js +7 -0
  131. package/package.json +10 -5
  132. package/dist/api-CZzirVMj.js +0 -151
  133. package/dist/api-output-aJNw7Syy.js +0 -20
  134. package/dist/app-DH6U8yuI.js +0 -190
  135. package/dist/asa-C-sQzPPn.js +0 -1194
  136. package/dist/asc-1ZBJ6DwS.js +0 -778
  137. package/dist/auth-YRhlV3DE.js +0 -140
  138. package/dist/billing-CCYHdApx.js +0 -80
  139. package/dist/bundle-id-CKxl_026.js +0 -121
  140. package/dist/command-CMIz81Da.js +0 -301
  141. package/dist/dev-DZy6pOnB.js +0 -22
  142. package/dist/doctor-H-hf-Yww.js +0 -88
  143. package/dist/feedback-CKf-rpBW.js +0 -152
  144. package/dist/hosted-CXe9TrWx.js +0 -32
  145. package/dist/migrate-C9ERDR6y.js +0 -284
  146. package/dist/org-sj7uyvp-.js +0 -40
  147. package/dist/output-C4o2gJ1K.js +0 -146
  148. package/dist/params-l3CrvRtR.js +0 -51
  149. package/dist/pipeline-BqzqZhX1.js +0 -977
  150. package/dist/print-skill-ZojRSybs.js +0 -74
  151. package/dist/promote-BG8X4Nv_.js +0 -88
  152. package/dist/publish-sxLh-G4G.js +0 -35
  153. package/dist/push-bQ6Vxtg8.js +0 -35
  154. package/dist/query-_FbybaH-.js +0 -53
  155. package/dist/resource-CGIwSd29.js +0 -323
  156. package/dist/revenue-provider-ebsRINY8.js +0 -100
  157. package/dist/scope-BvzD-kO4.js +0 -223
  158. package/dist/skills-D_R-lEsK.js +0 -64
  159. package/dist/spinner-TWa0hia6.js +0 -18
  160. package/dist/storekit-Cj9Cpjcz.js +0 -29
  161. package/dist/telemetry-DeA1mvnT.js +0 -169
  162. package/dist/ui-Dy0b-9L8.js +0 -27738
  163. package/dist/update-B2fWIc4q.js +0 -59
  164. package/dist/upgrade-BmzkTKrh.js +0 -72
  165. /package/dist/{devtools-8EgLo86w.js → devtools-ByZ6XYnn.js} +0 -0
@@ -0,0 +1,467 @@
1
+ ---
2
+ name: animate-onboarding
3
+ description: Animate a tap-through onboarding or web funnel (quiz, survey, web2app flow) so the motion tells the flow's story — each page-to-page hand-off gets its own choreography tied to what the two pages say, the chosen answer physically becomes the progress it earns or the next page's hero, and everything stays fluid, physical and smooth on real phones. Built for flows shipped as Superwall surfaces (the superwall framework: pages, router transitions, layout chrome), with the engine mapped onto the router; the same direction applies to any tap-through web flow. Motion only; no new screens. Use when the user asks to "animate the onboarding", "make the funnel feel premium", "add transitions between onboarding pages", or when a flow's page transitions feel flat, generic, choppy, or cheap.
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Animate Onboarding
8
+
9
+ Make an onboarding flow move like it means something. The pages, answer
10
+ capsules, progress bar and buttons already exist; this skill changes only how
11
+ they move — so the reader feels the story the questions tell, and the tap on an
12
+ answer is visibly what moves them forward.
13
+
14
+ ## Where the flow lives: a Superwall surface
15
+
16
+ An onboarding is a screen the team will want to change after shipping —
17
+ reorder a question, cut a step, try a new statement — without an app release.
18
+ That is what the **superwall framework** is for: the flow is one surface in
19
+ `superwall/` (`config.ts` plus one page per screen in `app/`, shared chrome in
20
+ `layout.tsx`), previewed on every device in `superwall dev`, pushed as an
21
+ immutable version and switched live from the dashboard. Everything in this
22
+ skill assumes that shape, and the engine below is mapped onto its router:
23
+
24
+ - **A page is a route and the router owns every page change**
25
+ (`router.push`, `router.back`, `useRouter()` from `superwall/navigation`).
26
+ Never build a page swapper, a custom router or a cloned outgoing page:
27
+ the leaving page stays mounted while it animates away, so there is
28
+ nothing to clone. The only script in a hand-off is the shared-element
29
+ flight that rides on top of the router's transition (a thin wrapper
30
+ around `useRouter`, `references/framework/useStoryRouter.ts`, that
31
+ measures, calls `router.push`, and measures again).
32
+ - **A hand-off is a custom transition name** on the page being entered
33
+ (`export const transition = "story-picture"`), styled through the router's
34
+ four phases (`enter`, `recede`, `leave`, `return`) on `[data-sw-route]`.
35
+ - **The progress bar, back button and primary button live in `layout.tsx`**,
36
+ so the chosen answer has something persistent to fly into.
37
+ - **The first page's entrance gates on presentation** (`useSuperwallSnapshot
38
+ ().paywall !== undefined`), never mount: the SDK preloads surfaces hidden.
39
+
40
+ Read the `superwall-framework` skill before touching the flow (install it if
41
+ it isn't there: `npx skills add https://github.com/superwall/skills/tree/next
42
+ --skill superwall-framework --global --yes --agent claude-code universal
43
+ --full-depth`); its `references/mobile-design.md` carries the touch, motion
44
+ and type rules this skill builds on. A flow that is not a surface yet (a
45
+ native onboarding, a hand-rolled web funnel) is worth proposing as one first
46
+ (`superwall create`, or `superwall migrate --screen <path>` for a native
47
+ screen); the user decides. Only if they keep their own web runtime does
48
+ `references/web-runtime/` apply, and never on a surface.
49
+
50
+ The direction comes from Emil Kowalski's design engineering and Apple's
51
+ fluid interfaces (both folded into `mobile-design.md`), the idea that every
52
+ hand-off is tied to the copy of the two pages it joins, and a long round of
53
+ direct feedback on a shipped funnel (Reflective's discovery flow). **The
54
+ direction below is that feedback. It outranks general taste.**
55
+
56
+ ## The one rule: Frame A → Frame B share one geometry, at every moment
57
+
58
+ > **When element A transforms into element B, A and B must have exactly the
59
+ > same geometry — size, position, corner radius, blur — on every frame of the
60
+ > transition. Not "close". Not "driven by the same numbers". The same.**
61
+
62
+ Two separate animated copies (A's and B's), each with its own clip, transform
63
+ and blur, *will* drift apart: A's own rounded ends, a border, a margin, a
64
+ different blur, a rounding difference. The eye catches a 1px mismatch
65
+ instantly, and the whole morph reads as broken.
66
+
67
+ So build every A → B as **one frame with two faces** (`references/morphFrame.ts`):
68
+ a single element owns all of the geometry (the clip is the only outline, one
69
+ transform, one blur), and A and B are *faces* that fill it and only crossfade.
70
+ They cannot differ in geometry, because there is only one.
71
+
72
+ ```ts
73
+ const answer = fillFace(answerEl, answerRect); // capture A before the page swaps
74
+ // …swap the page…
75
+ morph({
76
+ from: { rect: answerRect, radius: answerRect.height / 2 },
77
+ to: { rect: photoRect, radius: 20 },
78
+ faces: { from: answer, to: photoFace(photoEl) },
79
+ duration: 504,
80
+ });
81
+ ```
82
+
83
+ Faces: `photoFace(img)`, `fillFace(el, rect)` (answers, buttons: its colour
84
+ fills the frame, its content sits where it rests), `colorFace(color)`
85
+ (backgrounds). Recipes for every case are in `references/handoffs.md`. Never
86
+ hand-roll an A → B morph as two layers.
87
+
88
+ Check it: the frame must start exactly on A's rect and radius and end exactly
89
+ on B's, so the handover to the live elements is pixel-exact.
90
+
91
+ References — read when you reach that part:
92
+
93
+ - `references/framework/` — **the engine on the superwall framework, as
94
+ shipped** in the `animated-onboarding` example (`superwall create --example
95
+ animated-onboarding` gives the whole project): `handoffs.ts` (every
96
+ hand-off, both directions, cleanup), `useStoryRouter.ts` (`router.push` /
97
+ `back` inside the hand-off), `motion.css` (exits and entrances on the
98
+ router's phases), `layout.tsx` (chrome and the motion layer),
99
+ `Question.tsx`, `flow.ts`. Start from these on a surface.
100
+ - `references/engine.md` — the hand-off engine on the framework's router:
101
+ the hold on the layer, `flushSync` around `router.push`, the motion
102
+ layer, chrome in the layout, the focus trap, the flag, roles declared up
103
+ front, loaded destinations, interruption, traps.
104
+ - `references/handoffs.md` — how the transforms are built (answer → progress
105
+ bar, answer ↔ photo, bar → answer), the clock, and the hand-off catalog.
106
+ - `references/performance.md` — what to animate, what never to, and how to
107
+ diagnose "it's choppy".
108
+ - `references/morphFrame.ts` — **the A → B morph**: one frame, two faces, the
109
+ glide clock, the shape. Use it for every element-into-element transform.
110
+ - `references/imageReady.ts` — image readiness incl. Safari.
111
+ - `references/web-runtime/` — the same engine for a flow the user keeps in
112
+ a hand-rolled web runtime (it clones the outgoing page because that
113
+ runtime has no router). Never the starting point on a surface.
114
+
115
+ ## Direction (from the feedback)
116
+
117
+ ### 1. Map every element before choreographing
118
+
119
+ Before writing any motion, build a **map of every element on every page, for
120
+ each hand-off in both directions**, and give each exactly one role. Elements
121
+ are the same when they're **optically equivalent** — they look like the same
122
+ thing in the same place — not when they're literally the same component.
123
+ Always read between the lines.
124
+
125
+ | From → to | Motion |
126
+ |---|---|
127
+ | **A → A**, same position, same size | **No animation.** No transition out or in for either. Animating it only draws attention to something that didn't change (e.g. a pinned "Continue" on consecutive pages). |
128
+ | **A → A**, different position, size or text | Transition gracefully out and in. |
129
+ | **A → B** (a different element) | **The transform *is* the transition.** No exit on A, no entrance on B; nothing else may compete with it. |
130
+ | **A → nothing** | Scale, fade and blur out. Cascade it so the elements feel like they move *because the others did* — subtle, like dominoes. Sneak in physics wherever possible: falling back with a skew or perspective. |
131
+ | **nothing → B** | Usually the reverse idea of the above. |
132
+
133
+ **Choosing A (the source)** — the element the user interacted with last has
134
+ top priority: the option they picked in a single select. A continue button has
135
+ the lowest. For multiple choice, animate **all** the chosen options into the
136
+ progress bar.
137
+
138
+ **Choosing B (the destination)** — in order:
139
+
140
+ 1. **The most visually demanding element on the next screen that ties to the
141
+ story.** If option A in a selection is purple and the next screen has a
142
+ purple background, the background is a great destination.
143
+ 2. **A hero image.** It's always nice to morph a chosen option, or the
144
+ continue button, into the next screen's hero.
145
+ 3. When in doubt, **the progress bar**: it gamifies selection and increases
146
+ completion.
147
+ 4. Or **the next continue button**: it makes them want to press it again.
148
+
149
+ **Back reverses roles.** If three answers collapsed into a photo going
150
+ forward, all three come *out of* it going back — not just the chosen one while
151
+ the others do a standard rise.
152
+
153
+ **Verify the map in code.** Every element gets the standard entrance by
154
+ default, so an element marked "transformed from" whose exemption is missing
155
+ runs its entrance *and* the transform — two animations fighting. For every
156
+ hand-off in both directions, confirm each destination's standard entrance is
157
+ off (declare it up front: `engine.md`, "Roles, declared up front").
158
+
159
+ ### 2. How an A → B transform moves
160
+
161
+ It should feel fluid and physical, as one continuous thing.
162
+
163
+ - **One clock for every stacked phase.** A transform is several phases
164
+ stacked (lift, travel, open, land). Drive every channel — position, size,
165
+ corners, crossfade, blur — from **one** clock, so phase 1 eases in, each next
166
+ phase starts with the velocity and acceleration the last one left, and the
167
+ final phase eases out. Giving each phase its own eased span makes it stall
168
+ at every boundary. The move leads and the opening follows on the same curve
169
+ (e.g. size on `p^1.5`), never restarting from rest.
170
+ - **The clock is a critically damped spring** (damping 1.0, Apple's default
171
+ for UI), in every dimension it drives (position *and* size): a barely-there
172
+ pull-back (~1%), a quick rise to top speed early (~27% of the duration),
173
+ then a **long, continuously slowing tail** into the target — **no constant-
174
+ speed middle and no overshoot or bounce at the end**. At rest at both ends
175
+ (a final taper lands it exactly on the last frame). Check it numerically:
176
+ near top speed ≤ ~15% of the time, overshoot 0, soft braking in the last
177
+ quarter.
178
+ - **Keep the path gentle.** Arrive at a normal slope and grow size linearly
179
+ near the destination; a steep final curve or a multiplicative grow rushes
180
+ the end and magnifies any change in speed.
181
+ - **Size floor: never more than 20% smaller than the smaller end.** 80 → 100
182
+ may dip to 64 on the way, never to 20. No pinching an answer down to a
183
+ thumbnail. (Exception: an answer becoming a stretch of a 4px progress bar
184
+ has to shrink to be it.)
185
+ - **Bubbly:** a dimension that's about the same at both ends (e.g. both
186
+ 348px wide) **dips up to 20%** mid-flight (sin-shaped) and swells back —
187
+ squeezing through like a bubble. None once the ends differ by half or more.
188
+ - **One geometry** (the rule above): the frame's clip is the only outline.
189
+ Never scale a rounded shape non-uniformly (it squashes round ends into
190
+ ovals); the frame clips (`inset(... round r)`) and only ever scales *up*.
191
+ - **Corners are proportional.** Interpolate the corner radius as a *fraction
192
+ of the shape's shorter side* (its roundness: 0.5 = fully round ends), not in
193
+ pixels, starting from the source's own roundness and ending at the
194
+ destination's. A fully round answer opening into a square full-screen
195
+ background stays visibly rounded while it's big and only goes square at the
196
+ very end; interpolated in pixels, a big frame has tiny, sharp-looking
197
+ corners almost at once.
198
+ - **Blur is motion blur.** It **starts and ends crisp**, and is blurred only
199
+ while the frame is moving fastest: **from 25% to 75% of the duration**
200
+ (easing in over 25–35%, a full 5px on screen over 35–65%, easing out over
201
+ 65–75%). One blur for both faces, on the frame's outer wrapper (no
202
+ transform), so it softens the silhouette in screen pixels. **The swap
203
+ (handover) happens inside that window**, so A becomes B under the blur.
204
+ A single colour going into the bar (or back out) has nothing to smear:
205
+ `blur: 0`. Keep one switch for all motion blur (`MOTION_BLUR_ENABLED` in
206
+ `morphFrame.ts`) so it can be turned off in one place to isolate a problem.
207
+ - **Back is never a rewind.** Going back is its own move on the same clock,
208
+ landing on the same long gentle tail, with no direction flip mid-motion. E.g. back from
209
+ the progress bar: the pill takes its stretch of bar with it (the bar gives
210
+ it up at once, under the pill), slides out, and drops and grows into the
211
+ answer.
212
+ - **One duration for every A → B transform** — 504ms in the reference. They
213
+ drifted to 720–820ms and felt slow; keep them equal and brisk.
214
+
215
+ ### 3. Handovers: no doubles, no flashes, no missing targets
216
+
217
+ - **A destination never fades in while something transforms into it.** Keep
218
+ the live element hidden; the transforming copy carries it the whole way.
219
+ - **Hand over on the last frame, already painted.** Keep the live element at
220
+ `opacity: 0.001` for the whole transform (painted, but invisible), let it
221
+ return to 1 as the transform ends, and remove the copy in that same frame.
222
+ A browser doesn't paint a fully transparent element, so one kept at 0 and
223
+ revealed only on the last frame shows a frame of nothing: a flash.
224
+ - **The destination must be loaded.** An unloaded `<img>` has no height, so
225
+ the morph measures a zero target and animates a blank. Decode every image
226
+ up front and keep it; before a hand-off into a page with an image, wait for
227
+ it (up to ~400ms, a newer tap cancels the wait); if it still isn't there,
228
+ skip the morph and fade the image in on load.
229
+ - **Safari (every iPhone) loads even a cached image asynchronously** when a
230
+ new `<img>` is created: right after the page swaps, the new image reports
231
+ "not loaded" with zero height. So:
232
+ - never require the *new* `<img>` to be loaded to run the morph — require
233
+ the flow's own decoded copy to be ready (a morph gated on the live element
234
+ simply never runs on an iPhone);
235
+ - render images with `width`/`height` from their known natural size, so the
236
+ box is right before it paints;
237
+ - build copies from the already-decoded `Image` object, not `cloneNode()`
238
+ of an `<img>` (a clone reloads and paints blank);
239
+ - keep the copy on top until the live image has actually loaded;
240
+ - mark an image ready on its `load` event; older Safari rejects `decode()`
241
+ for images outside the document.
242
+ Test on a real iPhone: none of this reproduces in desktop Chrome.
243
+
244
+ - **Remove each copy when its own transform ends.** The copies' removal waits
245
+ only on the copies' animations and the destinations' 0.001 holds (which end
246
+ on the same frame), plus a live photo's load. Never on the new page's
247
+ entrances: a copy that waits for them sits over them for their whole
248
+ duration. Under a full-screen colour that hid the statement's words for
249
+ ~1s, then they just appeared. Keep two lists (`engine.md`): everything, for
250
+ a fast second tap to finish, and the handovers, for cleanup.
251
+ - **Nothing enters under a covering copy.** A morph frame is above the live
252
+ page until it hands over. Anything whose entrance starts before then (words
253
+ on a full-screen colour, a header switching onto it) fades in unseen and pops
254
+ in mid-fade when the frame goes. Start those after `TRANSFORM_MS`.
255
+
256
+ ### 3b. Full-screen colour moments (statement screens)
257
+
258
+ A "Did you know…" statement on a full-screen field of the answer colour is a
259
+ strong beat between questions. Its background is by far the most visually
260
+ demanding element on the screen, and it's the answer's own colour, so by the
261
+ destination rules:
262
+
263
+ - **Question → statement: the chosen answer opens into the background.** One
264
+ frame, answer face → colour face, the corners going from the pill's full
265
+ roundness to square only at the end. The answer doesn't fly into the
266
+ progress bar here: the background is the better destination (the bar steps
267
+ normally).
268
+ - **The colour is its own full-screen layer**, rendered by the runtime behind
269
+ the page (not the page's or body's background), so it can be a morph
270
+ destination and source as one element, and stays out of sight (0.001) until
271
+ the morph hands over.
272
+ - **The words arrive after the colour** (entrance delayed ~540ms: just after
273
+ the 504ms frame hands over, never under it), and the header and button
274
+ invert onto it, switching only once the colour has arrived.
275
+ - **Statement → next question: the colour goes into the progress bar exactly
276
+ like an answer pill** (see 4): its right edge flies to where the bar ends as
277
+ it shrinks to a bar-height pill, joins, grows together with the bar to the
278
+ new length, and bounces. The statement becomes progress. Its words leave
279
+ first, one after another, above the colour.
280
+ - **Back** is the pill's return: the stretch of bar slides out along it, then
281
+ drops and grows into the full-screen colour; and the colour closes back into
282
+ the answer that opened it.
283
+
284
+ ### 3c. The browser's own chrome (iOS 26 toolbar tint) — web funnels only
285
+
286
+ A surface in the SDK's webview has no browser chrome; skip this section
287
+ there, and never add a `position: fixed` element to a native surface (the
288
+ framework's insets rule). On a web funnel in Safari it matters: iOS 26
289
+ Safari ignores `<meta name="theme-color">`. It tints its toolbars from
290
+ a `position: fixed` element touching the top edge (within ~4px, 80%+ of the
291
+ width, 3px+ tall, with its own background colour), otherwise from the page
292
+ background. A full-screen colour sweeping in makes it retint mid-transition,
293
+ which looks janky. So:
294
+
295
+ - **Pin the tint with a sentinel**: one permanent fixed element at the very
296
+ top, 4px tall, full width, in the page colour, topmost. Safari always tints
297
+ from it. Keep `theme-color` for Chrome and older Safari.
298
+ - **Never animate with `position: fixed`.** Every copy, frame and flying pill
299
+ is `position: absolute` at the same screen coordinates (the page itself
300
+ doesn't scroll). A full-screen fixed morph frame is exactly what Safari tints
301
+ from: it flashed the statement colour into the toolbar. The sentinel must be
302
+ the only fixed element.
303
+ - To verify on a phone, turn the sentinel red for a test: the toolbar should
304
+ go red and hold through every transition.
305
+
306
+ ### 4. The signature move: the answer becomes the progress
307
+
308
+ - **Every chosen answer flies into the progress bar** — on every question
309
+ page, unless it's morphing into something better (the next page's hero).
310
+ - **The selection is what grows the bar, not a timer.** The bar holds still
311
+ until the answer arrives, then they move as one, driven by **one sampled
312
+ timeline**. A CSS transition with a guessed delay is not good enough.
313
+ - **Right edge to right edge.** The answer shrinks around its *right* edge,
314
+ and that edge flies to where the bar *currently ends*; they join, then
315
+ **grow together** to the new length. Not "dropping into the gap like a
316
+ brick".
317
+ - **Path: rise and drift together, rise leading**; it reaches the bar's height
318
+ ~87% of the way across and slides the last short stretch level.
319
+ - **A bounce after growing** (~13%, ease-out-back).
320
+ - **Nothing about the bar changes except its length** — no colour or opacity
321
+ animation (the pill reaches the bar's colour *before* it joins and is
322
+ removed without a fade), and **no height change** (a swell reads as a flash,
323
+ since the pill on top doesn't swell with it).
324
+ - The fill slides with `translateX` inside the clipping track, never `scaleX`,
325
+ so its round end stays round.
326
+ - **Anything that goes into the bar goes the same way** — a full-screen
327
+ statement colour included: right edge to the bar's end, shrinking to a
328
+ bar-height pill, join, grow together, bounce. Build it through the
329
+ one-geometry frame with a custom path (`morph({ path })`), never by
330
+ stretching the shape (a full-screen rectangle scaled to 4px squashes its
331
+ corners). The progress bar is the one exception to the size floor.
332
+ - **Back:** see "Back is never a rewind" above.
333
+
334
+ ### 5. What landed well
335
+
336
+ - "Gone within a day": the old page fades to nothing, a beat of emptiness
337
+ (~120ms), then the photo settles in from `scale(1.03)`; its exit lifts the
338
+ photo first, then the words.
339
+ - The welcome page's exit — **the example of physics in an A → nothing**: it
340
+ leans back in perspective as it floats up
341
+ (`perspective(900px) translateY(-20px) rotateX(22deg) scale(.97)` about its
342
+ bottom edge, fading), like a card tipping away.
343
+ - Hand-offs chosen per pair from the copy (forgetting pages drift away,
344
+ "re-explaining" arrives from above, agitation gets faster cuts, the last
345
+ answer completes the bar and hands over to "You're all set").
346
+
347
+ ### 6. What was tried and rejected — don't reach for these
348
+
349
+ | Tried | Why it failed |
350
+ |---|---|
351
+ | View Transitions API snapshots for exits and morphs | Snapshot artefacts (smeared edges, stretched morphs), a full-page snapshot re-composited every frame |
352
+ | `filter: blur()` on every entering line, answer and image | ~15fps on software raster; blurred text halos |
353
+ | `backdrop-filter` on answer capsules while they move | Re-computed every frame they move |
354
+ | Genie / mesh "sucked into the bar" (sliced strips) | Didn't read as premium; too clever |
355
+ | Rotating the pill to face its velocity | Didn't feel right; a straight path with the right timing did |
356
+ | A decorative background pattern reacting to transitions | Decoration competing with the story |
357
+ | Answer filling the bar's gap like a brick (left edge to bar end) | Reads as placement, not propulsion |
358
+ | A height swell on the bar when the answer joins | Flash: the pill on top doesn't swell with it |
359
+ | Fading the flying pill out over the bar | Visible as a colour change in the bar |
360
+ | A photo fading in from a large source rect | Ghosting |
361
+ | Squeezing the answer to a thumbnail to swap with the photo | Too small; squashed corners; not fluid |
362
+ | Stock `easeInOutBack` | 10% pull-back and overshoot, rushed middle: abrupt |
363
+ | A stiff simulated spring | ~6% overshoot that swells and snaps back in ~75ms |
364
+ | A smooth-step ease to a 1.5% overshoot at 82%, settling back in ~90ms | Too linear in the middle, too bouncy/snappy at the end |
365
+ | A separately eased span per phase | Stalls at every phase boundary |
366
+ | The destination fading in as the transform arrives | The element appears twice |
367
+ | Playing the forward move in reverse for back | Direction flips mid-motion; no physical landing |
368
+ | Revealing the destination on the last frame | A one-frame flash before it's painted |
369
+ | A and B as two separate animated layers, each with its own clip, transform and blur, "driven by the same numbers" | Geometry drift: A's own rounded ends, different blur, rounding; visibly different sizes mid-morph |
370
+ | Gating the morph on the new `<img>` being loaded | Never ran on iOS Safari (it loads cached images asynchronously) |
371
+ | Corner radius interpolated in pixels | A big frame gets tiny, sharp-looking corners almost at once |
372
+ | A statement colour shrinking into the bar as a plain morph to the new segment | Should move like a pill: right edge to the bar's end, join, grow together |
373
+ | `position: fixed` animated copies and morph frames | iOS 26 Safari tints its toolbar from a fixed element at the top: the statement colour flashed into the browser chrome |
374
+ | Blur tied to the swap, rising into it and fading out to the last frame | Blurred only for the first half. Blur is motion blur: crisp at both ends, blurred from 25% to 75% |
375
+ | Removing the copies once *every* animation had finished, the new page's entrances included | The full-screen colour frame sat over the statement's words for their whole entrance: a long red pause, then the words just appeared |
376
+ | Words entering on a statement at ~420ms, under a 504ms frame | Their first ~84ms happened unseen, so they popped in mid-fade when the frame went |
377
+
378
+ When the user rejects an approach, **revert it completely** to the last
379
+ approved state (confirm with the build output), then try the next idea. Don't
380
+ stack a fix on top of a rejected idea.
381
+
382
+ ## Principles
383
+
384
+ **Restraint first.** Onboarding is a
385
+ first-time, rare surface — it has the delight budget — but every motion still
386
+ needs a named purpose: explanation, spatial consistency, state indication,
387
+ feedback. Keyboard navigation (Enter/Esc) and browser back/forward get a
388
+ **plain** 200ms fade: repeated or system-animated, they must not be
389
+ choreographed.
390
+
391
+ **The router owns navigation.** Every hand-off is a custom transition the
392
+ router runs (`export const transition = "story-…"`, CSS on
393
+ `data-sw-transition` and `data-sw-phase`); the script only adds the
394
+ shared-element flights, inside a wrapper around `useRouter`. A custom
395
+ router, a page swapper, a cloned page or a `position: fixed` copy is a
396
+ rejected approach on a surface, whatever it would make easier.
397
+
398
+ **Each hand-off is tied to the pair.** Read the copy of page A
399
+ and page B, and pick motion that says what B says. Name the idea for each pair
400
+ in a code comment. In a long quiz, a family of related question → question
401
+ hand-offs is fine; make the act boundaries the distinct moments. Change pacing
402
+ by act: calm, soft, faster under tension, settled at the resolution.
403
+
404
+ **Fluid, not scripted.** Respond on pointer-down. Every
405
+ navigation first settles the previous hand-off instantly, so a fast second tap
406
+ never waits. Motion hints at its destination (it starts moving before it
407
+ opens).
408
+
409
+ **Craft (`mobile-design.md`, Motion).**
410
+ - Curves: `--ease-out: cubic-bezier(0.23, 1, 0.32, 1)`,
411
+ `--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1)`. Never `ease-in` on UI.
412
+ - Exits quicker than entries: exits 120–380ms, entries 240–720ms; A → B
413
+ transforms one shared, brisk duration.
414
+ - Entrances: title, then subtitle, then answers 40ms apart (30–80ms); answers
415
+ are tappable from the first frame.
416
+ - Never from `scale(0)`; from 0.9+ with opacity.
417
+ - Only `transform` and `opacity` move, with two sanctioned exceptions on a
418
+ single element at a time: the morph's `clip-path` and its 5px blur.
419
+ - Reduced motion: opacity only, nothing moves.
420
+ - Self-check against the never-ship list in `mobile-design.md` (`transition:
421
+ all`, `scale(0)`, `ease-in`, width/height animation, ungated hover, no
422
+ reduced motion, everything entering at once).
423
+
424
+ ## Workflow
425
+
426
+ 1. **Recon.** Find the surface (`config.ts`, one route per page in `app/`,
427
+ `layout.tsx` with the progress bar and back button), the answer
428
+ component, the page-title component, every image, and existing
429
+ easing/duration tokens. Read every page's copy and name the story arc
430
+ (acts). If a page change happens anywhere but `router.push` /
431
+ `router.back`, fix that first.
432
+ 2. **Plan as a table, then stop.** One row per hand-off: from → to, what
433
+ moves, why it fits that pair — choosing A and B by the priorities above.
434
+ Under it, the **element map** for each hand-off in both directions (every
435
+ element's role). Plus the whole-flow rules. Ask at most one decision
436
+ question with a recommendation. Build only after approval.
437
+ 3. **Build the engine** (`engine.md`, starting from `references/framework/`):
438
+ an opt-in flag, a `story-…` transition name per page, the hold on the
439
+ route layer, `router.push` / `router.back` wrapped so the swap happens
440
+ inside the hand-off (and waits for the destination's image), the motion
441
+ layer in the layout, destinations declared up front.
442
+ 4. **Build the transforms and hand-offs** (`handoffs.md`): the answer → bar
443
+ flight first, then the A → B morphs, then each pair's exit, then entrances
444
+ as CSS variable overrides.
445
+ 5. **Map check, geometry check, timeline check and performance pass** before
446
+ showing anyone: every "transformed from" element has its entrance off;
447
+ every A → B goes through `morph()` (one frame) and starts and ends exactly
448
+ on the real rects; no destination is visible before the last frame or faded
449
+ in over its copy; nothing animated is `position: fixed`. **Timeline:** for
450
+ each hand-off, list every copy's lifetime on screen next to every entrance
451
+ beneath it. No entrance may run under a copy that covers it (a full-screen
452
+ colour frame covers the whole page), and each copy is removed when its own
453
+ transform ends, not when the entrances do. Then `performance.md`. Then test
454
+ on a real iPhone.
455
+ 6. **Run it for the user.** `superwall dev`, then the studio's **Preview**
456
+ button for a QR code that opens the flow on their phone; a production
457
+ build (`superwall push`, then the studio's pushed version) is what to judge
458
+ smoothness on. Don't claim it feels right without the user's eyes on it.
459
+ 7. **Iterate on feel, one change per round, with numbers.** Compute a table
460
+ from the actual keyframes (t, ms, size, corners, position, opacity, blur)
461
+ and verify the invariants (size floor, no overshoot, speed continuity, at rest
462
+ at both ends) before reporting. For your own checks, play it at 2–5× or step
463
+ it frame by frame.
464
+ 8. **Ship behind the flag** so the old motion stays reachable (a `motion`
465
+ query key on a web funnel; a constant or a placement param natively) for
466
+ comparing funnel drop-off. `superwall push` only when asked; the user
467
+ promotes.