@wildshard/dev 0.0.0-stage → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (139) hide show
  1. package/bin/wildshard.mjs +75 -0
  2. package/lint/host-callbacks.d.mts +6 -0
  3. package/lint/host-callbacks.mjs +123 -0
  4. package/lint/ratchet.json +3 -0
  5. package/package.json +101 -3
  6. package/scripts/audit-assets.d.mts +10 -0
  7. package/scripts/audit-assets.mjs +151 -0
  8. package/scripts/bake/coatFiles.d.mts +6 -0
  9. package/scripts/bake/coatFiles.mjs +37 -0
  10. package/scripts/bake/navmeshGround.ts +22 -0
  11. package/scripts/bake/near-placeholder.mjs +331 -0
  12. package/scripts/bake/viewmodelBytes.ts +26 -0
  13. package/scripts/bake/viewmodelPage.ts +11 -0
  14. package/scripts/bake-catalogue.mjs +44 -0
  15. package/scripts/bake-check.mjs +54 -0
  16. package/scripts/bake-chunk.mjs +124 -0
  17. package/scripts/bake-cloud-field.mjs +24 -0
  18. package/scripts/bake-coats.mjs +110 -0
  19. package/scripts/bake-data-maps.d.mts +24 -0
  20. package/scripts/bake-data-maps.mjs +78 -0
  21. package/scripts/bake-entry-programs.mjs +126 -0
  22. package/scripts/bake-geometry.mjs +106 -0
  23. package/scripts/bake-ktx2.mjs +477 -0
  24. package/scripts/bake-map-glb.mjs +127 -0
  25. package/scripts/bake-map-rest.d.mts +7 -0
  26. package/scripts/bake-map-rest.mjs +50 -0
  27. package/scripts/bake-maps.mjs +200 -0
  28. package/scripts/bake-navmesh.mjs +259 -0
  29. package/scripts/bake-packs.mjs +129 -0
  30. package/scripts/bake-pickups.mjs +102 -0
  31. package/scripts/bake-query-terrain.mjs +64 -0
  32. package/scripts/bake-textures.mjs +80 -0
  33. package/scripts/bake-viewmodel-sets.mjs +137 -0
  34. package/scripts/bake-voxel-ao.mjs +119 -0
  35. package/scripts/bake-water-ripples.mjs +25 -0
  36. package/scripts/browser-imports.d.mts +2 -0
  37. package/scripts/browser-imports.mjs +40 -0
  38. package/scripts/browser-machine-loader-proof.mjs +39 -0
  39. package/scripts/browser-machine-loader.d.mts +8 -0
  40. package/scripts/browser-machine-loader.mjs +87 -0
  41. package/scripts/browser-playwright.d.mts +10 -0
  42. package/scripts/browser-playwright.mjs +5 -0
  43. package/scripts/browser-test.d.mts +4 -0
  44. package/scripts/browser-test.mjs +18 -0
  45. package/scripts/build-sdk.mjs +95 -0
  46. package/scripts/build-shardfiles.d.mts +7 -0
  47. package/scripts/build-shardfiles.mjs +230 -0
  48. package/scripts/capture-hero.mjs +211 -0
  49. package/scripts/chromium-keychain.d.mts +1 -0
  50. package/scripts/chromium-keychain.mjs +7 -0
  51. package/scripts/entry-reads/crawl.ts +152 -0
  52. package/scripts/gen-host-catalogue.d.mts +14 -0
  53. package/scripts/gen-host-catalogue.mjs +108 -0
  54. package/scripts/gen-shards.d.mts +17 -0
  55. package/scripts/gen-shards.mjs +311 -0
  56. package/scripts/goldens/plot-inputs.d.mts +12 -0
  57. package/scripts/goldens/plot-inputs.mjs +46 -0
  58. package/scripts/gpu-texmem.mjs +98 -0
  59. package/scripts/ktx2-ab.mjs +111 -0
  60. package/scripts/map-bake-frames.d.mts +4 -0
  61. package/scripts/map-bake-frames.mjs +23 -0
  62. package/scripts/map-world.mjs +162 -0
  63. package/scripts/memory-product.mjs +62 -0
  64. package/scripts/music/export-midi.mjs +69 -0
  65. package/scripts/named-blob-output.d.mts +8 -0
  66. package/scripts/named-blob-output.mjs +48 -0
  67. package/scripts/practice/verify_unimate_skin.mjs +356 -0
  68. package/scripts/preparation-browser.mjs +25 -0
  69. package/scripts/preparation-seed.mjs +15 -0
  70. package/scripts/prepare-product.d.mts +14 -0
  71. package/scripts/prepare-product.mjs +133 -0
  72. package/scripts/prove-walk.mjs +83 -0
  73. package/scripts/push-tables.d.mts +1 -0
  74. package/scripts/push-tables.mjs +28 -0
  75. package/scripts/record-shard-mounts.mjs +133 -0
  76. package/scripts/section-inventory.ts +209 -0
  77. package/scripts/shard-build-pool.d.mts +4 -0
  78. package/scripts/shard-build-pool.mjs +53 -0
  79. package/scripts/shard-milestones.d.mts +15 -0
  80. package/scripts/shard-milestones.mjs +105 -0
  81. package/scripts/shard-progress.mjs +212 -0
  82. package/scripts/shardfile-cold-boot.mjs +79 -0
  83. package/scripts/shardfile-rolldown.d.mts +2 -0
  84. package/scripts/shardfile-rolldown.mjs +32 -0
  85. package/scripts/shardfile-vite.d.mts +4 -0
  86. package/scripts/shardfile-vite.mjs +20 -0
  87. package/scripts/site-facts.mjs +88 -0
  88. package/scripts/test-template-gate.mjs +44 -0
  89. package/scripts/tex-tiers.mjs +240 -0
  90. package/scripts/unused-assets.mjs +173 -0
  91. package/scripts/wildshard.d.mts +4 -0
  92. package/scripts/wildshard.mjs +146 -0
  93. package/scripts/witness-generation.d.mts +10 -0
  94. package/scripts/witness-generation.mjs +45 -0
  95. package/src/.oxlintrc.json +12 -0
  96. package/src/cli/bin.mjs +8 -0
  97. package/src/cli/content-command.ts +44 -0
  98. package/src/cli/content.ts +287 -0
  99. package/src/cli/grid/command.ts +48 -0
  100. package/src/cli/grid/grid.ts +155 -0
  101. package/src/cli/help.ts +262 -0
  102. package/src/cli/hero/adopt.ts +109 -0
  103. package/src/cli/install-home.ts +40 -0
  104. package/src/cli/main.ts +142 -0
  105. package/src/cli/version.ts +63 -0
  106. package/src/server/app.ts +19 -0
  107. package/src/server/serve.ts +49 -0
  108. package/src/sharddev/bake/json.mjs +84 -0
  109. package/src/sharddev/bake/mapRest.ts +57 -0
  110. package/src/sharddev/bake/nativeRaster.ts +106 -0
  111. package/src/sharddev/bake/source-loader.mjs +55 -0
  112. package/src/sharddev/bake/splatLayers.ts +29 -0
  113. package/src/sharddev/bootInventory.ts +132 -0
  114. package/src/sharddev/check.ts +125 -0
  115. package/src/sharddev/checkProject.ts +134 -0
  116. package/src/sharddev/cli.ts +207 -0
  117. package/src/sharddev/dev.ts +150 -0
  118. package/src/sharddev/devClient.ts +120 -0
  119. package/src/sharddev/devRoot.ts +6 -0
  120. package/src/sharddev/engineMusic.ts +23 -0
  121. package/src/sharddev/projectEntryProof.ts +32 -0
  122. package/src/sharddev/test/diskScriptScenario.ts +88 -0
  123. package/src/sharddev/test/scriptScenario.ts +254 -0
  124. package/src/sharddev/tsconfig.json +3 -0
  125. package/src/sharddev/watch/page.ts +288 -0
  126. package/src/sharddev/watch/pageEntry.ts +44 -0
  127. package/src/sharddev/watch/parity-baseline.json +22 -0
  128. package/src/sharddev/watch/parity.mjs +194 -0
  129. package/src/sharddev/watch/proof.mjs +199 -0
  130. package/src/sharddev/watch/socket.ts +57 -0
  131. package/src/sharddev/watch/watch.ts +382 -0
  132. package/src/shared/health.ts +10 -0
  133. package/src/tools/build-web.ts +59 -0
  134. package/src/web/app.tsx +53 -0
  135. package/src/web/index.html +12 -0
  136. package/src/web/main.tsx +10 -0
  137. package/tsconfig.author.json +25 -0
  138. package/tsconfig.json +47 -0
  139. package/README.md +0 -3
@@ -0,0 +1,75 @@
1
+ #!/usr/bin/env node
2
+ // `wildshard`: the author commands run through scripts/wildshard.mjs, which bundles the CLI once; pack, upload and serve are
3
+ // this repo's own, and so is `build <folder>` (SA3): a built shard file folder needs no author bundle, only its shard file.
4
+ // Node strips no types under node_modules, so J82's hook goes first and every import below it is dynamic.
5
+ import '@wildshard/sdk/internal/threeGate';
6
+ import { pathToFileURL } from 'node:url';
7
+ import { dirname, resolve } from 'node:path';
8
+ import { createRequire } from 'node:module';
9
+ import { existsSync } from 'node:fs';
10
+ import '@wildshard/sdk/internal/bake/format-hook';
11
+ import { homedir } from 'node:os';
12
+ // SP-NE1: an install that landed in the home folder (no package.json here) says so before any verb runs.
13
+ const { homeInstallWarning } = await import('../src/cli/install-home.ts');
14
+ const homeWarning = homeInstallWarning({ sdk: resolve(import.meta.dirname, '..'), cwd: process.cwd(), home: homedir() });
15
+ if (homeWarning !== undefined) process.stderr.write(homeWarning);
16
+
17
+ /** Build's compiled bin, when this install has one (an installed build always does; a checkout after its compile). */
18
+ function compiledBuild() {
19
+ if (process.argv.some(arg => arg.startsWith('--input-receipt=') || arg === '--behaviour-only')) return undefined;
20
+ const script = resolve(dirname(createRequire(import.meta.url).resolve('@wildshard/build/package.json')), 'dist/build.mjs');
21
+ return existsSync(script) ? script : undefined;
22
+ }
23
+ const AUTHOR = new Set(['new', 'update', 'check', 'synth', 'build', 'validate', 'prove', 'dev', 'watch', 'schema', '--prepare-compiler']);
24
+ const [command, operand] = process.argv.slice(2);
25
+ // SA2: `wildshard <verb> --help` and `wildshard help [verb]` print help (src/cli/help.ts) before any verb runs.
26
+ const verbHelp = command === 'help' || (command !== undefined && !command.startsWith('-') && process.argv.slice(3).some(arg => arg === '--help' || arg === '-h'));
27
+ const builtFolder = command === 'build' && operand !== undefined && !operand.startsWith('--')
28
+ && existsSync(resolve(operand, 'shard.json')) && !existsSync(resolve(operand, 'shard.config.ts'));
29
+ if (verbHelp) {
30
+ const help = await import('../src/cli/help.ts');
31
+ const verb = command === 'help' ? operand : command;
32
+ const text = verb === undefined ? help.USAGE : help.verbHelp(verb);
33
+ if (text === undefined) { process.stderr.write(`wildshard: unknown command ${verb}\n\n${help.USAGE}`); process.exitCode = 1; }
34
+ else process.stdout.write(text);
35
+ } else if (command === 'prove' && /\.m?js$/u.test(process.argv[4] ?? '')) {
36
+ // F27: a walk proof (a script, not a tape) plays the shard on a `wildshard dev` page in headless Chromium.
37
+ const script = resolve(import.meta.dirname, '../scripts/prove-walk.mjs');
38
+ process.argv.splice(1, 2, script);
39
+ await import(pathToFileURL(script).href);
40
+ } else if (command === 'build' && !builtFolder && compiledBuild() !== undefined) {
41
+ // SDK-SPLIT SP9d3: an author's `build` runs build's compiled bin (packages/build, dist/build.mjs from its prepack): no
42
+ // run-time bundle of this CLI and no engine. build-shards' recorded builds (--input-receipt) and --behaviour-only stay
43
+ // on the author bundle below, whose rolldown bridge records the bundles' inputs.
44
+ const script = compiledBuild();
45
+ process.argv.splice(1, 2, script);
46
+ await import(pathToFileURL(script).href);
47
+ } else if (AUTHOR.has(command) && !builtFolder) {
48
+ const script = resolve(import.meta.dirname, '../scripts/wildshard.mjs');
49
+ process.argv[1] = script;
50
+ await import(pathToFileURL(script).href);
51
+ } else if (command === 'memory') {
52
+ const script = resolve(import.meta.dirname, '../scripts/memory-product.mjs');
53
+ process.argv.splice(1, 2, script);
54
+ await import(pathToFileURL(script).href);
55
+ } else if (command === 'prepare') {
56
+ const script = resolve(import.meta.dirname, '../scripts/prepare-product.mjs');
57
+ process.argv.splice(1, 2, script);
58
+ await import(pathToFileURL(script).href);
59
+ } else if (command === 'hero') {
60
+ const script = resolve(import.meta.dirname, '../scripts/capture-hero.mjs');
61
+ process.argv.splice(1, 2, script);
62
+ await import(pathToFileURL(script).href);
63
+ } else if (command === 'build-shards') {
64
+ const script = resolve(import.meta.dirname, '../scripts/build-shardfiles.mjs');
65
+ process.argv.splice(1, 2, script);
66
+ await import(pathToFileURL(script).href);
67
+ } else if (command === 'grid') {
68
+ const script = resolve(import.meta.dirname, '../src/cli/grid/command.ts');
69
+ process.argv.splice(1, 2, script);
70
+ await import(pathToFileURL(script).href);
71
+ } else if (command === 'content') {
72
+ const script = resolve(import.meta.dirname, '../src/cli/content-command.ts');
73
+ process.argv.splice(1, 2, script);
74
+ await import(pathToFileURL(script).href);
75
+ } else await import('../src/cli/main.ts');
@@ -0,0 +1,6 @@
1
+ import type ts from '@typescript/typescript6';
2
+
3
+ export interface HostCall { module: string; export: string; member?: string; file: string; start: number; end: number; strings?: string[] }
4
+ export interface HostCallback extends HostCall { path: string; message: string }
5
+ export function hostAnalysis(root: string): { program: ts.Program; checker: ts.TypeChecker; files: string[]; scan: (file: string) => { calls: HostCall[]; callbacks: HostCallback[] } };
6
+ export function hostCallbackViolations(root: string, file: string): HostCallback[];
@@ -0,0 +1,123 @@
1
+ // G454: typed build-time host catalogue; oxlint uses host-callback-syntax.
2
+ import { existsSync } from 'node:fs';
3
+ import { relative, resolve } from 'node:path';
4
+ import ts from '@typescript/typescript6';
5
+ import { hostPlayFile } from '@wildshard/sdk/internal/lint/host-files';
6
+ import { formatSource } from '@wildshard/engine/scripts/format-package.mjs';
7
+
8
+ const projects = new Map();
9
+ const localPath = (root, file) => relative(root, file).replaceAll('\\', '/');
10
+ const platform = file => /^src\/(?:engine|game|sdk|sharddev)\//u.test(file);
11
+ const shard = file => /^src\/shards\/([^/]+)\/(.+)$/u.exec(file);
12
+ /** One compiler/checker per immutable tree; no diagnostics or emit, only binding/signature resolution. */
13
+ export function hostAnalysis(inputRoot) {
14
+ const root = resolve(inputRoot);
15
+ if (projects.has(root)) return projects.get(root);
16
+ const configFile = resolve(root, 'tsconfig.json');
17
+ const config = existsSync(configFile) ? ts.readConfigFile(configFile, file => ts.sys.readFile(file)).config : {};
18
+ const parsed = ts.parseJsonConfigFileContent(config, ts.sys, root);
19
+ const files = ts.sys.readDirectory(resolve(root, 'src/shards'), ['.ts', '.tsx', '.mts', '.cts'], ['**/node_modules/**', '**/dist/**'])
20
+ .filter(file => hostPlayFile(root, localPath(root, file)));
21
+ const sectionRegistry = formatSource(root, 'sections.ts');
22
+ const program = ts.createProgram([...files, ...existsSync(sectionRegistry) ? [sectionRegistry] : []], { target: ts.ScriptTarget.ES2022, module: ts.ModuleKind.ESNext,
23
+ moduleResolution: ts.ModuleResolutionKind.Bundler, ...parsed.options, noEmit: true });
24
+ const checker = program.getTypeChecker();
25
+ const scans = new Map();
26
+ const pathOf = node => localPath(root, node.getSourceFile().fileName);
27
+ const unalias = symbol => symbol?.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
28
+ const nameOf = node => node?.name?.getText() ?? 'default';
29
+ const hostOf = declaration => {
30
+ if (!declaration || !platform(pathOf(declaration))) return null;
31
+ let owner = declaration, member;
32
+ while (owner.parent && !ts.isSourceFile(owner.parent)) {
33
+ if (owner.name) member = nameOf(owner);
34
+ if (ts.isVariableDeclaration(owner)) break;
35
+ owner = owner.parent;
36
+ }
37
+ if (member === nameOf(owner)) member = undefined;
38
+ return { module: pathOf(declaration), export: nameOf(owner), ...(member === undefined || member === 'default' ? {} : { member }) };
39
+ };
40
+ const unwrap = node => ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isSatisfiesExpression(node)
41
+ || ts.isNonNullExpression(node) ? unwrap(node.expression) : node;
42
+
43
+ // Explicit function values, including named aliases and shard-authored option bags.
44
+ // Opaque engine service instances are not expanded into all their inherited methods.
45
+ function typeLeaves(type, node, label, seen = new Set()) {
46
+ if (seen.has(type)) return [];
47
+ const next = new Set(seen).add(type);
48
+ if (type.isUnion()) return [...new Set(type.types.flatMap(part => typeLeaves(part, node, label, next)))];
49
+ if (type.getCallSignatures().length > 0) return [label];
50
+ return checker.getPropertiesOfType(type).flatMap(property => {
51
+ const decl = property.valueDeclaration;
52
+ if (!decl || !shard(pathOf(decl))) return [];
53
+ return typeLeaves(checker.getTypeOfSymbolAtLocation(property, node), node, `${label}.${property.name}`, next);
54
+ });
55
+ }
56
+ function leaves(input, label, seen = new Set()) {
57
+ const node = unwrap(input);
58
+ if (seen.has(node)) return [];
59
+ const next = new Set(seen).add(node);
60
+ if (ts.isArrowFunction(node) || ts.isFunctionExpression(node) || ts.isMethodDeclaration(node)) return [label];
61
+ if (ts.isConditionalExpression(node)) return [...leaves(node.whenTrue, `${label}.true`, next), ...leaves(node.whenFalse, `${label}.false`, next)];
62
+ if (ts.isObjectLiteralExpression(node)) return node.properties.flatMap(property => {
63
+ if (ts.isSpreadAssignment(property)) return leaves(property.expression, `${label}.*`, next);
64
+ if (ts.isMethodDeclaration(property)) return [`${label}.${nameOf(property)}`];
65
+ if (ts.isPropertyAssignment(property)) return leaves(property.initializer, `${label}.${nameOf(property)}`, next);
66
+ if (ts.isShorthandPropertyAssignment(property)) return leaves(property.name, `${label}.${nameOf(property)}`, next);
67
+ return [];
68
+ });
69
+ if (ts.isArrayLiteralExpression(node)) return node.elements.flatMap((entry, index) => leaves(ts.isSpreadElement(entry) ? entry.expression : entry, `${label}[${index}]`, next));
70
+ const type = checker.getTypeAtLocation(node);
71
+ if (type.getCallSignatures().length > 0) return [label];
72
+ const symbol = unalias(checker.getSymbolAtLocation(node));
73
+ const declaration = symbol?.valueDeclaration;
74
+ if (declaration && (ts.isVariableDeclaration(declaration) || ts.isPropertyAssignment(declaration)) && declaration.initializer) {
75
+ return leaves(declaration.initializer, label, next);
76
+ }
77
+ // Function-valued fields on shard-defined parameter/return types are forwarded too.
78
+ return typeLeaves(type, node, label);
79
+ }
80
+
81
+ function scan(file) {
82
+ if (scans.has(file)) return scans.get(file);
83
+ const source = program.getSourceFile(resolve(root, file));
84
+ if (!source || !hostPlayFile(root, file)) return { calls: [], callbacks: [] };
85
+ const calls = [], callbacks = [];
86
+ function walk(node) {
87
+ if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
88
+ let signature = checker.getResolvedSignature(node);
89
+ // Function.call/apply/bind resolve to lib.es5, not the actual platform function.
90
+ const expression = node.expression;
91
+ const indirect = ts.isPropertyAccessExpression(expression) && ['call', 'apply', 'bind'].includes(expression.name.text);
92
+ if (indirect && !hostOf(signature?.declaration)) signature = checker.getTypeAtLocation(expression.expression).getCallSignatures()[0];
93
+ const host = hostOf(signature?.declaration);
94
+ if (host) {
95
+ const start = node.getStart(source), end = node.getEnd();
96
+ const strings = [...node.arguments ?? []].flatMap(argument => {
97
+ const type = checker.getTypeAtLocation(argument);
98
+ return type.isStringLiteral() ? [type.value] : [];
99
+ });
100
+ calls.push({ ...host, file, start, end, strings });
101
+ for (const [index, argument] of [...node.arguments ?? []].entries()) {
102
+ if (indirect && index === 0) continue;
103
+ for (const path of new Set(leaves(argument, `arg${index}`))) callbacks.push({
104
+ ...host, file, start: argument.getStart(source), end: argument.getEnd(), path,
105
+ message: `Shard TS callback ${path} crosses ${host.module}#${host.export}${host.member ? `.${host.member}` : ''}; pass data or a Wasm reference (G454)`,
106
+ });
107
+ }
108
+ }
109
+ }
110
+ ts.forEachChild(node, walk);
111
+ }
112
+ walk(source);
113
+ const result = { calls, callbacks };
114
+ scans.set(file, result);
115
+ return result;
116
+ }
117
+ const result = { program, checker, files: files.map(file => localPath(root, file)).filter(file => hostPlayFile(root, file)), scan };
118
+ projects.set(root, result);
119
+ return result;
120
+ }
121
+
122
+ /** Raw sites, with no migration allowance. Used only on immutable compiler inputs. */
123
+ export function hostCallbackViolations(root, file) { return hostAnalysis(root).scan(file).callbacks; }
@@ -0,0 +1,3 @@
1
+ {
2
+ "budgets": {}
3
+ }
package/package.json CHANGED
@@ -1,6 +1,104 @@
1
1
  {
2
2
  "name": "@wildshard/dev",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.4.0",
4
+ "description": "The local game and the `wildshard` CLI (SDK-SPLIT SP8): dev, watch, check (sim and walk proofs), prove, hero, serve, the local page, the sim test harness, build-shards and the drafts tool. Depends on the engine; the sdk, kit, build and upload never do. Published with the others at one version (D5, SP12).",
5
+ "license": "UNLICENSED",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/project-wildshard/sharddev.git",
9
+ "directory": "packages/dev"
10
+ },
11
+ "type": "module",
12
+ "bin": {
13
+ "sharddev": "./bin/wildshard.mjs",
14
+ "wildshard": "./bin/wildshard.mjs"
15
+ },
16
+ "engines": {
17
+ "node": ">=24.18.0"
18
+ },
19
+ "files": [
20
+ "bin",
21
+ "src",
22
+ "!src/**/*.test.*",
23
+ "!src/e2e",
24
+ "!src/test",
25
+ "!src/ci",
26
+ "!src/web/tsconfig.json",
27
+ "!src/tsconfig.json",
28
+ "scripts",
29
+ "!scripts/**/*.test.*",
30
+ "!scripts/docs",
31
+ "lint",
32
+ "!lint/**/*.test.*",
33
+ "tsconfig*.json"
34
+ ],
35
+ "dependencies": {
36
+ "@dimforge/rapier3d-simd": "0.21.0",
37
+ "@gltf-transform/core": "4.5.0",
38
+ "@gltf-transform/extensions": "4.5.0",
39
+ "@hono/node-server": "2.1.8",
40
+ "@loaders.gl/core": "4.5.3",
41
+ "@loaders.gl/textures": "4.5.3",
42
+ "@types/three": "0.186.0",
43
+ "@typescript/typescript6": "6.0.2",
44
+ "@wildshard/engine": "0.1.35",
45
+ "@wildshard/format": "npm:@wildshard/shard-format@0.23.0",
46
+ "esbuild": "0.28.2",
47
+ "fflate": "0.8.3",
48
+ "happy-dom": "21.0.4",
49
+ "hono": "4.13.19",
50
+ "meshoptimizer": "1.2.0",
51
+ "playwright": "1.65.0",
52
+ "postprocessing": "6.39.5",
53
+ "preact": "11.1.1",
54
+ "rolldown": "1.2.16",
55
+ "sharp": "0.35.5",
56
+ "valibot": "1.5.0",
57
+ "vite": "8.3.0",
58
+ "@wildshard/build": "0.4.0",
59
+ "@wildshard/kit": "0.4.0",
60
+ "@wildshard/sdk": "0.4.0",
61
+ "@wildshard/upload": "0.4.0"
62
+ },
63
+ "peerDependencies": {
64
+ "three": "0.186.0"
65
+ },
66
+ "devDependencies": {
67
+ "@playwright/test": "1.65.0",
68
+ "@types/node": "24.3.1",
69
+ "three": "0.186.0",
70
+ "vitest": "5.0.3"
71
+ },
72
+ "exports": {
73
+ "./package.json": "./package.json",
74
+ "./bootInventory": "./src/sharddev/bootInventory.ts",
75
+ "./bake/nativeRaster": "./src/sharddev/bake/nativeRaster.ts",
76
+ "./test/scriptScenario": "./src/sharddev/test/scriptScenario.ts",
77
+ "./watch/watch": "./src/sharddev/watch/watch.ts",
78
+ "./watch/page": "./src/sharddev/watch/page.ts",
79
+ "./bake/mapRest": "./src/sharddev/bake/mapRest.ts",
80
+ "./test/diskScriptScenario": "./src/sharddev/test/diskScriptScenario.ts",
81
+ "./bake/splatLayers": "./src/sharddev/bake/splatLayers.ts",
82
+ "./projectEntryProof": "./src/sharddev/projectEntryProof.ts",
83
+ "./scripts/*": "./scripts/*"
84
+ },
85
+ "publishConfig": {
86
+ "access": "public"
87
+ },
88
+ "scripts": {
89
+ "dev": "node src/tools/build-web.ts --dev",
90
+ "build": "node src/tools/build-web.ts",
91
+ "drafts:dev": "vite --config drafts/vite.config.ts",
92
+ "drafts:build": "vite build --config drafts/vite.config.ts",
93
+ "drafts:deploy": "bash drafts/tools/deploy.sh",
94
+ "drafts:test": "../../node_modules/.bin/npr tsc -p drafts/tsconfig.json && ../../node_modules/.bin/npr tsc -p drafts/tools/tsconfig.json && vitest run drafts/test && node drafts/tools/atlas.ts --check",
95
+ "lint:kit": "node ../../kit/scripts/lint.mjs --type-aware --deny-warnings --ignore-pattern 'src/sharddev/**' --no-error-on-unmatched-pattern src",
96
+ "lint:author": "WILDSHARD_RATCHET_FILE=lint/ratchet.json node ../../kit/scripts/bin-tools.mjs -c .oxlintrc.author.json --deny-warnings src/sharddev",
97
+ "test": "pnpm test:kit && pnpm test:author",
98
+ "test:ci": "node --test 'src/ci/**/*.test.ts'",
99
+ "test:e2e": "playwright test --config src/e2e/playwright.config.ts",
100
+ "test:kit": "node --test 'src/cli/**/*.test.ts' 'src/server/*.test.ts' 'src/test/**/*.test.ts'",
101
+ "test:author": "vitest run",
102
+ "check:watch-build": "node src/sharddev/watch/parity.mjs --check"
103
+ }
6
104
  }
@@ -0,0 +1,10 @@
1
+ export interface InventoryRow {
2
+ slug: string; tier: string; files: readonly string[]; packFiles: readonly string[];
3
+ packed: readonly string[]; gpu: Readonly<Record<string, string>>; ktxFiles: readonly string[];
4
+ }
5
+ export function auditInventory(rows: readonly InventoryRow[], exists: (url: string) => boolean): string[];
6
+
7
+ export interface TextureReference { url: string; referencedBy: string[] }
8
+ export interface TextureSource { path: string; text: string }
9
+ export function auditTextureReferences(files: readonly string[], rows: readonly InventoryRow[], sources: readonly TextureSource[]): TextureReference[];
10
+ export function textureSources(root: string): TextureSource[];
@@ -0,0 +1,151 @@
1
+ #!/usr/bin/env node
2
+ // E357 X3 / T3: validate authored inventories; report unused originals without removing them.
3
+ import { execFileSync } from 'node:child_process';
4
+ import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
5
+ import { dirname, resolve, relative, posix } from 'node:path';
6
+ import { textureTierJobs } from '@wildshard/engine/scripts/texture-inputs.mjs';
7
+ import { pathToFileURL } from 'node:url';
8
+
9
+ export function auditInventory(rows, exists) {
10
+ const errors = [];
11
+ for (const row of rows) {
12
+ const packed = new Set(row.packed);
13
+ for (const file of row.files) if (!exists(file)) errors.push(`${row.slug}/${row.tier}: missing declared file ${file}`);
14
+ for (const file of row.packFiles) if (!packed.has(file)) errors.push(`${row.slug}/${row.tier}: file absent from pack ${file}`);
15
+ for (const file of packed) if (!row.packFiles.includes(file)) errors.push(`${row.slug}/${row.tier}: orphan pack member ${file}`);
16
+ for (const [source, target] of Object.entries(row.gpu)) if (!exists(target)) errors.push(`${row.slug}/${row.tier}: missing GPU stand-in ${source} -> ${target}`);
17
+ for (const file of row.ktxFiles) if (!exists(file)) errors.push(`${row.slug}/${row.tier}: missing KTX2-mode file ${file}`);
18
+ }
19
+ return errors;
20
+ }
21
+
22
+ /** Conservative deletion check: inventories include image fallbacks and GPU source keys, not just served URLs. */
23
+ export function auditTextureReferences(files, rows, sources) {
24
+ const reasons = new Map(files.map((url) => [url, new Set()]));
25
+ const clean = (url) => url.split(/[?#]/)[0];
26
+ const add = (url, why) => reasons.get(clean(url))?.add(why);
27
+ for (const row of rows) {
28
+ const why = `${row.slug}/${row.tier}`;
29
+ for (const url of [...row.files, ...row.ktxFiles, ...row.packFiles]) add(url, `inventory: ${why}`);
30
+ for (const [source, target] of Object.entries(row.gpu)) { add(source, `GPU source: ${why}`); add(target, `GPU target: ${why}`); }
31
+ }
32
+ // Exactly the jobs tex-tiers runs: original sources, selected _1k inputs, and cached output files it verifies.
33
+ for (const job of textureTierJobs(files.map((url) => `public${url}`))) {
34
+ for (const path of new Set([job.source, job.served, job.output])) add(path.slice(6), `scripts/tex-tiers.mjs: ${job.kind} input/cache (${job.source})`);
35
+ }
36
+ for (const url of files) {
37
+ const folder = posix.dirname(url);
38
+ const set = posix.basename(folder);
39
+ const filename = posix.basename(url);
40
+ const stem = filename.split('.')[0];
41
+ for (const source of sources) {
42
+ // Keep named folders too: Blender inputs and interpolated generator paths read their contents.
43
+ if (source.text.includes(url) || source.text.includes(folder) ||
44
+ (source.text.includes(set) && (source.text.includes(filename) || source.text.includes(stem)))) add(url, `source: ${source.path}`);
45
+ }
46
+ }
47
+ return files.map((url) => ({ url, referencedBy: [...(reasons.get(url) ?? [])].sort((a, b) => a.localeCompare(b)) }));
48
+ }
49
+
50
+ /** Generated byte indexes are file catalogues, not uses. Authored GPU tables and generator inputs are uses. */
51
+ export function textureSources(root) {
52
+ const sources = [];
53
+ const walk = (dir) => {
54
+ if (!existsSync(dir)) return;
55
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
56
+ const path = resolve(dir, entry.name);
57
+ if (entry.isDirectory()) walk(path);
58
+ else if (/\.(ts|tsx|js|mjs|cjs|py|sh|json|html|css|glsl)$/.test(entry.name) &&
59
+ (!entry.name.includes('.generated.') || entry.name === 'ktx2.generated.ts') &&
60
+ !['audit-assets.mjs', 'unused-assets.mjs', 'texture-inputs.mjs'].includes(entry.name)) sources.push({ path: relative(root, path), text: readFileSync(path, 'utf8') });
61
+ }
62
+ };
63
+ for (const dir of ['src', 'scripts', 'vite']) walk(resolve(root, dir));
64
+ return sources;
65
+ }
66
+
67
+ const root = resolve(import.meta.dirname, '..');
68
+ const tier = process.argv.find((arg) => arg.startsWith('--collect='))?.slice(10);
69
+ if (tier) {
70
+ if (tier !== 'phone' && tier !== 'desktop') throw new Error(`audit-assets: unknown tier ${tier}`);
71
+ const { initializeTier } = await import('@wildshard/engine/core/tier'); initializeTier(tier);
72
+ const { SHARDS } = await import('../src/shards.generated.ts');
73
+ const { PACKS } = await import('@wildshard/engine/game/boot/packs.generated');
74
+ const { GPU_FILES: shared } = await import('@wildshard/engine/boot/ktx2.generated');
75
+ const { prepareShardAssets } = await import('@wildshard/engine/game/shard/load');
76
+ const { registerGpuFiles, autoTexturePolicy } = await import('@wildshard/engine/boot/gpuFiles');
77
+ const { imagesFirstPlayingBytes } = await import('@wildshard/engine/game/grid/runtimeCost');
78
+ const { bootFileList, bootSourceFiles, bootLateReads } = await import('@wildshard/engine/boot/filePolicy');
79
+ const { chunkFiles } = await import('@wildshard/engine/boot/manifest');
80
+ const { resolveBootAudio } = await import('@wildshard/engine/boot/audioInventory');
81
+ const { folderAudioInventory } = await import('@wildshard/engine/scripts/app-build/audioPacks.ts');
82
+ const { bootFetches } = await import('@wildshard/engine/boot/prefetch');
83
+ // Match the pack baker and cold boot: install shard overlays before resolving the same Auto policy and file source.
84
+ await Promise.all(SHARDS.map((manifest) => prepareShardAssets(manifest, registerGpuFiles)));
85
+ const rows = [];
86
+ for (const manifest of SHARDS) {
87
+ if (manifest.status === 'hidden') continue;
88
+ const boot = manifest.boot;
89
+ if (!boot?.sources) throw new Error(`audit-assets: ${manifest.slug} has no authored boot.sources`);
90
+ // A function loads the product from the page's origin; this process has neither, so read the build output.
91
+ const audio = typeof boot.audio === 'function' ? await folderAudioInventory(root, manifest.slug) : await resolveBootAudio(boot);
92
+ const art = boot.explore?.art ?? [];
93
+ const shown = [];
94
+ const pictures = (value) => {
95
+ if (typeof value === 'string' && /^\/(src|assets)\/.+\.(jpe?g|png|webp)$/.test(value)) shown.push(value);
96
+ else if (value !== null && typeof value === 'object') for (const child of Object.values(value)) pictures(child);
97
+ };
98
+ pictures(manifest.explore);
99
+ for (const image of shown) if (!art.includes(image)) throw new Error(`${manifest.slug}: Explore image absent from boot.explore.art: ${image}`);
100
+ const table = manifest.ktx2 ? (await manifest.ktx2()).GPU_FILES[tier] : {};
101
+ const gpu = { ...shared[tier], ...table };
102
+ const img = bootSourceFiles(boot.sources, tier, 'img'), ktx = bootSourceFiles(boot.sources, tier, 'ktx2');
103
+ const mode = autoTexturePolicy(manifest.tiers?.[tier]?.textures, imagesFirstPlayingBytes(manifest.runtimeCost))?.mode ?? 'img';
104
+ const packFiles = bootFetches(manifest, chunkFiles(manifest, mode));
105
+ const pack = Object.hasOwn(PACKS, manifest.slug) ? PACKS[manifest.slug]?.[tier] : undefined;
106
+ const packed = pack === undefined ? [] : pack.files.map(([path]) => path);
107
+ rows.push({ slug: manifest.slug, tier, files: [...new Set([...bootFileList(boot.files, tier), ...Object.values(img).flat(), ...bootLateReads(boot.lateReads, tier, 'img'), ...(boot.precache ?? []), ...art, ...Object.values(manifest.card).filter((value) => typeof value === 'string' && value.startsWith('/src/')), ...audio])], packFiles: [...new Set(packFiles)], packed, gpu, ktxFiles: [...new Set([...Object.values(ktx).flat(), ...bootLateReads(boot.lateReads, tier, 'ktx2')])] });
108
+ }
109
+ process.stdout.write(JSON.stringify(rows));
110
+ } else if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
111
+ try {
112
+ const rows = ['phone', 'desktop'].flatMap((value) => JSON.parse(execFileSync(process.execPath, ['--experimental-transform-types', '--import', './scripts/bake-loader.mjs', 'scripts/audit-assets.mjs', `--collect=${value}`], { cwd: root, encoding: 'utf8' })));
113
+ const publicFile = (url) => resolve(root, url.startsWith('/src/') ? '.' : 'public', `.${url.split('#')[0]}`);
114
+ const errors = auditInventory(rows, (url) => existsSync(publicFile(url)));
115
+ // Licenced audio has its attribution beside its inventory. CC0/procedural art needs no credit row.
116
+ const credits = [];
117
+ for (const kind of ['music', 'sfx']) {
118
+ const dir = resolve(root, 'public/assets', kind);
119
+ for (const set of readdirSync(dir)) {
120
+ const path = resolve(dir, set, `${kind}.json`); if (!existsSync(path)) continue;
121
+ const text = readFileSync(path, 'utf8'), manifest = JSON.parse(text);
122
+ const required = kind === 'music' && /MiniMax/i.test(text) ? 'MiniMax-Music3' : kind === 'sfx' && /Stable Audio|Stability AI/i.test(text) ? 'Powered by Stability AI' : null;
123
+ if (required && (typeof manifest.credit !== 'string' || !manifest.credit.includes(required))) errors.push(`${kind}/${set}: missing required credit ${required}`);
124
+ credits.push({ set: `${kind}/${set}`, credit: manifest.credit ?? null, required });
125
+ }
126
+ }
127
+ const originals = [];
128
+ const texRoot = resolve(root, 'public/assets/tex');
129
+ const walk = (dir) => {
130
+ for (const entry of readdirSync(dir, { withFileTypes: true })) {
131
+ const path = resolve(dir, entry.name);
132
+ if (entry.isDirectory()) walk(path);
133
+ else {
134
+ const url = `/${path.slice(resolve(root, 'public').length + 1)}`;
135
+ originals.push({ url, bytes: statSync(path).size, referencedBy: rows.filter((row) => row.files.includes(url)).map((row) => `${row.slug}/${row.tier}`), gpu: Object.fromEntries(rows.map((row) => [`${row.slug}/${row.tier}`, row.gpu[url] ?? row.gpu[`${url}#layer`] ?? null]).filter(([, value]) => value !== null)) });
136
+ }
137
+ }
138
+ };
139
+ walk(texRoot);
140
+ const references = auditTextureReferences(originals.map((row) => row.url), rows, textureSources(root));
141
+ for (const row of originals) row.referencedBy = references.find((reference) => reference.url === row.url)?.referencedBy ?? [];
142
+ const unreferenced = originals.filter((row) => row.referencedBy.length === 0);
143
+ const report = { errors, inventories: rows, credits, originals, unreferencedOriginals: unreferenced, unreferencedBytes: unreferenced.reduce((sum, row) => sum + row.bytes, 0), note: 'Deletion candidates exclude runtime/image/phone inventories, GPU source keys, shared tex-tiers input/cache jobs and authored src/scripts references. Conservative source-folder matches are retained; no automatic deletions.' };
144
+ const out = process.argv.find((arg) => arg.startsWith('--out='))?.slice(6);
145
+ if (out) { if (!existsSync(dirname(out))) throw new Error(`audit-assets: output directory does not exist: ${dirname(out)}`); writeFileSync(out, `${JSON.stringify(report, null, 2)}\n`); }
146
+ for (const row of rows) console.log(`${row.slug}/${row.tier}: ${row.files.length} declared, ${row.packed.length} packed, ${row.ktxFiles.length} KTX2-mode files`);
147
+ console.log(`T3: ${originals.length} original texture files; ${unreferenced.length} without runtime or generator references (${(report.unreferencedBytes / 1048576).toFixed(2)} MiB). No deletions.`);
148
+ for (const error of errors) console.error(`audit-assets: ${error}`);
149
+ if (errors.length > 0) process.exitCode = 1;
150
+ } catch (error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; }
151
+ }
@@ -0,0 +1,6 @@
1
+ /** Lossless bytes paired with their unchanged coat-table identity. */
2
+ export interface CoatFileBytes { readonly url: string; readonly png: Uint8Array }
3
+ /** Write ordered PNG files and publish a path-only manifest last. */
4
+ export function writeCoatFiles(manifest: string, coats: readonly CoatFileBytes[]): void;
5
+ /** Read the same owned PNG bytes; encoded payloads and escaped paths refuse. */
6
+ export function readCoatFiles(manifest: string): CoatFileBytes[];
@@ -0,0 +1,37 @@
1
+ import { mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
2
+ import { basename, dirname, resolve } from 'node:path';
3
+ import { jsonOutputGuard } from '@wildshard/engine/scripts/json-output-guard.mjs';
4
+
5
+ /** Keep PNG bytes outside JSON during the native painter's process handoff.
6
+ * @param {string} manifest
7
+ * @param {ReadonlyArray<{readonly url:string;readonly png:Uint8Array}>} coats */
8
+ export function writeCoatFiles(manifest, coats) {
9
+ const directory = `${basename(manifest)}.pngs`;
10
+ mkdirSync(resolve(dirname(manifest), directory), { recursive: true });
11
+ const rows = coats.map((coat, index) => {
12
+ const png = `${directory}/${index}.png`;
13
+ writeFileSync(resolve(dirname(manifest), png), coat.png);
14
+ return { url: coat.url, png };
15
+ });
16
+ const wire = JSON.stringify(rows);
17
+ jsonOutputGuard(dirname(manifest))(manifest, wire);
18
+ writeFileSync(manifest, wire);
19
+ }
20
+
21
+ /** Read only the exact ordered files owned by this handoff, never an encoded
22
+ * fallback or a path outside its scratch directory.
23
+ * @param {string} manifest */
24
+ export function readCoatFiles(manifest) {
25
+ /** @type {unknown} */
26
+ const input = JSON.parse(readFileSync(manifest, 'utf8'));
27
+ if (!Array.isArray(input)) throw new Error('Invalid coat file manifest');
28
+ const root = realpathSync(dirname(manifest));
29
+ return input.map((/** @type {unknown} */ row, index) => {
30
+ if (typeof row !== 'object' || row === null || Object.keys(row).length !== 2
31
+ || !('url' in row) || typeof row.url !== 'string' || !('png' in row)
32
+ || row.png !== `${basename(manifest)}.pngs/${index}.png`) throw new Error('Invalid coat file manifest');
33
+ const file = resolve(root, row.png);
34
+ if (realpathSync(file) !== file) throw new Error('Coat file escapes its handoff');
35
+ return { url: row.url, png: readFileSync(file) };
36
+ });
37
+ }
@@ -0,0 +1,22 @@
1
+ import * as v from 'valibot';
2
+ import { NavmeshGroundSchema } from '@wildshard/format/navigation';
3
+ import { isJsonData } from '@wildshard/format/json';
4
+ import { readScalarLattice,type ScalarLatticeBindings } from '@wildshard/engine/world/scalarChannel';
5
+ import type { TerrainField } from '@wildshard/engine/level/data';
6
+
7
+ type Exclusion = (x: number,z: number,y: number) => boolean;
8
+ const legacy = v.strictObject({ excludeGroundAt: v.custom<Exclusion>(value => typeof value === 'function') });
9
+ const declared = v.strictObject({ ground: NavmeshGroundSchema });
10
+
11
+ /** Bake-only admission, before world construction. Retain the original live
12
+ * terrain receiver and water -> wet -> trail short circuit; decode once. */
13
+ export function navmeshGroundExclusion(input: unknown,terrain: Pick<TerrainField,'waterLevel' | 'trailDistance'> | undefined,scalars?:ScalarLatticeBindings): Exclusion | undefined {
14
+ if (input === undefined) return undefined;
15
+ if (input === null || typeof input !== 'object' || Object.getOwnPropertySymbols(input).length > 0
16
+ || !Object.values(Object.getOwnPropertyDescriptors(input)).every(row => row.enumerable && 'value' in row)) throw new Error('Invalid navmesh bake policy');
17
+ if (!isJsonData(input)) return v.parse(legacy,input).excludeGroundAt;
18
+ const { ground: row } = v.parse(declared,input);
19
+ if (terrain === undefined) throw new Error('Navmesh ground exclusion requires its bound terrain');
20
+ const wet = scalars===undefined?readScalarLattice(row.wet):scalars.lattice(row.wet);
21
+ return (x,z,y) => y <= terrain.waterLevel()+row.waterMargin || (wet(x,z) > row.wetThreshold && terrain.trailDistance(x,z) > row.trailClearance);
22
+ }