@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.
- package/README.md +192 -52
- package/dist/{setup-Bxj22rYi.js → apple-CSzNTGHM.js} +82 -76
- package/dist/auth.d.ts +4 -19
- package/dist/auth.js +4 -2
- package/dist/{actions-B7ym3oVS.js → billing-C3Q8DBU2.js} +98 -28
- package/dist/{bind-YrJvuRF9.js → bind-BumHTi9O.js} +38 -33
- package/dist/{build-DLoCW5Ri.js → build-Bpviiclc.js} +20 -26
- package/dist/client-BL0f_yGf.js +176 -0
- package/dist/{asc-Bf7zBbyS.js → client-BZ1UbpXz.js} +16 -15
- package/dist/config-BO1Y87kV.js +105 -0
- package/dist/create-BSfvpWoD.js +19 -0
- package/dist/{create-pkANt1Gs.js → create-BUcVG4Ab.js} +195 -169
- package/dist/{notification-url-DuKF2659.js → create-CfK3PeKA.js} +235 -539
- package/dist/doctor-BWqIYcMn.js +83 -0
- package/dist/{drivers-Qx9LxmRN.js → drivers-CPhdPkW5.js} +185 -172
- package/dist/entry.d.ts +0 -5
- package/dist/entry.js +28072 -1134
- package/dist/environment-eBXjELoN.js +58 -0
- package/dist/{existing-AVEfZu2A.js → existing-BltvQiX5.js} +12 -6
- package/dist/held-CPve03KJ.js +16 -0
- package/dist/held-DgnTFMl3.js +1112 -0
- package/dist/input-vi0bou04.js +42 -0
- package/dist/{integrate-brmhPG-S.js → integrate-BRsqoe01.js} +277 -254
- package/dist/log-NVhVe_oe.js +62 -0
- package/dist/login-BCEH5q0U.js +53 -0
- package/dist/login-BPOONe7n.js +16 -0
- package/dist/{login-Do4wFuLv.js → login-BbTIrCFT.js} +118 -55
- package/dist/lookup-rr1AkCJA.js +71 -0
- package/dist/migrate-C9X2Vz81.js +274 -0
- package/dist/notification-url-CV86qiKP.js +100 -0
- package/dist/{open-studio-DOw-6ydc.js → open-CcpXotHG.js} +34 -43
- package/dist/org-BQQDo7wm.js +35 -0
- package/dist/output-Ggzq5_-t.js +122 -0
- package/dist/paths-CRlU72cq.js +29 -0
- package/dist/playbook-DVMXN7fh.js +53 -0
- package/dist/{asc-products-9JXtDxI4.js → products-DH_fK9tY.js} +6 -6
- package/dist/promote-Da8xctzy.js +91 -0
- package/dist/push-BV-grvQg.js +22 -0
- package/dist/push-D6R9icWN.js +495 -0
- package/dist/registry-BYVD-_h6.js +10385 -0
- package/dist/{reports-CfJqoava.js → reports-D_qbl7_u.js} +7 -6
- package/dist/{resources-Bf9O1JNM.js → resources-DLON3-61.js} +162 -55
- package/dist/{run-DsVZ5snL.js → run-Co-BwhOg.js} +16 -22
- package/dist/scan-B88OlWOt.js +4 -0
- package/dist/{scan-zKsddO72.js → scan-CKuk-_6W.js} +48 -37
- package/dist/scope-DV22_Ufm.js +198 -0
- package/dist/screenshot-file-tVBfUEIi.js +16 -0
- package/dist/{selection-CxZoX4NT.js → selection-C2_KbLuo.js} +100 -51
- package/dist/server-C4f6ccUr.js +22 -0
- package/dist/{dev-DmB3XqaJ.js → server-D0d2oP-5.js} +86 -94
- package/dist/session-B-Uz0cQ7.js +40 -0
- package/dist/session-BuvArt1j.js +6 -0
- package/dist/session-C4rbE3VS.js +796 -0
- package/dist/skills/animate-onboarding/SKILL.md +467 -0
- package/dist/skills/animate-onboarding/references/engine.md +494 -0
- package/dist/skills/animate-onboarding/references/framework/Question.tsx +71 -0
- package/dist/skills/animate-onboarding/references/framework/README.md +40 -0
- package/dist/skills/animate-onboarding/references/framework/answers.ts +19 -0
- package/dist/skills/animate-onboarding/references/framework/flow.ts +80 -0
- package/dist/skills/animate-onboarding/references/framework/handoffs.ts +869 -0
- package/dist/skills/animate-onboarding/references/framework/layout.tsx +113 -0
- package/dist/skills/animate-onboarding/references/framework/motion.css +559 -0
- package/dist/skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
- package/dist/skills/animate-onboarding/references/handoffs.md +375 -0
- package/dist/skills/animate-onboarding/references/imageReady.ts +92 -0
- package/dist/skills/animate-onboarding/references/morphFrame.ts +356 -0
- package/dist/skills/animate-onboarding/references/performance.md +41 -0
- package/dist/skills/animate-onboarding/references/web-runtime/README.md +17 -0
- package/dist/skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
- package/dist/skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
- package/dist/skills/index.json +37 -0
- package/dist/skills/mobile-design/SKILL.md +447 -0
- package/dist/skills/mobile-design/references/responsive.md +162 -0
- package/dist/skills/onboarding-questions/SKILL.md +231 -0
- package/dist/skills/onboarding-questions/references/arpu-questions.md +139 -0
- package/dist/skills/onboarding-questions/references/craft.md +142 -0
- package/dist/skills/onboarding-questions/references/example-reflective.md +117 -0
- package/dist/skills/superwall/SKILL.md +82 -9
- package/dist/skills/superwall/references/api.md +153 -37
- package/dist/skills/superwall/references/apple-setup.md +316 -0
- package/dist/skills/superwall/references/asc.md +74 -38
- package/dist/skills/superwall/references/data-analytics.md +55 -21
- package/dist/skills/superwall/workflows/dashboard/playbook.md +3 -3
- package/dist/skills/superwall/workflows/dashboard/setup.md +8 -8
- package/dist/skills/superwall/workflows/migrate/adapty.md +6 -6
- package/dist/skills/superwall/workflows/migrate/playbook.md +4 -4
- package/dist/skills/superwall/workflows/migrate/qonversion.md +5 -5
- package/dist/skills/superwall/workflows/migrate/revenuecat.md +6 -6
- package/dist/skills/superwall/workflows/placements/android.md +2 -2
- package/dist/skills/superwall/workflows/placements/expo.md +2 -2
- package/dist/skills/superwall/workflows/placements/flutter.md +2 -2
- package/dist/skills/superwall/workflows/placements/ios.md +2 -2
- package/dist/skills/superwall/workflows/placements/playbook.md +2 -2
- package/dist/skills/superwall/workflows/placements/react-native.md +2 -2
- package/dist/skills/superwall/workflows/placements/strategy.md +2 -2
- package/dist/skills/superwall/workflows/review/playbook.md +1 -1
- package/dist/skills/superwall-editor/SKILL.md +61 -0
- package/dist/skills/superwall-editor/references/cli.md +135 -0
- package/dist/skills/superwall-editor/references/design.md +51 -0
- package/dist/skills/superwall-editor/references/native-elements.md +171 -0
- package/dist/skills/superwall-editor/references/workflow.md +65 -0
- package/dist/skills/superwall-editor/scripts/sw-editor.sh +662 -0
- package/dist/skills/superwall-framework/SKILL.md +85 -31
- package/dist/skills/superwall-framework/references/cli.md +58 -27
- package/dist/skills/superwall-framework/references/examples.md +4 -3
- package/dist/skills/superwall-framework/references/layout.md +64 -9
- package/dist/skills/superwall-framework/references/migrate-from-editor.md +1 -1
- package/dist/skills/superwall-framework/references/onboarding-state.md +245 -0
- package/dist/skills/wwdc/SKILL.md +22 -0
- package/dist/skills/wwdc/references/docs.md +52 -0
- package/dist/skills/wwdc/scripts/wwdc.sh +266 -0
- package/dist/skills-CLGJuMnF.js +14 -0
- package/dist/{skills-DPzlnfCK.js → skills-CZcpnEnG.js} +100 -122
- package/dist/{spawn-DSoTXy_j.js → spawn-DmmmHIP-.js} +14 -12
- package/dist/spinner-C2U6QBJ9.js +294 -0
- package/dist/storage-6h9vyiAz.js +31 -0
- package/dist/storage-CerJ5KLP.d.ts +16 -0
- package/dist/storekit-CK9JmM2D.js +16 -0
- package/dist/storekit-CinJra3V.js +47 -0
- package/dist/telemetry-DKyDhURo.js +56 -0
- package/dist/theme-DUsCh-Vd.js +25 -0
- package/dist/timing-BVxPrYq3.js +5 -0
- package/dist/{token-C0it-Xh7.js → token-DaxQgQkv.js} +6 -38
- package/dist/tools-skills/animate-onboarding/SKILL.md +467 -0
- package/dist/tools-skills/animate-onboarding/references/engine.md +494 -0
- package/dist/tools-skills/animate-onboarding/references/framework/Question.tsx +71 -0
- package/dist/tools-skills/animate-onboarding/references/framework/README.md +40 -0
- package/dist/tools-skills/animate-onboarding/references/framework/answers.ts +19 -0
- package/dist/tools-skills/animate-onboarding/references/framework/flow.ts +80 -0
- package/dist/tools-skills/animate-onboarding/references/framework/handoffs.ts +869 -0
- package/dist/tools-skills/animate-onboarding/references/framework/layout.tsx +113 -0
- package/dist/tools-skills/animate-onboarding/references/framework/motion.css +559 -0
- package/dist/tools-skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
- package/dist/tools-skills/animate-onboarding/references/handoffs.md +375 -0
- package/dist/tools-skills/animate-onboarding/references/imageReady.ts +92 -0
- package/dist/tools-skills/animate-onboarding/references/morphFrame.ts +356 -0
- package/dist/tools-skills/animate-onboarding/references/performance.md +41 -0
- package/dist/tools-skills/animate-onboarding/references/web-runtime/README.md +17 -0
- package/dist/tools-skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
- package/dist/tools-skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
- package/dist/tools-skills/mobile-design/SKILL.md +447 -0
- package/dist/tools-skills/mobile-design/references/responsive.md +162 -0
- package/dist/tools-skills/onboarding-questions/SKILL.md +231 -0
- package/dist/tools-skills/onboarding-questions/references/arpu-questions.md +139 -0
- package/dist/tools-skills/onboarding-questions/references/craft.md +142 -0
- package/dist/tools-skills/onboarding-questions/references/example-reflective.md +117 -0
- package/dist/tools-skills/superwall/SKILL.md +263 -0
- package/dist/tools-skills/superwall/references/api.md +303 -0
- package/dist/tools-skills/superwall/references/asa.md +166 -0
- package/dist/tools-skills/superwall/references/asc.md +95 -0
- package/dist/tools-skills/superwall/references/dashboard-links.md +57 -0
- package/dist/tools-skills/superwall/references/data-analytics.md +896 -0
- package/dist/tools-skills/superwall/references/docs.md +51 -0
- package/dist/tools-skills/superwall/references/sdk-integration.md +104 -0
- package/dist/tools-skills/superwall/references/sdk-source.md +18 -0
- package/dist/tools-skills/superwall/workflows/dashboard/playbook.md +76 -0
- package/dist/tools-skills/superwall/workflows/dashboard/setup.md +100 -0
- package/dist/tools-skills/superwall/workflows/integrate/android.md +292 -0
- package/dist/tools-skills/superwall/workflows/integrate/expo.md +272 -0
- package/dist/tools-skills/superwall/workflows/integrate/flutter.md +285 -0
- package/dist/tools-skills/superwall/workflows/integrate/ios.md +314 -0
- package/dist/tools-skills/superwall/workflows/integrate/playbook.md +83 -0
- package/dist/tools-skills/superwall/workflows/integrate/react-native.md +246 -0
- package/dist/tools-skills/superwall/workflows/migrate/adapty.md +229 -0
- package/dist/tools-skills/superwall/workflows/migrate/playbook.md +78 -0
- package/dist/tools-skills/superwall/workflows/migrate/qonversion.md +227 -0
- package/dist/tools-skills/superwall/workflows/migrate/revenuecat.md +414 -0
- package/dist/tools-skills/superwall/workflows/placements/android.md +175 -0
- package/dist/tools-skills/superwall/workflows/placements/expo.md +161 -0
- package/dist/tools-skills/superwall/workflows/placements/flutter.md +139 -0
- package/dist/tools-skills/superwall/workflows/placements/ios.md +165 -0
- package/dist/tools-skills/superwall/workflows/placements/playbook.md +69 -0
- package/dist/tools-skills/superwall/workflows/placements/react-native.md +145 -0
- package/dist/tools-skills/superwall/workflows/placements/strategy.md +222 -0
- package/dist/tools-skills/superwall/workflows/review/android.md +120 -0
- package/dist/tools-skills/superwall/workflows/review/expo.md +100 -0
- package/dist/tools-skills/superwall/workflows/review/flutter.md +99 -0
- package/dist/tools-skills/superwall/workflows/review/ios.md +108 -0
- package/dist/tools-skills/superwall/workflows/review/playbook.md +70 -0
- package/dist/tools-skills/superwall/workflows/review/react-native.md +100 -0
- package/dist/tools-skills/superwall-editor/SKILL.md +113 -0
- package/dist/tools-skills/superwall-editor/references/cli.md +135 -0
- package/dist/tools-skills/superwall-editor/references/design.md +51 -0
- package/dist/tools-skills/superwall-editor/references/native-elements.md +171 -0
- package/dist/tools-skills/superwall-editor/references/workflow.md +65 -0
- package/dist/tools-skills/superwall-editor/scripts/sw-editor.sh +662 -0
- package/dist/tools-skills/wwdc/SKILL.md +22 -0
- package/dist/tools-skills/wwdc/references/docs.md +52 -0
- package/dist/tools-skills/wwdc/scripts/wwdc.sh +266 -0
- package/dist/tools.d.ts +96 -0
- package/dist/tools.js +11360 -0
- package/dist/ui-D_qf3Gvw.js +53 -0
- package/dist/upgrade-DPo0a4Es.js +117 -0
- package/dist/upgrade-ffseQDMx.js +7 -0
- package/package.json +10 -5
- package/dist/api-CZzirVMj.js +0 -151
- package/dist/api-output-aJNw7Syy.js +0 -20
- package/dist/app-DH6U8yuI.js +0 -190
- package/dist/asa-C-sQzPPn.js +0 -1194
- package/dist/asc-1ZBJ6DwS.js +0 -778
- package/dist/auth-YRhlV3DE.js +0 -140
- package/dist/billing-CCYHdApx.js +0 -80
- package/dist/bundle-id-CKxl_026.js +0 -121
- package/dist/command-CMIz81Da.js +0 -301
- package/dist/dev-DZy6pOnB.js +0 -22
- package/dist/doctor-H-hf-Yww.js +0 -88
- package/dist/feedback-CKf-rpBW.js +0 -152
- package/dist/hosted-CXe9TrWx.js +0 -32
- package/dist/migrate-C9ERDR6y.js +0 -284
- package/dist/org-sj7uyvp-.js +0 -40
- package/dist/output-C4o2gJ1K.js +0 -146
- package/dist/params-l3CrvRtR.js +0 -51
- package/dist/pipeline-BqzqZhX1.js +0 -977
- package/dist/print-skill-ZojRSybs.js +0 -74
- package/dist/promote-BG8X4Nv_.js +0 -88
- package/dist/publish-sxLh-G4G.js +0 -35
- package/dist/push-bQ6Vxtg8.js +0 -35
- package/dist/query-_FbybaH-.js +0 -53
- package/dist/resource-CGIwSd29.js +0 -323
- package/dist/revenue-provider-ebsRINY8.js +0 -100
- package/dist/scope-BvzD-kO4.js +0 -223
- package/dist/skills-D_R-lEsK.js +0 -64
- package/dist/spinner-TWa0hia6.js +0 -18
- package/dist/storekit-Cj9Cpjcz.js +0 -29
- package/dist/telemetry-DeA1mvnT.js +0 -169
- package/dist/ui-Dy0b-9L8.js +0 -27738
- package/dist/update-B2fWIc4q.js +0 -59
- package/dist/upgrade-BmzkTKrh.js +0 -72
- /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
|
|
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
|
|
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.
|
|
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. **
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
201
|
-
hand — the
|
|
202
|
-
|
|
203
|
-
|
|
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
|
-
|
|
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
|
-
|
|
231
|
-
email on a page must
|
|
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
|
-
|
|
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
|
-
|
|
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,
|
|
242
|
-
modal's zero top, landscape sides) and live
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
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
|
|
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`)
|
|
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
|
-
--
|
|
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
|
|
169
|
-
with "
|
|
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
|
-
|
|
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
|
|
312
|
-
dashboard can show and diff the code each version was
|
|
313
|
-
`-m "why"` records the reason there.
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
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
|
-
| `
|
|
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` |
|
|
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
|
|
51
|
-
because a branching flow's depth is not its step
|
|
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
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
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);
|
|
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 |
|