@iwsdk/create 0.4.2 → 0.5.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 (107) hide show
  1. package/README.md +103 -41
  2. package/dist/cli.js +1003 -3418
  3. package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +96 -0
  4. package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +135 -0
  5. package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +129 -0
  6. package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -0
  7. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/component-reference.md +154 -0
  8. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +88 -0
  9. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/workflows.md +303 -0
  10. package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +364 -0
  11. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/api-reference.md +1489 -0
  12. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +241 -0
  13. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +101 -0
  14. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +176 -0
  15. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +156 -0
  16. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +199 -0
  17. package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +159 -0
  18. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +255 -0
  19. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +5 -0
  20. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +295 -0
  21. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +243 -0
  22. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/image-intake.md +191 -0
  23. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +99 -0
  24. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/scene-format.md +458 -0
  25. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/text-intake.md +82 -0
  26. package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +208 -0
  27. package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +450 -0
  28. package/dist/guidance/claude/.claude/rules/assets-and-manifest.md +55 -0
  29. package/dist/guidance/claude/.claude/rules/ecs-api.md +102 -0
  30. package/dist/guidance/claude/.claude/rules/scene-json.md +64 -0
  31. package/dist/guidance/claude/.claude/rules/uikitml.md +60 -0
  32. package/dist/guidance/claude/.claude/settings.json +19 -0
  33. package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +96 -0
  34. package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +135 -0
  35. package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +129 -0
  36. package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -0
  37. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/component-reference.md +154 -0
  38. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +88 -0
  39. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/workflows.md +303 -0
  40. package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +364 -0
  41. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/api-reference.md +1489 -0
  42. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +241 -0
  43. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +101 -0
  44. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +176 -0
  45. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +156 -0
  46. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +199 -0
  47. package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +159 -0
  48. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +255 -0
  49. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +5 -0
  50. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +295 -0
  51. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +243 -0
  52. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/image-intake.md +191 -0
  53. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +99 -0
  54. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/scene-format.md +458 -0
  55. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/text-intake.md +82 -0
  56. package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +208 -0
  57. package/dist/guidance/claude/CLAUDE.md +142 -0
  58. package/dist/guidance/codex/.codex/config.toml +2 -0
  59. package/dist/guidance/common/AGENTS.md +151 -0
  60. package/dist/guidance/copilot/.github/instructions/assets-and-manifest.instructions.md +52 -0
  61. package/dist/guidance/copilot/.github/instructions/ecs-api.instructions.md +100 -0
  62. package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +63 -0
  63. package/dist/guidance/copilot/.github/instructions/uikitml.instructions.md +59 -0
  64. package/dist/guidance/cursor/.cursor/rules/assets-and-manifest.mdc +57 -0
  65. package/dist/guidance/cursor/.cursor/rules/ecs-api.mdc +104 -0
  66. package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +66 -0
  67. package/dist/guidance/cursor/.cursor/rules/uikitml.mdc +62 -0
  68. package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +63 -0
  69. package/dist/guidance/scoped-agents/public/ui/AGENTS.md +59 -0
  70. package/dist/guidance/scoped-agents/src/AGENTS.md +149 -0
  71. package/dist/template/common/README.md +13 -0
  72. package/dist/template/common/gitignore.template +45 -0
  73. package/dist/template/common/index.html +16 -0
  74. package/dist/template/common/nvmrc.template +1 -0
  75. package/dist/template/common/public/audio/chime.mp3 +0 -0
  76. package/dist/template/common/public/gltf/webxr-banner/banner.gltf +68 -0
  77. package/dist/template/common/public/textures/webxr.png +0 -0
  78. package/dist/template/common/public/ui/welcome.uikitml +98 -0
  79. package/dist/template/common/src/assets.ts +54 -0
  80. package/dist/template/common/src/components.ts +11 -0
  81. package/dist/template/common/src/index.ts +19 -0
  82. package/dist/template/common/src/panel.ts +38 -0
  83. package/dist/template/common/src/robot-component.ts +10 -0
  84. package/dist/template/common/src/robot.ts +38 -0
  85. package/dist/template/common/src/vite-env.d.ts +2 -0
  86. package/dist/template/common/tsconfig.json +15 -0
  87. package/dist/template/common/vite.config.ts +27 -0
  88. package/dist/template/common-js/README.md +13 -0
  89. package/dist/template/common-js/gitignore.template +45 -0
  90. package/dist/template/common-js/index.html +16 -0
  91. package/dist/template/common-js/nvmrc.template +1 -0
  92. package/dist/template/common-js/public/audio/chime.mp3 +0 -0
  93. package/dist/template/common-js/public/gltf/webxr-banner/banner.gltf +68 -0
  94. package/dist/template/common-js/public/textures/webxr.png +0 -0
  95. package/dist/template/common-js/public/ui/welcome.uikitml +98 -0
  96. package/dist/template/common-js/src/assets.js +45 -0
  97. package/dist/template/common-js/src/components.js +9 -0
  98. package/dist/template/common-js/src/index.js +14 -0
  99. package/dist/template/common-js/src/panel.js +31 -0
  100. package/dist/template/common-js/src/robot-component.js +8 -0
  101. package/dist/template/common-js/src/robot.js +37 -0
  102. package/dist/template/common-js/vite.config.js +25 -0
  103. package/dist/template/scenes/ar.iwsdk.scene.json +96 -0
  104. package/dist/template/scenes/immersive.iwsdk.scene.json +109 -0
  105. package/package.json +23 -17
  106. package/scripts/verify-release-ready.mjs +76 -0
  107. package/LICENSE +0 -21
@@ -0,0 +1,458 @@
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
+ - `LevelRoot`, `LevelTag`, and `Transform` are runtime-owned and must not appear in
54
+ `components`.
55
+ - `resources` contains only reusable scene prefabs.
56
+ - Use namespaced keys in opaque `metadata`. Do not hide structural fields there.
57
+ - Structural objects are closed. Unknown fields fail validation.
58
+
59
+ ## Asset Boundary
60
+
61
+ Scene JSON never declares assets, URLs, geometry, or materials. Those live in the
62
+ `defineAssets()` module selected by `iwsdk.config.json` at `assets.module`.
63
+
64
+ Valid renderable content references a manifest ID:
65
+
66
+ ```json
67
+ {
68
+ "id": "hero-chair",
69
+ "name": "Hero reading chair",
70
+ "content": {
71
+ "type": "asset",
72
+ "asset": "reading-chair",
73
+ "castShadow": true,
74
+ "receiveShadow": true
75
+ },
76
+ "transform": {
77
+ "position": [0.6, 0, -0.8],
78
+ "rotationDeg": [0, -18, 0],
79
+ "scale": 1
80
+ }
81
+ }
82
+ ```
83
+
84
+ The `asset` string is application-global. It is not namespaced when a scene module is
85
+ imported. The editor validates it against the live manifest and derives bounds from
86
+ the registered object.
87
+
88
+ The following old branches are invalid and must never be emitted:
89
+
90
+ - `content.type: "model"`;
91
+ - `content.type: "primitive"`;
92
+ - `resources.assets`;
93
+ - `resources.materials`;
94
+ - node or prefab material overrides.
95
+
96
+ Create procedural shapes and custom PBR/shader materials in TypeScript, register the
97
+ resulting parentless `Object3D`, then reference its asset ID. See
98
+ [asset-authoring.md](asset-authoring.md).
99
+
100
+ ## Nodes And Content
101
+
102
+ Every node has a stable `id` and may contain `name`, `content`, `transform`,
103
+ `constraints`, `components`, `metadata`, `framingRole`, and `children`.
104
+
105
+ Supported content kinds are:
106
+
107
+ ### Group
108
+
109
+ ```json
110
+ { "id": "furniture", "content": { "type": "group" }, "children": [] }
111
+ ```
112
+
113
+ A group has no visible surface. It cannot prove presence, silhouette, support, or
114
+ framing by itself.
115
+
116
+ ### Asset
117
+
118
+ ```json
119
+ {
120
+ "id": "table",
121
+ "content": {
122
+ "type": "asset",
123
+ "asset": "round-side-table",
124
+ "castShadow": true,
125
+ "receiveShadow": false
126
+ }
127
+ }
128
+ ```
129
+
130
+ Shadow flags default to false. Opt in only where the shadow contributes to the scene.
131
+
132
+ ### Prefab Instance
133
+
134
+ ```json
135
+ {
136
+ "id": "left-chair",
137
+ "content": {
138
+ "type": "instance",
139
+ "prefab": "chair-with-cushion",
140
+ "overrides": {
141
+ "cushion": {
142
+ "transform": { "position": [0, 0.03, 0] },
143
+ "visible": true
144
+ }
145
+ }
146
+ }
147
+ }
148
+ ```
149
+
150
+ Overrides may adjust transforms, visibility, and component payloads. They cannot
151
+ change geometry or materials.
152
+
153
+ ### Pattern
154
+
155
+ ```json
156
+ {
157
+ "id": "books",
158
+ "content": {
159
+ "type": "pattern",
160
+ "prefab": "book",
161
+ "distribution": {
162
+ "type": "linear",
163
+ "count": 12,
164
+ "step": [0.065, 0, 0]
165
+ }
166
+ }
167
+ }
168
+ ```
169
+
170
+ Supported distributions are capability-defined and normally include `linear`,
171
+ `grid`, `radial`, `along-path`, `scatter`, and `explicit`. Scatter uses an explicit
172
+ seed and algorithm. Use `collision: "allow"` or `"skip"` deliberately.
173
+
174
+ ### Light
175
+
176
+ Lights are ECS components on otherwise ordinary scene nodes. The node transform
177
+ positions the light; directional, spot, and rectangular area lights emit along
178
+ the node's local `-Z` axis.
179
+
180
+ ```json
181
+ {
182
+ "id": "key-light",
183
+ "transform": {
184
+ "position": [2, 4, 3],
185
+ "rotationDeg": [55, -45, 0]
186
+ },
187
+ "components": {
188
+ "com.iwsdk.components.DirectionalLight": {
189
+ "color": [1, 0.897, 0.738, 1],
190
+ "intensity": 2.2,
191
+ "castShadow": true,
192
+ "shadowMapSize": "1024"
193
+ }
194
+ }
195
+ }
196
+ ```
197
+
198
+ The built-in component IDs are `AmbientLight`, `HemisphereLight`,
199
+ `DirectionalLight`, `PointLight`, `SpotLight`, and `RectAreaLight`, each under
200
+ the `com.iwsdk.components` namespace. Component colors are linear RGBA arrays.
201
+ Use root IBL for general PBR response and authored lights for composition.
202
+
203
+ Structural objects are closed, so an unknown field fails validation. The exact
204
+ fields are:
205
+
206
+ | Component | Fields |
207
+ | --- | --- |
208
+ | `AmbientLight` | `color`, `intensity` |
209
+ | `HemisphereLight` | `skyColor`, `groundColor`, `intensity` |
210
+ | `DirectionalLight` | `color`, `intensity`, `shadowCameraSize`, + shadow set |
211
+ | `PointLight` | `color`, `intensity` (candela), `distance`, `decay`, + shadow set |
212
+ | `SpotLight` | `color`, `intensity` (candela), `distance`, `decay`, `angleDeg`, `penumbra`, + shadow set |
213
+ | `RectAreaLight` | `color`, `intensity` (nit), `width`, `height` — no shadows |
214
+
215
+ The shadow set is `castShadow`, `shadowMapSize` (enum string `"256"`, `"512"`,
216
+ `"1024"`, `"2048"`), `shadowBias`, `shadowNormalBias`, `shadowRadius`,
217
+ `shadowCameraNear`, `shadowCameraFar`. `AmbientLight` and `HemisphereLight`
218
+ ignore the node transform.
219
+
220
+ ## Prefabs And Patterns
221
+
222
+ Prefabs are the only scene-local resource:
223
+
224
+ ```json
225
+ {
226
+ "resources": {
227
+ "prefabs": [
228
+ {
229
+ "id": "book",
230
+ "root": {
231
+ "id": "book-root",
232
+ "content": { "type": "asset", "asset": "hardcover-book" }
233
+ }
234
+ },
235
+ {
236
+ "id": "chair-with-cushion",
237
+ "root": {
238
+ "id": "chair-root",
239
+ "content": { "type": "asset", "asset": "reading-chair" },
240
+ "children": [
241
+ {
242
+ "id": "cushion",
243
+ "content": { "type": "asset", "asset": "chair-cushion" }
244
+ }
245
+ ]
246
+ }
247
+ }
248
+ ]
249
+ }
250
+ }
251
+ ```
252
+
253
+ Prefab node IDs are local until instantiated. Runtime IDs are derived
254
+ deterministically. Do not author IDs that collide with derived paths such as
255
+ `chairs/0000/book-root`.
256
+
257
+ A pattern may become one `InstancedMesh` when its prefab resolves to one eligible
258
+ mesh. Component-bearing or compound prefabs expand to distinct cloned hierarchies.
259
+
260
+ ## Authoring-Only Imports
261
+
262
+ ```json
263
+ {
264
+ "imports": [
265
+ {
266
+ "id": "nook",
267
+ "src": "./modules/nook.iwsdk.scene.json",
268
+ "transform": { "position": [2, 0, -1] }
269
+ }
270
+ ]
271
+ }
272
+ ```
273
+
274
+ Each imported file must be a valid standalone v1 scene. Imports are permitted only in
275
+ scratch composition documents rendered by authoring tools; the editable final scene
276
+ and application runtime reject them. Imports resolve recursively in declaration order.
277
+ Node and prefab IDs are namespaced as
278
+ `<import-id>/<local-id>`. Asset and component IDs remain unchanged and
279
+ application-global.
280
+
281
+ The import entry becomes a group wrapper carrying the import transform. The root owns
282
+ top-level components, environment, metadata, and authoring globals; module globals do
283
+ not override them. Once the composition passes, flatten and make the generated
284
+ import-free document the sole source of truth. Never re-flatten over later editor
285
+ changes.
286
+
287
+ Use `scene_flatten_file` or `npx iwsdk scene flatten` to materialize the final
288
+ document. The command resolves the import graph, preserves wrapper transforms,
289
+ validates the flat output, writes atomically, and refuses the write if flattening
290
+ changes runtime semantics.
291
+
292
+ Verify the flatten preserved semantics by comparing `runtimeHash` before and
293
+ after — they must be identical. Note that only `authoring` and `imports` are
294
+ stripped from the runtime projection, so writing provenance into `metadata`
295
+ changes the hash and defeats this check.
296
+
297
+ ## Components And Constraints
298
+
299
+ Component keys use their registered IWSDK IDs. Values are the component's raw props:
300
+
301
+ ```json
302
+ {
303
+ "components": {
304
+ "com.iwsdk.components.Visibility": {
305
+ "isVisible": true
306
+ }
307
+ }
308
+ }
309
+ ```
310
+
311
+ Scene files never embed component schemas. Declare application components in a
312
+ system-free module, export a manifest with `defineComponents`, and give that same
313
+ manifest to the runtime and Vite plugin:
314
+
315
+ ```ts
316
+ // src/components.ts
317
+ import { defineComponents } from '@iwsdk/core';
318
+ import { ReadingState } from './components/reading-state.js';
319
+
320
+ export default defineComponents([ReadingState]);
321
+ ```
322
+
323
+ ```ts
324
+ // iwsdk.config.json points components.module at ./src/components
325
+ // runtime and editor both consume virtual:iwsdk-project
326
+ import projectOptions from 'virtual:iwsdk-project';
327
+ World.create(container, projectOptions);
328
+ ```
329
+
330
+ The editor and runtime independently import the same manifest and derive validation
331
+ and inspector metadata from the executable component declarations. Component IDs must
332
+ be unique across IWSDK and the application. Keep declaration modules free of system,
333
+ DOM, renderer, and world side effects; systems may import those declarations.
334
+
335
+ Transforms use `[x, y, z]` tuples, degrees, and positive scalar or vector scale.
336
+ The optional `lookAt` constraint resolves yaw deterministically during lowering:
337
+
338
+ ```json
339
+ {
340
+ "constraints": {
341
+ "lookAt": { "mode": "yaw-v1", "target": [0, 1.2, 0] }
342
+ }
343
+ }
344
+ ```
345
+
346
+ Author spatial relationships directly through node transforms. The schema does not
347
+ infer support, floor contact, or other physical-placement semantics.
348
+
349
+ ## Authoring And Review
350
+
351
+ Use `authoring.composition` as a fixed brief, not a process transcript:
352
+
353
+ ```json
354
+ {
355
+ "authoring": {
356
+ "composition": {
357
+ "mode": "static",
358
+ "input": {
359
+ "kind": "hybrid",
360
+ "prompt": "A courtyard reading nook",
361
+ "references": []
362
+ },
363
+ "target": {
364
+ "surfaces": ["browser", "vr"],
365
+ "style": "stylized-pbr",
366
+ "assetPolicy": "manifest-assets"
367
+ },
368
+ "feasibility": { "status": "supported" },
369
+ "provenance": {
370
+ "adapter": { "id": "hybrid-intake", "version": "1.0.0" },
371
+ "skill": { "id": "iwsdk-scene-composer", "version": "1.0.0" },
372
+ "capabilityHash": "sha256:cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
373
+ "inputHashes": []
374
+ },
375
+ "representationPolicy": {
376
+ "fidelityCeiling": "stylized-static",
377
+ "allowed": ["asset", "prefab", "pattern"]
378
+ },
379
+ "features": [],
380
+ "assumptions": [],
381
+ "review": {
382
+ "heroView": "hero",
383
+ "requiredViews": ["hero", "top", "quarter"],
384
+ "lenses": ["layout", "geometry", "final"],
385
+ "maxCorrectionRounds": 2
386
+ }
387
+ },
388
+ "views": []
389
+ }
390
+ }
391
+ ```
392
+
393
+ `inputHashes` is the exact unique set of the prompt SHA-256, when present, plus every
394
+ declared reference digest with a `sha256:` prefix. Changing prompt whitespace changes
395
+ identity.
396
+
397
+ Every required feature needs implementation node bindings and immutable acceptance
398
+ criteria. Supported kinds normally include presence, count, projected-region,
399
+ spatial-relation, and visual-judgment.
400
+
401
+ Use `capture-node-mask-bounds-v1` for projected region evidence of manifest assets.
402
+ Their arbitrary external geometry cannot be proven from a JSON world-AABB assumption.
403
+
404
+ Authoring views contain exact projection parameters. Perspective views use position,
405
+ target, and FOV. Orthographic views use position, target, and height. Pass a saved
406
+ `viewId` to camera or screenshot tools rather than approximating it with a preset.
407
+ The separate `view` field accepts only built-in preset names. The runtime applies the
408
+ scene's hero view after level initialization, so adjust that authored view when editor
409
+ and runtime framing need to stay in parity; an initial `World.create` camera is not an
410
+ override for a scene-owned camera.
411
+
412
+ ```json
413
+ {
414
+ "authoring": {
415
+ "views": [
416
+ {
417
+ "id": "hero",
418
+ "role": "hero",
419
+ "projection": "perspective",
420
+ "position": [0, 1.6, 4.5],
421
+ "target": [0, 1.4, 0],
422
+ "fov": 42
423
+ },
424
+ {
425
+ "id": "top",
426
+ "role": "diagnostic",
427
+ "projection": "orthographic",
428
+ "position": [0, 8, 0],
429
+ "target": [0, 0, 0],
430
+ "height": 8
431
+ }
432
+ ]
433
+ }
434
+ }
435
+ ```
436
+
437
+ `nodeAnnotations` bind actual nodes to layout, geometry, or final review layers.
438
+ Unannotated renderables default to layout; descendants inherit the nearest annotation.
439
+
440
+ Every node may set `framingRole` to `content` or `support`. Use support only for
441
+ rendered infrastructure such as an oversized floor or backdrop. Requested subjects
442
+ must remain content.
443
+
444
+ ## Validation Traps
445
+
446
+ - Do not put `assets` or `materials` under `resources`.
447
+ - Do not emit model, primitive, geometry, material, or material override fields.
448
+ - Do not assume that a file in `public/` is registered; check `src/assets.ts`.
449
+ - Do not use a group as the only binding for a required visible feature.
450
+ - Do not namespace manifest asset IDs inside imported modules.
451
+ - Do not open or load an import-bearing composition as the editable/runtime scene;
452
+ flatten it first.
453
+ - Do not author duplicate or derived runtime IDs.
454
+ - Do not use non-finite transforms, unsafe paths, or unknown
455
+ component fields.
456
+ - Do not claim projected AABB silhouette evidence for arbitrary manifest assets; use
457
+ trusted capture node masks.
458
+ - Do not save over unsaved human editor changes. Resolve the reported conflict first.
@@ -0,0 +1,82 @@
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. author a new manifest asset when identity, geometry, or material response is
50
+ missing;
51
+ 3. assemble registered assets in a scene prefab for a reusable semantic object;
52
+ 4. use a deterministic pattern for repeated compatible prefabs;
53
+ 5. accept an approximation with a named fidelity ceiling;
54
+ 6. block when a required feature has no supportable representation.
55
+
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.
59
+
60
+ ## Establish Scale And Coordinates
61
+
62
+ Use `+Y` up. Choose a semantic origin such as scene center, floor center, or crossing
63
+ center. Put group origins where later editing is natural. Use conventional dimensions
64
+ only when the prompt supplies no evidence; record those values as assumptions.
65
+
66
+ The persistent player origin materializes at `[0, 0, 0]` unless the top-level
67
+ `player.transform` deliberately moves it. A semantic scene center is therefore not
68
+ automatically a safe object center: keep a standing capsule around the authored
69
+ player origin clear, or move the player to a deliberate spawn. Include an exact
70
+ spawn review view at player eye height (about 1.6 m above the origin) looking into
71
+ the composition; hero cameras do not substitute for this check.
72
+
73
+ Text-only scenes need at least one hero view plus diagnostic top, quarter, and player
74
+ spawn views.
75
+ The hero view is a design choice, not a match to an imaginary source image.
76
+
77
+ ## Review Text-Only Output
78
+
79
+ Use deterministic hierarchy, count, support, relation, bounds, and runtime checks.
80
+ Agent visual judgment evaluates composition and legibility against the written
81
+ criteria, not similarity to an absent reference. Do not use IoU, SSIM, pHash, or
82
+ camera-fit metrics.