@iwsdk/create 0.5.0 → 0.5.2

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 (35) hide show
  1. package/LICENSE +21 -0
  2. package/dist/cli.js +27 -9
  3. package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +0 -1
  4. package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +0 -1
  5. package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +0 -1
  6. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/component-reference.md +0 -2
  7. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +0 -1
  8. package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +2 -2
  9. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/api-reference.md +5 -0
  10. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +5 -3
  11. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +1 -1
  12. package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +0 -1
  13. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +5 -3
  14. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +0 -1
  15. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/image-intake.md +0 -1
  16. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/scene-format.md +6 -4
  17. package/dist/guidance/claude/.claude/rules/scene-json.md +8 -5
  18. package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +0 -1
  19. package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +0 -1
  20. package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +0 -1
  21. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/component-reference.md +0 -2
  22. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +0 -1
  23. package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +2 -2
  24. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/api-reference.md +5 -0
  25. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +5 -3
  26. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +1 -1
  27. package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +0 -1
  28. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +5 -3
  29. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +0 -1
  30. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/image-intake.md +0 -1
  31. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/scene-format.md +6 -4
  32. package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +8 -5
  33. package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +8 -5
  34. package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +8 -5
  35. package/package.json +21 -22
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) Meta Platforms, Inc. and affiliates.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/dist/cli.js CHANGED
@@ -11190,8 +11190,12 @@ async function installDependenciesFromBundle(outDir, source) {
11190
11190
  throw e;
11191
11191
  }
11192
11192
  }
11193
- /** Initialize the shared reference corpus/model cache after dependencies exist. */
11194
- async function warmupReference(outDir) {
11193
+ const DEFAULT_REFERENCE_WARMUP_TIMEOUT_MS = 120_000;
11194
+ /**
11195
+ * Initialize the optional reference cache without making project creation
11196
+ * depend on network/model availability.
11197
+ */
11198
+ async function warmupReference(outDir, timeoutMs = DEFAULT_REFERENCE_WARMUP_TIMEOUT_MS) {
11195
11199
  const spinner = ora({
11196
11200
  text: 'Initializing IWSDK reference tools (one-time shared download) ...',
11197
11201
  stream: process.stderr,
@@ -11206,22 +11210,32 @@ async function warmupReference(outDir) {
11206
11210
  stdio: 'inherit',
11207
11211
  });
11208
11212
  await new Promise((resolve, reject) => {
11209
- child.on('error', reject);
11213
+ const timeout = setTimeout(() => {
11214
+ child.kill();
11215
+ reject(new Error(`Reference initialization timed out after ${Math.ceil(timeoutMs / 1000)} seconds`));
11216
+ }, timeoutMs);
11217
+ const finish = (callback) => {
11218
+ clearTimeout(timeout);
11219
+ callback();
11220
+ };
11221
+ child.on('error', (error) => finish(() => reject(error)));
11210
11222
  child.on('exit', (code) => code === 0
11211
- ? resolve()
11212
- : reject(new Error(`Reference initialization failed (${code})`)));
11223
+ ? finish(resolve)
11224
+ : finish(() => reject(new Error(`Reference initialization failed (${code})`))));
11213
11225
  });
11214
11226
  spinner.stopAndPersist({
11215
11227
  symbol: stderrColor.green('✔'),
11216
11228
  text: 'IWSDK reference tools ready',
11217
11229
  });
11230
+ return true;
11218
11231
  }
11219
11232
  catch (error) {
11220
11233
  spinner.stopAndPersist({
11221
11234
  symbol: stderrColor.red('✖'),
11222
11235
  text: 'IWSDK reference initialization failed',
11223
11236
  });
11224
- throw error;
11237
+ console.warn(stderrColor.yellow(`Project creation will continue without the optional reference cache: ${error instanceof Error ? error.message : String(error)}. Run "npx iwsdk reference warmup" from the project directory to retry.`));
11238
+ return false;
11225
11239
  }
11226
11240
  }
11227
11241
  function printReferenceWarmupGuidance() {
@@ -11371,7 +11385,7 @@ function createProjectManifest(configuration) {
11371
11385
  };
11372
11386
  }
11373
11387
 
11374
- const VERSION = "0.5.0";
11388
+ const VERSION = "0.5.2";
11375
11389
  const NODE_ENGINE = ">=20.19.0 <21.0.0-0 || >=22.12.0 <23.0.0-0 || >=24.0.0";
11376
11390
 
11377
11391
  /**
@@ -18475,6 +18489,7 @@ IWSDK Create CLI v${VERSION}\nNode ${process.version}`;
18475
18489
  .option('--no-scene-understanding', 'Disable scene understanding')
18476
18490
  .option('--environment-raycast', 'Enable environment raycast (AR mode)')
18477
18491
  .option('--no-environment-raycast', 'Disable environment raycast')
18492
+ .option('--skip-reference-warmup', 'Skip the optional one-time reference model download')
18478
18493
  .action((n, opts) => {
18479
18494
  nameArg = n;
18480
18495
  cliOpts = opts;
@@ -18660,6 +18675,7 @@ IWSDK Create CLI v${VERSION}\nNode ${process.version}`;
18660
18675
  }
18661
18676
  }
18662
18677
  // Install dependencies
18678
+ let referenceReady = false;
18663
18679
  if (res.installNow) {
18664
18680
  if (source.isBundleMode) {
18665
18681
  await installDependenciesFromBundle(outDir, source);
@@ -18667,7 +18683,9 @@ IWSDK Create CLI v${VERSION}\nNode ${process.version}`;
18667
18683
  else {
18668
18684
  await installDependencies(outDir);
18669
18685
  }
18670
- await warmupReference(outDir);
18686
+ if (!cliOpts.skipReferenceWarmup) {
18687
+ referenceReady = await warmupReference(outDir);
18688
+ }
18671
18689
  }
18672
18690
  // Write MCP adapter configs for every supported coding harness.
18673
18691
  if (res.installNow) {
@@ -18686,7 +18704,7 @@ IWSDK Create CLI v${VERSION}\nNode ${process.version}`;
18686
18704
  const prereqs = [...(res.prerequisites || [])];
18687
18705
  // Print prerequisites first, then next steps
18688
18706
  printPrerequisites(prereqs);
18689
- printNextSteps(projectTarget.displayPath, res.installNow, res.actionItems || [], projectTarget.inPlace, res.installNow);
18707
+ printNextSteps(projectTarget.displayPath, res.installNow, res.actionItems || [], projectTarget.inPlace, referenceReady);
18690
18708
  }
18691
18709
  finally {
18692
18710
  await source.cleanup();
@@ -93,4 +93,3 @@ Short domain-specific tips. Apply the core workflow above, plus these hints.
93
93
  - **Resume is safe** — the first frame after resume uses a capped delta to prevent physics explosions from accumulated time.
94
94
  - **Render loop continues while paused** — screenshots always work, and the XR session stays alive.
95
95
  - **Stepping requires pause** — `ecs_step` will fail if you haven't called `ecs_pause` first.
96
-
@@ -126,4 +126,3 @@ workspace switches to runtime before capture.
126
126
  - **Never use `xr_select` or trigger (button index 0) for grabs** — OneHandGrabbable/TwoHandsGrabbable respond to squeeze (button index 1).
127
127
  - **DistanceGrabbable is different** — it uses ray-based selection, not proximity. This skill does not cover DistanceGrabbable.
128
128
  - If the object lacks a name in the hierarchy, suggest adding `mesh.name = "MyObject"` in code before `createTransformEntity`.
129
-
@@ -89,4 +89,3 @@ Read the one the task needs; each is complete on its own.
89
89
  4. **Minimize dynamic body count** -- each dynamic body requires per-frame transform sync
90
90
  5. **Use damping** to settle objects faster and reduce ongoing simulation work
91
91
  6. **TriMesh is for static only** -- it is computationally expensive and should never be used on dynamic bodies
92
-
@@ -13,7 +13,6 @@ entity.addComponent(PhysicsBody, {
13
13
  centerOfMass: [Infinity, Infinity, Infinity], // Infinity = auto-compute from shape
14
14
  });
15
15
  ```
16
-
17
16
  **Properties:**
18
17
 
19
18
  | Property | Type | Default | Description |
@@ -151,4 +150,3 @@ update() {
151
150
  }
152
151
  }
153
152
  ```
154
-
@@ -85,4 +85,3 @@ Physics components can be configured declaratively in native scene JSON files:
85
85
  - `ConvexHull`
86
86
  - `TriMesh`
87
87
  - `Auto`
88
-
@@ -158,9 +158,9 @@ project directory exists for every later artifact and tool:
158
158
  Phase 2/3 agents (or brief them with the final app paths) — agents
159
159
  writing to a stale staging path while you move it lose work.
160
160
  3. Run the deferred Phase 0 probes (`npx iwsdk status`, `npx iwsdk reference
161
- status`). Creation initializes the reference cache before returning. Only if
161
+ status`). Creation initializes the reference cache before returning. Only if
162
162
  status still reports warmup required should you run `npx iwsdk reference
163
- warmup` and treat a failure as a scaffold/setup defect.
163
+ warmup` and treat a failure as a scaffold/setup defect.
164
164
  4. Do **not** modify app code yet — Phase 5's M0 verifies the untouched
165
165
  scaffold. Never scaffold a nested app inside an existing IWSDK app.
166
166
 
@@ -41,6 +41,11 @@ Use `input.canvasPointerEvents` for browser mouse/touch canvas events. Browser c
41
41
 
42
42
  ## Critical Best Practices
43
43
 
44
+ `createSystem()` accepts query descriptors as its first argument and optional
45
+ configuration schema as its second. Lifecycle methods never go inside either
46
+ object: define `init()`, `update()`, and `destroy()` in the subclass body. A
47
+ function inside the query map is a lifecycle-placement mistake, not a query.
48
+
44
49
  ### 1. Keep Systems Stateless
45
50
 
46
51
  Systems should NOT store arrays of entities or maintain entity references. Use queries instead.
@@ -28,9 +28,11 @@ current release documented on iwsdk.dev.
28
28
 
29
29
  Notes:
30
30
 
31
- - `--no-xr` scaffolds `xr: false` but does **not** wire browser locomotion,
32
- mouselook, or browser grabbing — add `features.locomotion.browserControls`
33
- and app-owned camera controls in code.
31
+ - `--no-xr` (the legacy alias for `--target browser`) scaffolds `xr: false`,
32
+ browser locomotion, canvas pointer input, and browser interaction support.
33
+ Camera look remains intentionally app-owned because first-person, orbit,
34
+ editor, and follow cameras need different behavior. For a first-person app,
35
+ adapt the pointer-lock pattern in `examples/browser-first/src/mouselook.ts`.
34
36
  - Dual-runtime (VR + browser testable): scaffold `--mode vr`, then set
35
37
  `xr: { offer: 'once' }`, `input: { canvasPointerEvents: true }`,
36
38
  `locomotion: { browserControls: true }`.
@@ -153,4 +153,4 @@ mechanics, 1 environment, 1–2 UI panels, 3–8 custom components, 2–5 custom
153
153
  systems. Physics, grabbing, spatial UI, audio, and environment theming are
154
154
  nearly free (built-ins); multiplayer, persistence, custom shaders, and
155
155
  skeletal animation are expensive (custom). If the idea is big, put the
156
- expensive parts in Stretch and say so in the pitch summary.
156
+ expensive parts in Stretch and say so in the pitch summary.
@@ -156,4 +156,3 @@ switches to runtime before capture.
156
156
  is needed. Guessing from panel offsets or transient entity indices is fragile.
157
157
  - **DistanceGrabbable movement modes:** Check the entity's DistanceGrabbable component to see which `movementMode` is set. Use `ecs_query_entity` if unsure.
158
158
  - **Don't move the controller to the target** — ray interactions work at a distance. Only rotate via `xr_look_at`, don't translate.
159
-
@@ -87,9 +87,11 @@ gate as blocked.
87
87
 
88
88
  Camera parameters are intentionally distinct: `view` accepts only the built-in
89
89
  presets (`current`, `top`, `front`, `back`, `left`, `right`, `quarter`, `orbit`),
90
- while `viewId` selects an exact camera declared in `authoring.views`. Once a level
91
- loads, its saved hero view owns runtime framing and supersedes the initial
92
- `World.create({ render: { camera } })` pose.
90
+ while `viewId` selects an exact camera declared in `authoring.views`. Outside
91
+ immersive XR, a loaded level's saved hero view owns runtime framing and
92
+ supersedes the initial `World.create({ render: { camera } })` pose. In XR, the
93
+ tracked player rig owns the camera, so the player-spawn view is a separate
94
+ required framing check.
93
95
 
94
96
  ## Workflow
95
97
 
@@ -2,4 +2,3 @@ interface:
2
2
  display_name: 'IWSDK Scene Composer'
3
3
  short_description: 'Compose editable IWSDK scenes from text or images'
4
4
  default_prompt: 'Use $iwsdk-scene-composer to compose this request as an editable, validated IWSDK scene.'
5
-
@@ -188,4 +188,3 @@ gates for full environments, foliage, cast shadows, or inferred hidden geometry.
188
188
 
189
189
  Agent visual judgment follows deterministic diagnostics and must report every required
190
190
  feature separately. A strong global impression cannot hide a missing critical object.
191
-
@@ -404,10 +404,12 @@ Their arbitrary external geometry cannot be proven from a JSON world-AABB assump
404
404
  Authoring views contain exact projection parameters. Perspective views use position,
405
405
  target, and FOV. Orthographic views use position, target, and height. Pass a saved
406
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.
407
+ The separate `view` field accepts only built-in preset names. Outside immersive XR,
408
+ the runtime applies the scene's hero view after level initialization, so adjust that
409
+ authored view when editor and browser framing need to stay in parity; an initial
410
+ `World.create` camera is not an override for a scene-owned camera. In XR the tracked
411
+ player rig owns the camera, so separately inspect framing from the authored player
412
+ spawn.
411
413
 
412
414
  ```json
413
415
  {
@@ -48,11 +48,14 @@ node already uses instead of normalising.
48
48
 
49
49
  `LevelRoot`, `LevelTag` and `Transform` are runtime-owned; never author them.
50
50
 
51
- ## The scene owns the runtime camera
52
-
53
- The hero authoring view supersedes `world.render.camera` from
54
- `iwsdk.config.json` once the level initialises. Changing the config camera to fix
55
- runtime framing will appear to do nothing — change the hero view instead.
51
+ ## Browser hero views and XR spawn framing are distinct
52
+
53
+ Outside immersive XR, the hero authoring view supersedes `world.render.camera`
54
+ from `iwsdk.config.json` once the level initialises. While XR is presenting,
55
+ the tracked player rig owns the camera and the hero view is intentionally not
56
+ applied. Use the hero view for editor/browser framing, and validate important
57
+ content from the authored `player.transform` spawn (or the default standing
58
+ view near `[0, 1.6, 0]`) before accepting XR framing.
56
59
 
57
60
  ## Validation
58
61
 
@@ -93,4 +93,3 @@ Short domain-specific tips. Apply the core workflow above, plus these hints.
93
93
  - **Resume is safe** — the first frame after resume uses a capped delta to prevent physics explosions from accumulated time.
94
94
  - **Render loop continues while paused** — screenshots always work, and the XR session stays alive.
95
95
  - **Stepping requires pause** — `ecs_step` will fail if you haven't called `ecs_pause` first.
96
-
@@ -126,4 +126,3 @@ workspace switches to runtime before capture.
126
126
  - **Never use `xr_select` or trigger (button index 0) for grabs** — OneHandGrabbable/TwoHandsGrabbable respond to squeeze (button index 1).
127
127
  - **DistanceGrabbable is different** — it uses ray-based selection, not proximity. This skill does not cover DistanceGrabbable.
128
128
  - If the object lacks a name in the hierarchy, suggest adding `mesh.name = "MyObject"` in code before `createTransformEntity`.
129
-
@@ -89,4 +89,3 @@ Read the one the task needs; each is complete on its own.
89
89
  4. **Minimize dynamic body count** -- each dynamic body requires per-frame transform sync
90
90
  5. **Use damping** to settle objects faster and reduce ongoing simulation work
91
91
  6. **TriMesh is for static only** -- it is computationally expensive and should never be used on dynamic bodies
92
-
@@ -13,7 +13,6 @@ entity.addComponent(PhysicsBody, {
13
13
  centerOfMass: [Infinity, Infinity, Infinity], // Infinity = auto-compute from shape
14
14
  });
15
15
  ```
16
-
17
16
  **Properties:**
18
17
 
19
18
  | Property | Type | Default | Description |
@@ -151,4 +150,3 @@ update() {
151
150
  }
152
151
  }
153
152
  ```
154
-
@@ -85,4 +85,3 @@ Physics components can be configured declaratively in native scene JSON files:
85
85
  - `ConvexHull`
86
86
  - `TriMesh`
87
87
  - `Auto`
88
-
@@ -158,9 +158,9 @@ project directory exists for every later artifact and tool:
158
158
  Phase 2/3 agents (or brief them with the final app paths) — agents
159
159
  writing to a stale staging path while you move it lose work.
160
160
  3. Run the deferred Phase 0 probes (`npx iwsdk status`, `npx iwsdk reference
161
- status`). Creation initializes the reference cache before returning. Only if
161
+ status`). Creation initializes the reference cache before returning. Only if
162
162
  status still reports warmup required should you run `npx iwsdk reference
163
- warmup` and treat a failure as a scaffold/setup defect.
163
+ warmup` and treat a failure as a scaffold/setup defect.
164
164
  4. Do **not** modify app code yet — Phase 5's M0 verifies the untouched
165
165
  scaffold. Never scaffold a nested app inside an existing IWSDK app.
166
166
 
@@ -41,6 +41,11 @@ Use `input.canvasPointerEvents` for browser mouse/touch canvas events. Browser c
41
41
 
42
42
  ## Critical Best Practices
43
43
 
44
+ `createSystem()` accepts query descriptors as its first argument and optional
45
+ configuration schema as its second. Lifecycle methods never go inside either
46
+ object: define `init()`, `update()`, and `destroy()` in the subclass body. A
47
+ function inside the query map is a lifecycle-placement mistake, not a query.
48
+
44
49
  ### 1. Keep Systems Stateless
45
50
 
46
51
  Systems should NOT store arrays of entities or maintain entity references. Use queries instead.
@@ -28,9 +28,11 @@ current release documented on iwsdk.dev.
28
28
 
29
29
  Notes:
30
30
 
31
- - `--no-xr` scaffolds `xr: false` but does **not** wire browser locomotion,
32
- mouselook, or browser grabbing — add `features.locomotion.browserControls`
33
- and app-owned camera controls in code.
31
+ - `--no-xr` (the legacy alias for `--target browser`) scaffolds `xr: false`,
32
+ browser locomotion, canvas pointer input, and browser interaction support.
33
+ Camera look remains intentionally app-owned because first-person, orbit,
34
+ editor, and follow cameras need different behavior. For a first-person app,
35
+ adapt the pointer-lock pattern in `examples/browser-first/src/mouselook.ts`.
34
36
  - Dual-runtime (VR + browser testable): scaffold `--mode vr`, then set
35
37
  `xr: { offer: 'once' }`, `input: { canvasPointerEvents: true }`,
36
38
  `locomotion: { browserControls: true }`.
@@ -153,4 +153,4 @@ mechanics, 1 environment, 1–2 UI panels, 3–8 custom components, 2–5 custom
153
153
  systems. Physics, grabbing, spatial UI, audio, and environment theming are
154
154
  nearly free (built-ins); multiplayer, persistence, custom shaders, and
155
155
  skeletal animation are expensive (custom). If the idea is big, put the
156
- expensive parts in Stretch and say so in the pitch summary.
156
+ expensive parts in Stretch and say so in the pitch summary.
@@ -156,4 +156,3 @@ switches to runtime before capture.
156
156
  is needed. Guessing from panel offsets or transient entity indices is fragile.
157
157
  - **DistanceGrabbable movement modes:** Check the entity's DistanceGrabbable component to see which `movementMode` is set. Use `ecs_query_entity` if unsure.
158
158
  - **Don't move the controller to the target** — ray interactions work at a distance. Only rotate via `xr_look_at`, don't translate.
159
-
@@ -87,9 +87,11 @@ gate as blocked.
87
87
 
88
88
  Camera parameters are intentionally distinct: `view` accepts only the built-in
89
89
  presets (`current`, `top`, `front`, `back`, `left`, `right`, `quarter`, `orbit`),
90
- while `viewId` selects an exact camera declared in `authoring.views`. Once a level
91
- loads, its saved hero view owns runtime framing and supersedes the initial
92
- `World.create({ render: { camera } })` pose.
90
+ while `viewId` selects an exact camera declared in `authoring.views`. Outside
91
+ immersive XR, a loaded level's saved hero view owns runtime framing and
92
+ supersedes the initial `World.create({ render: { camera } })` pose. In XR, the
93
+ tracked player rig owns the camera, so the player-spawn view is a separate
94
+ required framing check.
93
95
 
94
96
  ## Workflow
95
97
 
@@ -2,4 +2,3 @@ interface:
2
2
  display_name: 'IWSDK Scene Composer'
3
3
  short_description: 'Compose editable IWSDK scenes from text or images'
4
4
  default_prompt: 'Use $iwsdk-scene-composer to compose this request as an editable, validated IWSDK scene.'
5
-
@@ -188,4 +188,3 @@ gates for full environments, foliage, cast shadows, or inferred hidden geometry.
188
188
 
189
189
  Agent visual judgment follows deterministic diagnostics and must report every required
190
190
  feature separately. A strong global impression cannot hide a missing critical object.
191
-
@@ -404,10 +404,12 @@ Their arbitrary external geometry cannot be proven from a JSON world-AABB assump
404
404
  Authoring views contain exact projection parameters. Perspective views use position,
405
405
  target, and FOV. Orthographic views use position, target, and height. Pass a saved
406
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.
407
+ The separate `view` field accepts only built-in preset names. Outside immersive XR,
408
+ the runtime applies the scene's hero view after level initialization, so adjust that
409
+ authored view when editor and browser framing need to stay in parity; an initial
410
+ `World.create` camera is not an override for a scene-owned camera. In XR the tracked
411
+ player rig owns the camera, so separately inspect framing from the authored player
412
+ spawn.
411
413
 
412
414
  ```json
413
415
  {
@@ -47,11 +47,14 @@ node already uses instead of normalising.
47
47
 
48
48
  `LevelRoot`, `LevelTag` and `Transform` are runtime-owned; never author them.
49
49
 
50
- ## The scene owns the runtime camera
51
-
52
- The hero authoring view supersedes `world.render.camera` from
53
- `iwsdk.config.json` once the level initialises. Changing the config camera to fix
54
- runtime framing will appear to do nothing — change the hero view instead.
50
+ ## Browser hero views and XR spawn framing are distinct
51
+
52
+ Outside immersive XR, the hero authoring view supersedes `world.render.camera`
53
+ from `iwsdk.config.json` once the level initialises. While XR is presenting,
54
+ the tracked player rig owns the camera and the hero view is intentionally not
55
+ applied. Use the hero view for editor/browser framing, and validate important
56
+ content from the authored `player.transform` spawn (or the default standing
57
+ view near `[0, 1.6, 0]`) before accepting XR framing.
55
58
 
56
59
  ## Validation
57
60
 
@@ -50,11 +50,14 @@ node already uses instead of normalising.
50
50
 
51
51
  `LevelRoot`, `LevelTag` and `Transform` are runtime-owned; never author them.
52
52
 
53
- ## The scene owns the runtime camera
54
-
55
- The hero authoring view supersedes `world.render.camera` from
56
- `iwsdk.config.json` once the level initialises. Changing the config camera to fix
57
- runtime framing will appear to do nothing — change the hero view instead.
53
+ ## Browser hero views and XR spawn framing are distinct
54
+
55
+ Outside immersive XR, the hero authoring view supersedes `world.render.camera`
56
+ from `iwsdk.config.json` once the level initialises. While XR is presenting,
57
+ the tracked player rig owns the camera and the hero view is intentionally not
58
+ applied. Use the hero view for editor/browser framing, and validate important
59
+ content from the authored `player.transform` spawn (or the default standing
60
+ view near `[0, 1.6, 0]`) before accepting XR framing.
58
61
 
59
62
  ## Validation
60
63
 
@@ -47,11 +47,14 @@ node already uses instead of normalising.
47
47
 
48
48
  `LevelRoot`, `LevelTag` and `Transform` are runtime-owned; never author them.
49
49
 
50
- ## The scene owns the runtime camera
51
-
52
- The hero authoring view supersedes `world.render.camera` from
53
- `iwsdk.config.json` once the level initialises. Changing the config camera to fix
54
- runtime framing will appear to do nothing — change the hero view instead.
50
+ ## Browser hero views and XR spawn framing are distinct
51
+
52
+ Outside immersive XR, the hero authoring view supersedes `world.render.camera`
53
+ from `iwsdk.config.json` once the level initialises. While XR is presenting,
54
+ the tracked player rig owns the camera and the hero view is intentionally not
55
+ applied. Use the hero view for editor/browser framing, and validate important
56
+ content from the authored `player.transform` spawn (or the default standing
57
+ view near `[0, 1.6, 0]`) before accepting XR framing.
55
58
 
56
59
  ## Validation
57
60
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@iwsdk/create",
3
- "version": "0.5.0",
3
+ "version": "0.5.2",
4
4
  "description": "Interactive CLI to scaffold Immersive Web SDK starter apps",
5
5
  "type": "module",
6
6
  "private": false,
@@ -14,18 +14,6 @@
14
14
  "scripts/verify-release-ready.mjs",
15
15
  "README.md"
16
16
  ],
17
- "scripts": {
18
- "prebuild": "node scripts/gen-version.cjs && node scripts/build-template.mjs",
19
- "prepublishOnly": "corepack pnpm@10.18.3 build && corepack pnpm@10.18.3 verify:release-ready",
20
- "build": "rollup -c",
21
- "dev": "corepack pnpm@10.18.3 -s build && node dist/cli.js",
22
- "watch": "rollup -c --watch",
23
- "clean": "rm -rf dist",
24
- "test": "corepack pnpm@10.18.3 --filter @iwsdk/scene-composition build && corepack pnpm@10.18.3 --filter @iwsdk/cli build && corepack pnpm@10.18.3 build && vitest run",
25
- "test:watch": "vitest",
26
- "test:coverage": "vitest run --coverage",
27
- "verify:release-ready": "node scripts/verify-release-ready.mjs"
28
- },
29
17
  "keywords": [
30
18
  "create",
31
19
  "cli",
@@ -44,21 +32,32 @@
44
32
  "node": ">=20.19.0 <21.0.0-0 || >=22.12.0 <23.0.0-0 || >=24.0.0"
45
33
  },
46
34
  "dependencies": {
47
- "cross-spawn": "^7.0.6",
48
35
  "chalk": "^5.6.2",
49
36
  "commander": "^14.0.0",
50
- "semver": "^7.6.3",
37
+ "cross-spawn": "^7.0.6",
51
38
  "ora": "^8.2.0",
52
- "prompts": "^2.4.2"
39
+ "prompts": "^2.4.2",
40
+ "semver": "^7.6.3"
53
41
  },
54
42
  "devDependencies": {
55
- "@iwsdk/cli": "workspace:*",
56
- "@iwsdk/core": "workspace:*",
57
- "@iwsdk/scene-composition": "workspace:*",
43
+ "@types/cross-spawn": "^6.0.6",
58
44
  "@types/prompts": "^2.4.9",
59
45
  "@types/semver": "^7.5.8",
60
- "@types/cross-spawn": "^6.0.6",
61
46
  "typescript": "^5.8.3",
62
- "vitest": "^4.1.10"
47
+ "vitest": "^4.1.10",
48
+ "@iwsdk/core": "0.5.2",
49
+ "@iwsdk/scene-composition": "0.5.2",
50
+ "@iwsdk/cli": "0.5.2"
51
+ },
52
+ "scripts": {
53
+ "prebuild": "node scripts/gen-version.cjs && node scripts/build-template.mjs",
54
+ "build": "rollup -c",
55
+ "dev": "corepack pnpm@10.18.3 -s build && node dist/cli.js",
56
+ "watch": "rollup -c --watch",
57
+ "clean": "rm -rf dist",
58
+ "test": "corepack pnpm@10.18.3 --filter @iwsdk/scene-composition build && corepack pnpm@10.18.3 --filter @iwsdk/cli build && corepack pnpm@10.18.3 build && vitest run",
59
+ "test:watch": "vitest",
60
+ "test:coverage": "vitest run --coverage",
61
+ "verify:release-ready": "node scripts/verify-release-ready.mjs"
63
62
  }
64
- }
63
+ }