@iwsdk/cli 1.1.0 → 1.2.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (160) hide show
  1. package/README.md +106 -2
  2. package/dist/agent-adapters.d.ts +12 -1
  3. package/dist/agent-adapters.d.ts.map +1 -1
  4. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +312 -0
  5. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  6. package/dist/agent-guidance/files/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  7. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +277 -0
  8. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  9. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
  10. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  11. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
  12. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  13. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
  14. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  15. package/dist/agent-guidance/files/.agents/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
  16. package/dist/agent-guidance/files/.agents/skills/iwsdk-debug/SKILL.md +74 -0
  17. package/dist/agent-guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
  18. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/SKILL.md +46 -0
  19. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +1532 -0
  20. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +96 -0
  21. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +267 -0
  22. package/dist/agent-guidance/files/.agents/skills/iwsdk-dev/references/planner.md +307 -0
  23. package/dist/agent-guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +282 -0
  24. package/dist/agent-guidance/files/.agents/skills/iwsdk-grab/SKILL.md +75 -0
  25. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +179 -0
  26. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  27. package/dist/agent-guidance/files/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
  28. package/dist/agent-guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +262 -0
  29. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/SKILL.md +217 -0
  30. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/offline.ts.template +99 -0
  31. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/sw.js.template +241 -0
  32. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
  33. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/build-step.md +71 -0
  34. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/page.md +70 -0
  35. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/service-worker.md +107 -0
  36. package/dist/agent-guidance/files/.agents/skills/iwsdk-offline/references/testing.md +57 -0
  37. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/SKILL.md +106 -0
  38. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/component-reference.md +152 -0
  39. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +102 -0
  40. package/dist/agent-guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +309 -0
  41. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +230 -0
  42. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  43. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  44. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  45. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  46. package/dist/agent-guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +208 -0
  47. package/dist/agent-guidance/files/.agents/skills/iwsdk-ray/SKILL.md +70 -0
  48. package/dist/agent-guidance/files/.agents/skills/iwsdk-ui/SKILL.md +335 -0
  49. package/dist/agent-guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
  50. package/dist/agent-guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +521 -0
  51. package/dist/agent-guidance/files/.claude/rules/assets-and-manifest.md +60 -0
  52. package/dist/agent-guidance/files/.claude/rules/ecs-api.md +103 -0
  53. package/dist/agent-guidance/files/.claude/rules/scene-json.md +72 -0
  54. package/dist/agent-guidance/files/.claude/rules/uikitml.md +66 -0
  55. package/dist/agent-guidance/files/.claude/settings.json +30 -0
  56. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +312 -0
  57. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  58. package/dist/agent-guidance/files/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  59. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +277 -0
  60. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  61. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +234 -0
  62. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  63. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/image-intake.md +190 -0
  64. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  65. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-format.md +466 -0
  66. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  67. package/dist/agent-guidance/files/.claude/skills/iwsdk-compose-scene/references/text-intake.md +80 -0
  68. package/dist/agent-guidance/files/.claude/skills/iwsdk-debug/SKILL.md +74 -0
  69. package/dist/agent-guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +88 -0
  70. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/SKILL.md +46 -0
  71. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +1532 -0
  72. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +96 -0
  73. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +267 -0
  74. package/dist/agent-guidance/files/.claude/skills/iwsdk-dev/references/planner.md +307 -0
  75. package/dist/agent-guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +282 -0
  76. package/dist/agent-guidance/files/.claude/skills/iwsdk-grab/SKILL.md +75 -0
  77. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +179 -0
  78. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  79. package/dist/agent-guidance/files/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
  80. package/dist/agent-guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +262 -0
  81. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/SKILL.md +217 -0
  82. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/offline.ts.template +99 -0
  83. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/sw.js.template +241 -0
  84. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
  85. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/build-step.md +71 -0
  86. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/page.md +70 -0
  87. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/service-worker.md +107 -0
  88. package/dist/agent-guidance/files/.claude/skills/iwsdk-offline/references/testing.md +57 -0
  89. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/SKILL.md +106 -0
  90. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/component-reference.md +152 -0
  91. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +102 -0
  92. package/dist/agent-guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +309 -0
  93. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +230 -0
  94. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  95. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  96. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  97. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  98. package/dist/agent-guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +208 -0
  99. package/dist/agent-guidance/files/.claude/skills/iwsdk-ray/SKILL.md +70 -0
  100. package/dist/agent-guidance/files/.claude/skills/iwsdk-ui/SKILL.md +335 -0
  101. package/dist/agent-guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
  102. package/dist/agent-guidance/files/.cursor/rules/assets-and-manifest.mdc +62 -0
  103. package/dist/agent-guidance/files/.cursor/rules/ecs-api.mdc +105 -0
  104. package/dist/agent-guidance/files/.cursor/rules/scene-json.mdc +74 -0
  105. package/dist/agent-guidance/files/.cursor/rules/uikitml.mdc +68 -0
  106. package/dist/agent-guidance/files/.github/instructions/assets-and-manifest.instructions.md +55 -0
  107. package/dist/agent-guidance/files/.github/instructions/ecs-api.instructions.md +101 -0
  108. package/dist/agent-guidance/files/.github/instructions/scene-json.instructions.md +71 -0
  109. package/dist/agent-guidance/files/.github/instructions/uikitml.instructions.md +65 -0
  110. package/{guidance → dist/agent-guidance/files}/AGENTS.md +107 -27
  111. package/dist/agent-guidance/files/CLAUDE.md +3 -0
  112. package/dist/agent-guidance/files/public/scenes/AGENTS.md +72 -0
  113. package/dist/agent-guidance/files/public/ui/AGENTS.md +66 -0
  114. package/dist/agent-guidance/files/src/AGENTS.md +153 -0
  115. package/dist/agent-guidance/manifest.json +954 -0
  116. package/dist/agent-guidance.d.ts +140 -0
  117. package/dist/agent-guidance.d.ts.map +1 -0
  118. package/dist/agent-guidance.js +3612 -0
  119. package/dist/agent-guidance.js.map +1 -0
  120. package/dist/cli.js +4010 -750
  121. package/dist/cli.js.map +1 -1
  122. package/dist/commands/adapter.d.ts +1 -0
  123. package/dist/commands/adapter.d.ts.map +1 -1
  124. package/dist/commands/agents.d.ts +11 -0
  125. package/dist/commands/agents.d.ts.map +1 -0
  126. package/dist/commands/browser.d.ts +11 -0
  127. package/dist/commands/browser.d.ts.map +1 -1
  128. package/dist/commands/dev.d.ts +1 -0
  129. package/dist/commands/dev.d.ts.map +1 -1
  130. package/dist/commands/reference.d.ts +15 -1
  131. package/dist/commands/reference.d.ts.map +1 -1
  132. package/dist/commands/runtime.d.ts.map +1 -1
  133. package/dist/commands/upgrade.d.ts +138 -0
  134. package/dist/commands/upgrade.d.ts.map +1 -0
  135. package/dist/contract.js +32 -0
  136. package/dist/contract.js.map +1 -1
  137. package/dist/guidance-refresh.d.ts +53 -0
  138. package/dist/guidance-refresh.d.ts.map +1 -0
  139. package/dist/help.d.ts +2 -0
  140. package/dist/help.d.ts.map +1 -1
  141. package/dist/index.d.ts.map +1 -1
  142. package/dist/index.js +6114 -508
  143. package/dist/index.js.map +1 -1
  144. package/dist/mcp-stdio.d.ts.map +1 -1
  145. package/dist/metavr-telemetry.d.ts +6 -0
  146. package/dist/metavr-telemetry.d.ts.map +1 -1
  147. package/dist/migrations/iwsdk-migrate-0-5/SKILL.md +413 -0
  148. package/dist/migrations.d.ts +36 -0
  149. package/dist/migrations.d.ts.map +1 -0
  150. package/dist/package-manager.d.ts +34 -0
  151. package/dist/package-manager.d.ts.map +1 -0
  152. package/dist/release-notes.d.ts +28 -0
  153. package/dist/release-notes.d.ts.map +1 -0
  154. package/dist/release-notes.json +1506 -0
  155. package/dist/runtime-contract.d.ts +8 -0
  156. package/dist/runtime-contract.d.ts.map +1 -1
  157. package/dist/runtime-telemetry.d.ts +8 -1
  158. package/dist/runtime-telemetry.d.ts.map +1 -1
  159. package/dist/version.d.ts +1 -1
  160. package/package.json +9 -3
@@ -0,0 +1,96 @@
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. A profile first draws three warm-up frames, so
21
+ one-time first-draw costs (shader compilation, texture uploads) stay out of
22
+ its numbers.
23
+ - Headed sessions, including collaborate mode, always draw every frame.
24
+ - To draw every frame in a headless session, start it with
25
+ `IWSDK_DEV_RENDER_MODE=continuous`.
26
+
27
+ ## Check state, then look
28
+
29
+ Prove behavior with ECS state (`ecs query`, `ecs find`, `ecs snapshot`,
30
+ `ecs diff`). These need no pixels and see every frame. Take a screenshot only
31
+ for visual claims.
32
+
33
+ ## Capture an exact frame
34
+
35
+ ```bash
36
+ npx @iwsdk/cli ecs pause --input-json '{}'
37
+ npx @iwsdk/cli ecs step --input-json '{"count":1}'
38
+ npx @iwsdk/cli browser screenshot --input-json '{}' --output-file artifacts/frame.png
39
+ npx @iwsdk/cli ecs resume --input-json '{}'
40
+ ```
41
+
42
+ A screenshot draws without advancing the simulation, so it shows exactly the
43
+ paused frame.
44
+
45
+ To see motion, capture a filmstrip: exact simulation frames at offsets 0, K,
46
+ 2K, … in one contact-sheet image.
47
+
48
+ ```bash
49
+ npx @iwsdk/cli browser filmstrip --count 6 --every 5 --output-file artifacts/fall.png
50
+ ```
51
+
52
+ ## Switch the render mode at runtime
53
+
54
+ The `RuntimeSettings` component controls the render mode. It exists only at
55
+ runtime and is never saved into scene files.
56
+
57
+ ```bash
58
+ npx @iwsdk/cli ecs find --input-json '{"withComponents":["RuntimeSettings"]}'
59
+ npx @iwsdk/cli ecs set-component --input-json '{"entityIndex":<index>,"componentId":"RuntimeSettings","field":"renderMode","value":"continuous"}'
60
+ ```
61
+
62
+ Without a GPU, continuous drawing drops the app to a few frames per second, so
63
+ set it back to `"on-demand"` when done.
64
+
65
+ ## Do not
66
+
67
+ - Judge performance from headless frame rates. Profile instead, which draws
68
+ every frame while it runs, or measure on a device:
69
+ `npx @iwsdk/cli browser profile --input-json '{"action":"start","mode":"rendering"}'`,
70
+ exercise the scene, then
71
+ `npx @iwsdk/cli browser profile --input-json '{"action":"stop"}'`.
72
+ - Trust the frame times of a profile that reports a `render-warmup-timeout`
73
+ interruption (the app did not draw its warm-up frames in the time the start
74
+ allowed, at most 5 seconds) or `render-loop-stopped` (the app drew nothing
75
+ for 30 or more animation frames in a row while the profile held rendering:
76
+ its render loop stopped, before the profile or during it, or stalled). The
77
+ usual cause is an uncaught error in a frame, which stops the render loop;
78
+ check `npx @iwsdk/cli browser logs`. After a warm-up timeout, the first
79
+ frames may also just be very slow. Fix the error, or profile again.
80
+ - Trust the frame times of a profile that reports
81
+ `render-warmup-skipped-budget` (less than a second of the command's time
82
+ was left for the warm-up) or `render-mode-unavailable`. It sampled without
83
+ warm-up frames, so its numbers may include first-draw costs. Profile again.
84
+ - Expect a frame to change between screenshots if the scene did not change.
85
+ - Restart into headed mode to "fix" a stale view; screenshots already draw a
86
+ fresh frame.
87
+
88
+ ## Limits
89
+
90
+ - App code that reads pixels from the canvas itself (for example
91
+ `canvas.toDataURL()`) must draw and read in the same task (call
92
+ `renderer.render()`, then read), or create the renderer with
93
+ `preserveDrawingBuffer: true`. `await world.requestRender()` resolves after
94
+ the frame is presented, when the drawing buffer may already be cleared. See
95
+ the render loop API: `world.renderMode`, `world.requestRender(frames)` and
96
+ `world.holdRender()`.
@@ -0,0 +1,267 @@
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 reports
158
+ contact, not a click: confirm the click by the state it changes (`ui inspect`
159
+ on the control, or the app state it drives). A `presses[0].contactMs` of more
160
+ than 800 never clicks. A stalled frame can stretch a press that far, so run
161
+ that press once more before changing code. A control out of reach stretches it
162
+ too, because the body walks to it during the press: walk first, with
163
+ `{"body":{"stepTo":"Btn_Action"}}` as a step of its own, then press.
164
+
165
+ If a scene/source/UI edit happens after the managed runtime started and live
166
+ state becomes stale, do not call `scene open`, repeatedly poll `dev status`, or
167
+ loop on browser reload. Run one
168
+ `npx @iwsdk/cli dev restart --ai-mode <the session's current mode> --timeout 60000`, then resume the named-state
169
+ check. One failed restart may be diagnosed once; do not enter a recovery loop.
170
+
171
+ Do not perform a full product replay when the edit affects one bounded path.
172
+ Expand verification only when a measured failure shows broader impact.
173
+
174
+ ## Visual comparison
175
+
176
+ Use the supplied pre-edit baseline when present. Pixel reads have a hard ceiling
177
+ of two: one bounded baseline or final comparison and one replacement after a
178
+ focused correction. Never read aim, hover, panel, coordinate, or duplicate debug
179
+ screenshots. Debug interactions with state, not pixels.
180
+
181
+ Never load a full-resolution PNG into model context. Preserve deliverable
182
+ images unchanged, but create a temporary JPEG preview no wider than 600 pixels
183
+ at about 70% quality with an image tool already available in the environment.
184
+ Do not install a dependency only to resize evidence, and delete the temporary
185
+ preview after the visual decision.
186
+
187
+ Do not use repeated `scene render-file` calls to discover framing. When an
188
+ authored hero view must be checked, run it once and read
189
+ `data.result.renderStats.visibleNodeIds`; make at most one focused camera or
190
+ composition correction from that result. The second render is the final hero
191
+ attempt even if it fails; do not issue a third `scene render-file` call.
192
+
193
+ Do not reconcile hero and default-player framing with trigonometry, coordinate
194
+ sweeps, repeated screenshots, or browser logs. Keep the panel identity-rotated
195
+ for the player. If the one hero check misses it, move only the existing hero
196
+ camera to the same side of the panel as the default player, check once more,
197
+ and freeze. Inspect browser logs at most once and only after a command returns
198
+ an explicit runtime error; never create a log-debugging loop.
199
+
200
+ Preserve the existing composition and visual language unless the request asks
201
+ to change them. When it does, compare the same viewpoint before and after and
202
+ make one focused correction for clipping, legibility, contrast, or hierarchy.
203
+ When adding a new primary spatial panel, it must be readable at the default
204
+ runtime viewpoint rather than a tiny accessory: keep its visible bounds at
205
+ least roughly 12% of frame width and 8% of frame height, but normally below 70%
206
+ of frame width and 40% of frame height, while staying fully inside the frame.
207
+ It must not cover the preserved product primary object, existing primary UI,
208
+ or focused regression object. Readability alone is insufficient: visible
209
+ bounds must not touch or overlap. Leave roughly 3% of the frame as clear
210
+ separation. If the first preview shows contact, move the new panel into the
211
+ largest empty region above or beside the preserved composition.
212
+
213
+ Use an opaque or strongly contrasting panel surface. Primary copy must be dark
214
+ on light or light on dark; white or pale text on translucent white, sky, or
215
+ another bright background fails even when the glyphs are technically present.
216
+ For the scaffold's Horizon `<Panel>`, assume the kit's opaque surface wins
217
+ over a custom root `background-color`. That surface follows the color scheme:
218
+ the runtime renders it dark because `iwsdk.config.json` prefers `dark`, while
219
+ editor previews render it white. Give every text class a dark color plus a light
220
+ `:dark` variant, as `public/ui/welcome.uikitml` does, so copy reads on both.
221
+ Do not spend a restart discovering dark-on-dark or white-on-white text that the
222
+ stock kit behavior already predicts.
223
+
224
+ Reuse the established app panel scale and spacing when available. In the stock
225
+ starter-scale composition, a new front-facing UIKitML panel should begin at
226
+ 0.25-0.32 scale. If it shares the central horizontal band, place its center at
227
+ least 0.75 world meters above the preserved panel and at the same or greater
228
+ depth; side-by-side placement needs a clear gap beyond both half-widths. Keep
229
+ that separation through the one allowed correction.
230
+
231
+ On the first final preview, inspect the whole change together: new UI is fully
232
+ inside the frame; a visible gap separates it from existing primary UI and
233
+ objects; important copy and controls remain readable at preview size; and text
234
+ has strong contrast against its actual rendered surface. Batch one correction
235
+ for all failures, then take the second and final preview.
236
+
237
+ Keep primary added UI away from fragile frame edges unless the established
238
+ composition reserves a stable edge region. XR captures may use a square or
239
+ otherwise narrower aspect ratio than the browser. Prefer an above-central
240
+ placement over pushing a panel to the side, and retain a generous lateral
241
+ margin before accepting the final preview.
242
+
243
+ Progress and completion evidence must remain distinguishable at the compact
244
+ 600-pixel preview scale. Do not rely on changing only one short status sentence.
245
+ Use one coarse, deliberate milestone change such as a large status chip or bar,
246
+ clearly marked step indicators, or a strong color/state change on both the
247
+ panel and the affected object. The changed treatment should occupy a visible
248
+ region of the panel and make completion obvious without reading fine print.
249
+
250
+ For a front-facing UIKitML panel in the stock starter layout, keep rotationDeg
251
+ absent unless the existing app establishes another convention. Do not calculate
252
+ a look-at yaw solely to face the default player: the stock panel front is
253
+ face-on at identity. Judge the final result from a fresh default runtime
254
+ viewpoint, without custom headset repositioning before capture.
255
+
256
+ For XR work, keep the immersive session active through the final browser
257
+ screenshot. Immediately before capture, check XR status and enter once if the
258
+ session is inactive. A non-immersive browser camera is not placement evidence
259
+ for world-space UI; return to the default immersive viewpoint instead of moving
260
+ correctly placed content to satisfy the unrelated browser view.
261
+
262
+ ## Stop rule
263
+
264
+ Stop when the requested delta works through real input, the named state/UI
265
+ evidence passes, the focused preserved-path smoke passes, the production build
266
+ passes, and required evidence files exist. Do not reopen unrelated polish or
267
+ 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.