@iwsdk/cli 1.2.0-rc.0 → 1.2.0-rc.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/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 +1 -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-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 +13 -2
- 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 +1 -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 +1 -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-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 +13 -2
- 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 +1 -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 +111 -11
- 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 +132 -0
- package/dist/version.d.ts +1 -1
- package/package.json +1 -1
|
@@ -80,6 +80,12 @@ it on the headset after sideloading (step 4).
|
|
|
80
80
|
`index.html` ships `<link rel="icon" href="data:," />` and no manifest link, so
|
|
81
81
|
the app is not installable until step 3 adds them.
|
|
82
82
|
|
|
83
|
+
**Optional: launch offline.** The TWA loads `<DOMAIN>` over the network, so with
|
|
84
|
+
no connection an installed app shows an error page instead of the app. If it
|
|
85
|
+
must launch offline, add an offline copy with the `iwsdk-offline` skill before
|
|
86
|
+
packaging: one online launch then keeps the release on the device. Keep the
|
|
87
|
+
manifest's `start_url` and `scope` inside the service worker's scope.
|
|
88
|
+
|
|
83
89
|
Then confirm the app itself is sound before wrapping it — `npm run --if-present typecheck`,
|
|
84
90
|
and `npm run build` producing a `dist/` you have actually loaded. Packaging a
|
|
85
91
|
broken build wastes a full round trip through hosting, signing, and upload.
|
|
@@ -191,6 +197,10 @@ retry the identical command. Tool download, auth, and flag reference:
|
|
|
191
197
|
| App logic, assets, styling, manifest text, icons, asset links | republish `<DOMAIN>`; installed TWA picks it up next launch |
|
|
192
198
|
| Package id, app name, launcher icon, version, **app mode**, signing | rebuild the APK and re-upload |
|
|
193
199
|
|
|
200
|
+
With an offline copy (`iwsdk-offline`), a republished release installs in the
|
|
201
|
+
background during a launch and takes over when the app is idle, or on the
|
|
202
|
+
launch after that.
|
|
203
|
+
|
|
194
204
|
## Security
|
|
195
205
|
|
|
196
206
|
The keystore and the app secret never go near `public/` or `dist/`. After every
|
|
@@ -213,7 +223,8 @@ updated — only replaced by a new Store entry.
|
|
|
213
223
|
| [`references/store-upload.md`](references/store-upload.md) | Step 5 — `ovr-platform-util`, auth, channels, the DDA blocker |
|
|
214
224
|
| [`references/troubleshooting.md`](references/troubleshooting.md) | Anything installed but misbehaving — stuck loading, URL bar, will-not-launch |
|
|
215
225
|
|
|
216
|
-
Getting the app online is the `iwsdk-hosting` skill
|
|
226
|
+
Getting the app online is the `iwsdk-hosting` skill, and keeping it working
|
|
227
|
+
offline is `iwsdk-offline`. Building the app itself is
|
|
217
228
|
`iwsdk-planner` and the other `iwsdk-*` skills — do not re-derive IWSDK
|
|
218
229
|
patterns here.
|
|
219
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
230
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=2fbb9b9e9245162fa8cdb51e0a1396dde89b3d459ad5bcc29b45b92ade7a0022 name=iwsdk-pwa-packaging (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -34,7 +34,7 @@ it is served at `/manifest.webmanifest` with no further wiring.
|
|
|
34
34
|
| Field | Why it matters here |
|
|
35
35
|
| ----- | ------------------- |
|
|
36
36
|
| `name` / `short_name` | `short_name` is the launcher label; keep it under ~12 characters or it truncates |
|
|
37
|
-
| `start_url` / `scope` | must match the hosting path — `/` at an origin root, `/<path>/` on a subpath deployment |
|
|
37
|
+
| `start_url` / `scope` | must match the hosting path — `/` at an origin root, `/<path>/` on a subpath deployment; with an offline copy (`iwsdk-offline`), both must also sit inside the service worker's scope |
|
|
38
38
|
| `display` | `standalone` for both modes; `browser` forces a URL bar |
|
|
39
39
|
| `background_color` | painted before first frame — match the app's clear color or launch flashes white |
|
|
40
40
|
| `theme_color` | colors the custom tab bar on a 2D panel; add `theme_color_dark` if the app is dark-first |
|
package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md
CHANGED
|
@@ -10,6 +10,8 @@ symptoms, so start there.
|
|
|
10
10
|
| Opens with a browser URL bar | `horizonOSAppMode: "2D"` on an immersive app | [App mode](#app-mode-failures) |
|
|
11
11
|
| Opens flat, no URL bar, never enters VR | auto-enter code missing or not firing | [App mode](#app-mode-failures) |
|
|
12
12
|
| Blank / white / error page | the origin is unreachable from the device | [Origin](#origin-failures) |
|
|
13
|
+
| Error page only when the headset is offline | no offline copy, or the app never launched online | [Offline](#offline-failures) |
|
|
14
|
+
| Old version after a web redeploy | an offline copy waiting for an idle moment or the next launch | [Offline](#offline-failures) |
|
|
13
15
|
|
|
14
16
|
Before diagnosing, establish which layer is wrong. A **web** bug is fixed by
|
|
15
17
|
republishing `<DOMAIN>`; a **native** bug needs a new APK and a new upload.
|
|
@@ -116,6 +118,34 @@ to `/<path>/` and republish. The scaffolded `base: './'` handles the bundle
|
|
|
116
118
|
paths already, so if bundles load and only `public/` assets 404, look for a
|
|
117
119
|
publish that missed those files.
|
|
118
120
|
|
|
121
|
+
## Offline failures
|
|
122
|
+
|
|
123
|
+
These apply only when the site keeps an offline copy (`iwsdk-offline`).
|
|
124
|
+
|
|
125
|
+
### Error page only when the headset is offline
|
|
126
|
+
|
|
127
|
+
The device has no copy to serve. Usually one of:
|
|
128
|
+
|
|
129
|
+
- **No offline copy** — the site registers no service worker. Add one with
|
|
130
|
+
`iwsdk-offline`.
|
|
131
|
+
- **The app never launched online** since the copy was added. The copy is made
|
|
132
|
+
on the first online launch.
|
|
133
|
+
- **`start_url` or `scope` sits outside the worker's scope**, so the launch
|
|
134
|
+
misses the copy. Serve `sw.js` from the root of that scope.
|
|
135
|
+
|
|
136
|
+
Confirm the worker is live and uncached:
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
curl -sI https://<DOMAIN>/sw.js | grep -iE '^(HTTP|cache-control)' # want 200, no-cache
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### Old version after a web redeploy
|
|
143
|
+
|
|
144
|
+
Expected for one launch: the new release installs in the background during a
|
|
145
|
+
launch and takes over when the app is idle, or on the launch after that. If it
|
|
146
|
+
never arrives, `sw.js` is being cached — serve it with `Cache-Control: no-cache`
|
|
147
|
+
and purge the CDN.
|
|
148
|
+
|
|
119
149
|
## Packaging failures
|
|
120
150
|
|
|
121
151
|
### bubblewrap hangs or exits without doing anything
|
|
@@ -67,4 +67,4 @@ When the request names an artifact path, save it directly with
|
|
|
67
67
|
context and then add a copy step.
|
|
68
68
|
Stop when the real input and resulting named state are proven, leaving all
|
|
69
69
|
buttons released.
|
|
70
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
70
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=ec23dce5226ca91367042de7907fb3664c055a1ceb737fede2fd6710eab1f37f name=iwsdk-ray (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -265,10 +265,17 @@ npx @iwsdk/cli xr set-input-mode --input-json '{"mode":"hand"}'
|
|
|
265
265
|
npx @iwsdk/cli xr run-sequence --input-json '{"device":"hand-right","steps":[{"target":"Btn_Action","press":{}}]}' --timeout 45000
|
|
266
266
|
```
|
|
267
267
|
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
268
|
+
A press result reports contact, not a click: a `presses[0].contactMs` of 800 or
|
|
269
|
+
less does not prove the control clicked, because the fingertip can touch the
|
|
270
|
+
panel or a neighbouring control instead. Verify the click by the state it
|
|
271
|
+
changes, with `ui inspect` on the control or a query of the app state it
|
|
272
|
+
drives, and press once more if nothing changed. A contact of more than 800 ms
|
|
273
|
+
never clicks. A slow headless frame can hold the touch that long. So can a
|
|
274
|
+
press on a control out of reach: the body walks to it during the press (a
|
|
275
|
+
contact of seconds). Walk to such a control in a step of its own before the
|
|
276
|
+
press:
|
|
277
|
+
`"steps":[{"body":{"stepTo":"Btn_Action"}},{"target":"Btn_Action","press":{}}]`.
|
|
278
|
+
`xr list-targets` lists the element IDs that can be pressed.
|
|
272
279
|
|
|
273
280
|
The commands in this section are the supported path. Do not call broad
|
|
274
281
|
`iwsdk`, `ui`, `browser`, `ecs`, or `xr` help. If a shown command fails, use its
|
|
@@ -325,4 +332,4 @@ The final visual check must confirm:
|
|
|
325
332
|
Finish with a passing typecheck and production build, no UIKit parser/resource
|
|
326
333
|
errors, and concise runtime evidence. Remove temporary preview files or camera
|
|
327
334
|
workarounds that are not deliverables.
|
|
328
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
335
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=9b79caeeedded4cb53e69688c7e5006daa1187c951a333ef06cbdb3063f062a2 name=iwsdk-ui (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -71,4 +71,4 @@ error-free browser log, and enter XR when the app is an XR app.
|
|
|
71
71
|
|
|
72
72
|
The upgrade is done when every migration guide is applied, the comparison
|
|
73
73
|
shows no new errors, and the user knows which existing errors remain.
|
|
74
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
74
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=5ccb37dbe152b3611496740e89bc8e42c8d59dfed8be7512635d877924b79988 name=iwsdk-upgrade (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -518,4 +518,4 @@ Only report issues you're confident about:
|
|
|
518
518
|
|
|
519
519
|
[Brief summary of overall code quality and key recommendations]
|
|
520
520
|
```
|
|
521
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
521
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=976bd24f6ae91d050ed7bef71cdfb4cfab1fc41e4718d2042d9618860cb1161e name=iwsdk-project-code-reviewer.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -57,4 +57,4 @@ mesh lowers to one `InstancedMesh`.
|
|
|
57
57
|
Start assets at `castShadow: false` and opt in only for grounded focal masses.
|
|
58
58
|
Don't build contact-shadow blob cards or `ShadowMaterial` catcher planes here: put
|
|
59
59
|
`ContactShadow` or `ShadowCatcher` node components on the scene nodes instead.
|
|
60
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
60
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=9c0abbe2f1b3cc83f826ac6a5c24f0088375757ec17bfb970301a3c32b940a44 name=assets-and-manifest.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -100,4 +100,4 @@ buttons. Browser controls live at `world.input.keyboard` and
|
|
|
100
100
|
`world.visibilityState` reports `NonImmersive`, `Visible`, `VisibleBlurred` —
|
|
101
101
|
pause simulation on blur. `world.camera.position` is local to `world.player`; use
|
|
102
102
|
`getWorldPosition()` when logic needs the true viewer position.
|
|
103
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
103
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=56f1044b9936f279404ef715676b734a119ef495824d5916737f3a00579acc64 name=ecs-api.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -69,4 +69,4 @@ back. Render each changed module before the root.
|
|
|
69
69
|
|
|
70
70
|
For composing a scene rather than editing one, use the `iwsdk-compose-scene`
|
|
71
71
|
skill — it owns the intake, review and stop-rule procedure this file does not.
|
|
72
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
72
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=d507943047667757a27a1b58cff203b0e3d1bdc646b0f5998cf0851840dde550 name=scene-json.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -63,4 +63,4 @@ can.
|
|
|
63
63
|
For the authoring procedure — isolated preview, placement, editing, wiring
|
|
64
64
|
runtime behavior, and the completion checklist — use the `iwsdk-ui` skill rather
|
|
65
65
|
than improvising. This file is the format reference it relies on.
|
|
66
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
66
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=101e26d6362ef8867f020086e5edae81ae70c45a11e53339171da8591f41f1a6 name=uikitml.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -309,4 +309,4 @@ Hand `iwsdk-compose-scene`:
|
|
|
309
309
|
|
|
310
310
|
Do not compensate for a model-local defect with a scene transform. Do not start scene
|
|
311
311
|
lighting or camera iteration until the model passes isolated review.
|
|
312
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
312
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=95fc72ddf1f3915aa71a839558a3ce051b803214b25ad8c594e882068a3d7917 name=iwsdk-build-model (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -274,4 +274,4 @@ components, schema errors, image reconstruction, or ambiguous composition eviden
|
|
|
274
274
|
When the Fast Path does not apply, read and follow
|
|
275
275
|
[extended-workflow.md](references/extended-workflow.md). Do not load that reference
|
|
276
276
|
for a routine scene assembled from known manifest assets.
|
|
277
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
277
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=e6feb83023b2ddbe9a3cceea3b0deda0fe8beb9743d4af6b8e0a89ea31e61b93 name=iwsdk-compose-scene (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -71,4 +71,4 @@ established from the measured state.
|
|
|
71
71
|
Make at most one focused correction. Stop when the original symptom no longer
|
|
72
72
|
reproduces and the measured state agrees with the intended behavior. Call
|
|
73
73
|
`ecs_resume` before finishing and leave input buttons released.
|
|
74
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
74
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=7dd8250ca95e23b6f0696a86a3dfcb2d038ac730a7578118fb21290c6169c3f0 name=iwsdk-debug (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -85,4 +85,4 @@ not alter the project camera or render extra authored angles to manufacture an
|
|
|
85
85
|
occlusion view; stage the requested nodes once, then judge the live AR capture.
|
|
86
86
|
Do not inspect framework source when the build, registered-system query, entity
|
|
87
87
|
components, and console warnings already establish the failing layer.
|
|
88
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
88
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=819e3f213766f12b567fa8ffd5e343f1a17f83973642067d82ebd7c5dee1dbe3 name=iwsdk-depth-occlusion (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -43,4 +43,4 @@ Observable workspace state wins over wording:
|
|
|
43
43
|
|
|
44
44
|
iwsdk-dev does not add another implementation phase. The selected playbook owns
|
|
45
45
|
the work, evidence budget, specialist routing, verification, and stopping rule.
|
|
46
|
-
<!-- iwsdk-agent-guidance version=1.2.0-rc.
|
|
46
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=58d4ce27ef04658c338d8bb0883b0718ba52037bd043fcc5f80783550bc20673 name=iwsdk-dev (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -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.1 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.1 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.1 sha256=360be8c5297e0b33bdbdf82188b95dbbcfc586b00d0c0840a21094eb9745e21d name=iwsdk-hosting (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -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.1 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.1 sha256=7f4f5034d84d6f0aaf3c353603e4d6d18eb99d107c5946ec018f8674e1001f38 name=iwsdk-offline (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Copyright (c) Meta Platforms, Inc. and affiliates.
|
|
3
|
+
*
|
|
4
|
+
* This source code is licensed under the MIT license found in the
|
|
5
|
+
* LICENSE file in the root directory of this source tree.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
// src/offline.ts: the page's side. Call startOffline() first thing at startup, keepOfflineCopy()
|
|
9
|
+
// once the first screen is up, and checkIdle() whenever the app becomes idle (an XR session ends).
|
|
10
|
+
// isIdle() is your app's own test: would a reload now interrupt nothing?
|
|
11
|
+
|
|
12
|
+
export function startOffline(isIdle: () => boolean): void {
|
|
13
|
+
if (!('serviceWorker' in navigator)) return;
|
|
14
|
+
const hadCopy = navigator.serviceWorker.controller != null;
|
|
15
|
+
navigator.serviceWorker
|
|
16
|
+
.getRegistration()
|
|
17
|
+
.then((registration) => {
|
|
18
|
+
if (registration == null) return;
|
|
19
|
+
// A release that finished installing on an earlier visit takes over before anything starts.
|
|
20
|
+
if (registration.waiting != null && hadCopy)
|
|
21
|
+
takeOver(registration.waiting);
|
|
22
|
+
else watch(registration, isIdle);
|
|
23
|
+
})
|
|
24
|
+
.catch(() => {});
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
export function keepOfflineCopy(isIdle: () => boolean): void {
|
|
28
|
+
if (!('serviceWorker' in navigator)) return;
|
|
29
|
+
navigator.serviceWorker
|
|
30
|
+
.register('./sw.js', { scope: './' })
|
|
31
|
+
.then((registration) => {
|
|
32
|
+
watch(registration, isIdle);
|
|
33
|
+
// Ask the browser not to evict the copy under storage pressure. It decides without a prompt.
|
|
34
|
+
navigator.storage?.persist?.().catch(() => {});
|
|
35
|
+
// Tell the worker what the page fetched before it took control, so it can keep optional files.
|
|
36
|
+
new PerformanceObserver((list) => {
|
|
37
|
+
const fetched = list.getEntries().map((entry) => entry.name);
|
|
38
|
+
navigator.serviceWorker.ready.then((ready) =>
|
|
39
|
+
ready.active?.postMessage({ fetched }),
|
|
40
|
+
);
|
|
41
|
+
}).observe({ type: 'resource', buffered: true });
|
|
42
|
+
})
|
|
43
|
+
.catch(() => {
|
|
44
|
+
// No offline copy (storage turned off, some private windows): the app still runs online.
|
|
45
|
+
});
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
// A release that installed while the app was busy waits; call this when the app becomes idle to
|
|
49
|
+
// let it take over now rather than at the next load.
|
|
50
|
+
export function checkIdle(): void {
|
|
51
|
+
retry?.();
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
const watched = new WeakSet<ServiceWorkerRegistration>();
|
|
55
|
+
let retry: (() => void) | undefined;
|
|
56
|
+
|
|
57
|
+
function watch(
|
|
58
|
+
registration: ServiceWorkerRegistration,
|
|
59
|
+
isIdle: () => boolean,
|
|
60
|
+
): void {
|
|
61
|
+
if (watched.has(registration)) return;
|
|
62
|
+
watched.add(registration);
|
|
63
|
+
const follow = (worker: ServiceWorker | null) => {
|
|
64
|
+
if (worker == null) return;
|
|
65
|
+
const settled = () => {
|
|
66
|
+
// Otherwise the release waits, and the next load takes it at startup.
|
|
67
|
+
if (
|
|
68
|
+
worker.state === 'installed' &&
|
|
69
|
+
navigator.serviceWorker.controller != null &&
|
|
70
|
+
isIdle()
|
|
71
|
+
) {
|
|
72
|
+
takeOver(worker);
|
|
73
|
+
}
|
|
74
|
+
};
|
|
75
|
+
if (worker.state === 'installed') settled();
|
|
76
|
+
else worker.addEventListener('statechange', settled);
|
|
77
|
+
};
|
|
78
|
+
retry = () => follow(registration.waiting);
|
|
79
|
+
follow(registration.waiting);
|
|
80
|
+
follow(registration.installing); // an update the navigation started before this script ran
|
|
81
|
+
registration.addEventListener('updatefound', () =>
|
|
82
|
+
follow(registration.installing),
|
|
83
|
+
);
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
let listening = false;
|
|
87
|
+
|
|
88
|
+
// The worker takes over only if this is the only page of the app open; asking again later is safe.
|
|
89
|
+
function takeOver(worker: ServiceWorker): void {
|
|
90
|
+
if (!listening) {
|
|
91
|
+
listening = true;
|
|
92
|
+
navigator.serviceWorker.addEventListener(
|
|
93
|
+
'controllerchange',
|
|
94
|
+
() => location.reload(),
|
|
95
|
+
{ once: true },
|
|
96
|
+
);
|
|
97
|
+
}
|
|
98
|
+
worker.postMessage('take-over');
|
|
99
|
+
}
|