@iwsdk/create 0.5.3 → 1.0.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.
Files changed (106) hide show
  1. package/dist/cli.js +7223 -215
  2. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/SKILL.md +311 -0
  3. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  4. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  5. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/SKILL.md +262 -0
  6. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  7. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  8. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  9. package/dist/guidance/{claude/.claude/skills/iwsdk-scene-composer → agents/.agents/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
  10. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  11. package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
  12. package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +69 -91
  13. package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
  14. package/dist/guidance/agents/.agents/skills/iwsdk-dev/SKILL.md +45 -0
  15. package/dist/guidance/{claude/.claude/skills/iwsdk-planner → agents/.agents/skills/iwsdk-dev}/references/api-reference.md +53 -45
  16. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/iterate.md +239 -0
  17. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/planner.md +303 -0
  18. package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +37 -114
  19. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/SKILL.md +177 -0
  20. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  21. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
  22. package/dist/guidance/agents/.agents/skills/iwsdk-native-xr-test/SKILL.md +246 -0
  23. package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -78
  24. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
  25. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
  26. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  27. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  28. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  29. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  30. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  31. package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +45 -136
  32. package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +251 -157
  33. package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +9 -6
  34. package/dist/guidance/claude/.claude/rules/scene-json.md +6 -4
  35. package/dist/guidance/claude/.claude/settings.json +6 -2
  36. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/SKILL.md +311 -0
  37. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  38. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  39. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/SKILL.md +262 -0
  40. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  41. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  42. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  43. package/dist/guidance/{agents/.agents/skills/iwsdk-scene-composer → claude/.claude/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
  44. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  45. package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
  46. package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +69 -91
  47. package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
  48. package/dist/guidance/claude/.claude/skills/iwsdk-dev/SKILL.md +45 -0
  49. package/dist/guidance/{agents/.agents/skills/iwsdk-planner → claude/.claude/skills/iwsdk-dev}/references/api-reference.md +53 -45
  50. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/iterate.md +239 -0
  51. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/planner.md +303 -0
  52. package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +37 -114
  53. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/SKILL.md +177 -0
  54. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  55. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
  56. package/dist/guidance/claude/.claude/skills/iwsdk-native-xr-test/SKILL.md +246 -0
  57. package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -78
  58. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
  59. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
  60. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  61. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  62. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  63. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  64. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  65. package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +45 -136
  66. package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +251 -157
  67. package/dist/guidance/claude/CLAUDE.md +2 -141
  68. package/dist/guidance/codex/.codex/config.toml +1 -1
  69. package/dist/guidance/common/AGENTS.md +96 -37
  70. package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +6 -4
  71. package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +6 -4
  72. package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +6 -4
  73. package/dist/template/common/README.md +13 -0
  74. package/dist/template/common/public/ui/welcome.uikitml +0 -19
  75. package/dist/template/common/src/robot.ts +5 -0
  76. package/dist/template/common/vite.config.ts +18 -0
  77. package/dist/template/common-js/README.md +13 -0
  78. package/dist/template/common-js/public/ui/welcome.uikitml +0 -19
  79. package/dist/template/common-js/src/robot.js +5 -0
  80. package/dist/template/common-js/vite.config.js +18 -0
  81. package/package.json +8 -7
  82. package/scripts/verify-release-ready.mjs +25 -0
  83. package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +0 -364
  84. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +0 -243
  85. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +0 -101
  86. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +0 -176
  87. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +0 -156
  88. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +0 -199
  89. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +0 -257
  90. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
  91. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
  92. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
  93. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
  94. package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +0 -364
  95. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +0 -243
  96. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +0 -101
  97. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +0 -176
  98. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +0 -156
  99. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +0 -199
  100. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +0 -257
  101. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
  102. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
  103. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
  104. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
  105. /package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
  106. /package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
@@ -0,0 +1,262 @@
1
+ ---
2
+ name: iwsdk-compose-scene
3
+ description: Compose and review IWSDK scenes from existing manifest assets using scene JSON, placement, scale, contacts, prefabs, patterns, lighting, environment, cameras, and final framing. Does not author geometry or materials; create or repair an individual 3D asset with iwsdk-build-model.
4
+ ---
5
+
6
+ # IWSDK Compose Scene
7
+
8
+ Arrange existing IWSDK assets into a coherent scene. Scene JSON owns composition;
9
+ asset modules own geometry and materials; the managed editor provides visual
10
+ feedback and human transform/component adjustment.
11
+
12
+ If the request creates or materially changes one model, invoke `iwsdk-build-model`
13
+ for that asset first. If scene review reveals a defect inside one asset, route the
14
+ repair back to `iwsdk-build-model`. Keep placement, cross-asset contact, lighting,
15
+ environment, and cameras here.
16
+
17
+ ## Route Before Loading References
18
+
19
+ Choose exactly one route before opening any reference:
20
+
21
+ - Use the **Fast Path** when the model handoff already supplies manifest ids, bounds,
22
+ and contact planes and the task needs only asset placement, built-in lighting or
23
+ environment, player spawn, and named views. Follow only that section and stop when
24
+ its finish gates pass.
25
+ - Use the **Extended Workflow** for imports, prefabs, patterns, unfamiliar components,
26
+ schema errors, image reconstruction, missing asset contracts, or genuinely ambiguous
27
+ composition evidence.
28
+
29
+ After selecting the Extended Workflow, read
30
+ [extended-workflow.md](references/extended-workflow.md). Do not load it on the Fast
31
+ Path; it routes the additional format, intake, composition, and review references.
32
+
33
+ ## Bounded Opening
34
+
35
+ Read the applicable scoped scene/assets instructions and inspect
36
+ `iwsdk.config.json`, the configured asset manifest, relevant model handoffs, and the
37
+ active scene in one bounded pass. Reach the first scene edit within roughly eight
38
+ tool calls. Do not begin with dependency-tree searches, generated declarations,
39
+ repeated capability queries, or marketplace browsing.
40
+
41
+ For the routine Fast Path, the scoped rules plus the model handoff are sufficient.
42
+ Load the long scene-format material only for imports, prefabs, patterns, or after a
43
+ concrete schema rejection.
44
+
45
+ ## Fixed Boundaries
46
+
47
+ - Do not author geometry or materials in this skill. An asset-internal defect belongs
48
+ to `iwsdk-build-model`; scene-relative placement and lighting defects stay here.
49
+ - A display stand, architectural shell, terrain piece, or set-dressing object is still
50
+ a model. If one is missing or must materially change, pause composition and finish it
51
+ with `iwsdk-build-model`; do not create or edit its asset module here.
52
+ - Repetition inside one manifest asset belongs to `iwsdk-build-model`; repetition of
53
+ placed assets belongs here through scene prefabs and patterns.
54
+ - UIKitML panels belong to `iwsdk-ui`, not either 3D skill.
55
+ - Use only `iwsdk.scene.v1`. There is no compatibility schema.
56
+ - Scene files are the composition source of truth. Create and edit them with normal
57
+ filesystem tools under `public/scenes/`.
58
+ - Scene JSON has one renderable content kind: `asset`. It does not define models,
59
+ primitive geometry, material resources, or material overrides.
60
+ - The default export of the configured application asset manifest is the asset source
61
+ of truth. It may contain URL-backed glTF and UIKitML entries plus parentless
62
+ `Object3D` prototypes with arbitrary Three.js geometry and materials.
63
+ - The application runtime and editor import the same manifest module independently.
64
+ Never depend on shared object identity, iframe messaging, DOM state, or a live
65
+ runtime world when defining assets.
66
+ - Humans use the editor for selection, hierarchy, transforms, components, root
67
+ lighting, and preview visibility. They do not edit geometry or materials there.
68
+ - Agents may edit asset TypeScript and scene JSON, then use the editor to validate and
69
+ render the result.
70
+
71
+ ## Small Stateful Interactions
72
+
73
+ When a composed scene needs a small stateful interaction, keep it in one project
74
+ system with project components. Use `createComponent` plus `defineComponents`, then
75
+ `createSystem` queries whose `entities` values are Sets. React to ray activation with
76
+ a query qualified by `Pressed`; read or move scene-authored entities through each
77
+ entity's `object3D`.
78
+
79
+ Use `"OneHandGrabbable": {}` for proximity grab and `"RayInteractable": {}` for ray
80
+ activation. `Grabbed` is a transient tag managed by `GrabSystem`; use query
81
+ qualify/disqualify transitions for lifecycle work and `GrabSystem.forceRelease()` for
82
+ reset. Import these APIs and Three.js runtime classes from `@iwsdk/core`; do not inspect
83
+ package source or generated declarations to rediscover established contracts.
84
+
85
+ Route substantial UI behavior to `iwsdk-ui`, unfamiliar grab or ray behavior to the
86
+ matching interaction skill, and runtime failures to `iwsdk-debug`.
87
+
88
+ The public scene MCP surface is intentionally small:
89
+
90
+ ```text
91
+ scene_open
92
+ scene_render_file
93
+ scene_flatten_file
94
+ scene_get_state
95
+ scene_get_capabilities
96
+ scene_screenshot
97
+ scene_select
98
+ scene_set_camera
99
+ scene_set_preview_visibility
100
+ scene_measure_image_regions
101
+ ```
102
+
103
+ Document creation and mutation happen through direct file edits. Do not look for MCP
104
+ create/add/update/remove/patch/save/compose/review/publish tools.
105
+
106
+ When MCP is unavailable, use the CLI equivalents:
107
+
108
+ ```bash
109
+ npx @iwsdk/cli dev status
110
+ npx @iwsdk/cli dev up
111
+ npx @iwsdk/cli scene capabilities --raw
112
+ npx @iwsdk/cli scene render-file \
113
+ --input-json '{"path":"public/scenes/room.iwsdk.scene.json","viewId":"hero"}' \
114
+ --output-file artifacts/room.png
115
+ npx @iwsdk/cli scene flatten \
116
+ --input-json '{"path":"public/scenes/room.composition.iwsdk.scene.json","outputPath":"public/scenes/room.iwsdk.scene.json"}' --raw
117
+ npx @iwsdk/cli scene open \
118
+ --input-json '{"path":"public/scenes/room.iwsdk.scene.json"}' --raw
119
+ npx @iwsdk/cli scene state --raw
120
+ ```
121
+
122
+ `iwsdk dev up` starts the server in the background and launches the configured
123
+ managed editor browser. It can return while that browser is still starting; use
124
+ `iwsdk runtime wait` or inspect `iwsdk runtime status` before browser-backed
125
+ commands. Do not edit `vite.config.ts` to change browser mode as an ad hoc
126
+ startup workaround.
127
+
128
+ `scene_render_file` renders a file without replacing the editor's active document,
129
+ but it still uses the managed editor browser for manifest evaluation and WebGL.
130
+ MCP screenshot tools persist their PNG and return `screenshotPath`; read the file only
131
+ when the requested visual check requires it.
132
+ If readiness does not arrive, inspect `iwsdk runtime status` and `iwsdk dev logs
133
+ --tail 100`. Use `iwsdk runtime recover` only when the diagnostics indicate a
134
+ recoverable launch failure. Do not invent a custom CPU or Playwright renderer
135
+ and present it as authoritative editor evidence. Preserve the structured
136
+ failure, continue type/schema/build checks that remain meaningful, and report
137
+ the visual-verification gate as blocked.
138
+
139
+ Camera parameters are intentionally distinct: `view` accepts only the built-in
140
+ presets (`current`, `top`, `front`, `back`, `left`, `right`, `quarter`, `orbit`),
141
+ while `viewId` selects an exact camera declared in `authoring.views`. Outside
142
+ immersive XR, a loaded level's saved hero view owns runtime framing and
143
+ supersedes the initial `World.create({ render: { camera } })` pose. In XR, the
144
+ tracked player rig owns the camera, so the player-spawn view is a separate
145
+ required framing check.
146
+
147
+ ## Fast Path
148
+
149
+ Use this path when the handoff already provides manifest ids, envelopes, and contact
150
+ planes and the scene needs only placed assets, built-in lights/environment, player
151
+ spawn, and named authoring views:
152
+
153
+ 1. inspect the existing scene once;
154
+ 2. write one import-free scene JSON with all placements, lighting, and only the
155
+ requested authoring views;
156
+ 3. render the first hero at 512×512 or smaller;
157
+ 4. make at most one coherent visual correction;
158
+ 5. verify that correction at 384×384 or smaller; do not raise the resolution;
159
+ 6. open the file, confirm clean state, and run the application build;
160
+ 7. stop. Do not continue into the Extended Workflow after these gates pass.
161
+
162
+ Keep the ordinary starting player pose unless the request explicitly requires a
163
+ different spawn. In the stock scaffold the viewer is near `[0, 1.6, 0]` and looks
164
+ down negative Z, so primary no-locomotion content normally belongs around
165
+ `z = -0.5` to `-2.5`; positive Z is behind the player. After any diagnostic camera
166
+ or headset movement, restore that starting pose and verify one live frame there.
167
+
168
+ The default Fast Path budget is at most three scene renders, two compact image reads,
169
+ and one correction round. Expand it only to diagnose a specific failed criterion.
170
+
171
+ Agent-loop images are inspection evidence, not delivery renders. The evaluator or
172
+ delivery workflow can capture the unchanged scene at higher resolution after the
173
+ agent stops; do not feed that larger duplicate image back into the model context.
174
+
175
+ In Claude Code, `Write` echoes the complete document into the transcript. Use it only
176
+ when the new scene is roughly 80 lines or 8 KB or smaller. For a longer initial scene,
177
+ use single-quoted Bash heredocs (`<<'EOF'`) capped at roughly 120 lines or 12 KB per
178
+ tool call: create with `>` and append in later calls with `>>`. End each call at its
179
+ heredoc delimiter rather than adding command substitutions or validation. For
180
+ corrections above roughly 120 lines, do not use `Edit`; use one narrowly scoped
181
+ scripted replacement that asserts exactly one match, writes once, and prints only a
182
+ short confirmation. Do not put JSON or TypeScript template literals in `node -e`.
183
+
184
+ A player transform is not an authoring view. Do not add an extra player-spawn or
185
+ inspection view unless the task requests it. Every authored view must declare a valid
186
+ `role`; the common Fast Path normally needs only the `hero` view shown below.
187
+
188
+ Use this complete minimal shape instead of looking up the common schema. Duplicate
189
+ asset and light nodes as needed, then choose positions from the handed-off bounds:
190
+
191
+ ```json
192
+ {
193
+ "version": "iwsdk.scene.v1",
194
+ "units": "meters",
195
+ "components": {
196
+ "com.iwsdk.components.DomeGradient": {
197
+ "sky": [0.02, 0.03, 0.05, 1],
198
+ "equator": [0.05, 0.06, 0.08, 1],
199
+ "ground": [0.01, 0.01, 0.015, 1],
200
+ "intensity": 1
201
+ },
202
+ "com.iwsdk.components.IBLGradient": {
203
+ "sky": [0.25, 0.3, 0.4, 1],
204
+ "equator": [0.12, 0.14, 0.18, 1],
205
+ "ground": [0.03, 0.035, 0.04, 1],
206
+ "intensity": 1
207
+ }
208
+ },
209
+ "resources": {},
210
+ "authoring": {
211
+ "views": [{
212
+ "id": "hero", "role": "hero", "projection": "perspective",
213
+ "position": [4, 3, 4], "target": [0, 1, -1.5], "fov": 42
214
+ }]
215
+ },
216
+ "nodes": [
217
+ {
218
+ "id": "Hero", "content": {
219
+ "type": "asset", "asset": "HeroModel",
220
+ "castShadow": true, "receiveShadow": true
221
+ },
222
+ "transform": {"position": [0, 0, -1.5]}
223
+ },
224
+ {
225
+ "id": "KeyLight", "transform": {
226
+ "position": [-4, 6, 2], "rotationDeg": [-45, -35, 0]
227
+ },
228
+ "components": {"com.iwsdk.components.DirectionalLight": {
229
+ "color": [1, 0.92, 0.8, 1], "intensity": 3, "castShadow": true
230
+ }}
231
+ },
232
+ {
233
+ "id": "Fill", "components": {"com.iwsdk.components.AmbientLight": {
234
+ "color": [0.45, 0.55, 0.8, 1], "intensity": 0.45
235
+ }}
236
+ }
237
+ ]
238
+ }
239
+ ```
240
+
241
+ Directional lights emit along local `-Z`. Start from the shown transform or another
242
+ simple intentional angle and refine it from the render; do not write a look-at solver.
243
+ The common light payloads are `AmbientLight: {color, intensity}`,
244
+ `HemisphereLight: {skyColor, groundColor, intensity}` (there is no `color` field),
245
+ and `PointLight: {color, intensity, distance, decay, castShadow}`. A clean state after
246
+ the correction is the finish gate; do not query capabilities again merely to confirm
247
+ these established fields.
248
+
249
+ For this common path, do not read the references or call
250
+ `scene_get_capabilities`: `DomeGradient`, `IBLGradient`, `AmbientLight`,
251
+ `HemisphereLight`, `DirectionalLight`, `PointLight`, asset nodes,
252
+ `player.transform`, and perspective/orthographic `authoring.views` are established
253
+ schema. Do not write a separate projection or light-aim solver. Choose the initial
254
+ camera from the handed-off envelopes and refine it from the authoritative render.
255
+ Use the longer workflow and references only for imports, prefabs, patterns, unfamiliar
256
+ components, schema errors, image reconstruction, or ambiguous composition evidence.
257
+
258
+ ## Extended Workflow
259
+
260
+ When the Fast Path does not apply, read and follow
261
+ [extended-workflow.md](references/extended-workflow.md). Do not load that reference
262
+ for a routine scene assembled from known manifest assets.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: 'IWSDK Compose Scene'
3
+ short_description: 'Arrange, light, and review editable IWSDK scenes'
4
+ default_prompt: 'Use $iwsdk-compose-scene to compose this request from validated manifest assets.'
@@ -0,0 +1,166 @@
1
+ # IWSDK Compose Scene: Extended Workflow
2
+
3
+ Read this reference only after the top-level skill has ruled out the Fast Path.
4
+
5
+ Use the focused references as needed:
6
+
7
+ - [scene-format.md](scene-format.md) when the existing scene does not demonstrate a
8
+ required construct, or when schema diagnostics need investigation;
9
+ - [text-intake.md](text-intake.md) for scene-layout evidence from text;
10
+ - [image-intake.md](image-intake.md) for scene-layout and camera evidence from image
11
+ or hybrid requests; route model-local reconstruction separately;
12
+ - [scene-composition.md](scene-composition.md) for modules, scene-level repetition,
13
+ lighting, cameras, and cost control;
14
+ - [scene-review.md](scene-review.md) before final review.
15
+
16
+
17
+ Enter this workflow only when the routing criteria above exclude the Fast Path.
18
+
19
+ ### 1. Specify
20
+
21
+ Turn the request into a compact implementation brief:
22
+
23
+ - required and optional features;
24
+ - source evidence regions for image input;
25
+ - silhouette, proportions, parts, negative space, contacts, and material response;
26
+ - hero and diagnostic views;
27
+ - measurable acceptance criteria;
28
+ - assumptions, uncertainty, and fidelity ceiling.
29
+
30
+ A single image proves visible composition, not hidden geometry. Do not silently invent
31
+ occluded detail or lower requested fidelity.
32
+
33
+ ### 2. Inventory Assets And Modules
34
+
35
+ Inspect the existing scene, `src/assets.ts`, and relevant asset modules first. Call
36
+ `scene_get_capabilities` only when the task introduces a component, content kind,
37
+ pattern, import, or schema feature that the existing project and focused reference
38
+ search do not already demonstrate. Do not load the full schema for routine placement.
39
+
40
+ Classify each requested visible element as an existing manifest asset, a new model,
41
+ a UIKitML panel, or a scene-level assembly. Invoke `iwsdk-build-model` for each new
42
+ or materially changed 3D model—including support, architecture, and set dressing—and
43
+ `iwsdk-ui` for UIKitML. Continue here only once every visible asset has a stable
44
+ manifest id, object-local envelope, and relevant attachment anchors. From this point
45
+ until a model-local defect is discovered, do not create or edit asset TypeScript.
46
+
47
+ For initial construction, plan independent semantic groups as standalone scratch
48
+ scene modules. Give each module a local origin, size envelope, attachment points,
49
+ required views, and asset IDs. Asset and component IDs are application-global;
50
+ imported node and prefab IDs are namespaced. Imports are an authoring-only assembly
51
+ mechanism, never a runtime or editable-project format.
52
+
53
+ ### 3. Compose
54
+
55
+ Author scene JSON in dependency order:
56
+
57
+ 1. support/stage and representative lighting;
58
+ 2. large placed assets and cross-asset scale;
59
+ 3. identity-critical spatial relationships and support contacts;
60
+ 4. repeated placed assets through prefabs or patterns;
61
+ 5. hero camera and final environment.
62
+
63
+ Use meters, stable descriptive IDs, deterministic ordering, and explicit transforms.
64
+ Groups supply hierarchy, never visible mass. Use `castShadow` and `receiveShadow`
65
+ only when needed. Do not rebuild missing model detail from scene primitives or JSON.
66
+
67
+ ### 4. Validate And Materialize
68
+
69
+ With the managed editor command-ready, call `scene_render_file` on every changed
70
+ scratch module, then the composition root. It resolves imports for authoring preview,
71
+ validates schema and manifest references, lowers the scene, and returns a PNG plus
72
+ diagnostics without changing the active document. Fix failures in the owning asset or
73
+ scratch file.
74
+
75
+ Keep agent-loop renders at 640×640 or smaller and prefer the MCP call, which persists
76
+ the image and returns `screenshotPath`. Read that file only when visual inspection is
77
+ needed. Generate a larger delivery image only after the final camera is chosen, and
78
+ do not feed that duplicate image back into the model context.
79
+
80
+ After the composition root passes, run `scene_flatten_file` / `iwsdk scene flatten`
81
+ once to materialize an import-free final scene. The command preserves import wrapper
82
+ groups, validates the output, and refuses to write if its runtime hash differs from
83
+ the composed source. This is a one-way publication boundary: the flat file becomes
84
+ the sole source of truth, and later scratch-module changes must not be re-flattened
85
+ over human edits.
86
+
87
+ Call `scene_open` only on the flattened file for live collaboration. Import-bearing
88
+ files remain renderable composition previews but are never opened as editable scenes
89
+ and never load in the application runtime.
90
+
91
+ Use `scene_get_state` for selection, hashes, diagnostics, dirty/conflict state, runtime
92
+ readiness, and render statistics. Use camera, screenshot, selection, and preview
93
+ visibility tools only when their live-editor context is useful.
94
+
95
+ ### 5. Review And Refine
96
+
97
+ Review in three passes:
98
+
99
+ 1. **Layout**: hierarchy, scale, support contacts, and arrangement.
100
+ 2. **Asset fit**: silhouette and proportions in context, occlusion, and cross-asset
101
+ contacts. If the defect remains when the asset is viewed by itself, route it to
102
+ `iwsdk-build-model` instead of compensating with scene transforms.
103
+ 3. **Final**: material response, color, lighting, environment, and hero framing.
104
+
105
+ Keep review orchestration and evidence outside the editor. The editor supplies
106
+ authoritative screenshots, hashes, camera state, diagnostics, and render measurements.
107
+ Derive comparisons, defect lists, lineage, and stop decisions in ordinary task files.
108
+
109
+ Fix the highest-impact scene defect in its owning scene module. Route model-local
110
+ geometry or material defects to `iwsdk-build-model`, then rerender that asset and the
111
+ scene. Default to two focused correction rounds. Stop earlier on a
112
+ repeated defect, oscillation, plateau, missing input/asset, or representation ceiling.
113
+
114
+ ### 6. Finish
115
+
116
+ Finish only when:
117
+
118
+ - every scratch module and the composition root validates and renders;
119
+ - the final editable scene is flattened and contains no `imports`;
120
+ - the active editor state is clean and conflict-free;
121
+ - every new or changed model has passed `iwsdk-build-model` isolated review;
122
+ - required views are nonblank and correctly framed;
123
+ - required features pass measurable and visual checks;
124
+ - manifest asset IDs resolve in both editor and application runtime;
125
+ - the application build and selected scene load without blocking errors.
126
+
127
+ If a required gate is unavailable, finish with an explicit blocked or
128
+ accepted-with-gaps result. Passing a local schema check, production build, or custom
129
+ diagnostic image does not substitute for authoritative editor renders and state.
130
+
131
+ ## Modular Composition
132
+
133
+ ```json
134
+ {
135
+ "version": "iwsdk.scene.v1",
136
+ "units": "meters",
137
+ "imports": [
138
+ {
139
+ "id": "reading-nook",
140
+ "src": "./modules/reading-nook.iwsdk.scene.json",
141
+ "transform": { "position": [1.8, 0, -0.6] }
142
+ }
143
+ ],
144
+ "resources": {},
145
+ "nodes": []
146
+ }
147
+ ```
148
+
149
+ Each scratch module must be valid by itself. Imports resolve recursively in
150
+ declaration order. The import entry becomes a transform group. The composition root
151
+ owns global components, environment, metadata, and authoring settings. Cycles, unsafe
152
+ IDs, missing files, duplicate namespaced IDs, and invalid modules fail composition.
153
+
154
+ For parallel initial construction, assign one scratch module file per worker. Never
155
+ let two workers edit one file. Render modules independently, import only passing
156
+ modules, correct cross-module scale, contact, occlusion, lighting, and framing at the
157
+ composition root, then flatten exactly once. Parallel module iteration ends at that
158
+ boundary; continue all later edits in the flat file.
159
+
160
+ ## Regeneration And Provenance
161
+
162
+ Preserve stable IDs when revising the flat file. Never overwrite unrelated
163
+ human-authored files or re-flatten over editor changes. Record the skill/runtime
164
+ versions, input hashes, composition/final/module paths, capability hash,
165
+ source/composed/runtime hashes, assumptions, and fidelity ceiling in authoring
166
+ metadata or adjacent task evidence.
@@ -0,0 +1,80 @@
1
+ # IWSDK Scene Composition Patterns
2
+
3
+ This reference covers world-relative composition only. Geometry, materials, and
4
+ repetition inside one model belong to `iwsdk-build-model`.
5
+
6
+ ## Modules And Ownership
7
+
8
+ Use standalone scratch scene modules when a scene has independent spatial groups.
9
+ Each module should declare:
10
+
11
+ - a local origin and size envelope;
12
+ - asset ids and stable node ids;
13
+ - attachment/contact expectations with neighboring modules;
14
+ - the diagnostic and hero views that prove its layout.
15
+
16
+ Render every module before importing it. The composition root owns global components,
17
+ environment, lights, metadata, and authoring views. Flatten once after all modules
18
+ pass; later edits happen only in the flat scene.
19
+
20
+ ## Scene-Level Repetition
21
+
22
+ Use a prefab when a repeated placed object needs children or components. Use a
23
+ pattern when placement follows a deterministic grid, ring, line, or scatter rule.
24
+ Keep the model itself in the manifest; scene repetition must not duplicate geometry
25
+ or material declarations.
26
+
27
+ Repetition boundary:
28
+
29
+ - repeated bolts, vents, panels, or subparts inside one manifest asset →
30
+ `iwsdk-build-model`;
31
+ - repeated chairs, trees, props, modules, or buildings placed in the world → this
32
+ skill through prefabs and patterns.
33
+
34
+ ## Environment And Lighting
35
+
36
+ Put `DomeGradient` or `IBLGradient` on the level root only. Light direction follows
37
+ local `-Z`. Use a small deliberate rig: broad environment/fill, one readable key, and
38
+ only the shadows that communicate contact or depth.
39
+
40
+ If a material looks wrong, compare the asset's isolated material and clay previews.
41
+ If the defect survives clay, route it to `iwsdk-build-model`. If it appears only in
42
+ the scene, inspect light direction, intensity, exposure, tone mapping, and background
43
+ contrast here before changing the material.
44
+
45
+ ## Camera And Scale
46
+
47
+ Treat camera intent as data. Author exact named `authoring.views` for requested hero
48
+ or diagnostic shots. `view` selects built-in editor views; `viewId` selects an exact
49
+ saved camera. Outside immersive XR, a loaded level's saved hero view supersedes the
50
+ initial `World.create({render:{camera}})` pose. In XR, player spawn is a separate
51
+ required framing check.
52
+
53
+ Keep the standing volume around the origin clear unless the scene explicitly authors
54
+ a different player transform. Check scale with known human references and verify
55
+ support contacts from more than one angle.
56
+
57
+ ## Review Isolation
58
+
59
+ Use `scene_select` plus `scene_set_preview_visibility` to solo one scene node or keep
60
+ ghosted context. This isolates a placed asset, not named children inside its model.
61
+ For a model-internal part, use `asset_render_preview` through `iwsdk-build-model`.
62
+
63
+ Review the scene in this order:
64
+
65
+ 1. top/front layout and scale;
66
+ 2. quarter and side views for contacts, occlusion, and depth;
67
+ 3. hero framing and material response;
68
+ 4. player-spawn framing when immersive.
69
+
70
+ ## Cost Control
71
+
72
+ Use measured render statistics instead of intuition. Watch draw calls, expanded
73
+ instance counts, triangle count, unique materials/geometries, textures, shader
74
+ programs, and shadow casters. Prefer shared manifest resources and patterns where
75
+ they preserve editability. Do not trade away requested silhouette or interaction
76
+ readability merely to lower counts.
77
+
78
+ Run one complete scene review, fix the highest-impact composition defect, and repeat
79
+ at most once unless the second pass reveals a new blocking issue. Stop on repeated
80
+ defects, oscillation, or a clear plateau.
@@ -95,7 +95,7 @@ The following old branches are invalid and must never be emitted:
95
95
 
96
96
  Create procedural shapes and custom PBR/shader materials in TypeScript, register the
97
97
  resulting parentless `Object3D`, then reference its asset ID. See
98
- [asset-authoring.md](asset-authoring.md).
98
+ `iwsdk-build-model`.
99
99
 
100
100
  ## Nodes And Content
101
101
 
@@ -284,7 +284,7 @@ not override them. Once the composition passes, flatten and make the generated
284
284
  import-free document the sole source of truth. Never re-flatten over later editor
285
285
  changes.
286
286
 
287
- Use `scene_flatten_file` or `npx iwsdk scene flatten` to materialize the final
287
+ Use `scene_flatten_file` or `npx @iwsdk/cli scene flatten` to materialize the final
288
288
  document. The command resolves the import graph, preserves wrapper transforms,
289
289
  validates the flat output, writes atomically, and refuses the write if flattening
290
290
  changes runtime semantics.
@@ -368,7 +368,7 @@ Use `authoring.composition` as a fixed brief, not a process transcript:
368
368
  "feasibility": { "status": "supported" },
369
369
  "provenance": {
370
370
  "adapter": { "id": "hybrid-intake", "version": "1.0.0" },
371
- "skill": { "id": "iwsdk-scene-composer", "version": "1.0.0" },
371
+ "skill": { "id": "iwsdk-compose-scene", "version": "1.0.0" },
372
372
  "capabilityHash": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
373
373
  "inputHashes": []
374
374
  },
@@ -0,0 +1,66 @@
1
+ # IWSDK Scene Review
2
+
3
+ Review the actual managed-editor output, not source code alone. Keep evidence and the
4
+ defect list in the task or benchmark artifacts; do not create a process-document
5
+ pipeline unless the user requests one.
6
+
7
+ ## Inputs
8
+
9
+ Use:
10
+
11
+ - the request and explicit acceptance criteria;
12
+ - the active scene document and its hashes;
13
+ - editor screenshots from exact built-in or saved views;
14
+ - render statistics and recent unfiltered logs;
15
+ - isolated asset evidence from `iwsdk-build-model` for any new model.
16
+
17
+ ## Passes
18
+
19
+ ### Layout
20
+
21
+ Check hierarchy, scale, clear player volume, navigation space, repeated placement,
22
+ support relationships, and obvious overlap. Use top/front views first.
23
+
24
+ ### Asset Fit
25
+
26
+ Check whether each model reads correctly at its placed scale, whether contacts and
27
+ occlusion make spatial sense, and whether scene transforms are compensating for a
28
+ model-local defect. A defect that persists in an isolated clay preview routes to
29
+ `iwsdk-build-model`.
30
+
31
+ ### Final
32
+
33
+ Check material readability, lighting hierarchy, environment contrast, hero framing,
34
+ and player-spawn framing. The editor render proves static authored state; use the app
35
+ runtime for anything driven by systems.
36
+
37
+ ## Defect Record
38
+
39
+ For each material defect, record:
40
+
41
+ - view and affected scene node;
42
+ - observed evidence;
43
+ - expected result;
44
+ - owner: model or composition;
45
+ - proposed correction;
46
+ - regression risk.
47
+
48
+ Fix only the highest-impact coherent batch before rerendering. Do not compensate for
49
+ bad geometry with camera tricks, hide penetrations behind lighting, or silently lower
50
+ the requested fidelity.
51
+
52
+ ## Stop Rules
53
+
54
+ Default to at most two focused correction rounds after the first complete review.
55
+ Stop earlier when:
56
+
57
+ - the same defect repeats;
58
+ - two changes oscillate;
59
+ - applicable diagnostics plateau or regress;
60
+ - required input or assets are missing;
61
+ - the representation ceiling cannot satisfy a required feature;
62
+ - a user decision is required.
63
+
64
+ Completion requires passing scene/module renders, an import-free flat scene, a clean
65
+ editor state, nonblank required views, correct player-spawn framing, resolved manifest
66
+ ids, and a successful application build/runtime load.
@@ -46,16 +46,14 @@ Call `scene_get_capabilities`, inspect the configured asset manifest, then choos
46
46
  this order:
47
47
 
48
48
  1. reuse a registered glTF or procedural asset when it satisfies the required form;
49
- 2. author a new manifest asset when identity, geometry, or material response is
50
- missing;
49
+ 2. invoke `iwsdk-build-model` when identity, geometry, or material response is missing;
51
50
  3. assemble registered assets in a scene prefab for a reusable semantic object;
52
51
  4. use a deterministic pattern for repeated compatible prefabs;
53
52
  5. accept an approximation with a named fidelity ceiling;
54
53
  6. block when a required feature has no supportable representation.
55
54
 
56
- Do not fabricate catalog IDs. Procedural code is an explicit asset-authoring surface,
57
- not a hidden scene escape hatch: keep it deterministic in a dedicated asset module,
58
- register its parentless `Object3D` in the manifest, and reference that ID from JSON.
55
+ Do not fabricate catalog IDs or build model-local geometry from scene nodes. Continue
56
+ composition only after a new asset has a registered manifest id.
59
57
 
60
58
  ## Establish Scale And Coordinates
61
59