@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,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.
@@ -0,0 +1,70 @@
1
+ ---
2
+ name: iwsdk-ray
3
+ description: Verify ray clicks, UIKit selections, and DistanceGrabbable interactions with emulated XR controllers. Use for pointing, selecting, pressing spatial UI, or moving an object through a distance grab.
4
+ argument-hint: '(use the current request)'
5
+ ---
6
+
7
+ # IWSDK Ray Interaction
8
+
9
+ Choose one interaction branch from measured target components. Ray clicks and
10
+ distance grabs share aiming but not input duration or movement behavior.
11
+
12
+ ## Locate and aim once
13
+
14
+ 1. Check XR session state and enter only when inactive.
15
+ 2. Find the named entity or runtime-named UIKit control, then query its
16
+ components and transform. For UIKit, prefer the live name assigned through
17
+ `requireElementById`; use a project test hook only when no addressable runtime
18
+ target exists.
19
+ 3. Aim the requested controller with `xr look-at`. Do not translate the
20
+ controller toward a ray target. The transform of an open shape (a ring, a
21
+ knot) can sit in empty space: aim at its surface, such as the rim at
22
+ transform + (0, radius, 0), and confirm `Hovered` before pressing.
23
+
24
+ ## Select exactly one branch
25
+
26
+ ### Click or UIKit button
27
+
28
+ For `RayInteractable`, `Pressed`, or a UIKit control, use one normal select:
29
+
30
+ ```bash
31
+ npx @iwsdk/cli xr select --input-json '{"device":"controller-right","duration":0.2}'
32
+ ```
33
+
34
+ Use an explicit select-value press/release only when the task needs to inspect
35
+ the held interval. Query the named application state or control effect after the
36
+ click; a screenshot alone is not interaction proof.
37
+
38
+ ### Distance grab
39
+
40
+ For `DistanceGrabbable`, hold trigger button index `0`, optionally move the
41
+ controller, then release index `0`:
42
+
43
+ ```json
44
+ {"device":"controller-right","buttons":[{"index":0,"value":1}]}
45
+ ```
46
+
47
+ Check `movementMode` before deciding whether the object should remain remote or
48
+ move toward the hand. Query `Grabbed` or transform state while held and after
49
+ release. Do not substitute squeeze index `1`; that is the proximity-grab path.
50
+
51
+ For `MoveFromTarget`, do not inspect implementation source. Before pressing,
52
+ record controller position `P` and object position `S`, and compute the grab
53
+ distance `d = |S - P|`. While trigger is held, call `xr look-at` with the
54
+ requested object destination as `target` and `moveToDistance: d`; this preserves
55
+ the ray distance while moving its endpoint to the destination. Query the object
56
+ before release to confirm the move, then release and query again.
57
+
58
+ ## Evidence and stopping
59
+
60
+ For a task with both a click and a distance grab, locate/aim/click/query the first
61
+ target, then locate/aim/hold-move-release/query the second. Do not rediscover the
62
+ CLI family, inspect pointer internals, or guess panel offsets from screenshots.
63
+
64
+ Capture one runtime image only when visual placement is part of the request.
65
+ When the request names an artifact path, save it directly with
66
+ `npx @iwsdk/cli browser screenshot --output-file <path>`; do not capture into model
67
+ context and then add a copy step.
68
+ Stop when the real input and resulting named state are proven, leaving all
69
+ buttons released.
70
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=ec23dce5226ca91367042de7907fb3664c055a1ceb737fede2fd6710eab1f37f name=iwsdk-ray (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->