@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.
Files changed (103) hide show
  1. package/README.md +40 -13
  2. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +1 -1
  3. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +1 -1
  4. package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +1 -1
  5. package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +1 -1
  6. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +20 -1
  7. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +2 -1
  8. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +15 -1
  9. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +7 -3
  10. package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +1 -1
  11. package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +1 -1
  12. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +3 -2
  13. package/dist/agent-guidance/files/.agents/skills/iwsdk-metavr-native/SKILL.md +216 -0
  14. package/dist/agent-guidance/files/.agents/skills/iwsdk-metavr-native/assets/iwn-host.mjs +71 -0
  15. package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +1 -1
  16. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/SKILL.md +217 -0
  17. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/offline.ts.template +99 -0
  18. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/sw.js.template +241 -0
  19. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
  20. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/build-step.md +71 -0
  21. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/page.md +70 -0
  22. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/service-worker.md +107 -0
  23. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/testing.md +57 -0
  24. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +1 -1
  25. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +1 -0
  26. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +9 -3
  27. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +18 -3
  28. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +1 -1
  29. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +30 -0
  30. package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +1 -1
  31. package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +12 -5
  32. package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +1 -1
  33. package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +1 -1
  34. package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +1 -1
  35. package/dist/agent-guidance/files/.claude/rules/ecs-api.md +1 -1
  36. package/dist/agent-guidance/files/.claude/rules/scene-json.md +1 -1
  37. package/dist/agent-guidance/files/.claude/rules/uikitml.md +1 -1
  38. package/dist/agent-guidance/files/.claude/settings.json +2 -0
  39. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +1 -1
  40. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +1 -1
  41. package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +1 -1
  42. package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +1 -1
  43. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +20 -1
  44. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +2 -1
  45. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +15 -1
  46. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +7 -3
  47. package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +1 -1
  48. package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +1 -1
  49. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +3 -2
  50. package/dist/agent-guidance/files/.claude/skills/iwsdk-metavr-native/SKILL.md +216 -0
  51. package/dist/agent-guidance/files/.claude/skills/iwsdk-metavr-native/assets/iwn-host.mjs +71 -0
  52. package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +1 -1
  53. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/SKILL.md +217 -0
  54. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/offline.ts.template +99 -0
  55. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/sw.js.template +241 -0
  56. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
  57. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/build-step.md +71 -0
  58. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/page.md +70 -0
  59. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/service-worker.md +107 -0
  60. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/testing.md +57 -0
  61. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +1 -1
  62. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +1 -0
  63. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +9 -3
  64. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +18 -3
  65. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +1 -1
  66. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +30 -0
  67. package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +1 -1
  68. package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +12 -5
  69. package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +1 -1
  70. package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +1 -1
  71. package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +1 -1
  72. package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +1 -1
  73. package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +1 -1
  74. package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +1 -1
  75. package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +1 -1
  76. package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +1 -1
  77. package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +1 -1
  78. package/dist/agent-guidance/files/AGENTS.md +10 -1
  79. package/dist/agent-guidance/files/public/scenes/AGENTS.md +1 -1
  80. package/dist/agent-guidance/files/public/ui/AGENTS.md +1 -1
  81. package/dist/agent-guidance/files/src/AGENTS.md +1 -1
  82. package/dist/agent-guidance/manifest.json +142 -12
  83. package/dist/agent-guidance.d.ts +31 -4
  84. package/dist/agent-guidance.d.ts.map +1 -1
  85. package/dist/agent-guidance.js +269 -60
  86. package/dist/agent-guidance.js.map +1 -1
  87. package/dist/cli.js +1128 -131
  88. package/dist/cli.js.map +1 -1
  89. package/dist/commands/upgrade.d.ts +87 -0
  90. package/dist/commands/upgrade.d.ts.map +1 -1
  91. package/dist/guidance-refresh.d.ts +23 -3
  92. package/dist/guidance-refresh.d.ts.map +1 -1
  93. package/dist/help.d.ts.map +1 -1
  94. package/dist/index.d.ts.map +1 -1
  95. package/dist/index.js +1128 -131
  96. package/dist/index.js.map +1 -1
  97. package/dist/metavr-telemetry.d.ts +6 -0
  98. package/dist/metavr-telemetry.d.ts.map +1 -1
  99. package/dist/package-manager.d.ts +6 -0
  100. package/dist/package-manager.d.ts.map +1 -1
  101. package/dist/release-notes.json +183 -0
  102. package/dist/version.d.ts +1 -1
  103. package/package.json +1 -1
@@ -0,0 +1,71 @@
1
+ # Build Step
2
+
3
+ `scripts/write-service-worker.mjs` (copied from
4
+ `assets/write-service-worker.mjs.template`) runs after `vite build`, once every
5
+ output file — `public/` included — is in `dist/`. It hashes each file, sorts it
6
+ into a list, names the release, and writes `dist/sw.js` from
7
+ `scripts/sw.js.template`.
8
+
9
+ ```json
10
+ {
11
+ "scripts": {
12
+ "build": "vite build && node scripts/write-service-worker.mjs dist scripts/sw.js.template"
13
+ }
14
+ }
15
+ ```
16
+
17
+ It prints `sw.js: release <name>, <n> files, <m> on request`. Read that line
18
+ after every change to the rules.
19
+
20
+ ## Rewrite the rules for the app
21
+
22
+ - **`LEFT_OUT`** — never listed. Keep the worker itself, source maps, crawler
23
+ and link-preview files, and `AGENTS.md`; add anything nothing requests.
24
+ - **`ON_REQUEST`** — listed with its hash, but copied only once the page fetches
25
+ it. Use it for files only some users need: copying them for everyone costs
26
+ every user for the benefit of a few. The kit's two rules
27
+ (`fonts/(ja|ko|zh)-`, `levels/extra-`) are examples; replace them.
28
+
29
+ ## Three details that matter
30
+
31
+ - The paths are sorted before hashing, so the same output always gives the same
32
+ release name, and an unchanged build writes a byte-identical `sw.js`, which
33
+ browsers ignore.
34
+ - The placeholders are replaced through functions, because a replacement string
35
+ would read `$&` in a file name as a pattern.
36
+ - The script must run after every file exists: a file written later is missing
37
+ from the list, so it is never kept. That is why it runs after `vite build`
38
+ rather than from a plugin's `closeBundle` hook.
39
+
40
+ ## Identify files by hash
41
+
42
+ Decide everything by the SHA-256 of a file's bytes, never by its name, date, or
43
+ version number. The one hash answers three questions: did the file change since
44
+ the last release, is a copy already on the device, and is the copy just
45
+ downloaded the right one.
46
+
47
+ | Signal | Decide by it? | Why |
48
+ | --- | --- | --- |
49
+ | SHA-256 of the bytes, computed at build | yes | the same bytes give the same hash on any machine |
50
+ | Hashed file names (`index-3f9a2c.js`) | only for Vite's own output | files copied from `public/` keep their names when their content changes |
51
+ | Modification time | no | a fresh checkout or a CI build gives every file a new time |
52
+ | `ETag` or `Last-Modified` | no | each server or CDN edge computes its own |
53
+ | One version number for the whole app | only as a label | a new number makes every file look changed, so every user downloads everything again |
54
+
55
+ ## Duplicate files
56
+
57
+ Two paths with identical bytes share a hash but are stored twice, because the
58
+ Cache API keys entries by URL. To find them, group the list by hash inside
59
+ `writeServiceWorker()` (`Object.groupBy` needs Node.js 21 or later):
60
+
61
+ ```js
62
+ const byHash = Object.groupBy(Object.entries(files), ([, hash]) => hash);
63
+ for (const group of Object.values(byHash)) {
64
+ if (group.length > 1)
65
+ console.warn('same bytes:', group.map(([path]) => path).join(', '));
66
+ }
67
+ ```
68
+
69
+ One duplicate is built in: the page loads `/`, but the list names `index.html`,
70
+ so a first visit fetches the entry page twice under two URLs. It is usually a
71
+ few kilobytes; list the entry page under its own URL if that matters.
@@ -0,0 +1,70 @@
1
+ # Page Side
2
+
3
+ `src/offline.ts` (copied from `assets/offline.ts.template`) decides two moments:
4
+ when the copy is made, and when a new release may take over. It exports three
5
+ functions:
6
+
7
+ - **`startOffline(isIdle)`** — call first thing at startup. If a release
8
+ finished installing on an earlier visit, it takes over before anything
9
+ starts; otherwise it watches for one.
10
+ - **`keepOfflineCopy(isIdle)`** — call once the first screen is up. It registers
11
+ `./sw.js`, asks the browser to keep the copy with `navigator.storage.persist()`,
12
+ and reports what the page fetched before the worker existed.
13
+ - **`checkIdle()`** — call whenever the app becomes idle, such as when an XR
14
+ session ends. A release that installed while the app was busy takes over
15
+ then, instead of waiting for the next load.
16
+
17
+ In a JavaScript project, save it as `src/offline.js` and delete the type
18
+ annotations. In a TypeScript project it must be `.ts`: the scaffold's
19
+ `tsconfig.json` has no `allowJs`, so importing a `.js` module fails
20
+ `npm run typecheck`.
21
+
22
+ ## Wiring in `src/index.ts`
23
+
24
+ ```ts
25
+ import { VisibilityState, World } from '@iwsdk/core';
26
+ import projectOptions from 'virtual:iwsdk-project';
27
+ import { checkIdle, keepOfflineCopy, startOffline } from './offline.js';
28
+
29
+ let world: World | undefined;
30
+ const isIdle = () =>
31
+ world?.visibilityState.peek() === VisibilityState.NonImmersive;
32
+ startOffline(isIdle);
33
+
34
+ World.create(
35
+ document.getElementById('scene-container') as HTMLDivElement,
36
+ projectOptions,
37
+ ).then((created) => {
38
+ world = created;
39
+ // ... register your systems ...
40
+ keepOfflineCopy(isIdle);
41
+ created.visibilityState.subscribe(() => checkIdle());
42
+ });
43
+ ```
44
+
45
+ ## Why each part is there
46
+
47
+ - **Register after the first screen, not at startup.** Registered at startup,
48
+ the worker downloads the release while the page is still downloading it, so
49
+ every file comes down twice. Registered later, the worker takes each file from
50
+ the HTTP cache instead.
51
+ - **Report what came before the worker.** Files the page fetched before the
52
+ worker existed never passed through it. The buffered `PerformanceObserver`
53
+ reports them, and the worker keeps the optional and pinned ones among them.
54
+ The browser buffers 250 resource entries by default; if the first load fetches
55
+ more, raise the limit early with `performance.setResourceTimingBufferSize()`.
56
+ - **Define idle for the app.** `isIdle()` must be `false` whenever a reload
57
+ could lose work or interrupt a session. No XR session is the IWSDK baseline;
58
+ add the app's own state, such as an unsaved edit or a game in progress, and
59
+ call `checkIdle()` when that state ends. When `isIdle()` is `true` and a new
60
+ release has installed, the page sends `'take-over'`, listens for
61
+ `controllerchange`, and reloads into the new release. The worker ignores the
62
+ request while another page of the app is open, so asking again later is safe.
63
+ - **Catch an install already under way.** The browser checks `sw.js` as the page
64
+ navigates, so an update can be installing before the page's script runs, its
65
+ `updatefound` already gone. `watch()` follows `registration.waiting`,
66
+ `registration.installing`, and the next `updatefound`, so none is missed.
67
+ - **Mirror the connection.** `navigator.onLine` and the `online` and `offline`
68
+ events say whether the device has a network, not whether the server answers.
69
+ Use them to disable or explain features that need a connection, and still
70
+ handle failed requests.
@@ -0,0 +1,107 @@
1
+ # Service Worker
2
+
3
+ `scripts/sw.js.template` (copied from `assets/sw.js.template`) has three
4
+ placeholders — `RELEASE`, `FILES`, and `ON_REQUEST` — that the build step fills
5
+ in. It is plain JavaScript with no imports, so it is copied, not bundled. Install
6
+ copies the release, activate removes older releases, and fetch answers from the
7
+ copy.
8
+
9
+ ## Request routing
10
+
11
+ | Request | Answered from |
12
+ | --- | --- |
13
+ | Anything but a GET | the network, untouched |
14
+ | A pinned third-party URL | its long-lived cache; else the network, and kept |
15
+ | A path in `FILES` | the release cache; the network only if the browser evicted it |
16
+ | A path in `ON_REQUEST` | the release cache once kept; until then the network, kept if its hash matches |
17
+ | A navigation to a folder, such as the site root | that folder's `index.html` from the release cache |
18
+ | Anything else | the network, untouched |
19
+
20
+ ## What to change
21
+
22
+ - **`PREFIX`, `KEPT`, `HASH`** — rename for the app. `KEPT` must not start with
23
+ `PREFIX`, or the next activation deletes it.
24
+ - **`PINNED`** — covers IWSDK's controller models, the three.js decoders, and
25
+ the starter's stock models on jsDelivr. Match `three@` to the project's
26
+ three.js revision and `example-assets@` to `src/assets.ts`, and delete the
27
+ stock-model path if the app mirrors those files or never loads them. If the
28
+ app fetches nothing from other origins, delete `PINNED`, `PAIRED`,
29
+ `thirdParty()`, `keepPinned()`, and `keepPair()`.
30
+
31
+ Third-party files often come in families. IWSDK's controller models come as
32
+ `left.glb` and `right.glb` in the same profile folder, so `PAIRED` keeps the
33
+ other hand's model whenever one is kept: a user who only ever used one
34
+ controller online still has both offline. Add a rule like it for any other
35
+ family the app fetches piece by piece.
36
+
37
+ ## Behaviour to keep
38
+
39
+ - **Cache-first, with no revalidation.** A page loaded from the copy is exactly
40
+ its release, and a new release arrives only through `sw.js`.
41
+ - **Query strings are ignored**, so a start URL such as `/?source=pwa` gets the
42
+ cached `index.html`.
43
+ - **No `skipWaiting()` of its own.** The worker calls it only on the page's
44
+ `'take-over'` message; the page decides when a release takes over.
45
+ - **A take-over needs the asking page to be alone.** `skipWaiting()` moves every
46
+ open page of the scope onto the new release, and activation deletes the old
47
+ release's cache under them: a second tab in the middle of an XR session would
48
+ load the new release's files, or none offline. So the worker grants
49
+ `'take-over'` only when one window of the scope is open; otherwise the release
50
+ waits until every page has closed, and the browser activates it then.
51
+ - **Only CORS responses are kept.** A `no-cors` request returns an opaque
52
+ response with status `0` and an unreadable body, which cannot be checked.
53
+
54
+ ## Where the hash is compared
55
+
56
+ - **At build.** The release is named by a hash of its whole file list, so it
57
+ changes exactly when a listed file changes.
58
+ - **At install, file by file.** The worker looks in this release's own cache
59
+ first (an interrupted install resumes), then in earlier releases' caches, then
60
+ in the HTTP cache, and only then asks the server. Each cached copy carries its
61
+ hash in an `x-content-sha256` header, so an unchanged file is copied across,
62
+ never downloaded.
63
+ - **After every download.** The bytes are hashed before they are cached. A
64
+ mismatch is asked for again with `cache: 'no-cache'`, and a second mismatch
65
+ fails the install, which the browser retries on a later visit. This catches
66
+ stale CDN edges and a deploy that is still spreading.
67
+ - **On a first visit.** The page downloads its files before the worker exists,
68
+ and the worker takes them from the HTTP cache, so nothing crosses the wire
69
+ twice.
70
+ - **For optional files.** The same check runs when one is first fetched: a
71
+ stale copy is served that once and never kept.
72
+ - **For third-party files.** They have no hash in the list. The pinned URL is
73
+ their identity, and each is kept once per device.
74
+
75
+ ## Updates
76
+
77
+ A new release installs beside the old one and waits. The page decides when it
78
+ takes over: at once if `isIdle()` is `true`, when the app next calls
79
+ `checkIdle()` while idle, or otherwise at the next load, before the app builds
80
+ anything — each time only if no other page of the app is open. Installing reuses every unchanged file from the old
81
+ release's cache by its hash, so an update downloads only what changed. Optional
82
+ files the old release kept come across while their hash is unchanged, and the
83
+ third-party cache is never touched. After `'take-over'`, activation deletes the
84
+ older release caches and claims the page, which sees `controllerchange` and
85
+ reloads from the new copy.
86
+
87
+ ## Vercel headers
88
+
89
+ ```json
90
+ {
91
+ "headers": [
92
+ {
93
+ "source": "/sw.js",
94
+ "headers": [{ "key": "Cache-Control", "value": "no-cache" }]
95
+ },
96
+ {
97
+ "source": "/assets/(.*)",
98
+ "headers": [
99
+ {
100
+ "key": "Cache-Control",
101
+ "value": "public, max-age=31536000, immutable"
102
+ }
103
+ ]
104
+ }
105
+ ]
106
+ }
107
+ ```
@@ -0,0 +1,57 @@
1
+ # Testing the Offline Copy
2
+
3
+ Six checks prove the design. Each is about what crosses the wire, so the test
4
+ watches the wire.
5
+
6
+ | # | Check | Pass when |
7
+ | - | ----- | --------- |
8
+ | 1 | First visit | the release cache holds every listed file; no file was sent in full twice; no optional file nobody asked for was downloaded; optional and pinned files fetched before the worker existed are kept |
9
+ | 2 | Reload | the server is asked for nothing but `sw.js` |
10
+ | 3 | Offline | with the network off, a reload starts the app and kept files are served; an optional file never fetched online is missing, as it should be |
11
+ | 4 | Update while idle | after one file changes, only that file is downloaded; the new release takes over; the old release cache is gone; kept optional files came across |
12
+ | 5 | Update mid-session | the page is not reloaded during the session; when it ends, the new release takes over |
13
+ | 6 | Two pages open | an update while a second page of the app is open takes over neither page; once only one remains, the next idle moment or load takes it |
14
+
15
+ ## Harness
16
+
17
+ - **A logging server.** Serve the built `dist/` from a small server that logs
18
+ every request and answers revalidations with ETags and `304`, as a real host
19
+ does. Count only full `200` responses per path: a path sent twice is a
20
+ duplicate download.
21
+ - **No request interception.** Playwright turns the HTTP cache off whenever a
22
+ route is registered, and the first copy is made from that cache.
23
+ - **A persistent browser profile** (`launchPersistentContext`). It keeps the
24
+ HTTP cache on disk, as on a real device; an in-memory cache may refuse a large
25
+ file.
26
+ - **Polling loops.** Wait by calling `page.evaluate()` in a loop.
27
+ `page.waitForFunction()` does not wait for an async predicate, because a
28
+ promise counts as truthy.
29
+ - **An offline switch.** `context.setOffline(true)` takes the context offline
30
+ for check 3.
31
+ - **An XR session for check 5.** In desktop Chromium the injected IWER emulator
32
+ provides one: call `world.launchXR()` and wait until `world.visibilityState`
33
+ leaves `'non-immersive'`, so `isIdle()` is `false`.
34
+
35
+ Playwright attaches to every service worker, and that can stall activation after
36
+ `skipWaiting()` for over a minute, in some runs and not in others. If checks 4
37
+ or 5 hang on the take-over, drive them over the Chrome DevTools Protocol with
38
+ only the page attached, or by hand.
39
+
40
+ ## On the headset
41
+
42
+ Test a production build: `npm run dev` serves no `sw.js`. Build, serve `dist/`
43
+ over plain HTTP on a local port, and forward it so that
44
+ `http://localhost:<port>` counts as a secure context in Meta Quest Browser:
45
+
46
+ ```bash
47
+ npm run build
48
+ python3 -m http.server 4173 --bind 127.0.0.1 --directory dist
49
+ adb reverse tcp:4173 tcp:4173 # then open http://localhost:4173 on the headset
50
+ ```
51
+
52
+ Not `npx vite preview`: the IWSDK Vite plugin serves it over HTTPS with a
53
+ self-signed certificate, and Quest Browser refuses to register a service worker
54
+ from a page with a certificate error.
55
+
56
+ Clear the origin's storage between runs, for example with the DevTools
57
+ Protocol's `Storage.clearDataForOrigin`, or the site settings in the browser.
@@ -103,4 +103,4 @@ authored render cover deliberate framing.
103
103
  Make at most one focused correction, then replay the same observation. Stop
104
104
  when the requested bodies, collisions, and final state are evidenced. Resume
105
105
  ECS time and leave the app in a stable state.
106
- <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=5d66b2f83041f75889735be1e18747b078f2df32025ba1039cb77efbea3c2cb3 name=iwsdk-physics (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
106
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=24a1d1e5a61472ec045759f5e385de1843df34b6e43613dcd6b591c439ec69f1 name=iwsdk-physics (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -45,6 +45,7 @@ The project manifest accepts execution, frequency, and interpolation options:
45
45
  - `useWorker` defaults to `true`. Set it to `false` to run the same runtime and message protocol on the main thread.
46
46
  - `updateFrequency` defaults to 60 Hz and is capped at 240 Hz.
47
47
  - `interpolation` defaults to `true` and smooths rendered transforms between fixed physics snapshots.
48
+ - `applyScale` defaults to `false`. `Auto` shapes and mesh-derived `ConvexHull`/`TriMesh` shapes always use the object's world scale. Shapes with explicit `dimensions` ignore it unless `applyScale` is `true`; a scaled object with explicit dimensions logs a one-time warning. Prefer `applyScale: true` in new projects and author dimensions in the object's unscaled units.
48
49
 
49
50
  The system also accepts a reactive `gravity` config (defaults to Earth gravity):
50
51
 
@@ -70,7 +70,10 @@ envEntity.addComponent(PhysicsBody, { state: PhysicsState.Static });
70
70
 
71
71
  ### Creating a Kinematic Moving Platform
72
72
 
73
- Kinematic bodies are moved by code and push dynamic objects:
73
+ Kinematic bodies follow their Object3D: move it from a system and the body sweeps
74
+ there over the next physics steps, pushing dynamic objects and carrying anything
75
+ resting on it. When the Object3D stops, the body stops with it. Don't apply
76
+ `PhysicsManipulation` to a kinematic body; it is ignored with a warning.
74
77
 
75
78
  ```typescript
76
79
  // Setup
@@ -110,7 +113,10 @@ physics.setBodyTransform(entity, {
110
113
  ```
111
114
 
112
115
  Velocity is cleared by default. Pass `{ resetVelocity: false }` only when a teleport
113
- must preserve motion. `gravityFactor`, `linearDamping`, and `angularDamping` can be
116
+ must preserve motion. The pose is relative to the entity's parent, like
117
+ `object3D.position`; pass `{ space: 'world' }` for a world-space pose. Physics
118
+ simulates in world space, so bodies may live under a moved level root or another
119
+ entity. `gravityFactor`, `linearDamping`, and `angularDamping` can be
114
120
  changed reactively with `entity.setValue`; changing motion state or shape requires
115
121
  deliberate body lifecycle handling.
116
122
 
@@ -140,7 +146,7 @@ entity.addComponent(DistanceGrabbable, {
140
146
  });
141
147
  ```
142
148
 
143
- When grabbed, the `GrabSystem` drives the held body kinematically (via `HP_Body_SetTargetQTransform`), making the object follow the hand. On release, the object resumes dynamic simulation with natural velocity for realistic throwing. Note: near-field grabs do not add `Hovered`/`Pressed` tags — assert grab behavior with ECS snapshot/diff, not tag queries.
149
+ When grabbed, the `PhysicsSystem` makes a dynamic body kinematic and drives it toward the hand pose, so it pushes other bodies without being knocked out of the hand. A pose jump faster than a hand can move, such as an emulator controller teleport, moves the held body without sweeping it through its neighbours. On release, the body is dynamic again and leaves with the hand's recent velocity, smoothed over about 50 ms and capped at 10 m/s. Note: near-field grabs do not add `Hovered`/`Pressed` tags — assert grab behavior with ECS snapshot/diff, not tag queries.
144
150
 
145
151
  ### Reading Velocity for Game Logic
146
152
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: iwsdk-pwa-packaging
3
- description: Ship an IWSDK app to Meta Quest and the Horizon Store as a PWA/TWA — both immersive WebXR and 2D windowed panel modes. Use for PWA packaging, web app manifest and icons, auto-enter-XR on launch, bubblewrap APK builds, signing keystores, Digital Asset Links, sideloading, and Horizon Store upload. Also use when a packaged app is stuck loading, shows a URL bar, or will not launch.
3
+ description: Ship an IWSDK app to Meta Quest and the Horizon Store as a PWA/TWA — both immersive WebXR and 2D windowed panel modes. Use for PWA packaging, web app manifest and icons, auto-enter-XR on launch, bubblewrap APK builds, signing keystores, Digital Asset Links, sideloading, and Horizon Store upload. Also use when a packaged app is stuck loading, shows a URL bar, or will not launch. Not for a standalone APK that runs the app without Quest Browser (iwsdk-metavr-native).
4
4
  argument-hint: '[packaging goal, e.g. "ship to the store" or "build an APK"]'
5
5
  ---
6
6
 
@@ -12,6 +12,10 @@ wrapper, not a bundle of your files. That single fact explains most of the
12
12
  pipeline: the origin must be live before packaging, and web fixes ship by
13
13
  redeploying rather than rebuilding.
14
14
 
15
+ A different kind of APK, one that carries the app's files and runs them
16
+ without Quest Browser, is `iwsdk-metavr-native` (`npm run build:metavr`). If
17
+ the user only says "an APK", ask which one before starting.
18
+
15
19
  User request is in `$ARGUMENTS`.
16
20
 
17
21
  ```
@@ -80,6 +84,12 @@ it on the headset after sideloading (step 4).
80
84
  `index.html` ships `<link rel="icon" href="data:," />` and no manifest link, so
81
85
  the app is not installable until step 3 adds them.
82
86
 
87
+ **Optional: launch offline.** The TWA loads `<DOMAIN>` over the network, so with
88
+ no connection an installed app shows an error page instead of the app. If it
89
+ must launch offline, add an offline copy with the `iwsdk-offline` skill before
90
+ packaging: one online launch then keeps the release on the device. Keep the
91
+ manifest's `start_url` and `scope` inside the service worker's scope.
92
+
83
93
  Then confirm the app itself is sound before wrapping it — `npm run --if-present typecheck`,
84
94
  and `npm run build` producing a `dist/` you have actually loaded. Packaging a
85
95
  broken build wastes a full round trip through hosting, signing, and upload.
@@ -191,6 +201,10 @@ retry the identical command. Tool download, auth, and flag reference:
191
201
  | App logic, assets, styling, manifest text, icons, asset links | republish `<DOMAIN>`; installed TWA picks it up next launch |
192
202
  | Package id, app name, launcher icon, version, **app mode**, signing | rebuild the APK and re-upload |
193
203
 
204
+ With an offline copy (`iwsdk-offline`), a republished release installs in the
205
+ background during a launch and takes over when the app is idle, or on the
206
+ launch after that.
207
+
194
208
  ## Security
195
209
 
196
210
  The keystore and the app secret never go near `public/` or `dist/`. After every
@@ -213,7 +227,8 @@ updated — only replaced by a new Store entry.
213
227
  | [`references/store-upload.md`](references/store-upload.md) | Step 5 — `ovr-platform-util`, auth, channels, the DDA blocker |
214
228
  | [`references/troubleshooting.md`](references/troubleshooting.md) | Anything installed but misbehaving — stuck loading, URL bar, will-not-launch |
215
229
 
216
- Getting the app online is the `iwsdk-hosting` skill. Building the app itself is
230
+ Getting the app online is the `iwsdk-hosting` skill, and keeping it working
231
+ offline is `iwsdk-offline`. Building the app itself is
217
232
  `iwsdk-planner` and the other `iwsdk-*` skills — do not re-derive IWSDK
218
233
  patterns here.
219
- <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=e4e859d1977962769195f6bfb52dc9b02f159dd743e2609ea8b6111dd847e7eb name=iwsdk-pwa-packaging (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
234
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=6f7204ddddf36831ef555a3ede4202384ea029d217c59fdbf3dc51b903ebdb57 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 |
@@ -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.0 sha256=ec23dce5226ca91367042de7907fb3664c055a1ceb737fede2fd6710eab1f37f name=iwsdk-ray (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
70
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.2 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
- The press clicked when `presses[0].contactMs` is below 800; at 800 or more a
269
- slow headless frame held the touch too long, so run the press once more. Confirm
270
- the state change with `ui inspect`. `xr list-targets` lists the element IDs that
271
- can be pressed.
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.0 sha256=f38cb22c3f17e583db46ecffe8ac78d5d58a1b990ebd485e00f1f5623b690332 name=iwsdk-ui (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
335
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.2 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.0 sha256=5ccb37dbe152b3611496740e89bc8e42c8d59dfed8be7512635d877924b79988 name=iwsdk-upgrade (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
74
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.2 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.0 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) -->
521
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.2 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.0 sha256=9c0abbe2f1b3cc83f826ac6a5c24f0088375757ec17bfb970301a3c32b940a44 name=assets-and-manifest.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
60
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.2 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.0 sha256=56f1044b9936f279404ef715676b734a119ef495824d5916737f3a00579acc64 name=ecs-api.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
103
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.2 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.0 sha256=d507943047667757a27a1b58cff203b0e3d1bdc646b0f5998cf0851840dde550 name=scene-json.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
72
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.2 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.0 sha256=101e26d6362ef8867f020086e5edae81ae70c45a11e53339171da8591f41f1a6 name=uikitml.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
66
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=101e26d6362ef8867f020086e5edae81ae70c45a11e53339171da8591f41f1a6 name=uikitml.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -13,7 +13,9 @@
13
13
  "Skill(iwsdk-glasses-test)",
14
14
  "Skill(iwsdk-grab)",
15
15
  "Skill(iwsdk-hosting)",
16
+ "Skill(iwsdk-metavr-native)",
16
17
  "Skill(iwsdk-native-xr-test)",
18
+ "Skill(iwsdk-offline)",
17
19
  "Skill(iwsdk-physics)",
18
20
  "Skill(iwsdk-pwa-packaging)",
19
21
  "Skill(iwsdk-ray)",
@@ -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.0 sha256=95fc72ddf1f3915aa71a839558a3ce051b803214b25ad8c594e882068a3d7917 name=iwsdk-build-model (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
312
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.2 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.0 sha256=e6feb83023b2ddbe9a3cceea3b0deda0fe8beb9743d4af6b8e0a89ea31e61b93 name=iwsdk-compose-scene (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
277
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.2 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.0 sha256=7dd8250ca95e23b6f0696a86a3dfcb2d038ac730a7578118fb21290c6169c3f0 name=iwsdk-debug (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
74
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.2 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.0 sha256=819e3f213766f12b567fa8ffd5e343f1a17f83973642067d82ebd7c5dee1dbe3 name=iwsdk-depth-occlusion (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
88
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=819e3f213766f12b567fa8ffd5e343f1a17f83973642067d82ebd7c5dee1dbe3 name=iwsdk-depth-occlusion (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -31,6 +31,25 @@ Observable workspace state wins over wording:
31
31
  already exist;
32
32
  - explicit user selection of a child route overrides automatic routing.
33
33
 
34
+ ## Distribution requests
35
+
36
+ A request that only ships an existing app — hosting it, packaging it for
37
+ Quest or the Horizon Store, making it work offline, or building, installing
38
+ and debugging a native `@iwer/native` APK — takes neither playbook. Invoke
39
+ the owning skill directly and let it own the task:
40
+
41
+ | Request | Skill |
42
+ | --------------------------------------------------------------------------------- | --------------------- |
43
+ | Put the app on a public HTTPS origin | `iwsdk-hosting` |
44
+ | Installable PWA, or a TWA APK of the hosted site, Store upload | `iwsdk-pwa-packaging` |
45
+ | Work with no connection after one visit | `iwsdk-offline` |
46
+ | Standalone APK with no browser (`build:metavr`, `native` section, `dist-metavr/`) | `iwsdk-metavr-native` |
47
+
48
+ "Make an APK" alone could mean either the TWA or the native APK; ask which,
49
+ using the comparison in `iwsdk-metavr-native` step 0. A request that changes
50
+ the experience and then ships it routes to a playbook first; invoke the
51
+ distribution skill after the playbook's work is verified.
52
+
34
53
  ## Internal handoff
35
54
 
36
55
  1. State the selected route in one sentence.
@@ -43,4 +62,4 @@ Observable workspace state wins over wording:
43
62
 
44
63
  iwsdk-dev does not add another implementation phase. The selected playbook owns
45
64
  the work, evidence budget, specialist routing, verification, and stopping rule.
46
- <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=07f4648993de9020eb6eee38c94ad442ac6b1ca8ede99e4d369de20e60e3af2f name=iwsdk-dev (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
65
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=f21471a15775b322906d8b1431a149aab73ac6d34acfef6cc05159f7a9d005fb name=iwsdk-dev (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->