@superwall/cli 1.7.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (229) hide show
  1. package/README.md +192 -52
  2. package/dist/{setup-Bxj22rYi.js → apple-CSzNTGHM.js} +82 -76
  3. package/dist/auth.d.ts +4 -19
  4. package/dist/auth.js +4 -2
  5. package/dist/{actions-B7ym3oVS.js → billing-C3Q8DBU2.js} +98 -28
  6. package/dist/{bind-YrJvuRF9.js → bind-BumHTi9O.js} +38 -33
  7. package/dist/{build-DLoCW5Ri.js → build-Bpviiclc.js} +20 -26
  8. package/dist/client-BL0f_yGf.js +176 -0
  9. package/dist/{asc-Bf7zBbyS.js → client-BZ1UbpXz.js} +16 -15
  10. package/dist/config-BO1Y87kV.js +105 -0
  11. package/dist/create-BSfvpWoD.js +19 -0
  12. package/dist/{create-pkANt1Gs.js → create-BUcVG4Ab.js} +195 -169
  13. package/dist/{notification-url-DuKF2659.js → create-CfK3PeKA.js} +235 -539
  14. package/dist/doctor-BWqIYcMn.js +83 -0
  15. package/dist/{drivers-Qx9LxmRN.js → drivers-CPhdPkW5.js} +185 -172
  16. package/dist/entry.d.ts +0 -5
  17. package/dist/entry.js +28072 -1134
  18. package/dist/environment-eBXjELoN.js +58 -0
  19. package/dist/{existing-AVEfZu2A.js → existing-BltvQiX5.js} +12 -6
  20. package/dist/held-CPve03KJ.js +16 -0
  21. package/dist/held-DgnTFMl3.js +1112 -0
  22. package/dist/input-vi0bou04.js +42 -0
  23. package/dist/{integrate-brmhPG-S.js → integrate-BRsqoe01.js} +277 -254
  24. package/dist/log-NVhVe_oe.js +62 -0
  25. package/dist/login-BCEH5q0U.js +53 -0
  26. package/dist/login-BPOONe7n.js +16 -0
  27. package/dist/{login-Do4wFuLv.js → login-BbTIrCFT.js} +118 -55
  28. package/dist/lookup-rr1AkCJA.js +71 -0
  29. package/dist/migrate-C9X2Vz81.js +274 -0
  30. package/dist/notification-url-CV86qiKP.js +100 -0
  31. package/dist/{open-studio-DOw-6ydc.js → open-CcpXotHG.js} +34 -43
  32. package/dist/org-BQQDo7wm.js +35 -0
  33. package/dist/output-Ggzq5_-t.js +122 -0
  34. package/dist/paths-CRlU72cq.js +29 -0
  35. package/dist/playbook-DVMXN7fh.js +53 -0
  36. package/dist/{asc-products-9JXtDxI4.js → products-DH_fK9tY.js} +6 -6
  37. package/dist/promote-Da8xctzy.js +91 -0
  38. package/dist/push-BV-grvQg.js +22 -0
  39. package/dist/push-D6R9icWN.js +495 -0
  40. package/dist/registry-BYVD-_h6.js +10385 -0
  41. package/dist/{reports-CfJqoava.js → reports-D_qbl7_u.js} +7 -6
  42. package/dist/{resources-Bf9O1JNM.js → resources-DLON3-61.js} +162 -55
  43. package/dist/{run-DsVZ5snL.js → run-Co-BwhOg.js} +16 -22
  44. package/dist/scan-B88OlWOt.js +4 -0
  45. package/dist/{scan-zKsddO72.js → scan-CKuk-_6W.js} +48 -37
  46. package/dist/scope-DV22_Ufm.js +198 -0
  47. package/dist/screenshot-file-tVBfUEIi.js +16 -0
  48. package/dist/{selection-CxZoX4NT.js → selection-C2_KbLuo.js} +100 -51
  49. package/dist/server-C4f6ccUr.js +22 -0
  50. package/dist/{dev-DmB3XqaJ.js → server-D0d2oP-5.js} +86 -94
  51. package/dist/session-B-Uz0cQ7.js +40 -0
  52. package/dist/session-BuvArt1j.js +6 -0
  53. package/dist/session-C4rbE3VS.js +796 -0
  54. package/dist/skills/animate-onboarding/SKILL.md +467 -0
  55. package/dist/skills/animate-onboarding/references/engine.md +494 -0
  56. package/dist/skills/animate-onboarding/references/framework/Question.tsx +71 -0
  57. package/dist/skills/animate-onboarding/references/framework/README.md +40 -0
  58. package/dist/skills/animate-onboarding/references/framework/answers.ts +19 -0
  59. package/dist/skills/animate-onboarding/references/framework/flow.ts +80 -0
  60. package/dist/skills/animate-onboarding/references/framework/handoffs.ts +869 -0
  61. package/dist/skills/animate-onboarding/references/framework/layout.tsx +113 -0
  62. package/dist/skills/animate-onboarding/references/framework/motion.css +559 -0
  63. package/dist/skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
  64. package/dist/skills/animate-onboarding/references/handoffs.md +375 -0
  65. package/dist/skills/animate-onboarding/references/imageReady.ts +92 -0
  66. package/dist/skills/animate-onboarding/references/morphFrame.ts +356 -0
  67. package/dist/skills/animate-onboarding/references/performance.md +41 -0
  68. package/dist/skills/animate-onboarding/references/web-runtime/README.md +17 -0
  69. package/dist/skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
  70. package/dist/skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
  71. package/dist/skills/index.json +37 -0
  72. package/dist/skills/mobile-design/SKILL.md +447 -0
  73. package/dist/skills/mobile-design/references/responsive.md +162 -0
  74. package/dist/skills/onboarding-questions/SKILL.md +231 -0
  75. package/dist/skills/onboarding-questions/references/arpu-questions.md +139 -0
  76. package/dist/skills/onboarding-questions/references/craft.md +142 -0
  77. package/dist/skills/onboarding-questions/references/example-reflective.md +117 -0
  78. package/dist/skills/superwall/SKILL.md +82 -9
  79. package/dist/skills/superwall/references/api.md +153 -37
  80. package/dist/skills/superwall/references/apple-setup.md +316 -0
  81. package/dist/skills/superwall/references/asc.md +74 -38
  82. package/dist/skills/superwall/references/data-analytics.md +55 -21
  83. package/dist/skills/superwall/workflows/dashboard/playbook.md +3 -3
  84. package/dist/skills/superwall/workflows/dashboard/setup.md +8 -8
  85. package/dist/skills/superwall/workflows/migrate/adapty.md +6 -6
  86. package/dist/skills/superwall/workflows/migrate/playbook.md +4 -4
  87. package/dist/skills/superwall/workflows/migrate/qonversion.md +5 -5
  88. package/dist/skills/superwall/workflows/migrate/revenuecat.md +6 -6
  89. package/dist/skills/superwall/workflows/placements/android.md +2 -2
  90. package/dist/skills/superwall/workflows/placements/expo.md +2 -2
  91. package/dist/skills/superwall/workflows/placements/flutter.md +2 -2
  92. package/dist/skills/superwall/workflows/placements/ios.md +2 -2
  93. package/dist/skills/superwall/workflows/placements/playbook.md +2 -2
  94. package/dist/skills/superwall/workflows/placements/react-native.md +2 -2
  95. package/dist/skills/superwall/workflows/placements/strategy.md +2 -2
  96. package/dist/skills/superwall/workflows/review/playbook.md +1 -1
  97. package/dist/skills/superwall-editor/SKILL.md +61 -0
  98. package/dist/skills/superwall-editor/references/cli.md +135 -0
  99. package/dist/skills/superwall-editor/references/design.md +51 -0
  100. package/dist/skills/superwall-editor/references/native-elements.md +171 -0
  101. package/dist/skills/superwall-editor/references/workflow.md +65 -0
  102. package/dist/skills/superwall-editor/scripts/sw-editor.sh +662 -0
  103. package/dist/skills/superwall-framework/SKILL.md +85 -31
  104. package/dist/skills/superwall-framework/references/cli.md +58 -27
  105. package/dist/skills/superwall-framework/references/examples.md +4 -3
  106. package/dist/skills/superwall-framework/references/layout.md +64 -9
  107. package/dist/skills/superwall-framework/references/migrate-from-editor.md +1 -1
  108. package/dist/skills/superwall-framework/references/onboarding-state.md +245 -0
  109. package/dist/skills/wwdc/SKILL.md +22 -0
  110. package/dist/skills/wwdc/references/docs.md +52 -0
  111. package/dist/skills/wwdc/scripts/wwdc.sh +266 -0
  112. package/dist/skills-CLGJuMnF.js +14 -0
  113. package/dist/{skills-DPzlnfCK.js → skills-CZcpnEnG.js} +100 -122
  114. package/dist/{spawn-DSoTXy_j.js → spawn-DmmmHIP-.js} +14 -12
  115. package/dist/spinner-C2U6QBJ9.js +294 -0
  116. package/dist/storage-6h9vyiAz.js +31 -0
  117. package/dist/storage-CerJ5KLP.d.ts +16 -0
  118. package/dist/storekit-CK9JmM2D.js +16 -0
  119. package/dist/storekit-CinJra3V.js +47 -0
  120. package/dist/telemetry-DKyDhURo.js +56 -0
  121. package/dist/theme-DUsCh-Vd.js +25 -0
  122. package/dist/timing-BVxPrYq3.js +5 -0
  123. package/dist/{token-C0it-Xh7.js → token-DaxQgQkv.js} +6 -38
  124. package/dist/tools-skills/animate-onboarding/SKILL.md +467 -0
  125. package/dist/tools-skills/animate-onboarding/references/engine.md +494 -0
  126. package/dist/tools-skills/animate-onboarding/references/framework/Question.tsx +71 -0
  127. package/dist/tools-skills/animate-onboarding/references/framework/README.md +40 -0
  128. package/dist/tools-skills/animate-onboarding/references/framework/answers.ts +19 -0
  129. package/dist/tools-skills/animate-onboarding/references/framework/flow.ts +80 -0
  130. package/dist/tools-skills/animate-onboarding/references/framework/handoffs.ts +869 -0
  131. package/dist/tools-skills/animate-onboarding/references/framework/layout.tsx +113 -0
  132. package/dist/tools-skills/animate-onboarding/references/framework/motion.css +559 -0
  133. package/dist/tools-skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
  134. package/dist/tools-skills/animate-onboarding/references/handoffs.md +375 -0
  135. package/dist/tools-skills/animate-onboarding/references/imageReady.ts +92 -0
  136. package/dist/tools-skills/animate-onboarding/references/morphFrame.ts +356 -0
  137. package/dist/tools-skills/animate-onboarding/references/performance.md +41 -0
  138. package/dist/tools-skills/animate-onboarding/references/web-runtime/README.md +17 -0
  139. package/dist/tools-skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
  140. package/dist/tools-skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
  141. package/dist/tools-skills/mobile-design/SKILL.md +447 -0
  142. package/dist/tools-skills/mobile-design/references/responsive.md +162 -0
  143. package/dist/tools-skills/onboarding-questions/SKILL.md +231 -0
  144. package/dist/tools-skills/onboarding-questions/references/arpu-questions.md +139 -0
  145. package/dist/tools-skills/onboarding-questions/references/craft.md +142 -0
  146. package/dist/tools-skills/onboarding-questions/references/example-reflective.md +117 -0
  147. package/dist/tools-skills/superwall/SKILL.md +263 -0
  148. package/dist/tools-skills/superwall/references/api.md +303 -0
  149. package/dist/tools-skills/superwall/references/asa.md +166 -0
  150. package/dist/tools-skills/superwall/references/asc.md +95 -0
  151. package/dist/tools-skills/superwall/references/dashboard-links.md +57 -0
  152. package/dist/tools-skills/superwall/references/data-analytics.md +896 -0
  153. package/dist/tools-skills/superwall/references/docs.md +51 -0
  154. package/dist/tools-skills/superwall/references/sdk-integration.md +104 -0
  155. package/dist/tools-skills/superwall/references/sdk-source.md +18 -0
  156. package/dist/tools-skills/superwall/workflows/dashboard/playbook.md +76 -0
  157. package/dist/tools-skills/superwall/workflows/dashboard/setup.md +100 -0
  158. package/dist/tools-skills/superwall/workflows/integrate/android.md +292 -0
  159. package/dist/tools-skills/superwall/workflows/integrate/expo.md +272 -0
  160. package/dist/tools-skills/superwall/workflows/integrate/flutter.md +285 -0
  161. package/dist/tools-skills/superwall/workflows/integrate/ios.md +314 -0
  162. package/dist/tools-skills/superwall/workflows/integrate/playbook.md +83 -0
  163. package/dist/tools-skills/superwall/workflows/integrate/react-native.md +246 -0
  164. package/dist/tools-skills/superwall/workflows/migrate/adapty.md +229 -0
  165. package/dist/tools-skills/superwall/workflows/migrate/playbook.md +78 -0
  166. package/dist/tools-skills/superwall/workflows/migrate/qonversion.md +227 -0
  167. package/dist/tools-skills/superwall/workflows/migrate/revenuecat.md +414 -0
  168. package/dist/tools-skills/superwall/workflows/placements/android.md +175 -0
  169. package/dist/tools-skills/superwall/workflows/placements/expo.md +161 -0
  170. package/dist/tools-skills/superwall/workflows/placements/flutter.md +139 -0
  171. package/dist/tools-skills/superwall/workflows/placements/ios.md +165 -0
  172. package/dist/tools-skills/superwall/workflows/placements/playbook.md +69 -0
  173. package/dist/tools-skills/superwall/workflows/placements/react-native.md +145 -0
  174. package/dist/tools-skills/superwall/workflows/placements/strategy.md +222 -0
  175. package/dist/tools-skills/superwall/workflows/review/android.md +120 -0
  176. package/dist/tools-skills/superwall/workflows/review/expo.md +100 -0
  177. package/dist/tools-skills/superwall/workflows/review/flutter.md +99 -0
  178. package/dist/tools-skills/superwall/workflows/review/ios.md +108 -0
  179. package/dist/tools-skills/superwall/workflows/review/playbook.md +70 -0
  180. package/dist/tools-skills/superwall/workflows/review/react-native.md +100 -0
  181. package/dist/tools-skills/superwall-editor/SKILL.md +113 -0
  182. package/dist/tools-skills/superwall-editor/references/cli.md +135 -0
  183. package/dist/tools-skills/superwall-editor/references/design.md +51 -0
  184. package/dist/tools-skills/superwall-editor/references/native-elements.md +171 -0
  185. package/dist/tools-skills/superwall-editor/references/workflow.md +65 -0
  186. package/dist/tools-skills/superwall-editor/scripts/sw-editor.sh +662 -0
  187. package/dist/tools-skills/wwdc/SKILL.md +22 -0
  188. package/dist/tools-skills/wwdc/references/docs.md +52 -0
  189. package/dist/tools-skills/wwdc/scripts/wwdc.sh +266 -0
  190. package/dist/tools.d.ts +96 -0
  191. package/dist/tools.js +11360 -0
  192. package/dist/ui-D_qf3Gvw.js +53 -0
  193. package/dist/upgrade-DPo0a4Es.js +117 -0
  194. package/dist/upgrade-ffseQDMx.js +7 -0
  195. package/package.json +10 -5
  196. package/dist/api-CZzirVMj.js +0 -151
  197. package/dist/api-output-aJNw7Syy.js +0 -20
  198. package/dist/app-DH6U8yuI.js +0 -190
  199. package/dist/asa-C-sQzPPn.js +0 -1194
  200. package/dist/asc-1ZBJ6DwS.js +0 -778
  201. package/dist/auth-YRhlV3DE.js +0 -140
  202. package/dist/billing-CCYHdApx.js +0 -80
  203. package/dist/bundle-id-CKxl_026.js +0 -121
  204. package/dist/command-CMIz81Da.js +0 -301
  205. package/dist/dev-DZy6pOnB.js +0 -22
  206. package/dist/doctor-H-hf-Yww.js +0 -88
  207. package/dist/feedback-CKf-rpBW.js +0 -152
  208. package/dist/hosted-CXe9TrWx.js +0 -32
  209. package/dist/migrate-C9ERDR6y.js +0 -284
  210. package/dist/org-sj7uyvp-.js +0 -40
  211. package/dist/output-C4o2gJ1K.js +0 -146
  212. package/dist/params-l3CrvRtR.js +0 -51
  213. package/dist/pipeline-BqzqZhX1.js +0 -977
  214. package/dist/print-skill-ZojRSybs.js +0 -74
  215. package/dist/promote-BG8X4Nv_.js +0 -88
  216. package/dist/publish-sxLh-G4G.js +0 -35
  217. package/dist/push-bQ6Vxtg8.js +0 -35
  218. package/dist/query-_FbybaH-.js +0 -53
  219. package/dist/resource-CGIwSd29.js +0 -323
  220. package/dist/revenue-provider-ebsRINY8.js +0 -100
  221. package/dist/scope-BvzD-kO4.js +0 -223
  222. package/dist/skills-D_R-lEsK.js +0 -64
  223. package/dist/spinner-TWa0hia6.js +0 -18
  224. package/dist/storekit-Cj9Cpjcz.js +0 -29
  225. package/dist/telemetry-DeA1mvnT.js +0 -169
  226. package/dist/ui-Dy0b-9L8.js +0 -27738
  227. package/dist/update-B2fWIc4q.js +0 -59
  228. package/dist/upgrade-BmzkTKrh.js +0 -72
  229. /package/dist/{devtools-8EgLo86w.js → devtools-pBl_vt03.js} +0 -0
@@ -0,0 +1,135 @@
1
+ # sw-editor.sh CLI reference
2
+
3
+ The CLI is a thin bash wrapper over the Superwall editor relay. It speaks the same public HTTP surface the MCP gateway uses, authenticated by a short-lived controller token issued during attach. Tool definitions come from the browser. **Never hardcode tool names; always run `tools` first** when unsure.
4
+
5
+ ## Prerequisites
6
+
7
+ - `curl` and `jq` installed (both present by default on macOS/Linux, or one `brew install jq` away).
8
+ - For `expose`: a `SUPERWALL_API_KEY` with read access to the paywall.
9
+ - For manual `attach`: a live browser editor session with a visible pairing code.
10
+
11
+ ## Environment
12
+
13
+ | Variable | Default | Purpose |
14
+ | --- | --- | --- |
15
+ | `SUPERWALL_EDITOR_BASE_URL` | `https://mcp.superwall.com` | Relay base URL. Override for custom environments. |
16
+ | `SUPERWALL_EDITOR_WEB_URL` | `https://superwall.com/editor/` | Editor URL used by `expose`. Override only when the user provides a custom editor URL. |
17
+ | `SUPERWALL_API_KEY` | unset | Org API key used by `expose` / `wait-expose`. Also read from this skill `.env`, sibling `superwall/.env`, or `~/.superwall-cli/.env`. |
18
+ | `SUPERWALL_STATE_DIR` | `$PWD/.superwall` | Where to store attachment state. |
19
+
20
+ ## State file
21
+
22
+ `${SUPERWALL_STATE_DIR}/state.json`, chmod 600. Holds `{sessionId, controllerToken, baseUrl, transportSessionId, attachedAt}`. Treat it as an opaque implementation detail. Never read `sessionId` out of it when communicating with the user, and never echo `controllerToken`. The CLI's `status` and `whoami` commands already strip these.
23
+
24
+ ## Commands
25
+
26
+ ### Agent identity
27
+
28
+ Both `attach` and `expose` require `--agent-name`. Accepted slugs are
29
+ `superwall`, `claude`, `codex`, `cursor`, `opencode`, `windsurf`, `kilocode`,
30
+ `chatgpt`, `openwebui`, and `other`. Use `other` for Grok Build, Muse Code, or
31
+ any unlisted agent. The script sends the corresponding display name to the
32
+ editor so the user can see who is attached.
33
+
34
+ ### expose
35
+
36
+ ```
37
+ sw-editor.sh expose --application-id <id> --paywall-id <id> --agent-name <name> [--open] [--wait]
38
+ ```
39
+
40
+ Creates a short-lived editor launch URL through the relay API. Opening the URL loads the editor for that paywall and auto-exposes the browser session; the user only completes normal browser authorization if prompted. Launch creation and polling require `SUPERWALL_API_KEY`; the browser-side ready call uses only the short-lived launch token embedded in the URL. `--agent-name` is required so the editor can show which agent is attached.
41
+
42
+ Use `--open --wait` for the smoothest flow. The CLI opens the browser, polls the launch, and writes controller state once the editor connects.
43
+
44
+ Example:
45
+
46
+ ```bash
47
+ sw-editor.sh expose --application-id 5 --paywall-id 28 --agent-name codex --open --wait
48
+ ```
49
+
50
+ ### wait-expose
51
+
52
+ ```
53
+ sw-editor.sh wait-expose <launch-id> [--timeout <seconds>]
54
+ ```
55
+
56
+ Polls a launch created by `expose` until the browser editor auto-exposes and the CLI receives a controller token. Useful when `expose` was run without `--wait`.
57
+
58
+ ### attach
59
+
60
+ ```
61
+ sw-editor.sh attach <pairing-code> --agent-name <name>
62
+ ```
63
+
64
+ Exchange the single-use pairing code for a controller token and cache it locally. The pairing code is consumed on success; if you fail (bad code, expired code, editor disconnected, another client attached), the user needs to refresh the editor UI for a new one.
65
+
66
+ On success the response carries the browser's full tool list, but the CLI prints only a count. Run `tools` for details.
67
+
68
+ ### tools
69
+
70
+ ```
71
+ sw-editor.sh tools
72
+ ```
73
+
74
+ Prints `{toolDefinitions: [{name, description, parameters}], metadata}` as JSON. Always run this before calling an unfamiliar tool. Tool shapes can change when the editor ships.
75
+
76
+ ### call
77
+
78
+ ```
79
+ sw-editor.sh call <tool-name> [--args '<json>']
80
+ ```
81
+
82
+ Invokes a tool in the browser. `--args` must be valid JSON (defaults to `{}`). Prints the `CallToolResult` (`{content, isError, ...}`). Exits 1 when `isError: true`.
83
+
84
+ Example:
85
+
86
+ ```bash
87
+ sw-editor.sh call write_html --args '{"targetNodeId": "page:page", "position": "append", "html": "<h1>Hello</h1>"}'
88
+ ```
89
+
90
+ ### status
91
+
92
+ ```
93
+ sw-editor.sh status
94
+ ```
95
+
96
+ Prints session status (browser connectivity, pairing code freshness, metadata). Internal IDs are stripped from the output.
97
+
98
+ ### release
99
+
100
+ ```
101
+ sw-editor.sh release
102
+ ```
103
+
104
+ Notifies the relay, clears local state. Call when the user says they're done, or before attaching to a different session.
105
+
106
+ ### whoami
107
+
108
+ ```
109
+ sw-editor.sh whoami
110
+ ```
111
+
112
+ Prints `{attached, baseUrl, attachedAt}` without internal identifiers. Useful for confirming whether a session is cached.
113
+
114
+ ## Attach / call / release flow
115
+
116
+ ```
117
+ ┌────────────────┐ pairingCode ┌────────────────┐
118
+ │ Editor UI │ ────────────► │ User │
119
+ │ (browser) │ └────────────────┘
120
+ └────────────────┘ │ reads code aloud
121
+ ▼
122
+ ┌────────────────┐ POST /editor-sessions/claim
123
+ │ sw-editor.sh │ ────────────────────────┐
124
+ │ attach │ │
125
+ └────────────────┘ ▼
126
+ ▲ ┌───────────────┐
127
+ controllerToken │ Relay DO │
128
+ │ │ (per session)│
129
+ ┌────────────────┐ └───────────────┘
130
+ │ sw-editor.sh │ Authorization: Bearer ▲
131
+ │ call/tools/… │ ──────────────────────┘
132
+ └────────────────┘
133
+ ```
134
+
135
+ The controller token dies when the session expires or when `release` is called. Re-attach with a fresh pairing code, or create a fresh `expose` launch, to get a new token.
@@ -0,0 +1,51 @@
1
+ # Design Guide
2
+
3
+ Paywalls are purchase screens. Flows are multi-page experiences (onboardings, surveys, web2app retargeting). Both must feel polished, trustworthy, and optimized for their goal.
4
+
5
+ ## Review Checkpoints
6
+
7
+ After every 2-3 modifications, call `get_screenshot` and evaluate each:
8
+
9
+ - **Spacing**: Uneven gaps, cramped groups, areas that feel unintentionally empty
10
+ - **Typography**: Text too small, poor hierarchy between heading/body/caption
11
+ - **Contrast**: Low contrast text, elements blending into backgrounds
12
+ - **Alignment**: Elements that should share a lane but don't
13
+ - **Clipping**: Content cut off at edges (fix with `update_styles`, set dimension to `fit-content`)
14
+ - **CTA Clarity**: Purchase button must have the strongest visual weight
15
+
16
+ Summarize each into a one-line verdict. Fix issues before moving on.
17
+
18
+ ## Design Brief
19
+
20
+ Before writing HTML, generate:
21
+
22
+ 1. Color palette: 4-5 hex values (background, surface, text, accent, secondary)
23
+ 2. Type scale: headline/body/caption sizes and weights
24
+ 3. Spacing rhythm: section gaps, element gaps, padding
25
+ 4. One sentence visual direction
26
+ 5. CTA style: color, shape, text
27
+
28
+ ## Typography Hierarchy
29
+
30
+ | Level | Size | Weight | Purpose |
31
+ |-------|------|--------|---------|
32
+ | Hero | 28-36px | 700-800 | Short, punchy |
33
+ | Subheadline | 16-18px | 400-500 | 1-2 sentence value prop |
34
+ | Features | 14-16px | 400 | Benefit descriptions |
35
+ | Price | 20-28px | 700 | Clear currency + period |
36
+ | CTA | 16-18px | 600-700 | Action verb ("Start Free Trial") |
37
+ | Legal | 12px | 400 | Muted, cancellation terms |
38
+
39
+ ## Conversion Principles
40
+
41
+ - **One strong accent** for the CTA beats multiple colors. Build palette from neutrals first.
42
+ - **CTA buttons**: full-width, 16px+ vertical padding, strong background, clear text.
43
+ - **Trust signals**: trial duration, guarantee, cancellation policy, social proof.
44
+ - **Avoid clutter**: max 3 pricing options, 5-7 feature items.
45
+ - **Placeholder content**: realistic pricing ($4.99/week, $12.99/month, $49.99/year).
46
+
47
+ ## Build Cadence
48
+
49
+ - One visual group per `write_html` call (header, feature row, pricing card, CTA, footer).
50
+ - A full paywall = 5+ separate calls. Never batch everything into one.
51
+ - Screenshot every 2-3 modifications. The user watches in real-time.
@@ -0,0 +1,171 @@
1
+ # Superwall Native Elements Guide
2
+
3
+ When using `write_html`, prefer native `sw-*` elements over generic HTML whenever the UI represents a semantic control. Native elements stay editable, bindable, and tool-aware inside the editor.
4
+
5
+ ## When to use which element
6
+
7
+ | UI pattern | Element | Key attributes |
8
+ |------------|---------|---------------|
9
+ | Selectable options, surveys, radio/checkbox cards | `<sw-multiple-choice>` | `selection-mode`, `<sw-option>`, `<sw-choice-item>` |
10
+ | Dots, pills, progress bars, step indicators | `<sw-indicator>` | `current-index`, `total-items`, `<sw-indicator-item>` |
11
+ | Drawers, bottom sheets | `<sw-drawer>` | `dismissible`, `detents`, `open-state` |
12
+ | Date/time/custom wheel pickers | `<sw-picker>` | `picker-type`, `picker-style`, `components`, `columns` |
13
+ | Animations | `<sw-lottie>` | `src`, `autoplay`, `loop`, `speed` |
14
+ | Multi-page flows | `<sw-navigation>` | `transition`, `<sw-page>` children |
15
+
16
+ ## Native-first rules
17
+
18
+ - Selectable answers, survey options, radio rows, checkbox rows, tappable choice cards: use `<sw-multiple-choice>`.
19
+ - Dots, pills, segmented progress, linear progress bars, onboarding progress: use `<sw-indicator>`.
20
+ - Drawers, bottom sheets, slide-over panels: use `<sw-drawer>`.
21
+ - Date, time, or custom wheel pickers: use `<sw-picker>`.
22
+ - Lottie animations: use `<sw-lottie>`.
23
+ - Multi-page onboarding or paywall flows: use `<sw-navigation>` with `<sw-page>` children, then wire entry/routes with the dedicated navigation tools.
24
+ - Use plain HTML for layout, text, and visuals only when there is no native element that represents the control.
25
+
26
+ ## Multiple choice
27
+
28
+ Use `<sw-multiple-choice>` for any selectable list. Supply choices with direct `<sw-option>` children.
29
+
30
+ ```html
31
+ <sw-multiple-choice selection-mode="single">
32
+ <sw-option label="Cook at home" value="cook-home" />
33
+ <sw-option label="Order delivery" value="delivery" />
34
+ <sw-option label="Eat out" value="eat-out" />
35
+ </sw-multiple-choice>
36
+ ```
37
+
38
+ If you need a custom repeated row layout, provide at most one direct `<sw-choice-item>` template child:
39
+
40
+ ```html
41
+ <sw-multiple-choice selection-mode="single" style="gap:12px;">
42
+ <sw-option label="Starter" value="starter" />
43
+ <sw-option label="Pro" value="pro" />
44
+ <sw-choice-item style="background-color:#ffffff;border-radius:16px;padding:18px 20px;" />
45
+ </sw-multiple-choice>
46
+ ```
47
+
48
+ Important:
49
+
50
+ - `<sw-option>` is only valid as a direct child of `<sw-multiple-choice>`.
51
+ - `<sw-multiple-choice>` accepts at most one direct `<sw-choice-item>`.
52
+ - Do not create one `<sw-choice-item>` per option.
53
+ - Any visual or content difference between options should be implemented by dynamically changing child nodes inside the single `<sw-choice-item>` template.
54
+ - If the design has selected and unselected states, implement both states explicitly. Selected cards, checkmarks, highlights, borders, icons, and labels should respond correctly to `state:self.isSelected`, and the unselected fallback should also be defined.
55
+
56
+ ### Per-choice specialization
57
+
58
+ Per-choice icons, subtitles, colors, badges, visibility, and other specialized content are supported through the single template child. Create one `<sw-choice-item>` template, place child SVG/text/container nodes inside it, then call `set_dynamic_value` on those child nodes using self-scoped template state.
59
+
60
+ Use:
61
+
62
+ - `state:self.value` to branch by the option value.
63
+ - `state:self.label` to branch by label text.
64
+ - `state:self.index` to branch by position.
65
+ - `state:self.isSelected` to branch by selected state.
66
+ - `state:self.isFirst` and `state:self.isLast` for edge-specific layout tweaks.
67
+
68
+ ```html
69
+ <sw-multiple-choice selection-mode="single" style="gap:16px;">
70
+ <sw-option label="Improve sleep" value="sleep" />
71
+ <sw-option label="Improve focus" value="focus" />
72
+ <sw-option label="Regulate emotions" value="emotions" />
73
+ <sw-option label="Enhance energy" value="energy" />
74
+ <sw-choice-item style="border-radius:20px;padding:20px;">
75
+ <svg width="40" height="40" viewBox="0 0 40 40"></svg>
76
+ <p>Improve sleep</p>
77
+ <p>Subtitle</p>
78
+ <div style="display:none;">Popular</div>
79
+ </sw-choice-item>
80
+ </sw-multiple-choice>
81
+ ```
82
+
83
+ Then use `set_dynamic_value` on whatever child properties need specialization (SVG src, subtitle text, background color, badge visibility).
84
+
85
+ Never solve per-option specialization by creating multiple `sw-choice-item` nodes.
86
+
87
+ ## Indicator
88
+
89
+ Use `<sw-indicator>` for dots, segments, or progress bars. Style the single repeated `<sw-indicator-item>` template.
90
+
91
+ ```html
92
+ <sw-indicator current-index="1" total-items="3" style="width:100%;gap:8px;">
93
+ <sw-indicator-item style="height:6px;border-radius:3px;" />
94
+ </sw-indicator>
95
+ ```
96
+
97
+ Important:
98
+
99
+ - `<sw-indicator>` accepts at most one direct `<sw-indicator-item>`.
100
+ - Do not create one `<sw-indicator-item>` per segment manually.
101
+
102
+ Self-scoped fields: `state:self.index`, `state:self.isCurrent`, `state:self.isCompleted`, `state:self.isFirst`, `state:self.isLast`.
103
+
104
+ ## Drawer
105
+
106
+ ```html
107
+ <sw-drawer dismissible="true" detents="0.25,0.5,1" background-interactive="false">
108
+ <p>Drawer content</p>
109
+ </sw-drawer>
110
+ ```
111
+
112
+ Use `open-state="state:..."` when the drawer should bind to an external state.
113
+
114
+ ## Picker
115
+
116
+ ```html
117
+ <sw-picker
118
+ picker-type="date"
119
+ picker-style="wheel"
120
+ components="date-and-time"
121
+ minute-interval="5"
122
+ min-date="today"
123
+ max-date="+1 month"
124
+ />
125
+
126
+ <sw-picker
127
+ picker-type="weight-kg"
128
+ columns='[{"source":"range","id":"weight","min":10,"max":250,"step":1,"labelSuffix":" kg","width":96}]'
129
+ output-template="{weight}"
130
+ />
131
+ ```
132
+
133
+ Supported `components`: `date`, `date-and-time`, `time`, `time-list`.
134
+ Custom picker types are `custom`, `number`, `age`, `weight-kg`, `weight-lb`, `height-cm`, `height-imperial`, and `duration`. They use `picker-style="wheel"`, optional JSON `columns`, and optional `output-template`. Columns auto-size to the widest option unless a numeric `width` is provided. Output templates can use `{columnId}` or `{columnId.label}`.
135
+
136
+ ## Navigation
137
+
138
+ Use `<sw-navigation>` for multi-page flows. Each `<sw-page>` child becomes one page.
139
+
140
+ ```html
141
+ <sw-navigation transition="push">
142
+ <sw-page data-name="Welcome">
143
+ <p>Welcome</p>
144
+ </sw-page>
145
+ <sw-page data-name="Plans">
146
+ <p>Choose a plan</p>
147
+ </sw-page>
148
+ </sw-navigation>
149
+ ```
150
+
151
+ After creating structure, use navigation tools:
152
+ 1. `get_navigation_pages` to discover page IDs
153
+ 2. `set_navigation_entry_connection` for the starting page
154
+ 3. `set_navigation_connection` for page-to-page wiring
155
+ 4. `set_click_behavior` with `navigate-page` direction `next`/`back`
156
+
157
+ Do not encode routes in HTML. Do not pass target page IDs in click behavior.
158
+
159
+ ## Lottie
160
+
161
+ ```html
162
+ <sw-lottie src="https://example.com/animation.json" autoplay loop speed="1.0" />
163
+ ```
164
+
165
+ ## Constraints
166
+
167
+ - Leaf nodes (text, image, input, video, svg, lottie, picker) cannot contain children.
168
+ - `choice-item` is only valid as the single direct template child of `multiple-choice`.
169
+ - `indicator-item` is only valid as the single direct template child of `indicator`.
170
+ - Self-scoped template state is only valid inside `choice-item` or `indicator-item` subtrees.
171
+ - If a screenshot visually resembles a native control, prefer the native control.
@@ -0,0 +1,65 @@
1
+ # Superwall Paywall Workflow Guide
2
+
3
+ ## Recommended order of operations
4
+
5
+ 1. Decide theming first.
6
+ 2. If the design needs reusable colors, create only the style variables actually needed.
7
+ 3. Build the paywall structure with `write_html` and native elements where appropriate.
8
+ 4. Add products only if the paywall actually needs them.
9
+ 5. If the paywall is a multi-page flow, build it page by page rather than trying to create and polish every page at once.
10
+ 6. Connect the pages after the structure exists.
11
+ 7. Wire tap behaviors after the structure and flow wiring are in place.
12
+ 8. Add any remaining custom logic, dynamic values, and product-driven behavior last.
13
+
14
+ ## Writing new designs
15
+
16
+ 1. Generate a design brief (color palette, type scale, spacing, direction, CTA style).
17
+ 2. Call `get_basic_info` to find the page root.
18
+ 3. Add content in small pieces -- one visual group per `write_html` call.
19
+ 4. Use `duplicate_nodes` combined with `update_styles` and `set_text_content` for repeated elements.
20
+ 5. Screenshot and review after every 2-3 additions.
21
+
22
+ ## Editing existing designs
23
+
24
+ 1. Use `get_subtree` to understand the current structure.
25
+ 2. Use `get_screenshot` to see the current visual state.
26
+ 3. Prefer semantic edits over `write_html`:
27
+ - `update_styles` for visual changes
28
+ - `set_text_content` for copy changes
29
+ - `move_nodes` for reparenting/repositioning
30
+ - `reorder_children` for sibling order
31
+ - `duplicate_nodes` to create variations of existing elements
32
+ - `find_replace` for bulk changes (like updating all colors)
33
+ 4. Use `get_style_token_usage` before changing/deleting tokens.
34
+ 5. Use `bind_style_tokens` when nodes should adopt reusable interface theme tokens.
35
+ 6. Use `get_products` before working with product-specific pricing UI.
36
+ 7. Use `get_variables` before building interactive logic.
37
+ 8. Use `set_dynamic_value` for conditional styles/props. Cases are ordered, first match wins, empty `rules: []` as fallback.
38
+ 9. Use `set_click_behavior` for tap behavior (purchase, close, restore, open-url, navigate-page, set-state, etc.).
39
+ 10. Use `write_html` only for genuinely new structure or intentional section replacement.
40
+ 11. Screenshot and verify after changes.
41
+
42
+ ## Working status indicators
43
+
44
+ Always use `start_working_on_nodes` before modifications and `finish_working_on_nodes` when done. Use `page:page` for the entire paywall, or specific node IDs for targeted sections.
45
+
46
+ ## Best practices
47
+
48
+ - Prefer native elements over manual `div` recreations.
49
+ - Confirm light mode, dark mode, or both before creating style variables.
50
+ - Create reusable style variables only for colors that are actually reused.
51
+ - Do not create unused style variables.
52
+ - Build first, then specialize. Add dynamic behavior after the base structure exists.
53
+ - For multi-page flows, build and verify one page at a time.
54
+ - Add tap behaviors explicitly. Do not assume interactive elements are wired just because they are visible.
55
+ - Connect pages before wiring tappable elements that move through the flow.
56
+ - Set haptics intentionally for interactive elements.
57
+ - Prefer a subtle shrink/press animation for buttons and tappable controls.
58
+
59
+ ## Product and eligibility logic
60
+
61
+ - If the paywall uses products with trials, check whether introductory offer eligibility matters.
62
+ - Use `products.hasIntroductoryOffer` when the paywall should show different copy, styling, or branching depending on trial eligibility.
63
+ - Ensure the user does not see trial-specific messaging when they are not eligible.
64
+ - Product variables use Liquid syntax: `{{ products.<referenceName>.<variable> }}`.
65
+ - `get_products` returns `paywallProducts` (on the paywall) with `liquidPrefix` showing the exact Liquid path.