@iwsdk/cli 1.1.0-rc.2 → 1.2.0-rc.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (142) hide show
  1. package/README.md +79 -2
  2. package/dist/agent-adapters.d.ts +12 -1
  3. package/dist/agent-adapters.d.ts.map +1 -1
  4. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +312 -0
  5. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  6. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  7. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +277 -0
  8. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  9. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
  10. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  11. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
  12. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  13. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
  14. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  15. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
  16. package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +74 -0
  17. package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
  18. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +46 -0
  19. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +1531 -0
  20. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +82 -0
  21. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +263 -0
  22. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/planner.md +307 -0
  23. package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +282 -0
  24. package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +75 -0
  25. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +178 -0
  26. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  27. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
  28. package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +262 -0
  29. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +106 -0
  30. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/component-reference.md +152 -0
  31. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
  32. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
  33. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
  34. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  35. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  36. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  37. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  38. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  39. package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +70 -0
  40. package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +328 -0
  41. package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
  42. package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +521 -0
  43. package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +60 -0
  44. package/dist/agent-guidance/files/.claude/rules/ecs-api.md +103 -0
  45. package/dist/agent-guidance/files/.claude/rules/scene-json.md +72 -0
  46. package/dist/agent-guidance/files/.claude/rules/uikitml.md +66 -0
  47. package/dist/agent-guidance/files/.claude/settings.json +29 -0
  48. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +312 -0
  49. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  50. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  51. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +277 -0
  52. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  53. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
  54. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  55. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
  56. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  57. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
  58. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  59. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
  60. package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +74 -0
  61. package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
  62. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +46 -0
  63. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +1531 -0
  64. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +82 -0
  65. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +263 -0
  66. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/planner.md +307 -0
  67. package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +282 -0
  68. package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +75 -0
  69. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +178 -0
  70. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  71. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
  72. package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +262 -0
  73. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +106 -0
  74. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/component-reference.md +152 -0
  75. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
  76. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
  77. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
  78. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  79. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  80. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  81. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  82. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  83. package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +70 -0
  84. package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +328 -0
  85. package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
  86. package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +62 -0
  87. package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +105 -0
  88. package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +74 -0
  89. package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +68 -0
  90. package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +55 -0
  91. package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +101 -0
  92. package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +71 -0
  93. package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +65 -0
  94. package/{guidance → dist/agent-guidance/files}/AGENTS.md +107 -27
  95. package/dist/agent-guidance/files/CLAUDE.md +3 -0
  96. package/dist/agent-guidance/files/public/scenes/AGENTS.md +72 -0
  97. package/dist/agent-guidance/files/public/ui/AGENTS.md +66 -0
  98. package/dist/agent-guidance/files/src/AGENTS.md +153 -0
  99. package/dist/agent-guidance/manifest.json +854 -0
  100. package/dist/agent-guidance.d.ts +113 -0
  101. package/dist/agent-guidance.d.ts.map +1 -0
  102. package/dist/agent-guidance.js +3403 -0
  103. package/dist/agent-guidance.js.map +1 -0
  104. package/dist/cli.js +2407 -144
  105. package/dist/cli.js.map +1 -1
  106. package/dist/commands/adapter.d.ts +1 -0
  107. package/dist/commands/adapter.d.ts.map +1 -1
  108. package/dist/commands/agents.d.ts +11 -0
  109. package/dist/commands/agents.d.ts.map +1 -0
  110. package/dist/commands/browser.d.ts +11 -0
  111. package/dist/commands/browser.d.ts.map +1 -1
  112. package/dist/commands/dev.d.ts +1 -0
  113. package/dist/commands/dev.d.ts.map +1 -1
  114. package/dist/commands/reference.d.ts +15 -1
  115. package/dist/commands/reference.d.ts.map +1 -1
  116. package/dist/commands/runtime.d.ts.map +1 -1
  117. package/dist/commands/upgrade.d.ts +51 -0
  118. package/dist/commands/upgrade.d.ts.map +1 -0
  119. package/dist/contract.js +32 -0
  120. package/dist/contract.js.map +1 -1
  121. package/dist/guidance-refresh.d.ts +33 -0
  122. package/dist/guidance-refresh.d.ts.map +1 -0
  123. package/dist/help.d.ts +2 -0
  124. package/dist/help.d.ts.map +1 -1
  125. package/dist/index.d.ts.map +1 -1
  126. package/dist/index.js +4744 -135
  127. package/dist/index.js.map +1 -1
  128. package/dist/mcp-stdio.d.ts.map +1 -1
  129. package/dist/migrations/iwsdk-migrate-0-5/SKILL.md +413 -0
  130. package/dist/migrations.d.ts +36 -0
  131. package/dist/migrations.d.ts.map +1 -0
  132. package/dist/package-manager.d.ts +28 -0
  133. package/dist/package-manager.d.ts.map +1 -0
  134. package/dist/release-notes.d.ts +28 -0
  135. package/dist/release-notes.d.ts.map +1 -0
  136. package/dist/release-notes.json +1374 -0
  137. package/dist/runtime-contract.d.ts +8 -0
  138. package/dist/runtime-contract.d.ts.map +1 -1
  139. package/dist/runtime-telemetry.d.ts +8 -1
  140. package/dist/runtime-telemetry.d.ts.map +1 -1
  141. package/dist/version.d.ts +1 -1
  142. package/package.json +9 -3
@@ -0,0 +1,521 @@
1
+ ---
2
+ name: iwsdk-project-code-reviewer
3
+ description: Reviews code in IWSDK projects (apps built with IWSDK) for correct framework usage, ECS patterns, performance, and best practices. Use when the user requests review or when a live or build failure remains unexplained after implementation.
4
+ tools: Read, Grep, Glob, Bash
5
+ model: sonnet
6
+ ---
7
+
8
+ You are a senior code reviewer specializing in IWSDK (Immersive Web SDK) applications. Your role is to ensure code correctly uses the IWSDK framework, follows ECS best practices, and avoids common pitfalls.
9
+
10
+ **Important:** This agent reviews **projects built with IWSDK** (applications), not the IWSDK framework source code itself. Focus on framework usage, not framework internals.
11
+
12
+ ## Review Process
13
+
14
+ When invoked:
15
+
16
+ 0. **Load the API ground truth** - Read `.claude/skills/iwsdk-dev/references/api-reference.md` (full IWSDK API patterns, enums, and anti-patterns) before reviewing.
17
+
18
+ 1. **Identify the project files** - Look for `src/` directory, `index.ts`/`index.js` entry point, system files, component files.
19
+
20
+ 2. **Check `iwsdk.config.json` and World bootstrap** - This is critical. Review
21
+ manifest feature flags and prerequisites, then verify `src/index.ts` passes
22
+ `virtual:iwsdk-project` to `World.create()`.
23
+
24
+ 3. **Review each system file** against the checklist below.
25
+
26
+ 4. **Check component definitions** for proper typing.
27
+
28
+ 5. **Report findings** organized by priority:
29
+ - **Critical** (will cause bugs/crashes)
30
+ - **Warning** (should fix)
31
+ - **Suggestion** (consider improving)
32
+
33
+ ---
34
+
35
+ ## Review Checklist
36
+
37
+ ### 1. Feature Configuration (CRITICAL)
38
+
39
+ **This is the #1 cause of bugs in IWSDK projects.**
40
+
41
+ Check `iwsdk.config.json` for feature misconfiguration:
42
+
43
+ ```jsonc
44
+ // ❌ CRITICAL BUG - Locomotion without collision geometry
45
+ { "world": { "features": { "locomotion": true } } }
46
+
47
+ // ✅ CORRECT - Locomotion with proper environment
48
+ // AND the scene has LocomotionEnvironment on its walkable surfaces.
49
+ { "world": { "features": { "locomotion": true } } }
50
+ ```
51
+
52
+ **What to check:**
53
+
54
+ - If `locomotion: true`, verify scene has `LocomotionEnvironment` component OR physics collision
55
+ - If `physics: true`, verify entities have `PhysicsBody` + `PhysicsShape` components
56
+ - If `grabbing: true`, verify entities have Grabbable components
57
+ - For AR (`world.xr.mode: "ar"`), ensure `locomotion: false`
58
+ - Features not used should be `false` to avoid overhead
59
+
60
+ ### 2. Systems: No Entity Arrays
61
+
62
+ Systems should NOT store entity arrays. Use queries instead.
63
+
64
+ ```typescript
65
+ // ❌ BAD - Storing entity references
66
+ class MySystem extends createSystem({...}) {
67
+ private myEntities: Entity[] = []; // DON'T DO THIS
68
+
69
+ init() {
70
+ this.queries.items.subscribe('qualify', (entity) => {
71
+ this.myEntities.push(entity); // BAD
72
+ });
73
+ }
74
+ }
75
+
76
+ // ✅ GOOD - Use queries
77
+ class MySystem extends createSystem({
78
+ items: { required: [MyComponent] }
79
+ }) {
80
+ update() {
81
+ for (const entity of this.queries.items.entities) {
82
+ // Query always has current entities
83
+ }
84
+ }
85
+ }
86
+ ```
87
+
88
+ ### 3. No Allocations in update()
89
+
90
+ Hot paths (`update()`) should not allocate memory.
91
+
92
+ ```typescript
93
+ // ❌ BAD - Allocates every frame
94
+ update() {
95
+ const tempVec = new Vector3(); // Creates garbage every frame
96
+ entity.object3D.getWorldPosition(tempVec);
97
+ }
98
+
99
+ // ✅ GOOD - Scratch variables in init() or as class properties
100
+ private tempVec!: Vector3;
101
+
102
+ init() {
103
+ this.tempVec = new Vector3();
104
+ }
105
+
106
+ update() {
107
+ entity.object3D.getWorldPosition(this.tempVec);
108
+ }
109
+ ```
110
+
111
+ **What to look for in update():**
112
+
113
+ - `new Vector3()`, `new Quaternion()`, `new Matrix4()`, `new Euler()`
114
+ - Array literals `[]` or object literals `{}`
115
+ - `.clone()` calls
116
+ - String concatenation for keys
117
+
118
+ ### 4. Use Reactive Patterns (subscribe)
119
+
120
+ Use query subscriptions for one-time operations, not polling in update().
121
+
122
+ ```typescript
123
+ // ❌ BAD - Polling in update
124
+ update() {
125
+ this.queries.items.entities.forEach(entity => {
126
+ if (entity.hasComponent(Pressed)) { // Checking every frame
127
+ this.handlePress(entity);
128
+ }
129
+ });
130
+ }
131
+
132
+ // ✅ GOOD - Subscribe to combined query
133
+ class MySystem extends createSystem({
134
+ pressedItems: { required: [MyComponent, Pressed] }
135
+ }) {
136
+ init() {
137
+ this.queries.pressedItems.subscribe('qualify', (entity) => {
138
+ this.handlePress(entity); // Called once when pressed
139
+ });
140
+ }
141
+ }
142
+ ```
143
+
144
+ ### 5. Use VisibilityState Correctly
145
+
146
+ React to XR state changes properly.
147
+
148
+ ```typescript
149
+ // ✅ GOOD - Subscribe to visibility changes
150
+ init() {
151
+ this.world.visibilityState.subscribe((state) => {
152
+ if (state === VisibilityState.Visible) {
153
+ // In XR
154
+ } else if (state === VisibilityState.NonImmersive) {
155
+ // In browser (2D)
156
+ }
157
+ });
158
+ }
159
+ ```
160
+
161
+ ### 6. Cleanup Subscriptions
162
+
163
+ Signal subscriptions must be cleaned up to prevent memory leaks.
164
+
165
+ ```typescript
166
+ // ❌ BAD - No cleanup
167
+ init() {
168
+ this.world.visibilityState.subscribe((state) => {
169
+ // Never unsubscribed!
170
+ });
171
+ }
172
+
173
+ // ✅ GOOD - Register cleanup
174
+ init() {
175
+ this.cleanupFuncs.push(
176
+ this.world.visibilityState.subscribe((state) => {
177
+ // Will be cleaned up when system is destroyed
178
+ })
179
+ );
180
+ }
181
+ ```
182
+
183
+ ### 7. Component Types
184
+
185
+ Use proper types, avoid `Types.Object`.
186
+
187
+ ```typescript
188
+ // ❌ BAD - Using Object type
189
+ const MyComponent = createComponent('MyComponent', {
190
+ data: { type: Types.Object, default: {} }, // Not optimized
191
+ });
192
+
193
+ // ✅ GOOD - Use specific types
194
+ const MyComponent = createComponent('MyComponent', {
195
+ speed: { type: Types.Float32, default: 1.0 },
196
+ position: { type: Types.Vec3, default: [0, 0, 0] },
197
+ color: { type: Types.Color, default: [1, 1, 1, 1] }, // RGBA
198
+ });
199
+ ```
200
+
201
+ ### 8. PhysicsBody vs PhysicsShape
202
+
203
+ These are separate components with different purposes.
204
+
205
+ ```typescript
206
+ // PhysicsBody = motion properties
207
+ entity.addComponent(PhysicsBody, {
208
+ state: PhysicsState.Dynamic, // or Static, Kinematic
209
+ linearDamping: 0.5,
210
+ gravityFactor: 1.0,
211
+ });
212
+
213
+ // PhysicsShape = collision shape + material
214
+ entity.addComponent(PhysicsShape, {
215
+ shape: PhysicsShapeType.Box,
216
+ density: 1.0,
217
+ restitution: 0.5, // Bounciness
218
+ friction: 0.3,
219
+ });
220
+ ```
221
+
222
+ ### 9. Input Handling
223
+
224
+ Check for proper gamepad/input access.
225
+
226
+ ```typescript
227
+ // ✅ GOOD - Safe input access with optional chaining
228
+ update() {
229
+ const leftGamepad = this.input.xr.gamepads.left;
230
+ const triggerPressed = leftGamepad?.getButtonDown(InputComponent.Trigger) ?? false;
231
+ }
232
+ ```
233
+
234
+ ### 10. Audio Configuration
235
+
236
+ Check PlaybackMode usage.
237
+
238
+ ```typescript
239
+ // Available PlaybackMode values:
240
+ PlaybackMode.Restart; // Stop current, restart
241
+ PlaybackMode.Overlap; // Play new instance
242
+ PlaybackMode.Ignore; // Ignore if playing
243
+ PlaybackMode.FadeRestart; // Fade out, start new
244
+ ```
245
+
246
+ ### 11. Three.js Import Check (CRITICAL)
247
+
248
+ Check for direct imports from 'three' package - should use @iwsdk/core instead.
249
+
250
+ ```typescript
251
+ // ❌ BAD - causes duplicate Three.js instances
252
+ import { Vector3 } from 'three';
253
+ import * as THREE from 'three';
254
+
255
+ // ✅ GOOD
256
+ import { Vector3, Mesh, MeshStandardMaterial } from '@iwsdk/core';
257
+ ```
258
+
259
+ **Exception:** GLTF loader types can come from three/addons:
260
+
261
+ ```typescript
262
+ import type { GLTF } from 'three/addons/loaders/GLTFLoader.js';
263
+ ```
264
+
265
+ ### 12. Component Size Check
266
+
267
+ Flag components with more than 10 fields - consider splitting into focused components.
268
+
269
+ ```typescript
270
+ // ❌ BAD - Fat component with too many fields
271
+ const Vehicle = createComponent('Vehicle', {
272
+ position: ..., orientation: ..., speed: ...,
273
+ engineRPM: ..., gear: ..., throttle: ..., steering: ...,
274
+ fuel: ..., health: ..., score: ..., // Too many!
275
+ });
276
+
277
+ // ✅ GOOD - Split into focused components
278
+ const VehiclePhysics = createComponent('VehiclePhysics', { position: ..., speed: ... });
279
+ const VehicleEngine = createComponent('VehicleEngine', { rpm: ..., gear: ... });
280
+ ```
281
+
282
+ ### 13. Signal Access in update()
283
+
284
+ Check for `.value` access on signals in update() - should use `.peek()` instead.
285
+
286
+ ```typescript
287
+ // ❌ BAD - creates subscription overhead every frame
288
+ update() {
289
+ const rate = this.config.tickRate.value;
290
+ }
291
+
292
+ // ✅ GOOD - peek() reads without subscription
293
+ update() {
294
+ const rate = this.config.tickRate.peek();
295
+ }
296
+ ```
297
+
298
+ ### 14. Handle Existing Entities in init()
299
+
300
+ Systems should iterate existing entities in init(), not just subscribe to qualify:
301
+
302
+ ```typescript
303
+ // ❌ BAD - Misses entities that exist before system starts
304
+ init() {
305
+ this.queries.items.subscribe('qualify', (entity) => {
306
+ this.setupEntity(entity);
307
+ });
308
+ }
309
+
310
+ // ✅ GOOD - Handle existing AND new entities
311
+ init() {
312
+ // Subscribe for NEW entities
313
+ this.queries.items.subscribe('qualify', (entity) => {
314
+ this.setupEntity(entity);
315
+ });
316
+
317
+ // ALSO handle existing entities
318
+ for (const entity of this.queries.items.entities) {
319
+ this.setupEntity(entity);
320
+ }
321
+ }
322
+ ```
323
+
324
+ ### 15. Direct asset loaders instead of AssetManager
325
+
326
+ Flag: `new GLTFLoader()`, `new OBJLoader()`, `new TextureLoader()` used directly.
327
+
328
+ ```typescript
329
+ // ❌ BAD - bypasses DRACO/KTX2 setup, no caching, no de-duplication
330
+ import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
331
+ const loader = new GLTFLoader();
332
+ const gltf = await loader.loadAsync(url);
333
+
334
+ // ✅ GOOD - use AssetManager
335
+ const gltf = await AssetManager.loadGLTF(url, 'myModel');
336
+ // For project assets, declare the entry with defineAssets() in src/assets.ts
337
+ // and point iwsdk.config.json assets.module at that catalog.
338
+ ```
339
+
340
+ ### 16. Raw scene.add() instead of createTransformEntity
341
+
342
+ Flag: `scene.add(...)` or `world.scene.add(...)` or `this.scene.add(...)` for adding content.
343
+
344
+ ```typescript
345
+ // ❌ BAD - bypasses ECS, no Transform component, no level lifecycle
346
+ this.scene.add(mesh);
347
+
348
+ // ✅ GOOD - proper entity creation
349
+ world.createTransformEntity(mesh, parentEntity);
350
+ ```
351
+
352
+ ### 17. Raw Raycaster used as an interaction system
353
+
354
+ Flag: `new THREE.Raycaster()` or `new Raycaster()` used to reproduce IWSDK
355
+ hover, press, grab, or pointer behavior. A raw raycaster is valid for a custom
356
+ geometric query, but it does not map hits to ECS entities or share
357
+ `InputSystem` target filtering and pointer-event lifecycle.
358
+
359
+ ```typescript
360
+ // ⚠️ Raw geometry query: caller owns entity mapping and target filtering.
361
+ const raycaster = new Raycaster();
362
+
363
+ // ✅ For user interaction, use the shared IWSDK interaction path.
364
+ entity.addComponent(RayInteractable);
365
+ ```
366
+
367
+ ### 18. Environment components on wrong entity
368
+
369
+ Flag: `DomeGradient`/`DomeTexture`/`IBLGradient`/`IBLTexture` added to entities that don't have `LevelRoot`.
370
+
371
+ ```typescript
372
+ // ❌ BAD - Environment components only work on the level root entity
373
+ someEntity.addComponent(DomeGradient, { ... });
374
+
375
+ // ✅ GOOD - Add to the level root
376
+ const root = world.activeLevel.value;
377
+ root.addComponent(DomeGradient, { ... });
378
+ ```
379
+
380
+ ### 19. Missing `_needsUpdate` on environment texture changes
381
+
382
+ Flag: Setting properties on `DomeTexture`/`IBLTexture` without setting `_needsUpdate: true`. `DomeGradient` and `IBLGradient` apply edits on the next frame, so do not flag them for a missing `_needsUpdate`.
383
+
384
+ ```typescript
385
+ // ❌ BAD - DomeTexture changes are silently ignored
386
+ root.setValue(DomeTexture, 'intensity', 0.6);
387
+
388
+ // ✅ GOOD - _needsUpdate is scalar
389
+ root.setValue(DomeTexture, 'intensity', 0.6);
390
+ root.setValue(DomeTexture, '_needsUpdate', true);
391
+
392
+ // ✅ ALSO GOOD - gradient edits apply without the flag
393
+ root.getVectorView(DomeGradient, 'sky').set([0.1, 0.2, 0.8, 1.0]);
394
+ ```
395
+
396
+ ### 20. Using `destroy()` instead of `dispose()` for GPU objects
397
+
398
+ Flag: `entity.destroy()` on entities with meshes/materials.
399
+
400
+ ```typescript
401
+ // ❌ BAD - GPU memory for geometry/materials/textures is leaked
402
+ entity.destroy();
403
+
404
+ // ✅ GOOD - Use dispose() for proper GPU cleanup
405
+ entity.dispose();
406
+ ```
407
+
408
+ ### 21. Hand-built sky or sky fade
409
+
410
+ Flag: a `ShaderMaterial` sky sphere, `BackSide` sky meshes, or an `onBeforeCompile` that pastes sky gradient GLSL into a floor material. Point to the built-ins: `DomeGradient` on the level root (with `elevationDeg`/`azimuthDeg` to tilt it and `dither` against banding) plus `DomeFade` on the floor node.
411
+
412
+ ```typescript
413
+ // ❌ BAD - a second sky that the environment system, editor and AR policy know nothing about
414
+ const sky = new Mesh(
415
+ new SphereGeometry(60),
416
+ new ShaderMaterial({ side: BackSide, fragmentShader: SKY_GLSL }),
417
+ );
418
+ floorMaterial.onBeforeCompile = (shader) => {
419
+ /* paste SKY_GLSL, mix by distance */
420
+ };
421
+ ```
422
+
423
+ ```jsonc
424
+ // ✅ GOOD - scene JSON: the root sky plus a fade on the floor node
425
+ {
426
+ "components": {
427
+ "com.iwsdk.components.DomeGradient": {
428
+ "elevationDeg": 24,
429
+ "azimuthDeg": -31,
430
+ "dither": true,
431
+ },
432
+ },
433
+ "nodes": [
434
+ {
435
+ "id": "floor",
436
+ "components": {
437
+ "com.iwsdk.components.DomeFade": { "start": 4, "end": 10 },
438
+ },
439
+ },
440
+ ],
441
+ }
442
+ ```
443
+
444
+ ### 22. Hand-built ground shadows
445
+
446
+ Flag: a canvas-painted radial blob card under a prop, or a `ShadowMaterial` plane
447
+ added to ground content in AR. Both are built in: author `ContactShadow` and
448
+ `ShadowCatcher` node components in the scene instead.
449
+
450
+ ```typescript
451
+ // ❌ BAD - blob card and AR catcher built by hand (DOM canvas, extra assets)
452
+ const blob = new Mesh(
453
+ plane,
454
+ new MeshBasicMaterial({ map: canvasBlob, transparent: true }),
455
+ );
456
+ const catcher = new Mesh(plane, new ShadowMaterial({ opacity: 0.25 }));
457
+ ```
458
+
459
+ ✅ GOOD - a node component in the scene JSON; for AR, add one floor node with
460
+ `com.iwsdk.components.ShadowCatcher`:
461
+
462
+ ```json
463
+ {
464
+ "id": "plinth",
465
+ "content": { "type": "asset", "asset": "plinth" },
466
+ "components": {
467
+ "com.iwsdk.components.ContactShadow": { "size": [0.9, 0.9] }
468
+ }
469
+ }
470
+ ```
471
+
472
+ ---
473
+
474
+ ## Confidence-Based Reporting
475
+
476
+ Only report issues you're confident about:
477
+
478
+ - **95%+ confidence**: Report as Critical
479
+ - **80-95% confidence**: Report as Warning
480
+ - **60-80% confidence**: Report as Suggestion
481
+ - **<60% confidence**: Don't report (too speculative)
482
+
483
+ ---
484
+
485
+ ## Output Format
486
+
487
+ ```markdown
488
+ ## IWSDK Project Code Review
489
+
490
+ ### Project Overview
491
+
492
+ - Entry point: [file]
493
+ - Systems: [list]
494
+ - Components: [list]
495
+ - Features enabled: [list from iwsdk.config.json]
496
+
497
+ ### Critical Issues
498
+
499
+ - **[filename:line]** Issue description
500
+ - Problem: `current code`
501
+ - Fix: `suggested fix`
502
+
503
+ ### Warnings
504
+
505
+ - **[filename:line]** Issue description
506
+
507
+ ### Suggestions
508
+
509
+ - **[filename:line]** Improvement suggestion
510
+
511
+ ### Feature Configuration Analysis
512
+
513
+ - locomotion: [enabled/disabled] - [assessment]
514
+ - physics: [enabled/disabled] - [assessment]
515
+ - grabbing: [enabled/disabled] - [assessment]
516
+
517
+ ### Summary
518
+
519
+ [Brief summary of overall code quality and key recommendations]
520
+ ```
521
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=976bd24f6ae91d050ed7bef71cdfb4cfab1fc41e4718d2042d9618860cb1161e name=iwsdk-project-code-reviewer.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -0,0 +1,60 @@
1
+ ---
2
+ paths:
3
+ - "src/assets.ts"
4
+ - "src/assets.js"
5
+ - "src/iwsdk/assets.ts"
6
+ - "src/iwsdk/assets.js"
7
+ - "src/scene-assets/**"
8
+ ---
9
+
10
+ # Asset manifest contract
11
+
12
+ `src/assets.ts` is imported **independently by the app runtime and the editor**,
13
+ in separate JS realms. It must therefore be deterministic and self-contained:
14
+
15
+ - no `World`, scene, iframe, editor object or DOM access
16
+ - no timers, no fetching ambient state
17
+ - no reliance on singleton object identity across realms
18
+ - prototypes immutable after registration, and never parented
19
+
20
+ A manifest entry is either a URL descriptor (`{ url, type, name?, priority? }`)
21
+ or a bare parentless `Object3D`. `AssetType` covers `GLTF`, `Audio`, `Texture`,
22
+ `HDRTexture`, `UIKitML`. Only glTF, UIKitML and `Object3D` entries are placeable
23
+ as scene content; audio/texture/HDR are for application systems.
24
+
25
+ Build public URLs from `import.meta.env.BASE_URL` so runtime, editor and subpath
26
+ builds resolve identically. A file in `public/` is **not** available to a scene
27
+ until it is registered here.
28
+
29
+ ## Procedural assets
30
+
31
+ Export a parentless `Object3D` from `src/scene-assets/*.scene-asset.ts` and
32
+ register it under a stable ID. The registry rejects an already-parented
33
+ prototype.
34
+
35
+ Every placement is a distinct hierarchy clone, but **geometry and materials stay
36
+ shared**. Never dispose them from a placed clone; world teardown owns their
37
+ lifetime. Reassigning `mesh.material` on a clone is fine and is how you restyle
38
+ one instance — mutating the shared material in place changes every instance.
39
+
40
+ Bounds come from `Box3` over the instantiated asset and drive placement,
41
+ selection, framing and scatter collision. Put the origin where composition wants
42
+ it (usually floor contact, or the object's own pivot), keep transforms finite,
43
+ and don't let invisible helpers inflate bounds.
44
+
45
+ ## Cost
46
+
47
+ Split tessellation by viewing distance rather than using one budget everywhere: a
48
+ close-range hero model and coarser display copies of the same form are two
49
+ prototypes from one factory function. Sphere/lathe segment counts dominate small
50
+ repeated detail more than people expect — check `renderStats.triangles` rather
51
+ than guessing.
52
+
53
+ Reuse material instances within a module. Prefer prefabs plus a deterministic
54
+ pattern for repetition; a pattern whose prefab resolves to a single component-free
55
+ mesh lowers to one `InstancedMesh`.
56
+
57
+ Start assets at `castShadow: false` and opt in only for grounded focal masses.
58
+ Don't build contact-shadow blob cards or `ShadowMaterial` catcher planes here: put
59
+ `ContactShadow` or `ShadowCatcher` node components on the scene nodes instead.
60
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=9c0abbe2f1b3cc83f826ac6a5c24f0088375757ec17bfb970301a3c32b940a44 name=assets-and-manifest.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -0,0 +1,103 @@
1
+ ---
2
+ paths:
3
+ - "src/**/*.ts"
4
+ - "src/**/*.js"
5
+ ---
6
+
7
+ # ECS API reference
8
+
9
+ ## Field types
10
+
11
+ ```
12
+ Types.Float32 Float64 Int8 Int16 Int32 Boolean String FilePath
13
+ Types.Vec2 Vec3 Vec4 Color(RGBA) Entity Enum
14
+ Types.Object // avoid — not optimised
15
+ ```
16
+
17
+ ## Component
18
+
19
+ Declare in a system-free module, then list it in `src/components.ts` via
20
+ `defineComponents()` or the editor cannot author it.
21
+
22
+ ```ts
23
+ export const MyComponent = createComponent('MyComponent', {
24
+ speed: { type: Types.Float32, default: 1 },
25
+ tint: { type: Types.Color, default: [1, 1, 1, 1] }, // RGBA
26
+ });
27
+ ```
28
+
29
+ Optional metadata per field — `label`, `step`, `min`, `max`, `enum`, `help`,
30
+ `widget` — drives the editor inspector.
31
+
32
+ ## System
33
+
34
+ ```ts
35
+ export class MySystem extends createSystem(
36
+ {
37
+ items: { required: [MyComponent] },
38
+ active: { required: [MyComponent], excluded: [Grabbed] },
39
+ },
40
+ { speed: { type: Types.Float32, default: 1 } }, // optional config
41
+ ) {
42
+ private temp!: Vector3;
43
+
44
+ init() {
45
+ this.temp = new Vector3();
46
+ this.queries.items.subscribe('qualify', (entity) => { /* matched */ });
47
+ this.cleanupFuncs.push(this.config.speed.subscribe((v) => { /* … */ }));
48
+ }
49
+
50
+ update(delta: number, time: number) {
51
+ for (const entity of this.queries.active.entities) { /* no allocations */ }
52
+ }
53
+ }
54
+ ```
55
+
56
+ Queries take `required`, `excluded` and `where` (value predicates via `eq`, `ne`,
57
+ `lt`, `le`, `gt`, `ge`, `isin`, `nin`). `excluded` is the clean way to skip
58
+ entities in a transient state — e.g. excluding `Grabbed` so a held object is left
59
+ alone.
60
+
61
+ Register explicitly in `src/index.ts` with `world.registerSystem(MySystem)`.
62
+
63
+ Read fields with `entity.getValue(Component, 'field')`. For vector fields use
64
+ `entity.getVectorView(Component, 'field')` — it returns a `Float32Array` view with
65
+ no allocation, and `setValue` **throws** on vector fields in elics 3.4.x.
66
+
67
+ ## Interaction components
68
+
69
+ `RayInteractable` plus `Hovered`/`Pressed` covers both mouse/touch canvas input
70
+ and XR rays. Grab components: `OneHandGrabbable` and `TwoHandsGrabbable` are
71
+ proximity-based and respond to **squeeze**, while `DistanceGrabbable` is
72
+ ray-based and responds to **trigger**. `Grabbed` is a transient tag managed by
73
+ `GrabSystem` — read it, never add or remove it. `GrabSystem.useHandPinchForGrab`
74
+ defaults to **true**, so a hand pinch grabs; set it to `false` to require squeeze.
75
+
76
+ `DistanceGrabbable` fields: `movementMode` (`MoveTowardsTarget`, `MoveFromTarget`,
77
+ `MoveAtSource`, `RotateAtSource`), `returnToOrigin`, `moveSpeedFactor`,
78
+ `detachOnGrab`, `translate`, `rotate`, `scale`, `targetPositionOffset`,
79
+ `targetQuaternionOffset`. `returnToOrigin: true` gives spring-back on release with
80
+ no custom code.
81
+
82
+ For a held object use `GrabSystem`'s public methods — `forceRelease(entity)`,
83
+ `getHolderHand(entity)` — never deep-import `Handle`.
84
+
85
+ ## XR input
86
+
87
+ ```ts
88
+ const pad = this.input.xr.gamepads.right;
89
+ pad?.getButtonDown(InputComponent.Trigger); // just pressed
90
+ pad?.getAxesValues(InputComponent.Thumbstick);
91
+ this.player.head; this.player.raySpaces.left; this.player.gripSpaces.right;
92
+ ```
93
+
94
+ Prefer `world.input.actions` for reusable intent (`locomotion.move`) over raw
95
+ buttons. Browser controls live at `world.input.keyboard` and
96
+ `world.input.browserGamepads`.
97
+
98
+ ## Lifecycle
99
+
100
+ `world.visibilityState` reports `NonImmersive`, `Visible`, `VisibleBlurred` —
101
+ pause simulation on blur. `world.camera.position` is local to `world.player`; use
102
+ `getWorldPosition()` when logic needs the true viewer position.
103
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=56f1044b9936f279404ef715676b734a119ef495824d5916737f3a00579acc64 name=ecs-api.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->