@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
package/README.md CHANGED
@@ -12,8 +12,16 @@
12
12
 
13
13
  ```bash
14
14
  npm create @iwsdk@latest
15
+
16
+ # Cloud harness or repository that is already checked out
17
+ npm create @iwsdk@latest . -- --yes --force --target vr
15
18
  ```
16
19
 
20
+ `.` selects the current directory. If the target contains any files, Create
21
+ requires the explicit `--force` confirmation. Forced scaffolding overwrites
22
+ conflicting generated files but preserves unrelated files and an existing Git
23
+ repository. `--yes` never implies overwrite permission.
24
+
17
25
  Or with other package managers:
18
26
 
19
27
  ```bash
@@ -29,15 +37,33 @@ bun create @iwsdk
29
37
 
30
38
  ## Interactive Prompts
31
39
 
32
- The CLI will guide you through:
40
+ The default path is intentionally short and deterministic:
41
+
42
+ 1. **Project name** - Asked only when it is not provided as an argument
43
+ 2. **Starting point** - Virtual reality, mixed reality/passthrough, or Desktop 3D
44
+ 3. **Setup** - Create with recommended settings or customize the setup
45
+
46
+ Recommended settings create a TypeScript project, initialize Git, and install
47
+ dependencies. They also apply a small target-specific baseline:
48
+
49
+ | Starting point | Recommended baseline |
50
+ | --------------------------- | --------------------------------------------------------------------------------------------------------- |
51
+ | Virtual reality | Locomotion on a worker and grabbing enabled; physics disabled |
52
+ | Mixed reality / passthrough | Grabbing enabled; physics, room surfaces/anchors, and real-world placement disabled |
53
+ | Desktop 3D | Dedicated non-XR scene with browser camera, input, locomotion, and interaction behavior; physics disabled |
54
+
55
+ Choose **Customize setup...** to select JavaScript, change applicable SDK
56
+ features, or opt out of Git initialization and dependency installation. The CLI
57
+ derives low-level WebXR feature settings from those choices instead of asking
58
+ for raw `No` / `Optional` / `Required` states.
33
59
 
34
- 1. **Project name** - Directory name for your new project
35
- 2. **Language** - TypeScript or JavaScript
36
- 3. **Platform** - VR (Virtual Reality) or AR (Augmented Reality)
37
- 4. **XR Features** - Hand tracking, layers, anchors, hit-test, plane/mesh detection (tri-state: No/Optional/Required)
38
- 5. **SDK Features** - Locomotion (VR), Scene Understanding (AR), Grabbing, Physics
39
- 6. **Meta Spatial Editor** - Optional visual scene authoring integration
40
- 7. **Git & Install** - Initialize git repo and install dependencies
60
+ Every project includes guidance and configuration for Claude Code, Codex,
61
+ Cursor, GitHub Copilot/VS Code, and OpenCode. Delete integrations you do not use;
62
+ there is no tool-selection step during scaffolding.
63
+
64
+ Before writing files, Create prints the resolved starting point, language, SDK
65
+ features, and generated `World.create` options. These settings remain editable
66
+ in `src/index.ts`; changing them does not require scaffolding again.
41
67
 
42
68
  ## What You Get
43
69
 
@@ -45,9 +71,10 @@ A fully configured project with:
45
71
 
46
72
  - ⚡ **Vite** - Fast dev server with HMR
47
73
  - 🎮 **WebXR Emulator** - Develop without VR hardware
74
+ - 🖥️ **Desktop 3D starter** - Browser-native camera, movement, pointer input, and interactions
48
75
  - 📦 **GLTF Optimization** - Automatic asset compression
49
76
  - 🔒 **HTTPS** - Required for WebXR, auto-configured
50
- - 🏗️ **Meta Spatial Editor** - Visual scene authoring (optional)
77
+ - 🧩 **Native scene workflow** - IWSDK scene JSON and editor tooling
51
78
 
52
79
  ## Example
53
80
 
@@ -55,21 +82,12 @@ A fully configured project with:
55
82
  $ npm create @iwsdk@latest
56
83
 
57
84
  ===============================================
58
- IWSDK Create CLI v0.2.2
85
+ IWSDK Create CLI v<current version>
59
86
  Node v20.19.0
60
87
 
61
88
  ? Project name › iwsdk-app
62
- ? Which language do you want to use? › TypeScript
63
- ? What type of experience are you building? › Virtual Reality
64
- ? Enable Hand Tracking? › Optional
65
- ? Enable WebXR Layers? › Optional
66
- ? Enable locomotion? › Yes
67
- ? Deploy locomotion engine on a Worker? › Yes (recommended)
68
- ? Enable grabbing (one/two-hand, distance)? › Yes
69
- ? Enable physics simulation (Havok)? › No
70
- ? Enable Meta Spatial Editor integration? › No (Can change later)
71
- ? Set up a Git repository? › Yes
72
- ? Install dependencies now? › Yes
89
+ ? What should this project start as? › Virtual reality - Start inside an authored virtual environment.
90
+ ? Setup › Create with recommended settings
73
91
  ```
74
92
 
75
93
  ## Command Line Options
@@ -81,30 +99,65 @@ npm create @iwsdk@latest my-app
81
99
  # Skip all prompts and use defaults
82
100
  npm create @iwsdk@latest my-app -- -y
83
101
 
84
- # Use custom CDN for recipes/assets
85
- npm create @iwsdk@latest -- --assets-base https://my-cdn.com/iwsdk
102
+ # Create a mixed reality starter non-interactively
103
+ npm create @iwsdk@latest mr-app -- -y --target ar
104
+
105
+ # Create a desktop browser 3D starter non-interactively
106
+ npm create @iwsdk@latest desktop-app -- -y --target browser
107
+
108
+ # Scaffold into the current, already-populated repository
109
+ npm create @iwsdk@latest . -- -y --force --target vr
110
+
111
+ # Use canary SDK bundle
112
+ npm create @iwsdk@latest -- --canary
86
113
  ```
87
114
 
88
- | Flag | Description |
89
- | --------------------- | -------------------------------------------------------- |
90
- | `[name]` | Project name (first positional argument) |
91
- | `-y, --yes` | Skip prompts and use defaults (VR + TypeScript + manual) |
92
- | `--assets-base <url>` | Custom CDN base URL for recipes and assets |
115
+ Use `-y` / `--yes` for deterministic non-interactive scaffolding. Without it,
116
+ `--target` and its compatibility aliases can preselect the starting point, but
117
+ the interactive setup controls language, features, Git, and installation.
118
+
119
+ | Flag | Description |
120
+ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
121
+ | `[name]` | Project directory; use `.` to scaffold in the current directory |
122
+ | `-y, --yes` | Skip prompts; defaults to VR, TypeScript, recommended features, Git, and dependency installation |
123
+ | `--force` | Confirm overwriting conflicting generated files when the target directory is non-empty |
124
+ | `--target <target>` | Starting point: `vr`, `ar`, or `browser` |
125
+ | `--mode <mode>` | Compatibility alias for XR targets: `vr` or `ar` |
126
+ | `--xr` / `--no-xr` | Compatibility selectors for VR (or `--mode ar`) and Desktop 3D |
127
+ | `--language <lang>` | `ts` or `js` |
128
+ | `--locomotion` / `--no-locomotion` | Enable or disable VR locomotion |
129
+ | `--grabbing` / `--no-grabbing` | Enable or disable VR/MR grabbing |
130
+ | `--physics` / `--no-physics` | Enable or disable physics |
131
+ | `--scene-understanding` / `--no-scene-understanding` | Enable or disable MR room surfaces and anchors |
132
+ | `--environment-raycast` / `--no-environment-raycast` | Enable or disable MR real-world placement |
133
+ | `--install` / `--no-install` | Install or skip dependencies |
134
+ | `--git` / `--no-git` | Initialize or skip a Git repository |
135
+ | `--canary` | Use the default canary SDK bundle |
136
+ | `--canary URL` | Use a custom HTTP(S) SDK bundle |
137
+
138
+ Automation and coding agents should map the requested experience to a target
139
+ and high-level feature flags before invoking Create, then pass those choices
140
+ with `--yes`. When the harness starts inside an existing repository, pass `.`
141
+ and `--force`; do not treat `--yes` as overwrite consent. The CLI does not infer
142
+ application intent from an open-ended description.
93
143
 
94
144
  ## Generated Templates
95
145
 
96
146
  Based on your choices, one of these variants is generated:
97
147
 
98
- | Template ID | Description |
99
- | ------------------- | ------------------------------------- |
100
- | `vr-manual-ts` | VR + TypeScript + code-only scene |
101
- | `vr-manual-js` | VR + JavaScript + code-only scene |
102
- | `vr-metaspatial-ts` | VR + TypeScript + Meta Spatial Editor |
103
- | `vr-metaspatial-js` | VR + JavaScript + Meta Spatial Editor |
104
- | `ar-manual-ts` | AR + TypeScript + code-only scene |
105
- | `ar-manual-js` | AR + JavaScript + code-only scene |
106
- | `ar-metaspatial-ts` | AR + TypeScript + Meta Spatial Editor |
107
- | `ar-metaspatial-js` | AR + JavaScript + Meta Spatial Editor |
148
+ | Template ID | Description |
149
+ | ------------------- | --------------------------------------------- |
150
+ | `vr-manual-ts` | VR + TypeScript + native workflow |
151
+ | `vr-manual-js` | VR + JavaScript + native workflow |
152
+ | `ar-manual-ts` | MR/passthrough + TypeScript + native workflow |
153
+ | `ar-manual-js` | MR/passthrough + JavaScript + native workflow |
154
+ | `browser-manual-ts` | Desktop 3D + TypeScript + native workflow |
155
+ | `browser-manual-js` | Desktop 3D + JavaScript + native workflow |
156
+
157
+ The scaffolded project includes native scene JSON under `public/scenes/` and is
158
+ ready for declarative scene authoring through the IWSDK managed workspace. It
159
+ also includes one canonical `AGENTS.md`; selected tool adapters add only their
160
+ native MCP, permission, skill, or import-shim files.
108
161
 
109
162
  ## Requirements
110
163
 
@@ -137,13 +190,22 @@ pnpm --filter @iwsdk/create dev
137
190
 
138
191
  - `src/cli.ts` — Entrypoint: parses flags, runs prompts, scaffolds project
139
192
  - `src/prompts.ts` — Interactive questions and defaults
140
- - `src/recipes.ts` — Fetch helpers for CDN-hosted recipes
141
- - `src/scaffold.ts` — Wraps Chef's `buildProject` and writes files
193
+ - `src/project-target.ts` — Target-directory validation and in-place resolution
194
+ - `src/project-files.ts` — Builds the common source plus target manifest/scene
195
+ - `src/project-manifest.ts` — Generates the project manifest authority
196
+ - `src/scaffold.ts` — Safely writes the generated `ProjectFile[]`
142
197
  - `src/installer.ts` — Dependency installation and next steps
143
198
  - `src/types.ts` — Shared types (`VariantId`, `TriState`, `PromptResult`)
144
199
 
145
200
  ### How It Works
146
201
 
147
- The CLI uses [@pmndrs/chef](https://github.com/pmndrs/chef) to apply recipes fetched from jsDelivr CDN. Recipes and assets live in the `@iwsdk/starter-assets` package.
202
+ The CLI ships one common TypeScript source tree, mechanically generated
203
+ JavaScript output, target scene seeds, and agent guidance in its own package.
204
+ It writes `iwsdk.config.json` and the selected `main.iwsdk.scene.json` locally;
205
+ scaffolding does not fetch a remote recipe.
206
+
207
+ Claude guidance is the canonical Agent Skills source. The package build derives
208
+ the `.agents/skills` tree used by Codex, Cursor, Copilot, and OpenCode and
209
+ translates path-scoped rules into each selected harness's native format.
148
210
 
149
211
  </details>