@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,48 @@
1
+ import { useRouter } from "superwall/navigation";
2
+ import { HANDOFF, IMAGE, type Route } from "../flow";
3
+ import { handoffMode, runHandoff, type HandoffName } from "./handoffs";
4
+ import { isImageReady, whenImageReady } from "./imageReady";
5
+
6
+ /**
7
+ * The router, wrapped so every navigation runs inside its hand-off: the
8
+ * chosen answer and the bar are measured before the page swaps, the swap
9
+ * happens synchronously inside the hand-off, and the destination is measured
10
+ * right after. A morph into a page with an image first waits (briefly) for
11
+ * that image to be decoded; a newer tap during the wait wins.
12
+ */
13
+ const IMAGE_WAIT_MS = 400;
14
+ let token = 0;
15
+
16
+ export function useStoryRouter() {
17
+ const router = useRouter();
18
+
19
+ const go = (direction: "next" | "back", route: Exclude<Route, "index">, apply: () => void) => {
20
+ const mine = ++token;
21
+ const name: HandoffName = handoffMode() === "plain" ? "plain" : HANDOFF[route];
22
+ const run = () => {
23
+ if (mine !== token) return;
24
+ runHandoff({ handoff: name, direction, update: apply });
25
+ };
26
+ // Going back, the destination is the page we came from, whose image is already on screen.
27
+ const image = direction === "next" ? IMAGE[route] : undefined;
28
+ if (name === "plain" || !image || isImageReady(image)) return run();
29
+ void whenImageReady(image, IMAGE_WAIT_MS).then(run);
30
+ };
31
+
32
+ return {
33
+ /** Forward to `route`, by the hand-off that page declares. */
34
+ push: (route: Exclude<Route, "index">) =>
35
+ go("next", route, () =>
36
+ router.push(route, {
37
+ transition: handoffMode() === "plain" ? "fade" : `story-${HANDOFF[route]}`,
38
+ }),
39
+ ),
40
+ /** Back one page, reversing the hand-off the current page arrived by. */
41
+ back: () => {
42
+ if (!router.canGoBack()) return;
43
+ const current = router.name as Route;
44
+ if (current === "index") return router.back();
45
+ go("back", current, () => router.back());
46
+ },
47
+ };
48
+ }
@@ -0,0 +1,375 @@
1
+ # Hand-offs
2
+
3
+ Each hand-off is (a) the leaving page's exit, CSS keyed on the router's
4
+ `recede` / `leave` phase, (b) CSS variable overrides for the arriving
5
+ page's entrance on `enter` / `return`, and (c) the shared-element flights
6
+ the script plays across both. Pick per pair from what the two pages say.
7
+ Below: the two signature moves, then the catalog that shipped on a 15-page
8
+ discovery funnel.
9
+
10
+ The complete, working code for everything here is in
11
+ `framework/handoffs.ts` (the script: `fly()` answer → bar, `flyBack()` bar →
12
+ answer, the `picture` / `connect` / `flood` / `absorb` cases), `morphFrame.ts`
13
+ (`morph()`, the faces, `glideAt()` the A → B clock) and
14
+ `framework/motion.css` (every exit and entrance of the whole catalog below,
15
+ on the router's phases). The example flow names six of them; name any other
16
+ on a page (`export const transition = "story-slip"`) and it plays, both ways.
17
+ The excerpts below explain the parts; the web-runtime copies in
18
+ `web-runtime/` do the same with a cloned page because that runtime has no
19
+ router.
20
+
21
+ Shared helpers:
22
+
23
+ ```ts
24
+ const EASE_OUT = "cubic-bezier(0.23, 1, 0.32, 1)";
25
+ const EASE_IN_OUT = "cubic-bezier(0.77, 0, 0.175, 1)";
26
+ const easeInOut = (t: number) => (t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2);
27
+ const easeOut = (t: number) => 1 - Math.pow(1 - t, 3);
28
+ const easeOutBack = (t: number) => { const c1 = 2; return 1 + (c1 + 1) * (t - 1) ** 3 + c1 * (t - 1) ** 2; }; // ~13% overshoot
29
+ const out = (y: number, scale = 1): Keyframe[] => [
30
+ { transform: "none", opacity: 1 },
31
+ { transform: `translate3d(0, ${y}px, 0) scale(${scale})`, opacity: 0 },
32
+ ];
33
+ ```
34
+
35
+ ## The A → B clock
36
+
37
+ Every A → B transform runs on one clock, so its stacked phases share one
38
+ continuous speed. It's a **critically damped spring** (damping 1.0: no
39
+ overshoot) chasing a target that eases in from rest after a ~1% pull-back: top
40
+ speed early (~27%), then a long, continuously slowing tail. No constant-speed
41
+ middle, no bounce at the end, at rest at both ends.
42
+
43
+ ```ts
44
+ const TRANSFORM_MS = 504; // every A → B transform, so none feels slower
45
+ const CLOCK_RAMP = 0.25; // the target eases in over the first quarter
46
+ const CLOCK_OMEGA = 9; // spring stiffness, per transition length
47
+ const CLOCK_PULL = 0.6; // → ~1% pull-back
48
+ const CLOCK_TAPER = 0.12; // the last 12% eases the tail exactly onto the target
49
+ function buildClock(samples = 1200): Float64Array {
50
+ const smoother = (u) => { const k = Math.min(1, Math.max(0, u)); return k * k * k * (k * (k * 6 - 15) + 10); };
51
+ const table = new Float64Array(samples + 1);
52
+ let x = 0, v = 0; const dt = 1 / samples;
53
+ for (let i = 0; i <= samples; i++) {
54
+ const s = smoother((i * dt) / CLOCK_RAMP);
55
+ const target = s - CLOCK_PULL * Math.sin(Math.PI * s) * (1 - s); // dips a hair, then eases to 1
56
+ table[i] = x;
57
+ v += (CLOCK_OMEGA ** 2 * (target - x) - 2 * CLOCK_OMEGA * v) * dt; // ζ = 1: critically damped
58
+ x += v * dt;
59
+ }
60
+ const end = table[samples];
61
+ for (let i = 0; i <= samples; i++) { const y = table[i] / end; table[i] = y + (1 - y) * ease01(i / samples, 1 - CLOCK_TAPER, 1); }
62
+ return table;
63
+ }
64
+ // glideAt(t): look up (and interpolate) the table; see morphFrame.ts.
65
+ ```
66
+
67
+ Measured against the previous curve (a smooth-step ease to a 1.5% overshoot
68
+ at 82%): near top speed 13% of the time instead of 23%, no overshoot instead
69
+ of 1.5% past at 75%, braking in the last quarter 2.1 instead of 5.8.
70
+
71
+ Sample it into keyframes (~30 samples, `easing: "linear"`) and derive every
72
+ channel from its value `p`: position on `p`, size and corners on `p^1.5`
73
+ (sign kept, for the pull-back), the crossfade on a smoothstep window of `p`.
74
+ The blur runs on plain time `t` instead: it's motion blur, crisp at both ends
75
+ and blurred from 25% to 75% of the duration, and the swap is placed inside
76
+ that window.
77
+
78
+ ## Signature move 1: the answer becomes the progress
79
+
80
+ Runs on every question page going forward (unless the answer morphs into an
81
+ image instead). Going back has its own move (below). Timeline:
82
+ `TRANSFORM_MS`; the answer joins the bar at 55%, the rest is the two growing
83
+ together with the bounce.
84
+
85
+ 1. Pin a copy of the chosen answer in the layout's motion layer; hide the live one (`visibility: hidden`, restored when the copies go).
86
+ 2. Create a **slug**: a plain div, `border-radius: 999px`, the bar's exact
87
+ colour, positioned at the **landing rect**: the bar's height, one step
88
+ long, right edge on the bar's *current* end (inside the filled part).
89
+ `transform-origin: 100% 50%`. Put the answer copy on the same origin.
90
+ 3. Sample the flight. Everything is placed by its **right edge**:
91
+ `a` = the answer's right-centre, `b` = the landing rect's right-centre.
92
+
93
+ ```ts
94
+ const FLIGHT_MS = TRANSFORM_MS, JOIN = 0.55, STEPS = 40; // STEPS * JOIN is whole: a keyframe sits on the join
95
+ const loX = track.left + track.width * lo, hiX = track.left + track.width * hi;
96
+ const w = Math.max(track.height, Math.min(hiX - loX, loX - track.left));
97
+ const land = new DOMRect(Math.max(track.left, loX - w), track.top, w, track.height);
98
+ const a = { x: capsule.right, y: capsule.top + capsule.height / 2 };
99
+ const b = { x: land.right, y: land.top + land.height / 2 };
100
+ const sx0 = capsule.width / land.width, sy0 = capsule.height / land.height; // both long thin pills: ~uniform
101
+ // Rise and drift together; the rise leads and finishes first (≈87% across), then a short level entry.
102
+ const riseAt = (f: number) => easeInOut(Math.min(1, Math.max(0, f / 0.75)));
103
+ const slideAt = (f: number) => easeInOut(Math.min(1, Math.max(0, f)));
104
+
105
+ for (let i = 0; i <= STEPS; i++) {
106
+ const p = i / STEPS;
107
+ // f: flight (0 = answer, 1 = joined). g: joined edge's growth (0 = lo, 1 = hi).
108
+ const f = p <= JOIN ? p / JOIN : 1;
109
+ const g = p <= JOIN ? 0 : easeOutBack((p - JOIN) / (1 - JOIN));
110
+ const e = riseAt(f); // also how far it has shrunk to bar size
111
+ const x = a.x + (b.x - a.x) * slideAt(f) + (hiX - loX) * g;
112
+ const y = a.y + (b.y - a.y) * e;
113
+ const sx = sx0 ** (1 - e), sy = sy0 ** (1 - e);
114
+ const tone = 0.9 + 0.1 * Math.min(1, e / 0.9); // capsule is 90% primary; bar colour before it joins
115
+ slugFrames.push({ offset: p, transform: `translate3d(${x - b.x}px, ${y - b.y}px, 0) scale(${sx}, ${sy})`, opacity: tone }); // never fades over the bar
116
+ fillFrames.push({ offset: p, transform: `translateX(${(lo + (hi - lo) * g - 1) * 100}%)` });
117
+ answerFrames.push({ offset: p, transform: `translate3d(${x - a.x}px, ${y - a.y}px, 0) scale(${sx / sx0}, ${sy / sy0})`,
118
+ opacity: Math.max(0, 1 - p / 0.13) }); // its label and fill go in the first ~13%
119
+ }
120
+ // slug + answer copy: linear, fill "both" (they're removed). Fill: linear, fill "none". Transition paused meanwhile.
121
+ ```
122
+
123
+ ### Going back: `flyBack()`, not a rewind
124
+
125
+ Rewinding the flight means the bar's edge pulls left, then the pill reverses
126
+ to fly right: a direction flip mid-motion. Instead the pill starts as exactly
127
+ the stretch of bar the answer earned and **takes it with it**: the bar gives
128
+ that stretch up at once (its transition held, so React's new length applies
129
+ under the pill), and the pill slides out along the bar and drops and grows
130
+ into the answer on the A → B clock, landing on its long gentle tail.
131
+
132
+ ```ts
133
+ const s = 1 - glideAt(t); // 1 at the bar → 0 at the answer
134
+ const across = (s) => s; // linear
135
+ const up = (s) => (s >= 0.75 ? 1 : s + 2.6667 * s * s - 2.963 * s * s * s);
136
+ // Level for the first quarter (sliding out along the bar), then curving down to arrive at slope 1,
137
+ // so it arrives along its line of travel and a gentle clock stays gentle on screen.
138
+ const u = up(s); // 1 = bar-like, 0 = answer, < 0 past it
139
+ const sx = 1 + (capsule.width / seg.width - 1) * (1 - u); // linear grow: doesn't rush the end
140
+ ```
141
+
142
+ A pinned copy of the answer (with its label) travels the same path at the
143
+ same shape; the pill crossfades into it at 70–90% of the clock, the label
144
+ returns over the last 20%, and the live answer takes over on the last frame
145
+ (held at `opacity: 0.001` until then, so it's already painted).
146
+
147
+ Rules this encodes (each was a correction):
148
+ - one timeline drives the flight *and* the bar;
149
+ - the 80% size floor doesn't apply here: the answer has to shrink to become a 4px stretch of bar;
150
+ - right edge to the bar's current end, then grow together;
151
+ - rise leads, short level entry, no hugging the right side;
152
+ - bounce after growing;
153
+ - the fill slides (`translateX`) so its round end matches the slug's; the slug
154
+ stays opaque and is removed while it sits exactly over the fill's end, so
155
+ nothing changes colour;
156
+ - no height change on the bar, ever.
157
+
158
+ ## Signature move 2: A → B morphs, one frame, two faces
159
+
160
+ Every element-into-element transform (an answer into the next page's hero, a
161
+ button into a photo, an answer into a background) goes through `morph()` in
162
+ `morphFrame.ts`. It builds **one** frame that owns all of the geometry, and A
163
+ and B are faces inside it that only crossfade, so they share one geometry at
164
+ every moment by construction:
165
+
166
+ ```
167
+ outer absolute at `home` (the larger end; never fixed), no transform — the blur, in screen px
168
+ middle — translate to the box's centre, scale only *up* (never squashes)
169
+ clipper — clip-path: inset(... round r), the box's size and corners: the only outline
170
+ face A — fills the clipper, no shape of its own; opacity only
171
+ face B — fills the clipper, no shape of its own; opacity only, on top
172
+ ```
173
+
174
+ The box comes from `boxAt(a, b, glideAt(t))`: position on the clock, size and
175
+ corners on `p^1.5`, the 20% bubble dip for a dimension equal at both ends,
176
+ never below 80% of the smaller end. Corners are **proportional**: the radius
177
+ is interpolated as a fraction of the box's shorter side (`roundness()`: 0.5 =
178
+ fully round ends), from A's roundness to B's, so a pill opening into a square
179
+ full-screen colour stays visibly round while it's big and only squares off at
180
+ the end. A custom `path` (below) replaces `boxAt` for moves that aren't a
181
+ plain A → B, like going into the progress bar. B fades in on top over the `handover`
182
+ window while A stays opaque beneath (the frame never goes see-through). The
183
+ blur is motion blur on the frame: crisp at both ends, blurred from 25% to 75%
184
+ of the duration (easing in 25–35%, full 5px 35–65%, easing out 65–75%), and the
185
+ handover sits inside it, so the swap happens under the blur.
186
+
187
+ ### The faces
188
+
189
+ ```ts
190
+ photoFace(img) // the decoded image, object-fit: cover over the frame — exactly how it sits at rest
191
+ fillFace(el, restRect) // el's colour fills the whole frame; a copy of its content sits where el rests
192
+ colorFace(color) // a plain colour: backgrounds, colour blocks
193
+ ```
194
+
195
+ A face must never have a shape of its own: no border-radius, border, margin,
196
+ shadow or transform (they're stripped), or it reintroduces a second geometry.
197
+ `fillFace` and `photoFace` capture their element immediately, so create the
198
+ source's face **before** the page swaps.
199
+
200
+ ### Recipe: chosen answer → next page's hero image
201
+
202
+ ```ts
203
+ // before the page swaps
204
+ const answerRect = answerEl.getBoundingClientRect();
205
+ const answer = fillFace(answerEl, answerRect);
206
+ ghostAnswer.style.visibility = "hidden"; // its copy in the leaving page
207
+ flushSync(update); // swap the page
208
+ // after
209
+ const photoEl = page.querySelector("[data-flow-image]");
210
+ photoEl.dataset.morph = ""; // its CSS entrance is off: the morph is its entrance
211
+ const photoRect = photoEl.getBoundingClientRect(); // reserved box (width/height attrs), so it's right
212
+ const m = morph({
213
+ from: { rect: answerRect, radius: answerRect.height / 2 },
214
+ to: { rect: photoRect, radius: 20 },
215
+ faces: { from: answer, to: photoFace(photoEl) },
216
+ duration: TRANSFORM_MS,
217
+ handover: [0.45, 0.75], // ~32–45% of the time: under the motion blur
218
+ });
219
+ m.faces.from.querySelectorAll("span").forEach((l) => l.animate([{ opacity: 1 }, { offset: 0.15, opacity: 0 }, { opacity: 0 }], { duration: TRANSFORM_MS }));
220
+ photoEl.animate(REVEAL_UNDER_COPY, { duration: TRANSFORM_MS, easing: "linear", fill: "backwards" });
221
+ // when the handovers (the frame's animations and this hold) and the live photo's load are done,
222
+ // in that same frame: m.frame.remove(). Not when the new page's entrances are (engine.md).
223
+ ```
224
+
225
+ ### Recipe: hero image → answer (going back)
226
+
227
+ Its own move on the same clock, landing on its gentle tail — not the forward
228
+ one reversed:
229
+
230
+ ```ts
231
+ const photoRect = oldPhoto.getBoundingClientRect();
232
+ const photo = photoFace(oldPhoto); // before the swap
233
+ flushSync(update);
234
+ answerEl.dataset.morph = "";
235
+ const answerRect = answerEl.getBoundingClientRect();
236
+ const m = morph({
237
+ from: { rect: photoRect, radius: 20 },
238
+ to: { rect: answerRect, radius: answerRect.height / 2 },
239
+ faces: { from: photo, to: fillFace(answerEl, answerRect) },
240
+ duration: TRANSFORM_MS,
241
+ handover: [0.7, 0.94], // ~43–65% of the time: under the motion blur
242
+ });
243
+ m.faces.to.querySelectorAll("span").forEach((l) => l.animate([{ opacity: 0 }, { offset: 0.85, opacity: 0 }, { opacity: 1 }], { duration: TRANSFORM_MS }));
244
+ answerEl.animate(REVEAL_UNDER_COPY, { duration: TRANSFORM_MS, easing: "linear", fill: "backwards" });
245
+ ```
246
+
247
+ ### Recipe: continue button → hero image
248
+
249
+ Same as the answer recipe with the button as A (lowest-priority source: use it
250
+ when nothing was chosen on the page):
251
+
252
+ ```ts
253
+ const button = fillFace(continueEl, continueRect); // before the swap
254
+ morph({ from: { rect: continueRect, radius: continueRect.height / 2 }, to: { rect: photoRect, radius: 20 },
255
+ faces: { from: button, to: photoFace(photoEl) }, duration: TRANSFORM_MS });
256
+ ```
257
+
258
+ ### Recipe: chosen answer → a background that ties to it (`flood`)
259
+
260
+ When the next screen's most demanding element is a background in the answer's
261
+ colour (a "Did you know…" statement), the answer opens into it. The background
262
+ is its own full-screen layer (`[data-flow-backdrop]`, see `engine.md`), so it's
263
+ one element to morph into; the statement's words arrive ~540ms later, on it
264
+ (just after the frame hands over: an entrance under it would play unseen).
265
+
266
+ ```ts
267
+ const answer = fillFace(answerEl, answerRect); // before the swap
268
+ flushSync(update);
269
+ const backdrop = document.querySelector("[data-flow-backdrop]");
270
+ backdrop.dataset.morph = "";
271
+ const m = morph({
272
+ from: { rect: answerRect, radius: answerRect.height / 2 }, // roundness 0.5
273
+ to: { rect: backdrop.getBoundingClientRect(), radius: 0 }, // square: only at the very end
274
+ faces: { from: answer, to: colorFace(getComputedStyle(backdrop).backgroundColor) },
275
+ duration: TRANSFORM_MS,
276
+ handover: [0.45, 0.75],
277
+ });
278
+ m.faces.from.querySelectorAll("span").forEach((l) => l.animate([{ opacity: 1 }, { offset: 0.15, opacity: 0 }, { opacity: 0 }], { duration: TRANSFORM_MS }));
279
+ backdrop.animate(REVEAL_UNDER_COPY, { duration: TRANSFORM_MS, easing: "linear", fill: "backwards" });
280
+ ```
281
+
282
+ Back: the colour (captured before the swap as `colorFace(color)`) closes into
283
+ the answer's `fillFace`, handover `[0.7, 0.94]`, the answer's words last, the
284
+ same as the photo → answer recipe.
285
+
286
+ ### Recipe: a full-screen colour → the progress bar (`absorb`)
287
+
288
+ The statement's colour goes into the bar **exactly like an answer pill**
289
+ (signature move 1): its right edge flies to where the bar ends as it shrinks
290
+ to a bar-height pill (rising first), joins at 55%, grows together with the
291
+ bar to the new length, and bounces. It runs through the one-geometry frame
292
+ with a custom `path`, so the big rectangle is never stretched: its corners go
293
+ from its own roundness to a fully round pill.
294
+
295
+ ```ts
296
+ // Before the swap: the backdrop's rect and colour (it's gone once the page swaps). Hold the bar's transition.
297
+ const { path, fillFrames, to } = intoBarPath(backdropRect, 0, trackRect, fromFraction, toFraction);
298
+ morph({
299
+ from: { rect: backdropRect, radius: 0 },
300
+ to: { rect: to, radius: to.height / 2 },
301
+ faces: { from: colorFace(color), to: colorFace(color) },
302
+ duration: FLIGHT_MS,
303
+ blur: 0, // one colour, nothing to smear
304
+ zIndex: 29, // under the leaving words
305
+ path, // (t) => Box: replaces boxAt
306
+ steps: STEPS, // STEPS * JOIN whole, so a keyframe lands on the join
307
+ });
308
+ fill.animate(fillFrames, { duration: FLIGHT_MS, easing: "linear", fill: "none" }); // holds, then grows with it
309
+ // The words leave first, one after another, above the colour: out(-10), 180ms, 40ms apart.
310
+ ```
311
+
312
+ `intoBarPath` is the pill flight generalised to any rect: width and height
313
+ interpolate in log space toward the landing pill (so a huge shape doesn't
314
+ race), the rise leads (`f / 0.75`), the slide eases in-out to the join, then
315
+ the right edge travels `(hi - lo) · easeOutBack(g)` with the fill.
316
+
317
+ Back (`outOfBarPath`): the bar gives up the stretch at once (held), and the
318
+ frame starts exactly on it, slides out along the bar, drops and grows into
319
+ the full-screen colour by its right edge on the A → B clock, corners from 0.5
320
+ to the backdrop's own. The backdrop is held at 0.001 and takes over on the
321
+ last frame; the statement's words arrive after.
322
+
323
+ ### Recipe: many answers → one image (`connect`)
324
+
325
+ The other answers gather into the chosen one (translate to its centre, never
326
+ below 95%, 5px blur, fade, 30ms apart), and the chosen one morphs into the
327
+ photo exactly as in the first recipe. Going back, **every** answer comes back
328
+ out of the photo: the chosen one via the reverse recipe, the others emerging
329
+ from where the frame is at 60% of the clock.
330
+
331
+ ### A new kind of face
332
+
333
+ Anything else can be a face as long as it **fills the frame and has no shape
334
+ of its own**: a function `(home) => HTMLElement` returning an absolutely
335
+ positioned element at `inset: 0`, `width/height: 100%`, no radius, border,
336
+ margin, shadow or transform. Place inner content in the frame's local
337
+ coordinates (centred at the element's rest size, scaled by `1/k` if that rest
338
+ size is larger than `home`), as `fillFace` does.
339
+
340
+ ### Checklist
341
+
342
+ - One `morph()` per A → B. Never two layers.
343
+ - The frame starts exactly on A's rect/radius and ends exactly on B's.
344
+ - A's face is created before the page swaps; B's live element has its CSS
345
+ entrance off (`data-morph` / declared in CSS) and is held at `opacity:
346
+ 0.001` until the last frame, when the copy is removed.
347
+ - Corners are proportional (a fraction of the shorter side), not pixels.
348
+ - The frame is `position: absolute`, never fixed (the iOS 26 toolbar tint).
349
+ - Faces fill the frame and have no shape of their own.
350
+ - Blur is motion blur on the frame: crisp at both ends, 5px from 25% to 75%
351
+ of the duration, with the handover inside that window.
352
+ - All A → B morphs share one duration (`TRANSFORM_MS`).
353
+
354
+ ## Catalog (a 15-page discovery funnel)
355
+
356
+ | Hand-off | Pair (from → to) | Exit (the leaving page, on `recede` / `leave`) | Entrance (overrides) | Why |
357
+ |---|---|---|---|---|
358
+ | `begin` | welcome → first question | `perspective(900px) translateY(-20px) rotateX(22deg) scale(.97)`, fade, 320ms, origin bottom — **the model A → nothing**: physics (it tips back like a card) | `--in-delay: 140ms; --in-ms: 520ms`; bar fades in and slides from 0 | the journey starts; progress appears |
359
+ | `kept` | question → question | lines and other answers lift 10px, 180ms | default | the answer → bar flight carries it |
360
+ | `picture` | price → "biggest investment" | lines/other answers lift; the chosen answer morphs | the photo *is* the morph (signature move 2) | the price *is* the investment |
361
+ | `inward` | explainer → "can you remember…" | `out(8, 0.92)`, 320ms | `--in-delay: 160ms; --in-ms: 600ms; --in-y: 24px` | big picture → looking back inward |
362
+ | `slip` | recall → "lost a breakthrough" | `out(-28)`, 380ms | `--in-delay: 180ms; --in-ms: 560ms; --in-y: 0; --in-scale: .98` | the page is forgotten, drifts off |
363
+ | `fade` | breakthrough → "how long do insights stay" | answers leave one by one, `out(-6 - 3k)`, 60ms apart | `--in-delay: 260ms` | memories fading over time |
364
+ | `gone` | → "gone within a day" | `out(0, 0.98)`, 300ms | `--in-delay: 420ms; --in-ms: 600ms; --in-y: 0; --in-scale: 1.03` | fade to nothing, a beat, then it settles |
365
+ | `blank` | "gone" → "what did we talk about" | photo lifts first `out(-16)`, words 60ms later | `--in-delay: 160ms` | the mind goes blank |
366
+ | `again` | → "re-explaining" | `out(14)` (down) | `--in-y: -16px` (from above); going back, the previous page rises from below | going back over the same ground |
367
+ | `jolt` | → "something big happens" | `out(0, .98)`, 120ms | `--in-ms: 240ms; --in-y: 0; --in-scale: .96; --stagger: 25ms` | tension: faster cuts |
368
+ | `cadence` | → "name your pattern" | answers leave 50ms apart, linear | answers `scale(.94)` on a 70ms beat | the hand-off forms a pattern |
369
+ | `connect` | pattern → "patterns are invisible" | the others gather into the chosen answer | it opens into the photo (signature move 2) | many weeks → one view |
370
+ | `flood` | answer → "Did you know…" statement | lines/other answers lift; the chosen answer opens into the full-screen colour | words `--in-delay: 540ms` (after the frame hands over); header and button invert after the colour lands | the answer *becomes* the moment |
371
+ | `absorb` | statement → next question | words leave one by one, above the colour | the colour goes into the bar like a pill; `--in-delay: 200ms` | the statement becomes progress |
372
+ | `settle` | explainer → "be honest" | `out(20)` (settles down) | `--in-delay: 200ms; --in-ms: 680ms; --in-y: 10px; --stagger: 70ms` | the calmest, most honest moment |
373
+ | `finish` | last question → done | `out(-12)`, 220ms | `--in-delay: 380ms`; bar holds full ~200ms after its bounce, then fades | the bar you watched completes |
374
+ | back (all) | — | `out(12)`, 160ms (the way it came, quicker) | `--in-ms: 300ms; --in-y: -10px; --stagger: 25ms` | spatial consistency |
375
+ | `plain` | keyboard, browser nav, reduced motion | none | 200ms fade, no stagger | frequent or system-animated |
@@ -0,0 +1,92 @@
1
+ // Reference implementation: image readiness for hand-offs (engine.md "Loaded
2
+ // destinations"), as shipped on Reflective's web2app. Call warmImage() for every
3
+ // image when the flow opens; navigation checks isImageReady()/whenImageReady()
4
+ // before a hand-off into a page with an image.
5
+
6
+ /**
7
+ * Decoded images, kept alive for the session. A hand-off that morphs into a
8
+ * page's photo needs that photo decoded before the page swaps: an <img> that
9
+ * hasn't loaded has no height yet, so the morph would measure a zero-size
10
+ * target and animate a blank copy. Holding the Image objects here also keeps
11
+ * them from being dropped before they finish.
12
+ *
13
+ * Readiness comes from the image having loaded, not from decode() alone:
14
+ * older Safari rejects decode() on an image that isn't in the document, which
15
+ * would leave a perfectly good image marked "not ready" forever. decode() is
16
+ * still awaited when it works, so the first paint doesn't stall on decoding.
17
+ */
18
+ type Entry = { img: HTMLImageElement; ready: boolean; done: Promise<void> };
19
+
20
+ const images = new Map<string, Entry>();
21
+
22
+ /** Start downloading and decoding `src` (once); resolves when it's ready or has failed. */
23
+ export function warmImage(src: string): Promise<void> {
24
+ const existing = images.get(src);
25
+ if (existing) return existing.done;
26
+ const img = new Image();
27
+ img.decoding = "async";
28
+ const entry: Entry = { img, ready: false, done: Promise.resolve() };
29
+ entry.done = new Promise<void>((resolve) => {
30
+ const settle = () => {
31
+ entry.ready = img.complete && img.naturalWidth > 0;
32
+ resolve();
33
+ };
34
+ const decodeThenSettle = () => {
35
+ img
36
+ .decode()
37
+ .catch(() => {})
38
+ .then(settle);
39
+ };
40
+ img.addEventListener("load", decodeThenSettle, { once: true });
41
+ img.addEventListener("error", settle, { once: true });
42
+ img.src = src;
43
+ if (img.complete && img.naturalWidth > 0) decodeThenSettle();
44
+ });
45
+ images.set(src, entry);
46
+ return entry.done;
47
+ }
48
+
49
+ export const isImageReady = (src: string) => images.get(src)?.ready ?? false;
50
+
51
+ /** The image's natural size once it's ready, so pages can reserve its box before it paints. */
52
+ export function imageSize(src: string): { width: number; height: number } | null {
53
+ const entry = images.get(src);
54
+ return entry?.ready ? { width: entry.img.naturalWidth, height: entry.img.naturalHeight } : null;
55
+ }
56
+
57
+ /**
58
+ * A copy of the image that paints on its first frame: the already-decoded element itself when it's
59
+ * free, else a clone. Safari loads even a cached image asynchronously when a new <img> is created, so
60
+ * a plain clone can show nothing for its first frames — the whole morph, on a phone.
61
+ */
62
+ export function decodedCopy(img: HTMLImageElement): HTMLImageElement {
63
+ const entry = images.get(img.getAttribute("src") ?? "");
64
+ // One DOM node can only be in one place: whoever claims it first gets it, the rest get a clone.
65
+ const free = entry?.ready && !claimed.has(entry.img) && !entry.img.isConnected;
66
+ if (!free) return img.cloneNode(true) as HTMLImageElement;
67
+ const decoded = entry.img;
68
+ claimed.add(decoded);
69
+ // The decoded element is reused: a morph may have left it stretched to fill its frame. Make it an
70
+ // exact stand-in for `img` every time — its attributes and nothing else (class, size, style…).
71
+ for (const { name } of Array.from(decoded.attributes))
72
+ if (name !== "src") decoded.removeAttribute(name);
73
+ for (const { name, value } of Array.from(img.attributes))
74
+ if (name !== "src") decoded.setAttribute(name, value);
75
+ return decoded;
76
+ }
77
+
78
+ const claimed = new Set<HTMLImageElement>();
79
+
80
+ /** Frees every decoded image handed out by decodedCopy (call when the copies using them are gone). */
81
+ export function releaseDecoded() {
82
+ claimed.forEach((img) => img.remove());
83
+ claimed.clear();
84
+ }
85
+
86
+ /** Resolves once `src` is decoded, or after `timeoutMs`, whichever comes first. */
87
+ export function whenImageReady(src: string, timeoutMs: number): Promise<void> {
88
+ return Promise.race([
89
+ warmImage(src),
90
+ new Promise<void>((resolve) => window.setTimeout(resolve, timeoutMs)),
91
+ ]);
92
+ }