@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
@@ -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` |
@@ -143,7 +145,8 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
143
145
  4. **Dark mode is the `:root.dark` class the SDK stamps**, not
144
146
  `prefers-color-scheme`.
145
147
  5. **Routes are names on a stack** — no params, no order. Closing the
146
- paywall is `useActions().close()`, not navigation. Cross-route state
148
+ paywall is `useActions().close()`, not navigation. Answers a flow
149
+ collects are user attributes (principle 6); other cross-route UI state
147
150
  lives in `layout.tsx` or a plain module on a native paywall — but **on a
148
151
  web funnel (`checkout` set) every answer, selection and input is
149
152
  `useQueryState`, never `useState`**: an in-app browser hands only the
@@ -162,16 +165,47 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
162
165
  bar) rides on top of the router's transition in a layout-level layer,
163
166
  never instead of it. The `transitions` example and the
164
167
  `animate-onboarding` skill show both halves.
165
- 6. **Links go through `useActions().openUrl`**, never `<a href>` — in a
168
+ 6. **An onboarding remembers every answer, so a user who quits halfway
169
+ resumes where they left off.** Every answer is a user attribute, read and
170
+ written with `useUserAttribute(key, parser)` — `useQueryState`'s API with
171
+ the same parsers, kept by the host SDK across presentations and launches,
172
+ re-rendering at once. Keep the flow in one `next(route, user)` function:
173
+ the buttons push what it returns, and `app/layout.tsx` exports `entry`,
174
+ which replays it with `replayStack` (every answered page, then the first
175
+ unanswered one, down the branch the user actually took). `entry` runs
176
+ once with the host's attributes already in, so that page is the first
177
+ thing that paints. Never keep answers only in React state, a module or
178
+ `layout.tsx` (they die with the paywall), and never store the step or
179
+ page index: store the answers. Keys are stable snake_case meant to be
180
+ queried (`onboarding_goal`), values are enum ids read through
181
+ `parseAsStringEnum`, so an unknown or garbage value reads as `null`
182
+ (unanswered). Read
183
+ [references/onboarding-state.md](references/onboarding-state.md) before
184
+ building any multi-page question flow.
185
+
186
+ ```tsx
187
+ const goals = parseAsStringEnum(["lose", "build", "endure"]);
188
+ const [goal, setGoal] = useUserAttribute("onboarding_goal", goals); // Goal | null
189
+ const choose = (value: Goal) => {
190
+ haptics.selection();
191
+ setGoal(value); // persisted by the host SDK
192
+ const to = next("goal", { ...user, onboarding_goal: value });
193
+ if (to) router.push(to);
194
+ };
195
+ // app/layout.tsx: the stack to open on, replayed once from the attributes
196
+ export const entry: Entry = ({ user }) =>
197
+ replayStack("index", (route) => next(route, user), (route) => answered(route, user));
198
+ ```
199
+ 7. **Links go through `useActions().openUrl`**, never `<a href>` — in a
166
200
  webview an anchor does nothing or navigates the paywall away.
167
- 7. **Haptics on every meaningful tap** (`light` navigate, `selection`
201
+ 8. **Haptics on every meaningful tap** (`light` navigate, `selection`
168
202
  choose, `success` purchase) — iOS fires nothing of its own. Icon
169
203
  buttons carry `aria-label`; tap targets ≥ 44px. Every control answers
170
204
  the press itself (`:active`, ~0.96 scale), every `:hover` sits inside
171
205
  `@media (hover: hover) and (pointer: fine)` (a webview keeps a fake
172
206
  hover after a tap), and inputs are 16px or larger (iOS zooms the page
173
207
  on anything smaller).
174
- 8. **Motion is `transform` and `opacity`, nothing else, and UI feedback is
208
+ 9. **Motion is `transform` and `opacity`, nothing else, and UI feedback is
175
209
  under 300ms.** This is the rule every first paywall breaks: a plan card
176
210
  whose selection animates `border-color`, `background` or `box-shadow`,
177
211
  and a 450ms staggered entrance. Transitions name their properties on a
@@ -191,16 +225,18 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
191
225
  ```
192
226
 
193
227
  The tokens, durations and the audit are in the `mobile-design` skill.
194
- 9. **`await restore()`** — it resolves `{ status: "restored" }` or
228
+ 10. **`await restore()`** — it resolves `{ status: "restored" }` or
195
229
  `{ status: "failed" }`. "Nothing to restore" is not distinguishable
196
230
  from a store error: the SDK writes that explanation to its own logs,
197
231
  never over the protocol, so write copy covering both. The lifecycle
198
232
  also lands on `useSuperwallSnapshot().restore` (iOS sends all three of
199
233
  `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
234
+ 11. **Commit `superwall.lock` and `superwall.d.ts`.** Never edit either by
235
+ hand — the exceptions are adding an app under `apps` when CI can't
236
+ prompt, and the binding line a push prints for a paywall the user
237
+ confirms is theirs. The lock also records the source commit each app was
238
+ last synced to, the base the next push merges from.
239
+ 12. **One project, several platforms.** `superwall.lock` binds one
204
240
  Superwall app per platform under `apps` (`ios`, `android`, `web`), and
205
241
  a paywall lists the platforms it ships
206
242
  to with `platforms: [...]` in `config.ts` (typed) — optional on one
@@ -223,19 +259,19 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
223
259
  hosts it as the web paywall app hosts editor paywalls: the SDK prices
224
260
  the Stripe products, reports the events and finishes the checkout, so
225
261
  `register()` resolves `purchased`, with no redemption step.
226
- 12. **Shipping includes the dashboard.** A push that fails on missing
262
+ 13. **Shipping includes the dashboard.** A push that fails on missing
227
263
  products is not a blocker to report — create them with
228
264
  `superwall products create` ([references/cli.md](references/cli.md)).
229
265
  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
266
+ 14. **A captured email must reach checkout.** A funnel that asks for the
267
+ email on a page must save it as the `email` user attribute
268
+ (`useUserAttribute("email")`'s setter) the moment it has it — that is what puts it on the Stripe session as
233
269
  `customer_email` (shown, not editable) and re-warms the prefetched
234
270
  session. Page state alone never reaches checkout. Same for a
235
271
  `stripe_customer_id`. Fetch `web-checkout` → "The shopper's email".
236
- 14. **Build the design reference 1:1.** Add nothing it doesn't show;
272
+ 15. **Build the design reference 1:1.** Add nothing it doesn't show;
237
273
  effects (shadows, gradients) are design decisions, not defaults.
238
- 15. **The paywall is inset by default; never write `env()` and never
274
+ 16. **The paywall is inset by default; never write `env()` and never
239
275
  `position: fixed`.** The framework's root box pads the whole paywall
240
276
  by the safe area, resolved per platform, screen and presentation
241
277
  (iPhone island/notch/home button, iPad, Android's status bar, a
@@ -249,18 +285,18 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
249
285
  bleed, and only chrome over a bleed reads `--sw-safe-area-inset-*`.
250
286
  When something sits under a bar, run the debugging order in
251
287
  [references/layout.md](references/layout.md) before touching CSS.
252
- 16. **A non-white background goes in `config.ts`, not only in CSS.**
288
+ 17. **A non-white background goes in `config.ts`, not only in CSS.**
253
289
  `--sw-background` paints the routes; `background` in config is what
254
290
  the framework writes on `<html>`, and `<html>` is what shows when an
255
291
  iOS scroll rubber-bands past the end of the content. Set only the CSS
256
292
  variable and every bounce flashes white — worst on a dark paywall.
257
293
  Set both, to the same colors, in the same change.
258
- 17. **A paywall is finished on the smallest and the largest screen it
294
+ 18. **A paywall is finished on the smallest and the largest screen it
259
295
  ships to**, not on the default frame: iPhone SE at 320–375 wide and
260
296
  667 tall, an island phone, a Pixel, an iPad, landscape where the app
261
297
  allows it, and the configured presentation style
262
298
  (`responsive.md` in the `mobile-design` skill).
263
- 18. **Every user-facing string is a message, from the first commit, even
299
+ 19. **Every user-facing string is a message, from the first commit, even
264
300
  in one language.** Copy lives in `messages/en.ts` (shared, or per
265
301
  paywall) and reaches the page through `useTranslation().t("key")`,
266
302
  `aria-label`s and button labels included; never a literal in JSX. A
@@ -268,7 +304,7 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
268
304
  never in a catalog: interpolate them (`"Subscribe · {price}"`) and
269
305
  guard on the value with a bare-key fallback. The scaffold starts this
270
306
  way; keep it that way (docs: `localization`).
271
- 19. **Any host the surface calls must be named in `allowedHosts`.** A
307
+ 20. **Any host the surface calls must be named in `allowedHosts`.** A
272
308
  published paywall is served under a Content-Security-Policy that
273
309
  permits Superwall and Stripe and nothing else, so a `fetch` to a
274
310
  customer's own API — saving quiz answers, capturing a lead, a custom
@@ -285,6 +321,14 @@ Docs beyond the framework (dashboard, SDKs, web checkout setup):
285
321
  all, so a local API works there unnamed and a missing host is only ever
286
322
  caught after deploy unless you write it up front (docs: `config`,
287
323
  `troubleshooting`).
324
+ 21. **Never require `localStorage` or `sessionStorage`.** In the Android
325
+ SDK's WebView both are `null`. They aren't `undefined`, so a `typeof`
326
+ guard passes and the call throws. An unguarded read in a render or an
327
+ effect unmounts the whole paywall and leaves a blank screen the user
328
+ can't leave. Keep state that spans pages in React (it lives for the
329
+ whole presentation), and state that must outlast it in a user
330
+ attribute (`useUserAttribute`), which the host persists. Use storage only for something optional, inside a
331
+ `try`/`catch` that treats a failure as unset (docs: `troubleshooting`).
288
332
 
289
333
  ## Working loop
290
334
 
@@ -303,12 +347,11 @@ on every preset, both schemes. When a layout bug appears, the numbered
303
347
  debugging order in [references/layout.md](references/layout.md) finds it
304
348
  from the devtools console in under a minute; don't guess at CSS first.
305
349
 
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.
350
+ Before promising a push will work, check that every product named in a
351
+ `config.ts` exists on the dashboard. A push merges onto teammates' source
352
+ and stops naming the files when it can't; `--overwrite-source` discards
353
+ their work, so pass it only when the user says to
354
+ ([references/cli.md](references/cli.md)).
312
355
 
313
356
  ## Report what's broken
314
357
 
@@ -319,6 +362,13 @@ on, however small. Write it with every ID needed to reproduce it, tell the
319
362
  user in one line, send on their yes (or straight away if they've said you
320
363
  may). Strip secrets and customer data.
321
364
 
365
+ First make sure it still happens on the latest release, since it may already be
366
+ fixed: compare `superwall --version` and the project's `superwall` dependency
367
+ with `npm view superwall version`. If either is older, run `superwall upgrade`
368
+ and `bun add superwall@latest` (or npm) in the project, then repeat what
369
+ failed. Fixed → tell the user which version fixed it and send nothing. Still
370
+ broken → report it with the versions you reproduced it on.
371
+
322
372
  ```bash
323
373
  superwall feedback "Ran X; expected Y; got Z. Steps: …" --title "..." --kind bug \
324
374
  --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
 
@@ -368,13 +394,17 @@ than listing none.
368
394
  | `…package.json is named "superwall"` | Rename the package — that name shadows the framework |
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
- | `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 |
397
+ | `You can open N projects - pass --app <id\|dashboard link> or --project <id>` | Add `--app <id\|dashboard link>` to the resource command |
398
+ | `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
399
  | Diagnostics block the push | The message names each stray file and where it belongs |
374
400
  | Rename ambiguity in CI | Add the printed `--rename old=new` |
375
401
  | `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` |
402
+ | `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
403
  | `This project has no app for "…"` | `--platform` takes a platform bound in `superwall.lock` (or that app's id); the message lists them |
378
404
  | `paywall x has never been pushed` (promote) | Push first |
379
405
  | `superwall publish requires git` | Install git — the source snapshot is part of every publish |
406
+ | `… version N has no source yet` (promote) | Run `superwall push` to finish that version's source, then promote |
407
+ | `Someone else published changes to …` | Pull their commits, push again; `--overwrite-source` only on the user's say-so |
408
+ | `The source repo differs from this project in …` | Pull the latest `superwall.lock`, push again; `--overwrite-source` only on the user's say-so |
409
+ | `The source in … is N MB, over the 250 MB limit` | Gitignore what doesn't belong in the source, push again |
380
410
  | 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
@@ -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 |