@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,70 @@
1
+ ---
2
+ name: iwsdk-ray
3
+ description: Verify ray clicks, UIKit selections, and DistanceGrabbable interactions with emulated XR controllers. Use for pointing, selecting, pressing spatial UI, or moving an object through a distance grab.
4
+ argument-hint: '(use the current request)'
5
+ ---
6
+
7
+ # IWSDK Ray Interaction
8
+
9
+ Choose one interaction branch from measured target components. Ray clicks and
10
+ distance grabs share aiming but not input duration or movement behavior.
11
+
12
+ ## Locate and aim once
13
+
14
+ 1. Check XR session state and enter only when inactive.
15
+ 2. Find the named entity or runtime-named UIKit control, then query its
16
+ components and transform. For UIKit, prefer the live name assigned through
17
+ `requireElementById`; use a project test hook only when no addressable runtime
18
+ target exists.
19
+ 3. Aim the requested controller with `xr look-at`. Do not translate the
20
+ controller toward a ray target. The transform of an open shape (a ring, a
21
+ knot) can sit in empty space: aim at its surface, such as the rim at
22
+ transform + (0, radius, 0), and confirm `Hovered` before pressing.
23
+
24
+ ## Select exactly one branch
25
+
26
+ ### Click or UIKit button
27
+
28
+ For `RayInteractable`, `Pressed`, or a UIKit control, use one normal select:
29
+
30
+ ```bash
31
+ npx @iwsdk/cli xr select --input-json '{"device":"controller-right","duration":0.2}'
32
+ ```
33
+
34
+ Use an explicit select-value press/release only when the task needs to inspect
35
+ the held interval. Query the named application state or control effect after the
36
+ click; a screenshot alone is not interaction proof.
37
+
38
+ ### Distance grab
39
+
40
+ For `DistanceGrabbable`, hold trigger button index `0`, optionally move the
41
+ controller, then release index `0`:
42
+
43
+ ```json
44
+ {"device":"controller-right","buttons":[{"index":0,"value":1}]}
45
+ ```
46
+
47
+ Check `movementMode` before deciding whether the object should remain remote or
48
+ move toward the hand. Query `Grabbed` or transform state while held and after
49
+ release. Do not substitute squeeze index `1`; that is the proximity-grab path.
50
+
51
+ For `MoveFromTarget`, do not inspect implementation source. Before pressing,
52
+ record controller position `P` and object position `S`, and compute the grab
53
+ distance `d = |S - P|`. While trigger is held, call `xr look-at` with the
54
+ requested object destination as `target` and `moveToDistance: d`; this preserves
55
+ the ray distance while moving its endpoint to the destination. Query the object
56
+ before release to confirm the move, then release and query again.
57
+
58
+ ## Evidence and stopping
59
+
60
+ For a task with both a click and a distance grab, locate/aim/click/query the first
61
+ target, then locate/aim/hold-move-release/query the second. Do not rediscover the
62
+ CLI family, inspect pointer internals, or guess panel offsets from screenshots.
63
+
64
+ Capture one runtime image only when visual placement is part of the request.
65
+ When the request names an artifact path, save it directly with
66
+ `npx @iwsdk/cli browser screenshot --output-file <path>`; do not capture into model
67
+ context and then add a copy step.
68
+ Stop when the real input and resulting named state are proven, leaving all
69
+ buttons released.
70
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=ec23dce5226ca91367042de7907fb3664c055a1ceb737fede2fd6710eab1f37f name=iwsdk-ray (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -0,0 +1,335 @@
1
+ ---
2
+ name: iwsdk-ui
3
+ description: Build or modify manifest-backed IWSDK UIKitML with bounded preview, placement, and runtime verification. Use for spatial panels, browser HUDs, UIKitML layout, fonts, editor previews, and runtime element behavior.
4
+ argument-hint: '(use the current request)'
5
+ ---
6
+
7
+ # IWSDK UI
8
+
9
+ Deliver the requested UI as one verified vertical slice. Use the current request
10
+ from conversation context; do not ask the user to repeat it or create a separate
11
+ design document.
12
+
13
+ ## Choose the required surface
14
+
15
+ Before editing, classify the request:
16
+
17
+ - **UIKitML only**: document layout, styling, fonts, or reusable controls;
18
+ - **spatial panel**: UIKitML plus manifest registration and a scene instance;
19
+ - **runtime UI**: either of the above plus element lookup, events, and state;
20
+ - **ScreenSpace HUD**: browser-camera UI that intentionally returns to its
21
+ authored world transform in immersive XR.
22
+
23
+ Do not add placement, ScreenSpace, runtime state, or camera changes when the
24
+ request does not require them.
25
+
26
+ ## Fast path
27
+
28
+ Inspect the relevant UI, asset manifest, active scene, and direct runtime caller
29
+ with one shell command that prints those files; do not issue a separate Read
30
+ tool call for every file. Then make the first coherent edit before broad
31
+ reference or dependency discovery. Use focused IWSDK reference queries only for
32
+ a concrete unsupported element, property, or runtime API question. Do not open,
33
+ grep, or list `node_modules` at any point in this workflow.
34
+
35
+ Strict image budget: during implementation, do not open any PNG, JPEG, or WebP
36
+ with the Read tool. Finish the runtime checks first. At the final visual gate,
37
+ create and open exactly one compact `artifacts/ui-runtime-review.jpg` contact
38
+ sheet as described below.
39
+
40
+ Keep the three stable identities explicit:
41
+
42
+ 1. manifest asset ID;
43
+ 2. scene node ID for a placed instance;
44
+ 3. UIKitML element IDs used by application code.
45
+
46
+ Register each file under `public/ui/` as `AssetType.UIKitML` in the configured
47
+ asset manifest. UIKitML is the source of truth; do not generate an intermediate
48
+ JSON representation.
49
+
50
+ ## Author the complete first pass
51
+
52
+ - UIKit numeric dimensions are centimeters (`100` is one meter).
53
+ - Use stable `id` attributes for every element code must address.
54
+ - Prefer supported explicit properties over CSS shorthand.
55
+ - Reuse the configured Horizon kit and bundled Lucide icons instead of
56
+ registering replacements in application code.
57
+ - Production builds keep only the Lucide icons named in static
58
+ `public/**/*.uikitml` files. UIKitML built or fetched at runtime (a string in
59
+ `src/`, a file outside `public/`, a remote URL) works in `npm run dev` but
60
+ fails after `npm run build` with `Unknown component <Settings>` and a hint.
61
+ List those icons by component name in `vite.config.ts`:
62
+ `iwsdkDev({ bundle: { icons: ['Settings'] } })` (`'all'` keeps all ~1,600,
63
+ about 4 MB more). Check dynamic UIKitML in a production build.
64
+ - In the stock Horizon kit, `<Panel>` renders an opaque surface that follows
65
+ the color scheme: dark at runtime when `spatialUI.preferredColorScheme` is
66
+ `dark` (the scaffold default), white in editor previews. Give text a dark
67
+ color plus a light `:dark` variant, as `public/ui/welcome.uikitml` does.
68
+ - Remote fonts can reflow layout. Use a local font when offline availability is
69
+ a product requirement.
70
+ - Use plain ASCII punctuation in runtime status copy. Do not use em dashes,
71
+ smart quotes, or other typographic punctuation unless the chosen local font
72
+ has already rendered that exact glyph successfully.
73
+
74
+ For a scene-authored instance, use asset content and an explicit transform. In
75
+ the stock starter composition, a front-facing UIKitML panel at negative Z faces
76
+ the default player with identity rotation. Do not add `rotationDeg: [0, 180, 0]`
77
+ unless the existing app establishes that convention or a measured render proves
78
+ it necessary.
79
+
80
+ The default XR player and an authored non-XR `hero` camera can be on opposite
81
+ sides of a single-sided panel. Preserve the transform required by the requested
82
+ player viewpoint; if an authored evidence camera sees the back face, move or aim
83
+ that camera instead of rotating the product UI away from the player.
84
+
85
+ When adding UI to an established composition, preserve existing primary UI and
86
+ objects. Start from the app's scale and spacing. In the stock scaffold, use
87
+ roughly `0.25`-`0.32` scale for a secondary panel and keep a same-band panel at
88
+ least `0.75` world meters above the existing central panel, at the same or
89
+ greater depth. Prefer a centered safe region over fragile frame edges.
90
+
91
+ ## Connect runtime behavior
92
+
93
+ Resolve a scene-authored panel by scene node ID:
94
+
95
+ ```ts
96
+ const panel = world.requireSceneObject<UIKitMLAsset>('PanelNode');
97
+ const status = panel.requireElementById<UIKit.Text>('StatusText');
98
+ const action = panel.requireElementById('Btn_Action');
99
+ status.name = 'StatusText';
100
+ action.name = 'Btn_Action';
101
+ action.addEventListener('click', onAction);
102
+ cleanupFuncs.push(() => action.removeEventListener('click', onAction));
103
+ ```
104
+
105
+ Assign exact runtime names when the request requires controls to be addressable.
106
+ Register listener cleanup. Do not locate panels by transient ECS index, manifest
107
+ URL, or internal document implementation details.
108
+
109
+ For a small scene-authored state machine, use the public ECS surface directly;
110
+ do not inspect `node_modules` to rediscover these contracts:
111
+
112
+ ```ts
113
+ export const PanelState = createComponent('PanelState', {
114
+ step: { type: Types.Int8, default: 0 },
115
+ complete: { type: Types.Boolean, default: false },
116
+ });
117
+ export default defineComponents([PanelState]);
118
+
119
+ class PanelSystem extends createSystem({
120
+ panel: { required: [PanelState] },
121
+ activated: { required: [ActionMarker, Pressed] },
122
+ }) {
123
+ init(): void {
124
+ this.queries.activated.subscribe('qualify', () => this.advance());
125
+ }
126
+
127
+ private advance(): void {
128
+ const panel = this.queries.panel.entities.values().next().value;
129
+ if (panel == null) return;
130
+ // Read and write scalar fields with getValue/setValue, then update UIKit.
131
+ }
132
+ }
133
+ ```
134
+
135
+ Query result `entities` is a `Set`; use iteration or
136
+ `entities.values().next().value`, never array indexing. `@iwsdk/core` re-exports
137
+ the Three.js types needed for visual feedback, and scene-authored systems may use
138
+ `Pressed` qualification plus the existing app's marker component. Clone shared
139
+ asset materials before per-instance color or emissive changes.
140
+
141
+ Imported models can use material arrays or emissive-capable material subclasses
142
+ that do not satisfy a narrow `instanceof MeshStandardMaterial` check. For an
143
+ explicit whole-body state tint, traverse every `Mesh`, normalize its material to
144
+ an array, clone each material with `emissive` and `emissiveIntensity`, assign the
145
+ clones back, and update all of them. If an existing `emissiveMap` masks the
146
+ requested solid diagnostic color, clear that map on the clones and set
147
+ `needsUpdate`; do not alter shared source materials.
148
+
149
+ ```ts
150
+ object3D.traverse((child) => {
151
+ if (!(child instanceof Mesh)) return;
152
+ const source = Array.isArray(child.material) ? child.material : [child.material];
153
+ const clones = source.map((material) => material.clone());
154
+ child.material = Array.isArray(child.material) ? clones : clones[0];
155
+ for (const material of clones) {
156
+ if ('emissive' in material && 'emissiveIntensity' in material) {
157
+ const stateMaterial = material as MeshStandardMaterial;
158
+ stateMaterial.emissiveMap = null;
159
+ stateMaterial.needsUpdate = true;
160
+ stateMaterials.push(stateMaterial);
161
+ }
162
+ }
163
+ });
164
+ ```
165
+
166
+ These are known public top-level exports: `createComponent`, `createSystem`,
167
+ `defineComponents`, `Types`, `Entity`, `Pressed`, `UIKitMLAsset`, `UIKit`,
168
+ `Color`, `Mesh`, `MeshStandardMaterial`, and `Object3D`. Import them directly
169
+ from `@iwsdk/core`. Typecheck the implementation; if an import fails, use the
170
+ compiler error or one focused IWSDK reference query. Do not inspect package
171
+ source, declarations, exports, or directories to reconfirm the export chain.
172
+
173
+ For immersive XR, default to a world-space panel or attach contextual UI to the
174
+ object it controls. Use a thresholded `Follower` targeting `world.player.head`
175
+ only when compact global UI must remain discoverable. Do not head-lock menus,
176
+ reading surfaces, or persistent panels; reserve direct `world.playerHeadEntity`
177
+ parenting for tiny, transient, non-interactive markers that require exact view
178
+ alignment. Do not use `ScreenSpace` expecting it to remain camera-attached in
179
+ XR. See https://iwsdk.dev/concepts/spatial-ui/hud.html for the placement
180
+ guidance.
181
+
182
+ Use `ScreenSpace` only for a real HUD requirement. Its dimensions and offsets are
183
+ CSS strings. Preserve the authored immersive transform and verify browser and XR
184
+ views independently when both modes matter.
185
+
186
+ ## Verify with a bounded loop
187
+
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` 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
+ session, start a second browser, or build a custom UIKit renderer.
192
+
193
+ 1. Run `npx @iwsdk/cli ui assets --raw` once to confirm registration.
194
+ 2. Render one isolated preview after the first complete layout:
195
+
196
+ ```bash
197
+ npx @iwsdk/cli ui render-preview \
198
+ --input-json '{"assetId":"panel-id","width":800,"height":600}' \
199
+ --output-file artifacts/panel-preview.png
200
+ ```
201
+
202
+ Always provide `--output-file`; do not accept a temporary screenshot path
203
+ and add a separate copy step.
204
+
205
+ 3. If spatial placement matters, render the authored hero view once; use
206
+ `view` only for built-in presets:
207
+
208
+ ```bash
209
+ npx @iwsdk/cli scene render-file \
210
+ --input-json '{"path":"public/scenes/main.iwsdk.scene.json","viewId":"hero"}' \
211
+ --output-file artifacts/scene-hero.png
212
+ ```
213
+
214
+ Keep the full render result from this call so `visibleNodeIds`, validity,
215
+ framing, and the PNG are checked together. Do not pipe it through
216
+ `head`/`tail`/`grep` and rerun only to recover discarded metadata.
217
+
218
+ 4. Find the panel entity, then inspect its live UIKitML state before and after
219
+ exercising each required control through real pointer or XR input:
220
+
221
+ ```bash
222
+ npx @iwsdk/cli ecs find --input-json '{"namePattern":"^Welcome Panel$"}'
223
+ npx @iwsdk/cli ui inspect --input-json '{"entityIndex":12,"selector":"#Btn_Action"}'
224
+ ```
225
+
226
+ Replace the example pattern with the panel's authored scene/entity name, and
227
+ reuse the returned entity index rather than hard-coding the example value.
228
+
229
+ 5. Capture one final runtime preview from the intended viewpoint. Reuse a
230
+ required completion-state capture when it already provides that evidence.
231
+
232
+ For common CLI verification, use these forms directly rather than discovery:
233
+
234
+ ```bash
235
+ npx @iwsdk/cli xr status
236
+ npx @iwsdk/cli xr enter --input-json '{}'
237
+ npx @iwsdk/cli xr look-at --input-json '{"device":"controller-right","target":{"x":0,"y":1.5,"z":-2}}'
238
+ npx @iwsdk/cli xr select --input-json '{"device":"controller-right","duration":0.2}'
239
+ npx @iwsdk/cli ecs find --input-json '{"withComponents":["ComponentName"]}'
240
+ npx @iwsdk/cli ecs query --input-json '{"entityIndex":12}'
241
+ npx @iwsdk/cli ui inspect --input-json '{"entityIndex":12,"selector":"#Btn_Action"}'
242
+ npx @iwsdk/cli browser logs --input-json '{"count":30}'
243
+ npx @iwsdk/cli browser reload --input-json '{}'
244
+ ```
245
+
246
+ For a file capture, use `npx @iwsdk/cli browser screenshot --output-file <path>`;
247
+ `browser_screenshot` does not accept an `outputPath` input field.
248
+
249
+ When a UI change requires a regression smoke for an existing
250
+ `DistanceGrabbable`, do not substitute a long `xr select` click. Aim at the
251
+ object, hold select with
252
+ `npx @iwsdk/cli xr set-select-value --input-json '{"device":"controller-right","value":1}'`,
253
+ query the entity while held to observe `Grabbed`, then release with the same
254
+ command and `"value":0`. Movement is unnecessary unless the request asks for
255
+ it.
256
+
257
+ When the request asks for a poke (near touch) on a control, press it with the
258
+ emulated hand's index fingertip by its element ID. The panel entity needs
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:
262
+
263
+ ```bash
264
+ npx @iwsdk/cli xr set-input-mode --input-json '{"mode":"hand"}'
265
+ npx @iwsdk/cli xr run-sequence --input-json '{"device":"hand-right","steps":[{"target":"Btn_Action","press":{}}]}' --timeout 45000
266
+ ```
267
+
268
+ A press result reports contact, not a click: a `presses[0].contactMs` of 800 or
269
+ less does not prove the control clicked, because the fingertip can touch the
270
+ panel or a neighbouring control instead. Verify the click by the state it
271
+ changes, with `ui inspect` on the control or a query of the app state it
272
+ drives, and press once more if nothing changed. A contact of more than 800 ms
273
+ never clicks. A slow headless frame can hold the touch that long. So can a
274
+ press on a control out of reach: the body walks to it during the press (a
275
+ contact of seconds). Walk to such a control in a step of its own before the
276
+ press:
277
+ `"steps":[{"body":{"stepTo":"Btn_Action"}},{"target":"Btn_Action","press":{}}]`.
278
+ `xr list-targets` lists the element IDs that can be pressed.
279
+
280
+ The commands in this section are the supported path. Do not call broad
281
+ `iwsdk`, `ui`, `browser`, `ecs`, or `xr` help. If a shown command fails, use its
282
+ error output and the exact forms above to correct it instead of invoking
283
+ `--help`.
284
+
285
+ Batch layout fixes before rerendering. By default allow one isolated preview,
286
+ one authored-scene render, and one final runtime capture; add one replacement
287
+ preview only to verify a focused correction. Do not rerender after every small
288
+ edit, repeatedly restart the runtime, or use screenshots to debug input state.
289
+ Keep the whole task under roughly 80 tool calls by batching independent reads
290
+ and related state queries. Check console logs once after final behavior unless a
291
+ new edit creates a concrete reason to check again. Do not capture extra
292
+ diagnostic screenshots for states already proven by named queries.
293
+ For the final visual comparison, create one compact JPEG contact sheet with the
294
+ supplied baseline above the final live-runtime capture, then load only that one
295
+ image into model context. Do not load the full-size PNGs separately. On Windows,
296
+ substitute the two paths in this known command:
297
+
298
+ ```powershell
299
+ powershell.exe -NoProfile -Command 'Add-Type -AssemblyName System.Drawing; $a=[Drawing.Image]::FromFile((Resolve-Path "BASELINE.png")); $b=[Drawing.Image]::FromFile((Resolve-Path "FINAL.png")); $w=600; $ha=[int]($a.Height*$w/$a.Width); $hb=[int]($b.Height*$w/$b.Width); $o=[Drawing.Bitmap]::new($w,$ha+$hb); $g=[Drawing.Graphics]::FromImage($o); $g.DrawImage($a,0,0,$w,$ha); $g.DrawImage($b,0,$ha,$w,$hb); $o.Save((Join-Path (Get-Location) "artifacts/ui-runtime-review.jpg"),[Drawing.Imaging.ImageFormat]::Jpeg); $g.Dispose(); $o.Dispose(); $a.Dispose(); $b.Dispose()'
300
+ ```
301
+
302
+ `artifacts/ui-runtime-review.jpg` is the only image file to open with the Read
303
+ tool. Do not open isolated previews, hero renders, progress captures, completion
304
+ captures, the baseline PNG, or the final PNG separately.
305
+
306
+ Treat that contact sheet as a bounded layout sanity check, not a request to
307
+ visually prove every state detail. If it shows no blocking overlap, clipping,
308
+ unreadable primary UI, or accidental scene replacement, stop visual inspection.
309
+ Do not create follow-up zooms, crops, or object close-ups. Use the named ECS
310
+ state queries to prove interaction feedback; the evaluator will inspect the
311
+ saved progress and completion artifacts.
312
+
313
+ Render isolated, hero, progress, completion, and invalid-action files when the
314
+ task requires them, but do not open those files in model context; use render
315
+ metadata, named state queries, and file existence for those checks. After a
316
+ context compaction, continue from the measured state instead of rediscovering
317
+ package exports, CLI command families, or already accepted visual framing.
318
+
319
+ The final visual check must confirm:
320
+
321
+ - the complete panel is inside the expected frame;
322
+ - important text and controls remain readable at a compact preview size;
323
+ - primary text has clear contrast against the actual rendered surface;
324
+ - new UI does not touch or obscure existing primary UI or objects;
325
+ - required states differ through a coarse visible treatment, not only fine text.
326
+ When the task explicitly asks for visually distinct progress/completion or
327
+ success/error states, change at least a quarter of the panel surface (for
328
+ example a substantial header block or whole-surface tint) and/or a major
329
+ scene object's whole-body emissive treatment. A thin accent bar, small chips,
330
+ icons, and copy changes alone are not sufficient evidence.
331
+
332
+ Finish with a passing typecheck and production build, no UIKit parser/resource
333
+ errors, and concise runtime evidence. Remove temporary preview files or camera
334
+ workarounds that are not deliverables.
335
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=9b79caeeedded4cb53e69688c7e5006daa1187c951a333ef06cbdb3063f062a2 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.1 sha256=5ccb37dbe152b3611496740e89bc8e42c8d59dfed8be7512635d877924b79988 name=iwsdk-upgrade (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -0,0 +1,62 @@
1
+ ---
2
+ description: "Asset manifest contract"
3
+ globs:
4
+ - "src/assets.ts"
5
+ - "src/assets.js"
6
+ - "src/iwsdk/assets.ts"
7
+ - "src/iwsdk/assets.js"
8
+ - "src/scene-assets/**"
9
+ alwaysApply: false
10
+ ---
11
+
12
+ # Asset manifest contract
13
+
14
+ `src/assets.ts` is imported **independently by the app runtime and the editor**,
15
+ in separate JS realms. It must therefore be deterministic and self-contained:
16
+
17
+ - no `World`, scene, iframe, editor object or DOM access
18
+ - no timers, no fetching ambient state
19
+ - no reliance on singleton object identity across realms
20
+ - prototypes immutable after registration, and never parented
21
+
22
+ A manifest entry is either a URL descriptor (`{ url, type, name?, priority? }`)
23
+ or a bare parentless `Object3D`. `AssetType` covers `GLTF`, `Audio`, `Texture`,
24
+ `HDRTexture`, `UIKitML`. Only glTF, UIKitML and `Object3D` entries are placeable
25
+ as scene content; audio/texture/HDR are for application systems.
26
+
27
+ Build public URLs from `import.meta.env.BASE_URL` so runtime, editor and subpath
28
+ builds resolve identically. A file in `public/` is **not** available to a scene
29
+ until it is registered here.
30
+
31
+ ## Procedural assets
32
+
33
+ Export a parentless `Object3D` from `src/scene-assets/*.scene-asset.ts` and
34
+ register it under a stable ID. The registry rejects an already-parented
35
+ prototype.
36
+
37
+ Every placement is a distinct hierarchy clone, but **geometry and materials stay
38
+ shared**. Never dispose them from a placed clone; world teardown owns their
39
+ lifetime. Reassigning `mesh.material` on a clone is fine and is how you restyle
40
+ one instance — mutating the shared material in place changes every instance.
41
+
42
+ Bounds come from `Box3` over the instantiated asset and drive placement,
43
+ selection, framing and scatter collision. Put the origin where composition wants
44
+ it (usually floor contact, or the object's own pivot), keep transforms finite,
45
+ and don't let invisible helpers inflate bounds.
46
+
47
+ ## Cost
48
+
49
+ Split tessellation by viewing distance rather than using one budget everywhere: a
50
+ close-range hero model and coarser display copies of the same form are two
51
+ prototypes from one factory function. Sphere/lathe segment counts dominate small
52
+ repeated detail more than people expect — check `renderStats.triangles` rather
53
+ than guessing.
54
+
55
+ Reuse material instances within a module. Prefer prefabs plus a deterministic
56
+ pattern for repetition; a pattern whose prefab resolves to a single component-free
57
+ mesh lowers to one `InstancedMesh`.
58
+
59
+ Start assets at `castShadow: false` and opt in only for grounded focal masses.
60
+ Don't build contact-shadow blob cards or `ShadowMaterial` catcher planes here: put
61
+ `ContactShadow` or `ShadowCatcher` node components on the scene nodes instead.
62
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=e6b8d299d9f7590043801fae63d23de387e937bcb87bafe59b9b70f6e0622db3 name=assets-and-manifest.mdc (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -0,0 +1,105 @@
1
+ ---
2
+ description: "ECS API reference"
3
+ globs:
4
+ - "src/**/*.ts"
5
+ - "src/**/*.js"
6
+ alwaysApply: false
7
+ ---
8
+
9
+ # ECS API reference
10
+
11
+ ## Field types
12
+
13
+ ```
14
+ Types.Float32 Float64 Int8 Int16 Int32 Boolean String FilePath
15
+ Types.Vec2 Vec3 Vec4 Color(RGBA) Entity Enum
16
+ Types.Object // avoid — not optimised
17
+ ```
18
+
19
+ ## Component
20
+
21
+ Declare in a system-free module, then list it in `src/components.ts` via
22
+ `defineComponents()` or the editor cannot author it.
23
+
24
+ ```ts
25
+ export const MyComponent = createComponent('MyComponent', {
26
+ speed: { type: Types.Float32, default: 1 },
27
+ tint: { type: Types.Color, default: [1, 1, 1, 1] }, // RGBA
28
+ });
29
+ ```
30
+
31
+ Optional metadata per field — `label`, `step`, `min`, `max`, `enum`, `help`,
32
+ `widget` — drives the editor inspector.
33
+
34
+ ## System
35
+
36
+ ```ts
37
+ export class MySystem extends createSystem(
38
+ {
39
+ items: { required: [MyComponent] },
40
+ active: { required: [MyComponent], excluded: [Grabbed] },
41
+ },
42
+ { speed: { type: Types.Float32, default: 1 } }, // optional config
43
+ ) {
44
+ private temp!: Vector3;
45
+
46
+ init() {
47
+ this.temp = new Vector3();
48
+ this.queries.items.subscribe('qualify', (entity) => { /* matched */ });
49
+ this.cleanupFuncs.push(this.config.speed.subscribe((v) => { /* … */ }));
50
+ }
51
+
52
+ update(delta: number, time: number) {
53
+ for (const entity of this.queries.active.entities) { /* no allocations */ }
54
+ }
55
+ }
56
+ ```
57
+
58
+ Queries take `required`, `excluded` and `where` (value predicates via `eq`, `ne`,
59
+ `lt`, `le`, `gt`, `ge`, `isin`, `nin`). `excluded` is the clean way to skip
60
+ entities in a transient state — e.g. excluding `Grabbed` so a held object is left
61
+ alone.
62
+
63
+ Register explicitly in `src/index.ts` with `world.registerSystem(MySystem)`.
64
+
65
+ Read fields with `entity.getValue(Component, 'field')`. For vector fields use
66
+ `entity.getVectorView(Component, 'field')` — it returns a `Float32Array` view with
67
+ no allocation, and `setValue` **throws** on vector fields in elics 3.4.x.
68
+
69
+ ## Interaction components
70
+
71
+ `RayInteractable` plus `Hovered`/`Pressed` covers both mouse/touch canvas input
72
+ and XR rays. Grab components: `OneHandGrabbable` and `TwoHandsGrabbable` are
73
+ proximity-based and respond to **squeeze**, while `DistanceGrabbable` is
74
+ ray-based and responds to **trigger**. `Grabbed` is a transient tag managed by
75
+ `GrabSystem` — read it, never add or remove it. `GrabSystem.useHandPinchForGrab`
76
+ defaults to **true**, so a hand pinch grabs; set it to `false` to require squeeze.
77
+
78
+ `DistanceGrabbable` fields: `movementMode` (`MoveTowardsTarget`, `MoveFromTarget`,
79
+ `MoveAtSource`, `RotateAtSource`), `returnToOrigin`, `moveSpeedFactor`,
80
+ `detachOnGrab`, `translate`, `rotate`, `scale`, `targetPositionOffset`,
81
+ `targetQuaternionOffset`. `returnToOrigin: true` gives spring-back on release with
82
+ no custom code.
83
+
84
+ For a held object use `GrabSystem`'s public methods — `forceRelease(entity)`,
85
+ `getHolderHand(entity)` — never deep-import `Handle`.
86
+
87
+ ## XR input
88
+
89
+ ```ts
90
+ const pad = this.input.xr.gamepads.right;
91
+ pad?.getButtonDown(InputComponent.Trigger); // just pressed
92
+ pad?.getAxesValues(InputComponent.Thumbstick);
93
+ this.player.head; this.player.raySpaces.left; this.player.gripSpaces.right;
94
+ ```
95
+
96
+ Prefer `world.input.actions` for reusable intent (`locomotion.move`) over raw
97
+ buttons. Browser controls live at `world.input.keyboard` and
98
+ `world.input.browserGamepads`.
99
+
100
+ ## Lifecycle
101
+
102
+ `world.visibilityState` reports `NonImmersive`, `Visible`, `VisibleBlurred` —
103
+ pause simulation on blur. `world.camera.position` is local to `world.player`; use
104
+ `getWorldPosition()` when logic needs the true viewer position.
105
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=f09a86b27ce781f8e69b6471051167bee392ac2f503526df33ded757940268f6 name=ecs-api.mdc (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->