@iwsdk/create 1.1.0-rc.2 → 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 (102) hide show
  1. package/README.md +52 -15
  2. package/dist/cli.js +7538 -3405
  3. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-build-model/SKILL.md +1 -0
  4. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-compose-scene/SKILL.md +3 -2
  5. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-debug/SKILL.md +1 -0
  6. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-depth-occlusion/SKILL.md +1 -0
  7. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-dev/SKILL.md +1 -0
  8. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-dev/references/api-reference.md +6 -0
  9. package/dist/guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +82 -0
  10. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-dev/references/iterate.md +10 -5
  11. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-dev/references/planner.md +9 -5
  12. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-glasses-test/SKILL.md +1 -0
  13. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-grab/SKILL.md +1 -0
  14. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-hosting/SKILL.md +1 -0
  15. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-native-xr-test/SKILL.md +17 -1
  16. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-physics/SKILL.md +1 -0
  17. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-pwa-packaging/SKILL.md +1 -0
  18. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-ray/SKILL.md +1 -0
  19. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-ui/SKILL.md +6 -3
  20. package/dist/guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
  21. package/dist/guidance/{claude → files}/.claude/agents/iwsdk-project-code-reviewer.md +1 -0
  22. package/dist/guidance/{claude → files}/.claude/rules/assets-and-manifest.md +3 -0
  23. package/dist/guidance/{claude → files}/.claude/rules/ecs-api.md +1 -0
  24. package/dist/guidance/{claude → files}/.claude/rules/scene-json.md +1 -0
  25. package/dist/guidance/{claude → files}/.claude/rules/uikitml.md +1 -0
  26. package/dist/guidance/{claude → files}/.claude/settings.json +8 -3
  27. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-build-model/SKILL.md +1 -0
  28. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-compose-scene/SKILL.md +3 -2
  29. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-debug/SKILL.md +1 -0
  30. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-depth-occlusion/SKILL.md +1 -0
  31. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-dev/SKILL.md +1 -0
  32. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-dev/references/api-reference.md +6 -0
  33. package/dist/guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +82 -0
  34. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-dev/references/iterate.md +10 -5
  35. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-dev/references/planner.md +9 -5
  36. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-glasses-test/SKILL.md +1 -0
  37. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-grab/SKILL.md +1 -0
  38. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-hosting/SKILL.md +1 -0
  39. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-native-xr-test/SKILL.md +17 -1
  40. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-physics/SKILL.md +1 -0
  41. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-pwa-packaging/SKILL.md +1 -0
  42. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-ray/SKILL.md +1 -0
  43. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-ui/SKILL.md +6 -3
  44. package/dist/guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
  45. package/dist/guidance/{cursor → files}/.cursor/rules/assets-and-manifest.mdc +3 -0
  46. package/dist/guidance/{cursor → files}/.cursor/rules/ecs-api.mdc +1 -0
  47. package/dist/guidance/{cursor → files}/.cursor/rules/scene-json.mdc +1 -0
  48. package/dist/guidance/{cursor → files}/.cursor/rules/uikitml.mdc +1 -0
  49. package/dist/guidance/{copilot → files}/.github/instructions/assets-and-manifest.instructions.md +2 -1
  50. package/dist/guidance/{copilot → files}/.github/instructions/ecs-api.instructions.md +1 -0
  51. package/dist/guidance/{copilot → files}/.github/instructions/scene-json.instructions.md +1 -0
  52. package/dist/guidance/{copilot → files}/.github/instructions/uikitml.instructions.md +1 -0
  53. package/dist/guidance/{common → files}/AGENTS.md +107 -27
  54. package/dist/guidance/{scoped-agents → files}/public/scenes/AGENTS.md +2 -0
  55. package/dist/guidance/{scoped-agents → files}/public/ui/AGENTS.md +2 -0
  56. package/dist/guidance/{scoped-agents → files}/src/AGENTS.md +2 -0
  57. package/dist/guidance/manifest.json +854 -0
  58. package/dist/template/common/.codex/config.toml +2 -0
  59. package/package.json +5 -5
  60. package/scripts/verify-release-ready.mjs +1 -2
  61. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-build-model/agents/openai.yaml +0 -0
  62. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +0 -0
  63. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +0 -0
  64. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +0 -0
  65. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +0 -0
  66. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/image-intake.md +0 -0
  67. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +0 -0
  68. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/scene-format.md +0 -0
  69. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/scene-review.md +0 -0
  70. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/text-intake.md +0 -0
  71. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-hosting/references/existing-hosts.md +0 -0
  72. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-hosting/references/vercel.md +0 -0
  73. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-physics/references/component-reference.md +0 -0
  74. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-physics/references/tuning-and-config.md +0 -0
  75. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-physics/references/workflows.md +0 -0
  76. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +0 -0
  77. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +0 -0
  78. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +0 -0
  79. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +0 -0
  80. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +0 -0
  81. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-build-model/agents/openai.yaml +0 -0
  82. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +0 -0
  83. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +0 -0
  84. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +0 -0
  85. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +0 -0
  86. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/image-intake.md +0 -0
  87. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +0 -0
  88. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/scene-format.md +0 -0
  89. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/scene-review.md +0 -0
  90. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/text-intake.md +0 -0
  91. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-hosting/references/existing-hosts.md +0 -0
  92. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-hosting/references/vercel.md +0 -0
  93. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-physics/references/component-reference.md +0 -0
  94. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-physics/references/tuning-and-config.md +0 -0
  95. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-physics/references/workflows.md +0 -0
  96. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +0 -0
  97. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +0 -0
  98. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +0 -0
  99. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +0 -0
  100. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +0 -0
  101. /package/dist/guidance/{claude → files}/CLAUDE.md +0 -0
  102. /package/dist/{guidance/codex → template/common-js}/.codex/config.toml +0 -0
@@ -184,7 +184,9 @@ the same question.
184
184
  Build the smallest structure that covers the whole contract:
185
185
 
186
186
  1. native scene assets and deliberate hero/panel framing;
187
- 2. component schemas and explicit authored values;
187
+ 2. component schemas and explicit authored values, including game state such
188
+ as score, lives, phase and timers, so verification can jump to any state
189
+ with `ecs set-component` instead of playing there or scripting the page;
188
190
  3. interaction/state systems;
189
191
  4. UIKitML and runtime control wiring;
190
192
  5. visible state feedback.
@@ -205,13 +207,15 @@ physics, deployment, and interactions with meaningful failure modes need
205
207
  broader scenarios and stronger evidence.
206
208
 
207
209
  After the coherent vertical slice typechecks, start one managed dev session
208
- and keep it alive while iterating. The developer owns headed versus headless
209
- mode: announce a proposed mode change before restarting rather than silently
210
- replacing their visible collaboration window. Do not start an untouched or
210
+ and keep it alive while iterating. Pick headed or headless with the session
211
+ rule in AGENTS.md (headless unless the user wants to watch) and announce a later
212
+ mode change before restarting rather than silently replacing a visible window. Do not start an untouched or
211
213
  knowingly non-typechecking app. Exercise the real paths rather than inferring
212
214
  behavior from code. Confirm `npx @iwsdk/cli xr status` is active before making pose,
213
215
  controller/hand alignment, or immersive-interaction claims; a flat screenshot
214
- outside XR cannot prove them.
216
+ outside XR cannot prove them. Headless sessions draw only when a tool needs
217
+ pixels; read references/headless-rendering.md before relying on frame rate,
218
+ frame timing, or which frame a screenshot shows.
215
219
 
216
220
  Verify:
217
221
 
@@ -279,3 +279,4 @@ synthetic `fov: 90`. Keep using step 3 for framing.
279
279
  - `[iwsdk][gaze]` console lines and other errors;
280
280
  - for a headset run, its serial, which Quest mode was used, and whether the
281
281
  page was paired.
282
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=86e1e324dd71e8dd832b5d446e6bdc03bb5150cf5128c0650838cf6227b79817 name=iwsdk-glasses-test (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -72,3 +72,4 @@ to model context does not satisfy a requested file deliverable.
72
72
 
73
73
  Stop once the requested grab/move/release path and final state are proven. Leave
74
74
  the controller released and the XR session in the state the user requested.
75
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=ad099acb82205620cb9cce44f245f40baf7e6808038d7d94ff9d873f316473d2 name=iwsdk-grab (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -175,3 +175,4 @@ trip:
175
175
 
176
176
  Packaging the hosted app into a signed Quest APK is the `iwsdk-pwa-packaging`
177
177
  skill; this skill only gets it online.
178
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=9e866989c506da5cf54ba96bb02c52d1b901e162ab8f32ad9f97ed84aa4dcc8b name=iwsdk-hosting (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -1,6 +1,6 @@
1
1
  ---
2
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.
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
4
  argument-hint: '[test scenario]'
5
5
  ---
6
6
 
@@ -14,6 +14,17 @@ override poses and input for the test.
14
14
 
15
15
  The requested scenario is in `$ARGUMENTS`.
16
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
+
17
28
  ## Safety and scope
18
29
 
19
30
  - Use only public Android platform tools and IWSDK commands. Do not depend on a
@@ -244,3 +255,8 @@ Report:
244
255
  - before/after evidence for the requested behavior;
245
256
  - console errors or capability notes;
246
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) -->
@@ -103,3 +103,4 @@ authored render cover deliberate framing.
103
103
  Make at most one focused correction, then replay the same observation. Stop
104
104
  when the requested bodies, collisions, and final state are evidenced. Resume
105
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) -->
@@ -216,3 +216,4 @@ updated — only replaced by a new Store entry.
216
216
  Getting the app online is the `iwsdk-hosting` skill. Building the app itself is
217
217
  `iwsdk-planner` and the other `iwsdk-*` skills — do not re-derive IWSDK
218
218
  patterns here.
219
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=e4e859d1977962769195f6bfb52dc9b02f159dd743e2609ea8b6111dd847e7eb name=iwsdk-pwa-packaging (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -67,3 +67,4 @@ When the request names an artifact path, save it directly with
67
67
  context and then add a copy step.
68
68
  Stop when the real input and resulting named state are proven, leaving all
69
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) -->
@@ -186,8 +186,8 @@ views independently when both modes matter.
186
186
  ## Verify with a bounded loop
187
187
 
188
188
  Typecheck after the complete first slice, then start or reuse one managed
189
- session. If no command-ready session exists, run `npx @iwsdk/cli dev up --open`
190
- once. Do not call `dev --help`, separately call `dev open`, restart a healthy
189
+ session. If no command-ready session exists, run `npx @iwsdk/cli dev up` once,
190
+ with the `--ai-mode` that AGENTS.md's session rule picks. Do not call `dev --help`, separately call `dev open`, restart a healthy
191
191
  session, start a second browser, or build a custom UIKit renderer.
192
192
 
193
193
  1. Run `npx @iwsdk/cli ui assets --raw` once to confirm registration.
@@ -256,7 +256,9 @@ it.
256
256
 
257
257
  When the request asks for a poke (near touch) on a control, press it with the
258
258
  emulated hand's index fingertip by its element ID. The panel entity needs
259
- `PokeInteractable`:
259
+ `PokeInteractable`. Its `hand` field (`"both"`, the default, `"left"` or
260
+ `"right"`) limits which hand can poke it, for example a wrist menu that only
261
+ the other hand should press:
260
262
 
261
263
  ```bash
262
264
  npx @iwsdk/cli xr set-input-mode --input-json '{"mode":"hand"}'
@@ -323,3 +325,4 @@ The final visual check must confirm:
323
325
  Finish with a passing typecheck and production build, no UIKit parser/resource
324
326
  errors, and concise runtime evidence. Remove temporary preview files or camera
325
327
  workarounds that are not deliverables.
328
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=f38cb22c3f17e583db46ecffe8ac78d5d58a1b990ebd485e00f1f5623b690332 name=iwsdk-ui (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -0,0 +1,74 @@
1
+ ---
2
+ name: iwsdk-upgrade
3
+ description: Upgrade an IWSDK app to a newer IWSDK release and prove it still works. Use when the user asks to upgrade, update or bump IWSDK or any @iwsdk/* package, when iwsdk dev up reports guidance updated from an older release, or when errors appear right after an IWSDK version change.
4
+ argument-hint: '[target version, default latest]'
5
+ ---
6
+
7
+ # Upgrade IWSDK
8
+
9
+ An upgrade has three parts: move the packages, apply what changed between the
10
+ two releases, and show that the app behaves as it did before. Do them in that
11
+ order.
12
+
13
+ ## 1. Record the baseline first
14
+
15
+ Before changing any version, check `git status`, make sure the user's work is
16
+ saved or committed (do not commit unless the user allowed it), and record how
17
+ the app behaves now: run its typecheck and build scripts with the project's
18
+ package manager (for example `npm run typecheck` and `npm run build`).
19
+
20
+ Write down every error, then start the dev server and save the browser log and
21
+ a runtime screenshot. Older apps often have errors that predate the upgrade;
22
+ without a baseline you cannot tell them from new ones, and proving it later
23
+ costs a full reinstall.
24
+
25
+ ## 2. Move the packages
26
+
27
+ ```bash
28
+ npx @iwsdk/cli@latest upgrade --dry-run
29
+ npx @iwsdk/cli@latest upgrade
30
+ ```
31
+
32
+ Always run it with `@latest`, even if the project has an older `@iwsdk/cli`:
33
+ the newest CLI carries every migration guide. For a specific release, add
34
+ `--to <version>` (`npx @iwsdk/cli@<version> upgrade` works only for releases
35
+ that include the `upgrade` command). It sets every `@iwsdk/*` package to the release, installs
36
+ with the project's package manager, aligns the `three` alias and an existing
37
+ `@types/three` with `@iwsdk/core`, refreshes this guidance, and writes to `.iwsdk/migrations/`:
38
+
39
+ - one `iwsdk-migrate-*/SKILL.md` for each release boundary that needs code
40
+ changes;
41
+ - `release-notes.md` with every change between the two versions.
42
+
43
+ It also checks `iwsdk.config.json` against the new release and lists settings
44
+ that no longer validate. Packages it reports as "not part of the IWSDK release"
45
+ were left as declared; remove one only if a migration guide says it was
46
+ retired. In a monorepo it installs with the workspace's package manager; if a
47
+ workspace-level override pins `three`, it tells you to change it.
48
+
49
+ If the user asked for a plain package-manager bump instead, do that, then run
50
+ `npx @iwsdk/cli@latest agents sync`; `iwsdk dev up` also refreshes unedited
51
+ guidance.
52
+
53
+ ## 3. Apply what changed
54
+
55
+ 1. Follow each migration guide in `.iwsdk/migrations/`, oldest first, before
56
+ other work.
57
+ 2. Read the major and minor entries in `release-notes.md` and check whether
58
+ the app uses what they change (renamed settings, new required versions,
59
+ changed defaults).
60
+ 3. Fix each `iwsdk.config.json` issue the upgrade listed.
61
+ 4. Re-read the `iwsdk-agent-guidance` block in `AGENTS.md`: it now describes
62
+ the new release. Do not hand-edit guidance files; an edited file stops
63
+ receiving updates.
64
+
65
+ ## 4. Prove it
66
+
67
+ Run the same checks as the baseline and compare. Report new errors and fix
68
+ them; report baseline errors separately as existing. A clean typecheck and
69
+ build do not show that the app renders: confirm the runtime screenshot and an
70
+ error-free browser log, and enter XR when the app is an XR app.
71
+
72
+ The upgrade is done when every migration guide is applied, the comparison
73
+ shows no new errors, and the user knows which existing errors remain.
74
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=5ccb37dbe152b3611496740e89bc8e42c8d59dfed8be7512635d877924b79988 name=iwsdk-upgrade (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -3,6 +3,8 @@ description: "Asset manifest contract"
3
3
  globs:
4
4
  - "src/assets.ts"
5
5
  - "src/assets.js"
6
+ - "src/iwsdk/assets.ts"
7
+ - "src/iwsdk/assets.js"
6
8
  - "src/scene-assets/**"
7
9
  alwaysApply: false
8
10
  ---
@@ -57,3 +59,4 @@ mesh lowers to one `InstancedMesh`.
57
59
  Start assets at `castShadow: false` and opt in only for grounded focal masses.
58
60
  Don't build contact-shadow blob cards or `ShadowMaterial` catcher planes here: put
59
61
  `ContactShadow` or `ShadowCatcher` node components on the scene nodes instead.
62
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=e6b8d299d9f7590043801fae63d23de387e937bcb87bafe59b9b70f6e0622db3 name=assets-and-manifest.mdc (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -102,3 +102,4 @@ buttons. Browser controls live at `world.input.keyboard` and
102
102
  `world.visibilityState` reports `NonImmersive`, `Visible`, `VisibleBlurred` —
103
103
  pause simulation on blur. `world.camera.position` is local to `world.player`; use
104
104
  `getWorldPosition()` when logic needs the true viewer position.
105
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=f09a86b27ce781f8e69b6471051167bee392ac2f503526df33ded757940268f6 name=ecs-api.mdc (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -71,3 +71,4 @@ back. Render each changed module before the root.
71
71
 
72
72
  For composing a scene rather than editing one, use the `iwsdk-compose-scene`
73
73
  skill — it owns the intake, review and stop-rule procedure this file does not.
74
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=f32c3e7d4024f56a3ff5ae32b42c236377551cbd3b2b231e84ada68362b68266 name=scene-json.mdc (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -65,3 +65,4 @@ can.
65
65
  For the authoring procedure — isolated preview, placement, editing, wiring
66
66
  runtime behavior, and the completion checklist — use the `iwsdk-ui` skill rather
67
67
  than improvising. This file is the format reference it relies on.
68
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=ce002bd4759a1d087c3e18fd3e2a9a009eb3bef5561d0a698f86726a1bd7f9c3 name=uikitml.mdc (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -1,5 +1,5 @@
1
1
  ---
2
- applyTo: "src/assets.ts,src/assets.js,src/scene-assets/**"
2
+ applyTo: "src/assets.ts,src/assets.js,src/iwsdk/assets.ts,src/iwsdk/assets.js,src/scene-assets/**"
3
3
  ---
4
4
 
5
5
  # Asset manifest contract
@@ -52,3 +52,4 @@ mesh lowers to one `InstancedMesh`.
52
52
  Start assets at `castShadow: false` and opt in only for grounded focal masses.
53
53
  Don't build contact-shadow blob cards or `ShadowMaterial` catcher planes here: put
54
54
  `ContactShadow` or `ShadowCatcher` node components on the scene nodes instead.
55
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=6949b512ef5bb71b488b7e8544b4e572f46f73f72a941b248a0856228299bfad name=assets-and-manifest.instructions.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -98,3 +98,4 @@ buttons. Browser controls live at `world.input.keyboard` and
98
98
  `world.visibilityState` reports `NonImmersive`, `Visible`, `VisibleBlurred` —
99
99
  pause simulation on blur. `world.camera.position` is local to `world.player`; use
100
100
  `getWorldPosition()` when logic needs the true viewer position.
101
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=724a02986ce0999bc31c02b4f1e4a7b6b83c9966f994979a340e36b6243d26fd name=ecs-api.instructions.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -68,3 +68,4 @@ back. Render each changed module before the root.
68
68
 
69
69
  For composing a scene rather than editing one, use the `iwsdk-compose-scene`
70
70
  skill — it owns the intake, review and stop-rule procedure this file does not.
71
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=c73f635cec34f9e99b2bc59ffe63583842d40e419a499225a56cbb7838d9bccd name=scene-json.instructions.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -62,3 +62,4 @@ can.
62
62
  For the authoring procedure — isolated preview, placement, editing, wiring
63
63
  runtime behavior, and the completion checklist — use the `iwsdk-ui` skill rather
64
64
  than improvising. This file is the format reference it relies on.
65
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=f06c88f681a856a0b8b93b5552257dd316f189082dfc0a6bca87e2e642ecbb3e name=uikitml.instructions.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -1,5 +1,14 @@
1
+ <!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.0 sha256=bb25ffd600c99d3f30cdc95518bb89161659907c667de45adcb29315b669bc7f -->
1
2
  # IWSDK project
2
3
 
4
+ IWSDK changes faster than model training data. GLXF scenes, the external 0.4
5
+ scene editor and its Vite plugin, and the UIKitML-compile and glTF-optimizer Vite
6
+ plugins were removed in 0.5: scenes are native `*.iwsdk.scene.json` files edited
7
+ in IWSDK's built-in editor, and `@iwsdk/vite-plugin-dev` is the only IWSDK Vite
8
+ plugin. Trust this file and the project skills over what you remember about
9
+ IWSDK. To upgrade IWSDK, run `npx @iwsdk/cli@latest upgrade` and follow the
10
+ migration guides it writes to `.iwsdk/migrations/`.
11
+
3
12
  A Vite + TypeScript or JavaScript app, but several things do **not** work the way
4
13
  a normal Vite project works. Read this section before assuming anything.
5
14
 
@@ -16,6 +25,12 @@ applicable IWSDK guide or concept page.
16
25
 
17
26
  ## What is not standard Vite
18
27
 
28
+ **No `iwsdk.config.json` in this project?** IWSDK was added by hand. Run
29
+ `npx @iwsdk/create@latest . --yes --target vr` (`ar` for mixed reality,
30
+ `browser` for desktop 3D) to add the project manifest, an empty scene, and a
31
+ `virtual:iwsdk-project` entry in `src/iwsdk/` without overwriting any file; the
32
+ rest of this file assumes them.
33
+
19
34
  **`iwsdk.config.json` is the project authority, not `vite.config.ts`.** It selects
20
35
  the active scene, the asset module, the component module, and all XR/world
21
36
  features. `vite.config.ts` only wires the plugin. Editing `iwsdk.config.json`
@@ -44,12 +59,29 @@ tabGeneration on every physical command. Reload is supported through the page
44
59
  bridge; screenshot, snapshot, interaction, profiling, console capture, and the
45
60
  managed editor are host-only. Rediscover after reload to get the new generation.
46
61
 
47
- The developer owns whether that managed window is headed or headless. Do not
48
- change modes silently: announce the change before restarting. In a visible
49
- collaboration session, use the Runtime/Editor toggle in the single managed
50
- Chromium window. Its expected unsupported-flag banner comes from
51
- `--ignore-certificate-errors` for the local development certificate. Playwright
52
- may add separate sandbox-related flags in constrained environments.
62
+ **Choose the session mode before the first `dev up`, and pass it explicitly**
63
+ (the CLI default is headed):
64
+
65
+ - `--ai-mode collaborate` (headed, draws every frame, Runtime/Editor toggle)
66
+ when the user wants to watch or steer the work as it happens: they ask to see
67
+ it, are pairing live, or will judge visuals or motion by eye.
68
+ - `--ai-mode agent` (headless, draws only when a tool needs pixels, fast without
69
+ a GPU) for everything else: autonomous or background work, CI, a remote host
70
+ or no display.
71
+
72
+ If the request does not say and the user is there, ask once whether they want to
73
+ watch in a browser window or let you work headless; if nobody can answer, use
74
+ agent. That one question is allowed even where a playbook avoids pausing; put it
75
+ in your first reply, and start agent mode if no answer has come by the time you
76
+ need the session. Reuse a healthy session in whatever mode it runs, and announce
77
+ any mode change before restarting. Headless screenshots always show a fresh
78
+ frame, but frame rate there means nothing; the iwsdk-dev skill's
79
+ `references/headless-rendering.md` covers exact frames, filmstrips and
80
+ `RuntimeSettings`. In a visible collaboration session, use the Runtime/Editor
81
+ toggle in the single managed Chromium window. Its expected unsupported-flag
82
+ banner comes from `--ignore-certificate-errors` for the local development
83
+ certificate. Playwright may add separate sandbox-related flags in constrained
84
+ environments.
53
85
 
54
86
  **`src/assets.ts`/`src/assets.js` is evaluated twice, in two different JS
55
87
  realms** — once by the app runtime, once by the editor. It must be deterministic
@@ -70,18 +102,17 @@ and subtle breakage. Exception: `import type { GLTF } from 'three/addons/...'`.
70
102
 
71
103
  ## Traps that produce silent failures
72
104
 
73
- | Trap | Symptom | Fix |
74
- | -------------------------------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
75
- | `locomotion: true` with no `LocomotionEnvironment` on a floor | player falls through the world | add the component to a walkable surface |
76
- | Scene origin left occupied | player spawns inside your geometry | the player origin is `0,0,0` unless the scene authors `player.transform` |
77
- | Scene JSON with `imports` | authoring preview works, but editable open and runtime load are rejected | run `npx @iwsdk/cli scene flatten` once, then edit the flat output |
78
- | `entity.destroy()` | GPU memory leaked | use `entity.dispose()` |
79
- | `setValue` on a Vec2/Vec3/Vec4/Color field | throws in elics 3.4.x | use `entity.getVectorView(...)` |
80
- | Environment component on a non-root entity | silently ignored | `DomeGradient`/`IBLGradient` go on the level root only |
81
- | `DomeFade` with no `DomeGradient` on the level root | no fade; the floor keeps its hard edge | add a `DomeGradient` (render stats report the DomeFade `inactiveReason`) |
82
- | `DomeTexture`/`IBLTexture` prop changed without `_needsUpdate` | change ignored | set `_needsUpdate` after writing; `DomeGradient`/`IBLGradient` apply edits without it |
83
- | `ScreenSpace` given numbers | clamped with a console warning | it takes CSS strings: `'400px'`, `'25vw'` |
84
- | `@iwsdk/reference` MCP tools in an old or `--no-install` app | queries report warmup required | run `npx @iwsdk/cli reference warmup`; fresh installed scaffolds do this during creation |
105
+ | Trap | Symptom | Fix |
106
+ | -------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
107
+ | `locomotion: true` with no `LocomotionEnvironment` on a floor | player falls through the world | add the component to a walkable surface |
108
+ | Scene origin left occupied | player spawns inside your geometry | the player origin is `0,0,0` unless the scene authors `player.transform` |
109
+ | Scene JSON with `imports` | authoring preview works, but editable open and runtime load are rejected | run `npx @iwsdk/cli scene flatten` once, then edit the flat output |
110
+ | `entity.destroy()` | GPU memory leaked | use `entity.dispose()` |
111
+ | `setValue` on a Vec2/Vec3/Vec4 field | throws in elics 3.4.x | use `entity.getVectorView(...)` (Color fields take `setValue` with hex or `Color`) |
112
+ | Environment component on a non-root entity | silently ignored | `DomeGradient`/`IBLGradient` go on the level root only |
113
+ | `DomeFade` with no `DomeGradient` on the level root | no fade; the floor keeps its hard edge | add a `DomeGradient` (render stats report the DomeFade `inactiveReason`) |
114
+ | `DomeTexture`/`IBLTexture` prop changed without `_needsUpdate` | change ignored | set `_needsUpdate` after writing; `DomeGradient`/`IBLGradient` apply edits without it |
115
+ | `ScreenSpace` given numbers | clamped with a console warning | it takes CSS strings: `'400px'`, `'25vw'` |
85
116
 
86
117
  ## Verify before you claim it works
87
118
 
@@ -112,11 +143,21 @@ active XR session (`npx @iwsdk/cli xr status`). A flat runtime screenshot taken
112
143
  outside XR can prove that the app renders, but it cannot prove immersive pose or
113
144
  interaction correctness.
114
145
 
115
- For a physical headset smoke test, run `npx @iwsdk/cli dev status`, open a URL from
116
- `data.runtimeUrls.network` on a headset connected to the same Wi-Fi network,
117
- and accept the expected local certificate warning. To run or automate the app
118
- on a Quest connected over USB, invoke `iwsdk-native-xr-test` instead. See
119
- [Testing Your Experience](https://iwsdk.dev/guides/02-testing-experience.html)
146
+ **When the user wants to try the app in a headset themselves**, give them a
147
+ plain session, never a native-control one. A session started with
148
+ `--native-xr-control` hands the head pose and controllers of every Quest Browser
149
+ page it serves to the CLI, with or without a pairing token in the URL, so the
150
+ user's own movement does nothing. If this session was started with
151
+ `--native-xr-control`, or you cannot tell, first run
152
+ `npx @iwsdk/cli dev restart` with the session's own `--ai-mode` and without that
153
+ flag; say so before restarting. Then run `npx @iwsdk/cli dev status` and give the
154
+ user a plain URL, never a `runtime pair-headset` URL: on the same Wi-Fi network,
155
+ one from `data.runtimeUrls.network` (they accept the expected local certificate
156
+ warning); on a Quest connected over USB, run
157
+ `adb -s <serial> reverse tcp:<port> tcp:<port>` and give
158
+ `data.runtimeUrls.local`. Invoke `iwsdk-native-xr-test` only when you drive the
159
+ headset yourself: automating, scripting, or debugging the app on a USB Quest.
160
+ See [Testing Your Experience](https://iwsdk.dev/guides/02-testing-experience.html)
120
161
  for the complete workflow.
121
162
 
122
163
  **Meta VR Glasses are not a Quest.** Their view is much narrower (37° left and
@@ -175,11 +216,14 @@ The selected playbook routes work to the narrowest owning specialist:
175
216
  - a model-local defect found during composition routes back to `iwsdk-build-model`;
176
217
  a placement or lighting defect stays in `iwsdk-compose-scene`.
177
218
 
178
- UI authoring, physics, depth occlusion, grab and ray interaction testing, ECS
179
- frame-stepping, and debugging have their own project skills. Use them only when
180
- the selected `iwsdk-dev` playbook calls for the matching specialty.
219
+ UI authoring, physics, depth occlusion, grab and ray interaction testing, and
220
+ debugging (including ECS frame-stepping, in `iwsdk-debug`) have their own
221
+ project skills. Use them only when the selected `iwsdk-dev` playbook calls for
222
+ the matching specialty.
223
+ Invoke `iwsdk-upgrade` whenever the user asks to upgrade or bump IWSDK.
181
224
  Two device-testing skills are invoked directly: `iwsdk-native-xr-test` whenever
182
- the user wants to run, automate, or debug the app on a connected Quest, and
225
+ you will drive the app on a connected Quest yourself (automate, script-test, or
226
+ debug it), never when the user wants to put the headset on and try it, and
183
227
  `iwsdk-glasses-test` whenever the user targets Meta VR Glasses or asks for gaze
184
228
  input.
185
229
 
@@ -199,6 +243,10 @@ public/scenes/ *.iwsdk.scene.json — composition only
199
243
  public/ui/ *.uikitml — runtime-loaded panels
200
244
  ```
201
245
 
246
+ An app that added IWSDK to an existing project keeps these modules in
247
+ `src/iwsdk/` instead. `iwsdk.config.json` names the modules either way; the
248
+ `src/...` paths in this guidance mean the modules it names.
249
+
202
250
  No barrel `index.ts` files. Keep component declarations free of system, DOM and
203
251
  renderer imports; systems import the declarations, never the reverse.
204
252
 
@@ -212,12 +260,44 @@ renderer imports; systems import the declarations, never the reverse.
212
260
  - Load assets through `AssetManager` / the manifest, never a raw `GLTFLoader`.
213
261
  - Create entities with `world.createTransformEntity(...)`, never `scene.add()`.
214
262
  - Use the `RayInteractable` component, never a manual `Raycaster`.
263
+ - Give a UI panel or button both `RayInteractable` and `PokeInteractable`.
264
+ Fingertip touches only reach entities with `PokeInteractable`, so a
265
+ ray-only panel ignores hand presses.
215
266
  - VR targets 72–90 fps: 11–14 ms per frame. Treat per-frame allocation as a bug.
267
+ - Keep an Enter XR control on the flat page of every XR app: the starter's
268
+ welcome-panel button, or your own UIKit or DOM button that calls
269
+ `world.launchXR()`. If you remove the welcome panel, replace its button.
270
+ `xr.offer` alone only adds a small "Enter VR" pill to the Quest Browser
271
+ toolbar (labelled VR even for AR), which people miss, so the page looks like
272
+ it has no way into XR.
273
+ - Keep app and game state that a person or agent will want to read or change
274
+ (score, lives, gold, wave, phase, timers, debug switches) in ECS components,
275
+ not module-level objects. `ecs query` and `ecs set-component` then read it and
276
+ jump it to any state from the CLI or MCP, in the emulator and on a paired
277
+ headset, without editing code or scripting the page.
278
+
279
+ **Browser automation is a last resort.** `dev up --allow-browser-automation`
280
+ enables `browser run`, which runs your own Playwright script inside the managed
281
+ browser. Before you reach for it, or for a temporary source edit such as
282
+ lowering a start value, to reach a hard-to-reach state, check whether that state
283
+ belongs in ECS. If it does, move it into a component as part of the work and
284
+ drive it with `ecs set-component`. Use browser automation only for what ECS and
285
+ the built-in tools cannot express, and say why.
216
286
 
217
287
  ## Deep reference
218
288
 
289
+ Look up IWSDK APIs with `npx @iwsdk/cli reference <op> --input-json '{...}'`
290
+ (the same tools are on MCP) instead of reading `node_modules`: `api`
291
+ `{"name":"World"}` for a known name, `search` `{"query":"PokeInteractable hand"}`,
292
+ `components` and `systems` to list every ECS type, `examples`
293
+ `{"api_name":"createSystem"}` for usage. `search` is a keyword search: give
294
+ identifiers plus a few words, not questions. The corpus ships inside
295
+ `@iwsdk/reference`, matches the installed version and needs no network or
296
+ warmup.
297
+
219
298
  Harness-native scoped rules cover `public/scenes/**`, `public/ui/**`,
220
299
  `src/assets.ts`, `src/scene-assets/**`, and `src/**/*.ts`. `AGENTS.md`-based
221
300
  harnesses receive nested instruction files; Cursor and Copilot receive their
222
301
  native rule formats. Skill procedures live in the selected harness's project
223
302
  skill directory and state when they apply.
303
+ <!-- END iwsdk-agent-guidance -->
@@ -1,3 +1,4 @@
1
+ <!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.0 sha256=4451a5b98ba38a835cca3fc49666cbe62ba77353f6b8d0ed7d46b691d35067c1 -->
1
2
  # IWSDK scoped project guidance
2
3
 
3
4
  This file augments the repository-root `AGENTS.md` for files in this directory.
@@ -68,3 +69,4 @@ back. Render each changed module before the root.
68
69
 
69
70
  For composing a scene rather than editing one, use the `iwsdk-compose-scene`
70
71
  skill — it owns the intake, review and stop-rule procedure this file does not.
72
+ <!-- END iwsdk-agent-guidance -->
@@ -1,3 +1,4 @@
1
+ <!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.0 sha256=abe74e27fdcd33f9fbdfa6fef5b11cd1427fe15c66fec1a0b884f3a09b750266 -->
1
2
  # IWSDK scoped project guidance
2
3
 
3
4
  This file augments the repository-root `AGENTS.md` for files in this directory.
@@ -62,3 +63,4 @@ can.
62
63
  For the authoring procedure — isolated preview, placement, editing, wiring
63
64
  runtime behavior, and the completion checklist — use the `iwsdk-ui` skill rather
64
65
  than improvising. This file is the format reference it relies on.
66
+ <!-- END iwsdk-agent-guidance -->
@@ -1,3 +1,4 @@
1
+ <!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.0 sha256=b60c812e637c6f5bd8f4480f83d7c28a93e042abac20fee504238e8981fa2b6f -->
1
2
  # IWSDK scoped project guidance
2
3
 
3
4
  This file augments the repository-root `AGENTS.md` for files in this directory.
@@ -149,3 +150,4 @@ mesh lowers to one `InstancedMesh`.
149
150
  Start assets at `castShadow: false` and opt in only for grounded focal masses.
150
151
  Don't build contact-shadow blob cards or `ShadowMaterial` catcher planes here: put
151
152
  `ContactShadow` or `ShadowCatcher` node components on the scene nodes instead.
153
+ <!-- END iwsdk-agent-guidance -->