@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
@@ -0,0 +1,303 @@
1
+ # Planner path
2
+
3
+ Deliver the requested experience with the smallest reliable loop. Preserve the
4
+ user's exact observable contract, use IWSDK-native workflows, verify the real
5
+ runtime, and stop when the contract is proven.
6
+
7
+ ## Default operating mode
8
+
9
+ - Work autonomously when the task is already specific. Do not pause for design
10
+ approval unless a missing choice materially changes the product.
11
+ - Keep one compact plan in the conversation or task list. Do not create
12
+ `design/`, pipeline-state, deck, concept-art, architecture, verification, or
13
+ retrospective files unless the user explicitly requests them.
14
+ - Do not scaffold a nested app. Treat the generated project in the working
15
+ directory as the starting point.
16
+ - Do not run an untouched-scaffold demo. Inspect the generated project briefly
17
+ and begin the requested implementation.
18
+ - Use subagents only for genuinely independent work that saves wall time. Do
19
+ not spawn a planner, documentation, or review subagent by default.
20
+
21
+ ## 1. Extract the executable contract
22
+
23
+ Before editing, reduce the prompt to a short checklist:
24
+
25
+ 1. exact files, scene node IDs, UIKit element IDs, component names, and fields;
26
+ 2. explicit initial values and state transitions;
27
+ 3. interaction paths that must work in the live app;
28
+ 4. visible states and required framing/legibility;
29
+ 5. build and runtime evidence needed before stopping.
30
+
31
+ Treat exact values as data, not implications. If a required field value equals
32
+ the component default, still serialize it explicitly in authored scene data.
33
+ For example, a required profile `A` must be written as `profileId: "A"`, not
34
+ left implicit because `A` is the schema default.
35
+
36
+ When the prompt names live runtime objects, assign those runtime `.name`
37
+ values exactly during initialization and verify them in the runtime hierarchy.
38
+ UIKit element IDs alone do not satisfy a runtime-name requirement.
39
+
40
+ ## 2. Inspect once, then ground only uncertainty
41
+
42
+ Read the existing entry point, project config, asset/component registries,
43
+ scene, and relevant scoped rules. Use precise `npx @iwsdk/cli reference` queries
44
+ only for APIs or file formats that are genuinely uncertain.
45
+
46
+ Convert FBX, OBJ, and other source model formats before registering them: in
47
+ Blender use **File → Import**, then **File → Export → glTF 2.0**, and add the
48
+ resulting GLB/GLTF to the asset manifest.
49
+
50
+ For a fresh scaffold that needs native scene composition and UIKitML, use this
51
+ exact fast path before broad discovery:
52
+
53
+ 1. read the applicable scoped `AGENTS.md`, then exactly these scaffold rules
54
+ when present: `.claude/rules/scene-json.md`, `ecs-api.md`, `uikitml.md`, and
55
+ `assets-and-manifest.md`; do not list directories first;
56
+ 2. in one bounded shell call, print `package.json`, `iwsdk.config.json`, the
57
+ small scaffold `src/*.ts` files, the authored scene JSON, and UIKitML;
58
+ 3. use `iwsdk-build-model` for every new or materially changed model, then use
59
+ `iwsdk-compose-scene` for scene placement, lighting, environment, and cameras;
60
+ load `iwsdk-ui/SKILL.md` only when UIKitML is part of the request;
61
+ 4. create or replace the first implementation files immediately, then let
62
+ typecheck/runtime errors identify any
63
+ additional API question.
64
+
65
+ The first edit is a checkpoint: reach it within 8 tool calls after loading this
66
+ playbook. Do not inspect generated declarations, search node_modules, or invoke
67
+ another specialist before it. If one framework boundary remains unclear, write
68
+ the straightforward typed slice, run npm run --if-present typecheck, and investigate only the
69
+ concrete compiler error. After the focused references, edit before optional
70
+ lookup.
71
+
72
+ For the bounded scaffold read, prefer one command shaped like this over a
73
+ series of individual reads (adjust globs only when the project differs):
74
+
75
+ ```bash
76
+ for f in package.json iwsdk.config.json src/*.ts public/scenes/*.json public/ui/*.uikitml; do
77
+ echo "--- $f"; sed -n '1,260p' "$f"
78
+ done
79
+ ```
80
+
81
+ For a compact greenfield scene, keep the default player spawn unless the prompt
82
+ explicitly requires another spawn. Do not inspect schemas to add an optional
83
+ `player` block. Keep the standing volume around the origin clear, place the
84
+ experience in front of it (normally negative Z), and use this document shape:
85
+
86
+ ```json
87
+ {
88
+ "version": "iwsdk.scene.v1",
89
+ "units": "meters",
90
+ "components": {},
91
+ "resources": {},
92
+ "nodes": [],
93
+ "authoring": { "views": [] }
94
+ }
95
+ ```
96
+
97
+ Use these stable high-friction recipes directly; do not rediscover them in
98
+ `node_modules`:
99
+
100
+ ```ts
101
+ const Profiles = { A: 'A', B: 'B', C: 'C' } as const;
102
+ const Example = createComponent('Example', {
103
+ profileId: { type: Types.Enum, default: Profiles.A, enum: Profiles },
104
+ occupant: { type: Types.Entity, default: null },
105
+ active: { type: Types.Boolean, default: false },
106
+ elapsed: { type: Types.Float32, default: 0 },
107
+ });
108
+
109
+ const panel = world.requireSceneObject<UIKitMLAsset>('ControlPanel');
110
+ const status = panel.requireElementById<UIKit.Text>('StatusText');
111
+ const button = panel.requireElementById('Btn_Action');
112
+ status.name = 'StatusText';
113
+ button.name = 'Btn_Action';
114
+ button.addEventListener('click', onAction);
115
+ cleanupFuncs.push(() => button.removeEventListener('click', onAction));
116
+
117
+ export class ExampleSystem extends createSystem({
118
+ examples: { required: [Example] },
119
+ held: { required: [Example, Grabbed] },
120
+ }) {
121
+ init(): void {
122
+ const onGrab = (entity: Entity) => entity.setValue(Example, 'active', true);
123
+ const onRelease = (entity: Entity) =>
124
+ entity.setValue(Example, 'active', false);
125
+ const offGrab = this.queries.held.subscribe('qualify', onGrab);
126
+ const offRelease = this.queries.held.subscribe('disqualify', onRelease);
127
+ this.cleanupFuncs.push(offGrab, offRelease);
128
+ }
129
+
130
+ update(delta: number): void {
131
+ for (const entity of this.queries.examples.entities) {
132
+ const active = entity.getValue(Example, 'active');
133
+ const elapsed = entity.getValue(Example, 'elapsed') ?? 0;
134
+ if (active) entity.setValue(Example, 'elapsed', elapsed + delta);
135
+ }
136
+ }
137
+ }
138
+ ```
139
+
140
+ - Declare systems with `class X extends createSystem({ queryName: { required: [...] } })`.
141
+ Iterate `this.queries.queryName.entities`, and use
142
+ `entity.getValue(Component, field)` / `entity.setValue(Component, field, value)`.
143
+ Query `subscribe` returns an unsubscribe function for `cleanupFuncs`.
144
+ - Author an empty entity reference as `null` in scene JSON.
145
+ - Put `OneHandGrabbable` on authored nodes that need proximity grabbing. Treat
146
+ `Grabbed` as a runtime tag; use qualify/disqualify transitions for lifecycle
147
+ handling and `GrabSystem.forceRelease(entity)` for reset.
148
+ - When a slot accepts only one entity, guard against replacement: if its current
149
+ entity is non-null and differs from the released entity, leave both unchanged.
150
+ - Resolve authored entities and objects with `world.requireSceneEntity(nodeId)`
151
+ and `world.requireSceneObject(nodeId)`.
152
+ - Import ECS, UIKit, grab helpers, and Three.js runtime classes from
153
+ `@iwsdk/core`; IWSDK re-exports the supported runtime surface.
154
+ - For a live UIKit ray click, aim with `npx @iwsdk/cli xr look-at`, then use
155
+ `npx @iwsdk/cli xr select --input-json '{"device":"controller-right","duration":0.2}'`.
156
+ Do not rederive pointer internals or manually pulse select unless diagnosing
157
+ a concrete helper failure.
158
+
159
+ Avoid broad repeated discovery:
160
+
161
+ - do not enumerate the same command family or dependency tree multiple times;
162
+ - do not read generated bundles or large reference files when a focused API or
163
+ example query answers the question;
164
+ - do not repeat successful status, hierarchy, or capability probes without a
165
+ state change that requires it.
166
+
167
+ Specialist skills are optional focused references, not mandatory phases. Use
168
+ only the skills needed by the contract, normally at most once each:
169
+
170
+ - `iwsdk-build-model` for new or materially changed model geometry, materials,
171
+ hierarchy, or surface detail;
172
+ - `iwsdk-compose-scene` for scene JSON, placement, cross-asset contacts,
173
+ lighting, environment, or camera views after model work is complete;
174
+ - `iwsdk-ui` for UIKitML authoring or layout debugging;
175
+ - `iwsdk-grab` / `iwsdk-ray` for unfamiliar live interaction simulation;
176
+ - `iwsdk-debug` after a concrete runtime failure.
177
+
178
+ Pass a concise problem statement to a specialist. Do not paste the full user
179
+ prompt, ask it to run another end-to-end plan, or invoke overlapping skills for
180
+ the same question.
181
+
182
+ ## 3. Implement one coherent vertical slice
183
+
184
+ Build the smallest structure that covers the whole contract:
185
+
186
+ 1. native scene assets and deliberate hero/panel framing;
187
+ 2. component schemas and explicit authored values;
188
+ 3. interaction/state systems;
189
+ 4. UIKitML and runtime control wiring;
190
+ 5. visible state feedback.
191
+
192
+ Prefer IWSDK built-ins and project-local patterns. Keep systems small, register
193
+ cleanup functions, avoid per-frame allocation, and preserve feature-flag
194
+ prerequisites. Do not create process documents while code is incomplete.
195
+
196
+ Run `npm run --if-present typecheck` after the coherent slice exists, then fix errors in a
197
+ batch. Do not typecheck after every small edit. Run the production build near
198
+ the end and again only after a change that can affect it.
199
+
200
+ ## 4. Verify the actual contract
201
+
202
+ Match verification depth to the app and its risk. A simple single-scene app
203
+ needs direct evidence for its few success criteria; multi-system behavior,
204
+ physics, deployment, and interactions with meaningful failure modes need
205
+ broader scenarios and stronger evidence.
206
+
207
+ After the coherent vertical slice typechecks, start one managed dev session
208
+ and keep it alive while iterating. The developer owns headed versus headless
209
+ mode: announce a proposed mode change before restarting rather than silently
210
+ replacing their visible collaboration window. Do not start an untouched or
211
+ knowingly non-typechecking app. Exercise the real paths rather than inferring
212
+ behavior from code. Confirm `npx @iwsdk/cli xr status` is active before making pose,
213
+ controller/hand alignment, or immersive-interaction claims; a flat screenshot
214
+ outside XR cannot prove them.
215
+
216
+ Verify:
217
+
218
+ - initial ECS state and explicit authored values;
219
+ - every interaction required by the acceptance contract;
220
+ - empty, rejected, boundary, or exclusivity guards when applicable;
221
+ - timed transitions and visible state feedback;
222
+ - reset of affected state, transforms, flags, timers, and references;
223
+ - exact runtime hierarchy names for addressable controls.
224
+
225
+ When the contract includes an exclusive slot or station, prove that a second
226
+ object cannot silently replace the current occupant.
227
+
228
+ Use compact CLI scripts to group related assertions. Capture screenshots at
229
+ the requested key states, not after every minor change.
230
+
231
+ Once the dev session is ready, target at most 24 shell-tool calls for the
232
+ entire verification pass. Batch the contract into a few coherent scenarios,
233
+ for example: initial state and guard behavior, successful primary interaction,
234
+ rejected or boundary behavior, and reset/runtime-name closeout. Each block
235
+ should perform its input sequence, query affected state, and print a compact
236
+ PASS/FAIL summary. After a failure, diagnose once and rerun only that block.
237
+
238
+ Keep context lean while iterating:
239
+
240
+ - do not re-read a file after a successful write or edit unless a later tool
241
+ reports a concrete mismatch; use a targeted range or search when only one
242
+ section is uncertain;
243
+ - project large CLI responses down to the exact fields being checked and cap
244
+ logs/search output;
245
+ - save evidence screenshots to disk, but do not load every full-resolution
246
+ image into model context. Image reads are expensive and can force context
247
+ compaction.
248
+
249
+ ## 5. Visual quality gate
250
+
251
+ Before finishing, inspect the same hero/runtime view a reviewer will see:
252
+
253
+ - the complete experience fills the frame at a useful scale;
254
+ - primary objects and controls are visually distinguishable;
255
+ - important text and controls are readable from the intended viewpoint;
256
+ - required states differ immediately through color, text, motion, or emissive
257
+ feedback;
258
+ - no unintended starter content, severe clipping, empty space, or back-facing UI
259
+ remains.
260
+
261
+ If the app is correct but the panel is tiny or the scene is too distant, fix
262
+ camera/framing before adding decorative complexity.
263
+
264
+ Use at most two visual reads by default: one early hero frame when composition
265
+ is uncertain, and one final inspection. Prefer a compact contact sheet of the
266
+ required states for the final read. If no contact-sheet tool is available,
267
+ inspect the hero frame plus the visually riskiest active state and prove the
268
+ remaining state changes through exact runtime text/color/state assertions.
269
+ Exceed this budget only to diagnose a specific visible defect, and replace an
270
+ earlier read rather than accumulating near-duplicate screenshots.
271
+
272
+ Keep original screenshots at evidence resolution, but load only a bounded
273
+ inspection copy into model context. Use an image tool already present in the
274
+ environment to limit an individual frame to roughly 640 pixels on its long edge
275
+ or a contact sheet to 1024 by 1024. Do not install a dependency only for this.
276
+
277
+ ## 6. Targeted closeout, then stop
278
+
279
+ Once live assertions pass:
280
+
281
+ 1. check the authored scene for every exact ID, component, and explicit value;
282
+ 2. check runtime names and event-listener cleanup;
283
+ 3. run `npm run --if-present typecheck` and `npm run build`;
284
+ 4. re-run only assertions affected by the final fixes;
285
+ 5. leave the app reset to its initial state and report concise evidence.
286
+
287
+ Do not launch the project code-reviewer by default. Use it only when a live or
288
+ build failure remains unexplained, the implementation uses an unfamiliar
289
+ framework boundary, or the user explicitly requests review. Do not apply
290
+ style-only review changes after the quality gates pass.
291
+
292
+ ## Budget and stopping rules
293
+
294
+ - By roughly 60% of the available session, the full vertical slice should
295
+ exist and typecheck.
296
+ - By roughly 75%, switch from feature work to runtime verification.
297
+ - By roughly 85%, freeze optional polish and close exact contract gaps.
298
+ - Prefer one proven implementation over alternate architectures, redundant
299
+ screenshots, repeated reviews, or speculative cleanup.
300
+ - Stop when static contract, production build, live paths, and visual gate pass.
301
+
302
+ The output is the working IWSDK app and concise final evidence—not a record of
303
+ the process used to produce it.
@@ -1,128 +1,51 @@
1
1
  ---
2
2
  name: iwsdk-grab
3
- description: Grab an object in the WebXR scene using emulated controllers. Use when the user wants to pick up, move, or test grabbing an object. Supports OneHandGrabbable and TwoHandsGrabbable components which use proximity-based grip (squeeze button), not trigger.
4
- argument-hint: <object-name> [destination]
3
+ description: Use emulated XR controllers to verify proximity grabbing for OneHandGrabbable and TwoHandsGrabbable objects. Use for pick up, move, release, or regression-test requests involving near-hand grab with the squeeze button.
4
+ argument-hint: '(use the current request)'
5
5
  ---
6
6
 
7
- # Grab Object
7
+ # IWSDK Proximity Grab
8
8
 
9
- Grab an object in the XR scene using the IWER emulated controllers. The workflow has a **required core** (steps 1-5) that must always execute, and **optional extensions** (steps 6-9) that depend on the user's intent.
9
+ Use this workflow only for `OneHandGrabbable` or `TwoHandsGrabbable`. A
10
+ `DistanceGrabbable` uses the ray/trigger path instead.
10
11
 
11
- User request is in `$ARGUMENTS`.
12
+ ## Execute the requested path
12
13
 
13
- ## Required Core
14
+ 1. Check XR session state and enter XR only when inactive.
15
+ 2. Find the named live entity and query its components and transform. If it is
16
+ absent, list nearby grabbable matches once and stop with the evidence.
17
+ 3. Confirm it has `OneHandGrabbable` or `TwoHandsGrabbable`. Do not guess the
18
+ interaction type from its name.
19
+ 4. Animate the requested controller to the object. Default to the right
20
+ controller only when the user did not choose a hand.
21
+ 5. Press and hold squeeze/grip button index `1`:
14
22
 
15
- These steps always execute in order. A grab cannot succeed without them.
23
+ ```json
24
+ {"device":"controller-right","buttons":[{"index":1,"value":1}]}
25
+ ```
16
26
 
17
- ### Step 1: Enter XR
27
+ 6. Query the entity for `Grabbed` or another requested observable state. If the
28
+ grab did not qualify, make one focused correction to controller position and
29
+ retry once.
30
+ 7. If movement was requested, animate the held controller to the destination.
31
+ 8. Release squeeze with index `1`, value `0`, then query the final transform or
32
+ state. Move the controller away only when overlap would interfere with the
33
+ result.
18
34
 
19
- Check session status. If not in an active XR session, accept and enter.
35
+ Do not use trigger index `0`, `xr select`, or teleport-style device mutation for
36
+ proximity grab. Do not edit source merely to make an existing named entity easier
37
+ to locate; report missing runtime identity when that is the actual defect.
20
38
 
21
- ```
22
- xr_get_session_status → if not sessionActive → xr_accept_session
23
- ```
39
+ ## Evidence and stopping
24
40
 
25
- ### Step 2: Locate the target
41
+ Prefer measured ECS state over screenshots. Capture one runtime image only when
42
+ the user requested visual evidence or placement must be judged. Batch related
43
+ queries and avoid repeating session, hierarchy, or transform discovery after a
44
+ successful read.
26
45
 
27
- Find the live entity by name or grabbable component, then query its component data.
46
+ When the request names an artifact path, save it directly with
47
+ `npx @iwsdk/cli browser screenshot --output-file <path>`. A screenshot returned only
48
+ to model context does not satisfy a requested file deliverable.
28
49
 
29
- ```
30
- ecs_find_entities({namePattern: target}) → ecs_query_entity(entityIndex)
31
- ```
32
-
33
- If the object is not found, search `OneHandGrabbable` and `TwoHandsGrabbable`
34
- entities, report the available matches, and stop.
35
-
36
- ### Step 3: Get its transform
37
-
38
- Read the object's Transform position from the queried entity.
39
-
40
- ```
41
- ecs_query_entity(entityIndex) → Transform.position
42
- ```
43
-
44
- ### Step 4: Animate controller to target
45
-
46
- Animate the controller to the object's position. Default to `"controller-right"` unless the user specified left.
47
-
48
- ```
49
- xr_animate_to({
50
- device: "controller-right",
51
- position: { x, y, z },
52
- duration: 0.5,
53
- })
54
- ```
55
-
56
- ### Step 5: Engage grip
57
-
58
- OneHandGrabbable and TwoHandsGrabbable are proximity-based and use the **squeeze/grip button (index 1)**, not the trigger.
59
-
60
- ```
61
- xr_set_gamepad_state({
62
- device: "controller-right",
63
- buttons: [{ index: 1, value: 1 }],
64
- })
65
- ```
66
-
67
- The object is now grabbed. If the user only asked to grab (not move), stop here.
68
-
69
- ## Optional Extensions
70
-
71
- Apply these based on the user's request.
72
-
73
- ### Step 6: Move to destination
74
-
75
- If the user specified a destination position, animate the controller there. If no position was given but the user asked to "move" the object, animate it to in front of the headset.
76
-
77
- To find "in front of headset": `xr_get_transform({ "device": "headset" })` → place at `(head.x, head.y - 0.2, head.z - 0.5)` adjusted for head orientation.
78
-
79
- ```
80
- xr_animate_to({
81
- device: "controller-right",
82
- position: { x, y, z },
83
- duration: 0.5,
84
- })
85
- ```
86
-
87
- ### Step 7: Release grip
88
-
89
- Release the squeeze button to drop the object.
90
-
91
- ```
92
- xr_set_gamepad_state({
93
- device: "controller-right",
94
- buttons: [{ index: 1, value: 0 }],
95
- })
96
- ```
97
-
98
- ### Step 8: Return controller
99
-
100
- Animate the controller back to its resting position so it's not overlapping the dropped object.
101
-
102
- ```
103
- xr_animate_to({
104
- device: "controller-right",
105
- position: { x: 0.2, y: 1.4, z: -0.3 },
106
- duration: 0.5,
107
- })
108
- ```
109
-
110
- Default resting positions: right `(0.2, 1.4, -0.3)`, left `(-0.2, 1.4, -0.3)`.
111
-
112
- ### Step 9: Verify
113
-
114
- Take a screenshot to confirm the result.
115
-
116
- ```
117
- browser_screenshot
118
- ```
119
-
120
- The screenshot command is runtime-only. If the editor is visible, the managed
121
- workspace switches to runtime before capture.
122
-
123
- ## Notes
124
-
125
- - **Never use `xr_set_device_state` to move controllers** — it teleports instead of animating, which can break grab state.
126
- - **Never use `xr_select` or trigger (button index 0) for grabs** — OneHandGrabbable/TwoHandsGrabbable respond to squeeze (button index 1).
127
- - **DistanceGrabbable is different** — it uses ray-based selection, not proximity. This skill does not cover DistanceGrabbable.
128
- - If the object lacks a name in the hierarchy, suggest adding `mesh.name = "MyObject"` in code before `createTransformEntity`.
50
+ Stop once the requested grab/move/release path and final state are proven. Leave
51
+ the controller released and the XR session in the state the user requested.
@@ -0,0 +1,177 @@
1
+ ---
2
+ name: iwsdk-hosting
3
+ description: Publish an IWSDK app to a public HTTPS origin so it can be installed as a PWA and packaged for the Meta Horizon Store. Use when deploying, hosting, or publishing the app, choosing a host, or when a file (web manifest, icons, .well-known/assetlinks.json) must reach an already-hosted site. Always asks first whether hosting already exists — recommends Vercel if not, and pauses with concrete upload steps if it does.
4
+ argument-hint: '[domain, host name, or deploy request]'
5
+ ---
6
+
7
+ # PWA Hosting
8
+
9
+ Packaging a Quest APK reads the app over the network, not off disk:
10
+ `bubblewrap` fetches the web manifest and icons from the live origin, and the
11
+ Trusted Web Activity refuses to launch until Digital Asset Links are reachable
12
+ there too. So the origin — call it `<DOMAIN>` — comes first, and every later
13
+ step depends on files actually being served from it.
14
+
15
+ User request is in `$ARGUMENTS`.
16
+
17
+ ## 1. Ask about hosting before doing anything else
18
+
19
+ **Never assume.** Ask the developer, up front, whether the app is already
20
+ deployed — with a structured question tool (AskUserQuestion) if the harness has
21
+ one, otherwise as a plain question. Do not deploy anything, do not pick a host,
22
+ and do not run a deploy CLI until this is answered.
23
+
24
+ > Is this app already deployed to a public HTTPS URL?
25
+ >
26
+ > - **Not deployed yet — recommend a host** → Route A
27
+ > - **Already hosted / host already chosen** (Netlify, Cloudflare Pages, GitHub
28
+ > Pages, S3+CloudFront, Firebase, own nginx/Apache server, internal CDN…) →
29
+ > Route B
30
+ > - **Deployed, but open to moving it** → describe both, then let them pick
31
+
32
+ If they answer with a URL, treat it as Route B and use that URL as `<DOMAIN>`.
33
+ If they are unreachable and you must proceed autonomously, take Route A, and
34
+ mark the choice `[ASSUMED]` in whatever plan or report you are writing.
35
+
36
+ ## 2. Route A — no host yet: recommend Vercel
37
+
38
+ Recommend Vercel, and say why in one line: it detects Vite with no config,
39
+ serves `dist/` over HTTPS with a stable public alias, keeps `public/` dotfolders
40
+ like `.well-known/` intact, and redeploys with one command — which matters
41
+ because asset links force a second publish later.
42
+
43
+ ```bash
44
+ npm run build # → dist/
45
+ npx -y vercel@latest whoami # auth check
46
+ npx -y vercel@latest teams ls # find <team-slug>
47
+ npx -y vercel@latest deploy --prod --yes --scope <team-slug>
48
+ ```
49
+
50
+ Use the **canonical alias** (`https://<project>.vercel.app`) as `<DOMAIN>`, not
51
+ the hashed per-deploy URL — under team deployment protection the hashed URL
52
+ returns 401 and every downstream fetch fails. Full walkthrough, first-run login,
53
+ and the redeploy rule: [`references/vercel.md`](references/vercel.md).
54
+
55
+ Then run the [contract check](#4-the-contract-what-must-be-reachable).
56
+
57
+ ## 3. Route B — host already chosen: pause and hand off
58
+
59
+ The developer owns the host, so **you do not publish — you prepare files and
60
+ stop.** Every time something new has to reach `<DOMAIN>`, run the handoff below
61
+ rather than guessing at their pipeline.
62
+
63
+ Publishing to an existing host happens at least **twice**, and the second one is
64
+ easy to forget:
65
+
66
+ | # | When | What must reach `<DOMAIN>` |
67
+ | - | ---- | -------------------------- |
68
+ | 1 | after the manifest + icons exist | the whole built `dist/` |
69
+ | 2 | after the signing keystore exists | `dist/.well-known/assetlinks.json` (rebuild first) |
70
+
71
+ A third happens for any later web-only fix — those need only a republish, never
72
+ a new APK.
73
+
74
+ ### Upload handoff protocol
75
+
76
+ Run this at each row above. Keep it short and literal; the developer should be
77
+ able to act without asking a follow-up question.
78
+
79
+ 1. **Build first.** `npm run build`. Vite copies `public/` — including
80
+ dotfolders like `.well-known/` — verbatim into `dist/`.
81
+ 2. **List the exact files and their exact destination URLs.** Local path →
82
+ public URL, one per line. Never say "upload the assets".
83
+ 3. **Give the concrete steps for their host**, not generic advice — the command
84
+ for their CLI, or the click path for their dashboard. Per-host recipes and
85
+ gotchas (dotfolder stripping, MIME types, subpath hosting, cache TTLs) are in
86
+ [`references/existing-hosts.md`](references/existing-hosts.md). If the host is
87
+ one you do not recognize, ask how they normally publish and adapt.
88
+ 4. **Offer to run it — do not assume you can.** Only run their deploy command
89
+ yourself if they confirm the CLI is installed and authenticated in this
90
+ environment. Otherwise they run it; suggest they can paste it into this
91
+ session prefixed with `!`.
92
+ 5. **Stop and wait.** Do not continue to the next pipeline step on the
93
+ assumption the upload happened.
94
+ 6. **Verify yourself once they say it is live**, with the checks in §4. If a
95
+ check fails, report the failing URL and status code and hand back — a wrong
96
+ guess here surfaces much later as "the TWA will not launch".
97
+
98
+ Handoff message template:
99
+
100
+ ```
101
+ Ready to publish. Please upload these to <DOMAIN>:
102
+
103
+ dist/manifest.webmanifest → https://<DOMAIN>/manifest.webmanifest
104
+ dist/icons/icon-192.png → https://<DOMAIN>/icons/icon-192.png
105
+ dist/icons/icon-512.png → https://<DOMAIN>/icons/icon-512.png
106
+ dist/icons/icon-512-maskable.png → https://<DOMAIN>/icons/icon-512-maskable.png
107
+ (or simply publish all of dist/ — these are already inside it)
108
+
109
+ On <host>, that is:
110
+ <the one command, or the exact dashboard click path>
111
+
112
+ Tell me when it is live and I will verify, then continue with packaging.
113
+ ```
114
+
115
+ ## 4. The contract: what must be reachable
116
+
117
+ Whichever route was taken, `<DOMAIN>` must satisfy all of this before
118
+ `bubblewrap update` runs. Check it yourself — do not take "it is deployed" as
119
+ proof.
120
+
121
+ | URL | Expected |
122
+ | --- | -------- |
123
+ | `https://<DOMAIN>/` | 200, HTTPS, valid cert |
124
+ | `https://<DOMAIN>/manifest.webmanifest` | 200, `Content-Type: application/manifest+json` |
125
+ | `https://<DOMAIN>/icons/icon-512.png` | 200, `image/png` |
126
+ | `https://<DOMAIN>/.well-known/assetlinks.json` | 200, `application/json` (after the keystore step) |
127
+ | `https://<DOMAIN>/android.keystore` | **404** — the keystore must never be published |
128
+
129
+ ```bash
130
+ for u in / /manifest.webmanifest /icons/icon-512.png /.well-known/assetlinks.json; do
131
+ printf '%s ' "$u"; curl -s -o /dev/null -w '%{http_code} %{content_type}\n' "https://<DOMAIN>$u"
132
+ done
133
+ curl -s -o /dev/null -w 'keystore %{http_code} (want 404)\n' "https://<DOMAIN>/android.keystore"
134
+ ```
135
+
136
+ Two failures are worth calling out because they look like host bugs and are not:
137
+
138
+ - **`.well-known/` 404s** while everything else works — the host is stripping
139
+ dotfolders. Fix per [`references/existing-hosts.md`](references/existing-hosts.md);
140
+ do not work around it by moving the file, the path is fixed by the TWA spec.
141
+ - **The manifest serves as `text/plain`** — some hosts have no mapping for
142
+ `.webmanifest`. Add the MIME type, or serve it as `manifest.json` and update
143
+ the `<link rel="manifest">` and `webManifestUrl` to match.
144
+
145
+ ## 5. Hosting at a subpath
146
+
147
+ If the app is served from `https://<DOMAIN>/<path>/` rather than the origin
148
+ root, two things change and both break silently:
149
+
150
+ - `start_url` and `scope` in the web manifest must be `/<path>/`, not `/`.
151
+ - `assetlinks.json` still has to sit at the **origin root**
152
+ (`https://<DOMAIN>/.well-known/assetlinks.json`) — a subpath copy is ignored.
153
+ If the developer does not control the origin root, they cannot ship a TWA from
154
+ that origin. Say so plainly and offer Route A as the alternative.
155
+
156
+ `base: './'` is already set in the scaffolded `vite.config.*`, so the JS/CSS
157
+ bundles themselves are fine at any path — it is only these two that need care.
158
+
159
+ ## 6. Redeploy vs rebuild
160
+
161
+ Once the APK exists, keep this distinction straight — it saves a Store round
162
+ trip:
163
+
164
+ - **Web-only change** (app logic, styling, manifest text, icons, asset links) →
165
+ republish `<DOMAIN>`. The installed TWA picks it up on next launch.
166
+ - **Native change** (package id, app name, launcher icon, version, app mode,
167
+ signing) → rebuild the APK and re-upload to the Store.
168
+
169
+ ## Reference Files
170
+
171
+ | File | Load when |
172
+ | ---- | --------- |
173
+ | [`references/vercel.md`](references/vercel.md) | Route A — full Vercel deploy, auth, aliases, redeploys |
174
+ | [`references/existing-hosts.md`](references/existing-hosts.md) | Route B — per-host publish recipes and their gotchas |
175
+
176
+ Packaging the hosted app into a signed Quest APK is the `iwsdk-pwa-packaging`
177
+ skill; this skill only gets it online.