@iwsdk/create 1.2.0-rc.0 → 1.2.0-rc.2

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 (87) hide show
  1. package/README.md +22 -6
  2. package/dist/cli.js +591 -99
  3. package/dist/guidance/files/.agents/skills/iwsdk-build-model/SKILL.md +1 -1
  4. package/dist/guidance/files/.agents/skills/iwsdk-compose-scene/SKILL.md +1 -1
  5. package/dist/guidance/files/.agents/skills/iwsdk-debug/SKILL.md +1 -1
  6. package/dist/guidance/files/.agents/skills/iwsdk-depth-occlusion/SKILL.md +1 -1
  7. package/dist/guidance/files/.agents/skills/iwsdk-dev/SKILL.md +20 -1
  8. package/dist/guidance/files/.agents/skills/iwsdk-dev/references/api-reference.md +2 -1
  9. package/dist/guidance/files/.agents/skills/iwsdk-dev/references/headless-rendering.md +15 -1
  10. package/dist/guidance/files/.agents/skills/iwsdk-dev/references/iterate.md +7 -3
  11. package/dist/guidance/files/.agents/skills/iwsdk-glasses-test/SKILL.md +1 -1
  12. package/dist/guidance/files/.agents/skills/iwsdk-grab/SKILL.md +1 -1
  13. package/dist/guidance/files/.agents/skills/iwsdk-hosting/SKILL.md +3 -2
  14. package/dist/guidance/files/.agents/skills/iwsdk-metavr-native/SKILL.md +216 -0
  15. package/dist/guidance/files/.agents/skills/iwsdk-metavr-native/assets/iwn-host.mjs +71 -0
  16. package/dist/guidance/files/.agents/skills/iwsdk-native-xr-test/SKILL.md +1 -1
  17. package/dist/guidance/files/.agents/skills/iwsdk-offline/SKILL.md +217 -0
  18. package/dist/guidance/files/.agents/skills/iwsdk-offline/assets/offline.ts.template +99 -0
  19. package/dist/guidance/files/.agents/skills/iwsdk-offline/assets/sw.js.template +241 -0
  20. package/dist/guidance/files/.agents/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
  21. package/dist/guidance/files/.agents/skills/iwsdk-offline/references/build-step.md +71 -0
  22. package/dist/guidance/files/.agents/skills/iwsdk-offline/references/page.md +70 -0
  23. package/dist/guidance/files/.agents/skills/iwsdk-offline/references/service-worker.md +107 -0
  24. package/dist/guidance/files/.agents/skills/iwsdk-offline/references/testing.md +57 -0
  25. package/dist/guidance/files/.agents/skills/iwsdk-physics/SKILL.md +1 -1
  26. package/dist/guidance/files/.agents/skills/iwsdk-physics/references/tuning-and-config.md +1 -0
  27. package/dist/guidance/files/.agents/skills/iwsdk-physics/references/workflows.md +9 -3
  28. package/dist/guidance/files/.agents/skills/iwsdk-pwa-packaging/SKILL.md +18 -3
  29. package/dist/guidance/files/.agents/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +1 -1
  30. package/dist/guidance/files/.agents/skills/iwsdk-pwa-packaging/references/troubleshooting.md +30 -0
  31. package/dist/guidance/files/.agents/skills/iwsdk-ray/SKILL.md +1 -1
  32. package/dist/guidance/files/.agents/skills/iwsdk-ui/SKILL.md +12 -5
  33. package/dist/guidance/files/.agents/skills/iwsdk-upgrade/SKILL.md +1 -1
  34. package/dist/guidance/files/.claude/agents/iwsdk-project-code-reviewer.md +1 -1
  35. package/dist/guidance/files/.claude/rules/assets-and-manifest.md +1 -1
  36. package/dist/guidance/files/.claude/rules/ecs-api.md +1 -1
  37. package/dist/guidance/files/.claude/rules/scene-json.md +1 -1
  38. package/dist/guidance/files/.claude/rules/uikitml.md +1 -1
  39. package/dist/guidance/files/.claude/settings.json +2 -0
  40. package/dist/guidance/files/.claude/skills/iwsdk-build-model/SKILL.md +1 -1
  41. package/dist/guidance/files/.claude/skills/iwsdk-compose-scene/SKILL.md +1 -1
  42. package/dist/guidance/files/.claude/skills/iwsdk-debug/SKILL.md +1 -1
  43. package/dist/guidance/files/.claude/skills/iwsdk-depth-occlusion/SKILL.md +1 -1
  44. package/dist/guidance/files/.claude/skills/iwsdk-dev/SKILL.md +20 -1
  45. package/dist/guidance/files/.claude/skills/iwsdk-dev/references/api-reference.md +2 -1
  46. package/dist/guidance/files/.claude/skills/iwsdk-dev/references/headless-rendering.md +15 -1
  47. package/dist/guidance/files/.claude/skills/iwsdk-dev/references/iterate.md +7 -3
  48. package/dist/guidance/files/.claude/skills/iwsdk-glasses-test/SKILL.md +1 -1
  49. package/dist/guidance/files/.claude/skills/iwsdk-grab/SKILL.md +1 -1
  50. package/dist/guidance/files/.claude/skills/iwsdk-hosting/SKILL.md +3 -2
  51. package/dist/guidance/files/.claude/skills/iwsdk-metavr-native/SKILL.md +216 -0
  52. package/dist/guidance/files/.claude/skills/iwsdk-metavr-native/assets/iwn-host.mjs +71 -0
  53. package/dist/guidance/files/.claude/skills/iwsdk-native-xr-test/SKILL.md +1 -1
  54. package/dist/guidance/files/.claude/skills/iwsdk-offline/SKILL.md +217 -0
  55. package/dist/guidance/files/.claude/skills/iwsdk-offline/assets/offline.ts.template +99 -0
  56. package/dist/guidance/files/.claude/skills/iwsdk-offline/assets/sw.js.template +241 -0
  57. package/dist/guidance/files/.claude/skills/iwsdk-offline/assets/write-service-worker.mjs.template +72 -0
  58. package/dist/guidance/files/.claude/skills/iwsdk-offline/references/build-step.md +71 -0
  59. package/dist/guidance/files/.claude/skills/iwsdk-offline/references/page.md +70 -0
  60. package/dist/guidance/files/.claude/skills/iwsdk-offline/references/service-worker.md +107 -0
  61. package/dist/guidance/files/.claude/skills/iwsdk-offline/references/testing.md +57 -0
  62. package/dist/guidance/files/.claude/skills/iwsdk-physics/SKILL.md +1 -1
  63. package/dist/guidance/files/.claude/skills/iwsdk-physics/references/tuning-and-config.md +1 -0
  64. package/dist/guidance/files/.claude/skills/iwsdk-physics/references/workflows.md +9 -3
  65. package/dist/guidance/files/.claude/skills/iwsdk-pwa-packaging/SKILL.md +18 -3
  66. package/dist/guidance/files/.claude/skills/iwsdk-pwa-packaging/references/manifest-and-icons.md +1 -1
  67. package/dist/guidance/files/.claude/skills/iwsdk-pwa-packaging/references/troubleshooting.md +30 -0
  68. package/dist/guidance/files/.claude/skills/iwsdk-ray/SKILL.md +1 -1
  69. package/dist/guidance/files/.claude/skills/iwsdk-ui/SKILL.md +12 -5
  70. package/dist/guidance/files/.claude/skills/iwsdk-upgrade/SKILL.md +1 -1
  71. package/dist/guidance/files/.cursor/rules/assets-and-manifest.mdc +1 -1
  72. package/dist/guidance/files/.cursor/rules/ecs-api.mdc +1 -1
  73. package/dist/guidance/files/.cursor/rules/scene-json.mdc +1 -1
  74. package/dist/guidance/files/.cursor/rules/uikitml.mdc +1 -1
  75. package/dist/guidance/files/.github/instructions/assets-and-manifest.instructions.md +1 -1
  76. package/dist/guidance/files/.github/instructions/ecs-api.instructions.md +1 -1
  77. package/dist/guidance/files/.github/instructions/scene-json.instructions.md +1 -1
  78. package/dist/guidance/files/.github/instructions/uikitml.instructions.md +1 -1
  79. package/dist/guidance/files/AGENTS.md +10 -1
  80. package/dist/guidance/files/public/scenes/AGENTS.md +1 -1
  81. package/dist/guidance/files/public/ui/AGENTS.md +1 -1
  82. package/dist/guidance/files/src/AGENTS.md +1 -1
  83. package/dist/guidance/manifest.json +142 -12
  84. package/dist/template/scenes/ar.iwsdk.scene.json +1 -0
  85. package/dist/template/scenes/immersive.iwsdk.scene.json +1 -0
  86. package/package.json +4 -4
  87. package/scripts/verify-release-ready.mjs +2 -2
package/dist/cli.js CHANGED
@@ -8,7 +8,7 @@ import require$$1 from 'node:child_process';
8
8
  import path$4 from 'node:path';
9
9
  import require$$3, { existsSync as existsSync$1 } from 'node:fs';
10
10
  import process$3 from 'node:process';
11
- import fsp, { readdir, readFile, lstat, rm, mkdir, writeFile, rename, realpath, rmdir } from 'fs/promises';
11
+ import fsp, { readdir, readFile, lstat, realpath, rm, mkdir, writeFile, rename, rmdir } from 'fs/promises';
12
12
  import { createHash, randomUUID } from 'crypto';
13
13
  import 'module';
14
14
  import { readFile as readFile$1, readdir as readdir$1 } from 'node:fs/promises';
@@ -12604,6 +12604,8 @@ const GUIDANCE_TOOLS = [
12604
12604
  // test/agent-guidance.test.ts checks both sides against a fresh render.
12605
12605
  const GUIDANCE_FORMAT = 1;
12606
12606
  const BLOCK_NAME = 'iwsdk-agent-guidance';
12607
+ /** The root AGENTS.md block unit, which a CLAUDE.md import points at. */
12608
+ const ROOT_BLOCK = 'AGENTS.md';
12607
12609
  const STAMP_LINE = /^<!-- iwsdk-agent-guidance version=(\S+) sha256=([0-9a-f]{64})(?: name=(\S+))? [^\n]*-->\r?\n?/mu;
12608
12610
  const BLOCK_PATTERN = new RegExp(`<!-- BEGIN ${BLOCK_NAME} version=(\\S+) sha256=([0-9a-f]{64}) -->\\n([\\s\\S]*?)<!-- END ${BLOCK_NAME} -->\\n?`, 'u');
12609
12611
  const BLOCK_BEGIN = new RegExp(`<!-- BEGIN ${BLOCK_NAME}\\b`, 'gu');
@@ -12715,6 +12717,12 @@ async function loadGuidanceSource(root, origin = 'explicit') {
12715
12717
  assertRelativeUnitPath(file);
12716
12718
  }
12717
12719
  }
12720
+ for (const [retired, successors] of Object.entries(manifest.successors ?? {})) {
12721
+ assertRelativeUnitPath(retired);
12722
+ for (const successor of successors) {
12723
+ assertRelativeUnitPath(successor);
12724
+ }
12725
+ }
12718
12726
  return { root, manifest, origin };
12719
12727
  }
12720
12728
  function selectedUnits(manifest, tools) {
@@ -12739,11 +12747,14 @@ async function isSameFile(first, second) {
12739
12747
  return false;
12740
12748
  }
12741
12749
  }
12742
- /** Temporary siblings a sync left behind when it was killed mid-swap. */
12743
- const TEMPORARY_SIBLING = /^\..+\.iwsdk-(?:new|old)-(\d+)-(\d+)$/u;
12750
+ /**
12751
+ * Temporary siblings a sync left behind when it was killed mid-swap: the
12752
+ * name they stand in for, `new` or `old`, the process id and the time.
12753
+ */
12754
+ const TEMPORARY_SIBLING = /^\.(.+)\.iwsdk-(new|old)-(\d+)-(\d+)$/u;
12744
12755
  /** A temporary sibling that a sync running right now may still need. */
12745
12756
  function isInUse(name) {
12746
- const [, pid, createdAt] = TEMPORARY_SIBLING.exec(name) ?? [];
12757
+ const [, , , pid, createdAt] = TEMPORARY_SIBLING.exec(name) ?? [];
12747
12758
  if (Date.now() - Number(createdAt) < 10 * 60_000) {
12748
12759
  return true;
12749
12760
  }
@@ -12900,6 +12911,19 @@ function replacementResult(unit, ownership, force) {
12900
12911
  }
12901
12912
  return null;
12902
12913
  }
12914
+ /**
12915
+ * A unit that `onlyExisting` left out because the project does not have it.
12916
+ * `lacks` names what an existing file is missing.
12917
+ */
12918
+ function missingResult(unit, unitPath = unit.path, lacks) {
12919
+ return {
12920
+ path: unitPath,
12921
+ kind: unit.kind,
12922
+ action: 'skipped',
12923
+ reason: 'missing',
12924
+ ...(lacks ? { detail: lacks } : {}),
12925
+ };
12926
+ }
12903
12927
  async function pathKind(filePath) {
12904
12928
  try {
12905
12929
  const stat = await lstat(filePath);
@@ -12912,7 +12936,13 @@ async function pathKind(filePath) {
12912
12936
  throw error;
12913
12937
  }
12914
12938
  }
12915
- async function syncDirectoryUnit(unit, source, writer, force) {
12939
+ /**
12940
+ * The unit syncs below take `create`: whether a unit the project lacks (a
12941
+ * missing file or folder, or a block or import missing from a file) may be
12942
+ * written. `onlyExisting` allows it only for units that replace guidance
12943
+ * this run retires, and for folders a killed sync was replacing.
12944
+ */
12945
+ async function syncDirectoryUnit(unit, source, writer, force, create) {
12916
12946
  const localRoot = path$5.join(writer.projectRoot, unit.path);
12917
12947
  const replace = async () => {
12918
12948
  const files = [];
@@ -12924,6 +12954,9 @@ async function syncDirectoryUnit(unit, source, writer, force) {
12924
12954
  const kind = await pathKind(localRoot);
12925
12955
  const localFiles = kind === 'directory' ? await readTree(localRoot) : null;
12926
12956
  if (kind === 'missing' || localFiles?.size === 0) {
12957
+ if (!create) {
12958
+ return missingResult(unit);
12959
+ }
12927
12960
  await replace();
12928
12961
  return { path: unit.path, kind: unit.kind, action: 'created' };
12929
12962
  }
@@ -12957,10 +12990,13 @@ async function syncDirectoryUnit(unit, source, writer, force) {
12957
12990
  }
12958
12991
  return result;
12959
12992
  }
12960
- async function syncFileUnit(unit, source, writer, force) {
12993
+ async function syncFileUnit(unit, source, writer, force, create) {
12961
12994
  const local = await readTextIfExists(path$5.join(writer.projectRoot, unit.path));
12962
12995
  const next = await readSourceFile(source, unit.path);
12963
12996
  if (local == null) {
12997
+ if (!create) {
12998
+ return missingResult(unit);
12999
+ }
12964
13000
  await writer.write(unit.path, next);
12965
13001
  return { path: unit.path, kind: unit.kind, action: 'created' };
12966
13002
  }
@@ -12974,10 +13010,13 @@ async function syncFileUnit(unit, source, writer, force) {
12974
13010
  }
12975
13011
  return result;
12976
13012
  }
12977
- async function syncBlockUnit(unit, source, writer, force) {
13013
+ async function syncBlockUnit(unit, source, writer, force, create) {
12978
13014
  const local = await readTextIfExists(path$5.join(writer.projectRoot, unit.path));
12979
13015
  const block = (await readSourceFile(source, unit.path)).toString('utf8');
12980
13016
  if (local == null) {
13017
+ if (!create) {
13018
+ return missingResult(unit);
13019
+ }
12981
13020
  await writer.write(unit.path, block);
12982
13021
  return { path: unit.path, kind: unit.kind, action: 'created' };
12983
13022
  }
@@ -13036,6 +13075,10 @@ async function syncBlockUnit(unit, source, writer, force) {
13036
13075
  reason: 'forced',
13037
13076
  };
13038
13077
  }
13078
+ if (!create) {
13079
+ // No IWSDK block: the developer removed it or replaced the file.
13080
+ return missingResult(unit, unit.path, 'no iwsdk-agent-guidance block');
13081
+ }
13039
13082
  await writer.write(unit.path, withLineEndings(`${withTrailingNewline(normalized)}${normalized.trim() ? '\n' : ''}${block}`, local));
13040
13083
  return {
13041
13084
  path: unit.path,
@@ -13044,23 +13087,54 @@ async function syncBlockUnit(unit, source, writer, force) {
13044
13087
  reason: 'appended',
13045
13088
  };
13046
13089
  }
13047
- async function syncClaudeImport(unit, source, writer, force) {
13090
+ /**
13091
+ * A root CLAUDE.md that holds the full guidance of a release before 1.0, as
13092
+ * that release wrote it. It is replaced with an `@AGENTS.md` import, so the
13093
+ * guidance it held now comes from the AGENTS.md block.
13094
+ */
13095
+ async function holdsLegacyClaudeGuidance(unit, source, projectRoot) {
13096
+ const filePath = path$5.join(projectRoot, unit.path);
13097
+ const rootFile = await readTextIfExists(filePath);
13098
+ if (rootFile == null ||
13099
+ (await isSameFile(filePath, path$5.join(projectRoot, ROOT_BLOCK)))) {
13100
+ return false;
13101
+ }
13102
+ const hash = fileUnitHash(rootFile);
13103
+ return (hash !==
13104
+ fileUnitHash((await readSourceFile(source, unit.path)).toString()) &&
13105
+ (source.manifest.legacy[unit.path]?.includes(hash) ?? false));
13106
+ }
13107
+ /**
13108
+ * `replaceLegacy`: whether a CLAUDE.md holding the full guidance of a release
13109
+ * before 1.0 may become an import, which needs the AGENTS.md block in place.
13110
+ */
13111
+ async function syncClaudeImport(unit, source, writer, force, create, replaceLegacy) {
13048
13112
  const rootFile = await readTextIfExists(path$5.join(writer.projectRoot, unit.path));
13049
13113
  const nestedFile = await readTextIfExists(path$5.join(writer.projectRoot, '.claude', 'CLAUDE.md'));
13050
13114
  const next = await readSourceFile(source, unit.path);
13051
13115
  if (rootFile == null && nestedFile == null) {
13116
+ if (!create) {
13117
+ return missingResult(unit);
13118
+ }
13052
13119
  await writer.write(unit.path, next);
13053
13120
  return { path: unit.path, kind: unit.kind, action: 'created' };
13054
13121
  }
13055
13122
  if (rootFile != null &&
13056
- (await isSameFile(path$5.join(writer.projectRoot, unit.path), path$5.join(writer.projectRoot, 'AGENTS.md')))) {
13123
+ (await isSameFile(path$5.join(writer.projectRoot, unit.path), path$5.join(writer.projectRoot, ROOT_BLOCK)))) {
13057
13124
  // CLAUDE.md is a link to AGENTS.md: Claude already reads the guidance.
13058
13125
  return { path: unit.path, kind: unit.kind, action: 'unchanged' };
13059
13126
  }
13060
- if (rootFile != null &&
13061
- fileUnitHash(rootFile) !== fileUnitHash(next.toString('utf8')) &&
13062
- source.manifest.legacy[unit.path]?.includes(fileUnitHash(rootFile))) {
13127
+ if (await holdsLegacyClaudeGuidance(unit, source, writer.projectRoot)) {
13063
13128
  // Releases before 1.0 put the full guidance in CLAUDE.md.
13129
+ if (!replaceLegacy) {
13130
+ return {
13131
+ path: unit.path,
13132
+ kind: unit.kind,
13133
+ action: 'skipped',
13134
+ reason: 'retired',
13135
+ detail: 'It holds the full guidance of an IWSDK release before 1.0, and becomes an @AGENTS.md import once AGENTS.md has the iwsdk-agent-guidance block.',
13136
+ };
13137
+ }
13064
13138
  await writer.write(unit.path, withLineEndings(next.toString('utf8'), rootFile));
13065
13139
  return {
13066
13140
  path: unit.path,
@@ -13093,6 +13167,10 @@ async function syncClaudeImport(unit, source, writer, force) {
13093
13167
  (nestedFile != null && /^@\.\.\/AGENTS\.md\s*$/mu.test(nestedFile))) {
13094
13168
  return { path: unit.path, kind: unit.kind, action: 'unchanged' };
13095
13169
  }
13170
+ if (!create) {
13171
+ // The import was removed, or CLAUDE.md replaced.
13172
+ return missingResult(unit, rootFile != null ? unit.path : '.claude/CLAUDE.md', 'no @AGENTS.md import');
13173
+ }
13096
13174
  if (rootFile != null) {
13097
13175
  await writer.write(unit.path, withLineEndings(`${withTrailingNewline(rootFile)}\n@AGENTS.md\n`, rootFile));
13098
13176
  return {
@@ -13126,9 +13204,12 @@ function ownedSkillNames(manifest) {
13126
13204
  }
13127
13205
  return names;
13128
13206
  }
13129
- async function syncClaudeSettings(unit, source, writer, installedSkills, retiredSkills, force) {
13207
+ async function syncClaudeSettings(unit, source, writer, skills, force, onlyExisting, create) {
13130
13208
  const filePath = path$5.join(writer.projectRoot, unit.path);
13131
13209
  const raw = await readTextIfExists(filePath);
13210
+ if (raw == null && !create) {
13211
+ return missingResult(unit);
13212
+ }
13132
13213
  let settings = {};
13133
13214
  if (raw != null) {
13134
13215
  let parsed;
@@ -13160,24 +13241,34 @@ async function syncClaudeSettings(unit, source, writer, installedSkills, retired
13160
13241
  const shipped = new Set(unit.skills ?? []);
13161
13242
  const owned = new Set([
13162
13243
  ...ownedSkillNames(source.manifest),
13163
- ...retiredSkills,
13244
+ ...skills.removed,
13164
13245
  ]);
13246
+ const skillOf = (rule) => typeof rule === 'string' ? rule.match(SKILL_PERMISSION)?.[1] : undefined;
13247
+ const allowed = new Set(allow.map(skillOf));
13165
13248
  // Grant skills this sync installed (all of them for a new settings file);
13166
13249
  // a permission the developer removed for an untouched skill stays removed.
13167
13250
  // Grant every shipped skill when the file is new, when --force is given, or
13168
13251
  // when no IWSDK skill permission is left (after `adapter prune`, say).
13252
+ // `onlyExisting` grants a skill only the permission of the retired skill it
13253
+ // replaces, and keeps the permissions of retired skills that stay.
13169
13254
  const grantAll = raw == null ||
13170
13255
  force ||
13171
13256
  !allow.some((rule) => {
13172
- const name = typeof rule === 'string'
13173
- ? rule.match(SKILL_PERMISSION)?.[1]
13174
- : undefined;
13257
+ const name = skillOf(rule);
13175
13258
  return name != null && owned.has(name);
13176
13259
  });
13177
- const grant = [...shipped].filter((name) => grantAll || installedSkills.has(name));
13260
+ const grant = onlyExisting && raw != null
13261
+ ? [...skills.replacedBy]
13262
+ .filter(([retired]) => allowed.has(retired))
13263
+ .flatMap(([, successors]) => successors)
13264
+ .filter((name) => shipped.has(name))
13265
+ : [...shipped].filter((name) => grantAll || skills.installed.has(name));
13178
13266
  const isRetired = (rule) => {
13179
- const name = typeof rule === 'string' ? rule.match(SKILL_PERMISSION)?.[1] : undefined;
13180
- return name != null && owned.has(name) && !shipped.has(name);
13267
+ const name = skillOf(rule);
13268
+ return (name != null &&
13269
+ owned.has(name) &&
13270
+ !shipped.has(name) &&
13271
+ !(onlyExisting && skills.kept.has(name)));
13181
13272
  };
13182
13273
  const nextAllow = allow.filter((rule) => !isRetired(rule));
13183
13274
  for (const name of grant) {
@@ -13255,7 +13346,14 @@ function toolsForPath(unitPath) {
13255
13346
  }
13256
13347
  return GUIDANCE_TOOLS;
13257
13348
  }
13258
- async function pruneRetiredUnits(source, tools, writer) {
13349
+ /**
13350
+ * IWSDK units in the project that this release no longer ships, for the
13351
+ * selected tools. Also returns the temporary siblings a killed sync left
13352
+ * behind, for the caller to delete once its writes are done, and the units
13353
+ * such a sync was replacing when it was killed (their folder is gone, so
13354
+ * they count as present).
13355
+ */
13356
+ async function findRetiredUnits(source, tools, writer) {
13259
13357
  const shipped = new Set(source.manifest.units.map((unit) => unit.path));
13260
13358
  const blocks = new Set(source.manifest.units
13261
13359
  .filter((unit) => unit.kind === 'block' || unit.kind === 'claude-import')
@@ -13293,8 +13391,9 @@ async function pruneRetiredUnits(source, tools, writer) {
13293
13391
  }
13294
13392
  }
13295
13393
  }
13296
- const results = [];
13297
- const removedSkills = new Set();
13394
+ const retired = [];
13395
+ const interrupted = new Set();
13396
+ const leftovers = [];
13298
13397
  for (const directory of ['.', ...PRUNE_ROOTS.map((root) => root.directory)]) {
13299
13398
  let entries;
13300
13399
  try {
@@ -13304,7 +13403,15 @@ async function pruneRetiredUnits(source, tools, writer) {
13304
13403
  continue;
13305
13404
  }
13306
13405
  for (const name of entries.filter((entry) => TEMPORARY_SIBLING.test(entry) && !isInUse(entry))) {
13307
- await writer.remove(path$5.posix.join(directory, name));
13406
+ const [, original, label] = TEMPORARY_SIBLING.exec(name);
13407
+ const originalPath = path$5.posix.join(directory, original);
13408
+ if (label === 'old' &&
13409
+ (await pathKind(path$5.join(writer.projectRoot, originalPath))) ===
13410
+ 'missing') {
13411
+ // Killed between the two renames of replaceDirectory.
13412
+ interrupted.add(originalPath);
13413
+ }
13414
+ leftovers.push(path$5.posix.join(directory, name));
13308
13415
  }
13309
13416
  }
13310
13417
  for (const [unitPath, kind] of candidates) {
@@ -13330,24 +13437,13 @@ async function pruneRetiredUnits(source, tools, writer) {
13330
13437
  continue;
13331
13438
  }
13332
13439
  const ownership = classify(localHash, undefined, stamp, source.manifest.legacy[unitPath], source.manifest.version);
13333
- if (ownership === 'managed' || ownership === 'legacy') {
13334
- await writer.remove(unitPath);
13335
- results.push({ path: unitPath, kind, action: 'removed' });
13336
- if (kind === 'directory') {
13337
- removedSkills.add(name);
13338
- }
13339
- }
13340
- else if (ownership === 'modified') {
13341
- // A retired IWSDK unit the developer edited: keep it, but say so.
13342
- results.push({
13343
- path: unitPath,
13344
- kind,
13345
- action: 'skipped',
13346
- reason: 'modified',
13347
- });
13440
+ if (ownership === 'managed' ||
13441
+ ownership === 'legacy' ||
13442
+ ownership === 'modified') {
13443
+ retired.push({ path: unitPath, kind, ownership });
13348
13444
  }
13349
13445
  }
13350
- return { results, removedSkills };
13446
+ return { retired, interrupted, leftovers };
13351
13447
  }
13352
13448
  function readSkillDescription(text) {
13353
13449
  const frontmatter = normalizeText(text).match(/^---\n([\s\S]*?)\n---/u)?.[1];
@@ -13426,44 +13522,153 @@ function buildAgentNotice(source, skills, dryRun, changedCount) {
13426
13522
  /**
13427
13523
  * Write a guidance release into a project. Files IWSDK wrote and nobody edited
13428
13524
  * are replaced; edited files and files IWSDK does not own are reported and left
13429
- * alone unless `force` is set; retired IWSDK files are removed.
13525
+ * alone unless `force` is set; retired IWSDK files are removed once what
13526
+ * replaces them is in place. Missing units are created unless `onlyExisting`
13527
+ * is set (see there).
13430
13528
  */
13431
- async function syncAgentGuidance({ projectRoot, source, tools = [...GUIDANCE_TOOLS], force = false, dryRun = false, }) {
13529
+ async function syncAgentGuidance({ projectRoot, source, tools = [...GUIDANCE_TOOLS], force = false, dryRun = false, onlyExisting = false, }) {
13432
13530
  const writer = createWriter(projectRoot, dryRun);
13433
- const pruned = await pruneRetiredUnits(source, tools, writer);
13531
+ const { retired, interrupted, leftovers } = await findRetiredUnits(source, tools, writer);
13532
+ const units = selectedUnits(source.manifest, tools);
13533
+ const shipped = new Set(source.manifest.units.map((unit) => unit.path));
13534
+ const selected = new Map(units.map((unit) => [unit.path, unit.kind]));
13535
+ // A successor for a coding tool the project does not use is not this
13536
+ // project's, and settings replace no guidance (permissions follow the
13537
+ // skills); one this release does not ship can never be written.
13538
+ const counts = (successor) => shipped.has(successor)
13539
+ ? (selected.get(successor) ?? 'claude-settings') !== 'claude-settings'
13540
+ : true;
13541
+ // Retired units IWSDK wrote and nobody edited are replaced: removed once
13542
+ // the units that replace them are in place. `onlyExisting` replaces only
13543
+ // the ones the release names successors for, and keeps the rest.
13544
+ const replacing = new Map();
13545
+ for (const unit of retired) {
13546
+ const successors = source.manifest.successors?.[unit.path];
13547
+ if (unit.ownership !== 'modified' && (successors || !onlyExisting)) {
13548
+ replacing.set(unit.path, (successors ?? []).filter(counts));
13549
+ }
13550
+ }
13551
+ const claudeImport = units.find((unit) => unit.kind === 'claude-import');
13552
+ const migratesClaude = onlyExisting &&
13553
+ claudeImport != null &&
13554
+ (await holdsLegacyClaudeGuidance(claudeImport, source, projectRoot));
13555
+ // What `onlyExisting` may add: the successors of the guidance this run
13556
+ // replaces, and folders a killed sync was replacing.
13557
+ const additions = new Set([
13558
+ ...[...replacing.values()].flat(),
13559
+ ...(migratesClaude ? [ROOT_BLOCK] : []),
13560
+ ...interrupted,
13561
+ ]);
13562
+ const create = (unit) => !onlyExisting || additions.has(unit.path);
13434
13563
  const results = [];
13564
+ const resultsByUnit = new Map();
13565
+ // In the project once this run is done (in a dry run, once it would be).
13566
+ const present = (unitPath) => {
13567
+ const result = resultsByUnit.get(unitPath);
13568
+ return result !== undefined && result.reason !== 'missing';
13569
+ };
13570
+ // AGENTS.md holds the iwsdk-agent-guidance block once this run is done: not
13571
+ // when it is missing, holds edited guidance from before the block, or has
13572
+ // broken markers.
13573
+ const holdsRootBlock = () => {
13574
+ const reason = resultsByUnit.get(ROOT_BLOCK)?.reason;
13575
+ return (present(ROOT_BLOCK) &&
13576
+ reason !== 'legacy-modified' &&
13577
+ reason !== 'malformed-block');
13578
+ };
13435
13579
  const installedSkills = new Set();
13436
- const units = selectedUnits(source.manifest, tools);
13437
- // Settings last: they grant the skills this run installed.
13438
- for (const unit of [
13439
- ...units.filter((candidate) => candidate.kind !== 'claude-settings'),
13440
- ...units.filter((candidate) => candidate.kind === 'claude-settings'),
13441
- ]) {
13580
+ // The CLAUDE.md import after the AGENTS.md block it points at. Settings
13581
+ // last, once the skills and retired units are settled.
13582
+ const position = (unit) => unit.kind === 'claude-import' ? 1 : unit.kind === 'claude-settings' ? 2 : 0;
13583
+ for (const unit of [...units].sort((left, right) => position(left) - position(right))) {
13584
+ let result;
13442
13585
  switch (unit.kind) {
13443
- case 'directory': {
13444
- const result = await syncDirectoryUnit(unit, source, writer, force);
13586
+ case 'directory':
13587
+ result = await syncDirectoryUnit(unit, source, writer, force, create(unit));
13445
13588
  if (unit.path.startsWith('.claude/') &&
13446
13589
  (result.action === 'created' || result.action === 'updated')) {
13447
13590
  installedSkills.add(path$5.posix.basename(unit.path));
13448
13591
  }
13449
- results.push(result);
13450
13592
  break;
13451
- }
13452
13593
  case 'file':
13453
- results.push(await syncFileUnit(unit, source, writer, force));
13594
+ result = await syncFileUnit(unit, source, writer, force, create(unit));
13454
13595
  break;
13455
13596
  case 'block':
13456
- results.push(await syncBlockUnit(unit, source, writer, force));
13597
+ result = await syncBlockUnit(unit, source, writer, force, create(unit));
13457
13598
  break;
13458
13599
  case 'claude-import':
13459
- results.push(await syncClaudeImport(unit, source, writer, force));
13600
+ result = await syncClaudeImport(unit, source, writer, force, create(unit), !onlyExisting || holdsRootBlock());
13460
13601
  break;
13461
13602
  case 'claude-settings':
13462
- results.push(await syncClaudeSettings(unit, source, writer, installedSkills, pruned.removedSkills, force));
13463
- break;
13603
+ continue;
13464
13604
  }
13605
+ results.push(result);
13606
+ resultsByUnit.set(unit.path, result);
13465
13607
  }
13466
- results.push(...pruned.results);
13608
+ const removals = [];
13609
+ const retiredResults = [];
13610
+ for (const unit of retired) {
13611
+ const successors = replacing.get(unit.path);
13612
+ const result = { path: unit.path, kind: unit.kind };
13613
+ if (unit.ownership === 'modified') {
13614
+ // A retired IWSDK unit the developer edited: keep it, but say so.
13615
+ retiredResults.push({ ...result, action: 'skipped', reason: 'modified' });
13616
+ }
13617
+ else if (successors == null) {
13618
+ retiredResults.push({
13619
+ ...result,
13620
+ action: 'skipped',
13621
+ reason: 'retired',
13622
+ detail: `IWSDK ${source.manifest.version} no longer ships it and does not name a replacement; \`npx @iwsdk/cli@latest agents sync\` removes it.`,
13623
+ });
13624
+ }
13625
+ else if (!successors.every(present)) {
13626
+ // Never leave a project with less guidance than it had.
13627
+ retiredResults.push({
13628
+ ...result,
13629
+ action: 'skipped',
13630
+ reason: 'retired',
13631
+ detail: `It stays until ${successors.filter((successor) => !present(successor)).join(', ')} can be written in its place.`,
13632
+ });
13633
+ }
13634
+ else {
13635
+ removals.push(unit);
13636
+ retiredResults.push({
13637
+ ...result,
13638
+ action: 'removed',
13639
+ ...(successors.length > 0 ? { replacedBy: successors } : {}),
13640
+ });
13641
+ }
13642
+ }
13643
+ const settings = units.find((unit) => unit.kind === 'claude-settings');
13644
+ if (settings) {
13645
+ const claudeSkill = (unitPath) => unitPath.startsWith('.claude/skills/');
13646
+ const name = (unitPath) => path$5.posix.basename(unitPath);
13647
+ results.push(await syncClaudeSettings(settings, source, writer, {
13648
+ installed: installedSkills,
13649
+ removed: new Set(removals
13650
+ .filter((unit) => unit.kind === 'directory')
13651
+ .map((unit) => name(unit.path))),
13652
+ kept: new Set(retired
13653
+ .filter((unit) => claudeSkill(unit.path) && !removals.includes(unit))
13654
+ .map((unit) => name(unit.path))),
13655
+ replacedBy: new Map(removals
13656
+ .filter((unit) => claudeSkill(unit.path))
13657
+ .map((unit) => [
13658
+ name(unit.path),
13659
+ replacing.get(unit.path).filter(claudeSkill).map(name),
13660
+ ])),
13661
+ }, force, onlyExisting, create(settings)));
13662
+ }
13663
+ for (const unit of removals) {
13664
+ await writer.remove(unit.path);
13665
+ }
13666
+ // Last: until a folder that a killed sync moved aside is written again,
13667
+ // its moved-aside copy is what tells the next sync to write it.
13668
+ for (const leftover of leftovers) {
13669
+ await writer.remove(leftover);
13670
+ }
13671
+ results.push(...retiredResults);
13467
13672
  const skills = await summarizeSkills(source, tools);
13468
13673
  const changedCount = results.filter((result) => result.action !== 'unchanged' && result.action !== 'skipped').length;
13469
13674
  return {
@@ -20598,6 +20803,26 @@ function depthAt(code, start, offset) {
20598
20803
  }
20599
20804
  return depth;
20600
20805
  }
20806
+ /**
20807
+ * Whether the config loads @iwsdk/vite-plugin-dev with a static `import`,
20808
+ * `export … from` or `require()`. A config that Vite loads as CommonJS fails
20809
+ * on that, because the package is ESM-only. A dynamic `import()` works in
20810
+ * either, and `import type` is erased before the config runs.
20811
+ */
20812
+ function loadsPluginStatically(source) {
20813
+ const code = blankNonCode(source);
20814
+ const loads = /(?:^|[^\w$.])(?:(?:import|export)(\s+type(?!\s+from\b))?\b[^;'"`]*?\bfrom|import|require\s*\()\s*(['"])/gu;
20815
+ for (const match of code.matchAll(loads)) {
20816
+ // Strings are blanked in `code`; read the specifier from the source.
20817
+ const open = match.index + match[0].length - 1;
20818
+ const specifier = source.slice(open + 1, source.indexOf(match[2], open + 1));
20819
+ if (match[1] == null &&
20820
+ /^@iwsdk\/vite-plugin-dev(?:\/|$)/u.test(specifier)) {
20821
+ return true;
20822
+ }
20823
+ }
20824
+ return false;
20825
+ }
20601
20826
  function patchViteConfig(source) {
20602
20827
  const code = blankNonCode(source);
20603
20828
  if (/@iwsdk\/vite-plugin-dev/u.test(source) && /\biwsdkDev\b/u.test(code)) {
@@ -20673,18 +20898,21 @@ class AdoptError extends Error {
20673
20898
  this.name = 'AdoptError';
20674
20899
  }
20675
20900
  }
20901
+ /** In the order Vite 7 looks for them: it loads the first it finds. */
20676
20902
  const VITE_CONFIG_NAMES = [
20677
- 'vite.config.ts',
20678
- 'vite.config.mts',
20679
20903
  'vite.config.js',
20680
20904
  'vite.config.mjs',
20681
- 'vite.config.cts',
20905
+ 'vite.config.ts',
20682
20906
  'vite.config.cjs',
20907
+ 'vite.config.mts',
20908
+ 'vite.config.cts',
20683
20909
  ];
20684
20910
  /** @iwsdk/vite-plugin-dev's peer range. */
20685
20911
  const VITE_PEER_RANGE = '^7.0.0';
20686
20912
  const SKELETON_DIRECTORY = 'src/iwsdk';
20687
20913
  /** IWSDK's own .gitignore entries: runtime state and generated MCP configs. */
20914
+ /** Added with --metavr-native: native APK builds (npm run build:metavr). */
20915
+ const NATIVE_GITIGNORE_ENTRY = 'dist-metavr/';
20688
20916
  const GITIGNORE_ENTRIES = [
20689
20917
  '.iwsdk/',
20690
20918
  '.mcp.json',
@@ -20704,6 +20932,40 @@ function stringRecord(value) {
20704
20932
  function isRegistrySpec(spec) {
20705
20933
  return semver$4.validRange(spec) != null;
20706
20934
  }
20935
+ /** A dist-tag such as `latest`: the registry picks the version at install. */
20936
+ function isDistTag(spec) {
20937
+ return /^[a-z][\w.-]*$/iu.test(spec) && !isRegistrySpec(spec);
20938
+ }
20939
+ /** A scene keys LocomotionEnvironment with or without the prefix core strips. */
20940
+ const LOCOMOTION_ENVIRONMENT_KEYS = [
20941
+ 'LocomotionEnvironment',
20942
+ 'com.iwsdk.components.LocomotionEnvironment',
20943
+ ];
20944
+ /** Whether any node, prefab or override in a scene has LocomotionEnvironment. */
20945
+ function hasLocomotionEnvironment(value) {
20946
+ if (Array.isArray(value)) {
20947
+ return value.some(hasLocomotionEnvironment);
20948
+ }
20949
+ if (!isRecord$1(value)) {
20950
+ return false;
20951
+ }
20952
+ const { components } = value;
20953
+ return ((isRecord$1(components) &&
20954
+ LOCOMOTION_ENVIRONMENT_KEYS.some((key) => key in components)) ||
20955
+ Object.values(value).some(hasLocomotionEnvironment));
20956
+ }
20957
+ async function readJson(file) {
20958
+ try {
20959
+ return JSON.parse(await fsp.readFile(file, 'utf8'));
20960
+ }
20961
+ catch {
20962
+ return null;
20963
+ }
20964
+ }
20965
+ /** The .mjs or .mts name, which Vite loads as ESM whatever package.json says. */
20966
+ function esmConfigName(name) {
20967
+ return name.replace(/\.c?([jt]s)$/u, '.m$1');
20968
+ }
20707
20969
  /** True when `spec` asks for an older release than `wanted`. */
20708
20970
  function isOlder(spec, wanted) {
20709
20971
  const current = semver$4.minVersion(spec);
@@ -20748,7 +21010,7 @@ export const worldReady = World.create(sceneContainer(), projectOptions);
20748
21010
  * its own folder so it can never shadow the project's modules, plus the
20749
21011
  * starter's project-level files where the project has none.
20750
21012
  */
20751
- function skeletonFiles(files, language) {
21013
+ function skeletonFiles(files, language, esmPackage) {
20752
21014
  const byPath = new Map(files.map((file) => [file.path, file]));
20753
21015
  const extension = language === 'ts' ? 'ts' : 'js';
20754
21016
  const entry = `${SKELETON_DIRECTORY}/index.${extension}`;
@@ -20805,9 +21067,14 @@ function skeletonFiles(files, language) {
20805
21067
  '.codex/config.toml',
20806
21068
  ]) {
20807
21069
  const file = byPath.get(name);
20808
- if (file) {
20809
- skeleton.push(file);
21070
+ if (!file) {
21071
+ continue;
20810
21072
  }
21073
+ // Vite loads vite.config.ts/.js as CommonJS unless package.json says
21074
+ // "type": "module"; .mts/.mjs always load as ESM, which the plugin needs.
21075
+ skeleton.push(name.startsWith('vite.config.') && !esmPackage
21076
+ ? { ...file, path: name.replace(/\.(ts|js)$/u, '.m$1') }
21077
+ : file);
20811
21078
  }
20812
21079
  return skeleton;
20813
21080
  }
@@ -20883,7 +21150,7 @@ workspaceRoot = null) {
20883
21150
  }
20884
21151
  else if (name === 'vite') {
20885
21152
  if (!isRegistrySpec(current)) {
20886
- keep('not a registry version; check it satisfies Vite 7');
21153
+ keep(`${isDistTag(current) ? 'a dist-tag' : 'not a registry version'}; check it satisfies Vite 7`);
20887
21154
  continue;
20888
21155
  }
20889
21156
  if (semver$4.subset(semver$4.validRange(current), VITE_PEER_RANGE)) {
@@ -20894,11 +21161,16 @@ workspaceRoot = null) {
20894
21161
  continue;
20895
21162
  }
20896
21163
  else if (!isRegistrySpec(current)) {
20897
- keep('not a registry version');
21164
+ keep(isDistTag(current)
21165
+ ? 'a dist-tag, not a version range'
21166
+ : 'not a registry version');
20898
21167
  continue;
20899
21168
  }
20900
21169
  else if (!isOlder(current, spec)) {
20901
- keep('newer than this release');
21170
+ // ^1.2.0 for 1.2.0 already asks for this release: nothing to report.
21171
+ if (isOlder(spec, current)) {
21172
+ keep('newer than this release');
21173
+ }
20902
21174
  continue;
20903
21175
  }
20904
21176
  report.changed.push({ field: declaredIn, name, from: current, to: spec });
@@ -21038,7 +21310,7 @@ function mergePnpmOverrides(raw, overrides) {
21038
21310
  }
21039
21311
  return { text: document.toString(), added, replaced };
21040
21312
  }
21041
- async function adoptExistingProject({ outDir, files, guidanceRoot, language, }) {
21313
+ async function adoptExistingProject({ outDir, files, guidanceRoot, language, locomotionOffRequested = false, }) {
21042
21314
  // 1. Check everything; write nothing yet.
21043
21315
  const packageJsonPath = path$5.join(outDir, 'package.json');
21044
21316
  if ((await writeTarget(outDir, 'package.json')) !== 'file') {
@@ -21067,9 +21339,16 @@ async function adoptExistingProject({ outDir, files, guidanceRoot, language, })
21067
21339
  const packageManager = packageManagerInfo.name;
21068
21340
  const inWorkspace = packageManagerInfo.root !== path$5.resolve(outDir);
21069
21341
  const byPath = new Map(files.map((file) => [file.path, file]));
21070
- const existingViteConfig = VITE_CONFIG_NAMES.find((name) => existsSync(path$5.join(outDir, name))) ??
21071
- null;
21072
- const planned = skeletonFiles(files, language).filter((file) => !(file.path.startsWith('vite.config.') && existingViteConfig != null));
21342
+ const viteConfigs = VITE_CONFIG_NAMES.filter((name) => existsSync(path$5.join(outDir, name)));
21343
+ // The one Vite loads; it ignores the rest.
21344
+ const existingViteConfig = viteConfigs[0] ?? null;
21345
+ const esmPackage = existingPackageJson.type === 'module';
21346
+ // Vite loads .cjs/.cts configs, and .js/.ts ones without "type": "module",
21347
+ // as CommonJS, which cannot load the ESM-only @iwsdk/vite-plugin-dev.
21348
+ const commonJsViteConfig = existingViteConfig != null &&
21349
+ (/\.c[jt]s$/u.test(existingViteConfig) ||
21350
+ (!esmPackage && /\.[jt]s$/u.test(existingViteConfig)));
21351
+ const planned = skeletonFiles(files, language, esmPackage).filter((file) => !(file.path.startsWith('vite.config.') && existingViteConfig != null));
21073
21352
  const targets = new Map();
21074
21353
  for (const file of planned) {
21075
21354
  const target = await writeTarget(outDir, file.path);
@@ -21153,6 +21432,8 @@ async function adoptExistingProject({ outDir, files, guidanceRoot, language, })
21153
21432
  }
21154
21433
  }
21155
21434
  let viteConfig;
21435
+ // The config already had iwsdkDev() before this run.
21436
+ let pluginFound = false;
21156
21437
  if (existingViteConfig == null) {
21157
21438
  const createdConfig = created.find((file) => file.startsWith('vite.config.'));
21158
21439
  viteConfig = { file: createdConfig ?? null, status: 'created' };
@@ -21162,19 +21443,66 @@ async function adoptExistingProject({ outDir, files, guidanceRoot, language, })
21162
21443
  }
21163
21444
  else {
21164
21445
  const configPath = path$5.join(outDir, existingViteConfig);
21165
- const patched = patchViteConfig(await fsp.readFile(configPath, 'utf8'));
21166
- if (patched.status === 'patched') {
21446
+ const source = await fsp.readFile(configPath, 'utf8');
21447
+ const patched = patchViteConfig(source);
21448
+ pluginFound = patched.status === 'already-configured';
21449
+ let status = patched.status;
21450
+ if (
21451
+ // Adding the plugin to a CommonJS config would stop it from loading,
21452
+ // and with several configs the edit could land where Vite never looks.
21453
+ (status === 'patched' &&
21454
+ (commonJsViteConfig || viteConfigs.length > 1)) ||
21455
+ // A CommonJS config that imports the ESM-only plugin already fails.
21456
+ (pluginFound && commonJsViteConfig && loadsPluginStatically(source))) {
21457
+ status = 'manual';
21458
+ }
21459
+ if (status === 'patched') {
21167
21460
  await fsp.writeFile(configPath, patched.text);
21168
21461
  }
21169
- viteConfig = { file: existingViteConfig, status: patched.status };
21170
- }
21171
- if (viteConfig.status === 'manual') {
21172
- manualSteps.push(`Add the IWSDK plugin to ${viteConfig.file}: \`import { iwsdkDev } from '@iwsdk/vite-plugin-dev'\` and put \`iwsdkDev()\` in the config's top-level \`plugins\` array.`);
21173
- }
21174
- if (existingViteConfig != null &&
21175
- viteConfig.status !== 'already-configured') {
21176
- manualSteps.push(`If the app renders UIKitML panels, also dedupe \`three\` and the \`@pmndrs/uikit*\` packages in ${existingViteConfig} (\`resolve.dedupe\`, \`optimizeDeps.include\`), as the IWSDK starter's Vite config does.`);
21177
- }
21462
+ viteConfig = { file: existingViteConfig, status };
21463
+ }
21464
+ // Where the plugin belongs: the config Vite loads, once it loads as ESM.
21465
+ const pluginConfig = existingViteConfig != null && commonJsViteConfig
21466
+ ? esmConfigName(existingViteConfig)
21467
+ : existingViteConfig;
21468
+ if (existingViteConfig != null && viteConfig.status === 'manual') {
21469
+ const ignored = viteConfigs.slice(1);
21470
+ // A rename onto a config that exists would overwrite it.
21471
+ const esmNameTaken = (name) => viteConfigs.includes(esmConfigName(name));
21472
+ // tsc compiles vite.config.ts to .js (.mts to .mjs, .cts to .cjs), and
21473
+ // its next run replaces an edit to the output.
21474
+ const compiledFrom = ignored.find((name) => name === existingViteConfig.replace(/js$/u, 'ts'));
21475
+ manualSteps.push([
21476
+ ignored.length > 0 &&
21477
+ `Vite loads ${existingViteConfig} and ignores ${ignored.join(', ')}, so Create edited none of them.`,
21478
+ commonJsViteConfig &&
21479
+ `Vite loads ${existingViteConfig} as CommonJS and the IWSDK plugin is ESM-only: ${esmNameTaken(existingViteConfig)
21480
+ ? `merge it into ${pluginConfig} (which already exists) and delete ${existingViteConfig}, then update`
21481
+ : `rename it to ${pluginConfig} (ES module syntax) and update`} what refers to ${existingViteConfig}, such as \`include\` in tsconfig.node.json or \`--config ${existingViteConfig}\` in package.json scripts.`,
21482
+ !pluginFound &&
21483
+ `Add the IWSDK plugin to ${pluginConfig}: \`import { iwsdkDev } from '@iwsdk/vite-plugin-dev'\` and put \`iwsdkDev()\` in the config's top-level \`plugins\` array.`,
21484
+ compiledFrom != null &&
21485
+ `If ${existingViteConfig} is compiled from ${compiledFrom}, delete it and ${
21486
+ // The source loads as CommonJS too, so it needs the ESM name.
21487
+ commonJsViteConfig
21488
+ ? `make those changes to ${compiledFrom} instead, ${esmNameTaken(compiledFrom)
21489
+ ? `merging it into ${esmConfigName(compiledFrom)} (which already exists)`
21490
+ : `renaming it to ${esmConfigName(compiledFrom)}`}`
21491
+ : `add the plugin to ${compiledFrom} instead`}.`,
21492
+ ]
21493
+ .filter(Boolean)
21494
+ .join(' '));
21495
+ }
21496
+ if (existingViteConfig != null && !pluginFound) {
21497
+ manualSteps.push(`If the app renders UIKitML panels, also dedupe \`three\` and the \`@pmndrs/uikit*\` packages in ${pluginConfig} (\`resolve.dedupe\`, \`optimizeDeps.include\`), as the IWSDK starter's Vite config does.`);
21498
+ }
21499
+ const plannedManifestFile = files.find((file) => file.path === 'iwsdk.config.json');
21500
+ const plannedNative = plannedManifestFile
21501
+ ? JSON.parse(textContents(plannedManifestFile)).native
21502
+ : undefined;
21503
+ const gitignoreEntries = plannedNative === undefined
21504
+ ? GITIGNORE_ENTRIES
21505
+ : [...GITIGNORE_ENTRIES, NATIVE_GITIGNORE_ENTRY];
21178
21506
  const gitignoreAdded = [];
21179
21507
  if ((await writeTarget(outDir, '.gitignore')) !== 'blocked') {
21180
21508
  const gitignorePath = path$5.join(outDir, '.gitignore');
@@ -21182,7 +21510,7 @@ async function adoptExistingProject({ outDir, files, guidanceRoot, language, })
21182
21510
  ? await fsp.readFile(gitignorePath, 'utf8')
21183
21511
  : '';
21184
21512
  const present = new Set(current.split(/\r?\n/u).map((line) => line.trim()));
21185
- gitignoreAdded.push(...GITIGNORE_ENTRIES.filter((line) => !present.has(line)));
21513
+ gitignoreAdded.push(...gitignoreEntries.filter((line) => !present.has(line)));
21186
21514
  if (gitignoreAdded.length > 0) {
21187
21515
  const eol = current.includes('\r\n') ? '\r\n' : '\n';
21188
21516
  await fsp.writeFile(gitignorePath, `${current}${current && !/\r?\n$/u.test(current) ? eol : ''}${current ? eol : ''}# IWSDK${eol}${gitignoreAdded.join(eol)}${eol}`);
@@ -21206,6 +21534,36 @@ async function adoptExistingProject({ outDir, files, guidanceRoot, language, })
21206
21534
  manualSteps.push(`Load IWSDK from your app: add \`import '${importSpec}';\` to ${entryFile}, or add \`<script type="module" src="/${entry}"></script>\` to index.html. It calls World.create, which adds the 3D canvas.`);
21207
21535
  }
21208
21536
  }
21537
+ // The manifest written now or kept from an earlier run, which may have
21538
+ // turned locomotion on (1.2.0-rc.0 did) over the same empty scene.
21539
+ const manifest = await readJson(path$5.join(outDir, 'iwsdk.config.json'));
21540
+ const world = isRecord$1(manifest) && isRecord$1(manifest.world) ? manifest.world : {};
21541
+ const locomotion = isRecord$1(world.features)
21542
+ ? world.features.locomotion
21543
+ : undefined;
21544
+ if (locomotion && isRecord$1(manifest) && typeof manifest.scene === 'string') {
21545
+ const sceneFile = path$5.resolve(outDir, manifest.scene);
21546
+ const scene = await readJson(sceneFile);
21547
+ if (scene != null && !hasLocomotionEnvironment(scene)) {
21548
+ manualSteps.push(`Locomotion is on in iwsdk.config.json, but ${path$5.relative(outDir, sceneFile).split(path$5.sep).join('/')} has no \`LocomotionEnvironment\`: add it to the floor the player walks on, or set \`world.features.locomotion\` to \`false\`. Otherwise the player falls through the world.`);
21549
+ }
21550
+ }
21551
+ // --metavr-native over a project that already has iwsdk.config.json: the
21552
+ // manifest is kept, so build:metavr would stop at "no native section".
21553
+ if (plannedNative !== undefined &&
21554
+ isRecord$1(manifest) &&
21555
+ manifest.native === undefined) {
21556
+ manualSteps.push(`Add the native build target to iwsdk.config.json (your file was kept): \`"native": ${JSON.stringify(plannedNative)}\`. Replace the com.example package id before a store build. Until then \`npm run build:metavr\` stops at "no native section".`);
21557
+ }
21558
+ const locomotionOff = created.includes('iwsdk.config.json') &&
21559
+ created.some((file) => file.endsWith('.iwsdk.scene.json')) &&
21560
+ !locomotion &&
21561
+ (world.xr === false || (isRecord$1(world.xr) && world.xr.mode === 'vr'))
21562
+ ? {
21563
+ target: world.xr === false ? 'browser' : 'vr',
21564
+ requested: locomotionOffRequested,
21565
+ }
21566
+ : null;
21209
21567
  if (merge.report.keptScripts.includes('dev')) {
21210
21568
  manualSteps.push(`Your \`dev\` script was kept. Start the IWSDK-managed runtime with \`${runScriptCommand(packageManager, 'iwsdk:dev')}\` or \`npx @iwsdk/cli dev up\`.`);
21211
21569
  }
@@ -21226,6 +21584,7 @@ async function adoptExistingProject({ outDir, files, guidanceRoot, language, })
21226
21584
  packageJson: merge.report,
21227
21585
  overrides,
21228
21586
  viteConfig,
21587
+ locomotionOff,
21229
21588
  gitignoreAdded,
21230
21589
  guidance,
21231
21590
  manualSteps,
@@ -21261,8 +21620,16 @@ function printAdoptReport(report, outcome) {
21261
21620
  created: `created ${report.viteConfig.file}`,
21262
21621
  patched: `added iwsdkDev() to ${report.viteConfig.file}`,
21263
21622
  'already-configured': `${report.viteConfig.file} already uses iwsdkDev()`,
21264
- manual: `could not edit ${report.viteConfig.file} safely`,
21623
+ manual: `left ${report.viteConfig.file} unchanged; see "To finish"`,
21265
21624
  }[report.viteConfig.status]}`);
21625
+ if (report.locomotionOff) {
21626
+ const { target, requested } = report.locomotionOff;
21627
+ lines.push(` Locomotion: ${requested
21628
+ ? 'off'
21629
+ : 'left off, because the new scene has no floor to stand on'}. To turn it on, give your floor a \`LocomotionEnvironment\` component, then ${target === 'browser'
21630
+ ? 'set `world.features.locomotion` in iwsdk.config.json to `{ "browserControls": true }`: browser keyboard and gamepad controls are off by default.'
21631
+ : 'enable `world.features.locomotion` in iwsdk.config.json.'}`);
21632
+ }
21266
21633
  if (report.gitignoreAdded.length > 0) {
21267
21634
  lines.push(` .gitignore: added ${report.gitignoreAdded.join(', ')}`);
21268
21635
  }
@@ -22133,7 +22500,7 @@ crossSpawn.exports._enoent = enoent;
22133
22500
  * LICENSE file in the root directory of this source tree.
22134
22501
  */
22135
22502
  const BASE_OVERRIDES = {
22136
- sharp: '0.35.4',
22503
+ sharp: '0.35.5',
22137
22504
  three: 'npm:super-three@0.185.0',
22138
22505
  };
22139
22506
  const ONLY_BUILT_DEPENDENCIES = ['esbuild', 'protobufjs', 'sharp'];
@@ -22332,7 +22699,7 @@ function printMetavrNotice() {
22332
22699
  console.log(`\n metavr collects essential usage data, as described in the Meta Platform Technologies SDK License (${MPT_SDK_LICENSE_URL}). If you don't want to use metavr, uninstall it from your project:`);
22333
22700
  console.log(stdoutColor.gray(' npm uninstall @meta-quest/metavr'));
22334
22701
  }
22335
- function printNextSteps(appName, installed, actionItems = [], inPlace = false, xrEnabled = true) {
22702
+ function printNextSteps(appName, installed, actionItems = [], inPlace = false, xrEnabled = true, nativeAlpha = false) {
22336
22703
  const startCmd = 'npm run dev';
22337
22704
  printMetavrNotice();
22338
22705
  console.log('\nNext steps:');
@@ -22362,6 +22729,12 @@ function printNextSteps(appName, installed, actionItems = [], inPlace = false, x
22362
22729
  if (xrEnabled) {
22363
22730
  console.log(stdoutColor.gray(` IWER controls: ${IWER_CONTROLS_URL}`));
22364
22731
  }
22732
+ if (nativeAlpha) {
22733
+ console.log('\nNative Quest build (alpha):');
22734
+ console.log(stdoutColor.gray(' npx iwer-native doctor # adb, headset, native config'));
22735
+ console.log(stdoutColor.gray(' npm run build:metavr # writes dist-metavr/<appName>.apk'));
22736
+ console.log(stdoutColor.gray(' npx iwer-native install && npx iwer-native run'));
22737
+ }
22365
22738
  }
22366
22739
  function printPrerequisites(prereqs = []) {
22367
22740
  if (!prereqs.length) {
@@ -22399,6 +22772,75 @@ function printPrerequisites(prereqs = []) {
22399
22772
  }
22400
22773
  }
22401
22774
 
22775
+ /**
22776
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
22777
+ *
22778
+ * This source code is licensed under the MIT license found in the
22779
+ * LICENSE file in the root directory of this source tree.
22780
+ */
22781
+ /**
22782
+ * Alpha: `--metavr-native` (or IWSDK_CREATE_METAVR_NATIVE=1) adds the native
22783
+ * Quest build to a new VR or AR project. `npm run build:metavr` builds with Vite in
22784
+ * the `metavr` mode (the dev plugin then leaves the IWER emulator out) and packs
22785
+ * dist/ into dist-metavr/<appName>.apk with @iwer/native, which runs the app
22786
+ * without a browser. Off by default while @iwer/native is an alpha.
22787
+ */
22788
+ const NATIVE_ALPHA_FLAG = '--metavr-native';
22789
+ const NATIVE_ALPHA_ENV = 'IWSDK_CREATE_METAVR_NATIVE';
22790
+ /** Pinned exactly: experimental releases may change commands and config keys. */
22791
+ const IWER_NATIVE_ALPHA_VERSION = '2.9.0';
22792
+ const BUILD_METAVR_SCRIPT = 'vite build --mode metavr && iwer-native pack';
22793
+ const NATIVE_ALPHA_GITIGNORE = '\n# Native Quest builds (npm run build:metavr)\ndist-metavr/\n';
22794
+ function nativeAlphaRequested(args, env = process.env) {
22795
+ return (args.includes(NATIVE_ALPHA_FLAG) ||
22796
+ env[NATIVE_ALPHA_ENV] === '1' ||
22797
+ env[NATIVE_ALPHA_ENV] === 'true');
22798
+ }
22799
+ /**
22800
+ * The native runtime runs immersive sessions only: immersive-vr, and
22801
+ * immersive-ar over passthrough, which pack declares from world.xr.mode "ar".
22802
+ * It has no 2D page, so the Desktop 3D starting point cannot be packed.
22803
+ */
22804
+ function validateNativeAlphaTarget(target) {
22805
+ if (target !== 'vr' && target !== 'ar') {
22806
+ throw new Error(`${NATIVE_ALPHA_FLAG} is available for --target vr or ar only (the @iwer/native alpha runs immersive sessions, with no 2D page; got ${target}).`);
22807
+ }
22808
+ }
22809
+ // aapt2 rejects package segments that are Java keywords or literals.
22810
+ const JAVA_KEYWORDS = new Set('abstract assert boolean break byte case catch char class const continue default do double else enum extends final finally float for goto if implements import instanceof int interface long native new package private protected public return short static strictfp super switch synchronized this throw throws transient try void volatile while true false null _'.split(' '));
22811
+ /** Android application id from the project name: com.example.<name>, which the packer flags as a placeholder. */
22812
+ function nativePackageId(appName) {
22813
+ let segment = appName
22814
+ .replace(/^@[^/]+\//, '')
22815
+ .toLowerCase()
22816
+ .replace(/[^a-z0-9_]+/g, '_')
22817
+ .replace(/^_+|_+$/g, '');
22818
+ if (!/^[a-z]/.test(segment)) {
22819
+ segment = `app${segment ? `_${segment}` : ''}`;
22820
+ }
22821
+ if (JAVA_KEYWORDS.has(segment)) {
22822
+ segment = `${segment}_app`;
22823
+ }
22824
+ return `com.example.${segment}`;
22825
+ }
22826
+ /**
22827
+ * Origins the starter fetches from at run time. The native runtime refuses
22828
+ * every origin outside native.network.allow; the starter loads its controller
22829
+ * models from the WebXR input profiles on jsDelivr (@iwsdk/xr-input
22830
+ * DEFAULT_PROFILES_PATH), so without this entry controllers have no model.
22831
+ */
22832
+ const NATIVE_ALPHA_NETWORK_ALLOW = [
22833
+ 'https://cdn.jsdelivr.net',
22834
+ ];
22835
+ /** The `native` section of iwsdk.config.json (validated by @iwer/native). */
22836
+ function createNativeTargetSection(appName) {
22837
+ return {
22838
+ packageId: nativePackageId(appName),
22839
+ appName: appName.replace(/^@[^/]+\//, ''),
22840
+ network: { allow: [...NATIVE_ALPHA_NETWORK_ALLOW] },
22841
+ };
22842
+ }
22843
+
22402
22844
  /**
22403
22845
  * Copyright (c) Meta Platforms, Inc. and affiliates.
22404
22846
  *
@@ -22469,7 +22911,7 @@ function createProjectManifest(configuration) {
22469
22911
  };
22470
22912
  }
22471
22913
 
22472
- const VERSION = "1.2.0-rc.0";
22914
+ const VERSION = "1.2.0-rc.2";
22473
22915
  const NODE_ENGINE = ">=20.19.0 <21.0.0-0 || >=22.12.0 <23.0.0-0 || >=24.0.0";
22474
22916
 
22475
22917
  /**
@@ -22490,14 +22932,24 @@ async function buildStarterProjectFiles({ appName, configuration, language, pack
22490
22932
  path: 'public/scenes/main.iwsdk.scene.json',
22491
22933
  contents: await readFile$1(sceneSource),
22492
22934
  });
22935
+ const manifest = createProjectManifest(configuration);
22936
+ if (configuration.nativeAlpha) {
22937
+ manifest.native = createNativeTargetSection(appName);
22938
+ }
22493
22939
  files.push({
22494
22940
  path: 'iwsdk.config.json',
22495
- contents: `${JSON.stringify(createProjectManifest(configuration), null, 2)}\n`,
22941
+ contents: `${JSON.stringify(manifest, null, 2)}\n`,
22496
22942
  });
22497
22943
  files.push({
22498
22944
  path: 'package.json',
22499
- contents: `${JSON.stringify(createProjectPackageJson(appName, language, packageSource), null, 2)}\n`,
22945
+ contents: `${JSON.stringify(createProjectPackageJson(appName, language, packageSource, configuration.nativeAlpha === true), null, 2)}\n`,
22500
22946
  });
22947
+ if (configuration.nativeAlpha) {
22948
+ const gitignore = files.find((file) => file.path === '.gitignore');
22949
+ if (gitignore != null && typeof gitignore.contents === 'string') {
22950
+ gitignore.contents = `${gitignore.contents.trimEnd()}\n${NATIVE_ALPHA_GITIGNORE}`;
22951
+ }
22952
+ }
22501
22953
  files.push({
22502
22954
  path: 'pnpm-workspace.yaml',
22503
22955
  contents: createPnpmWorkspaceYaml(),
@@ -22508,7 +22960,7 @@ async function buildStarterProjectFiles({ appName, configuration, language, pack
22508
22960
  }
22509
22961
  return files.sort((left, right) => left.path.localeCompare(right.path));
22510
22962
  }
22511
- function createProjectPackageJson(appName, language, source) {
22963
+ function createProjectPackageJson(appName, language, source, nativeAlpha = false) {
22512
22964
  const packageSpec = (name) => source.getPackageInstallSpec(name) ?? VERSION;
22513
22965
  return {
22514
22966
  name: appName,
@@ -22523,6 +22975,7 @@ function createProjectPackageJson(appName, language, source) {
22523
22975
  'reference:status': 'iwsdk reference status',
22524
22976
  ...(language === 'ts' ? { typecheck: 'tsc --noEmit' } : {}),
22525
22977
  build: 'vite build',
22978
+ ...(nativeAlpha ? { 'build:metavr': BUILD_METAVR_SCRIPT } : {}),
22526
22979
  preview: 'vite preview',
22527
22980
  },
22528
22981
  dependencies: {
@@ -22538,6 +22991,7 @@ function createProjectPackageJson(appName, language, source) {
22538
22991
  '@iwsdk/reference': packageSpec('@iwsdk/reference'),
22539
22992
  '@iwsdk/cli': packageSpec('@iwsdk/cli'),
22540
22993
  '@iwsdk/vite-plugin-dev': packageSpec('@iwsdk/vite-plugin-dev'),
22994
+ ...(nativeAlpha ? { '@iwer/native': IWER_NATIVE_ALPHA_VERSION } : {}),
22541
22995
  '@meta-quest/metavr': '^1.8.1',
22542
22996
  ...(language === 'ts'
22543
22997
  ? { '@types/three': '^0.185.0', typescript: '^5.5.0' }
@@ -22545,7 +22999,7 @@ function createProjectPackageJson(appName, language, source) {
22545
22999
  vite: '^7.1.4',
22546
23000
  },
22547
23001
  overrides: {
22548
- sharp: '0.35.4',
23002
+ sharp: '0.35.5',
22549
23003
  three: 'npm:super-three@0.185.0',
22550
23004
  },
22551
23005
  engines: {
@@ -22647,6 +23101,11 @@ function targetHasContent(target) {
22647
23101
  }
22648
23102
  return fs$2.readdirSync(target.outDir).length > 0;
22649
23103
  }
23104
+ /** A target with a package.json: Create adds IWSDK to it, never over it. */
23105
+ function isExistingProject(target) {
23106
+ return (targetHasContent(target) &&
23107
+ fs$2.existsSync(path$5.join(target.outDir, 'package.json')));
23108
+ }
22650
23109
  function toPackageName(value) {
22651
23110
  const normalized = value
22652
23111
  .trim()
@@ -28997,6 +29456,7 @@ async function promptFlow(nameArg, defaults = {}) {
28997
29456
  let gitInit = true;
28998
29457
  let installNow = true;
28999
29458
  let configuration = getRecommendedConfiguration(target);
29459
+ const overrides = {};
29000
29460
  if (setup === 'advanced') {
29001
29461
  const languageAnswer = await prompts$1({
29002
29462
  type: 'select',
@@ -29010,17 +29470,22 @@ async function promptFlow(nameArg, defaults = {}) {
29010
29470
  }, { onCancel });
29011
29471
  assertNotCancelled();
29012
29472
  language = languageAnswer.language || 'ts';
29013
- const overrides = {};
29473
+ // An existing project gets an empty scene with nothing to stand on, so
29474
+ // locomotion starts off there.
29475
+ const adopting = defaults.isExistingProject?.(name) ?? false;
29014
29476
  for (const key of ADVANCED_FEATURE_KEYS) {
29015
29477
  const definition = FEATURE_CATALOG[key];
29016
29478
  if (!definition.targets.includes(target)) {
29017
29479
  continue;
29018
29480
  }
29481
+ const needsFloor = adopting && key === 'locomotionEnabled';
29019
29482
  const answer = await prompts$1({
29020
29483
  type: 'toggle',
29021
29484
  name: 'enabled',
29022
- message: `${definition.label}: ${definition.description}`,
29023
- initial: !!configuration.featureFlags[key],
29485
+ message: `${definition.label}: ${definition.description}${needsFloor
29486
+ ? ' Needs a floor with LocomotionEnvironment, which the new scene does not have yet.'
29487
+ : ''}`,
29488
+ initial: needsFloor ? false : !!configuration.featureFlags[key],
29024
29489
  active: 'Yes',
29025
29490
  inactive: 'No',
29026
29491
  }, { onCancel });
@@ -29058,6 +29523,7 @@ async function promptFlow(nameArg, defaults = {}) {
29058
29523
  mode: configuration.mode,
29059
29524
  language,
29060
29525
  featureFlags: configuration.featureFlags,
29526
+ featureOverrides: overrides,
29061
29527
  gitInit,
29062
29528
  xrFeatureStates: configuration.xrFeatureStates,
29063
29529
  actionItems: [],
@@ -29577,6 +30043,7 @@ IWSDK Create CLI v${VERSION}\nNode ${process.version}`;
29577
30043
  .option('--no-scene-understanding', 'Disable scene understanding')
29578
30044
  .option('--environment-raycast', 'Enable environment raycast (AR mode)')
29579
30045
  .option('--no-environment-raycast', 'Disable environment raycast')
30046
+ .option(NATIVE_ALPHA_FLAG, '(alpha) Add npm run build:metavr: a native Quest APK built with @iwer/native (VR or AR)')
29580
30047
  .option('--skip-reference-warmup', 'No effect; kept for older scripts (@iwsdk/reference bundles its corpus)')
29581
30048
  .action((n, opts) => {
29582
30049
  nameArg = n;
@@ -29659,12 +30126,17 @@ IWSDK Create CLI v${VERSION}\nNode ${process.version}`;
29659
30126
  mode: configuration.mode,
29660
30127
  language,
29661
30128
  featureFlags: configuration.featureFlags,
30129
+ featureOverrides: overrides,
29662
30130
  gitInit: resolveBooleanFlag(process.argv, '--git', '--no-git') ?? true,
29663
30131
  xrFeatureStates: configuration.xrFeatureStates,
29664
30132
  };
29665
30133
  }
29666
30134
  else {
29667
- res = await promptFlow(nameArg, { target: explicitTarget });
30135
+ res = await promptFlow(nameArg, {
30136
+ target: explicitTarget,
30137
+ isExistingProject: (name) => isValidProjectTarget(name) &&
30138
+ isExistingProject(resolveProjectTarget(name, process.cwd())),
30139
+ });
29668
30140
  }
29669
30141
  // Validate the requested directory (both interactive and non-interactive paths).
29670
30142
  if (!isValidProjectTarget(res.name)) {
@@ -29675,8 +30147,7 @@ IWSDK Create CLI v${VERSION}\nNode ${process.version}`;
29675
30147
  const hasTargetContent = targetHasContent(projectTarget);
29676
30148
  // An existing package.json means an existing project: adopt IWSDK into it
29677
30149
  // without overwriting anything, even when --force is passed.
29678
- const adopting = hasTargetContent &&
29679
- fs$2.existsSync(join(projectTarget.outDir, 'package.json'));
30150
+ const adopting = isExistingProject(projectTarget);
29680
30151
  if (adopting && cliOpts.canary) {
29681
30152
  throw new Error('--canary installs an SDK bundle into new projects only. Drop --canary to add IWSDK to this existing project.');
29682
30153
  }
@@ -29700,7 +30171,25 @@ IWSDK Create CLI v${VERSION}\nNode ${process.version}`;
29700
30171
  ? 'ts'
29701
30172
  : 'js';
29702
30173
  }
30174
+ if (adopting &&
30175
+ res.featureFlags.locomotionEnabled &&
30176
+ res.featureOverrides?.locomotionEnabled == null) {
30177
+ // The recommended locomotion assumes the starter's floor. An adopted
30178
+ // project gets an empty scene with nothing to stand on, so the player
30179
+ // would fall forever; locomotion stays opt-in there.
30180
+ Object.assign(res, getRecommendedConfiguration(res.target, {
30181
+ ...res.featureFlags,
30182
+ locomotionEnabled: false,
30183
+ }));
30184
+ }
30185
+ const nativeAlpha = nativeAlphaRequested(process.argv.slice(2));
30186
+ if (nativeAlpha) {
30187
+ validateNativeAlphaTarget(res.target);
30188
+ }
29703
30189
  printConfigurationSummary(res, adopting);
30190
+ if (nativeAlpha) {
30191
+ console.log(` Native Quest build: npm run build:metavr (alpha, @iwer/native)`);
30192
+ }
29704
30193
  const source = resolveSource(cliOpts.canary);
29705
30194
  // Prepare source (downloads tgz files for remote bundles)
29706
30195
  if (source.isBundleMode) {
@@ -29733,6 +30222,7 @@ IWSDK Create CLI v${VERSION}\nNode ${process.version}`;
29733
30222
  mode: res.mode,
29734
30223
  featureFlags: res.featureFlags,
29735
30224
  xrFeatureStates: res.xrFeatureStates,
30225
+ nativeAlpha,
29736
30226
  };
29737
30227
  const outDir = projectTarget.outDir;
29738
30228
  const projectFiles = await buildStarterProjectFiles({
@@ -29744,6 +30234,7 @@ IWSDK Create CLI v${VERSION}\nNode ${process.version}`;
29744
30234
  if (adopting) {
29745
30235
  await adoptProject(outDir, projectFiles, res.language, {
29746
30236
  install: res.installNow,
30237
+ locomotionOffRequested: res.featureOverrides?.locomotionEnabled === false,
29747
30238
  });
29748
30239
  return;
29749
30240
  }
@@ -29806,7 +30297,7 @@ IWSDK Create CLI v${VERSION}\nNode ${process.version}`;
29806
30297
  const prereqs = [...(res.prerequisites || [])];
29807
30298
  // Print prerequisites first, then next steps
29808
30299
  printPrerequisites(prereqs);
29809
- printNextSteps(projectTarget.displayPath, res.installNow, res.actionItems || [], projectTarget.inPlace, res.xrEnabled);
30300
+ printNextSteps(projectTarget.displayPath, res.installNow, res.actionItems || [], projectTarget.inPlace, res.xrEnabled, nativeAlpha);
29810
30301
  }
29811
30302
  finally {
29812
30303
  await source.cleanup();
@@ -29839,6 +30330,7 @@ async function adoptProject(outDir, files, language, options) {
29839
30330
  files,
29840
30331
  guidanceRoot: resolvePackagedGuidanceRoot(),
29841
30332
  language,
30333
+ locomotionOffRequested: options.locomotionOffRequested,
29842
30334
  });
29843
30335
  const outcome = { installed: false, adaptersSynced: false };
29844
30336
  if (options.install) {