@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,466 @@
1
+ # IWSDK Scene Format
2
+
3
+ ## Contents
4
+
5
+ 1. Capability First
6
+ 2. Document Boundary
7
+ 3. Asset Boundary
8
+ 4. Nodes And Content
9
+ 5. Prefabs And Patterns
10
+ 6. Imports
11
+ 7. Components And Constraints
12
+ 8. Authoring And Review
13
+ 9. Validation Traps
14
+
15
+ ## Capability First
16
+
17
+ Call `scene_get_capabilities` before authoring. The active schema version, content
18
+ kinds, component hashes, pattern algorithms, and limits are authoritative.
19
+
20
+ The only format is `iwsdk.scene.v1`, in meters. Scene JSON is composition data. The
21
+ runtime projection strips `authoring` and hashes canonical JSON for runtime identity.
22
+
23
+ ## Document Boundary
24
+
25
+ ```json
26
+ {
27
+ "version": "iwsdk.scene.v1",
28
+ "units": "meters",
29
+ "components": {
30
+ "com.iwsdk.components.DomeGradient": {
31
+ "sky": [0.2423, 0.6172, 0.8308, 1],
32
+ "equator": [0.6584, 0.7084, 0.7913, 1],
33
+ "ground": [0.807, 0.7758, 0.7454, 1],
34
+ "intensity": 1
35
+ },
36
+ "com.iwsdk.components.IBLGradient": {
37
+ "sky": [0.6902, 0.749, 0.7843, 1],
38
+ "equator": [0.6584, 0.7084, 0.7913, 1],
39
+ "ground": [0.807, 0.7758, 0.7454, 1],
40
+ "intensity": 1
41
+ }
42
+ },
43
+ "metadata": {},
44
+ "authoring": {},
45
+ "resources": { "prefabs": [] },
46
+ "environment": {},
47
+ "nodes": []
48
+ }
49
+ ```
50
+
51
+ - `components` apply to the actual IWSDK level-root entity. `DomeGradient` and
52
+ `IBLGradient` are normal removable components, not editor-only environment fields.
53
+ - `DomeFade` is a node component, not a root one: put
54
+ `"com.iwsdk.components.DomeFade": { "start": 4, "end": 10 }` on a floor or
55
+ terrain node to fade that node's own meshes into the root `DomeGradient` sky.
56
+ - `LevelRoot`, `LevelTag`, and `Transform` are runtime-owned and must not appear in
57
+ `components`.
58
+ - `ContactShadow` (a soft blob under a node) and `ShadowCatcher` (an invisible AR
59
+ floor that shows received shadows) are node components: put them on the grounded
60
+ node or a floor node, not in root `components`.
61
+ - `resources` contains only reusable scene prefabs.
62
+ - Use namespaced keys in opaque `metadata`. Do not hide structural fields there.
63
+ - Structural objects are closed. Unknown fields fail validation.
64
+
65
+ ## Asset Boundary
66
+
67
+ Scene JSON never declares assets, URLs, geometry, or materials. Those live in the
68
+ `defineAssets()` module selected by `iwsdk.config.json` at `assets.module`.
69
+
70
+ Valid renderable content references a manifest ID:
71
+
72
+ ```json
73
+ {
74
+ "id": "hero-chair",
75
+ "name": "Hero reading chair",
76
+ "content": {
77
+ "type": "asset",
78
+ "asset": "reading-chair",
79
+ "castShadow": true,
80
+ "receiveShadow": true
81
+ },
82
+ "transform": {
83
+ "position": [0.6, 0, -0.8],
84
+ "rotationDeg": [0, -18, 0],
85
+ "scale": 1
86
+ }
87
+ }
88
+ ```
89
+
90
+ The `asset` string is application-global. It is not namespaced when a scene module is
91
+ imported. The editor validates it against the live manifest and derives bounds from
92
+ the registered object.
93
+
94
+ The following old branches are invalid and must never be emitted:
95
+
96
+ - `content.type: "model"`;
97
+ - `content.type: "primitive"`;
98
+ - `resources.assets`;
99
+ - `resources.materials`;
100
+ - node or prefab material overrides.
101
+
102
+ Create procedural shapes and custom PBR/shader materials in TypeScript, register the
103
+ resulting parentless `Object3D`, then reference its asset ID. See
104
+ `iwsdk-build-model`.
105
+
106
+ ## Nodes And Content
107
+
108
+ Every node has a stable `id` and may contain `name`, `content`, `transform`,
109
+ `constraints`, `components`, `metadata`, `framingRole`, and `children`.
110
+
111
+ Supported content kinds are:
112
+
113
+ ### Group
114
+
115
+ ```json
116
+ { "id": "furniture", "content": { "type": "group" }, "children": [] }
117
+ ```
118
+
119
+ A group has no visible surface. It cannot prove presence, silhouette, support, or
120
+ framing by itself.
121
+
122
+ ### Asset
123
+
124
+ ```json
125
+ {
126
+ "id": "table",
127
+ "content": {
128
+ "type": "asset",
129
+ "asset": "round-side-table",
130
+ "castShadow": true,
131
+ "receiveShadow": false
132
+ }
133
+ }
134
+ ```
135
+
136
+ Shadow flags default to false. Opt in only where the shadow contributes to the scene.
137
+
138
+ ### Prefab Instance
139
+
140
+ ```json
141
+ {
142
+ "id": "left-chair",
143
+ "content": {
144
+ "type": "instance",
145
+ "prefab": "chair-with-cushion",
146
+ "overrides": {
147
+ "cushion": {
148
+ "transform": { "position": [0, 0.03, 0] },
149
+ "visible": true
150
+ }
151
+ }
152
+ }
153
+ }
154
+ ```
155
+
156
+ Overrides may adjust transforms, visibility, and component payloads. They cannot
157
+ change geometry or materials.
158
+
159
+ ### Pattern
160
+
161
+ ```json
162
+ {
163
+ "id": "books",
164
+ "content": {
165
+ "type": "pattern",
166
+ "prefab": "book",
167
+ "distribution": {
168
+ "type": "linear",
169
+ "count": 12,
170
+ "step": [0.065, 0, 0]
171
+ }
172
+ }
173
+ }
174
+ ```
175
+
176
+ Supported distributions are capability-defined and normally include `linear`,
177
+ `grid`, `radial`, `along-path`, `scatter`, and `explicit`. Scatter uses an explicit
178
+ seed and algorithm. Use `collision: "allow"` or `"skip"` deliberately.
179
+
180
+ ### Light
181
+
182
+ Lights are ECS components on otherwise ordinary scene nodes. The node transform
183
+ positions the light; directional, spot, and rectangular area lights emit along
184
+ the node's local `-Z` axis.
185
+
186
+ ```json
187
+ {
188
+ "id": "key-light",
189
+ "transform": {
190
+ "position": [2, 4, 3],
191
+ "rotationDeg": [55, -45, 0]
192
+ },
193
+ "components": {
194
+ "com.iwsdk.components.DirectionalLight": {
195
+ "color": [1, 0.897, 0.738, 1],
196
+ "intensity": 2.2,
197
+ "castShadow": true,
198
+ "shadowMapSize": "1024"
199
+ }
200
+ }
201
+ }
202
+ ```
203
+
204
+ The built-in component IDs are `AmbientLight`, `HemisphereLight`,
205
+ `DirectionalLight`, `PointLight`, `SpotLight`, and `RectAreaLight`, each under
206
+ the `com.iwsdk.components` namespace. Component colors are linear RGBA arrays.
207
+ Use root IBL for general PBR response and authored lights for composition.
208
+
209
+ Structural objects are closed, so an unknown field fails validation. The exact
210
+ fields are:
211
+
212
+ | Component | Fields |
213
+ | --- | --- |
214
+ | `AmbientLight` | `color`, `intensity` |
215
+ | `HemisphereLight` | `skyColor`, `groundColor`, `intensity` |
216
+ | `DirectionalLight` | `color`, `intensity`, `shadowCameraSize`, + shadow set |
217
+ | `PointLight` | `color`, `intensity` (candela), `distance`, `decay`, + shadow set |
218
+ | `SpotLight` | `color`, `intensity` (candela), `distance`, `decay`, `angleDeg`, `penumbra`, + shadow set |
219
+ | `RectAreaLight` | `color`, `intensity` (nit), `width`, `height` — no shadows |
220
+
221
+ The shadow set is `castShadow`, `shadowMapSize` (enum string `"256"`, `"512"`,
222
+ `"1024"`, `"2048"`), `shadowBias`, `shadowNormalBias`, `shadowRadius`,
223
+ `shadowCameraNear`, `shadowCameraFar`. `AmbientLight` and `HemisphereLight`
224
+ ignore the node transform.
225
+
226
+ ## Prefabs And Patterns
227
+
228
+ Prefabs are the only scene-local resource:
229
+
230
+ ```json
231
+ {
232
+ "resources": {
233
+ "prefabs": [
234
+ {
235
+ "id": "book",
236
+ "root": {
237
+ "id": "book-root",
238
+ "content": { "type": "asset", "asset": "hardcover-book" }
239
+ }
240
+ },
241
+ {
242
+ "id": "chair-with-cushion",
243
+ "root": {
244
+ "id": "chair-root",
245
+ "content": { "type": "asset", "asset": "reading-chair" },
246
+ "children": [
247
+ {
248
+ "id": "cushion",
249
+ "content": { "type": "asset", "asset": "chair-cushion" }
250
+ }
251
+ ]
252
+ }
253
+ }
254
+ ]
255
+ }
256
+ }
257
+ ```
258
+
259
+ Prefab node IDs are local until instantiated. Runtime IDs are derived
260
+ deterministically. Do not author IDs that collide with derived paths such as
261
+ `chairs/0000/book-root`.
262
+
263
+ A pattern may become one `InstancedMesh` when its prefab resolves to one eligible
264
+ mesh. Component-bearing or compound prefabs expand to distinct cloned hierarchies.
265
+
266
+ ## Authoring-Only Imports
267
+
268
+ ```json
269
+ {
270
+ "imports": [
271
+ {
272
+ "id": "nook",
273
+ "src": "./modules/nook.iwsdk.scene.json",
274
+ "transform": { "position": [2, 0, -1] }
275
+ }
276
+ ]
277
+ }
278
+ ```
279
+
280
+ Each imported file must be a valid standalone v1 scene. Imports are permitted only in
281
+ scratch composition documents rendered by authoring tools; the editable final scene
282
+ and application runtime reject them. Imports resolve recursively in declaration order.
283
+ Node and prefab IDs are namespaced as
284
+ `<import-id>/<local-id>`. Asset and component IDs remain unchanged and
285
+ application-global.
286
+
287
+ The import entry becomes a group wrapper carrying the import transform. The root owns
288
+ top-level components, environment, metadata, and authoring globals; module globals do
289
+ not override them. Once the composition passes, flatten and make the generated
290
+ import-free document the sole source of truth. Never re-flatten over later editor
291
+ changes.
292
+
293
+ Use `scene_flatten_file` or `npx @iwsdk/cli scene flatten` to materialize the final
294
+ document. The command resolves the import graph, preserves wrapper transforms,
295
+ validates the flat output, writes atomically, and refuses the write if flattening
296
+ changes runtime semantics.
297
+
298
+ Verify the flatten preserved semantics by comparing `runtimeHash` before and
299
+ after — they must be identical. Note that only `authoring` and `imports` are
300
+ stripped from the runtime projection, so writing provenance into `metadata`
301
+ changes the hash and defeats this check.
302
+
303
+ ## Components And Constraints
304
+
305
+ Component keys use their registered IWSDK IDs. Values are the component's raw props:
306
+
307
+ ```json
308
+ {
309
+ "components": {
310
+ "com.iwsdk.components.Visibility": {
311
+ "isVisible": true
312
+ }
313
+ }
314
+ }
315
+ ```
316
+
317
+ Scene files never embed component schemas. Declare application components in a
318
+ system-free module, export a manifest with `defineComponents`, and give that same
319
+ manifest to the runtime and Vite plugin:
320
+
321
+ ```ts
322
+ // src/components.ts
323
+ import { defineComponents } from '@iwsdk/core';
324
+ import { ReadingState } from './components/reading-state.js';
325
+
326
+ export default defineComponents([ReadingState]);
327
+ ```
328
+
329
+ ```ts
330
+ // iwsdk.config.json points components.module at ./src/components
331
+ // runtime and editor both consume virtual:iwsdk-project
332
+ import projectOptions from 'virtual:iwsdk-project';
333
+ World.create(container, projectOptions);
334
+ ```
335
+
336
+ The editor and runtime independently import the same manifest and derive validation
337
+ and inspector metadata from the executable component declarations. Component IDs must
338
+ be unique across IWSDK and the application. Keep declaration modules free of system,
339
+ DOM, renderer, and world side effects; systems may import those declarations.
340
+
341
+ Transforms use `[x, y, z]` tuples, degrees, and positive scalar or vector scale.
342
+ The optional `lookAt` constraint resolves yaw deterministically during lowering:
343
+
344
+ ```json
345
+ {
346
+ "constraints": {
347
+ "lookAt": { "mode": "yaw-v1", "target": [0, 1.2, 0] }
348
+ }
349
+ }
350
+ ```
351
+
352
+ Author spatial relationships directly through node transforms. The schema does not
353
+ infer support, floor contact, or other physical-placement semantics.
354
+
355
+ ## Authoring And Review
356
+
357
+ Use `authoring.composition` as a fixed brief, not a process transcript:
358
+
359
+ ```json
360
+ {
361
+ "authoring": {
362
+ "composition": {
363
+ "mode": "static",
364
+ "input": {
365
+ "kind": "hybrid",
366
+ "prompt": "A courtyard reading nook",
367
+ "references": []
368
+ },
369
+ "target": {
370
+ "surfaces": ["browser", "vr"],
371
+ "style": "stylized-pbr",
372
+ "assetPolicy": "manifest-assets"
373
+ },
374
+ "feasibility": { "status": "supported" },
375
+ "provenance": {
376
+ "adapter": { "id": "hybrid-intake", "version": "1.0.0" },
377
+ "skill": { "id": "iwsdk-compose-scene", "version": "1.0.0" },
378
+ "capabilityHash": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
379
+ "inputHashes": []
380
+ },
381
+ "representationPolicy": {
382
+ "fidelityCeiling": "stylized-static",
383
+ "allowed": ["asset", "prefab", "pattern"]
384
+ },
385
+ "features": [],
386
+ "assumptions": [],
387
+ "review": {
388
+ "heroView": "hero",
389
+ "requiredViews": ["hero", "top", "quarter"],
390
+ "lenses": ["layout", "geometry", "final"],
391
+ "maxCorrectionRounds": 2
392
+ }
393
+ },
394
+ "views": []
395
+ }
396
+ }
397
+ ```
398
+
399
+ `inputHashes` is the exact unique set of the prompt SHA-256, when present, plus every
400
+ declared reference digest with a `sha256:` prefix. Changing prompt whitespace changes
401
+ identity.
402
+
403
+ Every required feature needs implementation node bindings and immutable acceptance
404
+ criteria. Supported kinds normally include presence, count, projected-region,
405
+ spatial-relation, and visual-judgment.
406
+
407
+ Use `capture-node-mask-bounds-v1` for projected region evidence of manifest assets.
408
+ Their arbitrary external geometry cannot be proven from a JSON world-AABB assumption.
409
+
410
+ Authoring views contain exact projection parameters. Perspective views use position,
411
+ target, and FOV. Orthographic views use position, target, and height. Pass a saved
412
+ `viewId` to camera or screenshot tools rather than approximating it with a preset.
413
+ The separate `view` field accepts only built-in preset names. Outside immersive XR,
414
+ the runtime applies the scene's hero view after level initialization, so adjust that
415
+ authored view when editor and browser framing need to stay in parity; an initial
416
+ `World.create` camera is not an override for a scene-owned camera. In XR the tracked
417
+ player rig owns the camera, so separately inspect framing from the authored player
418
+ spawn.
419
+
420
+ ```json
421
+ {
422
+ "authoring": {
423
+ "views": [
424
+ {
425
+ "id": "hero",
426
+ "role": "hero",
427
+ "projection": "perspective",
428
+ "position": [0, 1.6, 4.5],
429
+ "target": [0, 1.4, 0],
430
+ "fov": 42
431
+ },
432
+ {
433
+ "id": "top",
434
+ "role": "diagnostic",
435
+ "projection": "orthographic",
436
+ "position": [0, 8, 0],
437
+ "target": [0, 0, 0],
438
+ "height": 8
439
+ }
440
+ ]
441
+ }
442
+ }
443
+ ```
444
+
445
+ `nodeAnnotations` bind actual nodes to layout, geometry, or final review layers.
446
+ Unannotated renderables default to layout; descendants inherit the nearest annotation.
447
+
448
+ Every node may set `framingRole` to `content` or `support`. Use support only for
449
+ rendered infrastructure such as an oversized floor or backdrop. Requested subjects
450
+ must remain content.
451
+
452
+ ## Validation Traps
453
+
454
+ - Do not put `assets` or `materials` under `resources`.
455
+ - Do not emit model, primitive, geometry, material, or material override fields.
456
+ - Do not assume that a file in `public/` is registered; check `src/assets.ts`.
457
+ - Do not use a group as the only binding for a required visible feature.
458
+ - Do not namespace manifest asset IDs inside imported modules.
459
+ - Do not open or load an import-bearing composition as the editable/runtime scene;
460
+ flatten it first.
461
+ - Do not author duplicate or derived runtime IDs.
462
+ - Do not use non-finite transforms, unsafe paths, or unknown
463
+ component fields.
464
+ - Do not claim projected AABB silhouette evidence for arbitrary manifest assets; use
465
+ trusted capture node masks.
466
+ - Do not save over unsaved human editor changes. Resolve the reported conflict first.
@@ -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.
@@ -0,0 +1,80 @@
1
+ # Text Intake
2
+
3
+ Use this adapter when the user supplies no visual reference. Text defines design
4
+ intent; do not invent a source-fidelity target or camera-confidence score.
5
+
6
+ ## Extract The Brief
7
+
8
+ Record:
9
+
10
+ - required objects and recognizable systems;
11
+ - spatial relations: beside, behind, centered, crossing, enclosing, supporting;
12
+ - counts, approximate scale, and one scale anchor;
13
+ - target surface: browser, VR, AR, or shared;
14
+ - style, palette, and material intent;
15
+ - desired hero view or application view when stated;
16
+ - existing glTF/procedural assets versus new asset-authoring needs;
17
+ - exclusions and non-goals;
18
+ - performance constraints stated by the user or calibrated target profile.
19
+
20
+ Performance constraints are not a first-class authoring branch in the scene format. Put user
21
+ constraints in `metadata["iwsdk.composer.performanceLimits"]` as JSON, or retain them
22
+ in the external cost report. Never present an uncalibrated desktop threshold as a
23
+ device profile.
24
+
25
+ Convert ambiguous but nonblocking choices into explicit assumptions with
26
+ `high | medium | low` certainty. Ask only when different interpretations would change
27
+ a required feature or make the request unsupported.
28
+
29
+ ## Define Features
30
+
31
+ Create 3-8 required or important features that make the request recognizably correct.
32
+ Prefer observable results:
33
+
34
+ - `crossroads`: two roads intersect at right angles with four pedestrian crossings;
35
+ - `relative-height`: apartment building is at least twice the house height;
36
+ - `reading-cluster`: chair, lamp, and side table form one reachable cluster;
37
+ - `arch-opening`: path passes visibly through the stone arch;
38
+ - `vehicle-heading`: car points along the east-west road.
39
+
40
+ Bind each feature to planned node IDs and typed acceptance criteria. Avoid vague
41
+ criteria such as "looks good" or "high quality."
42
+
43
+ ## Select A Representation
44
+
45
+ Call `scene_get_capabilities`, inspect the configured asset manifest, then choose in
46
+ this order:
47
+
48
+ 1. reuse a registered glTF or procedural asset when it satisfies the required form;
49
+ 2. invoke `iwsdk-build-model` when identity, geometry, or material response is missing;
50
+ 3. assemble registered assets in a scene prefab for a reusable semantic object;
51
+ 4. use a deterministic pattern for repeated compatible prefabs;
52
+ 5. accept an approximation with a named fidelity ceiling;
53
+ 6. block when a required feature has no supportable representation.
54
+
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.
57
+
58
+ ## Establish Scale And Coordinates
59
+
60
+ Use `+Y` up. Choose a semantic origin such as scene center, floor center, or crossing
61
+ center. Put group origins where later editing is natural. Use conventional dimensions
62
+ only when the prompt supplies no evidence; record those values as assumptions.
63
+
64
+ The persistent player origin materializes at `[0, 0, 0]` unless the top-level
65
+ `player.transform` deliberately moves it. A semantic scene center is therefore not
66
+ automatically a safe object center: keep a standing capsule around the authored
67
+ player origin clear, or move the player to a deliberate spawn. Include an exact
68
+ spawn review view at player eye height (about 1.6 m above the origin) looking into
69
+ the composition; hero cameras do not substitute for this check.
70
+
71
+ Text-only scenes need at least one hero view plus diagnostic top, quarter, and player
72
+ spawn views.
73
+ The hero view is a design choice, not a match to an imaginary source image.
74
+
75
+ ## Review Text-Only Output
76
+
77
+ Use deterministic hierarchy, count, support, relation, bounds, and runtime checks.
78
+ Agent visual judgment evaluates composition and legibility against the written
79
+ criteria, not similarity to an absent reference. Do not use IoU, SSIM, pHash, or
80
+ camera-fit metrics.
@@ -0,0 +1,74 @@
1
+ ---
2
+ name: iwsdk-debug
3
+ description: Diagnose and verify real-time IWSDK behavior with bounded ECS pause, query, snapshot, step, and diff loops. Use for physics, animation, collision, interaction, or state bugs that cannot be proven from a screenshot.
4
+ argument-hint: '(use the current request)'
5
+ ---
6
+
7
+ # IWSDK Runtime Debugging
8
+
9
+ Use the current request. The goal is a reproducible observation, the smallest
10
+ supported fix, and one matching replay—not an open-ended trace session.
11
+
12
+ ## 1. Establish one failing observation
13
+
14
+ Start the managed app once and enter XR only if required. Locate and query the
15
+ named entities and relevant systems. Freeze time as early as possible:
16
+
17
+ 1. `ecs_pause`
18
+ 2. `ecs_snapshot` with label `before`
19
+ 3. trigger or prepare the failing transition
20
+ 4. `ecs_step` for 1-3 frames at `0.016`
21
+ 5. `ecs_snapshot` with label `after`
22
+ 6. `ecs_diff` from `before` to `after`
23
+
24
+ Query the affected entity after the diff. For a startup failure that has already
25
+ occurred, record the bad live transform first, then use the next clean restart
26
+ for the frame-stepped observation. A screenshot can clarify geometry but is not
27
+ a substitute for ECS evidence.
28
+
29
+ ## 2. Form and test one hypothesis
30
+
31
+ Inspect only the configuration, scene node, component, or system implicated by
32
+ the measured change. Check the invariant before editing: colliders need both
33
+ body and shape, dynamic motion needs the correct state, interactions need the
34
+ matching input/component path, and animations need the responsible system to
35
+ be running. Do not browse framework internals while an authored invariant
36
+ already explains the evidence.
37
+
38
+ Use the common authored physics forms directly instead of dumping scene
39
+ capabilities: a detailed static environment normally pairs
40
+ `PhysicsBody: { "state": "STATIC" }` with
41
+ `PhysicsShape: { "shape": "TriMesh" }`; dynamic objects use a supported convex
42
+ or primitive shape. Query live components after reload to verify registration.
43
+
44
+ Make the smallest project edit that restores that invariant. Avoid unrelated
45
+ cleanup, visual redesign, or defensive rewrites.
46
+
47
+ Do not inspect IWSDK framework source, Vite plugin internals, or CLI help when a
48
+ missing authored component already explains the measured state. Use public
49
+ component data and the project files as the debugging boundary.
50
+ For a local authored-component fix, do not request the full scene capability or
51
+ scene-state payload; the source diff, production build, and focused live entity
52
+ query provide the required evidence.
53
+
54
+ ## 3. Replay the same probe
55
+
56
+ After editing, do not run an intermediate replay. Run the production build,
57
+ restart once, and repeat the same pause → snapshot → step → snapshot → diff
58
+ sequence with the same labels and timestep. Compare the same fields and query
59
+ the final entity. This gives exactly two probes: one failing observation and one
60
+ post-build replay. Capture one final runtime screenshot if position or collision
61
+ is visually relevant.
62
+
63
+ The build is the production-build proof; do not launch a second Vite preview
64
+ server. Replay with the same managed IWSDK dev runtime. Save file evidence with
65
+ `npx @iwsdk/cli browser screenshot --output-file <path>` rather than discovering the
66
+ screenshot CLI after the debug loop. When ECS evidence already proves the fix,
67
+ do not open or read the PNG back into model context; leave it for evaluator or
68
+ human review. Inspect one compact image only when the spatial result cannot be
69
+ established from the measured state.
70
+
71
+ Make at most one focused correction. Stop when the original symptom no longer
72
+ reproduces and the measured state agrees with the intended behavior. Call
73
+ `ecs_resume` before finishing and leave input buttons released.
74
+ <!-- iwsdk-agent-guidance version=1.2.0-rc.1 sha256=7dd8250ca95e23b6f0696a86a3dfcb2d038ac730a7578118fb21290c6169c3f0 name=iwsdk-debug (installed by IWSDK; `npx @iwsdk/cli@latest agents sync` refreshes it and leaves it alone once edited) -->