@iwsdk/create 0.5.3 → 1.0.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 (106) hide show
  1. package/dist/cli.js +7224 -216
  2. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/SKILL.md +311 -0
  3. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  4. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  5. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/SKILL.md +262 -0
  6. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  7. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  8. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  9. package/dist/guidance/{claude/.claude/skills/iwsdk-scene-composer → agents/.agents/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
  10. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  11. package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
  12. package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +69 -91
  13. package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
  14. package/dist/guidance/agents/.agents/skills/iwsdk-dev/SKILL.md +45 -0
  15. package/dist/guidance/{claude/.claude/skills/iwsdk-planner → agents/.agents/skills/iwsdk-dev}/references/api-reference.md +53 -45
  16. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/iterate.md +239 -0
  17. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/planner.md +303 -0
  18. package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +37 -114
  19. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/SKILL.md +177 -0
  20. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  21. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
  22. package/dist/guidance/agents/.agents/skills/iwsdk-native-xr-test/SKILL.md +246 -0
  23. package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -78
  24. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
  25. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
  26. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  27. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  28. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  29. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  30. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  31. package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +45 -136
  32. package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +251 -157
  33. package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +9 -6
  34. package/dist/guidance/claude/.claude/rules/scene-json.md +6 -4
  35. package/dist/guidance/claude/.claude/settings.json +6 -2
  36. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/SKILL.md +311 -0
  37. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  38. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  39. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/SKILL.md +262 -0
  40. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  41. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  42. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  43. package/dist/guidance/{agents/.agents/skills/iwsdk-scene-composer → claude/.claude/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
  44. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  45. package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
  46. package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +69 -91
  47. package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
  48. package/dist/guidance/claude/.claude/skills/iwsdk-dev/SKILL.md +45 -0
  49. package/dist/guidance/{agents/.agents/skills/iwsdk-planner → claude/.claude/skills/iwsdk-dev}/references/api-reference.md +53 -45
  50. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/iterate.md +239 -0
  51. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/planner.md +303 -0
  52. package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +37 -114
  53. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/SKILL.md +177 -0
  54. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  55. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
  56. package/dist/guidance/claude/.claude/skills/iwsdk-native-xr-test/SKILL.md +246 -0
  57. package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -78
  58. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
  59. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
  60. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  61. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  62. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  63. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  64. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  65. package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +45 -136
  66. package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +251 -157
  67. package/dist/guidance/claude/CLAUDE.md +2 -141
  68. package/dist/guidance/codex/.codex/config.toml +1 -1
  69. package/dist/guidance/common/AGENTS.md +96 -37
  70. package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +6 -4
  71. package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +6 -4
  72. package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +6 -4
  73. package/dist/template/common/README.md +13 -0
  74. package/dist/template/common/public/ui/welcome.uikitml +0 -19
  75. package/dist/template/common/src/robot.ts +5 -0
  76. package/dist/template/common/vite.config.ts +18 -0
  77. package/dist/template/common-js/README.md +13 -0
  78. package/dist/template/common-js/public/ui/welcome.uikitml +0 -19
  79. package/dist/template/common-js/src/robot.js +5 -0
  80. package/dist/template/common-js/vite.config.js +18 -0
  81. package/package.json +8 -7
  82. package/scripts/verify-release-ready.mjs +25 -0
  83. package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +0 -364
  84. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +0 -243
  85. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +0 -101
  86. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +0 -176
  87. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +0 -156
  88. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +0 -199
  89. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +0 -257
  90. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
  91. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
  92. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
  93. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
  94. package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +0 -364
  95. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +0 -243
  96. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +0 -101
  97. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +0 -176
  98. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +0 -156
  99. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +0 -199
  100. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +0 -257
  101. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
  102. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
  103. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
  104. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
  105. /package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
  106. /package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
@@ -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 |
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,178 @@
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
+
14
+ Before diagnosing, establish which layer is wrong. A **web** bug is fixed by
15
+ republishing `<DOMAIN>`; a **native** bug needs a new APK and a new upload.
16
+ Read the built APK rather than guessing:
17
+
18
+ ```bash
19
+ "$BT/aapt" dump badging app-release-signed.apk | grep -iE '^package:|APP_MODE|OCULUS'
20
+ ```
21
+
22
+ ## App mode failures
23
+
24
+ ### 2D app stuck on a loading screen
25
+
26
+ `horizonOSAppMode` is `"immersive"`, so Horizon waits for a WebXR session that
27
+ never starts. Note the field **defaults to `immersive`** when absent or
28
+ misspelled, so an omitted field looks identical.
29
+
30
+ Set `"horizonOSAppMode": "2D"`, then `bubblewrap update && bubblewrap build` and
31
+ re-upload. Asset links do not change.
32
+
33
+ ### Immersive app shows a URL bar
34
+
35
+ `horizonOSAppMode` is `"2D"`. Set `"immersive"`, rebuild, re-upload.
36
+
37
+ ### Immersive app opens flat with no URL bar
38
+
39
+ The mode is right; the session is never requested. Check, in order:
40
+
41
+ 1. The auto-enter block is present in `src/index.ts` **inside** the
42
+ `World.create(...).then(...)` callback — placed before the world resolves,
43
+ `world` is undefined and the `.catch` swallows it.
44
+ 2. The queried mode matches `iwsdk.config.json`. An AR app must query
45
+ `isSessionSupported('immersive-ar')`; querying `immersive-vr` returns `false`
46
+ and the app stays flat with no error.
47
+ 3. The deployed bundle actually contains it —
48
+ `curl -s https://<DOMAIN>/assets/index-*.js | grep -c getDigitalGoodsService`.
49
+ A forgotten republish is the most common answer.
50
+
51
+ This is a web bug: republish `<DOMAIN>`, relaunch the app. No rebuild.
52
+
53
+ ### Auto-enter works on device but breaks the browser
54
+
55
+ The `getDigitalGoodsService` gate was removed or inverted. In a tab, the app
56
+ should keep its normal Enter-XR button; auto-requesting a session without a user
57
+ gesture there fails with a security error.
58
+
59
+ ## Launch failures
60
+
61
+ ### "will not launch"
62
+
63
+ Asset-link verification failed. Check all four in order:
64
+
65
+ ```bash
66
+ curl -s https://<DOMAIN>/.well-known/assetlinks.json
67
+ "$BT/apksigner" verify --print-certs app-release-signed.apk | grep -i SHA-256
68
+ ```
69
+
70
+ 1. **The file is reachable** — a 404 means the host stripped the dotfolder. See
71
+ `iwsdk-hosting/references/existing-hosts.md`; do not relocate the file, the
72
+ path is fixed.
73
+ 2. **`package_name` matches `packageId`** in `twa-manifest.json`, exactly.
74
+ 3. **`sha256_cert_fingerprints` matches the APK signer**, comparing hex bytes —
75
+ the two tools differ in case and colon placement, and that difference is not
76
+ the problem.
77
+ 4. **It is served as JSON, not HTML.** A SPA catch-all route that returns
78
+ `index.html` for unknown paths will answer 200 with the wrong body. Check the
79
+ body, not the status code.
80
+
81
+ On a multi-origin 2D app, every `additional_trusted_origins` host needs the
82
+ file too.
83
+
84
+ ### Signature mismatch on update
85
+
86
+ The build was signed with a different keystore than the published app. Reuse the
87
+ original keystore, alias, and passwords — there is no way to re-sign a published
88
+ app with a new key. A lost keystore means a new `packageId` and a new Store
89
+ entry.
90
+
91
+ ## Origin failures
92
+
93
+ ### Blank, white, or error page after launch
94
+
95
+ The device cannot load `<DOMAIN>`. Usually one of:
96
+
97
+ - **The hashed Vercel per-deploy URL was used** instead of the canonical alias —
98
+ it returns 401 under deployment protection. Fix `host`/`webManifestUrl` in
99
+ `twa-manifest.json`, rebuild, re-upload.
100
+ - **Deployment protection is on** for the whole project. A TWA cannot
101
+ authenticate through it; it must be disabled.
102
+ - **The origin is internal-only** and unreachable from the headset's network.
103
+ - **Certificate problems** — a self-signed or expired cert fails silently in the
104
+ web view.
105
+
106
+ Confirm from a machine on the same network as the headset:
107
+
108
+ ```bash
109
+ curl -s -o /dev/null -w '%{http_code}\n' https://<DOMAIN>/
110
+ ```
111
+
112
+ ### App loads but assets 404
113
+
114
+ Usually a subpath deployment with `start_url`/`scope` still set to `/`. Set them
115
+ to `/<path>/` and republish. The scaffolded `base: './'` handles the bundle
116
+ paths already, so if bundles load and only `public/` assets 404, look for a
117
+ publish that missed those files.
118
+
119
+ ## Packaging failures
120
+
121
+ ### bubblewrap hangs or exits without doing anything
122
+
123
+ It is waiting on an `inquirer` prompt with no TTY — either `init`, or the
124
+ first-run JDK/Android SDK install. Have the developer run `bubblewrap doctor`
125
+ once in a real terminal, then use the scripted path (`update` + `build`) rather
126
+ than `init`.
127
+
128
+ ### Build fails with a keystore or password error
129
+
130
+ Passwords come only from `BUBBLEWRAP_KEYSTORE_PASSWORD` and
131
+ `BUBBLEWRAP_KEY_PASSWORD`; there are no CLI flags. Confirm both are exported in
132
+ the same shell as the build, that `signingKey.path` is absolute, and that
133
+ `signingKey.alias` matches the keystore's actual alias:
134
+
135
+ ```bash
136
+ "$KT" -list -keystore <keystore> -storepass <PW>
137
+ ```
138
+
139
+ ### bubblewrap update fails fetching the manifest
140
+
141
+ `update` reads `webManifestUrl` over the network. The manifest must be live and
142
+ 200 at that exact URL — not merely present in a local `dist/`.
143
+
144
+ ### Wrong icon in the launcher
145
+
146
+ `iconUrl` and `maskableIconUrl` are fetched at `update` time and baked into the
147
+ APK. Changing the icon on the host later does nothing; rebuild and re-upload.
148
+
149
+ ## Upload failures
150
+
151
+ ### "must first agree to our Developer Distribution Agreement"
152
+
153
+ The most common first-time blocker. An org admin signs it once at
154
+ `https://developer.oculus.com/manage/organizations/<ORG_ID>/legal-documents/`.
155
+ Pause, ask, then retry the identical command.
156
+
157
+ ### Version code must be higher
158
+
159
+ Bump `appVersionCode` in `twa-manifest.json`, then `bubblewrap update &&
160
+ bubblewrap build`. `update` also bumps it on its own, so this usually means an
161
+ earlier build was uploaded from a different working directory.
162
+
163
+ ## Security incidents
164
+
165
+ ### The keystore is reachable on the public host
166
+
167
+ It was generated inside the web tree and published. Move it out, republish,
168
+ confirm the URL 404s, and treat the key as compromised — generate a new one
169
+ under a new `packageId`, since the key/package pairing is permanent.
170
+
171
+ ```bash
172
+ curl -s -o /dev/null -w '%{http_code}\n' https://<DOMAIN>/android.keystore # want 404
173
+ ```
174
+
175
+ ### An app secret was committed or published
176
+
177
+ Regenerate it in the Dashboard (API tab) immediately; the old value stays valid
178
+ until you do.