@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.
Files changed (99) 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 +1 -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-native-xr-test/SKILL.md +1 -1
  14. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/SKILL.md +217 -0
  15. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/offline.ts.template +99 -0
  16. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/sw.js.template +241 -0
  17. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
  18. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/build-step.md +71 -0
  19. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/page.md +70 -0
  20. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/service-worker.md +107 -0
  21. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/testing.md +57 -0
  22. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +1 -1
  23. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +1 -0
  24. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +9 -3
  25. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +13 -2
  26. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +1 -1
  27. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +30 -0
  28. package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +1 -1
  29. package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +12 -5
  30. package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +1 -1
  31. package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +1 -1
  32. package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +1 -1
  33. package/dist/agent-guidance/files/.claude/rules/ecs-api.md +1 -1
  34. package/dist/agent-guidance/files/.claude/rules/scene-json.md +1 -1
  35. package/dist/agent-guidance/files/.claude/rules/uikitml.md +1 -1
  36. package/dist/agent-guidance/files/.claude/settings.json +1 -0
  37. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +1 -1
  38. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +1 -1
  39. package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +1 -1
  40. package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +1 -1
  41. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +1 -1
  42. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +2 -1
  43. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +15 -1
  44. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +7 -3
  45. package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +1 -1
  46. package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +1 -1
  47. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +3 -2
  48. package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +1 -1
  49. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/SKILL.md +217 -0
  50. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/offline.ts.template +99 -0
  51. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/sw.js.template +241 -0
  52. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
  53. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/build-step.md +71 -0
  54. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/page.md +70 -0
  55. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/service-worker.md +107 -0
  56. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/testing.md +57 -0
  57. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +1 -1
  58. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +1 -0
  59. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +9 -3
  60. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +13 -2
  61. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +1 -1
  62. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +30 -0
  63. package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +1 -1
  64. package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +12 -5
  65. package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +1 -1
  66. package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +1 -1
  67. package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +1 -1
  68. package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +1 -1
  69. package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +1 -1
  70. package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +1 -1
  71. package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +1 -1
  72. package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +1 -1
  73. package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +1 -1
  74. package/dist/agent-guidance/files/AGENTS.md +1 -1
  75. package/dist/agent-guidance/files/public/scenes/AGENTS.md +1 -1
  76. package/dist/agent-guidance/files/public/ui/AGENTS.md +1 -1
  77. package/dist/agent-guidance/files/src/AGENTS.md +1 -1
  78. package/dist/agent-guidance/manifest.json +111 -11
  79. package/dist/agent-guidance.d.ts +31 -4
  80. package/dist/agent-guidance.d.ts.map +1 -1
  81. package/dist/agent-guidance.js +269 -60
  82. package/dist/agent-guidance.js.map +1 -1
  83. package/dist/cli.js +1128 -131
  84. package/dist/cli.js.map +1 -1
  85. package/dist/commands/upgrade.d.ts +87 -0
  86. package/dist/commands/upgrade.d.ts.map +1 -1
  87. package/dist/guidance-refresh.d.ts +23 -3
  88. package/dist/guidance-refresh.d.ts.map +1 -1
  89. package/dist/help.d.ts.map +1 -1
  90. package/dist/index.d.ts.map +1 -1
  91. package/dist/index.js +1128 -131
  92. package/dist/index.js.map +1 -1
  93. package/dist/metavr-telemetry.d.ts +6 -0
  94. package/dist/metavr-telemetry.d.ts.map +1 -1
  95. package/dist/package-manager.d.ts +6 -0
  96. package/dist/package-manager.d.ts.map +1 -1
  97. package/dist/release-notes.json +132 -0
  98. package/dist/version.d.ts +1 -1
  99. package/package.json +1 -1
package/README.md CHANGED
@@ -73,10 +73,26 @@ installed it.
73
73
 
74
74
  `iwsdk dev up` and `dev restart` keep the guidance current after an upgrade:
75
75
  when the installed `@iwsdk/core` ships different guidance than the project has,
76
- they refresh the files nobody edited and print what changed. They only report,
77
- without writing, when `CI` is set, when `node_modules` holds a different
78
- `@iwsdk/core` than the lockfile resolves (for example after switching branches
79
- without installing), or when `iwsdk.config.json` sets
76
+ they refresh the files nobody edited and print what changed. They update only
77
+ the guidance the project already has, and replace retired guidance whole: an
78
+ unedited skill or file that a release renamed or retired is removed only when
79
+ the release names its successors, which are written in the same run (each
80
+ gets the retired skill's `Skill()` permission if it had one), and a
81
+ `CLAUDE.md` from before 1.0 that holds the full guidance becomes an
82
+ `@AGENTS.md` import only once `AGENTS.md` holds the managed block, written in
83
+ the same run if needed. An `AGENTS.md` that cannot take the block (edited
84
+ guidance from before 1.2, or broken block markers) leaves that `CLAUDE.md` as
85
+ it is. A retired skill or file whose release names no successor is kept;
86
+ when they refresh, the output names it, and `agents sync` removes it. Apart
87
+ from that they never add guidance the project does not have: a skill, rule,
88
+ `AGENTS.md` block or `CLAUDE.md` import that you removed, or that is new in
89
+ the release, stays out, and a skill permission you removed is not granted
90
+ again. When they refresh, the output lists the skills and files left out (not
91
+ permissions) for `agents sync`; a start with nothing to refresh prints
92
+ nothing, so a deliberate removal is not reported on every start. They only
93
+ report, without writing, when `CI` is set, when `node_modules` holds a
94
+ different `@iwsdk/core` than the lockfile resolves (for example after
95
+ switching branches without installing), or when `iwsdk.config.json` sets
80
96
  `"dev": { "agentGuidance": "warn" }`. `"off"` (or `IWSDK_AGENT_GUIDANCE=off`)
81
97
  disables the check. They never install guidance into a project that has none.
82
98
 
@@ -103,15 +119,26 @@ npx @iwsdk/cli@latest upgrade [--to <version>] [--dry-run] [--no-install]
103
119
 
104
120
  `upgrade` sets every `@iwsdk/*` dependency in the release group to the CLI's
105
121
  release (or `--to`), keeping `^` and `~` ranges and leaving `workspace:`,
106
- `file:` and `catalog:` specs alone. It installs with the package manager found
107
- from the nearest lockfile, aligns the `three` alias (in `package.json` or
108
- `pnpm-workspace.yaml`) with the one `@iwsdk/core` uses, refreshes the agent
109
- guidance the project already has, and checks `iwsdk.config.json` against the
110
- new release. It writes to `.iwsdk/migrations/` (gitignored) the migration guide
111
- for each release boundary crossed and `release-notes.md` with every change in
112
- between, and names them in its output. Use `@latest`: migration guides and
113
- release notes ship with the CLI, so the newest CLI covers every release,
114
- whatever version the project starts from.
122
+ `file:` and `catalog:` specs alone, and aligns the `three` alias (in
123
+ `package.json` or `pnpm-workspace.yaml`) with the one the new `@iwsdk/core`
124
+ uses. Before it writes anything, it asks the registry the install will use for
125
+ the release, and changes nothing if the release is missing there (error code
126
+ `release_not_on_registry`), as when a mirror lags behind. It reads the
127
+ settings the install reads: npm's (an npm workspace's root `.npmrc`; in a pnpm
128
+ workspace, the root's `.npmrc` with the app's own over it, setting by setting),
129
+ or Yarn's (`.yarnrc` and `.npmrc` for Yarn 1, `.yarnrc.yml` for Yarn 2+). For
130
+ npm, pnpm and Yarn 1, the `npm_config_registry` environment variable overrides
131
+ the registry unless an `@iwsdk` scope registry is set. Offline, npm answers
132
+ from its cache when that has the release; only the registry itself can report
133
+ a release missing. If the registry cannot be asked, for example offline or
134
+ without npm, it says why, goes on, and aligns `three` after the install. It
135
+ installs with the package manager found from the nearest lockfile, refreshes
136
+ the agent guidance the project already has, and checks `iwsdk.config.json`
137
+ against the new release. It writes to `.iwsdk/migrations/` (gitignored) the
138
+ migration guide for each release boundary crossed and `release-notes.md` with
139
+ every change in between, and names them in its output. Use `@latest`:
140
+ migration guides and release notes ship with the CLI, so the newest CLI covers
141
+ every release, whatever version the project starts from.
115
142
 
116
143
  - `iwsdk adapter status` reports MCP, instruction, and permission state.
117
144
  - `iwsdk adapter prune` removes managed MCP/permission entries and preserves
@@ -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.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.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.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.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.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.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.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.0 sha256=07f4648993de9020eb6eee38c94ad442ac6b1ca8ede99e4d369de20e60e3af2f name=iwsdk-dev (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
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 whose
158
- `presses[0].contactMs` is 800 or more did not click. A stalled frame can
159
- stretch a press that far, so run that press once more before changing code.
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.0 sha256=86e1e324dd71e8dd832b5d446e6bdc03bb5150cf5128c0650838cf6227b79817 name=iwsdk-glasses-test (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
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.0 sha256=ad099acb82205620cb9cce44f245f40baf7e6808038d7d94ff9d873f316473d2 name=iwsdk-grab (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
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; this skill only gets it online.
178
- <!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=9e866989c506da5cf54ba96bb02c52d1b901e162ab8f32ad9f97ed84aa4dcc8b name=iwsdk-hosting (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
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.0 sha256=931a8822463f2bb6652cbbf2b7571db92e5331af44b598890057319b0177939b name=iwsdk-native-xr-test (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
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
+ }