@iwsdk/create 1.1.0-rc.0 → 1.1.0-rc.2

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 (60) hide show
  1. package/dist/cli.js +8 -13
  2. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/SKILL.md +16 -2
  3. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
  4. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-format.md +6 -0
  5. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/api-reference.md +56 -33
  6. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/iterate.md +24 -5
  7. package/dist/guidance/agents/.agents/skills/iwsdk-glasses-test/SKILL.md +281 -0
  8. package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +24 -1
  9. package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +3 -1
  10. package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +25 -2
  11. package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +73 -6
  12. package/dist/guidance/claude/.claude/rules/assets-and-manifest.md +2 -0
  13. package/dist/guidance/claude/.claude/rules/ecs-api.md +1 -1
  14. package/dist/guidance/claude/.claude/rules/scene-json.md +3 -1
  15. package/dist/guidance/claude/.claude/rules/uikitml.md +5 -0
  16. package/dist/guidance/claude/.claude/settings.json +1 -0
  17. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/SKILL.md +16 -2
  18. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
  19. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-format.md +6 -0
  20. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/api-reference.md +56 -33
  21. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/iterate.md +24 -5
  22. package/dist/guidance/claude/.claude/skills/iwsdk-glasses-test/SKILL.md +281 -0
  23. package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +24 -1
  24. package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +3 -1
  25. package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +25 -2
  26. package/dist/guidance/common/AGENTS.md +25 -12
  27. package/dist/guidance/copilot/.github/instructions/assets-and-manifest.instructions.md +2 -0
  28. package/dist/guidance/copilot/.github/instructions/ecs-api.instructions.md +1 -1
  29. package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +3 -1
  30. package/dist/guidance/copilot/.github/instructions/uikitml.instructions.md +5 -0
  31. package/dist/guidance/cursor/.cursor/rules/assets-and-manifest.mdc +2 -0
  32. package/dist/guidance/cursor/.cursor/rules/ecs-api.mdc +1 -1
  33. package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +3 -1
  34. package/dist/guidance/cursor/.cursor/rules/uikitml.mdc +5 -0
  35. package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +3 -1
  36. package/dist/guidance/scoped-agents/public/ui/AGENTS.md +5 -0
  37. package/dist/guidance/scoped-agents/src/AGENTS.md +3 -1
  38. package/dist/template/common/README.md +19 -0
  39. package/dist/template/common/public/ui/label-grab.uikitml +57 -0
  40. package/dist/template/common/public/ui/label-select.uikitml +57 -0
  41. package/dist/template/common/public/ui/label-spin.uikitml +57 -0
  42. package/dist/template/common/public/ui/welcome.uikitml +33 -32
  43. package/dist/template/common/src/assets.ts +32 -23
  44. package/dist/template/common/src/scene-assets/decor.scene-asset.ts +781 -0
  45. package/dist/template/common/src/scene-assets/studio.scene-asset.ts +298 -0
  46. package/dist/template/common-js/README.md +19 -0
  47. package/dist/template/common-js/public/ui/label-grab.uikitml +57 -0
  48. package/dist/template/common-js/public/ui/label-select.uikitml +57 -0
  49. package/dist/template/common-js/public/ui/label-spin.uikitml +57 -0
  50. package/dist/template/common-js/public/ui/welcome.uikitml +33 -32
  51. package/dist/template/common-js/src/assets.js +20 -23
  52. package/dist/template/common-js/src/scene-assets/decor.scene-asset.js +554 -0
  53. package/dist/template/common-js/src/scene-assets/studio.scene-asset.js +236 -0
  54. package/dist/template/scenes/ar.iwsdk.scene.json +354 -58
  55. package/dist/template/scenes/immersive.iwsdk.scene.json +435 -54
  56. package/package.json +4 -4
  57. package/dist/template/common/public/gltf/webxr-banner/banner.gltf +0 -68
  58. package/dist/template/common/public/textures/webxr.png +0 -0
  59. package/dist/template/common-js/public/gltf/webxr-banner/banner.gltf +0 -68
  60. package/dist/template/common-js/public/textures/webxr.png +0 -0
@@ -0,0 +1,281 @@
1
+ ---
2
+ name: iwsdk-glasses-test
3
+ description: Test an IWSDK app for Meta VR Glasses — gaze-and-pinch input, the glasses' narrower field of view, and gaze preview on a Quest without eye tracking. Use when the user targets Meta VR Glasses, asks for gaze or eye-tracking input, or wants to check that content fits the glasses' view.
4
+ argument-hint: '[test scenario]'
5
+ ---
6
+
7
+ # Test for Meta VR Glasses
8
+
9
+ Meta VR Glasses run the same WebXR app as Quest, with two differences that
10
+ break untested apps: a much narrower field of view, and gaze-and-pinch input
11
+ (look at a target, pinch either hand to select it). Prove both with the
12
+ desktop emulator first; use a Quest only for what the emulator cannot show.
13
+
14
+ The requested scenario is in `$ARGUMENTS`.
15
+
16
+ ## What differs from Quest
17
+
18
+ | Property | Meta VR Glasses |
19
+ | ------------- | ------------------------------------------------------------------------------------------------ |
20
+ | Field of view | 37° left and right, 25° up, 43° down from the view direction (74° × 68°), the same for both eyes |
21
+ | Primary input | One gaze ray (`targetRayMode: "gaze"`) picks the target; a pinch from either hand selects |
22
+ | Other input | Hands; hand and controller far rays take over whenever gaze is disconnected |
23
+ | Frame rates | 72, 90, 96, 100, 120 Hz |
24
+ | Session modes | `immersive-vr` and `immersive-ar`, with the same features as Quest 3 plus `gaze-tracking` |
25
+ | Gaze cursor | None in production: each target must show its own hover and pressed feedback |
26
+
27
+ Because the view is short above eye level (25°) and tall below it (43°), put
28
+ UI and key targets level with or slightly below the eyes and near the middle.
29
+ Content that Quest shows comfortably at 40° to the side or 30° up is out of
30
+ view on the glasses.
31
+
32
+ ## 1. Configure the project
33
+
34
+ In `iwsdk.config.json`, request gaze and hands, and select the glasses
35
+ emulator profile:
36
+
37
+ ```json
38
+ {
39
+ "world": {
40
+ "xr": {
41
+ "features": {
42
+ "handTracking": true,
43
+ "gazeTracking": true
44
+ }
45
+ }
46
+ },
47
+ "dev": {
48
+ "emulator": { "device": "metaVRGlasses" }
49
+ }
50
+ }
51
+ ```
52
+
53
+ - Keep `gazeTracking` optional (`true`). `{ "required": true }` makes a
54
+ runtime without gaze reject the whole session. The same holds for
55
+ `handTracking`: keep it `true` unless the app cannot work without hands.
56
+ - `gazeTracking` is what registers `GazeSystem`. `world.features.gaze` only
57
+ tunes it; it does not enable gaze on its own.
58
+ - Targets need no gaze-specific code: `RayInteractable`, `DistanceGrabbable`,
59
+ UIKit controls and the `Hovered` and `Pressed` tags work for gaze as they do
60
+ for hand rays.
61
+ - While testing, `world.features.gaze.showDebugReticle: true` draws a white
62
+ hit reticle. Remove it before shipping.
63
+
64
+ Editing `iwsdk.config.json` restarts Vite in place and reloads the page, which
65
+ ends any XR session: enter XR again afterwards. Run
66
+ `npm run --if-present typecheck`, then `npx @iwsdk/cli dev up` (or wait for
67
+ `npx @iwsdk/cli dev status` to report `browserCommandReady: true` if it is
68
+ already running).
69
+
70
+ ## 2. Confirm the glasses profile
71
+
72
+ ```bash
73
+ npx @iwsdk/cli xr status
74
+ npx @iwsdk/cli xr enter # only when no session is active
75
+ npx @iwsdk/cli xr status # sessionActive must now be true
76
+ npx @iwsdk/cli xr get-device-state
77
+ ```
78
+
79
+ Continue only when `xr status` reports `deviceName: "Meta VR Glasses"` and,
80
+ with the session active, `enabledFeatures` contains `"gaze-tracking"`, and
81
+ `xr get-device-state` has a `gaze` entry with `connected: true`. With the
82
+ Quest 3 profile, `deviceName` is `Meta Quest 3` and there is no `gaze` entry:
83
+ fix `dev.emulator.device` and re-check. `xr enter` can return
84
+ `success: true` even when the session request fails (for example, a required
85
+ feature the profile lacks), so always confirm `sessionActive`.
86
+
87
+ Neither command reports the glasses' field of view. The `fov` value in
88
+ `xr get-device-state` (90) is the emulator preview's vertical angle and is the
89
+ same for every profile. The glasses' view shows up as a black mask around the
90
+ runtime screenshot in step 3.
91
+
92
+ ## 3. Check the field of view
93
+
94
+ List every element the user must see or reach (panels, buttons, targets,
95
+ instructions). `npx @iwsdk/cli xr list-targets` lists the interactables with
96
+ box centres and sizes; `npx @iwsdk/cli scene runtime-hierarchy` lists every
97
+ named object with its `uuid`, including labels and panels. Read each
98
+ element's position with
99
+ `npx @iwsdk/cli scene transform --input-json '{"uuid":"<uuid>"}'` and use
100
+ `positionRelativeToXROrigin`, which is in the same frame as the headset pose
101
+ in `xr get-device-state`. (`ecs query` returns the `Transform` relative to the
102
+ parent entity, not a world position.)
103
+
104
+ With the headset looking straight ahead (identity orientation, down −Z) and
105
+ the element at offset `(dx, dy, dz)` from the headset (`dz` negative, in
106
+ front):
107
+
108
+ - horizontal angle `atan2(dx, -dz)` must be within ±37°;
109
+ - vertical angle `atan2(dy, -dz)` must be between −43° and +25°.
110
+
111
+ Both angles are measured against the view axis, as the glasses' projection
112
+ and the emulator's mask are. Do not use the elevation
113
+ `atan2(dy, hypot(dx, dz))`: it under-reports the vertical angle of anything
114
+ off to the side. A point 35° to the side and 46° below the view axis is out
115
+ of view, but its elevation is only −40°.
116
+
117
+ Check corners, not just centres, and leave a few degrees of margin. For
118
+ objects, use the box corners from `xr list-targets`. For a UIKitML panel,
119
+ `npx @iwsdk/cli ui inspect --input-json '{"entityIndex":<n>}'` reports
120
+ `panel.computedSize` in centimetres; multiply by the panel's `globalScale`
121
+ from `scene transform` (or use `targetSize`, in metres, when it is not 0×0),
122
+ then place the rectangle at the panel's position with its rotation.
123
+ `xr list-targets` boxes for UIKit panels can be inflated, so do not use them
124
+ for panel corners.
125
+
126
+ Then capture one runtime image as visual evidence:
127
+
128
+ ```bash
129
+ npx @iwsdk/cli browser screenshot --output-file /tmp/glasses-fov.png
130
+ ```
131
+
132
+ Everything outside the glasses' view is masked black in the image. In the
133
+ default managed session, IWER's control panels cover the left and right of
134
+ the image and can hide content near the edges of the view. For an
135
+ unobstructed image, restart with `npx @iwsdk/cli dev restart --ai-mode agent`
136
+ (headless, no control panels). Tell the developer before switching modes.
137
+
138
+ Use the runtime screenshot, not `scene_screenshot`: the editor camera does not
139
+ use the glasses' view. Content clipped in the image or outside the angles
140
+ above must move closer to the view centre (or lower, rather than higher).
141
+
142
+ ## 4. Test gaze and pinch
143
+
144
+ Gaze picks the target; hands only pinch. Switch to hands, and record what is
145
+ hovered before aiming so the check shows a change:
146
+
147
+ ```bash
148
+ npx @iwsdk/cli xr set-input-mode --input-json '{"mode":"hand"}'
149
+ npx @iwsdk/cli ecs find --input-json '{"withComponents":["Hovered"]}'
150
+ npx @iwsdk/cli xr look-at --input-json '{"device":"gaze","target":{"x":0,"y":1.2,"z":-2}}'
151
+ npx @iwsdk/cli ecs find --input-json '{"withComponents":["Hovered"]}'
152
+ ```
153
+
154
+ Aim at a point on the target's visible surface. A box centre from
155
+ `xr list-targets` works for solid objects, but the centre of a ring or frame
156
+ is empty and the gaze ray passes through it. After aiming, `ecs find` must
157
+ list the target entity with `Hovered` (or the app must show its own hover
158
+ state). The default gaze looks straight ahead, so whatever is in front may
159
+ already be hovered: aim at another target first and show `Hovered` move.
160
+
161
+ - **Click or UIKit button:** `xr select` with `{"device":"hand-right"}`,
162
+ keeping the default `duration`. A click needs press and release within
163
+ 300 ms: `xr select` with a long `duration` (for example 1 s), or
164
+ `xr set-select-value` 1 then 0, shows `Pressed` (and the button's `active`
165
+ state in `ui inspect`) but never clicks. Query the resulting app state
166
+ afterwards. A select that ends the session, such as an Exit button, returns
167
+ `runtime_command_failed` ("The XR session ended.") even though it worked:
168
+ confirm with `xr status`. For a target that reacts to `Pressed` rather than
169
+ a click, the tag only lasts for the press: run
170
+ `xr select` with `"duration":2` in the background and `ecs find` `Pressed`
171
+ during the hold.
172
+ - **Hold, grab or drag:** `xr set-select-value` with
173
+ `{"device":"hand-right","value":1}`, move the hand with `xr set-transform`
174
+ or `xr animate-to`, query while held (`Pressed`, `Grabbed`, the transform),
175
+ then release with `value: 0` and query again. With the default
176
+ `pointerTransformFollowsHand`, a gaze-started grab follows the pinching
177
+ hand's movement, not the gaze.
178
+ - **Either hand:** repeat one selection with `hand-left`; both hands commit.
179
+
180
+ Gaze reports `pointerType === "ray"` with `source: "gaze"` in its pointer
181
+ state, so the app's ordinary ray handlers receive it.
182
+
183
+ ## 5. Test fallback and priority
184
+
185
+ ```bash
186
+ npx @iwsdk/cli xr set-connected --input-json '{"device":"gaze","connected":false}'
187
+ ```
188
+
189
+ With gaze disconnected, hand far rays must target and select again (aim a hand
190
+ with `xr look-at` and select). Reconnect gaze with `"connected":true` and
191
+ confirm it owns targeting again: the hand ray's hover is dropped and the gaze
192
+ target is hovered. A near touch or grab with either hand suppresses gaze while
193
+ it lasts; test that when the app mixes near and far interaction.
194
+
195
+ Read the console with `npx @iwsdk/cli browser logs` (no level filter) and keep
196
+ the `[iwsdk][gaze]` lines. `browser logs` works on the managed browser only: a
197
+ physical headset target returns `unsupported_on_target`, so on a Quest read the
198
+ console through Chrome remote debugging
199
+ (`adb -s <serial> forward tcp:9222 localabstract:chrome_devtools_remote`, then
200
+ `chrome://inspect`).
201
+
202
+ | Message | Meaning |
203
+ | ------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
204
+ | `'gaze-tracking' granted for this session` | The runtime granted the feature |
205
+ | `'gaze-tracking' was NOT granted` | The runtime refused the feature |
206
+ | `gaze XRInputSource appeared` | A gaze source is present (also after a reconnect) |
207
+ | `eye pose is valid — real gaze data is flowing` | Real eye tracking is delivering poses |
208
+ | `emulated gaze pose is valid` | The emulator or a Quest mode supplies synthetic gaze: expected in testing |
209
+ | `the gaze XRInputSource disappeared` | Gaze disconnected; hand and controller far rays target |
210
+ | `no XRInputSource with targetRayMode === "gaze"` | No gaze source appeared within 3 s of session start |
211
+ | `getPose(targetRaySpace) returned null` | The source has no valid pose |
212
+ | `mapping XRTargetRaySpace onto the head pose` | On real glasses, the runtime returned head-directed gaze: a runtime problem, not an app one |
213
+ | `emulated gaze still points where the head does` | Emulated gaze has not been aimed yet: aim it with `xr look-at` |
214
+ | `target-device preview is intentionally providing ...` | The hands-on Quest preview (step 6) is running: expected |
215
+ | `renderer has no XRFrame or reference space yet` | Printed once at session start on Quest; a problem only if it repeats |
216
+
217
+ ## 6. On a Quest headset (optional)
218
+
219
+ Quest 3 and 3S have no eye tracking, so a Quest checks real rendering, frame rate
220
+ and native hands, not gaze accuracy. In both modes below the headset renders
221
+ its own, wider field of view (about 45° to 49° to each side, 48° up and 50°
222
+ down on a Quest 3S), and `xr get-device-state` reports the emulator's
223
+ synthetic `fov: 90`. Keep using step 3 for framing.
224
+
225
+ - **Hands-on preview:** add `"targetDevicePreview": { "gazeSimulation": "head" }`
226
+ under `dev` (the app must request `gazeTracking`) and run
227
+ `npx @iwsdk/cli dev up` without `--native-xr-control`. On Quest Browser,
228
+ the dev server keeps the browser's own viewer, hands and controllers and
229
+ adds a gaze source that follows the head; while it is connected, hand and
230
+ controller far rays are off. The user looks at a target and pinches with a
231
+ real hand. It is dev-server only and left out of production builds.
232
+ - Opening the app: the dev server uses HTTPS with a self-signed
233
+ certificate. On the same Wi-Fi, open a `data.runtimeUrls.network` URL and
234
+ accept the certificate warning. Over USB, run
235
+ `adb -s <serial> reverse tcp:<port> tcp:<port>` and open
236
+ `https://localhost:<port>/` (`http://` does not connect) and accept the
237
+ warning, or set `iwsdkDev({ https: false })` in `vite.config.ts` to serve
238
+ HTTP: `http://localhost` through `adb reverse` is a secure context, so
239
+ there is no warning.
240
+ - Enter XR with the app's Enter XR button or the browser's Enter VR
241
+ button; this mode does not enter on its own. The first entry for each
242
+ origin (`http://` and `https://` are separate) shows Quest Browser's
243
+ hand-tracking permission prompt: ask the user to choose Allow.
244
+ - To read state from the CLI, pair the page first: open the URL from
245
+ `runtime pair-headset` and use its physical `runtimeTarget` as in
246
+ `iwsdk-native-xr-test`. `ecs find`, `ecs query`, `xr status` and
247
+ `xr look-at` with `"device":"gaze"` work (look-at sets the gaze direction
248
+ relative to the head). Hand, controller and headset commands such as
249
+ `xr select` and `xr set-transform` report success but do nothing in this
250
+ mode, and `xr get-device-state` lists hands and controllers the session
251
+ does not have: only a real pinch selects.
252
+ - **Scripted run:** follow the `iwsdk-native-xr-test` skill with
253
+ `dev.emulator.device` set to `metaVRGlasses`. `dev up --native-xr-control`
254
+ replaces the headset's inputs with the glasses profile (synthetic
255
+ controllers or hands, plus a gaze source), so steps 4 and 5 run on the
256
+ device with each command's `runtimeTarget`; only `browser logs` is
257
+ unavailable there (see step 5). `targetDevicePreview` is ignored in that
258
+ mode.
259
+
260
+ ## Rules
261
+
262
+ - Do not treat head-directed gaze (the preview, or the emulator's **Head**
263
+ gaze mode) as proof of eye-tracking accuracy. It proves the interaction
264
+ plumbing only.
265
+ - Do not add a head-pose fallback for missing gaze in production code: when
266
+ gaze is unavailable, IWSDK hands targeting back to hand and controller rays.
267
+ - Do not move gaze with `set-transform` position: gaze takes orientation only
268
+ and its origin follows the headset.
269
+ - Do not claim a fit from a Quest screenshot or the editor view; only the
270
+ glasses profile in the desktop emulator has the narrower field of view.
271
+
272
+ ## Report
273
+
274
+ - emulator device and enabled XR features (gaze granted or not);
275
+ - each checked element with its horizontal and vertical angles, and any that
276
+ fall outside the glasses' view;
277
+ - each gaze target: hover evidence, the pinch used, and the state change;
278
+ - fallback result with gaze disconnected;
279
+ - `[iwsdk][gaze]` console lines and other errors;
280
+ - for a headset run, its serial, which Quest mode was used, and whether the
281
+ page was paired.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: iwsdk-grab
3
- description: Use emulated XR controllers to verify proximity grabbing for OneHandGrabbable and TwoHandsGrabbable objects. Use for pick up, move, release, or regression-test requests involving near-hand grab with the squeeze button.
3
+ description: Use emulated XR controllers or hands to verify proximity grabbing for OneHandGrabbable and TwoHandsGrabbable objects. Use for pick up, move, release, or regression-test requests involving near-hand grab with the squeeze button or a hand pinch.
4
4
  argument-hint: '(use the current request)'
5
5
  ---
6
6
 
@@ -36,6 +36,29 @@ Do not use trigger index `0`, `xr select`, or teleport-style device mutation for
36
36
  proximity grab. Do not edit source merely to make an existing named entity easier
37
37
  to locate; report missing runtime identity when that is the actual defect.
38
38
 
39
+ ## Hand pinch grab
40
+
41
+ When the user asks for hands or a pinch, grab with the emulated hand instead of
42
+ squeeze. This needs `grabbing.useHandPinchForGrab`, which is on unless the project
43
+ manifest sets it to `false`.
44
+ Switch input once, then grab and carry in one sequence, by the entity's name
45
+ from `xr list-targets`:
46
+
47
+ ```bash
48
+ npx @iwsdk/cli xr set-input-mode --input-json '{"mode":"hand"}'
49
+ npx @iwsdk/cli xr run-sequence --input-json '{"device":"hand-right","steps":[{"target":"Requested Name","approach":{"distance":0.06},"pinch":{"value":1,"at":"arrival"}},{"position":{"x":0.3,"y":1,"z":-1.2},"depart":{"distance":0.08}}]}' --timeout 45000
50
+ ```
51
+
52
+ While the hand holds something, a step `position` is where the object's base
53
+ goes. Query `Grabbed` while held, then let go and query the final transform:
54
+
55
+ ```bash
56
+ npx @iwsdk/cli xr run-sequence --input-json '{"device":"hand-right","steps":[{"pinch":0,"duration":0.15}]}'
57
+ ```
58
+
59
+ The sequence result lists the select events the application saw; a missing
60
+ `selectstart` means the pinch never reached the object.
61
+
39
62
  ## Evidence and stopping
40
63
 
41
64
  Prefer measured ECS state over screenshots. Capture one runtime image only when
@@ -17,7 +17,9 @@ distance grabs share aiming but not input duration or movement behavior.
17
17
  `requireElementById`; use a project test hook only when no addressable runtime
18
18
  target exists.
19
19
  3. Aim the requested controller with `xr look-at`. Do not translate the
20
- controller toward a ray target.
20
+ controller toward a ray target. The transform of an open shape (a ring, a
21
+ knot) can sit in empty space: aim at its surface, such as the rim at
22
+ transform + (0, radius, 0), and confirm `Hovered` before pressing.
21
23
 
22
24
  ## Select exactly one branch
23
25
 
@@ -54,8 +54,17 @@ JSON representation.
54
54
  - Prefer supported explicit properties over CSS shorthand.
55
55
  - Reuse the configured Horizon kit and bundled Lucide icons instead of
56
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.
57
+ - Production builds keep only the Lucide icons named in static
58
+ `public/**/*.uikitml` files. UIKitML built or fetched at runtime (a string in
59
+ `src/`, a file outside `public/`, a remote URL) works in `npm run dev` but
60
+ fails after `npm run build` with `Unknown component <Settings>` and a hint.
61
+ List those icons by component name in `vite.config.ts`:
62
+ `iwsdkDev({ bundle: { icons: ['Settings'] } })` (`'all'` keeps all ~1,600,
63
+ about 4 MB more). Check dynamic UIKitML in a production build.
64
+ - In the stock Horizon kit, `<Panel>` renders an opaque surface that follows
65
+ the color scheme: dark at runtime when `spatialUI.preferredColorScheme` is
66
+ `dark` (the scaffold default), white in editor previews. Give text a dark
67
+ color plus a light `:dark` variant, as `public/ui/welcome.uikitml` does.
59
68
  - Remote fonts can reflow layout. Use a local font when offline availability is
60
69
  a product requirement.
61
70
  - Use plain ASCII punctuation in runtime status copy. Do not use em dashes,
@@ -245,6 +254,20 @@ query the entity while held to observe `Grabbed`, then release with the same
245
254
  command and `"value":0`. Movement is unnecessary unless the request asks for
246
255
  it.
247
256
 
257
+ When the request asks for a poke (near touch) on a control, press it with the
258
+ emulated hand's index fingertip by its element ID. The panel entity needs
259
+ `PokeInteractable`:
260
+
261
+ ```bash
262
+ npx @iwsdk/cli xr set-input-mode --input-json '{"mode":"hand"}'
263
+ npx @iwsdk/cli xr run-sequence --input-json '{"device":"hand-right","steps":[{"target":"Btn_Action","press":{}}]}' --timeout 45000
264
+ ```
265
+
266
+ The press clicked when `presses[0].contactMs` is below 800; at 800 or more a
267
+ slow headless frame held the touch too long, so run the press once more. Confirm
268
+ the state change with `ui inspect`. `xr list-targets` lists the element IDs that
269
+ can be pressed.
270
+
248
271
  The commands in this section are the supported path. Do not call broad
249
272
  `iwsdk`, `ui`, `browser`, `ecs`, or `xr` help. If a shown command fails, use its
250
273
  error output and the exact forms above to correct it instead of invoking
@@ -70,17 +70,18 @@ and subtle breakage. Exception: `import type { GLTF } from 'three/addons/...'`.
70
70
 
71
71
  ## Traps that produce silent failures
72
72
 
73
- | Trap | Symptom | Fix |
74
- | ------------------------------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
75
- | `locomotion: true` with no `LocomotionEnvironment` on a floor | player falls through the world | add the component to a walkable surface |
76
- | Scene origin left occupied | player spawns inside your geometry | the player origin is `0,0,0` unless the scene authors `player.transform` |
77
- | Scene JSON with `imports` | authoring preview works, but editable open and runtime load are rejected | run `npx @iwsdk/cli scene flatten` once, then edit the flat output |
78
- | `entity.destroy()` | GPU memory leaked | use `entity.dispose()` |
79
- | `setValue` on a Vec2/Vec3/Vec4/Color field | throws in elics 3.4.x | use `entity.getVectorView(...)` |
80
- | Environment component on a non-root entity | silently ignored | `DomeGradient`/`IBLGradient` go on the level root only |
81
- | Environment prop changed without `_needsUpdate` | change ignored | set `_needsUpdate` after writing |
82
- | `ScreenSpace` given numbers | clamped with a console warning | it takes CSS strings: `'400px'`, `'25vw'` |
83
- | `@iwsdk/reference` MCP tools in an old or `--no-install` app | queries report warmup required | run `npx @iwsdk/cli reference warmup`; fresh installed scaffolds do this during creation |
73
+ | Trap | Symptom | Fix |
74
+ | -------------------------------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
75
+ | `locomotion: true` with no `LocomotionEnvironment` on a floor | player falls through the world | add the component to a walkable surface |
76
+ | Scene origin left occupied | player spawns inside your geometry | the player origin is `0,0,0` unless the scene authors `player.transform` |
77
+ | Scene JSON with `imports` | authoring preview works, but editable open and runtime load are rejected | run `npx @iwsdk/cli scene flatten` once, then edit the flat output |
78
+ | `entity.destroy()` | GPU memory leaked | use `entity.dispose()` |
79
+ | `setValue` on a Vec2/Vec3/Vec4/Color field | throws in elics 3.4.x | use `entity.getVectorView(...)` |
80
+ | Environment component on a non-root entity | silently ignored | `DomeGradient`/`IBLGradient` go on the level root only |
81
+ | `DomeFade` with no `DomeGradient` on the level root | no fade; the floor keeps its hard edge | add a `DomeGradient` (render stats report the DomeFade `inactiveReason`) |
82
+ | `DomeTexture`/`IBLTexture` prop changed without `_needsUpdate` | change ignored | set `_needsUpdate` after writing; `DomeGradient`/`IBLGradient` apply edits without it |
83
+ | `ScreenSpace` given numbers | clamped with a console warning | it takes CSS strings: `'400px'`, `'25vw'` |
84
+ | `@iwsdk/reference` MCP tools in an old or `--no-install` app | queries report warmup required | run `npx @iwsdk/cli reference warmup`; fresh installed scaffolds do this during creation |
84
85
 
85
86
  ## Verify before you claim it works
86
87
 
@@ -113,10 +114,18 @@ interaction correctness.
113
114
 
114
115
  For a physical headset smoke test, run `npx @iwsdk/cli dev status`, open a URL from
115
116
  `data.runtimeUrls.network` on a headset connected to the same Wi-Fi network,
116
- and accept the expected local certificate warning. See
117
+ and accept the expected local certificate warning. To run or automate the app
118
+ on a Quest connected over USB, invoke `iwsdk-native-xr-test` instead. See
117
119
  [Testing Your Experience](https://iwsdk.dev/guides/02-testing-experience.html)
118
120
  for the complete workflow.
119
121
 
122
+ **Meta VR Glasses are not a Quest.** Their view is much narrower (37° left and
123
+ right, 25° up, 43° down) and their main input is gaze plus a pinch. Before
124
+ claiming an app works on the glasses, or when it uses gaze or eye tracking,
125
+ invoke `iwsdk-glasses-test`: it sets the `metaVRGlasses` emulator device, checks
126
+ that content fits that view, and drives gaze and pinch from the CLI. A Quest
127
+ screenshot or the editor view cannot show that fit.
128
+
120
129
  ## MCP and CLI are one surface, not two
121
130
 
122
131
  Nearly every capability exists both ways — `scene_render_file` and
@@ -169,6 +178,10 @@ The selected playbook routes work to the narrowest owning specialist:
169
178
  UI authoring, physics, depth occlusion, grab and ray interaction testing, ECS
170
179
  frame-stepping, and debugging have their own project skills. Use them only when
171
180
  the selected `iwsdk-dev` playbook calls for the matching specialty.
181
+ Two device-testing skills are invoked directly: `iwsdk-native-xr-test` whenever
182
+ the user wants to run, automate, or debug the app on a connected Quest, and
183
+ `iwsdk-glasses-test` whenever the user targets Meta VR Glasses or asks for gaze
184
+ input.
172
185
 
173
186
  The failure worth guarding against is improvising a domain that already has a
174
187
  skill because the naive approach looks tractable. Before hand-authoring scene
@@ -50,3 +50,5 @@ pattern for repetition; a pattern whose prefab resolves to a single component-fr
50
50
  mesh lowers to one `InstancedMesh`.
51
51
 
52
52
  Start assets at `castShadow: false` and opt in only for grounded focal masses.
53
+ Don't build contact-shadow blob cards or `ShadowMaterial` catcher planes here: put
54
+ `ContactShadow` or `ShadowCatcher` node components on the scene nodes instead.
@@ -69,7 +69,7 @@ and XR rays. Grab components: `OneHandGrabbable` and `TwoHandsGrabbable` are
69
69
  proximity-based and respond to **squeeze**, while `DistanceGrabbable` is
70
70
  ray-based and responds to **trigger**. `Grabbed` is a transient tag managed by
71
71
  `GrabSystem` — read it, never add or remove it. `GrabSystem.useHandPinchForGrab`
72
- defaults to **false**, so hand pinch does not grab unless you enable it.
72
+ defaults to **true**, so a hand pinch grabs; set it to `false` to require squeeze.
73
73
 
74
74
  `DistanceGrabbable` fields: `movementMode` (`MoveTowardsTarget`, `MoveFromTarget`,
75
75
  `MoveAtSource`, `RotateAtSource`), `returnToOrigin`, `moveSpeedFactor`,
@@ -38,6 +38,8 @@ player eye height to prove it.
38
38
  did not appear — even when the image looks plausible and `valid` is `true`. Check
39
39
  it against what you expect rather than trusting the picture. Single-sided
40
40
  surfaces facing away from the camera are the usual cause, and they report nothing.
41
+ `ContactShadow` and `ShadowCatcher` meshes take no rays, so a node whose only
42
+ content is one of them is never listed; check the object it grounds instead.
41
43
 
42
44
  ## Component keys come in two forms
43
45
 
@@ -64,5 +66,5 @@ view near `[0, 1.6, 0]`) before accepting XR framing.
64
66
  open document. A result is usable only when `valid: true` **and** a PNG comes
65
67
  back. Render each changed module before the root.
66
68
 
67
- For composing a scene rather than editing one, use the `iwsdk-scene-composer`
69
+ For composing a scene rather than editing one, use the `iwsdk-compose-scene`
68
70
  skill — it owns the intake, review and stop-rule procedure this file does not.
@@ -25,6 +25,11 @@ Expand shorthands (`padding: 12 18` → four properties), use unitless
25
25
  line-height multipliers, and prefer uniform `border-color`/`border-width` over
26
26
  directional variants. Parser errors include source locations.
27
27
 
28
+ **Production builds drop unused Lucide icons.** They keep only icons named in
29
+ `public/**/*.uikitml`. Icons named only by UIKitML built at runtime or loaded
30
+ from elsewhere must be listed in `iwsdkDev({ bundle: { icons: [...] } })`, or
31
+ they fail after `npm run build`.
32
+
28
33
  ## Runtime API
29
34
 
30
35
  Resolve the placed panel by **scene node id**, then elements by their `id`
@@ -55,3 +55,5 @@ pattern for repetition; a pattern whose prefab resolves to a single component-fr
55
55
  mesh lowers to one `InstancedMesh`.
56
56
 
57
57
  Start assets at `castShadow: false` and opt in only for grounded focal masses.
58
+ Don't build contact-shadow blob cards or `ShadowMaterial` catcher planes here: put
59
+ `ContactShadow` or `ShadowCatcher` node components on the scene nodes instead.
@@ -73,7 +73,7 @@ and XR rays. Grab components: `OneHandGrabbable` and `TwoHandsGrabbable` are
73
73
  proximity-based and respond to **squeeze**, while `DistanceGrabbable` is
74
74
  ray-based and responds to **trigger**. `Grabbed` is a transient tag managed by
75
75
  `GrabSystem` — read it, never add or remove it. `GrabSystem.useHandPinchForGrab`
76
- defaults to **false**, so hand pinch does not grab unless you enable it.
76
+ defaults to **true**, so a hand pinch grabs; set it to `false` to require squeeze.
77
77
 
78
78
  `DistanceGrabbable` fields: `movementMode` (`MoveTowardsTarget`, `MoveFromTarget`,
79
79
  `MoveAtSource`, `RotateAtSource`), `returnToOrigin`, `moveSpeedFactor`,
@@ -41,6 +41,8 @@ player eye height to prove it.
41
41
  did not appear — even when the image looks plausible and `valid` is `true`. Check
42
42
  it against what you expect rather than trusting the picture. Single-sided
43
43
  surfaces facing away from the camera are the usual cause, and they report nothing.
44
+ `ContactShadow` and `ShadowCatcher` meshes take no rays, so a node whose only
45
+ content is one of them is never listed; check the object it grounds instead.
44
46
 
45
47
  ## Component keys come in two forms
46
48
 
@@ -67,5 +69,5 @@ view near `[0, 1.6, 0]`) before accepting XR framing.
67
69
  open document. A result is usable only when `valid: true` **and** a PNG comes
68
70
  back. Render each changed module before the root.
69
71
 
70
- For composing a scene rather than editing one, use the `iwsdk-scene-composer`
72
+ For composing a scene rather than editing one, use the `iwsdk-compose-scene`
71
73
  skill — it owns the intake, review and stop-rule procedure this file does not.
@@ -28,6 +28,11 @@ Expand shorthands (`padding: 12 18` → four properties), use unitless
28
28
  line-height multipliers, and prefer uniform `border-color`/`border-width` over
29
29
  directional variants. Parser errors include source locations.
30
30
 
31
+ **Production builds drop unused Lucide icons.** They keep only icons named in
32
+ `public/**/*.uikitml`. Icons named only by UIKitML built at runtime or loaded
33
+ from elsewhere must be listed in `iwsdkDev({ bundle: { icons: [...] } })`, or
34
+ they fail after `npm run build`.
35
+
31
36
  ## Runtime API
32
37
 
33
38
  Resolve the placed panel by **scene node id**, then elements by their `id`
@@ -38,6 +38,8 @@ player eye height to prove it.
38
38
  did not appear — even when the image looks plausible and `valid` is `true`. Check
39
39
  it against what you expect rather than trusting the picture. Single-sided
40
40
  surfaces facing away from the camera are the usual cause, and they report nothing.
41
+ `ContactShadow` and `ShadowCatcher` meshes take no rays, so a node whose only
42
+ content is one of them is never listed; check the object it grounds instead.
41
43
 
42
44
  ## Component keys come in two forms
43
45
 
@@ -64,5 +66,5 @@ view near `[0, 1.6, 0]`) before accepting XR framing.
64
66
  open document. A result is usable only when `valid: true` **and** a PNG comes
65
67
  back. Render each changed module before the root.
66
68
 
67
- For composing a scene rather than editing one, use the `iwsdk-scene-composer`
69
+ For composing a scene rather than editing one, use the `iwsdk-compose-scene`
68
70
  skill — it owns the intake, review and stop-rule procedure this file does not.
@@ -25,6 +25,11 @@ Expand shorthands (`padding: 12 18` → four properties), use unitless
25
25
  line-height multipliers, and prefer uniform `border-color`/`border-width` over
26
26
  directional variants. Parser errors include source locations.
27
27
 
28
+ **Production builds drop unused Lucide icons.** They keep only icons named in
29
+ `public/**/*.uikitml`. Icons named only by UIKitML built at runtime or loaded
30
+ from elsewhere must be listed in `iwsdkDev({ bundle: { icons: [...] } })`, or
31
+ they fail after `npm run build`.
32
+
28
33
  ## Runtime API
29
34
 
30
35
  Resolve the placed panel by **scene node id**, then elements by their `id`
@@ -69,7 +69,7 @@ and XR rays. Grab components: `OneHandGrabbable` and `TwoHandsGrabbable` are
69
69
  proximity-based and respond to **squeeze**, while `DistanceGrabbable` is
70
70
  ray-based and responds to **trigger**. `Grabbed` is a transient tag managed by
71
71
  `GrabSystem` — read it, never add or remove it. `GrabSystem.useHandPinchForGrab`
72
- defaults to **false**, so hand pinch does not grab unless you enable it.
72
+ defaults to **true**, so a hand pinch grabs; set it to `false` to require squeeze.
73
73
 
74
74
  `DistanceGrabbable` fields: `movementMode` (`MoveTowardsTarget`, `MoveFromTarget`,
75
75
  `MoveAtSource`, `RotateAtSource`), `returnToOrigin`, `moveSpeedFactor`,
@@ -147,3 +147,5 @@ pattern for repetition; a pattern whose prefab resolves to a single component-fr
147
147
  mesh lowers to one `InstancedMesh`.
148
148
 
149
149
  Start assets at `castShadow: false` and opt in only for grounded focal masses.
150
+ Don't build contact-shadow blob cards or `ShadowMaterial` catcher planes here: put
151
+ `ContactShadow` or `ShadowCatcher` node components on the scene nodes instead.
@@ -22,5 +22,24 @@ from `src/components.ts` or `src/components.js`; you can then delete the unused
22
22
  robot component and system files. To remove the welcome panel, delete its scene
23
23
  node and its `PanelSystem` registration from the application entry point.
24
24
 
25
+ The robot stands on the second of three numbered stations. The first holds dark
26
+ pieces you can grab and move, and the third holds a ring you can spin in place.
27
+ The studio props (the plinths and the dark pieces, plus the floor and stage in VR
28
+ and Desktop 3D) are built in code in `src/scene-assets/studio.scene-asset.ts` or
29
+ `.js`. The VR and Desktop 3D background furniture is built the same way in
30
+ `src/scene-assets/decor.scene-asset.ts` or `.js`, so the starter downloads no
31
+ extra models. To remove any of them, delete their scene nodes and their entries
32
+ in `src/assets.ts` or `src/assets.js`, then delete the files you no longer use.
33
+ The station labels are `public/ui/label-*.uikitml`.
34
+
35
+ The rest of the look is built-in components in the scene, which you can edit in
36
+ the editor without code. The soft light on every object is the scene root's
37
+ `IBLGradient` (select the Level Root to edit it), and the soft shadows under
38
+ each object are `ContactShadow` nodes. In VR and Desktop 3D, the sky is the
39
+ scene root's `DomeGradient` (its colors, tilt and dither are also on the Level
40
+ Root), and the floor fades into it through the `DomeFade` on the floor node. AR
41
+ projects have no sky or floor, so passthrough stays visible, and a
42
+ `ShadowCatcher` node grounds the stations.
43
+
25
44
  - Minimal scene walkthrough: https://iwsdk.dev/guides/01b-minimal-scene.html
26
45
  - XR-enabled projects — IWER emulator controls: https://iwsdk.dev/guides/02-testing-experience.html#iwer-controls