@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,288 @@
1
+ import { Scope } from '@wildshard/engine/app/scope';
2
+ import { DEV_HOOK_VERSION, DEV_SCENE_PATH, WATCH_SOCKET, WATCH_WIRE, budgetLines, decodeGeometry, type WatchBuild, type WatchPart, type WatchState } from '@wildshard/sdk/watch/protocol';
3
+
4
+ /**
5
+ * SHARD-SOURCE AP5 (J347): the page script `wildshard watch` injects into the page it serves (`pageEntry.ts`, bundled at
6
+ * start). It owns the page's half of watch: the socket, the fetches, a cache of decoded geometry and rasters, one scope
7
+ * per part and the swap order, and drives engine's dev hook (`window.__wildshardDevHook`, five calls). Per revision:
8
+ *
9
+ * 1. the look's day keys, if they changed (`setLook`; a look the page can't take live reloads it), and the ground (AP18:
10
+ * `setGround`, the whole lattice; a page that can't take it reloads)
11
+ * 1b. the gameplay sections, if they changed (AP19: `restartGameplay`: the in-page server restarts its world on them and the
12
+ * quest views are built again; a page that can't reloads)
13
+ * 2. every changed part is fetched and decoded first, so a slow fetch never leaves half a revision on screen
14
+ * 3. each one swaps in (`addPart` or `replacePart`, then `swapColliders`), and only then its old scope goes
15
+ * 4. parts no longer in the scene go (`removePart`, `swapColliders(name, [])`)
16
+ *
17
+ * `window.__wsDevScene` reports what landed and the first frame after it, for `proof.mjs`'s timing.
18
+ */
19
+ export interface DevHookLike {
20
+ readonly version: number;
21
+ addPart: (name: string, part: unknown) => void;
22
+ replacePart: (name: string, part: unknown) => void;
23
+ removePart: (name: string) => void;
24
+ setLook: (look: { readonly keys: readonly unknown[]; readonly look?: unknown }) => boolean;
25
+ swapColliders: (name: string, boxes: readonly unknown[]) => void;
26
+ setGround: (ground: Uint8Array) => boolean;
27
+ /** v4 (AP19) */
28
+ restartGameplay: (gameplay: unknown) => Promise<DevRestartLike>;
29
+ }
30
+
31
+ /** What engine's soft restart did (its `DevRestart`): the server's world restart and the page's quest views, in ms. */
32
+ export interface DevRestartLike { readonly ok: boolean; readonly serverMs: number; readonly questsMs: number | null; readonly reason?: string }
33
+
34
+ export interface SocketLike { onmessage: ((event: { data: unknown }) => void) | null; onclose: (() => void) | null; close: () => void }
35
+
36
+ export interface WatchPageEnv {
37
+ /** the watch server's origin, `http://127.0.0.1:<port>` */
38
+ readonly origin: string;
39
+ readonly hook: () => DevHookLike | undefined;
40
+ readonly fetch: (url: string) => Promise<{ ok: boolean; status: number; json: () => Promise<unknown>; arrayBuffer: () => Promise<ArrayBuffer> }>;
41
+ readonly socket: (url: string) => SocketLike;
42
+ /** the page's next frame (`requestAnimationFrame`) */
43
+ readonly frame: (run: () => void) => void;
44
+ readonly wait: (ms: number, run: () => void) => void;
45
+ readonly reload: () => void;
46
+ /** AP17: ask the watch server for a new shell (a look the page's hook refused live); the page reloads into it */
47
+ readonly reshell: () => void;
48
+ readonly now: () => number;
49
+ readonly log: (message: string) => void;
50
+ /** the shell this page booted from (`window.__wsShell`, written into the page per shell); a state for another reloads */
51
+ readonly shell?: () => number | null;
52
+ /** AP19, AP20: the page's watch panel: what the last revision did, and the last full build's budget table */
53
+ readonly overlay?: (lines: readonly string[]) => void;
54
+ }
55
+
56
+ export interface WatchPageReport {
57
+ revision: number;
58
+ /** the last revision whose parts all landed, and the wall clock (ms) of the first frame after it */
59
+ framedRevision: number;
60
+ framedAt: number;
61
+ /** the wall clock (ms) of the last revision's steps: its state received, its parts fetched and decoded, swapped in */
62
+ readonly steps: { seen: number; sent: number; received: number; fetched: number; swapped: number };
63
+ /** frames since the script started: it only grows, swap or no swap */
64
+ frames: number;
65
+ /** the page's own failure: a part the hook refused, a fetch, a message it couldn't read */
66
+ error: string | null;
67
+ /** the watch server's: the source failed to bundle or describe (the page keeps the last good revision) */
68
+ serverError: string | null;
69
+ /** every part swapped in, in order (`name@hash`) */
70
+ readonly applied: string[];
71
+ /** AP17 to AP19: what the last revision changed on this page, joined with `and` (`look`, `ground`, `gameplay`, `parts`),
72
+ * `nothing`, or `reload` */
73
+ kind: string | null;
74
+ /** AP19: the last soft restart, as engine's hook answered it */
75
+ restart: DevRestartLike | null;
76
+ /** AP20: the last full build the watch server ran, and its budget table */
77
+ build: WatchBuild | null;
78
+ }
79
+
80
+ interface Held<T> { readonly value: T; users: number }
81
+
82
+ /** The panel's name for each kind of reload a revision ran (the plan's `wildshard watch` table). */
83
+ const RELOADS: Readonly<Record<string, string>> = { look: 'look data live', ground: 'ground and colliders swapped', parts: 'parts swapped', gameplay: 'simulation restarted (player kept)',
84
+ nothing: 'nothing changed', reload: 'full page reload' };
85
+ interface LivePart { readonly hash: string; readonly scope: Scope }
86
+
87
+ /** How long the script waits for the engine to boot and install its hook. */
88
+ const HOOK_WAIT_MS = 180_000;
89
+
90
+ export function startWatchPage(env: WatchPageEnv): { readonly report: WatchPageReport; readonly stop: () => void } {
91
+ const scope = new Scope('watch.page');
92
+ const report: WatchPageReport = { revision: 0, framedRevision: 0, framedAt: 0, frames: 0, error: null, serverError: null, applied: [], kind: null, restart: null, build: null, steps: { seen: 0, sent: 0, received: 0, fetched: 0, swapped: 0 } };
93
+ const parts = new Map<string, LivePart>(), geometries = new Map<string, Held<ReturnType<typeof decodeGeometry>>>(), textures = new Map<string, Held<Uint8Array>>();
94
+ let hook: DevHookLike | null = null, shell: number | null = env.shell?.() ?? null, look: string | null = null, ground: string | null = null, gameplay: string | null = null, socket: SocketLike | null = null;
95
+ let pendingFrame: number | null = null;
96
+
97
+ /** The watch panel: which reload the last revision ran and its time, then the build's table. */
98
+ const show = (): void => {
99
+ const took = report.framedAt > 0 && report.steps.seen > 0 ? ` in ${Math.max(0, report.framedAt - report.steps.seen)} ms` : '';
100
+ const named = (report.kind ?? 'starting').split(' and ').map((kind) => RELOADS[kind] ?? kind).join(' and ');
101
+ env.overlay?.([`watch: revision ${report.revision}, ${named}${report.kind === null || report.kind === 'nothing' || report.kind === 'reload' ? '' : took}`,
102
+ ...report.serverError === null ? [] : [`refused: ${report.serverError}`], ...report.build === null ? ['full build: once edits rest 5 s'] : budgetLines(report.build)]);
103
+ };
104
+ // NEW-SHARD-E2E F17: one frame asked for each landed revision, never one every frame. A page frame cap that runs one
105
+ // animation-frame callback a frame (an agent's 60 fps cap) ran this script's request first every frame, and the engine's
106
+ // boot, waiting on its own frames, stalled at "Application modules".
107
+ let frameAsked = false;
108
+ const tick = (): void => {
109
+ frameAsked = false;
110
+ if (scope.disposed) return;
111
+ report.frames++;
112
+ if (pendingFrame !== null) { report.framedRevision = pendingFrame; report.framedAt = env.now(); pendingFrame = null; show(); }
113
+ };
114
+ const askFrame = (): void => { if (!frameAsked && !scope.disposed) { frameAsked = true; env.frame(tick); } };
115
+
116
+ const fail = (message: string): void => { report.error = message; env.log(`wildshard watch: ${message}`); };
117
+ const get = async (path: string): Promise<{ json: () => Promise<unknown>; arrayBuffer: () => Promise<ArrayBuffer> }> => {
118
+ const response = await env.fetch(`${env.origin}${DEV_SCENE_PATH}${path}`);
119
+ if (!response.ok) throw new Error(`${path} answered ${response.status}`);
120
+ return response;
121
+ };
122
+ /** Take one use of a cached asset for `owner`; it is let go when `owner` is disposed. */
123
+ const hold = <T>(map: Map<string, Held<T>>, key: string, owner: Scope): T => {
124
+ const held = map.get(key);
125
+ if (held === undefined) throw new Error(`asset ${key} was not fetched`);
126
+ held.users++;
127
+ owner.onDispose(() => { if (--held.users === 0) map.delete(key); });
128
+ return held.value;
129
+ };
130
+
131
+ /**
132
+ * Ask the server for a new shell, which the page reloads into: once per revision, and never for a revision that carries the
133
+ * server's refusal (its shell build of that source failed too, so asking again would rebuild it in a loop).
134
+ */
135
+ let asked: string | null = null;
136
+ const reshell = (state: WatchState, why: string): void => {
137
+ report.kind = 'reload';
138
+ const key = `${state.shell}/${state.revision}`;
139
+ if (state.error !== null || asked === key) { env.log(`wildshard watch: ${why}; waiting for an edit the shell build takes`); return; }
140
+ asked = key; env.log(`wildshard watch: ${why}; reloading`); env.reshell();
141
+ };
142
+ /** Draw each fetched part through the hook; false when any failed (the hook keeps that part's old copy drawn). */
143
+ const place = (fetched: readonly WatchPart[], live: DevHookLike): boolean => {
144
+ let landed = true;
145
+ for (const part of fetched) {
146
+ const owner = scope.child(`watch.part.${part.name}@${part.hash}`), old = parts.get(part.name);
147
+ try {
148
+ const devPart = { materials: part.materials, sprites: part.sprites, lamps: part.lamps, water: part.water, draws: part.draws, ...(part.swings === undefined ? {} : { swings: part.swings }),
149
+ geometries: part.geometries.map((key) => hold(geometries, key, owner)),
150
+ textures: part.textures.map((t) => ({ ...t, rgba: hold(textures, t.key, owner) })) };
151
+ if (old === undefined) live.addPart(part.name, devPart); else live.replacePart(part.name, devPart);
152
+ } catch (cause) {
153
+ // the hook keeps the old part drawn; this revision's copy lets its assets go
154
+ owner.dispose(); landed = false;
155
+ fail(`part ${part.name}: ${cause instanceof Error ? cause.message : String(cause)}`);
156
+ continue;
157
+ }
158
+ // the new part is drawn: record it before anything else can throw, so the next revision replaces it
159
+ parts.set(part.name, { hash: part.hash, scope: owner });
160
+ report.applied.push(`${part.name}@${part.hash}`);
161
+ old?.scope.dispose();
162
+ try { live.swapColliders(part.name, part.colliders); }
163
+ catch (cause) { landed = false; fail(`part ${part.name} colliders: ${cause instanceof Error ? cause.message : String(cause)}`); }
164
+ }
165
+ return landed;
166
+ };
167
+ const sync = async (state: WatchState, first: boolean): Promise<void> => {
168
+ const live = hook;
169
+ if (live === null) return;
170
+ report.serverError = state.error;
171
+ if (state.error !== null) env.log(`wildshard watch: ${state.error}`);
172
+ const lookChanged = state.look.hash !== look;
173
+ if (lookChanged) {
174
+ if (!live.setLook({ keys: state.look.keys, look: state.look.look })) {
175
+ if (!first) { reshell(state, 'this look change needs a new shell'); return; }
176
+ fail('the page\'s look can\'t take this look live: look edits will reload the page');
177
+ }
178
+ look = state.look.hash;
179
+ }
180
+ // AP18: the ground the page holds is its shell's until one is set live
181
+ const groundChanged = state.ground.hash !== (ground ?? state.ground.shell);
182
+ if (groundChanged) {
183
+ const bytes = new Uint8Array(await (await get(`ground/${encodeURIComponent(state.ground.hash)}`)).arrayBuffer());
184
+ if (scope.disposed) return;
185
+ if (!live.setGround(bytes)) { reshell(state, 'the page can\'t take this ground live'); return; }
186
+ ground = state.ground.hash;
187
+ }
188
+ // AP19: a quest, encounter, spawn or script change restarts the in-page simulation (the player keeps their place)
189
+ const gameplayChanged = state.gameplay.hash !== (gameplay ?? state.gameplay.shell);
190
+ if (gameplayChanged) {
191
+ const rows = await (await get(`gameplay/${encodeURIComponent(state.gameplay.hash)}`)).json();
192
+ if (scope.disposed) return;
193
+ const done = await live.restartGameplay(rows);
194
+ report.restart = done;
195
+ if (scope.disposed) return;
196
+ if (!done.ok) { reshell(state, `the page can't restart its simulation on this revision${done.reason === undefined ? '' : ` (${done.reason})`}`); return; }
197
+ gameplay = state.gameplay.hash;
198
+ }
199
+ // fetch and decode every changed part before any swaps in
200
+ const changed = state.parts.filter((part) => parts.get(part.name)?.hash !== part.hash);
201
+ const fetched = await Promise.all(changed.map(async ({ name }) => await (await get(`part/${encodeURIComponent(name)}`)).json() as WatchPart));
202
+ const fresh = new Map<string, Promise<void>>();
203
+ for (const part of fetched) {
204
+ for (const key of part.geometries) if (!geometries.has(key) && !fresh.has(`g:${key}`)) fresh.set(`g:${key}`, (async () => { const bytes = await (await get(`geometry/${key}`)).arrayBuffer(); geometries.set(key, { value: decodeGeometry(key, bytes), users: 0 }); })());
205
+ for (const t of part.textures) if (!textures.has(t.key) && !fresh.has(`t:${t.key}`)) fresh.set(`t:${t.key}`, (async () => { const bytes = await (await get(`texture/${t.key}`)).arrayBuffer(); textures.set(t.key, { value: new Uint8Array(bytes), users: 0 }); })());
206
+ }
207
+ await Promise.all(fresh.values());
208
+ if (scope.disposed) return;
209
+ report.steps.fetched = env.now();
210
+ // the revision holds every asset it fetched until all its parts are placed: a part that fails lets its own holds go,
211
+ // and an asset it shares with a later part must not leave the cache on that (it would be "not fetched" there)
212
+ const revision = scope.child(`watch.revision.${state.revision}`);
213
+ for (const part of fetched) {
214
+ for (const key of part.geometries) if (geometries.has(key)) hold(geometries, key, revision);
215
+ for (const t of part.textures) if (textures.has(t.key)) hold(textures, t.key, revision);
216
+ }
217
+ let landed: boolean;
218
+ try { landed = place(fetched, live); } finally { revision.dispose(); }
219
+ const names = new Set(state.parts.map((part) => part.name));
220
+ let removed = 0;
221
+ for (const [name, part] of parts) {
222
+ if (names.has(name)) continue;
223
+ removed++;
224
+ live.removePart(name); live.swapColliders(name, []);
225
+ parts.delete(name); part.scope.dispose();
226
+ }
227
+ report.kind = [lookChanged ? 'look' : '', groundChanged ? 'ground' : '', gameplayChanged ? 'gameplay' : '', fetched.length > 0 || removed > 0 ? 'parts' : ''].filter((what) => what !== '').join(' and ') || 'nothing';
228
+ report.revision = state.revision;
229
+ // the timing counts a revision only once all its parts landed
230
+ report.steps.swapped = env.now();
231
+ if (landed) { pendingFrame = state.revision; askFrame(); }
232
+ };
233
+
234
+ // one sync at a time; a revision announced while one runs waits, and only the newest one runs
235
+ let running = false, next: WatchState | null = null, synced = 0;
236
+ const drain = async (): Promise<void> => {
237
+ running = true;
238
+ while (next !== null && !scope.disposed) {
239
+ const state = next; next = null;
240
+ try { await sync(state, synced++ === 0); } catch (cause) { fail(cause instanceof Error ? cause.message : String(cause)); }
241
+ }
242
+ running = false;
243
+ };
244
+ const receive = (data: unknown): void => {
245
+ report.steps.received = env.now();
246
+ let state: WatchState;
247
+ try { state = JSON.parse(String(data)) as WatchState; }
248
+ catch { fail('the watch server sent a message this page can\'t read'); return; }
249
+ // AP20: a full build of a revision this page already holds changes only the panel
250
+ if (state.revision === report.revision && report.revision > 0 && state.shell === shell) { report.build = state.build; show(); return; }
251
+ report.build = state.build;
252
+ if (state.wire !== WATCH_WIRE) { env.log(`wildshard watch: the server speaks wire ${state.wire}, this page ${WATCH_WIRE}; reloading`); env.reload(); return; }
253
+ if (shell !== null && state.shell !== shell) { env.log('wildshard watch: the spawn or a fixed look field changed; reloading'); env.reload(); return; }
254
+ shell = state.shell; next = state;
255
+ report.steps.seen = state.seenAt; report.steps.sent = state.sentAt;
256
+ if (!running) void drain();
257
+ };
258
+ const connect = (): void => {
259
+ if (scope.disposed) return;
260
+ const opened = env.socket(`${env.origin.replace(/^http/u, 'ws')}${WATCH_SOCKET}`);
261
+ socket = opened;
262
+ opened.onmessage = (event) => { receive(event.data); };
263
+ opened.onclose = () => { if (socket === opened && !scope.disposed) env.wait(1000, connect); };
264
+ };
265
+
266
+ const started = env.now();
267
+ const find = (): void => {
268
+ if (scope.disposed) return;
269
+ const found = env.hook();
270
+ if (found === undefined) {
271
+ if (env.now() - started > HOOK_WAIT_MS) { fail('the page never installed engine\'s dev hook: is this a devserver client?'); return; }
272
+ env.wait(250, find); return;
273
+ }
274
+ if (found.version !== DEV_HOOK_VERSION) { fail(`the page's dev hook is v${found.version}, this sdk drives v${DEV_HOOK_VERSION}: move the sdk and its engine pin together`); return; }
275
+ hook = found;
276
+ connect();
277
+ };
278
+ find();
279
+ return { report, stop: () => { scope.dispose(); const open = socket; socket = null; open?.close(); } };
280
+ }
281
+
282
+ /** A platform WebSocket as the page script's `SocketLike` (the browser's, or Node's in a test). */
283
+ export function socketOf(open: WebSocket): SocketLike {
284
+ const socket: SocketLike = { onmessage: null, onclose: null, close: () => { open.close(); } };
285
+ open.onmessage = (event) => { socket.onmessage?.({ data: event.data }); };
286
+ open.onclose = () => { socket.onclose?.(); };
287
+ return socket;
288
+ }
@@ -0,0 +1,44 @@
1
+ import { Scope } from '@wildshard/engine/app/scope';
2
+ import { installBrowserScopeEnvironment } from '@wildshard/engine/app/view/scopeEnvironment';
3
+ import { socketOf, startWatchPage, type DevHookLike, type WatchPageReport } from './page';
4
+ import { WATCH_RESHELL } from '@wildshard/sdk/watch/protocol';
5
+
6
+ // SHARD-SOURCE AP5: the browser entry `wildshard watch` bundles and injects into the page it serves (watch.ts `pageScript`).
7
+ // It is its own bundle beside the engine's, so it installs its own copy of the browser scope environment (frames, timers).
8
+ declare global { interface Window { __wildshardDevHook?: DevHookLike; __wsDevScene?: WatchPageReport; __wsShell?: number } }
9
+
10
+ installBrowserScopeEnvironment();
11
+ /** AP19, AP20: the watch panel, top left over the game (the vitals sit bottom left): what the last edit did, and the last full build's budget table. */
12
+ let held: HTMLElement | null = null;
13
+ const panel = (): HTMLElement => {
14
+ if (held !== null) return held;
15
+ const node = document.createElement('pre');
16
+ node.id = 'wildshard-watch';
17
+ Object.assign(node.style, { position: 'fixed', left: '8px', top: '8px', zIndex: '2147483000', margin: '0', padding: '6px 8px', maxWidth: '46ch',
18
+ font: '11px/1.35 ui-monospace, Menlo, monospace', color: '#e8f0e0', background: 'rgba(12, 16, 12, 0.72)', borderRadius: '4px', pointerEvents: 'none', whiteSpace: 'pre-wrap' });
19
+ // oxlint-disable-next-line wildshard/no-raw-hud, wildshard/no-global-listener-patch -- sharddev's own dev panel beside the game, not a game HUD; the page lives as long as it does
20
+ document.body.append(node);
21
+ held = node;
22
+ return node;
23
+ };
24
+ const entry = location.href;
25
+ const timers = new Scope('watch.entry');
26
+ const page = startWatchPage({
27
+ origin: location.origin,
28
+ hook: () => window.__wildshardDevHook,
29
+ fetch: (url) => fetch(url, { cache: 'no-store' }),
30
+ socket: (url) => socketOf(new WebSocket(url)),
31
+ // the next frame, or 250 ms if a page frame cap holds this script's frame back (NEW-SHARD-E2E F17)
32
+ frame: (run) => { let done = false; const once = (): void => { if (!done) { done = true; run(); } }; timers.raf(once); timers.timeout(250, once); },
33
+ wait: (ms, run) => { timers.timeout(ms, run); },
34
+ // the address the page opened at (`?skipintro`): the engine rewrites it once it boots, and a plain reload would land on the title.
35
+ // NEW-SHARD-E2E F18: under a new `devrev` too, since Chromium counts a same-URL replace as a reload, which the engine reads as
36
+ // the player's own and sends to the title
37
+ reload: () => { const next = new URL(entry); next.searchParams.set('devrev', String(Date.now())); location.replace(next.href); },
38
+ reshell: () => { void fetch(`${location.origin}${WATCH_RESHELL}`, { method: 'POST' }).catch((cause: unknown) => { console.error('wildshard watch: reshell', cause); }); },
39
+ now: () => Date.now(),
40
+ log: (message) => { console.error(message); },
41
+ shell: () => window.__wsShell ?? null,
42
+ overlay: (lines) => { panel().textContent = lines.join('\n'); },
43
+ });
44
+ window.__wsDevScene = page.report;
@@ -0,0 +1,22 @@
1
+ {
2
+ "note": "AP20: each camera's measured watch-against-build drift; parity.mjs --rebase writes it",
3
+ "source": "src/shards/authoring-slice",
4
+ "cameras": {
5
+ "hut-front": {
6
+ "mean": 2.155,
7
+ "share": 0.03402
8
+ },
9
+ "door-lamp": {
10
+ "mean": 4.239,
11
+ "share": 0.07664
12
+ },
13
+ "hut-back": {
14
+ "mean": 0.471,
15
+ "share": 0.00751
16
+ },
17
+ "pond": {
18
+ "mean": 3.499,
19
+ "share": 0.0484
20
+ }
21
+ }
22
+ }
@@ -0,0 +1,194 @@
1
+ // SHARD-SOURCE AP20: watch equals build. One scene source through both back ends, shot from the same fixed cameras:
2
+ //
3
+ // live `wildshard watch <source>`: the shell boots, then the page script draws every part through engine's dev hook
4
+ // build `wildshard dev <source>`: the full `wildshard build` (baked GLB tiles, the shardfile's look and terrain)
5
+ //
6
+ // Each camera's two frames are compared: the mean absolute difference per channel (out of 255) and the share of pixels off
7
+ // by more than 24 in any channel. The two back ends still differ where the shardfile back end lowers on purpose (a glowing
8
+ // material is the emissive family with no base colour, AP10's sorted transparency, AP11's billboards, AP28's lamps), so the
9
+ // guard is a ratchet: `parity-baseline.json` holds each camera's measured drift, and a camera over it by `MEAN` or `SHARE`
10
+ // is red. A fix that lowers the drift lowers the baseline (`--rebase`); nothing raises it unseen.
11
+ //
12
+ // node src/sharddev/watch/parity.mjs [--source <dir>] [--out <dir>] one comparison; exit 1 when red
13
+ // node src/sharddev/watch/parity.mjs --check sharddev's pre-push: the clean run must be green,
14
+ // and the live page with its roof colour halved (a
15
+ // planted material difference) must be red
16
+ // node src/sharddev/watch/parity.mjs --rebase write this run's drift as the baseline
17
+ //
18
+ // The page client is `$WILDSHARD_DEV_CLIENT` or the engine pin's devserver client (`wildshard dev`'s own). `--check` passes
19
+ // with one line saying why when that client has no dev hook this sdk drives (an engine pin from before hook v3). The servers
20
+ // and the browser are this script's: it ends them before it exits. Headless and muted.
21
+ // oxlint-disable-next-line import/no-nodejs-modules -- a node script: it runs `wildshard watch` and `wildshard dev` as children.
22
+ import { spawn } from 'node:child_process';
23
+ // oxlint-disable-next-line import/no-nodejs-modules -- it reads its baseline and writes the frames it shot.
24
+ import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
25
+ // oxlint-disable-next-line import/no-nodejs-modules -- paths from the repo root.
26
+ import { join, resolve } from 'node:path';
27
+ // oxlint-disable-next-line import/no-nodejs-modules -- its flags.
28
+ import { parseArgs } from 'node:util';
29
+ import { chromium } from "../../../scripts/browser-playwright.mjs";
30
+ import sharp from 'sharp';
31
+
32
+ const ROOT = resolve(import.meta.dirname, '../../..');
33
+ // SDK-SPLIT SP8c: the authoring slice is the sdk's sample shard; the bin is this (dev) package's.
34
+ const SDK = resolve(ROOT, '../sdk');
35
+ const { values } = parseArgs({ options: { source: { type: 'string' }, out: { type: 'string' }, check: { type: 'boolean' }, rebase: { type: 'boolean' } } });
36
+ const SOURCE = resolve(values.source ?? join(SDK, 'src/shards/authoring-slice'));
37
+ const BASELINE = join(import.meta.dirname, 'parity-baseline.json');
38
+ // The slice's own cameras (Mossgate cleanroom scripts/cameras.json): [id, x, z, yaw, pitch]
39
+ const CAMERAS = [['hut-front', -3.9, -5.6, 0.03, -0.04], ['door-lamp', -4.6, -7.8, 0.03, 0.05], ['hut-back', -3.9, -10.4, 3.4, -0.05], ['pond', -10.4, 0.3, 1.571, -0.08]];
40
+ /** The eye's height (m): the cameras' 1.68 m over the slice's ground, which is flat at 0 by every camera. */
41
+ const EYE = 1.68;
42
+ /** Red over the baseline by these, at any camera. Two clean runs differ by under 0.002/255; the planted roof adds over 1/255. */
43
+ const MEAN = 0.25, SHARE = 0.005, OFF = 24;
44
+
45
+ /** Start `wildshard <command> <source> 0` and resolve its page URL; `stop` kills the child. */
46
+ function serve(command) {
47
+ const child = spawn(process.execPath, [join(ROOT, 'bin/wildshard.mjs'), command, SOURCE, '0'], { cwd: SDK, stdio: ['ignore', 'pipe', 'pipe'] });
48
+ let log = '';
49
+ const url = new Promise((_resolve, _reject) => {
50
+ const read = (chunk) => {
51
+ log += String(chunk);
52
+ const found = /wildshard (?:watch|dev): (http:\/\/127\.0\.0\.1:\d+\/)/u.exec(log);
53
+ if (found !== null) _resolve(found[1]);
54
+ };
55
+ child.stdout.on('data', read); child.stderr.on('data', read);
56
+ child.on('exit', (code) => { _reject(new Error(`wildshard ${command} ended (${code}) before it served:\n${log.slice(-2000)}`)); });
57
+ });
58
+ return { url, stop: () => { if (child.exitCode === null) child.kill('SIGTERM'); } };
59
+ }
60
+
61
+ /** Each camera's frame, once the page stands still there; then, for each of `after`, the same after it runs in the page. */
62
+ async function shoot(browser, url, live, after = []) {
63
+ const page = await browser.newPage({ viewport: { width: 960, height: 540 } });
64
+ try {
65
+ await page.addInitScript({ content: 'window.__wildshardHarness=Object.assign(window.__wildshardHarness??{},{seed:357});' });
66
+ await page.goto(`${url}?skipintro`);
67
+ await page.waitForFunction((watched) => window.__wildshard?.world?.player !== undefined && (!watched || (window.__wsDevScene?.framedRevision ?? 0) > 0),
68
+ live, { timeout: 180_000, polling: 500 });
69
+ await page.evaluate(() => {
70
+ const w = window.__wildshard.world, camera = w.game.camera;
71
+ const lampUpdates = new WeakMap();
72
+ if (w.animals) w.animals.calm = true;
73
+ // the camera leaves the player (whose body stands where colliders put it, which this test does not compare): each
74
+ // frame it is set to the shot's eye, one field of view, no viewmodel
75
+ w.freeCamera = true;
76
+ w.game.onLate(() => {
77
+ const eye = window.__ap20Eye;
78
+ // Sample this static material fixture at one presentation instant.
79
+ // Capture mode holds the tier's render scale; pause holds scheduled
80
+ // systems. Water and lamp accumulators need their own explicit sample.
81
+ let water = 0, lamps = 0;
82
+ w.game.rootScene.traverse((object) => {
83
+ if (object.name.startsWith('water:') && object.material?.uniforms?.uTime !== undefined) {
84
+ object.material.uniforms.uTime.value = 5; water++;
85
+ }
86
+ if (object.name === 'look-light-lamps' && typeof object.update === 'function') {
87
+ let update = lampUpdates.get(object);
88
+ if (update === undefined) {
89
+ update = object.update.bind(object); lampUpdates.set(object, update);
90
+ // The built look updates after late; watch holds the original
91
+ // callback, so both the property and this late sample are needed.
92
+ object.update = () => { update(5); };
93
+ }
94
+ update(5); lamps++;
95
+ }
96
+ });
97
+ window.__ap20Phases = { water, lamps };
98
+ for (const child of camera.children) child.visible = false;
99
+ if (Math.abs(camera.fov - 72) > 0.01) { camera.fov = 72; camera.updateProjectionMatrix(); }
100
+ if (eye !== undefined) { camera.position.set(eye[0], eye[1], eye[2]); camera.rotation.set(eye[4], eye[3], 0, 'YXZ'); camera.updateMatrixWorld(true); }
101
+ w.game.app.clock.restore({ version: 1, elapsed: 5, wall: 5, frames: 300, captureFps: 60, paused: true, scale: 1 });
102
+ }, 'ap20.camera');
103
+ });
104
+ // the watch panel's timings and build table change from run to run: they are not the scene
105
+ await page.addStyleTag({ content: '#wildshard-watch { display: none !important; }' });
106
+ const sets = [];
107
+ for (const change of [null, ...after]) {
108
+ if (change !== null) await page.evaluate(change);
109
+ const frames = [];
110
+ for (const [id, x, z, yaw, pitch] of CAMERAS) {
111
+ await page.evaluate((eye) => { window.__ap20Eye = eye; }, [x, EYE, z, yaw, pitch]);
112
+ await page.waitForTimeout(2500);
113
+ const phases = await page.evaluate(() => window.__ap20Phases);
114
+ if (phases === undefined || phases.water < 1 || phases.lamps < 1) throw new Error('Parity scene lacks its controlled water or lamp presentation');
115
+ frames.push({ id, png: await page.screenshot() });
116
+ }
117
+ sets.push(frames);
118
+ }
119
+ return sets;
120
+ } finally { await page.close(); }
121
+ }
122
+
123
+ /** The planted difference: the live page's roof colour halved (page code, passed as text). */
124
+ const PLANT = `window.__wildshard.world.game.rootScene.getObjectByName('devScene')?.traverse((o) => { if (o.material?.name === 'roof') o.material.color.multiplyScalar(0.5); })`;
125
+
126
+ /** Two PNG frames compared, pixel by pixel. */
127
+ async function compare(a, b) {
128
+ const [p, q] = await Promise.all([a, b].map(async (png) => (await sharp(png).removeAlpha().raw().toBuffer())));
129
+ let sum = 0, offPixels = 0;
130
+ for (let i = 0; i < p.length; i += 3) {
131
+ let worst = 0;
132
+ for (let k = 0; k < 3; k++) { const d = Math.abs(p[i + k] - q[i + k]); sum += d; if (d > worst) worst = d; }
133
+ if (worst > OFF) offPixels++;
134
+ }
135
+ return { mean: Number((sum / p.length).toFixed(3)), share: Number((offPixels / (p.length / 3)).toFixed(5)) };
136
+ }
137
+
138
+ /** Both back ends, every camera: the clean comparison, and with `plant` the planted one too. */
139
+ async function run(plant, out) {
140
+ const live = serve('watch'), built = serve('dev');
141
+ const browser = await chromium.launch({ headless: true, args: ['--use-mock-keychain', '--password-store=basic', '--mute-audio', '--use-angle=metal', '--ignore-gpu-blocklist'] });
142
+ try {
143
+ const [liveUrl, builtUrl] = await Promise.all([live.url, built.url]);
144
+ const watched = await shoot(browser, liveUrl, true, plant ? [PLANT] : []), [baked] = await shoot(browser, builtUrl, false);
145
+ const baseline = readBaseline(), results = [];
146
+ for (const [n, frames] of watched.entries()) {
147
+ const rows = [];
148
+ for (const [i, frame] of frames.entries()) {
149
+ const score = await compare(frame.png, baked[i].png), base = baseline[frame.id] ?? { mean: 0, share: 0 };
150
+ rows.push({ id: frame.id, ...score, red: score.mean > base.mean + MEAN || score.share > base.share + SHARE });
151
+ if (out !== undefined) {
152
+ writeFileSync(join(out, `${n > 0 ? 'planted-' : ''}${frame.id}-watch.png`), frame.png);
153
+ if (n === 0) writeFileSync(join(out, `${frame.id}-build.png`), baked[i].png);
154
+ }
155
+ }
156
+ results.push({ rows, red: rows.some((row) => row.red) });
157
+ }
158
+ return results;
159
+ } finally { await browser.close(); live.stop(); built.stop(); }
160
+ }
161
+
162
+ function readBaseline() {
163
+ try { return JSON.parse(readFileSync(BASELINE, 'utf8')).cameras ?? {}; } catch { return {}; }
164
+ }
165
+
166
+ const line = (label, result) => `${label}: ${result.red ? 'RED' : 'green'} ${result.rows.map((row) => `${row.id} ${row.mean}/255 ${(row.share * 100).toFixed(2)}%${row.red ? ' (over its baseline)' : ''}`).join(', ')}`;
167
+ const out = values.out === undefined ? undefined : resolve(values.out);
168
+ if (out !== undefined) mkdirSync(out, { recursive: true });
169
+
170
+ async function main() {
171
+ let results;
172
+ try { results = await run(values.check === true, out); }
173
+ catch (cause) {
174
+ // an engine pin from before this sdk's dev hook serves no page watch can drive, and a machine with no client (offline, no
175
+ // release asset) or no browser has nothing to compare: the check says so and passes. Only a comparison goes red.
176
+ const message = cause instanceof Error ? cause.message : String(cause);
177
+ if (values.check !== true || !/dev hook|dev client|engine release .* has no|fetch failed|browserType\.launch/u.test(message)) throw cause;
178
+ console.info(`watch equals build: skipped, ${/(this engine client[^\n]*|the page's dev hook[^\n]*)/u.exec(message)?.[1] ?? message.split('\n')[0]}`);
179
+ return;
180
+ }
181
+ const [clean, planted] = results;
182
+ console.info(line('watch equals build', clean));
183
+ if (out !== undefined) writeFileSync(join(out, 'parity.json'), `${JSON.stringify(results, null, 2)}\n`);
184
+ if (values.rebase === true) {
185
+ writeFileSync(BASELINE, `${JSON.stringify({ note: 'AP20: each camera\'s measured watch-against-build drift; parity.mjs --rebase writes it', source: 'src/shards/authoring-slice',
186
+ cameras: Object.fromEntries(clean.rows.map((row) => [row.id, { mean: row.mean, share: row.share }])) }, null, 2)}\n`);
187
+ console.info(`wrote ${BASELINE}`);
188
+ } else if (clean.red) { console.error('watch equals build: the two back ends drifted past the baseline (parity.mjs --out <dir> writes the frames)'); process.exitCode = 1; }
189
+ if (planted !== undefined) {
190
+ console.info(line('planted roof difference', planted));
191
+ if (!planted.red) { console.error('watch equals build: a planted material difference went unseen'); process.exitCode = 1; }
192
+ }
193
+ }
194
+ await main();