@superwall/cli 2.0.0 → 2.1.1

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 (142) hide show
  1. package/README.md +3 -2
  2. package/dist/{apple-CkKlHBZ9.js → apple-BHbX0jbn.js} +13 -13
  3. package/dist/auth.d.ts +1 -1
  4. package/dist/auth.js +3 -3
  5. package/dist/{billing-XCZU_T46.js → billing-4zhIBFRQ.js} +3 -3
  6. package/dist/{bind-drne__Ys.js → bind-CHLHmxgA.js} +4 -4
  7. package/dist/{build-Gpdq5QXP.js → build-5PQeSnNN.js} +6 -6
  8. package/dist/{client-DP6Rc0t_.js → client-BIvOmWPC.js} +7 -3
  9. package/dist/{create-BBrtgUgS.js → create-BSNIFsnN.js} +6 -6
  10. package/dist/{create-Cwc3SRWJ.js → create-VK-pNfN7.js} +23 -23
  11. package/dist/create-oj3zXvHZ.js +19 -0
  12. package/dist/{doctor-C9ldpPFC.js → doctor-9JS96QkX.js} +6 -6
  13. package/dist/{drivers-DNrx4LWA.js → drivers-BamBJ10Y.js} +3 -3
  14. package/dist/entry.js +20 -21
  15. package/dist/{environment-DF1qKlny.js → environment-eV7LEnSN.js} +15 -2
  16. package/dist/{existing-78LWSsqS.js → existing-C8dSYHGk.js} +2 -2
  17. package/dist/{held-Cy8Wl4D1.js → held-BMisHn8F.js} +6 -6
  18. package/dist/held-DeJW2gUk.js +16 -0
  19. package/dist/{integrate-DcJhpXy8.js → integrate-VWtTNPCr.js} +22 -22
  20. package/dist/login-2JHCG6c1.js +16 -0
  21. package/dist/{login-D0lh3_JI.js → login-BimbukE5.js} +5 -5
  22. package/dist/{login-B2TsCE2H.js → login-BmwG14LC.js} +1 -1
  23. package/dist/{lookup-D-nmmAbw.js → lookup-k9EeOiZr.js} +2 -2
  24. package/dist/{migrate-Cfec564E.js → migrate-C86h6jeF.js} +22 -22
  25. package/dist/{notification-url-YDbq6FMA.js → notification-url-BVaTgWZ5.js} +2 -2
  26. package/dist/{open-Ba2vBl1_.js → open-0tDCQOXC.js} +10 -10
  27. package/dist/{org-D0g_q3mv.js → org-DUwdrKPV.js} +2 -2
  28. package/dist/{paths-DxSLdpOI.js → paths-BCbjCLP5.js} +1 -1
  29. package/dist/{playbook-DIeb7hne.js → playbook-oov9yV0q.js} +10 -10
  30. package/dist/{promote-COD4fYdz.js → promote-DPGPamkE.js} +16 -16
  31. package/dist/push-Chp21y3a.js +22 -0
  32. package/dist/{push-CncywhkQ.js → push-Cz4lJ8Qd.js} +27 -14
  33. package/dist/{registry-DSrosOYs.js → registry-CTczUigi.js} +525 -179
  34. package/dist/{resources-Dqr01Dep.js → resources-B1qKDVXd.js} +18 -6
  35. package/dist/{run-C9qg_QlC.js → run-DTPsVmFw.js} +2 -2
  36. package/dist/scan-B1SkkUi7.js +4 -0
  37. package/dist/{scan-DLrsrFS9.js → scan-Bb48xZqB.js} +1 -1
  38. package/dist/{scope-V336uz8j.js → scope-B6UYGuwn.js} +4 -4
  39. package/dist/{selection-Rdw-ZUoG.js → selection-BbNk9r1q.js} +10 -4
  40. package/dist/server-CwrZ-I1r.js +22 -0
  41. package/dist/{server-D0tGG8C4.js → server-EYBMKAG1.js} +10 -8
  42. package/dist/{session-D_nEWKXT.js → session-Crg9X-FI.js} +41 -13
  43. package/dist/session-DItGa4z0.js +6 -0
  44. package/dist/{session-CFAmMhem.js → session-xG9E8J2N.js} +1 -1
  45. package/dist/skills/superwall-framework/SKILL.md +43 -7
  46. package/dist/skills/superwall-framework/references/cli.md +1 -0
  47. package/dist/skills/superwall-framework/references/examples.md +1 -0
  48. package/dist/skills/superwall-framework/references/layout.md +34 -1
  49. package/dist/skills/superwall-framework/references/migrate-from-editor.md +16 -3
  50. package/dist/{skills-BvFOa4y6.js → skills-BdMKE2uO.js} +5 -4
  51. package/dist/{skills-DMG4bpKk.js → skills-Dg3k6TRC.js} +8 -8
  52. package/dist/{spinner-CneRK5rk.js → spinner-Ba3XhlMb.js} +3 -3
  53. package/dist/{storage-s2Dnz-yl.js → storage-DIkYajce.js} +1 -1
  54. package/dist/{storekit-yY_kS2iR.js → storekit-C2UzIIMs.js} +3 -3
  55. package/dist/storekit-DHNxDDpA.js +16 -0
  56. package/dist/{telemetry-DtG92m5O.js → telemetry-CVP8O6Y3.js} +1 -1
  57. package/dist/{token-DzRh7dI1.js → token-IWv2httm.js} +1 -1
  58. package/dist/tools-skills/animate-onboarding/SKILL.md +467 -0
  59. package/dist/tools-skills/animate-onboarding/references/engine.md +494 -0
  60. package/dist/tools-skills/animate-onboarding/references/framework/Question.tsx +71 -0
  61. package/dist/tools-skills/animate-onboarding/references/framework/README.md +40 -0
  62. package/dist/tools-skills/animate-onboarding/references/framework/answers.ts +19 -0
  63. package/dist/tools-skills/animate-onboarding/references/framework/flow.ts +80 -0
  64. package/dist/tools-skills/animate-onboarding/references/framework/handoffs.ts +869 -0
  65. package/dist/tools-skills/animate-onboarding/references/framework/layout.tsx +113 -0
  66. package/dist/tools-skills/animate-onboarding/references/framework/motion.css +559 -0
  67. package/dist/tools-skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
  68. package/dist/tools-skills/animate-onboarding/references/handoffs.md +375 -0
  69. package/dist/tools-skills/animate-onboarding/references/imageReady.ts +92 -0
  70. package/dist/tools-skills/animate-onboarding/references/morphFrame.ts +356 -0
  71. package/dist/tools-skills/animate-onboarding/references/performance.md +41 -0
  72. package/dist/tools-skills/animate-onboarding/references/web-runtime/README.md +17 -0
  73. package/dist/tools-skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
  74. package/dist/tools-skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
  75. package/dist/tools-skills/mobile-design/SKILL.md +447 -0
  76. package/dist/tools-skills/mobile-design/references/responsive.md +162 -0
  77. package/dist/tools-skills/onboarding-questions/SKILL.md +231 -0
  78. package/dist/tools-skills/onboarding-questions/references/arpu-questions.md +139 -0
  79. package/dist/tools-skills/onboarding-questions/references/craft.md +142 -0
  80. package/dist/tools-skills/onboarding-questions/references/example-reflective.md +117 -0
  81. package/dist/tools-skills/superwall/SKILL.md +263 -0
  82. package/dist/tools-skills/superwall/references/api.md +303 -0
  83. package/dist/tools-skills/superwall/references/asa.md +166 -0
  84. package/dist/tools-skills/superwall/references/asc.md +95 -0
  85. package/dist/tools-skills/superwall/references/dashboard-links.md +57 -0
  86. package/dist/tools-skills/superwall/references/data-analytics.md +896 -0
  87. package/dist/tools-skills/superwall/references/docs.md +51 -0
  88. package/dist/tools-skills/superwall/references/sdk-integration.md +104 -0
  89. package/dist/tools-skills/superwall/references/sdk-source.md +18 -0
  90. package/dist/tools-skills/superwall/workflows/dashboard/playbook.md +76 -0
  91. package/dist/tools-skills/superwall/workflows/dashboard/setup.md +100 -0
  92. package/dist/tools-skills/superwall/workflows/integrate/android.md +292 -0
  93. package/dist/tools-skills/superwall/workflows/integrate/expo.md +272 -0
  94. package/dist/tools-skills/superwall/workflows/integrate/flutter.md +285 -0
  95. package/dist/tools-skills/superwall/workflows/integrate/ios.md +314 -0
  96. package/dist/tools-skills/superwall/workflows/integrate/playbook.md +83 -0
  97. package/dist/tools-skills/superwall/workflows/integrate/react-native.md +246 -0
  98. package/dist/tools-skills/superwall/workflows/migrate/adapty.md +229 -0
  99. package/dist/tools-skills/superwall/workflows/migrate/playbook.md +78 -0
  100. package/dist/tools-skills/superwall/workflows/migrate/qonversion.md +227 -0
  101. package/dist/tools-skills/superwall/workflows/migrate/revenuecat.md +414 -0
  102. package/dist/tools-skills/superwall/workflows/placements/android.md +175 -0
  103. package/dist/tools-skills/superwall/workflows/placements/expo.md +161 -0
  104. package/dist/tools-skills/superwall/workflows/placements/flutter.md +139 -0
  105. package/dist/tools-skills/superwall/workflows/placements/ios.md +165 -0
  106. package/dist/tools-skills/superwall/workflows/placements/playbook.md +69 -0
  107. package/dist/tools-skills/superwall/workflows/placements/react-native.md +145 -0
  108. package/dist/tools-skills/superwall/workflows/placements/strategy.md +222 -0
  109. package/dist/tools-skills/superwall/workflows/review/android.md +120 -0
  110. package/dist/tools-skills/superwall/workflows/review/expo.md +100 -0
  111. package/dist/tools-skills/superwall/workflows/review/flutter.md +99 -0
  112. package/dist/tools-skills/superwall/workflows/review/ios.md +108 -0
  113. package/dist/tools-skills/superwall/workflows/review/playbook.md +70 -0
  114. package/dist/tools-skills/superwall/workflows/review/react-native.md +100 -0
  115. package/dist/tools-skills/superwall-editor/SKILL.md +113 -0
  116. package/dist/tools-skills/superwall-editor/references/cli.md +135 -0
  117. package/dist/tools-skills/superwall-editor/references/design.md +51 -0
  118. package/dist/tools-skills/superwall-editor/references/native-elements.md +171 -0
  119. package/dist/tools-skills/superwall-editor/references/workflow.md +65 -0
  120. package/dist/tools-skills/superwall-editor/scripts/sw-editor.sh +662 -0
  121. package/dist/tools-skills/wwdc/SKILL.md +22 -0
  122. package/dist/tools-skills/wwdc/references/docs.md +52 -0
  123. package/dist/tools-skills/wwdc/scripts/wwdc.sh +266 -0
  124. package/dist/tools.d.ts +4 -2
  125. package/dist/tools.js +561 -161
  126. package/dist/{upgrade-Bt4Ouw1y.js → upgrade-1t3aQUxh.js} +1 -1
  127. package/dist/{upgrade-Cqy5orjb.js → upgrade-DLf0LJDh.js} +2 -2
  128. package/package.json +2 -2
  129. package/dist/create-Yvf2gStM.js +0 -19
  130. package/dist/held-Ddw1XSsr.js +0 -16
  131. package/dist/kinds-GFXB3sYu.js +0 -11
  132. package/dist/login-BoBe8Psl.js +0 -16
  133. package/dist/push-CtD4FZQV.js +0 -22
  134. package/dist/scan-Cv5uOwVY.js +0 -4
  135. package/dist/send-BxD9yf6F.js +0 -150
  136. package/dist/server-z1LH94R_.js +0 -22
  137. package/dist/session-1AV_Bs_d.js +0 -6
  138. package/dist/storekit-DafAnGkM.js +0 -16
  139. /package/dist/{devtools-ByZ6XYnn.js → devtools-pBl_vt03.js} +0 -0
  140. /package/dist/{reports-DdPq4blM.js → reports-D_qbl7_u.js} +0 -0
  141. /package/dist/{screenshot-file-0UETadF8.js → screenshot-file-tVBfUEIi.js} +0 -0
  142. /package/dist/{storage-DYvmIOHa.d.ts → storage-CerJ5KLP.d.ts} +0 -0
@@ -0,0 +1,494 @@
1
+ # The hand-off engine
2
+
3
+ ## In the superwall framework
4
+
5
+ The framework's router already does half of what the generic engine below
6
+ builds by hand. `references/framework/` is the engine ported onto it, as
7
+ shipped in the `animated-onboarding` example (`superwall create --example
8
+ animated-onboarding`): start from those files, and read the rest of this
9
+ document for the parts that are the same everywhere (the moving parts, loaded
10
+ destinations, handing over, traps).
11
+
12
+ - **No outgoing clone.** Every page is an absolutely positioned layer inside
13
+ `[data-sw-routes]`, and the page being left stays mounted, carrying
14
+ `data-sw-phase="recede"` (going forward) or `"leave"` (going back), for as
15
+ long as the animation declared on its layer runs (capped at 5s). The
16
+ router measures that on the layer element itself, so give the layer a
17
+ silent hold of the hand-off's length and key everything else on the
18
+ phase:
19
+
20
+ ```css
21
+ [data-sw-route][data-sw-transition^="story-"][data-sw-phase] {
22
+ animation: story-hold var(--story-ms) linear; /* opacity 1 → 1 */
23
+ }
24
+ [data-sw-phase="recede"] [data-flow-page] [data-flow-line] { animation: story-out … }
25
+ [data-sw-phase="enter"] [data-flow-page] [data-flow-line] { animation: story-in … }
26
+ ```
27
+
28
+ `--story-ms` must outlast every exit, every entrance delay plus duration,
29
+ and the transform (504ms): once the phase clears, a still-running entrance
30
+ is cut. Shared elements (the chosen answer, the bar, a photo, a
31
+ statement's colour) are the only things the script animates.
32
+ - **The hand-off name is the transition name**, prefixed: `export const
33
+ transition = "story-picture"` on the page being entered (`framework/flow.ts`
34
+ maps route → hand-off → progress fraction → image). Going forward the router
35
+ uses the incoming page's transition, going back the leaving one's, so the
36
+ pair plays in reverse on the way back for free: the entry carries the name
37
+ it was pushed with. Wrap every story rule in `@media
38
+ (prefers-reduced-motion: no-preference)`; with reduced motion the wrapper
39
+ asks the router for `fade` and nothing of yours runs.
40
+ - **Swap synchronously, then measure.** `router.push(name)` is a React state
41
+ update; the destination mounts on the next render. `runHandoff` measures
42
+ the leaving page, wraps the push in `flushSync` so the new page exists to
43
+ measure in the same frame as the tap, then plays the transforms across
44
+ both (`framework/handoffs.ts`, `framework/useStoryRouter.ts`):
45
+
46
+ ```ts
47
+ const oldPage = document.querySelector('[data-sw-state="active"] [data-flow-page]');
48
+ const answer = oldSelected.getBoundingClientRect(); // before
49
+ flushSync(() => router.push("insight", { transition: "story-picture" }));
50
+ const photo = document.querySelector('[data-sw-state="active"] [data-flow-image]');
51
+ morph({ from: { rect: answer, … }, to: { rect: photo.getBoundingClientRect(), … }, mount: layer });
52
+ ```
53
+
54
+ Wait for the destination's image first exactly as below (`whenImageReady`);
55
+ a newer tap cancels the wait.
56
+ - **Copies are pinned inside a motion layer in the layout**, never
57
+ `position: fixed` (the framework forbids fixed: it ignores the insets and
58
+ rides along during transitions). `layout.tsx` renders an empty
59
+ `<div data-motion-layer>` (`position: absolute; inset: 0; z-index: 30;
60
+ pointer-events: none`) after the pages; every copy, pill and morph frame
61
+ goes in there at `rect - layerRect` (`morphFrame.ts` takes it as `mount`).
62
+ The page layers are an isolated stacking context, so the layer is always
63
+ above them.
64
+ - **Persistent chrome is `layout.tsx`.** The progress bar, back button and
65
+ close render there once and survive every navigation, which is what makes
66
+ "the answer becomes the bar" possible; the layout reads `useRouter().name`
67
+ to set the bar's fraction (`data-progress` on the fill, read by the script)
68
+ and to invert the chrome on a statement (`data-tone="inverse"`).
69
+ - **Pages stay mounted behind the next one**, which is the point (the chosen
70
+ answer is still there to hand back out of the bar) and a trap: component
71
+ state survives too. A question's commit lock must release when the page
72
+ regains focus (`useIsFocused()` from `superwall/navigation`,
73
+ `framework/Question.tsx`), or the user can never re-answer after going
74
+ back. The script hides the live answer under its copy with `visibility`
75
+ and restores it when the copies go, never removes it.
76
+ - **Only the first page gates on `paywall_open`.** Its entrance runs when
77
+ `useSuperwallSnapshot().paywall !== undefined`; every later page's
78
+ entrance is a router phase and runs on a tap, so it needs no gate.
79
+ - **The flag.** On a web funnel, `useQueryState("m")` (short key; the URL is
80
+ the state there); natively, a constant or a placement param from
81
+ `useVariables()`. `"classic"` turns the choreography off: push with the
82
+ built-in `shift` and skip the story CSS.
83
+ - **State** is user attributes: `components/answers.ts` names each
84
+ answer's key and parser, and `Question` reads and writes it with
85
+ `useUserAttribute(answer.key, answer.parser)`, saved the moment it is
86
+ tapped and selected again on the way back. No module-level answers
87
+ object; the router carries none.
88
+
89
+ Everything below describes the same engine inside a hand-rolled web
90
+ runtime (`references/web-runtime/handoffs.ts`, `story-motion.css`), which
91
+ has no router and so clones the outgoing page itself. **On a surface, never
92
+ do that**: the router is the page swapper, and a clone, a custom router or
93
+ a `position: fixed` copy is the wrong build. Read on for the parts that are
94
+ the same everywhere (the moving parts, loaded destinations, handing over,
95
+ statement screens, traps), with "the clone" read as "the leaving page".
96
+
97
+ ## The same engine in a hand-rolled web runtime (not for surfaces)
98
+
99
+ A page change in a tap-through flow is one moment: the old page leaves, the new
100
+ page arrives. The engine splits it cleanly:
101
+
102
+ - **Outgoing page:** a DOM clone of the old page, pinned (`position: absolute`
103
+ at its screen coordinates, never `fixed`: see "The browser's toolbar tint"
104
+ below) exactly where it was, animated away with WAAPI, removed when done.
105
+ - **Incoming page:** the real, live page. Its entrance is plain CSS keyed on
106
+ the hand-off name, so it also works if the script does nothing.
107
+ - **Shared elements** (the chosen answer, the progress bar, a photo) are
108
+ animated by the script across both.
109
+
110
+ Don't use the View Transitions API for this. Its snapshots smear morphs,
111
+ stretch shapes, and re-composite a full-page image every frame (see
112
+ `performance.md`). A clone is cheaper and fully controllable.
113
+
114
+ ## Data model
115
+
116
+ ```ts
117
+ // On the flow: opt in, so other flows keep their motion.
118
+ type Flow = { id: string; pages: Page[]; motion?: "story" };
119
+
120
+ // On each page: how it hands off to the next one (and back).
121
+ type FlowHandoff = "begin" | "kept" | "picture" | "inward" | "slip" | "fade" | "gone"
122
+ | "blank" | "again" | "jolt" | "cadence" | "connect" | "settle" | "finish";
123
+ type Page = { pageId: string; type: string; props: object; handoff?: FlowHandoff };
124
+ ```
125
+
126
+ Going forward, the page being **left** names the hand-off. Going back, the page
127
+ being **returned to** names it (and the pair plays in reverse).
128
+
129
+ Keep a URL override to turn it off (`?motion=classic`), read once on mount and
130
+ reserved so it doesn't leak into flow state. That's the A/B lever.
131
+
132
+ ## Mark the moving parts
133
+
134
+ Data attributes, not new components:
135
+
136
+ | Attribute | On |
137
+ |---|---|
138
+ | `data-flow-page` | the keyed page container (remounts per page) |
139
+ | `data-flow-line` | title, subtitle, eyebrow, body |
140
+ | `data-flow-option` | each answer; plus `data-selected` when chosen |
141
+ | `data-committing` | answers, during the short auto-advance pause after a tap |
142
+ | `data-flow-image` | the page's photo |
143
+ | `data-next-button` | the primary button |
144
+ | `data-progress`, `data-progress-fill` | the bar wrapper and its fill (fill carries its fraction: `data-progress="0.35"`) |
145
+ | `data-morph` | set by the script on a live element it animates itself (disables its CSS entrance) |
146
+
147
+ ### Roles, declared up front
148
+
149
+ Every element gets the standard entrance by default, so every element that is
150
+ **transformed from** something on the previous page (see the element map in
151
+ SKILL.md) needs an explicit exemption, or its entrance competes with the
152
+ morph. Don't leave that to a `dataset.morph = ""` line remembered inside each
153
+ morph's script: declare the destinations per hand-off and direction in CSS,
154
+ from the element map, so they're off from the new page's first frame.
155
+
156
+ ```css
157
+ /* forward: the chosen answer becomes the photo */
158
+ [data-motion="story"][data-flow-transition="flow-next"]:is([data-handoff="picture"], [data-handoff="connect"]) [data-flow-page] [data-flow-image],
159
+ /* back, picture: only the chosen answer comes out of the photo; the others return from nothing */
160
+ [data-motion="story"][data-flow-transition="flow-back"][data-handoff="picture"] [data-flow-page] [data-flow-option][data-selected],
161
+ /* back, connect: every answer went into the photo, so every answer comes back out */
162
+ [data-motion="story"][data-flow-transition="flow-back"][data-handoff="connect"] [data-flow-page] [data-flow-option] {
163
+ animation: none;
164
+ }
165
+ ```
166
+
167
+ Derive each selector from the map, element by element: here the unchosen
168
+ answers on the price page left on their own going forward, so going back they
169
+ *enter from nothing* and keep the standard entrance; exempting them too would
170
+ leave them popping in with no motion at all.
171
+
172
+ Keep setting `data-morph` in the script as well, as a backstop and to mark what
173
+ it's animating. Then check the map against the code for every hand-off in both
174
+ directions.
175
+
176
+ The reference code once missed this: going back through `connect`, only the
177
+ chosen answer came out of the photo while the others, which had gathered into
178
+ it going forward, ran the standard entrance. It now brings every answer back
179
+ out of the photo; check for the same slip in any new morph.
180
+
181
+ The runtime's section carries `data-motion="story"`,
182
+ `data-flow-transition="flow-next|flow-back|flow-idle"`, and
183
+ `data-handoff="<name>|default|plain"`.
184
+
185
+ ## Navigation wiring
186
+
187
+ Wrap the state changes of next/back in the hand-off, so the old DOM is measured
188
+ and cloned before React swaps it:
189
+
190
+ ```ts
191
+ const IMAGE_WAIT_MS = 400;
192
+ const token = useRef(0); // the latest navigation; one still waiting for its image is dropped
193
+
194
+ const handOff = (pair: FlowHandoff | undefined, direction: "next" | "back", destinationId: string, apply: () => void) => {
195
+ const mine = ++token.current;
196
+ if (!story) return apply();
197
+ const name = handoffMode() === "plain" ? "plain" : pair ?? "default";
198
+ const run = () => {
199
+ if (mine !== token.current) return;
200
+ runHandoff({ handoff: name, direction, update: () => { setHandoff(name); apply(); } });
201
+ };
202
+ // A morph needs its destination image decoded (see "Loaded destinations"). Ready = same frame as the tap.
203
+ const image = getPage(destinationId)?.props.image;
204
+ if (name === "plain" || !image || isImageReady(image)) return run();
205
+ void whenImageReady(image, IMAGE_WAIT_MS).then(run);
206
+ };
207
+
208
+ // goNext — the URL is written inside apply, so a dropped navigation never touches it
209
+ handOff(currentPage.handoff, "next", nextId, () => { setState(next); setDirection("next"); setHistory(h); setPageId(nextId); writeFlowUrl(/* … */); });
210
+ // goBack
211
+ handOff(getPage(previousId)?.handoff, "back", previousId, () => { setDirection("back"); setHistory(h.slice(0, -1)); setPageId(previousId); });
212
+ // popstate (browser back/forward, iOS swipe): token.current++ and setHandoff("plain") — the system already animates.
213
+ ```
214
+
215
+ `handoffMode()` returns `"plain"` for reduced motion and when the last input
216
+ was a key (listen to `pointerdown`/`keydown` in the capture phase).
217
+
218
+ ## Loaded destinations
219
+
220
+ An `<img>` that hasn't loaded has no height, so a morph into it measures a
221
+ zero-size target and animates a blank copy. `imageReady.ts`:
222
+
223
+ - **Warm and decode** every image in the flow when it opens (`warmImage`), and
224
+ hold the `Image` objects for the session (a bare `new Image()` can be
225
+ dropped before it decodes).
226
+ - **Wait briefly**: before a hand-off into a page with an image, `isImageReady`
227
+ → run now; otherwise `whenImageReady(src, 400)` then run. A newer tap, a back
228
+ press or browser navigation during the wait supersedes it.
229
+ - **Fall back**: if the image isn't known when the hand-off runs, skip the
230
+ morph — the source leaves normally — and fade the image in on its `load`
231
+ event.
232
+
233
+ **Safari** loads even a cached image asynchronously when a new `<img>` is
234
+ created, so right after the swap the new element reports not-loaded with zero
235
+ height. Chrome doesn't, which is why this only breaks on phones:
236
+
237
+ - Gate the morph on the flow's decoded copy (`isImageReady(src)`), not on the
238
+ new element (`img.complete`): gated on the element, the morph never runs on
239
+ an iPhone.
240
+ - Reserve the box from the known size, so the rect is right before it paints:
241
+ ```tsx
242
+ const size = imageSize(src); // natural size once warmed
243
+ <img data-flow-image src={src} width={size?.width} height={size?.height} className="w-full" />
244
+ ```
245
+ - Build copies from the decoded `Image` object (`decodedCopy(img)`), never
246
+ `img.cloneNode()` (a clone reloads and paints blank for its first frames).
247
+ One DOM node can only be in one place, so each decoded image is claimed by
248
+ one copy at a time and released when the hand-off ends. And because it's
249
+ reused, reset it to an exact stand-in every time (the original's attributes
250
+ and nothing else): a morph face leaves it stretched to fill its frame, and a
251
+ page copy that inherits that shows the photo filling the whole page.
252
+ - Keep the morph frame on top until the live image has actually loaded (max
253
+ ~1s), then remove it.
254
+ - Mark readiness on the `load` event; older Safari rejects `decode()` for
255
+ images outside the document.
256
+
257
+ ## runHandoff skeleton
258
+
259
+ ```ts
260
+ let running: Animation[] = []; // everything, so a quick second tap can finish it
261
+ let handovers: Animation[] = []; // only what the copies' removal waits for (see "Handing over")
262
+ let clones: HTMLElement[] = [];
263
+ let heldFill: HTMLElement | null = null;
264
+
265
+ function settlePrevious() { // a quick second tap never waits
266
+ running.forEach((a) => a.finish());
267
+ running = [];
268
+ handovers = [];
269
+ clones.forEach((c) => c.remove());
270
+ clones = [];
271
+ if (heldFill) heldFill.style.transition = "";
272
+ heldFill = null;
273
+ }
274
+
275
+ function pin(el: HTMLElement) { // clone pinned over the original
276
+ const r = el.getBoundingClientRect();
277
+ const c = el.cloneNode(true) as HTMLElement;
278
+ c.removeAttribute("data-flow-page"); // so CSS entrance selectors don't match it
279
+ c.setAttribute("aria-hidden", "true");
280
+ c.setAttribute("data-handoff-clone", "");
281
+ // Absolute, never fixed: iOS 26 Safari tints its toolbar from a fixed element at the top.
282
+ Object.assign(c.style, { position: "absolute", left: `${r.left + scrollX}px`, top: `${r.top + scrollY}px`,
283
+ width: `${r.width}px`, height: `${r.height}px`, margin: "0", zIndex: "30", pointerEvents: "none" });
284
+ document.body.appendChild(c);
285
+ clones.push(c);
286
+ return c;
287
+ }
288
+
289
+ export function runHandoff({ handoff, direction, update }) {
290
+ settlePrevious();
291
+ if (handoff === "plain") return update();
292
+ const oldPage = document.querySelector<HTMLElement>("[data-flow-page]");
293
+ if (!oldPage) return update();
294
+
295
+ // 1. Measure the old page (selected answer, image, bar fraction) and pin a clone.
296
+ // 2. Pin the chosen answer separately if it will fly; hide its copy inside the page clone.
297
+ // 3. If the bar will be carried by the answer, pause its CSS transition (heldFill).
298
+ flushSync(update); // 4. Swap the real page underneath, synchronously.
299
+ // 5. Measure the new page (image, selected answer, bar fraction, track rect).
300
+ // 6. Play: the pair's exit on the clone, flights/morphs across both.
301
+ // 7. When the handovers have finished (and no newer hand-off started): remove clones, release the bar.
302
+ // Not when *every* animation has: the new page's entrances play under the copies.
303
+ }
304
+ ```
305
+
306
+ ## Entrances: one keyframe, variables per hand-off
307
+
308
+ ```css
309
+ [data-motion="story"] {
310
+ --in-ms: 420ms; --in-delay: 70ms; /* a beat after the exit starts: pages barely overlap */
311
+ --in-y: 14px; --in-scale: 1;
312
+ --line-gap: 60ms; --opt-lead: 100ms; --stagger: 40ms; --img-lead: 120ms; --btn-lead: 180ms;
313
+ }
314
+ [data-motion="story"][data-flow-transition="flow-idle"] { --in-delay: 0ms; }
315
+
316
+ @keyframes story-in {
317
+ from { opacity: 0; transform: translate3d(0, var(--in-y), 0) scale(var(--in-scale)); }
318
+ }
319
+
320
+ [data-motion="story"] [data-flow-page] :is([data-flow-line], [data-flow-option], [data-flow-image], [data-next-button]) {
321
+ animation: story-in var(--in-ms) var(--ease-out) backwards;
322
+ }
323
+ /* delays by position: lines at --in-delay + n·--line-gap, answers at + --opt-lead + n·--stagger
324
+ (nth-child rules), image + --img-lead, button + --btn-lead */
325
+ [data-motion="story"] [data-flow-page] [data-morph] { animation: none; }
326
+
327
+ /* A hand-off is just overrides, e.g.: */
328
+ [data-motion="story"][data-flow-transition="flow-next"][data-handoff="gone"] {
329
+ --in-delay: 420ms; --in-ms: 600ms; --in-y: 0px; --in-scale: 1.03;
330
+ }
331
+ [data-motion="story"][data-flow-transition="flow-back"] { --in-ms: 300ms; --in-y: -10px; --stagger: 25ms; }
332
+ [data-motion="story"][data-handoff="plain"] { --in-ms: 200ms; --in-delay: 0ms; --in-y: 0px; --stagger: 0ms; }
333
+ @media (prefers-reduced-motion: reduce) { [data-motion="story"][data-handoff] { --in-y: 0px !important; /* … all motion vars zeroed */ } }
334
+ ```
335
+
336
+ Use `backwards` fill for entrances: once landed, press and selection styles own
337
+ the element again.
338
+
339
+ **The commit beat:** during the auto-advance pause after a tap, the other
340
+ answers step back (`[data-committing]:not([data-selected]) { opacity: 0.4 }`),
341
+ so the tap is visibly heard before the page moves. Mirror that rule for
342
+ `[data-handoff-clone]` so the leaving copy keeps it.
343
+
344
+ ## The progress bar markup
345
+
346
+ ```tsx
347
+ <div data-progress className={hidden ? "opacity-0" : "opacity-100"}>
348
+ <div className="h-1 w-full overflow-hidden rounded-full bg-ink/10"> {/* the track clips the fill */}
349
+ <div
350
+ data-progress-fill
351
+ data-progress={fraction} // read by the script
352
+ className="h-full w-full rounded-full bg-primary transition-transform duration-300"
353
+ // Slides in instead of scaling, so its rounded end stays round (matches the flying pill).
354
+ style={{ transform: `translateX(${(fraction - 1) * 100}%)` }}
355
+ />
356
+ </div>
357
+ </div>
358
+ ```
359
+
360
+ ## The commit beat, in the selection component
361
+
362
+ ```ts
363
+ // In the group that owns auto-advance: flag the pause between tap and page change.
364
+ setCommitting(true);
365
+ timeout = setTimeout(() => {
366
+ onAutoAdvance(value);
367
+ setTimeout(() => setCommitting(false), 800); // only matters if the page couldn't advance
368
+ }, 200);
369
+ // Each answer renders: data-flow-option, data-selected={selected || undefined}, data-committing={committing || undefined}
370
+ ```
371
+
372
+ ## Handing over to the live element
373
+
374
+ The transforming copies carry the destination the whole way; the live element
375
+ must never fade in over them (it appears twice). Keep it invisible but
376
+ painted for the whole transform, and swap on the last frame:
377
+
378
+ ```ts
379
+ // 0.001, not 0: a browser doesn't paint a fully transparent element, so one held at 0 and shown on the
380
+ // last frame paints a frame of nothing (a flash). At 0.001 it's painted, and invisible.
381
+ const REVEAL_UNDER_COPY: Keyframe[] = [{ opacity: 0.001 }, { opacity: 0.001 }];
382
+ live.animate(REVEAL_UNDER_COPY, { duration: TRANSFORM_MS, easing: "linear", fill: "backwards" });
383
+
384
+ // Remove the copies in the same frame the live element returns to full opacity: when the copies'
385
+ // own animations and these holds (which end together) have finished, and the live photo has loaded.
386
+ // No gap, no double layer.
387
+ Promise.all([...handovers.map((a) => a.finished), photoLoaded]).finally(() => {
388
+ clones.forEach((c) => c.remove());
389
+ releaseDecoded();
390
+ });
391
+ ```
392
+
393
+ **Remove each copy when its own transform ends, never when the whole
394
+ hand-off ends.** Keep two lists: `running` (everything, so `settlePrevious()`
395
+ can finish it on a fast tap) and `handovers` (the copies' animations plus the
396
+ live destinations' `REVEAL_UNDER_COPY` holds). Cleanup waits on `handovers`
397
+ and the photo's load, nothing else. A copy that waits for the new page's
398
+ entrances sits over them for their whole duration: with a full-screen colour
399
+ frame on top, the statement's words stayed hidden for ~1s and then just
400
+ appeared. The reference's entrances are CSS, so they're never in either list;
401
+ if you move entrances into script (WAAPI), this is the contract that breaks.
402
+
403
+ **Nothing enters under a covering copy.** The frame is above the live page
404
+ until it hands over at `TRANSFORM_MS`, so an entrance that starts earlier
405
+ plays unseen and pops in mid-fade when the frame goes. Anything arriving on a
406
+ full-screen colour (its words, the inverted header and button) starts after it.
407
+
408
+ ## The browser's toolbar tint (iOS 26)
409
+
410
+ iOS 26 Safari ignores `theme-color`. It tints its toolbars from a
411
+ `position: fixed` element touching the top edge (within ~4px, 80%+ of the
412
+ width, 3px+ tall, with its own background colour), else from the page. A
413
+ full-screen colour moving in retints the chrome mid-transition. Pin it:
414
+
415
+ ```html
416
+ <!-- index.html, before the app root. Keep the theme-color metas for Chrome and older Safari. -->
417
+ <div class="chrome-tint" aria-hidden="true"></div>
418
+ ```
419
+
420
+ ```css
421
+ /* The only fixed element: Safari always tints from it, so full-screen colours never retint the chrome. */
422
+ .chrome-tint {
423
+ position: fixed; top: 0; left: 0; right: 0; height: 4px;
424
+ z-index: 2147483647; pointer-events: none;
425
+ background-color: rgb(var(--color-ui-bg));
426
+ }
427
+ ```
428
+
429
+ Then every animated copy, morph frame and flying pill is `position: absolute`
430
+ at `rect + scroll` (the page itself doesn't scroll, so it's the same as
431
+ fixed). To check on a phone, make the sentinel red: the toolbar should turn
432
+ red and hold through every transition.
433
+
434
+ ## Statement screens: a full-screen colour as its own layer
435
+
436
+ ```tsx
437
+ // FlowRuntime: the colour is a layer behind the page, not the page's background, so a hand-off can
438
+ // morph into and out of it as one element. data-tone flips the header and button onto it.
439
+ <section data-motion="story" data-tone={page.type === "statement" ? "inverse" : undefined} className="relative …">
440
+ {page.type === "statement" && <div data-flow-backdrop aria-hidden="true" className="absolute inset-0 bg-ui-primary" />}
441
+ …
442
+ </section>
443
+ ```
444
+
445
+ ```tsx
446
+ // StatementPage: the words, centred, each a line so they arrive (and leave) one after another.
447
+ <div className="my-auto">
448
+ <p data-flow-line className="text-ui-bg/70">{eyebrow}</p> {/* "Did you know…" */}
449
+ <h1 data-flow-line className="text-[34px] text-ui-bg">{title}</h1>
450
+ {body && <p data-flow-line className="text-ui-bg/80">{body}</p>}
451
+ </div>
452
+ ```
453
+
454
+ ```css
455
+ /* Inverse tone: header, back, skip, progress and button switch once the colour has arrived. */
456
+ [data-tone="inverse"] :is(h2, [data-back-button], [data-skip-button]) { color: rgb(var(--color-ui-bg)); }
457
+ [data-tone="inverse"] [data-progress] > div { background-color: rgb(var(--color-ui-bg) / 0.3); }
458
+ [data-tone="inverse"] [data-progress-fill] { background-color: rgb(var(--color-ui-bg)); }
459
+ [data-tone="inverse"] [data-next-button] { background-color: rgb(var(--color-ui-bg)); color: rgb(var(--color-ui-primary)); }
460
+ [data-motion="story"][data-tone="inverse"] :is(h2, [data-back-button], [data-progress] > div) {
461
+ transition: color 160ms var(--ease-out) 504ms, background-color 160ms var(--ease-out) 504ms;
462
+ }
463
+ /* The words arrive once the colour has filled the screen and its frame has handed over (504ms). */
464
+ [data-motion="story"][data-flow-transition="flow-next"][data-handoff="flood"],
465
+ [data-motion="story"][data-flow-transition="flow-back"][data-handoff="absorb"] { --in-delay: 540ms; --in-y: 10px; }
466
+ [data-motion="story"][data-flow-transition="flow-next"][data-handoff="absorb"] { --in-delay: 200ms; }
467
+ ```
468
+
469
+ The hand-offs: `flood` (answer → backdrop, and back) and `absorb` (backdrop →
470
+ progress bar like a pill, and back). Recipes in `handoffs.md`.
471
+
472
+ ## Traps
473
+
474
+ - **`fill: "both"` on a live, persistent element freezes it.** A finished
475
+ WAAPI animation with forwards fill overrides every later style change. Use
476
+ `fill: "none"` for the progress fill/track, `fill: "backwards"` for live
477
+ incoming elements; keep `"both"` only for clones that get removed. On the
478
+ router the leaving page is live too (it comes back on Back): an exit the
479
+ script plays on its own elements is parked (`park()` in
480
+ `framework/handoffs.ts`: `forwards` until the hand-off is over, then
481
+ cancelled), and a cancelled animation is skipped when the next tap settles
482
+ the previous hand-off, or `finish()` would replay its end frame.
483
+ - **Measure after disabling the CSS entrance.** Set `data-morph` on a live
484
+ element *before* `getBoundingClientRect()`, or you measure it mid-entrance
485
+ and the morph lands a few pixels off, then snaps.
486
+ - **Keyframe mid-points stall motion.** Two eased segments meeting at a pinned
487
+ transform both decelerate into the pin. Put waypoints for other properties
488
+ (blur, opacity) on keyframes without `transform`; per-property intervals then
489
+ skip them.
490
+ - **Sampled paths.** For anything with its own physics (the answer's flight),
491
+ compute ~40 keyframes in JS and animate them `linear`. Make `STEPS × JOIN`
492
+ a whole number so a keyframe lands exactly on the join frame.
493
+ - **The progress fill's transition** must step aside (`transition: none`)
494
+ while the script carries the bar, and be restored when the hand-off ends.
@@ -0,0 +1,71 @@
1
+ import { useEffect, useRef, useState } from "react";
2
+ import { useHaptics, useTranslation, useUserAttribute, type Parser } from "superwall/hooks";
3
+ import { useIsFocused } from "superwall/navigation";
4
+ import type { Route } from "./flow";
5
+ import { Choice } from "./Choice";
6
+ import { useStoryRouter } from "./motion/useStoryRouter";
7
+
8
+ const COMMIT_MS = 140;
9
+
10
+ /**
11
+ * A question with a stack of answers, saved as the user attribute
12
+ * `answer.key`. A tap selects, the others step back for a beat
13
+ * (`data-committing`) so the tap is visibly heard, and the flow moves on by
14
+ * the next page's hand-off. Coming back, the earlier answer is already
15
+ * selected: that is what the bar hands back out, and what the user can
16
+ * change. The page stays mounted behind the next one, so the commit lock is
17
+ * released when it regains focus.
18
+ */
19
+ export function Question<T extends string>({
20
+ answer,
21
+ title,
22
+ options,
23
+ next,
24
+ }: {
25
+ answer: { key: string; parser: Parser<T> };
26
+ title: string;
27
+ options: readonly { value: T; label: string }[];
28
+ next: Exclude<Route, "index">;
29
+ }) {
30
+ const story = useStoryRouter();
31
+ const { t } = useTranslation();
32
+ const haptics = useHaptics();
33
+ const [selected, setSelected] = useUserAttribute(answer.key, answer.parser);
34
+ const [committing, setCommitting] = useState(false);
35
+ const timer = useRef<number>(undefined);
36
+ const focused = useIsFocused();
37
+
38
+ useEffect(() => {
39
+ if (focused) setCommitting(false);
40
+ }, [focused]);
41
+
42
+ const choose = (value: T) => {
43
+ if (committing) return;
44
+ haptics.selection();
45
+ setSelected(value);
46
+ setCommitting(true);
47
+ window.clearTimeout(timer.current);
48
+ timer.current = window.setTimeout(() => story.push(next), COMMIT_MS);
49
+ };
50
+
51
+ return (
52
+ <main className="page" data-flow-page="">
53
+ <div className="lede">
54
+ <h1 data-flow-line="">{t(title)}</h1>
55
+ </div>
56
+
57
+ <div className="choices" role="radiogroup" aria-label={t(title)}>
58
+ {options.map((option) => (
59
+ <Choice
60
+ key={option.value}
61
+ selected={selected === option.value}
62
+ committing={committing}
63
+ onChoose={() => choose(option.value)}
64
+ >
65
+ {t(option.label)}
66
+ </Choice>
67
+ ))}
68
+ </div>
69
+ </main>
70
+ );
71
+ }
@@ -0,0 +1,40 @@
1
+ # The engine on the superwall framework
2
+
3
+ These files are copied verbatim from the `animated-onboarding` example in the
4
+ superwall monorepo (`superwall create --example animated-onboarding` gives the
5
+ whole project: pages, theme, assets, messages). In that project they live at:
6
+
7
+ | here | there |
8
+ | --- | --- |
9
+ | `flow.ts` | `components/flow.ts` — route → hand-off, progress fraction, image |
10
+ | `Question.tsx` | `components/Question.tsx` — a question page; releases its commit lock on focus |
11
+ | `answers.ts` | `components/answers.ts` — each answer's user-attribute key and parser |
12
+ | `useStoryRouter.ts` | `components/motion/useStoryRouter.ts` — `push` / `back` inside the hand-off |
13
+ | `handoffs.ts` | `components/motion/handoffs.ts` — the engine |
14
+ | `../morphFrame.ts` | `components/motion/morphFrame.ts` — the one-geometry morph, with `mount` |
15
+ | `../imageReady.ts` | `components/motion/imageReady.ts` — decoded images, for Safari |
16
+ | `motion.css` | `app/motion.css` — exits and entrances on the router's phases |
17
+ | `layout.tsx` | `app/layout.tsx` — chrome, progress bar, the motion layer |
18
+
19
+ So `handoffs.ts` imports `../flow`, `./imageReady` and `./morphFrame` relative
20
+ to that layout, not to this folder. Copy them into the same places in the
21
+ user's surface and the imports hold.
22
+
23
+ What each page needs, beyond these: `export const transition = "story-<handoff>"`,
24
+ a `<main data-flow-page>` root, `data-flow-line` on each line of copy,
25
+ `data-flow-image` on the hero, `data-flow-backdrop` on a statement's colour
26
+ layer, `data-next-button` on the primary button; answers through `Question`
27
+ (`answer={STRUGGLE}`, which saves it with `useUserAttribute`), or any button
28
+ with `data-flow-option` / `data-selected` / `data-committing`.
29
+ The verified flow: cover → `begin` → question → `kept` → question → `flood` →
30
+ statement → `absorb` → question → `picture` → insight → `finish` → end, each
31
+ one also played backwards. The other ten of the catalog (`connect`, `inward`,
32
+ `slip`, `fade`, `gone`, `blank`, `again`, `jolt`, `cadence`, `settle`) are
33
+ built in the same files with the catalog's values (handoffs.md), so a page
34
+ can name any of them; `connect` was verified both ways too.
35
+
36
+ One thing the router changes about Jake's engine: the leaving page is not a
37
+ throwaway clone, it stays mounted and comes back on Back. So anything the
38
+ script animates on that page's own elements (connect's gathering answers) is
39
+ `park`ed: held at its end frame until the hand-off is over, then cancelled,
40
+ never left with `fill: both`.
@@ -0,0 +1,19 @@
1
+ import { parseAsStringEnum } from "superwall/hooks";
2
+
3
+ /**
4
+ * Every answer is a user attribute, read and written with `useUserAttribute`,
5
+ * so it outlives the page that asked and reaches Superwall the moment it is
6
+ * given. Values are stable kebab-case so audiences built on them hold.
7
+ */
8
+ export const STRUGGLE = {
9
+ key: "sleep_struggle",
10
+ parser: parseAsStringEnum(["racing", "waking", "schedule", "noise"]),
11
+ };
12
+ export const NIGHTS = {
13
+ key: "bad_nights",
14
+ parser: parseAsStringEnum(["one", "few", "most", "every"]),
15
+ };
16
+ export const TRIED = {
17
+ key: "tried_before",
18
+ parser: parseAsStringEnum(["nothing", "melatonin", "apps", "routine"]),
19
+ };