@iwsdk/create 0.4.2 → 0.5.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/README.md +103 -41
  2. package/dist/cli.js +1003 -3418
  3. package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +96 -0
  4. package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +135 -0
  5. package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +129 -0
  6. package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -0
  7. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/component-reference.md +154 -0
  8. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +88 -0
  9. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
  10. package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +364 -0
  11. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/api-reference.md +1489 -0
  12. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +241 -0
  13. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +101 -0
  14. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +176 -0
  15. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +156 -0
  16. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +199 -0
  17. package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +159 -0
  18. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +255 -0
  19. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +5 -0
  20. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +295 -0
  21. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +243 -0
  22. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/image-intake.md +191 -0
  23. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +99 -0
  24. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/scene-format.md +458 -0
  25. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/text-intake.md +82 -0
  26. package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +208 -0
  27. package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +450 -0
  28. package/dist/guidance/claude/.claude/rules/assets-and-manifest.md +55 -0
  29. package/dist/guidance/claude/.claude/rules/ecs-api.md +102 -0
  30. package/dist/guidance/claude/.claude/rules/scene-json.md +64 -0
  31. package/dist/guidance/claude/.claude/rules/uikitml.md +60 -0
  32. package/dist/guidance/claude/.claude/settings.json +19 -0
  33. package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +96 -0
  34. package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +135 -0
  35. package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +129 -0
  36. package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -0
  37. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/component-reference.md +154 -0
  38. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +88 -0
  39. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
  40. package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +364 -0
  41. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/api-reference.md +1489 -0
  42. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +241 -0
  43. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +101 -0
  44. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +176 -0
  45. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +156 -0
  46. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +199 -0
  47. package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +159 -0
  48. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +255 -0
  49. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +5 -0
  50. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +295 -0
  51. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +243 -0
  52. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/image-intake.md +191 -0
  53. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +99 -0
  54. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/scene-format.md +458 -0
  55. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/text-intake.md +82 -0
  56. package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +208 -0
  57. package/dist/guidance/claude/CLAUDE.md +142 -0
  58. package/dist/guidance/codex/.codex/config.toml +2 -0
  59. package/dist/guidance/common/AGENTS.md +151 -0
  60. package/dist/guidance/copilot/.github/instructions/assets-and-manifest.instructions.md +52 -0
  61. package/dist/guidance/copilot/.github/instructions/ecs-api.instructions.md +100 -0
  62. package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +63 -0
  63. package/dist/guidance/copilot/.github/instructions/uikitml.instructions.md +59 -0
  64. package/dist/guidance/cursor/.cursor/rules/assets-and-manifest.mdc +57 -0
  65. package/dist/guidance/cursor/.cursor/rules/ecs-api.mdc +104 -0
  66. package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +66 -0
  67. package/dist/guidance/cursor/.cursor/rules/uikitml.mdc +62 -0
  68. package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +63 -0
  69. package/dist/guidance/scoped-agents/public/ui/AGENTS.md +59 -0
  70. package/dist/guidance/scoped-agents/src/AGENTS.md +149 -0
  71. package/dist/template/common/README.md +13 -0
  72. package/dist/template/common/gitignore.template +45 -0
  73. package/dist/template/common/index.html +16 -0
  74. package/dist/template/common/nvmrc.template +1 -0
  75. package/dist/template/common/public/audio/chime.mp3 +0 -0
  76. package/dist/template/common/public/gltf/webxr-banner/banner.gltf +68 -0
  77. package/dist/template/common/public/textures/webxr.png +0 -0
  78. package/dist/template/common/public/ui/welcome.uikitml +98 -0
  79. package/dist/template/common/src/assets.ts +54 -0
  80. package/dist/template/common/src/components.ts +11 -0
  81. package/dist/template/common/src/index.ts +19 -0
  82. package/dist/template/common/src/panel.ts +38 -0
  83. package/dist/template/common/src/robot-component.ts +10 -0
  84. package/dist/template/common/src/robot.ts +38 -0
  85. package/dist/template/common/src/vite-env.d.ts +2 -0
  86. package/dist/template/common/tsconfig.json +15 -0
  87. package/dist/template/common/vite.config.ts +27 -0
  88. package/dist/template/common-js/README.md +13 -0
  89. package/dist/template/common-js/gitignore.template +45 -0
  90. package/dist/template/common-js/index.html +16 -0
  91. package/dist/template/common-js/nvmrc.template +1 -0
  92. package/dist/template/common-js/public/audio/chime.mp3 +0 -0
  93. package/dist/template/common-js/public/gltf/webxr-banner/banner.gltf +68 -0
  94. package/dist/template/common-js/public/textures/webxr.png +0 -0
  95. package/dist/template/common-js/public/ui/welcome.uikitml +98 -0
  96. package/dist/template/common-js/src/assets.js +45 -0
  97. package/dist/template/common-js/src/components.js +9 -0
  98. package/dist/template/common-js/src/index.js +14 -0
  99. package/dist/template/common-js/src/panel.js +31 -0
  100. package/dist/template/common-js/src/robot-component.js +8 -0
  101. package/dist/template/common-js/src/robot.js +37 -0
  102. package/dist/template/common-js/vite.config.js +25 -0
  103. package/dist/template/scenes/ar.iwsdk.scene.json +96 -0
  104. package/dist/template/scenes/immersive.iwsdk.scene.json +109 -0
  105. package/package.json +23 -17
  106. package/scripts/verify-release-ready.mjs +76 -0
  107. package/LICENSE +0 -21
@@ -0,0 +1,208 @@
1
+ ---
2
+ name: iwsdk-ui
3
+ description: Create, place, preview, debug, and connect manifest-backed IWSDK UIKitML assets. Use for spatial panels, browser HUDs, UIKitML layout, fonts, editor previews, or runtime element behavior.
4
+ argument-hint: '[panel-name or description of changes]'
5
+ ---
6
+
7
+ # UIKitML Asset Workflow
8
+
9
+ Treat UIKitML as a first-class renderable asset. Use the managed editor's isolated
10
+ renderer for layout, the scene editor for placement, and the application runtime for
11
+ behavior. Do not change the scene, camera, or component model merely to inspect a
12
+ panel.
13
+
14
+ User request is in `$ARGUMENTS`.
15
+
16
+ ## 1. Find the three stable identities
17
+
18
+ Every scene-authored panel has three different identities:
19
+
20
+ 1. the manifest asset ID, which names the reusable UIKitML definition;
21
+ 2. the scene node ID, which names one placed instance;
22
+ 3. element `id` attributes, which name fields and controls inside the document.
23
+
24
+ Find or add the manifest entry in `src/assets.ts` and keep the source under
25
+ `public/ui/`:
26
+
27
+ ```ts
28
+ import { AssetType, defineAssets } from '@iwsdk/core';
29
+
30
+ const publicAssetUrl = (path: string) =>
31
+ `${import.meta.env.BASE_URL}${path.replace(/^\/+/u, '')}`;
32
+
33
+ export default defineAssets({
34
+ 'welcome-panel': {
35
+ name: 'Welcome panel',
36
+ type: AssetType.UIKitML,
37
+ url: publicAssetUrl('ui/welcome.uikitml'),
38
+ },
39
+ });
40
+ ```
41
+
42
+ A file under `public/ui/` is not placeable until it is registered. The `.uikitml`
43
+ file is the runtime source of truth; never generate an intermediate JSON file.
44
+
45
+ ## 2. Reuse the managed editor
46
+
47
+ Run commands from the application directory. Reuse a command-ready session instead
48
+ of starting a second server or browser:
49
+
50
+ ```bash
51
+ npx iwsdk dev status
52
+ npx iwsdk dev up --timeout 60000
53
+ npx iwsdk ui assets --raw
54
+ ```
55
+
56
+ `dev up` owns the managed headed browser. Do not launch a second Playwright browser,
57
+ enable Vite's independent opener, or implement a custom UIKit renderer.
58
+
59
+ ## 3. Render the panel in isolation
60
+
61
+ Use the editor-backed isolated renderer before debugging scene placement:
62
+
63
+ ```bash
64
+ npx iwsdk ui render-preview \
65
+ --input-json '{"assetId":"welcome-panel","width":800,"height":600}' \
66
+ --output-file artifacts/welcome-panel.png
67
+ ```
68
+
69
+ This renders the real manifest entry through the real UIKitML parser, fonts, layout,
70
+ and WebGL path on a neutral background. It waits for UIKit render and resource
71
+ signals; do not add fixed frame delays. Re-run the command after every layout change.
72
+ Same-URL sources are reloaded without restarting the server.
73
+
74
+ ## 4. Place and inspect it in the scene editor
75
+
76
+ For a human-authored placement, open the scene and add the UIKitML asset from the
77
+ asset drawer. For file authoring, use the same asset-only node contract:
78
+
79
+ ```json
80
+ {
81
+ "id": "welcome-panel-instance",
82
+ "name": "Welcome panel",
83
+ "content": { "type": "asset", "asset": "welcome-panel" },
84
+ "transform": {
85
+ "position": [0, 1.4, -1.5],
86
+ "rotationDeg": [0, 180, 0],
87
+ "scale": 0.5
88
+ }
89
+ }
90
+ ```
91
+
92
+ ```bash
93
+ npx iwsdk scene render-file \
94
+ --input-json '{"path":"public/scenes/main.iwsdk.scene.json","view":"quarter"}' \
95
+ --output-file artifacts/main-editor.png
96
+ npx iwsdk scene open \
97
+ --input-json '{"path":"public/scenes/main.iwsdk.scene.json"}' --raw
98
+ ```
99
+
100
+ UIKitML surfaces are single-sided. If the isolated preview works but the placed panel
101
+ is invisible, inspect its rotation first. Size a world-space panel with its ordinary
102
+ entity transform scale. There is no `maxWidth`/`maxHeight` fitting layer and no
103
+ editor-visible legacy `PanelUI` component to configure.
104
+
105
+ Use `scene screenshot` for editor/scene evidence. `browser screenshot` is intentionally
106
+ runtime-only and switches the managed workspace to runtime before capturing.
107
+
108
+ ## 5. Edit UIKitML
109
+
110
+ UIKitML is HTML/CSS-shaped, but it is not a browser engine. Before assuming browser
111
+ behavior, use `npx iwsdk reference search` or the connected IWSDK reference tools to
112
+ confirm supported elements and properties.
113
+
114
+ Key rules:
115
+
116
+ - numeric UIKit sizes are centimeters (`100` = 100 cm = 1 m);
117
+ - use stable `id` attributes for elements application code must manipulate;
118
+ - prefer explicit supported declarations over CSS shorthand;
119
+ - parser errors include source locations;
120
+ - relative and remote font URLs are supported, but font completion can change layout;
121
+ - the managed preview settles from UIKit render/font/texture signals, so inspect logs
122
+ instead of compensating with arbitrary waits.
123
+
124
+ ### Reuse built-in kits, icons, and remote fonts
125
+
126
+ IWSDK bundles the UIKitML Horizon component kit and Lucide icon set. Select the
127
+ Horizon kit explicitly in `iwsdk.config.json` so the choice is visible to both the
128
+ runtime and editor:
129
+
130
+ ```json
131
+ {
132
+ "world": {
133
+ "features": {
134
+ "spatialUI": { "kit": "horizon" }
135
+ }
136
+ }
137
+ }
138
+ ```
139
+
140
+ Horizon tags such as `<Panel>`, `<Button>`, `<ButtonIcon>`, and `<ButtonLabel>`
141
+ can then be combined directly with Lucide tags such as `<RectangleGoggles>` or
142
+ `<LogIn>`. Do not install or register either component set in application code.
143
+
144
+ UIKitML also accepts remote TTF declarations. The starter's
145
+ `public/ui/welcome.uikitml` demonstrates multiple DM Sans weights loaded from
146
+ `fonts.gstatic.com` with `@font-face`; apply the declared family to a root class so
147
+ all descendants inherit it. Keep a local font under `public/` when offline or
148
+ cross-origin availability is a product requirement.
149
+
150
+ After each edit:
151
+
152
+ 1. rerender with `ui render-preview` and inspect the image;
153
+ 2. rerender the scene when placement or scale matters;
154
+ 3. inspect `browser logs` for parser, font, texture, or runtime failures.
155
+
156
+ ## 6. Connect runtime behavior
157
+
158
+ For a code-owned instance, keep the `UIKitMLAsset` returned by the asset manager:
159
+
160
+ ```ts
161
+ import { UIKitMLAsset } from '@iwsdk/core';
162
+
163
+ const panel = await world.assets.instantiate<UIKitMLAsset>('welcome-panel');
164
+ const entity = world.createTransformEntity(panel);
165
+ const button = panel.requireElementById('xr-button');
166
+ button.addEventListener('click', () => world.launchXR());
167
+ ```
168
+
169
+ For a scene-authored instance, resolve it by stable scene node ID after the level has
170
+ loaded:
171
+
172
+ ```ts
173
+ const panel = world.requireSceneObject<UIKitMLAsset>('welcome-panel-instance');
174
+ const button = panel.requireElementById('xr-button');
175
+ button.setProperties({ display: 'none' });
176
+ ```
177
+
178
+ Do not locate a panel by transient ECS index, manifest URL, or a scan for an internal
179
+ `PanelDocument`. Use the scene node ID and element IDs.
180
+
181
+ ## ScreenSpace is product behavior
182
+
183
+ Add `ScreenSpace` only when the experience genuinely needs a browser-camera HUD:
184
+
185
+ ```ts
186
+ entity.addComponent(ScreenSpace, {
187
+ width: '420px',
188
+ height: '240px',
189
+ top: '20px',
190
+ right: '20px',
191
+ zOffset: 0.2,
192
+ });
193
+ ```
194
+
195
+ Position and size values are CSS strings. In immersive mode the document returns to
196
+ its authored world transform. Do not add `ScreenSpace`, a backdrop, or a temporary
197
+ camera pose merely to make a panel easier to inspect—the editor already provides the
198
+ correct isolated and in-scene render paths.
199
+
200
+ ## Completion checklist
201
+
202
+ - Manifest ID resolves and `ui assets` lists it.
203
+ - Isolated preview is nonblank, correctly laid out, and uses the intended fonts.
204
+ - Scene preview has correct facing, transform scale, and lighting-independent color.
205
+ - Runtime behavior resolves the placed node and required element IDs.
206
+ - Browser logs contain no UIKitML parser, resource, or font errors.
207
+ - No generated UI JSON, temporary ScreenSpace component, backdrop, or camera hack
208
+ remains.
@@ -0,0 +1,450 @@
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 proactively after writing or modifying code in IWSDK applications.
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-planner/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. Manual Raycaster instead of RayInteractable
353
+
354
+ Flag: `new THREE.Raycaster()` or `new Raycaster()` for interaction detection.
355
+
356
+ ```typescript
357
+ // ❌ BAD - no BVH acceleration, doesn't work in XR, no pointer events
358
+ const raycaster = new Raycaster();
359
+
360
+ // ✅ GOOD - add RayInteractable component, query Hovered/Pressed in system
361
+ entity.addComponent(RayInteractable);
362
+ ```
363
+
364
+ ### 18. Environment components on wrong entity
365
+
366
+ Flag: `DomeGradient`/`DomeTexture`/`IBLGradient`/`IBLTexture` added to entities that don't have `LevelRoot`.
367
+
368
+ ```typescript
369
+ // ❌ BAD - Environment components only work on the level root entity
370
+ someEntity.addComponent(DomeGradient, { ... });
371
+
372
+ // ✅ GOOD - Add to the level root
373
+ const root = world.activeLevel.value;
374
+ root.addComponent(DomeGradient, { ... });
375
+ ```
376
+
377
+ ### 19. Missing `_needsUpdate` on environment changes
378
+
379
+ Flag: Setting properties on `DomeGradient`/`DomeTexture`/`IBLGradient`/`IBLTexture` without setting `_needsUpdate: true`.
380
+
381
+ ```typescript
382
+ // ❌ BAD - Changes are silently ignored
383
+ root.setValue(DomeGradient, 'sky', [0.1, 0.2, 0.8, 1.0]);
384
+
385
+ // ✅ GOOD - Vector writes use getVectorView; _needsUpdate is scalar
386
+ root.getVectorView(DomeGradient, 'sky').set([0.1, 0.2, 0.8, 1.0]);
387
+ root.setValue(DomeGradient, '_needsUpdate', true);
388
+ ```
389
+
390
+ ### 20. Using `destroy()` instead of `dispose()` for GPU objects
391
+
392
+ Flag: `entity.destroy()` on entities with meshes/materials.
393
+
394
+ ```typescript
395
+ // ❌ BAD - GPU memory for geometry/materials/textures is leaked
396
+ entity.destroy();
397
+
398
+ // ✅ GOOD - Use dispose() for proper GPU cleanup
399
+ entity.dispose();
400
+ ```
401
+
402
+ ---
403
+
404
+ ## Confidence-Based Reporting
405
+
406
+ Only report issues you're confident about:
407
+
408
+ - **95%+ confidence**: Report as Critical
409
+ - **80-95% confidence**: Report as Warning
410
+ - **60-80% confidence**: Report as Suggestion
411
+ - **<60% confidence**: Don't report (too speculative)
412
+
413
+ ---
414
+
415
+ ## Output Format
416
+
417
+ ```markdown
418
+ ## IWSDK Project Code Review
419
+
420
+ ### Project Overview
421
+
422
+ - Entry point: [file]
423
+ - Systems: [list]
424
+ - Components: [list]
425
+ - Features enabled: [list from iwsdk.config.json]
426
+
427
+ ### Critical Issues
428
+
429
+ - **[filename:line]** Issue description
430
+ - Problem: `current code`
431
+ - Fix: `suggested fix`
432
+
433
+ ### Warnings
434
+
435
+ - **[filename:line]** Issue description
436
+
437
+ ### Suggestions
438
+
439
+ - **[filename:line]** Improvement suggestion
440
+
441
+ ### Feature Configuration Analysis
442
+
443
+ - locomotion: [enabled/disabled] - [assessment]
444
+ - physics: [enabled/disabled] - [assessment]
445
+ - grabbing: [enabled/disabled] - [assessment]
446
+
447
+ ### Summary
448
+
449
+ [Brief summary of overall code quality and key recommendations]
450
+ ```
@@ -0,0 +1,55 @@
1
+ ---
2
+ paths:
3
+ - "src/assets.ts"
4
+ - "src/assets.js"
5
+ - "src/scene-assets/**"
6
+ ---
7
+
8
+ # Asset manifest contract
9
+
10
+ `src/assets.ts` is imported **independently by the app runtime and the editor**,
11
+ in separate JS realms. It must therefore be deterministic and self-contained:
12
+
13
+ - no `World`, scene, iframe, editor object or DOM access
14
+ - no timers, no fetching ambient state
15
+ - no reliance on singleton object identity across realms
16
+ - prototypes immutable after registration, and never parented
17
+
18
+ A manifest entry is either a URL descriptor (`{ url, type, name?, priority? }`)
19
+ or a bare parentless `Object3D`. `AssetType` covers `GLTF`, `Audio`, `Texture`,
20
+ `HDRTexture`, `UIKitML`. Only glTF, UIKitML and `Object3D` entries are placeable
21
+ as scene content; audio/texture/HDR are for application systems.
22
+
23
+ Build public URLs from `import.meta.env.BASE_URL` so runtime, editor and subpath
24
+ builds resolve identically. A file in `public/` is **not** available to a scene
25
+ until it is registered here.
26
+
27
+ ## Procedural assets
28
+
29
+ Export a parentless `Object3D` from `src/scene-assets/*.scene-asset.ts` and
30
+ register it under a stable ID. The registry rejects an already-parented
31
+ prototype.
32
+
33
+ Every placement is a distinct hierarchy clone, but **geometry and materials stay
34
+ shared**. Never dispose them from a placed clone; world teardown owns their
35
+ lifetime. Reassigning `mesh.material` on a clone is fine and is how you restyle
36
+ one instance — mutating the shared material in place changes every instance.
37
+
38
+ Bounds come from `Box3` over the instantiated asset and drive placement,
39
+ selection, framing and scatter collision. Put the origin where composition wants
40
+ it (usually floor contact, or the object's own pivot), keep transforms finite,
41
+ and don't let invisible helpers inflate bounds.
42
+
43
+ ## Cost
44
+
45
+ Split tessellation by viewing distance rather than using one budget everywhere: a
46
+ close-range hero model and coarser display copies of the same form are two
47
+ prototypes from one factory function. Sphere/lathe segment counts dominate small
48
+ repeated detail more than people expect — check `renderStats.triangles` rather
49
+ than guessing.
50
+
51
+ Reuse material instances within a module. Prefer prefabs plus a deterministic
52
+ pattern for repetition; a pattern whose prefab resolves to a single component-free
53
+ mesh lowers to one `InstancedMesh`.
54
+
55
+ Start assets at `castShadow: false` and opt in only for grounded focal masses.