@iwsdk/create 0.5.3 → 1.0.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 (106) hide show
  1. package/dist/cli.js +7224 -216
  2. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/SKILL.md +311 -0
  3. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  4. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  5. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/SKILL.md +262 -0
  6. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  7. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  8. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  9. package/dist/guidance/{claude/.claude/skills/iwsdk-scene-composer → agents/.agents/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
  10. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  11. package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
  12. package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +69 -91
  13. package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
  14. package/dist/guidance/agents/.agents/skills/iwsdk-dev/SKILL.md +45 -0
  15. package/dist/guidance/{claude/.claude/skills/iwsdk-planner → agents/.agents/skills/iwsdk-dev}/references/api-reference.md +53 -45
  16. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/iterate.md +239 -0
  17. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/planner.md +303 -0
  18. package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +37 -114
  19. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/SKILL.md +177 -0
  20. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  21. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
  22. package/dist/guidance/agents/.agents/skills/iwsdk-native-xr-test/SKILL.md +246 -0
  23. package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -78
  24. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
  25. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
  26. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  27. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  28. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  29. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  30. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  31. package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +45 -136
  32. package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +251 -157
  33. package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +9 -6
  34. package/dist/guidance/claude/.claude/rules/scene-json.md +6 -4
  35. package/dist/guidance/claude/.claude/settings.json +6 -2
  36. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/SKILL.md +311 -0
  37. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  38. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  39. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/SKILL.md +262 -0
  40. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  41. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  42. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  43. package/dist/guidance/{agents/.agents/skills/iwsdk-scene-composer → claude/.claude/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
  44. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  45. package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
  46. package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +69 -91
  47. package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
  48. package/dist/guidance/claude/.claude/skills/iwsdk-dev/SKILL.md +45 -0
  49. package/dist/guidance/{agents/.agents/skills/iwsdk-planner → claude/.claude/skills/iwsdk-dev}/references/api-reference.md +53 -45
  50. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/iterate.md +239 -0
  51. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/planner.md +303 -0
  52. package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +37 -114
  53. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/SKILL.md +177 -0
  54. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  55. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
  56. package/dist/guidance/claude/.claude/skills/iwsdk-native-xr-test/SKILL.md +246 -0
  57. package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -78
  58. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
  59. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
  60. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  61. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  62. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  63. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  64. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  65. package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +45 -136
  66. package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +251 -157
  67. package/dist/guidance/claude/CLAUDE.md +2 -141
  68. package/dist/guidance/codex/.codex/config.toml +1 -1
  69. package/dist/guidance/common/AGENTS.md +96 -37
  70. package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +6 -4
  71. package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +6 -4
  72. package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +6 -4
  73. package/dist/template/common/README.md +13 -0
  74. package/dist/template/common/public/ui/welcome.uikitml +0 -19
  75. package/dist/template/common/src/robot.ts +5 -0
  76. package/dist/template/common/vite.config.ts +18 -0
  77. package/dist/template/common-js/README.md +13 -0
  78. package/dist/template/common-js/public/ui/welcome.uikitml +0 -19
  79. package/dist/template/common-js/src/robot.js +5 -0
  80. package/dist/template/common-js/vite.config.js +18 -0
  81. package/package.json +8 -7
  82. package/scripts/verify-release-ready.mjs +25 -0
  83. package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +0 -364
  84. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +0 -243
  85. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +0 -101
  86. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +0 -176
  87. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +0 -156
  88. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +0 -199
  89. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +0 -257
  90. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
  91. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
  92. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
  93. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
  94. package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +0 -364
  95. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +0 -243
  96. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +0 -101
  97. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +0 -176
  98. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +0 -156
  99. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +0 -199
  100. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +0 -257
  101. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
  102. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
  103. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
  104. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
  105. /package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
  106. /package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
@@ -1,208 +1,302 @@
1
1
  ---
2
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]'
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
5
  ---
6
6
 
7
- # UIKitML Asset Workflow
7
+ # IWSDK UI
8
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.
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.
13
12
 
14
- User request is in `$ARGUMENTS`.
13
+ ## Choose the required surface
15
14
 
16
- ## 1. Find the three stable identities
15
+ Before editing, classify the request:
17
16
 
18
- Every scene-authored panel has three different identities:
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.
19
22
 
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
+ Do not add placement, ScreenSpace, runtime state, or camera changes when the
24
+ request does not require them.
23
25
 
24
- Find or add the manifest entry in `src/assets.ts` and keep the source under
25
- `public/ui/`:
26
+ ## Fast path
26
27
 
27
- ```ts
28
- import { AssetType, defineAssets } from '@iwsdk/core';
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.
29
34
 
30
- const publicAssetUrl = (path: string) =>
31
- `${import.meta.env.BASE_URL}${path.replace(/^\/+/u, '')}`;
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.
32
39
 
33
- export default defineAssets({
34
- 'welcome-panel': {
35
- name: 'Welcome panel',
36
- type: AssetType.UIKitML,
37
- url: publicAssetUrl('ui/welcome.uikitml'),
38
- },
39
- });
40
- ```
40
+ Keep the three stable identities explicit:
41
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.
42
+ 1. manifest asset ID;
43
+ 2. scene node ID for a placed instance;
44
+ 3. UIKitML element IDs used by application code.
44
45
 
45
- ## 2. Reuse the managed editor
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.
46
49
 
47
- Run commands from the application directory. Reuse a command-ready session instead
48
- of starting a second server or browser:
50
+ ## Author the complete first pass
49
51
 
50
- ```bash
51
- npx iwsdk dev status
52
- npx iwsdk dev up --timeout 60000
53
- npx iwsdk ui assets --raw
54
- ```
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
+ - In the stock Horizon kit, assume `<Panel>` renders an opaque light surface;
58
+ start with dark primary and secondary text unless a preview proves otherwise.
59
+ - Remote fonts can reflow layout. Use a local font when offline availability is
60
+ a product requirement.
61
+ - Use plain ASCII punctuation in runtime status copy. Do not use em dashes,
62
+ smart quotes, or other typographic punctuation unless the chosen local font
63
+ has already rendered that exact glyph successfully.
55
64
 
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.
65
+ For a scene-authored instance, use asset content and an explicit transform. In
66
+ the stock starter composition, a front-facing UIKitML panel at negative Z faces
67
+ the default player with identity rotation. Do not add `rotationDeg: [0, 180, 0]`
68
+ unless the existing app establishes that convention or a measured render proves
69
+ it necessary.
58
70
 
59
- ## 3. Render the panel in isolation
71
+ The default XR player and an authored non-XR `hero` camera can be on opposite
72
+ sides of a single-sided panel. Preserve the transform required by the requested
73
+ player viewpoint; if an authored evidence camera sees the back face, move or aim
74
+ that camera instead of rotating the product UI away from the player.
60
75
 
61
- Use the editor-backed isolated renderer before debugging scene placement:
76
+ When adding UI to an established composition, preserve existing primary UI and
77
+ objects. Start from the app's scale and spacing. In the stock scaffold, use
78
+ roughly `0.25`-`0.32` scale for a secondary panel and keep a same-band panel at
79
+ least `0.75` world meters above the existing central panel, at the same or
80
+ greater depth. Prefer a centered safe region over fragile frame edges.
62
81
 
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
- ```
82
+ ## Connect runtime behavior
68
83
 
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
- ```
84
+ Resolve a scene-authored panel by scene node ID:
91
85
 
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
86
+ ```ts
87
+ const panel = world.requireSceneObject<UIKitMLAsset>('PanelNode');
88
+ const status = panel.requireElementById<UIKit.Text>('StatusText');
89
+ const action = panel.requireElementById('Btn_Action');
90
+ status.name = 'StatusText';
91
+ action.name = 'Btn_Action';
92
+ action.addEventListener('click', onAction);
93
+ cleanupFuncs.push(() => action.removeEventListener('click', onAction));
98
94
  ```
99
95
 
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
96
+ Assign exact runtime names when the request requires controls to be addressable.
97
+ Register listener cleanup. Do not locate panels by transient ECS index, manifest
98
+ URL, or internal document implementation details.
109
99
 
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.
100
+ For a small scene-authored state machine, use the public ECS surface directly;
101
+ do not inspect `node_modules` to rediscover these contracts:
113
102
 
114
- Key rules:
103
+ ```ts
104
+ export const PanelState = createComponent('PanelState', {
105
+ step: { type: Types.Int8, default: 0 },
106
+ complete: { type: Types.Boolean, default: false },
107
+ });
108
+ export default defineComponents([PanelState]);
109
+
110
+ class PanelSystem extends createSystem({
111
+ panel: { required: [PanelState] },
112
+ activated: { required: [ActionMarker, Pressed] },
113
+ }) {
114
+ init(): void {
115
+ this.queries.activated.subscribe('qualify', () => this.advance());
116
+ }
115
117
 
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.
118
+ private advance(): void {
119
+ const panel = this.queries.panel.entities.values().next().value;
120
+ if (panel == null) return;
121
+ // Read and write scalar fields with getValue/setValue, then update UIKit.
122
+ }
123
+ }
124
+ ```
123
125
 
124
- ### Reuse built-in kits, icons, and remote fonts
126
+ Query result `entities` is a `Set`; use iteration or
127
+ `entities.values().next().value`, never array indexing. `@iwsdk/core` re-exports
128
+ the Three.js types needed for visual feedback, and scene-authored systems may use
129
+ `Pressed` qualification plus the existing app's marker component. Clone shared
130
+ asset materials before per-instance color or emissive changes.
125
131
 
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:
132
+ Imported models can use material arrays or emissive-capable material subclasses
133
+ that do not satisfy a narrow `instanceof MeshStandardMaterial` check. For an
134
+ explicit whole-body state tint, traverse every `Mesh`, normalize its material to
135
+ an array, clone each material with `emissive` and `emissiveIntensity`, assign the
136
+ clones back, and update all of them. If an existing `emissiveMap` masks the
137
+ requested solid diagnostic color, clear that map on the clones and set
138
+ `needsUpdate`; do not alter shared source materials.
129
139
 
130
- ```json
131
- {
132
- "world": {
133
- "features": {
134
- "spatialUI": { "kit": "horizon" }
140
+ ```ts
141
+ object3D.traverse((child) => {
142
+ if (!(child instanceof Mesh)) return;
143
+ const source = Array.isArray(child.material) ? child.material : [child.material];
144
+ const clones = source.map((material) => material.clone());
145
+ child.material = Array.isArray(child.material) ? clones : clones[0];
146
+ for (const material of clones) {
147
+ if ('emissive' in material && 'emissiveIntensity' in material) {
148
+ const stateMaterial = material as MeshStandardMaterial;
149
+ stateMaterial.emissiveMap = null;
150
+ stateMaterial.needsUpdate = true;
151
+ stateMaterials.push(stateMaterial);
135
152
  }
136
153
  }
137
- }
154
+ });
138
155
  ```
139
156
 
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.
157
+ These are known public top-level exports: `createComponent`, `createSystem`,
158
+ `defineComponents`, `Types`, `Entity`, `Pressed`, `UIKitMLAsset`, `UIKit`,
159
+ `Color`, `Mesh`, `MeshStandardMaterial`, and `Object3D`. Import them directly
160
+ from `@iwsdk/core`. Typecheck the implementation; if an import fails, use the
161
+ compiler error or one focused IWSDK reference query. Do not inspect package
162
+ source, declarations, exports, or directories to reconfirm the export chain.
143
163
 
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.
164
+ For immersive XR, default to a world-space panel or attach contextual UI to the
165
+ object it controls. Use a thresholded `Follower` targeting `world.player.head`
166
+ only when compact global UI must remain discoverable. Do not head-lock menus,
167
+ reading surfaces, or persistent panels; reserve direct `world.playerHeadEntity`
168
+ parenting for tiny, transient, non-interactive markers that require exact view
169
+ alignment. Do not use `ScreenSpace` expecting it to remain camera-attached in
170
+ XR. See https://iwsdk.dev/concepts/spatial-ui/hud.html for the placement
171
+ guidance.
149
172
 
150
- After each edit:
173
+ Use `ScreenSpace` only for a real HUD requirement. Its dimensions and offsets are
174
+ CSS strings. Preserve the authored immersive transform and verify browser and XR
175
+ views independently when both modes matter.
151
176
 
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.
177
+ ## Verify with a bounded loop
155
178
 
156
- ## 6. Connect runtime behavior
179
+ Typecheck after the complete first slice, then start or reuse one managed
180
+ session. If no command-ready session exists, run `npx @iwsdk/cli dev up --open`
181
+ once. Do not call `dev --help`, separately call `dev open`, restart a healthy
182
+ session, start a second browser, or build a custom UIKit renderer.
157
183
 
158
- For a code-owned instance, keep the `UIKitMLAsset` returned by the asset manager:
184
+ 1. Run `npx @iwsdk/cli ui assets --raw` once to confirm registration.
185
+ 2. Render one isolated preview after the first complete layout:
159
186
 
160
- ```ts
161
- import { UIKitMLAsset } from '@iwsdk/core';
187
+ ```bash
188
+ npx @iwsdk/cli ui render-preview \
189
+ --input-json '{"assetId":"panel-id","width":800,"height":600}' \
190
+ --output-file artifacts/panel-preview.png
191
+ ```
162
192
 
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
- ```
193
+ Always provide `--output-file`; do not accept a temporary screenshot path
194
+ and add a separate copy step.
168
195
 
169
- For a scene-authored instance, resolve it by stable scene node ID after the level has
170
- loaded:
196
+ 3. If spatial placement matters, render the authored hero view once; use
197
+ `view` only for built-in presets:
171
198
 
172
- ```ts
173
- const panel = world.requireSceneObject<UIKitMLAsset>('welcome-panel-instance');
174
- const button = panel.requireElementById('xr-button');
175
- button.setProperties({ display: 'none' });
176
- ```
199
+ ```bash
200
+ npx @iwsdk/cli scene render-file \
201
+ --input-json '{"path":"public/scenes/main.iwsdk.scene.json","viewId":"hero"}' \
202
+ --output-file artifacts/scene-hero.png
203
+ ```
177
204
 
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.
205
+ Keep the full render result from this call so `visibleNodeIds`, validity,
206
+ framing, and the PNG are checked together. Do not pipe it through
207
+ `head`/`tail`/`grep` and rerun only to recover discarded metadata.
180
208
 
181
- ## ScreenSpace is product behavior
209
+ 4. Find the panel entity, then inspect its live UIKitML state before and after
210
+ exercising each required control through real pointer or XR input:
182
211
 
183
- Add `ScreenSpace` only when the experience genuinely needs a browser-camera HUD:
212
+ ```bash
213
+ npx @iwsdk/cli ecs find --input-json '{"namePattern":"^Welcome Panel$"}'
214
+ npx @iwsdk/cli ui inspect --input-json '{"entityIndex":12,"selector":"#Btn_Action"}'
215
+ ```
184
216
 
185
- ```ts
186
- entity.addComponent(ScreenSpace, {
187
- width: '420px',
188
- height: '240px',
189
- top: '20px',
190
- right: '20px',
191
- zOffset: 0.2,
192
- });
193
- ```
217
+ Replace the example pattern with the panel's authored scene/entity name, and
218
+ reuse the returned entity index rather than hard-coding the example value.
219
+
220
+ 5. Capture one final runtime preview from the intended viewpoint. Reuse a
221
+ required completion-state capture when it already provides that evidence.
194
222
 
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.
223
+ For common CLI verification, use these forms directly rather than discovery:
199
224
 
200
- ## Completion checklist
225
+ ```bash
226
+ npx @iwsdk/cli xr status
227
+ npx @iwsdk/cli xr enter --input-json '{}'
228
+ npx @iwsdk/cli xr look-at --input-json '{"device":"controller-right","target":{"x":0,"y":1.5,"z":-2}}'
229
+ npx @iwsdk/cli xr select --input-json '{"device":"controller-right","duration":0.2}'
230
+ npx @iwsdk/cli ecs find --input-json '{"withComponents":["ComponentName"]}'
231
+ npx @iwsdk/cli ecs query --input-json '{"entityIndex":12}'
232
+ npx @iwsdk/cli ui inspect --input-json '{"entityIndex":12,"selector":"#Btn_Action"}'
233
+ npx @iwsdk/cli browser logs --input-json '{"count":30}'
234
+ npx @iwsdk/cli browser reload --input-json '{}'
235
+ ```
236
+
237
+ For a file capture, use `npx @iwsdk/cli browser screenshot --output-file <path>`;
238
+ `browser_screenshot` does not accept an `outputPath` input field.
239
+
240
+ When a UI change requires a regression smoke for an existing
241
+ `DistanceGrabbable`, do not substitute a long `xr select` click. Aim at the
242
+ object, hold select with
243
+ `npx @iwsdk/cli xr set-select-value --input-json '{"device":"controller-right","value":1}'`,
244
+ query the entity while held to observe `Grabbed`, then release with the same
245
+ command and `"value":0`. Movement is unnecessary unless the request asks for
246
+ it.
247
+
248
+ The commands in this section are the supported path. Do not call broad
249
+ `iwsdk`, `ui`, `browser`, `ecs`, or `xr` help. If a shown command fails, use its
250
+ error output and the exact forms above to correct it instead of invoking
251
+ `--help`.
252
+
253
+ Batch layout fixes before rerendering. By default allow one isolated preview,
254
+ one authored-scene render, and one final runtime capture; add one replacement
255
+ preview only to verify a focused correction. Do not rerender after every small
256
+ edit, repeatedly restart the runtime, or use screenshots to debug input state.
257
+ Keep the whole task under roughly 80 tool calls by batching independent reads
258
+ and related state queries. Check console logs once after final behavior unless a
259
+ new edit creates a concrete reason to check again. Do not capture extra
260
+ diagnostic screenshots for states already proven by named queries.
261
+ For the final visual comparison, create one compact JPEG contact sheet with the
262
+ supplied baseline above the final live-runtime capture, then load only that one
263
+ image into model context. Do not load the full-size PNGs separately. On Windows,
264
+ substitute the two paths in this known command:
265
+
266
+ ```powershell
267
+ 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()'
268
+ ```
201
269
 
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.
270
+ `artifacts/ui-runtime-review.jpg` is the only image file to open with the Read
271
+ tool. Do not open isolated previews, hero renders, progress captures, completion
272
+ captures, the baseline PNG, or the final PNG separately.
273
+
274
+ Treat that contact sheet as a bounded layout sanity check, not a request to
275
+ visually prove every state detail. If it shows no blocking overlap, clipping,
276
+ unreadable primary UI, or accidental scene replacement, stop visual inspection.
277
+ Do not create follow-up zooms, crops, or object close-ups. Use the named ECS
278
+ state queries to prove interaction feedback; the evaluator will inspect the
279
+ saved progress and completion artifacts.
280
+
281
+ Render isolated, hero, progress, completion, and invalid-action files when the
282
+ task requires them, but do not open those files in model context; use render
283
+ metadata, named state queries, and file existence for those checks. After a
284
+ context compaction, continue from the measured state instead of rediscovering
285
+ package exports, CLI command families, or already accepted visual framing.
286
+
287
+ The final visual check must confirm:
288
+
289
+ - the complete panel is inside the expected frame;
290
+ - important text and controls remain readable at a compact preview size;
291
+ - primary text has clear contrast against the actual rendered surface;
292
+ - new UI does not touch or obscure existing primary UI or objects;
293
+ - required states differ through a coarse visible treatment, not only fine text.
294
+ When the task explicitly asks for visually distinct progress/completion or
295
+ success/error states, change at least a quarter of the panel surface (for
296
+ example a substantial header block or whole-surface tint) and/or a major
297
+ scene object's whole-body emissive treatment. A thin accent bar, small chips,
298
+ icons, and copy changes alone are not sufficient evidence.
299
+
300
+ Finish with a passing typecheck and production build, no UIKit parser/resource
301
+ errors, and concise runtime evidence. Remove temporary preview files or camera
302
+ workarounds that are not deliverables.
@@ -1,142 +1,3 @@
1
- # IWSDK project
1
+ # IWSDK project guidance
2
2
 
3
- A Vite + TypeScript or JavaScript app, but several things do **not** work the way
4
- a normal Vite project works. Read this section before assuming anything.
5
-
6
- Deeper material is path-scoped in `.claude/rules/` and loads automatically when
7
- you touch the matching files. `AGENTS.md` is the vendor-neutral copy for other
8
- agents; this file is the one Claude Code reads.
9
-
10
- ## What is not standard Vite
11
-
12
- **`iwsdk.config.json` is the project authority, not `vite.config.ts`.** It selects
13
- the active scene, the asset module, the component module, and all XR/world
14
- features. `vite.config.ts` only wires the plugin. Editing `iwsdk.config.json`
15
- restarts Vite in place; the managed window remains open and its command bridges
16
- reconnect automatically. Wait for `npx iwsdk dev status` to report
17
- `browserCommandReady: true` before issuing browser-backed commands.
18
-
19
- **`virtual:iwsdk-project` is a virtual module**, not a file. `src/index.ts` or
20
- `src/index.js` imports it and passes it whole to `World.create()`. Do not
21
- hand-build that options object.
22
-
23
- **The dev server is CLI-managed.** Use `npx iwsdk dev up` (or `npm run dev`), not
24
- `vite`. It launches a managed browser that hosts the MCP command bridge.
25
- `--no-open` intentionally starts only the server: status reports
26
- `browser.status: "not_launched"`, and browser-backed commands fail immediately
27
- with `browser_not_launched` plus restart guidance. One managed window hosts two
28
- roles, editor and runtime.
29
-
30
- **`src/assets.ts`/`src/assets.js` is evaluated twice, in two different JS
31
- realms** — once by the app runtime, once by the editor. It must be deterministic
32
- and side-effect free: no `World`, no DOM, no timers, no reliance on shared object
33
- identity.
34
-
35
- **Static geometry lives in TypeScript, composition lives in JSON.** Scene JSON
36
- never declares URLs, geometry or materials — only manifest IDs.
37
-
38
- **Components must be declared in a system-free module** and exported from
39
- `src/components.ts`/`src/components.js` via `defineComponents()`. The editor
40
- imports that same manifest to build its inspector, so a component that is not in
41
- it cannot be authored in scenes.
42
-
43
- **Import Three.js from `@iwsdk/core`, never from `three`.** `@iwsdk/core`
44
- re-exports all of Three; importing `three` directly creates a duplicate instance
45
- and subtle breakage. Exception: `import type { GLTF } from 'three/addons/...'`.
46
-
47
- ## Traps that produce silent failures
48
-
49
- | Trap | Symptom | Fix |
50
- | ------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
51
- | `locomotion: true` with no `LocomotionEnvironment` on a floor | player falls through the world | add the component to a walkable surface |
52
- | Scene origin left occupied | player spawns inside your geometry | the player origin is `0,0,0` unless the scene authors `player.transform` |
53
- | Scene JSON with `imports` | authoring preview works, but editable open and runtime load are rejected | run `npx iwsdk scene flatten` once, then edit the flat output (see `.claude/rules/scene-json.md`) |
54
- | `entity.destroy()` | GPU memory leaked | use `entity.dispose()` |
55
- | `setValue` on a Vec2/Vec3/Vec4/Color field | throws in elics 3.4.x | use `entity.getVectorView(...)` |
56
- | Environment component on a non-root entity | silently ignored | `DomeGradient`/`IBLGradient` go on the level root only |
57
- | Environment prop changed without `_needsUpdate` | change ignored | set `_needsUpdate` after writing |
58
- | `ScreenSpace` given numbers | clamped with a console warning | it takes CSS strings: `'400px'`, `'25vw'` |
59
- | `@iwsdk/reference` MCP tools in an old or `--no-install` app | queries report warmup required | run `npx iwsdk reference warmup`; fresh installed scaffolds do this during creation |
60
-
61
- ## Verify before you claim it works
62
-
63
- **Always `npx tsc --noEmit` before testing.** Type errors stop systems
64
- initialising without necessarily logging anything in the browser.
65
-
66
- Then check the right status for the task — these are not interchangeable:
67
-
68
- - scene/editor work → `scene_get_state`
69
- - XR device or session actions → `xr_get_session_status`
70
- - server readiness → `npx iwsdk dev status` (XR availability is not a server signal)
71
-
72
- When something is missing but the console is clean: call
73
- `browser_get_console_logs` with only `count` (a `level` filter hides errors), then
74
- `ecs_find_entities` to confirm the entity exists and carries the components you
75
- expect.
76
-
77
- The non-obvious part is which observation proves what: the **editor** render does
78
- not run application systems, so anything driven by a system must be verified with
79
- `browser_screenshot` (runtime), not `scene_screenshot` (editor).
80
-
81
- ## MCP and CLI are one surface, not two
82
-
83
- Nearly every capability exists both ways — `scene_render_file` and
84
- `npx iwsdk scene render-file`, `ecs_find_entities` and `npx iwsdk ecs find`.
85
- Discover CLI actions with the bare domain or domain help (`npx iwsdk scene` or
86
- `npx iwsdk scene --help`); both list that domain's actions.
87
-
88
- **The CLI is not a fallback for a dead bridge.** Both routes drive the same
89
- managed browser, so when `dev status` reports `browserConnected: false`,
90
- every scene/ecs/xr/browser/ui command fails either way. Only `dev status`,
91
- `dev logs` and `reference status` work without a browser.
92
-
93
- Choose by the shape of the call, not by availability:
94
-
95
- - **MCP** for one-off calls, and whenever you want the image returned inline.
96
- - **CLI** when you need to loop or script — rendering six views, or sampling a
97
- value twice to measure a rate — or when the response is big enough to be worth
98
- filtering before it reaches context. A render of a scene containing an
99
- instanced pattern returns an id for every expanded instance.
100
-
101
- CLI `--output-file` returns a **different payload shape** from the plain call:
102
- the result nests under `data.result` instead of `data`, and `renderStats` and the
103
- hashes are dropped. If you need a hash or triangle count, omit `--output-file`
104
- and filter the JSON instead.
105
-
106
- ## Skills
107
-
108
- Scene composition, UI authoring, physics, depth occlusion, grab and ray
109
- interaction testing, ECS frame-stepping, and end-to-end planning each have a
110
- skill under `.claude/skills/`. Their descriptions handle routing, so they are not
111
- restated here.
112
-
113
- The failure worth guarding against is improvising a domain that already has a
114
- skill because the naive approach looks tractable. Before hand-authoring scene
115
- JSON, a UIKitML panel, or a physics body, invoke the skill.
116
-
117
- ## Layout
118
-
119
- ```
120
- iwsdk.config.json project authority: scene, assets, components, world, dev
121
- src/index.ts|js World.create() + explicit system registration
122
- src/assets.ts|js defineAssets() — shared runtime/editor catalog
123
- src/components.ts|js defineComponents() — shared runtime/editor catalog
124
- src/scene-assets/ *.scene-asset.ts|js — parentless Object3D prototypes
125
- public/scenes/ *.iwsdk.scene.json — composition only
126
- public/ui/ *.uikitml — runtime-loaded panels
127
- ```
128
-
129
- No barrel `index.ts` files. Keep component declarations free of system, DOM and
130
- renderer imports; systems import the declarations, never the reverse.
131
-
132
- ## Conventions
133
-
134
- - Systems use queries, never manually tracked entity arrays.
135
- - Never allocate in `update()`. Allocate in `init()` as class properties.
136
- - Prefer `queries.x.subscribe('qualify', ...)` over polling state each frame.
137
- - Register every subscription teardown in `this.cleanupFuncs`.
138
- - Use `signal.peek()` in `update()`; `.value` adds per-frame subscription overhead.
139
- - Load assets through `AssetManager` / the manifest, never a raw `GLTFLoader`.
140
- - Create entities with `world.createTransformEntity(...)`, never `scene.add()`.
141
- - Use the `RayInteractable` component, never a manual `Raycaster`.
142
- - VR targets 72–90 fps: 11–14 ms per frame. Treat per-frame allocation as a bug.
3
+ @AGENTS.md
@@ -1,2 +1,2 @@
1
1
  # Codex MCP configuration is populated after dependencies are installed.
2
- # Run `npx iwsdk adapter sync --tools codex` to register local MCP servers.
2
+ # Run `npx @iwsdk/cli adapter sync --tools codex` to register local MCP servers.