@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.
- package/README.md +79 -2
- package/dist/agent-adapters.d.ts +12 -1
- package/dist/agent-adapters.d.ts.map +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +312 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +277 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +74 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +46 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +1531 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +263 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/planner.md +307 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +282 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +75 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +178 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +262 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +106 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/component-reference.md +152 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +70 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +328 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +521 -0
- package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +60 -0
- package/dist/agent-guidance/files/.claude/rules/ecs-api.md +103 -0
- package/dist/agent-guidance/files/.claude/rules/scene-json.md +72 -0
- package/dist/agent-guidance/files/.claude/rules/uikitml.md +66 -0
- package/dist/agent-guidance/files/.claude/settings.json +29 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +312 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +277 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +74 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +46 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +1531 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +263 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/planner.md +307 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +282 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +75 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +178 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +262 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +106 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/component-reference.md +152 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +70 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +328 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +62 -0
- package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +105 -0
- package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +74 -0
- package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +68 -0
- package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +55 -0
- package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +101 -0
- package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +71 -0
- package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +65 -0
- package/{guidance → dist/agent-guidance/files}/AGENTS.md +107 -27
- package/dist/agent-guidance/files/CLAUDE.md +3 -0
- package/dist/agent-guidance/files/public/scenes/AGENTS.md +72 -0
- package/dist/agent-guidance/files/public/ui/AGENTS.md +66 -0
- package/dist/agent-guidance/files/src/AGENTS.md +153 -0
- package/dist/agent-guidance/manifest.json +854 -0
- package/dist/agent-guidance.d.ts +113 -0
- package/dist/agent-guidance.d.ts.map +1 -0
- package/dist/agent-guidance.js +3403 -0
- package/dist/agent-guidance.js.map +1 -0
- package/dist/cli.js +2407 -144
- package/dist/cli.js.map +1 -1
- package/dist/commands/adapter.d.ts +1 -0
- package/dist/commands/adapter.d.ts.map +1 -1
- package/dist/commands/agents.d.ts +11 -0
- package/dist/commands/agents.d.ts.map +1 -0
- package/dist/commands/browser.d.ts +11 -0
- package/dist/commands/browser.d.ts.map +1 -1
- package/dist/commands/dev.d.ts +1 -0
- package/dist/commands/dev.d.ts.map +1 -1
- package/dist/commands/reference.d.ts +15 -1
- package/dist/commands/reference.d.ts.map +1 -1
- package/dist/commands/runtime.d.ts.map +1 -1
- package/dist/commands/upgrade.d.ts +51 -0
- package/dist/commands/upgrade.d.ts.map +1 -0
- package/dist/contract.js +32 -0
- package/dist/contract.js.map +1 -1
- package/dist/guidance-refresh.d.ts +33 -0
- package/dist/guidance-refresh.d.ts.map +1 -0
- package/dist/help.d.ts +2 -0
- package/dist/help.d.ts.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4744 -135
- package/dist/index.js.map +1 -1
- package/dist/mcp-stdio.d.ts.map +1 -1
- package/dist/migrations/iwsdk-migrate-0-5/SKILL.md +413 -0
- package/dist/migrations.d.ts +36 -0
- package/dist/migrations.d.ts.map +1 -0
- package/dist/package-manager.d.ts +28 -0
- package/dist/package-manager.d.ts.map +1 -0
- package/dist/release-notes.d.ts +28 -0
- package/dist/release-notes.d.ts.map +1 -0
- package/dist/release-notes.json +1374 -0
- package/dist/runtime-contract.d.ts +8 -0
- package/dist/runtime-contract.d.ts.map +1 -1
- package/dist/runtime-telemetry.d.ts +8 -1
- package/dist/runtime-telemetry.d.ts.map +1 -1
- package/dist/version.d.ts +1 -1
- 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`.
|
package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md
ADDED
|
@@ -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.
|
package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md
ADDED
|
@@ -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) -->
|