@iwsdk/cli 0.5.3 → 1.0.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 (39) hide show
  1. package/README.md +62 -1
  2. package/bin/iwsdk.js +1 -1
  3. package/dist/browser-lease.d.ts +14 -0
  4. package/dist/browser-lease.d.ts.map +1 -0
  5. package/dist/cli-types.d.ts +1 -1
  6. package/dist/cli-types.d.ts.map +1 -1
  7. package/dist/cli.js +2811 -485
  8. package/dist/cli.js.map +1 -1
  9. package/dist/commands/browser.d.ts +14 -0
  10. package/dist/commands/browser.d.ts.map +1 -0
  11. package/dist/commands/dev.d.ts +6 -2
  12. package/dist/commands/dev.d.ts.map +1 -1
  13. package/dist/commands/runtime.d.ts.map +1 -1
  14. package/dist/commands/status.d.ts.map +1 -1
  15. package/dist/contract.js +481 -30
  16. package/dist/contract.js.map +1 -1
  17. package/dist/help.d.ts +1 -0
  18. package/dist/help.d.ts.map +1 -1
  19. package/dist/index.d.ts.map +1 -1
  20. package/dist/index.js +2813 -487
  21. package/dist/index.js.map +1 -1
  22. package/dist/mcp-stdio.d.ts.map +1 -1
  23. package/dist/runtime-contract.d.ts +70 -1
  24. package/dist/runtime-contract.d.ts.map +1 -1
  25. package/dist/runtime-files.d.ts +19 -0
  26. package/dist/runtime-files.d.ts.map +1 -0
  27. package/dist/runtime-files.js +318 -0
  28. package/dist/runtime-files.js.map +1 -0
  29. package/dist/runtime-owner.d.ts +50 -0
  30. package/dist/runtime-owner.d.ts.map +1 -0
  31. package/dist/runtime-owner.js +539 -0
  32. package/dist/runtime-owner.js.map +1 -0
  33. package/dist/runtime-state.d.ts +20 -18
  34. package/dist/runtime-state.d.ts.map +1 -1
  35. package/dist/runtime-transport.d.ts.map +1 -1
  36. package/dist/screenshot-output.d.ts +13 -0
  37. package/dist/screenshot-output.d.ts.map +1 -0
  38. package/guidance/AGENTS.md +96 -37
  39. package/package.json +16 -2
@@ -0,0 +1,13 @@
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
+ export type ScreenshotResult = Record<string, unknown> & {
8
+ imageData: string;
9
+ mimeType?: string;
10
+ };
11
+ export declare function isScreenshotResult(value: unknown): value is ScreenshotResult;
12
+ export declare function saveScreenshot(result: ScreenshotResult, requestedPath?: string): Promise<string>;
13
+ //# sourceMappingURL=screenshot-output.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"screenshot-output.d.ts","sourceRoot":"","sources":["../src/screenshot-output.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAO5E;AAED,wBAAsB,cAAc,CAClC,MAAM,EAAE,gBAAgB,EACxB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,MAAM,CAAC,CAYjB"}
@@ -8,25 +8,48 @@ format. Harnesses that use `AGENTS.md` also receive equivalent nested files near
8
8
  the code they govern. Read the applicable scoped instructions before working in
9
9
  that area.
10
10
 
11
+ Explain immersive terms in plain language when they first matter instead of
12
+ assuming the reader knows them. In particular, introduce XR (an immersive
13
+ session), IWER (IWSDK's browser-based XR emulator), ECS (entity-component
14
+ system), and controller target-ray versus grip poses with a link to the
15
+ applicable IWSDK guide or concept page.
16
+
11
17
  ## What is not standard Vite
12
18
 
13
19
  **`iwsdk.config.json` is the project authority, not `vite.config.ts`.** It selects
14
20
  the active scene, the asset module, the component module, and all XR/world
15
21
  features. `vite.config.ts` only wires the plugin. Editing `iwsdk.config.json`
16
22
  restarts Vite in place; the managed window remains open and its command bridges
17
- reconnect automatically. Wait for `npx iwsdk dev status` to report
23
+ reconnect automatically. Wait for `npx @iwsdk/cli dev status` to report
18
24
  `browserCommandReady: true` before issuing browser-backed commands.
19
25
 
20
26
  **`virtual:iwsdk-project` is a virtual module**, not a file. `src/index.ts` or
21
27
  `src/index.js` imports it and passes it whole to `World.create()`. Do not
22
28
  hand-build that options object.
23
29
 
24
- **The dev server is CLI-managed.** Use `npx iwsdk dev up` (or `npm run dev`), not
30
+ **The dev server is CLI-managed.** Use `npx @iwsdk/cli dev up` (or `npm run dev`), not
25
31
  `vite`. It launches a managed browser that hosts the MCP command bridge.
26
- `--no-open` intentionally starts only the server: status reports
27
- `browser.status: "not_launched"`, and browser-backed commands fail immediately
28
- with `browser_not_launched` plus restart guidance. One managed window hosts two
29
- roles, editor and runtime.
32
+ `--no-open` starts the server with managed-browser launch disabled. Server status
33
+ and explicitly paired physical targets remain available. A targetless managed
34
+ browser command then fails with `browser_not_launched`; it never falls through
35
+ to a physical page. Commands default to the managed browser. One managed
36
+ window hosts the editor and application roles. Browser failure leaves Vite and
37
+ HMR running. `runtime status`, `runtime targets`, and `runtime wait` do not recover
38
+ or launch a browser; `runtime recover` explicitly retries after a failure.
39
+
40
+ Pair a headset using `runtime pair-headset --input-json '{"headsetId":"ADB_SERIAL"}'`,
41
+ open the returned URL on that exact device through ADB reverse, then copy its
42
+ `runtimeTarget` from `runtime targets`. Include deviceClass, headsetId, pageId, and
43
+ tabGeneration on every physical command. Reload is supported through the page
44
+ bridge; screenshot, snapshot, interaction, profiling, console capture, and the
45
+ managed editor are host-only. Rediscover after reload to get the new generation.
46
+
47
+ The developer owns whether that managed window is headed or headless. Do not
48
+ change modes silently: announce the change before restarting. In a visible
49
+ collaboration session, use the Runtime/Editor toggle in the single managed
50
+ Chromium window. Its expected unsupported-flag banner comes from
51
+ `--ignore-certificate-errors` for the local development certificate. Playwright
52
+ may add separate sandbox-related flags in constrained environments.
30
53
 
31
54
  **`src/assets.ts`/`src/assets.js` is evaluated twice, in two different JS
32
55
  realms** — once by the app runtime, once by the editor. It must be deterministic
@@ -47,28 +70,32 @@ and subtle breakage. Exception: `import type { GLTF } from 'three/addons/...'`.
47
70
 
48
71
  ## Traps that produce silent failures
49
72
 
50
- | Trap | Symptom | Fix |
51
- | ------------------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
52
- | `locomotion: true` with no `LocomotionEnvironment` on a floor | player falls through the world | add the component to a walkable surface |
53
- | Scene origin left occupied | player spawns inside your geometry | the player origin is `0,0,0` unless the scene authors `player.transform` |
54
- | Scene JSON with `imports` | authoring preview works, but editable open and runtime load are rejected | run `npx iwsdk scene flatten` once, then edit the flat output |
55
- | `entity.destroy()` | GPU memory leaked | use `entity.dispose()` |
56
- | `setValue` on a Vec2/Vec3/Vec4/Color field | throws in elics 3.4.x | use `entity.getVectorView(...)` |
57
- | Environment component on a non-root entity | silently ignored | `DomeGradient`/`IBLGradient` go on the level root only |
58
- | Environment prop changed without `_needsUpdate` | change ignored | set `_needsUpdate` after writing |
59
- | `ScreenSpace` given numbers | clamped with a console warning | it takes CSS strings: `'400px'`, `'25vw'` |
60
- | `@iwsdk/reference` MCP tools in an old or `--no-install` app | queries report warmup required | run `npx iwsdk reference warmup`; fresh installed scaffolds do this during creation |
73
+ | Trap | Symptom | Fix |
74
+ | ------------------------------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
75
+ | `locomotion: true` with no `LocomotionEnvironment` on a floor | player falls through the world | add the component to a walkable surface |
76
+ | Scene origin left occupied | player spawns inside your geometry | the player origin is `0,0,0` unless the scene authors `player.transform` |
77
+ | Scene JSON with `imports` | authoring preview works, but editable open and runtime load are rejected | run `npx @iwsdk/cli scene flatten` once, then edit the flat output |
78
+ | `entity.destroy()` | GPU memory leaked | use `entity.dispose()` |
79
+ | `setValue` on a Vec2/Vec3/Vec4/Color field | throws in elics 3.4.x | use `entity.getVectorView(...)` |
80
+ | Environment component on a non-root entity | silently ignored | `DomeGradient`/`IBLGradient` go on the level root only |
81
+ | Environment prop changed without `_needsUpdate` | change ignored | set `_needsUpdate` after writing |
82
+ | `ScreenSpace` given numbers | clamped with a console warning | it takes CSS strings: `'400px'`, `'25vw'` |
83
+ | `@iwsdk/reference` MCP tools in an old or `--no-install` app | queries report warmup required | run `npx @iwsdk/cli reference warmup`; fresh installed scaffolds do this during creation |
61
84
 
62
85
  ## Verify before you claim it works
63
86
 
64
- **Always `npx tsc --noEmit` before testing.** Type errors stop systems
87
+ **Always `npm run --if-present typecheck` before testing.** Type errors stop systems
65
88
  initialising without necessarily logging anything in the browser.
66
89
 
90
+ For a new multi-file procedural model, finish the initial asset module and manifest
91
+ registration before `npx @iwsdk/cli dev up`; do not keep the browser live while its import
92
+ graph is half-written. Typecheck first, then launch the managed editor for inspection.
93
+
67
94
  Then check the right status for the task — these are not interchangeable:
68
95
 
69
96
  - scene/editor work → `scene_get_state`
70
97
  - XR device or session actions → `xr_get_session_status`
71
- - server readiness → `npx iwsdk dev status` (XR availability is not a server signal)
98
+ - server readiness → `npx @iwsdk/cli dev status` (XR availability is not a server signal)
72
99
 
73
100
  When something is missing but the console is clean: call
74
101
  `browser_get_console_logs` with only `count` (a `level` filter hides errors), then
@@ -79,41 +106,73 @@ The non-obvious part is which observation proves what: the **editor** render doe
79
106
  not run application systems, so anything driven by a system must be verified with
80
107
  `browser_screenshot` (runtime), not `scene_screenshot` (editor).
81
108
 
109
+ Pose, controller/hand alignment, and immersive interaction claims require an
110
+ active XR session (`npx @iwsdk/cli xr status`). A flat runtime screenshot taken
111
+ outside XR can prove that the app renders, but it cannot prove immersive pose or
112
+ interaction correctness.
113
+
114
+ For a physical headset smoke test, run `npx @iwsdk/cli dev status`, open a URL from
115
+ `data.runtimeUrls.network` on a headset connected to the same Wi-Fi network,
116
+ and accept the expected local certificate warning. See
117
+ [Testing Your Experience](https://iwsdk.dev/guides/02-testing-experience.html)
118
+ for the complete workflow.
119
+
82
120
  ## MCP and CLI are one surface, not two
83
121
 
84
122
  Nearly every capability exists both ways — `scene_render_file` and
85
- `npx iwsdk scene render-file`, `ecs_find_entities` and `npx iwsdk ecs find`.
86
- Discover CLI actions with the bare domain or domain help (`npx iwsdk scene` or
87
- `npx iwsdk scene --help`); both list that domain's actions.
88
-
89
- **The CLI is not a fallback for a dead bridge.** Both routes drive the same
90
- managed browser, so when `dev status` reports `browserConnected: false`,
91
- every scene/ecs/xr/browser/ui command fails either way. Only `dev status`,
92
- `dev logs` and `reference status` work without a browser.
123
+ `npx @iwsdk/cli scene render-file`, `ecs_find_entities` and `npx @iwsdk/cli ecs find`,
124
+ or `ui_inspect` and `npx @iwsdk/cli ui inspect`.
125
+ Discover CLI actions with the bare domain or domain help (`npx @iwsdk/cli scene` or
126
+ `npx @iwsdk/cli scene --help`); both list that domain's actions.
127
+
128
+ **CLI and MCP share the same target resolver and recovery policy.** A managed
129
+ command can recover a missing managed browser; it then returns
130
+ `browser_relaunched` with `outcome: "not_executed"`. Inspect the new state and issue
131
+ a fresh command. `outcome_unknown` means a dispatched mutation may have executed;
132
+ inspect state before retrying. Requests are never broadcast or replayed on
133
+ reconnect. Host browser tools can remain usable while a runtime bridge is loading.
93
134
 
94
135
  Choose by the shape of the call, not by availability:
95
136
 
96
- - **MCP** for one-off calls, and whenever you want the image returned inline.
137
+ - **MCP** for one-off calls. Screenshot tools persist the PNG locally and return
138
+ `screenshotPath`; read that file only when visual inspection is needed.
97
139
  - **CLI** when you need to loop or script — rendering six views, or sampling a
98
140
  value twice to measure a rate — or when the response is big enough to be worth
99
141
  filtering before it reaches context. A render of a scene containing an
100
142
  instanced pattern returns an id for every expanded instance.
101
143
 
102
- CLI `--output-file` returns a **different payload shape** from the plain call:
103
- the result nests under `data.result` instead of `data`, and `renderStats` and the
104
- hashes are dropped. If you need a hash or triangle count, omit `--output-file`
105
- and filter the JSON instead.
144
+ For screenshot-producing CLI commands, the default response writes the image to a
145
+ temporary file and returns a normal envelope with metadata under `data.result` and
146
+ the path at `data.screenshotPath`. `--output-file <path>` selects the destination and
147
+ keeps that same metadata, including hashes and render statistics. `--raw` instead
148
+ prints the raw runtime result, including base64 `imageData`; when both flags are
149
+ present, `--output-file` takes precedence and image bytes are omitted.
106
150
 
107
151
  ## Skills
108
152
 
109
- Scene composition, UI authoring, physics, depth occlusion, grab and ray
110
- interaction testing, ECS frame-stepping, and end-to-end planning each have a
111
- project skill in the selected harness's standard skill directory. Their
112
- descriptions handle routing, so they are not restated here.
153
+ Invoke `iwsdk-dev` first for any request that builds, extends, fixes, tunes,
154
+ or polishes the app. It privately selects the greenfield planner path or the
155
+ bounded established-app iteration path; do not look for those paths as separate
156
+ public skills.
157
+
158
+ The selected playbook routes work to the narrowest owning specialist:
159
+
160
+ - creating or materially changing one glTF or procedural 3D asset →
161
+ `iwsdk-build-model`;
162
+ - arranging existing assets, scene JSON, cross-asset contacts, lighting,
163
+ environment, or cameras → `iwsdk-compose-scene`;
164
+ - a mixed build → finish every new or changed model, including support and set assets,
165
+ with `iwsdk-build-model`, then compose the scene with `iwsdk-compose-scene`;
166
+ - a model-local defect found during composition routes back to `iwsdk-build-model`;
167
+ a placement or lighting defect stays in `iwsdk-compose-scene`.
168
+
169
+ UI authoring, physics, depth occlusion, grab and ray interaction testing, ECS
170
+ frame-stepping, and debugging have their own project skills. Use them only when
171
+ the selected `iwsdk-dev` playbook calls for the matching specialty.
113
172
 
114
173
  The failure worth guarding against is improvising a domain that already has a
115
174
  skill because the naive approach looks tractable. Before hand-authoring scene
116
- JSON, a UIKitML panel, or a physics body, invoke the skill.
175
+ JSON, a 3D model, a UIKitML panel, or a physics body, invoke the owning skill.
117
176
 
118
177
  ## Layout
119
178
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@iwsdk/cli",
3
- "version": "0.5.3",
3
+ "version": "1.0.0-rc.1",
4
4
  "description": "Runtime-first CLI for IWSDK dev servers, adapters, and MCP access",
5
5
  "private": false,
6
6
  "type": "module",
@@ -17,12 +17,26 @@
17
17
  "./contract": {
18
18
  "types": "./dist/runtime-contract.d.ts",
19
19
  "import": "./dist/contract.js"
20
+ },
21
+ "./runtime-files": {
22
+ "types": "./dist/runtime-files.d.ts",
23
+ "import": "./dist/runtime-files.js"
24
+ },
25
+ "./runtime-owner": {
26
+ "types": "./dist/runtime-owner.d.ts",
27
+ "import": "./dist/runtime-owner.js"
20
28
  }
21
29
  },
22
30
  "typesVersions": {
23
31
  "*": {
24
32
  "contract": [
25
33
  "dist/runtime-contract.d.ts"
34
+ ],
35
+ "runtime-files": [
36
+ "dist/runtime-files.d.ts"
37
+ ],
38
+ "runtime-owner": [
39
+ "dist/runtime-owner.d.ts"
26
40
  ]
27
41
  }
28
42
  },
@@ -66,7 +80,7 @@
66
80
  "prebuild": "node scripts/gen-version.cjs",
67
81
  "build": "tsc -p tsconfig.json --emitDeclarationOnly && rollup -c",
68
82
  "clean": "rm -rf dist",
69
- "test": "corepack pnpm@10.18.3 build && vitest run",
83
+ "test": "npm run build && vitest run",
70
84
  "test:watch": "vitest"
71
85
  }
72
86
  }