@iwsdk/cli 1.1.0 → 1.2.0-rc.1

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 (160) hide show
  1. package/README.md +106 -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 +1532 -0
  20. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +96 -0
  21. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +267 -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 +179 -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-offline/SKILL.md +217 -0
  30. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/offline.ts.template +99 -0
  31. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/sw.js.template +241 -0
  32. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
  33. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/build-step.md +71 -0
  34. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/page.md +70 -0
  35. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/service-worker.md +107 -0
  36. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/testing.md +57 -0
  37. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +106 -0
  38. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/component-reference.md +152 -0
  39. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +102 -0
  40. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +309 -0
  41. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +230 -0
  42. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  43. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  44. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  45. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  46. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +208 -0
  47. package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +70 -0
  48. package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +335 -0
  49. package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
  50. package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +521 -0
  51. package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +60 -0
  52. package/dist/agent-guidance/files/.claude/rules/ecs-api.md +103 -0
  53. package/dist/agent-guidance/files/.claude/rules/scene-json.md +72 -0
  54. package/dist/agent-guidance/files/.claude/rules/uikitml.md +66 -0
  55. package/dist/agent-guidance/files/.claude/settings.json +30 -0
  56. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +312 -0
  57. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  58. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  59. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +277 -0
  60. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  61. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
  62. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  63. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
  64. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  65. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
  66. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  67. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
  68. package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +74 -0
  69. package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
  70. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +46 -0
  71. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +1532 -0
  72. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +96 -0
  73. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +267 -0
  74. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/planner.md +307 -0
  75. package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +282 -0
  76. package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +75 -0
  77. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +179 -0
  78. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  79. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
  80. package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +262 -0
  81. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/SKILL.md +217 -0
  82. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/offline.ts.template +99 -0
  83. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/sw.js.template +241 -0
  84. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
  85. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/build-step.md +71 -0
  86. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/page.md +70 -0
  87. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/service-worker.md +107 -0
  88. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/testing.md +57 -0
  89. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +106 -0
  90. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/component-reference.md +152 -0
  91. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +102 -0
  92. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +309 -0
  93. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +230 -0
  94. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  95. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  96. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  97. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  98. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +208 -0
  99. package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +70 -0
  100. package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +335 -0
  101. package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
  102. package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +62 -0
  103. package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +105 -0
  104. package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +74 -0
  105. package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +68 -0
  106. package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +55 -0
  107. package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +101 -0
  108. package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +71 -0
  109. package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +65 -0
  110. package/{guidance → dist/agent-guidance/files}/AGENTS.md +107 -27
  111. package/dist/agent-guidance/files/CLAUDE.md +3 -0
  112. package/dist/agent-guidance/files/public/scenes/AGENTS.md +72 -0
  113. package/dist/agent-guidance/files/public/ui/AGENTS.md +66 -0
  114. package/dist/agent-guidance/files/src/AGENTS.md +153 -0
  115. package/dist/agent-guidance/manifest.json +954 -0
  116. package/dist/agent-guidance.d.ts +140 -0
  117. package/dist/agent-guidance.d.ts.map +1 -0
  118. package/dist/agent-guidance.js +3612 -0
  119. package/dist/agent-guidance.js.map +1 -0
  120. package/dist/cli.js +4010 -750
  121. package/dist/cli.js.map +1 -1
  122. package/dist/commands/adapter.d.ts +1 -0
  123. package/dist/commands/adapter.d.ts.map +1 -1
  124. package/dist/commands/agents.d.ts +11 -0
  125. package/dist/commands/agents.d.ts.map +1 -0
  126. package/dist/commands/browser.d.ts +11 -0
  127. package/dist/commands/browser.d.ts.map +1 -1
  128. package/dist/commands/dev.d.ts +1 -0
  129. package/dist/commands/dev.d.ts.map +1 -1
  130. package/dist/commands/reference.d.ts +15 -1
  131. package/dist/commands/reference.d.ts.map +1 -1
  132. package/dist/commands/runtime.d.ts.map +1 -1
  133. package/dist/commands/upgrade.d.ts +138 -0
  134. package/dist/commands/upgrade.d.ts.map +1 -0
  135. package/dist/contract.js +32 -0
  136. package/dist/contract.js.map +1 -1
  137. package/dist/guidance-refresh.d.ts +53 -0
  138. package/dist/guidance-refresh.d.ts.map +1 -0
  139. package/dist/help.d.ts +2 -0
  140. package/dist/help.d.ts.map +1 -1
  141. package/dist/index.d.ts.map +1 -1
  142. package/dist/index.js +6114 -508
  143. package/dist/index.js.map +1 -1
  144. package/dist/mcp-stdio.d.ts.map +1 -1
  145. package/dist/metavr-telemetry.d.ts +6 -0
  146. package/dist/metavr-telemetry.d.ts.map +1 -1
  147. package/dist/migrations/iwsdk-migrate-0-5/SKILL.md +413 -0
  148. package/dist/migrations.d.ts +36 -0
  149. package/dist/migrations.d.ts.map +1 -0
  150. package/dist/package-manager.d.ts +34 -0
  151. package/dist/package-manager.d.ts.map +1 -0
  152. package/dist/release-notes.d.ts +28 -0
  153. package/dist/release-notes.d.ts.map +1 -0
  154. package/dist/release-notes.json +1506 -0
  155. package/dist/runtime-contract.d.ts +8 -0
  156. package/dist/runtime-contract.d.ts.map +1 -1
  157. package/dist/runtime-telemetry.d.ts +8 -1
  158. package/dist/runtime-telemetry.d.ts.map +1 -1
  159. package/dist/version.d.ts +1 -1
  160. package/package.json +9 -3
@@ -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.
@@ -0,0 +1,149 @@
1
+ # Web App Manifest and Icons
2
+
3
+ Both modes need a valid, installable web app manifest and PNG icons, live on
4
+ `<DOMAIN>` **before** `bubblewrap update` runs — it fetches them over the
5
+ network and fails or silently falls back if they are missing.
6
+
7
+ The scaffolded app ships neither: `public/` has no manifest, and `index.html`
8
+ has a placeholder `<link rel="icon" href="data:," />`. Both are added here.
9
+
10
+ ## The manifest
11
+
12
+ `public/manifest.webmanifest` — Vite copies `public/` verbatim into `dist/`, so
13
+ it is served at `/manifest.webmanifest` with no further wiring.
14
+
15
+ ```json
16
+ {
17
+ "name": "Full App Name",
18
+ "short_name": "App",
19
+ "description": "One sentence shown at install time.",
20
+ "start_url": "/",
21
+ "scope": "/",
22
+ "display": "standalone",
23
+ "orientation": "landscape",
24
+ "background_color": "#06010f",
25
+ "theme_color": "#0a0418",
26
+ "icons": [
27
+ { "src": "/icons/icon-192.png", "type": "image/png", "sizes": "192x192", "purpose": "any" },
28
+ { "src": "/icons/icon-512.png", "type": "image/png", "sizes": "512x512", "purpose": "any" },
29
+ { "src": "/icons/icon-512-maskable.png", "type": "image/png", "sizes": "512x512", "purpose": "maskable" }
30
+ ]
31
+ }
32
+ ```
33
+
34
+ | Field | Why it matters here |
35
+ | ----- | ------------------- |
36
+ | `name` / `short_name` | `short_name` is the launcher label; keep it under ~12 characters or it truncates |
37
+ | `start_url` / `scope` | must match the hosting path — `/` at an origin root, `/<path>/` on a subpath deployment; with an offline copy (`iwsdk-offline`), both must also sit inside the service worker's scope |
38
+ | `display` | `standalone` for both modes; `browser` forces a URL bar |
39
+ | `background_color` | painted before first frame — match the app's clear color or launch flashes white |
40
+ | `theme_color` | colors the custom tab bar on a 2D panel; add `theme_color_dark` if the app is dark-first |
41
+ | `icons` | at minimum 192 and 512 `any`, plus one 512 `maskable` |
42
+
43
+ `bubblewrap` seeds `twa-manifest.json` from these values, so getting them right
44
+ now avoids hand-correcting them in two places later.
45
+
46
+ ## Link it in `index.html`
47
+
48
+ Replace the placeholder icon line in the scaffolded `<head>`:
49
+
50
+ ```html
51
+ <link rel="manifest" href="/manifest.webmanifest" />
52
+ <meta name="theme-color" content="#0a0418" />
53
+ <link rel="icon" href="/icons/icon-192.png" />
54
+ ```
55
+
56
+ Use absolute `/`-rooted paths here even though `vite.config.*` sets
57
+ `base: './'`. The relative base is for hashed bundle assets; the manifest and
58
+ icons are referenced by the platform from a known URL, and a relative path
59
+ resolves differently depending on the entry route.
60
+
61
+ ## Generating icons
62
+
63
+ There is no ImageMagick or PIL to rely on. Use `sharp` — the scaffold already
64
+ pins a working version via `overrides`:
65
+
66
+ ```bash
67
+ npm i -D sharp
68
+ ```
69
+
70
+ Write an SVG and rasterize each size:
71
+
72
+ ```js
73
+ // scripts/icons.mjs — run with `node scripts/icons.mjs`
74
+ import sharp from 'sharp';
75
+ import { mkdir } from 'node:fs/promises';
76
+
77
+ const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
78
+ <defs>
79
+ <radialGradient id="g" cx="50%" cy="40%" r="70%">
80
+ <stop offset="0%" stop-color="#7c4dff"/>
81
+ <stop offset="100%" stop-color="#06010f"/>
82
+ </radialGradient>
83
+ </defs>
84
+ <rect width="512" height="512" fill="url(#g)"/>
85
+ <!-- glyph goes here -->
86
+ </svg>`;
87
+
88
+ await mkdir('public/icons', { recursive: true });
89
+ const png = (size, out) =>
90
+ sharp(Buffer.from(svg)).resize(size, size).png().toFile(out);
91
+
92
+ await png(512, 'public/icons/icon-512.png');
93
+ await png(192, 'public/icons/icon-192.png');
94
+ await png(512, 'public/icons/icon-512-maskable.png');
95
+ ```
96
+
97
+ Two constraints that produce visible defects when ignored:
98
+
99
+ - **Prefer radial/linear gradients over blur filters.** `sharp`'s SVG rasterizer
100
+ renders Gaussian blur poorly; glows come out banded or clipped.
101
+ - **The maskable icon must be full-bleed and opaque** — no transparency, no
102
+ rounded corners, and keep the glyph inside the middle ~80% safe zone. The
103
+ platform applies its own mask, so transparent or pre-rounded edges show as
104
+ chipped corners on the launcher.
105
+
106
+ The `any` and `maskable` icons can be the same artwork only if that artwork is
107
+ already full-bleed. If the `any` icon has transparent padding, generate two.
108
+
109
+ ## Subpath hosting
110
+
111
+ Serving from `https://<DOMAIN>/<path>/` changes two manifest fields:
112
+
113
+ ```json
114
+ "start_url": "/<path>/",
115
+ "scope": "/<path>/"
116
+ ```
117
+
118
+ Icon `src` values can stay `/`-rooted if the icons are at the origin root, but
119
+ it is less error-prone to make them relative to the scope (`icons/icon-512.png`)
120
+ and let the manifest URL resolve them.
121
+
122
+ `assetlinks.json` is unaffected by this and must still be at the **origin
123
+ root** — see `iwsdk-hosting` §5.
124
+
125
+ ## Multi-origin 2D apps
126
+
127
+ If a 2D panel app legitimately navigates across origins, list them so they stay
128
+ in scope instead of bouncing to the browser:
129
+
130
+ ```json
131
+ "additional_trusted_origins": ["https://other.example"]
132
+ ```
133
+
134
+ Every listed origin must also serve `/.well-known/assetlinks.json` with the same
135
+ package name and certificate fingerprint. A missing one does not error — the
136
+ origin just falls out of scope at runtime.
137
+
138
+ ## Verify before packaging
139
+
140
+ ```bash
141
+ npm run build
142
+ for u in /manifest.webmanifest /icons/icon-192.png /icons/icon-512.png /icons/icon-512-maskable.png; do
143
+ printf '%s ' "$u"; curl -s -o /dev/null -w '%{http_code} %{content_type}\n' "https://<DOMAIN>$u"
144
+ done
145
+ ```
146
+
147
+ All 200. The manifest must be `application/manifest+json` — `text/plain` means
148
+ the host has no mapping for `.webmanifest`; fix it per
149
+ `iwsdk-hosting/references/existing-hosts.md`.
@@ -0,0 +1,104 @@
1
+ # Uploading to the Meta Horizon Store
2
+
3
+ Uploads go through Meta's `ovr-platform-util`. The same command handles
4
+ immersive and 2D builds — nothing about the upload differs by app mode.
5
+
6
+ ## Before uploading
7
+
8
+ - The app exists in the [Developer Dashboard](https://developer.oculus.com/manage/)
9
+ and you have its numeric **App ID**. `applicationId` in `twa-manifest.json`
10
+ must be that id, not `"0"` — rebuild if it is still the placeholder.
11
+ - The APK is signed with the app's permanent key, and asset links are live.
12
+ - The build has been sideloaded and launched on a headset. Store review is slow;
13
+ catching a wrong app mode here costs minutes instead of days.
14
+
15
+ ## Get the tool
16
+
17
+ ```bash
18
+ # macOS
19
+ curl -L -o ovr-platform-util \
20
+ "https://www.oculus.com/download_app/?id=1462426033810370&access_token=OC%7C1462426033810370%7C"
21
+ chmod +x ./ovr-platform-util && ./ovr-platform-util version
22
+ ```
23
+
24
+ Windows and Linux builds are linked from the Dashboard under Distribution →
25
+ Upload. On macOS, Gatekeeper may quarantine the binary on first run — the
26
+ developer clears it in System Settings → Privacy & Security, or with
27
+ `xattr -d com.apple.quarantine ./ovr-platform-util`.
28
+
29
+ Use the upload utility described here for this Store submission workflow.
30
+
31
+ ## Authentication
32
+
33
+ Two options — **ask the developer for one, never invent or guess a value:**
34
+
35
+ | Credential | Where | Flag |
36
+ | ---------- | ----- | ---- |
37
+ | App Secret | Dashboard → your app → **API** tab | `--app-secret` |
38
+ | User token | Dashboard → Account → Generate token | `--token` |
39
+
40
+ Treat either as a secret: pass it on the command line or through an environment
41
+ variable, never into a file under `public/`, and never into version control. If
42
+ one is pasted into the conversation, do not echo it back in later output.
43
+
44
+ ## Upload
45
+
46
+ ```bash
47
+ ./ovr-platform-util upload-quest-build \
48
+ --app-id <HORIZON_APP_ID> \
49
+ --app-secret <SECRET> \
50
+ --apk app-release-signed.apk \
51
+ --channel ALPHA \
52
+ --age-group MIXED_AGES \
53
+ --notes "Short description of this build" \
54
+ --disable-progress-bar
55
+ ```
56
+
57
+ | Flag | Required | Values |
58
+ | ---- | -------- | ------ |
59
+ | `--app-id` | yes | numeric Horizon App ID |
60
+ | `--apk` | yes | path to `app-release-signed.apk` |
61
+ | `--channel` | yes | `ALPHA` / `BETA` / `RC` for testing, `STORE` for production |
62
+ | `--age-group` | yes | `TEENS_AND_ADULTS` / `MIXED_AGES` / `CHILDREN` |
63
+ | `--app-secret` or `--token` | yes | one of the two |
64
+ | `--notes` | no | release notes |
65
+ | `--disable-progress-bar` | no | use it in agent/CI contexts; the animated bar floods the log |
66
+
67
+ Start on `ALPHA`. Promote to `STORE` from the Dashboard once the build has been
68
+ tested by real users on the channel.
69
+
70
+ A successful upload prints a **Build ID** and a `…/test-results/` URL. Report
71
+ both back to the developer — the test-results page is where automated VRC
72
+ checks land.
73
+
74
+ ## The blocker you should expect first
75
+
76
+ ```
77
+ must first agree to our Developer Distribution Agreement
78
+ ```
79
+
80
+ Nearly every organization's first upload fails this way. An **org admin** must
81
+ sign the DDA once at:
82
+
83
+ ```
84
+ https://developer.oculus.com/manage/organizations/<ORG_ID>/legal-documents/
85
+ ```
86
+
87
+ This is a legal action only the developer can take. **Pause, explain, and wait**
88
+ — then retry the identical command; nothing about the build needs to change.
89
+
90
+ ## Other responses worth recognizing
91
+
92
+ | Message | Meaning |
93
+ | ------- | ------- |
94
+ | Quest 1 not supported | harmless warning; Quest 1 is end-of-life |
95
+ | Signature does not match previous build | the APK was signed with a different key than the published app — reuse the original keystore |
96
+ | Version code must be higher | bump `appVersionCode` in `twa-manifest.json`, `bubblewrap update && bubblewrap build`, re-upload |
97
+ | App ID not found / unauthorized | `--app-id` and the secret belong to different apps, or the secret was regenerated |
98
+
99
+ ## After the upload
100
+
101
+ Store metadata — listing copy, screenshots, store art, age rating, VRC
102
+ compliance — is handled in the Dashboard, not by this tool. Uploading a build
103
+ does not submit it for review; that is a separate Dashboard action once a build
104
+ is promoted to the `STORE` channel.
@@ -0,0 +1,208 @@
1
+ # Troubleshooting
2
+
3
+ Failure modes across the whole pipeline. Most present on device as one of four
4
+ symptoms, so start there.
5
+
6
+ | Symptom on the headset | Most likely cause | Section |
7
+ | ---------------------- | ----------------- | ------- |
8
+ | "will not launch" | asset links | [Launch](#launch-failures) |
9
+ | Stuck on a loading screen | `horizonOSAppMode: "immersive"` on a 2D app | [App mode](#app-mode-failures) |
10
+ | Opens with a browser URL bar | `horizonOSAppMode: "2D"` on an immersive app | [App mode](#app-mode-failures) |
11
+ | Opens flat, no URL bar, never enters VR | auto-enter code missing or not firing | [App mode](#app-mode-failures) |
12
+ | Blank / white / error page | the origin is unreachable from the device | [Origin](#origin-failures) |
13
+ | Error page only when the headset is offline | no offline copy, or the app never launched online | [Offline](#offline-failures) |
14
+ | Old version after a web redeploy | an offline copy waiting for an idle moment or the next launch | [Offline](#offline-failures) |
15
+
16
+ Before diagnosing, establish which layer is wrong. A **web** bug is fixed by
17
+ republishing `<DOMAIN>`; a **native** bug needs a new APK and a new upload.
18
+ Read the built APK rather than guessing:
19
+
20
+ ```bash
21
+ "$BT/aapt" dump badging app-release-signed.apk | grep -iE '^package:|APP_MODE|OCULUS'
22
+ ```
23
+
24
+ ## App mode failures
25
+
26
+ ### 2D app stuck on a loading screen
27
+
28
+ `horizonOSAppMode` is `"immersive"`, so Horizon waits for a WebXR session that
29
+ never starts. Note the field **defaults to `immersive`** when absent or
30
+ misspelled, so an omitted field looks identical.
31
+
32
+ Set `"horizonOSAppMode": "2D"`, then `bubblewrap update && bubblewrap build` and
33
+ re-upload. Asset links do not change.
34
+
35
+ ### Immersive app shows a URL bar
36
+
37
+ `horizonOSAppMode` is `"2D"`. Set `"immersive"`, rebuild, re-upload.
38
+
39
+ ### Immersive app opens flat with no URL bar
40
+
41
+ The mode is right; the session is never requested. Check, in order:
42
+
43
+ 1. The auto-enter block is present in `src/index.ts` **inside** the
44
+ `World.create(...).then(...)` callback — placed before the world resolves,
45
+ `world` is undefined and the `.catch` swallows it.
46
+ 2. The queried mode matches `iwsdk.config.json`. An AR app must query
47
+ `isSessionSupported('immersive-ar')`; querying `immersive-vr` returns `false`
48
+ and the app stays flat with no error.
49
+ 3. The deployed bundle actually contains it —
50
+ `curl -s https://<DOMAIN>/assets/index-*.js | grep -c getDigitalGoodsService`.
51
+ A forgotten republish is the most common answer.
52
+
53
+ This is a web bug: republish `<DOMAIN>`, relaunch the app. No rebuild.
54
+
55
+ ### Auto-enter works on device but breaks the browser
56
+
57
+ The `getDigitalGoodsService` gate was removed or inverted. In a tab, the app
58
+ should keep its normal Enter-XR button; auto-requesting a session without a user
59
+ gesture there fails with a security error.
60
+
61
+ ## Launch failures
62
+
63
+ ### "will not launch"
64
+
65
+ Asset-link verification failed. Check all four in order:
66
+
67
+ ```bash
68
+ curl -s https://<DOMAIN>/.well-known/assetlinks.json
69
+ "$BT/apksigner" verify --print-certs app-release-signed.apk | grep -i SHA-256
70
+ ```
71
+
72
+ 1. **The file is reachable** — a 404 means the host stripped the dotfolder. See
73
+ `iwsdk-hosting/references/existing-hosts.md`; do not relocate the file, the
74
+ path is fixed.
75
+ 2. **`package_name` matches `packageId`** in `twa-manifest.json`, exactly.
76
+ 3. **`sha256_cert_fingerprints` matches the APK signer**, comparing hex bytes —
77
+ the two tools differ in case and colon placement, and that difference is not
78
+ the problem.
79
+ 4. **It is served as JSON, not HTML.** A SPA catch-all route that returns
80
+ `index.html` for unknown paths will answer 200 with the wrong body. Check the
81
+ body, not the status code.
82
+
83
+ On a multi-origin 2D app, every `additional_trusted_origins` host needs the
84
+ file too.
85
+
86
+ ### Signature mismatch on update
87
+
88
+ The build was signed with a different keystore than the published app. Reuse the
89
+ original keystore, alias, and passwords — there is no way to re-sign a published
90
+ app with a new key. A lost keystore means a new `packageId` and a new Store
91
+ entry.
92
+
93
+ ## Origin failures
94
+
95
+ ### Blank, white, or error page after launch
96
+
97
+ The device cannot load `<DOMAIN>`. Usually one of:
98
+
99
+ - **The hashed Vercel per-deploy URL was used** instead of the canonical alias —
100
+ it returns 401 under deployment protection. Fix `host`/`webManifestUrl` in
101
+ `twa-manifest.json`, rebuild, re-upload.
102
+ - **Deployment protection is on** for the whole project. A TWA cannot
103
+ authenticate through it; it must be disabled.
104
+ - **The origin is internal-only** and unreachable from the headset's network.
105
+ - **Certificate problems** — a self-signed or expired cert fails silently in the
106
+ web view.
107
+
108
+ Confirm from a machine on the same network as the headset:
109
+
110
+ ```bash
111
+ curl -s -o /dev/null -w '%{http_code}\n' https://<DOMAIN>/
112
+ ```
113
+
114
+ ### App loads but assets 404
115
+
116
+ Usually a subpath deployment with `start_url`/`scope` still set to `/`. Set them
117
+ to `/<path>/` and republish. The scaffolded `base: './'` handles the bundle
118
+ paths already, so if bundles load and only `public/` assets 404, look for a
119
+ publish that missed those files.
120
+
121
+ ## Offline failures
122
+
123
+ These apply only when the site keeps an offline copy (`iwsdk-offline`).
124
+
125
+ ### Error page only when the headset is offline
126
+
127
+ The device has no copy to serve. Usually one of:
128
+
129
+ - **No offline copy** — the site registers no service worker. Add one with
130
+ `iwsdk-offline`.
131
+ - **The app never launched online** since the copy was added. The copy is made
132
+ on the first online launch.
133
+ - **`start_url` or `scope` sits outside the worker's scope**, so the launch
134
+ misses the copy. Serve `sw.js` from the root of that scope.
135
+
136
+ Confirm the worker is live and uncached:
137
+
138
+ ```bash
139
+ curl -sI https://<DOMAIN>/sw.js | grep -iE '^(HTTP|cache-control)' # want 200, no-cache
140
+ ```
141
+
142
+ ### Old version after a web redeploy
143
+
144
+ Expected for one launch: the new release installs in the background during a
145
+ launch and takes over when the app is idle, or on the launch after that. If it
146
+ never arrives, `sw.js` is being cached — serve it with `Cache-Control: no-cache`
147
+ and purge the CDN.
148
+
149
+ ## Packaging failures
150
+
151
+ ### bubblewrap hangs or exits without doing anything
152
+
153
+ It is waiting on an `inquirer` prompt with no TTY — either `init`, or the
154
+ first-run JDK/Android SDK install. Have the developer run `bubblewrap doctor`
155
+ once in a real terminal, then use the scripted path (`update` + `build`) rather
156
+ than `init`.
157
+
158
+ ### Build fails with a keystore or password error
159
+
160
+ Passwords come only from `BUBBLEWRAP_KEYSTORE_PASSWORD` and
161
+ `BUBBLEWRAP_KEY_PASSWORD`; there are no CLI flags. Confirm both are exported in
162
+ the same shell as the build, that `signingKey.path` is absolute, and that
163
+ `signingKey.alias` matches the keystore's actual alias:
164
+
165
+ ```bash
166
+ "$KT" -list -keystore <keystore> -storepass <PW>
167
+ ```
168
+
169
+ ### bubblewrap update fails fetching the manifest
170
+
171
+ `update` reads `webManifestUrl` over the network. The manifest must be live and
172
+ 200 at that exact URL — not merely present in a local `dist/`.
173
+
174
+ ### Wrong icon in the launcher
175
+
176
+ `iconUrl` and `maskableIconUrl` are fetched at `update` time and baked into the
177
+ APK. Changing the icon on the host later does nothing; rebuild and re-upload.
178
+
179
+ ## Upload failures
180
+
181
+ ### "must first agree to our Developer Distribution Agreement"
182
+
183
+ The most common first-time blocker. An org admin signs it once at
184
+ `https://developer.oculus.com/manage/organizations/<ORG_ID>/legal-documents/`.
185
+ Pause, ask, then retry the identical command.
186
+
187
+ ### Version code must be higher
188
+
189
+ Bump `appVersionCode` in `twa-manifest.json`, then `bubblewrap update &&
190
+ bubblewrap build`. `update` also bumps it on its own, so this usually means an
191
+ earlier build was uploaded from a different working directory.
192
+
193
+ ## Security incidents
194
+
195
+ ### The keystore is reachable on the public host
196
+
197
+ It was generated inside the web tree and published. Move it out, republish,
198
+ confirm the URL 404s, and treat the key as compromised — generate a new one
199
+ under a new `packageId`, since the key/package pairing is permanent.
200
+
201
+ ```bash
202
+ curl -s -o /dev/null -w '%{http_code}\n' https://<DOMAIN>/android.keystore # want 404
203
+ ```
204
+
205
+ ### An app secret was committed or published
206
+
207
+ Regenerate it in the Dashboard (API tab) immediately; the old value stays valid
208
+ until you do.