@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,193 @@
1
+ # Migrating a native screen to a Superwall surface
2
+
3
+ Any screen the app would rather change without a release — update-required
4
+ and force-upgrade, onboarding steps, rate-us and notification prompts,
5
+ announcements, offers and win-backs — can become a framework surface shown
6
+ through a placement. The move is a **rebuild**, not a port: same copy,
7
+ assets and behavior, expressed as a page with the framework's hooks. The
8
+ CLI does the deterministic half; you rebuild the page; the user reviews it
9
+ next to a screenshot of the original; then the app is wired.
10
+
11
+ ```bash
12
+ superwall migrate --screen App/UpdateRequiredView.swift # in the app's root
13
+ superwall migrate --screen # scan for likely screens and pick
14
+ ```
15
+
16
+ The scan reads that one file — SwiftUI or UIKit (`.swift`), Jetpack Compose or
17
+ Android Views (`.kt`), React Native (`.tsx`), Flutter (`.dart`) — and writes into the project it finds (or a
18
+ new `superwall/`):
19
+
20
+ - `paywalls/<slug>/config.ts`: the screen's name, and a product slot per
21
+ store identifier the source referenced. The user confirms they exist on
22
+ the dashboard; a push refuses unknown products.
23
+ - `paywalls/<slug>/MIGRATION.md`, the brief: source path and framework,
24
+ every user-visible string with its dynamic values, assets and system
25
+ symbols, links, product ids, and each action mapped to the hook that
26
+ replaces it. **Read the brief first; then read the source and what it
27
+ imports.** Strings in string tables, view models and theme files are not
28
+ in the scan.
29
+ - `superwall.lock` → `origins["paywall/<slug>"] = { path, framework,
30
+ screenshot? }`, so `superwall migrate --screen <path>` picks the rebuild
31
+ up later and the studio knows the original.
32
+
33
+ Then the CLI offers to run the rebuild headless with the user's agent, copy
34
+ the prompt, or stop; `--skill` prints the prompt. When *you* are the agent
35
+ driving it, do the inventory with the user rather than the headless path.
36
+
37
+ ## The original
38
+
39
+ The studio cannot render native UI, so **Compare › Original** shows a
40
+ screenshot: the CLI offers to capture a booted iOS simulator, or the user
41
+ passes `--screenshot <file>` (an Android emulator capture works too). It is
42
+ saved as `paywalls/<slug>/original.png`. Without one there is no Original
43
+ entry — keep the app running in the simulator beside the studio, and take
44
+ your own screenshots when reviewing.
45
+
46
+ ## Rebuilding
47
+
48
+ Read [layout.md](layout.md) and [mobile-design.md](mobile-design.md) first,
49
+ and hold to the localization rule in `SKILL.md` (every string through
50
+ `messages/` and `t()`, even for one language). Then:
51
+
52
+ - One page per screen state that was a separate view; a single screen is
53
+ `app/index.tsx` alone. Tokens from the source's styles and the app's
54
+ theme into `:root` / `:root.dark` in `theme.css`; match the app's dark
55
+ appearance, not the starter's.
56
+ - Every string in `messages/en.ts`, read with `t()`; dynamic values as
57
+ `t()` parameters from `useVariables()`, `useProducts()` or placement
58
+ params. Every locale the app has becomes `messages/<locale>.ts`.
59
+ - Assets copied into `assets/`; system symbols and Material icons become
60
+ SVGs; fonts subset with `@font-face`.
61
+ - Actions, per the brief's table:
62
+
63
+ | The screen did | The surface does |
64
+ | --- | --- |
65
+ | a purchase | `usePurchase()` with the slot from `config.ts` |
66
+ | a restore | `useActions().restore()` |
67
+ | opened a URL, the App Store included | `useActions().openUrl(url)` |
68
+ | asked for a store review | `useActions().requestStoreReview()` |
69
+ | asked for notifications | `useActions().requestPermission("notification")` |
70
+ | dismissed itself | `useActions().close()` |
71
+ | navigated within its own flow | another route and `useRouter().push()` |
72
+ | navigated elsewhere, refreshed data, routed the app | nothing: close, and the app's placement handler continues |
73
+ | read app / OS version, device facts | `useDevice()`, `useVariables()` |
74
+ | fetched its own data | placement params or user attributes set before `register()`, read with `useVariables()` |
75
+ | safe-area work | nothing; the framework insets the screen |
76
+
77
+ - Only write inside `paywalls/<slug>/`. Never edit the app, never add
78
+ `register()` calls, never delete the native screen, never push or touch
79
+ campaigns. Anything with no equivalent (share sheet, camera, a settings
80
+ deep link the SDK cannot open) goes in the closing note as not carried
81
+ over.
82
+
83
+ ## Wiring the app (after the user has reviewed and pushed)
84
+
85
+ The brief names the placement (the screen's name in snake_case). Where the
86
+ app presented the screen, register instead, with the same condition and
87
+ the data the screen needs as params. This is ordinary placement work:
88
+ the `superwall` skill's `workflows/placements/` playbook (printed by
89
+ `superwall integrate --skill`) is the playbook for where and how to
90
+ register in each SDK, and the SDK docs are the API reference —
91
+ fetch the page for the app's platform rather than working from memory:
92
+
93
+ ```bash
94
+ curl -sL https://superwall.com/docs/ios/quickstart/feature-gating.md
95
+ curl -sL https://superwall.com/docs/android/quickstart/feature-gating.md
96
+ curl -sL https://superwall.com/docs/expo/quickstart/feature-gating.md
97
+ curl -sL https://superwall.com/docs/flutter/quickstart/feature-gating.md
98
+ ```
99
+
100
+ ```swift
101
+ if needsUpdate { Superwall.shared.register(placement: "update_required") }
102
+ ```
103
+
104
+ ```kotlin
105
+ if (needsUpdate) Superwall.instance.register("update_required")
106
+ ```
107
+
108
+ ```tsx
109
+ const { registerPlacement } = usePlacement();
110
+ if (needsUpdate) await registerPlacement({ placement: "update_required" });
111
+ ```
112
+
113
+ ```dart
114
+ if (needsUpdate) Superwall.shared.registerPlacement('update_required');
115
+ ```
116
+
117
+ A screen the user must not dismiss is a **gated** surface: the campaign's
118
+ paywall is gated and the `feature` callback only runs when the user is
119
+ let through; keep the app's hard block until the surface is live. Create
120
+ the campaign and placement on the dashboard (`superwall integrate`, the
121
+ `superwall` skill's `workflows/dashboard/`), verify on a device, then delete
122
+ the native screen, its assets and strings. `native/<framework>.md` beside
123
+ this file has the full construct table for each source framework.
124
+
125
+ ## Playbook: rebuilding the screen
126
+
127
+ You are inside a `superwall/` project. One surface, `paywalls/<slug>/`, was
128
+ scaffolded from a screen in the app: its `config.ts` carries the name and
129
+ any products the screen sold, its `MIGRATION.md` is your brief, and
130
+ everything under `app/` is a starter to replace. Rebuild the screen so it
131
+ looks and behaves like the source, written the way the framework is meant
132
+ to be used. The source file stays untouched; wiring the app is a later
133
+ step the user runs.
134
+
135
+ Read `layout.md` (insets, positioning, scrolling) and `mobile-design.md`
136
+ before writing a line, and hold to the localization rule in `SKILL.md`:
137
+ every string through `messages/` and `t()`, even for one language. This section fixes the order of
138
+ work and the boundaries; the source framework's file under `native/`
139
+ (`ios.md`, `android.md`, `react-native.md`, `flutter.md`) explains how the
140
+ source was wired and what each construct becomes.
141
+
142
+ ### Docs access
143
+
144
+ ```bash
145
+ curl -sL https://superwall.com/docs/framework/llms.txt # page index
146
+ curl -sL https://superwall.com/docs/framework/{page}.md # one page
147
+ ```
148
+
149
+ ### Order of work
150
+
151
+ - [ ] Read `MIGRATION.md`, then the source file it names (the path is
152
+ relative to this directory). Confirm the brief's inventory against
153
+ the code: every string, every asset, every control and what it does,
154
+ every conditional branch (a loading state, an error, a version
155
+ check). Follow imports for view models, string tables and theme
156
+ files that hold what the screen draws; the brief only saw one file.
157
+ - [ ] Design tokens: colors, type, spacing and radii from the source's
158
+ styles (and the app's theme if it uses one) into `:root` /
159
+ `:root.dark` variables in `app/theme.css`. Keep
160
+ `--sw-background: var(--bg)`. Match the app's dark appearance, not
161
+ the framework starter's.
162
+ - [ ] One route per screen state that was a separate view; a single
163
+ screen is `app/index.tsx` alone. Every control becomes the hook call
164
+ the brief's action table names; anything the app did after the
165
+ screen (routing, refreshing) is not yours — the screen closes and
166
+ the app's placement handler continues.
167
+ - [ ] Every string through messages, even for one language: the copy in
168
+ `messages/en.ts`, `t()` in the pages (`aria-label`s included), dynamic
169
+ values as `t()` parameters read from `useVariables()`, `useProducts()`
170
+ or placement params. Assets copied into `assets/` and referenced
171
+ relatively; system symbols replaced with SVGs.
172
+ - [ ] Layout rules from `layout.md`: the framework insets the screen; no
173
+ `env()`, no `position: fixed`, a pinned CTA sticky in the page, shell
174
+ `flex: 1 1 auto`, nothing `100dvh`.
175
+ - [ ] `bun run typecheck` in the project passes. Fix every diagnostic
176
+ `superwall dev` would print.
177
+ - [ ] Leave `MIGRATION.md` in place; the user deletes it after review.
178
+ - [ ] End your note with the placement name from the brief and the file in
179
+ the app that presented the screen, so the wiring step starts from it.
180
+
181
+ ### Boundaries
182
+
183
+ - Only write inside `paywalls/<slug>/`. Never edit the app's source, never
184
+ add `register()` calls, never delete the native screen: the user wires
185
+ the app after reviewing the rebuild, with the framework reference below.
186
+ - Never run `superwall push`, `promote` or `publish`, and never touch
187
+ campaigns or products. The user reviews in the studio (Compare › Original
188
+ shows the simulator screenshot when one was captured) and ships.
189
+ - Never change `config.ts` except to replace a product identifier the
190
+ user has named. Never invent a product or a price.
191
+ - Anything with no framework equivalent (a native share sheet, a system
192
+ settings deep link the SDK cannot open, a camera view) is listed in your
193
+ final note as not carried over, never approximated.
@@ -0,0 +1,371 @@
1
+ # Mobile design execution
2
+
3
+ A paywall renders inside a native webview on a phone, presented by the
4
+ app over whatever the user was doing. It is judged against the native
5
+ screens around it, not against other web pages. Two things decide whether
6
+ it passes: reproducing the design exactly, and following the platform
7
+ conventions users feel but never name. These are working practices, not
8
+ laws — the design reference always wins over any rule here — but every
9
+ one of them exists because a shipped paywall got it wrong.
10
+
11
+ Read this whole file once per paywall. Skim the audit at the end before
12
+ every hand-off.
13
+
14
+ ## The reference is the contract
15
+
16
+ - **Build 1:1.** Spacing, sizing, weights, colors, and effects come from
17
+ the reference, not from habit. Measure the reference at logical points
18
+ (a screenshot at device width) instead of eyeballing; compare your
19
+ build against it side by side before calling it done.
20
+ - **Add nothing the design doesn't show.** No extra links, badges,
21
+ footnotes, or affordances, however well-intentioned. If something seems
22
+ missing (a restore affordance, a legal link), raise it in conversation
23
+ — never add it to the UI unprompted.
24
+ - **Effects are design decisions, not defaults.** Shadows, gradients,
25
+ borders, blurs, and radii belong to the design system of the paywall
26
+ being built. If the reference is flat, build flat; if it is soft and
27
+ elevated, match that. Reach for an effect only when the reference shows
28
+ it.
29
+ - **A reference drawn at one size is a specification for every size.**
30
+ A Figma frame is 393×852 or so; the paywall ships to 320-wide phones,
31
+ 667-tall phones, tablets and, sometimes, landscape. Where the reference
32
+ is silent, [responsive.md](responsive.md) says what to do; where it
33
+ speaks, follow it and scale the rest around it.
34
+
35
+ ## The skeleton every screen shares
36
+
37
+ Native screens have a fixed anatomy, and a paywall that follows it reads
38
+ as native before a single color is applied:
39
+
40
+ ```
41
+ ┌──────────────────────────────┐ ← status bar / cutout — the framework's inset, not yours
42
+ │ [close] [skip] │ ← layout chrome, absolute inside the shell
43
+ │ │
44
+ │ scrolling content │ ← a page: ordinary padding, the page itself scrolls
45
+ │ (the page itself scrolls) │
46
+ │ │
47
+ │ ░░░░░░░░ fade ░░░░░░░░░░░░░░ │ ← content slides under the pinned area
48
+ │ [ Primary CTA (full) ] │ ← pinned bottom chrome
49
+ │ Restore · Terms · Privacy │
50
+ └──────────────────────────────┘ ← home indicator / nav bar — the framework's inset
51
+ ```
52
+
53
+ **The framework insets the whole paywall.** Its root box fills the
54
+ viewport and is padded by the safe area of the device the paywall is on,
55
+ so everything you render already starts clear of the bars, and its
56
+ content box is what layout chrome positions against. Each page's scroll
57
+ container reaches back out to the screen edges and carries the inset as
58
+ its scroll padding, so content scrolls under the bars and rests clear of
59
+ them, like a native scroll view. You write ordinary padding. The canonical stylesheet, which every example and the
60
+ `superwall create` scaffold share:
61
+
62
+ ```css
63
+ :root {
64
+ --sw-background: var(--bg); /* every route paints it */
65
+ --sw-page-inset-bottom: 0px; /* the layout's footer owns the bottom edge; drop this line if the layout has no footer below the pages */
66
+ }
67
+ ```
68
+
69
+ **A background that is not white MUST also be set in `config.ts`.** This is
70
+ not a duplicate of `--sw-background` and it is not optional:
71
+
72
+ ```ts
73
+ background: { light: "#fdfef6", dark: "#0c0b0a" } // config.ts
74
+ ```
75
+
76
+ `--sw-background` paints the *routes*. `background` in config is what the
77
+ framework writes on `<html>`, per scheme, and `<html>` is what the shopper
78
+ sees when the scroll rubber-bands past the end of the content — every
79
+ iOS scroll does this. Set only the CSS variable and the paywall looks
80
+ right at rest and flashes a white band on every bounce, on a dark paywall
81
+ most of all. The two always carry the same colors; the audit below checks
82
+ it.
83
+
84
+ ```css
85
+ .shell { /* layout.tsx — a flex child of the framework's content box */
86
+ display: flex;
87
+ flex: 1 1 auto; /* never min-height: 100dvh — that overflows the insets and scrolls */
88
+ flex-direction: column;
89
+ }
90
+
91
+ .page { /* a route — plain padding, the inset is already outside */
92
+ display: flex;
93
+ flex-direction: column;
94
+ min-height: 100%;
95
+ padding: 16px 20px 0;
96
+ }
97
+
98
+ .close { /* layout chrome — absolute, already below the bar */
99
+ position: absolute;
100
+ top: 4px;
101
+ right: 16px;
102
+ }
103
+
104
+ .footer { /* pinned CTA, last child of the page; sticks above the home indicator, content scrolls under the fade to the edge */
105
+ position: sticky;
106
+ bottom: 0;
107
+ margin-top: auto;
108
+ padding: 24px 0 12px;
109
+ background: linear-gradient(to bottom, transparent, var(--bg) 32px);
110
+ }
111
+ ```
112
+
113
+ Three rules keep it honest, and [layout.md](layout.md) is the exact
114
+ mechanics behind them — the DOM the framework renders, what fixed,
115
+ absolute and sticky resolve against inside it, the inset settings and
116
+ their precedence, the floor table, and the debugging order:
117
+
118
+ 1. **Nothing in a layout or page adds or subtracts a safe-area inset,
119
+ and nothing is `position: fixed`.** The root did the insets and the
120
+ pages already scroll under them; fixed ignores them and
121
+ rides along with a page during transitions. Chrome is absolute in the
122
+ layout or sticky in the page. The one time a control reads the safe
123
+ area itself is over a deliberate bleed (`insets: { top: "none" }`),
124
+ and then it reads `--sw-safe-area-inset-*`, never `env()`.
125
+ 2. **Chrome sits at inset *plus* spacing, never at the inset.** The
126
+ floor for a class of device is a minimum (an iPhone 16 Pro's bar is
127
+ 62px against the island floor of 59; a cutout Pixel's is taller than
128
+ Android's 24), so the 4–16px of ordinary spacing above the first
129
+ element is what absorbs the difference on the real phone.
130
+ 3. **Sides are real.** Rotate an island phone and the cutout takes 59px of
131
+ one side; the framework pads the root's sides for it. Don't undo that
132
+ with negative margins unless the element is meant to bleed.
133
+
134
+ ## Insets — when to change them
135
+
136
+ `insets` in `config.ts` is what the paywall is padded with. The default,
137
+ `"safe-area"`, is right for almost every paywall and needs no CSS. Change
138
+ it only when the design bleeds, and say so in the hand-off:
139
+
140
+ ```ts
141
+ insets: "none" // full-bleed: the paywall draws the whole screen
142
+ insets: { top: "none" } // a hero under the status bar; other edges stay safe
143
+ insets: 24 // pixels on every edge (a web-only paywall with a fixed gutter)
144
+ ```
145
+
146
+ Android is the platform to think about twice: its bottom inset is 0
147
+ because the SDK keeps the webview above the navigation bar, so a design
148
+ tuned to 34px of air under the CTA on iPhone needs its own 12–16px on
149
+ Android, and its top floor is the standard 24px status bar while cutout
150
+ phones can run taller.
151
+
152
+ **Tailwind**: the shell is `flex flex-1 flex-col`, chrome is
153
+ `absolute top-1 right-4`, a pinned CTA is `sticky bottom-0 mt-auto`, and
154
+ chrome over a bleed reads the safe area as an arbitrary value:
155
+ `top-[calc(var(--sw-safe-area-inset-top)+8px)]`. Do not reinvent the
156
+ variables as theme tokens.
157
+
158
+ ## Scrolling and pinned chrome
159
+
160
+ - **The page scrolls; the CTA does not.** On a page with real content the
161
+ primary action is pinned at the bottom and the content scrolls under
162
+ it. A CTA that scrolls away with the copy is the single most common
163
+ reason a paywall underperforms a native one. Pinned means
164
+ `position: sticky; bottom: 0` as the page's last child, never fixed
165
+ ([layout.md](layout.md)).
166
+ - The pinned area carries a **gradient from transparent to the page
167
+ background** so content fades out behind it instead of clipping to a
168
+ hard edge; set `background` in config to the same color so the native
169
+ loading backdrop matches.
170
+ - If the fade is a separate element over the content, `pointer-events:
171
+ none` on it so it doesn't swallow scroll gestures; a sticky footer that
172
+ *is* the button needs nothing.
173
+ - **The last content row must scroll clear of the fade**: a sticky footer
174
+ takes its own space at the end of the page, so give the content above it
175
+ a little bottom margin rather than a page padding that guesses the
176
+ footer's height.
177
+ - Let the page itself scroll. Don't invent nested scroll areas — the
178
+ platform (and `scrollEnabled` in config) owns scroll behavior, and a
179
+ nested scroller breaks the rubber-band and the SDK's scroll control.
180
+ The scroll container is the page's route, not the window.
181
+ - A short page still lays out the same way: the pinned chrome is pinned
182
+ whether or not there is anything to scroll, so nothing jumps when the
183
+ content grows by a line in another locale.
184
+ - Never `overflow: hidden` on `html`/`body` to "fix" scrolling. If
185
+ something scrolls that shouldn't, find the element that is taller than
186
+ the viewport.
187
+
188
+ ## Platform conventions
189
+
190
+ The SDK reports the platform, and the studio's presets switch it. Design
191
+ for each; don't design for iOS and let Android inherit it.
192
+
193
+ ### iOS
194
+
195
+ - **Close** is a small circular button (≈ 30–32px visual, 44px tap) at
196
+ the top-right, or top-left when the design says so; a sheet
197
+ (`presentation: modal`) has the system grabber and usually no close.
198
+ - **Back** lives in the layout as a chevron at top-left and pops the
199
+ stack; there is no hardware back.
200
+ - Buttons are rounded (12–16px) or fully pill-shaped, full width, 50–56px
201
+ tall; text is 17px semibold. The primary CTA is the only filled button
202
+ on screen.
203
+ - The system font (`-apple-system, BlinkMacSystemFont, "SF Pro Text"`)
204
+ with tight negative tracking on display sizes is what reads as native.
205
+ - Segmented controls, toggles and radio rows look like their UIKit
206
+ counterparts; if the design shows a custom one, match the design.
207
+ - Restore, Terms and Privacy sit under the CTA as small, muted text
208
+ links (13px), never as buttons.
209
+
210
+ ### Android
211
+
212
+ - **Close** is an `×` or `←` at the top-left in the Material tradition,
213
+ or wherever the design puts it; the **hardware/gesture back** dismisses
214
+ the paywall through the SDK, so never rely on your own back control
215
+ being the only way out.
216
+ - The status bar on a fullscreen paywall is drawn *over* the paywall
217
+ (the framework's top inset handles it); the navigation bar is *not* —
218
+ the SDK keeps the webview above it, so the bottom inset is 0 there and
219
+ a pinned CTA needs its own bottom padding (12–16px) rather than
220
+ relying on the inset to give it air.
221
+ - Buttons are fully rounded (Material 3 pill) or 12px, 48–56px tall;
222
+ labels 16px medium; Roboto through the system stack
223
+ (`system-ui, Roboto, sans-serif`).
224
+ - Ripple is the native press feedback; a scale-down press state is an
225
+ acceptable web stand-in and should be subtler (0.98) than on iOS.
226
+ - Copy differs: "Restore purchases" is fine on both, but "Cancel anytime
227
+ in Settings" is iOS-specific wording; say "in Google Play" or keep it
228
+ store-neutral when the paywall ships to both.
229
+
230
+ ### Web (a web funnel or a web-only paywall)
231
+
232
+ - No status bar, no home indicator, no SDK chrome: every inset is 0 and
233
+ the browser draws its own bars around the viewport. The framework's
234
+ wrapper is sized with `100dvh`, so a pinned CTA sits above Safari's
235
+ toolbar as it collapses; never size anything of your own with `100vh`.
236
+ - Keyboard focus is real here. Keep `:focus-visible` styles on inputs
237
+ and buttons; it is the one surface where you should not suppress them.
238
+ - Mouse exists: hover states are welcome, and the desktop layout centers
239
+ a phone-width column (`max-width: 28–34rem`) rather than stretching
240
+ cards across 1440px.
241
+ - Links may still go through `openUrl`, which is a plain navigation on
242
+ the web; keep the one call so the same page runs natively.
243
+
244
+ ## Touch
245
+
246
+ - Tap targets ≥ 44×44pt on iOS, ≥ 48×48dp on Android. A visually
247
+ shorter control (a slim segmented control) can trade height when the
248
+ design demands it — width and spacing must compensate, and the hit
249
+ area can be extended with padding or a pseudo-element.
250
+ - Haptics on every meaningful tap (`useHaptics()`): `light` for
251
+ navigation and CTAs, `selection` for choosing between options,
252
+ `success` on `transaction_complete`, `error` sparingly on failures.
253
+ iOS fires nothing on its own inside a webview.
254
+ - **Suppress focus rings on tap-driven controls** in native paywalls —
255
+ `:focus-visible` heuristics misfire in webviews and previews, drawing
256
+ outlines the design never asked for. Keep keyboard focus styles only
257
+ where a keyboard is real (web).
258
+ - On controls: `-webkit-tap-highlight-color: transparent`,
259
+ `touch-action: manipulation`, `user-select: none`; on the page,
260
+ `-webkit-user-select: none` except on copy the user might want to
261
+ select (legal text).
262
+ - Never disable a control to show "loading"; the store sheet is the
263
+ feedback (`usePurchase().isPurchasing` exists for the rare case that
264
+ genuinely needs it — a buy button is not one).
265
+ - The whole option row is the tap target, not just its radio; the whole
266
+ footer link is, not just its text.
267
+
268
+ ## Motion
269
+
270
+ - **Animate functional movement only** — elements that physically travel
271
+ between states: a segmented-control thumb sliding, a sheet presenting,
272
+ a progress bar filling, an accordion opening. Content that merely
273
+ changes (text, list rows, a price) updates in place; it does not fade,
274
+ slide, or stagger unless the design explicitly calls for it.
275
+ - **Press feedback is the baseline interaction**: a scale-down active
276
+ state (~0.96 iOS, ~0.98 Android; fast in ~80ms, settle out ~200ms) on
277
+ tappable elements, paired with a haptic. That is the whole story for
278
+ most controls.
279
+ - Entry animations are opt-in per design — and when a design has one, it
280
+ gates on presentation (`paywall_open`), never mount, because the SDK
281
+ preloads paywalls hidden (docs: `lifecycle`).
282
+ - Page transitions belong to the router (`push`, `slide`, `fade`,
283
+ `shift`, or a custom one on `[data-sw-route]`); never animate a page's
284
+ own root on navigation, or the two fight.
285
+ - Honor `prefers-reduced-motion` by collapsing durations to ~1ms; the
286
+ router already does for its transitions.
287
+ - Durations: 150–250ms for state changes, 300–500ms for spatial moves,
288
+ never longer than 600ms for anything the user waits on.
289
+
290
+ ## Type and rendering
291
+
292
+ - Default to the system font stack unless the design specifies brand
293
+ type — it is what makes a webview read as native. `-apple-system,
294
+ BlinkMacSystemFont, system-ui, "Segoe UI", Roboto, sans-serif` covers
295
+ every platform in one declaration.
296
+ - `-webkit-text-size-adjust: 100%` on `html`; antialiased smoothing;
297
+ body copy 15–17px (17 matches iOS body text; 16 Android); display sizes
298
+ with `clamp()` so they shrink on 320px and stop growing on tablets.
299
+ - Line lengths: 45–65 characters on phones; on tablets and desktop web,
300
+ cap the column, don't stretch the measure.
301
+ - Custom fonts are bytes every open pays for: **subset before shipping**
302
+ (latin-only Manrope ≈ 24 kB vs ≈ 90 kB for the family), ship **woff2**
303
+ only, and treat one family plus one mono as the budget. Compress and
304
+ size imagery for a phone screen for the same reason (docs: `assets`).
305
+ - Respect the user's text size where the design allows: `rem` for type
306
+ and the spacing tied to it, `px` for hairlines, radii and icon boxes.
307
+ The host reports `fontScale`/`preferredContentSizeCategory` if a design
308
+ needs to clamp at the extremes.
309
+
310
+ ## Color and dark mode
311
+
312
+ - Dark mode styles hang off the `:root.dark` class — never
313
+ `prefers-color-scheme` (docs: `lifecycle`). Design both palettes even
314
+ when the reference shows only one, and check both in the studio.
315
+ - Set `background` in config to the page background in both schemes; it
316
+ paints the native backdrop and the loading spinner, so the load is
317
+ seamless.
318
+ - Semantic tokens, never raw hex in components: `--bg`, `--fg`,
319
+ `--surface`, `--accent`, then muted/border/wash derived with
320
+ `color-mix()` so the dark palette needs only the base values.
321
+ - Contrast: body text ≥ 4.5:1, large display ≥ 3:1, on *both* schemes.
322
+ Muted text is the usual offender; 55% of the foreground is about the
323
+ floor on a light background.
324
+ - Never paint pure `#000` behind content in dark mode unless the design
325
+ is OLED-black on purpose; `#0d0f12`–`#1c1b19` is what native dark
326
+ screens use.
327
+
328
+ ## Images and media
329
+
330
+ - Ship hero imagery at 2× the logical size it renders, compressed, and
331
+ in a modern format; a 1290-wide PNG for a 393-wide hero is the wrong
332
+ file.
333
+ - A hero that bleeds to the top edge sits *under* the status bar on
334
+ purpose — `insets: { top: "none" }` in config, the layout's absolute
335
+ close button positioned from `--sw-safe-area-inset-top`, and a scrim on
336
+ the image so the bar's text stays legible in both schemes.
337
+ - Video and Lottie autoplay muted, loop only when the design loops, and
338
+ pause when the page is covered (`useIsFocused()`).
339
+
340
+ ## The pre-ship audit
341
+
342
+ Run it in the studio on every preset and both schemes; a paywall is not
343
+ done until every line passes.
344
+
345
+ - [ ] No `env()` and no `position: fixed` in the stylesheet; no layout or
346
+ page adds a safe-area inset of its own; nothing of yours is
347
+ `100dvh`/`100vh` tall; `insets` in config only where the design
348
+ bleeds, and then the chrome over the bleed reads
349
+ `--sw-safe-area-inset-*`.
350
+ - [ ] Close/back sits below the bar on iPhone SE (home button, 20px), an
351
+ island phone, a Pixel, an iPad; and clear of the cutout in landscape
352
+ where the app allows rotation.
353
+ - [ ] The primary CTA is pinned, full width, above the home indicator on
354
+ iOS and 12px+ above the bottom on Android; the last content row
355
+ scrolls clear of it.
356
+ - [ ] Nothing overflows horizontally at 320px; nothing is clipped at 667px
357
+ tall with the largest locale's copy.
358
+ - [ ] Both schemes designed and checked; `background` in `config.ts` and
359
+ `--sw-background` in CSS set to the same colors. Scroll past the end
360
+ of a page in both schemes: any white flash means `background` is
361
+ missing from config.
362
+ - [ ] Tap targets ≥ 44px; haptics on every meaningful tap; no focus rings
363
+ on tap controls natively; `aria-label` on icon buttons.
364
+ - [ ] No loading state on the buy button; unpriced state designed;
365
+ abandoned purchase handled.
366
+ - [ ] Copy is store-neutral where the paywall ships to both stores, and
367
+ every string, `aria-label`s included, comes from `messages/` through
368
+ `t()`, with prices interpolated and guarded, never in a catalog.
369
+ - [ ] Custom fonts subset and woff2; images sized for a phone.
370
+ - [ ] The configured presentation (`modal`, `drawer`, `popup`) checked as
371
+ a sheet, not only as fullscreen.
@@ -0,0 +1,83 @@
1
+ # Android source screens (Jetpack Compose and Views)
2
+
3
+ How the screen you are rebuilding was wired, what each construct becomes,
4
+ and what the user changes in the app once the rebuild is reviewed.
5
+
6
+ ## Reading the source
7
+
8
+ | In the source | Becomes |
9
+ | --- | --- |
10
+ | `Text("…")`, `stringResource(R.string.x)`, `getString(R.string.x)`, `android:text="@string/x"` in a layout | a `messages/en.ts` entry read with `t()`; the text is in `res/values/strings.xml`, and every `res/values-<locale>/strings.xml` becomes `messages/<locale>.ts` |
11
+ | `"$value"` / `"${expr}"` in a string, `%1$s` placeholders in a resource | a `t()` parameter |
12
+ | `painterResource(R.drawable.x)`, `android:src="@drawable/x"`, `app:srcCompat` | the file from `res/drawable*` copied into `assets/` (take the vector XML as SVG or the highest-density PNG) |
13
+ | `Icons.Default.X` / `Icons.Outlined.X` | an SVG in `assets/`; Material icons are not on the web unless you add them |
14
+ | `FontFamily(Font(R.font.x))`, `res/font` | the font file, subset, in `assets/`; `@font-face` in `theme.css` |
15
+ | `MaterialTheme.colorScheme`, `colorResource(R.color.x)`, `res/values/colors.xml`, `values-night` | `:root` / `:root.dark` variables, both themes from the resources |
16
+ | `isSystemInDarkTheme()`, `Configuration.UI_MODE_NIGHT_MASK` | `useColorScheme()` from the framework, or `:root.dark` CSS |
17
+ | `BillingClient.launchBillingFlow`, RevenueCat `purchaseWith` | `usePurchase()` with the slot from `config.ts` |
18
+ | `queryPurchasesAsync`, `restorePurchases` | `useActions().restore()` |
19
+ | `Intent(Intent.ACTION_VIEW, uri)`, `CustomTabsIntent`, `LocalUriHandler.openUri` (Play Store links included) | `useActions().openUrl(url)` |
20
+ | `ReviewManager.requestReviewFlow` / `launchReviewFlow` | `useActions().requestStoreReview()` |
21
+ | `POST_NOTIFICATIONS` via `RequestPermission()` / `rememberPermissionState` | `useActions().requestPermission("notification")` |
22
+ | `finish()`, `onBackPressedDispatcher`, `popBackStack()`, `onDismiss` | `useActions().close()` |
23
+ | `navController.navigate` to a destination in the same flow | a second route under `app/` and `useRouter().push()` |
24
+ | `startActivity` / `navigate` to something outside the flow (settings, a web view) | close and let the app's placement handler route; note it |
25
+ | `ViewModel`, `StateFlow`, `remember { }` state | React state; data the ViewModel fetched becomes a placement param or a user attribute the app sets before `register()` |
26
+ | `BuildConfig.VERSION_NAME`, `Build.VERSION` reads | `useDevice()` and `useVariables()`; the SDK reports app and OS versions |
27
+ | `WindowInsets`, `systemBarsPadding()`, `fitsSystemWindows` | nothing; the framework insets the screen (`layout.md`); Android's bottom inset is 0 because the SDK keeps the paywall above the navigation bar |
28
+
29
+ A Views screen splits across an Activity or Fragment, a layout XML under
30
+ `res/layout`, and `strings.xml`; the scan resolved `R.string` and
31
+ `@string/` references into the brief, but read the layout for structure and
32
+ `res/values-night` for the dark theme. A Compose screen keeps its structure in
33
+ the composable; follow `viewModel()` and `hiltViewModel()` to the data.
34
+
35
+ ## Wiring the app afterwards (the user does this, with you, after review)
36
+
37
+ This is a placement at a feature gate — the `superwall` skill's
38
+ `workflows/placements/` playbook (`superwall integrate --skill` includes it)
39
+ is the full playbook for
40
+ where and how to register, and the SDK docs are the reference for the
41
+ API; fetch them rather than working from memory:
42
+
43
+ ```bash
44
+ curl -sL https://superwall.com/docs/android/quickstart/feature-gating.md # Superwall.instance.register(placement) { }
45
+ curl -sL https://superwall.com/docs/android/llms.txt # every other page
46
+ ```
47
+
48
+ Where the app presented the screen:
49
+
50
+ ```kotlin
51
+ // before
52
+ if (needsUpdate) startActivity(Intent(this, UpdateRequiredActivity::class.java))
53
+
54
+ // after
55
+ if (needsUpdate) Superwall.instance.register("update_required")
56
+ ```
57
+
58
+ or in Compose:
59
+
60
+ ```kotlin
61
+ // before
62
+ if (needsUpdate) navController.navigate("update_required")
63
+
64
+ // after
65
+ LaunchedEffect(needsUpdate) {
66
+ if (needsUpdate) Superwall.instance.register("update_required")
67
+ }
68
+ ```
69
+
70
+ - The placement name is in the brief. Register it with the same condition
71
+ the app used, from UI code with an Activity in the foreground; pass what
72
+ the screen needs as `params` instead of reading it in the screen. Never
73
+ register inside a composable body.
74
+ - A screen the user must not dismiss (a forced update) is a **gated**
75
+ surface: the campaign's paywall is set to gated, and the `feature` lambda
76
+ passed to `register` only runs when the surface reports the user
77
+ through. Keep the app's own hard block until the surface is live.
78
+ - Create the campaign and placement on the dashboard for that placement
79
+ name and point it at the pushed surface; `superwall integrate` and the
80
+ `superwall` skill's `workflows/dashboard/` playbook cover it.
81
+ - Delete the native screen, its layout, drawables and strings once the
82
+ campaign is live and verified on a device. Keep a release with both for
83
+ one cycle if users on old builds still need the native one.