@iwsdk/cli 1.1.0 → 1.2.0-rc.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 (142) hide show
  1. package/README.md +79 -2
  2. package/dist/agent-adapters.d.ts +12 -1
  3. package/dist/agent-adapters.d.ts.map +1 -1
  4. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +312 -0
  5. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  6. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  7. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +277 -0
  8. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  9. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
  10. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  11. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
  12. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  13. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
  14. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  15. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
  16. package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +74 -0
  17. package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
  18. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +46 -0
  19. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +1531 -0
  20. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +82 -0
  21. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +263 -0
  22. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/planner.md +307 -0
  23. package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +282 -0
  24. package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +75 -0
  25. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +178 -0
  26. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  27. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
  28. package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +262 -0
  29. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +106 -0
  30. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/component-reference.md +152 -0
  31. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
  32. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
  33. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
  34. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  35. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  36. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  37. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  38. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  39. package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +70 -0
  40. package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +328 -0
  41. package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
  42. package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +521 -0
  43. package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +60 -0
  44. package/dist/agent-guidance/files/.claude/rules/ecs-api.md +103 -0
  45. package/dist/agent-guidance/files/.claude/rules/scene-json.md +72 -0
  46. package/dist/agent-guidance/files/.claude/rules/uikitml.md +66 -0
  47. package/dist/agent-guidance/files/.claude/settings.json +29 -0
  48. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +312 -0
  49. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  50. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  51. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +277 -0
  52. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  53. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
  54. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  55. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
  56. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  57. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
  58. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  59. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
  60. package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +74 -0
  61. package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
  62. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +46 -0
  63. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +1531 -0
  64. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +82 -0
  65. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +263 -0
  66. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/planner.md +307 -0
  67. package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +282 -0
  68. package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +75 -0
  69. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +178 -0
  70. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  71. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
  72. package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +262 -0
  73. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +106 -0
  74. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/component-reference.md +152 -0
  75. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
  76. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
  77. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
  78. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  79. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  80. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  81. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  82. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  83. package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +70 -0
  84. package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +328 -0
  85. package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
  86. package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +62 -0
  87. package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +105 -0
  88. package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +74 -0
  89. package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +68 -0
  90. package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +55 -0
  91. package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +101 -0
  92. package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +71 -0
  93. package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +65 -0
  94. package/{guidance → dist/agent-guidance/files}/AGENTS.md +107 -27
  95. package/dist/agent-guidance/files/CLAUDE.md +3 -0
  96. package/dist/agent-guidance/files/public/scenes/AGENTS.md +72 -0
  97. package/dist/agent-guidance/files/public/ui/AGENTS.md +66 -0
  98. package/dist/agent-guidance/files/src/AGENTS.md +153 -0
  99. package/dist/agent-guidance/manifest.json +854 -0
  100. package/dist/agent-guidance.d.ts +113 -0
  101. package/dist/agent-guidance.d.ts.map +1 -0
  102. package/dist/agent-guidance.js +3403 -0
  103. package/dist/agent-guidance.js.map +1 -0
  104. package/dist/cli.js +2407 -144
  105. package/dist/cli.js.map +1 -1
  106. package/dist/commands/adapter.d.ts +1 -0
  107. package/dist/commands/adapter.d.ts.map +1 -1
  108. package/dist/commands/agents.d.ts +11 -0
  109. package/dist/commands/agents.d.ts.map +1 -0
  110. package/dist/commands/browser.d.ts +11 -0
  111. package/dist/commands/browser.d.ts.map +1 -1
  112. package/dist/commands/dev.d.ts +1 -0
  113. package/dist/commands/dev.d.ts.map +1 -1
  114. package/dist/commands/reference.d.ts +15 -1
  115. package/dist/commands/reference.d.ts.map +1 -1
  116. package/dist/commands/runtime.d.ts.map +1 -1
  117. package/dist/commands/upgrade.d.ts +51 -0
  118. package/dist/commands/upgrade.d.ts.map +1 -0
  119. package/dist/contract.js +32 -0
  120. package/dist/contract.js.map +1 -1
  121. package/dist/guidance-refresh.d.ts +33 -0
  122. package/dist/guidance-refresh.d.ts.map +1 -0
  123. package/dist/help.d.ts +2 -0
  124. package/dist/help.d.ts.map +1 -1
  125. package/dist/index.d.ts.map +1 -1
  126. package/dist/index.js +4744 -135
  127. package/dist/index.js.map +1 -1
  128. package/dist/mcp-stdio.d.ts.map +1 -1
  129. package/dist/migrations/iwsdk-migrate-0-5/SKILL.md +413 -0
  130. package/dist/migrations.d.ts +36 -0
  131. package/dist/migrations.d.ts.map +1 -0
  132. package/dist/package-manager.d.ts +28 -0
  133. package/dist/package-manager.d.ts.map +1 -0
  134. package/dist/release-notes.d.ts +28 -0
  135. package/dist/release-notes.d.ts.map +1 -0
  136. package/dist/release-notes.json +1374 -0
  137. package/dist/runtime-contract.d.ts +8 -0
  138. package/dist/runtime-contract.d.ts.map +1 -1
  139. package/dist/runtime-telemetry.d.ts +8 -1
  140. package/dist/runtime-telemetry.d.ts.map +1 -1
  141. package/dist/version.d.ts +1 -1
  142. package/package.json +9 -3
@@ -0,0 +1,219 @@
1
+ ---
2
+ name: iwsdk-pwa-packaging
3
+ description: Ship an IWSDK app to Meta Quest and the Horizon Store as a PWA/TWA — both immersive WebXR and 2D windowed panel modes. Use for PWA packaging, web app manifest and icons, auto-enter-XR on launch, bubblewrap APK builds, signing keystores, Digital Asset Links, sideloading, and Horizon Store upload. Also use when a packaged app is stuck loading, shows a URL bar, or will not launch.
4
+ argument-hint: '[packaging goal, e.g. "ship to the store" or "build an APK"]'
5
+ ---
6
+
7
+ # PWA Packaging for Meta Horizon
8
+
9
+ Turn a built IWSDK app into a signed Quest APK and get it on the Store. The app
10
+ runs from a live URL inside a Trusted Web Activity — the APK is a thin native
11
+ wrapper, not a bundle of your files. That single fact explains most of the
12
+ pipeline: the origin must be live before packaging, and web fixes ship by
13
+ redeploying rather than rebuilding.
14
+
15
+ User request is in `$ARGUMENTS`.
16
+
17
+ ```
18
+ 0. Pick app mode → immersive WebXR vs 2D panel (decides steps 1 and 4)
19
+ 1. Prepare the app → auto-enter XR (immersive only) + manifest link
20
+ 2. Get it hosted → public HTTPS origin = <DOMAIN> [iwsdk-hosting]
21
+ 3. Manifest + icons → installable PWA, live on <DOMAIN>
22
+ 4. Package the APK → keystore, twa-manifest.json, build, asset links
23
+ 5. Upload to Store → ovr-platform-util
24
+ ```
25
+
26
+ Do not reorder these. Step 4 fetches from `<DOMAIN>`, and asset links in step 4
27
+ need a second publish through step 2 — so hosting is a dependency, not a
28
+ finishing touch.
29
+
30
+ ## Step 0 — Pick the app mode first
31
+
32
+ One decision, made once, that changes exactly two things downstream. Ask the
33
+ developer if it is not obvious from the project.
34
+
35
+ | | **Immersive WebXR** | **2D panel** |
36
+ | --- | --- | --- |
37
+ | Runs as | full VR/WebXR session | windowed 2D panel with a Library entry |
38
+ | Auto-enter session (step 1) | **yes** | **no — must not be added** |
39
+ | `horizonOSAppMode` (step 4) | `"immersive"` | `"2D"` |
40
+
41
+ An IWSDK app scaffolded with `--mode vr` or `--mode ar` is immersive. A wrong
42
+ value here is the classic failure: a 2D app marked `immersive` hangs on a
43
+ loading screen, and an immersive app marked `2D` opens with a browser URL bar.
44
+ Details and the AR/VR nuance: [`references/app-modes.md`](references/app-modes.md).
45
+
46
+ ## Step 1 — Prepare the app
47
+
48
+ **Immersive only: auto-enter the XR session on launch.** An installed immersive
49
+ PWA has no 2D page to click, so nothing would ever call `requestSession` — the
50
+ app-icon tap is the user activation and the app must spend it itself. Gate on
51
+ `getDigitalGoodsService` so this fires only in the installed PWA and never in a
52
+ browser tab, which keeps its normal Enter-XR button.
53
+
54
+ In `src/index.ts`, inside the `World.create(...)` callback:
55
+
56
+ ```ts
57
+ World.create(container, projectOptions).then((world) => {
58
+ // …system registration…
59
+
60
+ const nav = navigator as Navigator & {
61
+ xr?: { isSessionSupported?: (m: string) => Promise<boolean> };
62
+ };
63
+ if ('getDigitalGoodsService' in window && nav.xr?.isSessionSupported) {
64
+ nav.xr
65
+ .isSessionSupported('immersive-vr') // 'immersive-ar' for an AR app
66
+ .then((supported) => {
67
+ if (supported) world.launchXR();
68
+ })
69
+ .catch(() => {});
70
+ }
71
+ });
72
+ ```
73
+
74
+ `world.launchXR()` is IWSDK's `requestSession` plus session setup — do not call
75
+ `navigator.xr.requestSession` directly. `getDigitalGoodsService` exists only on
76
+ device, so this path cannot be validated in a desktop browser or in IWER; verify
77
+ it on the headset after sideloading (step 4).
78
+
79
+ **Both modes:** link the manifest and icons in `index.html`. The scaffolded
80
+ `index.html` ships `<link rel="icon" href="data:," />` and no manifest link, so
81
+ the app is not installable until step 3 adds them.
82
+
83
+ Then confirm the app itself is sound before wrapping it — `npm run --if-present typecheck`,
84
+ and `npm run build` producing a `dist/` you have actually loaded. Packaging a
85
+ broken build wastes a full round trip through hosting, signing, and upload.
86
+
87
+ ## Step 2 — Get it hosted
88
+
89
+ **Invoke the `iwsdk-hosting` skill.** It asks whether hosting already exists,
90
+ recommends and runs Vercel if not, and — if the developer already has a host —
91
+ pauses with concrete upload steps instead of guessing at their pipeline.
92
+
93
+ Come back with a `<DOMAIN>` that passes the hosting contract: root, manifest,
94
+ and icons all 200, manifest served as `application/manifest+json`. Asset links
95
+ are still expected to 404 at this point; they arrive in step 4.
96
+
97
+ Do not substitute a localhost tunnel or a preview URL. `bubblewrap` bakes the
98
+ host into the APK, and a URL that later 401s or disappears produces an app that
99
+ installs and then shows nothing.
100
+
101
+ ## Step 3 — Manifest and icons
102
+
103
+ Both modes need a valid installable manifest plus PNG icons, live on `<DOMAIN>`
104
+ before `bubblewrap update` runs — it fetches them over the network.
105
+
106
+ `public/manifest.webmanifest`:
107
+
108
+ ```json
109
+ {
110
+ "name": "…", "short_name": "…", "description": "…",
111
+ "start_url": "/", "scope": "/",
112
+ "display": "standalone", "orientation": "landscape",
113
+ "background_color": "#06010f", "theme_color": "#0a0418",
114
+ "icons": [
115
+ { "src": "/icons/icon-192.png", "type": "image/png", "sizes": "192x192", "purpose": "any" },
116
+ { "src": "/icons/icon-512.png", "type": "image/png", "sizes": "512x512", "purpose": "any" },
117
+ { "src": "/icons/icon-512-maskable.png", "type": "image/png", "sizes": "512x512", "purpose": "maskable" }
118
+ ]
119
+ }
120
+ ```
121
+
122
+ Generate icons with `sharp` (`npm i -D sharp`; the scaffold already pins a
123
+ working version). The maskable icon must be full-bleed and opaque. Full manifest
124
+ reference, the icon script, and subpath/multi-origin cases:
125
+ [`references/manifest-and-icons.md`](references/manifest-and-icons.md).
126
+
127
+ Rebuild and publish — via `iwsdk-hosting` again if the developer owns the host —
128
+ then verify the manifest and both icon URLs return 200 before continuing.
129
+
130
+ ## Step 4 — Package the APK with bubblewrap
131
+
132
+ ```bash
133
+ npm i -g @meta-quest/bubblewrap-cli # bin: bubblewrap, needs Node >= 18
134
+ ```
135
+
136
+ First run downloads a JDK 17 and the Android SDK into `~/.bubblewrap` behind
137
+ **interactive prompts** (including an SDK licence confirmation). An agent cannot
138
+ answer those — have the developer run `bubblewrap doctor` once in a real
139
+ terminal, then continue. Everything after that is scriptable.
140
+
141
+ `bubblewrap init` is also an interactive wizard with no value flags to bypass
142
+ it, so **use the scripted path**: hand-write `twa-manifest.json`, then `update`
143
+ and `build`.
144
+
145
+ Four things happen here, in order:
146
+
147
+ 1. **Choose the signing key — pause and ask.** The key is permanent: every
148
+ future update must reuse the same keystore, alias, and `packageId`, and a
149
+ published listing is already bound to one. Reuse an existing keystore, or
150
+ generate a new one outside the deployable web tree so it never ships.
151
+ 2. **Write `twa-manifest.json`**, with `isMetaQuest: true` and the
152
+ `horizonOSAppMode` chosen in step 0.
153
+ 3. **Build** — `bubblewrap update && bubblewrap build`, passwords passed through
154
+ `BUBBLEWRAP_KEYSTORE_PASSWORD` / `BUBBLEWRAP_KEY_PASSWORD` (there are no
155
+ password CLI flags).
156
+ 4. **Publish `public/.well-known/assetlinks.json`** with the package name and
157
+ the certificate SHA-256. Until it is live on `<DOMAIN>`, the TWA will not
158
+ launch. This is the second hosting handoff — go back through `iwsdk-hosting`
159
+ and verify the URL yourself.
160
+
161
+ Commands, the full manifest template, keystore handling, and build verification:
162
+ [`references/bubblewrap.md`](references/bubblewrap.md).
163
+
164
+ Sideload and test on device before uploading — `adb install -r
165
+ app-release-signed.apk`, or the `metavr` MCP server that scaffolded projects
166
+ register. This is the only place the immersive auto-enter path can be verified.
167
+
168
+ ## Step 5 — Upload to the Horizon Store
169
+
170
+ ```bash
171
+ ./ovr-platform-util upload-quest-build \
172
+ --app-id <HORIZON_APP_ID> --app-secret <SECRET> \
173
+ --apk app-release-signed.apk \
174
+ --channel ALPHA --age-group MIXED_AGES \
175
+ --notes "…" --disable-progress-bar
176
+ ```
177
+
178
+ Same command for both modes. Channels: `ALPHA`/`BETA`/`RC` for testing, `STORE`
179
+ for production. Auth is the app's App Secret or a user token — ask the
180
+ developer, never invent one, and never write it into a file under `public/`.
181
+
182
+ Expect the first upload to fail with *"must first agree to our Developer
183
+ Distribution Agreement"*. Only an org admin can sign it, so pause, ask, and
184
+ retry the identical command. Tool download, auth, and flag reference:
185
+ [`references/store-upload.md`](references/store-upload.md).
186
+
187
+ ## Redeploy vs rebuild
188
+
189
+ | Change | Action |
190
+ | ------ | ------ |
191
+ | App logic, assets, styling, manifest text, icons, asset links | republish `<DOMAIN>`; installed TWA picks it up next launch |
192
+ | Package id, app name, launcher icon, version, **app mode**, signing | rebuild the APK and re-upload |
193
+
194
+ ## Security
195
+
196
+ The keystore and the app secret never go near `public/` or `dist/`. After every
197
+ publish, confirm the keystore is not being served:
198
+
199
+ ```bash
200
+ curl -s -o /dev/null -w '%{http_code}\n' https://<DOMAIN>/android.keystore # want 404
201
+ ```
202
+
203
+ Back up the keystore somewhere durable. Losing it means the app can never be
204
+ updated — only replaced by a new Store entry.
205
+
206
+ ## Reference Files
207
+
208
+ | File | Load when |
209
+ | ---- | --------- |
210
+ | [`references/app-modes.md`](references/app-modes.md) | Step 0 — choosing immersive vs 2D, and what each implies |
211
+ | [`references/manifest-and-icons.md`](references/manifest-and-icons.md) | Step 3 — manifest fields, icon generation, subpath and multi-origin |
212
+ | [`references/bubblewrap.md`](references/bubblewrap.md) | Step 4 — prereqs, keystore, `twa-manifest.json`, build, asset links |
213
+ | [`references/store-upload.md`](references/store-upload.md) | Step 5 — `ovr-platform-util`, auth, channels, the DDA blocker |
214
+ | [`references/troubleshooting.md`](references/troubleshooting.md) | Anything installed but misbehaving — stuck loading, URL bar, will-not-launch |
215
+
216
+ Getting the app online is the `iwsdk-hosting` skill. Building the app itself is
217
+ `iwsdk-planner` and the other `iwsdk-*` skills — do not re-derive IWSDK
218
+ patterns here.
219
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=e4e859d1977962769195f6bfb52dc9b02f159dd743e2609ea8b6111dd847e7eb name=iwsdk-pwa-packaging (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -0,0 +1,104 @@
1
+ # App Modes: Immersive WebXR vs 2D Panel
2
+
3
+ The first decision in the pipeline and the one most likely to be wrong. It is
4
+ made once, and it changes exactly two things:
5
+
6
+ 1. Whether the app auto-enters a WebXR session on launch (immersive only).
7
+ 2. The `horizonOSAppMode` value in `twa-manifest.json`.
8
+
9
+ Everything else — hosting, manifest, icons, keystore, asset links, Store upload
10
+ — is identical for both.
11
+
12
+ | | **Immersive WebXR** | **2D panel** |
13
+ | --- | --- | --- |
14
+ | Runs as | full VR/WebXR session on launch | windowed 2D panel with its own Library entry |
15
+ | Typical app | IWSDK scene, game, spatial tool | dashboard, companion app, store front, any responsive site |
16
+ | Web app requirement | must support `immersive-vr` / `immersive-ar` | any responsive PWA; IWSDK not required |
17
+ | Auto-enter `requestSession` | **yes — built into the app** | **no — must not be added** |
18
+ | `horizonOSAppMode` | `"immersive"` | `"2D"` |
19
+
20
+ ## Choosing
21
+
22
+ An IWSDK app scaffolded with `--mode vr` or `--mode ar` is immersive; that is
23
+ the whole point of the scaffold. Pick 2D only when the experience is genuinely a
24
+ flat panel — a companion or admin surface next to an immersive app, or a web
25
+ property being brought to the headset unchanged.
26
+
27
+ If the same origin should be both, that is two Store apps with two `packageId`s
28
+ sharing one `<DOMAIN>`. The asset-links file lists both packages.
29
+
30
+ ## The classic failure
31
+
32
+ `horizonOSAppMode` is validated against `['immersive', '2D']` and **defaults to
33
+ `immersive`** when absent or misspelled — so a 2D app whose manifest omits the
34
+ field inherits the wrong mode silently.
35
+
36
+ | Symptom on device | Cause | Fix |
37
+ | ----------------- | ----- | --- |
38
+ | 2D app stuck on a loading screen | mode is `immersive`; Horizon waits for a session that never starts | set `"2D"`, `bubblewrap update && bubblewrap build`, re-upload |
39
+ | Immersive app opens showing a browser URL bar | mode is `2D` | set `"immersive"`, rebuild, re-upload |
40
+ | Immersive app opens flat with no URL bar | mode is right, auto-enter code is missing or never fires | add/repair the auto-enter block, republish `<DOMAIN>` — no rebuild needed |
41
+
42
+ The third row is worth internalizing: a missing session call is a **web** bug,
43
+ fixed by a redeploy. A wrong mode is a **native** bug, fixed only by a new APK.
44
+ Check the mode in the built APK before blaming the app code:
45
+
46
+ ```bash
47
+ "$BT/aapt" dump badging app-release-signed.apk | grep -iE 'package:|APP_MODE|OCULUS'
48
+ ```
49
+
50
+ ## Auto-enter, in detail (immersive only)
51
+
52
+ An installed immersive PWA has no 2D page and no button to press. Horizon
53
+ launches it straight into a headset context, so if the app waits for a click it
54
+ waits forever. The app-icon tap counts as the user activation that
55
+ `requestSession` requires — but only if the app spends it immediately on load.
56
+
57
+ ```ts
58
+ const nav = navigator as Navigator & {
59
+ xr?: { isSessionSupported?: (m: string) => Promise<boolean> };
60
+ };
61
+ if ('getDigitalGoodsService' in window && nav.xr?.isSessionSupported) {
62
+ nav.xr
63
+ .isSessionSupported('immersive-vr') // 'immersive-ar' for an AR app
64
+ .then((supported) => {
65
+ if (supported) world.launchXR();
66
+ })
67
+ .catch(() => {});
68
+ }
69
+ ```
70
+
71
+ Three things this code is doing deliberately:
72
+
73
+ - **`getDigitalGoodsService` as the install gate.** It is present in an
74
+ installed PWA and absent in a browser tab, so the same build keeps its normal
75
+ Enter-XR button on desktop and in IWER while auto-entering on device. Feature-
76
+ detecting the headset any other way (user agent, screen size) misfires.
77
+ - **`isSessionSupported` before `launchXR`.** Calling into an unsupported mode
78
+ throws and leaves the app on a black screen with nothing in the console.
79
+ - **`world.launchXR()`, not `navigator.xr.requestSession`.** `launchXR` is
80
+ IWSDK's session request plus the renderer, reference-space, and input wiring
81
+ that the world needs. A raw `requestSession` gets a session the world does not
82
+ know about.
83
+
84
+ Match the session mode to `iwsdk.config.json` — `world.xr.mode: "ar"` means
85
+ `isSessionSupported('immersive-ar')`. Querying the wrong mode returns `false`
86
+ and the app silently stays flat.
87
+
88
+ Because `getDigitalGoodsService` is device-only, this branch never runs on a
89
+ development machine. It can only be verified by sideloading the APK and
90
+ launching from the Library.
91
+
92
+ ## 2D panel notes
93
+
94
+ A 2D app runs as a single-instance standalone panel. There is no tab or
95
+ navigation bar by default; `theme_color` / `theme_color_dark` in the web
96
+ manifest color the custom tab bar when one is shown. Cookies and storage are
97
+ shared with the Quest Browser.
98
+
99
+ Out-of-scope links open inside the panel unless targeted at a new tab or window.
100
+ If the app legitimately spans origins, add `additional_trusted_origins` to the
101
+ web manifest and host `/.well-known/assetlinks.json` on **every** listed origin
102
+ — a missing one silently drops that origin out of scope mid-session.
103
+
104
+ Do not add the auto-enter block to a 2D app under any circumstances.
@@ -0,0 +1,219 @@
1
+ # Packaging a Quest APK with bubblewrap
2
+
3
+ `@meta-quest/bubblewrap-cli` wraps a live PWA into a signed Android APK — a
4
+ Trusted Web Activity that loads `<DOMAIN>` in a full-screen web view. It is a
5
+ wrapper: your files are not inside the APK, which is why the origin must already
6
+ be live and why web fixes never need a rebuild.
7
+
8
+ ```bash
9
+ npm i -g @meta-quest/bubblewrap-cli # bin: bubblewrap, requires Node >= 18
10
+ ```
11
+
12
+ ## Prerequisites — one interactive step, then scriptable
13
+
14
+ On first run bubblewrap has no JDK or Android SDK and offers to install its own
15
+ into `~/.bubblewrap`, behind `inquirer` prompts that include an Android SDK
16
+ licence confirmation. **An agent cannot answer these.** Have the developer run
17
+ this once in a real terminal:
18
+
19
+ ```bash
20
+ bubblewrap doctor
21
+ ```
22
+
23
+ Accept the JDK and SDK installs. It writes `~/.bubblewrap/config.json` with
24
+ `jdkPath` and `androidSdkPath`; every later command is non-interactive. If they
25
+ already have a JDK 17 and an Android SDK, `bubblewrap updateConfig --jdkPath …
26
+ --androidSdkPath …` points at those instead.
27
+
28
+ Locate the tools dynamically rather than hard-coding versions:
29
+
30
+ ```bash
31
+ KT=$(find ~/.bubblewrap/jdk -path '*/bin/keytool' | head -1)
32
+ BT=$(ls -d ~/.bubblewrap/android_sdk/build-tools/* | sort -V | tail -1)
33
+ ```
34
+
35
+ ## init is interactive — use the scripted path
36
+
37
+ `bubblewrap init` generates `twa-manifest.json` and the Gradle project through a
38
+ wizard (host, name, packageId, version, display, colors, icon, **App Mode**,
39
+ signing key). It needs a real TTY and has no value flags to bypass the prompts.
40
+
41
+ - **Developer at a terminal:** `bubblewrap init --manifest=https://<DOMAIN>/manifest.webmanifest --metaquest`
42
+ and answer the prompts. `--metaquest` is what surfaces the Quest-specific
43
+ questions, including App Mode.
44
+ - **Agent, or any non-TTY caller:** skip `init`. Hand-write
45
+ `twa-manifest.json` as below, then run `update` and `build`, which are both
46
+ non-interactive.
47
+
48
+ Work in a directory **outside** the web tree — `twa/` next to the app, never
49
+ inside `public/` or anywhere that gets published.
50
+
51
+ ## Step 1 — The signing key: pause and ask
52
+
53
+ **Stop and ask the developer which key to use before building anything.** This
54
+ is not a detail to default. The key is permanent: every future update must be
55
+ signed with the same keystore, alias, and `packageId`, and a published Store
56
+ listing is already bound to one. There is no recovery from a lost key — only a
57
+ new Store entry under a new package name.
58
+
59
+ **(A) Existing keystore.** Ask for the file path, the alias, and the store and
60
+ key passwords, and use them as-is. Required when updating an app that is already
61
+ published. Reusing one keystore across several apps is normal and fine.
62
+
63
+ **(B) Generate a new one** — only when there is nothing to reuse. Create it
64
+ outside the deployable web tree, and tell the developer to back it up:
65
+
66
+ ```bash
67
+ "$KT" -genkeypair -v -keystore twa/android.keystore \
68
+ -alias android -keyalg RSA -keysize 2048 -validity 10000 \
69
+ -storepass <PW> -keypass <PW> -dname "CN=<App>, O=<Org>, C=US"
70
+ ```
71
+
72
+ Either way, read the certificate SHA-256 now — step 4 needs it:
73
+
74
+ ```bash
75
+ "$KT" -list -v -keystore <keystore> -alias <alias> \
76
+ -storepass <PW> -keypass <PW> | grep -i SHA256
77
+ ```
78
+
79
+ ## Step 2 — twa-manifest.json
80
+
81
+ Field names and types come from the `TwaManifest` class in
82
+ `@meta-quest/bubblewrap-core`; treat that as authoritative if something here
83
+ looks stale.
84
+
85
+ ```json
86
+ {
87
+ "packageId": "com.<org>.<app>",
88
+ "applicationId": "<HORIZON_APP_ID or 0>",
89
+ "host": "<DOMAIN>",
90
+ "name": "Full App Name",
91
+ "launcherName": "App",
92
+ "display": "standalone",
93
+ "orientation": "landscape",
94
+ "themeColor": "#0a0418",
95
+ "backgroundColor": "#06010f",
96
+ "startUrl": "/",
97
+ "iconUrl": "https://<DOMAIN>/icons/icon-512.png",
98
+ "maskableIconUrl": "https://<DOMAIN>/icons/icon-512-maskable.png",
99
+ "webManifestUrl": "https://<DOMAIN>/manifest.webmanifest",
100
+ "signingKey": { "path": "<abs>/twa/android.keystore", "alias": "android" },
101
+ "appVersion": "1",
102
+ "appVersionName": "1",
103
+ "appVersionCode": 1,
104
+ "fallbackType": "customtabs",
105
+ "features": {},
106
+ "isMetaQuest": true,
107
+ "horizonOSAppMode": "immersive",
108
+ "fingerprints": [],
109
+ "minSdkVersion": 23
110
+ }
111
+ ```
112
+
113
+ The four fields that actually decide whether this works:
114
+
115
+ - **`isMetaQuest`** — defaults to `false`. Left unset, you get a plain Android
116
+ TWA with no Quest behavior at all.
117
+ - **`horizonOSAppMode`** — `"immersive"` or `"2D"`, validated against exactly
118
+ those two strings, **defaulting to `"immersive"`** when absent or misspelled.
119
+ A 2D app that omits it inherits the wrong mode silently.
120
+ - **`packageId`** — permanent, paired with the signing key. Choose it once.
121
+ - **`applicationId`** — the numeric Horizon App ID. `"0"` builds and sideloads
122
+ fine (no in-app purchases); set the real id before any Store upload.
123
+
124
+ `signingKey.path` should be absolute — a relative path resolves against the
125
+ Gradle project directory, not your shell's.
126
+
127
+ ## Step 3 — Build
128
+
129
+ `update` regenerates the Gradle project from the manifest and bumps the version;
130
+ `build` compiles and signs. Passwords are read from the environment — there are
131
+ no password CLI flags.
132
+
133
+ ```bash
134
+ cd twa
135
+ export BUBBLEWRAP_KEYSTORE_PASSWORD=<PW> BUBBLEWRAP_KEY_PASSWORD=<PW>
136
+ bubblewrap update && bubblewrap build
137
+ # → app-release-signed.apk + app-release-bundle.aab
138
+ ```
139
+
140
+ Verify what you actually built before shipping it:
141
+
142
+ ```bash
143
+ "$BT/aapt" dump badging app-release-signed.apk | grep -iE '^package:|APP_MODE|OCULUS'
144
+ "$BT/apksigner" verify --print-certs app-release-signed.apk | grep -i SHA-256
145
+ ```
146
+
147
+ The package name, app mode, and app id must be what you intended, and the
148
+ signer's SHA-256 must equal the keystore's from step 1. If they differ, the
149
+ build picked up a different key — asset links will fail and the app will not
150
+ launch.
151
+
152
+ Upload `app-release-signed.apk` to the Store; the `.aab` is not used by the
153
+ Horizon pipeline.
154
+
155
+ ## Step 4 — Digital Asset Links
156
+
157
+ The TWA verifies at launch that the origin vouches for this exact package and
158
+ certificate. If verification fails, Horizon shows *"will not launch"* — there is
159
+ no partial or degraded mode.
160
+
161
+ `public/.well-known/assetlinks.json`:
162
+
163
+ ```json
164
+ [
165
+ {
166
+ "relation": ["delegate_permission/common.handle_all_urls"],
167
+ "target": {
168
+ "namespace": "android_app",
169
+ "package_name": "com.<org>.<app>",
170
+ "sha256_cert_fingerprints": ["3B:06:…:8B"]
171
+ }
172
+ }
173
+ ]
174
+ ```
175
+
176
+ The fingerprint is the colon-separated uppercase hex from step 1. List one
177
+ object per package if several apps share the origin, and publish the same file
178
+ on every `additional_trusted_origins` host.
179
+
180
+ This is the **second hosting handoff**. Rebuild and publish through the
181
+ `iwsdk-hosting` skill, then verify the content, not just the status code:
182
+
183
+ ```bash
184
+ npm run build
185
+ # …publish…
186
+ curl -s https://<DOMAIN>/.well-known/assetlinks.json
187
+ ```
188
+
189
+ Changing `applicationId` or `horizonOSAppMode` does not change this file — the
190
+ package name and certificate are unchanged, so no republish is needed for a
191
+ mode fix.
192
+
193
+ ## Sideload and test
194
+
195
+ Test on device before uploading. This is the only place the immersive auto-enter
196
+ path can be verified, since `getDigitalGoodsService` does not exist off-device.
197
+
198
+ ```bash
199
+ adb install -r app-release-signed.apk
200
+ ```
201
+
202
+ Scaffolded IWSDK projects also register the `metavr` MCP server, which can
203
+ manage the connected Quest. Launch from the Library, not from `adb shell am
204
+ start` — launching from the Library is what exercises the real install path.
205
+
206
+ What to look for: the immersive app should enter VR with no visible 2D page and
207
+ no URL bar; a 2D app should open as a windowed panel. Anything else, go to
208
+ [`troubleshooting.md`](troubleshooting.md).
209
+
210
+ ## Security
211
+
212
+ - The keystore and its passwords never enter `public/`, `dist/`, or version
213
+ control. Confirm after each publish:
214
+ `curl -s -o /dev/null -w '%{http_code}\n' https://<DOMAIN>/android.keystore`
215
+ → 404.
216
+ - If a keystore was ever published, treat it as compromised: generate a new key
217
+ under a new `packageId`, since the old pairing is permanent.
218
+ - Back up the keystore, alias, and passwords together. They are only useful as a
219
+ set.