create-threenative 0.2.4 → 0.2.6

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 (58) hide show
  1. package/README.md +23 -1
  2. package/agent-docs/references/assertion-reference.md +40 -1
  3. package/agent-docs/references/capability-reference.md +972 -66
  4. package/agent-docs/references/finding-assets.md +8 -1
  5. package/agent-docs/references/performance-basics.md +114 -0
  6. package/agent-docs/references/rigging-characters.md +51 -0
  7. package/agent-docs/references/webview-ui.md +3 -2
  8. package/agent-files/.agents/skills/ponytail/SKILL.md +68 -0
  9. package/agent-files/.agents/skills/threenative-assets/SKILL.md +8 -0
  10. package/agent-files/.agents/skills/threenative-context/SKILL.md +8 -0
  11. package/agent-files/.agents/skills/threenative-performance/SKILL.md +26 -10
  12. package/agent-files/.claude/hooks/ponytail-context.mjs +51 -0
  13. package/agent-files/.claude/settings.json +38 -0
  14. package/agent-files/.claude/skills/ponytail/SKILL.md +68 -0
  15. package/agent-files/.claude/skills/threenative-assets/SKILL.md +8 -0
  16. package/agent-files/.claude/skills/threenative-context/SKILL.md +8 -0
  17. package/agent-files/.claude/skills/threenative-performance/SKILL.md +26 -10
  18. package/agent-files/.codex/hooks.json +40 -0
  19. package/capabilities.json +1344 -88
  20. package/dist/index.d.ts +10 -1
  21. package/dist/index.js +186 -1
  22. package/dist/threenative.js +660 -150
  23. package/package.json +6 -6
  24. package/template-assets/patches/three@0.185.1.patch +179 -19
  25. package/templates/action-rpg/AGENTS.md +5 -5
  26. package/templates/action-rpg/CLAUDE.md +5 -5
  27. package/templates/action-rpg/package.json +8 -8
  28. package/templates/defense/AGENTS.md +5 -5
  29. package/templates/defense/CLAUDE.md +5 -5
  30. package/templates/defense/package.json +8 -8
  31. package/templates/minimal/AGENTS.md +5 -5
  32. package/templates/minimal/CLAUDE.md +5 -5
  33. package/templates/minimal/package.json +7 -7
  34. package/templates/minimal/threenative.config.ts +1 -0
  35. package/templates/platformer/AGENTS.md +5 -5
  36. package/templates/platformer/CLAUDE.md +5 -5
  37. package/templates/platformer/package.json +9 -9
  38. package/templates/puzzle/AGENTS.md +5 -5
  39. package/templates/puzzle/CLAUDE.md +5 -5
  40. package/templates/puzzle/package.json +8 -8
  41. package/templates/racing/AGENTS.md +5 -5
  42. package/templates/racing/CLAUDE.md +5 -5
  43. package/templates/racing/package.json +8 -8
  44. package/templates/runner/AGENTS.md +5 -5
  45. package/templates/runner/CLAUDE.md +5 -5
  46. package/templates/runner/package.json +8 -8
  47. package/templates/sailing/AGENTS.md +6 -6
  48. package/templates/sailing/CLAUDE.md +6 -6
  49. package/templates/sailing/package.json +8 -8
  50. package/templates/shooter/AGENTS.md +5 -5
  51. package/templates/shooter/CLAUDE.md +5 -5
  52. package/templates/shooter/package.json +8 -8
  53. package/templates/starter/AGENTS.md +8 -8
  54. package/templates/starter/CLAUDE.md +8 -8
  55. package/templates/starter/package.json +9 -9
  56. package/templates/starter/playtests/production-readiness.playtest.json +96 -0
  57. package/templates/starter/src/ui/Hud.tsx +2 -2
  58. package/templates/starter/src/ui/Menu.tsx +5 -1
@@ -2,15 +2,72 @@
2
2
  import { createRequire } from 'node:module';
3
3
  import { spawnSync, execFileSync, spawn } from 'child_process';
4
4
  import { randomUUID, createHash } from 'crypto';
5
- import { readFile, readdir, stat, mkdir, writeFile, rm, rename, access, unlink } from 'fs/promises';
5
+ import { existsSync, realpathSync, readFileSync, statSync, openSync, readSync, closeSync, accessSync, constants } from 'fs';
6
+ import { readFile, readdir, writeFile, stat, mkdir, rm, rename, access, unlink } from 'fs/promises';
6
7
  import { createRequire as createRequire$1 } from 'module';
7
- import path2 from 'path';
8
+ import path3 from 'path';
8
9
  import { compileAssets, parsePng, parseAudioConfig } from '@threenative/assets';
10
+ import { brotliCompressSync, constants as constants$1, gzipSync } from 'zlib';
9
11
  import { pathToFileURL, fileURLToPath } from 'url';
10
- import { existsSync, realpathSync, readFileSync, statSync, openSync, readSync, closeSync, accessSync, constants } from 'fs';
11
12
  import { platform, homedir } from 'os';
12
13
 
13
14
  createRequire(import.meta.url);
15
+ var COMPRESSIBLE_EXTENSIONS = /* @__PURE__ */ new Set([".css", ".html", ".js", ".json", ".mjs", ".wasm"]);
16
+ var MIN_BYTES = 1024;
17
+ async function walk(directory, files) {
18
+ for (const entry of await readdir(directory, { withFileTypes: true })) {
19
+ const file = path3.join(directory, entry.name);
20
+ if (entry.isDirectory()) await walk(file, files);
21
+ else if (entry.isFile()) files.push(file);
22
+ }
23
+ }
24
+ function brotli(data) {
25
+ return brotliCompressSync(data, {
26
+ params: { [constants$1.BROTLI_PARAM_QUALITY]: constants$1.BROTLI_MAX_QUALITY }
27
+ });
28
+ }
29
+ function gzip(data) {
30
+ return gzipSync(data, { level: constants$1.Z_BEST_COMPRESSION });
31
+ }
32
+ async function writeCompressionSidecars(outputDirectory) {
33
+ const files = [];
34
+ if (!existsSync(outputDirectory)) {
35
+ process.stdout.write(`web compression skipped: no build output at ${outputDirectory}
36
+ `);
37
+ return void 0;
38
+ }
39
+ await walk(outputDirectory, files);
40
+ for (const file of files) {
41
+ if (!COMPRESSIBLE_EXTENSIONS.has(path3.extname(file).toLowerCase())) continue;
42
+ try {
43
+ const data = await readFile(file);
44
+ if (data.byteLength <= MIN_BYTES) continue;
45
+ await writeFile(`${file}.br`, brotli(data));
46
+ await writeFile(`${file}.gz`, gzip(data));
47
+ } catch (error) {
48
+ throw new Error(
49
+ `TN_WEB_COMPRESSION_FAILED: ${path3.relative(outputDirectory, file)}: ${error.message}`
50
+ );
51
+ }
52
+ }
53
+ return mainEntryReport(outputDirectory, files);
54
+ }
55
+ async function mainEntryReport(outputDirectory, files) {
56
+ const html = files.find((file) => path3.basename(file) === "index.html");
57
+ if (html === void 0) return void 0;
58
+ const match = /<script[^>]+src="([^"]+\.m?js)"/u.exec(await readFile(html, "utf8"));
59
+ const source = match?.[1];
60
+ if (source === void 0) return void 0;
61
+ const entry = path3.join(outputDirectory, source.replace(/^\//u, ""));
62
+ const raw = (await stat(entry)).size;
63
+ if (raw <= MIN_BYTES) return void 0;
64
+ return {
65
+ brotli: (await stat(`${entry}.br`)).size,
66
+ entry: path3.relative(outputDirectory, entry),
67
+ gzip: (await stat(`${entry}.gz`)).size,
68
+ raw
69
+ };
70
+ }
14
71
  var ORIENTATIONS = ["landscape", "portrait", "sensor"];
15
72
  var CONFIG_FILE = "threenative.config.ts";
16
73
  var ConfigFailure = class extends Error {
@@ -85,13 +142,13 @@ function defaultAppId(name) {
85
142
  return `com.threenative.${segment}`;
86
143
  }
87
144
  function projectRequire(cwd) {
88
- return createRequire$1(path2.join(cwd, "package.json"));
145
+ return createRequire$1(path3.join(cwd, "package.json"));
89
146
  }
90
147
  function configLoaderSearch(cwd) {
91
148
  return [
92
- path2.join(cwd, "node_modules", "vite"),
93
- path2.join(cwd, "node_modules", "esbuild"),
94
- path2.resolve(path2.dirname(fileURLToPath(import.meta.url)), "..", "node_modules", "esbuild")
149
+ path3.join(cwd, "node_modules", "vite"),
150
+ path3.join(cwd, "node_modules", "esbuild"),
151
+ path3.resolve(path3.dirname(fileURLToPath(import.meta.url)), "..", "node_modules", "esbuild")
95
152
  ];
96
153
  }
97
154
  var CONFIG_BUILD_COMMAND = "pnpm exec threenative build --target web";
@@ -99,7 +156,7 @@ function configContext(cwd, layer, sources, searched, fix) {
99
156
  return { cwd, fix, layer, searched, sources };
100
157
  }
101
158
  function packageContext(cwd) {
102
- const packagePath = path2.join(cwd, "package.json");
159
+ const packagePath = path3.join(cwd, "package.json");
103
160
  return configContext(
104
161
  cwd,
105
162
  "package manifest",
@@ -122,8 +179,8 @@ function validationContext(cwd, sources) {
122
179
  cwd,
123
180
  "config validation",
124
181
  sources,
125
- [path2.join(cwd, "package.json"), path2.join(cwd, CONFIG_FILE)],
126
- `fix '${path2.join(cwd, CONFIG_FILE)}' and rerun ${CONFIG_BUILD_COMMAND}`
182
+ [path3.join(cwd, "package.json"), path3.join(cwd, CONFIG_FILE)],
183
+ `fix '${path3.join(cwd, CONFIG_FILE)}' and rerun ${CONFIG_BUILD_COMMAND}`
127
184
  );
128
185
  }
129
186
  function configFailure(code, context, detail) {
@@ -163,7 +220,7 @@ function resolveEsbuild(cwd) {
163
220
  }
164
221
  }
165
222
  async function importConfig(cwd) {
166
- const sourcePath = path2.join(cwd, CONFIG_FILE);
223
+ const sourcePath = path3.join(cwd, CONFIG_FILE);
167
224
  try {
168
225
  await access(sourcePath);
169
226
  } catch {
@@ -224,7 +281,7 @@ async function importConfig(cwd) {
224
281
  error instanceof Error ? error.message : String(error)
225
282
  );
226
283
  }
227
- const compiledPath = path2.join(cwd, `.threenative.config.${process.pid}.${Date.now()}.mjs`);
284
+ const compiledPath = path3.join(cwd, `.threenative.config.${process.pid}.${Date.now()}.mjs`);
228
285
  try {
229
286
  await writeFile(compiledPath, code, "utf8");
230
287
  } catch (error) {
@@ -260,7 +317,7 @@ async function importConfig(cwd) {
260
317
  async function readManifest(cwd) {
261
318
  let parsed;
262
319
  try {
263
- parsed = JSON.parse(await readFile(path2.join(cwd, "package.json"), "utf8"));
320
+ parsed = JSON.parse(await readFile(path3.join(cwd, "package.json"), "utf8"));
264
321
  } catch (error) {
265
322
  fail("TN_CONFIG_PACKAGE_INVALID", error instanceof Error ? error.message : String(error));
266
323
  }
@@ -279,12 +336,12 @@ function packageNativeEntry(manifest) {
279
336
  }
280
337
  function validateNativeEntry(value, cwd) {
281
338
  const entry = nonEmptyString(value, "TN_NATIVE_ENTRY_MISSING", "nativeEntry");
282
- if (path2.isAbsolute(entry)) {
339
+ if (path3.isAbsolute(entry)) {
283
340
  fail("TN_CONFIG_NATIVE_ENTRY_INVALID", "nativeEntry must be project-relative.");
284
341
  }
285
- const resolved = path2.resolve(cwd, entry);
286
- const relative = path2.relative(cwd, resolved);
287
- if (relative === ".." || relative.startsWith(`..${path2.sep}`) || path2.isAbsolute(relative)) {
342
+ const resolved = path3.resolve(cwd, entry);
343
+ const relative = path3.relative(cwd, resolved);
344
+ if (relative === ".." || relative.startsWith(`..${path3.sep}`) || path3.isAbsolute(relative)) {
288
345
  fail("TN_CONFIG_NATIVE_ENTRY_INVALID", "nativeEntry must stay inside the project.");
289
346
  }
290
347
  return entry;
@@ -328,18 +385,18 @@ async function validateApp(raw, name, cwd) {
328
385
  }
329
386
  async function validateProjectAsset(raw, cwd, label, options) {
330
387
  const relative = nonEmptyString(raw, `${options.codePrefix}_INVALID`, label);
331
- if (path2.isAbsolute(relative)) {
388
+ if (path3.isAbsolute(relative)) {
332
389
  fail(`${options.codePrefix}_PATH_INVALID`, `${label} must be project-relative: ${relative}`);
333
390
  }
334
- const resolved = path2.resolve(cwd, relative);
335
- const withinProject = path2.relative(cwd, resolved);
336
- if (withinProject === ".." || withinProject.startsWith(`..${path2.sep}`) || path2.isAbsolute(withinProject)) {
391
+ const resolved = path3.resolve(cwd, relative);
392
+ const withinProject = path3.relative(cwd, resolved);
393
+ if (withinProject === ".." || withinProject.startsWith(`..${path3.sep}`) || path3.isAbsolute(withinProject)) {
337
394
  fail(
338
395
  `${options.codePrefix}_PATH_INVALID`,
339
396
  `${label} must stay inside the project: ${relative}`
340
397
  );
341
398
  }
342
- const extension = path2.extname(relative).slice(1).toLowerCase();
399
+ const extension = path3.extname(relative).slice(1).toLowerCase();
343
400
  if (!options.formats.includes(extension)) {
344
401
  fail(
345
402
  options.codePrefix === "TN_CONFIG_ICON" ? `${options.codePrefix}_INVALID` : `${options.codePrefix}_FORMAT_INVALID`,
@@ -563,7 +620,7 @@ var UI_RENDERERS = ["native", "web"];
563
620
  function validateUi(raw) {
564
621
  const ui = assertRecord(raw, "ui");
565
622
  assertKeys(ui, "ui", ["renderer"]);
566
- const renderer = ui.renderer === void 0 ? "native" : ui.renderer;
623
+ const renderer = ui.renderer === void 0 ? "web" : ui.renderer;
567
624
  if (typeof renderer !== "string" || !UI_RENDERERS.includes(renderer)) {
568
625
  fail("TN_CONFIG_UI_RENDERER_INVALID", "ui.renderer must be web or native.");
569
626
  }
@@ -576,6 +633,9 @@ function validateRenderer(raw) {
576
633
  "resolutionScale",
577
634
  "antialias",
578
635
  "alphaAntialiasing",
636
+ "projection",
637
+ "minimumProjectedPixels",
638
+ "matrixWorld",
579
639
  "android"
580
640
  ]);
581
641
  const android = assertRecord(renderer.android, "renderer.android");
@@ -604,6 +664,15 @@ function validateRenderer(raw) {
604
664
  android.alphaAntialiasing,
605
665
  "renderer.android.alphaAntialiasing"
606
666
  );
667
+ const projection = booleanOrUndefined(renderer.projection, "renderer.projection");
668
+ const minimumProjectedPixels = numberOrFalse(
669
+ renderer.minimumProjectedPixels,
670
+ "renderer.minimumProjectedPixels"
671
+ );
672
+ const matrixWorld = renderer.matrixWorld;
673
+ if (matrixWorld !== void 0 && matrixWorld !== "visible" && matrixWorld !== "all") {
674
+ fail("TN_CONFIG_RENDERER_INVALID", 'renderer.matrixWorld must be "visible" or "all".');
675
+ }
607
676
  const androidOverrides = {
608
677
  ...androidResolutionScale === void 0 ? {} : { resolutionScale: androidResolutionScale },
609
678
  ...androidAntialias === void 0 ? {} : { antialias: androidAntialias },
@@ -618,6 +687,9 @@ function validateRenderer(raw) {
618
687
  ),
619
688
  ...antialias === void 0 ? {} : { antialias },
620
689
  ...alphaAntialiasing === void 0 ? {} : { alphaAntialiasing },
690
+ ...projection === void 0 ? {} : { projection },
691
+ ...minimumProjectedPixels === void 0 ? {} : { minimumProjectedPixels },
692
+ ...matrixWorld === void 0 ? {} : { matrixWorld },
621
693
  ...resolutionScale === void 0 ? {} : { resolutionScale },
622
694
  ...Object.keys(androidOverrides).length === 0 ? {} : { android: androidOverrides }
623
695
  };
@@ -627,6 +699,13 @@ function booleanOrUndefined(value, name) {
627
699
  if (typeof value !== "boolean") fail("TN_CONFIG_RENDERER_INVALID", `${name} must be a boolean.`);
628
700
  return value;
629
701
  }
702
+ function numberOrFalse(value, name) {
703
+ if (value === void 0 || value === false) return value;
704
+ if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
705
+ fail("TN_CONFIG_RENDERER_INVALID", `${name} must be false or a positive finite number.`);
706
+ }
707
+ return value;
708
+ }
630
709
  var ASSET_TARGET_KEYS = [
631
710
  "maxMaterials",
632
711
  "maxTriangles",
@@ -845,6 +924,156 @@ function validateModels(raw) {
845
924
  ...virtual === void 0 ? {} : { virtual }
846
925
  };
847
926
  }
927
+ var LOD_PRESETS = ["aggressive", "balanced", "quality"];
928
+ var LOD_MIN_TRIANGLES_SCOPES = ["primitive", "asset"];
929
+ var LOD_KEYS = ["enabled", "generation", "overrides", "preset", "runtime"];
930
+ var LOD_GENERATION_KEYS = [
931
+ "errorTargets",
932
+ "join",
933
+ "maxLevels",
934
+ "minSaving",
935
+ "minTriangles",
936
+ "minTrianglesScope"
937
+ ];
938
+ var LOD_RUNTIME_KEYS = ["hysteresis", "maxPixelError"];
939
+ var LOD_OVERRIDE_KEYS = ["enabled", "generation", "preset", "runtime"];
940
+ function lodGeneration(raw, label) {
941
+ const value = assertRecord(raw, label);
942
+ assertKeys(value, label, LOD_GENERATION_KEYS);
943
+ const generation = {};
944
+ if (value.join !== void 0) {
945
+ if (typeof value.join !== "boolean") {
946
+ fail("TN_CONFIG_ASSETS_INVALID", `${label}.join must be a boolean.`);
947
+ }
948
+ generation.join = value.join;
949
+ }
950
+ if (value.maxLevels !== void 0) {
951
+ if (!Number.isSafeInteger(value.maxLevels) || value.maxLevels < 1 || value.maxLevels > 8) {
952
+ fail("TN_CONFIG_ASSETS_INVALID", `${label}.maxLevels must be an integer between 1 and 8.`);
953
+ }
954
+ generation.maxLevels = value.maxLevels;
955
+ }
956
+ if (value.minTriangles !== void 0) {
957
+ generation.minTriangles = positiveInteger(
958
+ value.minTriangles,
959
+ 1,
960
+ "TN_CONFIG_ASSETS_INVALID",
961
+ `${label}.minTriangles`
962
+ );
963
+ }
964
+ if (value.minTrianglesScope !== void 0) {
965
+ if (typeof value.minTrianglesScope !== "string" || !LOD_MIN_TRIANGLES_SCOPES.includes(value.minTrianglesScope)) {
966
+ fail(
967
+ "TN_CONFIG_ASSETS_INVALID",
968
+ `${label}.minTrianglesScope must be one of ${LOD_MIN_TRIANGLES_SCOPES.join(", ")}.`
969
+ );
970
+ }
971
+ generation.minTrianglesScope = value.minTrianglesScope;
972
+ }
973
+ if (value.minSaving !== void 0) {
974
+ if (typeof value.minSaving !== "number" || !Number.isFinite(value.minSaving) || value.minSaving < 0 || value.minSaving >= 1) {
975
+ fail("TN_CONFIG_ASSETS_INVALID", `${label}.minSaving must be a finite number in [0, 1).`);
976
+ }
977
+ generation.minSaving = value.minSaving;
978
+ }
979
+ if (value.errorTargets !== void 0) {
980
+ const targets = value.errorTargets;
981
+ if (!Array.isArray(targets) || targets.length === 0 || targets.length > 16) {
982
+ fail(
983
+ "TN_CONFIG_ASSETS_INVALID",
984
+ `${label}.errorTargets must be 1 to 16 geometric-error targets.`
985
+ );
986
+ }
987
+ let previous = -1;
988
+ for (const target of targets) {
989
+ if (typeof target !== "number" || !Number.isFinite(target) || target <= 0) {
990
+ fail("TN_CONFIG_ASSETS_INVALID", `${label}.errorTargets must be positive finite numbers.`);
991
+ }
992
+ if (target <= previous) {
993
+ fail("TN_CONFIG_ASSETS_INVALID", `${label}.errorTargets must increase strictly.`);
994
+ }
995
+ previous = target;
996
+ }
997
+ generation.errorTargets = [...targets];
998
+ }
999
+ return generation;
1000
+ }
1001
+ function lodRuntime(raw, label) {
1002
+ const value = assertRecord(raw, label);
1003
+ assertKeys(value, label, LOD_RUNTIME_KEYS);
1004
+ const runtime = {};
1005
+ if (value.maxPixelError !== void 0) {
1006
+ if (typeof value.maxPixelError !== "number" || !Number.isFinite(value.maxPixelError) || value.maxPixelError <= 0) {
1007
+ fail("TN_CONFIG_ASSETS_INVALID", `${label}.maxPixelError must be a positive finite number.`);
1008
+ }
1009
+ runtime.maxPixelError = value.maxPixelError;
1010
+ }
1011
+ if (value.hysteresis !== void 0) {
1012
+ if (typeof value.hysteresis !== "number" || !Number.isFinite(value.hysteresis) || value.hysteresis < 0 || value.hysteresis >= 0.5) {
1013
+ fail("TN_CONFIG_ASSETS_INVALID", `${label}.hysteresis must be a finite number in [0, 0.5).`);
1014
+ }
1015
+ runtime.hysteresis = value.hysteresis;
1016
+ }
1017
+ return runtime;
1018
+ }
1019
+ function lodPreset(raw, label) {
1020
+ if (typeof raw !== "string" || !LOD_PRESETS.includes(raw)) {
1021
+ fail("TN_CONFIG_ASSETS_INVALID", `${label} must be one of ${LOD_PRESETS.join(", ")}.`);
1022
+ }
1023
+ return raw;
1024
+ }
1025
+ function lodOverride(raw, label) {
1026
+ if (typeof raw === "boolean") return raw;
1027
+ const value = assertRecord(raw, label);
1028
+ assertKeys(value, label, LOD_OVERRIDE_KEYS);
1029
+ return {
1030
+ ...value.enabled === void 0 ? {} : {
1031
+ enabled: booleanValue(
1032
+ value.enabled,
1033
+ true,
1034
+ "TN_CONFIG_ASSETS_INVALID",
1035
+ `${label}.enabled`
1036
+ )
1037
+ },
1038
+ ...value.generation === void 0 ? {} : { generation: lodGeneration(value.generation, `${label}.generation`) },
1039
+ ...value.preset === void 0 ? {} : { preset: lodPreset(value.preset, `${label}.preset`) },
1040
+ ...value.runtime === void 0 ? {} : { runtime: lodRuntime(value.runtime, `${label}.runtime`) }
1041
+ };
1042
+ }
1043
+ function validateLod(raw) {
1044
+ if (typeof raw === "boolean") return raw;
1045
+ const value = assertRecord(raw, "assets.lod");
1046
+ assertKeys(value, "assets.lod", LOD_KEYS);
1047
+ const overrides = {};
1048
+ if (value.overrides !== void 0) {
1049
+ if (!isRecord(value.overrides)) {
1050
+ fail("TN_CONFIG_ASSETS_INVALID", "assets.lod.overrides must be an object.");
1051
+ }
1052
+ for (const [key, entry] of Object.entries(value.overrides)) {
1053
+ if (key.trim() === "") {
1054
+ fail(
1055
+ "TN_CONFIG_ASSETS_INVALID",
1056
+ "assets.lod.overrides keys must be non-empty source asset paths."
1057
+ );
1058
+ }
1059
+ overrides[key] = lodOverride(entry, `assets.lod.overrides['${key}']`);
1060
+ }
1061
+ }
1062
+ return {
1063
+ ...value.enabled === void 0 ? {} : {
1064
+ enabled: booleanValue(
1065
+ value.enabled,
1066
+ true,
1067
+ "TN_CONFIG_ASSETS_INVALID",
1068
+ "assets.lod.enabled"
1069
+ )
1070
+ },
1071
+ ...value.generation === void 0 ? {} : { generation: lodGeneration(value.generation, "assets.lod.generation") },
1072
+ ...Object.keys(overrides).length === 0 ? {} : { overrides },
1073
+ ...value.preset === void 0 ? {} : { preset: lodPreset(value.preset, "assets.lod.preset") },
1074
+ ...value.runtime === void 0 ? {} : { runtime: lodRuntime(value.runtime, "assets.lod.runtime") }
1075
+ };
1076
+ }
848
1077
  function validateBudget(raw) {
849
1078
  const limit = (value) => value === "none" || typeof value === "number" && Number.isSafeInteger(value) && value > 0;
850
1079
  if (limit(raw)) return raw;
@@ -873,6 +1102,7 @@ function validateAssets(raw) {
873
1102
  "budget",
874
1103
  "exclude",
875
1104
  "concurrency",
1105
+ "lod",
876
1106
  "models",
877
1107
  "source",
878
1108
  "output",
@@ -880,6 +1110,7 @@ function validateAssets(raw) {
880
1110
  "textures"
881
1111
  ]);
882
1112
  const targets = assets.targets === void 0 ? void 0 : validateAssetTargets(assets.targets);
1113
+ const lod = assets.lod === void 0 ? void 0 : validateLod(assets.lod);
883
1114
  const models = assets.models === void 0 ? void 0 : validateModels(assets.models);
884
1115
  const textures = assets.textures === void 0 ? void 0 : validateTextures(assets.textures);
885
1116
  if (assets.exclude !== void 0 && (!Array.isArray(assets.exclude) || assets.exclude.some((glob) => typeof glob !== "string" || glob.trim() === ""))) {
@@ -903,13 +1134,14 @@ function validateAssets(raw) {
903
1134
  ...assets.source === void 0 ? {} : { source: nonEmptyString(assets.source, "TN_CONFIG_ASSETS_INVALID", "assets.source") },
904
1135
  ...assets.output === void 0 ? {} : { output: nonEmptyString(assets.output, "TN_CONFIG_ASSETS_INVALID", "assets.output") },
905
1136
  ...targets === void 0 ? {} : { targets },
1137
+ ...lod === void 0 ? {} : { lod },
906
1138
  ...models === void 0 ? {} : { models },
907
1139
  ...textures === void 0 ? {} : { textures }
908
1140
  };
909
1141
  }
910
1142
  async function loadConfigInternal(root) {
911
- const packagePath = path2.join(root, "package.json");
912
- const sourcePath = path2.join(root, CONFIG_FILE);
1143
+ const packagePath = path3.join(root, "package.json");
1144
+ const sourcePath = path3.join(root, CONFIG_FILE);
913
1145
  const manifest = await withConfigContext(
914
1146
  packageContext(root),
915
1147
  "TN_CONFIG_PACKAGE_INVALID",
@@ -967,9 +1199,9 @@ async function loadConfigInternal(root) {
967
1199
  );
968
1200
  }
969
1201
  async function loadConfig(cwd) {
970
- const root = path2.resolve(cwd);
1202
+ const root = path3.resolve(cwd);
971
1203
  return withConfigContext(
972
- validationContext(root, [path2.join(root, CONFIG_FILE), path2.join(root, "package.json")]),
1204
+ validationContext(root, [path3.join(root, CONFIG_FILE), path3.join(root, "package.json")]),
973
1205
  "TN_CONFIG_VALIDATION_FAILED",
974
1206
  () => loadConfigInternal(root)
975
1207
  );
@@ -978,33 +1210,27 @@ async function loadConfig(cwd) {
978
1210
  // src/build.ts
979
1211
  var TARGETS = ["web", "desktop", "android", "ios"];
980
1212
  function projectRequire2(cwd) {
981
- return createRequire$1(path2.join(cwd, "package.json"));
1213
+ return createRequire$1(path3.join(cwd, "package.json"));
982
1214
  }
983
1215
  function packageRoot(cwd, packageName) {
984
1216
  try {
985
- return path2.dirname(projectRequire2(cwd).resolve(`${packageName}/package.json`));
1217
+ return path3.dirname(projectRequire2(cwd).resolve(`${packageName}/package.json`));
986
1218
  } catch {
987
- throw new Error(
988
- `Cannot build a native target because '${packageName}' is not installed in ${cwd}.`
989
- );
1219
+ throw new Error(`Cannot build because '${packageName}' is not installed in ${cwd}.`);
990
1220
  }
991
1221
  }
992
- function executable(cwd, name) {
993
- const suffix = process.platform === "win32" ? ".cmd" : "";
994
- return path2.join(cwd, "node_modules", ".bin", `${name}${suffix}`);
995
- }
996
1222
  async function run(command, args, cwd) {
997
1223
  await new Promise((resolve, reject) => {
998
1224
  const child = spawn(command, [...args], { cwd, stdio: "inherit" });
999
1225
  child.once("error", reject);
1000
1226
  child.once("exit", (code) => {
1001
1227
  if (code === 0) resolve();
1002
- else reject(new Error(`${path2.basename(command)} exited with code ${code ?? "unknown"}.`));
1228
+ else reject(new Error(`${path3.basename(command)} exited with code ${code ?? "unknown"}.`));
1003
1229
  });
1004
1230
  });
1005
1231
  }
1006
1232
  async function projectName(cwd) {
1007
- const manifest = JSON.parse(await readFile(path2.join(cwd, "package.json"), "utf8"));
1233
+ const manifest = JSON.parse(await readFile(path3.join(cwd, "package.json"), "utf8"));
1008
1234
  const name = manifest.name?.replace(/^@[^/]+\//u, "").replace(/[^a-zA-Z0-9._-]/gu, "-");
1009
1235
  if (name === void 0 || name.length === 0) throw new Error("package.json must name the game.");
1010
1236
  return name;
@@ -1033,7 +1259,9 @@ async function assertNativeBundleCompatible(bundle, target) {
1033
1259
  }
1034
1260
  function assertNativeUiRendererCompatible(target, renderer, platform2 = process.platform) {
1035
1261
  if (renderer === "native" || target === "android" || target === "ios") return;
1036
- if (target === "desktop" && platform2 === "linux") return;
1262
+ if (target === "desktop" && (platform2 === "linux" || platform2 === "darwin" || platform2 === "win32")) {
1263
+ return;
1264
+ }
1037
1265
  const platformName = platform2 === "darwin" ? "macOS" : platform2 === "win32" ? "Windows" : platform2;
1038
1266
  throw new Error(
1039
1267
  `TN_UI_RENDERER_UNSUPPORTED: ui.renderer is "web", but ${target} has no WebView host on ${platformName}. Set ui.renderer to "native" for ${target}.`
@@ -1051,8 +1279,8 @@ function namedAssets(logicalPaths) {
1051
1279
  }
1052
1280
  async function assertNativeAssetsCompatible(cwd, target, config) {
1053
1281
  if (target === "desktop" || target === "web") return;
1054
- const outputRoot = path2.resolve(cwd, config.assets?.output ?? "public");
1055
- const manifestPath = path2.join(outputRoot, "assets.manifest.json");
1282
+ const outputRoot = path3.resolve(cwd, config.assets?.output ?? "public");
1283
+ const manifestPath = path3.join(outputRoot, "assets.manifest.json");
1056
1284
  let raw;
1057
1285
  try {
1058
1286
  raw = await readFile(manifestPath, "utf8");
@@ -1091,11 +1319,11 @@ async function assertNativeAssetsCompatible(cwd, target, config) {
1091
1319
  );
1092
1320
  }
1093
1321
  }
1094
- var UI_ENTRY = path2.join("src", "ui", "main.tsx");
1322
+ var UI_ENTRY = path3.join("src", "ui", "main.tsx");
1095
1323
  var UI_PAGE_PREFIX = ".threenative-ui-";
1096
1324
  async function buildUi(cwd, config) {
1097
- const output = path2.join(cwd, ".threenative", "build", "ui");
1098
- const entry = path2.join(cwd, UI_ENTRY);
1325
+ const output = path3.join(cwd, ".threenative", "build", "ui");
1326
+ const entry = path3.join(cwd, UI_ENTRY);
1099
1327
  try {
1100
1328
  if (!(await stat(entry)).isFile()) throw new Error("not a file");
1101
1329
  } catch {
@@ -1103,9 +1331,9 @@ async function buildUi(cwd, config) {
1103
1331
  `TN_UI_ENTRY_MISSING: ui.renderer is "${config.ui.renderer}" but ${UI_ENTRY} does not exist. It is the entry every platform's web view loads; create it, or set ui.renderer to "native".`
1104
1332
  );
1105
1333
  }
1106
- const buildRoot = path2.join(cwd, ".threenative", "build");
1334
+ const buildRoot = path3.join(cwd, ".threenative", "build");
1107
1335
  await mkdir(buildRoot, { recursive: true });
1108
- const page = path2.join(cwd, `${UI_PAGE_PREFIX}${randomUUID()}.html`);
1336
+ const page = path3.join(cwd, `${UI_PAGE_PREFIX}${randomUUID()}.html`);
1109
1337
  await writeFile(
1110
1338
  page,
1111
1339
  [
@@ -1118,20 +1346,20 @@ async function buildUi(cwd, config) {
1118
1346
  " </head>",
1119
1347
  " <body>",
1120
1348
  ' <div id="tn-ui"></div>',
1121
- ` <script type="module" src="/${UI_ENTRY.split(path2.sep).join("/")}"></script>`,
1349
+ ` <script type="module" src="/${UI_ENTRY.split(path3.sep).join("/")}"></script>`,
1122
1350
  " </body>",
1123
1351
  "</html>"
1124
1352
  ].join("\n")
1125
1353
  );
1126
- const driver = path2.join(buildRoot, "build-ui.mjs");
1354
+ const driver = path3.join(buildRoot, "build-ui.mjs");
1127
1355
  await writeFile(driver, uiBuildDriver(cwd, page, output));
1128
1356
  try {
1129
1357
  await run(process.execPath, [driver], cwd);
1130
1358
  } finally {
1131
1359
  await rm(page, { force: true });
1132
1360
  }
1133
- const generatedPage = path2.join(output, path2.basename(page));
1134
- const index = path2.join(output, "index.html");
1361
+ const generatedPage = path3.join(output, path3.basename(page));
1362
+ const index = path3.join(output, "index.html");
1135
1363
  await rename(generatedPage, index);
1136
1364
  return output;
1137
1365
  }
@@ -1174,11 +1402,28 @@ function uiBuildDriver(cwd, page, output) {
1174
1402
  async function buildWeb(cwd, viteArgs = []) {
1175
1403
  const config = await loadConfig(cwd);
1176
1404
  await compileAssets({ config: config.assets, cwd, platform: "web" });
1177
- await run(executable(cwd, "vite"), ["build", ...viteArgs], cwd);
1405
+ await run(
1406
+ process.execPath,
1407
+ [path3.join(packageRoot(cwd, "vite"), "bin/vite.js"), "build", ...viteArgs],
1408
+ cwd
1409
+ );
1410
+ const report = await writeCompressionSidecars(path3.resolve(cwd, viteOutDir(viteArgs)));
1411
+ if (report !== void 0) {
1412
+ process.stdout.write(
1413
+ `web main chunk ${report.entry}: raw ${report.raw} B, gzip ${report.gzip} B, brotli ${report.brotli} B
1414
+ `
1415
+ );
1416
+ }
1417
+ }
1418
+ function viteOutDir(viteArgs) {
1419
+ const index = viteArgs.findIndex((arg) => arg === "--outDir" || arg.startsWith("--outDir="));
1420
+ if (index === -1) return "dist";
1421
+ const flag = viteArgs[index];
1422
+ return flag.startsWith("--outDir=") ? flag.slice("--outDir=".length) : viteArgs[index + 1] ?? "dist";
1178
1423
  }
1179
1424
  async function nativeEntry(cwd, config) {
1180
1425
  const relative = (config ?? await loadConfig(cwd)).nativeEntry;
1181
- const entry = path2.resolve(cwd, relative);
1426
+ const entry = path3.resolve(cwd, relative);
1182
1427
  try {
1183
1428
  if (!(await stat(entry)).isFile()) throw new Error("not a file");
1184
1429
  } catch {
@@ -1187,25 +1432,25 @@ async function nativeEntry(cwd, config) {
1187
1432
  return entry;
1188
1433
  }
1189
1434
  function resolvePackagingConfig(cwd, config) {
1190
- const resolve = (value) => value === void 0 ? void 0 : path2.resolve(cwd, value);
1435
+ const resolve = (value) => value === void 0 ? void 0 : path3.resolve(cwd, value);
1191
1436
  const artifact = {
1192
1437
  ...config,
1193
1438
  app: {
1194
1439
  ...config.app,
1195
- ...config.app.icon === void 0 ? {} : { icon: path2.resolve(cwd, config.app.icon) },
1440
+ ...config.app.icon === void 0 ? {} : { icon: path3.resolve(cwd, config.app.icon) },
1196
1441
  ...config.app.icons === void 0 ? {} : {
1197
1442
  icons: {
1198
1443
  ...config.app.icons.android === void 0 ? {} : {
1199
1444
  android: {
1200
- ...config.app.icons.android.foreground === void 0 ? {} : { foreground: path2.resolve(cwd, config.app.icons.android.foreground) },
1445
+ ...config.app.icons.android.foreground === void 0 ? {} : { foreground: path3.resolve(cwd, config.app.icons.android.foreground) },
1201
1446
  ...config.app.icons.android.background === void 0 ? {} : { background: config.app.icons.android.background },
1202
- ...config.app.icons.android.monochrome === void 0 ? {} : { monochrome: path2.resolve(cwd, config.app.icons.android.monochrome) }
1447
+ ...config.app.icons.android.monochrome === void 0 ? {} : { monochrome: path3.resolve(cwd, config.app.icons.android.monochrome) }
1203
1448
  }
1204
1449
  },
1205
1450
  ...config.app.icons.ios === void 0 ? {} : {
1206
1451
  ios: {
1207
- ...config.app.icons.ios.dark === void 0 ? {} : { dark: path2.resolve(cwd, config.app.icons.ios.dark) },
1208
- ...config.app.icons.ios.tinted === void 0 ? {} : { tinted: path2.resolve(cwd, config.app.icons.ios.tinted) }
1452
+ ...config.app.icons.ios.dark === void 0 ? {} : { dark: path3.resolve(cwd, config.app.icons.ios.dark) },
1453
+ ...config.app.icons.ios.tinted === void 0 ? {} : { tinted: path3.resolve(cwd, config.app.icons.ios.tinted) }
1209
1454
  }
1210
1455
  },
1211
1456
  ...config.app.icons.web === void 0 ? {} : {
@@ -1222,27 +1467,39 @@ function resolvePackagingConfig(cwd, config) {
1222
1467
  ...config.bootSplash === void 0 ? {} : {
1223
1468
  bootSplash: {
1224
1469
  ...config.bootSplash,
1225
- ...config.bootSplash.image === void 0 ? {} : { image: path2.resolve(cwd, config.bootSplash.image) }
1470
+ ...config.bootSplash.image === void 0 ? {} : { image: path3.resolve(cwd, config.bootSplash.image) }
1226
1471
  }
1227
1472
  }
1228
1473
  };
1229
1474
  return artifact;
1230
1475
  }
1231
1476
  async function writePackagingConfig(cwd, config) {
1232
- const directory = path2.join(cwd, ".threenative", "build");
1477
+ const directory = path3.join(cwd, ".threenative", "build");
1233
1478
  await mkdir(directory, { recursive: true });
1234
1479
  const artifact = resolvePackagingConfig(cwd, config);
1235
- const output = path2.join(directory, "config.json");
1480
+ const output = path3.join(directory, "config.json");
1236
1481
  await writeFile(output, `${JSON.stringify(artifact, null, 2)}
1237
1482
  `);
1238
1483
  return output;
1239
1484
  }
1240
- async function bundleNative(cwd, runtimeRoot, entry, target) {
1241
- const output = path2.join(cwd, ".threenative", "build", "game.js");
1485
+ function runtimeHasWebAssembly(binary = process.env.THREENATIVE_RUNTIME_BINARY, probe = spawnSync) {
1486
+ if (binary === void 0 || !existsSync(binary)) return true;
1487
+ let result;
1488
+ try {
1489
+ result = probe(binary, ["--version"], { encoding: "utf8" });
1490
+ } catch {
1491
+ return true;
1492
+ }
1493
+ if (result.status !== 0) return true;
1494
+ const engine = /\+ (\S+) build/u.exec(String(result.stdout ?? ""))?.[1] ?? "";
1495
+ return !/^(?:quickjs|jsc)$/iu.test(engine);
1496
+ }
1497
+ async function bundleNative(cwd, runtimeRoot, entry, target, nativeBackend) {
1498
+ const output = path3.join(cwd, ".threenative", "build", "game.js");
1242
1499
  await run(
1243
1500
  process.execPath,
1244
1501
  [
1245
- path2.join(runtimeRoot, "scripts", "bundle.mjs"),
1502
+ path3.join(runtimeRoot, "scripts", "bundle.mjs"),
1246
1503
  "--project",
1247
1504
  cwd,
1248
1505
  "--entry",
@@ -1250,31 +1507,38 @@ async function bundleNative(cwd, runtimeRoot, entry, target) {
1250
1507
  "--target",
1251
1508
  target,
1252
1509
  "--output",
1253
- output
1510
+ output,
1511
+ ...nativeBackend ? ["--native-backend"] : []
1254
1512
  ],
1255
1513
  cwd
1256
1514
  );
1257
1515
  return output;
1258
1516
  }
1259
- async function buildNative(target, cwd, allowSourceBuild = false) {
1517
+ async function buildNative(target, cwd, allowSourceBuild = false, mode = "debug", format = "apk") {
1260
1518
  const config = await loadConfig(cwd);
1261
1519
  assertNativeUiRendererCompatible(target, config.ui.renderer);
1262
- await compileAssets({ config: config.assets, cwd, platform: target });
1520
+ const webAssembly = runtimeHasWebAssembly();
1521
+ await compileAssets({
1522
+ config: config.assets,
1523
+ cwd,
1524
+ platform: target,
1525
+ ...webAssembly ? {} : { runtimeDecoders: { ktx2: false, meshopt: false } }
1526
+ });
1263
1527
  await assertNativeAssetsCompatible(cwd, target, config);
1264
1528
  const entry = await nativeEntry(cwd, config);
1265
1529
  const orientation = config.display.orientation;
1266
1530
  const configPath = await writePackagingConfig(cwd, config);
1267
1531
  const runtimeRoot = packageRoot(cwd, "@threenative/runtime-native");
1268
- const bundle = await bundleNative(cwd, runtimeRoot, entry, target);
1532
+ const bundle = await bundleNative(cwd, runtimeRoot, entry, target, !webAssembly);
1269
1533
  await assertNativeBundleCompatible(bundle, target);
1270
- const assets = path2.join(cwd, "public");
1534
+ const assets = path3.join(cwd, "public");
1271
1535
  const ui = config.ui.renderer === "web" ? await buildUi(cwd, config) : void 0;
1272
1536
  if (target === "ios") {
1273
- const output2 = path2.join(cwd, "dist-native", `${await projectName(cwd)}.app`);
1537
+ const output2 = path3.join(cwd, "dist-native", `${await projectName(cwd)}.app`);
1274
1538
  await run(
1275
1539
  process.execPath,
1276
1540
  [
1277
- path2.join(runtimeRoot, "scripts", "package-ios.mjs"),
1541
+ path3.join(runtimeRoot, "scripts", "package-ios.mjs"),
1278
1542
  "--bundle",
1279
1543
  bundle,
1280
1544
  "--assets",
@@ -1292,12 +1556,24 @@ async function buildNative(target, cwd, allowSourceBuild = false) {
1292
1556
  return;
1293
1557
  }
1294
1558
  if (target === "android") {
1295
- const output2 = path2.join(cwd, "dist-native", `${await projectName(cwd)}.apk`);
1559
+ const output2 = path3.join(
1560
+ cwd,
1561
+ "dist-native",
1562
+ `${await projectName(cwd)}.${format === "aab" ? "aab" : "apk"}`
1563
+ );
1296
1564
  await run(
1297
1565
  process.execPath,
1298
1566
  [
1299
- path2.join(runtimeRoot, "scripts", "package-android.mjs"),
1567
+ path3.join(runtimeRoot, "scripts", "package-android.mjs"),
1300
1568
  ...allowSourceBuild ? ["--allow-source-build"] : [],
1569
+ "--mode",
1570
+ mode,
1571
+ "--format",
1572
+ format,
1573
+ // The consumer project, so a relative keystore path in the signing environment resolves
1574
+ // against the game rather than the engine's Android project.
1575
+ "--project-root",
1576
+ cwd,
1301
1577
  "--bundle",
1302
1578
  bundle,
1303
1579
  "--assets",
@@ -1314,11 +1590,13 @@ async function buildNative(target, cwd, allowSourceBuild = false) {
1314
1590
  );
1315
1591
  return;
1316
1592
  }
1317
- const output = path2.join(cwd, "dist-native", await projectName(cwd));
1593
+ const output = path3.join(cwd, "dist-native", await projectName(cwd));
1318
1594
  await run(
1319
1595
  process.execPath,
1320
1596
  [
1321
- path2.join(runtimeRoot, "scripts", "package-desktop.mjs"),
1597
+ path3.join(runtimeRoot, "scripts", "package-desktop.mjs"),
1598
+ "--mode",
1599
+ mode,
1322
1600
  "--bundle",
1323
1601
  bundle,
1324
1602
  "--assets",
@@ -1326,7 +1604,7 @@ async function buildNative(target, cwd, allowSourceBuild = false) {
1326
1604
  ...ui === void 0 ? [] : ["--ui", ui],
1327
1605
  "--config",
1328
1606
  configPath,
1329
- ...process.env.THREENATIVE_RUNTIME_BINARY ? ["--runtime", path2.resolve(process.env.THREENATIVE_RUNTIME_BINARY)] : [],
1607
+ ...process.env.THREENATIVE_RUNTIME_BINARY ? ["--runtime", path3.resolve(process.env.THREENATIVE_RUNTIME_BINARY)] : [],
1330
1608
  "--output",
1331
1609
  output
1332
1610
  ],
@@ -1337,7 +1615,17 @@ async function build(options) {
1337
1615
  if (options.allowSourceBuild && options.target !== "android") {
1338
1616
  throw new Error("--allow-source-build is supported only for --target android.");
1339
1617
  }
1340
- const cwd = path2.resolve(options.cwd ?? process.cwd());
1618
+ if (options.mode !== void 0 && options.target !== "android" && options.target !== "desktop" || options.format !== void 0 && options.target !== "android") {
1619
+ throw new Error(
1620
+ "--mode is supported only for --target android or desktop; --format only for --target android."
1621
+ );
1622
+ }
1623
+ const mode = options.mode ?? "debug";
1624
+ const format = options.format ?? "apk";
1625
+ if (format === "aab" && mode !== "release") {
1626
+ throw new Error("--format aab requires --mode release.");
1627
+ }
1628
+ const cwd = path3.resolve(options.cwd ?? process.cwd());
1341
1629
  if (options.target === "web") await buildWeb(cwd, options.viteArgs);
1342
1630
  else {
1343
1631
  if ((options.viteArgs?.length ?? 0) > 0) {
@@ -1345,15 +1633,17 @@ async function build(options) {
1345
1633
  `${options.target} build does not accept ${options.viteArgs?.join(" ")}. iOS output is simulator-only; device signing remains OPEN.`
1346
1634
  );
1347
1635
  }
1348
- await buildNative(options.target, cwd, options.allowSourceBuild === true);
1636
+ await buildNative(options.target, cwd, options.allowSourceBuild === true, mode, format);
1349
1637
  }
1350
1638
  }
1351
1639
  function buildHelp() {
1352
1640
  return `${[
1353
- "Usage: threenative build [--target web|desktop|android|ios]",
1641
+ "Usage: threenative build [--target web|desktop|android|ios] [--mode debug|release] [--format apk|aab]",
1354
1642
  "",
1355
1643
  "Options:",
1356
1644
  " --target <target> Choose web, desktop, android, or ios (default: web).",
1645
+ " --mode <mode> debug (default) or release. Desktop release wraps the executable in one complete OS container.",
1646
+ " --format <format> Android only: apk (default) or aab. aab requires --mode release.",
1357
1647
  " --allow-source-build Explicitly allow Android maintainer source compilation.",
1358
1648
  " --help Show this help."
1359
1649
  ].join("\n")}
@@ -1372,12 +1662,36 @@ function parseBuildArgs(argv) {
1372
1662
  if (allowSourceBuild && value !== "android") {
1373
1663
  throw new Error("--allow-source-build is supported only for --target android.");
1374
1664
  }
1665
+ const mode = flagValue(argv, "--mode");
1666
+ if (mode !== void 0 && mode !== "debug" && mode !== "release") {
1667
+ throw new Error(`Unknown build mode '${mode}'. Choose debug or release.`);
1668
+ }
1669
+ const format = flagValue(argv, "--format");
1670
+ if (format !== void 0 && format !== "apk" && format !== "aab") {
1671
+ throw new Error(`Unknown build format '${format}'. Choose apk or aab.`);
1672
+ }
1673
+ if (mode !== void 0 && value !== "android" && value !== "desktop" || format !== void 0 && value !== "android") {
1674
+ throw new Error(
1675
+ "--mode is supported only for --target android or desktop; --format only for --target android."
1676
+ );
1677
+ }
1678
+ if (format === "aab" && (mode ?? "debug") !== "release") {
1679
+ throw new Error("--format aab requires --mode release.");
1680
+ }
1375
1681
  const consumed = /* @__PURE__ */ new Set([0]);
1376
1682
  if (allowSourceBuild) {
1377
1683
  for (let index = 1; index < argv.length; index += 1) {
1378
1684
  if (argv[index] === "--allow-source-build") consumed.add(index);
1379
1685
  }
1380
1686
  }
1687
+ for (const flag of ["--mode", "--format"]) {
1688
+ for (let index = 1; index < argv.length; index += 1) {
1689
+ if (argv[index] === flag) {
1690
+ consumed.add(index);
1691
+ consumed.add(index + 1);
1692
+ }
1693
+ }
1694
+ }
1381
1695
  if (targetIndex !== -1) {
1382
1696
  consumed.add(targetIndex);
1383
1697
  consumed.add(targetIndex + 1);
@@ -1385,9 +1699,18 @@ function parseBuildArgs(argv) {
1385
1699
  return {
1386
1700
  target: value,
1387
1701
  ...allowSourceBuild ? { allowSourceBuild: true } : {},
1702
+ ...mode === void 0 ? {} : { mode },
1703
+ ...format === void 0 ? {} : { format },
1388
1704
  viteArgs: argv.filter((_, index) => !consumed.has(index))
1389
1705
  };
1390
1706
  }
1707
+ function flagValue(argv, flag) {
1708
+ const index = argv.indexOf(flag);
1709
+ if (index === -1) return void 0;
1710
+ const value = argv[index + 1];
1711
+ if (value === void 0 || value.startsWith("--")) throw new Error(`${flag} requires a value.`);
1712
+ return value;
1713
+ }
1391
1714
 
1392
1715
  // src/commands.ts
1393
1716
  var threenativeCommands = ["build", "doctor"];
@@ -1424,13 +1747,13 @@ function binaryNames(platformName) {
1424
1747
  function pathCandidates(environment, platformName) {
1425
1748
  const raw = environment.PATH ?? environment.Path ?? "";
1426
1749
  if (raw.trim().length === 0) return [];
1427
- return raw.split(path2.delimiter).filter((directory) => directory.trim().length > 0).flatMap((directory) => binaryNames(platformName).map((name) => path2.join(directory, name)));
1750
+ return raw.split(path3.delimiter).filter((directory) => directory.trim().length > 0).flatMap((directory) => binaryNames(platformName).map((name) => path3.join(directory, name)));
1428
1751
  }
1429
1752
  function conventionalCandidates(platformName, home) {
1430
1753
  if (platformName === "darwin") {
1431
1754
  return [
1432
1755
  "/Applications/Blender.app/Contents/MacOS/Blender",
1433
- path2.join(home, "Applications/Blender.app/Contents/MacOS/Blender")
1756
+ path3.join(home, "Applications/Blender.app/Contents/MacOS/Blender")
1434
1757
  ];
1435
1758
  }
1436
1759
  if (platformName === "win32") {
@@ -1440,7 +1763,7 @@ function conventionalCandidates(platformName, home) {
1440
1763
  ];
1441
1764
  return roots.flatMap(
1442
1765
  (root) => ["5.2", "5.1", "5.0", "4.5", "4.2"].map(
1443
- (release) => path2.join(root, "Blender Foundation", `Blender ${release}`, "blender.exe")
1766
+ (release) => path3.join(root, "Blender Foundation", `Blender ${release}`, "blender.exe")
1444
1767
  )
1445
1768
  );
1446
1769
  }
@@ -1449,7 +1772,7 @@ function conventionalCandidates(platformName, home) {
1449
1772
  "/usr/local/bin/blender",
1450
1773
  "/snap/bin/blender",
1451
1774
  "/var/lib/flatpak/exports/bin/org.blender.Blender",
1452
- path2.join(home, ".local/bin/blender")
1775
+ path3.join(home, ".local/bin/blender")
1453
1776
  ];
1454
1777
  }
1455
1778
  function parseBlenderVersion(output) {
@@ -1482,7 +1805,7 @@ function resolveBlender(environment = process.env, options = {}) {
1482
1805
  const install = BLENDER_INSTALL_GUIDANCE;
1483
1806
  const override = environment.THREENATIVE_BLENDER_PATH;
1484
1807
  if (override !== void 0 && override.trim().length > 0) {
1485
- const candidate = path2.resolve(override.trim());
1808
+ const candidate = path3.resolve(override.trim());
1486
1809
  if (!executableFile(candidate)) {
1487
1810
  return {
1488
1811
  available: false,
@@ -1576,10 +1899,10 @@ var MCP_SERVERS = Object.freeze({
1576
1899
  })
1577
1900
  });
1578
1901
  var MCP_PACKAGES = Object.freeze({
1579
- assets: Object.freeze({ name: "threenative-asset-mcp", version: "0.8.0" }),
1902
+ assets: Object.freeze({ name: "threenative-asset-mcp", version: "0.9.1" }),
1580
1903
  sculpt: Object.freeze({ name: "threenative-sculpt-mcp", version: "0.1.1" }),
1581
- engine: Object.freeze({ name: "threenative-engine-mcp", version: "0.2.1" }),
1582
- blender: Object.freeze({ name: "threenative-blender-mcp", version: "0.1.1" })
1904
+ engine: Object.freeze({ name: "threenative-engine-mcp", version: "0.2.3" }),
1905
+ blender: Object.freeze({ name: "threenative-blender-mcp", version: "0.1.3" })
1583
1906
  });
1584
1907
  var SERVER_FORMATS = Object.freeze({
1585
1908
  // Claude Code (`.mcp.json`), Cursor and the Gemini CLI all read this one.
@@ -1699,9 +2022,29 @@ var DEFAULT_NATIVE_ENTRY = "src/game.ts";
1699
2022
  var RUNTIME_PACKAGE = "@threenative/runtime-native";
1700
2023
  var PLAYTEST_BINARY = "threenative-playtest";
1701
2024
  var ANDROID_JDK_MAJOR = 17;
1702
- var ANDROID_COMPILE_SDK = 35;
2025
+ var DEFAULT_ANDROID_COMPILE_SDK = 36;
2026
+ function androidGradleSdk(source) {
2027
+ if (source === void 0) return void 0;
2028
+ const target = /targetSdk\s*=\s*(\d+)/u.exec(source);
2029
+ const compile = /compileSdk\s*=\s*(\d+)/u.exec(source);
2030
+ const value = target?.[1] ?? compile?.[1];
2031
+ return value === void 0 ? void 0 : Number(value);
2032
+ }
2033
+ function requiredAndroidSdk(snapshot) {
2034
+ return androidGradleSdk(snapshot.readRuntimeText?.("android/app/build.gradle.kts")) ?? DEFAULT_ANDROID_COMPILE_SDK;
2035
+ }
2036
+ function requiredAndroidSdkFromRoot(root) {
2037
+ if (root === void 0) return DEFAULT_ANDROID_COMPILE_SDK;
2038
+ try {
2039
+ return androidGradleSdk(
2040
+ readFileSync(path3.join(root, "android", "app", "build.gradle.kts"), "utf8")
2041
+ ) ?? DEFAULT_ANDROID_COMPILE_SDK;
2042
+ } catch {
2043
+ return DEFAULT_ANDROID_COMPILE_SDK;
2044
+ }
2045
+ }
1703
2046
  var CORE_PACKAGE_NAME = "@threenative/core";
1704
- var CORE_PACKAGE_VERSION = "0.3.1";
2047
+ var CORE_PACKAGE_VERSION = "0.3.3";
1705
2048
  var CORE_RESOLVED_SERVERS = /* @__PURE__ */ new Set([
1706
2049
  "threenative-engine",
1707
2050
  "threenative-blender"
@@ -1762,26 +2105,60 @@ for (const host of MCP_HOSTS) {
1762
2105
  var SHAPE_VERIFIABLE_HOSTS = MCP_HOSTS.filter(
1763
2106
  ({ format }) => format === "mcpServers"
1764
2107
  );
2108
+ var X11_COMPOSITOR_PROBE = [
2109
+ "import ctypes, ctypes.util, sys",
2110
+ 'path = ctypes.util.find_library("X11")',
2111
+ "if not path:",
2112
+ " print('unknown'); sys.exit(0)",
2113
+ "x = ctypes.CDLL(path)",
2114
+ "x.XOpenDisplay.restype = ctypes.c_void_p",
2115
+ "x.XOpenDisplay.argtypes = [ctypes.c_char_p]",
2116
+ "display = x.XOpenDisplay(None)",
2117
+ "if not display:",
2118
+ " print('unknown'); sys.exit(0)",
2119
+ "x.XDefaultScreen.restype = ctypes.c_int",
2120
+ "x.XDefaultScreen.argtypes = [ctypes.c_void_p]",
2121
+ "screen = x.XDefaultScreen(display)",
2122
+ "x.XInternAtom.restype = ctypes.c_ulong",
2123
+ "x.XInternAtom.argtypes = [ctypes.c_void_p, ctypes.c_char_p, ctypes.c_int]",
2124
+ 'atom = x.XInternAtom(display, ("_NET_WM_CM_S%d" % screen).encode(), 0)',
2125
+ "x.XGetSelectionOwner.restype = ctypes.c_ulong",
2126
+ "x.XGetSelectionOwner.argtypes = [ctypes.c_void_p, ctypes.c_ulong]",
2127
+ "owner = x.XGetSelectionOwner(display, atom)",
2128
+ "x.XCloseDisplay.argtypes = [ctypes.c_void_p]",
2129
+ "x.XCloseDisplay(display)",
2130
+ "print('1' if owner else '0')"
2131
+ ].join("\n");
1765
2132
  function detectX11Compositor(environment = process.env) {
1766
2133
  if (environment.DISPLAY === void 0) return void 0;
1767
2134
  try {
1768
- const output = execFileSync("xprop", ["-root", "_NET_WM_CM_S0"], {
2135
+ const output = execFileSync("python3", ["-c", X11_COMPOSITOR_PROBE], {
1769
2136
  encoding: "utf8",
1770
2137
  env: { ...environment },
1771
2138
  stdio: ["ignore", "pipe", "pipe"]
1772
2139
  });
1773
- return /window id\s*#/u.test(output);
1774
- } catch (error) {
1775
- return error.code === "ENOENT" ? void 0 : false;
2140
+ const answer = output.trim();
2141
+ if (answer === "1") return true;
2142
+ if (answer === "0") return false;
2143
+ return void 0;
2144
+ } catch {
2145
+ return void 0;
1776
2146
  }
1777
2147
  }
1778
2148
  function probeDesktopOverlay(environment = process.env, compositor = detectX11Compositor) {
1779
2149
  const wayland = environment.WAYLAND_DISPLAY !== void 0 || environment.XDG_SESSION_TYPE === "wayland";
1780
2150
  if (wayland) {
2151
+ if (environment.DISPLAY === void 0) {
2152
+ return {
2153
+ detail: "a Wayland session without an X11 display (Xwayland) cannot host the desktop overlay",
2154
+ fix: "Enable Xwayland for this session or use the web UI target.",
2155
+ status: "fail"
2156
+ };
2157
+ }
1781
2158
  return {
1782
- detail: "the transparent container could not be created on this Wayland/Xwayland session",
1783
- fix: "Run the desktop target under an X11 session (for example SDL_VIDEODRIVER=x11) or use the web UI target.",
1784
- status: "fail"
2159
+ detail: "the runtime selects Xwayland (SDL x11, GDK_BACKEND=x11) and the Wayland compositor blends the overlay's alpha",
2160
+ fix: "",
2161
+ status: "ok"
1785
2162
  };
1786
2163
  }
1787
2164
  if (environment.DISPLAY === void 0) {
@@ -1802,13 +2179,13 @@ function probeDesktopOverlay(environment = process.env, compositor = detectX11Co
1802
2179
  if (present === false) {
1803
2180
  return {
1804
2181
  detail: "no compositing manager is running, so nothing would blend the overlay",
1805
- fix: "Start a compositing manager or run the desktop target under a composited X11 session.",
2182
+ fix: "Start a compositing manager (xcompmgr -n, picom or compton -- the three the repository's own private displays borrow) or run the desktop target under a composited X11 session.",
1806
2183
  status: "fail"
1807
2184
  };
1808
2185
  }
1809
2186
  return {
1810
2187
  detail: "the X11 compositor probe could not run, so overlay transparency is unknown",
1811
- fix: "Install xprop and rerun doctor in the desktop display session.",
2188
+ fix: "Install python3 and rerun doctor in the desktop display session.",
1812
2189
  status: "warn"
1813
2190
  };
1814
2191
  }
@@ -1838,11 +2215,11 @@ function nativeEntryCompat(value) {
1838
2215
  return typeof entry === "string" && entry.length > 0 ? { nativeEntry: entry } : void 0;
1839
2216
  }
1840
2217
  function resolvePackageDirectoryFrom(start, name) {
1841
- let directory = path2.resolve(start);
2218
+ let directory = path3.resolve(start);
1842
2219
  while (true) {
1843
- const candidate = path2.join(directory, "node_modules", name);
1844
- if (existsSync(path2.join(candidate, "package.json"))) return candidate;
1845
- const parent = path2.dirname(directory);
2220
+ const candidate = path3.join(directory, "node_modules", name);
2221
+ if (existsSync(path3.join(candidate, "package.json"))) return candidate;
2222
+ const parent = path3.dirname(directory);
1846
2223
  if (parent === directory) return void 0;
1847
2224
  directory = parent;
1848
2225
  }
@@ -1863,13 +2240,13 @@ function resolvePackageDirectory(snapshot, name) {
1863
2240
  }
1864
2241
  }
1865
2242
  function resolveBinaryFrom(start, name) {
1866
- let directory = path2.resolve(start);
2243
+ let directory = path3.resolve(start);
1867
2244
  while (true) {
1868
- const binDirectory = path2.join(directory, "node_modules", ".bin");
1869
- const candidates = process.platform === "win32" ? [path2.join(binDirectory, `${name}.cmd`), path2.join(binDirectory, name)] : [path2.join(binDirectory, name)];
2245
+ const binDirectory = path3.join(directory, "node_modules", ".bin");
2246
+ const candidates = process.platform === "win32" ? [path3.join(binDirectory, `${name}.cmd`), path3.join(binDirectory, name)] : [path3.join(binDirectory, name)];
1870
2247
  const found = candidates.find((candidate) => existsSync(candidate));
1871
2248
  if (found !== void 0) return found;
1872
- const parent = path2.dirname(directory);
2249
+ const parent = path3.dirname(directory);
1873
2250
  if (parent === directory) return void 0;
1874
2251
  directory = parent;
1875
2252
  }
@@ -1942,7 +2319,7 @@ function mcpServerCheck(snapshot, spec, value, file) {
1942
2319
  status: "fail"
1943
2320
  };
1944
2321
  }
1945
- if (snapshot.projectRoot !== void 0 && !existsSync(path2.resolve(snapshot.projectRoot, spec.expectedArgs))) {
2322
+ if (snapshot.projectRoot !== void 0 && !existsSync(path3.resolve(snapshot.projectRoot, spec.expectedArgs))) {
1946
2323
  return {
1947
2324
  detail: `${spec.configName} points at missing ${spec.expectedArgs}; @threenative/core is not providing the configured server shim`,
1948
2325
  fix: "Install @threenative/core again so the generated MCP server entry exists.",
@@ -1968,7 +2345,7 @@ function mcpServerCheck(snapshot, spec, value, file) {
1968
2345
  status: "warn"
1969
2346
  };
1970
2347
  }
1971
- const manifest = readJsonSync(path2.join(packageDirectory, "package.json"));
2348
+ const manifest = readJsonSync(path3.join(packageDirectory, "package.json"));
1972
2349
  const installedVersion = record(manifest)?.version;
1973
2350
  if (typeof installedVersion !== "string") {
1974
2351
  return {
@@ -1999,7 +2376,7 @@ function probeMcpServer(projectRoot, spec) {
1999
2376
  method: "initialize",
2000
2377
  params: {
2001
2378
  capabilities: {},
2002
- clientInfo: { name: "threenative-doctor", version: "0.3.1" },
2379
+ clientInfo: { name: "threenative-doctor", version: "0.3.3" },
2003
2380
  protocolVersion: "2025-06-18"
2004
2381
  }
2005
2382
  });
@@ -2129,10 +2506,10 @@ function configuredTargets(snapshot) {
2129
2506
  function directoryCanBeWritten(snapshot, relative) {
2130
2507
  if (snapshot.directoryWritable !== void 0) return snapshot.directoryWritable(relative);
2131
2508
  if (snapshot.projectRoot === void 0) return void 0;
2132
- const root = path2.resolve(snapshot.projectRoot);
2133
- let candidate = path2.resolve(root, relative);
2134
- if (candidate !== root && !candidate.startsWith(`${root}${path2.sep}`)) return false;
2135
- while (candidate !== root && !existsSync(candidate)) candidate = path2.dirname(candidate);
2509
+ const root = path3.resolve(snapshot.projectRoot);
2510
+ let candidate = path3.resolve(root, relative);
2511
+ if (candidate !== root && !candidate.startsWith(`${root}${path3.sep}`)) return false;
2512
+ while (candidate !== root && !existsSync(candidate)) candidate = path3.dirname(candidate);
2136
2513
  if (!existsSync(candidate)) return false;
2137
2514
  try {
2138
2515
  if (!statSync(candidate).isDirectory()) return false;
@@ -2185,7 +2562,7 @@ function assetPipelineCheck(snapshot) {
2185
2562
  status
2186
2563
  };
2187
2564
  }
2188
- function androidToolchainFacts(probe) {
2565
+ function androidToolchainFacts(probe, requiredSdk = DEFAULT_ANDROID_COMPILE_SDK) {
2189
2566
  const details = [];
2190
2567
  const blockers = [];
2191
2568
  let status = probe.status ?? "ok";
@@ -2203,20 +2580,20 @@ function androidToolchainFacts(probe) {
2203
2580
  details.push(`JDK ${probe.jdkVersion} found (supported JDK ${ANDROID_JDK_MAJOR})`);
2204
2581
  }
2205
2582
  if (probe.sdkVersion === void 0) {
2206
- const blocker = `Android SDK platform android-${ANDROID_COMPILE_SDK} not found`;
2583
+ const blocker = `Android SDK platform android-${requiredSdk} not found`;
2207
2584
  details.push(blocker);
2208
2585
  blockers.push(blocker);
2209
2586
  status = "warn";
2210
2587
  } else {
2211
- details.push(`Android SDK platform android-${ANDROID_COMPILE_SDK} ${probe.sdkVersion} found`);
2588
+ details.push(`Android SDK platform android-${requiredSdk} ${probe.sdkVersion} found`);
2212
2589
  }
2213
2590
  return { blockers, details, status };
2214
2591
  }
2215
- function androidToolchainStatus(probe) {
2216
- const { details, status } = androidToolchainFacts(probe);
2592
+ function androidToolchainStatus(probe, requiredSdk = DEFAULT_ANDROID_COMPILE_SDK) {
2593
+ const { details, status } = androidToolchainFacts(probe, requiredSdk);
2217
2594
  return {
2218
2595
  detail: details.join("; "),
2219
- fix: status === "ok" ? void 0 : `Install Android SDK platform android-${ANDROID_COMPILE_SDK} and JDK ${ANDROID_JDK_MAJOR}, or set ANDROID_HOME or ANDROID_SDK_ROOT and JAVA_HOME (or put JDK ${ANDROID_JDK_MAJOR} on PATH).`,
2596
+ fix: status === "ok" ? void 0 : `Install Android SDK platform android-${requiredSdk} and JDK ${ANDROID_JDK_MAJOR}, or set ANDROID_HOME or ANDROID_SDK_ROOT and JAVA_HOME (or put JDK ${ANDROID_JDK_MAJOR} on PATH).`,
2220
2597
  name: "android toolchain",
2221
2598
  status
2222
2599
  };
@@ -2266,6 +2643,53 @@ function executePlaytestDoctor(runner, projectRoot, capturePath) {
2266
2643
  timeout: 3e4
2267
2644
  });
2268
2645
  }
2646
+ var SCENE_WARNING_MARKER = "TN_SCENE_WARNING";
2647
+ function sceneShapeCheck(snapshot) {
2648
+ let latest;
2649
+ for (const file of snapshot.files) {
2650
+ if (!file.endsWith(".log") && !file.endsWith(".txt") && !file.endsWith(".json")) continue;
2651
+ const text = snapshot.readText(file);
2652
+ if (text === void 0 || !text.includes(SCENE_WARNING_MARKER)) continue;
2653
+ for (const line of text.split("\n")) {
2654
+ const at = line.indexOf(`${SCENE_WARNING_MARKER}:`);
2655
+ if (at >= 0) latest = line.slice(at + SCENE_WARNING_MARKER.length + 1).trim();
2656
+ }
2657
+ }
2658
+ if (latest === void 0) {
2659
+ return {
2660
+ detail: "no recorded run carries a scene verdict yet",
2661
+ name: "scene shape",
2662
+ status: "ok"
2663
+ };
2664
+ }
2665
+ let verdict;
2666
+ try {
2667
+ verdict = JSON.parse(latest);
2668
+ } catch {
2669
+ return {
2670
+ detail: `a ${SCENE_WARNING_MARKER} line was recorded but could not be read: ${latest.slice(0, 120)}`,
2671
+ fix: "Re-run the game and keep its stdout; the marker is one JSON object on one line.",
2672
+ name: "scene shape",
2673
+ status: "warn"
2674
+ };
2675
+ }
2676
+ if (typeof verdict !== "object" || verdict === null || !("dominantTerm" in verdict)) {
2677
+ return {
2678
+ detail: `a ${SCENE_WARNING_MARKER} line was recorded without a verdict in it`,
2679
+ name: "scene shape",
2680
+ status: "warn"
2681
+ };
2682
+ }
2683
+ const term = String(verdict.dominantTerm);
2684
+ const renderMs = "renderMs" in verdict ? String(verdict.renderMs) : "?";
2685
+ const gpuShare = "gpuShare" in verdict ? String(verdict.gpuShare) : "?";
2686
+ return {
2687
+ detail: `the last window was CPU-bound on scene shape: render ${renderMs} ms with the GPU at ${gpuShare} of the frame, dominated by ${term}`,
2688
+ fix: "Reduce the dominant term before tuning the renderer: fewer objects and fewer draws, not different render settings.",
2689
+ name: "scene shape",
2690
+ status: "warn"
2691
+ };
2692
+ }
2269
2693
  function playtestCheck(snapshot, capturePath) {
2270
2694
  const runner = playtestRunner(snapshot);
2271
2695
  if (runner === void 0) return missingPlaytestCheck(snapshot);
@@ -2322,10 +2746,10 @@ function sha256File(file) {
2322
2746
  }
2323
2747
  }
2324
2748
  function evidencePath(snapshot, relative) {
2325
- if (snapshot.projectRoot === void 0 || path2.isAbsolute(relative)) return void 0;
2326
- const root = path2.resolve(snapshot.projectRoot);
2327
- const resolved = path2.resolve(root, relative);
2328
- return resolved === root || resolved.startsWith(`${root}${path2.sep}`) ? resolved : void 0;
2749
+ if (snapshot.projectRoot === void 0 || path3.isAbsolute(relative)) return void 0;
2750
+ const root = path3.resolve(snapshot.projectRoot);
2751
+ const resolved = path3.resolve(root, relative);
2752
+ return resolved === root || resolved.startsWith(`${root}${path3.sep}`) ? resolved : void 0;
2329
2753
  }
2330
2754
  function evidenceExists(snapshot, relative, directory) {
2331
2755
  const absolute = evidencePath(snapshot, relative);
@@ -2459,6 +2883,20 @@ function nativeRuntimeKey() {
2459
2883
  function nativeRuntimeFilename() {
2460
2884
  return process.platform === "win32" ? "threenative-runtime.exe" : "threenative-runtime";
2461
2885
  }
2886
+ var NATIVE_HOST_PROBE_TIMEOUT_MS = 2e4;
2887
+ function probeNativeHost(binary) {
2888
+ try {
2889
+ const output = execFileSync(binary, ["--version"], {
2890
+ encoding: "utf8",
2891
+ stdio: ["ignore", "pipe", "pipe"],
2892
+ timeout: NATIVE_HOST_PROBE_TIMEOUT_MS
2893
+ });
2894
+ const runtimeVersion = output.match(/Native Runtime v(\d+\.\d+(?:\.\d+)?)/u)?.[1];
2895
+ return runtimeVersion === void 0 ? { reason: "the host did not name its runtime version" } : { runtimeVersion };
2896
+ } catch (error) {
2897
+ return { reason: error instanceof Error ? error.message : String(error) };
2898
+ }
2899
+ }
2462
2900
  function nativeRuntimeCheck(snapshot) {
2463
2901
  const key = nativeRuntimeKey();
2464
2902
  if (snapshot.runtimeRoot === void 0 || snapshot.readRuntimeText === void 0) {
@@ -2540,7 +2978,7 @@ function nativeRuntimeCheck(snapshot) {
2540
2978
  };
2541
2979
  }
2542
2980
  const binary = `prebuilt/${key}/${nativeRuntimeFilename()}`;
2543
- const exists = snapshot.runtimeFileExists?.(binary) ?? existsSync(path2.join(snapshot.runtimeRoot, binary));
2981
+ const exists = snapshot.runtimeFileExists?.(binary) ?? existsSync(path3.join(snapshot.runtimeRoot, binary));
2544
2982
  if (!exists) {
2545
2983
  return {
2546
2984
  detail: `unavailable \u2014 ${key} prebuilt binary is missing`,
@@ -2549,7 +2987,72 @@ function nativeRuntimeCheck(snapshot) {
2549
2987
  status: "fail"
2550
2988
  };
2551
2989
  }
2552
- return { detail: `available (${key})`, name: "native runtime", status: "ok" };
2990
+ const host = snapshot.nativeHost ?? probeNativeHost(path3.join(snapshot.runtimeRoot, binary));
2991
+ const reported = host.runtimeVersion;
2992
+ if (reported === void 0) {
2993
+ return {
2994
+ detail: `unavailable \u2014 the ${key} host did not report a runtime version (${host.reason ?? "no reason given"})`,
2995
+ fix: "Reinstall the native runtime, or build it from source with `pnpm --filter @threenative/runtime-native native:build`: doctor cannot vouch for a host it cannot identify.",
2996
+ name: "native runtime",
2997
+ status: "fail"
2998
+ };
2999
+ }
3000
+ const required = newestVersion([
3001
+ snapshot.installedVersions.get(RUNTIME_PACKAGE),
3002
+ snapshot.installedVersions.get(CORE_PACKAGE_NAME)
3003
+ ]);
3004
+ const lags = required === void 0 ? void 0 : hostIsOlder(reported, required);
3005
+ if (lags !== false) {
3006
+ return {
3007
+ detail: lags === true ? `unavailable \u2014 the ${key} host reports runtime v${reported}, older than the installed engine ${String(required)}` : `unavailable \u2014 the ${key} host reports runtime v${reported}, which cannot be compared with the installed engine ${String(required)}`,
3008
+ fix: "Install a native runtime at least as new as the engine, or build one from source with `pnpm --filter @threenative/runtime-native native:build`. A host older than the engine builds a desktop binary whose UI never appears.",
3009
+ name: "native runtime",
3010
+ status: "fail"
3011
+ };
3012
+ }
3013
+ return {
3014
+ detail: `available (${key}, host runtime v${reported})`,
3015
+ name: "native runtime",
3016
+ status: "ok"
3017
+ };
3018
+ }
3019
+ function versionParts(value) {
3020
+ const match = /^(\d+)\.(\d+)\.(\d+)/u.exec(value.trim());
3021
+ if (match === null) return void 0;
3022
+ const parts = [Number(match[1]), Number(match[2]), Number(match[3])];
3023
+ return parts.every(Number.isSafeInteger) ? parts : void 0;
3024
+ }
3025
+ function newestVersion(versions) {
3026
+ let best;
3027
+ let bestParts;
3028
+ for (const candidate of versions) {
3029
+ if (candidate === void 0) continue;
3030
+ const parts = versionParts(candidate);
3031
+ if (parts === void 0) continue;
3032
+ if (bestParts === void 0 || isNewer(parts, bestParts)) {
3033
+ best = candidate;
3034
+ bestParts = parts;
3035
+ }
3036
+ }
3037
+ return best;
3038
+ }
3039
+ function isNewer(left, right) {
3040
+ const [leftMajor, leftMinor, leftPatch] = left;
3041
+ const [rightMajor, rightMinor, rightPatch] = right;
3042
+ if (leftMajor !== rightMajor) return leftMajor > rightMajor;
3043
+ if (leftMinor !== rightMinor) return leftMinor > rightMinor;
3044
+ return leftPatch > rightPatch;
3045
+ }
3046
+ function hostIsOlder(host, required) {
3047
+ const hostParts = versionParts(host);
3048
+ const requiredParts = versionParts(required);
3049
+ if (hostParts === void 0 || requiredParts === void 0) return void 0;
3050
+ const [hostMajor, hostMinor, hostPatch] = hostParts;
3051
+ const [requiredMajor, requiredMinor, requiredPatch] = requiredParts;
3052
+ if (hostMajor !== requiredMajor) return hostMajor < requiredMajor;
3053
+ if (hostMinor !== requiredMinor) return hostMinor < requiredMinor;
3054
+ if (hostPatch !== requiredPatch) return hostPatch < requiredPatch;
3055
+ return /[-+]/u.test(host.trim()) && !/[-+]/u.test(required.trim());
2553
3056
  }
2554
3057
  function javaVersion(output) {
2555
3058
  const match = output.match(/version\s+["']([^"']+)["']/iu);
@@ -2560,11 +3063,11 @@ function javaVersion(output) {
2560
3063
  const major = majorText === void 0 ? Number.NaN : Number(majorText);
2561
3064
  return Number.isSafeInteger(major) ? { major, version } : void 0;
2562
3065
  }
2563
- function androidSdkVersion(root) {
2564
- const sourceProperties = path2.join(
3066
+ function androidSdkVersion(root, requiredSdk) {
3067
+ const sourceProperties = path3.join(
2565
3068
  root,
2566
3069
  "platforms",
2567
- `android-${ANDROID_COMPILE_SDK}`,
3070
+ `android-${requiredSdk}`,
2568
3071
  "source.properties"
2569
3072
  );
2570
3073
  try {
@@ -2575,9 +3078,9 @@ function androidSdkVersion(root) {
2575
3078
  return void 0;
2576
3079
  }
2577
3080
  }
2578
- function probeAndroidToolchain(environment = process.env) {
3081
+ function probeAndroidToolchain(environment = process.env, requiredSdk = DEFAULT_ANDROID_COMPILE_SDK) {
2579
3082
  const javaHome = environment.JAVA_HOME?.trim() || void 0;
2580
- const java = javaHome === void 0 ? "java" : path2.join(javaHome, "bin", process.platform === "win32" ? "java.exe" : "java");
3083
+ const java = javaHome === void 0 ? "java" : path3.join(javaHome, "bin", process.platform === "win32" ? "java.exe" : "java");
2581
3084
  let jdkMajor;
2582
3085
  let jdkVersion;
2583
3086
  try {
@@ -2595,18 +3098,18 @@ function probeAndroidToolchain(environment = process.env) {
2595
3098
  const sdkCandidates = [
2596
3099
  environment.ANDROID_HOME,
2597
3100
  environment.ANDROID_SDK_ROOT,
2598
- path2.join(homedir(), "Android", "Sdk")
3101
+ path3.join(homedir(), "Android", "Sdk")
2599
3102
  ].map((candidate) => candidate?.trim()).filter((candidate) => candidate !== void 0 && candidate.length > 0);
2600
3103
  const sdkRoot = sdkCandidates.find((candidate) => existsSync(candidate));
2601
3104
  return {
2602
3105
  ...jdkMajor === void 0 ? {} : { jdkMajor },
2603
3106
  ...jdkVersion === void 0 ? {} : { jdkVersion },
2604
- ...sdkRoot === void 0 ? {} : { sdkVersion: androidSdkVersion(sdkRoot) }
3107
+ ...sdkRoot === void 0 ? {} : { sdkVersion: androidSdkVersion(sdkRoot, requiredSdk) }
2605
3108
  };
2606
3109
  }
2607
3110
  function runtimeFileAvailable(snapshot, relative) {
2608
3111
  if (snapshot.runtimeRoot === void 0) return false;
2609
- return snapshot.runtimeFileExists?.(relative) ?? existsSync(path2.join(snapshot.runtimeRoot, relative));
3112
+ return snapshot.runtimeFileExists?.(relative) ?? existsSync(path3.join(snapshot.runtimeRoot, relative));
2610
3113
  }
2611
3114
  function androidTargetCheck(snapshot) {
2612
3115
  if (!runtimeFileAvailable(snapshot, "scripts/package-android.mjs")) {
@@ -2616,8 +3119,9 @@ function androidTargetCheck(snapshot) {
2616
3119
  status: snapshot.runtimeRoot === void 0 ? "warn" : "fail"
2617
3120
  };
2618
3121
  }
2619
- const androidToolchain = snapshot.androidToolchain ?? (snapshot.projectRoot === void 0 ? void 0 : probeAndroidToolchain());
2620
- const toolchain = androidToolchain === void 0 ? void 0 : androidToolchainStatus(androidToolchain);
3122
+ const requiredSdk = requiredAndroidSdk(snapshot);
3123
+ const androidToolchain = snapshot.androidToolchain ?? (snapshot.projectRoot === void 0 ? void 0 : probeAndroidToolchain(process.env, requiredSdk));
3124
+ const toolchain = androidToolchain === void 0 ? void 0 : androidToolchainStatus(androidToolchain, requiredSdk);
2621
3125
  return {
2622
3126
  detail: toolchain === void 0 ? "available \u2014 runtime packager installed; Android toolchain was not probed in this in-memory snapshot" : `available \u2014 runtime packager installed; ${toolchain.detail}`,
2623
3127
  ...toolchain?.fix === void 0 ? {} : { fix: toolchain.fix },
@@ -2667,9 +3171,10 @@ function requestedBuildBlockers(snapshot, request, nativeRuntime) {
2667
3171
  }
2668
3172
  if (!runtimeFileAvailable(snapshot, "scripts/package-android.mjs"))
2669
3173
  blockers.push(`${RUNTIME_PACKAGE} has no Android packager`);
2670
- const androidToolchain = snapshot.androidToolchain ?? (snapshot.projectRoot === void 0 ? void 0 : probeAndroidToolchain());
3174
+ const requiredSdk = requiredAndroidSdk(snapshot);
3175
+ const androidToolchain = snapshot.androidToolchain ?? (snapshot.projectRoot === void 0 ? void 0 : probeAndroidToolchain(process.env, requiredSdk));
2671
3176
  if (androidToolchain === void 0) blockers.push("the Android toolchain was not probed");
2672
- else blockers.push(...androidToolchainFacts(androidToolchain).blockers);
3177
+ else blockers.push(...androidToolchainFacts(androidToolchain, requiredSdk).blockers);
2673
3178
  if (request.mode === "release") {
2674
3179
  const environment = snapshot.environment ?? {};
2675
3180
  const missing = ANDROID_RELEASE_SIGNING_ENV.filter(
@@ -2687,9 +3192,10 @@ function requestedBuildCheck(snapshot, request, nativeRuntime) {
2687
3192
  const blockers = requestedBuildBlockers(snapshot, { ...request, target }, nativeRuntime);
2688
3193
  if (blockers.length === 0)
2689
3194
  return { detail: `buildable \u2014 ${scope}`, name: "requested build", status: "ok" };
3195
+ const requiredSdk = requiredAndroidSdk(snapshot);
2690
3196
  return {
2691
3197
  detail: `not buildable \u2014 ${scope}: ${blockers.join("; ")}`,
2692
- fix: target === "android" ? `Install JDK ${ANDROID_JDK_MAJOR} and Android SDK platform android-${ANDROID_COMPILE_SDK}, reinstall ${RUNTIME_PACKAGE} so its prebuilt downloads${request.mode === "release" ? `, and export ${ANDROID_RELEASE_SIGNING_ENV.join(", ")} from the game's build environment` : ""}.` : `Resolve the cause above, then run 'threenative doctor --target ${target}' again.`,
3198
+ fix: target === "android" ? `Install JDK ${ANDROID_JDK_MAJOR} and Android SDK platform android-${requiredSdk}, reinstall ${RUNTIME_PACKAGE} so its prebuilt downloads${request.mode === "release" ? `, and export ${ANDROID_RELEASE_SIGNING_ENV.join(", ")} from the game's build environment` : ""}.` : `Resolve the cause above, then run 'threenative doctor --target ${target}' again.`,
2693
3199
  name: "requested build",
2694
3200
  status: "fail"
2695
3201
  };
@@ -2887,6 +3393,7 @@ function diagnoseProject(snapshot, options = {}) {
2887
3393
  name: "playtests",
2888
3394
  status: "warn"
2889
3395
  },
3396
+ sceneShapeCheck(snapshot),
2890
3397
  ...capabilitySearchChecks(snapshot),
2891
3398
  editorActivationCheck(snapshot),
2892
3399
  ...blender === void 0 ? [] : [blender]
@@ -2899,7 +3406,7 @@ function diagnoseProject(snapshot, options = {}) {
2899
3406
  }
2900
3407
  async function collectFiles(root, relative = "", depth = 0) {
2901
3408
  if (depth > 3) return [];
2902
- const absolute = path2.join(root, relative);
3409
+ const absolute = path3.join(root, relative);
2903
3410
  if (!existsSync(absolute)) return [];
2904
3411
  const entries = await readdir(absolute, { withFileTypes: true });
2905
3412
  const files = [];
@@ -2920,7 +3427,7 @@ async function readJson(file) {
2920
3427
  }
2921
3428
  async function runtimeReleaseManifestUrl(runtimeRoot, version) {
2922
3429
  try {
2923
- const module = await import(pathToFileURL(path2.join(runtimeRoot, "scripts", "install-prebuilt.mjs")).href);
3430
+ const module = await import(pathToFileURL(path3.join(runtimeRoot, "scripts", "install-prebuilt.mjs")).href);
2924
3431
  const releaseUrl = record(module)?.releaseManifestUrl;
2925
3432
  if (typeof releaseUrl !== "function") return void 0;
2926
3433
  const result = releaseUrl(version);
@@ -2930,19 +3437,19 @@ async function runtimeReleaseManifestUrl(runtimeRoot, version) {
2930
3437
  }
2931
3438
  }
2932
3439
  async function readProject(root) {
2933
- const projectRoot = path2.resolve(root);
2934
- const packageJson = await readJson(path2.join(projectRoot, "package.json"));
2935
- const typeScriptConfig = path2.join(projectRoot, "threenative.config.ts");
3440
+ const projectRoot = path3.resolve(root);
3441
+ const packageJson = await readJson(path3.join(projectRoot, "package.json"));
3442
+ const typeScriptConfig = path3.join(projectRoot, "threenative.config.ts");
2936
3443
  const config = existsSync(typeScriptConfig) ? await readTypeScriptConfig(projectRoot) : nativeEntryCompat(record(packageJson)?.threenative);
2937
3444
  const files = new Set(await collectFiles(projectRoot));
2938
3445
  const installedVersions = /* @__PURE__ */ new Map();
2939
3446
  for (const name of declaredDependencies(packageJson)) {
2940
- const manifest = await readJson(path2.join(projectRoot, "node_modules", name, "package.json"));
3447
+ const manifest = await readJson(path3.join(projectRoot, "node_modules", name, "package.json"));
2941
3448
  const version = record(manifest)?.version;
2942
3449
  if (typeof version === "string") installedVersions.set(name, version);
2943
3450
  }
2944
3451
  const runtimeRoot = installedVersions.has(RUNTIME_PACKAGE) ? (() => {
2945
- const candidate = path2.join(projectRoot, "node_modules", RUNTIME_PACKAGE);
3452
+ const candidate = path3.join(projectRoot, "node_modules", RUNTIME_PACKAGE);
2946
3453
  try {
2947
3454
  return realpathSync(candidate);
2948
3455
  } catch {
@@ -2955,7 +3462,7 @@ async function readProject(root) {
2955
3462
  const mcpServerHealth = /* @__PURE__ */ new Map();
2956
3463
  if (SHAPE_VERIFIABLE_HOSTS.some(({ file }) => files.has(file))) {
2957
3464
  for (const spec of MCP_SERVER_SPECS) {
2958
- if (existsSync(path2.resolve(projectRoot, spec.expectedArgs))) {
3465
+ if (existsSync(path3.resolve(projectRoot, spec.expectedArgs))) {
2959
3466
  mcpServerHealth.set(spec.configName, probeMcpServer(projectRoot, spec));
2960
3467
  }
2961
3468
  }
@@ -2968,14 +3475,14 @@ async function readProject(root) {
2968
3475
  packageJson,
2969
3476
  projectRoot,
2970
3477
  readText: (relative) => {
2971
- const file = path2.join(projectRoot, relative);
3478
+ const file = path3.join(projectRoot, relative);
2972
3479
  try {
2973
3480
  return existsSync(file) ? readFileSync(file, "utf8") : void 0;
2974
3481
  } catch {
2975
3482
  return void 0;
2976
3483
  }
2977
3484
  },
2978
- androidToolchain: probeAndroidToolchain(),
3485
+ androidToolchain: probeAndroidToolchain(process.env, requiredAndroidSdkFromRoot(runtimeRoot)),
2979
3486
  blender: (() => {
2980
3487
  const status = resolveBlender();
2981
3488
  return {
@@ -2994,12 +3501,15 @@ async function readProject(root) {
2994
3501
  ...runtimeRoot === void 0 ? {} : {
2995
3502
  readRuntimeText: (relative) => {
2996
3503
  try {
2997
- return readFileSync(path2.join(runtimeRoot, relative), "utf8");
3504
+ return readFileSync(path3.join(runtimeRoot, relative), "utf8");
2998
3505
  } catch {
2999
3506
  return void 0;
3000
3507
  }
3001
3508
  },
3002
- runtimeFileExists: (relative) => existsSync(path2.join(runtimeRoot, relative)),
3509
+ runtimeFileExists: (relative) => existsSync(path3.join(runtimeRoot, relative)),
3510
+ nativeHost: probeNativeHost(
3511
+ path3.join(runtimeRoot, "prebuilt", nativeRuntimeKey(), nativeRuntimeFilename())
3512
+ ),
3003
3513
  ...runtimeManifestUrl === void 0 ? {} : { runtimeManifestUrl },
3004
3514
  runtimeRoot
3005
3515
  }