@wildshard/dev 0.0.0 → 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 +95 -4
  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,230 @@
1
+ #!/usr/bin/env node
2
+ // Every source project is built before Vite copies public/. Legacy shards without a config remain on their runtime.
3
+ // SF66 (G247): a shard whose baked map (look/map.baked.json) no longer matches its world is refused in CI and on Vercel,
4
+ // so a stale map never deploys; a local build only warns, since the rebake itself needs a served build of that world
5
+ // (node scripts/bake-maps.mjs --url=<scripts/serve-build.sh --head> --shards=<slug>). test/baked-maps.test.ts is the gate's check.
6
+ import { createBuildCacheCounters, observeBuildCache, formatBuildCacheReport } from '@wildshard/engine/scripts/build-cache-report.mjs';
7
+ import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
8
+ import { dirname, resolve } from 'node:path';
9
+ import { pathToFileURL } from 'node:url';
10
+ import { runWildshard } from './wildshard.mjs';
11
+ import { mapInputHashes, mapTilesHash, verifyMapPixels } from '@wildshard/engine/scripts/map-hash.mjs';
12
+ import { borrowShardfileEntry, readBuildKey, reuseOrBuild, shardfileCacheRoot, shardfileKey, treeHashes } from '@wildshard/engine/scripts/shardfile-cache.mjs';
13
+ import { randomBytes } from 'node:crypto';
14
+ import { InputHashMemo } from '@wildshard/engine/scripts/bake-input-hashes.mjs';
15
+ import { folderInputKey, folderToolchainKey, matchingFolderInputKey, publishFolderInputs } from '@wildshard/engine/scripts/shardfile-inputs.mjs';
16
+ import { quietCli } from '@wildshard/engine/scripts/quiet-cli.mjs';
17
+ import { manifestFolders, outputManifest, shardOutputs, shardSourceDir, shardSourceFolders } from '@wildshard/build/scripts/shard-outputs.mjs';
18
+ import { usesProgramDiscovery } from '@wildshard/engine/scripts/program-discovery.mjs';
19
+ import { shardfileValidationRevision } from '@wildshard/engine/scripts/shardfile-validation-revision.mjs';
20
+ import { runShardBuild, runShardBuildPool } from './shard-build-pool.mjs';
21
+ import { orderFolderBuilds, readFolderBuildTimes, recordFolderBuildTimes } from '@wildshard/engine/scripts/folder-build-times.mjs';
22
+ import { prepareProductBuildTools } from '@wildshard/sdk/scripts/product-build-tools.mjs';
23
+ import { checkTileBake } from '@wildshard/engine/scripts/tile-bakes.mjs';
24
+ import { reportTileBake } from '@wildshard/engine/scripts/tile-bake-report.mjs';
25
+ import { runtimeCopyIssues, folderMapInput, publishFolderMap, folderFlags, folderRecipe, retainFolderInputs, readBuiltShardfile as selectBuiltShardfile } from '@wildshard/engine/scripts/built-folder.mjs';
26
+ import { isWorktreePath } from '@wildshard/sdk/scripts/worktree-ignore.mjs';
27
+
28
+ /** Read CI's output or a matching immutable product without invoking the builder.
29
+ * @param {string} root @param {string} name
30
+ * @param {{cacheRoot?:string,env?:NodeJS.ProcessEnv}} [options] */
31
+ export function readBuiltShardfile(root, name, options = {}) { return selectBuiltShardfile(root, name, options); }
32
+
33
+ // --reuse (fast proofs: serve-build.sh, `pnpm build:proof`): a shard whose inputs are unchanged keeps its product, from
34
+ // the slot or the shared content-keyed cache (scripts/shardfile-cache.mjs). The plain `pnpm build` (the push gate)
35
+ // rebuilds every shard into a fresh folder. CI may explicitly reuse exact input receipts, then fully validates each hit.
36
+ // --shard=<slug>[,<slug>] builds only those shards: another shard's product stays only while its key still matches,
37
+ // else it is removed, so a one-shard preview never serves a stale product of a changed shard. A product whose discovery
38
+ // is program-bound (scripts/program-discovery.mjs) is always built too: the app build writes its discovery module from
39
+ // that product's current receipt, so it cannot be left stale (unchanged inputs reuse it at once).
40
+ /** The nearest folder at or above `root` with a pnpm-workspace.yaml: the root itself in a shard repo, the workspace root
41
+ * for sharddev's packages/sdk (SDK-SPLIT SP2b). @param {string} root */
42
+ function workspaceRootOf(root) {
43
+ for (let dir = resolve(root); ; dir = dirname(dir)) {
44
+ if (existsSync(resolve(dir, 'pnpm-workspace.yaml')) && existsSync(resolve(dir, 'pnpm-lock.yaml'))) return dir;
45
+ if (dirname(dir) === dir) return resolve(root);
46
+ }
47
+ }
48
+
49
+ /** The engine's toolchain key hashes package.json, pnpm-lock.yaml and pnpm-workspace.yaml in one root. In a workspace
50
+ * package the lockfile and workspace file are the workspace root's, so key those there and add the package's own
51
+ * package.json. @param {string} root @param {InputHashMemo} memo */
52
+ function toolchainKey(root, memo) {
53
+ const workspace = workspaceRootOf(root);
54
+ if (workspace === resolve(root)) return folderToolchainKey(root, memo);
55
+ return `${folderToolchainKey(workspace, new InputHashMemo(workspace))}+${memo.hash('package.json')}`;
56
+ }
57
+
58
+ /** Pack every first-party map through the existing charged SDK row; missing maps keep the old no-map build path.
59
+ * @param {string} root @param {{strict?:boolean, build?:typeof runWildshard, reuse?:boolean, only?:string[], scope?:string[], copyRuntime?:boolean|'closed',onFailure?:(slug:string,error:unknown)=>void}} options */
60
+ async function buildShardfilesWork(root, { strict = [process.env.CI, process.env.VERCEL].some(flag => flag !== undefined && flag !== '' && flag !== 'false'), build = runWildshard, reuse = false, only, scope, copyRuntime = 'closed',onFailure } = {}, counters = createBuildCacheCounters()) {
61
+ if(onFailure!==undefined&&strict)throw new Error('Product failure collection is report-only; strict builds must fail');
62
+ if (scope !== undefined && only !== undefined) throw new Error('Product phase scope and CLI only filter cannot be combined');
63
+ const outputRoot = resolve(root, 'out');
64
+ // Discard the retired discovery artifact left by older builds.
65
+ rmSync(resolve(outputRoot, 'catalog.json'), { force: true });
66
+ let count = 0;
67
+ const stale = [], runtimeReport = [];
68
+ // A folder may emit many products. Its shared source closure and prerequisite
69
+ // generation are one immutable build-phase fact; output stamps/pixels stay
70
+ // product-specific and are still checked for every output below.
71
+ /** @type {Map<string,{file:string,message:string}[]>} */
72
+ const runtimeChecks=new Map();
73
+ /** @type {Map<string,string>} */
74
+ const mapTileHashes=new Map();
75
+ const runtimeIssues = project => {
76
+ let issues = runtimeChecks.get(project);
77
+ if (issues === undefined) { issues = runtimeCopyIssues(root, project); runtimeChecks.set(project, issues); }
78
+ return issues;
79
+ };
80
+ // SA42 (SA16's rule): a single-shard repo's source is `src/` (its folder named by its slug), a multi-shard repo's is
81
+ // `src/shards/<folder>/`. The engine's shard-outputs owns the layout, so every product helper below agrees with it.
82
+ // SHARD-SOURCE AP7: a `src/shards/<folder>` with no manifest declares no product (the products tests read the manifests),
83
+ // so it is a source proof that `wildshard check` and `watch` take by path (src/shards/authoring-slice), never built here.
84
+ const declared = new Set(manifestFolders(root));
85
+ const proofs = shardSourceFolders(root, ['shard.config.ts']).filter(folder => !declared.has(folder) && existsSync(resolve(root, 'src/shards', folder)));
86
+ for (const folder of proofs) console.info(`build-shards: src/shards/${folder} has no manifest: a source proof, not a product; skipped`);
87
+ const folders = shardSourceFolders(root, ['shard.config.ts']).filter(folder => !proofs.includes(folder)).sort((a, b) => a.localeCompare(b));
88
+ // SF88g: a folder with declared outputs (scripts/shard-outputs.mjs) builds one product per output, each to out/<slug>
89
+ const products = folders.flatMap(folder => (shardOutputs(root, folder) ?? [{ slug: folder }]).map(row => ({ name: row.slug, folder, output: row.slug === folder ? undefined : row.slug })));
90
+ const built = products.map(row => row.name).sort((a, b) => a.localeCompare(b));
91
+ // A product folder no source declares any more (a folder that now emits outputs, a dropped output) never ships stale
92
+ for (const entry of existsSync(outputRoot) ? readdirSync(outputRoot, { withFileTypes: true }) : []) {
93
+ if (entry.isDirectory() && !entry.name.startsWith('.') && !built.includes(entry.name) && existsSync(resolve(outputRoot, entry.name, 'shard.json'))) {
94
+ rmSync(resolve(outputRoot, entry.name), { recursive: true, force: true }); console.info(`wildshard build: ${entry.name} is no longer built here; its folder removed`);
95
+ }
96
+ }
97
+ for (const slug of scope ?? only ?? []) if (!built.includes(slug)) throw new Error(`wildshard build: --shard=${slug} is not an output this repo builds (${built.join(', ')})`);
98
+ const bound = (only === undefined || strict ? [] : products).filter(({ folder, output }) => {
99
+ const manifest = resolve(shardSourceDir(root, folder), 'manifest.json');
100
+ if (!existsSync(manifest)) return false;
101
+ const row = output === undefined ? undefined : shardOutputs(root, folder)?.find(entry => entry.slug === output);
102
+ return usesProgramDiscovery(row === undefined ? JSON.parse(readFileSync(manifest, 'utf8')) : outputManifest(root, folder, row));
103
+ }).map(row => row.name).filter(name => only?.includes(name) !== true);
104
+ if (bound.length > 0) console.info(`wildshard build: --shard also keeps the program-bound discovery folders current: ${bound.join(', ')}`);
105
+ const selected = scope ?? (strict || only === undefined ? undefined : [...only, ...bound]);
106
+ if (only !== undefined && strict) console.warn('wildshard build: --shard ignored in CI; building every shard');
107
+ const recorded = build === runWildshard;
108
+ /** @type {Map<string,number>} */
109
+ const buildTimes=new Map();
110
+ /** @type {Map<string,number>} */
111
+ const validationTimes=new Map();
112
+ const ordered=recorded?orderFolderBuilds(products,readFolderBuildTimes(shardfileCacheRoot())):products;
113
+ // The engine pin's treeHashes skips .worktrees/ only from engine 03d4d79; drop plan worktrees here either way (DS11).
114
+ const files = recorded ? undefined : new Map([...treeHashes(root)].filter(([path]) => !isWorktreePath(path)));
115
+ const inputHashes = new InputHashMemo(root,resolve(root,'.cache/shardfile-input-hashes.json'));
116
+ // The validation receipt every product carries is checked against this revision (vite.config.ts, the ruler). The
117
+ // cached author CLI computes it once per compiler child, so a traced read set may miss its sources: key it directly,
118
+ // or a product reused after the revision moved ships a stale receipt.
119
+ const toolchainOf = () => `${toolchainKey(root,inputHashes)}:${shardfileValidationRevision(root)}`;
120
+ const toolchain = recorded ? toolchainOf() : '';
121
+ try {
122
+ await runShardBuildPool(ordered, async ({ name, folder, output }, signal) => {
123
+ if (scope !== undefined && !scope.includes(name)) return;
124
+ const buildOne = args => build === runWildshard ? runShardBuild(args, signal, report=>{counters.merge(report);}) : build(args);
125
+ const project = shardSourceDir(root, folder);
126
+ try {
127
+ const started = performance.now();
128
+ const map = folderMapInput(project, output), expected = map?.tilesHash ?? null;
129
+ let actual=mapTileHashes.get(project);
130
+ if(actual===undefined){actual=mapTilesHash(project);mapTileHashes.set(project,actual);}
131
+ if (expected !== actual) {
132
+ stale.push(name);
133
+ console.error(`wildshard map inputs: ${JSON.stringify({ shard: name, expected, actual, files: mapInputHashes(project) })}`);
134
+ }
135
+ if (map?.image !== undefined && map.image !== `/assets/${name}/map/top.webp`) throw new Error(`Unexpected baked map path for ${name}`);
136
+ if (map?.image !== undefined) {
137
+ if (map.pixelHash === undefined) throw new Error(`Missing baked map pixel identity for ${name}`);
138
+ await verifyMapPixels(resolve(root, 'public', map.image.slice(1)), map.pixelHash);
139
+ }
140
+ const issues = copyRuntime === 'closed' ? runtimeIssues(project) : [];
141
+ runtimeReport.push({ slug: name, runtime: issues.length > 0 ? 'source' : 'output', issues });
142
+ const flags = folderFlags(root, output, map, copyRuntime === true || copyRuntime === 'closed' && issues.length === 0);
143
+ // --no-placeholders (G348): a first-party product keeps its own bytes; its near / far views come from the repo bakes
144
+ // until the grid reads a shardfile's `near`. The CLI's default baked a near row into Signal Dunes' product, whose play
145
+ // stage then never ran (677bd1cf1: "Shardfile requires the normal play stage", the page held at 82 %).
146
+ const destination = resolve(root, 'out', name);
147
+ const { normalized, recipe, receipts } = folderRecipe(root, name, flags, toolchain, shardfileCacheRoot());
148
+ if (recorded) borrowShardfileEntry(receipts, true);
149
+ const currentKey = () => recorded ? matchingFolderInputKey(root,receipts,recipe,inputHashes) : shardfileKey(files ?? new Map(),name,folders.filter(other=>other!==folder),normalized);
150
+ const key = currentKey();
151
+ if (selected !== undefined && !selected.includes(name)) {
152
+ const here = readBuildKey(destination);
153
+ if (here !== key && existsSync(destination)) { rmSync(destination, { recursive: true, force: true }); console.info(`wildshard build: ${name} skipped (--shard), stale folder removed`); }
154
+ else console.info(`wildshard build: ${name} skipped (--shard)${here === key ? ', folder current' : ''}`);
155
+ return;
156
+ }
157
+ const how = await reuseOrBuild({ slug: name, key:key ?? randomBytes(32).toString('hex'), destination, fresh:!reuse && (strict || only === undefined), build: async out => {
158
+ const receipt=resolve(shardfileCacheRoot(),'.input-traces',`${process.pid}-${randomBytes(8).toString('hex')}.json`);
159
+ try {
160
+ await buildOne(['build',project,out,'--folder-only','--no-placeholders','--format=2',...flags,...(recorded?[`--input-receipt=${receipt}`]:[])]);
161
+ if (recorded && toolchainOf() !== toolchain) throw new Error('Product toolchain changed during build');
162
+ const next = recorded ? folderInputKey(root,receipt,recipe,inputHashes) : currentKey();
163
+ if (next === undefined) throw new Error(`Missing complete product input receipt: ${name}`);
164
+ if(recorded) {
165
+ retainFolderInputs(root,name,receipt,next,recipe,inputHashes);
166
+ publishFolderInputs(receipts,receipt,next);
167
+ }
168
+ return next;
169
+ } finally { if(recorded)rmSync(receipt,{force:true}); }
170
+ } });
171
+ if (recorded && how !== 'built') {
172
+ const retained = readBuildKey(destination);
173
+ retainFolderInputs(root,name,resolve(receipts,`${retained}.json`),retained,recipe,inputHashes);
174
+ }
175
+ // Cache transport never substitutes for current strict admission, including
176
+ // file hashes, schemas, budgets and executing the admitted script bytes.
177
+ if (strict && how !== 'built') await buildOne(['validate',destination]);
178
+ const tiles = checkTileBake(root, name, destination);
179
+ reportTileBake(root, name, destination);
180
+ if (map !== undefined && map.image === undefined) await publishFolderMap(root, name, destination, map.tilesHash);
181
+ console.info(`tile bake: ${name} ${tiles.l0} L0/${tiles.l1} L1, 16 full 5x5 windows checked, ${Object.keys(tiles.debt).length} existing debt metrics`);
182
+ console.info(`wildshard build: ${name} ${how === 'built' ? 'built' : `reused (${how})`} in ${((performance.now() - started) / 1000).toFixed(1)}s`);
183
+ count++;
184
+ counters.product(how==='built');
185
+ if(how==='built')buildTimes.set(name,performance.now()-started);
186
+ else if(strict)validationTimes.set(name,performance.now()-started);
187
+ } catch(error) {
188
+ counters.failure();
189
+ if(onFailure===undefined)throw error;
190
+ // A previous product cannot vouch for a failed rebuild or grant a census user.
191
+ rmSync(resolve(outputRoot,name),{recursive:true,force:true});
192
+ onFailure(name,error);
193
+ }
194
+ }, recorded ? async () => {
195
+ await prepareProductBuildTools(products.filter(row => selected === undefined || selected.includes(row.name)).map(row => row.name));
196
+ // Keep the compiler receipt independent of modules loaded by generation's
197
+ // parent. Otherwise unrelated table generators become every product's input.
198
+ await runShardBuild(['--prepare-compiler'],new AbortController().signal,report=>{counters.merge(report);});
199
+ } : undefined);
200
+ } finally { inputHashes.flush(); }
201
+ runtimeReport.sort((a,b)=>a.slug.localeCompare(b.slug));
202
+ if (copyRuntime === 'closed') for (const report of runtimeReport) console.info(`runtime copy: ${JSON.stringify(report)}`);
203
+ console.info(`wildshard build: ${count} shard file folder(s)`);
204
+ if (stale.length > 0) {
205
+ const message = `wildshard build: the baked map of ${stale.join(', ')} does not match its world (SF66); rebake: node scripts/bake-maps.mjs --url=<scripts/serve-build.sh --head> --shards=${stale.join(',')}`;
206
+ if (strict) throw new Error(message);
207
+ console.warn(message);
208
+ }
209
+ if(recorded)recordFolderBuildTimes(shardfileCacheRoot(),buildTimes,validationTimes);
210
+ return count;
211
+ }
212
+
213
+ /** The phase report is observational: payload bytes, not time saved. Zero
214
+ * lookups means not invoked, including whole-product reuse. All failures and
215
+ * strict admission still belong to the unchanged build path.
216
+ * @param {string} root
217
+ * @param {Parameters<typeof buildShardfilesWork>[1]} [options] */
218
+ export async function buildShardfiles(root,options={}) {
219
+ const counters=createBuildCacheCounters(),stop=observeBuildCache(counters);
220
+ let complete=false;
221
+ try {const result=await buildShardfilesWork(root,options,counters);complete=true;return result;}
222
+ finally {stop();if(process.env.WILDSHARD_CACHE_REPORT==='1')console.info(formatBuildCacheReport(counters.snapshot(complete)));}
223
+ }
224
+
225
+ if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
226
+ quietCli('build-shardfiles');
227
+ const only = process.argv.find(arg => arg.startsWith('--shard='))?.slice('--shard='.length).split(',').filter(Boolean);
228
+ try { await buildShardfiles(process.cwd(), { copyRuntime: process.argv.includes('--copy-runtime') ? true : 'closed', reuse: process.argv.includes('--reuse'), ...(only === undefined ? {} : { only }) }); }
229
+ catch (error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; }
230
+ }
@@ -0,0 +1,211 @@
1
+ #!/usr/bin/env node
2
+ // `wildshard hero <shard-dir> --base <served-build-url>`: capture a shard's hero (its SHARD SELECT card) from a served
3
+ // build of this exact candidate, write it over the card files the manifest names, and stamp `hero.json` with the
4
+ // content it shows. `wildshard build` refuses a cut whose stamp no longer matches the content (packages/upload/src/cli/hero/hero.ts).
5
+ // Jake, 2026-11-12 17:14 Cancún: "you have to update the hero images for the templates."
6
+ //
7
+ // Serve the candidate first: `wildshard dev .` (SA17; its page enters the shard by `?skipintro`), or an engine build
8
+ // (engine: `scripts/serve-build.sh --shard <slug>`), and run this from the shard project root. A new project's
9
+ // generated `data:` card gets files of its own: `card/<slot>.jpg`, and manifest.json names them after the capture. Headless Chromium on the real GPU (Metal), never a visible window. The view is `hero.json`'s `camera`
10
+ // ({ pos: [x,y,z], look: [x,y,z], fov, center }, engine scripts/hero-shots.mjs's view shape) when the shard declares
11
+ // one, else the player's own spawn view. Sizes: thumb 640x360, portrait 804x1626, landscape 1600x900.
12
+ //
13
+ // A scene shard (a `shard.config.ts` and no manifest.json, meta NEW-SHARD-E2E F28) wears a generated card: its hero goes
14
+ // to `card/<slot>.jpg`, which its generated discovery card names from the next build on. Every refusal is one line with a
15
+ // rule id (`[hero-<rule>] ...`), never a stack.
16
+ //
17
+ // `wildshard hero <shard-dir> --stamp-existing` captures nothing: it stamps the hero files already there as showing
18
+ // the content now. It exists for a shard repo that gains this check with curated heroes and no stamp. WARNING: use it
19
+ // only when those images match the current content; a wrong stamp hides a stale hero until the next content change.
20
+ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
21
+ import { basename, dirname, join, resolve } from 'node:path';
22
+ import { heroSlotFiles, writeHeroStamp } from '@wildshard/upload/cli/hero/stamp.ts';
23
+ import { stampExistingHero } from '../src/cli/hero/adopt.ts';
24
+ import { findShardSource, shardFolderName, shardRepoRoot } from '@wildshard/upload/sharddev/shardSource.ts';
25
+
26
+ const SCALE = 2;
27
+ const VIEWS = { portrait: { width: 402, height: 813 }, landscape: { width: 800, height: 450 }, thumb: { width: 320, height: 180 } };
28
+ const QUALITY = 86;
29
+ const sleep = ms => new Promise(done => { setTimeout(done, ms); });
30
+
31
+ /** A baseline or progressive JPEG's pixel size, from its SOF0 or SOF2 frame header. */
32
+ function jpegSize(bytes) {
33
+ for (let at = 2; at + 9 < bytes.length;) {
34
+ const marker = bytes[at + 1], length = (bytes[at + 2] << 8) | bytes[at + 3];
35
+ if (marker === 0xc0 || marker === 0xc2) return [(bytes[at + 7] << 8) | bytes[at + 8], (bytes[at + 5] << 8) | bytes[at + 6]];
36
+ at += 2 + length;
37
+ }
38
+ throw new Error('No JPEG frame header');
39
+ }
40
+
41
+ /** A refusal the CLI prints as one line, `[hero-<rule>] <message>`, never a stack. */
42
+ export class HeroRefusal extends Error {
43
+ constructor(rule, message) { super(`[hero-${rule}] ${message}`); this.name = 'HeroRefusal'; this.rule = rule; }
44
+ }
45
+
46
+ /** The shard's manifest, or null for a scene shard (its discovery is generated; F28). */
47
+ function manifestOf(shard) {
48
+ const file = join(shard, 'manifest.json');
49
+ return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : null;
50
+ }
51
+
52
+ /** The name SHARD SELECT shows this shard under: its built product's, else the manifest's. */
53
+ export function servedName(shard) {
54
+ const product = resolve(shardRepoRoot(shard), 'out', shardFolderName(shard), 'shard.json');
55
+ if (existsSync(product)) return JSON.parse(readFileSync(product, 'utf8')).identity.name;
56
+ const manifest = manifestOf(shard);
57
+ if (manifest === null) throw new HeroRefusal('no-name', `${shard} is a scene shard with no built product, so its SHARD SELECT name is unknown; capture from \`wildshard dev .\` (pass the URL it prints as --base), or build it first`);
58
+ return String(manifest.name);
59
+ }
60
+
61
+ /** The served root, so the URL `wildshard dev` prints (`…/?skipintro`) works as `--base` as well as a bare origin. */
62
+ function servedRoot(base) {
63
+ const url = new URL(base);
64
+ url.search = ''; url.hash = '';
65
+ return url.href.replace(/\/+$/u, '');
66
+ }
67
+
68
+ /** True when `base` is a `wildshard dev` server: it answers its reload poll, `/__wildshard_dev_revision`. */
69
+ async function isDevServer(base) {
70
+ try {
71
+ const response = await fetch(`${base.replace(/\/+$/u, '')}/__wildshard_dev_revision`, { cache: 'no-store' });
72
+ return response.ok && typeof (await response.json()).revision === 'number';
73
+ } catch { return false; }
74
+ }
75
+
76
+ /** Enter the shard the way a player does: SHARD SELECT, its card, ENTER WORLD (hidden shards are Developer cards).
77
+ * A `wildshard dev` page serves this shard alone and enters it by `?skipintro`; its SHARD SELECT lists engine's. */
78
+ async function enter(page, base, named, log) {
79
+ const dev = await isDevServer(base);
80
+ // a dev page serves this shard alone: no card to pick, so no name is needed (a scene shard may have none yet)
81
+ const name = dev ? '' : named();
82
+ const url = `${base.replace(/\/+$/u, '')}/?${dev ? 'skipintro&' : ''}mute=1&sw=0&tier=desktop&nolock=1&perf=0`;
83
+ log(dev ? `hero: loading ${url} (wildshard dev)` : `hero: loading ${url}, card "${name}"`);
84
+ await page.goto(url, { waitUntil: 'load' });
85
+ if (!dev) await selectCard(page, base, name);
86
+ await page.waitForFunction(() => Boolean(window.__wildshard?.world?.hud?.entered && window.__wildshard?.world?.game) && document.querySelector('.ws-load') === null,
87
+ undefined, { timeout: 240000, polling: 500 });
88
+ if (await page.evaluate(() => window.__wildshard.world.hud.paused)) await page.keyboard.press('Escape');
89
+ }
90
+
91
+ async function selectCard(page, base, name) {
92
+ await page.locator('.ws-main-select').click({ timeout: 120000 });
93
+ await page.locator('.ws-menu-card').first().waitFor({ timeout: 60000 });
94
+ const names = await page.evaluate(() => [...document.querySelectorAll('.ws-menu-card')].map(card => card.querySelector('b')?.textContent?.trim() ?? ''));
95
+ const at = names.indexOf(name);
96
+ if (at < 0) throw new HeroRefusal('no-card', `no SHARD SELECT card named "${name}" on ${base} (cards: ${names.join(', ')}); serve a build that carries this candidate`);
97
+ await page.evaluate(index => document.querySelector(`.ws-menu-dots i[data-i="${index}"]`)?.click(), at);
98
+ await sleep(1000);
99
+ await page.locator('.ws-menu-play').click();
100
+ }
101
+
102
+ export async function captureHero(shard, given, { name, log = console.info } = {}) {
103
+ // A curated card (hero.json "curated": true) is hand-picked art: a capture would put the spawn view over it.
104
+ const stampPath = join(shard, 'hero.json');
105
+ if (existsSync(stampPath) && JSON.parse(readFileSync(stampPath, 'utf8')).curated === true) {
106
+ throw new HeroRefusal('curated', `${stampPath}: this hero is curated ("curated": true), hand-picked art that is never recaptured; re-stamp it for new content with \`wildshard hero <source> --stamp-existing\`, or remove "curated" to capture this view`);
107
+ }
108
+ const base = servedRoot(given);
109
+ // Loaded here, so --stamp-existing needs no browser or engine to resolve.
110
+ const [{ chromium }, { NAME_ASKED, saveFixture }, { KEYCHAIN_ARGS }] = await Promise.all([
111
+ import("./browser-playwright.mjs"), import('@wildshard/engine/scripts/debug-settings.mjs'), import('./chromium-keychain.mjs')]);
112
+ // A `data:` slot (new's generated card) is captured to card/<slot>.jpg and named in both card files after; any other
113
+ // slot must already name a file in the shard folder.
114
+ // F28: a scene shard (no manifest) wears a generated card, so every slot it has not captured yet is a new card/<slot>.jpg
115
+ const manifest = manifestOf(shard), files = { ...(await heroSlotFiles(shard)) }, card = manifest?.card ?? {};
116
+ const missing = Object.keys(VIEWS).filter(slot => files[slot] === undefined && (manifest === null || String(card[slot]).startsWith('data:')));
117
+ const unnamed = Object.keys(VIEWS).filter(slot => files[slot] === undefined && !missing.includes(slot));
118
+ if (unnamed.length > 0) throw new HeroRefusal('card-file', `${join(shard, 'manifest.json')}: card.${unnamed.join(', card.')} must name a file in the shard folder (e.g. card/${unnamed[0]}.jpg)`);
119
+ for (const slot of missing) files[slot] = join(shard, 'card', `${slot}.jpg`);
120
+ const stampFile = join(shard, 'hero.json');
121
+ const camera = existsSync(stampFile) ? JSON.parse(readFileSync(stampFile, 'utf8')).camera : undefined;
122
+ const errors = [], shots = {};
123
+ const browser = await chromium.launch({ headless: true, args: [...KEYCHAIN_ARGS, '--mute-audio', '--use-angle=metal', '--ignore-gpu-blocklist'] });
124
+ try {
125
+ const context = await browser.newContext({ viewport: VIEWS.portrait, deviceScaleFactor: SCALE });
126
+ await saveFixture(context, { scope: 'device', key: 'devMode', data: true }); // hidden and experimental shards enter only in developer mode
127
+ await saveFixture(context, { scope: 'global', key: 'gfx', data: { dpr: 'native', aa: 'on' } });
128
+ await saveFixture(context, NAME_ASKED);
129
+ const page = await context.newPage();
130
+ page.on('pageerror', error => errors.push(error.message.slice(0, 200)));
131
+ await enter(page, base, () => name ?? servedName(shard), log);
132
+ await page.evaluate(view => {
133
+ const world = window.__wildshard.world, cam = world.game.camera;
134
+ try { world.animals.calm = true; } catch { /* a shard without animals */ }
135
+ const style = document.createElement('style');
136
+ style.textContent = 'body *{visibility:hidden!important} canvas.__hero{visibility:visible!important}';
137
+ world.game.renderer.domElement.classList.add('__hero'); document.head.append(style);
138
+ // Posed last in the frame, as engine scripts/hero-shots.mjs does; with no declared camera only the held
139
+ // weapon and hands go, and the player's spawn view stays.
140
+ world.game.onLate(() => {
141
+ for (const child of cam.children) child.visible = false;
142
+ if (view === undefined) return;
143
+ cam.position.set(...view.pos); cam.up.set(0, 1, 0); cam.lookAt(...view.look);
144
+ const center = view.center ?? 0.5, span = 2 * Math.tan(((view.fov ?? 60) * Math.PI) / 360), aspect = innerWidth / innerHeight;
145
+ const height = 2 * Math.max(center, 1 - center), offset = center < 0.5 ? 1 - 2 * center : 0;
146
+ cam.fov = (2 * Math.atan((height / 2) * span) * 180) / Math.PI;
147
+ cam.far = Math.max(cam.far, 6000);
148
+ cam.setViewOffset(aspect, height, 0, offset, aspect, 1);
149
+ cam.updateMatrixWorld(true);
150
+ });
151
+ }, camera);
152
+ await sleep(8000);
153
+ for (const [slot, viewport] of Object.entries(VIEWS)) {
154
+ await page.setViewportSize(viewport);
155
+ await sleep(3000);
156
+ shots[slot] = await page.screenshot({ type: 'jpeg', quality: QUALITY });
157
+ const [width, height] = jpegSize(shots[slot]);
158
+ if (width !== viewport.width * SCALE || height !== viewport.height * SCALE) throw new HeroRefusal('size', `${slot} came out ${width}x${height}`);
159
+ log(`hero: ${slot} ${width}x${height}`);
160
+ }
161
+ await context.close();
162
+ } finally { await browser.close(); }
163
+ if (errors.length > 0) throw new HeroRefusal('page-error', `page errors during capture, nothing written: ${errors.slice(0, 3).join(' | ')}`);
164
+ // Write every file, then the stamp, so a failed capture leaves the old hero and its old stamp.
165
+ if (missing.length > 0) mkdirSync(join(shard, 'card'), { recursive: true });
166
+ for (const [slot, bytes] of Object.entries(shots)) {
167
+ const partial = `${files[slot]}.partial`;
168
+ try { writeFileSync(partial, bytes); renameSync(partial, files[slot]); } finally { rmSync(partial, { force: true }); }
169
+ log(`hero: wrote ${files[slot]}`);
170
+ }
171
+ if (missing.length > 0) {
172
+ const named = Object.fromEntries(missing.map(slot => [slot, `/src/shards/${shardFolderName(shard)}/card/${slot}.jpg`]));
173
+ // new writes the card twice, manifest.json and the reference world's data/card.json, and build refuses a pair that
174
+ // differs; so the slots move in both. Each file keeps its own layout (new writes them on one line).
175
+ for (const file of ['manifest.json', join('data', 'card.json')].map(name => join(shard, name)).filter(existsSync)) {
176
+ const text = readFileSync(file, 'utf8'), json = JSON.parse(text);
177
+ json.card = { ...json.card, ...named };
178
+ writeFileSync(file, `${/^\{\s*\n/u.test(text) ? JSON.stringify(json, null, 2) : JSON.stringify(json)}\n`);
179
+ log(`hero: ${file} card.${missing.join(', card.')} now name card/*.jpg`);
180
+ }
181
+ }
182
+ return await writeHeroStamp(shard, { base, ...(camera === undefined ? {} : { camera }) });
183
+ }
184
+
185
+ if (process.argv[1] !== undefined && resolve(process.argv[1]) === resolve(import.meta.filename)) {
186
+ const [dir, flag, base] = process.argv.slice(2);
187
+ const adopt = flag === '--stamp-existing' && base === undefined;
188
+ if (dir === undefined || (!adopt && (flag !== '--base' || base === undefined))) {
189
+ console.error('usage: wildshard hero <source> --base <served-build-url> (serve the candidate first: `wildshard dev .` prints its URL)');
190
+ console.error(' wildshard hero <source> --stamp-existing WARNING: no capture; stamps the hero images already there as current.');
191
+ console.error(' Use it ONLY when you have looked at those images and they show the current content; a wrong stamp hides a stale hero.');
192
+ process.exit(2);
193
+ }
194
+ try {
195
+ // SA16 (J317): a repo path names its shard source at src/ or its one src/shards/<slug>/, as the other verbs do.
196
+ let shard;
197
+ try { shard = findShardSource(dir); } catch (error) { throw new HeroRefusal('no-source', error instanceof Error ? error.message : String(error)); }
198
+ // F28: a shard source is a manifest.json (a reference shard) or a shard.config.ts (a scene shard, generated card)
199
+ if (!existsSync(join(shard, 'manifest.json')) && !existsSync(join(shard, 'shard.config.ts'))) throw new HeroRefusal('no-source', `${shard} has neither a manifest.json nor a shard.config.ts; run it from the shard project root`);
200
+ if (adopt) console.warn('hero: --stamp-existing: NO capture. Stamping the images already there as showing this content. Only right if they do.');
201
+ const stamp = adopt ? await stampExistingHero(shard) : { written: true, ...(await captureHero(shard, base)) };
202
+ const file = join(dirname(shard), basename(shard), 'hero.json');
203
+ console.info(stamp.written ? `hero: stamped ${file} (content ${stamp.content.slice(0, 12)})` : `hero: ${file} is already current; nothing stamped`);
204
+ if (stamp.written && !existsSync(join(shard, 'manifest.json'))) console.info('hero: a scene shard\'s card is card/*.jpg; build again so its card wears the capture');
205
+ } catch (error) {
206
+ // one line, never a stack: a refusal names its rule; anything else is [hero-failed] with its message
207
+ const message = error instanceof HeroRefusal ? error.message : `[hero-failed] ${error instanceof Error ? error.message : String(error)}`;
208
+ console.error(message);
209
+ process.exitCode = 1;
210
+ }
211
+ }
@@ -0,0 +1 @@
1
+ export const KEYCHAIN_ARGS: readonly ['--use-mock-keychain', '--password-store=basic', '--mute-audio'];
@@ -0,0 +1,7 @@
1
+ // Every Chromium this repo starts passes these two (Jake, 2026-11-09). Without them Chrome for Testing asks the macOS
2
+ // keychain for "Chrome for Testing Safe Storage" and a dialog lands on the desktop at each launch. Playwright adds them
3
+ // by default, but a raw `spawn` of the executable skips its defaults, so every launch site spreads them explicitly and
4
+ // test/tooling/chrome-keychain.test.mjs refuses a launch file that does not.
5
+ // `--mute-audio` rides along (Jake, 2026-11-13: "headless chromium with volume off"), so a launch that forgets it
6
+ // still cannot play a game's sound out of Jake's speakers.
7
+ export const KEYCHAIN_ARGS = Object.freeze(['--use-mock-keychain', '--password-store=basic', '--mute-audio']);
@@ -0,0 +1,152 @@
1
+ #!/usr/bin/env node
2
+ import { KEYCHAIN_ARGS } from '../chromium-keychain.mjs';
3
+ // Plain post-build bake: browser-lane.sh node --experimental-transform-types
4
+ // --import ./scripts/shard-platform-format.mjs scripts/entry-reads/crawl.ts
5
+ // --base=http://127.0.0.1:4400 --pin=<landed full SHA> [--shards=a,b]
6
+ // A fresh context per region/tier walks the maintained declared entry. No new
7
+ // Vite plugin, constructor shortcut, admission root or readiness claim is used.
8
+ import { mkdir, writeFile } from 'node:fs/promises';
9
+ import { dirname, resolve } from 'node:path';
10
+ import { chromium, devices, type Browser, type BrowserContext, type Page } from "../browser-playwright.mjs";
11
+ import * as v from 'valibot';
12
+ import { crawlEntryReadSet, entryDemandUrls, type EntryCrawlDemand, type EntryCrawlRegion } from '@wildshard/sdk/entryReads';
13
+ import { hashImmutableBytes } from '@wildshard/sdk/immutable';
14
+ import { parseOutputIndex } from '@wildshard/format/outputIndex';
15
+ import type { RegionEntryReads } from '@wildshard/format/entryReads';
16
+ import { saveFixture, harnessPins } from '@wildshard/engine/scripts/debug-settings.mjs';
17
+ import { entryReadsFile } from '@wildshard/engine/scripts/shard-public.mjs';
18
+ import { frameFloorSettingsCode } from '@wildshard/engine/scripts/frame-floor-settings.mjs';
19
+ import { floorGridBenchmarkUrl, FLOOR_GRID_ENTER } from '@wildshard/engine/scripts/frame-floor-navigation.mjs';
20
+ import { gridFloorPlans, gridFloorDeclaredPlan, gridFloorDocumentIdentity, stageFloorGrid, driveFloorGrid,
21
+ gridFloorWitnessFailures, floorGridEntryRoute, type FloorGridWitness, type FloorGridState } from '@wildshard/engine/scripts/frame-floor-grid.mjs';
22
+
23
+ const stateSchema = v.object({ home: v.string(), pitch: v.pipe(v.number(), v.finite(), v.minValue(501)),
24
+ cells: v.array(v.object({ instance: v.string(), slug: v.string(), cell: v.tuple([v.number(), v.number()]) })) });
25
+ const spansSchema = v.array(v.object({ name: v.string(), startTime: v.number(), duration: v.number() }));
26
+ const versionSchema = v.object({ build: v.string() });
27
+ const stateCode = 'window.__wildshard.shard.grid.state()';
28
+ const readyCode = 'window.__wildshard?.shard?.grid?.state().live?.live?.gameplayReady === true';
29
+ const arg = (key: string): string | undefined => process.argv.find(value => value.startsWith(`--${key}=`))?.slice(key.length + 3);
30
+ const base = arg('base'), pin = arg('pin'), network = arg('network') ?? 'local';
31
+ if (!['local', 'fast4g-crossing'].includes(network)) throw new Error('Unknown entry crawl network');
32
+ if (base === undefined || pin === undefined || !/^[a-f0-9]{40}$/u.test(pin)) throw new Error('Requires --base and --pin=<landed full SHA>');
33
+ const origin = new URL(base);
34
+ if (!['http:', 'https:'].includes(origin.protocol)) throw new Error('HTTP preview required');
35
+ const out = arg('out'), requested = arg('shards')?.split(',');
36
+ if (requested?.some(slug => !/^_?[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(slug))) throw new Error('Canonical shard names required');
37
+ const versionResponse = await fetch(new URL('/version.json', origin));
38
+ if (!versionResponse.ok) throw new Error('Preview identity unavailable');
39
+ const version = v.parse(versionSchema, await versionResponse.json());
40
+ if (!version.build.startsWith(pin.slice(0, 7))) throw new Error('Preview differs from the requested pin');
41
+ const browser = await chromium.launch({ channel: 'chromium', headless: true, args: [...KEYCHAIN_ARGS, '--mute-audio', '--use-angle=metal', '--ignore-gpu-blocklist'] });
42
+ const { defaultBrowserType: _type, ...phone } = devices['iPhone 16 Pro'];
43
+
44
+ async function contextFor(host: Browser, tier: RegionEntryReads['tier']): Promise<BrowserContext> {
45
+ const context = await host.newContext(phone);
46
+ await context.addInitScript({ content: frameFloorSettingsCode({ tier, fps: 'auto' }) });
47
+ await saveFixture(context, { scope: 'global', key: 'gfx', data: { dpr: '2', aa: 'auto' } });
48
+ await saveFixture(context, { scope: 'device', key: 'devMode', data: true });
49
+ await harnessPins(context, { seed: 357, browser: 'Chromium / iPhone 16 Pro', lane: 'entry-read-bake' });
50
+ // A previous optional hint must not prewarm the crawl and erase its own input.
51
+ // Actual asset, worker and product responses stay unchanged.
52
+ await context.route('**/assets/*/entry-reads.json', route => route.fulfill({ status: 404, body: '' }));
53
+ return context;
54
+ }
55
+ async function openGrid(page: Page, fresh: boolean): Promise<void> {
56
+ await page.goto(floorGridBenchmarkUrl(origin.href), { waitUntil: 'load' });
57
+ if (fresh) await page.locator('.ws-main-grid').click();
58
+ await page.waitForFunction(readyCode, undefined, { timeout: 240_000 });
59
+ await page.evaluate(FLOOR_GRID_ENTER);
60
+ await page.waitForFunction('!document.querySelector("#hud")?.classList.contains("ws-grid-revealing")', undefined, { timeout: 30_000 });
61
+ }
62
+ async function catalogue(): Promise<v.InferOutput<typeof stateSchema>> {
63
+ const context = await contextFor(browser, 'phone');
64
+ try { const page = await context.newPage(); await openGrid(page, true); return v.parse(stateSchema, await page.evaluate(stateCode)); }
65
+ finally { await context.close(); }
66
+ }
67
+ try {
68
+ const declared = await catalogue(), cells = declared.cells.filter(cell => requested === undefined || requested.includes(cell.slug));
69
+ if (cells.length === 0 || requested?.some(slug => !cells.some(cell => cell.slug === slug))) throw new Error('Requested entry missing from the served grid');
70
+ const entries: EntryCrawlRegion[] = cells.map(cell => ({ region: cell.instance, at: [0, 0] }));
71
+ const index = new Map<string, ReturnType<typeof parseOutputIndex>>();
72
+ for (const slug of new Set(cells.map(cell => cell.slug))) {
73
+ const response = await fetch(new URL(`/shardfiles/${slug}/shard.json`, origin));
74
+ if (!response.ok) throw new Error(`Entry descriptor unavailable: ${slug}`);
75
+ index.set(slug, parseOutputIndex(await response.json()));
76
+ }
77
+ const productFailures: unknown[] = [];
78
+ for (const productSlug of new Set(cells.map(cell => cell.slug))) {
79
+ const regions = new Set(cells.filter(cell => cell.slug === productSlug).map(cell => cell.instance));
80
+ try {
81
+ const rows = await crawlEntryReadSet(entries.filter(entry => regions.has(entry.region)), {
82
+ read: async url => {
83
+ const response = await fetch(new URL(url, origin), { headers: { 'accept-encoding': 'identity' } });
84
+ if (!response.ok) throw new Error(`Entry body refused: ${response.status} ${url}`);
85
+ const bytes = new Uint8Array(await response.arrayBuffer());
86
+ for (const [slug, product] of index) {
87
+ const file = product.files.find(row => url.split('?')[0] === `/shardfiles/${slug}/${row.path}`);
88
+ if (file !== undefined && (bytes.length !== file.compressed || hashImmutableBytes(bytes) !== file.hash)) throw new Error('Crawled product body differs from its descriptor');
89
+ }
90
+ return bytes;
91
+ },
92
+ visit: async (entry, tier, read) => {
93
+ const cell = cells.find(row => row.instance === entry.region), source = cell === undefined ? undefined : index.get(cell.slug);
94
+ if (cell === undefined || source === undefined) throw new Error('Crawl region lacks its descriptor');
95
+ const home = declared.cells.find(row => row.slug === '_template' && row.instance !== cell.instance)
96
+ ?? declared.cells.find(row => row.slug === 'driftwood-isle' && row.instance !== cell.instance);
97
+ if (home === undefined) throw new Error('Crawl requires a distinct cold source');
98
+ const context = await contextFor(browser, tier), demands: (EntryCrawlDemand & { readonly at: number })[] = [];
99
+ try {
100
+ const catalogueId = JSON.stringify({ pitch: declared.pitch, cells: declared.cells.map(row => [row.instance, row.slug, ...row.cell]).sort((a, b) => String(a[0]).localeCompare(String(b[0]))) });
101
+ await saveFixture(context, { scope: 'session', key: 'grid.recovery.once', once: 'entry-read-cold-source', data: {
102
+ instance: home.instance, slug: home.slug, catalogue: catalogueId, at: Date.now(), reason: 'reload',
103
+ road: { x: home.cell[0] * declared.pitch + declared.pitch / 2 + 3.6, z: home.cell[1] * declared.pitch, yaw: 0 } } });
104
+ const page = await context.newPage(), errors: string[] = [];
105
+ const cdp = await context.newCDPSession(page);
106
+ if (network === 'fast4g-crossing') await cdp.send('Emulation.setCPUThrottlingRate', { rate: 4 });
107
+ page.on('pageerror', error => { errors.push(error.stack ?? error.message); });
108
+ context.on('request', request => {
109
+ const url = new URL(request.url());
110
+ if (url.origin !== origin.origin || !['/assets/', `/shardfiles/${cell.slug}/blobs/`].some(prefix => url.pathname.startsWith(prefix))) return;
111
+ const { range } = request.headers();
112
+ demands.push({ url: `${url.pathname}${url.search}`, at: Date.now(), ...(range === undefined ? {} : { range }) });
113
+ });
114
+ await openGrid(page, false);
115
+ const state = await page.evaluate(stateCode) as FloorGridState;
116
+ if (state.home !== home.instance || state.live.live.residents.includes(cell.instance)) throw new Error('Crawl target is not a cold entry');
117
+ if (network === 'fast4g-crossing') {
118
+ await cdp.send('Network.enable');
119
+ await cdp.send('Network.emulateNetworkConditions', { offline: false, latency: 150, downloadThroughput: 9e6 / 8, uploadThroughput: 1.5e6 / 8 });
120
+ }
121
+ const identity = await page.evaluate(gridFloorDocumentIdentity), route = floorGridEntryRoute(gridFloorPlans(state, 'cell', { cell: cell.instance, roadApproach: true }), cell.instance);
122
+ for (const plan of [...route.setup, route.entry]) {
123
+ const live = await page.evaluate(stateCode) as FloorGridState, resolved = await gridFloorDeclaredPlan(page, live, plan);
124
+ await page.evaluate(`(${stageFloorGrid.toString()})(${JSON.stringify(resolved)},${JSON.stringify(identity)},(${driveFloorGrid.toString()}))`);
125
+ const witness = await page.evaluate<FloorGridWitness>(`(${driveFloorGrid.toString()})(${JSON.stringify(resolved)},${JSON.stringify(identity)})`);
126
+ const failures = gridFloorWitnessFailures(witness);
127
+ if (failures.length > 0) throw new Error(`Entry crawl refused: ${failures.join('; ')}`);
128
+ }
129
+ if (errors.length > 0) throw new Error(`Entry crawl page errors: ${errors.join('; ')}`);
130
+ const timeOrigin = v.parse(v.number(), await page.evaluate('performance.timeOrigin'));
131
+ const spans = v.parse(spansSchema, await page.evaluate('performance.getEntriesByType("measure").map(row=>({name:row.name,startTime:row.startTime,duration:row.duration}))'));
132
+ const spansForEntry = spans.filter(row => row.name === `wildshard.prepare:${cell.slug}:grid.prepare:${cell.instance}.create`);
133
+ if (spansForEntry.length !== 1) throw new Error(`Expected one completed cold entry span: ${cell.slug}`);
134
+ const hold = spansForEntry[0]; if (hold === undefined) throw new Error('Entry span missing');
135
+ const urls = entryDemandUrls(cell.slug, source, demands.filter(row => row.at >= timeOrigin + hold.startTime && row.at <= timeOrigin + hold.startTime + hold.duration));
136
+ for (const url of urls) await read(url);
137
+ console.log(JSON.stringify({ region: cell.instance, tier, pin, network, complete: true, errors, heldMs: hold.duration, files: urls.length }));
138
+ } finally { await context.close(); }
139
+ },
140
+ });
141
+ // Publish only a complete product: every selected region/tier and all its
142
+ // bodies succeeded. An independent product failure never erases this data.
143
+ const path = out === undefined ? entryReadsFile(process.cwd(), productSlug) : resolve(out, productSlug, 'entry-reads.json');
144
+ await mkdir(dirname(path), { recursive: true });
145
+ await writeFile(path, `${JSON.stringify(rows, null, 1)}\n`);
146
+ } catch (error: unknown) {
147
+ productFailures.push(error);
148
+ console.error({ product: productSlug, error: error instanceof Error ? error.stack ?? error.message : String(error) });
149
+ }
150
+ }
151
+ if (productFailures.length > 0) throw new AggregateError(productFailures, 'Entry crawl has refused products; completed tables are retained');
152
+ } finally { await browser.close(); }
@@ -0,0 +1,14 @@
1
+ import type { HostCall, HostCallback } from '../lint/host-callbacks.mjs';
2
+
3
+ export interface HostVerdict { status: string; evidence: string }
4
+ export interface HostReview { sourceHash: string; evidence: string; verdicts: Record<string, string> }
5
+ export function hostVerdicts(users: string[], callbacks: HostCallback[], audited?: HostReview, sourceHash?: string | null): Record<string, HostVerdict>;
6
+ export interface HostCatalogue {
7
+ schema: string; coverage: string;
8
+ sections: { name: string; type: string; fields: { name: string; type: string }[]; readers: HostCall[]; hosts: string[]; users: string[] }[];
9
+ fields: unknown[]; wasm: { contract: unknown; signatures: unknown[] };
10
+ hosts: { module: string; export: string; calls: HostCall[]; callbacks: HostCallback[]; users: string[]; pendingUsers: { shard: string }[]; sourceHash: string | null; verdicts: Record<string, HostVerdict> }[];
11
+ }
12
+ export function hostCatalogue(root?: string, reference?: { fields: unknown[]; contract: unknown; abi: unknown[] }): HostCatalogue;
13
+ export function renderHostCatalogue(catalogue: HostCatalogue): string;
14
+ export function writeHostCatalogue(root?: string): HostCatalogue;