@iwsdk/create 0.5.2 → 1.0.0-rc.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/dist/cli.js +7223 -215
  2. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/SKILL.md +311 -0
  3. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  4. package/dist/guidance/agents/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  5. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/SKILL.md +262 -0
  6. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  7. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  8. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  9. package/dist/guidance/{claude/.claude/skills/iwsdk-scene-composer → agents/.agents/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
  10. package/dist/guidance/agents/.agents/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  11. package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
  12. package/dist/guidance/agents/.agents/skills/iwsdk-debug/SKILL.md +69 -91
  13. package/dist/guidance/agents/.agents/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
  14. package/dist/guidance/agents/.agents/skills/iwsdk-dev/SKILL.md +45 -0
  15. package/dist/guidance/{claude/.claude/skills/iwsdk-planner → agents/.agents/skills/iwsdk-dev}/references/api-reference.md +53 -45
  16. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/iterate.md +239 -0
  17. package/dist/guidance/agents/.agents/skills/iwsdk-dev/references/planner.md +303 -0
  18. package/dist/guidance/agents/.agents/skills/iwsdk-grab/SKILL.md +37 -114
  19. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/SKILL.md +177 -0
  20. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  21. package/dist/guidance/agents/.agents/skills/iwsdk-hosting/references/vercel.md +114 -0
  22. package/dist/guidance/agents/.agents/skills/iwsdk-native-xr-test/SKILL.md +246 -0
  23. package/dist/guidance/agents/.agents/skills/iwsdk-physics/SKILL.md +92 -78
  24. package/dist/guidance/agents/.agents/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
  25. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
  26. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  27. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  28. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  29. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  30. package/dist/guidance/agents/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  31. package/dist/guidance/agents/.agents/skills/iwsdk-ray/SKILL.md +45 -136
  32. package/dist/guidance/agents/.agents/skills/iwsdk-ui/SKILL.md +251 -157
  33. package/dist/guidance/claude/.claude/agents/iwsdk-project-code-reviewer.md +9 -6
  34. package/dist/guidance/claude/.claude/rules/scene-json.md +6 -4
  35. package/dist/guidance/claude/.claude/settings.json +6 -2
  36. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/SKILL.md +311 -0
  37. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/agents/openai.yaml +4 -0
  38. package/dist/guidance/claude/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +599 -0
  39. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/SKILL.md +262 -0
  40. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +4 -0
  41. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +166 -0
  42. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +80 -0
  43. package/dist/guidance/{agents/.agents/skills/iwsdk-scene-composer → claude/.claude/skills/iwsdk-compose-scene}/references/scene-format.md +3 -3
  44. package/dist/guidance/claude/.claude/skills/iwsdk-compose-scene/references/scene-review.md +66 -0
  45. package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/text-intake.md +3 -5
  46. package/dist/guidance/claude/.claude/skills/iwsdk-debug/SKILL.md +69 -91
  47. package/dist/guidance/claude/.claude/skills/iwsdk-depth-occlusion/SKILL.md +81 -129
  48. package/dist/guidance/claude/.claude/skills/iwsdk-dev/SKILL.md +45 -0
  49. package/dist/guidance/{agents/.agents/skills/iwsdk-planner → claude/.claude/skills/iwsdk-dev}/references/api-reference.md +53 -45
  50. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/iterate.md +239 -0
  51. package/dist/guidance/claude/.claude/skills/iwsdk-dev/references/planner.md +303 -0
  52. package/dist/guidance/claude/.claude/skills/iwsdk-grab/SKILL.md +37 -114
  53. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/SKILL.md +177 -0
  54. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/existing-hosts.md +181 -0
  55. package/dist/guidance/claude/.claude/skills/iwsdk-hosting/references/vercel.md +114 -0
  56. package/dist/guidance/claude/.claude/skills/iwsdk-native-xr-test/SKILL.md +246 -0
  57. package/dist/guidance/claude/.claude/skills/iwsdk-physics/SKILL.md +92 -78
  58. package/dist/guidance/claude/.claude/skills/iwsdk-physics/references/tuning-and-config.md +15 -1
  59. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/SKILL.md +218 -0
  60. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +104 -0
  61. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +219 -0
  62. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +149 -0
  63. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +104 -0
  64. package/dist/guidance/claude/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +178 -0
  65. package/dist/guidance/claude/.claude/skills/iwsdk-ray/SKILL.md +45 -136
  66. package/dist/guidance/claude/.claude/skills/iwsdk-ui/SKILL.md +251 -157
  67. package/dist/guidance/claude/CLAUDE.md +2 -141
  68. package/dist/guidance/codex/.codex/config.toml +1 -1
  69. package/dist/guidance/common/AGENTS.md +96 -37
  70. package/dist/guidance/copilot/.github/instructions/scene-json.instructions.md +6 -4
  71. package/dist/guidance/cursor/.cursor/rules/scene-json.mdc +6 -4
  72. package/dist/guidance/scoped-agents/public/scenes/AGENTS.md +6 -4
  73. package/dist/template/common/README.md +13 -0
  74. package/dist/template/common/public/ui/welcome.uikitml +0 -19
  75. package/dist/template/common/src/robot.ts +5 -0
  76. package/dist/template/common/vite.config.ts +18 -0
  77. package/dist/template/common-js/README.md +13 -0
  78. package/dist/template/common-js/public/ui/welcome.uikitml +0 -19
  79. package/dist/template/common-js/src/robot.js +5 -0
  80. package/dist/template/common-js/vite.config.js +18 -0
  81. package/dist/template/scenes/ar.iwsdk.scene.json +8 -1
  82. package/package.json +8 -7
  83. package/scripts/verify-release-ready.mjs +25 -0
  84. package/dist/guidance/agents/.agents/skills/iwsdk-planner/SKILL.md +0 -364
  85. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/build-milestones.md +0 -243
  86. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/design-deck.md +0 -101
  87. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/grounding.md +0 -176
  88. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/ideation.md +0 -156
  89. package/dist/guidance/agents/.agents/skills/iwsdk-planner/references/verification.md +0 -199
  90. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/SKILL.md +0 -257
  91. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
  92. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
  93. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
  94. package/dist/guidance/agents/.agents/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
  95. package/dist/guidance/claude/.claude/skills/iwsdk-planner/SKILL.md +0 -364
  96. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/build-milestones.md +0 -243
  97. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/design-deck.md +0 -101
  98. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/grounding.md +0 -176
  99. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/ideation.md +0 -156
  100. package/dist/guidance/claude/.claude/skills/iwsdk-planner/references/verification.md +0 -199
  101. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/SKILL.md +0 -257
  102. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/agents/openai.yaml +0 -4
  103. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/asset-authoring.md +0 -295
  104. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/composition-patterns.md +0 -243
  105. package/dist/guidance/claude/.claude/skills/iwsdk-scene-composer/references/review-and-stop.md +0 -99
  106. /package/dist/guidance/agents/.agents/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
  107. /package/dist/guidance/claude/.claude/skills/{iwsdk-scene-composer → iwsdk-compose-scene}/references/image-intake.md +0 -0
@@ -8,25 +8,48 @@ format. Harnesses that use `AGENTS.md` also receive equivalent nested files near
8
8
  the code they govern. Read the applicable scoped instructions before working in
9
9
  that area.
10
10
 
11
+ Explain immersive terms in plain language when they first matter instead of
12
+ assuming the reader knows them. In particular, introduce XR (an immersive
13
+ session), IWER (IWSDK's browser-based XR emulator), ECS (entity-component
14
+ system), and controller target-ray versus grip poses with a link to the
15
+ applicable IWSDK guide or concept page.
16
+
11
17
  ## What is not standard Vite
12
18
 
13
19
  **`iwsdk.config.json` is the project authority, not `vite.config.ts`.** It selects
14
20
  the active scene, the asset module, the component module, and all XR/world
15
21
  features. `vite.config.ts` only wires the plugin. Editing `iwsdk.config.json`
16
22
  restarts Vite in place; the managed window remains open and its command bridges
17
- reconnect automatically. Wait for `npx iwsdk dev status` to report
23
+ reconnect automatically. Wait for `npx @iwsdk/cli dev status` to report
18
24
  `browserCommandReady: true` before issuing browser-backed commands.
19
25
 
20
26
  **`virtual:iwsdk-project` is a virtual module**, not a file. `src/index.ts` or
21
27
  `src/index.js` imports it and passes it whole to `World.create()`. Do not
22
28
  hand-build that options object.
23
29
 
24
- **The dev server is CLI-managed.** Use `npx iwsdk dev up` (or `npm run dev`), not
30
+ **The dev server is CLI-managed.** Use `npx @iwsdk/cli dev up` (or `npm run dev`), not
25
31
  `vite`. It launches a managed browser that hosts the MCP command bridge.
26
- `--no-open` intentionally starts only the server: status reports
27
- `browser.status: "not_launched"`, and browser-backed commands fail immediately
28
- with `browser_not_launched` plus restart guidance. One managed window hosts two
29
- roles, editor and runtime.
32
+ `--no-open` starts the server with managed-browser launch disabled. Server status
33
+ and explicitly paired physical targets remain available. A targetless managed
34
+ browser command then fails with `browser_not_launched`; it never falls through
35
+ to a physical page. Commands default to the managed browser. One managed
36
+ window hosts the editor and application roles. Browser failure leaves Vite and
37
+ HMR running. `runtime status`, `runtime targets`, and `runtime wait` do not recover
38
+ or launch a browser; `runtime recover` explicitly retries after a failure.
39
+
40
+ Pair a headset using `runtime pair-headset --input-json '{"headsetId":"ADB_SERIAL"}'`,
41
+ open the returned URL on that exact device through ADB reverse, then copy its
42
+ `runtimeTarget` from `runtime targets`. Include deviceClass, headsetId, pageId, and
43
+ tabGeneration on every physical command. Reload is supported through the page
44
+ bridge; screenshot, snapshot, interaction, profiling, console capture, and the
45
+ managed editor are host-only. Rediscover after reload to get the new generation.
46
+
47
+ The developer owns whether that managed window is headed or headless. Do not
48
+ change modes silently: announce the change before restarting. In a visible
49
+ collaboration session, use the Runtime/Editor toggle in the single managed
50
+ Chromium window. Its expected unsupported-flag banner comes from
51
+ `--ignore-certificate-errors` for the local development certificate. Playwright
52
+ may add separate sandbox-related flags in constrained environments.
30
53
 
31
54
  **`src/assets.ts`/`src/assets.js` is evaluated twice, in two different JS
32
55
  realms** — once by the app runtime, once by the editor. It must be deterministic
@@ -47,28 +70,32 @@ and subtle breakage. Exception: `import type { GLTF } from 'three/addons/...'`.
47
70
 
48
71
  ## Traps that produce silent failures
49
72
 
50
- | Trap | Symptom | Fix |
51
- | ------------------------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
52
- | `locomotion: true` with no `LocomotionEnvironment` on a floor | player falls through the world | add the component to a walkable surface |
53
- | Scene origin left occupied | player spawns inside your geometry | the player origin is `0,0,0` unless the scene authors `player.transform` |
54
- | Scene JSON with `imports` | authoring preview works, but editable open and runtime load are rejected | run `npx iwsdk scene flatten` once, then edit the flat output |
55
- | `entity.destroy()` | GPU memory leaked | use `entity.dispose()` |
56
- | `setValue` on a Vec2/Vec3/Vec4/Color field | throws in elics 3.4.x | use `entity.getVectorView(...)` |
57
- | Environment component on a non-root entity | silently ignored | `DomeGradient`/`IBLGradient` go on the level root only |
58
- | Environment prop changed without `_needsUpdate` | change ignored | set `_needsUpdate` after writing |
59
- | `ScreenSpace` given numbers | clamped with a console warning | it takes CSS strings: `'400px'`, `'25vw'` |
60
- | `@iwsdk/reference` MCP tools in an old or `--no-install` app | queries report warmup required | run `npx iwsdk reference warmup`; fresh installed scaffolds do this during creation |
73
+ | Trap | Symptom | Fix |
74
+ | ------------------------------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- |
75
+ | `locomotion: true` with no `LocomotionEnvironment` on a floor | player falls through the world | add the component to a walkable surface |
76
+ | Scene origin left occupied | player spawns inside your geometry | the player origin is `0,0,0` unless the scene authors `player.transform` |
77
+ | Scene JSON with `imports` | authoring preview works, but editable open and runtime load are rejected | run `npx @iwsdk/cli scene flatten` once, then edit the flat output |
78
+ | `entity.destroy()` | GPU memory leaked | use `entity.dispose()` |
79
+ | `setValue` on a Vec2/Vec3/Vec4/Color field | throws in elics 3.4.x | use `entity.getVectorView(...)` |
80
+ | Environment component on a non-root entity | silently ignored | `DomeGradient`/`IBLGradient` go on the level root only |
81
+ | Environment prop changed without `_needsUpdate` | change ignored | set `_needsUpdate` after writing |
82
+ | `ScreenSpace` given numbers | clamped with a console warning | it takes CSS strings: `'400px'`, `'25vw'` |
83
+ | `@iwsdk/reference` MCP tools in an old or `--no-install` app | queries report warmup required | run `npx @iwsdk/cli reference warmup`; fresh installed scaffolds do this during creation |
61
84
 
62
85
  ## Verify before you claim it works
63
86
 
64
- **Always `npx tsc --noEmit` before testing.** Type errors stop systems
87
+ **Always `npm run --if-present typecheck` before testing.** Type errors stop systems
65
88
  initialising without necessarily logging anything in the browser.
66
89
 
90
+ For a new multi-file procedural model, finish the initial asset module and manifest
91
+ registration before `npx @iwsdk/cli dev up`; do not keep the browser live while its import
92
+ graph is half-written. Typecheck first, then launch the managed editor for inspection.
93
+
67
94
  Then check the right status for the task — these are not interchangeable:
68
95
 
69
96
  - scene/editor work → `scene_get_state`
70
97
  - XR device or session actions → `xr_get_session_status`
71
- - server readiness → `npx iwsdk dev status` (XR availability is not a server signal)
98
+ - server readiness → `npx @iwsdk/cli dev status` (XR availability is not a server signal)
72
99
 
73
100
  When something is missing but the console is clean: call
74
101
  `browser_get_console_logs` with only `count` (a `level` filter hides errors), then
@@ -79,41 +106,73 @@ The non-obvious part is which observation proves what: the **editor** render doe
79
106
  not run application systems, so anything driven by a system must be verified with
80
107
  `browser_screenshot` (runtime), not `scene_screenshot` (editor).
81
108
 
109
+ Pose, controller/hand alignment, and immersive interaction claims require an
110
+ active XR session (`npx @iwsdk/cli xr status`). A flat runtime screenshot taken
111
+ outside XR can prove that the app renders, but it cannot prove immersive pose or
112
+ interaction correctness.
113
+
114
+ For a physical headset smoke test, run `npx @iwsdk/cli dev status`, open a URL from
115
+ `data.runtimeUrls.network` on a headset connected to the same Wi-Fi network,
116
+ and accept the expected local certificate warning. See
117
+ [Testing Your Experience](https://iwsdk.dev/guides/02-testing-experience.html)
118
+ for the complete workflow.
119
+
82
120
  ## MCP and CLI are one surface, not two
83
121
 
84
122
  Nearly every capability exists both ways — `scene_render_file` and
85
- `npx iwsdk scene render-file`, `ecs_find_entities` and `npx iwsdk ecs find`.
86
- Discover CLI actions with the bare domain or domain help (`npx iwsdk scene` or
87
- `npx iwsdk scene --help`); both list that domain's actions.
88
-
89
- **The CLI is not a fallback for a dead bridge.** Both routes drive the same
90
- managed browser, so when `dev status` reports `browserConnected: false`,
91
- every scene/ecs/xr/browser/ui command fails either way. Only `dev status`,
92
- `dev logs` and `reference status` work without a browser.
123
+ `npx @iwsdk/cli scene render-file`, `ecs_find_entities` and `npx @iwsdk/cli ecs find`,
124
+ or `ui_inspect` and `npx @iwsdk/cli ui inspect`.
125
+ Discover CLI actions with the bare domain or domain help (`npx @iwsdk/cli scene` or
126
+ `npx @iwsdk/cli scene --help`); both list that domain's actions.
127
+
128
+ **CLI and MCP share the same target resolver and recovery policy.** A managed
129
+ command can recover a missing managed browser; it then returns
130
+ `browser_relaunched` with `outcome: "not_executed"`. Inspect the new state and issue
131
+ a fresh command. `outcome_unknown` means a dispatched mutation may have executed;
132
+ inspect state before retrying. Requests are never broadcast or replayed on
133
+ reconnect. Host browser tools can remain usable while a runtime bridge is loading.
93
134
 
94
135
  Choose by the shape of the call, not by availability:
95
136
 
96
- - **MCP** for one-off calls, and whenever you want the image returned inline.
137
+ - **MCP** for one-off calls. Screenshot tools persist the PNG locally and return
138
+ `screenshotPath`; read that file only when visual inspection is needed.
97
139
  - **CLI** when you need to loop or script — rendering six views, or sampling a
98
140
  value twice to measure a rate — or when the response is big enough to be worth
99
141
  filtering before it reaches context. A render of a scene containing an
100
142
  instanced pattern returns an id for every expanded instance.
101
143
 
102
- CLI `--output-file` returns a **different payload shape** from the plain call:
103
- the result nests under `data.result` instead of `data`, and `renderStats` and the
104
- hashes are dropped. If you need a hash or triangle count, omit `--output-file`
105
- and filter the JSON instead.
144
+ For screenshot-producing CLI commands, the default response writes the image to a
145
+ temporary file and returns a normal envelope with metadata under `data.result` and
146
+ the path at `data.screenshotPath`. `--output-file <path>` selects the destination and
147
+ keeps that same metadata, including hashes and render statistics. `--raw` instead
148
+ prints the raw runtime result, including base64 `imageData`; when both flags are
149
+ present, `--output-file` takes precedence and image bytes are omitted.
106
150
 
107
151
  ## Skills
108
152
 
109
- Scene composition, UI authoring, physics, depth occlusion, grab and ray
110
- interaction testing, ECS frame-stepping, and end-to-end planning each have a
111
- project skill in the selected harness's standard skill directory. Their
112
- descriptions handle routing, so they are not restated here.
153
+ Invoke `iwsdk-dev` first for any request that builds, extends, fixes, tunes,
154
+ or polishes the app. It privately selects the greenfield planner path or the
155
+ bounded established-app iteration path; do not look for those paths as separate
156
+ public skills.
157
+
158
+ The selected playbook routes work to the narrowest owning specialist:
159
+
160
+ - creating or materially changing one glTF or procedural 3D asset →
161
+ `iwsdk-build-model`;
162
+ - arranging existing assets, scene JSON, cross-asset contacts, lighting,
163
+ environment, or cameras → `iwsdk-compose-scene`;
164
+ - a mixed build → finish every new or changed model, including support and set assets,
165
+ with `iwsdk-build-model`, then compose the scene with `iwsdk-compose-scene`;
166
+ - a model-local defect found during composition routes back to `iwsdk-build-model`;
167
+ a placement or lighting defect stays in `iwsdk-compose-scene`.
168
+
169
+ UI authoring, physics, depth occlusion, grab and ray interaction testing, ECS
170
+ frame-stepping, and debugging have their own project skills. Use them only when
171
+ the selected `iwsdk-dev` playbook calls for the matching specialty.
113
172
 
114
173
  The failure worth guarding against is improvising a domain that already has a
115
174
  skill because the naive approach looks tractable. Before hand-authoring scene
116
- JSON, a UIKitML panel, or a physics body, invoke the skill.
175
+ JSON, a 3D model, a UIKitML panel, or a physics body, invoke the owning skill.
117
176
 
118
177
  ## Layout
119
178
 
@@ -5,10 +5,12 @@ applyTo: "public/scenes/**"
5
5
  # Scene JSON — things that fail silently
6
6
 
7
7
  Format reference lives in
8
- `.agents/skills/iwsdk-scene-composer/references/scene-format.md`: the document
8
+ `.agents/skills/iwsdk-compose-scene/references/scene-format.md`: the document
9
9
  boundary, content kinds, prefabs, patterns, light fields, authoring views. Read
10
- it before composing. This file is only the short list of behaviours that produce
11
- no error when you get them wrong.
10
+ it for imports, prefabs, patterns, or a schema detail not covered by active
11
+ guidance. For ordinary flat node, component, and authored-view edits, this rule,
12
+ the existing scene, and the active specialist are sufficient. This file is only
13
+ the short list of behaviours that produce no error when you get them wrong.
12
14
 
13
15
  Only `iwsdk.scene.v1` exists, units are always meters, and structural objects are
14
16
  closed — an unknown field fails validation.
@@ -18,7 +20,7 @@ closed — an unknown field fails validation.
18
20
  Authoring tools can validate and render a root with `imports`, so modular scratch
19
21
  scenes remain useful for composition. The editable scene session and application
20
22
  runtime deliberately reject imports. Run `scene_flatten_file` or
21
- `npx iwsdk scene flatten` once, verify the source and output runtime hashes match,
23
+ `npx @iwsdk/cli scene flatten` once, verify the source and output runtime hashes match,
22
24
  then make the flat output the sole editable source of truth. Never re-flatten over
23
25
  later human editor changes.
24
26
 
@@ -8,10 +8,12 @@ alwaysApply: false
8
8
  # Scene JSON — things that fail silently
9
9
 
10
10
  Format reference lives in
11
- `.agents/skills/iwsdk-scene-composer/references/scene-format.md`: the document
11
+ `.agents/skills/iwsdk-compose-scene/references/scene-format.md`: the document
12
12
  boundary, content kinds, prefabs, patterns, light fields, authoring views. Read
13
- it before composing. This file is only the short list of behaviours that produce
14
- no error when you get them wrong.
13
+ it for imports, prefabs, patterns, or a schema detail not covered by active
14
+ guidance. For ordinary flat node, component, and authored-view edits, this rule,
15
+ the existing scene, and the active specialist are sufficient. This file is only
16
+ the short list of behaviours that produce no error when you get them wrong.
15
17
 
16
18
  Only `iwsdk.scene.v1` exists, units are always meters, and structural objects are
17
19
  closed — an unknown field fails validation.
@@ -21,7 +23,7 @@ closed — an unknown field fails validation.
21
23
  Authoring tools can validate and render a root with `imports`, so modular scratch
22
24
  scenes remain useful for composition. The editable scene session and application
23
25
  runtime deliberately reject imports. Run `scene_flatten_file` or
24
- `npx iwsdk scene flatten` once, verify the source and output runtime hashes match,
26
+ `npx @iwsdk/cli scene flatten` once, verify the source and output runtime hashes match,
25
27
  then make the flat output the sole editable source of truth. Never re-flatten over
26
28
  later human editor changes.
27
29
 
@@ -5,10 +5,12 @@ This file augments the repository-root `AGENTS.md` for files in this directory.
5
5
  # Scene JSON — things that fail silently
6
6
 
7
7
  Format reference lives in
8
- `.agents/skills/iwsdk-scene-composer/references/scene-format.md`: the document
8
+ `.agents/skills/iwsdk-compose-scene/references/scene-format.md`: the document
9
9
  boundary, content kinds, prefabs, patterns, light fields, authoring views. Read
10
- it before composing. This file is only the short list of behaviours that produce
11
- no error when you get them wrong.
10
+ it for imports, prefabs, patterns, or a schema detail not covered by active
11
+ guidance. For ordinary flat node, component, and authored-view edits, this rule,
12
+ the existing scene, and the active specialist are sufficient. This file is only
13
+ the short list of behaviours that produce no error when you get them wrong.
12
14
 
13
15
  Only `iwsdk.scene.v1` exists, units are always meters, and structural objects are
14
16
  closed — an unknown field fails validation.
@@ -18,7 +20,7 @@ closed — an unknown field fails validation.
18
20
  Authoring tools can validate and render a root with `imports`, so modular scratch
19
21
  scenes remain useful for composition. The editable scene session and application
20
22
  runtime deliberately reject imports. Run `scene_flatten_file` or
21
- `npx iwsdk scene flatten` once, verify the source and output runtime hashes match,
23
+ `npx @iwsdk/cli scene flatten` once, verify the source and output runtime hashes match,
22
24
  then make the flat output the sole editable source of truth. Never re-flatten over
23
25
  later human editor changes.
24
26
 
@@ -11,3 +11,16 @@ npm run dev
11
11
 
12
12
  Use the Runtime and Editor controls in the managed browser to switch between
13
13
  the running experience and its authored scene.
14
+
15
+ ## Starter content
16
+
17
+ The robot and welcome panel are small examples of authored scene content plus
18
+ runtime systems. The robot turns toward the player's head and plays a sound
19
+ when pressed. To remove the robot, delete its scene node, its `RobotSystem`
20
+ registration from `src/index.ts` or `src/index.js`, and its `Robot` registration
21
+ from `src/components.ts` or `src/components.js`; you can then delete the unused
22
+ robot component and system files. To remove the welcome panel, delete its scene
23
+ node and its `PanelSystem` registration from the application entry point.
24
+
25
+ - Minimal scene walkthrough: https://iwsdk.dev/guides/01b-minimal-scene.html
26
+ - XR-enabled projects — IWER emulator controls: https://iwsdk.dev/guides/02-testing-experience.html#iwer-controls
@@ -3,27 +3,8 @@
3
3
  Horizon kit. RectangleGoggles and LogIn are bundled Lucide icon components.
4
4
  -->
5
5
  <style>
6
- @font-face {
7
- font-family: "DM Sans";
8
- src: url("https://fonts.gstatic.com/s/dmsans/v17/rP2tp2ywxg089UriI5-g4vlH9VoD8CmcqZG40F9JadbnoEwAopxhTg.ttf");
9
- font-weight: 400;
10
- }
11
-
12
- @font-face {
13
- font-family: "DM Sans";
14
- src: url("https://fonts.gstatic.com/s/dmsans/v17/rP2tp2ywxg089UriI5-g4vlH9VoD8CmcqZG40F9JadbnoEwAkJxhTg.ttf");
15
- font-weight: 500;
16
- }
17
-
18
- @font-face {
19
- font-family: "DM Sans";
20
- src: url("https://fonts.gstatic.com/s/dmsans/v17/rP2tp2ywxg089UriI5-g4vlH9VoD8CmcqZG40F9JadbnoEwARZthTg.ttf");
21
- font-weight: 700;
22
- }
23
-
24
6
  .panel-root {
25
7
  flex-direction: column;
26
- font-family: "DM Sans";
27
8
  width: 344px;
28
9
  }
29
10
 
@@ -8,6 +8,11 @@
8
8
  import { AudioUtils, createSystem, Pressed, Vector3 } from '@iwsdk/core';
9
9
  import { Robot } from './robot-component.js';
10
10
 
11
+ /**
12
+ * Starter-only behavior for the sample robot: face the player and play its
13
+ * configured audio when pressed. It is safe to delete with the robot scene
14
+ * node, Robot component declaration, and registration in src/index.ts.
15
+ */
11
16
  export class RobotSystem extends createSystem({
12
17
  robot: { required: [Robot] },
13
18
  robotClicked: { required: [Robot, Pressed] },
@@ -18,8 +18,26 @@ export default defineConfig({
18
18
  rollupOptions: { input: './index.html' },
19
19
  },
20
20
  esbuild: { target: 'esnext' },
21
+ // @drawcall/uikitml otherwise pulls a second three/@pmndrs/uikit graph
22
+ // (three@0.185 vs app super-three@0.181). Duplicate Component classes break
23
+ // instanceof checks → "Only pmndrs/uikit components can be added as children".
24
+ resolve: {
25
+ dedupe: [
26
+ 'three',
27
+ '@pmndrs/uikit',
28
+ '@pmndrs/uikit-horizon',
29
+ '@pmndrs/uikit-lucide',
30
+ ],
31
+ },
21
32
  optimizeDeps: {
22
33
  exclude: ['@babylonjs/havok'],
34
+ include: [
35
+ 'three',
36
+ '@pmndrs/uikit',
37
+ '@pmndrs/uikit-horizon',
38
+ '@pmndrs/uikit-lucide',
39
+ '@drawcall/uikitml',
40
+ ],
23
41
  esbuildOptions: { target: 'esnext' },
24
42
  },
25
43
  publicDir: 'public',
@@ -11,3 +11,16 @@ npm run dev
11
11
 
12
12
  Use the Runtime and Editor controls in the managed browser to switch between
13
13
  the running experience and its authored scene.
14
+
15
+ ## Starter content
16
+
17
+ The robot and welcome panel are small examples of authored scene content plus
18
+ runtime systems. The robot turns toward the player's head and plays a sound
19
+ when pressed. To remove the robot, delete its scene node, its `RobotSystem`
20
+ registration from `src/index.ts` or `src/index.js`, and its `Robot` registration
21
+ from `src/components.ts` or `src/components.js`; you can then delete the unused
22
+ robot component and system files. To remove the welcome panel, delete its scene
23
+ node and its `PanelSystem` registration from the application entry point.
24
+
25
+ - Minimal scene walkthrough: https://iwsdk.dev/guides/01b-minimal-scene.html
26
+ - XR-enabled projects — IWER emulator controls: https://iwsdk.dev/guides/02-testing-experience.html#iwer-controls
@@ -3,27 +3,8 @@
3
3
  Horizon kit. RectangleGoggles and LogIn are bundled Lucide icon components.
4
4
  -->
5
5
  <style>
6
- @font-face {
7
- font-family: "DM Sans";
8
- src: url("https://fonts.gstatic.com/s/dmsans/v17/rP2tp2ywxg089UriI5-g4vlH9VoD8CmcqZG40F9JadbnoEwAopxhTg.ttf");
9
- font-weight: 400;
10
- }
11
-
12
- @font-face {
13
- font-family: "DM Sans";
14
- src: url("https://fonts.gstatic.com/s/dmsans/v17/rP2tp2ywxg089UriI5-g4vlH9VoD8CmcqZG40F9JadbnoEwAkJxhTg.ttf");
15
- font-weight: 500;
16
- }
17
-
18
- @font-face {
19
- font-family: "DM Sans";
20
- src: url("https://fonts.gstatic.com/s/dmsans/v17/rP2tp2ywxg089UriI5-g4vlH9VoD8CmcqZG40F9JadbnoEwARZthTg.ttf");
21
- font-weight: 700;
22
- }
23
-
24
6
  .panel-root {
25
7
  flex-direction: column;
26
- font-family: "DM Sans";
27
8
  width: 344px;
28
9
  }
29
10
 
@@ -6,6 +6,11 @@
6
6
  */
7
7
  import { AudioUtils, createSystem, Pressed, Vector3 } from '@iwsdk/core';
8
8
  import { Robot } from './robot-component.js';
9
+ /**
10
+ * Starter-only behavior for the sample robot: face the player and play its
11
+ * configured audio when pressed. It is safe to delete with the robot scene
12
+ * node, Robot component declaration, and registration in src/index.ts.
13
+ */
9
14
  export class RobotSystem extends createSystem({
10
15
  robot: { required: [Robot] },
11
16
  robotClicked: { required: [Robot, Pressed] },
@@ -16,8 +16,26 @@ export default defineConfig({
16
16
  rollupOptions: { input: './index.html' },
17
17
  },
18
18
  esbuild: { target: 'esnext' },
19
+ // @drawcall/uikitml otherwise pulls a second three/@pmndrs/uikit graph
20
+ // (three@0.185 vs app super-three@0.181). Duplicate Component classes break
21
+ // instanceof checks → "Only pmndrs/uikit components can be added as children".
22
+ resolve: {
23
+ dedupe: [
24
+ 'three',
25
+ '@pmndrs/uikit',
26
+ '@pmndrs/uikit-horizon',
27
+ '@pmndrs/uikit-lucide',
28
+ ],
29
+ },
19
30
  optimizeDeps: {
20
31
  exclude: ['@babylonjs/havok'],
32
+ include: [
33
+ 'three',
34
+ '@pmndrs/uikit',
35
+ '@pmndrs/uikit-horizon',
36
+ '@pmndrs/uikit-lucide',
37
+ '@drawcall/uikitml',
38
+ ],
21
39
  esbuildOptions: { target: 'esnext' },
22
40
  },
23
41
  publicDir: 'public',
@@ -1,7 +1,14 @@
1
1
  {
2
2
  "version": "iwsdk.scene.v1",
3
3
  "units": "meters",
4
- "components": {},
4
+ "components": {
5
+ "com.iwsdk.components.IBLGradient": {
6
+ "sky": [0.6902, 0.749, 0.7843, 1],
7
+ "equator": [0.6584, 0.7084, 0.7913, 1],
8
+ "ground": [0.807, 0.7758, 0.7454, 1],
9
+ "intensity": 1
10
+ }
11
+ },
5
12
  "resources": {},
6
13
  "nodes": [
7
14
  {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@iwsdk/create",
3
- "version": "0.5.2",
3
+ "version": "1.0.0-rc.0",
4
4
  "description": "Interactive CLI to scaffold Immersive Web SDK starter apps",
5
5
  "type": "module",
6
6
  "private": false,
@@ -37,7 +37,8 @@
37
37
  "cross-spawn": "^7.0.6",
38
38
  "ora": "^8.2.0",
39
39
  "prompts": "^2.4.2",
40
- "semver": "^7.6.3"
40
+ "semver": "^7.6.3",
41
+ "yaml": "2.8.3"
41
42
  },
42
43
  "devDependencies": {
43
44
  "@types/cross-spawn": "^6.0.6",
@@ -45,17 +46,17 @@
45
46
  "@types/semver": "^7.5.8",
46
47
  "typescript": "^5.8.3",
47
48
  "vitest": "^4.1.10",
48
- "@iwsdk/core": "0.5.2",
49
- "@iwsdk/scene-composition": "0.5.2",
50
- "@iwsdk/cli": "0.5.2"
49
+ "@iwsdk/cli": "1.0.0-rc.0",
50
+ "@iwsdk/scene-composition": "1.0.0-rc.0",
51
+ "@iwsdk/core": "1.0.0-rc.0"
51
52
  },
52
53
  "scripts": {
53
54
  "prebuild": "node scripts/gen-version.cjs && node scripts/build-template.mjs",
54
55
  "build": "rollup -c",
55
- "dev": "corepack pnpm@10.18.3 -s build && node dist/cli.js",
56
+ "dev": "npm run --silent build && node dist/cli.js",
56
57
  "watch": "rollup -c --watch",
57
58
  "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": "npm --prefix ../scene-composition run build && npm --prefix ../cli run build && npm run build && vitest run",
59
60
  "test:watch": "vitest",
60
61
  "test:coverage": "vitest run --coverage",
61
62
  "verify:release-ready": "node scripts/verify-release-ready.mjs"
@@ -11,6 +11,7 @@ import { tmpdir } from 'node:os';
11
11
  import path from 'node:path';
12
12
  import { fileURLToPath } from 'node:url';
13
13
  import { promisify } from 'node:util';
14
+ import { parse } from 'yaml';
14
15
 
15
16
  const execFileAsync = promisify(execFile);
16
17
 
@@ -45,6 +46,30 @@ try {
45
46
  const packageJson = JSON.parse(
46
47
  await readFile(path.join(appRoot, 'package.json'), 'utf8'),
47
48
  );
49
+ const pnpmWorkspace = parse(
50
+ await readFile(path.join(appRoot, 'pnpm-workspace.yaml'), 'utf8'),
51
+ );
52
+ if (
53
+ packageJson.overrides?.sharp !== '0.35.4' ||
54
+ packageJson.overrides?.three !== 'npm:super-three@0.181.0'
55
+ ) {
56
+ blockers.push(
57
+ 'generated package.json is missing the npm Sharp/Three overrides',
58
+ );
59
+ }
60
+ if (
61
+ pnpmWorkspace.packages?.length !== 1 ||
62
+ pnpmWorkspace.packages[0] !== '.' ||
63
+ pnpmWorkspace.overrides?.sharp !== '0.35.4' ||
64
+ pnpmWorkspace.overrides?.three !== 'npm:super-three@0.181.0' ||
65
+ pnpmWorkspace.allowBuilds?.sharp !== true ||
66
+ pnpmWorkspace.allowBuilds?.['@meta-quest/metavr'] !== false ||
67
+ pnpmWorkspace.allowBuilds?.['onnxruntime-node'] !== false
68
+ ) {
69
+ blockers.push(
70
+ 'generated pnpm-workspace.yaml is missing the pnpm 10/11 override and build policy',
71
+ );
72
+ }
48
73
  if (
49
74
  packageJson.dependencies?.['@iwsdk/example-assets'] != null ||
50
75
  packageJson.devDependencies?.['@iwsdk/example-assets'] != null