@iwsdk/cli 1.2.0-rc.1 → 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 (58) hide show
  1. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +1 -1
  2. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +1 -1
  3. package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +1 -1
  4. package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +1 -1
  5. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +20 -1
  6. package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +1 -1
  7. package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +1 -1
  8. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +1 -1
  9. package/dist/agent-guidance/files/.agents/skills/iwsdk-metavr-native/SKILL.md +216 -0
  10. package/dist/agent-guidance/files/.agents/skills/iwsdk-metavr-native/assets/iwn-host.mjs +71 -0
  11. package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +1 -1
  12. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/SKILL.md +1 -1
  13. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +1 -1
  14. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +6 -2
  15. package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +1 -1
  16. package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +1 -1
  17. package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +1 -1
  18. package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +1 -1
  19. package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +1 -1
  20. package/dist/agent-guidance/files/.claude/rules/ecs-api.md +1 -1
  21. package/dist/agent-guidance/files/.claude/rules/scene-json.md +1 -1
  22. package/dist/agent-guidance/files/.claude/rules/uikitml.md +1 -1
  23. package/dist/agent-guidance/files/.claude/settings.json +1 -0
  24. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +1 -1
  25. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +1 -1
  26. package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +1 -1
  27. package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +1 -1
  28. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +20 -1
  29. package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +1 -1
  30. package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +1 -1
  31. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +1 -1
  32. package/dist/agent-guidance/files/.claude/skills/iwsdk-metavr-native/SKILL.md +216 -0
  33. package/dist/agent-guidance/files/.claude/skills/iwsdk-metavr-native/assets/iwn-host.mjs +71 -0
  34. package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +1 -1
  35. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/SKILL.md +1 -1
  36. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +1 -1
  37. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +6 -2
  38. package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +1 -1
  39. package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +1 -1
  40. package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +1 -1
  41. package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +1 -1
  42. package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +1 -1
  43. package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +1 -1
  44. package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +1 -1
  45. package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +1 -1
  46. package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +1 -1
  47. package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +1 -1
  48. package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +1 -1
  49. package/dist/agent-guidance/files/AGENTS.md +10 -1
  50. package/dist/agent-guidance/files/public/scenes/AGENTS.md +1 -1
  51. package/dist/agent-guidance/files/public/ui/AGENTS.md +1 -1
  52. package/dist/agent-guidance/files/src/AGENTS.md +1 -1
  53. package/dist/agent-guidance/manifest.json +36 -6
  54. package/dist/cli.js +1 -1
  55. package/dist/index.js +1 -1
  56. package/dist/release-notes.json +51 -0
  57. package/dist/version.d.ts +1 -1
  58. package/package.json +1 -1
@@ -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.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) -->
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) -->
@@ -214,4 +214,4 @@ offline — after **one online launch**, which is when the copy is made.
214
214
  Publishing the build and its headers is the `iwsdk-hosting` skill, and packaging
215
215
  it into a Quest APK is `iwsdk-pwa-packaging`. This skill only makes it work
216
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) -->
217
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=7f4f5034d84d6f0aaf3c353603e4d6d18eb99d107c5946ec018f8674e1001f38 name=iwsdk-offline (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -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.1 sha256=24a1d1e5a61472ec045759f5e385de1843df34b6e43613dcd6b591c439ec69f1 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) -->
@@ -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
  ```
@@ -227,4 +231,4 @@ Getting the app online is the `iwsdk-hosting` skill, and keeping it working
227
231
  offline is `iwsdk-offline`. Building the app itself is
228
232
  `iwsdk-planner` and the other `iwsdk-*` skills — do not re-derive IWSDK
229
233
  patterns here.
230
- <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=2fbb9b9e9245162fa8cdb51e0a1396dde89b3d459ad5bcc29b45b92ade7a0022 name=iwsdk-pwa-packaging (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
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) -->
@@ -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.1 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) -->
@@ -332,4 +332,4 @@ The final visual check must confirm:
332
332
  Finish with a passing typecheck and production build, no UIKit parser/resource
333
333
  errors, and concise runtime evidence. Remove temporary preview files or camera
334
334
  workarounds that are not deliverables.
335
- <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=9b79caeeedded4cb53e69688c7e5006daa1187c951a333ef06cbdb3063f062a2 name=iwsdk-ui (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
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.1 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) -->
@@ -59,4 +59,4 @@ mesh lowers to one `InstancedMesh`.
59
59
  Start assets at `castShadow: false` and opt in only for grounded focal masses.
60
60
  Don't build contact-shadow blob cards or `ShadowMaterial` catcher planes here: put
61
61
  `ContactShadow` or `ShadowCatcher` node components on the scene nodes instead.
62
- <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=e6b8d299d9f7590043801fae63d23de387e937bcb87bafe59b9b70f6e0622db3 name=assets-and-manifest.mdc (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
62
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=e6b8d299d9f7590043801fae63d23de387e937bcb87bafe59b9b70f6e0622db3 name=assets-and-manifest.mdc (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -102,4 +102,4 @@ buttons. Browser controls live at `world.input.keyboard` and
102
102
  `world.visibilityState` reports `NonImmersive`, `Visible`, `VisibleBlurred` —
103
103
  pause simulation on blur. `world.camera.position` is local to `world.player`; use
104
104
  `getWorldPosition()` when logic needs the true viewer position.
105
- <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=f09a86b27ce781f8e69b6471051167bee392ac2f503526df33ded757940268f6 name=ecs-api.mdc (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
105
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=f09a86b27ce781f8e69b6471051167bee392ac2f503526df33ded757940268f6 name=ecs-api.mdc (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -71,4 +71,4 @@ back. Render each changed module before the root.
71
71
 
72
72
  For composing a scene rather than editing one, use the `iwsdk-compose-scene`
73
73
  skill — it owns the intake, review and stop-rule procedure this file does not.
74
- <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=f32c3e7d4024f56a3ff5ae32b42c236377551cbd3b2b231e84ada68362b68266 name=scene-json.mdc (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=f32c3e7d4024f56a3ff5ae32b42c236377551cbd3b2b231e84ada68362b68266 name=scene-json.mdc (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -65,4 +65,4 @@ can.
65
65
  For the authoring procedure — isolated preview, placement, editing, wiring
66
66
  runtime behavior, and the completion checklist — use the `iwsdk-ui` skill rather
67
67
  than improvising. This file is the format reference it relies on.
68
- <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=ce002bd4759a1d087c3e18fd3e2a9a009eb3bef5561d0a698f86726a1bd7f9c3 name=uikitml.mdc (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
68
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=ce002bd4759a1d087c3e18fd3e2a9a009eb3bef5561d0a698f86726a1bd7f9c3 name=uikitml.mdc (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -52,4 +52,4 @@ mesh lowers to one `InstancedMesh`.
52
52
  Start assets at `castShadow: false` and opt in only for grounded focal masses.
53
53
  Don't build contact-shadow blob cards or `ShadowMaterial` catcher planes here: put
54
54
  `ContactShadow` or `ShadowCatcher` node components on the scene nodes instead.
55
- <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=6949b512ef5bb71b488b7e8544b4e572f46f73f72a941b248a0856228299bfad name=assets-and-manifest.instructions.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
55
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=6949b512ef5bb71b488b7e8544b4e572f46f73f72a941b248a0856228299bfad name=assets-and-manifest.instructions.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -98,4 +98,4 @@ buttons. Browser controls live at `world.input.keyboard` and
98
98
  `world.visibilityState` reports `NonImmersive`, `Visible`, `VisibleBlurred` —
99
99
  pause simulation on blur. `world.camera.position` is local to `world.player`; use
100
100
  `getWorldPosition()` when logic needs the true viewer position.
101
- <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=724a02986ce0999bc31c02b4f1e4a7b6b83c9966f994979a340e36b6243d26fd name=ecs-api.instructions.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
101
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=724a02986ce0999bc31c02b4f1e4a7b6b83c9966f994979a340e36b6243d26fd name=ecs-api.instructions.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -68,4 +68,4 @@ back. Render each changed module before the root.
68
68
 
69
69
  For composing a scene rather than editing one, use the `iwsdk-compose-scene`
70
70
  skill — it owns the intake, review and stop-rule procedure this file does not.
71
- <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=c73f635cec34f9e99b2bc59ffe63583842d40e419a499225a56cbb7838d9bccd name=scene-json.instructions.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
71
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.2 sha256=c73f635cec34f9e99b2bc59ffe63583842d40e419a499225a56cbb7838d9bccd name=scene-json.instructions.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -62,4 +62,4 @@ can.
62
62
  For the authoring procedure — isolated preview, placement, editing, wiring
63
63
  runtime behavior, and the completion checklist — use the `iwsdk-ui` skill rather
64
64
  than improvising. This file is the format reference it relies on.
65
- <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=f06c88f681a856a0b8b93b5552257dd316f189082dfc0a6bca87e2e642ecbb3e name=uikitml.instructions.md (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=f06c88f681a856a0b8b93b5552257dd316f189082dfc0a6bca87e2e642ecbb3e name=uikitml.instructions.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
@@ -1,4 +1,4 @@
1
- <!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.1 sha256=bb25ffd600c99d3f30cdc95518bb89161659907c667de45adcb29315b669bc7f -->
1
+ <!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.2 sha256=38bd04c1a307ecc19d3693e1482b6f7883fb08e2be0141169ce9857c2c4e75c4 -->
2
2
  # IWSDK project
3
3
 
4
4
  IWSDK changes faster than model training data. GLXF scenes, the external 0.4
@@ -227,6 +227,15 @@ debug it), never when the user wants to put the headset on and try it, and
227
227
  `iwsdk-glasses-test` whenever the user targets Meta VR Glasses or asks for gaze
228
228
  input.
229
229
 
230
+ Distribution skills are invoked directly too, without `iwsdk-dev`, when the
231
+ request ships an app rather than changes it: `iwsdk-hosting` to put it on a
232
+ public HTTPS origin, `iwsdk-pwa-packaging` for a PWA/TWA APK of the hosted
233
+ site, `iwsdk-offline` to keep it working without a connection, and
234
+ `iwsdk-metavr-native` for a standalone APK built with `@iwer/native`
235
+ (`npm run build:metavr`, a `native` section in `iwsdk.config.json`) and for
236
+ installing, running and debugging that APK. "Make an APK" alone is ambiguous:
237
+ ask which of the last two the user wants.
238
+
230
239
  The failure worth guarding against is improvising a domain that already has a
231
240
  skill because the naive approach looks tractable. Before hand-authoring scene
232
241
  JSON, a 3D model, a UIKitML panel, or a physics body, invoke the owning skill.
@@ -1,4 +1,4 @@
1
- <!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.1 sha256=4451a5b98ba38a835cca3fc49666cbe62ba77353f6b8d0ed7d46b691d35067c1 -->
1
+ <!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.2 sha256=4451a5b98ba38a835cca3fc49666cbe62ba77353f6b8d0ed7d46b691d35067c1 -->
2
2
  # IWSDK scoped project guidance
3
3
 
4
4
  This file augments the repository-root `AGENTS.md` for files in this directory.
@@ -1,4 +1,4 @@
1
- <!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.1 sha256=abe74e27fdcd33f9fbdfa6fef5b11cd1427fe15c66fec1a0b884f3a09b750266 -->
1
+ <!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.2 sha256=abe74e27fdcd33f9fbdfa6fef5b11cd1427fe15c66fec1a0b884f3a09b750266 -->
2
2
  # IWSDK scoped project guidance
3
3
 
4
4
  This file augments the repository-root `AGENTS.md` for files in this directory.
@@ -1,4 +1,4 @@
1
- <!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.1 sha256=b60c812e637c6f5bd8f4480f83d7c28a93e042abac20fee504238e8981fa2b6f -->
1
+ <!-- BEGIN iwsdk-agent-guidance version=1.2.0-rc.2 sha256=b60c812e637c6f5bd8f4480f83d7c28a93e042abac20fee504238e8981fa2b6f -->
2
2
  # IWSDK scoped project guidance
3
3
 
4
4
  This file augments the repository-root `AGENTS.md` for files in this directory.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "format": 1,
3
3
  "package": "@iwsdk/core",
4
- "version": "1.2.0-rc.1",
4
+ "version": "1.2.0-rc.2",
5
5
  "units": [
6
6
  {
7
7
  "kind": "directory",
@@ -78,7 +78,7 @@
78
78
  "copilot",
79
79
  "opencode"
80
80
  ],
81
- "sha256": "58d4ce27ef04658c338d8bb0883b0718ba52037bd043fcc5f80783550bc20673",
81
+ "sha256": "f21471a15775b322906d8b1431a149aab73ac6d34acfef6cc05159f7a9d005fb",
82
82
  "files": [
83
83
  "SKILL.md",
84
84
  "references/api-reference.md",
@@ -131,6 +131,21 @@
131
131
  "references/vercel.md"
132
132
  ]
133
133
  },
134
+ {
135
+ "kind": "directory",
136
+ "path": ".agents/skills/iwsdk-metavr-native",
137
+ "tools": [
138
+ "codex",
139
+ "cursor",
140
+ "copilot",
141
+ "opencode"
142
+ ],
143
+ "sha256": "c28e2ac59fab5db24f36df736b7f246c7abbc2b016de2ae90a76a9a20669686e",
144
+ "files": [
145
+ "SKILL.md",
146
+ "assets/iwn-host.mjs"
147
+ ]
148
+ },
134
149
  {
135
150
  "kind": "directory",
136
151
  "path": ".agents/skills/iwsdk-native-xr-test",
@@ -192,7 +207,7 @@
192
207
  "copilot",
193
208
  "opencode"
194
209
  ],
195
- "sha256": "2fbb9b9e9245162fa8cdb51e0a1396dde89b3d459ad5bcc29b45b92ade7a0022",
210
+ "sha256": "6f7204ddddf36831ef555a3ede4202384ea029d217c59fdbf3dc51b903ebdb57",
196
211
  "files": [
197
212
  "SKILL.md",
198
213
  "references/app-modes.md",
@@ -299,6 +314,7 @@
299
314
  "iwsdk-glasses-test",
300
315
  "iwsdk-grab",
301
316
  "iwsdk-hosting",
317
+ "iwsdk-metavr-native",
302
318
  "iwsdk-native-xr-test",
303
319
  "iwsdk-offline",
304
320
  "iwsdk-physics",
@@ -368,7 +384,7 @@
368
384
  "tools": [
369
385
  "claude"
370
386
  ],
371
- "sha256": "58d4ce27ef04658c338d8bb0883b0718ba52037bd043fcc5f80783550bc20673",
387
+ "sha256": "f21471a15775b322906d8b1431a149aab73ac6d34acfef6cc05159f7a9d005fb",
372
388
  "files": [
373
389
  "SKILL.md",
374
390
  "references/api-reference.md",
@@ -412,6 +428,18 @@
412
428
  "references/vercel.md"
413
429
  ]
414
430
  },
431
+ {
432
+ "kind": "directory",
433
+ "path": ".claude/skills/iwsdk-metavr-native",
434
+ "tools": [
435
+ "claude"
436
+ ],
437
+ "sha256": "c28e2ac59fab5db24f36df736b7f246c7abbc2b016de2ae90a76a9a20669686e",
438
+ "files": [
439
+ "SKILL.md",
440
+ "assets/iwn-host.mjs"
441
+ ]
442
+ },
415
443
  {
416
444
  "kind": "directory",
417
445
  "path": ".claude/skills/iwsdk-native-xr-test",
@@ -461,7 +489,7 @@
461
489
  "tools": [
462
490
  "claude"
463
491
  ],
464
- "sha256": "2fbb9b9e9245162fa8cdb51e0a1396dde89b3d459ad5bcc29b45b92ade7a0022",
492
+ "sha256": "6f7204ddddf36831ef555a3ede4202384ea029d217c59fdbf3dc51b903ebdb57",
465
493
  "files": [
466
494
  "SKILL.md",
467
495
  "references/app-modes.md",
@@ -578,7 +606,7 @@
578
606
  "codex",
579
607
  "opencode"
580
608
  ],
581
- "sha256": "bb25ffd600c99d3f30cdc95518bb89161659907c667de45adcb29315b669bc7f"
609
+ "sha256": "38bd04c1a307ecc19d3693e1482b6f7883fb08e2be0141169ce9857c2c4e75c4"
582
610
  },
583
611
  {
584
612
  "kind": "claude-import",
@@ -915,6 +943,7 @@
915
943
  ".agents/skills/iwsdk-glasses-test",
916
944
  ".agents/skills/iwsdk-grab",
917
945
  ".agents/skills/iwsdk-hosting",
946
+ ".agents/skills/iwsdk-metavr-native",
918
947
  ".agents/skills/iwsdk-native-xr-test",
919
948
  ".agents/skills/iwsdk-offline",
920
949
  ".agents/skills/iwsdk-physics",
@@ -937,6 +966,7 @@
937
966
  ".agents/skills/iwsdk-glasses-test",
938
967
  ".agents/skills/iwsdk-grab",
939
968
  ".agents/skills/iwsdk-hosting",
969
+ ".agents/skills/iwsdk-metavr-native",
940
970
  ".agents/skills/iwsdk-native-xr-test",
941
971
  ".agents/skills/iwsdk-offline",
942
972
  ".agents/skills/iwsdk-physics",
package/dist/cli.js CHANGED
@@ -2384,7 +2384,7 @@ function getUnsupportedNodeMessage(version, requiredRange) {
2384
2384
  }
2385
2385
 
2386
2386
  const NODE_ENGINE = ">=20.19.0 <21.0.0-0 || >=22.12.0 <23.0.0-0 || >=24.0.0";
2387
- const CLI_VERSION = "1.2.0-rc.1";
2387
+ const CLI_VERSION = "1.2.0-rc.2";
2388
2388
 
2389
2389
  /**
2390
2390
  * Copyright (c) Meta Platforms, Inc. and affiliates.
package/dist/index.js CHANGED
@@ -33110,7 +33110,7 @@ function reportToolCall(toolName, success, durationMs, error, sessionId, clientV
33110
33110
  metaVrTelemetry(args, clientVersion);
33111
33111
  }
33112
33112
 
33113
- const CLI_VERSION = "1.2.0-rc.1";
33113
+ const CLI_VERSION = "1.2.0-rc.2";
33114
33114
 
33115
33115
  /**
33116
33116
  * Copyright (c) Meta Platforms, Inc. and affiliates.