@iwsdk/cli 1.2.0-rc.0 → 1.2.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.
- package/README.md +40 -13
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +20 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +2 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +15 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +7 -3
- package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +3 -2
- package/dist/agent-guidance/files/.agents/skills/iwsdk-metavr-native/SKILL.md +216 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-metavr-native/assets/iwn-host.mjs +71 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/SKILL.md +217 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/offline.ts.template +99 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/sw.js.template +241 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/build-step.md +71 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/page.md +70 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/service-worker.md +107 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/testing.md +57 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +1 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +9 -3
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +18 -3
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +30 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +12 -5
- package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +1 -1
- package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +1 -1
- package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +1 -1
- package/dist/agent-guidance/files/.claude/rules/ecs-api.md +1 -1
- package/dist/agent-guidance/files/.claude/rules/scene-json.md +1 -1
- package/dist/agent-guidance/files/.claude/rules/uikitml.md +1 -1
- package/dist/agent-guidance/files/.claude/settings.json +2 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +1 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +1 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +1 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +1 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +20 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +2 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +15 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +7 -3
- package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +1 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +1 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +3 -2
- package/dist/agent-guidance/files/.claude/skills/iwsdk-metavr-native/SKILL.md +216 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-metavr-native/assets/iwn-host.mjs +71 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +1 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/SKILL.md +217 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/offline.ts.template +99 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/sw.js.template +241 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/build-step.md +71 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/page.md +70 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/service-worker.md +107 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/testing.md +57 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +1 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +1 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +9 -3
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +18 -3
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +1 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +30 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +1 -1
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +12 -5
- package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +1 -1
- package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +1 -1
- package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +1 -1
- package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +1 -1
- package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +1 -1
- package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +1 -1
- package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +1 -1
- package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +1 -1
- package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +1 -1
- package/dist/agent-guidance/files/AGENTS.md +10 -1
- package/dist/agent-guidance/files/public/scenes/AGENTS.md +1 -1
- package/dist/agent-guidance/files/public/ui/AGENTS.md +1 -1
- package/dist/agent-guidance/files/src/AGENTS.md +1 -1
- package/dist/agent-guidance/manifest.json +142 -12
- package/dist/agent-guidance.d.ts +31 -4
- package/dist/agent-guidance.d.ts.map +1 -1
- package/dist/agent-guidance.js +269 -60
- package/dist/agent-guidance.js.map +1 -1
- package/dist/cli.js +1128 -131
- package/dist/cli.js.map +1 -1
- package/dist/commands/upgrade.d.ts +87 -0
- package/dist/commands/upgrade.d.ts.map +1 -1
- package/dist/guidance-refresh.d.ts +23 -3
- package/dist/guidance-refresh.d.ts.map +1 -1
- package/dist/help.d.ts.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1128 -131
- package/dist/index.js.map +1 -1
- package/dist/metavr-telemetry.d.ts +6 -0
- package/dist/metavr-telemetry.d.ts.map +1 -1
- package/dist/package-manager.d.ts +6 -0
- package/dist/package-manager.d.ts.map +1 -1
- package/dist/release-notes.json +183 -0
- package/dist/version.d.ts +1 -1
- package/package.json +1 -1
|
@@ -461,7 +461,8 @@ PhysicsShapeType.Auto; // Auto-detect from Three.js geometry
|
|
|
461
461
|
|
|
462
462
|
**Teleporting / re-posing an existing body:** use the live physics system rather than
|
|
463
463
|
removing and re-adding components. It updates Havok and the Object3D immediately and
|
|
464
|
-
clears velocity by default
|
|
464
|
+
clears velocity by default. The pose is parent-relative unless you pass
|
|
465
|
+
`{ space: 'world' }`:
|
|
465
466
|
|
|
466
467
|
```typescript
|
|
467
468
|
const physics = world.getSystem(PhysicsSystem);
|
|
@@ -17,7 +17,9 @@ per second.
|
|
|
17
17
|
room behind the app draws with it, so the two always match.
|
|
18
18
|
- `scene render-stats` draws one fresh frame before it reads the stats.
|
|
19
19
|
`browser profile`, runtime evidence and `browser run` scripts draw every
|
|
20
|
-
frame while they run.
|
|
20
|
+
frame while they run. A profile first draws three warm-up frames, so
|
|
21
|
+
one-time first-draw costs (shader compilation, texture uploads) stay out of
|
|
22
|
+
its numbers.
|
|
21
23
|
- Headed sessions, including collaborate mode, always draw every frame.
|
|
22
24
|
- To draw every frame in a headless session, start it with
|
|
23
25
|
`IWSDK_DEV_RENDER_MODE=continuous`.
|
|
@@ -67,6 +69,18 @@ set it back to `"on-demand"` when done.
|
|
|
67
69
|
`npx @iwsdk/cli browser profile --input-json '{"action":"start","mode":"rendering"}'`,
|
|
68
70
|
exercise the scene, then
|
|
69
71
|
`npx @iwsdk/cli browser profile --input-json '{"action":"stop"}'`.
|
|
72
|
+
- Trust the frame times of a profile that reports a `render-warmup-timeout`
|
|
73
|
+
interruption (the app did not draw its warm-up frames in the time the start
|
|
74
|
+
allowed, at most 5 seconds) or `render-loop-stopped` (the app drew nothing
|
|
75
|
+
for 30 or more animation frames in a row while the profile held rendering:
|
|
76
|
+
its render loop stopped, before the profile or during it, or stalled). The
|
|
77
|
+
usual cause is an uncaught error in a frame, which stops the render loop;
|
|
78
|
+
check `npx @iwsdk/cli browser logs`. After a warm-up timeout, the first
|
|
79
|
+
frames may also just be very slow. Fix the error, or profile again.
|
|
80
|
+
- Trust the frame times of a profile that reports
|
|
81
|
+
`render-warmup-skipped-budget` (less than a second of the command's time
|
|
82
|
+
was left for the warm-up) or `render-mode-unavailable`. It sampled without
|
|
83
|
+
warm-up frames, so its numbers may include first-draw costs. Profile again.
|
|
70
84
|
- Expect a frame to change between screenshots if the scene did not change.
|
|
71
85
|
- Restart into headed mode to "fix" a stale view; screenshots already draw a
|
|
72
86
|
fresh frame.
|
|
@@ -154,9 +154,13 @@ npx @iwsdk/cli xr run-sequence --input-json '{"device":"hand-right","steps":[{"t
|
|
|
154
154
|
npx @iwsdk/cli xr run-sequence --input-json '{"device":"hand-right","steps":[{"pinch":0,"duration":0.15}]}'
|
|
155
155
|
```
|
|
156
156
|
|
|
157
|
-
Query `Grabbed` between the grab and the release. A press result
|
|
158
|
-
|
|
159
|
-
|
|
157
|
+
Query `Grabbed` between the grab and the release. A press result reports
|
|
158
|
+
contact, not a click: confirm the click by the state it changes (`ui inspect`
|
|
159
|
+
on the control, or the app state it drives). A `presses[0].contactMs` of more
|
|
160
|
+
than 800 never clicks. A stalled frame can stretch a press that far, so run
|
|
161
|
+
that press once more before changing code. A control out of reach stretches it
|
|
162
|
+
too, because the body walks to it during the press: walk first, with
|
|
163
|
+
`{"body":{"stepTo":"Btn_Action"}}` as a step of its own, then press.
|
|
160
164
|
|
|
161
165
|
If a scene/source/UI edit happens after the managed runtime started and live
|
|
162
166
|
state becomes stale, do not call `scene open`, repeatedly poll `dev status`, or
|
|
@@ -279,4 +279,4 @@ synthetic `fov: 90`. Keep using step 3 for framing.
|
|
|
279
279
|
- `[iwsdk][gaze]` console lines and other errors;
|
|
280
280
|
- for a headset run, its serial, which Quest mode was used, and whether the
|
|
281
281
|
page was paired.
|
|
282
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
282
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=86e1e324dd71e8dd832b5d446e6bdc03bb5150cf5128c0650838cf6227b79817 name=iwsdk-glasses-test (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -72,4 +72,4 @@ to model context does not satisfy a requested file deliverable.
|
|
|
72
72
|
|
|
73
73
|
Stop once the requested grab/move/release path and final state are proven. Leave
|
|
74
74
|
the controller released and the XR session in the state the user requested.
|
|
75
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
75
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=ad099acb82205620cb9cce44f245f40baf7e6808038d7d94ff9d873f316473d2 name=iwsdk-grab (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -174,5 +174,6 @@ trip:
|
|
|
174
174
|
| [`references/existing-hosts.md`](references/existing-hosts.md) | Route B — per-host publish recipes and their gotchas |
|
|
175
175
|
|
|
176
176
|
Packaging the hosted app into a signed Quest APK is the `iwsdk-pwa-packaging`
|
|
177
|
-
skill
|
|
178
|
-
|
|
177
|
+
skill, and keeping an offline copy on the device — with the `sw.js` cache
|
|
178
|
+
headers that copy needs — is `iwsdk-offline`. This skill only gets it online.
|
|
179
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=360be8c5297e0b33bdbdf82188b95dbbcfc586b00d0c0840a21094eb9745e21d name=iwsdk-hosting (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: iwsdk-metavr-native
|
|
3
|
+
description: Build, install, run and debug an IWSDK VR or AR app as a standalone Quest APK with @iwer/native (alpha), which runs the app's own JavaScript on the headset without Quest Browser. Use when the project has a `native` section in iwsdk.config.json or a `build:metavr` script, when the user asks for a native or browserless Quest build, or when a dist-metavr APK fails to pack, launch, enter XR or fetch. Not for PWA/TWA store packaging of a hosted site (iwsdk-pwa-packaging) or for driving Quest Browser over ADB (iwsdk-native-xr-test).
|
|
4
|
+
argument-hint: '[goal, e.g. "add a native build", "the APK shows black"]'
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Native Quest APK (@iwer/native, alpha)
|
|
8
|
+
|
|
9
|
+
`npm run build:metavr` runs `vite build --mode metavr && iwer-native pack`.
|
|
10
|
+
The Vite step is a normal production build without the IWER emulator, and with
|
|
11
|
+
the `native` section of `iwsdk.config.json` left out of the bundle. `pack` puts
|
|
12
|
+
`dist/` into a template APK that carries the @iwer/native runtime (V8, WebGL 2
|
|
13
|
+
over OpenGL ES, fetch, Web Audio, workers, a DOM stand-in, WebXR over OpenXR)
|
|
14
|
+
and signs it in Node. The result, `dist-metavr/<appName>.apk`, runs on the
|
|
15
|
+
headset with no browser and no server: app files load from the APK.
|
|
16
|
+
|
|
17
|
+
User request is in `$ARGUMENTS`.
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
0. Pick the route → native APK, or PWA/TWA (iwsdk-pwa-packaging)
|
|
21
|
+
1. Set up → IWSDK ≥ 1.2, @iwer/native, native section
|
|
22
|
+
2. Fit the app → VR only, offers XR, no HTML UI, allow-listed origins
|
|
23
|
+
3. Build and launch → doctor → build:metavr → install → run
|
|
24
|
+
4. Verify on device → logcat, debug endpoint, state hook
|
|
25
|
+
5. Ship → package id, signing, --release
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
The package README is the reference for every config key, API and error:
|
|
29
|
+
`node_modules/@iwer/native/README.md`. Read its support matrix, Known
|
|
30
|
+
limitations and Troubleshooting before you promise a feature works natively.
|
|
31
|
+
Trust it over this skill if they disagree; the alpha changes between releases.
|
|
32
|
+
|
|
33
|
+
## Step 0 — Native APK or PWA?
|
|
34
|
+
|
|
35
|
+
| | **Native APK (this skill)** | **PWA/TWA (`iwsdk-pwa-packaging`)** |
|
|
36
|
+
| --- | --- | --- |
|
|
37
|
+
| Runs in | the @iwer/native runtime | Quest Browser, from a live URL |
|
|
38
|
+
| Needs hosting | no, files are in the APK | yes, a public HTTPS origin |
|
|
39
|
+
| Web fixes ship by | a new APK | redeploying the site |
|
|
40
|
+
| App modes | immersive VR and AR (passthrough) | immersive VR, AR, 2D panel |
|
|
41
|
+
| Web platform | the subset in the README matrix | the full browser |
|
|
42
|
+
| APK size | about 47 MB of runtime + assets | small wrapper |
|
|
43
|
+
|
|
44
|
+
Ask when the user says only "make an APK". Choose native for an offline,
|
|
45
|
+
self-contained immersive app; choose the PWA for a 2D panel, HTML UI, or an
|
|
46
|
+
app that depends on browser APIs the matrix marks "not yet" or "out of
|
|
47
|
+
scope".
|
|
48
|
+
|
|
49
|
+
## Step 1 — Set up
|
|
50
|
+
|
|
51
|
+
Requirements: `@iwsdk/core`, `@iwsdk/vite-plugin-dev` and `@iwsdk/create` 1.2.0
|
|
52
|
+
or later (1.1.0 rejects the `native` key), Node 20.19+, `adb` on `PATH` (or
|
|
53
|
+
`$ADB`/`$ANDROID_HOME`), and a Quest in developer mode with USB debugging
|
|
54
|
+
accepted. No Android SDK, NDK or Gradle is needed.
|
|
55
|
+
|
|
56
|
+
- **New project:** `npm create @iwsdk@latest <name> -- --target vr --metavr-native`
|
|
57
|
+
(or `--target ar`).
|
|
58
|
+
It adds `@iwer/native` (pinned), the `build:metavr` script, a `native`
|
|
59
|
+
section and `dist-metavr/` in `.gitignore`.
|
|
60
|
+
- **Existing IWSDK project:** run `npx @iwsdk/create@latest . --yes --target <vr|ar> --metavr-native`.
|
|
61
|
+
It adds the script, the dependency and the ignore entry but keeps your
|
|
62
|
+
`iwsdk.config.json`, so add the section it prints yourself:
|
|
63
|
+
|
|
64
|
+
```json
|
|
65
|
+
"native": {
|
|
66
|
+
"packageId": "com.example.myapp",
|
|
67
|
+
"appName": "myapp",
|
|
68
|
+
"network": { "allow": ["https://cdn.jsdelivr.net"] }
|
|
69
|
+
}
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Without it, `pack` stops at `iwsdk.config.json has no "native" section`.
|
|
73
|
+
|
|
74
|
+
Then `npx iwer-native doctor`. It checks Node, adb, the connected headsets, the
|
|
75
|
+
native config, signing and the bundled template. Fix every `[fail]` before
|
|
76
|
+
building. The `com.example` warning is fine for sideloading.
|
|
77
|
+
|
|
78
|
+
## Step 2 — Fit the app to the runtime
|
|
79
|
+
|
|
80
|
+
- **Immersive only.** `world.xr.mode` `"vr"` or `"ar"`; there is no 2D page, so
|
|
81
|
+
a Desktop 3D (`world.xr: false`) app cannot be packed. For `"ar"`, `pack`
|
|
82
|
+
declares passthrough itself. Plane, mesh, hit-test and anchor support needs a
|
|
83
|
+
room from Space Setup and is not yet device-tested in a real room (README
|
|
84
|
+
Known limitations): verify scene-understanding features on the headset.
|
|
85
|
+
A feature marked `required` that the headset lacks rejects the session, and
|
|
86
|
+
the app never leaves the splash: a Quest 3S has no depth sensing, so
|
|
87
|
+
`depthSensing: { required: true }` never starts there. Prefer optional
|
|
88
|
+
features and feature-detect them, and note the headset model you tested on
|
|
89
|
+
(`iwn-host.mjs info`). With several headsets attached, always pass `--serial`.
|
|
90
|
+
- **The app must offer XR.** Keep `world.xr.offer` at `"always"` (the default)
|
|
91
|
+
or `"once"`. The runtime shows only WebXR content: with `"none"` the app stays
|
|
92
|
+
black and logs `XR-LIFE-7` after 10 s.
|
|
93
|
+
- **No HTML UI.** There is no layout, CSS or pointer/keyboard event. Build UI in
|
|
94
|
+
3D with IWSDK spatial UI (`iwsdk-ui`). DOM overlays do not draw.
|
|
95
|
+
- **There is no browser to exit to.** Ending the session (the starter's
|
|
96
|
+
"Exit to Browser" button, `world.exitXR()`) makes `offer: "always"` start a new
|
|
97
|
+
session at once, so the button only flickers. Hide such controls in native
|
|
98
|
+
builds and let the system menu quit:
|
|
99
|
+
`const isNative = navigator.userAgent.includes('IWERNative');`
|
|
100
|
+
- **Network allow-list.** Only origins in `native.network.allow` are reachable
|
|
101
|
+
(`https://host[:port]`, no path). The starter needs `https://cdn.jsdelivr.net`
|
|
102
|
+
for its controller models. Prefer bundling assets in `public/` so the app works
|
|
103
|
+
offline. No WebSocket, IndexedDB, Cache API, service worker or HTTP cache.
|
|
104
|
+
- **Media.** `<video>`/`<audio>` file playback is not supported; use Web Audio
|
|
105
|
+
(`AudioContext`, buffer sources, gain, panner, `decodeAudioData`).
|
|
106
|
+
- **Check compatibility:** `npx iwer-native compat` (static) and
|
|
107
|
+
`npx iwer-native compat --trace` (a headless run into XR). `pack` runs the
|
|
108
|
+
static check and fails on an injected emulator; `pack --strict` fails on any
|
|
109
|
+
unsupported API. Treat the `WebAssembly.instantiateStreaming()` warning on an
|
|
110
|
+
IWSDK physics or UI build as expected: Havok and the MSDF worker fall back to
|
|
111
|
+
`WebAssembly.instantiate`, and physics runs. Act on every other warning: feature-detect
|
|
112
|
+
the API or drop it (`compat --verbose` shows the call site).
|
|
113
|
+
|
|
114
|
+
## Step 3 — Build, install, run
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
npm run --if-present typecheck
|
|
118
|
+
npm run build:metavr # dist-metavr/<appName>.apk, debug build
|
|
119
|
+
npx iwer-native install --serial <serial>
|
|
120
|
+
npx iwer-native run --serial <serial> # or: npx iwer-native pack --install --run
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
The loop is quick (build about 5 s, pack under 1 s, install about 10 s), so
|
|
124
|
+
rebuild instead of reasoning about stale state. Always pass `--serial` when
|
|
125
|
+
more than one device is connected. Debug and release builds write the same
|
|
126
|
+
path; the last `pack` wins.
|
|
127
|
+
|
|
128
|
+
**Before blaming the app, check what the headset shows:**
|
|
129
|
+
|
|
130
|
+
```bash
|
|
131
|
+
adb -s <serial> shell dumpsys activity activities | grep topResumedActivity
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
- `com.example.<app>/android.app.NativeActivity` → the app is in front.
|
|
135
|
+
- `GuardianDialogActivity` ("Finding position in room") or
|
|
136
|
+
`LaunchCheckRequires6dofDialogActivity` ("Turn on tracking") → the headset has
|
|
137
|
+
lost tracking, usually because the room is dark or the cameras are covered.
|
|
138
|
+
`run` then reports `adb did not finish within 60 s`. A native APK needs 6DoF
|
|
139
|
+
tracking: ask the user for light. If the dialog stays after tracking is back,
|
|
140
|
+
`adb -s <serial> reboot` clears it.
|
|
141
|
+
- Any other system dialog (permissions, first-run notices) → ask the user to
|
|
142
|
+
answer it in the headset, or read its buttons with
|
|
143
|
+
`adb shell uiautomator dump` and answer it only if the user allowed you to.
|
|
144
|
+
|
|
145
|
+
## Step 4 — Verify on the device
|
|
146
|
+
|
|
147
|
+
IWSDK's CLI and MCP tools (`ecs`, `xr`, `scene`, `browser`) reach the managed
|
|
148
|
+
browser and paired Quest Browser pages, **not** a native APK. On the APK use:
|
|
149
|
+
|
|
150
|
+
1. **Logs:** `adb -s <serial> logcat -v tag | grep '/iwn'`. Every runtime tag
|
|
151
|
+
starts with `iwn`; app `console.*` output is `iwn-js`. A healthy launch logs
|
|
152
|
+
`xr: first WebXR frame`, then `xr-stats fps=72…` lines every few seconds.
|
|
153
|
+
Lines from an older process of the same app (another PID) are not this run.
|
|
154
|
+
2. **The debug endpoint** (debug builds; `pack --release --inspector` for a
|
|
155
|
+
release build). Forward it, then use the bundled client:
|
|
156
|
+
|
|
157
|
+
```bash
|
|
158
|
+
adb -s <serial> forward tcp:9229 localabstract:<packageId>_devtools_9229
|
|
159
|
+
kit="$(dirname "$(find .claude/skills .agents/skills -path '*/iwsdk-metavr-native/assets/iwn-host.mjs' -print -quit)")"
|
|
160
|
+
node "$kit/iwn-host.mjs" eval 'document.title'
|
|
161
|
+
node "$kit/iwn-host.mjs" shot shot.png left 0.5 # what the eye buffer shows
|
|
162
|
+
node "$kit/iwn-host.mjs" stats # fps, GC, heap, boot timings
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
`adb shell screencap` is black during an immersive session; use `shot`.
|
|
166
|
+
The shot follows the live head pose: a headset lying on a desk looks
|
|
167
|
+
wherever it points. It holds the app's layer only; in AR, passthrough is
|
|
168
|
+
not in it, so empty areas come out blank.
|
|
169
|
+
3. **App state.** The APK has no IWSDK command bridge, so expose the world for
|
|
170
|
+
tests yourself, only when asked for:
|
|
171
|
+
|
|
172
|
+
```ts
|
|
173
|
+
if (new URLSearchParams(location.search).has('iwsdkDebug')) {
|
|
174
|
+
(globalThis as { __world?: World }).__world = world;
|
|
175
|
+
}
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Launch with `npx iwer-native run --query iwsdkDebug=1`, then read state with
|
|
179
|
+
`eval` (for example `__world.player.position.toArray()`, or a value from
|
|
180
|
+
one of your components). Keep state you want to check in ECS components, as
|
|
181
|
+
AGENTS.md asks.
|
|
182
|
+
4. **A debugger:** `npx iwer-native run --inspect --forward 9229`, then open
|
|
183
|
+
`chrome://inspect` and add `localhost:9229`. If the port is
|
|
184
|
+
`still in use`, another debug build holds it:
|
|
185
|
+
`adb shell am force-stop <its packageId>`.
|
|
186
|
+
|
|
187
|
+
**Scripted input does not exist on the APK.** You cannot press, grab or point
|
|
188
|
+
from the CLI. Prove interaction logic in the emulator or Quest Browser with
|
|
189
|
+
`iwsdk-grab`, `iwsdk-ray` and `iwsdk-native-xr-test` (the same IWSDK code runs
|
|
190
|
+
there), and use the APK for what only it can show: that the app starts and
|
|
191
|
+
enters XR, renders, holds frame rate, loads its assets, reaches its network
|
|
192
|
+
origins, and that physics and audio run. Say which claims were verified where.
|
|
193
|
+
|
|
194
|
+
## Step 5 — Ship
|
|
195
|
+
|
|
196
|
+
- Replace `com.example.*` with your own reverse-domain `packageId`; stores
|
|
197
|
+
reject `com.example`. A changed id installs as a separate app.
|
|
198
|
+
- Add a `signing` section (keystore path plus the names of the environment
|
|
199
|
+
variables that hold the passwords) and build with
|
|
200
|
+
`npx iwer-native pack --release`. Never write passwords into
|
|
201
|
+
`iwsdk.config.json` or commit a keystore. Without `signing`, `--release` signs
|
|
202
|
+
with the debug key and warns.
|
|
203
|
+
- Raise `versionCode` for every upload. Set `icon` and `splash` (the README's
|
|
204
|
+
Configuration section lists every key; `iwer-native validate` checks them).
|
|
205
|
+
- Installing a release over a debug build signed with another key fails with
|
|
206
|
+
`INSTALL_FAILED_UPDATE_INCOMPATIBLE`: `adb uninstall <packageId>` first.
|
|
207
|
+
|
|
208
|
+
## Report
|
|
209
|
+
|
|
210
|
+
State the APK path, size and package id, the device serial and OS build
|
|
211
|
+
(`node "$kit/iwn-host.mjs" info`), the compat result, what you verified on the
|
|
212
|
+
APK (with logcat lines, `eval` values or shots) and what you verified only in
|
|
213
|
+
the emulator or Quest Browser, and any warning you left in place with its
|
|
214
|
+
reason. For a runtime bug, collect what the README's Reporting issues section
|
|
215
|
+
lists.
|
|
216
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=c28e2ac59fab5db24f36df736b7f246c7abbc2b016de2ae90a76a9a20669686e name=iwsdk-metavr-native (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Copyright (c) Meta Platforms, Inc. and affiliates.
|
|
4
|
+
*
|
|
5
|
+
* This source code is licensed under the MIT license found in the
|
|
6
|
+
* LICENSE file in the root directory of this source tree.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
// Client for the @iwer/native debug endpoint (debug builds, or
|
|
10
|
+
// `pack --release --inspector`). Forward the port first:
|
|
11
|
+
// adb -s <serial> forward tcp:9229 localabstract:<packageId>_devtools_9229
|
|
12
|
+
//
|
|
13
|
+
// node iwn-host.mjs eval '<expression>' value of the expression (promises awaited)
|
|
14
|
+
// node iwn-host.mjs shot <out.png> [left|right|both] [scale] eye-buffer PNG
|
|
15
|
+
// node iwn-host.mjs stats frame, GC, heap and boot timings
|
|
16
|
+
// node iwn-host.mjs info device, runtime and app identity
|
|
17
|
+
//
|
|
18
|
+
// PORT selects another forwarded port (default 9229). Exit code 1 on an error
|
|
19
|
+
// reply, 2 when the endpoint does not answer.
|
|
20
|
+
import { writeFileSync } from 'node:fs';
|
|
21
|
+
|
|
22
|
+
const [method, ...args] = process.argv.slice(2);
|
|
23
|
+
const port = process.env.PORT || '9229';
|
|
24
|
+
let params;
|
|
25
|
+
let out;
|
|
26
|
+
switch (method) {
|
|
27
|
+
case 'eval':
|
|
28
|
+
params = { expression: args[0] ?? 'undefined', awaitPromise: true };
|
|
29
|
+
break;
|
|
30
|
+
case 'shot':
|
|
31
|
+
out = args[0] ?? 'iwn-shot.png';
|
|
32
|
+
params = { eye: args[1] ?? 'left', scale: Number(args[2] ?? 0.5) };
|
|
33
|
+
break;
|
|
34
|
+
case 'stats':
|
|
35
|
+
case 'info':
|
|
36
|
+
params = {};
|
|
37
|
+
break;
|
|
38
|
+
default:
|
|
39
|
+
console.error('usage: iwn-host.mjs eval <expr> | shot <out.png> [eye] [scale] | stats | info');
|
|
40
|
+
process.exit(2);
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
const timer = setTimeout(() => {
|
|
44
|
+
console.error(`no reply from ws://127.0.0.1:${port}/host: is the app running a debug build, and is the port forwarded?`);
|
|
45
|
+
process.exit(2);
|
|
46
|
+
}, 40_000);
|
|
47
|
+
const ws = new WebSocket(`ws://127.0.0.1:${port}/host`);
|
|
48
|
+
ws.onopen = () => ws.send(JSON.stringify({ id: 1, method, params }));
|
|
49
|
+
ws.onerror = () => {
|
|
50
|
+
console.error(`cannot connect to ws://127.0.0.1:${port}/host: forward the port with adb first`);
|
|
51
|
+
process.exit(2);
|
|
52
|
+
};
|
|
53
|
+
ws.onmessage = (message) => {
|
|
54
|
+
clearTimeout(timer);
|
|
55
|
+
const reply = JSON.parse(String(message.data));
|
|
56
|
+
if (reply.error) {
|
|
57
|
+
console.error(reply.error);
|
|
58
|
+
process.exit(1);
|
|
59
|
+
}
|
|
60
|
+
if (method === 'shot') {
|
|
61
|
+
writeFileSync(out, Buffer.from(reply.png, 'base64'));
|
|
62
|
+
console.log(JSON.stringify({ file: out, width: reply.width, height: reply.height, frame: reply.frame }));
|
|
63
|
+
} else if (method === 'eval') {
|
|
64
|
+
console.log(typeof reply.result === 'string' ? reply.result : JSON.stringify(reply.result ?? null, null, 1));
|
|
65
|
+
} else {
|
|
66
|
+
delete reply.id;
|
|
67
|
+
console.log(JSON.stringify(reply, null, 1));
|
|
68
|
+
}
|
|
69
|
+
ws.close();
|
|
70
|
+
process.exit(0);
|
|
71
|
+
};
|
|
@@ -259,4 +259,4 @@ Report:
|
|
|
259
259
|
If the user wants to try the app in the headset afterwards, start a plain
|
|
260
260
|
session (`npx @iwsdk/cli dev up` with the session's `--ai-mode`, without
|
|
261
261
|
`--native-xr-control`) and give them the plain URL from `dev status`.
|
|
262
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
262
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=931a8822463f2bb6652cbbf2b7571db92e5331af44b598890057319b0177939b name=iwsdk-native-xr-test (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: iwsdk-offline
|
|
3
|
+
description: Make an IWSDK app run with no connection after one online visit — a service worker that keeps one hash-checked copy of the current release, downloads each file once, and swaps releases only when nothing would be interrupted. Use when the app must work offline or survive a dropped connection, when an installed PWA/TWA must launch without a network, or when an offline copy serves a stale release, misses files, or downloads everything twice.
|
|
4
|
+
argument-hint: '[offline goal, e.g. "work offline" or "launch offline from the Store"]'
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Offline Copy
|
|
8
|
+
|
|
9
|
+
A built IWSDK app is a static `dist/`, so it can run with no connection once a
|
|
10
|
+
service worker holds a complete copy of it. This design keeps exactly one
|
|
11
|
+
release on the device: the build lists every file with its SHA-256, the worker
|
|
12
|
+
copies that list and answers from it cache-first, and the page alone decides
|
|
13
|
+
when the next release takes over. Each file crosses the wire once, nothing
|
|
14
|
+
unchecked is kept, and a release never swaps mid-session.
|
|
15
|
+
|
|
16
|
+
User request is in `$ARGUMENTS`.
|
|
17
|
+
|
|
18
|
+
```
|
|
19
|
+
1. Sort the files → release list, kept on request, or never cached
|
|
20
|
+
2. Copy the kit → build script, worker template, page module + build step
|
|
21
|
+
3. Adapt the worker → cache names and PINNED third-party paths
|
|
22
|
+
4. Wire the page → startOffline() and keepOfflineCopy() in src/index.ts
|
|
23
|
+
5. Hosting → sw.js uncached, hashed files immutable [iwsdk-hosting]
|
|
24
|
+
6. Verify → first visit, reload, offline, update, mid-session, two pages
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
The kit in `assets/` was tested end to end in Chromium against an IWSDK starter
|
|
28
|
+
build — first visit, reload, offline, update, and an update during an XR
|
|
29
|
+
session. Copy it verbatim and change only what steps 2–4 name; a rewrite loses
|
|
30
|
+
that.
|
|
31
|
+
|
|
32
|
+
## Step 1 — Sort the files
|
|
33
|
+
|
|
34
|
+
Ask of every file the build emits or the app fetches:
|
|
35
|
+
|
|
36
|
+
| Question | If yes |
|
|
37
|
+
| --- | --- |
|
|
38
|
+
| Does the build produce it, and does every user need it to run? | release list — copied at install |
|
|
39
|
+
| Do only some users need it (extra levels, other languages' fonts, HD packs)? | `ON_REQUEST` — kept the first time it is fetched |
|
|
40
|
+
| Is it a third-party file at a version named in its URL? | `PINNED` — kept in a long-lived cache on first fetch |
|
|
41
|
+
| Does the server decide it per user or per moment (APIs, sign-in, analytics, any non-GET)? | never cached |
|
|
42
|
+
|
|
43
|
+
What the user creates — saves, settings, progress — belongs in IndexedDB or
|
|
44
|
+
`localStorage`, never in the release cache, which is replaced on every update.
|
|
45
|
+
|
|
46
|
+
IWSDK and the starter fetch from other origins at runtime, and the kit's
|
|
47
|
+
`PINNED` already matches all three:
|
|
48
|
+
|
|
49
|
+
- **Controller models** —
|
|
50
|
+
`https://cdn.jsdelivr.net/npm/@webxr-input-profiles/assets@1.0/dist/profiles/<profile>/<handedness>.glb`.
|
|
51
|
+
The path is hard-coded, so the worker's cache is the only way to keep them
|
|
52
|
+
offline. `@1.0` is a release line, not one version; the worker keeps the
|
|
53
|
+
first copy it receives, and keeps the other hand's model with it.
|
|
54
|
+
- **Draco and KTX2 decoders** — `https://unpkg.com/three@0.<revision>.0/…`,
|
|
55
|
+
fetched only when the app loads compressed glTF files or KTX2 textures. Apps
|
|
56
|
+
cannot point IWSDK at self-hosted decoders.
|
|
57
|
+
|
|
58
|
+
- **Stock models** — the starter's `src/assets.ts` loads them from
|
|
59
|
+
`https://cdn.jsdelivr.net/npm/@iwsdk/example-assets@0.4.2/assets/…`. Mirroring
|
|
60
|
+
them under `public/` with `VITE_IWSDK_EXAMPLE_ASSET_BASE_URL` is better:
|
|
61
|
+
mirrored files become release files and are hash-checked like any other.
|
|
62
|
+
Then delete that path from `PINNED`.
|
|
63
|
+
|
|
64
|
+
## Step 2 — Copy the kit
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
kit="$(dirname "$(find .claude/skills .agents/skills -path '*/iwsdk-offline/assets/sw.js.template' -print -quit)")"
|
|
68
|
+
mkdir -p scripts
|
|
69
|
+
cp "$kit/write-service-worker.mjs.template" scripts/write-service-worker.mjs
|
|
70
|
+
cp "$kit/sw.js.template" scripts/sw.js.template
|
|
71
|
+
cp "$kit/offline.ts.template" src/offline.ts
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
In a JavaScript project, save the page module as `src/offline.js` and delete
|
|
75
|
+
its type annotations; nothing else changes. A TypeScript project needs the `.ts`
|
|
76
|
+
file: the scaffold's `tsconfig.json` has no `allowJs`. The worker keeps its
|
|
77
|
+
`.template` extension so Vite, `tsc`, and linters never touch its placeholders.
|
|
78
|
+
|
|
79
|
+
Make the build script the last step of `build` in `package.json`:
|
|
80
|
+
|
|
81
|
+
```json
|
|
82
|
+
"build": "vite build && node scripts/write-service-worker.mjs dist scripts/sw.js.template"
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Run it after `vite build`, never from a plugin's `closeBundle` hook: every
|
|
86
|
+
plugin must have finished writing, or a late file is missing from the list and
|
|
87
|
+
never kept. Its `LEFT_OUT` rules skip source maps (the starter emits them unless
|
|
88
|
+
`NODE_ENV=production`) and `AGENTS.md` (the scaffold keeps agent instructions in
|
|
89
|
+
`public/ui/` and `public/scenes/`, so Vite publishes them); add the app's own
|
|
90
|
+
`LEFT_OUT` and `ON_REQUEST` rules from step 1. Rules, hash signals, and a
|
|
91
|
+
duplicate finder: [`references/build-step.md`](references/build-step.md).
|
|
92
|
+
|
|
93
|
+
## Step 3 — Adapt the worker
|
|
94
|
+
|
|
95
|
+
In `scripts/sw.js.template`, change only:
|
|
96
|
+
|
|
97
|
+
- **`PREFIX`, `KEPT`, `HASH`** — rename for the app. `KEPT` must not start with
|
|
98
|
+
`PREFIX`, or the next activation deletes the third-party cache.
|
|
99
|
+
- **`PINNED`** — the kit pins `three@0.185.0` and `example-assets@0.4.2`, the
|
|
100
|
+
versions new projects get. Match `three@` to the project's `three` in
|
|
101
|
+
`package.json` (`super-three@0.181.0` → `three@0.181.0`) and
|
|
102
|
+
`example-assets@` to `src/assets.ts`, delete paths the app never loads, and
|
|
103
|
+
add any other third-party paths from step 1. If the app fetches nothing from
|
|
104
|
+
other origins, delete `PINNED`, `PAIRED`, `thirdParty()`, `keepPinned()`, and
|
|
105
|
+
`keepPair()`.
|
|
106
|
+
|
|
107
|
+
Never add `skipWaiting()` to `install` or `activate`, and never revalidate in
|
|
108
|
+
`fetch`: the page alone decides when a release takes over, and answers are
|
|
109
|
+
cache-first so that a page is exactly its release. The worker grants a
|
|
110
|
+
take-over only while the asking page is the app's only open page, because it
|
|
111
|
+
moves every open page onto the new release. Request routing, hash checks,
|
|
112
|
+
and updates: [`references/service-worker.md`](references/service-worker.md).
|
|
113
|
+
|
|
114
|
+
## Step 4 — Wire the page
|
|
115
|
+
|
|
116
|
+
In `src/index.ts`:
|
|
117
|
+
|
|
118
|
+
```ts
|
|
119
|
+
import { VisibilityState, World } from '@iwsdk/core';
|
|
120
|
+
import { checkIdle, keepOfflineCopy, startOffline } from './offline.js';
|
|
121
|
+
|
|
122
|
+
let world: World | undefined;
|
|
123
|
+
const isIdle = () =>
|
|
124
|
+
world?.visibilityState.peek() === VisibilityState.NonImmersive;
|
|
125
|
+
startOffline(isIdle); // before World.create()
|
|
126
|
+
|
|
127
|
+
World.create(container, projectOptions).then((created) => {
|
|
128
|
+
world = created;
|
|
129
|
+
// …system registration…
|
|
130
|
+
keepOfflineCopy(isIdle); // after the first screen, not at startup
|
|
131
|
+
created.visibilityState.subscribe(() => checkIdle()); // a session just ended
|
|
132
|
+
});
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
`isIdle()` must be `false` whenever a reload would interrupt anything: an XR
|
|
136
|
+
session (covered above), an unsaved edit, a game in progress. Call
|
|
137
|
+
`checkIdle()` whenever one of those ends, so a release that installed
|
|
138
|
+
meanwhile takes over then rather than at the next load. Registering only
|
|
139
|
+
once `World.create()` has resolved lets the worker take every file from the
|
|
140
|
+
HTTP cache instead of downloading it a second time. The reason for each line:
|
|
141
|
+
[`references/page.md`](references/page.md).
|
|
142
|
+
|
|
143
|
+
## Step 5 — Hosting
|
|
144
|
+
|
|
145
|
+
| Path | Header |
|
|
146
|
+
| --- | --- |
|
|
147
|
+
| `/sw.js` | `Cache-Control: no-cache` |
|
|
148
|
+
| `/assets/*` (Vite's hashed output) | `public, max-age=31536000, immutable` |
|
|
149
|
+
| Unhashed files: images, models, fonts, data | a short `max-age`, optionally `stale-while-revalidate` |
|
|
150
|
+
| HTML | `no-cache` or a short `max-age` |
|
|
151
|
+
| Every path, if a CSP is sent | `worker-src 'self'`, and a `connect-src` naming each `PINNED` path |
|
|
152
|
+
|
|
153
|
+
Serve `sw.js` from the root of the scope it controls; a worker cannot control
|
|
154
|
+
pages above its own folder. It needs a secure context — HTTPS, or
|
|
155
|
+
`http://localhost` for testing. On a host the developer owns, these headers are
|
|
156
|
+
part of the upload handoff, so take them through `iwsdk-hosting`. Then verify:
|
|
157
|
+
|
|
158
|
+
```bash
|
|
159
|
+
curl -sI https://<DOMAIN>/sw.js | grep -i '^cache-control' # want no-cache
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
The `vercel.json` headers for Vercel are in
|
|
163
|
+
[`references/service-worker.md`](references/service-worker.md).
|
|
164
|
+
|
|
165
|
+
## Step 6 — Verify
|
|
166
|
+
|
|
167
|
+
`npm run dev` serves no `sw.js`, so registration fails quietly there and proves
|
|
168
|
+
nothing — verify a production build. Six checks, each about what crosses the
|
|
169
|
+
wire:
|
|
170
|
+
|
|
171
|
+
1. **First visit** — the release cache holds every listed file, and no file was
|
|
172
|
+
sent in full twice.
|
|
173
|
+
2. **Reload** — the server is asked for nothing but `sw.js`.
|
|
174
|
+
3. **Offline** — with the network off, a reload starts the app and kept files
|
|
175
|
+
are served.
|
|
176
|
+
4. **Update while idle** — only the changed file downloads, the new release
|
|
177
|
+
takes over, and the old release cache is gone.
|
|
178
|
+
5. **Update mid-session** — the page is not reloaded during the session; when
|
|
179
|
+
it ends, the new release takes over.
|
|
180
|
+
6. **Two pages open** — an update takes over neither page; once one remains,
|
|
181
|
+
its next idle moment or load takes it.
|
|
182
|
+
|
|
183
|
+
The harness rules (logging server, no Playwright routes, persistent profile,
|
|
184
|
+
polling loops) and headset testing over `adb reverse`:
|
|
185
|
+
[`references/testing.md`](references/testing.md).
|
|
186
|
+
|
|
187
|
+
## Installed apps (PWA/TWA)
|
|
188
|
+
|
|
189
|
+
A packaged Quest app loads `<DOMAIN>` like any page, so the same copy serves it
|
|
190
|
+
offline — after **one online launch**, which is when the copy is made.
|
|
191
|
+
|
|
192
|
+
- `start_url` and `scope` in the manifest must sit inside the worker's scope;
|
|
193
|
+
`/sw.js` covers the whole origin. The worker ignores query strings, so
|
|
194
|
+
`"start_url": "/?source=pwa"` is served the cached `index.html`.
|
|
195
|
+
- The manifest and its icons live in `public/`, so they are in the release list.
|
|
196
|
+
- A web redeploy installs in the background during a launch and takes over when
|
|
197
|
+
the app is idle (no XR session), or on the launch after that — one launch later than without
|
|
198
|
+
the copy. Native changes still need a new APK.
|
|
199
|
+
- An immersive app that auto-enters XR (`iwsdk-pwa-packaging` step 1) spends the
|
|
200
|
+
launch tap on `world.launchXR()`. When a release is waiting, `startOffline()`
|
|
201
|
+
reloads the page at startup to take it, so verify on the headset that the
|
|
202
|
+
reloaded page still enters XR before shipping.
|
|
203
|
+
|
|
204
|
+
## Reference Files
|
|
205
|
+
|
|
206
|
+
| File | Load when |
|
|
207
|
+
| ---- | --------- |
|
|
208
|
+
| [`assets/`](assets/) | Step 2 — `write-service-worker.mjs.template`, `sw.js.template`, `offline.ts.template`; copy, never retype |
|
|
209
|
+
| [`references/build-step.md`](references/build-step.md) | Step 2 — `LEFT_OUT` and `ON_REQUEST`, hash signals, duplicate files |
|
|
210
|
+
| [`references/service-worker.md`](references/service-worker.md) | Step 3 — request routing, what to keep, hash checks, updates, Vercel headers |
|
|
211
|
+
| [`references/page.md`](references/page.md) | Step 4 — what each part of the page module does, and the wiring |
|
|
212
|
+
| [`references/testing.md`](references/testing.md) | Step 6 — the five checks, the harness, headset testing |
|
|
213
|
+
|
|
214
|
+
Publishing the build and its headers is the `iwsdk-hosting` skill, and packaging
|
|
215
|
+
it into a Quest APK is `iwsdk-pwa-packaging`. This skill only makes it work
|
|
216
|
+
offline.
|
|
217
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=7f4f5034d84d6f0aaf3c353603e4d6d18eb99d107c5946ec018f8674e1001f38 name=iwsdk-offline (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|