@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,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,262 @@
1
+ ---
2
+ name: iwsdk-native-xr-test
3
+ description: Drive an IWSDK app in a real Quest immersive session while you control headset and controller poses through the IWSDK CLI. Use when you will automate, script-test, or debug an app on a connected Quest. Not for the user trying the app by hand; native control takes over their head pose and controllers, so give them a plain dev session instead.
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
+ ## Not for hands-on testing
18
+
19
+ Use this skill only when you drive the headset. If the user wants to put the
20
+ headset on and try the app themselves, do not start native control and do not
21
+ give them a pairing URL. A `--native-xr-control` session overrides the head pose
22
+ and controllers of every Quest Browser page it serves, even after the pairing
23
+ token is removed from the URL; the page shows an "Agent-controlled page"
24
+ notice saying so. Restart without the flag and hand over a plain URL as described in
25
+ AGENTS.md. If a native-control test is running when the user asks to try the
26
+ app, finish or stop it, clean up as in step 6, then do the same.
27
+
28
+ ## Safety and scope
29
+
30
+ - Use only public Android platform tools and IWSDK commands. Do not depend on a
31
+ device-rental service, XRPilot, or internal Meta tooling.
32
+ - Always work with an explicit device serial. With exactly one authorized
33
+ device in `adb devices`, use its serial. With several connected devices,
34
+ require the user to name the serial to test; never choose one yourself. Pass
35
+ `-s <serial>` to every ADB command and use the same serial as the IWSDK
36
+ `headsetId`.
37
+ - Support Quest Browser only. Do not broaden the browser user-agent check.
38
+ - Keep the command bridge on loopback. Use `adb reverse`; never expose or
39
+ forward the bridge over a LAN.
40
+ - Native control replaces the headset's native controller input sources with
41
+ synthetic controllers for the duration of the test. Physical controller and
42
+ hand-action playback are unavailable while the override is installed.
43
+ - `xr set-transform` applies absolute test poses, not offsets from live
44
+ tracking.
45
+ - A first run may show an immersive-WebXR permission prompt in the headset.
46
+ Ask the user to approve it physically, then relaunch. Do not automate that
47
+ permission dialog.
48
+ - Always remove the ADB reverse and stop the dev session during cleanup,
49
+ including after a failed test.
50
+
51
+ ## Target the headset explicitly
52
+
53
+ A command without `runtimeTarget` always routes to the managed host browser,
54
+ never to a headset, even when a paired headset page is the only connected page.
55
+ This workflow starts with `--no-open`, so such a command fails with
56
+ `browser_not_launched`. Do not restart with `--open` to fix a headset command;
57
+ the managed browser never forwards commands to the Quest.
58
+
59
+ - Discover connected targets with `npx @iwsdk/cli runtime targets --raw`. Each
60
+ entry in `targets` carries a nested `runtimeTarget` object and the `methods`
61
+ that page supports.
62
+ - A headset page qualifies only when its entry has `deviceClass: "physical"`,
63
+ `role: "app"`, `commandReady: true`, and a `headsetId` equal to the explicit
64
+ serial.
65
+ - Copy the qualifying entry's complete `runtimeTarget` unchanged: `deviceClass`,
66
+ `headsetId`, `pageId`, `tabGeneration`, and any returned `sessionId` or
67
+ `browserEpoch`. Never rebuild it from separate fields, drop or edit a field,
68
+ or pass the surrounding entry instead.
69
+ - Put it under the top-level `runtimeTarget` key of every headset command's
70
+ `--input-json`, next to that command's own parameters. It is unrelated to the
71
+ position-vector `target` parameter of commands such as `xr look-at`.
72
+ - Never select a headset page with `expectedTab` alone. It carries no
73
+ `deviceClass` or `headsetId`, so the command stays on the managed browser.
74
+ - Never guess between candidates. If these rules do not identify exactly one
75
+ page, or a command returns `ambiguous_target`, ask the user to close the extra
76
+ app tabs in the headset, then rediscover. Do not fall back to list order, the
77
+ newest entry, another headset, or an untargeted command.
78
+ - A reload or relaunch advances the page generation. After one, or after a
79
+ `stale_browser_tab` or `target_unavailable` error, run `runtime targets` again
80
+ and reselect with these rules. An old `runtimeTarget` stays fenced to its
81
+ generation.
82
+ - `outcome_unknown` means the command may have executed. Never replay it.
83
+ Rediscover the target, inspect state with read-only commands such as
84
+ `xr status`, `ecs query`, or `scene transform`, and only then decide whether a
85
+ new command is needed.
86
+ - Headset pages accept runtime commands only. Host-only browser tools, such as
87
+ screenshots, snapshots, interaction, profiling, and console capture, return
88
+ `unsupported_on_target`; check the entry's `methods` first.
89
+
90
+ To test several headsets in one dev session, set up each serial separately: one
91
+ `adb -s <serial> reverse` route and one `runtime pair-headset` call per device,
92
+ discovery by each device's own `headsetId`, and one recorded `runtimeTarget` per
93
+ headset. Send each command with the `runtimeTarget` of the headset it is meant
94
+ for; never reuse one headset's `runtimeTarget` for another.
95
+
96
+ ## 1. Verify the app and device
97
+
98
+ Run `npm run --if-present typecheck` and fix type errors before device testing.
99
+
100
+ Run `adb devices` and settle the explicit serial as described above. Continue
101
+ only when that serial is in the `device` state. A `pending`, `offline`, or
102
+ `unauthorized` device is not ready.
103
+
104
+ This workflow expects a manifest-first app that imports
105
+ `virtual:iwsdk-project` and passes it to `World.create()`. For a hand-built
106
+ `WorldOptions` object, opt in explicitly with:
107
+
108
+ ```ts
109
+ xr: {
110
+ // existing XR options
111
+ launchOnSessionGranted: true,
112
+ }
113
+ ```
114
+
115
+ ## 2. Start the native-control dev session
116
+
117
+ From the application root, run:
118
+
119
+ ```bash
120
+ npx @iwsdk/cli dev up --native-xr-control --no-open
121
+ ```
122
+
123
+ Inspect `npx @iwsdk/cli dev status` and record the numeric port from the
124
+ active runtime. Native-control sessions default to HTTP when the application
125
+ does not explicitly configure Vite HTTPS. The app is loaded from
126
+ headset-localhost through ADB reverse, so the default remains a trustworthy
127
+ WebXR origin. `--no-open` leaves the managed host browser unlaunched, so only
128
+ commands that carry the headset's `runtimeTarget` can run.
129
+
130
+ ## 3. Install the ADB route and pair the headset
131
+
132
+ Replace `<serial>` and `<port>` with the values verified above:
133
+
134
+ ```bash
135
+ adb -s <serial> reverse tcp:<port> tcp:<port>
136
+ npx @iwsdk/cli runtime pair-headset --input-json '{"headsetId":"<serial>"}' --raw
137
+ ```
138
+
139
+ Record the returned `url`. It carries this headset's pairing token for the
140
+ current dev session; an unpaired headset page is refused and never becomes a
141
+ target. Continue only if the URL points at `localhost` or `127.0.0.1` on
142
+ `<port>`. Pair again after any dev-session restart.
143
+
144
+ ## 4. Enter the real immersive session
145
+
146
+ Before each launch, run `npx @iwsdk/cli runtime targets --raw` and record the
147
+ `pageId` and `tabGeneration` of every physical target whose `headsetId` is
148
+ `<serial>`.
149
+
150
+ URL-encode the returned pairing URL without changing its host or dropping its
151
+ query, then launch:
152
+
153
+ ```bash
154
+ adb -s <serial> shell am broadcast \
155
+ -n com.oculus.vrshell/.ShellControlBroadcastReceiver \
156
+ -a com.oculus.vrshell.intent.action.LAUNCH \
157
+ -d apk://com.oculus.browser \
158
+ -e uri "ovrweb://vr?uri=<encoded-pairing-url>"
159
+ ```
160
+
161
+ Keep the nested URL encoded so `?`, `&`, and fragment characters cannot be
162
+ interpreted as parameters of the outer deep link.
163
+
164
+ Poll `npx @iwsdk/cli runtime targets --raw`. Select the qualifying target that
165
+ this launch created: its `pageId` was not recorded, or its `tabGeneration` is
166
+ higher than recorded. If exactly one target matches, record its complete
167
+ `runtimeTarget`. A physical target has this shape:
168
+
169
+ ```json
170
+ {
171
+ "deviceClass": "physical",
172
+ "headsetId": "<serial>",
173
+ "pageId": "<pageId>",
174
+ "tabGeneration": 1,
175
+ "sessionId": "<sessionId>"
176
+ }
177
+ ```
178
+
179
+ If no target appears, check in the headset that the page loaded from the
180
+ pairing URL and did not redirect to a network hostname. If more than one
181
+ matches, ask the user to close the extra tabs and relaunch.
182
+
183
+ Replace `<runtimeTarget>` below with the recorded object, verbatim:
184
+
185
+ ```bash
186
+ npx @iwsdk/cli xr status --input-json '{"runtimeTarget":<runtimeTarget>}' --raw
187
+ ```
188
+
189
+ XR status must show an active `immersive-vr` or `immersive-ar` session. Its
190
+ `browserConnected` and `browserCommandReady` fields describe the managed host
191
+ browser, not the headset. If the session stays inactive, ask the user to accept
192
+ the one-time browser permission in the headset, then repeat this step from the
193
+ pre-launch record.
194
+
195
+ Do not use `iwsdk xr enter` for this step: that command accepts an emulated
196
+ offer, while this workflow must preserve the browser's native session.
197
+
198
+ ## 5. Run the scenario
199
+
200
+ Discover the available command shapes before improvising:
201
+
202
+ ```bash
203
+ npx @iwsdk/cli xr --help
204
+ npx @iwsdk/cli ecs --help
205
+ npx @iwsdk/cli scene --help
206
+ ```
207
+
208
+ Add the recorded `runtimeTarget` to each command's `--input-json`, next to the
209
+ command's own parameters. Here `target` is the world position to aim at:
210
+
211
+ ```bash
212
+ npx @iwsdk/cli xr look-at --input-json \
213
+ '{"device":"controller-right","target":{"x":0,"y":1.2,"z":-1},"runtimeTarget":<runtimeTarget>}' --raw
214
+ ```
215
+
216
+ The exact `runtimeTarget` both selects the intended headset page and rejects
217
+ stale commands after a page reload.
218
+
219
+ Use the same commands as desktop automation. Typical controls are:
220
+
221
+ - `xr set-transform` for headset or controller position/orientation.
222
+ - `xr look-at` to aim a controller ray at a world position.
223
+ - `xr set-select-value` or `xr select` for trigger/pinch interaction.
224
+ - `xr set-gamepad-state` for squeeze and controller buttons.
225
+ - `ecs query`, `ecs snapshot`, and `ecs diff` for authoritative state.
226
+ - `scene runtime-hierarchy` and `scene transform` to locate and measure
227
+ rendered objects.
228
+
229
+ Prove behavior with state, not only screenshots. For an interaction test,
230
+ record the target transform or component state before the action, perform the
231
+ pose/input sequence, and show the corresponding state change afterward.
232
+
233
+ ## 6. Exit and clean up
234
+
235
+ Run these cleanup actions individually even if an earlier assertion failed:
236
+
237
+ ```bash
238
+ npx @iwsdk/cli xr exit --input-json '{"runtimeTarget":<runtimeTarget>}' --raw
239
+ adb -s <serial> reverse --remove tcp:<port>
240
+ npx @iwsdk/cli dev down
241
+ ```
242
+
243
+ Use the most recently discovered `runtimeTarget` for `xr exit`. If it returns
244
+ `stale_browser_tab` or `target_unavailable`, rediscover and exit with the fresh
245
+ object; if it returns `outcome_unknown`, check `xr status` instead of repeating
246
+ the exit. Remove the reverse route from every device you configured.
247
+
248
+ Report:
249
+
250
+ - device serial (`headsetId`) and app URL used;
251
+ - the exact `runtimeTarget` of the final command;
252
+ - native session mode and enabled features;
253
+ - the selected target's command-ready state;
254
+ - pose/input actions performed;
255
+ - before/after evidence for the requested behavior;
256
+ - console errors or capability notes;
257
+ - confirmation that the reverse route and dev session were removed.
258
+
259
+ If the user wants to try the app in the headset afterwards, start a plain
260
+ session (`npx @iwsdk/cli dev up` with the session's `--ai-mode`, without
261
+ `--native-xr-control`) and give them the plain URL from `dev status`.
262
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=931a8822463f2bb6652cbbf2b7571db92e5331af44b598890057319b0177939b name=iwsdk-native-xr-test (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -0,0 +1,106 @@
1
+ ---
2
+ name: iwsdk-physics
3
+ description: Add or repair IWSDK rigid-body simulation, collision shapes, forces, and physics-aware grabbing. Use for gravity, falling, collision, bouncing, kinematic motion, or physics tuning.
4
+ argument-hint: '(use the current request)'
5
+ ---
6
+
7
+ # IWSDK Physics
8
+
9
+ Use the current request as the specification. Prefer the scaffold's project
10
+ manifest and native scene components over rebuilding physics in TypeScript.
11
+
12
+ ## Implement the smallest complete physics path
13
+
14
+ 1. Inspect `iwsdk.config.json`, the active scene, and only the source file that
15
+ owns any requested custom behavior.
16
+ Make the complete first config/asset/scene edit before starting the dev
17
+ server. The contracts below are sufficient for the common path: do not call
18
+ `scene capabilities`, CLI `--help`, search `node_modules`, or inspect
19
+ generated declarations unless a concrete build/runtime error remains after
20
+ that edit.
21
+ 2. Set `world.features.physics` to `true`. The scaffold registers
22
+ `PhysicsSystem`, `PhysicsBody`, `PhysicsShape`, and `PhysicsManipulation`; do
23
+ not register them again unless the project deliberately replaced bootstrap.
24
+ 3. Every colliding entity needs both `PhysicsBody` and `PhysicsShape`:
25
+
26
+ - moving under simulation: `PhysicsBody.state: "DYNAMIC"`;
27
+ - fixed floor or wall: `PhysicsBody.state: "STATIC"`;
28
+ - code-driven moving platform: `PhysicsBody.state: "KINEMATIC"`.
29
+
30
+ 4. Match shapes to visible geometry. Use `Sphere`, `Box`, or `Cylinder` with
31
+ explicit dimensions for primitives. Use `ConvexHull` for a dynamic complex
32
+ mesh and reserve `TriMesh` for static geometry.
33
+ 5. Add only requested material tuning. Start with low restitution and moderate
34
+ friction; avoid compensating for a missing collider with extreme damping.
35
+ 6. For a throwable object, combine a dynamic body and shape with the requested
36
+ grab component. `OneHandGrabbable` is proximity squeeze; a distance grab
37
+ also requires `RayInteractable` and `DistanceGrabbable`.
38
+ 7. Apply a one-shot force or velocity through `PhysicsManipulation`. For a
39
+ reset/teleport of an existing body, use `PhysicsSystem.setBodyTransform` so
40
+ Havok and the render transform remain synchronized.
41
+
42
+ For simple primitive assets, import `Mesh`, `SphereGeometry`, `BoxGeometry`,
43
+ and `MeshStandardMaterial` from `@iwsdk/core`, construct parentless meshes, and
44
+ add those mesh values directly to the existing `defineAssets({...})` map. Keep
45
+ the render geometry and collider dimensions identical: a sphere of radius `r`
46
+ uses `PhysicsShape: { shape: "Sphere", dimensions: [r, 0, 0] }`; a box sized
47
+ `[w, h, d]` uses `{ shape: "Box", dimensions: [w, h, d] }`.
48
+
49
+ Read one bundled reference only when needed; do not read the complete set:
50
+
51
+ - exact component fields and dimensions: `references/component-reference.md`;
52
+ - implementation patterns: `references/workflows.md`;
53
+ - material or system tuning: `references/tuning-and-config.md`.
54
+
55
+ ## Verify behavior, not just source
56
+
57
+ Run the production build once. Start the app once and inspect the named live
58
+ entities. For falling, collision, force, or kinematic behavior, pause before the
59
+ interesting transition, take a `before` snapshot, step a small fixed number of
60
+ frames, take an `after` snapshot, and diff them. Query the final transform and
61
+ physics state. Capture one final runtime image when spatial layout matters.
62
+
63
+ Use the documented CLI shape directly; do not call help to rediscover it:
64
+
65
+ ```bash
66
+ npx @iwsdk/cli ecs pause --input-json '{}'
67
+ npx @iwsdk/cli ecs snapshot --input-json '{"label":"before"}'
68
+ npx @iwsdk/cli ecs step --input-json '{"count":8,"delta":0.016}'
69
+ npx @iwsdk/cli ecs snapshot --input-json '{"label":"after"}'
70
+ npx @iwsdk/cli ecs diff --input-json '{"from":"before","to":"after"}'
71
+ npx @iwsdk/cli ecs resume --input-json '{}'
72
+ ```
73
+
74
+ If a gravity body has already settled by the time the bridge is ready, its
75
+ resting transform plus a zero-motion stepped diff is valid collision evidence.
76
+ Do not teleport the body solely to recreate the fall.
77
+
78
+ Use an options object when you need to select the execution mode or simulation rate. Worker execution is the default; `useWorker: false` runs the same physics runtime and protocol on the main thread for compatibility and diagnostics.
79
+
80
+ ```jsonc
81
+ "physics": {
82
+ "useWorker": true,
83
+ "updateFrequency": 60,
84
+ "interpolation": true
85
+ }
86
+ ```
87
+
88
+ **Only enable physics when needed.** If no objects require dynamic simulation, omit it to avoid overhead.
89
+
90
+ For a newly composed test fixture, run `scene render-file` on the authored hero
91
+ view once and inspect at most that one image. After a valid, readable hero,
92
+ do not call `scene open`, `scene state`, or `scene screenshot`, and do not create
93
+ alternate editor views. Save the final live browser screenshot to a file but do
94
+ not read it back when the ECS measurements already prove the requested motion.
95
+
96
+ Pure rigid-body verification does not require entering XR. The authored `hero`
97
+ view is composition evidence, while the live browser camera can differ. Do not
98
+ temporarily edit `iwsdk.config.json`, restart the runtime, or render extra camera
99
+ angles solely to make a screenshot match the hero view. Save the live capture
100
+ directly with `npx @iwsdk/cli browser screenshot --output-file <path>` and let the
101
+ authored render cover deliberate framing.
102
+
103
+ Make at most one focused correction, then replay the same observation. Stop
104
+ when the requested bodies, collisions, and final state are evidenced. Resume
105
+ ECS time and leave the app in a stable state.
106
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=5d66b2f83041f75889735be1e18747b078f2df32025ba1039cb77efbea3c2cb3 name=iwsdk-physics (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->