@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,190 @@
1
+ # Image And Hybrid Intake
2
+
3
+ Treat an image as evidence about one projection of a scene. Do not claim recovered
4
+ hidden geometry, exact physical scale, calibrated optics, or inverse-rendered
5
+ materials.
6
+
7
+ ## Verify The Source
8
+
9
+ Record the original path/URI, width, height, and SHA-256. Confirm the file decodes and
10
+ is large enough to inspect. Detect exact/near duplicates when multiple references are
11
+ provided.
12
+
13
+ Do not reject a full-frame environment because its foreground mask is large,
14
+ fragmented, or touches the frame. Foreground coverage/coherence gates are appropriate
15
+ only for an intentionally isolated object crop.
16
+
17
+ ## Assign Reference Roles
18
+
19
+ Assign each reference one or more roles:
20
+
21
+ - `layout`: placement, overlap, proportions, and camera framing;
22
+ - `identity`: object-specific silhouette or features;
23
+ - `palette`: broad hue/value grouping;
24
+ - `style`: rendering character, not literal geometry.
25
+
26
+ For hybrid input, text overrides image content when they conflict. Record the chosen
27
+ interpretation and do not silently discard either source.
28
+
29
+ ## Decompose The Visible Scene
30
+
31
+ Inventory macro systems first:
32
+
33
+ - ground, paths, roads, water, and boundaries;
34
+ - architecture and large natural forms;
35
+ - focal object or cluster;
36
+ - repeated structures and vegetation;
37
+ - vehicles, people, props, and accents;
38
+ - dominant light direction, background, and atmosphere.
39
+
40
+ Then identify 3-8 features that control recognition. Prefer silhouette, count,
41
+ relative size, overlap, negative space, material family, and spatial rhythm. Create
42
+ normalized `[x, y, width, height]` regions or `[x, y]` anchors only for critical
43
+ features.
44
+
45
+ Map each feature to planned node/resource IDs before materialization. If a visible
46
+ feature cannot be represented, mark the brief conditional and name the approximation.
47
+
48
+ Choose and record one fidelity level before detailed authoring: composition match,
49
+ editable stylized reconstruction, close visual recreation, or calibrated
50
+ reconstruction. An unqualified request to recreate an image defaults to close visual
51
+ recreation. A lower level requires an explicit conditional limitation rather than a
52
+ self-authored fidelity ceiling that narrows the request silently.
53
+
54
+ ## Infer Depth And Camera
55
+
56
+ Separate observations from inferences:
57
+
58
+ - observations: image-space positions, visible edges, counts, occlusions, colors,
59
+ shadows, and top/side ratios;
60
+ - inferences: depth, unseen sides, true dimensions, focal length, and material values.
61
+
62
+ Use line convergence, visible top surfaces, occlusion order, cast shadows, familiar
63
+ scale anchors, and repeated spacing to propose a coherent 3D layout. Prefer shallow,
64
+ editable hidden geometry over elaborate invention.
65
+
66
+ Represent camera uncertainty as a hypothesis or fitted range. Save one exact hero
67
+ view after fitting; use the same view and resolution for every comparison. For an
68
+ orthographic/isometric-like source, use an orthographic authoring view when supported.
69
+ Otherwise declare the perspective approximation conditional.
70
+
71
+ ## Establish The Inspection Context Early
72
+
73
+ Materialize the room shell or stage, support geometry, an approximate reference
74
+ camera, and representative lighting before building the focal objects. Add one
75
+ identity-critical object group at a time and inspect it in that shared context before
76
+ adding the next. Use neutral form-reading light for silhouette and proportion checks,
77
+ then restore representative final light for material response. Preserve approved
78
+ background and lighting while isolating a focal group when the editor supports it;
79
+ otherwise inspect the object before later groups are accumulated or render its module
80
+ file independently. Complete object-level inspection before composing later groups.
81
+
82
+ ## Handle Materials
83
+
84
+ Classify broad families such as matte stone, painted wood, foliage, fabric, exposed
85
+ metal, painted metal, ceramic glaze, or glazing proxy. Use scalar standard PBR only
86
+ when the visible finish is materially uniform and its highlight response is not
87
+ identity-bearing. When clearcoat, sheen, transmission, IOR, anisotropy, mottling,
88
+ weave, patina, or another spatially varying finish controls recognition, put the
89
+ supported physical material and independent maps in the initial candidate. Do not
90
+ defer them until a correction round.
91
+
92
+ Map the finish to topology, not just object identity. Cylinder/cone/lathe side UVs
93
+ wrap around U and run along height/profile in V; tube U follows the path and V wraps
94
+ the cross-section; every box face restarts its own UV square. Use separate named
95
+ material variants when repeat scale or weave/grain direction must differ. On closed
96
+ or lathed surfaces, repeating procedural samplers must use rotation `0`, `90`, `180`,
97
+ or `270`, and the sampler repeat mapped to every closed UV axis must be a positive
98
+ integer. At rotations `0`/`180`, closed U maps to `repeat[0]` and closed V maps to
99
+ `repeat[1]`; at `90`/`270` the mappings swap. Thus a cylinder with rotation `0` may
100
+ use `[4, 2.5]` because only U closes, but `[4.25, 2]` will expose its U seam; a closed
101
+ tube needs integer values on both repeat axes. Arbitrary rotation is not seam-safe.
102
+ Prefer close albedo stops, high roughness, restrained sheen, and shallow bump for
103
+ fabric unless the image provides evidence for a high-contrast weave.
104
+
105
+ Do not treat pixel brightness as roughness, metalness, AO, height, or normal data.
106
+ Whole-image finish classifiers are non-authoritative. Use a verified part crop only
107
+ as optional evidence and retain uncertainty. When the active capabilities report
108
+ `periodic-fbm-v1`, author independent deterministic albedo, emissive, roughness,
109
+ metalness, AO, alpha, and normal-or-bump maps to approximate a material family. Do
110
+ not claim these maps reconstruct source pixels or physical surface measurements.
111
+
112
+ Evaluate feasibility against the full reported capability set, not the cheapest
113
+ initial representation. Never move an identity-bearing requested or observed finish
114
+ into `acceptedApproximations` when the active capabilities can represent it. Bind a
115
+ required material feature to the affected nodes and make its visual criterion name
116
+ both spatial variation and highlight behavior explicitly.
117
+
118
+ For an isolated studio product, compile a coherent first-pass recipe when supported:
119
+
120
+ - physical PBR for glaze, clearcoat, textile sheen, glass, or polished finishes;
121
+ - independent deterministic albedo, roughness, and bump/normal channels for visible
122
+ within-object variation;
123
+ - environment IBL plus shaped area lights that reproduce the observed highlight
124
+ footprint;
125
+ - soft, directional contact shadowing;
126
+ - one floor/support surface that extends beyond every required, alternate, and
127
+ diagnostic camera frustum and matches the background closely enough that no
128
+ horizon, diagonal edge, corner, or value seam appears in any saved view. Mark that
129
+ infrastructure `framingRole: "support"`, fit from content-only `framingBounds`, and
130
+ verify coverage with raw `worldBounds` plus exact-view captures.
131
+
132
+ Do not add procedural variation merely because it is available. Its scale, amplitude,
133
+ and channel independence must be supported by visible evidence and recorded as an
134
+ approximation rather than recovered source texture.
135
+
136
+ ## Tune Color And Value
137
+
138
+ Do not leave palette matching as an informal final impression. After camera, layout,
139
+ and major occlusion are stable, compare the reference and exact hero render at the
140
+ same aspect ratio and record:
141
+
142
+ - mean luma plus dark/mid/high percentile luma;
143
+ - average color for a few broad, unoccluded semantic regions such as wall, floor,
144
+ focal object, and background;
145
+ - highlight and shadow footprint for the focal material;
146
+ - the renderer's tone mapping, exposure, IBL intensity, light colors/intensities, and
147
+ background color.
148
+
149
+ Use `scene_measure_image_regions` with the trusted hero `captureToken`, the declared
150
+ reference ID, and explicitly aligned normalized regions. The tool verifies reference
151
+ bytes against their declared SHA-256 and reports luma percentiles, mean OKLab color,
152
+ and highlight/shadow footprints without pretending those diagnostics are a universal
153
+ similarity score. Do not use full-frame metrics when camera or crop alignment is not
154
+ established.
155
+
156
+ Use these as revision diagnostics rather than a universal score. Tune in this order:
157
+
158
+ 1. tone mapping, background, exposure, and IBL intensity;
159
+ 2. key/fill/practical light color and intensity;
160
+ 3. large material base colors;
161
+ 4. roughness, metalness, sheen, clearcoat, and transmission response;
162
+ 5. spatial albedo/roughness/bump variation.
163
+
164
+ Do not darken albedo to compensate for excessive exposure, or increase saturation to
165
+ compensate for a flat lighting ratio. Re-capture after each coherent tuning pass and
166
+ retain the measured before/after values. A color pass may not move the saved camera or
167
+ silently repair geometry, so its effect remains attributable.
168
+
169
+ ## Review Against The Image
170
+
171
+ Run technical gates first. Then compare:
172
+
173
+ - projected centers/extents of bound feature groups;
174
+ - visible top-to-side ratios and negative spaces;
175
+ - relative scale and overlap order;
176
+ - counts and repeated spacing;
177
+ - support/contact gaps;
178
+ - major palette and light/dark grouping;
179
+ - masked within-object color variance and coarse spatial distribution;
180
+ - highlight position, area, shape, and intensity;
181
+ - contact-shadow area, softness, and direction;
182
+ - floor/background continuity and any visible plane edge or seam;
183
+ - alternate-view volume for non-planar features.
184
+
185
+ Use object-mask IoU, SSIM, pHash, edge overlap, or color delta only for isolated crops
186
+ or calibrated synthetic fixtures whose assumptions hold. They are not universal hard
187
+ gates for full environments, foliage, cast shadows, or inferred hidden geometry.
188
+
189
+ Agent visual judgment follows deterministic diagnostics and must report every required
190
+ feature separately. A strong global impression cannot hide a missing critical object.
@@ -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.