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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (142) hide show
  1. package/README.md +79 -2
  2. package/dist/agent-adapters.d.ts +12 -1
  3. package/dist/agent-adapters.d.ts.map +1 -1
  4. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +312 -0
  5. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  6. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  7. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +277 -0
  8. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  9. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
  10. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  11. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
  12. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  13. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
  14. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  15. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
  16. package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +74 -0
  17. package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
  18. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +46 -0
  19. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +1531 -0
  20. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +82 -0
  21. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +263 -0
  22. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/planner.md +307 -0
  23. package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +282 -0
  24. package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +75 -0
  25. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +178 -0
  26. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  27. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
  28. package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +262 -0
  29. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +106 -0
  30. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/component-reference.md +152 -0
  31. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
  32. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
  33. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
  34. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  35. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  36. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  37. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  38. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  39. package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +70 -0
  40. package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +328 -0
  41. package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
  42. package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +521 -0
  43. package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +60 -0
  44. package/dist/agent-guidance/files/.claude/rules/ecs-api.md +103 -0
  45. package/dist/agent-guidance/files/.claude/rules/scene-json.md +72 -0
  46. package/dist/agent-guidance/files/.claude/rules/uikitml.md +66 -0
  47. package/dist/agent-guidance/files/.claude/settings.json +29 -0
  48. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +312 -0
  49. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  50. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  51. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +277 -0
  52. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  53. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
  54. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  55. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
  56. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  57. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
  58. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  59. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
  60. package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +74 -0
  61. package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
  62. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +46 -0
  63. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +1531 -0
  64. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +82 -0
  65. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +263 -0
  66. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/planner.md +307 -0
  67. package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +282 -0
  68. package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +75 -0
  69. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +178 -0
  70. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  71. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
  72. package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +262 -0
  73. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +106 -0
  74. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/component-reference.md +152 -0
  75. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
  76. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
  77. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
  78. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  79. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  80. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  81. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  82. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  83. package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +70 -0
  84. package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +328 -0
  85. package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
  86. package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +62 -0
  87. package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +105 -0
  88. package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +74 -0
  89. package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +68 -0
  90. package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +55 -0
  91. package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +101 -0
  92. package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +71 -0
  93. package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +65 -0
  94. package/{guidance → dist/agent-guidance/files}/AGENTS.md +107 -27
  95. package/dist/agent-guidance/files/CLAUDE.md +3 -0
  96. package/dist/agent-guidance/files/public/scenes/AGENTS.md +72 -0
  97. package/dist/agent-guidance/files/public/ui/AGENTS.md +66 -0
  98. package/dist/agent-guidance/files/src/AGENTS.md +153 -0
  99. package/dist/agent-guidance/manifest.json +854 -0
  100. package/dist/agent-guidance.d.ts +113 -0
  101. package/dist/agent-guidance.d.ts.map +1 -0
  102. package/dist/agent-guidance.js +3403 -0
  103. package/dist/agent-guidance.js.map +1 -0
  104. package/dist/cli.js +2407 -144
  105. package/dist/cli.js.map +1 -1
  106. package/dist/commands/adapter.d.ts +1 -0
  107. package/dist/commands/adapter.d.ts.map +1 -1
  108. package/dist/commands/agents.d.ts +11 -0
  109. package/dist/commands/agents.d.ts.map +1 -0
  110. package/dist/commands/browser.d.ts +11 -0
  111. package/dist/commands/browser.d.ts.map +1 -1
  112. package/dist/commands/dev.d.ts +1 -0
  113. package/dist/commands/dev.d.ts.map +1 -1
  114. package/dist/commands/reference.d.ts +15 -1
  115. package/dist/commands/reference.d.ts.map +1 -1
  116. package/dist/commands/runtime.d.ts.map +1 -1
  117. package/dist/commands/upgrade.d.ts +51 -0
  118. package/dist/commands/upgrade.d.ts.map +1 -0
  119. package/dist/contract.js +32 -0
  120. package/dist/contract.js.map +1 -1
  121. package/dist/guidance-refresh.d.ts +33 -0
  122. package/dist/guidance-refresh.d.ts.map +1 -0
  123. package/dist/help.d.ts +2 -0
  124. package/dist/help.d.ts.map +1 -1
  125. package/dist/index.d.ts.map +1 -1
  126. package/dist/index.js +4744 -135
  127. package/dist/index.js.map +1 -1
  128. package/dist/mcp-stdio.d.ts.map +1 -1
  129. package/dist/migrations/iwsdk-migrate-0-5/SKILL.md +413 -0
  130. package/dist/migrations.d.ts +36 -0
  131. package/dist/migrations.d.ts.map +1 -0
  132. package/dist/package-manager.d.ts +28 -0
  133. package/dist/package-manager.d.ts.map +1 -0
  134. package/dist/release-notes.d.ts +28 -0
  135. package/dist/release-notes.d.ts.map +1 -0
  136. package/dist/release-notes.json +1374 -0
  137. package/dist/runtime-contract.d.ts +8 -0
  138. package/dist/runtime-contract.d.ts.map +1 -1
  139. package/dist/runtime-telemetry.d.ts +8 -1
  140. package/dist/runtime-telemetry.d.ts.map +1 -1
  141. package/dist/version.d.ts +1 -1
  142. package/package.json +9 -3
@@ -0,0 +1,282 @@
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.
282
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=86e1e324dd71e8dd832b5d446e6bdc03bb5150cf5128c0650838cf6227b79817 name=iwsdk-glasses-test (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -0,0 +1,75 @@
1
+ ---
2
+ name: iwsdk-grab
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
+ argument-hint: '(use the current request)'
5
+ ---
6
+
7
+ # IWSDK Proximity Grab
8
+
9
+ Use this workflow only for `OneHandGrabbable` or `TwoHandsGrabbable`. A
10
+ `DistanceGrabbable` uses the ray/trigger path instead.
11
+
12
+ ## Execute the requested path
13
+
14
+ 1. Check XR session state and enter XR only when inactive.
15
+ 2. Find the named live entity and query its components and transform. If it is
16
+ absent, list nearby grabbable matches once and stop with the evidence.
17
+ 3. Confirm it has `OneHandGrabbable` or `TwoHandsGrabbable`. Do not guess the
18
+ interaction type from its name.
19
+ 4. Animate the requested controller to the object. Default to the right
20
+ controller only when the user did not choose a hand.
21
+ 5. Press and hold squeeze/grip button index `1`:
22
+
23
+ ```json
24
+ {"device":"controller-right","buttons":[{"index":1,"value":1}]}
25
+ ```
26
+
27
+ 6. Query the entity for `Grabbed` or another requested observable state. If the
28
+ grab did not qualify, make one focused correction to controller position and
29
+ retry once.
30
+ 7. If movement was requested, animate the held controller to the destination.
31
+ 8. Release squeeze with index `1`, value `0`, then query the final transform or
32
+ state. Move the controller away only when overlap would interfere with the
33
+ result.
34
+
35
+ Do not use trigger index `0`, `xr select`, or teleport-style device mutation for
36
+ proximity grab. Do not edit source merely to make an existing named entity easier
37
+ to locate; report missing runtime identity when that is the actual defect.
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
+
62
+ ## Evidence and stopping
63
+
64
+ Prefer measured ECS state over screenshots. Capture one runtime image only when
65
+ the user requested visual evidence or placement must be judged. Batch related
66
+ queries and avoid repeating session, hierarchy, or transform discovery after a
67
+ successful read.
68
+
69
+ When the request names an artifact path, save it directly with
70
+ `npx @iwsdk/cli browser screenshot --output-file <path>`. A screenshot returned only
71
+ to model context does not satisfy a requested file deliverable.
72
+
73
+ Stop once the requested grab/move/release path and final state are proven. Leave
74
+ the controller released and the XR session in the state the user requested.
75
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=ad099acb82205620cb9cce44f245f40baf7e6808038d7d94ff9d873f316473d2 name=iwsdk-grab (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -0,0 +1,178 @@
1
+ ---
2
+ name: iwsdk-hosting
3
+ description: Publish an IWSDK app to a public HTTPS origin so it can be installed as a PWA and packaged for the Meta Horizon Store. Use when deploying, hosting, or publishing the app, choosing a host, or when a file (web manifest, icons, .well-known/assetlinks.json) must reach an already-hosted site. Always asks first whether hosting already exists — recommends Vercel if not, and pauses with concrete upload steps if it does.
4
+ argument-hint: '[domain, host name, or deploy request]'
5
+ ---
6
+
7
+ # PWA Hosting
8
+
9
+ Packaging a Quest APK reads the app over the network, not off disk:
10
+ `bubblewrap` fetches the web manifest and icons from the live origin, and the
11
+ Trusted Web Activity refuses to launch until Digital Asset Links are reachable
12
+ there too. So the origin — call it `<DOMAIN>` — comes first, and every later
13
+ step depends on files actually being served from it.
14
+
15
+ User request is in `$ARGUMENTS`.
16
+
17
+ ## 1. Ask about hosting before doing anything else
18
+
19
+ **Never assume.** Ask the developer, up front, whether the app is already
20
+ deployed — with a structured question tool (AskUserQuestion) if the harness has
21
+ one, otherwise as a plain question. Do not deploy anything, do not pick a host,
22
+ and do not run a deploy CLI until this is answered.
23
+
24
+ > Is this app already deployed to a public HTTPS URL?
25
+ >
26
+ > - **Not deployed yet — recommend a host** → Route A
27
+ > - **Already hosted / host already chosen** (Netlify, Cloudflare Pages, GitHub
28
+ > Pages, S3+CloudFront, Firebase, own nginx/Apache server, internal CDN…) →
29
+ > Route B
30
+ > - **Deployed, but open to moving it** → describe both, then let them pick
31
+
32
+ If they answer with a URL, treat it as Route B and use that URL as `<DOMAIN>`.
33
+ If they are unreachable and you must proceed autonomously, take Route A, and
34
+ mark the choice `[ASSUMED]` in whatever plan or report you are writing.
35
+
36
+ ## 2. Route A — no host yet: recommend Vercel
37
+
38
+ Recommend Vercel, and say why in one line: it detects Vite with no config,
39
+ serves `dist/` over HTTPS with a stable public alias, keeps `public/` dotfolders
40
+ like `.well-known/` intact, and redeploys with one command — which matters
41
+ because asset links force a second publish later.
42
+
43
+ ```bash
44
+ npm run build # → dist/
45
+ npx -y vercel@latest whoami # auth check
46
+ npx -y vercel@latest teams ls # find <team-slug>
47
+ npx -y vercel@latest deploy --prod --yes --scope <team-slug>
48
+ ```
49
+
50
+ Use the **canonical alias** (`https://<project>.vercel.app`) as `<DOMAIN>`, not
51
+ the hashed per-deploy URL — under team deployment protection the hashed URL
52
+ returns 401 and every downstream fetch fails. Full walkthrough, first-run login,
53
+ and the redeploy rule: [`references/vercel.md`](references/vercel.md).
54
+
55
+ Then run the [contract check](#4-the-contract-what-must-be-reachable).
56
+
57
+ ## 3. Route B — host already chosen: pause and hand off
58
+
59
+ The developer owns the host, so **you do not publish — you prepare files and
60
+ stop.** Every time something new has to reach `<DOMAIN>`, run the handoff below
61
+ rather than guessing at their pipeline.
62
+
63
+ Publishing to an existing host happens at least **twice**, and the second one is
64
+ easy to forget:
65
+
66
+ | # | When | What must reach `<DOMAIN>` |
67
+ | - | ---- | -------------------------- |
68
+ | 1 | after the manifest + icons exist | the whole built `dist/` |
69
+ | 2 | after the signing keystore exists | `dist/.well-known/assetlinks.json` (rebuild first) |
70
+
71
+ A third happens for any later web-only fix — those need only a republish, never
72
+ a new APK.
73
+
74
+ ### Upload handoff protocol
75
+
76
+ Run this at each row above. Keep it short and literal; the developer should be
77
+ able to act without asking a follow-up question.
78
+
79
+ 1. **Build first.** `npm run build`. Vite copies `public/` — including
80
+ dotfolders like `.well-known/` — verbatim into `dist/`.
81
+ 2. **List the exact files and their exact destination URLs.** Local path →
82
+ public URL, one per line. Never say "upload the assets".
83
+ 3. **Give the concrete steps for their host**, not generic advice — the command
84
+ for their CLI, or the click path for their dashboard. Per-host recipes and
85
+ gotchas (dotfolder stripping, MIME types, subpath hosting, cache TTLs) are in
86
+ [`references/existing-hosts.md`](references/existing-hosts.md). If the host is
87
+ one you do not recognize, ask how they normally publish and adapt.
88
+ 4. **Offer to run it — do not assume you can.** Only run their deploy command
89
+ yourself if they confirm the CLI is installed and authenticated in this
90
+ environment. Otherwise they run it; suggest they can paste it into this
91
+ session prefixed with `!`.
92
+ 5. **Stop and wait.** Do not continue to the next pipeline step on the
93
+ assumption the upload happened.
94
+ 6. **Verify yourself once they say it is live**, with the checks in §4. If a
95
+ check fails, report the failing URL and status code and hand back — a wrong
96
+ guess here surfaces much later as "the TWA will not launch".
97
+
98
+ Handoff message template:
99
+
100
+ ```
101
+ Ready to publish. Please upload these to <DOMAIN>:
102
+
103
+ dist/manifest.webmanifest → https://<DOMAIN>/manifest.webmanifest
104
+ dist/icons/icon-192.png → https://<DOMAIN>/icons/icon-192.png
105
+ dist/icons/icon-512.png → https://<DOMAIN>/icons/icon-512.png
106
+ dist/icons/icon-512-maskable.png → https://<DOMAIN>/icons/icon-512-maskable.png
107
+ (or simply publish all of dist/ — these are already inside it)
108
+
109
+ On <host>, that is:
110
+ <the one command, or the exact dashboard click path>
111
+
112
+ Tell me when it is live and I will verify, then continue with packaging.
113
+ ```
114
+
115
+ ## 4. The contract: what must be reachable
116
+
117
+ Whichever route was taken, `<DOMAIN>` must satisfy all of this before
118
+ `bubblewrap update` runs. Check it yourself — do not take "it is deployed" as
119
+ proof.
120
+
121
+ | URL | Expected |
122
+ | --- | -------- |
123
+ | `https://<DOMAIN>/` | 200, HTTPS, valid cert |
124
+ | `https://<DOMAIN>/manifest.webmanifest` | 200, `Content-Type: application/manifest+json` |
125
+ | `https://<DOMAIN>/icons/icon-512.png` | 200, `image/png` |
126
+ | `https://<DOMAIN>/.well-known/assetlinks.json` | 200, `application/json` (after the keystore step) |
127
+ | `https://<DOMAIN>/android.keystore` | **404** — the keystore must never be published |
128
+
129
+ ```bash
130
+ for u in / /manifest.webmanifest /icons/icon-512.png /.well-known/assetlinks.json; do
131
+ printf '%s ' "$u"; curl -s -o /dev/null -w '%{http_code} %{content_type}\n' "https://<DOMAIN>$u"
132
+ done
133
+ curl -s -o /dev/null -w 'keystore %{http_code} (want 404)\n' "https://<DOMAIN>/android.keystore"
134
+ ```
135
+
136
+ Two failures are worth calling out because they look like host bugs and are not:
137
+
138
+ - **`.well-known/` 404s** while everything else works — the host is stripping
139
+ dotfolders. Fix per [`references/existing-hosts.md`](references/existing-hosts.md);
140
+ do not work around it by moving the file, the path is fixed by the TWA spec.
141
+ - **The manifest serves as `text/plain`** — some hosts have no mapping for
142
+ `.webmanifest`. Add the MIME type, or serve it as `manifest.json` and update
143
+ the `<link rel="manifest">` and `webManifestUrl` to match.
144
+
145
+ ## 5. Hosting at a subpath
146
+
147
+ If the app is served from `https://<DOMAIN>/<path>/` rather than the origin
148
+ root, two things change and both break silently:
149
+
150
+ - `start_url` and `scope` in the web manifest must be `/<path>/`, not `/`.
151
+ - `assetlinks.json` still has to sit at the **origin root**
152
+ (`https://<DOMAIN>/.well-known/assetlinks.json`) — a subpath copy is ignored.
153
+ If the developer does not control the origin root, they cannot ship a TWA from
154
+ that origin. Say so plainly and offer Route A as the alternative.
155
+
156
+ `base: './'` is already set in the scaffolded `vite.config.*`, so the JS/CSS
157
+ bundles themselves are fine at any path — it is only these two that need care.
158
+
159
+ ## 6. Redeploy vs rebuild
160
+
161
+ Once the APK exists, keep this distinction straight — it saves a Store round
162
+ trip:
163
+
164
+ - **Web-only change** (app logic, styling, manifest text, icons, asset links) →
165
+ republish `<DOMAIN>`. The installed TWA picks it up on next launch.
166
+ - **Native change** (package id, app name, launcher icon, version, app mode,
167
+ signing) → rebuild the APK and re-upload to the Store.
168
+
169
+ ## Reference Files
170
+
171
+ | File | Load when |
172
+ | ---- | --------- |
173
+ | [`references/vercel.md`](references/vercel.md) | Route A — full Vercel deploy, auth, aliases, redeploys |
174
+ | [`references/existing-hosts.md`](references/existing-hosts.md) | Route B — per-host publish recipes and their gotchas |
175
+
176
+ Packaging the hosted app into a signed Quest APK is the `iwsdk-pwa-packaging`
177
+ skill; this skill only gets it online.
178
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=9e866989c506da5cf54ba96bb02c52d1b901e162ab8f32ad9f97ed84aa4dcc8b name=iwsdk-hosting (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->