@iwsdk/create 0.5.2 → 1.0.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 (107) hide show
  1. package/dist/cli.js +7223 -215
  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/dist/template/scenes/ar.iwsdk.scene.json +8 -1
  82. package/package.json +8 -7
  83. package/scripts/verify-release-ready.mjs +25 -0
  84. package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +0 -364
  85. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +0 -243
  86. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +0 -101
  87. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +0 -176
  88. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +0 -156
  89. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +0 -199
  90. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +0 -257
  91. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
  92. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
  93. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
  94. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
  95. package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +0 -364
  96. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +0 -243
  97. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +0 -101
  98. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +0 -176
  99. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +0 -156
  100. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +0 -199
  101. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +0 -257
  102. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
  103. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
  104. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
  105. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
  106. /package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
  107. /package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
@@ -0,0 +1,181 @@
1
+ # Publishing to an Existing Host
2
+
3
+ Use this when the developer already has hosting. **You prepare files and stop**
4
+ — they publish. Your job is to make the handoff precise: the exact local files,
5
+ the exact public URLs, the exact command or click path for their host, and then
6
+ verification once they confirm.
7
+
8
+ Everything the app needs is inside `dist/` after `npm run build` (Vite copies
9
+ `public/` verbatim, dotfolders included), so in most cases the handoff is simply
10
+ "publish `dist/`". The recipes below exist for the cases where it is not.
11
+
12
+ ## The two moments that need a publish
13
+
14
+ 1. **Manifest + icons** — before `bubblewrap update`, which fetches them over
15
+ the network.
16
+ 2. **`.well-known/assetlinks.json`** — after the signing keystore exists. The
17
+ TWA will not launch until this is live. This is the one that gets forgotten,
18
+ and the one hosts most often break.
19
+
20
+ ## Universal gotchas
21
+
22
+ **Dotfolders get stripped.** Several hosts and build pipelines ignore
23
+ `.`-prefixed paths, so `.well-known/` silently never ships. Symptom: everything
24
+ else is 200, `/.well-known/assetlinks.json` is 404, and the installed app opens
25
+ to "will not launch". The path is fixed by the TWA spec — fix the host, do not
26
+ relocate the file.
27
+
28
+ **`.webmanifest` has no MIME mapping.** Older servers serve it as `text/plain`
29
+ or `application/octet-stream`. Either add the mapping
30
+ (`application/manifest+json`) or rename to `manifest.json` and update both
31
+ `<link rel="manifest">` in `index.html` and `webManifestUrl` in
32
+ `twa-manifest.json`.
33
+
34
+ **Aggressive CDN caching.** After the asset-links publish, a cached 404 keeps
35
+ the TWA broken long after the file is live. Purge the cache, then verify.
36
+
37
+ **Subpath hosting.** `assetlinks.json` must be at the origin root even when the
38
+ app is at `/<path>/`. See §5 of `SKILL.md`.
39
+
40
+ ## Per-host recipes
41
+
42
+ ### Netlify
43
+
44
+ ```bash
45
+ npm run build
46
+ npx -y netlify-cli deploy --prod --dir=dist
47
+ ```
48
+
49
+ Dotfolders in the publish directory are served as-is; no config needed. If a
50
+ build plugin or a `.gitignore` rule is dropping `.well-known/`, publish `dist/`
51
+ directly as above rather than letting Netlify build from source.
52
+
53
+ MIME types are inferred correctly. To force one, add to `netlify.toml`:
54
+
55
+ ```toml
56
+ [[headers]]
57
+ for = "/manifest.webmanifest"
58
+ [headers.values]
59
+ Content-Type = "application/manifest+json"
60
+ ```
61
+
62
+ ### Cloudflare Pages
63
+
64
+ ```bash
65
+ npm run build
66
+ npx -y wrangler pages deploy dist --project-name <project>
67
+ ```
68
+
69
+ Pages skips dot-prefixed files on upload but makes an explicit exception for
70
+ `.well-known/`, so asset links normally work with no configuration. Verify
71
+ rather than trust it — a custom build step or an `.assetsignore` entry can still
72
+ drop the directory:
73
+
74
+ ```bash
75
+ curl -s -o /dev/null -w '%{http_code}\n' https://<DOMAIN>/.well-known/assetlinks.json
76
+ ```
77
+
78
+ If that 404s, emit a second copy at `public/assetlinks.json` and rewrite the
79
+ dotted path to it with a `_redirects` rule (status `200` = rewrite, not
80
+ redirect — a 3xx does not satisfy asset-link verification):
81
+
82
+ ```
83
+ # public/_redirects
84
+ /.well-known/assetlinks.json /assetlinks.json 200
85
+ ```
86
+
87
+ Re-verify that the dotted URL returns the JSON body itself.
88
+
89
+ ### GitHub Pages
90
+
91
+ ```bash
92
+ npm run build
93
+ npx -y gh-pages -d dist --dotfiles
94
+ ```
95
+
96
+ `--dotfiles` is **required** — without it `.well-known/` is silently omitted.
97
+ Also add an empty `public/.nojekyll` file, or Jekyll strips underscore- and
98
+ dot-prefixed paths during the Pages build.
99
+
100
+ Project sites (`https://<user>.github.io/<repo>/`) are a subpath deployment:
101
+ `start_url`/`scope` become `/<repo>/`, and `assetlinks.json` must live in the
102
+ `<user>.github.io` **user/organization** repository so it is served from the
103
+ origin root. If the developer does not control that repo, they cannot ship a TWA
104
+ from this origin — say so and offer Vercel.
105
+
106
+ ### AWS S3 + CloudFront
107
+
108
+ ```bash
109
+ npm run build
110
+ aws s3 sync dist/ s3://<bucket>/ --delete
111
+ aws s3 cp dist/manifest.webmanifest s3://<bucket>/manifest.webmanifest \
112
+ --content-type application/manifest+json
113
+ aws s3 cp dist/.well-known/assetlinks.json s3://<bucket>/.well-known/assetlinks.json \
114
+ --content-type application/json
115
+ aws cloudfront create-invalidation --distribution-id <id> --paths '/*'
116
+ ```
117
+
118
+ `aws s3 sync` guesses content types from the extension and gets `.webmanifest`
119
+ wrong, so re-upload those two files explicitly. The CloudFront invalidation is
120
+ not optional — a cached 404 on `assetlinks.json` keeps the TWA broken.
121
+
122
+ ### Firebase Hosting
123
+
124
+ ```bash
125
+ npm run build
126
+ npx -y firebase-tools deploy --only hosting
127
+ ```
128
+
129
+ Set `"public": "dist"` in `firebase.json`. Firebase serves `.well-known/`
130
+ correctly, but an `"ignore"` entry containing `"**/.*"` — which is in the
131
+ default generated config — will drop it. Remove or narrow that pattern.
132
+
133
+ ### nginx / Apache on a VPS
134
+
135
+ ```bash
136
+ npm run build
137
+ rsync -av --delete dist/ <user>@<host>:/var/www/<site>/
138
+ ```
139
+
140
+ nginx: add the manifest MIME type and make sure no `location ~ /\.` rule is
141
+ denying dotfolders — the common hardening snippet `location ~ /\. { deny all; }`
142
+ blocks `.well-known/`. Allow it explicitly:
143
+
144
+ ```nginx
145
+ location ^~ /.well-known/ { allow all; }
146
+ types { application/manifest+json webmanifest; }
147
+ ```
148
+
149
+ Apache: the equivalent trap is `<FilesMatch "^\.">` or a `RedirectMatch` rule
150
+ denying dot paths.
151
+
152
+ ```apache
153
+ AddType application/manifest+json .webmanifest
154
+ <Directory "/var/www/<site>/.well-known">
155
+ Require all granted
156
+ </Directory>
157
+ ```
158
+
159
+ ### Unknown or internal host
160
+
161
+ Do not guess. Ask two questions and adapt:
162
+
163
+ 1. How do you normally publish a build — a CLI command, a CI pipeline, or a
164
+ dashboard upload?
165
+ 2. Can the origin serve a path beginning with a dot (`/.well-known/...`)?
166
+
167
+ Then produce the handoff in the same shape as the recipes above: exact files,
168
+ exact URLs, their command, and the verification you will run afterwards.
169
+
170
+ ## Verify after every publish
171
+
172
+ ```bash
173
+ for u in / /manifest.webmanifest /icons/icon-512.png /.well-known/assetlinks.json; do
174
+ printf '%s ' "$u"; curl -s -o /dev/null -w '%{http_code} %{content_type}\n' "https://<DOMAIN>$u"
175
+ done
176
+ curl -s -o /dev/null -w 'keystore %{http_code} (want 404)\n' "https://<DOMAIN>/android.keystore"
177
+ ```
178
+
179
+ Report the actual status codes back to the developer rather than a bare "looks
180
+ good" — a 200 on the keystore URL, or a 404 on asset links, is the whole
181
+ difference between a working app and a launch failure diagnosed hours later.
@@ -0,0 +1,114 @@
1
+ # Vercel Deployment
2
+
3
+ The recommended host when the developer has not already chosen one. Vercel
4
+ auto-detects Vite, serves `dist/` over HTTPS on a stable public alias, preserves
5
+ `public/` dotfolders (`.well-known/`), serves `.webmanifest` with the right MIME
6
+ type, and redeploys in one command — which matters because Digital Asset Links
7
+ force a second publish after the APK is signed.
8
+
9
+ ## Prerequisites
10
+
11
+ The scaffolded `vite.config.*` is already correct — `base: './'`,
12
+ `publicDir: 'public'`, `build.outDir: 'dist'`. Nothing to change.
13
+
14
+ ```bash
15
+ npm run build # → dist/
16
+ ls dist # sanity: index.html, assets/, icons/, manifest.webmanifest
17
+ ```
18
+
19
+ ## First run: authentication
20
+
21
+ ```bash
22
+ npx -y vercel@latest whoami
23
+ ```
24
+
25
+ If this errors, the developer is not logged in. `vercel login` is interactive
26
+ (it prompts for an email/SSO choice and waits on a browser round trip), so an
27
+ agent cannot complete it — **hand it off**: ask them to run `npx vercel login`
28
+ in their terminal, or to paste `! npx vercel login` into this session, then
29
+ re-run `whoami`.
30
+
31
+ For CI or an unattended run, a token works instead and skips the prompt:
32
+
33
+ ```bash
34
+ npx -y vercel@latest deploy --prod --yes --token "$VERCEL_TOKEN"
35
+ ```
36
+
37
+ ## Find the scope
38
+
39
+ Personal accounts need no `--scope`. Team accounts do — omitting it deploys to
40
+ the wrong place or fails outright:
41
+
42
+ ```bash
43
+ npx -y vercel@latest teams ls
44
+ ```
45
+
46
+ ## Deploy
47
+
48
+ ```bash
49
+ npx -y vercel@latest deploy --prod --yes --scope <team-slug>
50
+ ```
51
+
52
+ `--yes` accepts the project-creation and link prompts, so the command is
53
+ non-interactive. Vite is auto-detected: Vercel runs `vite build` and serves
54
+ `dist/`.
55
+
56
+ ## Two URLs come back — only one is usable
57
+
58
+ | URL | Behavior | Use as `<DOMAIN>`? |
59
+ | --- | -------- | ------------------ |
60
+ | Canonical alias `https://<project>.vercel.app` | public, 200 | **yes** |
61
+ | Hashed per-deploy `https://<project>-<hash>-<team>.vercel.app` | 401 under team deployment protection | no |
62
+
63
+ The hashed URL is what the CLI prints most prominently, which is exactly how it
64
+ ends up baked into a `twa-manifest.json` by mistake. The resulting APK fetches a
65
+ 401 and the app shows a blank or error screen on the headset. Always confirm the
66
+ alias returns 200 before using it anywhere downstream:
67
+
68
+ ```bash
69
+ curl -s -o /dev/null -w '%{http_code}\n' https://<project>.vercel.app/
70
+ ```
71
+
72
+ If the canonical alias is also 401, deployment protection is enabled for the
73
+ whole project. It must be turned off (Project → Settings → Deployment
74
+ Protection) — a TWA cannot authenticate through it. This is the developer's
75
+ call: pause and ask.
76
+
77
+ ## Custom domain
78
+
79
+ If they want a real domain instead of `*.vercel.app`, add it before packaging —
80
+ the domain is baked into `twa-manifest.json` and the asset links, so changing it
81
+ later means a new APK and a new Store build:
82
+
83
+ ```bash
84
+ npx -y vercel@latest domains add <domain> --scope <team-slug>
85
+ ```
86
+
87
+ ## Verify
88
+
89
+ ```bash
90
+ for u in / /manifest.webmanifest /icons/icon-512.png; do
91
+ printf '%s ' "$u"
92
+ curl -s -o /dev/null -w '%{http_code} %{content_type}\n' "https://<DOMAIN>$u"
93
+ done
94
+ ```
95
+
96
+ The manifest should be `application/manifest+json`. Vercel infers this from the
97
+ `.webmanifest` extension with no configuration.
98
+
99
+ ## Redeploying
100
+
101
+ Re-run the same deploy command. The alias moves to the new deployment; the
102
+ installed TWA picks up the change on its next launch, with no rebuild and no
103
+ Store upload.
104
+
105
+ The second deploy in this pipeline is the asset-links one: after the keystore
106
+ exists, write `public/.well-known/assetlinks.json`, then `npm run build` and
107
+ deploy again. Vite copies dotfolders out of `public/`, and Vercel serves them —
108
+ no `vercel.json` needed.
109
+
110
+ ## When not to use Vercel
111
+
112
+ If the app needs a backend, private networking, or an existing corporate CDN,
113
+ this is the wrong recommendation. Ask, and fall back to Route B (existing host)
114
+ in `SKILL.md`.
@@ -0,0 +1,246 @@
1
+ ---
2
+ name: iwsdk-native-xr-test
3
+ description: Test an IWSDK app in a real Quest immersive session while controlling headset and controller poses through the IWSDK CLI. Use when the user asks to run, automate, or debug an app on a connected Quest rather than in desktop IWER emulation.
4
+ argument-hint: '[test scenario]'
5
+ ---
6
+
7
+ # Test on a physical Quest
8
+
9
+ Run the app through an ADB-reversed localhost connection, enter the browser's
10
+ real immersive session, and use the ordinary IWSDK XR, ECS, scene, and browser
11
+ commands to observe and control it. The native browser continues to own
12
+ `XRSession`, frame scheduling, rendering, and tracking; IWSDK/IWER selectively
13
+ override poses and input for the test.
14
+
15
+ The requested scenario is in `$ARGUMENTS`.
16
+
17
+ ## Safety and scope
18
+
19
+ - Use only public Android platform tools and IWSDK commands. Do not depend on a
20
+ device-rental service, XRPilot, or internal Meta tooling.
21
+ - Always work with an explicit device serial. With exactly one authorized
22
+ device in `adb devices`, use its serial. With several connected devices,
23
+ require the user to name the serial to test; never choose one yourself. Pass
24
+ `-s <serial>` to every ADB command and use the same serial as the IWSDK
25
+ `headsetId`.
26
+ - Support Quest Browser only. Do not broaden the browser user-agent check.
27
+ - Keep the command bridge on loopback. Use `adb reverse`; never expose or
28
+ forward the bridge over a LAN.
29
+ - Native control replaces the headset's native controller input sources with
30
+ synthetic controllers for the duration of the test. Physical controller and
31
+ hand-action playback are unavailable while the override is installed.
32
+ - `xr set-transform` applies absolute test poses, not offsets from live
33
+ tracking.
34
+ - A first run may show an immersive-WebXR permission prompt in the headset.
35
+ Ask the user to approve it physically, then relaunch. Do not automate that
36
+ permission dialog.
37
+ - Always remove the ADB reverse and stop the dev session during cleanup,
38
+ including after a failed test.
39
+
40
+ ## Target the headset explicitly
41
+
42
+ A command without `runtimeTarget` always routes to the managed host browser,
43
+ never to a headset, even when a paired headset page is the only connected page.
44
+ This workflow starts with `--no-open`, so such a command fails with
45
+ `browser_not_launched`. Do not restart with `--open` to fix a headset command;
46
+ the managed browser never forwards commands to the Quest.
47
+
48
+ - Discover connected targets with `npx @iwsdk/cli runtime targets --raw`. Each
49
+ entry in `targets` carries a nested `runtimeTarget` object and the `methods`
50
+ that page supports.
51
+ - A headset page qualifies only when its entry has `deviceClass: "physical"`,
52
+ `role: "app"`, `commandReady: true`, and a `headsetId` equal to the explicit
53
+ serial.
54
+ - Copy the qualifying entry's complete `runtimeTarget` unchanged: `deviceClass`,
55
+ `headsetId`, `pageId`, `tabGeneration`, and any returned `sessionId` or
56
+ `browserEpoch`. Never rebuild it from separate fields, drop or edit a field,
57
+ or pass the surrounding entry instead.
58
+ - Put it under the top-level `runtimeTarget` key of every headset command's
59
+ `--input-json`, next to that command's own parameters. It is unrelated to the
60
+ position-vector `target` parameter of commands such as `xr look-at`.
61
+ - Never select a headset page with `expectedTab` alone. It carries no
62
+ `deviceClass` or `headsetId`, so the command stays on the managed browser.
63
+ - Never guess between candidates. If these rules do not identify exactly one
64
+ page, or a command returns `ambiguous_target`, ask the user to close the extra
65
+ app tabs in the headset, then rediscover. Do not fall back to list order, the
66
+ newest entry, another headset, or an untargeted command.
67
+ - A reload or relaunch advances the page generation. After one, or after a
68
+ `stale_browser_tab` or `target_unavailable` error, run `runtime targets` again
69
+ and reselect with these rules. An old `runtimeTarget` stays fenced to its
70
+ generation.
71
+ - `outcome_unknown` means the command may have executed. Never replay it.
72
+ Rediscover the target, inspect state with read-only commands such as
73
+ `xr status`, `ecs query`, or `scene transform`, and only then decide whether a
74
+ new command is needed.
75
+ - Headset pages accept runtime commands only. Host-only browser tools, such as
76
+ screenshots, snapshots, interaction, profiling, and console capture, return
77
+ `unsupported_on_target`; check the entry's `methods` first.
78
+
79
+ To test several headsets in one dev session, set up each serial separately: one
80
+ `adb -s <serial> reverse` route and one `runtime pair-headset` call per device,
81
+ discovery by each device's own `headsetId`, and one recorded `runtimeTarget` per
82
+ headset. Send each command with the `runtimeTarget` of the headset it is meant
83
+ for; never reuse one headset's `runtimeTarget` for another.
84
+
85
+ ## 1. Verify the app and device
86
+
87
+ Run `npm run --if-present typecheck` and fix type errors before device testing.
88
+
89
+ Run `adb devices` and settle the explicit serial as described above. Continue
90
+ only when that serial is in the `device` state. A `pending`, `offline`, or
91
+ `unauthorized` device is not ready.
92
+
93
+ This workflow expects a manifest-first app that imports
94
+ `virtual:iwsdk-project` and passes it to `World.create()`. For a hand-built
95
+ `WorldOptions` object, opt in explicitly with:
96
+
97
+ ```ts
98
+ xr: {
99
+ // existing XR options
100
+ launchOnSessionGranted: true,
101
+ }
102
+ ```
103
+
104
+ ## 2. Start the native-control dev session
105
+
106
+ From the application root, run:
107
+
108
+ ```bash
109
+ npx @iwsdk/cli dev up --native-xr-control --no-open
110
+ ```
111
+
112
+ Inspect `npx @iwsdk/cli dev status` and record the numeric port from the
113
+ active runtime. Native-control sessions default to HTTP when the application
114
+ does not explicitly configure Vite HTTPS. The app is loaded from
115
+ headset-localhost through ADB reverse, so the default remains a trustworthy
116
+ WebXR origin. `--no-open` leaves the managed host browser unlaunched, so only
117
+ commands that carry the headset's `runtimeTarget` can run.
118
+
119
+ ## 3. Install the ADB route and pair the headset
120
+
121
+ Replace `<serial>` and `<port>` with the values verified above:
122
+
123
+ ```bash
124
+ adb -s <serial> reverse tcp:<port> tcp:<port>
125
+ npx @iwsdk/cli runtime pair-headset --input-json '{"headsetId":"<serial>"}' --raw
126
+ ```
127
+
128
+ Record the returned `url`. It carries this headset's pairing token for the
129
+ current dev session; an unpaired headset page is refused and never becomes a
130
+ target. Continue only if the URL points at `localhost` or `127.0.0.1` on
131
+ `<port>`. Pair again after any dev-session restart.
132
+
133
+ ## 4. Enter the real immersive session
134
+
135
+ Before each launch, run `npx @iwsdk/cli runtime targets --raw` and record the
136
+ `pageId` and `tabGeneration` of every physical target whose `headsetId` is
137
+ `<serial>`.
138
+
139
+ URL-encode the returned pairing URL without changing its host or dropping its
140
+ query, then launch:
141
+
142
+ ```bash
143
+ adb -s <serial> shell am broadcast \
144
+ -n com.oculus.vrshell/.ShellControlBroadcastReceiver \
145
+ -a com.oculus.vrshell.intent.action.LAUNCH \
146
+ -d apk://com.oculus.browser \
147
+ -e uri "ovrweb://vr?uri=<encoded-pairing-url>"
148
+ ```
149
+
150
+ Keep the nested URL encoded so `?`, `&`, and fragment characters cannot be
151
+ interpreted as parameters of the outer deep link.
152
+
153
+ Poll `npx @iwsdk/cli runtime targets --raw`. Select the qualifying target that
154
+ this launch created: its `pageId` was not recorded, or its `tabGeneration` is
155
+ higher than recorded. If exactly one target matches, record its complete
156
+ `runtimeTarget`. A physical target has this shape:
157
+
158
+ ```json
159
+ {
160
+ "deviceClass": "physical",
161
+ "headsetId": "<serial>",
162
+ "pageId": "<pageId>",
163
+ "tabGeneration": 1,
164
+ "sessionId": "<sessionId>"
165
+ }
166
+ ```
167
+
168
+ If no target appears, check in the headset that the page loaded from the
169
+ pairing URL and did not redirect to a network hostname. If more than one
170
+ matches, ask the user to close the extra tabs and relaunch.
171
+
172
+ Replace `<runtimeTarget>` below with the recorded object, verbatim:
173
+
174
+ ```bash
175
+ npx @iwsdk/cli xr status --input-json '{"runtimeTarget":<runtimeTarget>}' --raw
176
+ ```
177
+
178
+ XR status must show an active `immersive-vr` or `immersive-ar` session. Its
179
+ `browserConnected` and `browserCommandReady` fields describe the managed host
180
+ browser, not the headset. If the session stays inactive, ask the user to accept
181
+ the one-time browser permission in the headset, then repeat this step from the
182
+ pre-launch record.
183
+
184
+ Do not use `iwsdk xr enter` for this step: that command accepts an emulated
185
+ offer, while this workflow must preserve the browser's native session.
186
+
187
+ ## 5. Run the scenario
188
+
189
+ Discover the available command shapes before improvising:
190
+
191
+ ```bash
192
+ npx @iwsdk/cli xr --help
193
+ npx @iwsdk/cli ecs --help
194
+ npx @iwsdk/cli scene --help
195
+ ```
196
+
197
+ Add the recorded `runtimeTarget` to each command's `--input-json`, next to the
198
+ command's own parameters. Here `target` is the world position to aim at:
199
+
200
+ ```bash
201
+ npx @iwsdk/cli xr look-at --input-json \
202
+ '{"device":"controller-right","target":{"x":0,"y":1.2,"z":-1},"runtimeTarget":<runtimeTarget>}' --raw
203
+ ```
204
+
205
+ The exact `runtimeTarget` both selects the intended headset page and rejects
206
+ stale commands after a page reload.
207
+
208
+ Use the same commands as desktop automation. Typical controls are:
209
+
210
+ - `xr set-transform` for headset or controller position/orientation.
211
+ - `xr look-at` to aim a controller ray at a world position.
212
+ - `xr set-select-value` or `xr select` for trigger/pinch interaction.
213
+ - `xr set-gamepad-state` for squeeze and controller buttons.
214
+ - `ecs query`, `ecs snapshot`, and `ecs diff` for authoritative state.
215
+ - `scene runtime-hierarchy` and `scene transform` to locate and measure
216
+ rendered objects.
217
+
218
+ Prove behavior with state, not only screenshots. For an interaction test,
219
+ record the target transform or component state before the action, perform the
220
+ pose/input sequence, and show the corresponding state change afterward.
221
+
222
+ ## 6. Exit and clean up
223
+
224
+ Run these cleanup actions individually even if an earlier assertion failed:
225
+
226
+ ```bash
227
+ npx @iwsdk/cli xr exit --input-json '{"runtimeTarget":<runtimeTarget>}' --raw
228
+ adb -s <serial> reverse --remove tcp:<port>
229
+ npx @iwsdk/cli dev down
230
+ ```
231
+
232
+ Use the most recently discovered `runtimeTarget` for `xr exit`. If it returns
233
+ `stale_browser_tab` or `target_unavailable`, rediscover and exit with the fresh
234
+ object; if it returns `outcome_unknown`, check `xr status` instead of repeating
235
+ the exit. Remove the reverse route from every device you configured.
236
+
237
+ Report:
238
+
239
+ - device serial (`headsetId`) and app URL used;
240
+ - the exact `runtimeTarget` of the final command;
241
+ - native session mode and enabled features;
242
+ - the selected target's command-ready state;
243
+ - pose/input actions performed;
244
+ - before/after evidence for the requested behavior;
245
+ - console errors or capability notes;
246
+ - confirmation that the reverse route and dev session were removed.