@iwsdk/create 0.5.2 → 1.0.0-rc.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (107) hide show
  1. package/dist/cli.js +7223 -215
  2. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/SKILL.md +311 -0
  3. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  4. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  5. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/SKILL.md +262 -0
  6. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  7. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  8. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  9. package/dist/guidance/{claude/.claude/skills/iwsdk-scene-composer → agents/.agents/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
  10. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  11. package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
  12. package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +69 -91
  13. package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
  14. package/dist/guidance/agents/.agents/skills/iwsdk-dev/SKILL.md +45 -0
  15. package/dist/guidance/{claude/.claude/skills/iwsdk-planner → agents/.agents/skills/iwsdk-dev}/references/api-reference.md +53 -45
  16. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/iterate.md +239 -0
  17. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/planner.md +303 -0
  18. package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +37 -114
  19. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/SKILL.md +177 -0
  20. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  21. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
  22. package/dist/guidance/agents/.agents/skills/iwsdk-native-xr-test/SKILL.md +246 -0
  23. package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -78
  24. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
  25. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
  26. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  27. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  28. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  29. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  30. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  31. package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +45 -136
  32. package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +251 -157
  33. package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +9 -6
  34. package/dist/guidance/claude/.claude/rules/scene-json.md +6 -4
  35. package/dist/guidance/claude/.claude/settings.json +6 -2
  36. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/SKILL.md +311 -0
  37. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  38. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  39. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/SKILL.md +262 -0
  40. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  41. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  42. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  43. package/dist/guidance/{agents/.agents/skills/iwsdk-scene-composer → claude/.claude/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
  44. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  45. package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
  46. package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +69 -91
  47. package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
  48. package/dist/guidance/claude/.claude/skills/iwsdk-dev/SKILL.md +45 -0
  49. package/dist/guidance/{agents/.agents/skills/iwsdk-planner → claude/.claude/skills/iwsdk-dev}/references/api-reference.md +53 -45
  50. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/iterate.md +239 -0
  51. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/planner.md +303 -0
  52. package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +37 -114
  53. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/SKILL.md +177 -0
  54. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  55. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
  56. package/dist/guidance/claude/.claude/skills/iwsdk-native-xr-test/SKILL.md +246 -0
  57. package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -78
  58. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
  59. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
  60. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  61. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  62. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  63. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  64. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  65. package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +45 -136
  66. package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +251 -157
  67. package/dist/guidance/claude/CLAUDE.md +2 -141
  68. package/dist/guidance/codex/.codex/config.toml +1 -1
  69. package/dist/guidance/common/AGENTS.md +96 -37
  70. package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +6 -4
  71. package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +6 -4
  72. package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +6 -4
  73. package/dist/template/common/README.md +13 -0
  74. package/dist/template/common/public/ui/welcome.uikitml +0 -19
  75. package/dist/template/common/src/robot.ts +5 -0
  76. package/dist/template/common/vite.config.ts +18 -0
  77. package/dist/template/common-js/README.md +13 -0
  78. package/dist/template/common-js/public/ui/welcome.uikitml +0 -19
  79. package/dist/template/common-js/src/robot.js +5 -0
  80. package/dist/template/common-js/vite.config.js +18 -0
  81. package/dist/template/scenes/ar.iwsdk.scene.json +8 -1
  82. package/package.json +8 -7
  83. package/scripts/verify-release-ready.mjs +25 -0
  84. package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +0 -364
  85. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +0 -243
  86. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +0 -101
  87. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +0 -176
  88. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +0 -156
  89. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +0 -199
  90. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +0 -257
  91. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
  92. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
  93. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
  94. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
  95. package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +0 -364
  96. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +0 -243
  97. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +0 -101
  98. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +0 -176
  99. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +0 -156
  100. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +0 -199
  101. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +0 -257
  102. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
  103. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
  104. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
  105. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
  106. /package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
  107. /package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
@@ -1,10 +1,10 @@
1
1
  # IWSDK API Reference & Best Practices
2
2
 
3
- Ground-truth API patterns for IWSDK app development. This file backs the
4
- `iwsdk-planner` skill: load it whenever you are grounding a plan to real APIs,
5
- writing IWSDK code, or reviewing it. It contains no process guidance — the
6
- pipeline lives in `SKILL.md`; phase playbooks live in the sibling
7
- `references/*.md` files.
3
+ Ground-truth API patterns for IWSDK app development. This file is the shared
4
+ API reference behind `iwsdk-dev`; load it when grounding implementation details,
5
+ writing IWSDK code, or reviewing it. It contains no process guidance. The router
6
+ lives in `SKILL.md`, and the internal planner and iterate playbooks are siblings
7
+ in this directory.
8
8
 
9
9
  **Version sensitivity:** this reference tracks the SDK at the time the skill
10
10
  shipped. For any API your plan depends on, verify the signature against the
@@ -37,7 +37,7 @@ shared by runtime and editor. Build local public URLs from
37
37
  `import.meta.env.BASE_URL`; literal `./...` URLs resolve against the managed
38
38
  editor route during editor use and are not a safe project-wide convention.
39
39
 
40
- Use `input.canvasPointerEvents` for browser mouse/touch canvas events. Browser canvas pointers and XR rays both feed Three/Object3D pointer events and ECS `Hovered`/`Pressed` tags on `Interactable`/`RayInteractable` entities. XR-specific input is available at `world.input.xr`; keyboard and standard browser gamepads live at `world.input.keyboard` and `world.input.browserGamepads`. Reusable systems should prefer `world.input.actions` for intent such as `locomotion.move` or `locomotion.jump`; opt into browser locomotion bindings with `features.locomotion.browserControls`.
40
+ Use `input.canvasPointerEvents` for browser mouse/touch canvas events. Browser canvas pointers and XR rays both feed Three/Object3D pointer events and ECS `Hovered`/`Pressed` tags on `RayInteractable` entities. XR-specific input is available at `world.input.xr`; keyboard and standard browser gamepads live at `world.input.keyboard` and `world.input.browserGamepads`. Reusable systems should prefer `world.input.actions` for intent such as `locomotion.move` or `locomotion.jump`; opt into browser locomotion bindings with `features.locomotion.browserControls`.
41
41
 
42
42
  ## Critical Best Practices
43
43
 
@@ -85,7 +85,7 @@ Instead of polling or storing state, react to entity lifecycle events:
85
85
 
86
86
  ```typescript
87
87
  export class ReactiveSystem extends createSystem({
88
- interactables: { required: [Interactable, Transform] },
88
+ interactables: { required: [RayInteractable, Transform] },
89
89
  }) {
90
90
  init() {
91
91
  // React when entities enter the query
@@ -177,7 +177,7 @@ Types.Object; // Any JS object (avoid if possible - not optimized)
177
177
  import { createComponent, Types } from '@iwsdk/core';
178
178
 
179
179
  // Tag component (no data, just marks entities)
180
- export const Interactable = createComponent('Interactable', {}, '');
180
+ export const Targetable = createComponent('Targetable', {}, '');
181
181
 
182
182
  // Data component with proper types
183
183
  export const Health = createComponent('Health', {
@@ -336,8 +336,8 @@ this.player; // XROrigin (Group) - VR rig root
336
336
  this.player.head; // Head tracking (viewer pose)
337
337
  this.player.raySpaces.left; // Left controller ray origin
338
338
  this.player.raySpaces.right; // Right controller ray origin
339
- this.player.gripSpaces.left; // Left controller grip position
340
- this.player.gripSpaces.right; // Right controller grip position
339
+ this.player.gripSpaces.left; // Left controller grip pose
340
+ this.player.gripSpaces.right; // Right controller grip pose
341
341
  this.player.secondaryRaySpaces.left; // Secondary left ray
342
342
  this.player.secondaryRaySpaces.right; // Secondary right ray
343
343
  this.player.secondaryGripSpaces.left; // Secondary left grip
@@ -349,6 +349,10 @@ this.player.head.getWorldPosition(headPos);
349
349
 
350
350
  const rightHandPos = new Vector3();
351
351
  this.player.gripSpaces.right.getWorldPosition(rightHandPos);
352
+
353
+ // Attach a held model so it inherits both grip position and orientation.
354
+ heldModel.position.set(0, -0.02, 0.05); // Model-local alignment offset.
355
+ this.player.gripSpaces.right.add(heldModel);
352
356
  ```
353
357
 
354
358
  ### 10. Audio System
@@ -1007,7 +1011,8 @@ RaycastSpace.Screen; // Phone AR screen touch (tap-to-place)
1007
1011
 
1008
1012
  ### 23. Follower Component
1009
1013
 
1010
- Makes an entity follow another Object3D (typically the player's head for head-locked UI).
1014
+ Makes an entity follow another Object3D with thresholded, smoothed motion. It
1015
+ can keep compact global UI discoverable without rigidly head-locking it.
1011
1016
 
1012
1017
  ```typescript
1013
1018
  import { Follower, FollowBehavior } from '@iwsdk/core';
@@ -1074,7 +1079,7 @@ CameraFacing.Unknown; // Any available camera (default)
1074
1079
  CameraState.Inactive; // Not started
1075
1080
  CameraState.Starting; // Async initialization in progress
1076
1081
  CameraState.Active; // Stream running
1077
- CameraState.Error; // Failed to start
1082
+ CameraState.Error; // Failed to start; terminal until explicitly restarted
1078
1083
  ```
1079
1084
 
1080
1085
  **CameraUtils** static class:
@@ -1084,6 +1089,9 @@ CameraState.Error; // Failed to start
1084
1089
  const devices = await CameraUtils.getDevices();
1085
1090
  const backCam = CameraUtils.findByFacing(devices, CameraFacing.Back);
1086
1091
 
1092
+ // Retry after correcting a startup error or changing camera configuration
1093
+ CameraUtils.restart(cameraEntity);
1094
+
1087
1095
  // Capture current frame as canvas (for snapshot/processing)
1088
1096
  const canvas = CameraUtils.captureFrame(cameraEntity);
1089
1097
  if (canvas) {
@@ -1091,7 +1099,7 @@ if (canvas) {
1091
1099
  }
1092
1100
  ```
1093
1101
 
1094
- **Requires:** `features: { camera: true }`. Camera stream only activates during XR sessions.
1102
+ **Requires:** `features: { camera: true }`, a secure context, camera permission, and a camera exposed through browser `MediaDevices`. Streams can run while the world is visible in browser-only or immersive XR mode. `CameraSource` does not expose Quest passthrough or raw headset-camera frames.
1095
1103
 
1096
1104
  ### 25. PhysicsManipulation Component
1097
1105
 
@@ -1187,7 +1195,7 @@ world.getPersistentRoot(); // Returns the scene Object3D
1187
1195
  | Visibility | Show/hide objects |
1188
1196
  | LevelTag | Marks level membership |
1189
1197
  | LevelRoot | Level root marker |
1190
- | Interactable | Marks interactive objects |
1198
+ | RayInteractable | Marks objects for ray and pointer interaction |
1191
1199
  | Hovered | Currently hovered |
1192
1200
  | Pressed | Currently pressed/grabbed |
1193
1201
  | OneHandGrabbable | Single-hand manipulation |
@@ -1219,7 +1227,7 @@ world.getPersistentRoot(); // Returns the scene Object3D
1219
1227
  | System | Priority | Purpose |
1220
1228
  | ------------------------ | -------- | --------------------------------------------------------------------------------------------------- |
1221
1229
  | LocomotionSystem | -5 | Movement (teleport/slide/turn) |
1222
- | InputSystem | -4 | Interactable state management |
1230
+ | InputSystem | -4 | Pointer interaction state management |
1223
1231
  | GrabSystem | -3 | Grab handling |
1224
1232
  | PhysicsSystem | -2 | Physics simulation |
1225
1233
  | SceneUnderstandingSystem | -1 | AR plane/mesh detection |
@@ -1289,30 +1297,30 @@ Before writing custom code, check if IWSDK already provides the functionality. R
1289
1297
 
1290
1298
  ### Reinvention Risk Table
1291
1299
 
1292
- | What you might build from scratch | What IWSDK already provides |
1293
- | ------------------------------------- | ---------------------------------------------------------------------------- |
1294
- | GLTF loading with GLTFLoader | `AssetManager.loadGLTF()` or a `defineAssets()` project catalog |
1295
- | Ray/line mesh for controller pointing | `RayPointer` — cylinder + gradient shader + cursor circle (auto) |
1296
- | Hover/click detection with Raycaster | `Interactable` + `Hovered` + `Pressed` components |
1297
- | Custom skybox sphere | `DomeGradient` or `DomeTexture` component |
1298
- | PBR environment lighting | `IBLGradient` or `IBLTexture` component |
1299
- | Teleport arc + landing marker | `LocomotionSystem` — full visuals included |
1300
- | Comfort vignette for motion | `LocomotionSystem` — `comfortAssist` config |
1301
- | Controller 3D models | Auto-loaded from WebXR Input Profiles |
1302
- | Hand tracking meshes | `AnimatedHand` with skeletal mesh + outline |
1303
- | Object grab + manipulation | `OneHandGrabbable` / `TwoHandsGrabbable` / `DistanceGrabbable` |
1304
- | Hit-test against real world | `EnvironmentRaycastTarget` component |
1305
- | Spatial audio | `AudioSource` component with pooling |
1306
- | Camera feed texture | `CameraSource` component |
1307
- | Depth occlusion shader | `DepthOccludable` component |
1308
- | HUD / screen-space UI | `ScreenSpace` component with CSS units |
1309
- | Follow-head billboard | `Follower` component |
1310
- | Scene cleanup on level change | `LevelSystem` + `LevelTag` (automatic) |
1311
- | Gamepad button debouncing | `StatefulGamepad` — `getButtonDown()` / `getButtonUp()` |
1312
- | Manual GPU cleanup with traverse | `entity.dispose()` — destroys entity + cleans up geometry/materials/textures |
1313
- | Manual world-space positioning | `setWorldPosition()` / `setWorldQuaternion()` utilities |
1314
- | Manual XR hit-test setup | `EnvironmentRaycastTarget` component + `EnvironmentRaycastSystem` |
1315
- | Manual camera video feed | `CameraSource` component + `CameraUtils` static class |
1300
+ | What you might build from scratch | What IWSDK already provides |
1301
+ | -------------------------------------- | ---------------------------------------------------------------------------- |
1302
+ | GLTF loading with GLTFLoader | `AssetManager.loadGLTF()` or a `defineAssets()` project catalog |
1303
+ | Ray/line mesh for controller pointing | `RayPointer` — cylinder + gradient shader + cursor circle (auto) |
1304
+ | Hover/click interaction with Raycaster | `RayInteractable` + `Hovered` + `Pressed` components |
1305
+ | Custom skybox sphere | `DomeGradient` or `DomeTexture` component |
1306
+ | PBR environment lighting | `IBLGradient` or `IBLTexture` component |
1307
+ | Teleport arc + landing marker | `LocomotionSystem` — full visuals included |
1308
+ | Comfort vignette for motion | `LocomotionSystem` — `comfortAssist` config |
1309
+ | Controller 3D models | Auto-loaded from WebXR Input Profiles |
1310
+ | Hand tracking meshes | `AnimatedHand` with skeletal mesh + outline |
1311
+ | Object grab + manipulation | `OneHandGrabbable` / `TwoHandsGrabbable` / `DistanceGrabbable` |
1312
+ | Hit-test against real world | `EnvironmentRaycastTarget` component |
1313
+ | Spatial audio | `AudioSource` component with pooling |
1314
+ | Camera feed texture | `CameraSource` component |
1315
+ | Depth occlusion shader | `DepthOccludable` component |
1316
+ | HUD / screen-space UI | `ScreenSpace` component with CSS units |
1317
+ | Follow-head billboard | `Follower` component |
1318
+ | Scene cleanup on level change | `LevelSystem` + `LevelTag` (automatic) |
1319
+ | Gamepad button debouncing | `StatefulGamepad` — `getButtonDown()` / `getButtonUp()` |
1320
+ | Manual GPU cleanup with traverse | `entity.dispose()` — destroys entity + cleans up geometry/materials/textures |
1321
+ | Manual world-space positioning | `setWorldPosition()` / `setWorldQuaternion()` utilities |
1322
+ | Manual XR hit-test setup | `EnvironmentRaycastTarget` component + `EnvironmentRaycastSystem` |
1323
+ | Manual camera video feed | `CameraSource` component + `CameraUtils` static class |
1316
1324
 
1317
1325
  ### Asset Loading (AssetManager)
1318
1326
 
@@ -1404,17 +1412,17 @@ const hud = world.createTransformEntity(hudMesh, {
1404
1412
 
1405
1413
  ### Input & Interaction
1406
1414
 
1407
- **Interactable → Hovered/Pressed flow:**
1415
+ **RayInteractable → Hovered/Pressed flow:**
1408
1416
 
1409
- 1. Add `Interactable` component to any entity that should respond to pointer input
1417
+ 1. Add `RayInteractable` component to any entity that should respond to pointer input
1410
1418
  2. `InputSystem` automatically performs BVH-accelerated raycasting each frame
1411
- 3. When a ray hits an Interactable entity, `Hovered` tag is added
1419
+ 3. When a ray hits a RayInteractable entity, `Hovered` tag is added
1412
1420
  4. When the user presses the select button while hovering, `Pressed` tag is added
1413
1421
  5. Query for `Hovered`/`Pressed` in your system to react to interactions
1414
1422
 
1415
1423
  ```typescript
1416
1424
  // Setup
1417
- entity.addComponent(Interactable);
1425
+ entity.addComponent(RayInteractable);
1418
1426
 
1419
1427
  // In your system — react to interactions
1420
1428
  export class MyInteractionSystem extends createSystem({
@@ -1463,7 +1471,7 @@ These visuals are automatically created and managed by IWSDK systems:
1463
1471
  10. **DON'T** confuse PhysicsBody (motion) with PhysicsShape (collision + material)
1464
1472
  11. **DON'T** use raw `GLTFLoader`/`TextureLoader` — use `AssetManager` for caching, DRACO/KTX2 setup
1465
1473
  12. **DON'T** use `scene.add()` — use `createTransformEntity()` for proper ECS integration
1466
- 13. **DON'T** use `new Raycaster()` — use `Interactable` component for BVH-accelerated XR interaction
1474
+ 13. **DON'T** replace IWSDK pointer interaction with `new Raycaster()` — use `RayInteractable`; raw raycasters are valid for custom geometric queries, but the caller owns ECS entity mapping, target filtering, and pointer lifecycle
1467
1475
  14. **DON'T** add environment components (`DomeGradient`/`IBLTexture`/etc.) to arbitrary entities — must go on the level root (`world.activeLevel.value`)
1468
1476
  15. **DON'T** forget `_needsUpdate` after changing environment properties — changes are silently ignored without `entity.setValue(DomeGradient, '_needsUpdate', true)`
1469
1477
  16. **DON'T** use `entity.destroy()` for objects with GPU resources — use `entity.dispose()` which also cleans up geometry/materials/textures
@@ -1491,4 +1499,4 @@ These visuals are automatically created and managed by IWSDK systems:
1491
1499
  8. **VR vs AR** - Does this work differently in each mode?
1492
1500
  9. **Input handling** - What controller/hand inputs are needed?
1493
1501
  10. **Audio feedback** - What sounds should play on interactions?
1494
- 11. **Select 3D assets** - What models are needed? (see the Asset Strategy section in `build-milestones.md`)
1502
+ 11. **Select 3D assets** - What models are needed, and what are their licensing, provenance, and performance constraints?
@@ -0,0 +1,239 @@
1
+ # Iterate path
2
+
3
+ Make the requested delta to the established app without reopening its product
4
+ definition. The existing working experience is the baseline and the requested
5
+ change is the scope boundary.
6
+
7
+ ## Fast opening
8
+
9
+ To keep a bounded edit from turning into rediscovery, begin in this order:
10
+
11
+ 1. Run the bounded source/scene/UI Bash command below.
12
+ 2. Make a Write/Edit under `src/` or `public/` based only on that bundle. A
13
+ small safe skeleton such as the requested component or UI asset is enough;
14
+ finish it after typecheck if an API detail remains uncertain.
15
+
16
+ When the request names a state or component, prefer writing that exact
17
+ createComponent skeleton as the opening edit. Scene and UI schema details need
18
+ not block a safe scalar-state skeleton; let the first typecheck surface a real
19
+ API question. Do not reread root guidance or enumerate rule, skill, dependency,
20
+ or node_modules trees before the edit. If the harness did not automatically
21
+ load an applicable path-scoped instruction, include only that one instruction
22
+ in the bounded opening bundle. Preserve any authored view already present.
23
+
24
+ Do not insert unrelated discovery, CLI help, another skill, or broad reference
25
+ lookup between the bounded inspection and the first edit.
26
+
27
+ ## Operating contract
28
+
29
+ - Do not create an experience brief, product plan, architecture document,
30
+ retrospective, or review artifact unless the user explicitly requests it.
31
+ - Preserve existing scene anchors, interactions, state, UI, visual language,
32
+ and behavior outside the requested delta. Do not replace the app with a new
33
+ concept or rebuild working systems for stylistic consistency.
34
+ - Inspect the smallest source/scene/UI bundle that establishes the affected
35
+ path and its immediate dependencies in one bounded shell call, then make the
36
+ mandatory opening edit before any additional discovery.
37
+ - Record the acceptance contract mentally or in the active response: requested
38
+ behavior, preserved behavior, observable state, and visual consequence. Do
39
+ not write a process document.
40
+ - Reuse the app's existing component, system, asset, naming, and UI patterns.
41
+ Introduce a new abstraction only when the requested change cannot fit the
42
+ current structure cleanly.
43
+ - Treat preserved ScreenSpace UI as occupying its authored transform in
44
+ immersive mode even when its browser presentation differs. Reuse established
45
+ panel scale and spacing. For the stock scaffold layout, a new front-facing
46
+ panel in the same horizontal band should start at 0.25-0.32 scale, at least
47
+ 0.75 world meters above the preserved panel center, and at the same or greater
48
+ depth. Keep that separation during corrections; move laterally into clear
49
+ space rather than lowering it into the object interaction band.
50
+ - Invoke `iwsdk-build-model` before materially changing a model and
51
+ `iwsdk-compose-scene` before changing scene placement, lighting, environment,
52
+ or cameras. Invoke other matching specialists only after a concrete uncertainty
53
+ or the first failed required interaction. After that first failure, do not sweep
54
+ coordinates, read screenshots for interaction debugging, or inspect pointer,
55
+ input, grab, ray, or UIKit internals in `node_modules`; use the specialist and
56
+ measured ECS/UI state.
57
+ - Before the first typecheck, do not read specialist references or inspect
58
+ `node_modules`. Import IWSDK ECS, UIKit, interaction, material, and Three.js
59
+ re-exports from `@iwsdk/core`; use
60
+ `createComponent('Name', {field: {type: Types.Int8, default: 0}})` directly.
61
+ Let `npm run --if-present typecheck` produce the exact remaining API question.
62
+
63
+ Use this opening command shape directly, tolerating missing paths and keeping
64
+ the output bounded. The existing scaffold rules are already in context:
65
+
66
+ ```bash
67
+ {
68
+ for f in iwsdk.config.json package.json \
69
+ $(find src -maxdepth 2 -type f \
70
+ \( -name '*.ts' -o -name '*.tsx' \) 2>/dev/null | sort) \
71
+ $(find public/ui -maxdepth 2 -type f \
72
+ \( -name '*.uikitml' -o -name '*.json' \) 2>/dev/null | sort) \
73
+ $(find public/scenes -maxdepth 2 -type f \
74
+ -name '*.json' 2>/dev/null | sort); do
75
+ if [ -f "$f" ]; then
76
+ echo "=== $f ==="
77
+ sed -n '1,220p' "$f"
78
+ fi
79
+ done
80
+ } | head -c 32000
81
+ ```
82
+
83
+ ## Implementation loop
84
+
85
+ 1. Inspect the affected files plus the active scene and UI in one bounded call.
86
+ 2. Identify the current behavior that must remain unchanged.
87
+ 3. Implement the smallest complete vertical delta, including state/UI feedback
88
+ and recovery when the request needs them.
89
+ 4. Run one batched typecheck and fix errors together.
90
+ 5. Start the managed runtime directly with
91
+ `npx @iwsdk/cli dev up --headless --timeout 45000`.
92
+ 6. Exercise the changed path with real user input and query only the named state
93
+ needed to prove it. Direct ECS mutation may prepare/reset a scenario but is
94
+ not interaction proof.
95
+ 7. Run one focused regression smoke for the preserved behavior most likely to
96
+ have been affected.
97
+ 8. Run the production build and stop.
98
+
99
+ Use the known CLI surface without help discovery: `xr status|enter|look-at|select`,
100
+ `ecs find|query`, `browser screenshot`, and `scene render-file`. These call
101
+ shapes are authoritative; substitute the requested target, entity index, and
102
+ artifact name instead of running family-level or subcommand `--help`:
103
+
104
+ ```bash
105
+ npx @iwsdk/cli xr enter --input-json '{}'
106
+ npx @iwsdk/cli xr look-at --input-json '{"device":"controller-right","target":{"x":0,"y":1.5,"z":-2}}'
107
+ npx @iwsdk/cli xr select --input-json '{"device":"controller-right","duration":0.2}'
108
+ npx @iwsdk/cli ecs find --input-json '{"namePattern":"Requested Name","limit":10}'
109
+ npx @iwsdk/cli ecs query --input-json '{"entityIndex":1,"components":["RequestedState"]}'
110
+ npx @iwsdk/cli browser screenshot --input-json '{}' --output-file artifacts/final.png
111
+ npx @iwsdk/cli scene render-file --input-json '{"path":"public/scenes/main.iwsdk.scene.json","viewId":"hero","width":800,"height":800}' --output-file artifacts/hero.png
112
+ ```
113
+
114
+ After `dev up`, target at most 32 Bash calls for all interaction and visual
115
+ verification. Batch each look-at, input, and state query into one shell call.
116
+ Run the full end-to-end sequence once; after a measured failure, patch the
117
+ cause and rerun only the affected path.
118
+
119
+ ## Efficiency budget
120
+
121
+ Treat 90 total tool calls, 36 shell calls after dev startup, two image
122
+ previews, two runtime restarts, and two authored-scene renders as default upper
123
+ bounds for a bounded edit. Avoid CLI help calls when the known command shapes
124
+ below apply. These guardrails prevent verification from becoming open-ended;
125
+ they do not justify omitting required acceptance evidence.
126
+
127
+ At roughly 70 tool calls, drop optional diagnostics and finish only missing
128
+ evidence. At 80, freeze optional polish, save required artifacts once, run the
129
+ production build, and close the task.
130
+
131
+ For
132
+ `DistanceGrabbable`, hold/release gamepad button index `0`; for proximity
133
+ `OneHandGrabbable`/`TwoHandsGrabbable`, use squeeze button index `1`.
134
+ The focused distance-grab smoke is not another `xr select`: aim at the preserved
135
+ object, run
136
+ `npx @iwsdk/cli xr set-gamepad-state --input-json '{"device":"controller-right","buttons":[{"index":0,"value":1}]}'`,
137
+ observe `Grabbed` or movement, then repeat with `value:0` to release.
138
+
139
+ If a scene/source/UI edit happens after the managed runtime started and live
140
+ state becomes stale, do not call `scene open`, repeatedly poll `dev status`, or
141
+ loop on browser reload. Run one
142
+ `npx @iwsdk/cli dev restart --headless --timeout 60000`, then resume the named-state
143
+ check. One failed restart may be diagnosed once; do not enter a recovery loop.
144
+
145
+ Do not perform a full product replay when the edit affects one bounded path.
146
+ Expand verification only when a measured failure shows broader impact.
147
+
148
+ ## Visual comparison
149
+
150
+ Use the supplied pre-edit baseline when present. Pixel reads have a hard ceiling
151
+ of two: one bounded baseline or final comparison and one replacement after a
152
+ focused correction. Never read aim, hover, panel, coordinate, or duplicate debug
153
+ screenshots. Debug interactions with state, not pixels.
154
+
155
+ Never load a full-resolution PNG into model context. Preserve deliverable
156
+ images unchanged, but create a temporary JPEG preview no wider than 600 pixels
157
+ at about 70% quality with an image tool already available in the environment.
158
+ Do not install a dependency only to resize evidence, and delete the temporary
159
+ preview after the visual decision.
160
+
161
+ Do not use repeated `scene render-file` calls to discover framing. When an
162
+ authored hero view must be checked, run it once and read
163
+ `data.result.renderStats.visibleNodeIds`; make at most one focused camera or
164
+ composition correction from that result. The second render is the final hero
165
+ attempt even if it fails; do not issue a third `scene render-file` call.
166
+
167
+ Do not reconcile hero and default-player framing with trigonometry, coordinate
168
+ sweeps, repeated screenshots, or browser logs. Keep the panel identity-rotated
169
+ for the player. If the one hero check misses it, move only the existing hero
170
+ camera to the same side of the panel as the default player, check once more,
171
+ and freeze. Inspect browser logs at most once and only after a command returns
172
+ an explicit runtime error; never create a log-debugging loop.
173
+
174
+ Preserve the existing composition and visual language unless the request asks
175
+ to change them. When it does, compare the same viewpoint before and after and
176
+ make one focused correction for clipping, legibility, contrast, or hierarchy.
177
+ When adding a new primary spatial panel, it must be readable at the default
178
+ runtime viewpoint rather than a tiny accessory: keep its visible bounds at
179
+ least roughly 12% of frame width and 8% of frame height, but normally below 70%
180
+ of frame width and 40% of frame height, while staying fully inside the frame.
181
+ It must not cover the preserved product primary object, existing primary UI,
182
+ or focused regression object. Readability alone is insufficient: visible
183
+ bounds must not touch or overlap. Leave roughly 3% of the frame as clear
184
+ separation. If the first preview shows contact, move the new panel into the
185
+ largest empty region above or beside the preserved composition.
186
+
187
+ Use an opaque or strongly contrasting panel surface. Primary copy must be dark
188
+ on light or light on dark; white or pale text on translucent white, sky, or
189
+ another bright background fails even when the glyphs are technically present.
190
+ For the scaffold's Horizon `<Panel>`, assume the kit's opaque white surface
191
+ wins over a custom root `background-color`; use dark primary and secondary text
192
+ on the first attempt. Use light text only after a compact runtime preview proves
193
+ the actual rendered panel surface is dark. Do not spend a restart discovering
194
+ white-on-white text that the stock kit behavior already predicts.
195
+
196
+ Reuse the established app panel scale and spacing when available. In the stock
197
+ starter-scale composition, a new front-facing UIKitML panel should begin at
198
+ 0.25-0.32 scale. If it shares the central horizontal band, place its center at
199
+ least 0.75 world meters above the preserved panel and at the same or greater
200
+ depth; side-by-side placement needs a clear gap beyond both half-widths. Keep
201
+ that separation through the one allowed correction.
202
+
203
+ On the first final preview, inspect the whole change together: new UI is fully
204
+ inside the frame; a visible gap separates it from existing primary UI and
205
+ objects; important copy and controls remain readable at preview size; and text
206
+ has strong contrast against its actual rendered surface. Batch one correction
207
+ for all failures, then take the second and final preview.
208
+
209
+ Keep primary added UI away from fragile frame edges unless the established
210
+ composition reserves a stable edge region. XR captures may use a square or
211
+ otherwise narrower aspect ratio than the browser. Prefer an above-central
212
+ placement over pushing a panel to the side, and retain a generous lateral
213
+ margin before accepting the final preview.
214
+
215
+ Progress and completion evidence must remain distinguishable at the compact
216
+ 600-pixel preview scale. Do not rely on changing only one short status sentence.
217
+ Use one coarse, deliberate milestone change such as a large status chip or bar,
218
+ clearly marked step indicators, or a strong color/state change on both the
219
+ panel and the affected object. The changed treatment should occupy a visible
220
+ region of the panel and make completion obvious without reading fine print.
221
+
222
+ For a front-facing UIKitML panel in the stock starter layout, keep rotationDeg
223
+ absent unless the existing app establishes another convention. Do not calculate
224
+ a look-at yaw solely to face the default player: the stock panel front is
225
+ face-on at identity. Judge the final result from a fresh default runtime
226
+ viewpoint, without custom headset repositioning before capture.
227
+
228
+ For XR work, keep the immersive session active through the final browser
229
+ screenshot. Immediately before capture, check XR status and enter once if the
230
+ session is inactive. A non-immersive browser camera is not placement evidence
231
+ for world-space UI; return to the default immersive viewpoint instead of moving
232
+ correctly placed content to satisfy the unrelated browser view.
233
+
234
+ ## Stop rule
235
+
236
+ Stop when the requested delta works through real input, the named state/UI
237
+ evidence passes, the focused preserved-path smoke passes, the production build
238
+ passes, and required evidence files exist. Do not reopen unrelated polish or
239
+ review after those gates pass.