@superwall/cli 1.7.0 → 2.1.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 (229) hide show
  1. package/README.md +192 -52
  2. package/dist/{setup-Bxj22rYi.js → apple-CSzNTGHM.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-C3Q8DBU2.js} +98 -28
  6. package/dist/{bind-YrJvuRF9.js → bind-BumHTi9O.js} +38 -33
  7. package/dist/{build-DLoCW5Ri.js → build-Bpviiclc.js} +20 -26
  8. package/dist/client-BL0f_yGf.js +176 -0
  9. package/dist/{asc-Bf7zBbyS.js → client-BZ1UbpXz.js} +16 -15
  10. package/dist/config-BO1Y87kV.js +105 -0
  11. package/dist/create-BSfvpWoD.js +19 -0
  12. package/dist/{create-pkANt1Gs.js → create-BUcVG4Ab.js} +195 -169
  13. package/dist/{notification-url-DuKF2659.js → create-CfK3PeKA.js} +235 -539
  14. package/dist/doctor-BWqIYcMn.js +83 -0
  15. package/dist/{drivers-Qx9LxmRN.js → drivers-CPhdPkW5.js} +185 -172
  16. package/dist/entry.d.ts +0 -5
  17. package/dist/entry.js +28072 -1134
  18. package/dist/environment-eBXjELoN.js +58 -0
  19. package/dist/{existing-AVEfZu2A.js → existing-BltvQiX5.js} +12 -6
  20. package/dist/held-CPve03KJ.js +16 -0
  21. package/dist/held-DgnTFMl3.js +1112 -0
  22. package/dist/input-vi0bou04.js +42 -0
  23. package/dist/{integrate-brmhPG-S.js → integrate-BRsqoe01.js} +277 -254
  24. package/dist/log-NVhVe_oe.js +62 -0
  25. package/dist/login-BCEH5q0U.js +53 -0
  26. package/dist/login-BPOONe7n.js +16 -0
  27. package/dist/{login-Do4wFuLv.js → login-BbTIrCFT.js} +118 -55
  28. package/dist/lookup-rr1AkCJA.js +71 -0
  29. package/dist/migrate-C9X2Vz81.js +274 -0
  30. package/dist/notification-url-CV86qiKP.js +100 -0
  31. package/dist/{open-studio-DOw-6ydc.js → open-CcpXotHG.js} +34 -43
  32. package/dist/org-BQQDo7wm.js +35 -0
  33. package/dist/output-Ggzq5_-t.js +122 -0
  34. package/dist/paths-CRlU72cq.js +29 -0
  35. package/dist/playbook-DVMXN7fh.js +53 -0
  36. package/dist/{asc-products-9JXtDxI4.js → products-DH_fK9tY.js} +6 -6
  37. package/dist/promote-Da8xctzy.js +91 -0
  38. package/dist/push-BV-grvQg.js +22 -0
  39. package/dist/push-D6R9icWN.js +495 -0
  40. package/dist/registry-BYVD-_h6.js +10385 -0
  41. package/dist/{reports-CfJqoava.js → reports-D_qbl7_u.js} +7 -6
  42. package/dist/{resources-Bf9O1JNM.js → resources-DLON3-61.js} +162 -55
  43. package/dist/{run-DsVZ5snL.js → run-Co-BwhOg.js} +16 -22
  44. package/dist/scan-B88OlWOt.js +4 -0
  45. package/dist/{scan-zKsddO72.js → scan-CKuk-_6W.js} +48 -37
  46. package/dist/scope-DV22_Ufm.js +198 -0
  47. package/dist/screenshot-file-tVBfUEIi.js +16 -0
  48. package/dist/{selection-CxZoX4NT.js → selection-C2_KbLuo.js} +100 -51
  49. package/dist/server-C4f6ccUr.js +22 -0
  50. package/dist/{dev-DmB3XqaJ.js → server-D0d2oP-5.js} +86 -94
  51. package/dist/session-B-Uz0cQ7.js +40 -0
  52. package/dist/session-BuvArt1j.js +6 -0
  53. package/dist/session-C4rbE3VS.js +796 -0
  54. package/dist/skills/animate-onboarding/SKILL.md +467 -0
  55. package/dist/skills/animate-onboarding/references/engine.md +494 -0
  56. package/dist/skills/animate-onboarding/references/framework/Question.tsx +71 -0
  57. package/dist/skills/animate-onboarding/references/framework/README.md +40 -0
  58. package/dist/skills/animate-onboarding/references/framework/answers.ts +19 -0
  59. package/dist/skills/animate-onboarding/references/framework/flow.ts +80 -0
  60. package/dist/skills/animate-onboarding/references/framework/handoffs.ts +869 -0
  61. package/dist/skills/animate-onboarding/references/framework/layout.tsx +113 -0
  62. package/dist/skills/animate-onboarding/references/framework/motion.css +559 -0
  63. package/dist/skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
  64. package/dist/skills/animate-onboarding/references/handoffs.md +375 -0
  65. package/dist/skills/animate-onboarding/references/imageReady.ts +92 -0
  66. package/dist/skills/animate-onboarding/references/morphFrame.ts +356 -0
  67. package/dist/skills/animate-onboarding/references/performance.md +41 -0
  68. package/dist/skills/animate-onboarding/references/web-runtime/README.md +17 -0
  69. package/dist/skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
  70. package/dist/skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
  71. package/dist/skills/index.json +37 -0
  72. package/dist/skills/mobile-design/SKILL.md +447 -0
  73. package/dist/skills/mobile-design/references/responsive.md +162 -0
  74. package/dist/skills/onboarding-questions/SKILL.md +231 -0
  75. package/dist/skills/onboarding-questions/references/arpu-questions.md +139 -0
  76. package/dist/skills/onboarding-questions/references/craft.md +142 -0
  77. package/dist/skills/onboarding-questions/references/example-reflective.md +117 -0
  78. package/dist/skills/superwall/SKILL.md +82 -9
  79. package/dist/skills/superwall/references/api.md +153 -37
  80. package/dist/skills/superwall/references/apple-setup.md +316 -0
  81. package/dist/skills/superwall/references/asc.md +74 -38
  82. package/dist/skills/superwall/references/data-analytics.md +55 -21
  83. package/dist/skills/superwall/workflows/dashboard/playbook.md +3 -3
  84. package/dist/skills/superwall/workflows/dashboard/setup.md +8 -8
  85. package/dist/skills/superwall/workflows/migrate/adapty.md +6 -6
  86. package/dist/skills/superwall/workflows/migrate/playbook.md +4 -4
  87. package/dist/skills/superwall/workflows/migrate/qonversion.md +5 -5
  88. package/dist/skills/superwall/workflows/migrate/revenuecat.md +6 -6
  89. package/dist/skills/superwall/workflows/placements/android.md +2 -2
  90. package/dist/skills/superwall/workflows/placements/expo.md +2 -2
  91. package/dist/skills/superwall/workflows/placements/flutter.md +2 -2
  92. package/dist/skills/superwall/workflows/placements/ios.md +2 -2
  93. package/dist/skills/superwall/workflows/placements/playbook.md +2 -2
  94. package/dist/skills/superwall/workflows/placements/react-native.md +2 -2
  95. package/dist/skills/superwall/workflows/placements/strategy.md +2 -2
  96. package/dist/skills/superwall/workflows/review/playbook.md +1 -1
  97. package/dist/skills/superwall-editor/SKILL.md +61 -0
  98. package/dist/skills/superwall-editor/references/cli.md +135 -0
  99. package/dist/skills/superwall-editor/references/design.md +51 -0
  100. package/dist/skills/superwall-editor/references/native-elements.md +171 -0
  101. package/dist/skills/superwall-editor/references/workflow.md +65 -0
  102. package/dist/skills/superwall-editor/scripts/sw-editor.sh +662 -0
  103. package/dist/skills/superwall-framework/SKILL.md +85 -31
  104. package/dist/skills/superwall-framework/references/cli.md +58 -27
  105. package/dist/skills/superwall-framework/references/examples.md +4 -3
  106. package/dist/skills/superwall-framework/references/layout.md +64 -9
  107. package/dist/skills/superwall-framework/references/migrate-from-editor.md +1 -1
  108. package/dist/skills/superwall-framework/references/onboarding-state.md +245 -0
  109. package/dist/skills/wwdc/SKILL.md +22 -0
  110. package/dist/skills/wwdc/references/docs.md +52 -0
  111. package/dist/skills/wwdc/scripts/wwdc.sh +266 -0
  112. package/dist/skills-CLGJuMnF.js +14 -0
  113. package/dist/{skills-DPzlnfCK.js → skills-CZcpnEnG.js} +100 -122
  114. package/dist/{spawn-DSoTXy_j.js → spawn-DmmmHIP-.js} +14 -12
  115. package/dist/spinner-C2U6QBJ9.js +294 -0
  116. package/dist/storage-6h9vyiAz.js +31 -0
  117. package/dist/storage-CerJ5KLP.d.ts +16 -0
  118. package/dist/storekit-CK9JmM2D.js +16 -0
  119. package/dist/storekit-CinJra3V.js +47 -0
  120. package/dist/telemetry-DKyDhURo.js +56 -0
  121. package/dist/theme-DUsCh-Vd.js +25 -0
  122. package/dist/timing-BVxPrYq3.js +5 -0
  123. package/dist/{token-C0it-Xh7.js → token-DaxQgQkv.js} +6 -38
  124. package/dist/tools-skills/animate-onboarding/SKILL.md +467 -0
  125. package/dist/tools-skills/animate-onboarding/references/engine.md +494 -0
  126. package/dist/tools-skills/animate-onboarding/references/framework/Question.tsx +71 -0
  127. package/dist/tools-skills/animate-onboarding/references/framework/README.md +40 -0
  128. package/dist/tools-skills/animate-onboarding/references/framework/answers.ts +19 -0
  129. package/dist/tools-skills/animate-onboarding/references/framework/flow.ts +80 -0
  130. package/dist/tools-skills/animate-onboarding/references/framework/handoffs.ts +869 -0
  131. package/dist/tools-skills/animate-onboarding/references/framework/layout.tsx +113 -0
  132. package/dist/tools-skills/animate-onboarding/references/framework/motion.css +559 -0
  133. package/dist/tools-skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
  134. package/dist/tools-skills/animate-onboarding/references/handoffs.md +375 -0
  135. package/dist/tools-skills/animate-onboarding/references/imageReady.ts +92 -0
  136. package/dist/tools-skills/animate-onboarding/references/morphFrame.ts +356 -0
  137. package/dist/tools-skills/animate-onboarding/references/performance.md +41 -0
  138. package/dist/tools-skills/animate-onboarding/references/web-runtime/README.md +17 -0
  139. package/dist/tools-skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
  140. package/dist/tools-skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
  141. package/dist/tools-skills/mobile-design/SKILL.md +447 -0
  142. package/dist/tools-skills/mobile-design/references/responsive.md +162 -0
  143. package/dist/tools-skills/onboarding-questions/SKILL.md +231 -0
  144. package/dist/tools-skills/onboarding-questions/references/arpu-questions.md +139 -0
  145. package/dist/tools-skills/onboarding-questions/references/craft.md +142 -0
  146. package/dist/tools-skills/onboarding-questions/references/example-reflective.md +117 -0
  147. package/dist/tools-skills/superwall/SKILL.md +263 -0
  148. package/dist/tools-skills/superwall/references/api.md +303 -0
  149. package/dist/tools-skills/superwall/references/asa.md +166 -0
  150. package/dist/tools-skills/superwall/references/asc.md +95 -0
  151. package/dist/tools-skills/superwall/references/dashboard-links.md +57 -0
  152. package/dist/tools-skills/superwall/references/data-analytics.md +896 -0
  153. package/dist/tools-skills/superwall/references/docs.md +51 -0
  154. package/dist/tools-skills/superwall/references/sdk-integration.md +104 -0
  155. package/dist/tools-skills/superwall/references/sdk-source.md +18 -0
  156. package/dist/tools-skills/superwall/workflows/dashboard/playbook.md +76 -0
  157. package/dist/tools-skills/superwall/workflows/dashboard/setup.md +100 -0
  158. package/dist/tools-skills/superwall/workflows/integrate/android.md +292 -0
  159. package/dist/tools-skills/superwall/workflows/integrate/expo.md +272 -0
  160. package/dist/tools-skills/superwall/workflows/integrate/flutter.md +285 -0
  161. package/dist/tools-skills/superwall/workflows/integrate/ios.md +314 -0
  162. package/dist/tools-skills/superwall/workflows/integrate/playbook.md +83 -0
  163. package/dist/tools-skills/superwall/workflows/integrate/react-native.md +246 -0
  164. package/dist/tools-skills/superwall/workflows/migrate/adapty.md +229 -0
  165. package/dist/tools-skills/superwall/workflows/migrate/playbook.md +78 -0
  166. package/dist/tools-skills/superwall/workflows/migrate/qonversion.md +227 -0
  167. package/dist/tools-skills/superwall/workflows/migrate/revenuecat.md +414 -0
  168. package/dist/tools-skills/superwall/workflows/placements/android.md +175 -0
  169. package/dist/tools-skills/superwall/workflows/placements/expo.md +161 -0
  170. package/dist/tools-skills/superwall/workflows/placements/flutter.md +139 -0
  171. package/dist/tools-skills/superwall/workflows/placements/ios.md +165 -0
  172. package/dist/tools-skills/superwall/workflows/placements/playbook.md +69 -0
  173. package/dist/tools-skills/superwall/workflows/placements/react-native.md +145 -0
  174. package/dist/tools-skills/superwall/workflows/placements/strategy.md +222 -0
  175. package/dist/tools-skills/superwall/workflows/review/android.md +120 -0
  176. package/dist/tools-skills/superwall/workflows/review/expo.md +100 -0
  177. package/dist/tools-skills/superwall/workflows/review/flutter.md +99 -0
  178. package/dist/tools-skills/superwall/workflows/review/ios.md +108 -0
  179. package/dist/tools-skills/superwall/workflows/review/playbook.md +70 -0
  180. package/dist/tools-skills/superwall/workflows/review/react-native.md +100 -0
  181. package/dist/tools-skills/superwall-editor/SKILL.md +113 -0
  182. package/dist/tools-skills/superwall-editor/references/cli.md +135 -0
  183. package/dist/tools-skills/superwall-editor/references/design.md +51 -0
  184. package/dist/tools-skills/superwall-editor/references/native-elements.md +171 -0
  185. package/dist/tools-skills/superwall-editor/references/workflow.md +65 -0
  186. package/dist/tools-skills/superwall-editor/scripts/sw-editor.sh +662 -0
  187. package/dist/tools-skills/wwdc/SKILL.md +22 -0
  188. package/dist/tools-skills/wwdc/references/docs.md +52 -0
  189. package/dist/tools-skills/wwdc/scripts/wwdc.sh +266 -0
  190. package/dist/tools.d.ts +96 -0
  191. package/dist/tools.js +11360 -0
  192. package/dist/ui-D_qf3Gvw.js +53 -0
  193. package/dist/upgrade-DPo0a4Es.js +117 -0
  194. package/dist/upgrade-ffseQDMx.js +7 -0
  195. package/package.json +10 -5
  196. package/dist/api-CZzirVMj.js +0 -151
  197. package/dist/api-output-aJNw7Syy.js +0 -20
  198. package/dist/app-DH6U8yuI.js +0 -190
  199. package/dist/asa-C-sQzPPn.js +0 -1194
  200. package/dist/asc-1ZBJ6DwS.js +0 -778
  201. package/dist/auth-YRhlV3DE.js +0 -140
  202. package/dist/billing-CCYHdApx.js +0 -80
  203. package/dist/bundle-id-CKxl_026.js +0 -121
  204. package/dist/command-CMIz81Da.js +0 -301
  205. package/dist/dev-DZy6pOnB.js +0 -22
  206. package/dist/doctor-H-hf-Yww.js +0 -88
  207. package/dist/feedback-CKf-rpBW.js +0 -152
  208. package/dist/hosted-CXe9TrWx.js +0 -32
  209. package/dist/migrate-C9ERDR6y.js +0 -284
  210. package/dist/org-sj7uyvp-.js +0 -40
  211. package/dist/output-C4o2gJ1K.js +0 -146
  212. package/dist/params-l3CrvRtR.js +0 -51
  213. package/dist/pipeline-BqzqZhX1.js +0 -977
  214. package/dist/print-skill-ZojRSybs.js +0 -74
  215. package/dist/promote-BG8X4Nv_.js +0 -88
  216. package/dist/publish-sxLh-G4G.js +0 -35
  217. package/dist/push-bQ6Vxtg8.js +0 -35
  218. package/dist/query-_FbybaH-.js +0 -53
  219. package/dist/resource-CGIwSd29.js +0 -323
  220. package/dist/revenue-provider-ebsRINY8.js +0 -100
  221. package/dist/scope-BvzD-kO4.js +0 -223
  222. package/dist/skills-D_R-lEsK.js +0 -64
  223. package/dist/spinner-TWa0hia6.js +0 -18
  224. package/dist/storekit-Cj9Cpjcz.js +0 -29
  225. package/dist/telemetry-DeA1mvnT.js +0 -169
  226. package/dist/ui-Dy0b-9L8.js +0 -27738
  227. package/dist/update-B2fWIc4q.js +0 -59
  228. package/dist/upgrade-BmzkTKrh.js +0 -72
  229. /package/dist/{devtools-8EgLo86w.js → devtools-pBl_vt03.js} +0 -0
@@ -34,7 +34,7 @@ dashboard paywall built in the visual editor (`"headless": false` in
34
34
  ```
35
35
  superwall/paywalls/<id>/
36
36
  ├── config.ts definePaywall({ name, platforms: ["ios", "android"], products: { annual: "pro_5999_year" } })
37
- ├── app/ routes only — index.tsx, plans.tsx, layout.tsx (reserved)
37
+ ├── app/ routes only — index.tsx, plans.tsx, layout.tsx (reserved; may export `entry`, the stack to open on)
38
38
  ├── components/ everything that is not a route
39
39
  └── messages/en.ts strings, discovered by filename
40
40
  ```
@@ -43,7 +43,7 @@ Entry points: `superwall` (SuperwallProvider — mounted for you),
43
43
  `superwall/config`, `superwall/hooks`, `superwall/navigation`,
44
44
  `superwall/assets`.
45
45
 
46
- The framework is a private beta on the `next` channel. The CLI has
46
+ The framework ships on the `next` channel. The CLI has
47
47
  `create`/`dev`/`push`/`promote`/`publish` and the rebuild forms of `migrate`
48
48
  only while `SUPERWALL_CHANNEL=next` is set in the environment.
49
49
  `Unknown command: create` means the variable is missing from your
@@ -57,6 +57,7 @@ web page inside an app.
57
57
 
58
58
  | Task | Reference |
59
59
  | --- | --- |
60
+ | **Any onboarding, quiz, survey or multi-page funnel that asks questions — must-follow.** Every answer a typed user attribute (`useUserAttribute`) saved the moment it is given, one `next` for the buttons and `entry`, `replayStack` resuming at the first unanswered question of the user's branch, attribute naming, back and "Start over" after resuming | [references/onboarding-state.md](references/onboarding-state.md) |
60
61
  | The layout system — the DOM the framework renders, what fixed / absolute / sticky resolve against, insets (config, variables, precedence, the floor table per device and presentation), scrolling, recipes, and the debugging order for "it's under the status bar" | [references/layout.md](references/layout.md) |
61
62
  | Mobile design craft — press feedback, hover gating, inputs and the keyboard, motion values, type, worst-case content, dark mode, platform conventions, the pre-ship audit. **Read it for every new screen, and especially when there is no design reference: its values are then the design.** | the **`mobile-design`** skill (install: `npx skills add https://github.com/superwall/skills/tree/next --skill mobile-design --global --yes --agent claude-code universal --full-depth`); what the framework adds to it (the skeleton, insets, scrolling, its hooks) is [references/mobile-design.md](references/mobile-design.md) |
62
63
  | Writing the questions of an onboarding or web2app funnel — what to ask, in what order, the branching, the statements, which answers predict revenue | the **`onboarding-questions`** skill (install: `npx skills add https://github.com/superwall/skills/tree/next --skill onboarding-questions --global --yes --agent claude-code universal --full-depth`) |
@@ -95,7 +96,8 @@ curl -sL https://superwall.com/docs/framework/{page}.md # one page
95
96
  | Message catalogs, t(), locales | `localization` |
96
97
  | Preload, entry animations, SDK events, dark mode | `lifecycle` |
97
98
  | Images, video, fonts, Lottie/Rive, app-bundled local resources (`useLocalResource`) | `assets` |
98
- | close/openUrl/permissions/callbacks/`setUserAttributes` | `actions` |
99
+ | close/openUrl/permissions/callbacks (`setUserAttributes` is deprecated: `useUserAttribute`) | `actions` |
100
+ | `useUserAttribute` / `readAttribute`, parsers | `hooks` |
99
101
  | The messages a paywall exchanges with its host, hosting one yourself | `host-protocol` |
100
102
  | Device/user/params records, personalization | `variables` |
101
103
  | The dev studio, dev-vs-device differences | `studio` |
@@ -139,11 +141,15 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
139
141
  preloads paywalls hidden. Gate on
140
142
  `useSuperwallSnapshot().paywall !== undefined`. That includes CSS:
141
143
  `@starting-style` and an animation on a class present at render both
142
- finish during the preload.
144
+ finish during the preload. When iOS kills the web process, the SDK
145
+ reloads the page; from SuperwallKit 4.18.0 the reloaded page gets
146
+ `paywall_open` again, so the gate recovers with no code in the
147
+ paywall. Older iOS SDKs leave a gated reloaded page blank.
143
148
  4. **Dark mode is the `:root.dark` class the SDK stamps**, not
144
149
  `prefers-color-scheme`.
145
150
  5. **Routes are names on a stack** — no params, no order. Closing the
146
- paywall is `useActions().close()`, not navigation. Cross-route state
151
+ paywall is `useActions().close()`, not navigation. Answers a flow
152
+ collects are user attributes (principle 6); other cross-route UI state
147
153
  lives in `layout.tsx` or a plain module on a native paywall — but **on a
148
154
  web funnel (`checkout` set) every answer, selection and input is
149
155
  `useQueryState`, never `useState`**: an in-app browser hands only the
@@ -162,16 +168,47 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
162
168
  bar) rides on top of the router's transition in a layout-level layer,
163
169
  never instead of it. The `transitions` example and the
164
170
  `animate-onboarding` skill show both halves.
165
- 6. **Links go through `useActions().openUrl`**, never `<a href>` — in a
171
+ 6. **An onboarding remembers every answer, so a user who quits halfway
172
+ resumes where they left off.** Every answer is a user attribute, read and
173
+ written with `useUserAttribute(key, parser)` — `useQueryState`'s API with
174
+ the same parsers, kept by the host SDK across presentations and launches,
175
+ re-rendering at once. Keep the flow in one `next(route, user)` function:
176
+ the buttons push what it returns, and `app/layout.tsx` exports `entry`,
177
+ which replays it with `replayStack` (every answered page, then the first
178
+ unanswered one, down the branch the user actually took). `entry` runs
179
+ once with the host's attributes already in, so that page is the first
180
+ thing that paints. Never keep answers only in React state, a module or
181
+ `layout.tsx` (they die with the paywall), and never store the step or
182
+ page index: store the answers. Keys are stable snake_case meant to be
183
+ queried (`onboarding_goal`), values are enum ids read through
184
+ `parseAsStringEnum`, so an unknown or garbage value reads as `null`
185
+ (unanswered). Read
186
+ [references/onboarding-state.md](references/onboarding-state.md) before
187
+ building any multi-page question flow.
188
+
189
+ ```tsx
190
+ const goals = parseAsStringEnum(["lose", "build", "endure"]);
191
+ const [goal, setGoal] = useUserAttribute("onboarding_goal", goals); // Goal | null
192
+ const choose = (value: Goal) => {
193
+ haptics.selection();
194
+ setGoal(value); // persisted by the host SDK
195
+ const to = next("goal", { ...user, onboarding_goal: value });
196
+ if (to) router.push(to);
197
+ };
198
+ // app/layout.tsx: the stack to open on, replayed once from the attributes
199
+ export const entry: Entry = ({ user }) =>
200
+ replayStack("index", (route) => next(route, user), (route) => answered(route, user));
201
+ ```
202
+ 7. **Links go through `useActions().openUrl`**, never `<a href>` — in a
166
203
  webview an anchor does nothing or navigates the paywall away.
167
- 7. **Haptics on every meaningful tap** (`light` navigate, `selection`
204
+ 8. **Haptics on every meaningful tap** (`light` navigate, `selection`
168
205
  choose, `success` purchase) — iOS fires nothing of its own. Icon
169
206
  buttons carry `aria-label`; tap targets ≥ 44px. Every control answers
170
207
  the press itself (`:active`, ~0.96 scale), every `:hover` sits inside
171
208
  `@media (hover: hover) and (pointer: fine)` (a webview keeps a fake
172
209
  hover after a tap), and inputs are 16px or larger (iOS zooms the page
173
210
  on anything smaller).
174
- 8. **Motion is `transform` and `opacity`, nothing else, and UI feedback is
211
+ 9. **Motion is `transform` and `opacity`, nothing else, and UI feedback is
175
212
  under 300ms.** This is the rule every first paywall breaks: a plan card
176
213
  whose selection animates `border-color`, `background` or `box-shadow`,
177
214
  and a 450ms staggered entrance. Transitions name their properties on a
@@ -191,16 +228,18 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
191
228
  ```
192
229
 
193
230
  The tokens, durations and the audit are in the `mobile-design` skill.
194
- 9. **`await restore()`** — it resolves `{ status: "restored" }` or
231
+ 10. **`await restore()`** — it resolves `{ status: "restored" }` or
195
232
  `{ status: "failed" }`. "Nothing to restore" is not distinguishable
196
233
  from a store error: the SDK writes that explanation to its own logs,
197
234
  never over the protocol, so write copy covering both. The lifecycle
198
235
  also lands on `useSuperwallSnapshot().restore` (iOS sends all three of
199
236
  `restore_start/complete/fail`, Android only `restore_fail`).
200
- 10. **Commit `superwall.lock` and `superwall.d.ts`.** Never edit either by
201
- hand — the one exception is adding an app under `apps` in the lock when
202
- CI can't prompt.
203
- 11. **One project, several platforms.** `superwall.lock` binds one
237
+ 11. **Commit `superwall.lock` and `superwall.d.ts`.** Never edit either by
238
+ hand — the exceptions are adding an app under `apps` when CI can't
239
+ prompt, and the binding line a push prints for a paywall the user
240
+ confirms is theirs. The lock also records the source commit each app was
241
+ last synced to, the base the next push merges from.
242
+ 12. **One project, several platforms.** `superwall.lock` binds one
204
243
  Superwall app per platform under `apps` (`ios`, `android`, `web`), and
205
244
  a paywall lists the platforms it ships
206
245
  to with `platforms: [...]` in `config.ts` (typed) — optional on one
@@ -223,23 +262,24 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
223
262
  hosts it as the web paywall app hosts editor paywalls: the SDK prices
224
263
  the Stripe products, reports the events and finishes the checkout, so
225
264
  `register()` resolves `purchased`, with no redemption step.
226
- 12. **Shipping includes the dashboard.** A push that fails on missing
265
+ 13. **Shipping includes the dashboard.** A push that fails on missing
227
266
  products is not a blocker to report — create them with
228
267
  `superwall products create` ([references/cli.md](references/cli.md)).
229
268
  Treat "make this live" as spanning code *and* the resources it needs.
230
- 13. **A captured email must reach checkout.** A funnel that asks for the
231
- email on a page must call `useActions().setUserAttributes({ email })`
232
- the moment it has it — that is what puts it on the Stripe session as
269
+ 14. **A captured email must reach checkout.** A funnel that asks for the
270
+ email on a page must save it as the `email` user attribute
271
+ (`useUserAttribute("email")`'s setter) the moment it has it — that is what puts it on the Stripe session as
233
272
  `customer_email` (shown, not editable) and re-warms the prefetched
234
273
  session. Page state alone never reaches checkout. Same for a
235
274
  `stripe_customer_id`. Fetch `web-checkout` → "The shopper's email".
236
- 14. **Build the design reference 1:1.** Add nothing it doesn't show;
275
+ 15. **Build the design reference 1:1.** Add nothing it doesn't show;
237
276
  effects (shadows, gradients) are design decisions, not defaults.
238
- 15. **The paywall is inset by default; never write `env()` and never
277
+ 16. **The paywall is inset by default; never write `env()` and never
239
278
  `position: fixed`.** The framework's root box pads the whole paywall
240
279
  by the safe area, resolved per platform, screen and presentation
241
- (iPhone island/notch/home button, iPad, Android's status bar, a
242
- modal's zero top, landscape sides) and live on device; its content
280
+ (iPhone island/notch/home button, iPhone Duo's camera strip, iPad,
281
+ Android's status bar, a modal's zero top, landscape sides) and live
282
+ on device; its content
243
283
  box is what layout chrome positions against. So layouts and pages
244
284
  write ordinary padding, a layout's shell is `flex: 1 1 auto` (never
245
285
  `100dvh`), chrome is absolute in `layout.tsx`, a pinned CTA is sticky
@@ -249,18 +289,18 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
249
289
  bleed, and only chrome over a bleed reads `--sw-safe-area-inset-*`.
250
290
  When something sits under a bar, run the debugging order in
251
291
  [references/layout.md](references/layout.md) before touching CSS.
252
- 16. **A non-white background goes in `config.ts`, not only in CSS.**
292
+ 17. **A non-white background goes in `config.ts`, not only in CSS.**
253
293
  `--sw-background` paints the routes; `background` in config is what
254
294
  the framework writes on `<html>`, and `<html>` is what shows when an
255
295
  iOS scroll rubber-bands past the end of the content. Set only the CSS
256
296
  variable and every bounce flashes white — worst on a dark paywall.
257
297
  Set both, to the same colors, in the same change.
258
- 17. **A paywall is finished on the smallest and the largest screen it
298
+ 18. **A paywall is finished on the smallest and the largest screen it
259
299
  ships to**, not on the default frame: iPhone SE at 320–375 wide and
260
300
  667 tall, an island phone, a Pixel, an iPad, landscape where the app
261
301
  allows it, and the configured presentation style
262
302
  (`responsive.md` in the `mobile-design` skill).
263
- 18. **Every user-facing string is a message, from the first commit, even
303
+ 19. **Every user-facing string is a message, from the first commit, even
264
304
  in one language.** Copy lives in `messages/en.ts` (shared, or per
265
305
  paywall) and reaches the page through `useTranslation().t("key")`,
266
306
  `aria-label`s and button labels included; never a literal in JSX. A
@@ -268,7 +308,7 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
268
308
  never in a catalog: interpolate them (`"Subscribe · {price}"`) and
269
309
  guard on the value with a bare-key fallback. The scaffold starts this
270
310
  way; keep it that way (docs: `localization`).
271
- 19. **Any host the surface calls must be named in `allowedHosts`.** A
311
+ 20. **Any host the surface calls must be named in `allowedHosts`.** A
272
312
  published paywall is served under a Content-Security-Policy that
273
313
  permits Superwall and Stripe and nothing else, so a `fetch` to a
274
314
  customer's own API — saving quiz answers, capturing a lead, a custom
@@ -285,6 +325,14 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
285
325
  all, so a local API works there unnamed and a missing host is only ever
286
326
  caught after deploy unless you write it up front (docs: `config`,
287
327
  `troubleshooting`).
328
+ 21. **Never require `localStorage` or `sessionStorage`.** In the Android
329
+ SDK's WebView both are `null`. They aren't `undefined`, so a `typeof`
330
+ guard passes and the call throws. An unguarded read in a render or an
331
+ effect unmounts the whole paywall and leaves a blank screen the user
332
+ can't leave. Keep state that spans pages in React (it lives for the
333
+ whole presentation), and state that must outlast it in a user
334
+ attribute (`useUserAttribute`), which the host persists. Use storage only for something optional, inside a
335
+ `try`/`catch` that treats a failure as unset (docs: `troubleshooting`).
288
336
 
289
337
  ## Working loop
290
338
 
@@ -303,12 +351,11 @@ on every preset, both schemes. When a layout bug appears, the numbered
303
351
  debugging order in [references/layout.md](references/layout.md) finds it
304
352
  from the devtools console in under a minute; don't guess at CSS first.
305
353
 
306
- Two gates before promising a push will work: Superwall for Agents is in
307
- private beta and must be enabled on each app you push to (`superwall apps
308
- list --json` → `features_enabled` lists `headless_paywalls`; a refused push
309
- says "Superwall for Agents is in private beta and isn't enabled for this
310
- app yet" — support@superwall.com turns it on), and every product named in a
311
- `config.ts` must exist on the dashboard.
354
+ Before promising a push will work, check that every product named in a
355
+ `config.ts` exists on the dashboard. A push merges onto teammates' source
356
+ and stops naming the files when it can't; `--overwrite-source` discards
357
+ their work, so pass it only when the user says to
358
+ ([references/cli.md](references/cli.md)).
312
359
 
313
360
  ## Report what's broken
314
361
 
@@ -319,6 +366,13 @@ on, however small. Write it with every ID needed to reproduce it, tell the
319
366
  user in one line, send on their yes (or straight away if they've said you
320
367
  may). Strip secrets and customer data.
321
368
 
369
+ First make sure it still happens on the latest release, since it may already be
370
+ fixed: compare `superwall --version` and the project's `superwall` dependency
371
+ with `npm view superwall version`. If either is older, run `superwall upgrade`
372
+ and `bun add superwall@latest` (or npm) in the project, then repeat what
373
+ failed. Fixed → tell the user which version fixed it and send nothing. Still
374
+ broken → report it with the versions you reproduced it on.
375
+
322
376
  ```bash
323
377
  superwall feedback "Ran X; expected Y; got Z. Steps: …" --title "..." --kind bug \
324
378
  --command "superwall push" --app <id> --context paywall=<id> \
@@ -15,7 +15,8 @@ superwall publish -m "Q3 test" # record why
15
15
 
16
16
  The scaffolded package scripts mirror these (`dev`, `push`, `promote`,
17
17
  `ship`). Auth: `superwall login` once interactively; in CI set
18
- `SUPERWALL_API_KEY` (an `sk_…` key). `dev` needs no login.
18
+ `SUPERWALL_API_KEY`, which is only ever the organization's secret key
19
+ (`sk_…`), never an app's public `pk_…` key. `dev` needs no login.
19
20
 
20
21
  ## `superwall create`
21
22
 
@@ -66,12 +67,7 @@ wiring are [migrate-from-native.md](migrate-from-native.md).
66
67
  Hosts the studio for the project (or several:
67
68
  `superwall dev examples/*`). Regenerates `superwall.d.ts` first, so route
68
69
  and product types are always current. `--port/-p` (default 6100, moves to
69
- the next free port), `--host` (default `0.0.0.0`), `--chat <url>`
70
- (development only: a chat worker's origin, default
71
- `$SUPERWALL_STUDIO_AI_URL`, needs `superwall login` — an `sk_` key is
72
- refused). `--chat` opens the studio's AI chat locally, and that chat edits
73
- the source the app last pushed, inside a cloud sandbox — never the working
74
- tree it is running in.
70
+ the next free port), `--host` (default `0.0.0.0`).
75
71
 
76
72
  It prints a **Device** URL and QR beside the studio one, for opening the
77
73
  paywalls on a phone on the same wifi. If the app's App Transport Security
@@ -157,16 +153,17 @@ A push refuses if a `config.ts` names a product the dashboard doesn't have.
157
153
 
158
154
  ```sh
159
155
  superwall entitlements list --json # grab the NUMERIC entitlement id
160
- superwall products create <identifier> \
161
- --project <id> --app <id> \
156
+ superwall products create --identifier <identifier> \
157
+ --app <id|dashboard link> \
162
158
  --name "Annual" --price 39.99 --period year \
163
159
  --trial-days 7 --entitlement <numeric-id> --json
164
160
  ```
165
161
 
166
162
  - `--entitlement` takes the **numeric id** (`55688`), not the identifier
167
163
  (`pro`) — the identifier fails with a decode error.
168
- - Pass `--project` explicitly when the account has several, or it errors
169
- with "Multiple projects found".
164
+ - Pass `--app <id|dashboard link>` (or `--project <id>`) when the account
165
+ has several projects, or it stops with "You can open N projects" and
166
+ lists them.
170
167
  - `--price` is major units (39.99); `--period` is `day|week|month|year`;
171
168
  `--trial-days` sets the intro offer. `--dry-run` confirms the target first.
172
169
 
@@ -178,13 +175,8 @@ Creating products writes to the user's real dashboard. Doing it is right
178
175
  when they've asked you to push or to create them; name it in your summary
179
176
  either way.
180
177
 
181
- Two gates to check before promising a push will work:
178
+ One more gate to check before promising a push will work:
182
179
 
183
- - **Superwall for Agents is in private beta and must be enabled on each
184
- app you push to** — otherwise the push stops with "Superwall for Agents
185
- is in private beta and isn't enabled for this app yet." Nothing in the
186
- CLI can set it; support@superwall.com turns it on. Check
187
- `superwall apps list --json` → `features_enabled` for `headless_paywalls`.
188
180
  - **One broken surface blocks the whole push.** A leftover scaffold aimed at
189
181
  a nonexistent product stops everything — push what you built with repeated
190
182
  `--id` flags instead of touching unrelated directories.
@@ -207,7 +199,8 @@ The hosted studio's chat runs this at the end of every turn for its preview.
207
199
  Builds every paywall, versions the changed ones, and leaves production
208
200
  alone. Re-running with nothing changed is a no-op. Flags: `--id <id>`
209
201
  (limit, repeatable), `--platform <p>` (repeatable or comma-separated; limits the platforms),
210
- `--rename <old>=<new>`, `-m <note>`.
202
+ `--rename <old>=<new>`, `-m <note>`, `--overwrite-source` (below; `publish`
203
+ takes it too).
211
204
 
212
205
  A push refuses — before anything is written — when:
213
206
 
@@ -221,6 +214,11 @@ A push refuses — before anything is written — when:
221
214
  First push binds each paywall (creating it on Superwall if needed) and
222
215
  records the binding in `superwall.lock`, per platform — commit it. After
223
216
  that, push always updates the same paywalls; no IDs ever appear in your code.
217
+ An existing headless paywall with the same id that the lock doesn't bind is
218
+ never taken over on a name alone: interactively push asks, otherwise it
219
+ stops and prints the lock line to add if the paywall is this project's.
220
+ Never add that line without the user confirming the paywall is theirs;
221
+ renaming the directory creates a new one instead.
224
222
 
225
223
  ### Several platforms
226
224
 
@@ -236,10 +234,14 @@ under `apps`:
236
234
  "plus-upgrade": { "ios": { "paywallId": "2001" }, "android": { "paywallId": "2002" } },
237
235
  "web-upgrade": { "web": { "paywallId": "2003" } }
238
236
  },
239
- "funnels": {}
237
+ "funnels": {},
238
+ "sources": { "…": "<commit sha>" }
240
239
  }
241
240
  ```
242
241
 
242
+ `sources` is the commit each app's source repo was last synced to (see
243
+ Source, below). Never edit it.
244
+
243
245
  Each paywall says which platforms it ships to in `config.ts` — a typed
244
246
  array of `ios | android | web`:
245
247
 
@@ -308,12 +310,36 @@ next promote.
308
310
 
309
311
  ### Source
310
312
 
311
- Every push also snapshots your `superwall/` source to Superwall, so the
312
- dashboard can show and diff the code each version was built from — and
313
- `-m "why"` records the reason there. `.env`, `node_modules/`, and
314
- gitignored files never leave the machine. If any import reaches outside
315
- the project directory, the push warns and the dashboard disables remote
316
- editing for that paywall (docs: `project-structure`).
313
+ Every push also saves the `superwall/` source to the app's source repo on
314
+ Superwall, so the dashboard can show and diff the code each version was
315
+ built from — and `-m "why"` records the reason there.
316
+
317
+ - **Teammates' work is kept.** The repo is shared by everyone who pushes to
318
+ the app. A push applies this project's changes on top of whatever others
319
+ published since its last push, from the commit `superwall.lock` records
320
+ under `sources` (commit the lock). It stops and names the files rather
321
+ than overwrite: `Someone else published changes to …` (the same files
322
+ changed on both sides: pull their commits, push again) or `The source
323
+ repo differs from this project in …` (no sync point recorded: pull the
324
+ latest `superwall.lock`). `--overwrite-source` replaces the remote
325
+ source with this project's. It discards a teammate's work, so it is the
326
+ user's decision, never a fix you reach for on your own.
327
+ - **No version ships without its source.** A version whose source didn't
328
+ land is recorded in `superwall.lock` (`sourcePending`); the next push
329
+ finishes its source before anything else, `promote` refuses it (`version
330
+ N has no source yet`), and `publish` finishes the source before
331
+ promoting.
332
+ - **What never leaves the machine:** `.env*`, `node_modules/`,
333
+ `.superwall/`, `.git/`, key and credential files (`*.p8`, `*.p12`,
334
+ `*.pem`, `*.key`, keystores, `.npmrc`, `.netrc`, `google-services.json`,
335
+ `GoogleService-Info.plist`), and gitignored files. A source tree over
336
+ 250 MB stops the push before any version exists, naming the largest
337
+ files.
338
+ - **Git is required.** Without it nothing is created.
339
+
340
+ If any import reaches outside the project directory, the push warns and
341
+ the dashboard disables remote editing for that paywall (docs:
342
+ `project-structure`).
317
343
 
318
344
  ## `superwall promote`
319
345
 
@@ -369,12 +395,17 @@ than listing none.
369
395
  | `No superwall framework found` | `bun add superwall` (or npm) inside the project |
370
396
  | `These N products do not exist on Superwall` | Create them with `superwall products create` (above) — don't just report it — or fix the identifiers in `config.ts` |
371
397
  | `Superwall for Agents is in private beta and isn't enabled for this app yet` | Enabled per app on Superwall's side; contact support@superwall.com. Nothing in the CLI can set it |
372
- | `Multiple projects found. Pass --project <id>.` | Add `--project <id>` (and usually `--app <id>`) to the resource command |
398
+ | `You can open N projects - pass --app <id\|dashboard link> or --project <id>` | Add `--app <id\|dashboard link>` to the resource command |
399
+ | `App <id> already has a paywall … that superwall.lock doesn't bind` | Ask the user whether it's this project's; if so add the printed line under `paywalls`, if not rename the directory |
373
400
  | Diagnostics block the push | The message names each stray file and where it belongs |
374
401
  | Rename ambiguity in CI | Add the printed `--rename old=new` |
375
402
  | `x doesn't say which platforms it's for` | The project pushes to several platforms — add `platforms: [...]` to that `config.ts` |
376
- | `Several iOS apps in your account` / `no Web app to bind` | Run push interactively once, add `"web": "<app id>"` under `apps` in `superwall.lock`, or `superwall apps create --platform web` |
403
+ | `Several iOS apps in your account` / `no Web app to bind` | Run push interactively once, add `"web": "<app id>"` under `apps` in `superwall.lock`, or `superwall apps create --name <name> --platform web` |
377
404
  | `This project has no app for "…"` | `--platform` takes a platform bound in `superwall.lock` (or that app's id); the message lists them |
378
405
  | `paywall x has never been pushed` (promote) | Push first |
379
406
  | `superwall publish requires git` | Install git — the source snapshot is part of every publish |
407
+ | `… version N has no source yet` (promote) | Run `superwall push` to finish that version's source, then promote |
408
+ | `Someone else published changes to …` | Pull their commits, push again; `--overwrite-source` only on the user's say-so |
409
+ | `The source repo differs from this project in …` | Pull the latest `superwall.lock`, push again; `--overwrite-source` only on the user's say-so |
410
+ | `The source in … is N MB, over the 250 MB limit` | Gitignore what doesn't belong in the source, push again |
380
411
  | Not signed in | `superwall login`, or `SUPERWALL_API_KEY` in CI |
@@ -44,11 +44,12 @@ never arithmetic), and a designed unpriced state.
44
44
  | --- | --- |
45
45
  | `multi-page` | `router.push/back`, the route stack, chrome in `layout.tsx` that reads router state (`canGoBack()`, `depth + 1`) |
46
46
  | `transitions` | All four built-ins plus a custom `zoom` — proof a transition is just CSS on two attributes |
47
- | `onboarding-quiz` | Answers decide where you land; the router carries no state (plain module outside React) |
47
+ | `onboarding-quiz` | Every answer a typed user attribute (`useUserAttribute`), one `next` for the buttons and `entry`, so a branching quiz closed halfway resumes on its branch at the first unanswered question (`replayStack`, [onboarding-state.md](onboarding-state.md)) |
48
48
 
49
49
  `onboarding-quiz`'s terminal route defends every read — a replayed route
50
- never crashes on a missing answer. Its step labels are hardcoded per route
51
- because a branching flow's depth is not its step number.
50
+ never crashes on a missing answer. Its step labels come from walking `next`
51
+ over the user's branch, because a branching flow's depth is not its step
52
+ number.
52
53
 
53
54
  ## Purchases
54
55
 
@@ -55,7 +55,9 @@ Six consequences, each the answer to a common bug:
55
55
  and the home indicator and rests clear of them; nothing you render
56
56
  sits under a bar at rest unless you put it there. The moment you add
57
57
  `env()` or `--sw-inset-*` to a page or a layout, that edge is padded
58
- twice.
58
+ twice. The insets are padding, never a black bar: `--sw-background`
59
+ still paints every edge of the screen, under the status bar and around
60
+ the camera, and only content is inset.
59
61
  4. **Sticky honours the scroll container's padding.** `position: sticky;
60
62
  bottom: 0` in a page sticks at the inset, above the home indicator,
61
63
  while the content scrolls under it to the screen edge. `top: 0` sticks
@@ -162,6 +164,7 @@ the attributes the framework stamps on `<html>`:
162
164
  | ios · none (home button) · fullscreen | 20 | 0 | 0 |
163
165
  | ios · phone, cutout unknown · fullscreen | 59 | 34 | 0 |
164
166
  | ios · island/notch · landscape | 0 | 21 | 59/44 both sides |
167
+ | ios · strip (iPhone Duo) · any | 0 | 0 | 0 — `env()` only, see below |
165
168
  | ios · tablet · fullscreen | 24 | 20 | 0 |
166
169
  | ios · phone · modal or drawer | 0 (sheet starts below the bar) | 34 (island/notch), 0 (home button) | 0 |
167
170
  | ios · tablet · modal or drawer | 0 | 0 (the sheet floats) | 0 |
@@ -170,13 +173,32 @@ the attributes the framework stamps on `<html>`:
170
173
  | any · popup | 0 | 0 | 0 (the SDK insets it) |
171
174
  | web | 0 | 0 | 0 (the browser owns its chrome) |
172
175
 
173
- The "cutout unknown" row is what a **simulator** gets: it reports its host
174
- architecture (`arm64`) as the device model instead of an `iPhone17,1`, so
175
- the cutout cannot be derived and a modern phone is assumed. A real device
176
- reports its model and lands on the exact row. This is why a paywall can
177
- look right in the studio, which sets the attributes from the preset, and
178
- sit under the island in the simulator — if you see that, check
179
- `document.documentElement.dataset.swCutout` first.
176
+ A **simulator** reports its host architecture (`arm64`) as `deviceModel`,
177
+ not an `iPhone17,1`. SDKs that know it also report the simulated phone as
178
+ `device.simulatorModel`, and the framework reads that first everywhere it
179
+ needs the model (`data-sw-cutout`, `data-sw-idiom`, `useDevice().cutout`,
180
+ the checkout sheet), so the simulator lands on the phone's own row. An
181
+ older SDK sends no `simulatorModel`: the cutout can't be derived and the
182
+ "cutout unknown" row assumes a modern phone. That is why a paywall can look
183
+ right in the studio, which sets the attributes from the preset, and sit
184
+ under the island in the simulator — if you see that, check
185
+ `document.documentElement.dataset.swCutout` first. Branching on the model
186
+ yourself: `device.simulatorModel || device.deviceModel`.
187
+
188
+ **iPhone Duo** (`iPhone19,4`) is `data-sw-cutout="strip"`, and
189
+ `useDevice().cutout` is `"strip"`. Its camera strip sits on the right when
190
+ the phone is closed or in landscape and on top when it is open in portrait,
191
+ and a host app built with an older iOS SDK runs beside the strip rather
192
+ than under it, so no floor is right: only `env()` knows the inset. Nothing
193
+ changes for you: lay out with `--sw-safe-area-inset-*` and the defaults,
194
+ and the paywall follows the strip. Use `cutout` only for a design choice
195
+ the insets can't make.
196
+
197
+ **Insets the host reports.** A host can send the safe area itself as
198
+ `device.safeAreaInsets` (`{ top, right, bottom, left }`); the framework
199
+ writes those as the `--sw-safe-area-floor-*`, so they stand in where
200
+ `env()` reads 0. The studio's iPhone Duo (Closed) and (Open) presets do
201
+ this with the insets measured in Apple's Duo simulator.
180
202
 
181
203
  `push` and `noAnimation` are fullscreen. The attributes come from the
182
204
  device the host reports and are absent, never guessed, until the host's
@@ -185,6 +207,35 @@ there moves the insets. The value on an actual iPhone is `env()`, so a
185
207
  16 Pro shows 62 on device and 59 in the studio — that 3px is why chrome
186
208
  sits at inset *plus* spacing.
187
209
 
210
+ ### iPhone Duo in practice
211
+
212
+ Measured insets, by posture:
213
+
214
+ | State | Viewport | Safe area T / R / B / L |
215
+ | --- | --- | --- |
216
+ | Closed (outer screen), portrait or landscape | 466×678 / 678×466 | 0 / 84 / 34 / 0 |
217
+ | Open (inner screen), landscape | 951×669 | 0 / 84 / 34 / 0 |
218
+ | Open (inner screen), portrait | 669×951 | 82 / 0 / 34 / 0 |
219
+
220
+ Folding the phone doesn't change the safe area.
221
+
222
+ What this means for a paywall:
223
+
224
+ - **The close button.** Most paywalls put it top-right, which is exactly
225
+ where the strip is when the phone is closed. Inside the inset root it is
226
+ already clear. Over a bleed, inset it from **both** edges:
227
+ `top: calc(var(--sw-safe-area-inset-top) + 8px); right: calc(var(--sw-safe-area-inset-right) + 16px)`.
228
+ Never `right: 16px` alone over a bleed.
229
+ - **Never assume left equals right.** The insets are asymmetric. Write each
230
+ edge with its own variable, never `padding: 0 var(--sw-safe-area-inset-right)`.
231
+ - **The fold.** In book posture (open, portrait, folded) a 40px hinge band
232
+ runs across the inner screen at y 456–496; in tabletop (open, landscape,
233
+ folded) it runs down it at x 456–496. Web pages cannot detect whether the
234
+ phone is folded, so keep the primary CTA and the close button out of that
235
+ band on the inner screen (`min-width: 600px` on an iPhone).
236
+ - Detect it with `useDevice().cutout === "strip"` only for a design choice
237
+ the insets cannot make; layout itself needs nothing.
238
+
188
239
  ## Recipes
189
240
 
190
241
  **Close button** (`layout.tsx`):
@@ -193,6 +244,9 @@ sits at inset *plus* spacing.
193
244
  .close { position: absolute; top: 4px; right: 16px; }
194
245
  ```
195
246
 
247
+ The root is already inset, so this clears the island, the notch and the
248
+ iPhone Duo's camera strip without any variable.
249
+
196
250
  **Pinned CTA that content scrolls under** (last child of the page):
197
251
 
198
252
  ```css
@@ -229,7 +283,8 @@ insets: { top: "none" }
229
283
  ```
230
284
 
231
285
  ```css
232
- .close { position: absolute; top: calc(var(--sw-safe-area-inset-top) + 8px); right: 16px; }
286
+ .close { position: absolute; top: calc(var(--sw-safe-area-inset-top) + 8px);
287
+ right: calc(var(--sw-safe-area-inset-right) + 16px); }
233
288
  .hero::after { /* scrim so the bar's clock stays legible in both schemes */ }
234
289
  ```
235
290
 
@@ -65,7 +65,7 @@ is whichever slot the selection state points at.
65
65
  | `navigate-page` (`next` / `back`) | `useRouter().push("<next route>")` / `router.back()` |
66
66
  | `set-product-index` | set your selection state |
67
67
  | `set-state` | set the matching React state |
68
- | `set-attribute` | `useActions().setUserAttributes({ … })` |
68
+ | `set-attribute` | the setter of `useUserAttribute(key, parser)`, one hook per attribute (`useActions().setUserAttributes` is deprecated) |
69
69
  | `custom-placement` | `useActions().customPlacement(name, params)` |
70
70
  | `custom-in-app` | `useActions().requestCallback(...)` (docs: `actions`) |
71
71
  | `request-permission` | `useActions().requestPermission(type)`; `onGranted`/`onDenied` become the resolved status |