@iwsdk/cli 1.1.0-rc.2 → 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 +79 -2
- package/dist/agent-adapters.d.ts +12 -1
- package/dist/agent-adapters.d.ts.map +1 -1
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +312 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +277 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +74 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +46 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +1531 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +263 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/planner.md +307 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +282 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +75 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +178 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +262 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +106 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/component-reference.md +152 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +70 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +328 -0
- package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +521 -0
- package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +60 -0
- package/dist/agent-guidance/files/.claude/rules/ecs-api.md +103 -0
- package/dist/agent-guidance/files/.claude/rules/scene-json.md +72 -0
- package/dist/agent-guidance/files/.claude/rules/uikitml.md +66 -0
- package/dist/agent-guidance/files/.claude/settings.json +29 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +312 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +277 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +74 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +46 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +1531 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +82 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +263 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/planner.md +307 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +282 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +75 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +178 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +262 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +106 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/component-reference.md +152 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +101 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +219 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +70 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +328 -0
- package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
- package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +62 -0
- package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +105 -0
- package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +74 -0
- package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +68 -0
- package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +55 -0
- package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +101 -0
- package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +71 -0
- package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +65 -0
- package/{guidance → dist/agent-guidance/files}/AGENTS.md +107 -27
- package/dist/agent-guidance/files/CLAUDE.md +3 -0
- package/dist/agent-guidance/files/public/scenes/AGENTS.md +72 -0
- package/dist/agent-guidance/files/public/ui/AGENTS.md +66 -0
- package/dist/agent-guidance/files/src/AGENTS.md +153 -0
- package/dist/agent-guidance/manifest.json +854 -0
- package/dist/agent-guidance.d.ts +113 -0
- package/dist/agent-guidance.d.ts.map +1 -0
- package/dist/agent-guidance.js +3403 -0
- package/dist/agent-guidance.js.map +1 -0
- package/dist/cli.js +2407 -144
- package/dist/cli.js.map +1 -1
- package/dist/commands/adapter.d.ts +1 -0
- package/dist/commands/adapter.d.ts.map +1 -1
- package/dist/commands/agents.d.ts +11 -0
- package/dist/commands/agents.d.ts.map +1 -0
- package/dist/commands/browser.d.ts +11 -0
- package/dist/commands/browser.d.ts.map +1 -1
- package/dist/commands/dev.d.ts +1 -0
- package/dist/commands/dev.d.ts.map +1 -1
- package/dist/commands/reference.d.ts +15 -1
- package/dist/commands/reference.d.ts.map +1 -1
- package/dist/commands/runtime.d.ts.map +1 -1
- package/dist/commands/upgrade.d.ts +51 -0
- package/dist/commands/upgrade.d.ts.map +1 -0
- package/dist/contract.js +32 -0
- package/dist/contract.js.map +1 -1
- package/dist/guidance-refresh.d.ts +33 -0
- package/dist/guidance-refresh.d.ts.map +1 -0
- package/dist/help.d.ts +2 -0
- package/dist/help.d.ts.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4744 -135
- package/dist/index.js.map +1 -1
- package/dist/mcp-stdio.d.ts.map +1 -1
- package/dist/migrations/iwsdk-migrate-0-5/SKILL.md +413 -0
- package/dist/migrations.d.ts +36 -0
- package/dist/migrations.d.ts.map +1 -0
- package/dist/package-manager.d.ts +28 -0
- package/dist/package-manager.d.ts.map +1 -0
- package/dist/release-notes.d.ts +28 -0
- package/dist/release-notes.d.ts.map +1 -0
- package/dist/release-notes.json +1374 -0
- package/dist/runtime-contract.d.ts +8 -0
- package/dist/runtime-contract.d.ts.map +1 -1
- package/dist/runtime-telemetry.d.ts +8 -1
- package/dist/runtime-telemetry.d.ts.map +1 -1
- package/dist/version.d.ts +1 -1
- package/package.json +9 -3
|
@@ -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()`.
|
|
@@ -0,0 +1,263 @@
|
|
|
1
|
+
# Iterate path
|
|
2
|
+
|
|
3
|
+
Make the requested delta to the established app without reopening its product
|
|
4
|
+
definition. The existing working experience is the baseline and the requested
|
|
5
|
+
change is the scope boundary.
|
|
6
|
+
|
|
7
|
+
## Fast opening
|
|
8
|
+
|
|
9
|
+
To keep a bounded edit from turning into rediscovery, begin in this order:
|
|
10
|
+
|
|
11
|
+
1. Run the bounded source/scene/UI Bash command below.
|
|
12
|
+
2. Make a Write/Edit under `src/` or `public/` based only on that bundle. A
|
|
13
|
+
small safe skeleton such as the requested component or UI asset is enough;
|
|
14
|
+
finish it after typecheck if an API detail remains uncertain.
|
|
15
|
+
|
|
16
|
+
When the request names a state or component, prefer writing that exact
|
|
17
|
+
createComponent skeleton as the opening edit. Scene and UI schema details need
|
|
18
|
+
not block a safe scalar-state skeleton; let the first typecheck surface a real
|
|
19
|
+
API question. Do not reread root guidance or enumerate rule, skill, dependency,
|
|
20
|
+
or node_modules trees before the edit. If the harness did not automatically
|
|
21
|
+
load an applicable path-scoped instruction, include only that one instruction
|
|
22
|
+
in the bounded opening bundle. Preserve any authored view already present.
|
|
23
|
+
|
|
24
|
+
Do not insert unrelated discovery, CLI help, another skill, or broad reference
|
|
25
|
+
lookup between the bounded inspection and the first edit.
|
|
26
|
+
|
|
27
|
+
## Operating contract
|
|
28
|
+
|
|
29
|
+
- Do not create an experience brief, product plan, architecture document,
|
|
30
|
+
retrospective, or review artifact unless the user explicitly requests it.
|
|
31
|
+
- Preserve existing scene anchors, interactions, state, UI, visual language,
|
|
32
|
+
and behavior outside the requested delta. Do not replace the app with a new
|
|
33
|
+
concept or rebuild working systems for stylistic consistency.
|
|
34
|
+
- Inspect the smallest source/scene/UI bundle that establishes the affected
|
|
35
|
+
path and its immediate dependencies in one bounded shell call, then make the
|
|
36
|
+
mandatory opening edit before any additional discovery.
|
|
37
|
+
- Record the acceptance contract mentally or in the active response: requested
|
|
38
|
+
behavior, preserved behavior, observable state, and visual consequence. Do
|
|
39
|
+
not write a process document.
|
|
40
|
+
- Reuse the app's existing component, system, asset, naming, and UI patterns.
|
|
41
|
+
Introduce a new abstraction only when the requested change cannot fit the
|
|
42
|
+
current structure cleanly.
|
|
43
|
+
- Treat preserved ScreenSpace UI as occupying its authored transform in
|
|
44
|
+
immersive mode even when its browser presentation differs. Reuse established
|
|
45
|
+
panel scale and spacing. For the stock scaffold layout, a new front-facing
|
|
46
|
+
panel in the same horizontal band should start at 0.25-0.32 scale, at least
|
|
47
|
+
0.75 world meters above the preserved panel center, and at the same or greater
|
|
48
|
+
depth. Keep that separation during corrections; move laterally into clear
|
|
49
|
+
space rather than lowering it into the object interaction band.
|
|
50
|
+
- Invoke `iwsdk-build-model` before materially changing a model and
|
|
51
|
+
`iwsdk-compose-scene` before changing scene placement, lighting, environment,
|
|
52
|
+
or cameras. Invoke other matching specialists only after a concrete uncertainty
|
|
53
|
+
or the first failed required interaction. After that first failure, do not sweep
|
|
54
|
+
coordinates, read screenshots for interaction debugging, or inspect pointer,
|
|
55
|
+
input, grab, ray, or UIKit internals in `node_modules`; use the specialist and
|
|
56
|
+
measured ECS/UI state.
|
|
57
|
+
- Before the first typecheck, do not read specialist references or inspect
|
|
58
|
+
`node_modules`. Import IWSDK ECS, UIKit, interaction, material, and Three.js
|
|
59
|
+
re-exports from `@iwsdk/core`; use
|
|
60
|
+
`createComponent('Name', {field: {type: Types.Int8, default: 0}})` directly.
|
|
61
|
+
Let `npm run --if-present typecheck` produce the exact remaining API question.
|
|
62
|
+
|
|
63
|
+
Use this opening command shape directly, tolerating missing paths and keeping
|
|
64
|
+
the output bounded. The existing scaffold rules are already in context:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
{
|
|
68
|
+
for f in iwsdk.config.json package.json \
|
|
69
|
+
$(find src -maxdepth 2 -type f \
|
|
70
|
+
\( -name '*.ts' -o -name '*.tsx' \) 2>/dev/null | sort) \
|
|
71
|
+
$(find public/ui -maxdepth 2 -type f \
|
|
72
|
+
\( -name '*.uikitml' -o -name '*.json' \) 2>/dev/null | sort) \
|
|
73
|
+
$(find public/scenes -maxdepth 2 -type f \
|
|
74
|
+
-name '*.json' 2>/dev/null | sort); do
|
|
75
|
+
if [ -f "$f" ]; then
|
|
76
|
+
echo "=== $f ==="
|
|
77
|
+
sed -n '1,220p' "$f"
|
|
78
|
+
fi
|
|
79
|
+
done
|
|
80
|
+
} | head -c 32000
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## Implementation loop
|
|
84
|
+
|
|
85
|
+
1. Inspect the affected files plus the active scene and UI in one bounded call.
|
|
86
|
+
2. Identify the current behavior that must remain unchanged.
|
|
87
|
+
3. Implement the smallest complete vertical delta, including state/UI feedback
|
|
88
|
+
and recovery when the request needs them.
|
|
89
|
+
4. Run one batched typecheck and fix errors together.
|
|
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.
|
|
95
|
+
6. Exercise the changed path with real user input and query only the named state
|
|
96
|
+
needed to prove it. Direct ECS mutation may prepare/reset a scenario but is
|
|
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.
|
|
100
|
+
7. Run one focused regression smoke for the preserved behavior most likely to
|
|
101
|
+
have been affected.
|
|
102
|
+
8. Run the production build and stop.
|
|
103
|
+
|
|
104
|
+
Use the known CLI surface without help discovery: `xr status|enter|look-at|select`,
|
|
105
|
+
`ecs find|query`, `browser screenshot`, and `scene render-file`. These call
|
|
106
|
+
shapes are authoritative; substitute the requested target, entity index, and
|
|
107
|
+
artifact name instead of running family-level or subcommand `--help`:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
npx @iwsdk/cli xr enter --input-json '{}'
|
|
111
|
+
npx @iwsdk/cli xr look-at --input-json '{"device":"controller-right","target":{"x":0,"y":1.5,"z":-2}}'
|
|
112
|
+
npx @iwsdk/cli xr select --input-json '{"device":"controller-right","duration":0.2}'
|
|
113
|
+
npx @iwsdk/cli ecs find --input-json '{"namePattern":"Requested Name","limit":10}'
|
|
114
|
+
npx @iwsdk/cli ecs query --input-json '{"entityIndex":1,"components":["RequestedState"]}'
|
|
115
|
+
npx @iwsdk/cli browser screenshot --input-json '{}' --output-file artifacts/final.png
|
|
116
|
+
npx @iwsdk/cli scene render-file --input-json '{"path":"public/scenes/main.iwsdk.scene.json","viewId":"hero","width":800,"height":800}' --output-file artifacts/hero.png
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
After `dev up`, target at most 32 Bash calls for all interaction and visual
|
|
120
|
+
verification. Batch each look-at, input, and state query into one shell call.
|
|
121
|
+
Run the full end-to-end sequence once; after a measured failure, patch the
|
|
122
|
+
cause and rerun only the affected path.
|
|
123
|
+
|
|
124
|
+
## Efficiency budget
|
|
125
|
+
|
|
126
|
+
Treat 90 total tool calls, 36 shell calls after dev startup, two image
|
|
127
|
+
previews, two runtime restarts, and two authored-scene renders as default upper
|
|
128
|
+
bounds for a bounded edit. Avoid CLI help calls when the known command shapes
|
|
129
|
+
below apply. These guardrails prevent verification from becoming open-ended;
|
|
130
|
+
they do not justify omitting required acceptance evidence.
|
|
131
|
+
|
|
132
|
+
At roughly 70 tool calls, drop optional diagnostics and finish only missing
|
|
133
|
+
evidence. At 80, freeze optional polish, save required artifacts once, run the
|
|
134
|
+
production build, and close the task.
|
|
135
|
+
|
|
136
|
+
For
|
|
137
|
+
`DistanceGrabbable`, hold/release gamepad button index `0`; for proximity
|
|
138
|
+
`OneHandGrabbable`/`TwoHandsGrabbable`, use squeeze button index `1`.
|
|
139
|
+
The focused distance-grab smoke is not another `xr select`: aim at the preserved
|
|
140
|
+
object, run
|
|
141
|
+
`npx @iwsdk/cli xr set-gamepad-state --input-json '{"device":"controller-right","buttons":[{"index":0,"value":1}]}'`,
|
|
142
|
+
observe `Grabbed` or movement, then repeat with `value:0` to release.
|
|
143
|
+
|
|
144
|
+
For hand input (poke, pinch-grab, gestures), switch with
|
|
145
|
+
`xr set-input-mode` `{"mode":"hand"}` and drive the hand by target name with one
|
|
146
|
+
`xr run-sequence` per interaction (`--timeout 45000`). `xr list-targets` names
|
|
147
|
+
the interactable entities and their UIKitML element IDs. Press a button with
|
|
148
|
+
`press`, never a pinch; a near grab needs `grabbing.useHandPinchForGrab` (on by
|
|
149
|
+
default):
|
|
150
|
+
|
|
151
|
+
```bash
|
|
152
|
+
npx @iwsdk/cli xr run-sequence --input-json '{"device":"hand-right","steps":[{"target":"Btn_Action","press":{}}]}' --timeout 45000
|
|
153
|
+
npx @iwsdk/cli xr run-sequence --input-json '{"device":"hand-right","steps":[{"target":"Requested Name","approach":{"distance":0.06},"pinch":{"value":1,"at":"arrival"}},{"position":{"x":0,"y":1,"z":-0.5},"depart":{"distance":0.08}}]}' --timeout 45000
|
|
154
|
+
npx @iwsdk/cli xr run-sequence --input-json '{"device":"hand-right","steps":[{"pinch":0,"duration":0.15}]}'
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Query `Grabbed` between the grab and the release. A press result whose
|
|
158
|
+
`presses[0].contactMs` is 800 or more did not click. A stalled frame can
|
|
159
|
+
stretch a press that far, so run that press once more before changing code.
|
|
160
|
+
|
|
161
|
+
If a scene/source/UI edit happens after the managed runtime started and live
|
|
162
|
+
state becomes stale, do not call `scene open`, repeatedly poll `dev status`, or
|
|
163
|
+
loop on browser reload. Run one
|
|
164
|
+
`npx @iwsdk/cli dev restart --ai-mode <the session's current mode> --timeout 60000`, then resume the named-state
|
|
165
|
+
check. One failed restart may be diagnosed once; do not enter a recovery loop.
|
|
166
|
+
|
|
167
|
+
Do not perform a full product replay when the edit affects one bounded path.
|
|
168
|
+
Expand verification only when a measured failure shows broader impact.
|
|
169
|
+
|
|
170
|
+
## Visual comparison
|
|
171
|
+
|
|
172
|
+
Use the supplied pre-edit baseline when present. Pixel reads have a hard ceiling
|
|
173
|
+
of two: one bounded baseline or final comparison and one replacement after a
|
|
174
|
+
focused correction. Never read aim, hover, panel, coordinate, or duplicate debug
|
|
175
|
+
screenshots. Debug interactions with state, not pixels.
|
|
176
|
+
|
|
177
|
+
Never load a full-resolution PNG into model context. Preserve deliverable
|
|
178
|
+
images unchanged, but create a temporary JPEG preview no wider than 600 pixels
|
|
179
|
+
at about 70% quality with an image tool already available in the environment.
|
|
180
|
+
Do not install a dependency only to resize evidence, and delete the temporary
|
|
181
|
+
preview after the visual decision.
|
|
182
|
+
|
|
183
|
+
Do not use repeated `scene render-file` calls to discover framing. When an
|
|
184
|
+
authored hero view must be checked, run it once and read
|
|
185
|
+
`data.result.renderStats.visibleNodeIds`; make at most one focused camera or
|
|
186
|
+
composition correction from that result. The second render is the final hero
|
|
187
|
+
attempt even if it fails; do not issue a third `scene render-file` call.
|
|
188
|
+
|
|
189
|
+
Do not reconcile hero and default-player framing with trigonometry, coordinate
|
|
190
|
+
sweeps, repeated screenshots, or browser logs. Keep the panel identity-rotated
|
|
191
|
+
for the player. If the one hero check misses it, move only the existing hero
|
|
192
|
+
camera to the same side of the panel as the default player, check once more,
|
|
193
|
+
and freeze. Inspect browser logs at most once and only after a command returns
|
|
194
|
+
an explicit runtime error; never create a log-debugging loop.
|
|
195
|
+
|
|
196
|
+
Preserve the existing composition and visual language unless the request asks
|
|
197
|
+
to change them. When it does, compare the same viewpoint before and after and
|
|
198
|
+
make one focused correction for clipping, legibility, contrast, or hierarchy.
|
|
199
|
+
When adding a new primary spatial panel, it must be readable at the default
|
|
200
|
+
runtime viewpoint rather than a tiny accessory: keep its visible bounds at
|
|
201
|
+
least roughly 12% of frame width and 8% of frame height, but normally below 70%
|
|
202
|
+
of frame width and 40% of frame height, while staying fully inside the frame.
|
|
203
|
+
It must not cover the preserved product primary object, existing primary UI,
|
|
204
|
+
or focused regression object. Readability alone is insufficient: visible
|
|
205
|
+
bounds must not touch or overlap. Leave roughly 3% of the frame as clear
|
|
206
|
+
separation. If the first preview shows contact, move the new panel into the
|
|
207
|
+
largest empty region above or beside the preserved composition.
|
|
208
|
+
|
|
209
|
+
Use an opaque or strongly contrasting panel surface. Primary copy must be dark
|
|
210
|
+
on light or light on dark; white or pale text on translucent white, sky, or
|
|
211
|
+
another bright background fails even when the glyphs are technically present.
|
|
212
|
+
For the scaffold's Horizon `<Panel>`, assume the kit's opaque surface wins
|
|
213
|
+
over a custom root `background-color`. That surface follows the color scheme:
|
|
214
|
+
the runtime renders it dark because `iwsdk.config.json` prefers `dark`, while
|
|
215
|
+
editor previews render it white. Give every text class a dark color plus a light
|
|
216
|
+
`:dark` variant, as `public/ui/welcome.uikitml` does, so copy reads on both.
|
|
217
|
+
Do not spend a restart discovering dark-on-dark or white-on-white text that the
|
|
218
|
+
stock kit behavior already predicts.
|
|
219
|
+
|
|
220
|
+
Reuse the established app panel scale and spacing when available. In the stock
|
|
221
|
+
starter-scale composition, a new front-facing UIKitML panel should begin at
|
|
222
|
+
0.25-0.32 scale. If it shares the central horizontal band, place its center at
|
|
223
|
+
least 0.75 world meters above the preserved panel and at the same or greater
|
|
224
|
+
depth; side-by-side placement needs a clear gap beyond both half-widths. Keep
|
|
225
|
+
that separation through the one allowed correction.
|
|
226
|
+
|
|
227
|
+
On the first final preview, inspect the whole change together: new UI is fully
|
|
228
|
+
inside the frame; a visible gap separates it from existing primary UI and
|
|
229
|
+
objects; important copy and controls remain readable at preview size; and text
|
|
230
|
+
has strong contrast against its actual rendered surface. Batch one correction
|
|
231
|
+
for all failures, then take the second and final preview.
|
|
232
|
+
|
|
233
|
+
Keep primary added UI away from fragile frame edges unless the established
|
|
234
|
+
composition reserves a stable edge region. XR captures may use a square or
|
|
235
|
+
otherwise narrower aspect ratio than the browser. Prefer an above-central
|
|
236
|
+
placement over pushing a panel to the side, and retain a generous lateral
|
|
237
|
+
margin before accepting the final preview.
|
|
238
|
+
|
|
239
|
+
Progress and completion evidence must remain distinguishable at the compact
|
|
240
|
+
600-pixel preview scale. Do not rely on changing only one short status sentence.
|
|
241
|
+
Use one coarse, deliberate milestone change such as a large status chip or bar,
|
|
242
|
+
clearly marked step indicators, or a strong color/state change on both the
|
|
243
|
+
panel and the affected object. The changed treatment should occupy a visible
|
|
244
|
+
region of the panel and make completion obvious without reading fine print.
|
|
245
|
+
|
|
246
|
+
For a front-facing UIKitML panel in the stock starter layout, keep rotationDeg
|
|
247
|
+
absent unless the existing app establishes another convention. Do not calculate
|
|
248
|
+
a look-at yaw solely to face the default player: the stock panel front is
|
|
249
|
+
face-on at identity. Judge the final result from a fresh default runtime
|
|
250
|
+
viewpoint, without custom headset repositioning before capture.
|
|
251
|
+
|
|
252
|
+
For XR work, keep the immersive session active through the final browser
|
|
253
|
+
screenshot. Immediately before capture, check XR status and enter once if the
|
|
254
|
+
session is inactive. A non-immersive browser camera is not placement evidence
|
|
255
|
+
for world-space UI; return to the default immersive viewpoint instead of moving
|
|
256
|
+
correctly placed content to satisfy the unrelated browser view.
|
|
257
|
+
|
|
258
|
+
## Stop rule
|
|
259
|
+
|
|
260
|
+
Stop when the requested delta works through real input, the named state/UI
|
|
261
|
+
evidence passes, the focused preserved-path smoke passes, the production build
|
|
262
|
+
passes, and required evidence files exist. Do not reopen unrelated polish or
|
|
263
|
+
review after those gates pass.
|
|
@@ -0,0 +1,307 @@
|
|
|
1
|
+
# Planner path
|
|
2
|
+
|
|
3
|
+
Deliver the requested experience with the smallest reliable loop. Preserve the
|
|
4
|
+
user's exact observable contract, use IWSDK-native workflows, verify the real
|
|
5
|
+
runtime, and stop when the contract is proven.
|
|
6
|
+
|
|
7
|
+
## Default operating mode
|
|
8
|
+
|
|
9
|
+
- Work autonomously when the task is already specific. Do not pause for design
|
|
10
|
+
approval unless a missing choice materially changes the product.
|
|
11
|
+
- Keep one compact plan in the conversation or task list. Do not create
|
|
12
|
+
`design/`, pipeline-state, deck, concept-art, architecture, verification, or
|
|
13
|
+
retrospective files unless the user explicitly requests them.
|
|
14
|
+
- Do not scaffold a nested app. Treat the generated project in the working
|
|
15
|
+
directory as the starting point.
|
|
16
|
+
- Do not run an untouched-scaffold demo. Inspect the generated project briefly
|
|
17
|
+
and begin the requested implementation.
|
|
18
|
+
- Use subagents only for genuinely independent work that saves wall time. Do
|
|
19
|
+
not spawn a planner, documentation, or review subagent by default.
|
|
20
|
+
|
|
21
|
+
## 1. Extract the executable contract
|
|
22
|
+
|
|
23
|
+
Before editing, reduce the prompt to a short checklist:
|
|
24
|
+
|
|
25
|
+
1. exact files, scene node IDs, UIKit element IDs, component names, and fields;
|
|
26
|
+
2. explicit initial values and state transitions;
|
|
27
|
+
3. interaction paths that must work in the live app;
|
|
28
|
+
4. visible states and required framing/legibility;
|
|
29
|
+
5. build and runtime evidence needed before stopping.
|
|
30
|
+
|
|
31
|
+
Treat exact values as data, not implications. If a required field value equals
|
|
32
|
+
the component default, still serialize it explicitly in authored scene data.
|
|
33
|
+
For example, a required profile `A` must be written as `profileId: "A"`, not
|
|
34
|
+
left implicit because `A` is the schema default.
|
|
35
|
+
|
|
36
|
+
When the prompt names live runtime objects, assign those runtime `.name`
|
|
37
|
+
values exactly during initialization and verify them in the runtime hierarchy.
|
|
38
|
+
UIKit element IDs alone do not satisfy a runtime-name requirement.
|
|
39
|
+
|
|
40
|
+
## 2. Inspect once, then ground only uncertainty
|
|
41
|
+
|
|
42
|
+
Read the existing entry point, project config, asset/component registries,
|
|
43
|
+
scene, and relevant scoped rules. Use precise `npx @iwsdk/cli reference` queries
|
|
44
|
+
only for APIs or file formats that are genuinely uncertain.
|
|
45
|
+
|
|
46
|
+
Convert FBX, OBJ, and other source model formats before registering them: in
|
|
47
|
+
Blender use **File → Import**, then **File → Export → glTF 2.0**, and add the
|
|
48
|
+
resulting GLB/GLTF to the asset manifest.
|
|
49
|
+
|
|
50
|
+
For a fresh scaffold that needs native scene composition and UIKitML, use this
|
|
51
|
+
exact fast path before broad discovery:
|
|
52
|
+
|
|
53
|
+
1. read the applicable scoped `AGENTS.md`, then exactly these scaffold rules
|
|
54
|
+
when present: `.claude/rules/scene-json.md`, `ecs-api.md`, `uikitml.md`, and
|
|
55
|
+
`assets-and-manifest.md`; do not list directories first;
|
|
56
|
+
2. in one bounded shell call, print `package.json`, `iwsdk.config.json`, the
|
|
57
|
+
small scaffold `src/*.ts` files, the authored scene JSON, and UIKitML;
|
|
58
|
+
3. use `iwsdk-build-model` for every new or materially changed model, then use
|
|
59
|
+
`iwsdk-compose-scene` for scene placement, lighting, environment, and cameras;
|
|
60
|
+
load `iwsdk-ui/SKILL.md` only when UIKitML is part of the request;
|
|
61
|
+
4. create or replace the first implementation files immediately, then let
|
|
62
|
+
typecheck/runtime errors identify any
|
|
63
|
+
additional API question.
|
|
64
|
+
|
|
65
|
+
The first edit is a checkpoint: reach it within 8 tool calls after loading this
|
|
66
|
+
playbook. Do not inspect generated declarations, search node_modules, or invoke
|
|
67
|
+
another specialist before it. If one framework boundary remains unclear, write
|
|
68
|
+
the straightforward typed slice, run npm run --if-present typecheck, and investigate only the
|
|
69
|
+
concrete compiler error. After the focused references, edit before optional
|
|
70
|
+
lookup.
|
|
71
|
+
|
|
72
|
+
For the bounded scaffold read, prefer one command shaped like this over a
|
|
73
|
+
series of individual reads (adjust globs only when the project differs):
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
for f in package.json iwsdk.config.json src/*.ts public/scenes/*.json public/ui/*.uikitml; do
|
|
77
|
+
echo "--- $f"; sed -n '1,260p' "$f"
|
|
78
|
+
done
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
For a compact greenfield scene, keep the default player spawn unless the prompt
|
|
82
|
+
explicitly requires another spawn. Do not inspect schemas to add an optional
|
|
83
|
+
`player` block. Keep the standing volume around the origin clear, place the
|
|
84
|
+
experience in front of it (normally negative Z), and use this document shape:
|
|
85
|
+
|
|
86
|
+
```json
|
|
87
|
+
{
|
|
88
|
+
"version": "iwsdk.scene.v1",
|
|
89
|
+
"units": "meters",
|
|
90
|
+
"components": {},
|
|
91
|
+
"resources": {},
|
|
92
|
+
"nodes": [],
|
|
93
|
+
"authoring": { "views": [] }
|
|
94
|
+
}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Use these stable high-friction recipes directly; do not rediscover them in
|
|
98
|
+
`node_modules`:
|
|
99
|
+
|
|
100
|
+
```ts
|
|
101
|
+
const Profiles = { A: 'A', B: 'B', C: 'C' } as const;
|
|
102
|
+
const Example = createComponent('Example', {
|
|
103
|
+
profileId: { type: Types.Enum, default: Profiles.A, enum: Profiles },
|
|
104
|
+
occupant: { type: Types.Entity, default: null },
|
|
105
|
+
active: { type: Types.Boolean, default: false },
|
|
106
|
+
elapsed: { type: Types.Float32, default: 0 },
|
|
107
|
+
});
|
|
108
|
+
|
|
109
|
+
const panel = world.requireSceneObject<UIKitMLAsset>('ControlPanel');
|
|
110
|
+
const status = panel.requireElementById<UIKit.Text>('StatusText');
|
|
111
|
+
const button = panel.requireElementById('Btn_Action');
|
|
112
|
+
status.name = 'StatusText';
|
|
113
|
+
button.name = 'Btn_Action';
|
|
114
|
+
button.addEventListener('click', onAction);
|
|
115
|
+
cleanupFuncs.push(() => button.removeEventListener('click', onAction));
|
|
116
|
+
|
|
117
|
+
export class ExampleSystem extends createSystem({
|
|
118
|
+
examples: { required: [Example] },
|
|
119
|
+
held: { required: [Example, Grabbed] },
|
|
120
|
+
}) {
|
|
121
|
+
init(): void {
|
|
122
|
+
const onGrab = (entity: Entity) => entity.setValue(Example, 'active', true);
|
|
123
|
+
const onRelease = (entity: Entity) =>
|
|
124
|
+
entity.setValue(Example, 'active', false);
|
|
125
|
+
const offGrab = this.queries.held.subscribe('qualify', onGrab);
|
|
126
|
+
const offRelease = this.queries.held.subscribe('disqualify', onRelease);
|
|
127
|
+
this.cleanupFuncs.push(offGrab, offRelease);
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
update(delta: number): void {
|
|
131
|
+
for (const entity of this.queries.examples.entities) {
|
|
132
|
+
const active = entity.getValue(Example, 'active');
|
|
133
|
+
const elapsed = entity.getValue(Example, 'elapsed') ?? 0;
|
|
134
|
+
if (active) entity.setValue(Example, 'elapsed', elapsed + delta);
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
- Declare systems with `class X extends createSystem({ queryName: { required: [...] } })`.
|
|
141
|
+
Iterate `this.queries.queryName.entities`, and use
|
|
142
|
+
`entity.getValue(Component, field)` / `entity.setValue(Component, field, value)`.
|
|
143
|
+
Query `subscribe` returns an unsubscribe function for `cleanupFuncs`.
|
|
144
|
+
- Author an empty entity reference as `null` in scene JSON.
|
|
145
|
+
- Put `OneHandGrabbable` on authored nodes that need proximity grabbing. Treat
|
|
146
|
+
`Grabbed` as a runtime tag; use qualify/disqualify transitions for lifecycle
|
|
147
|
+
handling and `GrabSystem.forceRelease(entity)` for reset.
|
|
148
|
+
- When a slot accepts only one entity, guard against replacement: if its current
|
|
149
|
+
entity is non-null and differs from the released entity, leave both unchanged.
|
|
150
|
+
- Resolve authored entities and objects with `world.requireSceneEntity(nodeId)`
|
|
151
|
+
and `world.requireSceneObject(nodeId)`.
|
|
152
|
+
- Import ECS, UIKit, grab helpers, and Three.js runtime classes from
|
|
153
|
+
`@iwsdk/core`; IWSDK re-exports the supported runtime surface.
|
|
154
|
+
- For a live UIKit ray click, aim with `npx @iwsdk/cli xr look-at`, then use
|
|
155
|
+
`npx @iwsdk/cli xr select --input-json '{"device":"controller-right","duration":0.2}'`.
|
|
156
|
+
Do not rederive pointer internals or manually pulse select unless diagnosing
|
|
157
|
+
a concrete helper failure.
|
|
158
|
+
|
|
159
|
+
Avoid broad repeated discovery:
|
|
160
|
+
|
|
161
|
+
- do not enumerate the same command family or dependency tree multiple times;
|
|
162
|
+
- do not read generated bundles or large reference files when a focused API or
|
|
163
|
+
example query answers the question;
|
|
164
|
+
- do not repeat successful status, hierarchy, or capability probes without a
|
|
165
|
+
state change that requires it.
|
|
166
|
+
|
|
167
|
+
Specialist skills are optional focused references, not mandatory phases. Use
|
|
168
|
+
only the skills needed by the contract, normally at most once each:
|
|
169
|
+
|
|
170
|
+
- `iwsdk-build-model` for new or materially changed model geometry, materials,
|
|
171
|
+
hierarchy, or surface detail;
|
|
172
|
+
- `iwsdk-compose-scene` for scene JSON, placement, cross-asset contacts,
|
|
173
|
+
lighting, environment, or camera views after model work is complete;
|
|
174
|
+
- `iwsdk-ui` for UIKitML authoring or layout debugging;
|
|
175
|
+
- `iwsdk-grab` / `iwsdk-ray` for unfamiliar live interaction simulation;
|
|
176
|
+
- `iwsdk-debug` after a concrete runtime failure.
|
|
177
|
+
|
|
178
|
+
Pass a concise problem statement to a specialist. Do not paste the full user
|
|
179
|
+
prompt, ask it to run another end-to-end plan, or invoke overlapping skills for
|
|
180
|
+
the same question.
|
|
181
|
+
|
|
182
|
+
## 3. Implement one coherent vertical slice
|
|
183
|
+
|
|
184
|
+
Build the smallest structure that covers the whole contract:
|
|
185
|
+
|
|
186
|
+
1. native scene assets and deliberate hero/panel framing;
|
|
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;
|
|
190
|
+
3. interaction/state systems;
|
|
191
|
+
4. UIKitML and runtime control wiring;
|
|
192
|
+
5. visible state feedback.
|
|
193
|
+
|
|
194
|
+
Prefer IWSDK built-ins and project-local patterns. Keep systems small, register
|
|
195
|
+
cleanup functions, avoid per-frame allocation, and preserve feature-flag
|
|
196
|
+
prerequisites. Do not create process documents while code is incomplete.
|
|
197
|
+
|
|
198
|
+
Run `npm run --if-present typecheck` after the coherent slice exists, then fix errors in a
|
|
199
|
+
batch. Do not typecheck after every small edit. Run the production build near
|
|
200
|
+
the end and again only after a change that can affect it.
|
|
201
|
+
|
|
202
|
+
## 4. Verify the actual contract
|
|
203
|
+
|
|
204
|
+
Match verification depth to the app and its risk. A simple single-scene app
|
|
205
|
+
needs direct evidence for its few success criteria; multi-system behavior,
|
|
206
|
+
physics, deployment, and interactions with meaningful failure modes need
|
|
207
|
+
broader scenarios and stronger evidence.
|
|
208
|
+
|
|
209
|
+
After the coherent vertical slice typechecks, start one managed dev session
|
|
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
|
|
213
|
+
knowingly non-typechecking app. Exercise the real paths rather than inferring
|
|
214
|
+
behavior from code. Confirm `npx @iwsdk/cli xr status` is active before making pose,
|
|
215
|
+
controller/hand alignment, or immersive-interaction claims; a flat screenshot
|
|
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.
|
|
219
|
+
|
|
220
|
+
Verify:
|
|
221
|
+
|
|
222
|
+
- initial ECS state and explicit authored values;
|
|
223
|
+
- every interaction required by the acceptance contract;
|
|
224
|
+
- empty, rejected, boundary, or exclusivity guards when applicable;
|
|
225
|
+
- timed transitions and visible state feedback;
|
|
226
|
+
- reset of affected state, transforms, flags, timers, and references;
|
|
227
|
+
- exact runtime hierarchy names for addressable controls.
|
|
228
|
+
|
|
229
|
+
When the contract includes an exclusive slot or station, prove that a second
|
|
230
|
+
object cannot silently replace the current occupant.
|
|
231
|
+
|
|
232
|
+
Use compact CLI scripts to group related assertions. Capture screenshots at
|
|
233
|
+
the requested key states, not after every minor change.
|
|
234
|
+
|
|
235
|
+
Once the dev session is ready, target at most 24 shell-tool calls for the
|
|
236
|
+
entire verification pass. Batch the contract into a few coherent scenarios,
|
|
237
|
+
for example: initial state and guard behavior, successful primary interaction,
|
|
238
|
+
rejected or boundary behavior, and reset/runtime-name closeout. Each block
|
|
239
|
+
should perform its input sequence, query affected state, and print a compact
|
|
240
|
+
PASS/FAIL summary. After a failure, diagnose once and rerun only that block.
|
|
241
|
+
|
|
242
|
+
Keep context lean while iterating:
|
|
243
|
+
|
|
244
|
+
- do not re-read a file after a successful write or edit unless a later tool
|
|
245
|
+
reports a concrete mismatch; use a targeted range or search when only one
|
|
246
|
+
section is uncertain;
|
|
247
|
+
- project large CLI responses down to the exact fields being checked and cap
|
|
248
|
+
logs/search output;
|
|
249
|
+
- save evidence screenshots to disk, but do not load every full-resolution
|
|
250
|
+
image into model context. Image reads are expensive and can force context
|
|
251
|
+
compaction.
|
|
252
|
+
|
|
253
|
+
## 5. Visual quality gate
|
|
254
|
+
|
|
255
|
+
Before finishing, inspect the same hero/runtime view a reviewer will see:
|
|
256
|
+
|
|
257
|
+
- the complete experience fills the frame at a useful scale;
|
|
258
|
+
- primary objects and controls are visually distinguishable;
|
|
259
|
+
- important text and controls are readable from the intended viewpoint;
|
|
260
|
+
- required states differ immediately through color, text, motion, or emissive
|
|
261
|
+
feedback;
|
|
262
|
+
- no unintended starter content, severe clipping, empty space, or back-facing UI
|
|
263
|
+
remains.
|
|
264
|
+
|
|
265
|
+
If the app is correct but the panel is tiny or the scene is too distant, fix
|
|
266
|
+
camera/framing before adding decorative complexity.
|
|
267
|
+
|
|
268
|
+
Use at most two visual reads by default: one early hero frame when composition
|
|
269
|
+
is uncertain, and one final inspection. Prefer a compact contact sheet of the
|
|
270
|
+
required states for the final read. If no contact-sheet tool is available,
|
|
271
|
+
inspect the hero frame plus the visually riskiest active state and prove the
|
|
272
|
+
remaining state changes through exact runtime text/color/state assertions.
|
|
273
|
+
Exceed this budget only to diagnose a specific visible defect, and replace an
|
|
274
|
+
earlier read rather than accumulating near-duplicate screenshots.
|
|
275
|
+
|
|
276
|
+
Keep original screenshots at evidence resolution, but load only a bounded
|
|
277
|
+
inspection copy into model context. Use an image tool already present in the
|
|
278
|
+
environment to limit an individual frame to roughly 640 pixels on its long edge
|
|
279
|
+
or a contact sheet to 1024 by 1024. Do not install a dependency only for this.
|
|
280
|
+
|
|
281
|
+
## 6. Targeted closeout, then stop
|
|
282
|
+
|
|
283
|
+
Once live assertions pass:
|
|
284
|
+
|
|
285
|
+
1. check the authored scene for every exact ID, component, and explicit value;
|
|
286
|
+
2. check runtime names and event-listener cleanup;
|
|
287
|
+
3. run `npm run --if-present typecheck` and `npm run build`;
|
|
288
|
+
4. re-run only assertions affected by the final fixes;
|
|
289
|
+
5. leave the app reset to its initial state and report concise evidence.
|
|
290
|
+
|
|
291
|
+
Do not launch the project code-reviewer by default. Use it only when a live or
|
|
292
|
+
build failure remains unexplained, the implementation uses an unfamiliar
|
|
293
|
+
framework boundary, or the user explicitly requests review. Do not apply
|
|
294
|
+
style-only review changes after the quality gates pass.
|
|
295
|
+
|
|
296
|
+
## Budget and stopping rules
|
|
297
|
+
|
|
298
|
+
- By roughly 60% of the available session, the full vertical slice should
|
|
299
|
+
exist and typecheck.
|
|
300
|
+
- By roughly 75%, switch from feature work to runtime verification.
|
|
301
|
+
- By roughly 85%, freeze optional polish and close exact contract gaps.
|
|
302
|
+
- Prefer one proven implementation over alternate architectures, redundant
|
|
303
|
+
screenshots, repeated reviews, or speculative cleanup.
|
|
304
|
+
- Stop when static contract, production build, live paths, and visual gate pass.
|
|
305
|
+
|
|
306
|
+
The output is the working IWSDK app and concise final evidence—not a record of
|
|
307
|
+
the process used to produce it.
|