@iwsdk/create 1.1.0 → 1.2.0-rc.0
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.
- package/README.md +52 -15
- package/dist/cli.js +7538 -3405
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-build-model/SKILL.md +1 -0
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-compose-scene/SKILL.md +3 -2
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-debug/SKILL.md +1 -0
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-depth-occlusion/SKILL.md +1 -0
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-dev/SKILL.md +1 -0
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-dev/references/api-reference.md +6 -0
- package/dist/guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-dev/references/iterate.md +10 -5
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-dev/references/planner.md +9 -5
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-glasses-test/SKILL.md +1 -0
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-grab/SKILL.md +1 -0
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-hosting/SKILL.md +1 -0
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-native-xr-test/SKILL.md +17 -1
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-physics/SKILL.md +1 -0
- package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-pwa-packaging/SKILL.md +1 -0
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-ray/SKILL.md +1 -0
- package/dist/guidance/{agents → files}/.agents/skills/iwsdk-ui/SKILL.md +6 -3
- package/dist/guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/guidance/{claude → files}/.claude/agents/iwsdk-project-code-reviewer.md +1 -0
- package/dist/guidance/{claude → files}/.claude/rules/assets-and-manifest.md +3 -0
- package/dist/guidance/{claude → files}/.claude/rules/ecs-api.md +1 -0
- package/dist/guidance/{claude → files}/.claude/rules/scene-json.md +1 -0
- package/dist/guidance/{claude → files}/.claude/rules/uikitml.md +1 -0
- package/dist/guidance/{claude → files}/.claude/settings.json +8 -3
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-build-model/SKILL.md +1 -0
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-compose-scene/SKILL.md +3 -2
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-debug/SKILL.md +1 -0
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-depth-occlusion/SKILL.md +1 -0
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-dev/SKILL.md +1 -0
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-dev/references/api-reference.md +6 -0
- package/dist/guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-dev/references/iterate.md +10 -5
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-dev/references/planner.md +9 -5
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-glasses-test/SKILL.md +1 -0
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-grab/SKILL.md +1 -0
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-hosting/SKILL.md +1 -0
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-native-xr-test/SKILL.md +17 -1
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-physics/SKILL.md +1 -0
- package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-pwa-packaging/SKILL.md +1 -0
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-ray/SKILL.md +1 -0
- package/dist/guidance/{claude → files}/.claude/skills/iwsdk-ui/SKILL.md +6 -3
- package/dist/guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/guidance/{cursor → files}/.cursor/rules/assets-and-manifest.mdc +3 -0
- package/dist/guidance/{cursor → files}/.cursor/rules/ecs-api.mdc +1 -0
- package/dist/guidance/{cursor → files}/.cursor/rules/scene-json.mdc +1 -0
- package/dist/guidance/{cursor → files}/.cursor/rules/uikitml.mdc +1 -0
- package/dist/guidance/{copilot → files}/.github/instructions/assets-and-manifest.instructions.md +2 -1
- package/dist/guidance/{copilot → files}/.github/instructions/ecs-api.instructions.md +1 -0
- package/dist/guidance/{copilot → files}/.github/instructions/scene-json.instructions.md +1 -0
- package/dist/guidance/{copilot → files}/.github/instructions/uikitml.instructions.md +1 -0
- package/dist/guidance/{common → files}/AGENTS.md +107 -27
- package/dist/guidance/{scoped-agents → files}/public/scenes/AGENTS.md +2 -0
- package/dist/guidance/{scoped-agents → files}/public/ui/AGENTS.md +2 -0
- package/dist/guidance/{scoped-agents → files}/src/AGENTS.md +2 -0
- package/dist/guidance/manifest.json +854 -0
- package/dist/template/common/.codex/config.toml +2 -0
- package/package.json +5 -5
- package/scripts/verify-release-ready.mjs +1 -2
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-build-model/agents/openai.yaml +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/image-intake.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/scene-format.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/scene-review.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/text-intake.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-hosting/references/existing-hosts.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-hosting/references/vercel.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-physics/references/component-reference.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-physics/references/tuning-and-config.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-physics/references/workflows.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +0 -0
- /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-build-model/agents/openai.yaml +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/image-intake.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/scene-format.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/scene-review.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/text-intake.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-hosting/references/existing-hosts.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-hosting/references/vercel.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-physics/references/component-reference.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-physics/references/tuning-and-config.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-physics/references/workflows.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +0 -0
- /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +0 -0
- /package/dist/guidance/{claude → files}/CLAUDE.md +0 -0
- /package/dist/{guidance/codex → template/common-js}/.codex/config.toml +0 -0
|
@@ -309,3 +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) -->
|
|
@@ -122,8 +122,8 @@ npx @iwsdk/cli scene state --raw
|
|
|
122
122
|
`iwsdk dev up` starts the server in the background and launches the configured
|
|
123
123
|
managed editor browser. It can return while that browser is still starting; use
|
|
124
124
|
`iwsdk runtime wait` or inspect `iwsdk runtime status` before browser-backed
|
|
125
|
-
commands.
|
|
126
|
-
startup workaround.
|
|
125
|
+
commands. Pass the `--ai-mode` that AGENTS.md's session rule picks; do not edit
|
|
126
|
+
`vite.config.ts` to change browser mode as an ad hoc startup workaround.
|
|
127
127
|
|
|
128
128
|
`scene_render_file` renders a file without replacing the editor's active document,
|
|
129
129
|
but it still uses the managed editor browser for manifest evaluation and WebGL.
|
|
@@ -274,3 +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) -->
|
|
@@ -71,3 +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) -->
|
package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-depth-occlusion/SKILL.md
RENAMED
|
@@ -85,3 +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) -->
|
|
@@ -43,3 +43,4 @@ Observable workspace state wins over wording:
|
|
|
43
43
|
|
|
44
44
|
iwsdk-dev does not add another implementation phase. The selected playbook owns
|
|
45
45
|
the work, evidence budget, specialist routing, verification, and stopping rule.
|
|
46
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=07f4648993de9020eb6eee38c94ad442ac6b1ca8ede99e4d369de20e60e3af2f name=iwsdk-dev (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -1387,6 +1387,12 @@ const texture = AssetManager.getTexture('myTexture');
|
|
|
1387
1387
|
const audio = AssetManager.getAudio('mySound');
|
|
1388
1388
|
```
|
|
1389
1389
|
|
|
1390
|
+
**Render loop (headless automation):** `world.renderMode` is `'continuous'`
|
|
1391
|
+
(default) or `'on-demand'`. On demand, systems still run every frame but only
|
|
1392
|
+
frames asked for are drawn: `await world.requestRender(frames)` or
|
|
1393
|
+
`const release = world.holdRender()` (draw every frame until `release()`).
|
|
1394
|
+
Headless dev sessions switch it on for you; shipped apps keep `'continuous'`.
|
|
1395
|
+
|
|
1390
1396
|
**Runtime loading (on-demand):**
|
|
1391
1397
|
|
|
1392
1398
|
```typescript
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# Headless rendering (no GPU)
|
|
2
|
+
|
|
3
|
+
Read this when the managed session is headless (`--ai-mode agent` or
|
|
4
|
+
`--headless`), the host has no GPU, or a result depends on frame rate, frame
|
|
5
|
+
timing, or which frame a screenshot shows.
|
|
6
|
+
|
|
7
|
+
## What headless sessions do
|
|
8
|
+
|
|
9
|
+
A headless managed session renders **on demand**. Every ECS system, input,
|
|
10
|
+
physics and UI update still runs on every frame, but the app draws a frame only
|
|
11
|
+
when a tool needs pixels. Without a GPU every draw is software-rasterized, so
|
|
12
|
+
this keeps the app at the browser's frame rate (60 fps) instead of a few frames
|
|
13
|
+
per second.
|
|
14
|
+
|
|
15
|
+
- `browser screenshot` draws a fresh frame first. Screenshots always show the
|
|
16
|
+
current state, in the browser view and in XR. In emulated AR, the synthetic
|
|
17
|
+
room behind the app draws with it, so the two always match.
|
|
18
|
+
- `scene render-stats` draws one fresh frame before it reads the stats.
|
|
19
|
+
`browser profile`, runtime evidence and `browser run` scripts draw every
|
|
20
|
+
frame while they run.
|
|
21
|
+
- Headed sessions, including collaborate mode, always draw every frame.
|
|
22
|
+
- To draw every frame in a headless session, start it with
|
|
23
|
+
`IWSDK_DEV_RENDER_MODE=continuous`.
|
|
24
|
+
|
|
25
|
+
## Check state, then look
|
|
26
|
+
|
|
27
|
+
Prove behavior with ECS state (`ecs query`, `ecs find`, `ecs snapshot`,
|
|
28
|
+
`ecs diff`). These need no pixels and see every frame. Take a screenshot only
|
|
29
|
+
for visual claims.
|
|
30
|
+
|
|
31
|
+
## Capture an exact frame
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
npx @iwsdk/cli ecs pause --input-json '{}'
|
|
35
|
+
npx @iwsdk/cli ecs step --input-json '{"count":1}'
|
|
36
|
+
npx @iwsdk/cli browser screenshot --input-json '{}' --output-file artifacts/frame.png
|
|
37
|
+
npx @iwsdk/cli ecs resume --input-json '{}'
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
A screenshot draws without advancing the simulation, so it shows exactly the
|
|
41
|
+
paused frame.
|
|
42
|
+
|
|
43
|
+
To see motion, capture a filmstrip: exact simulation frames at offsets 0, K,
|
|
44
|
+
2K, … in one contact-sheet image.
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
npx @iwsdk/cli browser filmstrip --count 6 --every 5 --output-file artifacts/fall.png
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Switch the render mode at runtime
|
|
51
|
+
|
|
52
|
+
The `RuntimeSettings` component controls the render mode. It exists only at
|
|
53
|
+
runtime and is never saved into scene files.
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
npx @iwsdk/cli ecs find --input-json '{"withComponents":["RuntimeSettings"]}'
|
|
57
|
+
npx @iwsdk/cli ecs set-component --input-json '{"entityIndex":<index>,"componentId":"RuntimeSettings","field":"renderMode","value":"continuous"}'
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Without a GPU, continuous drawing drops the app to a few frames per second, so
|
|
61
|
+
set it back to `"on-demand"` when done.
|
|
62
|
+
|
|
63
|
+
## Do not
|
|
64
|
+
|
|
65
|
+
- Judge performance from headless frame rates. Profile instead, which draws
|
|
66
|
+
every frame while it runs, or measure on a device:
|
|
67
|
+
`npx @iwsdk/cli browser profile --input-json '{"action":"start","mode":"rendering"}'`,
|
|
68
|
+
exercise the scene, then
|
|
69
|
+
`npx @iwsdk/cli browser profile --input-json '{"action":"stop"}'`.
|
|
70
|
+
- Expect a frame to change between screenshots if the scene did not change.
|
|
71
|
+
- Restart into headed mode to "fix" a stale view; screenshots already draw a
|
|
72
|
+
fresh frame.
|
|
73
|
+
|
|
74
|
+
## Limits
|
|
75
|
+
|
|
76
|
+
- App code that reads pixels from the canvas itself (for example
|
|
77
|
+
`canvas.toDataURL()`) must draw and read in the same task (call
|
|
78
|
+
`renderer.render()`, then read), or create the renderer with
|
|
79
|
+
`preserveDrawingBuffer: true`. `await world.requestRender()` resolves after
|
|
80
|
+
the frame is presented, when the drawing buffer may already be cleared. See
|
|
81
|
+
the render loop API: `world.renderMode`, `world.requestRender(frames)` and
|
|
82
|
+
`world.holdRender()`.
|
package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-dev/references/iterate.md
RENAMED
|
@@ -87,11 +87,16 @@ the output bounded. The existing scaffold rules are already in context:
|
|
|
87
87
|
3. Implement the smallest complete vertical delta, including state/UI feedback
|
|
88
88
|
and recovery when the request needs them.
|
|
89
89
|
4. Run one batched typecheck and fix errors together.
|
|
90
|
-
5. Start the managed runtime directly
|
|
91
|
-
`npx @iwsdk/cli dev up --
|
|
90
|
+
5. Start the managed runtime directly in the mode AGENTS.md's session rule
|
|
91
|
+
picks: `npx @iwsdk/cli dev up --ai-mode agent --timeout 45000`, or
|
|
92
|
+
`--ai-mode collaborate` when the user is watching. Headless sessions draw
|
|
93
|
+
only when a tool needs pixels; read references/headless-rendering.md before
|
|
94
|
+
relying on frame rate, frame timing, or which frame a screenshot shows.
|
|
92
95
|
6. Exercise the changed path with real user input and query only the named state
|
|
93
96
|
needed to prove it. Direct ECS mutation may prepare/reset a scenario but is
|
|
94
|
-
not interaction proof.
|
|
97
|
+
not interaction proof. If the state you need to prepare lives in a plain
|
|
98
|
+
object outside ECS, move it into a component as part of the change rather
|
|
99
|
+
than editing constants temporarily or enabling browser automation.
|
|
95
100
|
7. Run one focused regression smoke for the preserved behavior most likely to
|
|
96
101
|
have been affected.
|
|
97
102
|
8. Run the production build and stop.
|
|
@@ -150,13 +155,13 @@ npx @iwsdk/cli xr run-sequence --input-json '{"device":"hand-right","steps":[{"p
|
|
|
150
155
|
```
|
|
151
156
|
|
|
152
157
|
Query `Grabbed` between the grab and the release. A press result whose
|
|
153
|
-
`presses[0].contactMs` is 800 or more did not click.
|
|
158
|
+
`presses[0].contactMs` is 800 or more did not click. A stalled frame can
|
|
154
159
|
stretch a press that far, so run that press once more before changing code.
|
|
155
160
|
|
|
156
161
|
If a scene/source/UI edit happens after the managed runtime started and live
|
|
157
162
|
state becomes stale, do not call `scene open`, repeatedly poll `dev status`, or
|
|
158
163
|
loop on browser reload. Run one
|
|
159
|
-
`npx @iwsdk/cli dev restart --
|
|
164
|
+
`npx @iwsdk/cli dev restart --ai-mode <the session's current mode> --timeout 60000`, then resume the named-state
|
|
160
165
|
check. One failed restart may be diagnosed once; do not enter a recovery loop.
|
|
161
166
|
|
|
162
167
|
Do not perform a full product replay when the edit affects one bounded path.
|
package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-dev/references/planner.md
RENAMED
|
@@ -184,7 +184,9 @@ the same question.
|
|
|
184
184
|
Build the smallest structure that covers the whole contract:
|
|
185
185
|
|
|
186
186
|
1. native scene assets and deliberate hero/panel framing;
|
|
187
|
-
2. component schemas and explicit authored values
|
|
187
|
+
2. component schemas and explicit authored values, including game state such
|
|
188
|
+
as score, lives, phase and timers, so verification can jump to any state
|
|
189
|
+
with `ecs set-component` instead of playing there or scripting the page;
|
|
188
190
|
3. interaction/state systems;
|
|
189
191
|
4. UIKitML and runtime control wiring;
|
|
190
192
|
5. visible state feedback.
|
|
@@ -205,13 +207,15 @@ physics, deployment, and interactions with meaningful failure modes need
|
|
|
205
207
|
broader scenarios and stronger evidence.
|
|
206
208
|
|
|
207
209
|
After the coherent vertical slice typechecks, start one managed dev session
|
|
208
|
-
and keep it alive while iterating.
|
|
209
|
-
|
|
210
|
-
replacing
|
|
210
|
+
and keep it alive while iterating. Pick headed or headless with the session
|
|
211
|
+
rule in AGENTS.md (headless unless the user wants to watch) and announce a later
|
|
212
|
+
mode change before restarting rather than silently replacing a visible window. Do not start an untouched or
|
|
211
213
|
knowingly non-typechecking app. Exercise the real paths rather than inferring
|
|
212
214
|
behavior from code. Confirm `npx @iwsdk/cli xr status` is active before making pose,
|
|
213
215
|
controller/hand alignment, or immersive-interaction claims; a flat screenshot
|
|
214
|
-
outside XR cannot prove them.
|
|
216
|
+
outside XR cannot prove them. Headless sessions draw only when a tool needs
|
|
217
|
+
pixels; read references/headless-rendering.md before relying on frame rate,
|
|
218
|
+
frame timing, or which frame a screenshot shows.
|
|
215
219
|
|
|
216
220
|
Verify:
|
|
217
221
|
|
|
@@ -279,3 +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) -->
|
|
@@ -72,3 +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) -->
|
|
@@ -175,3 +175,4 @@ trip:
|
|
|
175
175
|
|
|
176
176
|
Packaging the hosted app into a signed Quest APK is the `iwsdk-pwa-packaging`
|
|
177
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) -->
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: iwsdk-native-xr-test
|
|
3
|
-
description:
|
|
3
|
+
description: Drive an IWSDK app in a real Quest immersive session while you control headset and controller poses through the IWSDK CLI. Use when you will automate, script-test, or debug an app on a connected Quest. Not for the user trying the app by hand; native control takes over their head pose and controllers, so give them a plain dev session instead.
|
|
4
4
|
argument-hint: '[test scenario]'
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -14,6 +14,17 @@ override poses and input for the test.
|
|
|
14
14
|
|
|
15
15
|
The requested scenario is in `$ARGUMENTS`.
|
|
16
16
|
|
|
17
|
+
## Not for hands-on testing
|
|
18
|
+
|
|
19
|
+
Use this skill only when you drive the headset. If the user wants to put the
|
|
20
|
+
headset on and try the app themselves, do not start native control and do not
|
|
21
|
+
give them a pairing URL. A `--native-xr-control` session overrides the head pose
|
|
22
|
+
and controllers of every Quest Browser page it serves, even after the pairing
|
|
23
|
+
token is removed from the URL; the page shows an "Agent-controlled page"
|
|
24
|
+
notice saying so. Restart without the flag and hand over a plain URL as described in
|
|
25
|
+
AGENTS.md. If a native-control test is running when the user asks to try the
|
|
26
|
+
app, finish or stop it, clean up as in step 6, then do the same.
|
|
27
|
+
|
|
17
28
|
## Safety and scope
|
|
18
29
|
|
|
19
30
|
- Use only public Android platform tools and IWSDK commands. Do not depend on a
|
|
@@ -244,3 +255,8 @@ Report:
|
|
|
244
255
|
- before/after evidence for the requested behavior;
|
|
245
256
|
- console errors or capability notes;
|
|
246
257
|
- confirmation that the reverse route and dev session were removed.
|
|
258
|
+
|
|
259
|
+
If the user wants to try the app in the headset afterwards, start a plain
|
|
260
|
+
session (`npx @iwsdk/cli dev up` with the session's `--ai-mode`, without
|
|
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) -->
|
|
@@ -103,3 +103,4 @@ authored render cover deliberate framing.
|
|
|
103
103
|
Make at most one focused correction, then replay the same observation. Stop
|
|
104
104
|
when the requested bodies, collisions, and final state are evidenced. Resume
|
|
105
105
|
ECS time and leave the app in a stable state.
|
|
106
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=5d66b2f83041f75889735be1e18747b078f2df32025ba1039cb77efbea3c2cb3 name=iwsdk-physics (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -216,3 +216,4 @@ updated — only replaced by a new Store entry.
|
|
|
216
216
|
Getting the app online is the `iwsdk-hosting` skill. Building the app itself is
|
|
217
217
|
`iwsdk-planner` and the other `iwsdk-*` skills — do not re-derive IWSDK
|
|
218
218
|
patterns here.
|
|
219
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=e4e859d1977962769195f6bfb52dc9b02f159dd743e2609ea8b6111dd847e7eb name=iwsdk-pwa-packaging (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -67,3 +67,4 @@ When the request names an artifact path, save it directly with
|
|
|
67
67
|
context and then add a copy step.
|
|
68
68
|
Stop when the real input and resulting named state are proven, leaving all
|
|
69
69
|
buttons released.
|
|
70
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=ec23dce5226ca91367042de7907fb3664c055a1ceb737fede2fd6710eab1f37f name=iwsdk-ray (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -186,8 +186,8 @@ views independently when both modes matter.
|
|
|
186
186
|
## Verify with a bounded loop
|
|
187
187
|
|
|
188
188
|
Typecheck after the complete first slice, then start or reuse one managed
|
|
189
|
-
session. If no command-ready session exists, run `npx @iwsdk/cli dev up
|
|
190
|
-
|
|
189
|
+
session. If no command-ready session exists, run `npx @iwsdk/cli dev up` once,
|
|
190
|
+
with the `--ai-mode` that AGENTS.md's session rule picks. Do not call `dev --help`, separately call `dev open`, restart a healthy
|
|
191
191
|
session, start a second browser, or build a custom UIKit renderer.
|
|
192
192
|
|
|
193
193
|
1. Run `npx @iwsdk/cli ui assets --raw` once to confirm registration.
|
|
@@ -256,7 +256,9 @@ it.
|
|
|
256
256
|
|
|
257
257
|
When the request asks for a poke (near touch) on a control, press it with the
|
|
258
258
|
emulated hand's index fingertip by its element ID. The panel entity needs
|
|
259
|
-
`PokeInteractable
|
|
259
|
+
`PokeInteractable`. Its `hand` field (`"both"`, the default, `"left"` or
|
|
260
|
+
`"right"`) limits which hand can poke it, for example a wrist menu that only
|
|
261
|
+
the other hand should press:
|
|
260
262
|
|
|
261
263
|
```bash
|
|
262
264
|
npx @iwsdk/cli xr set-input-mode --input-json '{"mode":"hand"}'
|
|
@@ -323,3 +325,4 @@ The final visual check must confirm:
|
|
|
323
325
|
Finish with a passing typecheck and production build, no UIKit parser/resource
|
|
324
326
|
errors, and concise runtime evidence. Remove temporary preview files or camera
|
|
325
327
|
workarounds that are not deliverables.
|
|
328
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=f38cb22c3f17e583db46ecffe8ac78d5d58a1b990ebd485e00f1f5623b690332 name=iwsdk-ui (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: iwsdk-upgrade
|
|
3
|
+
description: Upgrade an IWSDK app to a newer IWSDK release and prove it still works. Use when the user asks to upgrade, update or bump IWSDK or any @iwsdk/* package, when iwsdk dev up reports guidance updated from an older release, or when errors appear right after an IWSDK version change.
|
|
4
|
+
argument-hint: '[target version, default latest]'
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Upgrade IWSDK
|
|
8
|
+
|
|
9
|
+
An upgrade has three parts: move the packages, apply what changed between the
|
|
10
|
+
two releases, and show that the app behaves as it did before. Do them in that
|
|
11
|
+
order.
|
|
12
|
+
|
|
13
|
+
## 1. Record the baseline first
|
|
14
|
+
|
|
15
|
+
Before changing any version, check `git status`, make sure the user's work is
|
|
16
|
+
saved or committed (do not commit unless the user allowed it), and record how
|
|
17
|
+
the app behaves now: run its typecheck and build scripts with the project's
|
|
18
|
+
package manager (for example `npm run typecheck` and `npm run build`).
|
|
19
|
+
|
|
20
|
+
Write down every error, then start the dev server and save the browser log and
|
|
21
|
+
a runtime screenshot. Older apps often have errors that predate the upgrade;
|
|
22
|
+
without a baseline you cannot tell them from new ones, and proving it later
|
|
23
|
+
costs a full reinstall.
|
|
24
|
+
|
|
25
|
+
## 2. Move the packages
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npx @iwsdk/cli@latest upgrade --dry-run
|
|
29
|
+
npx @iwsdk/cli@latest upgrade
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
Always run it with `@latest`, even if the project has an older `@iwsdk/cli`:
|
|
33
|
+
the newest CLI carries every migration guide. For a specific release, add
|
|
34
|
+
`--to <version>` (`npx @iwsdk/cli@<version> upgrade` works only for releases
|
|
35
|
+
that include the `upgrade` command). It sets every `@iwsdk/*` package to the release, installs
|
|
36
|
+
with the project's package manager, aligns the `three` alias and an existing
|
|
37
|
+
`@types/three` with `@iwsdk/core`, refreshes this guidance, and writes to `.iwsdk/migrations/`:
|
|
38
|
+
|
|
39
|
+
- one `iwsdk-migrate-*/SKILL.md` for each release boundary that needs code
|
|
40
|
+
changes;
|
|
41
|
+
- `release-notes.md` with every change between the two versions.
|
|
42
|
+
|
|
43
|
+
It also checks `iwsdk.config.json` against the new release and lists settings
|
|
44
|
+
that no longer validate. Packages it reports as "not part of the IWSDK release"
|
|
45
|
+
were left as declared; remove one only if a migration guide says it was
|
|
46
|
+
retired. In a monorepo it installs with the workspace's package manager; if a
|
|
47
|
+
workspace-level override pins `three`, it tells you to change it.
|
|
48
|
+
|
|
49
|
+
If the user asked for a plain package-manager bump instead, do that, then run
|
|
50
|
+
`npx @iwsdk/cli@latest agents sync`; `iwsdk dev up` also refreshes unedited
|
|
51
|
+
guidance.
|
|
52
|
+
|
|
53
|
+
## 3. Apply what changed
|
|
54
|
+
|
|
55
|
+
1. Follow each migration guide in `.iwsdk/migrations/`, oldest first, before
|
|
56
|
+
other work.
|
|
57
|
+
2. Read the major and minor entries in `release-notes.md` and check whether
|
|
58
|
+
the app uses what they change (renamed settings, new required versions,
|
|
59
|
+
changed defaults).
|
|
60
|
+
3. Fix each `iwsdk.config.json` issue the upgrade listed.
|
|
61
|
+
4. Re-read the `iwsdk-agent-guidance` block in `AGENTS.md`: it now describes
|
|
62
|
+
the new release. Do not hand-edit guidance files; an edited file stops
|
|
63
|
+
receiving updates.
|
|
64
|
+
|
|
65
|
+
## 4. Prove it
|
|
66
|
+
|
|
67
|
+
Run the same checks as the baseline and compare. Report new errors and fix
|
|
68
|
+
them; report baseline errors separately as existing. A clean typecheck and
|
|
69
|
+
build do not show that the app renders: confirm the runtime screenshot and an
|
|
70
|
+
error-free browser log, and enter XR when the app is an XR app.
|
|
71
|
+
|
|
72
|
+
The upgrade is done when every migration guide is applied, the comparison
|
|
73
|
+
shows no new errors, and the user knows which existing errors remain.
|
|
74
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=5ccb37dbe152b3611496740e89bc8e42c8d59dfed8be7512635d877924b79988 name=iwsdk-upgrade (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -518,3 +518,4 @@ Only report issues you're confident about:
|
|
|
518
518
|
|
|
519
519
|
[Brief summary of overall code quality and key recommendations]
|
|
520
520
|
```
|
|
521
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=976bd24f6ae91d050ed7bef71cdfb4cfab1fc41e4718d2042d9618860cb1161e name=iwsdk-project-code-reviewer.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
paths:
|
|
3
3
|
- "src/assets.ts"
|
|
4
4
|
- "src/assets.js"
|
|
5
|
+
- "src/iwsdk/assets.ts"
|
|
6
|
+
- "src/iwsdk/assets.js"
|
|
5
7
|
- "src/scene-assets/**"
|
|
6
8
|
---
|
|
7
9
|
|
|
@@ -55,3 +57,4 @@ mesh lowers to one `InstancedMesh`.
|
|
|
55
57
|
Start assets at `castShadow: false` and opt in only for grounded focal masses.
|
|
56
58
|
Don't build contact-shadow blob cards or `ShadowMaterial` catcher planes here: put
|
|
57
59
|
`ContactShadow` or `ShadowCatcher` node components on the scene nodes instead.
|
|
60
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=9c0abbe2f1b3cc83f826ac6a5c24f0088375757ec17bfb970301a3c32b940a44 name=assets-and-manifest.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -100,3 +100,4 @@ buttons. Browser controls live at `world.input.keyboard` and
|
|
|
100
100
|
`world.visibilityState` reports `NonImmersive`, `Visible`, `VisibleBlurred` —
|
|
101
101
|
pause simulation on blur. `world.camera.position` is local to `world.player`; use
|
|
102
102
|
`getWorldPosition()` when logic needs the true viewer position.
|
|
103
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=56f1044b9936f279404ef715676b734a119ef495824d5916737f3a00579acc64 name=ecs-api.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -69,3 +69,4 @@ back. Render each changed module before the root.
|
|
|
69
69
|
|
|
70
70
|
For composing a scene rather than editing one, use the `iwsdk-compose-scene`
|
|
71
71
|
skill — it owns the intake, review and stop-rule procedure this file does not.
|
|
72
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=d507943047667757a27a1b58cff203b0e3d1bdc646b0f5998cf0851840dde550 name=scene-json.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -63,3 +63,4 @@ can.
|
|
|
63
63
|
For the authoring procedure — isolated preview, placement, editing, wiring
|
|
64
64
|
runtime behavior, and the completion checklist — use the `iwsdk-ui` skill rather
|
|
65
65
|
than improvising. This file is the format reference it relies on.
|
|
66
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=101e26d6362ef8867f020086e5edae81ae70c45a11e53339171da8591f41f1a6 name=uikitml.md (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -9,16 +9,21 @@
|
|
|
9
9
|
"Skill(iwsdk-compose-scene)",
|
|
10
10
|
"Skill(iwsdk-debug)",
|
|
11
11
|
"Skill(iwsdk-depth-occlusion)",
|
|
12
|
+
"Skill(iwsdk-dev)",
|
|
12
13
|
"Skill(iwsdk-glasses-test)",
|
|
13
14
|
"Skill(iwsdk-grab)",
|
|
14
15
|
"Skill(iwsdk-hosting)",
|
|
15
16
|
"Skill(iwsdk-native-xr-test)",
|
|
16
17
|
"Skill(iwsdk-physics)",
|
|
17
18
|
"Skill(iwsdk-pwa-packaging)",
|
|
18
|
-
"Skill(iwsdk-dev)",
|
|
19
19
|
"Skill(iwsdk-ray)",
|
|
20
|
-
"Skill(iwsdk-ui)"
|
|
20
|
+
"Skill(iwsdk-ui)",
|
|
21
|
+
"Skill(iwsdk-upgrade)"
|
|
21
22
|
]
|
|
22
23
|
},
|
|
23
|
-
"enabledMcpjsonServers": [
|
|
24
|
+
"enabledMcpjsonServers": [
|
|
25
|
+
"iwsdk-runtime",
|
|
26
|
+
"iwsdk-reference",
|
|
27
|
+
"metavr"
|
|
28
|
+
]
|
|
24
29
|
}
|
|
@@ -309,3 +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) -->
|
|
@@ -122,8 +122,8 @@ npx @iwsdk/cli scene state --raw
|
|
|
122
122
|
`iwsdk dev up` starts the server in the background and launches the configured
|
|
123
123
|
managed editor browser. It can return while that browser is still starting; use
|
|
124
124
|
`iwsdk runtime wait` or inspect `iwsdk runtime status` before browser-backed
|
|
125
|
-
commands.
|
|
126
|
-
startup workaround.
|
|
125
|
+
commands. Pass the `--ai-mode` that AGENTS.md's session rule picks; do not edit
|
|
126
|
+
`vite.config.ts` to change browser mode as an ad hoc startup workaround.
|
|
127
127
|
|
|
128
128
|
`scene_render_file` renders a file without replacing the editor's active document,
|
|
129
129
|
but it still uses the managed editor browser for manifest evaluation and WebGL.
|
|
@@ -274,3 +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) -->
|
|
@@ -71,3 +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) -->
|
package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-depth-occlusion/SKILL.md
RENAMED
|
@@ -85,3 +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) -->
|
|
@@ -43,3 +43,4 @@ Observable workspace state wins over wording:
|
|
|
43
43
|
|
|
44
44
|
iwsdk-dev does not add another implementation phase. The selected playbook owns
|
|
45
45
|
the work, evidence budget, specialist routing, verification, and stopping rule.
|
|
46
|
+
<!-- iwsdk-agent-guidance version=1.2.0-rc.0 sha256=07f4648993de9020eb6eee38c94ad442ac6b1ca8ede99e4d369de20e60e3af2f name=iwsdk-dev (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->
|
|
@@ -1387,6 +1387,12 @@ const texture = AssetManager.getTexture('myTexture');
|
|
|
1387
1387
|
const audio = AssetManager.getAudio('mySound');
|
|
1388
1388
|
```
|
|
1389
1389
|
|
|
1390
|
+
**Render loop (headless automation):** `world.renderMode` is `'continuous'`
|
|
1391
|
+
(default) or `'on-demand'`. On demand, systems still run every frame but only
|
|
1392
|
+
frames asked for are drawn: `await world.requestRender(frames)` or
|
|
1393
|
+
`const release = world.holdRender()` (draw every frame until `release()`).
|
|
1394
|
+
Headless dev sessions switch it on for you; shipped apps keep `'continuous'`.
|
|
1395
|
+
|
|
1390
1396
|
**Runtime loading (on-demand):**
|
|
1391
1397
|
|
|
1392
1398
|
```typescript
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# Headless rendering (no GPU)
|
|
2
|
+
|
|
3
|
+
Read this when the managed session is headless (`--ai-mode agent` or
|
|
4
|
+
`--headless`), the host has no GPU, or a result depends on frame rate, frame
|
|
5
|
+
timing, or which frame a screenshot shows.
|
|
6
|
+
|
|
7
|
+
## What headless sessions do
|
|
8
|
+
|
|
9
|
+
A headless managed session renders **on demand**. Every ECS system, input,
|
|
10
|
+
physics and UI update still runs on every frame, but the app draws a frame only
|
|
11
|
+
when a tool needs pixels. Without a GPU every draw is software-rasterized, so
|
|
12
|
+
this keeps the app at the browser's frame rate (60 fps) instead of a few frames
|
|
13
|
+
per second.
|
|
14
|
+
|
|
15
|
+
- `browser screenshot` draws a fresh frame first. Screenshots always show the
|
|
16
|
+
current state, in the browser view and in XR. In emulated AR, the synthetic
|
|
17
|
+
room behind the app draws with it, so the two always match.
|
|
18
|
+
- `scene render-stats` draws one fresh frame before it reads the stats.
|
|
19
|
+
`browser profile`, runtime evidence and `browser run` scripts draw every
|
|
20
|
+
frame while they run.
|
|
21
|
+
- Headed sessions, including collaborate mode, always draw every frame.
|
|
22
|
+
- To draw every frame in a headless session, start it with
|
|
23
|
+
`IWSDK_DEV_RENDER_MODE=continuous`.
|
|
24
|
+
|
|
25
|
+
## Check state, then look
|
|
26
|
+
|
|
27
|
+
Prove behavior with ECS state (`ecs query`, `ecs find`, `ecs snapshot`,
|
|
28
|
+
`ecs diff`). These need no pixels and see every frame. Take a screenshot only
|
|
29
|
+
for visual claims.
|
|
30
|
+
|
|
31
|
+
## Capture an exact frame
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
npx @iwsdk/cli ecs pause --input-json '{}'
|
|
35
|
+
npx @iwsdk/cli ecs step --input-json '{"count":1}'
|
|
36
|
+
npx @iwsdk/cli browser screenshot --input-json '{}' --output-file artifacts/frame.png
|
|
37
|
+
npx @iwsdk/cli ecs resume --input-json '{}'
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
A screenshot draws without advancing the simulation, so it shows exactly the
|
|
41
|
+
paused frame.
|
|
42
|
+
|
|
43
|
+
To see motion, capture a filmstrip: exact simulation frames at offsets 0, K,
|
|
44
|
+
2K, … in one contact-sheet image.
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
npx @iwsdk/cli browser filmstrip --count 6 --every 5 --output-file artifacts/fall.png
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Switch the render mode at runtime
|
|
51
|
+
|
|
52
|
+
The `RuntimeSettings` component controls the render mode. It exists only at
|
|
53
|
+
runtime and is never saved into scene files.
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
npx @iwsdk/cli ecs find --input-json '{"withComponents":["RuntimeSettings"]}'
|
|
57
|
+
npx @iwsdk/cli ecs set-component --input-json '{"entityIndex":<index>,"componentId":"RuntimeSettings","field":"renderMode","value":"continuous"}'
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Without a GPU, continuous drawing drops the app to a few frames per second, so
|
|
61
|
+
set it back to `"on-demand"` when done.
|
|
62
|
+
|
|
63
|
+
## Do not
|
|
64
|
+
|
|
65
|
+
- Judge performance from headless frame rates. Profile instead, which draws
|
|
66
|
+
every frame while it runs, or measure on a device:
|
|
67
|
+
`npx @iwsdk/cli browser profile --input-json '{"action":"start","mode":"rendering"}'`,
|
|
68
|
+
exercise the scene, then
|
|
69
|
+
`npx @iwsdk/cli browser profile --input-json '{"action":"stop"}'`.
|
|
70
|
+
- Expect a frame to change between screenshots if the scene did not change.
|
|
71
|
+
- Restart into headed mode to "fix" a stale view; screenshots already draw a
|
|
72
|
+
fresh frame.
|
|
73
|
+
|
|
74
|
+
## Limits
|
|
75
|
+
|
|
76
|
+
- App code that reads pixels from the canvas itself (for example
|
|
77
|
+
`canvas.toDataURL()`) must draw and read in the same task (call
|
|
78
|
+
`renderer.render()`, then read), or create the renderer with
|
|
79
|
+
`preserveDrawingBuffer: true`. `await world.requestRender()` resolves after
|
|
80
|
+
the frame is presented, when the drawing buffer may already be cleared. See
|
|
81
|
+
the render loop API: `world.renderMode`, `world.requestRender(frames)` and
|
|
82
|
+
`world.holdRender()`.
|
package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-dev/references/iterate.md
RENAMED
|
@@ -87,11 +87,16 @@ the output bounded. The existing scaffold rules are already in context:
|
|
|
87
87
|
3. Implement the smallest complete vertical delta, including state/UI feedback
|
|
88
88
|
and recovery when the request needs them.
|
|
89
89
|
4. Run one batched typecheck and fix errors together.
|
|
90
|
-
5. Start the managed runtime directly
|
|
91
|
-
`npx @iwsdk/cli dev up --
|
|
90
|
+
5. Start the managed runtime directly in the mode AGENTS.md's session rule
|
|
91
|
+
picks: `npx @iwsdk/cli dev up --ai-mode agent --timeout 45000`, or
|
|
92
|
+
`--ai-mode collaborate` when the user is watching. Headless sessions draw
|
|
93
|
+
only when a tool needs pixels; read references/headless-rendering.md before
|
|
94
|
+
relying on frame rate, frame timing, or which frame a screenshot shows.
|
|
92
95
|
6. Exercise the changed path with real user input and query only the named state
|
|
93
96
|
needed to prove it. Direct ECS mutation may prepare/reset a scenario but is
|
|
94
|
-
not interaction proof.
|
|
97
|
+
not interaction proof. If the state you need to prepare lives in a plain
|
|
98
|
+
object outside ECS, move it into a component as part of the change rather
|
|
99
|
+
than editing constants temporarily or enabling browser automation.
|
|
95
100
|
7. Run one focused regression smoke for the preserved behavior most likely to
|
|
96
101
|
have been affected.
|
|
97
102
|
8. Run the production build and stop.
|
|
@@ -150,13 +155,13 @@ npx @iwsdk/cli xr run-sequence --input-json '{"device":"hand-right","steps":[{"p
|
|
|
150
155
|
```
|
|
151
156
|
|
|
152
157
|
Query `Grabbed` between the grab and the release. A press result whose
|
|
153
|
-
`presses[0].contactMs` is 800 or more did not click.
|
|
158
|
+
`presses[0].contactMs` is 800 or more did not click. A stalled frame can
|
|
154
159
|
stretch a press that far, so run that press once more before changing code.
|
|
155
160
|
|
|
156
161
|
If a scene/source/UI edit happens after the managed runtime started and live
|
|
157
162
|
state becomes stale, do not call `scene open`, repeatedly poll `dev status`, or
|
|
158
163
|
loop on browser reload. Run one
|
|
159
|
-
`npx @iwsdk/cli dev restart --
|
|
164
|
+
`npx @iwsdk/cli dev restart --ai-mode <the session's current mode> --timeout 60000`, then resume the named-state
|
|
160
165
|
check. One failed restart may be diagnosed once; do not enter a recovery loop.
|
|
161
166
|
|
|
162
167
|
Do not perform a full product replay when the edit affects one bounded path.
|