@iwsdk/cli 1.1.0 → 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.
- package/README.md +79 -2
- package/dist/agent-adapters.d.ts +12 -1
- package/dist/agent-adapters.d.ts.map +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +312 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +277 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +74 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +46 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +1531 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +263 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/planner.md +307 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +282 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +75 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +178 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +262 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +106 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/component-reference.md +152 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +70 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +328 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +521 -0
- package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +60 -0
- package/dist/agent-guidance/files/.claude/rules/ecs-api.md +103 -0
- package/dist/agent-guidance/files/.claude/rules/scene-json.md +72 -0
- package/dist/agent-guidance/files/.claude/rules/uikitml.md +66 -0
- package/dist/agent-guidance/files/.claude/settings.json +29 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +312 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +277 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +74 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +46 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +1531 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +263 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/planner.md +307 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +282 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +75 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +178 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +262 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +106 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/component-reference.md +152 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +70 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +328 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +62 -0
- package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +105 -0
- package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +74 -0
- package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +68 -0
- package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +55 -0
- package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +101 -0
- package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +71 -0
- package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +65 -0
- package/{guidance → dist/agent-guidance/files}/AGENTS.md +107 -27
- package/dist/agent-guidance/files/CLAUDE.md +3 -0
- package/dist/agent-guidance/files/public/scenes/AGENTS.md +72 -0
- package/dist/agent-guidance/files/public/ui/AGENTS.md +66 -0
- package/dist/agent-guidance/files/src/AGENTS.md +153 -0
- package/dist/agent-guidance/manifest.json +854 -0
- package/dist/agent-guidance.d.ts +113 -0
- package/dist/agent-guidance.d.ts.map +1 -0
- package/dist/agent-guidance.js +3403 -0
- package/dist/agent-guidance.js.map +1 -0
- package/dist/cli.js +2407 -144
- package/dist/cli.js.map +1 -1
- package/dist/commands/adapter.d.ts +1 -0
- package/dist/commands/adapter.d.ts.map +1 -1
- package/dist/commands/agents.d.ts +11 -0
- package/dist/commands/agents.d.ts.map +1 -0
- package/dist/commands/browser.d.ts +11 -0
- package/dist/commands/browser.d.ts.map +1 -1
- package/dist/commands/dev.d.ts +1 -0
- package/dist/commands/dev.d.ts.map +1 -1
- package/dist/commands/reference.d.ts +15 -1
- package/dist/commands/reference.d.ts.map +1 -1
- package/dist/commands/runtime.d.ts.map +1 -1
- package/dist/commands/upgrade.d.ts +51 -0
- package/dist/commands/upgrade.d.ts.map +1 -0
- package/dist/contract.js +32 -0
- package/dist/contract.js.map +1 -1
- package/dist/guidance-refresh.d.ts +33 -0
- package/dist/guidance-refresh.d.ts.map +1 -0
- package/dist/help.d.ts +2 -0
- package/dist/help.d.ts.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4744 -135
- package/dist/index.js.map +1 -1
- package/dist/mcp-stdio.d.ts.map +1 -1
- package/dist/migrations/iwsdk-migrate-0-5/SKILL.md +413 -0
- package/dist/migrations.d.ts +36 -0
- package/dist/migrations.d.ts.map +1 -0
- package/dist/package-manager.d.ts +28 -0
- package/dist/package-manager.d.ts.map +1 -0
- package/dist/release-notes.d.ts +28 -0
- package/dist/release-notes.d.ts.map +1 -0
- package/dist/release-notes.json +1374 -0
- package/dist/runtime-contract.d.ts +8 -0
- package/dist/runtime-contract.d.ts.map +1 -1
- package/dist/runtime-telemetry.d.ts +8 -1
- package/dist/runtime-telemetry.d.ts.map +1 -1
- package/dist/version.d.ts +1 -1
- 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) -->
|