@superwall/cli 1.4.0 → 1.6.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 (103) hide show
  1. package/README.md +21 -5
  2. package/dist/{actions-EfP8phmb.js → actions-Dt35nIi8.js} +3 -2
  3. package/dist/{api-CEwXCCoC.js → api-BOR-uXZe.js} +9 -9
  4. package/dist/{app-D8mEVlQo.js → app-BU27SLPX.js} +9 -9
  5. package/dist/{asa-BFWehnTA.js → asa-2ykGnjaV.js} +11 -11
  6. package/dist/{asc-DJqQmtmR.js → asc-r3xmFT0L.js} +14 -14
  7. package/dist/{auth-CT2DWX8r.js → auth-BWZfguI8.js} +9 -9
  8. package/dist/auth.js +2 -2
  9. package/dist/{billing-BzEnVPD2.js → billing-BsQgXXYh.js} +1 -1
  10. package/dist/{bind-BZxVyt9P.js → bind-BSTAinn6.js} +5 -4
  11. package/dist/{command-DP96_gmP.js → command-DMoMn7uc.js} +39 -16
  12. package/dist/{create-Q8TqqjZt.js → create-CSo6XjSm.js} +118 -91
  13. package/dist/dev-B0MF6z3L.js +21 -0
  14. package/dist/{dev-DlCcwFu5.js → dev-CuXa3J4Z.js} +29 -24
  15. package/dist/{doctor-CJsjHpCZ.js → doctor-DXJaDqsx.js} +10 -10
  16. package/dist/{drivers-UT36AnOw.js → drivers-Cr252DOJ.js} +3 -3
  17. package/dist/entry.js +84 -50
  18. package/dist/{existing-Cak1WxWB.js → existing-Ckx_g7Be.js} +6 -3
  19. package/dist/{feedback-DDRzoqPx.js → feedback-Dt5yebMS.js} +6 -6
  20. package/dist/{hosted-CEH78QVn.js → hosted-Cjekn8oJ.js} +2 -2
  21. package/dist/{integrate-D8jyhDzk.js → integrate-DVqhvPVq.js} +25 -66
  22. package/dist/{login-kneYhhk0.js → login-Bjj8QvIN.js} +6 -6
  23. package/dist/migrate-qmvOtp3l.js +283 -0
  24. package/dist/open-studio-CpHqjovS.js +1299 -0
  25. package/dist/{org-Cg25bcsj.js → org-CV8c849b.js} +3 -3
  26. package/dist/{output-csAtR6kJ.js → output-CiELrN8w.js} +15 -2
  27. package/dist/{pipeline-DAeI9tHs.js → pipeline-DSCHL9KA.js} +482 -9
  28. package/dist/{print-skill-BHVPP9cX.js → print-skill-CaHRJ8xW.js} +7 -7
  29. package/dist/{promote-Boek5K2d.js → promote-UMTh8Q33.js} +17 -18
  30. package/dist/publish-DWX8S9yZ.js +34 -0
  31. package/dist/push-Dox4_5Dq.js +34 -0
  32. package/dist/{query-B8G6T8Ba.js → query-CnSsDZ7Q.js} +10 -10
  33. package/dist/reports-C0xHCLnt.js +27 -0
  34. package/dist/{resource-DjsWVka-.js → resource-5bgyyL9B.js} +15 -15
  35. package/dist/{resources-s64mBHaC.js → resources-Bf9O1JNM.js} +28 -2
  36. package/dist/{run-BtcQJCP8.js → run-BVeZWbXx.js} +39 -22
  37. package/dist/{scan-DJixvuHn.js → scan-CAObNRgc.js} +44 -4
  38. package/dist/skills/superwall/SKILL.md +146 -0
  39. package/dist/skills/superwall/references/api.md +275 -0
  40. package/dist/skills/superwall/references/asa.md +160 -0
  41. package/dist/skills/superwall/references/asc.md +96 -0
  42. package/dist/skills/superwall/references/dashboard-links.md +57 -0
  43. package/dist/skills/superwall/references/data-analytics.md +893 -0
  44. package/dist/skills/superwall/references/docs.md +51 -0
  45. package/dist/skills/superwall/references/sdk-integration.md +105 -0
  46. package/dist/skills/superwall/references/sdk-source.md +18 -0
  47. package/{skills/superwall-dashboard/SKILL.md → dist/skills/superwall/workflows/dashboard/playbook.md} +3 -9
  48. package/{skills/superwall-dashboard/references → dist/skills/superwall/workflows/dashboard}/setup.md +1 -3
  49. package/dist/skills/superwall/workflows/integrate/android.md +292 -0
  50. package/{skills/superwall-integrate/SKILL.md → dist/skills/superwall/workflows/integrate/playbook.md} +16 -11
  51. package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/adapty.md +4 -4
  52. package/{skills/superwall-migrate/SKILL.md → dist/skills/superwall/workflows/migrate/playbook.md} +4 -10
  53. package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/qonversion.md +4 -4
  54. package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/revenuecat.md +4 -4
  55. package/dist/skills/superwall/workflows/placements/android.md +175 -0
  56. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/expo.md +1 -1
  57. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/flutter.md +1 -1
  58. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/ios.md +1 -1
  59. package/{skills/superwall-placements/SKILL.md → dist/skills/superwall/workflows/placements/playbook.md} +6 -10
  60. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/react-native.md +2 -2
  61. package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/strategy.md +4 -3
  62. package/dist/skills/superwall/workflows/review/android.md +120 -0
  63. package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/expo.md +1 -1
  64. package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/flutter.md +1 -1
  65. package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/ios.md +1 -1
  66. package/{skills/superwall-review/SKILL.md → dist/skills/superwall/workflows/review/playbook.md} +2 -7
  67. package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/react-native.md +1 -1
  68. package/dist/skills/superwall-framework/SKILL.md +253 -0
  69. package/dist/skills/superwall-framework/references/cli.md +340 -0
  70. package/dist/skills/superwall-framework/references/examples.md +123 -0
  71. package/dist/skills/superwall-framework/references/layout.md +295 -0
  72. package/dist/skills/superwall-framework/references/migrate-from-editor.md +208 -0
  73. package/dist/skills/superwall-framework/references/migrate-from-native.md +193 -0
  74. package/dist/skills/superwall-framework/references/mobile-design.md +371 -0
  75. package/dist/skills/superwall-framework/references/native/android.md +83 -0
  76. package/dist/skills/superwall-framework/references/native/flutter.md +65 -0
  77. package/dist/skills/superwall-framework/references/native/ios.md +77 -0
  78. package/dist/skills/superwall-framework/references/native/react-native.md +67 -0
  79. package/dist/skills/superwall-framework/references/responsive.md +162 -0
  80. package/dist/{skills-CRG1xk0G.js → skills-Cu41i-Az.js} +12 -12
  81. package/dist/{skills-CODut1Hn.js → skills-grTDuHlc.js} +134 -36
  82. package/dist/{spinner-B9dT3DBY.js → spinner-DFctF_Jw.js} +1 -1
  83. package/dist/{telemetry-BtkMdT-5.js → telemetry-BuCbmoux.js} +3 -3
  84. package/dist/{token-hM7V1KMG.js → token-mju3Q-vc.js} +3 -3
  85. package/dist/{ui-Lqt_zFOr.js → ui-4gLyfrgl.js} +76 -46
  86. package/dist/{update-CeylIjx5.js → update-DnGfpCD7.js} +2 -2
  87. package/dist/{upgrade-DRqUfCBT.js → upgrade-PMoj3yqJ.js} +6 -6
  88. package/package.json +8 -7
  89. package/prompts/actions/paywall-migrate.xml +24 -0
  90. package/prompts/actions/screen-migrate.xml +26 -0
  91. package/dist/git-ZwA3Mx8m.js +0 -433
  92. package/dist/migrate-D_x1oyTk.js +0 -114
  93. package/dist/publish-C-zEUnO9.js +0 -35
  94. package/dist/push-DUDQG-EO.js +0 -35
  95. package/skills/README.md +0 -118
  96. /package/dist/{api-output-D9ggXQIr.js → api-output-CEhN-U_N.js} +0 -0
  97. /package/dist/{asc-products-C6MvSy8H.js → asc-products-1e1DoGeL.js} +0 -0
  98. /package/dist/{params-B1zeElGa.js → params-BxgTuCzr.js} +0 -0
  99. /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/expo.md +0 -0
  100. /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/flutter.md +0 -0
  101. /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/ios.md +0 -0
  102. /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/react-native.md +0 -0
  103. /package/dist/{storekit-DPonXSwe.js → storekit-Dlpbq5Wv.js} +0 -0
@@ -0,0 +1,123 @@
1
+ # Examples — the map
2
+
3
+ Every example is a complete, standalone superwall project teaching exactly
4
+ **one idea**. They teach functionality, not design: styling is
5
+ deliberately plain so the mechanism is the thing you read. When a task
6
+ matches one, read that example before writing code.
7
+
8
+ ## Use an example
9
+
10
+ ```bash
11
+ superwall create --example multi-page # scaffold it as a new project
12
+ superwall dev # open it in the studio
13
+ ```
14
+
15
+ All examples are public at
16
+ **https://github.com/superwall/superwall/tree/main/examples** — browse
17
+ them there, or fetch specific files raw:
18
+
19
+ ```bash
20
+ curl -sL https://raw.githubusercontent.com/superwall/superwall/main/examples/multi-page/paywalls/multi-page/app/layout.tsx
21
+ ```
22
+
23
+ Each example's `README.md` explains the idea, and every one is a
24
+ copyable project (`package.json`, `config.ts`, `app/` routes) — copying a
25
+ directory anywhere gives a working `superwall dev`.
26
+
27
+ ## Fundamentals
28
+
29
+ | Example | The one idea | Reach for it when |
30
+ | --- | --- | --- |
31
+ | `minimal` | One route, one product, purchase — a paywall is a React component, not a template | Starting anything |
32
+ | `product-selection` | Selection state is ordinary React — the framework has no "selected plan" concept | Multiple plans, price rows |
33
+
34
+ `minimal` shows the canonical price guard
35
+ (``price ? `Subscribe · ${price}` : "Subscribe"``). `product-selection` shows
36
+ a typed plan union, `haptics.selection()` on choice vs `haptics.light()` on
37
+ CTA, a real `role="radiogroup"`/`role="radio"` with `aria-checked`, one
38
+ product rendering both `price` and `monthlyPrice` (both store-formatted,
39
+ never arithmetic), and a designed unpriced state.
40
+
41
+ ## Navigation
42
+
43
+ | Example | The one idea |
44
+ | --- | --- |
45
+ | `multi-page` | `router.push/back`, the route stack, chrome in `layout.tsx` that reads router state (`canGoBack()`, `depth + 1`) |
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) |
48
+
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.
52
+
53
+ ## Purchases
54
+
55
+ | Example | The one idea |
56
+ | --- | --- |
57
+ | `purchase-states` | The two channels: what your `purchase()` call resolves vs what the SDK reports on its own (restore arrives as `transaction_complete` with no purchase in sight) |
58
+ | `trial-eligibility` | Two paywalls in one, chosen by the store — every string forks and both states read as intentional |
59
+ | `abandonment-offer` | `purchase()` resolving `abandoned` is a signal only this paywall can act on — push a last-chance offer (a second product, not a second design) with a custom `sheet` transition |
60
+ | `trial-reminders` | A local notification declared in config, scheduled by the SDK when the trial starts — the paywall needn't be open when it fires |
61
+ | `web-funnel` | Selling on the web: steps as routes on `shift`, the answer kept in the URL with `useQueryState` (the rule for every web-funnel answer), then `checkout: "sheet"` — `purchase()` unchanged; `prefetch(reference)` on selection so the sheet opens instantly |
62
+
63
+ `purchase-states` is the only example showing the full haptic vocabulary
64
+ (`success()` / `error()` keyed to outcomes). `abandonment-offer` contains
65
+ the deepest CSS lesson in the corpus: the scrim behind its sheet reuses
66
+ `--sw-transition`/`--sw-ease` and drives page-dim and backdrop from one
67
+ `--dim` number (docs: `transitions`).
68
+
69
+ ## The host
70
+
71
+ | Example | The one idea |
72
+ | --- | --- |
73
+ | `personalization` | `useVariables()` — device, user, placement params, and **guarding every read** (`?? "—"` for SDK-guaranteed device fields; `typeof x === "string"` for host-controlled user/params) |
74
+ | `permissions` | `requestPermission` (asks the OS) vs `requestCallback` (asks *your app* — run code, hand something back); both resolve from code the paywall doesn't control, and a denial is an outcome, not an error |
75
+
76
+ ## Look and feel
77
+
78
+ | Example | The one idea |
79
+ | --- | --- |
80
+ | `custom-fonts` | A typeface from a file in your project — relative-path `@font-face`, hosted by content hash; subset to latin (~24 kB vs ~90 kB) |
81
+ | `with-tailwind` | Tailwind v4 with zero framework config — one postcss.config line, `@theme` tokens, and crucially `@custom-variant dark (&:where(.dark, .dark *))` so `dark:` follows the SDK's class, not the media query |
82
+ | `with-motion` | In-page animation gated on `paywall_open` via the snapshot — the preload rule (docs: `lifecycle`) — plus a price count-up bound to `rawPrice`, gated on both `opened` and the value existing |
83
+ | `with-rive` | Interactive vector animation — `.riv` as a hosted asset, the WASM engine bundled and CDN fallback nulled (CSP), real state-machine names, controls as real buttons with aria-labels |
84
+ | `orientation` | `useDevice().orientation` — measured in the page, live on rotation; landscape is a two-column grid reflow, not a shrunken portrait |
85
+
86
+ ## Localization
87
+
88
+ | Example | The one idea |
89
+ | --- | --- |
90
+ | `localization` | Four locales by filename, shared + surface-local catalogs, `{price}` interpolation guarded on the value, no language picker on device |
91
+
92
+ ## Habits every example carries
93
+
94
+ These are the "treat it like a real paywall" conventions — carry them into
95
+ any paywall you author:
96
+
97
+ - **Haptics on every meaningful tap** — `light()` for navigation/CTAs,
98
+ `selection()` for changing a choice, `success()` when a purchase lands.
99
+ iOS fires nothing of its own inside a paywall.
100
+ - **Never a loading state on the buy button** — the store sheet is the
101
+ feedback and the SDK owns it.
102
+ - **Prices from `useProducts()`**, never from the file; product identifiers
103
+ are placeholders to repoint.
104
+ - **Every control reachable** — icon-only buttons carry `aria-label`; tap
105
+ targets ≥ 44px; primary actions full-width at the bottom of the screen.
106
+ - **Links through `useActions().openUrl`**, never `<a href>` — in a webview
107
+ an anchor does nothing or navigates the paywall away from itself.
108
+ - **Light and dark via the `:root.dark` class**, both always checked;
109
+ responsive from 320px to tablet.
110
+ - **No safe-area math and no `position: fixed` anywhere.** The framework
111
+ insets the paywall; the shell is `flex: 1 1 auto`, the close button is
112
+ `position: absolute; top: 4px`, pages use plain padding, the "Built
113
+ with" footer is a flex child of the layout — the skeleton in
114
+ [mobile-design.md](mobile-design.md) and the mechanics in
115
+ [layout.md](layout.md), which every example's `theme.css` (and
116
+ `with-tailwind`'s classes) follows. None sets `insets` in config,
117
+ because none bleeds.
118
+ - **`--sw-background: var(--bg)`** in `:root` on every paywall.
119
+ - **Strings through `messages/` and `t()` from day one.** The
120
+ `localization` example is the reference for the catalog shape and
121
+ guarded interpolation; the older examples still inline their copy
122
+ because each teaches one other idea. A paywall you author starts with
123
+ `messages/en.ts` even in a single language, as the scaffold does.
@@ -0,0 +1,295 @@
1
+ # The layout system — exactly how a paywall is laid out
2
+
3
+ Read this before positioning anything, and again when something sits
4
+ under a status bar, scrolls when it shouldn't, or jumps during a page
5
+ transition. Everything here is what the framework actually renders, so
6
+ it is what to check against, not a convention.
7
+
8
+ ## The DOM the framework renders
9
+
10
+ ```
11
+ html .dark|.light data-sw-platform data-sw-idiom data-sw-cutout data-sw-presentation
12
+ │ style="--sw-inset-top: …" ← only the edges `insets` in config sets
13
+ │ style="background-color: …" ← `background` in config, per scheme. THE ONLY
14
+ │ thing behind a rubber-banding scroll; white
15
+ │ without it, whatever --sw-background says
16
+ └ body
17
+ └ #root
18
+ └ [data-sw-root] ← THE INSET BOX. flex column, min-height: 100dvh,
19
+ │ padding: --sw-inset-top/right/bottom/left,
20
+ │ background: --sw-background
21
+ └ [data-sw-content] ← position: relative; flex column; flex: 1 1 auto.
22
+ │ The containing block for absolute chrome.
23
+ └ <Layout> ← your app/layout.tsx, if any. A flex child.
24
+ └ [data-sw-routes] ← the page stack: position: relative; overflow: hidden;
25
+ │ flex: 1 1 auto; min-height: --sw-routes-height (auto);
26
+ │ margin: the NEGATIVE --sw-page-inset-* — it reaches
27
+ │ back out under the insets, to the screen edges
28
+ └ [data-sw-route] ← ONE PER PAGE. position: absolute; inset: 0;
29
+ │ padding: --sw-page-inset-* (= the insets);
30
+ │ overflow: auto. THE SCROLL CONTAINER — edge to
31
+ │ edge, with the inset as its scroll padding
32
+ └ <Page /> ← your app/<name>.tsx
33
+ ```
34
+
35
+ Six consequences, each the answer to a common bug:
36
+
37
+ 1. **The viewport is never yours.** `[data-sw-root]` is the one element
38
+ sized to the viewport. Anything of yours with `min-height: 100dvh`
39
+ (or `100vh`, `100svh`) is taller than the space inside the insets and
40
+ makes the whole paywall scroll by the inset amount. A layout's shell
41
+ is `flex: 1 1 auto`; a page fills its route with `min-height: 100%`
42
+ (the route is absolutely positioned, so its height is definite).
43
+ 2. **Pages scroll, the document does not.** The scroll container is
44
+ `[data-sw-route]`, not `window`/`body`. `window.scrollTo` and
45
+ `document.documentElement.scrollTop` do nothing; scroll the route
46
+ (`el.closest("[data-sw-route]")`) or use `scrollIntoView`. Each page
47
+ keeps its own scroll position when covered. `scrollEnabled: false` in
48
+ config is applied by the platform stylesheet; do not fake it with
49
+ `overflow: hidden` on `html`/`body`.
50
+ 3. **Insets are applied once, and pages scroll under them.** The root is
51
+ padded by the insets and the page stack reaches back out under them,
52
+ so each page's scroll container runs edge to edge and carries the
53
+ inset as its own padding — the way a native scroll view runs under
54
+ the bars with a content inset. Content scrolls beneath the status bar
55
+ and the home indicator and rests clear of them; nothing you render
56
+ sits under a bar at rest unless you put it there. The moment you add
57
+ `env()` or `--sw-inset-*` to a page or a layout, that edge is padded
58
+ twice.
59
+ 4. **Sticky honours the scroll container's padding.** `position: sticky;
60
+ bottom: 0` in a page sticks at the inset, above the home indicator,
61
+ while the content scrolls under it to the screen edge. `top: 0` sticks
62
+ below the status bar. No inset arithmetic on the sticky element.
63
+ 5. **`[data-sw-content]` is what absolute chrome positions against.**
64
+ Absolute positioning resolves against the nearest positioned ancestor's
65
+ *padding* edge; the framework makes that ancestor the box that starts
66
+ *after* the insets, so `position: absolute; top: 4px` in a layout is
67
+ 4px below the bar with no positioned ancestor of your own.
68
+ 6. **A page is its own positioning world during a transition.** The
69
+ router animates `[data-sw-route]` with `transform` and `filter`, and a
70
+ transformed element becomes the containing block for *fixed*
71
+ descendants too. Fixed chrome inside a page therefore rides along with
72
+ the page while it moves and snaps to the viewport when the animation
73
+ ends. That is why fixed positioning has no place inside a page.
74
+
75
+ ## Positioning: what each value resolves against
76
+
77
+ | You write | It resolves against | Use it for | Never for |
78
+ | --- | --- | --- | --- |
79
+ | `position: absolute` in `layout.tsx` | `[data-sw-content]` — the inset area | close/back buttons, step counters, a pinned footer shared by every page | — |
80
+ | `position: absolute` in a page | the page's own positioned wrapper, or the route's padding box (which **scrolls with the content**) | overlays on a card, badges | pinning anything to the screen |
81
+ | `position: sticky` in a page | the route's scrollport minus the route's padding — the inset area, while the content scrolls under the bars | a pinned CTA that content scrolls under, a header that content scrolls under | — |
82
+ | `position: fixed` anywhere | the viewport, **ignoring the insets** (and the moving page, during a transition) | nothing in a paywall. Chrome portaled to `body` (the checkout sheet does this) is the only case | close buttons, footers, anything inside a page |
83
+ | a flex child of the layout below `[data-sw-routes]` | the layout's column | a footer that pages must not overlap (legal links, "Built with"), with `--sw-page-inset-bottom: 0px` on `:root` so the pages stop at it | — |
84
+
85
+ Two things follow from the fixed row. First, if something is under the
86
+ status bar or the home indicator, it is either `position: fixed`, on an
87
+ edge `insets` turned off, or pulled there with a negative margin: those
88
+ are the only three ways. Second, when a design *does* bleed under the
89
+ bar (`insets: { top: "none" }`), the chrome over the bleed stays
90
+ `position: absolute` in the layout and reads the safe area itself:
91
+ `top: calc(var(--sw-safe-area-inset-top) + 8px)`. Not `env()`, which is
92
+ 0 in previews and on Android. Not `--sw-inset-top`, which is the padding
93
+ you just turned off.
94
+
95
+ ## Insets — the three settings and their precedence
96
+
97
+ | Layer | Set by | What it is |
98
+ | --- | --- | --- |
99
+ | `--sw-inset-*` | `insets` in `config.ts` (written inline on `<html>`), else your `:root` CSS, else the framework default | **The padding on the root.** Default: the safe area. |
100
+ | `--sw-page-inset-*` | the framework (= `--sw-inset-*`); override on `:root` per edge | **How far each page's scroll container reaches back under the insets, and its scroll padding.** Set an edge to `0px` when the layout puts something of its own between the pages and that edge (a footer below them): the pages then stop at it. |
101
+ | `--sw-bleed` / `--sw-page-bleed` | the framework | The four negative insets in `inset:` order. An overlay that must cover the bars writes `position: absolute; inset: var(--sw-bleed)` in a layout, or `var(--sw-page-bleed)` inside a page's positioned wrapper. |
102
+ | `--sw-safe-area-inset-*` | the framework; override on `:root` only to correct it | **The safe area**: `max(env(safe-area-inset-*), floor)`. What chrome over a bleed reads. |
103
+ | `--sw-safe-area-floor-*` | the framework from `data-sw-*`; override on `:root` to teach it a device | The minimum for the host's platform, screen, presentation and orientation. Never shrinks a real `env()`. |
104
+
105
+ Precedence per edge, highest first: config (inline style) → your
106
+ unlayered `:root` rule → the framework's own `:root` defaults (declared before
107
+ your stylesheet, so yours win by order; the floors use `:root:where(…)`). An edge
108
+ config leaves at `"safe-area"` is untouched inline, so CSS can still set
109
+ it; an edge config sets cannot be changed from CSS without `!important`.
110
+ Pick one per edge.
111
+
112
+ ```ts
113
+ insets: "safe-area" // default
114
+ insets: "none" // flush everywhere — the paywall draws the whole screen
115
+ insets: 24 // 24px everywhere (a web-only paywall with a fixed gutter)
116
+ insets: { top: "none" } // a hero under the status bar; other edges stay safe
117
+ insets: { left: "1.25rem", right: "1.25rem" } // any CSS length, per edge
118
+ ```
119
+
120
+ ```css
121
+ :root[data-sw-platform="android"] { --sw-inset-top: 32px; } /* one platform's padding (edge not set in config) */
122
+ :root { --sw-safe-area-floor-top: 62px; } /* a taller floor, env() still live */
123
+ :root { --sw-page-inset-bottom: 0px; } /* the layout owns the bottom: pages stop above its footer */
124
+ ```
125
+
126
+ ### When to turn an edge off — and when not to
127
+
128
+ The default is right for almost every screen: content scrolls under the
129
+ bars and rests clear of them, chrome sits inside them, a sticky CTA sits
130
+ above the home indicator. Turn an edge off (`"none"`) only when something
131
+ must **rest** under the bar, not merely scroll under it:
132
+
133
+ - A hero image or video whose top edge is the screen edge
134
+ (`insets: { top: "none" }`), with a scrim so the clock stays legible
135
+ and the close button reading `--sw-safe-area-inset-top`.
136
+ - Full-screen art or an onboarding animation that fills the display
137
+ (`insets: "none"`).
138
+ - A bottom CTA block with its own edge-to-edge background that should
139
+ reach the screen edge (`insets: { bottom: "none" }`, and the block pads
140
+ itself with `calc(var(--sw-safe-area-inset-bottom) + 12px)`).
141
+
142
+ Never turn an edge off to fix scrolling, a cut-off footer, or a white
143
+ band under the content — those were symptoms of insets that shrank the
144
+ scroll area, and the pages now reach under the insets on their own.
145
+ `modal`, `drawer` and `popup` presentations and web funnels already have
146
+ the edges the platform gives them; do not touch them. Prefer `insets` in
147
+ config to a `:root` override for the same edge, so the setting is visible
148
+ next to the products and presentation.
149
+
150
+ ### The floors
151
+
152
+ The safe area is the host's `env()` wherever it reports one — an iPhone
153
+ reports the exact value for the phone in hand — and the floor wherever it
154
+ reports nothing: the studio, Android WebView (no `env()` for system
155
+ bars), and the odd webview. The floor is a minimum per class, keyed on
156
+ the attributes the framework stamps on `<html>`:
157
+
158
+ | Host (`data-sw-platform` · `data-sw-cutout`/`idiom` · `data-sw-presentation`) | top | bottom | sides |
159
+ | --- | --- | --- | --- |
160
+ | ios · island · fullscreen | 59 | 34 | 0 |
161
+ | ios · notch · fullscreen | 44 | 34 | 0 |
162
+ | ios · none (home button) · fullscreen | 20 | 0 | 0 |
163
+ | ios · phone, cutout unknown · fullscreen | 59 | 34 | 0 |
164
+ | ios · island/notch · landscape | 0 | 21 | 59/44 both sides |
165
+ | ios · tablet · fullscreen | 24 | 20 | 0 |
166
+ | ios · phone · modal or drawer | 0 (sheet starts below the bar) | 34 (island/notch), 0 (home button) | 0 |
167
+ | ios · tablet · modal or drawer | 0 | 0 (the sheet floats) | 0 |
168
+ | android · fullscreen | 24 (drawn under the status bar) | 0 (the SDK margins the webview above the nav bar) | 0 |
169
+ | android · modal or drawer | 0 (sheet starts below the bar) | 0 (SDK pads it) | 0 |
170
+ | any · popup | 0 | 0 | 0 (the SDK insets it) |
171
+ | web | 0 | 0 | 0 (the browser owns its chrome) |
172
+
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.
180
+
181
+ `push` and `noAnimation` are fullscreen. The attributes come from the
182
+ device the host reports and are absent, never guessed, until the host's
183
+ first message; the studio sets them per preset, so switching devices
184
+ there moves the insets. The value on an actual iPhone is `env()`, so a
185
+ 16 Pro shows 62 on device and 59 in the studio — that 3px is why chrome
186
+ sits at inset *plus* spacing.
187
+
188
+ ## Recipes
189
+
190
+ **Close button** (`layout.tsx`):
191
+
192
+ ```css
193
+ .close { position: absolute; top: 4px; right: 16px; }
194
+ ```
195
+
196
+ **Pinned CTA that content scrolls under** (last child of the page):
197
+
198
+ ```css
199
+ .page { display: flex; flex-direction: column; min-height: 100%; padding: 16px 20px 0; }
200
+ .footer { position: sticky; bottom: 0; margin-top: auto; padding: 24px 0 12px;
201
+ background: linear-gradient(to bottom, transparent, var(--bg) 32px); }
202
+ ```
203
+
204
+ `bottom: 0` sticks at the inset, above the home indicator, because the
205
+ scroll container's padding is the inset; the content behind it scrolls
206
+ on to the screen edge. `pointer-events: none` on the gradient region
207
+ only if the fade is a separate element; a sticky footer that is the
208
+ button itself needs no pointer tricks. On Android the bottom inset is 0,
209
+ so the 12px is what lifts it off the edge. Never `bottom: calc(-1 *
210
+ var(--sw-inset-bottom))` or a negative margin to "reach" the edge — the
211
+ route already does.
212
+
213
+ **A footer every page must stay above** (legal links, "Built with"): a
214
+ plain flex child of the layout after `{children}`, and
215
+ `:root { --sw-page-inset-bottom: 0px; }` so the pages stop at it instead
216
+ of reaching under it. The footer then sits above the home indicator on
217
+ the root's own padding; nothing overlaps; nothing to position.
218
+
219
+ **A scrim or sheet inside the paywall that must cover the bars** (an
220
+ exit offer, a confirmation): absolute in the layout with
221
+ `inset: var(--sw-bleed)`; inside a page's positioned wrapper,
222
+ `inset: var(--sw-page-bleed)`. The variables are the four negative
223
+ insets, so there is nothing to calculate.
224
+
225
+ **Full-bleed hero under the status bar**:
226
+
227
+ ```ts
228
+ insets: { top: "none" }
229
+ ```
230
+
231
+ ```css
232
+ .close { position: absolute; top: calc(var(--sw-safe-area-inset-top) + 8px); right: 16px; }
233
+ .hero::after { /* scrim so the bar's clock stays legible in both schemes */ }
234
+ ```
235
+
236
+ **Bottom sheet or drawer** (`presentation.style: "modal" | "drawer"`):
237
+ top inset is 0 because the sheet already starts below the bar; leave
238
+ 16–20px above the first element for the grabber. A drawer's viewport is
239
+ the drawer's height, not the screen.
240
+
241
+ **Web funnel**: every inset is 0 and the browser draws its own bars;
242
+ the root's `100dvh` already tracks Safari's collapsing toolbar. Design
243
+ the page to scroll; don't chase the toolbar.
244
+
245
+ **Turning it off for one platform** without touching the others:
246
+ leave that edge out of config and set it in CSS with the platform
247
+ attribute, as above.
248
+
249
+ ## Debugging, in order
250
+
251
+ Run these in the studio's devtools (or on device via Safari/Chrome
252
+ remote inspector) before changing any CSS:
253
+
254
+ 1. `document.documentElement.dataset` → are `swPlatform`, `swIdiom`,
255
+ `swCutout`, `swPresentation` what you expect? Missing platform means
256
+ the host hasn't replied yet (or the device variables have no
257
+ `platform`); a wrong presentation means `config.ts` and what you are
258
+ testing disagree.
259
+ 2. `getComputedStyle(document.querySelector("[data-sw-root]")).padding`
260
+ → the insets actually applied. Compare to the floor table. The same
261
+ values are the padding of `[data-sw-route]`, whose rect should be
262
+ the full viewport: if it stops short of an edge, something set
263
+ `--sw-page-inset-*` for that edge, or a layout element sits there.
264
+ 3. `document.documentElement.style.cssText` → what `insets` in config
265
+ wrote inline. If an edge is there, CSS cannot move it.
266
+ 4. **Under the bar?** It is `position: fixed`, on an edge you turned
267
+ off, or negatively margined. Search the stylesheet for `fixed`,
268
+ `env(`, and `margin-top: -`.
269
+ 5. **Double gap at the top?** Something adds the inset again: `env(`,
270
+ `--sw-inset-`, or a page padding that was tuned for a preview without
271
+ insets. The root already did it.
272
+ 6. **The whole paywall scrolls a little, or the footer is cut off?** An
273
+ element of yours is `100dvh`/`100vh` tall, or a sticky footer was
274
+ given a negative `bottom` to reach the edge (it now sticks under the
275
+ home indicator — use `bottom: 0`), or the layout isn't a flex
276
+ column so the routes collapsed (`[data-sw-routes]` height 0 → set
277
+ `--sw-routes-height`, or make the shell `display: flex; flex: 1 1 auto;
278
+ flex-direction: column`).
279
+ 7. **Chrome jumps during a transition?** It is fixed and inside a page.
280
+ Move it to `layout.tsx` (absolute) or make it sticky in the page.
281
+ 8. **Right on iPhone, wrong on Android?** Android has no bottom inset
282
+ (the SDK keeps the webview above the nav bar) and its top floor is
283
+ 24px; a design tuned to 34px of bottom air needs its own padding, and
284
+ a cutout phone can have a taller bar than 24 — that is what the
285
+ spacing above the first element absorbs.
286
+ 9. **Right in the studio, wrong on device (or vice versa)?** On an
287
+ iPhone the value is the real `env()`, in the studio it is the floor;
288
+ they differ by a few px on the tallest bars. On Android the floor is
289
+ the value on device too, and it is the platform's standard 24px bar:
290
+ a cutout phone whose bar is taller shows chrome closer to the bar than
291
+ the studio did, which is what the spacing above the first element is
292
+ for. The studio's Android presets draw the bar at 24px and reserve the
293
+ navigation bar below the paywall like the SDK does, so what you see
294
+ is what the floors assume. If the two differ by a lot, the attributes
295
+ in step 1 differ between the two.
@@ -0,0 +1,208 @@
1
+ # Migrating a dashboard (editor) paywall to code
2
+
3
+ A paywall built in Superwall's visual editor becomes a framework paywall by
4
+ being **rebuilt**, not transplanted: same design, same products, same
5
+ pages and actions, expressed as routes, hooks and your own CSS. The CLI
6
+ does the deterministic half; you do the pages; the user reviews in the
7
+ studio against the original; nothing goes live until they say so.
8
+
9
+ ```bash
10
+ superwall create --from <paywall-id> # in the app's root, or an empty directory
11
+ ```
12
+
13
+ That reads the dashboard paywall and its served document and scaffolds a
14
+ project whose `paywalls/<slug>/config.ts` already carries the name,
15
+ platform, product slots, presentation style and geometry, feature gating,
16
+ scroll and cache settings, background, and the locales to provide. It
17
+ writes `paywalls/<slug>/MIGRATION.md`, the brief with the source URL,
18
+ screenshot, product table and an inventory, records the source in
19
+ `superwall.lock` under `origins`, and connects the project to the same
20
+ app. Read the brief first; every step below refers to it.
21
+
22
+ ## What you are migrating from
23
+
24
+ The served document (the brief's "Served document" URL) is a rendered
25
+ HTML page **plus the editor's entire store as JSON** in
26
+ `<script id="vike_pageContext" type="application/json">`. Fetch it once
27
+ and read the store rather than scraping the DOM; it is the design's
28
+ source of truth:
29
+
30
+ ```bash
31
+ curl -sL -A "Mozilla/5.0" "<served document url>" -o source.html
32
+ ```
33
+
34
+ Inside the store (`typeName` on every record):
35
+
36
+ | Record | What it is | Becomes |
37
+ | --- | --- | --- |
38
+ | `paywall` | settings: `presentationStyleV3`, `featureGating`, `isScrollEnabled`, `onDeviceCache`, `gameControllerSupport`, `webCheckoutDestination` | already in `config.ts` |
39
+ | `paywall_product:<ref>` | a product slot, with `productVariables` (the example prices the editor rendered with) | `products.<ref>` in `config.ts`; the identifier is `"missing"` on templates and must be fixed |
40
+ | `paywall_language:<locale>` | a translated locale | `messages/<locale>.ts` |
41
+ | `node` (`type: stack \| text \| img \| video \| lottie \| icon \| navigation \| drawer`) | the element tree via `parentId`; `props` hold text, media, layout; inline `style`/classes on the rendered HTML hold the design tokens | components and CSS |
42
+ | `node` with `type: navigation` | **the pages**: each child stack is one page, in `index` order | one route per child under `app/`; the navigation's `currentIndex` state is the router |
43
+ | `node` with `type: drawer` | a bottom sheet with an `isOpen` state | a route pushed with a custom `sheet` transition (define it as the docs' Transitions › Bottom sheets shows, or copy the abandonment-offer example's), or local state for a small one |
44
+ | `property-click-behavior` on a node | the action a tap performs (below) | a hook call |
45
+ | `state:state.<name>` | custom state (a toggle, a selected choice) | React state, or `useQueryState` on a web funnel |
46
+ | `state:products.selectedIndex` | which product is selected | plain React state, as in the `product-selection` example |
47
+ | `state:products.hasIntroductoryOffer` | trial eligibility | `useIntroductoryOffer()` |
48
+ | `style_variable_group` | design tokens per interface style and breakpoint | `:root` / `:root.dark` custom properties |
49
+
50
+ Text nodes render **Liquid**: `{{ products.primary.price }}`,
51
+ `{{ products.selected.period }}`, `{{ products.yearly.rawPrice | divided_by: 12 | round }}`.
52
+ Every `{{ … }}` becomes a read of `useProducts()` variables (the brief
53
+ lists them all); filters become JavaScript, and arithmetic on `rawPrice`
54
+ becomes `Number()` arithmetic guarded on the value existing. `products.selected`
55
+ is whichever slot the selection state points at.
56
+
57
+ ### Action mapping
58
+
59
+ | Editor action (`"type"` in the store) | Framework |
60
+ | --- | --- |
61
+ | `purchase` (`by-index` / `by-selected`) | `usePurchase().purchase(reference)`; `by-selected` reads your selection state. `onPurchase` follow-ups become code after `await purchase()` resolves `completed` |
62
+ | `restore` | `useActions().restore()` |
63
+ | `close` | `useActions().close()` |
64
+ | `open-url` | `useActions().openUrl(url)` |
65
+ | `navigate-page` (`next` / `back`) | `useRouter().push("<next route>")` / `router.back()` |
66
+ | `set-product-index` | set your selection state |
67
+ | `set-state` | set the matching React state |
68
+ | `set-attribute` | `useActions().setUserAttributes({ … })` |
69
+ | `custom-placement` | `useActions().customPlacement(name, params)` |
70
+ | `custom-in-app` | `useActions().requestCallback(...)` (docs: `actions`) |
71
+ | `request-permission` | `useActions().requestPermission(type)`; `onGranted`/`onDenied` become the resolved status |
72
+ | `request-store-review` | `useActions().requestStoreReview()` |
73
+ | `redeem-discount` | `useDiscount().redeem(code)` |
74
+ | `redeem-purchase` | `useCheckoutRedemption()` (web) |
75
+ | `select-choice` / `select-indicator` | React state on the choice group |
76
+ | `focus-input` / `scroll-to-element` | a `ref` and `focus()` / `scrollIntoView()` |
77
+ | `teleport-to-web` | not migrated; ask the user what the web destination should be |
78
+
79
+ Fetch `curl -sL superwall.com/docs/framework/actions.md` for the exact hook
80
+ signatures before writing them.
81
+
82
+ ## The workflow
83
+
84
+ 1. **Inventory, and get a yes.** From the brief and the store, write down
85
+ every page (navigation children, in order), every drawer, every action
86
+ and where it sits, every `{{ }}` variable, every locale, every asset
87
+ URL (images, video, Lottie, fonts), and every custom state. Show that
88
+ list to the user with the screenshot, and ask whether anything should
89
+ change in the rebuild (usually: nothing, it is a migration). Don't
90
+ write code before that yes.
91
+ 2. **Fix the products.** A `"missing"` identifier in `config.ts` blocks
92
+ push. The dashboard paywall's product slots name the real products
93
+ on a published paywall; on a template they don't exist, and the user
94
+ has to choose (or you create them, see [cli.md](cli.md)).
95
+ 3. **Rebuild page by page, in the store's order.** Each navigation child
96
+ is a route; shared chrome (close, back, step indicator) that the editor
97
+ drew outside the navigation goes in `layout.tsx`. Use the framework's
98
+ layout system as written in [layout.md](layout.md): the paywall is
99
+ inset for you, chrome is absolute in the layout, the CTA is sticky in
100
+ the page, no `env()`, no `position: fixed`. Take spacing, type, colors
101
+ and radii from the rendered HTML's inline styles and the
102
+ `style_variable_group` tokens; take nothing from habit. The design
103
+ conventions in [mobile-design.md](mobile-design.md) apply, with the
104
+ reference winning every time.
105
+ 4. **Rebuild every state, not the one the screenshot shows.** Both
106
+ trial-eligibility variants, every selected product, every toggle, the
107
+ drawer open and closed. **Every string goes through messages**, even
108
+ when the source has one language: the default locale's copy in
109
+ `messages/en.ts` (or the paywall's `defaultLocale`), every
110
+ `paywall_language` as its own `messages/<locale>.ts`, and `t()` in the
111
+ pages, `aria-label`s included; Liquid product variables become `t()`
112
+ interpolations guarded on the value. Assets are downloaded into
113
+ `assets/` and referenced relatively; fonts are subset.
114
+ 5. **Compare in the studio.** `superwall dev`, open the paywall, and pick
115
+ **Compare › Original**. The right pane is the dashboard paywall served
116
+ as it is today, view-only: it does not follow the studio's theme,
117
+ locale or device variables, so it shows the editor's example prices in
118
+ light mode. Walk every page on an island phone, iPhone SE, a Pixel and
119
+ an iPad, both schemes on your side, and fix what differs. Then ask the
120
+ user to review it the same way; that review is the gate.
121
+ 6. **Push, never promote.** `superwall push` creates a **new** dashboard
122
+ paywall bound in `superwall.lock`; the original keeps serving. Tell the
123
+ user how to switch: point the campaign's variant at the new paywall,
124
+ and back at the old one to roll back. Do not promote or touch campaigns
125
+ unless asked.
126
+ 7. **Delete `MIGRATION.md`** when the user is satisfied. The `origins`
127
+ entry in the lock stays, so Compare › Original keeps working.
128
+
129
+ ## What does not migrate, and must be said
130
+
131
+ - **The original cannot be converted in place.** A framework paywall is a
132
+ new dashboard paywall; the switch is a campaign change the user makes.
133
+ - **Editor-only behavior with no framework equivalent**: surveys attached
134
+ to the paywall, `teleport-to-web`, and anything the editor computes
135
+ from states the store carries but the pages never render. Name each one
136
+ in the hand-off as "not carried over" rather than approximating it.
137
+ - **Example prices.** The editor stores example `productVariables` per
138
+ slot; the framework never invents prices. Guard every variable and
139
+ design the unpriced state as the framework skill says.
140
+ - **Pixel identity is not the goal; the design is.** The editor's
141
+ generated CSS (absolute `vw` widths, deep stack nesting) is not what to
142
+ reproduce. Reproduce what it looks like with clean CSS, and let the
143
+ Compare pane, not a diff of DOM, decide when it matches.
144
+
145
+ ## Playbook: rebuilding the pages
146
+
147
+ You are inside a `superwall/` project. One surface, `paywalls/<slug>/`, was
148
+ scaffolded from a dashboard paywall: its `config.ts` is final, its
149
+ `MIGRATION.md` is your brief, and everything under `app/` is a starter to
150
+ replace. Rebuild the paywall so it looks and behaves like the source,
151
+ written the way the framework is meant to be used.
152
+
153
+ Read `layout.md` (insets, positioning, scrolling) and `mobile-design.md`
154
+ before writing a line; the mapping above is the source of truth for every
155
+ element, action and state. This section fixes the order of work and the
156
+ boundaries.
157
+
158
+ ### Docs access
159
+
160
+ ```bash
161
+ curl -sL https://superwall.com/docs/framework/llms.txt # page index
162
+ curl -sL https://superwall.com/docs/framework/{page}.md # one page
163
+ ```
164
+
165
+ ### Order of work
166
+
167
+ - [ ] Read `MIGRATION.md`; fetch the served document from its URL
168
+ (`curl -sL -A "Mozilla/5.0" <url> -o source.html`, in a temp dir, never
169
+ inside the project) and parse the editor store from
170
+ `<script id="vike_pageContext">`. Confirm the brief's inventory against
171
+ it: pages (children of the `navigation` node, in `index` order),
172
+ drawers, every tap action, every `{{ }}` product variable, every
173
+ `paywall_language`, every asset URL, every custom `state:state.*`.
174
+ - [ ] Design tokens: take colors, type, spacing and radii from the rendered
175
+ HTML's inline styles and the `style_variable_group` records into
176
+ `:root` / `:root.dark` variables in `app/theme.css`. Keep
177
+ `--sw-background: var(--bg)`.
178
+ - [ ] One route per page under `app/`, `index.tsx` first; shared chrome the
179
+ editor drew outside the navigation goes in `layout.tsx`. Every action
180
+ becomes the hook call the mapping table names; `navigate-page` becomes
181
+ `useRouter().push/back`; a drawer becomes a route pushed with the
182
+ `sheet` transition or local state. Product text comes from
183
+ `useProducts()` variables, guarded, with the unpriced state designed.
184
+ - [ ] Every state: both trial-eligibility variants, every selected product,
185
+ every toggle, the drawer open and closed. Every string through
186
+ messages, even for one language: the default copy in
187
+ `messages/en.ts`, each source locale as `messages/<locale>.ts`, and
188
+ `t()` in the pages (`aria-label`s included); product variables as
189
+ guarded `t()` interpolations, never a price in a catalog. Assets
190
+ downloaded into `assets/` and referenced relatively; fonts subset.
191
+ - [ ] Layout rules from `layout.md`: the framework insets the paywall; no
192
+ `env()`, no `position: fixed`, chrome absolute in the layout, a pinned
193
+ CTA sticky in the page, shell `flex: 1 1 auto`, nothing `100dvh`.
194
+ - [ ] `bun run typecheck` in the project passes. Fix every diagnostic
195
+ `superwall dev` would print (a stray file in `app/`, a duplicate
196
+ route).
197
+ - [ ] Leave `MIGRATION.md` in place; the user deletes it after review.
198
+
199
+ ### Boundaries
200
+
201
+ - Never run `superwall push`, `promote` or `publish`, and never touch
202
+ campaigns. The user reviews in the studio (Compare › Original) and ships.
203
+ - Never change `config.ts` except to replace a `"missing"` product
204
+ identifier the user has named. Never invent a product or a price.
205
+ - Never paste the editor's generated HTML or CSS. Rebuild the design with
206
+ clean components; the Compare pane decides when it matches.
207
+ - Anything with no framework equivalent (surveys, `teleport-to-web`) is
208
+ listed in your final note as not carried over, never approximated.