@iwsdk/create 0.4.1 → 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,191 @@
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.
191
+
@@ -0,0 +1,99 @@
1
+ # Review And Stop
2
+
3
+ Use this reference after each authored module and again after root composition.
4
+ Review logic and evidence live in ordinary task files. The editor supplies raw,
5
+ authoritative observations; it does not own the review workflow.
6
+
7
+ ## Inputs
8
+
9
+ Retain:
10
+
11
+ - root and module paths;
12
+ - source, composed, runtime, capability, and screenshot hashes;
13
+ - exact camera state and resolution;
14
+ - renderer environment and render statistics;
15
+ - reference image regions and assumptions;
16
+ - required features with owning IDs and acceptance criteria.
17
+
18
+ Call `scene_render_file` for off-document validation and rendering through the
19
+ command-ready managed editor browser. A result is usable only when `valid` is true
20
+ and an authoritative PNG is returned. A custom renderer is diagnostic evidence, not
21
+ a substitute. For the open root use `scene_get_state`, `scene_set_camera`, and
22
+ `scene_screenshot`.
23
+
24
+ ## Object Review
25
+
26
+ Review identity-critical objects before judging the full scene. Capture each required
27
+ view under neutral form-reading conditions and representative final lighting.
28
+
29
+ For every object inspect:
30
+
31
+ 1. silhouette;
32
+ 2. major proportions;
33
+ 3. required parts;
34
+ 4. negative spaces;
35
+ 5. support contacts and placement;
36
+ 6. material response;
37
+ 7. appearance in context.
38
+
39
+ Use `scene_set_preview_visibility` for temporary solo-with-context or ghosted views.
40
+ It must not change scene hashes. Store observations and screenshot references in the
41
+ task evidence, not in the scene editor.
42
+
43
+ ## Composition Review
44
+
45
+ Review in this order:
46
+
47
+ 1. **Layout**: hierarchy, scale, support contacts, top/front/side arrangement, floor
48
+ and backdrop coverage.
49
+ 2. **Geometry**: alternate-angle volume, silhouette, proportions, occlusion, and
50
+ identity-critical details.
51
+ 3. **Final**: materials, color, light, environment, shadows, and hero framing.
52
+ 4. **Spawn**: inspect the exact player-origin view at standing eye height and confirm
53
+ that no authored geometry intersects the player's standing volume.
54
+
55
+ For image-driven work, align source and render at the same aspect ratio. Use explicit
56
+ source regions and measurable projected bounds. `scene_measure_image_regions` is
57
+ appropriate only when source/render alignment and the requested color, luma,
58
+ highlight, or shadow statistic are meaningful.
59
+
60
+ Do not present an estimated decimal as a measured score. Record categorical outcomes
61
+ and actual measurements separately.
62
+
63
+ ## Defects
64
+
65
+ Classify the largest remaining defect as one of:
66
+
67
+ - `contract`: requirement or ownership is wrong or incomplete;
68
+ - `resource`: asset/material cannot express the requirement;
69
+ - `scene`: geometry, placement, hierarchy, or lighting is wrong;
70
+ - `camera`: projection, pose, crop, or framing is wrong;
71
+ - `runtime`: composed and live application results differ.
72
+
73
+ Fix the owning module or root file directly. Rerender the changed module first and
74
+ then the root. Preserve the previous evidence so regressions are visible.
75
+
76
+ ## Performance Review
77
+
78
+ Use render statistics returned by `scene_get_state`, `scene_screenshot`, or
79
+ `scene_render_file`. Treat gratuitous draw calls, unique repeated geometry, large
80
+ textures, and unnecessary shadow casters as defects. Desktop/browser frame samples
81
+ are diagnostics, not calibrated headset performance.
82
+
83
+ ## Stop Rules
84
+
85
+ Default to at most two focused correction rounds after the first complete review.
86
+ Stop earlier when:
87
+
88
+ - the same defect repeats;
89
+ - two changes oscillate;
90
+ - applicable diagnostics plateau or regress;
91
+ - required input or assets are missing;
92
+ - the representation ceiling cannot satisfy a required feature;
93
+ - a user decision is required.
94
+
95
+ Completion requires all scratch-module renders to pass, a flattened import-free root,
96
+ a clean conflict-free editor state, nonblank required views (including player spawn),
97
+ passing required features, and a live application runtime bound to the expected
98
+ root/runtime hash. There is no editor publish tool; record the final evidence and
99
+ verify the application build normally.