@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.
- package/dist/cli.js +7224 -216
- package/dist/guidance/agents/.agents/skills/iwsdk-build-model/SKILL.md +311 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/SKILL.md +262 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/guidance/{claude/.claude/skills/iwsdk-scene-composer → agents/.agents/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
- package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
- package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +69 -91
- package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
- package/dist/guidance/agents/.agents/skills/iwsdk-dev/SKILL.md +45 -0
- package/dist/guidance/{claude/.claude/skills/iwsdk-planner → agents/.agents/skills/iwsdk-dev}/references/api-reference.md +53 -45
- package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/iterate.md +239 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/planner.md +303 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +37 -114
- package/dist/guidance/agents/.agents/skills/iwsdk-hosting/SKILL.md +177 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-native-xr-test/SKILL.md +246 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -78
- package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +45 -136
- package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +251 -157
- package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +9 -6
- package/dist/guidance/claude/.claude/rules/scene-json.md +6 -4
- package/dist/guidance/claude/.claude/settings.json +6 -2
- package/dist/guidance/claude/.claude/skills/iwsdk-build-model/SKILL.md +311 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/SKILL.md +262 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/guidance/{agents/.agents/skills/iwsdk-scene-composer → claude/.claude/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
- package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
- package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +69 -91
- package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
- package/dist/guidance/claude/.claude/skills/iwsdk-dev/SKILL.md +45 -0
- package/dist/guidance/{agents/.agents/skills/iwsdk-planner → claude/.claude/skills/iwsdk-dev}/references/api-reference.md +53 -45
- package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/iterate.md +239 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/planner.md +303 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +37 -114
- package/dist/guidance/claude/.claude/skills/iwsdk-hosting/SKILL.md +177 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-native-xr-test/SKILL.md +246 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -78
- package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +45 -136
- package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +251 -157
- package/dist/guidance/claude/CLAUDE.md +2 -141
- package/dist/guidance/codex/.codex/config.toml +1 -1
- package/dist/guidance/common/AGENTS.md +96 -37
- package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +6 -4
- package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +6 -4
- package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +6 -4
- package/dist/template/common/README.md +13 -0
- package/dist/template/common/public/ui/welcome.uikitml +0 -19
- package/dist/template/common/src/robot.ts +5 -0
- package/dist/template/common/vite.config.ts +18 -0
- package/dist/template/common-js/README.md +13 -0
- package/dist/template/common-js/public/ui/welcome.uikitml +0 -19
- package/dist/template/common-js/src/robot.js +5 -0
- package/dist/template/common-js/vite.config.js +18 -0
- package/package.json +8 -7
- package/scripts/verify-release-ready.mjs +25 -0
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +0 -364
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +0 -243
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +0 -101
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +0 -176
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +0 -156
- package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +0 -199
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +0 -257
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
- package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +0 -364
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +0 -243
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +0 -101
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +0 -176
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +0 -156
- package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +0 -199
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +0 -257
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
- package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
- /package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
- /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:
|
|
4
|
-
argument-hint: '
|
|
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
|
-
#
|
|
7
|
+
# IWSDK UI
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
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
|
-
|
|
13
|
+
## Choose the required surface
|
|
15
14
|
|
|
16
|
-
|
|
15
|
+
Before editing, classify the request:
|
|
17
16
|
|
|
18
|
-
|
|
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
|
-
|
|
21
|
-
|
|
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
|
-
|
|
25
|
-
`public/ui/`:
|
|
26
|
+
## Fast path
|
|
26
27
|
|
|
27
|
-
|
|
28
|
-
|
|
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
|
-
|
|
31
|
-
|
|
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
|
-
|
|
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
|
-
|
|
43
|
-
|
|
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
|
-
|
|
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
|
-
|
|
48
|
-
of starting a second server or browser:
|
|
50
|
+
## Author the complete first pass
|
|
49
51
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
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
|
-
|
|
57
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
```
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
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
|
-
|
|
101
|
-
|
|
102
|
-
|
|
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
|
-
|
|
111
|
-
|
|
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
|
-
|
|
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
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
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
|
-
|
|
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
|
-
|
|
127
|
-
|
|
128
|
-
|
|
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
|
-
```
|
|
131
|
-
{
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
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
|
-
|
|
141
|
-
|
|
142
|
-
|
|
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
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
```
|
|
161
|
-
|
|
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
|
-
|
|
164
|
-
|
|
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
|
-
|
|
170
|
-
|
|
196
|
+
3. If spatial placement matters, render the authored hero view once; use
|
|
197
|
+
`view` only for built-in presets:
|
|
171
198
|
|
|
172
|
-
```
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
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
|
-
|
|
179
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
186
|
-
entity.
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
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
|
-
|
|
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.
|