@superwall/cli 1.7.0 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +192 -52
- package/dist/{setup-Bxj22rYi.js → apple-CkKlHBZ9.js} +82 -76
- package/dist/auth.d.ts +4 -19
- package/dist/auth.js +4 -2
- package/dist/{actions-B7ym3oVS.js → billing-XCZU_T46.js} +98 -28
- package/dist/{bind-YrJvuRF9.js → bind-drne__Ys.js} +38 -33
- package/dist/{build-DLoCW5Ri.js → build-Gpdq5QXP.js} +20 -26
- package/dist/{asc-Bf7zBbyS.js → client-BZ1UbpXz.js} +16 -15
- package/dist/client-DP6Rc0t_.js +176 -0
- package/dist/config-BO1Y87kV.js +105 -0
- package/dist/{notification-url-DuKF2659.js → create-BBrtgUgS.js} +235 -539
- package/dist/{create-pkANt1Gs.js → create-Cwc3SRWJ.js} +194 -168
- package/dist/create-Yvf2gStM.js +19 -0
- package/dist/doctor-C9ldpPFC.js +83 -0
- package/dist/{drivers-Qx9LxmRN.js → drivers-DNrx4LWA.js} +185 -172
- package/dist/entry.d.ts +0 -5
- package/dist/entry.js +28073 -1134
- package/dist/environment-DF1qKlny.js +58 -0
- package/dist/{existing-AVEfZu2A.js → existing-78LWSsqS.js} +12 -6
- package/dist/held-Cy8Wl4D1.js +1112 -0
- package/dist/held-Ddw1XSsr.js +16 -0
- package/dist/input-vi0bou04.js +42 -0
- package/dist/{integrate-brmhPG-S.js → integrate-DcJhpXy8.js} +277 -254
- package/dist/kinds-GFXB3sYu.js +11 -0
- package/dist/log-NVhVe_oe.js +62 -0
- package/dist/login-B2TsCE2H.js +53 -0
- package/dist/login-BoBe8Psl.js +16 -0
- package/dist/{login-Do4wFuLv.js → login-D0lh3_JI.js} +118 -55
- package/dist/lookup-D-nmmAbw.js +71 -0
- package/dist/migrate-Cfec564E.js +274 -0
- package/dist/notification-url-YDbq6FMA.js +100 -0
- package/dist/{open-studio-DOw-6ydc.js → open-Ba2vBl1_.js} +34 -43
- package/dist/org-D0g_q3mv.js +35 -0
- package/dist/output-Ggzq5_-t.js +122 -0
- package/dist/paths-DxSLdpOI.js +29 -0
- package/dist/playbook-DIeb7hne.js +53 -0
- package/dist/{asc-products-9JXtDxI4.js → products-DH_fK9tY.js} +6 -6
- package/dist/promote-COD4fYdz.js +91 -0
- package/dist/push-CncywhkQ.js +482 -0
- package/dist/push-CtD4FZQV.js +22 -0
- package/dist/registry-DSrosOYs.js +10228 -0
- package/dist/{reports-CfJqoava.js → reports-DdPq4blM.js} +7 -6
- package/dist/{resources-Bf9O1JNM.js → resources-Dqr01Dep.js} +150 -55
- package/dist/{run-DsVZ5snL.js → run-C9qg_QlC.js} +16 -22
- package/dist/scan-Cv5uOwVY.js +4 -0
- package/dist/{scan-zKsddO72.js → scan-DLrsrFS9.js} +48 -37
- package/dist/scope-V336uz8j.js +198 -0
- package/dist/screenshot-file-0UETadF8.js +16 -0
- package/dist/{selection-CxZoX4NT.js → selection-Rdw-ZUoG.js} +94 -51
- package/dist/send-BxD9yf6F.js +150 -0
- package/dist/{dev-DmB3XqaJ.js → server-D0tGG8C4.js} +82 -92
- package/dist/server-z1LH94R_.js +22 -0
- package/dist/session-1AV_Bs_d.js +6 -0
- package/dist/session-CFAmMhem.js +40 -0
- package/dist/session-D_nEWKXT.js +768 -0
- package/dist/skills/animate-onboarding/SKILL.md +467 -0
- package/dist/skills/animate-onboarding/references/engine.md +494 -0
- package/dist/skills/animate-onboarding/references/framework/Question.tsx +71 -0
- package/dist/skills/animate-onboarding/references/framework/README.md +40 -0
- package/dist/skills/animate-onboarding/references/framework/answers.ts +19 -0
- package/dist/skills/animate-onboarding/references/framework/flow.ts +80 -0
- package/dist/skills/animate-onboarding/references/framework/handoffs.ts +869 -0
- package/dist/skills/animate-onboarding/references/framework/layout.tsx +113 -0
- package/dist/skills/animate-onboarding/references/framework/motion.css +559 -0
- package/dist/skills/animate-onboarding/references/framework/useStoryRouter.ts +48 -0
- package/dist/skills/animate-onboarding/references/handoffs.md +375 -0
- package/dist/skills/animate-onboarding/references/imageReady.ts +92 -0
- package/dist/skills/animate-onboarding/references/morphFrame.ts +356 -0
- package/dist/skills/animate-onboarding/references/performance.md +41 -0
- package/dist/skills/animate-onboarding/references/web-runtime/README.md +17 -0
- package/dist/skills/animate-onboarding/references/web-runtime/handoffs.ts +858 -0
- package/dist/skills/animate-onboarding/references/web-runtime/story-motion.css +301 -0
- package/dist/skills/index.json +37 -0
- package/dist/skills/mobile-design/SKILL.md +447 -0
- package/dist/skills/mobile-design/references/responsive.md +162 -0
- package/dist/skills/onboarding-questions/SKILL.md +231 -0
- package/dist/skills/onboarding-questions/references/arpu-questions.md +139 -0
- package/dist/skills/onboarding-questions/references/craft.md +142 -0
- package/dist/skills/onboarding-questions/references/example-reflective.md +117 -0
- package/dist/skills/superwall/SKILL.md +82 -9
- package/dist/skills/superwall/references/api.md +153 -37
- package/dist/skills/superwall/references/apple-setup.md +316 -0
- package/dist/skills/superwall/references/asc.md +74 -38
- package/dist/skills/superwall/references/data-analytics.md +55 -21
- package/dist/skills/superwall/workflows/dashboard/playbook.md +3 -3
- package/dist/skills/superwall/workflows/dashboard/setup.md +8 -8
- package/dist/skills/superwall/workflows/migrate/adapty.md +6 -6
- package/dist/skills/superwall/workflows/migrate/playbook.md +4 -4
- package/dist/skills/superwall/workflows/migrate/qonversion.md +5 -5
- package/dist/skills/superwall/workflows/migrate/revenuecat.md +6 -6
- package/dist/skills/superwall/workflows/placements/android.md +2 -2
- package/dist/skills/superwall/workflows/placements/expo.md +2 -2
- package/dist/skills/superwall/workflows/placements/flutter.md +2 -2
- package/dist/skills/superwall/workflows/placements/ios.md +2 -2
- package/dist/skills/superwall/workflows/placements/playbook.md +2 -2
- package/dist/skills/superwall/workflows/placements/react-native.md +2 -2
- package/dist/skills/superwall/workflows/placements/strategy.md +2 -2
- package/dist/skills/superwall/workflows/review/playbook.md +1 -1
- package/dist/skills/superwall-editor/SKILL.md +61 -0
- package/dist/skills/superwall-editor/references/cli.md +135 -0
- package/dist/skills/superwall-editor/references/design.md +51 -0
- package/dist/skills/superwall-editor/references/native-elements.md +171 -0
- package/dist/skills/superwall-editor/references/workflow.md +65 -0
- package/dist/skills/superwall-editor/scripts/sw-editor.sh +662 -0
- package/dist/skills/superwall-framework/SKILL.md +78 -28
- package/dist/skills/superwall-framework/references/cli.md +58 -28
- package/dist/skills/superwall-framework/references/examples.md +4 -3
- package/dist/skills/superwall-framework/references/layout.md +30 -8
- package/dist/skills/superwall-framework/references/migrate-from-editor.md +1 -1
- package/dist/skills/superwall-framework/references/onboarding-state.md +245 -0
- package/dist/skills/wwdc/SKILL.md +22 -0
- package/dist/skills/wwdc/references/docs.md +52 -0
- package/dist/skills/wwdc/scripts/wwdc.sh +266 -0
- package/dist/{skills-DPzlnfCK.js → skills-BvFOa4y6.js} +99 -122
- package/dist/skills-DMG4bpKk.js +14 -0
- package/dist/{spawn-DSoTXy_j.js → spawn-DmmmHIP-.js} +14 -12
- package/dist/spinner-CneRK5rk.js +294 -0
- package/dist/storage-DYvmIOHa.d.ts +16 -0
- package/dist/storage-s2Dnz-yl.js +31 -0
- package/dist/storekit-DafAnGkM.js +16 -0
- package/dist/storekit-yY_kS2iR.js +47 -0
- package/dist/telemetry-DtG92m5O.js +56 -0
- package/dist/theme-DUsCh-Vd.js +25 -0
- package/dist/timing-BVxPrYq3.js +5 -0
- package/dist/{token-C0it-Xh7.js → token-DzRh7dI1.js} +6 -38
- package/dist/tools.d.ts +96 -0
- package/dist/tools.js +11178 -0
- package/dist/ui-D_qf3Gvw.js +53 -0
- package/dist/upgrade-Bt4Ouw1y.js +117 -0
- package/dist/upgrade-Cqy5orjb.js +7 -0
- package/package.json +10 -5
- package/dist/api-CZzirVMj.js +0 -151
- package/dist/api-output-aJNw7Syy.js +0 -20
- package/dist/app-DH6U8yuI.js +0 -190
- package/dist/asa-C-sQzPPn.js +0 -1194
- package/dist/asc-1ZBJ6DwS.js +0 -778
- package/dist/auth-YRhlV3DE.js +0 -140
- package/dist/billing-CCYHdApx.js +0 -80
- package/dist/bundle-id-CKxl_026.js +0 -121
- package/dist/command-CMIz81Da.js +0 -301
- package/dist/dev-DZy6pOnB.js +0 -22
- package/dist/doctor-H-hf-Yww.js +0 -88
- package/dist/feedback-CKf-rpBW.js +0 -152
- package/dist/hosted-CXe9TrWx.js +0 -32
- package/dist/migrate-C9ERDR6y.js +0 -284
- package/dist/org-sj7uyvp-.js +0 -40
- package/dist/output-C4o2gJ1K.js +0 -146
- package/dist/params-l3CrvRtR.js +0 -51
- package/dist/pipeline-BqzqZhX1.js +0 -977
- package/dist/print-skill-ZojRSybs.js +0 -74
- package/dist/promote-BG8X4Nv_.js +0 -88
- package/dist/publish-sxLh-G4G.js +0 -35
- package/dist/push-bQ6Vxtg8.js +0 -35
- package/dist/query-_FbybaH-.js +0 -53
- package/dist/resource-CGIwSd29.js +0 -323
- package/dist/revenue-provider-ebsRINY8.js +0 -100
- package/dist/scope-BvzD-kO4.js +0 -223
- package/dist/skills-D_R-lEsK.js +0 -64
- package/dist/spinner-TWa0hia6.js +0 -18
- package/dist/storekit-Cj9Cpjcz.js +0 -29
- package/dist/telemetry-DeA1mvnT.js +0 -169
- package/dist/ui-Dy0b-9L8.js +0 -27738
- package/dist/update-B2fWIc4q.js +0 -59
- package/dist/upgrade-BmzkTKrh.js +0 -72
- /package/dist/{devtools-8EgLo86w.js → devtools-ByZ6XYnn.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.
|