@iwsdk/cli 1.1.0 → 1.2.0-rc.1

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 (160) hide show
  1. package/README.md +106 -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 +1532 -0
  20. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +96 -0
  21. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +267 -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 +179 -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-offline/SKILL.md +217 -0
  30. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/offline.ts.template +99 -0
  31. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/sw.js.template +241 -0
  32. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
  33. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/build-step.md +71 -0
  34. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/page.md +70 -0
  35. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/service-worker.md +107 -0
  36. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/testing.md +57 -0
  37. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +106 -0
  38. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/component-reference.md +152 -0
  39. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +102 -0
  40. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +309 -0
  41. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +230 -0
  42. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  43. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  44. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  45. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  46. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +208 -0
  47. package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +70 -0
  48. package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +335 -0
  49. package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
  50. package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +521 -0
  51. package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +60 -0
  52. package/dist/agent-guidance/files/.claude/rules/ecs-api.md +103 -0
  53. package/dist/agent-guidance/files/.claude/rules/scene-json.md +72 -0
  54. package/dist/agent-guidance/files/.claude/rules/uikitml.md +66 -0
  55. package/dist/agent-guidance/files/.claude/settings.json +30 -0
  56. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +312 -0
  57. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  58. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  59. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +277 -0
  60. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  61. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
  62. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  63. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
  64. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  65. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
  66. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  67. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
  68. package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +74 -0
  69. package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
  70. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +46 -0
  71. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +1532 -0
  72. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +96 -0
  73. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +267 -0
  74. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/planner.md +307 -0
  75. package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +282 -0
  76. package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +75 -0
  77. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +179 -0
  78. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  79. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
  80. package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +262 -0
  81. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/SKILL.md +217 -0
  82. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/offline.ts.template +99 -0
  83. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/sw.js.template +241 -0
  84. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
  85. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/build-step.md +71 -0
  86. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/page.md +70 -0
  87. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/service-worker.md +107 -0
  88. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/testing.md +57 -0
  89. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +106 -0
  90. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/component-reference.md +152 -0
  91. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +102 -0
  92. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +309 -0
  93. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +230 -0
  94. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  95. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  96. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  97. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  98. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +208 -0
  99. package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +70 -0
  100. package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +335 -0
  101. package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
  102. package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +62 -0
  103. package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +105 -0
  104. package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +74 -0
  105. package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +68 -0
  106. package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +55 -0
  107. package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +101 -0
  108. package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +71 -0
  109. package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +65 -0
  110. package/{guidance → dist/agent-guidance/files}/AGENTS.md +107 -27
  111. package/dist/agent-guidance/files/CLAUDE.md +3 -0
  112. package/dist/agent-guidance/files/public/scenes/AGENTS.md +72 -0
  113. package/dist/agent-guidance/files/public/ui/AGENTS.md +66 -0
  114. package/dist/agent-guidance/files/src/AGENTS.md +153 -0
  115. package/dist/agent-guidance/manifest.json +954 -0
  116. package/dist/agent-guidance.d.ts +140 -0
  117. package/dist/agent-guidance.d.ts.map +1 -0
  118. package/dist/agent-guidance.js +3612 -0
  119. package/dist/agent-guidance.js.map +1 -0
  120. package/dist/cli.js +4010 -750
  121. package/dist/cli.js.map +1 -1
  122. package/dist/commands/adapter.d.ts +1 -0
  123. package/dist/commands/adapter.d.ts.map +1 -1
  124. package/dist/commands/agents.d.ts +11 -0
  125. package/dist/commands/agents.d.ts.map +1 -0
  126. package/dist/commands/browser.d.ts +11 -0
  127. package/dist/commands/browser.d.ts.map +1 -1
  128. package/dist/commands/dev.d.ts +1 -0
  129. package/dist/commands/dev.d.ts.map +1 -1
  130. package/dist/commands/reference.d.ts +15 -1
  131. package/dist/commands/reference.d.ts.map +1 -1
  132. package/dist/commands/runtime.d.ts.map +1 -1
  133. package/dist/commands/upgrade.d.ts +138 -0
  134. package/dist/commands/upgrade.d.ts.map +1 -0
  135. package/dist/contract.js +32 -0
  136. package/dist/contract.js.map +1 -1
  137. package/dist/guidance-refresh.d.ts +53 -0
  138. package/dist/guidance-refresh.d.ts.map +1 -0
  139. package/dist/help.d.ts +2 -0
  140. package/dist/help.d.ts.map +1 -1
  141. package/dist/index.d.ts.map +1 -1
  142. package/dist/index.js +6114 -508
  143. package/dist/index.js.map +1 -1
  144. package/dist/mcp-stdio.d.ts.map +1 -1
  145. package/dist/metavr-telemetry.d.ts +6 -0
  146. package/dist/metavr-telemetry.d.ts.map +1 -1
  147. package/dist/migrations/iwsdk-migrate-0-5/SKILL.md +413 -0
  148. package/dist/migrations.d.ts +36 -0
  149. package/dist/migrations.d.ts.map +1 -0
  150. package/dist/package-manager.d.ts +34 -0
  151. package/dist/package-manager.d.ts.map +1 -0
  152. package/dist/release-notes.d.ts +28 -0
  153. package/dist/release-notes.d.ts.map +1 -0
  154. package/dist/release-notes.json +1506 -0
  155. package/dist/runtime-contract.d.ts +8 -0
  156. package/dist/runtime-contract.d.ts.map +1 -1
  157. package/dist/runtime-telemetry.d.ts +8 -1
  158. package/dist/runtime-telemetry.d.ts.map +1 -1
  159. package/dist/version.d.ts +1 -1
  160. package/package.json +9 -3
@@ -0,0 +1,74 @@
1
+ ---
2
+ description: "Scene JSON — things that fail silently"
3
+ globs:
4
+ - "public/scenes/**"
5
+ alwaysApply: false
6
+ ---
7
+
8
+ # Scene JSON — things that fail silently
9
+
10
+ Format reference lives in
11
+ `.agents/skills/iwsdk-compose-scene/references/scene-format.md`: the document
12
+ boundary, content kinds, prefabs, patterns, light fields, authoring views. Read
13
+ it for imports, prefabs, patterns, or a schema detail not covered by active
14
+ guidance. For ordinary flat node, component, and authored-view edits, this rule,
15
+ the existing scene, and the active specialist are sufficient. This file is only
16
+ the short list of behaviours that produce no error when you get them wrong.
17
+
18
+ Only `iwsdk.scene.v1` exists, units are always meters, and structural objects are
19
+ closed — an unknown field fails validation.
20
+
21
+ ## Imports stop at the authoring boundary
22
+
23
+ Authoring tools can validate and render a root with `imports`, so modular scratch
24
+ scenes remain useful for composition. The editable scene session and application
25
+ runtime deliberately reject imports. Run `scene_flatten_file` or
26
+ `npx @iwsdk/cli scene flatten` once, verify the source and output runtime hashes match,
27
+ then make the flat output the sole editable source of truth. Never re-flatten over
28
+ later human editor changes.
29
+
30
+ ## The player materialises at the scene origin
31
+
32
+ `0,0,0` unless the document authors `player.transform`. Nothing warns you. A
33
+ scene can pass every authored camera view and still spawn the player inside the
34
+ geometry, because review cameras are not the viewpoint that ships. Keep that
35
+ volume clear or place the player deliberately, and author a diagnostic view at
36
+ player eye height to prove it.
37
+
38
+ ## `visibleNodeIds` is the silent-failure detector
39
+
40
+ `renderStats.visibleNodeIds` lists what actually rendered. A node missing from it
41
+ did not appear — even when the image looks plausible and `valid` is `true`. Check
42
+ it against what you expect rather than trusting the picture. Single-sided
43
+ surfaces facing away from the camera are the usual cause, and they report nothing.
44
+ `ContactShadow` and `ShadowCatcher` meshes take no rays, so a node whose only
45
+ content is one of them is never listed; check the object it grounds instead.
46
+
47
+ ## Component keys come in two forms
48
+
49
+ Root-level components use the namespaced form
50
+ (`com.iwsdk.components.DomeGradient`). Node-level components accept the bare name
51
+ (`RayInteractable`, `LocomotionEnvironment`). **The editor writes the namespaced
52
+ form on nodes**, so a file touched by both hands contains both. Match whatever the
53
+ node already uses instead of normalising.
54
+
55
+ `LevelRoot`, `LevelTag` and `Transform` are runtime-owned; never author them.
56
+
57
+ ## Browser hero views and XR spawn framing are distinct
58
+
59
+ Outside immersive XR, the hero authoring view supersedes `world.render.camera`
60
+ from `iwsdk.config.json` once the level initialises. While XR is presenting,
61
+ the tracked player rig owns the camera and the hero view is intentionally not
62
+ applied. Use the hero view for editor/browser framing, and validate important
63
+ content from the authored `player.transform` spawn (or the default standing
64
+ view near `[0, 1.6, 0]`) before accepting XR framing.
65
+
66
+ ## Validation
67
+
68
+ `scene_render_file` validates, composes, lowers and renders without touching the
69
+ open document. A result is usable only when `valid: true` **and** a PNG comes
70
+ back. Render each changed module before the root.
71
+
72
+ For composing a scene rather than editing one, use the `iwsdk-compose-scene`
73
+ skill — it owns the intake, review and stop-rule procedure this file does not.
74
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=f32c3e7d4024f56a3ff5ae32b42c236377551cbd3b2b231e84ada68362b68266 name=scene-json.mdc (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -0,0 +1,68 @@
1
+ ---
2
+ description: "UIKitML panels"
3
+ globs:
4
+ - "public/ui/**"
5
+ alwaysApply: false
6
+ ---
7
+
8
+ # UIKitML panels
9
+
10
+ HTML/CSS-shaped, not a browser engine. Validate rather than assume support.
11
+
12
+ **Numeric sizes are UIKit units (centimetres), not pixels.** `width: 95` is a
13
+ 0.95 m panel. Font sizes follow the same scale: `font-size: 3` is 3 cm tall.
14
+
15
+ **Panels are single-sided and face +Z.** To aim one at a camera, yaw by
16
+ `atan2(dx, dz)` toward it — there is no 180° term. A back-facing panel renders
17
+ nothing, reports no error, and still returns `valid: true` from
18
+ `scene_render_file`; the only signal is its absence from
19
+ `renderStats.visibleNodeIds`.
20
+
21
+ Verified working: `display: flex`, `flex-direction`, `align-items`,
22
+ `justify-content: space-between`, `gap`, `margin-*`, `padding-*`, `width`,
23
+ `height`, `background-color`, `border-color`, `border-width`, `border-radius`,
24
+ `font-size`, `font-weight`, `color`, `text-align`, `cursor`. Tags `div`, `span`,
25
+ `button` all work.
26
+
27
+ Expand shorthands (`padding: 12 18` → four properties), use unitless
28
+ line-height multipliers, and prefer uniform `border-color`/`border-width` over
29
+ directional variants. Parser errors include source locations.
30
+
31
+ **Production builds drop unused Lucide icons.** They keep only icons named in
32
+ `public/**/*.uikitml`. Icons named only by UIKitML built at runtime or loaded
33
+ from elsewhere must be listed in `iwsdkDev({ bundle: { icons: [...] } })`, or
34
+ they fail after `npm run build`.
35
+
36
+ ## Runtime API
37
+
38
+ Resolve the placed panel by **scene node id**, then elements by their `id`
39
+ attribute:
40
+
41
+ ```ts
42
+ const panel = world.getSceneObject<UIKitMLAsset>('config-panel');
43
+ const chip = panel?.getElementById<UIKit.Text>('finish-gold');
44
+ chip?.addEventListener('click', onClick);
45
+ chip?.setProperties({ backgroundColor: '#d8e6f5', color: '#0e1116' });
46
+ ```
47
+
48
+ `setProperties` updates both text (`{ text }`) and style
49
+ (`backgroundColor`, `color`, `borderColor`, `display`) — style changes do apply,
50
+ including over class-based styles from the `<style>` block. `UIKit.Text` is the
51
+ public element type; no deep import from `@pmndrs/uikit` is needed.
52
+
53
+ Three distinct identities, don't conflate them: the **manifest ID** names the
54
+ reusable asset, the **scene node ID** names the placed instance, and the element
55
+ `id` names a field inside it. Never depend on a transient entity index.
56
+
57
+ Give the panel node `RayInteractable` so clicks land.
58
+
59
+ The editor render does not run application systems, so `scene_screenshot` can
60
+ never prove a panel *behaves* — only `browser_screenshot`, against the runtime,
61
+ can.
62
+
63
+ ---
64
+
65
+ For the authoring procedure — isolated preview, placement, editing, wiring
66
+ runtime behavior, and the completion checklist — use the `iwsdk-ui` skill rather
67
+ than improvising. This file is the format reference it relies on.
68
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=ce002bd4759a1d087c3e18fd3e2a9a009eb3bef5561d0a698f86726a1bd7f9c3 name=uikitml.mdc (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -0,0 +1,55 @@
1
+ ---
2
+ applyTo: "src/assets.ts,src/assets.js,src/iwsdk/assets.ts,src/iwsdk/assets.js,src/scene-assets/**"
3
+ ---
4
+
5
+ # Asset manifest contract
6
+
7
+ `src/assets.ts` is imported **independently by the app runtime and the editor**,
8
+ in separate JS realms. It must therefore be deterministic and self-contained:
9
+
10
+ - no `World`, scene, iframe, editor object or DOM access
11
+ - no timers, no fetching ambient state
12
+ - no reliance on singleton object identity across realms
13
+ - prototypes immutable after registration, and never parented
14
+
15
+ A manifest entry is either a URL descriptor (`{ url, type, name?, priority? }`)
16
+ or a bare parentless `Object3D`. `AssetType` covers `GLTF`, `Audio`, `Texture`,
17
+ `HDRTexture`, `UIKitML`. Only glTF, UIKitML and `Object3D` entries are placeable
18
+ as scene content; audio/texture/HDR are for application systems.
19
+
20
+ Build public URLs from `import.meta.env.BASE_URL` so runtime, editor and subpath
21
+ builds resolve identically. A file in `public/` is **not** available to a scene
22
+ until it is registered here.
23
+
24
+ ## Procedural assets
25
+
26
+ Export a parentless `Object3D` from `src/scene-assets/*.scene-asset.ts` and
27
+ register it under a stable ID. The registry rejects an already-parented
28
+ prototype.
29
+
30
+ Every placement is a distinct hierarchy clone, but **geometry and materials stay
31
+ shared**. Never dispose them from a placed clone; world teardown owns their
32
+ lifetime. Reassigning `mesh.material` on a clone is fine and is how you restyle
33
+ one instance — mutating the shared material in place changes every instance.
34
+
35
+ Bounds come from `Box3` over the instantiated asset and drive placement,
36
+ selection, framing and scatter collision. Put the origin where composition wants
37
+ it (usually floor contact, or the object's own pivot), keep transforms finite,
38
+ and don't let invisible helpers inflate bounds.
39
+
40
+ ## Cost
41
+
42
+ Split tessellation by viewing distance rather than using one budget everywhere: a
43
+ close-range hero model and coarser display copies of the same form are two
44
+ prototypes from one factory function. Sphere/lathe segment counts dominate small
45
+ repeated detail more than people expect — check `renderStats.triangles` rather
46
+ than guessing.
47
+
48
+ Reuse material instances within a module. Prefer prefabs plus a deterministic
49
+ pattern for repetition; a pattern whose prefab resolves to a single component-free
50
+ mesh lowers to one `InstancedMesh`.
51
+
52
+ Start assets at `castShadow: false` and opt in only for grounded focal masses.
53
+ Don't build contact-shadow blob cards or `ShadowMaterial` catcher planes here: put
54
+ `ContactShadow` or `ShadowCatcher` node components on the scene nodes instead.
55
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 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) -->
@@ -0,0 +1,101 @@
1
+ ---
2
+ applyTo: "src/**/*.ts,src/**/*.js"
3
+ ---
4
+
5
+ # ECS API reference
6
+
7
+ ## Field types
8
+
9
+ ```
10
+ Types.Float32 Float64 Int8 Int16 Int32 Boolean String FilePath
11
+ Types.Vec2 Vec3 Vec4 Color(RGBA) Entity Enum
12
+ Types.Object // avoid — not optimised
13
+ ```
14
+
15
+ ## Component
16
+
17
+ Declare in a system-free module, then list it in `src/components.ts` via
18
+ `defineComponents()` or the editor cannot author it.
19
+
20
+ ```ts
21
+ export const MyComponent = createComponent('MyComponent', {
22
+ speed: { type: Types.Float32, default: 1 },
23
+ tint: { type: Types.Color, default: [1, 1, 1, 1] }, // RGBA
24
+ });
25
+ ```
26
+
27
+ Optional metadata per field — `label`, `step`, `min`, `max`, `enum`, `help`,
28
+ `widget` — drives the editor inspector.
29
+
30
+ ## System
31
+
32
+ ```ts
33
+ export class MySystem extends createSystem(
34
+ {
35
+ items: { required: [MyComponent] },
36
+ active: { required: [MyComponent], excluded: [Grabbed] },
37
+ },
38
+ { speed: { type: Types.Float32, default: 1 } }, // optional config
39
+ ) {
40
+ private temp!: Vector3;
41
+
42
+ init() {
43
+ this.temp = new Vector3();
44
+ this.queries.items.subscribe('qualify', (entity) => { /* matched */ });
45
+ this.cleanupFuncs.push(this.config.speed.subscribe((v) => { /* … */ }));
46
+ }
47
+
48
+ update(delta: number, time: number) {
49
+ for (const entity of this.queries.active.entities) { /* no allocations */ }
50
+ }
51
+ }
52
+ ```
53
+
54
+ Queries take `required`, `excluded` and `where` (value predicates via `eq`, `ne`,
55
+ `lt`, `le`, `gt`, `ge`, `isin`, `nin`). `excluded` is the clean way to skip
56
+ entities in a transient state — e.g. excluding `Grabbed` so a held object is left
57
+ alone.
58
+
59
+ Register explicitly in `src/index.ts` with `world.registerSystem(MySystem)`.
60
+
61
+ Read fields with `entity.getValue(Component, 'field')`. For vector fields use
62
+ `entity.getVectorView(Component, 'field')` — it returns a `Float32Array` view with
63
+ no allocation, and `setValue` **throws** on vector fields in elics 3.4.x.
64
+
65
+ ## Interaction components
66
+
67
+ `RayInteractable` plus `Hovered`/`Pressed` covers both mouse/touch canvas input
68
+ and XR rays. Grab components: `OneHandGrabbable` and `TwoHandsGrabbable` are
69
+ proximity-based and respond to **squeeze**, while `DistanceGrabbable` is
70
+ ray-based and responds to **trigger**. `Grabbed` is a transient tag managed by
71
+ `GrabSystem` — read it, never add or remove it. `GrabSystem.useHandPinchForGrab`
72
+ defaults to **true**, so a hand pinch grabs; set it to `false` to require squeeze.
73
+
74
+ `DistanceGrabbable` fields: `movementMode` (`MoveTowardsTarget`, `MoveFromTarget`,
75
+ `MoveAtSource`, `RotateAtSource`), `returnToOrigin`, `moveSpeedFactor`,
76
+ `detachOnGrab`, `translate`, `rotate`, `scale`, `targetPositionOffset`,
77
+ `targetQuaternionOffset`. `returnToOrigin: true` gives spring-back on release with
78
+ no custom code.
79
+
80
+ For a held object use `GrabSystem`'s public methods — `forceRelease(entity)`,
81
+ `getHolderHand(entity)` — never deep-import `Handle`.
82
+
83
+ ## XR input
84
+
85
+ ```ts
86
+ const pad = this.input.xr.gamepads.right;
87
+ pad?.getButtonDown(InputComponent.Trigger); // just pressed
88
+ pad?.getAxesValues(InputComponent.Thumbstick);
89
+ this.player.head; this.player.raySpaces.left; this.player.gripSpaces.right;
90
+ ```
91
+
92
+ Prefer `world.input.actions` for reusable intent (`locomotion.move`) over raw
93
+ buttons. Browser controls live at `world.input.keyboard` and
94
+ `world.input.browserGamepads`.
95
+
96
+ ## Lifecycle
97
+
98
+ `world.visibilityState` reports `NonImmersive`, `Visible`, `VisibleBlurred` —
99
+ pause simulation on blur. `world.camera.position` is local to `world.player`; use
100
+ `getWorldPosition()` when logic needs the true viewer position.
101
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=724a02986ce0999bc31c02b4f1e4a7b6b83c9966f994979a340e36b6243d26fd name=ecs-api.instructions.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -0,0 +1,71 @@
1
+ ---
2
+ applyTo: "public/scenes/**"
3
+ ---
4
+
5
+ # Scene JSON — things that fail silently
6
+
7
+ Format reference lives in
8
+ `.agents/skills/iwsdk-compose-scene/references/scene-format.md`: the document
9
+ boundary, content kinds, prefabs, patterns, light fields, authoring views. Read
10
+ it for imports, prefabs, patterns, or a schema detail not covered by active
11
+ guidance. For ordinary flat node, component, and authored-view edits, this rule,
12
+ the existing scene, and the active specialist are sufficient. This file is only
13
+ the short list of behaviours that produce no error when you get them wrong.
14
+
15
+ Only `iwsdk.scene.v1` exists, units are always meters, and structural objects are
16
+ closed — an unknown field fails validation.
17
+
18
+ ## Imports stop at the authoring boundary
19
+
20
+ Authoring tools can validate and render a root with `imports`, so modular scratch
21
+ scenes remain useful for composition. The editable scene session and application
22
+ runtime deliberately reject imports. Run `scene_flatten_file` or
23
+ `npx @iwsdk/cli scene flatten` once, verify the source and output runtime hashes match,
24
+ then make the flat output the sole editable source of truth. Never re-flatten over
25
+ later human editor changes.
26
+
27
+ ## The player materialises at the scene origin
28
+
29
+ `0,0,0` unless the document authors `player.transform`. Nothing warns you. A
30
+ scene can pass every authored camera view and still spawn the player inside the
31
+ geometry, because review cameras are not the viewpoint that ships. Keep that
32
+ volume clear or place the player deliberately, and author a diagnostic view at
33
+ player eye height to prove it.
34
+
35
+ ## `visibleNodeIds` is the silent-failure detector
36
+
37
+ `renderStats.visibleNodeIds` lists what actually rendered. A node missing from it
38
+ did not appear — even when the image looks plausible and `valid` is `true`. Check
39
+ it against what you expect rather than trusting the picture. Single-sided
40
+ surfaces facing away from the camera are the usual cause, and they report nothing.
41
+ `ContactShadow` and `ShadowCatcher` meshes take no rays, so a node whose only
42
+ content is one of them is never listed; check the object it grounds instead.
43
+
44
+ ## Component keys come in two forms
45
+
46
+ Root-level components use the namespaced form
47
+ (`com.iwsdk.components.DomeGradient`). Node-level components accept the bare name
48
+ (`RayInteractable`, `LocomotionEnvironment`). **The editor writes the namespaced
49
+ form on nodes**, so a file touched by both hands contains both. Match whatever the
50
+ node already uses instead of normalising.
51
+
52
+ `LevelRoot`, `LevelTag` and `Transform` are runtime-owned; never author them.
53
+
54
+ ## Browser hero views and XR spawn framing are distinct
55
+
56
+ Outside immersive XR, the hero authoring view supersedes `world.render.camera`
57
+ from `iwsdk.config.json` once the level initialises. While XR is presenting,
58
+ the tracked player rig owns the camera and the hero view is intentionally not
59
+ applied. Use the hero view for editor/browser framing, and validate important
60
+ content from the authored `player.transform` spawn (or the default standing
61
+ view near `[0, 1.6, 0]`) before accepting XR framing.
62
+
63
+ ## Validation
64
+
65
+ `scene_render_file` validates, composes, lowers and renders without touching the
66
+ open document. A result is usable only when `valid: true` **and** a PNG comes
67
+ back. Render each changed module before the root.
68
+
69
+ For composing a scene rather than editing one, use the `iwsdk-compose-scene`
70
+ skill — it owns the intake, review and stop-rule procedure this file does not.
71
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=c73f635cec34f9e99b2bc59ffe63583842d40e419a499225a56cbb7838d9bccd name=scene-json.instructions.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -0,0 +1,65 @@
1
+ ---
2
+ applyTo: "public/ui/**"
3
+ ---
4
+
5
+ # UIKitML panels
6
+
7
+ HTML/CSS-shaped, not a browser engine. Validate rather than assume support.
8
+
9
+ **Numeric sizes are UIKit units (centimetres), not pixels.** `width: 95` is a
10
+ 0.95 m panel. Font sizes follow the same scale: `font-size: 3` is 3 cm tall.
11
+
12
+ **Panels are single-sided and face +Z.** To aim one at a camera, yaw by
13
+ `atan2(dx, dz)` toward it — there is no 180° term. A back-facing panel renders
14
+ nothing, reports no error, and still returns `valid: true` from
15
+ `scene_render_file`; the only signal is its absence from
16
+ `renderStats.visibleNodeIds`.
17
+
18
+ Verified working: `display: flex`, `flex-direction`, `align-items`,
19
+ `justify-content: space-between`, `gap`, `margin-*`, `padding-*`, `width`,
20
+ `height`, `background-color`, `border-color`, `border-width`, `border-radius`,
21
+ `font-size`, `font-weight`, `color`, `text-align`, `cursor`. Tags `div`, `span`,
22
+ `button` all work.
23
+
24
+ Expand shorthands (`padding: 12 18` → four properties), use unitless
25
+ line-height multipliers, and prefer uniform `border-color`/`border-width` over
26
+ directional variants. Parser errors include source locations.
27
+
28
+ **Production builds drop unused Lucide icons.** They keep only icons named in
29
+ `public/**/*.uikitml`. Icons named only by UIKitML built at runtime or loaded
30
+ from elsewhere must be listed in `iwsdkDev({ bundle: { icons: [...] } })`, or
31
+ they fail after `npm run build`.
32
+
33
+ ## Runtime API
34
+
35
+ Resolve the placed panel by **scene node id**, then elements by their `id`
36
+ attribute:
37
+
38
+ ```ts
39
+ const panel = world.getSceneObject<UIKitMLAsset>('config-panel');
40
+ const chip = panel?.getElementById<UIKit.Text>('finish-gold');
41
+ chip?.addEventListener('click', onClick);
42
+ chip?.setProperties({ backgroundColor: '#d8e6f5', color: '#0e1116' });
43
+ ```
44
+
45
+ `setProperties` updates both text (`{ text }`) and style
46
+ (`backgroundColor`, `color`, `borderColor`, `display`) — style changes do apply,
47
+ including over class-based styles from the `<style>` block. `UIKit.Text` is the
48
+ public element type; no deep import from `@pmndrs/uikit` is needed.
49
+
50
+ Three distinct identities, don't conflate them: the **manifest ID** names the
51
+ reusable asset, the **scene node ID** names the placed instance, and the element
52
+ `id` names a field inside it. Never depend on a transient entity index.
53
+
54
+ Give the panel node `RayInteractable` so clicks land.
55
+
56
+ The editor render does not run application systems, so `scene_screenshot` can
57
+ never prove a panel *behaves* — only `browser_screenshot`, against the runtime,
58
+ can.
59
+
60
+ ---
61
+
62
+ For the authoring procedure — isolated preview, placement, editing, wiring
63
+ runtime behavior, and the completion checklist — use the `iwsdk-ui` skill rather
64
+ than improvising. This file is the format reference it relies on.
65
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 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.1 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 -->
@@ -0,0 +1,3 @@
1
+ # IWSDK project guidance
2
+
3
+ @AGENTS.md