@iwsdk/create 0.4.2 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (106) 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 +17 -12
  106. package/scripts/verify-release-ready.mjs +76 -0
@@ -0,0 +1,63 @@
1
+ ---
2
+ applyTo: "public/scenes/**"
3
+ ---
4
+
5
+ # Scene JSON — things that fail silently
6
+
7
+ Format reference lives in
8
+ `.agents/skills/iwsdk-scene-composer/references/scene-format.md`: the document
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.
12
+
13
+ Only `iwsdk.scene.v1` exists, units are always meters, and structural objects are
14
+ closed — an unknown field fails validation.
15
+
16
+ ## Imports stop at the authoring boundary
17
+
18
+ Authoring tools can validate and render a root with `imports`, so modular scratch
19
+ scenes remain useful for composition. The editable scene session and application
20
+ runtime deliberately reject imports. Run `scene_flatten_file` or
21
+ `npx iwsdk scene flatten` once, verify the source and output runtime hashes match,
22
+ then make the flat output the sole editable source of truth. Never re-flatten over
23
+ later human editor changes.
24
+
25
+ ## The player materialises at the scene origin
26
+
27
+ `0,0,0` unless the document authors `player.transform`. Nothing warns you. A
28
+ scene can pass every authored camera view and still spawn the player inside the
29
+ geometry, because review cameras are not the viewpoint that ships. Keep that
30
+ volume clear or place the player deliberately, and author a diagnostic view at
31
+ player eye height to prove it.
32
+
33
+ ## `visibleNodeIds` is the silent-failure detector
34
+
35
+ `renderStats.visibleNodeIds` lists what actually rendered. A node missing from it
36
+ did not appear — even when the image looks plausible and `valid` is `true`. Check
37
+ it against what you expect rather than trusting the picture. Single-sided
38
+ surfaces facing away from the camera are the usual cause, and they report nothing.
39
+
40
+ ## Component keys come in two forms
41
+
42
+ Root-level components use the namespaced form
43
+ (`com.iwsdk.components.DomeGradient`). Node-level components accept the bare name
44
+ (`RayInteractable`, `LocomotionEnvironment`). **The editor writes the namespaced
45
+ form on nodes**, so a file touched by both hands contains both. Match whatever the
46
+ node already uses instead of normalising.
47
+
48
+ `LevelRoot`, `LevelTag` and `Transform` are runtime-owned; never author them.
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.
55
+
56
+ ## Validation
57
+
58
+ `scene_render_file` validates, composes, lowers and renders without touching the
59
+ open document. A result is usable only when `valid: true` **and** a PNG comes
60
+ back. Render each changed module before the root.
61
+
62
+ For composing a scene rather than editing one, use the `iwsdk-scene-composer`
63
+ skill — it owns the intake, review and stop-rule procedure this file does not.
@@ -0,0 +1,59 @@
1
+ ---
2
+ applyTo: "public/ui/**"
3
+ ---
4
+
5
+ # UIKitML panels
6
+
7
+ HTML/CSS-shaped, not a browser engine. Validate rather than assume support.
8
+
9
+ **Numeric sizes are UIKit units (centimetres), not pixels.** `width: 95` is a
10
+ 0.95 m panel. Font sizes follow the same scale: `font-size: 3` is 3 cm tall.
11
+
12
+ **Panels are single-sided and face +Z.** To aim one at a camera, yaw by
13
+ `atan2(dx, dz)` toward it — there is no 180° term. A back-facing panel renders
14
+ nothing, reports no error, and still returns `valid: true` from
15
+ `scene_render_file`; the only signal is its absence from
16
+ `renderStats.visibleNodeIds`.
17
+
18
+ Verified working: `display: flex`, `flex-direction`, `align-items`,
19
+ `justify-content: space-between`, `gap`, `margin-*`, `padding-*`, `width`,
20
+ `height`, `background-color`, `border-color`, `border-width`, `border-radius`,
21
+ `font-size`, `font-weight`, `color`, `text-align`, `cursor`. Tags `div`, `span`,
22
+ `button` all work.
23
+
24
+ Expand shorthands (`padding: 12 18` → four properties), use unitless
25
+ line-height multipliers, and prefer uniform `border-color`/`border-width` over
26
+ directional variants. Parser errors include source locations.
27
+
28
+ ## Runtime API
29
+
30
+ Resolve the placed panel by **scene node id**, then elements by their `id`
31
+ attribute:
32
+
33
+ ```ts
34
+ const panel = world.getSceneObject<UIKitMLAsset>('config-panel');
35
+ const chip = panel?.getElementById<UIKit.Text>('finish-gold');
36
+ chip?.addEventListener('click', onClick);
37
+ chip?.setProperties({ backgroundColor: '#d8e6f5', color: '#0e1116' });
38
+ ```
39
+
40
+ `setProperties` updates both text (`{ text }`) and style
41
+ (`backgroundColor`, `color`, `borderColor`, `display`) — style changes do apply,
42
+ including over class-based styles from the `<style>` block. `UIKit.Text` is the
43
+ public element type; no deep import from `@pmndrs/uikit` is needed.
44
+
45
+ Three distinct identities, don't conflate them: the **manifest ID** names the
46
+ reusable asset, the **scene node ID** names the placed instance, and the element
47
+ `id` names a field inside it. Never depend on a transient entity index.
48
+
49
+ Give the panel node `RayInteractable` so clicks land.
50
+
51
+ The editor render does not run application systems, so `scene_screenshot` can
52
+ never prove a panel *behaves* — only `browser_screenshot`, against the runtime,
53
+ can.
54
+
55
+ ---
56
+
57
+ For the authoring procedure — isolated preview, placement, editing, wiring
58
+ runtime behavior, and the completion checklist — use the `iwsdk-ui` skill rather
59
+ than improvising. This file is the format reference it relies on.
@@ -0,0 +1,57 @@
1
+ ---
2
+ description: "Asset manifest contract"
3
+ globs:
4
+ - "src/assets.ts"
5
+ - "src/assets.js"
6
+ - "src/scene-assets/**"
7
+ alwaysApply: false
8
+ ---
9
+
10
+ # Asset manifest contract
11
+
12
+ `src/assets.ts` is imported **independently by the app runtime and the editor**,
13
+ in separate JS realms. It must therefore be deterministic and self-contained:
14
+
15
+ - no `World`, scene, iframe, editor object or DOM access
16
+ - no timers, no fetching ambient state
17
+ - no reliance on singleton object identity across realms
18
+ - prototypes immutable after registration, and never parented
19
+
20
+ A manifest entry is either a URL descriptor (`{ url, type, name?, priority? }`)
21
+ or a bare parentless `Object3D`. `AssetType` covers `GLTF`, `Audio`, `Texture`,
22
+ `HDRTexture`, `UIKitML`. Only glTF, UIKitML and `Object3D` entries are placeable
23
+ as scene content; audio/texture/HDR are for application systems.
24
+
25
+ Build public URLs from `import.meta.env.BASE_URL` so runtime, editor and subpath
26
+ builds resolve identically. A file in `public/` is **not** available to a scene
27
+ until it is registered here.
28
+
29
+ ## Procedural assets
30
+
31
+ Export a parentless `Object3D` from `src/scene-assets/*.scene-asset.ts` and
32
+ register it under a stable ID. The registry rejects an already-parented
33
+ prototype.
34
+
35
+ Every placement is a distinct hierarchy clone, but **geometry and materials stay
36
+ shared**. Never dispose them from a placed clone; world teardown owns their
37
+ lifetime. Reassigning `mesh.material` on a clone is fine and is how you restyle
38
+ one instance — mutating the shared material in place changes every instance.
39
+
40
+ Bounds come from `Box3` over the instantiated asset and drive placement,
41
+ selection, framing and scatter collision. Put the origin where composition wants
42
+ it (usually floor contact, or the object's own pivot), keep transforms finite,
43
+ and don't let invisible helpers inflate bounds.
44
+
45
+ ## Cost
46
+
47
+ Split tessellation by viewing distance rather than using one budget everywhere: a
48
+ close-range hero model and coarser display copies of the same form are two
49
+ prototypes from one factory function. Sphere/lathe segment counts dominate small
50
+ repeated detail more than people expect — check `renderStats.triangles` rather
51
+ than guessing.
52
+
53
+ Reuse material instances within a module. Prefer prefabs plus a deterministic
54
+ pattern for repetition; a pattern whose prefab resolves to a single component-free
55
+ mesh lowers to one `InstancedMesh`.
56
+
57
+ Start assets at `castShadow: false` and opt in only for grounded focal masses.
@@ -0,0 +1,104 @@
1
+ ---
2
+ description: "ECS API reference"
3
+ globs:
4
+ - "src/**/*.ts"
5
+ - "src/**/*.js"
6
+ alwaysApply: false
7
+ ---
8
+
9
+ # ECS API reference
10
+
11
+ ## Field types
12
+
13
+ ```
14
+ Types.Float32 Float64 Int8 Int16 Int32 Boolean String FilePath
15
+ Types.Vec2 Vec3 Vec4 Color(RGBA) Entity Enum
16
+ Types.Object // avoid — not optimised
17
+ ```
18
+
19
+ ## Component
20
+
21
+ Declare in a system-free module, then list it in `src/components.ts` via
22
+ `defineComponents()` or the editor cannot author it.
23
+
24
+ ```ts
25
+ export const MyComponent = createComponent('MyComponent', {
26
+ speed: { type: Types.Float32, default: 1 },
27
+ tint: { type: Types.Color, default: [1, 1, 1, 1] }, // RGBA
28
+ });
29
+ ```
30
+
31
+ Optional metadata per field — `label`, `step`, `min`, `max`, `enum`, `help`,
32
+ `widget` — drives the editor inspector.
33
+
34
+ ## System
35
+
36
+ ```ts
37
+ export class MySystem extends createSystem(
38
+ {
39
+ items: { required: [MyComponent] },
40
+ active: { required: [MyComponent], excluded: [Grabbed] },
41
+ },
42
+ { speed: { type: Types.Float32, default: 1 } }, // optional config
43
+ ) {
44
+ private temp!: Vector3;
45
+
46
+ init() {
47
+ this.temp = new Vector3();
48
+ this.queries.items.subscribe('qualify', (entity) => { /* matched */ });
49
+ this.cleanupFuncs.push(this.config.speed.subscribe((v) => { /* … */ }));
50
+ }
51
+
52
+ update(delta: number, time: number) {
53
+ for (const entity of this.queries.active.entities) { /* no allocations */ }
54
+ }
55
+ }
56
+ ```
57
+
58
+ Queries take `required`, `excluded` and `where` (value predicates via `eq`, `ne`,
59
+ `lt`, `le`, `gt`, `ge`, `isin`, `nin`). `excluded` is the clean way to skip
60
+ entities in a transient state — e.g. excluding `Grabbed` so a held object is left
61
+ alone.
62
+
63
+ Register explicitly in `src/index.ts` with `world.registerSystem(MySystem)`.
64
+
65
+ Read fields with `entity.getValue(Component, 'field')`. For vector fields use
66
+ `entity.getVectorView(Component, 'field')` — it returns a `Float32Array` view with
67
+ no allocation, and `setValue` **throws** on vector fields in elics 3.4.x.
68
+
69
+ ## Interaction components
70
+
71
+ `RayInteractable` plus `Hovered`/`Pressed` covers both mouse/touch canvas input
72
+ and XR rays. Grab components: `OneHandGrabbable` and `TwoHandsGrabbable` are
73
+ proximity-based and respond to **squeeze**, while `DistanceGrabbable` is
74
+ ray-based and responds to **trigger**. `Grabbed` is a transient tag managed by
75
+ `GrabSystem` — read it, never add or remove it. `GrabSystem.useHandPinchForGrab`
76
+ defaults to **false**, so hand pinch does not grab unless you enable it.
77
+
78
+ `DistanceGrabbable` fields: `movementMode` (`MoveTowardsTarget`, `MoveFromTarget`,
79
+ `MoveAtSource`, `RotateAtSource`), `returnToOrigin`, `moveSpeedFactor`,
80
+ `detachOnGrab`, `translate`, `rotate`, `scale`, `targetPositionOffset`,
81
+ `targetQuaternionOffset`. `returnToOrigin: true` gives spring-back on release with
82
+ no custom code.
83
+
84
+ For a held object use `GrabSystem`'s public methods — `forceRelease(entity)`,
85
+ `getHolderHand(entity)` — never deep-import `Handle`.
86
+
87
+ ## XR input
88
+
89
+ ```ts
90
+ const pad = this.input.xr.gamepads.right;
91
+ pad?.getButtonDown(InputComponent.Trigger); // just pressed
92
+ pad?.getAxesValues(InputComponent.Thumbstick);
93
+ this.player.head; this.player.raySpaces.left; this.player.gripSpaces.right;
94
+ ```
95
+
96
+ Prefer `world.input.actions` for reusable intent (`locomotion.move`) over raw
97
+ buttons. Browser controls live at `world.input.keyboard` and
98
+ `world.input.browserGamepads`.
99
+
100
+ ## Lifecycle
101
+
102
+ `world.visibilityState` reports `NonImmersive`, `Visible`, `VisibleBlurred` —
103
+ pause simulation on blur. `world.camera.position` is local to `world.player`; use
104
+ `getWorldPosition()` when logic needs the true viewer position.
@@ -0,0 +1,66 @@
1
+ ---
2
+ description: "Scene JSON — things that fail silently"
3
+ globs:
4
+ - "public/scenes/**"
5
+ alwaysApply: false
6
+ ---
7
+
8
+ # Scene JSON — things that fail silently
9
+
10
+ Format reference lives in
11
+ `.agents/skills/iwsdk-scene-composer/references/scene-format.md`: the document
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.
15
+
16
+ Only `iwsdk.scene.v1` exists, units are always meters, and structural objects are
17
+ closed — an unknown field fails validation.
18
+
19
+ ## Imports stop at the authoring boundary
20
+
21
+ Authoring tools can validate and render a root with `imports`, so modular scratch
22
+ scenes remain useful for composition. The editable scene session and application
23
+ runtime deliberately reject imports. Run `scene_flatten_file` or
24
+ `npx iwsdk scene flatten` once, verify the source and output runtime hashes match,
25
+ then make the flat output the sole editable source of truth. Never re-flatten over
26
+ later human editor changes.
27
+
28
+ ## The player materialises at the scene origin
29
+
30
+ `0,0,0` unless the document authors `player.transform`. Nothing warns you. A
31
+ scene can pass every authored camera view and still spawn the player inside the
32
+ geometry, because review cameras are not the viewpoint that ships. Keep that
33
+ volume clear or place the player deliberately, and author a diagnostic view at
34
+ player eye height to prove it.
35
+
36
+ ## `visibleNodeIds` is the silent-failure detector
37
+
38
+ `renderStats.visibleNodeIds` lists what actually rendered. A node missing from it
39
+ did not appear — even when the image looks plausible and `valid` is `true`. Check
40
+ it against what you expect rather than trusting the picture. Single-sided
41
+ surfaces facing away from the camera are the usual cause, and they report nothing.
42
+
43
+ ## Component keys come in two forms
44
+
45
+ Root-level components use the namespaced form
46
+ (`com.iwsdk.components.DomeGradient`). Node-level components accept the bare name
47
+ (`RayInteractable`, `LocomotionEnvironment`). **The editor writes the namespaced
48
+ form on nodes**, so a file touched by both hands contains both. Match whatever the
49
+ node already uses instead of normalising.
50
+
51
+ `LevelRoot`, `LevelTag` and `Transform` are runtime-owned; never author them.
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.
58
+
59
+ ## Validation
60
+
61
+ `scene_render_file` validates, composes, lowers and renders without touching the
62
+ open document. A result is usable only when `valid: true` **and** a PNG comes
63
+ back. Render each changed module before the root.
64
+
65
+ For composing a scene rather than editing one, use the `iwsdk-scene-composer`
66
+ skill — it owns the intake, review and stop-rule procedure this file does not.
@@ -0,0 +1,62 @@
1
+ ---
2
+ description: "UIKitML panels"
3
+ globs:
4
+ - "public/ui/**"
5
+ alwaysApply: false
6
+ ---
7
+
8
+ # UIKitML panels
9
+
10
+ HTML/CSS-shaped, not a browser engine. Validate rather than assume support.
11
+
12
+ **Numeric sizes are UIKit units (centimetres), not pixels.** `width: 95` is a
13
+ 0.95 m panel. Font sizes follow the same scale: `font-size: 3` is 3 cm tall.
14
+
15
+ **Panels are single-sided and face +Z.** To aim one at a camera, yaw by
16
+ `atan2(dx, dz)` toward it — there is no 180° term. A back-facing panel renders
17
+ nothing, reports no error, and still returns `valid: true` from
18
+ `scene_render_file`; the only signal is its absence from
19
+ `renderStats.visibleNodeIds`.
20
+
21
+ Verified working: `display: flex`, `flex-direction`, `align-items`,
22
+ `justify-content: space-between`, `gap`, `margin-*`, `padding-*`, `width`,
23
+ `height`, `background-color`, `border-color`, `border-width`, `border-radius`,
24
+ `font-size`, `font-weight`, `color`, `text-align`, `cursor`. Tags `div`, `span`,
25
+ `button` all work.
26
+
27
+ Expand shorthands (`padding: 12 18` → four properties), use unitless
28
+ line-height multipliers, and prefer uniform `border-color`/`border-width` over
29
+ directional variants. Parser errors include source locations.
30
+
31
+ ## Runtime API
32
+
33
+ Resolve the placed panel by **scene node id**, then elements by their `id`
34
+ attribute:
35
+
36
+ ```ts
37
+ const panel = world.getSceneObject<UIKitMLAsset>('config-panel');
38
+ const chip = panel?.getElementById<UIKit.Text>('finish-gold');
39
+ chip?.addEventListener('click', onClick);
40
+ chip?.setProperties({ backgroundColor: '#d8e6f5', color: '#0e1116' });
41
+ ```
42
+
43
+ `setProperties` updates both text (`{ text }`) and style
44
+ (`backgroundColor`, `color`, `borderColor`, `display`) — style changes do apply,
45
+ including over class-based styles from the `<style>` block. `UIKit.Text` is the
46
+ public element type; no deep import from `@pmndrs/uikit` is needed.
47
+
48
+ Three distinct identities, don't conflate them: the **manifest ID** names the
49
+ reusable asset, the **scene node ID** names the placed instance, and the element
50
+ `id` names a field inside it. Never depend on a transient entity index.
51
+
52
+ Give the panel node `RayInteractable` so clicks land.
53
+
54
+ The editor render does not run application systems, so `scene_screenshot` can
55
+ never prove a panel *behaves* — only `browser_screenshot`, against the runtime,
56
+ can.
57
+
58
+ ---
59
+
60
+ For the authoring procedure — isolated preview, placement, editing, wiring
61
+ runtime behavior, and the completion checklist — use the `iwsdk-ui` skill rather
62
+ than improvising. This file is the format reference it relies on.
@@ -0,0 +1,63 @@
1
+ # IWSDK scoped project guidance
2
+
3
+ This file augments the repository-root `AGENTS.md` for files in this directory.
4
+
5
+ # Scene JSON — things that fail silently
6
+
7
+ Format reference lives in
8
+ `.agents/skills/iwsdk-scene-composer/references/scene-format.md`: the document
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.
12
+
13
+ Only `iwsdk.scene.v1` exists, units are always meters, and structural objects are
14
+ closed — an unknown field fails validation.
15
+
16
+ ## Imports stop at the authoring boundary
17
+
18
+ Authoring tools can validate and render a root with `imports`, so modular scratch
19
+ scenes remain useful for composition. The editable scene session and application
20
+ runtime deliberately reject imports. Run `scene_flatten_file` or
21
+ `npx iwsdk scene flatten` once, verify the source and output runtime hashes match,
22
+ then make the flat output the sole editable source of truth. Never re-flatten over
23
+ later human editor changes.
24
+
25
+ ## The player materialises at the scene origin
26
+
27
+ `0,0,0` unless the document authors `player.transform`. Nothing warns you. A
28
+ scene can pass every authored camera view and still spawn the player inside the
29
+ geometry, because review cameras are not the viewpoint that ships. Keep that
30
+ volume clear or place the player deliberately, and author a diagnostic view at
31
+ player eye height to prove it.
32
+
33
+ ## `visibleNodeIds` is the silent-failure detector
34
+
35
+ `renderStats.visibleNodeIds` lists what actually rendered. A node missing from it
36
+ did not appear — even when the image looks plausible and `valid` is `true`. Check
37
+ it against what you expect rather than trusting the picture. Single-sided
38
+ surfaces facing away from the camera are the usual cause, and they report nothing.
39
+
40
+ ## Component keys come in two forms
41
+
42
+ Root-level components use the namespaced form
43
+ (`com.iwsdk.components.DomeGradient`). Node-level components accept the bare name
44
+ (`RayInteractable`, `LocomotionEnvironment`). **The editor writes the namespaced
45
+ form on nodes**, so a file touched by both hands contains both. Match whatever the
46
+ node already uses instead of normalising.
47
+
48
+ `LevelRoot`, `LevelTag` and `Transform` are runtime-owned; never author them.
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.
55
+
56
+ ## Validation
57
+
58
+ `scene_render_file` validates, composes, lowers and renders without touching the
59
+ open document. A result is usable only when `valid: true` **and** a PNG comes
60
+ back. Render each changed module before the root.
61
+
62
+ For composing a scene rather than editing one, use the `iwsdk-scene-composer`
63
+ skill — it owns the intake, review and stop-rule procedure this file does not.
@@ -0,0 +1,59 @@
1
+ # IWSDK scoped project guidance
2
+
3
+ This file augments the repository-root `AGENTS.md` for files in this directory.
4
+
5
+ # UIKitML panels
6
+
7
+ HTML/CSS-shaped, not a browser engine. Validate rather than assume support.
8
+
9
+ **Numeric sizes are UIKit units (centimetres), not pixels.** `width: 95` is a
10
+ 0.95 m panel. Font sizes follow the same scale: `font-size: 3` is 3 cm tall.
11
+
12
+ **Panels are single-sided and face +Z.** To aim one at a camera, yaw by
13
+ `atan2(dx, dz)` toward it — there is no 180° term. A back-facing panel renders
14
+ nothing, reports no error, and still returns `valid: true` from
15
+ `scene_render_file`; the only signal is its absence from
16
+ `renderStats.visibleNodeIds`.
17
+
18
+ Verified working: `display: flex`, `flex-direction`, `align-items`,
19
+ `justify-content: space-between`, `gap`, `margin-*`, `padding-*`, `width`,
20
+ `height`, `background-color`, `border-color`, `border-width`, `border-radius`,
21
+ `font-size`, `font-weight`, `color`, `text-align`, `cursor`. Tags `div`, `span`,
22
+ `button` all work.
23
+
24
+ Expand shorthands (`padding: 12 18` → four properties), use unitless
25
+ line-height multipliers, and prefer uniform `border-color`/`border-width` over
26
+ directional variants. Parser errors include source locations.
27
+
28
+ ## Runtime API
29
+
30
+ Resolve the placed panel by **scene node id**, then elements by their `id`
31
+ attribute:
32
+
33
+ ```ts
34
+ const panel = world.getSceneObject<UIKitMLAsset>('config-panel');
35
+ const chip = panel?.getElementById<UIKit.Text>('finish-gold');
36
+ chip?.addEventListener('click', onClick);
37
+ chip?.setProperties({ backgroundColor: '#d8e6f5', color: '#0e1116' });
38
+ ```
39
+
40
+ `setProperties` updates both text (`{ text }`) and style
41
+ (`backgroundColor`, `color`, `borderColor`, `display`) — style changes do apply,
42
+ including over class-based styles from the `<style>` block. `UIKit.Text` is the
43
+ public element type; no deep import from `@pmndrs/uikit` is needed.
44
+
45
+ Three distinct identities, don't conflate them: the **manifest ID** names the
46
+ reusable asset, the **scene node ID** names the placed instance, and the element
47
+ `id` names a field inside it. Never depend on a transient entity index.
48
+
49
+ Give the panel node `RayInteractable` so clicks land.
50
+
51
+ The editor render does not run application systems, so `scene_screenshot` can
52
+ never prove a panel *behaves* — only `browser_screenshot`, against the runtime,
53
+ can.
54
+
55
+ ---
56
+
57
+ For the authoring procedure — isolated preview, placement, editing, wiring
58
+ runtime behavior, and the completion checklist — use the `iwsdk-ui` skill rather
59
+ than improvising. This file is the format reference it relies on.