@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.
- package/README.md +21 -5
- package/dist/{actions-EfP8phmb.js → actions-Dt35nIi8.js} +3 -2
- package/dist/{api-CEwXCCoC.js → api-BOR-uXZe.js} +9 -9
- package/dist/{app-D8mEVlQo.js → app-BU27SLPX.js} +9 -9
- package/dist/{asa-BFWehnTA.js → asa-2ykGnjaV.js} +11 -11
- package/dist/{asc-DJqQmtmR.js → asc-r3xmFT0L.js} +14 -14
- package/dist/{auth-CT2DWX8r.js → auth-BWZfguI8.js} +9 -9
- package/dist/auth.js +2 -2
- package/dist/{billing-BzEnVPD2.js → billing-BsQgXXYh.js} +1 -1
- package/dist/{bind-BZxVyt9P.js → bind-BSTAinn6.js} +5 -4
- package/dist/{command-DP96_gmP.js → command-DMoMn7uc.js} +39 -16
- package/dist/{create-Q8TqqjZt.js → create-CSo6XjSm.js} +118 -91
- package/dist/dev-B0MF6z3L.js +21 -0
- package/dist/{dev-DlCcwFu5.js → dev-CuXa3J4Z.js} +29 -24
- package/dist/{doctor-CJsjHpCZ.js → doctor-DXJaDqsx.js} +10 -10
- package/dist/{drivers-UT36AnOw.js → drivers-Cr252DOJ.js} +3 -3
- package/dist/entry.js +84 -50
- package/dist/{existing-Cak1WxWB.js → existing-Ckx_g7Be.js} +6 -3
- package/dist/{feedback-DDRzoqPx.js → feedback-Dt5yebMS.js} +6 -6
- package/dist/{hosted-CEH78QVn.js → hosted-Cjekn8oJ.js} +2 -2
- package/dist/{integrate-D8jyhDzk.js → integrate-DVqhvPVq.js} +25 -66
- package/dist/{login-kneYhhk0.js → login-Bjj8QvIN.js} +6 -6
- package/dist/migrate-qmvOtp3l.js +283 -0
- package/dist/open-studio-CpHqjovS.js +1299 -0
- package/dist/{org-Cg25bcsj.js → org-CV8c849b.js} +3 -3
- package/dist/{output-csAtR6kJ.js → output-CiELrN8w.js} +15 -2
- package/dist/{pipeline-DAeI9tHs.js → pipeline-DSCHL9KA.js} +482 -9
- package/dist/{print-skill-BHVPP9cX.js → print-skill-CaHRJ8xW.js} +7 -7
- package/dist/{promote-Boek5K2d.js → promote-UMTh8Q33.js} +17 -18
- package/dist/publish-DWX8S9yZ.js +34 -0
- package/dist/push-Dox4_5Dq.js +34 -0
- package/dist/{query-B8G6T8Ba.js → query-CnSsDZ7Q.js} +10 -10
- package/dist/reports-C0xHCLnt.js +27 -0
- package/dist/{resource-DjsWVka-.js → resource-5bgyyL9B.js} +15 -15
- package/dist/{resources-s64mBHaC.js → resources-Bf9O1JNM.js} +28 -2
- package/dist/{run-BtcQJCP8.js → run-BVeZWbXx.js} +39 -22
- package/dist/{scan-DJixvuHn.js → scan-CAObNRgc.js} +44 -4
- package/dist/skills/superwall/SKILL.md +146 -0
- package/dist/skills/superwall/references/api.md +275 -0
- package/dist/skills/superwall/references/asa.md +160 -0
- package/dist/skills/superwall/references/asc.md +96 -0
- package/dist/skills/superwall/references/dashboard-links.md +57 -0
- package/dist/skills/superwall/references/data-analytics.md +893 -0
- package/dist/skills/superwall/references/docs.md +51 -0
- package/dist/skills/superwall/references/sdk-integration.md +105 -0
- package/dist/skills/superwall/references/sdk-source.md +18 -0
- package/{skills/superwall-dashboard/SKILL.md → dist/skills/superwall/workflows/dashboard/playbook.md} +3 -9
- package/{skills/superwall-dashboard/references → dist/skills/superwall/workflows/dashboard}/setup.md +1 -3
- package/dist/skills/superwall/workflows/integrate/android.md +292 -0
- package/{skills/superwall-integrate/SKILL.md → dist/skills/superwall/workflows/integrate/playbook.md} +16 -11
- package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/adapty.md +4 -4
- package/{skills/superwall-migrate/SKILL.md → dist/skills/superwall/workflows/migrate/playbook.md} +4 -10
- package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/qonversion.md +4 -4
- package/{skills/superwall-migrate/references → dist/skills/superwall/workflows/migrate}/revenuecat.md +4 -4
- package/dist/skills/superwall/workflows/placements/android.md +175 -0
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/expo.md +1 -1
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/flutter.md +1 -1
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/ios.md +1 -1
- package/{skills/superwall-placements/SKILL.md → dist/skills/superwall/workflows/placements/playbook.md} +6 -10
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/react-native.md +2 -2
- package/{skills/superwall-placements/references → dist/skills/superwall/workflows/placements}/strategy.md +4 -3
- package/dist/skills/superwall/workflows/review/android.md +120 -0
- package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/expo.md +1 -1
- package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/flutter.md +1 -1
- package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/ios.md +1 -1
- package/{skills/superwall-review/SKILL.md → dist/skills/superwall/workflows/review/playbook.md} +2 -7
- package/{skills/superwall-review/references → dist/skills/superwall/workflows/review}/react-native.md +1 -1
- package/dist/skills/superwall-framework/SKILL.md +253 -0
- package/dist/skills/superwall-framework/references/cli.md +340 -0
- package/dist/skills/superwall-framework/references/examples.md +123 -0
- package/dist/skills/superwall-framework/references/layout.md +295 -0
- package/dist/skills/superwall-framework/references/migrate-from-editor.md +208 -0
- package/dist/skills/superwall-framework/references/migrate-from-native.md +193 -0
- package/dist/skills/superwall-framework/references/mobile-design.md +371 -0
- package/dist/skills/superwall-framework/references/native/android.md +83 -0
- package/dist/skills/superwall-framework/references/native/flutter.md +65 -0
- package/dist/skills/superwall-framework/references/native/ios.md +77 -0
- package/dist/skills/superwall-framework/references/native/react-native.md +67 -0
- package/dist/skills/superwall-framework/references/responsive.md +162 -0
- package/dist/{skills-CRG1xk0G.js → skills-Cu41i-Az.js} +12 -12
- package/dist/{skills-CODut1Hn.js → skills-grTDuHlc.js} +134 -36
- package/dist/{spinner-B9dT3DBY.js → spinner-DFctF_Jw.js} +1 -1
- package/dist/{telemetry-BtkMdT-5.js → telemetry-BuCbmoux.js} +3 -3
- package/dist/{token-hM7V1KMG.js → token-mju3Q-vc.js} +3 -3
- package/dist/{ui-Lqt_zFOr.js → ui-4gLyfrgl.js} +76 -46
- package/dist/{update-CeylIjx5.js → update-DnGfpCD7.js} +2 -2
- package/dist/{upgrade-DRqUfCBT.js → upgrade-PMoj3yqJ.js} +6 -6
- package/package.json +8 -7
- package/prompts/actions/paywall-migrate.xml +24 -0
- package/prompts/actions/screen-migrate.xml +26 -0
- package/dist/git-ZwA3Mx8m.js +0 -433
- package/dist/migrate-D_x1oyTk.js +0 -114
- package/dist/publish-C-zEUnO9.js +0 -35
- package/dist/push-DUDQG-EO.js +0 -35
- package/skills/README.md +0 -118
- /package/dist/{api-output-D9ggXQIr.js → api-output-CEhN-U_N.js} +0 -0
- /package/dist/{asc-products-C6MvSy8H.js → asc-products-1e1DoGeL.js} +0 -0
- /package/dist/{params-B1zeElGa.js → params-BxgTuCzr.js} +0 -0
- /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/expo.md +0 -0
- /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/flutter.md +0 -0
- /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/ios.md +0 -0
- /package/{skills/superwall-integrate/references → dist/skills/superwall/workflows/integrate}/react-native.md +0 -0
- /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.
|