@iwsdk/create 1.1.0 → 1.2.0-rc.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 (118) hide show
  1. package/README.md +68 -16
  2. package/dist/cli.js +7917 -3404
  3. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-build-model/SKILL.md +1 -0
  4. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-compose-scene/SKILL.md +3 -2
  5. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-debug/SKILL.md +1 -0
  6. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-depth-occlusion/SKILL.md +1 -0
  7. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-dev/SKILL.md +1 -0
  8. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-dev/references/api-reference.md +8 -1
  9. package/dist/guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +96 -0
  10. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-dev/references/iterate.md +16 -7
  11. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-dev/references/planner.md +9 -5
  12. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-glasses-test/SKILL.md +1 -0
  13. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-grab/SKILL.md +1 -0
  14. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-hosting/SKILL.md +3 -1
  15. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-native-xr-test/SKILL.md +17 -1
  16. package/dist/guidance/files/.agents/skills/iwsdk-offline/SKILL.md +217 -0
  17. package/dist/guidance/files/.agents/skills/iwsdk-offline/assets/offline.ts.template +99 -0
  18. package/dist/guidance/files/.agents/skills/iwsdk-offline/assets/sw.js.template +241 -0
  19. package/dist/guidance/files/.agents/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
  20. package/dist/guidance/files/.agents/skills/iwsdk-offline/references/build-step.md +71 -0
  21. package/dist/guidance/files/.agents/skills/iwsdk-offline/references/page.md +70 -0
  22. package/dist/guidance/files/.agents/skills/iwsdk-offline/references/service-worker.md +107 -0
  23. package/dist/guidance/files/.agents/skills/iwsdk-offline/references/testing.md +57 -0
  24. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-physics/SKILL.md +1 -0
  25. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-physics/references/tuning-and-config.md +1 -0
  26. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-physics/references/workflows.md +9 -3
  27. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-pwa-packaging/SKILL.md +13 -1
  28. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +1 -1
  29. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +30 -0
  30. package/dist/guidance/{agents → files}/.agents/skills/iwsdk-ray/SKILL.md +1 -0
  31. package/dist/guidance/{claude/.claude → files/.agents}/skills/iwsdk-ui/SKILL.md +17 -7
  32. package/dist/guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +74 -0
  33. package/dist/guidance/{claude → files}/.claude/agents/iwsdk-project-code-reviewer.md +1 -0
  34. package/dist/guidance/{claude → files}/.claude/rules/assets-and-manifest.md +3 -0
  35. package/dist/guidance/{claude → files}/.claude/rules/ecs-api.md +1 -0
  36. package/dist/guidance/{claude → files}/.claude/rules/scene-json.md +1 -0
  37. package/dist/guidance/{claude → files}/.claude/rules/uikitml.md +1 -0
  38. package/dist/guidance/{claude → files}/.claude/settings.json +9 -3
  39. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-build-model/SKILL.md +1 -0
  40. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-compose-scene/SKILL.md +3 -2
  41. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-debug/SKILL.md +1 -0
  42. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-depth-occlusion/SKILL.md +1 -0
  43. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-dev/SKILL.md +1 -0
  44. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-dev/references/api-reference.md +8 -1
  45. package/dist/guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +96 -0
  46. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-dev/references/iterate.md +16 -7
  47. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-dev/references/planner.md +9 -5
  48. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-glasses-test/SKILL.md +1 -0
  49. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-grab/SKILL.md +1 -0
  50. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-hosting/SKILL.md +3 -1
  51. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-native-xr-test/SKILL.md +17 -1
  52. package/dist/guidance/files/.claude/skills/iwsdk-offline/SKILL.md +217 -0
  53. package/dist/guidance/files/.claude/skills/iwsdk-offline/assets/offline.ts.template +99 -0
  54. package/dist/guidance/files/.claude/skills/iwsdk-offline/assets/sw.js.template +241 -0
  55. package/dist/guidance/files/.claude/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
  56. package/dist/guidance/files/.claude/skills/iwsdk-offline/references/build-step.md +71 -0
  57. package/dist/guidance/files/.claude/skills/iwsdk-offline/references/page.md +70 -0
  58. package/dist/guidance/files/.claude/skills/iwsdk-offline/references/service-worker.md +107 -0
  59. package/dist/guidance/files/.claude/skills/iwsdk-offline/references/testing.md +57 -0
  60. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-physics/SKILL.md +1 -0
  61. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-physics/references/tuning-and-config.md +1 -0
  62. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-physics/references/workflows.md +9 -3
  63. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-pwa-packaging/SKILL.md +13 -1
  64. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +1 -1
  65. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +30 -0
  66. package/dist/guidance/{claude → files}/.claude/skills/iwsdk-ray/SKILL.md +1 -0
  67. package/dist/guidance/{agents/.agents → files/.claude}/skills/iwsdk-ui/SKILL.md +17 -7
  68. package/dist/guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +74 -0
  69. package/dist/guidance/{cursor → files}/.cursor/rules/assets-and-manifest.mdc +3 -0
  70. package/dist/guidance/{cursor → files}/.cursor/rules/ecs-api.mdc +1 -0
  71. package/dist/guidance/{cursor → files}/.cursor/rules/scene-json.mdc +1 -0
  72. package/dist/guidance/{cursor → files}/.cursor/rules/uikitml.mdc +1 -0
  73. package/dist/guidance/{copilot → files}/.github/instructions/assets-and-manifest.instructions.md +2 -1
  74. package/dist/guidance/{copilot → files}/.github/instructions/ecs-api.instructions.md +1 -0
  75. package/dist/guidance/{copilot → files}/.github/instructions/scene-json.instructions.md +1 -0
  76. package/dist/guidance/{copilot → files}/.github/instructions/uikitml.instructions.md +1 -0
  77. package/dist/guidance/{common → files}/AGENTS.md +107 -27
  78. package/dist/guidance/{scoped-agents → files}/public/scenes/AGENTS.md +2 -0
  79. package/dist/guidance/{scoped-agents → files}/public/ui/AGENTS.md +2 -0
  80. package/dist/guidance/{scoped-agents → files}/src/AGENTS.md +2 -0
  81. package/dist/guidance/manifest.json +954 -0
  82. package/dist/template/common/.codex/config.toml +2 -0
  83. package/package.json +5 -5
  84. package/scripts/verify-release-ready.mjs +1 -2
  85. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-build-model/agents/openai.yaml +0 -0
  86. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-build-model/assets/hardsurface.ts.template +0 -0
  87. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/agents/openai.yaml +0 -0
  88. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/environment-recipes.md +0 -0
  89. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/extended-workflow.md +0 -0
  90. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/image-intake.md +0 -0
  91. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/scene-composition.md +0 -0
  92. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/scene-format.md +0 -0
  93. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/scene-review.md +0 -0
  94. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-compose-scene/references/text-intake.md +0 -0
  95. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-hosting/references/existing-hosts.md +0 -0
  96. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-hosting/references/vercel.md +0 -0
  97. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-physics/references/component-reference.md +0 -0
  98. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/app-modes.md +0 -0
  99. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/bubblewrap.md +0 -0
  100. /package/dist/guidance/{agents → files}/.agents/skills/iwsdk-pwa-packaging/references/store-upload.md +0 -0
  101. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-build-model/agents/openai.yaml +0 -0
  102. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-build-model/assets/hardsurface.ts.template +0 -0
  103. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/agents/openai.yaml +0 -0
  104. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/environment-recipes.md +0 -0
  105. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/extended-workflow.md +0 -0
  106. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/image-intake.md +0 -0
  107. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/scene-composition.md +0 -0
  108. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/scene-format.md +0 -0
  109. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/scene-review.md +0 -0
  110. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-compose-scene/references/text-intake.md +0 -0
  111. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-hosting/references/existing-hosts.md +0 -0
  112. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-hosting/references/vercel.md +0 -0
  113. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-physics/references/component-reference.md +0 -0
  114. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/app-modes.md +0 -0
  115. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/bubblewrap.md +0 -0
  116. /package/dist/guidance/{claude → files}/.claude/skills/iwsdk-pwa-packaging/references/store-upload.md +0 -0
  117. /package/dist/guidance/{claude → files}/CLAUDE.md +0 -0
  118. /package/dist/{guidance/codex → template/common-js}/.codex/config.toml +0 -0
package/README.md CHANGED
@@ -13,14 +13,60 @@
13
13
  ```bash
14
14
  npm create @iwsdk@latest
15
15
 
16
- # Cloud harness or repository that is already checked out
17
- npm create @iwsdk@latest . -- --yes --force --target vr
16
+ # Add IWSDK to an existing project, or a repository that is already checked out
17
+ npm create @iwsdk@latest . -- --yes --target vr
18
18
  ```
19
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.
20
+ `.` selects the current directory.
21
+
22
+ **Existing projects.** When the target already has a `package.json`, Create adds
23
+ IWSDK to that project and never overwrites an existing file, even with
24
+ `--force`:
25
+
26
+ - everything is checked before the first write: an invalid `package.json`, or a
27
+ Vite major the IWSDK plugin does not support yet (Vite 8), stops Create with
28
+ nothing changed, and `--canary` is refused;
29
+ - a minimal IWSDK skeleton goes into its own `src/iwsdk/` folder (a world entry,
30
+ empty asset and component manifests, and type references), so it never shadows
31
+ the project's modules. `iwsdk.config.json` and an empty scene are added where
32
+ missing, and `index.html`, a Vite config and `tsconfig.json` only when the
33
+ project has none. A new Vite config is `vite.config.mts` (`.mjs` in
34
+ JavaScript) unless `package.json` sets `"type": "module"`, because the IWSDK
35
+ plugin is ESM-only. The starter demo is not added;
36
+ - locomotion stays off unless asked for (`--locomotion`, or Yes in the
37
+ customize prompt, which starts at No here), because the empty scene has no
38
+ floor to stand on; the report says so. When it is on, give your floor a
39
+ `LocomotionEnvironment` component, or the player falls through the world. In
40
+ a project whose `iwsdk.config.json` already turns locomotion on, that step is
41
+ listed while its scene has no `LocomotionEnvironment`;
42
+ - `package.json` is merged in its own indentation: IWSDK packages, the `three`
43
+ alias and `@types/three` are set, versions are only raised, and specs that are
44
+ not version ranges (`workspace:`, `file:`, `catalog:`, or a dist-tag such as
45
+ `latest`) are left alone and reported. Other dependencies and your scripts are
46
+ kept; `iwsdk:dev` is added when `dev` is taken;
47
+ - overrides go where the package manager reads them: `overrides` (npm, bun),
48
+ `resolutions` (yarn), or `pnpm-workspace.yaml` (pnpm), merged without touching
49
+ its other settings;
50
+ - `iwsdkDev()` is added to an existing Vite config when the config's own
51
+ top-level `plugins` array is unambiguous, Vite loads it as an ES module, and
52
+ it is the project's only Vite config; otherwise it is listed as a step that
53
+ names the config Vite loads (in Vite's order: `.js`, `.mjs`, `.ts`, `.cjs`,
54
+ `.mts`, `.cts`). A config that Vite loads as CommonJS cannot import the
55
+ plugin, so renaming it to `.mjs`/`.mts` is listed too, also when it already
56
+ imports the plugin;
57
+ - `.gitignore` gains IWSDK's runtime and MCP entries, dependencies install with
58
+ the package manager found from the nearest lockfile (a monorepo's included),
59
+ and no Git repository is created;
60
+ - coding-agent guidance is installed as by `npx @iwsdk/cli agents sync`, keeping
61
+ the text of an existing `AGENTS.md` or `CLAUDE.md`.
62
+
63
+ Create then prints what it created and kept and the steps left to finish, such
64
+ as importing `./iwsdk` from the app's entry module. The report is printed even
65
+ when the install fails, with the command to retry.
66
+
67
+ A non-empty target **without** a `package.json` requires `--force`, which
68
+ overwrites conflicting generated files but preserves unrelated files and an
69
+ existing Git repository. `--yes` never implies overwrite permission.
24
70
 
25
71
  Or with other package managers:
26
72
 
@@ -55,7 +101,9 @@ dependencies. They also apply a small target-specific baseline:
55
101
  Choose **Customize setup...** to select JavaScript, change applicable SDK
56
102
  features, or opt out of Git initialization and dependency installation. The CLI
57
103
  derives low-level WebXR feature settings from those choices instead of asking
58
- for raw `No` / `Optional` / `Required` states.
104
+ for raw `No` / `Optional` / `Required` states. In an existing project, the
105
+ recommended settings leave locomotion off and the customize prompt starts it at
106
+ No (see above).
59
107
 
60
108
  Every project includes guidance and configuration for Claude Code, Codex,
61
109
  Cursor, GitHub Copilot/VS Code, and OpenCode. Delete integrations you do not use;
@@ -105,8 +153,8 @@ npm create @iwsdk@latest mr-app -- -y --target ar
105
153
  # Create a desktop browser 3D starter non-interactively
106
154
  npm create @iwsdk@latest desktop-app -- -y --target browser
107
155
 
108
- # Scaffold into the current, already-populated repository
109
- npm create @iwsdk@latest . -- -y --force --target vr
156
+ # Add IWSDK to the project in the current directory (overwrites nothing)
157
+ npm create @iwsdk@latest . -- -y --target vr
110
158
 
111
159
  # Use canary SDK bundle
112
160
  npm create @iwsdk@latest -- --canary
@@ -120,7 +168,7 @@ the interactive setup controls language, features, Git, and installation.
120
168
  | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
121
169
  | `[name]` | Project directory; use `.` to scaffold in the current directory |
122
170
  | `-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 |
171
+ | `--force` | Overwrite conflicting generated files in a non-empty target without a `package.json` |
124
172
  | `--target <target>` | Starting point: `vr`, `ar`, or `browser` |
125
173
  | `--mode <mode>` | Compatibility alias for XR targets: `vr` or `ar` |
126
174
  | `--xr` / `--no-xr` | Compatibility selectors for VR (or `--mode ar`) and Desktop 3D |
@@ -137,9 +185,10 @@ the interactive setup controls language, features, Git, and installation.
137
185
 
138
186
  Automation and coding agents should map the requested experience to a target
139
187
  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.
188
+ with `--yes`. When the harness starts inside an existing project, pass `.`;
189
+ Create adopts it without overwriting files. Do not treat `--yes` as overwrite
190
+ consent. The CLI does not infer application intent from an open-ended
191
+ description.
143
192
 
144
193
  ## Generated Templates
145
194
 
@@ -204,8 +253,11 @@ JavaScript output, target scene seeds, and agent guidance in its own package.
204
253
  It writes `iwsdk.config.json` and the selected `main.iwsdk.scene.json` locally;
205
254
  scaffolding does not fetch a remote recipe.
206
255
 
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.
256
+ Agent guidance comes from `@iwsdk/core` (`packages/core/agent-guidance`), so a
257
+ new app receives the same stamped files that `npx @iwsdk/cli agents sync`
258
+ installs and later refreshes. Claude guidance is the canonical Agent Skills
259
+ source; the core build derives the `.agents/skills` tree used by Codex, Cursor,
260
+ Copilot, and OpenCode and translates path-scoped rules into each harness's
261
+ native format.
210
262
 
211
263
  </details>