@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
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.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) -->
@@ -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.2 sha256=86e1e324dd71e8dd832b5d446e6bdc03bb5150cf5128c0650838cf6227b79817 name=iwsdk-glasses-test (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -72,4 +72,4 @@ to model context does not satisfy a requested file deliverable.
72
72
 
73
73
  Stop once the requested grab/move/release path and final state are proven. Leave
74
74
  the controller released and the XR session in the state the user requested.
75
- <!-- iwsdk-agent-guidance version=1.2.0-rc.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.2 sha256=ad099acb82205620cb9cce44f245f40baf7e6808038d7d94ff9d873f316473d2 name=iwsdk-grab (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -174,5 +174,6 @@ trip:
174
174
  | [`references/existing-hosts.md`](references/existing-hosts.md) | Route B — per-host publish recipes and their gotchas |
175
175
 
176
176
  Packaging the hosted app into a signed Quest APK is the `iwsdk-pwa-packaging`
177
- skill; 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.2 sha256=360be8c5297e0b33bdbdf82188b95dbbcfc586b00d0c0840a21094eb9745e21d name=iwsdk-hosting (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -0,0 +1,216 @@
1
+ ---
2
+ name: iwsdk-metavr-native
3
+ description: Build, install, run and debug an IWSDK VR or AR app as a standalone Quest APK with @iwer/native (alpha), which runs the app's own JavaScript on the headset without Quest Browser. Use when the project has a `native` section in iwsdk.config.json or a `build:metavr` script, when the user asks for a native or browserless Quest build, or when a dist-metavr APK fails to pack, launch, enter XR or fetch. Not for PWA/TWA store packaging of a hosted site (iwsdk-pwa-packaging) or for driving Quest Browser over ADB (iwsdk-native-xr-test).
4
+ argument-hint: '[goal, e.g. "add a native build", "the APK shows black"]'
5
+ ---
6
+
7
+ # Native Quest APK (@iwer/native, alpha)
8
+
9
+ `npm run build:metavr` runs `vite build --mode metavr && iwer-native pack`.
10
+ The Vite step is a normal production build without the IWER emulator, and with
11
+ the `native` section of `iwsdk.config.json` left out of the bundle. `pack` puts
12
+ `dist/` into a template APK that carries the @iwer/native runtime (V8, WebGL 2
13
+ over OpenGL ES, fetch, Web Audio, workers, a DOM stand-in, WebXR over OpenXR)
14
+ and signs it in Node. The result, `dist-metavr/<appName>.apk`, runs on the
15
+ headset with no browser and no server: app files load from the APK.
16
+
17
+ User request is in `$ARGUMENTS`.
18
+
19
+ ```
20
+ 0. Pick the route → native APK, or PWA/TWA (iwsdk-pwa-packaging)
21
+ 1. Set up → IWSDK ≥ 1.2, @iwer/native, native section
22
+ 2. Fit the app → VR only, offers XR, no HTML UI, allow-listed origins
23
+ 3. Build and launch → doctor → build:metavr → install → run
24
+ 4. Verify on device → logcat, debug endpoint, state hook
25
+ 5. Ship → package id, signing, --release
26
+ ```
27
+
28
+ The package README is the reference for every config key, API and error:
29
+ `node_modules/@iwer/native/README.md`. Read its support matrix, Known
30
+ limitations and Troubleshooting before you promise a feature works natively.
31
+ Trust it over this skill if they disagree; the alpha changes between releases.
32
+
33
+ ## Step 0 — Native APK or PWA?
34
+
35
+ | | **Native APK (this skill)** | **PWA/TWA (`iwsdk-pwa-packaging`)** |
36
+ | --- | --- | --- |
37
+ | Runs in | the @iwer/native runtime | Quest Browser, from a live URL |
38
+ | Needs hosting | no, files are in the APK | yes, a public HTTPS origin |
39
+ | Web fixes ship by | a new APK | redeploying the site |
40
+ | App modes | immersive VR and AR (passthrough) | immersive VR, AR, 2D panel |
41
+ | Web platform | the subset in the README matrix | the full browser |
42
+ | APK size | about 47 MB of runtime + assets | small wrapper |
43
+
44
+ Ask when the user says only "make an APK". Choose native for an offline,
45
+ self-contained immersive app; choose the PWA for a 2D panel, HTML UI, or an
46
+ app that depends on browser APIs the matrix marks "not yet" or "out of
47
+ scope".
48
+
49
+ ## Step 1 — Set up
50
+
51
+ Requirements: `@iwsdk/core`, `@iwsdk/vite-plugin-dev` and `@iwsdk/create` 1.2.0
52
+ or later (1.1.0 rejects the `native` key), Node 20.19+, `adb` on `PATH` (or
53
+ `$ADB`/`$ANDROID_HOME`), and a Quest in developer mode with USB debugging
54
+ accepted. No Android SDK, NDK or Gradle is needed.
55
+
56
+ - **New project:** `npm create @iwsdk@latest <name> -- --target vr --metavr-native`
57
+ (or `--target ar`).
58
+ It adds `@iwer/native` (pinned), the `build:metavr` script, a `native`
59
+ section and `dist-metavr/` in `.gitignore`.
60
+ - **Existing IWSDK project:** run `npx @iwsdk/create@latest . --yes --target <vr|ar> --metavr-native`.
61
+ It adds the script, the dependency and the ignore entry but keeps your
62
+ `iwsdk.config.json`, so add the section it prints yourself:
63
+
64
+ ```json
65
+ "native": {
66
+ "packageId": "com.example.myapp",
67
+ "appName": "myapp",
68
+ "network": { "allow": ["https://cdn.jsdelivr.net"] }
69
+ }
70
+ ```
71
+
72
+ Without it, `pack` stops at `iwsdk.config.json has no "native" section`.
73
+
74
+ Then `npx iwer-native doctor`. It checks Node, adb, the connected headsets, the
75
+ native config, signing and the bundled template. Fix every `[fail]` before
76
+ building. The `com.example` warning is fine for sideloading.
77
+
78
+ ## Step 2 — Fit the app to the runtime
79
+
80
+ - **Immersive only.** `world.xr.mode` `"vr"` or `"ar"`; there is no 2D page, so
81
+ a Desktop 3D (`world.xr: false`) app cannot be packed. For `"ar"`, `pack`
82
+ declares passthrough itself. Plane, mesh, hit-test and anchor support needs a
83
+ room from Space Setup and is not yet device-tested in a real room (README
84
+ Known limitations): verify scene-understanding features on the headset.
85
+ A feature marked `required` that the headset lacks rejects the session, and
86
+ the app never leaves the splash: a Quest 3S has no depth sensing, so
87
+ `depthSensing: { required: true }` never starts there. Prefer optional
88
+ features and feature-detect them, and note the headset model you tested on
89
+ (`iwn-host.mjs info`). With several headsets attached, always pass `--serial`.
90
+ - **The app must offer XR.** Keep `world.xr.offer` at `"always"` (the default)
91
+ or `"once"`. The runtime shows only WebXR content: with `"none"` the app stays
92
+ black and logs `XR-LIFE-7` after 10 s.
93
+ - **No HTML UI.** There is no layout, CSS or pointer/keyboard event. Build UI in
94
+ 3D with IWSDK spatial UI (`iwsdk-ui`). DOM overlays do not draw.
95
+ - **There is no browser to exit to.** Ending the session (the starter's
96
+ "Exit to Browser" button, `world.exitXR()`) makes `offer: "always"` start a new
97
+ session at once, so the button only flickers. Hide such controls in native
98
+ builds and let the system menu quit:
99
+ `const isNative = navigator.userAgent.includes('IWERNative');`
100
+ - **Network allow-list.** Only origins in `native.network.allow` are reachable
101
+ (`https://host[:port]`, no path). The starter needs `https://cdn.jsdelivr.net`
102
+ for its controller models. Prefer bundling assets in `public/` so the app works
103
+ offline. No WebSocket, IndexedDB, Cache API, service worker or HTTP cache.
104
+ - **Media.** `<video>`/`<audio>` file playback is not supported; use Web Audio
105
+ (`AudioContext`, buffer sources, gain, panner, `decodeAudioData`).
106
+ - **Check compatibility:** `npx iwer-native compat` (static) and
107
+ `npx iwer-native compat --trace` (a headless run into XR). `pack` runs the
108
+ static check and fails on an injected emulator; `pack --strict` fails on any
109
+ unsupported API. Treat the `WebAssembly.instantiateStreaming()` warning on an
110
+ IWSDK physics or UI build as expected: Havok and the MSDF worker fall back to
111
+ `WebAssembly.instantiate`, and physics runs. Act on every other warning: feature-detect
112
+ the API or drop it (`compat --verbose` shows the call site).
113
+
114
+ ## Step 3 — Build, install, run
115
+
116
+ ```bash
117
+ npm run --if-present typecheck
118
+ npm run build:metavr # dist-metavr/<appName>.apk, debug build
119
+ npx iwer-native install --serial <serial>
120
+ npx iwer-native run --serial <serial> # or: npx iwer-native pack --install --run
121
+ ```
122
+
123
+ The loop is quick (build about 5 s, pack under 1 s, install about 10 s), so
124
+ rebuild instead of reasoning about stale state. Always pass `--serial` when
125
+ more than one device is connected. Debug and release builds write the same
126
+ path; the last `pack` wins.
127
+
128
+ **Before blaming the app, check what the headset shows:**
129
+
130
+ ```bash
131
+ adb -s <serial> shell dumpsys activity activities | grep topResumedActivity
132
+ ```
133
+
134
+ - `com.example.<app>/android.app.NativeActivity` → the app is in front.
135
+ - `GuardianDialogActivity` ("Finding position in room") or
136
+ `LaunchCheckRequires6dofDialogActivity` ("Turn on tracking") → the headset has
137
+ lost tracking, usually because the room is dark or the cameras are covered.
138
+ `run` then reports `adb did not finish within 60 s`. A native APK needs 6DoF
139
+ tracking: ask the user for light. If the dialog stays after tracking is back,
140
+ `adb -s <serial> reboot` clears it.
141
+ - Any other system dialog (permissions, first-run notices) → ask the user to
142
+ answer it in the headset, or read its buttons with
143
+ `adb shell uiautomator dump` and answer it only if the user allowed you to.
144
+
145
+ ## Step 4 — Verify on the device
146
+
147
+ IWSDK's CLI and MCP tools (`ecs`, `xr`, `scene`, `browser`) reach the managed
148
+ browser and paired Quest Browser pages, **not** a native APK. On the APK use:
149
+
150
+ 1. **Logs:** `adb -s <serial> logcat -v tag | grep '/iwn'`. Every runtime tag
151
+ starts with `iwn`; app `console.*` output is `iwn-js`. A healthy launch logs
152
+ `xr: first WebXR frame`, then `xr-stats fps=72…` lines every few seconds.
153
+ Lines from an older process of the same app (another PID) are not this run.
154
+ 2. **The debug endpoint** (debug builds; `pack --release --inspector` for a
155
+ release build). Forward it, then use the bundled client:
156
+
157
+ ```bash
158
+ adb -s <serial> forward tcp:9229 localabstract:<packageId>_devtools_9229
159
+ kit="$(dirname "$(find .claude/skills .agents/skills -path '*/iwsdk-metavr-native/assets/iwn-host.mjs' -print -quit)")"
160
+ node "$kit/iwn-host.mjs" eval 'document.title'
161
+ node "$kit/iwn-host.mjs" shot shot.png left 0.5 # what the eye buffer shows
162
+ node "$kit/iwn-host.mjs" stats # fps, GC, heap, boot timings
163
+ ```
164
+
165
+ `adb shell screencap` is black during an immersive session; use `shot`.
166
+ The shot follows the live head pose: a headset lying on a desk looks
167
+ wherever it points. It holds the app's layer only; in AR, passthrough is
168
+ not in it, so empty areas come out blank.
169
+ 3. **App state.** The APK has no IWSDK command bridge, so expose the world for
170
+ tests yourself, only when asked for:
171
+
172
+ ```ts
173
+ if (new URLSearchParams(location.search).has('iwsdkDebug')) {
174
+ (globalThis as { __world?: World }).__world = world;
175
+ }
176
+ ```
177
+
178
+ Launch with `npx iwer-native run --query iwsdkDebug=1`, then read state with
179
+ `eval` (for example `__world.player.position.toArray()`, or a value from
180
+ one of your components). Keep state you want to check in ECS components, as
181
+ AGENTS.md asks.
182
+ 4. **A debugger:** `npx iwer-native run --inspect --forward 9229`, then open
183
+ `chrome://inspect` and add `localhost:9229`. If the port is
184
+ `still in use`, another debug build holds it:
185
+ `adb shell am force-stop <its packageId>`.
186
+
187
+ **Scripted input does not exist on the APK.** You cannot press, grab or point
188
+ from the CLI. Prove interaction logic in the emulator or Quest Browser with
189
+ `iwsdk-grab`, `iwsdk-ray` and `iwsdk-native-xr-test` (the same IWSDK code runs
190
+ there), and use the APK for what only it can show: that the app starts and
191
+ enters XR, renders, holds frame rate, loads its assets, reaches its network
192
+ origins, and that physics and audio run. Say which claims were verified where.
193
+
194
+ ## Step 5 — Ship
195
+
196
+ - Replace `com.example.*` with your own reverse-domain `packageId`; stores
197
+ reject `com.example`. A changed id installs as a separate app.
198
+ - Add a `signing` section (keystore path plus the names of the environment
199
+ variables that hold the passwords) and build with
200
+ `npx iwer-native pack --release`. Never write passwords into
201
+ `iwsdk.config.json` or commit a keystore. Without `signing`, `--release` signs
202
+ with the debug key and warns.
203
+ - Raise `versionCode` for every upload. Set `icon` and `splash` (the README's
204
+ Configuration section lists every key; `iwer-native validate` checks them).
205
+ - Installing a release over a debug build signed with another key fails with
206
+ `INSTALL_FAILED_UPDATE_INCOMPATIBLE`: `adb uninstall <packageId>` first.
207
+
208
+ ## Report
209
+
210
+ State the APK path, size and package id, the device serial and OS build
211
+ (`node "$kit/iwn-host.mjs" info`), the compat result, what you verified on the
212
+ APK (with logcat lines, `eval` values or shots) and what you verified only in
213
+ the emulator or Quest Browser, and any warning you left in place with its
214
+ reason. For a runtime bug, collect what the README's Reporting issues section
215
+ lists.
216
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=c28e2ac59fab5db24f36df736b7f246c7abbc2b016de2ae90a76a9a20669686e name=iwsdk-metavr-native (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -0,0 +1,71 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
4
+ *
5
+ * This source code is licensed under the MIT license found in the
6
+ * LICENSE file in the root directory of this source tree.
7
+ */
8
+
9
+ // Client for the @iwer/native debug endpoint (debug builds, or
10
+ // `pack --release --inspector`). Forward the port first:
11
+ // adb -s <serial> forward tcp:9229 localabstract:<packageId>_devtools_9229
12
+ //
13
+ // node iwn-host.mjs eval '<expression>' value of the expression (promises awaited)
14
+ // node iwn-host.mjs shot <out.png> [left|right|both] [scale] eye-buffer PNG
15
+ // node iwn-host.mjs stats frame, GC, heap and boot timings
16
+ // node iwn-host.mjs info device, runtime and app identity
17
+ //
18
+ // PORT selects another forwarded port (default 9229). Exit code 1 on an error
19
+ // reply, 2 when the endpoint does not answer.
20
+ import { writeFileSync } from 'node:fs';
21
+
22
+ const [method, ...args] = process.argv.slice(2);
23
+ const port = process.env.PORT || '9229';
24
+ let params;
25
+ let out;
26
+ switch (method) {
27
+ case 'eval':
28
+ params = { expression: args[0] ?? 'undefined', awaitPromise: true };
29
+ break;
30
+ case 'shot':
31
+ out = args[0] ?? 'iwn-shot.png';
32
+ params = { eye: args[1] ?? 'left', scale: Number(args[2] ?? 0.5) };
33
+ break;
34
+ case 'stats':
35
+ case 'info':
36
+ params = {};
37
+ break;
38
+ default:
39
+ console.error('usage: iwn-host.mjs eval <expr> | shot <out.png> [eye] [scale] | stats | info');
40
+ process.exit(2);
41
+ }
42
+
43
+ const timer = setTimeout(() => {
44
+ console.error(`no reply from ws://127.0.0.1:${port}/host: is the app running a debug build, and is the port forwarded?`);
45
+ process.exit(2);
46
+ }, 40_000);
47
+ const ws = new WebSocket(`ws://127.0.0.1:${port}/host`);
48
+ ws.onopen = () => ws.send(JSON.stringify({ id: 1, method, params }));
49
+ ws.onerror = () => {
50
+ console.error(`cannot connect to ws://127.0.0.1:${port}/host: forward the port with adb first`);
51
+ process.exit(2);
52
+ };
53
+ ws.onmessage = (message) => {
54
+ clearTimeout(timer);
55
+ const reply = JSON.parse(String(message.data));
56
+ if (reply.error) {
57
+ console.error(reply.error);
58
+ process.exit(1);
59
+ }
60
+ if (method === 'shot') {
61
+ writeFileSync(out, Buffer.from(reply.png, 'base64'));
62
+ console.log(JSON.stringify({ file: out, width: reply.width, height: reply.height, frame: reply.frame }));
63
+ } else if (method === 'eval') {
64
+ console.log(typeof reply.result === 'string' ? reply.result : JSON.stringify(reply.result ?? null, null, 1));
65
+ } else {
66
+ delete reply.id;
67
+ console.log(JSON.stringify(reply, null, 1));
68
+ }
69
+ ws.close();
70
+ process.exit(0);
71
+ };
@@ -259,4 +259,4 @@ Report:
259
259
  If the user wants to try the app in the headset afterwards, start a plain
260
260
  session (`npx @iwsdk/cli dev up` with the session's `--ai-mode`, without
261
261
  `--native-xr-control`) and give them the plain URL from `dev status`.
262
- <!-- iwsdk-agent-guidance version=1.2.0-rc.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.2 sha256=931a8822463f2bb6652cbbf2b7571db92e5331af44b598890057319b0177939b name=iwsdk-native-xr-test (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->