@wildshard/engine 0.1.15 → 0.1.18

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 (262) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/index.html +157 -11
  3. package/lint/engine-sides.json +23 -0
  4. package/lint/host-callback-syntax.mjs +2 -1
  5. package/lint/host-callbacks.mjs +3 -3
  6. package/lint/host-files.mjs +5 -4
  7. package/lint/host-register.json +496 -0
  8. package/lint/no-base64.mjs +3 -1
  9. package/lint/ratchet.json +2 -2
  10. package/lint/shard-imports.d.mts +1 -0
  11. package/lint/shard-imports.mjs +60 -13
  12. package/lint/shard-source.d.mts +9 -0
  13. package/lint/shard-source.mjs +91 -0
  14. package/lint/shardfile-boundaries.mjs +10 -8
  15. package/lint/sim-closure.mjs +6 -3
  16. package/lint/wildshard-plugin.d.ts +4 -0
  17. package/lint/wildshard-plugin.js +44 -27
  18. package/package.json +24 -6
  19. package/scripts/app-build/buildIdentity.d.mts +3 -1
  20. package/scripts/app-build/buildIdentity.mjs +25 -5
  21. package/scripts/app-build/builtAt.d.mts +4 -0
  22. package/scripts/app-build/builtAt.mjs +21 -0
  23. package/scripts/app-build/outputProducts.d.mts +3 -0
  24. package/scripts/app-build/outputProducts.mjs +31 -0
  25. package/scripts/app-build/serviceWorker.ts +16 -2
  26. package/scripts/app-build/versionFiles.ts +2 -1
  27. package/scripts/app-build-pipeline.mjs +7 -1
  28. package/scripts/audio-download-proof.mjs +843 -0
  29. package/scripts/build-app.mjs +4 -0
  30. package/scripts/build-mirror.d.mts +2 -0
  31. package/scripts/build-mirror.mjs +5 -4
  32. package/scripts/built-product.mjs +3 -3
  33. package/scripts/cell-mem/metrics-preload.mjs +65 -0
  34. package/scripts/cell-mem-bench.mjs +130 -0
  35. package/scripts/check-chunks.mjs +2 -1
  36. package/scripts/check-devserver.mjs +1 -1
  37. package/scripts/chromium-keychain-check.mjs +4 -2
  38. package/scripts/chromium-keychain.mjs +3 -1
  39. package/scripts/cook.mjs +7 -3
  40. package/scripts/devices.d.mts +4 -0
  41. package/scripts/devices.mjs +39 -0
  42. package/scripts/devserver-client.d.mts +7 -0
  43. package/scripts/devserver-client.mjs +85 -0
  44. package/scripts/doctor-proof.mjs +1 -1
  45. package/scripts/e2e-faults.mjs +159 -0
  46. package/scripts/engine-ci-budget.ts +7 -1
  47. package/scripts/format-lock.mjs +20 -11
  48. package/scripts/generate-title-launch.mjs +3 -2
  49. package/scripts/grid-crossing-walk-proof.mjs +30 -11
  50. package/scripts/heavy-lane.py +25 -1
  51. package/scripts/host-ruler/register-migrate.mjs +242 -0
  52. package/scripts/host-ruler/register.d.mts +36 -0
  53. package/scripts/host-ruler/register.mjs +116 -0
  54. package/scripts/host-ruler/roots.d.mts +29 -0
  55. package/scripts/host-ruler/roots.mjs +333 -0
  56. package/scripts/host-ruler/server-roots.d.mts +23 -0
  57. package/scripts/host-ruler/server-roots.mjs +272 -0
  58. package/scripts/main-watch.d.mts +1 -1
  59. package/scripts/main-watch.mjs +10 -6
  60. package/scripts/map-hash.mjs +3 -6
  61. package/scripts/memory-proof.mjs +158 -0
  62. package/scripts/mmo-bots.mjs +2 -2
  63. package/scripts/offline-proof-rules.d.mts +5 -2
  64. package/scripts/offline-proof-rules.mjs +43 -6
  65. package/scripts/offline-proof.mjs +15 -6
  66. package/scripts/online-rig.mjs +4 -4
  67. package/scripts/page-release/flow.d.mts +1 -0
  68. package/scripts/page-release/flow.mjs +6 -2
  69. package/scripts/page-release.mjs +5 -1
  70. package/scripts/physics-route.json +0 -71
  71. package/scripts/pins-catalogue.ts +103 -0
  72. package/scripts/pins-reuse.mjs +3 -1
  73. package/scripts/pins.ts +22 -14
  74. package/scripts/preview-grid.ts +203 -0
  75. package/scripts/road-preload-proof.mjs +167 -0
  76. package/scripts/server-release/publish.mjs +2 -2
  77. package/scripts/server-release/served-slug.d.mts +2 -0
  78. package/scripts/server-release/served-slug.mjs +10 -0
  79. package/scripts/server-release/sign.d.mts +1 -0
  80. package/scripts/server-release/sign.mjs +3 -7
  81. package/scripts/shard-components.mjs +0 -2
  82. package/scripts/shard-outputs.d.mts +8 -0
  83. package/scripts/shard-outputs.mjs +45 -11
  84. package/scripts/side-parity.d.mts +2 -1
  85. package/scripts/side-parity.mjs +25 -4
  86. package/scripts/test-amber.d.mts +1 -0
  87. package/scripts/test-amber.mjs +10 -0
  88. package/scripts/test-products.json +3 -3
  89. package/scripts/tier-textures-proof.mjs +101 -0
  90. package/scripts/tier-textures.mjs +60 -0
  91. package/scripts/tracked-public.d.mts +1 -0
  92. package/scripts/tracked-public.mjs +17 -0
  93. package/scripts/tsconfig.json +1 -0
  94. package/scripts/vps/wildshard-config +79 -23
  95. package/scripts/worker-client-play.mjs +1 -0
  96. package/scripts/worker-client-proof.mjs +1 -1
  97. package/scripts/worker-client-slug.mjs +44 -0
  98. package/src/cli/engine.mjs +8 -0
  99. package/src/client/app/bootRoute.ts +4 -1
  100. package/src/client/app/dropModal.ts +15 -2
  101. package/src/client/app/entry.ts +96 -13
  102. package/src/client/app/slugPath.ts +5 -0
  103. package/src/client/engine/audio/Audio.ts +20 -2
  104. package/src/client/engine/boot/bakedTextures.ts +3 -2
  105. package/src/client/engine/boot/bootTrace.ts +6 -1
  106. package/src/client/engine/boot/bytes.ts +4 -3
  107. package/src/client/engine/boot/clearDownloads.ts +1 -1
  108. package/src/client/engine/boot/contentRead.ts +4 -0
  109. package/src/client/engine/boot/dropNotice.ts +20 -6
  110. package/src/client/engine/boot/gpuFiles.ts +25 -2
  111. package/src/client/engine/boot/lastEnd.ts +8 -2
  112. package/src/client/engine/boot/parsedPages.ts +127 -58
  113. package/src/client/engine/boot/shardPrefetch.ts +7 -1
  114. package/src/client/engine/boot/sw.ts +19 -0
  115. package/src/client/engine/build.d.ts +2 -0
  116. package/src/client/engine/core/Game.ts +29 -3
  117. package/src/client/engine/core/GpuRecovery.ts +7 -0
  118. package/src/client/engine/core/Volumetrics.ts +5 -0
  119. package/src/client/engine/core/assets.ts +27 -20
  120. package/src/client/engine/core/bootstrap.ts +5 -3
  121. package/src/client/engine/core/ktx2.ts +84 -11
  122. package/src/client/engine/debug/probe.ts +18 -1
  123. package/src/client/engine/explore/Compare.ts +2 -2
  124. package/src/client/engine/explore/TouchFly.ts +3 -5
  125. package/src/client/engine/fx/LightPool.ts +41 -1
  126. package/src/client/engine/input/dom.ts +12 -0
  127. package/src/client/engine/net/predictor.ts +6 -2
  128. package/src/client/engine/player/Player.ts +10 -2
  129. package/src/client/engine/player/TouchControls.ts +12 -4
  130. package/src/client/engine/pwa/sw.js +59 -11
  131. package/src/client/engine/render/drawCheck.ts +96 -0
  132. package/src/client/engine/render/precompile.ts +20 -14
  133. package/src/client/engine/saves/staleBuildNote.ts +46 -0
  134. package/src/client/engine/telemetry/browserErrors.ts +161 -21
  135. package/src/client/engine/telemetry/deviceSnapshot.ts +155 -0
  136. package/src/client/engine/telemetry/screenOutbox.ts +61 -0
  137. package/src/client/engine/telemetry/staleBuildReport.ts +12 -0
  138. package/src/client/engine/ui/DeathFade.ts +99 -11
  139. package/src/client/engine/ui/ErrorModal.ts +13 -6
  140. package/src/client/engine/ui/Feedback.ts +2 -1
  141. package/src/client/engine/ui/Loading.ts +10 -6
  142. package/src/client/engine/ui/Map.ts +2 -1
  143. package/src/client/engine/ui/WeaponStrip.ts +2 -1
  144. package/src/client/engine/ui/backGuard.ts +104 -0
  145. package/src/client/engine/ui/hudAdapters.ts +30 -4
  146. package/src/client/engine/ui/loading.css +17 -0
  147. package/src/client/engine/ui/namePrompt.ts +6 -5
  148. package/src/client/engine/ui/styles/combat.css +12 -0
  149. package/src/client/engine/ui/styles/namePrompt.css +4 -2
  150. package/src/client/game/boot/audio.generated.ts +0 -396
  151. package/src/client/game/boot/bytes.generated.ts +42 -71
  152. package/src/client/game/boot/versions.generated.ts +0 -13
  153. package/src/client/game/compendium/keepsakes.ts +16 -6
  154. package/src/client/game/grapple/tool.ts +10 -7
  155. package/src/client/game/grid/area.ts +38 -0
  156. package/src/client/game/grid/cellLoading.ts +23 -12
  157. package/src/client/game/grid/cellScreens.ts +39 -74
  158. package/src/client/game/grid/live.ts +28 -2
  159. package/src/client/game/grid/liveSession.ts +54 -10
  160. package/src/client/game/grid/menu.ts +4 -0
  161. package/src/client/game/grid/nearPlaceholderPlan.ts +8 -0
  162. package/src/client/game/grid/nearPlaceholderView.ts +9 -3
  163. package/src/client/game/grid/neighbourPanels.ts +10 -1
  164. package/src/client/game/grid/oneWayIn.ts +92 -27
  165. package/src/client/game/grid/pageEntry.ts +19 -0
  166. package/src/client/game/grid/pageShell.ts +1 -1
  167. package/src/client/game/grid/placedCards.ts +55 -0
  168. package/src/client/game/grid/placedCells.ts +131 -0
  169. package/src/client/game/grid/plotAudio.ts +114 -0
  170. package/src/client/game/grid/products.ts +55 -5
  171. package/src/client/game/grid/regionalRuntime.ts +6 -0
  172. package/src/client/game/grid/regionalWorld.ts +15 -2
  173. package/src/client/game/grid/roadCull.ts +44 -14
  174. package/src/client/game/grid/roadLookPlatform.ts +2 -2
  175. package/src/client/game/grid/roadTileBacking.ts +13 -3
  176. package/src/client/game/grid/session.ts +47 -22
  177. package/src/client/game/grid/shardfileFar.ts +9 -3
  178. package/src/client/game/grid/spawnGround.ts +68 -0
  179. package/src/client/game/grid/voidLook.ts +29 -23
  180. package/src/client/game/loot/runtime.ts +3 -1
  181. package/src/client/game/mainMenu.ts +14 -6
  182. package/src/client/game/riding/hud.ts +6 -4
  183. package/src/client/game/session/finish.ts +22 -4
  184. package/src/client/game/session/play.ts +8 -2
  185. package/src/client/game/session/session.ts +4 -1
  186. package/src/client/game/shard/titleList.ts +6 -2
  187. package/src/client/game/shardfile/clientWorker.ts +43 -13
  188. package/src/client/game/shardfile/serverRoute.ts +10 -22
  189. package/src/client/game/slugPage.css +11 -0
  190. package/src/client/game/slugPage.ts +84 -0
  191. package/src/client/game/systems/viewmodel/heldView.ts +6 -3
  192. package/src/client/game/titleDeck.ts +56 -32
  193. package/src/client/host/online/doctor.ts +7 -6
  194. package/src/client/host/online/linkScreens.ts +16 -0
  195. package/src/client/host/online/release.ts +51 -5
  196. package/src/client/host/online/shell.ts +62 -27
  197. package/src/client/host/standalone/shell.ts +7 -3
  198. package/src/cook/game/audioReport.ts +57 -0
  199. package/src/cook/game/entryTotals.ts +26 -6
  200. package/src/cook/game/installedRuntimeReads.ts +3 -0
  201. package/src/cook/game/shardCook.ts +38 -8
  202. package/src/cook/game/tierTextures.ts +276 -0
  203. package/src/e2e/smoke/game.ts +19 -14
  204. package/src/e2e/smoke/page-globals.d.ts +9 -8
  205. package/src/e2e/smoke/template2.spec.ts +8 -7
  206. package/src/server/engine/sim/respawn.ts +6 -1
  207. package/src/server/engine/sim.ts +3 -0
  208. package/src/server/game/grid/simulation.ts +35 -0
  209. package/src/server/game/loot/harvest.ts +2 -0
  210. package/src/server/game/loot/keepsakeProgression.ts +40 -0
  211. package/src/server/game/loot/playerOwned.ts +5 -1
  212. package/src/server/game/plugin/simulation.ts +4 -0
  213. package/src/server/game/population/nativeBake.ts +2 -1
  214. package/src/server/game/quest/chapterRecords.ts +2 -0
  215. package/src/server/game/quest/serverChapters.ts +4 -0
  216. package/src/server/game/quest/serverDoors.ts +11 -5
  217. package/src/server/game/roomRespawn.ts +4 -0
  218. package/src/server/game/shardfile/installedSides.ts +18 -0
  219. package/src/server/game/shardfile/nativeAssemblyHosts.ts +19 -10
  220. package/src/server/game/shardfile/nativeAssemblyInput.ts +1 -4
  221. package/src/server/host/bake/headlessWorker.ts +5 -1
  222. package/src/server/host/dedicated/cellHost.ts +98 -29
  223. package/src/server/host/dedicated/cellProtocol.ts +11 -1
  224. package/src/server/host/dedicated/cellWorker.ts +9 -3
  225. package/src/server/host/dedicated/crossing.ts +6 -2
  226. package/src/server/host/dedicated/dedicatedRoom.ts +21 -8
  227. package/src/server/host/dedicated/gridCells.ts +52 -9
  228. package/src/server/host/dedicated/main.ts +31 -12
  229. package/src/server/host/dedicated/placementFile.ts +56 -0
  230. package/src/server/host/dedicated/releaseFile.ts +17 -10
  231. package/src/server/host/dedicated/roadRoom.ts +21 -5
  232. package/src/server/host/dedicated/socketTransport.ts +2 -1
  233. package/src/server/host/dedicated/workerTable.ts +13 -1
  234. package/src/server/host/dedicated/world.ts +111 -10
  235. package/src/server/host/headlessRuntime.ts +10 -5
  236. package/src/server/host/installers.ts +62 -0
  237. package/src/server/host/openWorld.ts +59 -0
  238. package/src/server/host/ropeDecks.ts +2 -0
  239. package/src/server/host/standalone/cellWorld.ts +25 -19
  240. package/src/server/host/standalone/fallFloor.ts +2 -2
  241. package/src/server/host/standalone/gridServer.ts +7 -4
  242. package/src/server/host/standalone/roadWorld.ts +41 -4
  243. package/src/shared/engine/audio/bootAudio.ts +33 -0
  244. package/src/shared/engine/level/spec.ts +3 -3
  245. package/src/shared/engine/net/acts.ts +3 -0
  246. package/src/shared/engine/net/deviceWord.ts +138 -0
  247. package/src/shared/engine/net/socketFrames.ts +7 -4
  248. package/src/shared/engine/physics/query.ts +27 -0
  249. package/src/shared/engine/physics/terrain.ts +19 -28
  250. package/src/shared/engine/saves/saves.lock.json +15 -0
  251. package/src/shared/engine/sim/actRoutes.ts +2 -0
  252. package/src/shared/game/compendium/keepsakeProgression.ts +24 -0
  253. package/src/shared/game/grid/catalogue.ts +12 -5
  254. package/src/shared/game/grid/catalogueSlot.ts +18 -0
  255. package/src/shared/game/grid/farProxy.ts +6 -5
  256. package/src/shared/game/grid/pageMode.ts +1 -1
  257. package/src/shared/game/grid/placementRows.ts +33 -0
  258. package/src/shared/game/grid/roadLayout.ts +26 -3
  259. package/src/shared/game/grid/singleplayer.json +0 -13
  260. package/src/shared/game/grid/voidFloor.ts +122 -0
  261. package/src/shared/game/strings.ts +15 -0
  262. package/src/shared/host/standalone/netInput.ts +2 -1
@@ -45,7 +45,7 @@ import { SHADOW_LAYER } from './shadowLayer';
45
45
  import { WorldRenderPass } from './worldDepth';
46
46
  import { ownComposerDepth } from '../render/composerDepth';
47
47
  import { noteDrawnEnvironment } from '../render/drawnEnvironment';
48
- import { makeSystem, setLoopState, systemFault, type GameSystem } from '../../../shared/engine/core/faults';
48
+ import { emitFault, makeSystem, setLoopState, systemFault, type GameSystem } from '../../../shared/engine/core/faults';
49
49
  import { frameCost } from '../../../shared/engine/core/frameCost';
50
50
  import { sustainedFrames } from './sustainedFrames';
51
51
  import { diagnosticNow } from '../../../shared/engine/core/clock';
@@ -63,6 +63,7 @@ import { duringShadowPass } from '../world/cascadeCull';
63
63
  import { recordGpuCheckpoint, traceBootPasses } from '../boot/gpuTrace';
64
64
  import { exploreEntryPending, recordExploreFrame, recordBootCheckpoint, bootTraceActive } from '../boot/bootTrace';
65
65
  import { cullPlaced } from '../models/place';
66
+ import { DrawCheck, hdrTargetType } from '../render/drawCheck';
66
67
 
67
68
  /** the world's pace during a hit-stop (not 0: nothing downstream has to cope with a zero dt) */
68
69
  const HIT_STOP_SCALE = 0.04;
@@ -393,6 +394,12 @@ export class Game {
393
394
  updateMs: Float32Array<ArrayBuffer> = new Float32Array(120); renderMs: Float32Array<ArrayBuffer> = new Float32Array(120);
394
395
  /** frames drawn since start() */
395
396
  frameCount = 0;
397
+ /** QA 2026-11-13 row 6: two reads after the first frames that make a world drawing nothing loud (render/drawCheck.ts) */
398
+ private readonly drawCheck = new DrawCheck({
399
+ renderer: { getContext: () => this.renderer.getContext(), getRenderTarget: () => this.renderer.getRenderTarget(), setRenderTarget: (t) => { this.renderer.setRenderTarget(t); } },
400
+ target: () => { const t: unknown = this._composer === null ? null : Reflect.get(this._composer, 'inputBuffer'); return t instanceof THREE.WebGLRenderTarget ? t : null; },
401
+ report: (error, certain) => { emitFault({ system: 'render.blank', error, verdict: certain ? 'fatal' : 'uncaught' }); },
402
+ });
396
403
  /** Browser rAF timestamp of the last completed draw; null for the initial synchronous draw.
397
404
  * Cadence reads this delivered-frame clock; callback-start work and polling use separate clocks. */
398
405
  frameRafTime: number | null = null;
@@ -684,7 +691,7 @@ export class Game {
684
691
  */
685
692
  private replaceComposer(R: ReplaceLook): EffectComposer {
686
693
  const msaa = TIER_CONFIG.smaa === 'off' ? 0 : this.renderKnobs().msaa ?? 0;
687
- const composer = new EffectComposer(this.renderer, { frameBufferType: THREE.HalfFloatType, multisampling: Math.min(msaa, this.renderer.capabilities.maxSamples) });
694
+ const composer = new EffectComposer(this.renderer, { frameBufferType: hdrTargetType(this.renderer), multisampling: Math.min(msaa, this.renderer.capabilities.maxSamples) });
688
695
  ownComposerDepth(composer);
689
696
  const scope = this.levelScope.child('look');
690
697
  const { chain } = R.compose({ app: this.app, scope, debug: { expose: (name, value) => { scope.onDispose(this.app.debug.scopedExpose(name, value)); } }, renderer: this.renderer, scene: this.rootScene, camera: this.camera, composer, tier: TIER });
@@ -704,7 +711,7 @@ export class Game {
704
711
  if (this.lookStrategy?.mode === 'replace') { this._composer = this.replaceComposer(this.lookStrategy); return; } // the level look's whole chain
705
712
  const { atmosphere: A } = this.level;
706
713
  const { grade: G, look } = this.app.gradeFor({ grade: this.level.grade, ...(this.level.lookLayer === undefined ? {} : { look: this.level.lookLayer }) }); // + the look loop's layer (PH-L1 / L4)
707
- const composer = new EffectComposer(this.renderer, { frameBufferType: THREE.HalfFloatType, multisampling: 0 });
714
+ const composer = new EffectComposer(this.renderer, { frameBufferType: hdrTargetType(this.renderer), multisampling: 0 });
708
715
  ownComposerDepth(composer);
709
716
  // the scene pass keeps the world's depth for the depth readers below (AO, the volumetric march, the god rays' sun mask):
710
717
  // the viewmodels' depth clear used to leave them the weapon alone (worldDepth.ts)
@@ -1215,6 +1222,24 @@ export class Game {
1215
1222
  }
1216
1223
  }
1217
1224
 
1225
+ /**
1226
+ * RP4: link the road (exterior) variants of an entered grid cell's content, as the boot's entry roots' are
1227
+ * (`warmDeferredEntryRoots`: nearest first, spaced by drawn frames, dropped once `owner` leaves). Past its sky layer's half
1228
+ * weight the road draws the cell with the page's own environment (none on a grid page), not the cell's PMREM: without
1229
+ * these, every program of the cell linked in one frame 2 m before its edge (Driftwood's west edge: about 17 links, 2.5 to
1230
+ * 4.3 s in Chromium). `roots` are not registered exterior roots (those are left out of the road's variants).
1231
+ */
1232
+ async warmExteriorRoots(owner: Scope, roots: readonly THREE.Object3D[], current: () => boolean): Promise<void> {
1233
+ this.deferredEntryRoots.push({ owner, roots });
1234
+ if (this.frameCount === 0) return; // the boot's own in-play warm-up takes it (finish.ts)
1235
+ // one loop at a time: a second entry joins the queue behind the first, never a parallel warm-up in the same frames
1236
+ const run = this.exteriorWarm.catch(() => undefined).then(() => this.warmDeferredEntryRoots(current));
1237
+ this.exteriorWarm = run;
1238
+ await run;
1239
+ }
1240
+ /** RP4: the running road-variant warm-up (`warmExteriorRoots`), which the next one waits behind */
1241
+ private exteriorWarm: Promise<void> = Promise.resolve();
1242
+
1218
1243
  /**
1219
1244
  * D188 (G815): after an arrival's reveal, what it left (`rest`, gated out of live draws) is linked and first-drawn
1220
1245
  * nearest the player first: the whole remaining program inventory under the live slice budget, then the rest's 1×1
@@ -1784,6 +1809,7 @@ export class Game {
1784
1809
  this.workMs[this.frameI] = work;
1785
1810
  this.frameRafTime = now ?? null;
1786
1811
  this.frameCount++;
1812
+ this.drawCheck.afterDraw(this.frameCount); // QA 2026-11-13 row 6: a world that draws nothing is reported (drawCheck.ts)
1787
1813
  this.updateMs[this.frameI] = renderAt - lastRun; this.renderMs[this.frameI] = done - renderAt;
1788
1814
  if (on) frameCost.end(realDt * 1000, renderAt - lastRun, done - renderAt, cap > 0 ? 1000 / cap : 0);
1789
1815
  // QA row 31: play's sustained fps (a paused game's frames are not play)
@@ -37,6 +37,7 @@ import { gpuOnlyContent, rebakeGpuContent } from './gpuOnly';
37
37
  import { emitFault } from '../../../shared/engine/core/faults';
38
38
  import { recordGpuRecovery } from '../boot/bootTrace';
39
39
  import { leaveSaved, markReload } from '../boot/lastEnd';
40
+ import { gpuSummary } from '../render/drawCheck';
40
41
 
41
42
  const savedStorage = saveStorage('session');
42
43
 
@@ -73,6 +74,8 @@ export function installGpuRecovery(host: RecoveryHost): void {
73
74
  const canvas = game.renderer.domElement;
74
75
  if (canvas !== game.canvas) return; // an offscreen canvas of our own, not the one the player sees
75
76
  const gl = game.renderer.getContext();
77
+ let lostGpu = 'GPU unknown'; // read while the context lives: a lost one answers nothing
78
+ try { lostGpu = gpuSummary(gl); } catch { /* the summary is a courtesy */ }
76
79
 
77
80
  let phase: Phase = 'ok';
78
81
  let hidden = document.visibilityState === 'hidden';
@@ -129,6 +132,10 @@ export function installGpuRecovery(host: RecoveryHost): void {
129
132
  game.hold = true;
130
133
  document.dispatchEvent(new Event('ws:background'));
131
134
  console.warn(`[gl] ${why}: holding the frame loop`);
135
+ // QA 2026-11-13 row 6 (Android Chrome: the world went black after a jump): a loss in front of the player reaches
136
+ // Sentry with the GPU that lost it (one behind a hidden page is the iOS app switch: routine, not reported). Time
137
+ // still never reloads: only a confirmed wipe or failed restore does (gpu-recovery-conditions.test.ts)
138
+ if (!hidden) emitFault({ system: 'gpu-recovery', error: new Error(`WebGL context lost (${why}) · ${lostGpu}`), verdict: 'retry' });
132
139
  // the GPU process died (every canvas wiped): nothing to restore in place — do not wait for the restore event
133
140
  if (canvasesWiped()) reload('the GPU process restarted: every canvas was wiped');
134
141
  };
@@ -6,6 +6,7 @@ import {
6
6
  } from 'three';
7
7
  import { fogUniforms, volumetricFog } from '../world/Atmosphere';
8
8
  import type { Renderer } from '../render/renderer';
9
+ import { fitHdrTarget } from '../render/drawCheck';
9
10
 
10
11
  /** the march's uniforms, typed per slot so the per-frame `.value.copy(...)` calls are checked */
11
12
  interface MarchUniforms {
@@ -216,6 +217,7 @@ export class VolumetricsEffect extends Effect {
216
217
  targetSize(): readonly [number, number] | null { return this.renderTarget === null ? null : [this.renderTarget.width, this.renderTarget.height]; }
217
218
  /** Compile the separate march's program now (a page that adds this effect late warms it at install, not at first use). */
218
219
  warm(renderer: Renderer): void {
220
+ if (this.renderTarget) fitHdrTarget(renderer, this.renderTarget); // QA 2026-11-13 row 6: 8-bit where half float cannot be drawn into
219
221
  if (this.marchScene === null || this.renderTarget === null) return;
220
222
  // Output colour space / tone mapping participate in the key even for a raw ShaderMaterial.
221
223
  // Compile in the march's real target, as update() draws it, rather than the current canvas.
@@ -224,6 +226,8 @@ export class VolumetricsEffect extends Effect {
224
226
  finally { renderer.setRenderTarget(previous); }
225
227
  }
226
228
 
229
+ /** fitHdrTarget ran on the light-ray target (once: the GPU does not change under a renderer) */
230
+ private fitted = false;
227
231
  override update(renderer: Renderer, inputBuffer?: WebGLRenderTarget): void {
228
232
  // an effect added to a pass after its last resize (a page's late install) takes its size from the frame it composites
229
233
  if (inputBuffer !== undefined && (inputBuffer.width !== this.size.width || inputBuffer.height !== this.size.height)) this.setSize(inputBuffer.width, inputBuffer.height);
@@ -238,6 +242,7 @@ export class VolumetricsEffect extends Effect {
238
242
  u.uDensity.value = DENSITY;
239
243
  u.uFrame.value = (this.frame++ % 64);
240
244
  if (this.renderTarget && this.marchMat && this.marchScene && !this.parked) {
245
+ if (!this.fitted) { fitHdrTarget(renderer, this.renderTarget); this.fitted = true; }
241
246
  this.nearU.value = cam.near; this.farU.value = cam.far;
242
247
  const prev = renderer.getRenderTarget();
243
248
  renderer.setRenderTarget(this.renderTarget);
@@ -5,7 +5,8 @@ import type { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
5
5
  import { prepareRigLoader } from '../anim/rig';
6
6
  import { HDRLoader } from 'three/examples/jsm/loaders/HDRLoader.js';
7
7
  import { fetchImage, tierUrl } from '../boot/bytes';
8
- import { initKtx2, ktx2Layers, ktx2Texture, linearKtx2Texture, prepareCompressedTexture, releaseAfterUpload } from './ktx2';
8
+ import type { ContentReadOptions } from '../boot/contentRead';
9
+ import { cacheHolds, heldForm, initKtx2, ktx2Layers, ktx2Texture, linearKtx2Texture, prepareCompressedTexture, readHeldForm, releaseAfterUpload } from './ktx2';
9
10
  import { TIER_CONFIG } from './tier';
10
11
  import { workSlice } from '../../../shared/engine/core/workSlice';
11
12
  import type { Renderer } from '../render/renderer';
@@ -61,13 +62,14 @@ export function decodedImageCount(): number {
61
62
  for (const [key, image] of images) if (image.deref() === undefined) images.delete(key);
62
63
  return images.size + imageLoads.size;
63
64
  }
64
- export function loadImage(url: string, maxSize: number = TIER_CONFIG.maxTexture): Promise<ImageBitmap | HTMLImageElement> {
65
+ /** `instead` (OF17): see fetchImage — a failed read may throw rather than wait on RETRY */
66
+ export function loadImage(url: string, maxSize: number = TIER_CONFIG.maxTexture, instead?: ContentReadOptions['instead']): Promise<ImageBitmap | HTMLImageElement> {
65
67
  const key = imageKey(url, maxSize);
66
68
  const image = images.get(key)?.deref();
67
69
  if (image !== undefined) return Promise.resolve(image);
68
70
  const pending = imageLoads.get(key);
69
71
  if (pending !== undefined) return pending;
70
- const load = fetchImage(url, maxSize).then(decoded => {
72
+ const load = fetchImage(url, maxSize, true, false, instead).then(decoded => {
71
73
  images.set(key, new WeakRef(decoded));
72
74
  return decoded;
73
75
  }).finally(() => { imageLoads.delete(key); });
@@ -108,7 +110,7 @@ function shareSource(owned: THREE.TextureSource<unknown>, flipY: boolean, key: s
108
110
  /** Register all source users before their awaiting callers may upload. A warm
109
111
  * image is acquired synchronously, so no caller can borrow a bitmap closed
110
112
  * during an intervening await. In-flight source ownership ends on settlement. */
111
- function loadTextureSource(url: string, srgb: boolean, maxSize: number): Promise<SharedSource> {
113
+ function loadTextureSource(url: string, srgb: boolean, maxSize: number, instead?: ContentReadOptions['instead']): Promise<SharedSource> {
112
114
  const key = imageKey(url, maxSize), shared = sourceKey(key, srgb);
113
115
  const make = (image: ImageBitmap | HTMLImageElement): SharedSource => {
114
116
  const source = new THREE.TextureSource(image), flipY = !(typeof ImageBitmap !== 'undefined' && image instanceof ImageBitmap);
@@ -119,7 +121,7 @@ function loadTextureSource(url: string, srgb: boolean, maxSize: number): Promise
119
121
  if (pending !== undefined) return pending;
120
122
  const decoding = imageLoads.get(key), image = images.get(key)?.deref();
121
123
  if (decoding === undefined && image !== undefined) return Promise.resolve(make(image));
122
- const loading = (decoding ?? loadImage(url, maxSize)).then(make);
124
+ const loading = (decoding ?? loadImage(url, maxSize, instead)).then(make);
123
125
  sourceLoads.set(shared, loading);
124
126
  const settled = (): void => { if (sourceLoads.get(shared) === loading) sourceLoads.delete(shared); };
125
127
  void loading.then(settled, settled);
@@ -133,9 +135,8 @@ function loadTextureSource(url: string, srgb: boolean, maxSize: number): Promise
133
135
  */
134
136
  export async function loadTexture(url: string, srgb = false, repeat = 1, maxSize: number = TIER_CONFIG.maxTexture,
135
137
  configure?: (texture: THREE.Texture) => void): Promise<THREE.Texture> {
136
- // E157: the KTX2 stand-in, when the build has one and KTX2 is on; on the image fallback, a linear file's ASTC stand-in (src/client/engine/core/ktx2.ts)
137
- const k = await ktx2Texture(tierUrl(url), maxSize) ?? (srgb ? null : await linearKtx2Texture(tierUrl(url), maxSize));
138
- if (k) {
138
+ const served = tierUrl(url);
139
+ const compressed = (k: THREE.CompressedTexture): Promise<THREE.Texture> => {
139
140
  k.wrapS = k.wrapT = THREE.RepeatWrapping;
140
141
  k.repeat.set(repeat, repeat);
141
142
  k.anisotropy = maxAniso;
@@ -143,19 +144,17 @@ export async function loadTexture(url: string, srgb = false, repeat = 1, maxSize
143
144
  k.needsUpdate = true;
144
145
  configure?.(k);
145
146
  return prepareCompressedTexture(labelAsset(k, 'engine/loadTexture', url));
146
- }
147
+ };
148
+ // E157: the KTX2 stand-in, when the build has one and KTX2 is on; on the image fallback, a linear file's ASTC stand-in (src/client/engine/core/ktx2.ts)
149
+ // OF17: a form that fails to read gives way to the other when the cache holds it (a form the warm visit never read)
147
150
  const key = imageKey(url, maxSize);
148
151
  const shared = sharedSources.get(sourceKey(key, srgb));
149
152
  const source = shared?.source.deref();
150
- let t: THREE.Texture;
151
- if (shared === undefined || source === undefined) {
152
- const decoded = await loadTextureSource(url, srgb, maxSize);
153
- t = new THREE.Texture(); t.source = decoded.source; t.flipY = decoded.flipY;
154
- } else {
155
- t = new THREE.Texture();
156
- t.source = source;
157
- t.flipY = shared.flipY;
158
- }
153
+ const read = await readHeldForm(served, async tex => tex !== undefined ? ktx2Texture(served, maxSize, tex)
154
+ : await ktx2Texture(served, maxSize) ?? (srgb ? null : await linearKtx2Texture(served, maxSize)),
155
+ instead => shared === undefined || source === undefined ? loadTextureSource(url, srgb, maxSize, instead) : Promise.resolve({ source, flipY: shared.flipY }));
156
+ if (read instanceof THREE.CompressedTexture) return compressed(read);
157
+ const t = new THREE.Texture(); t.source = read.source; t.flipY = read.flipY;
159
158
  t.wrapS = t.wrapT = THREE.RepeatWrapping;
160
159
  t.repeat.set(repeat, repeat);
161
160
  t.anisotropy = maxAniso;
@@ -167,6 +166,7 @@ export async function loadTexture(url: string, srgb = false, repeat = 1, maxSize
167
166
  return labelAsset(t, 'engine/loadTexture', url);
168
167
  }
169
168
 
169
+
170
170
  /**
171
171
  * URL of one map of a Poly Haven set. The phone tier gets the `_1k.jpg` sibling
172
172
  * (scripts/tex-tiers.mjs: ≤ 1024², q82 — a quarter of the bytes) when the build has one.
@@ -285,8 +285,15 @@ export async function loadPBRArray(ids: string[], size: number = TIER_CONFIG.lay
285
285
  t.needsUpdate = true;
286
286
  return prepareCompressedTexture(labelAsset(t, 'engine/loadPBRArray', arrayLabel(kind)));
287
287
  };
288
- const build = async (kind: (typeof kinds)[number], srgb: boolean): Promise<THREE.DataArrayTexture | THREE.CompressedArrayTexture> =>
289
- (await buildKtx2(kind, srgb)) ?? (gpu ? buildGPU(kind, srgb, gpu) : buildCPU(kind, srgb));
288
+ const build = async (kind: (typeof kinds)[number], srgb: boolean): Promise<THREE.DataArrayTexture | THREE.CompressedArrayTexture> => {
289
+ let k: THREE.CompressedArrayTexture | null = null;
290
+ try { k = await buildKtx2(kind, srgb); }
291
+ catch (error) { // OF17: stand-ins that failed to read while the cache holds every layer's image build from the images
292
+ const forms = await Promise.all(ids.map(id => heldForm(tierUrl(texUrl(id, kind)), 'ktx2', cacheHolds)));
293
+ if (!forms.every(form => form === 'img')) throw error;
294
+ }
295
+ return k ?? (gpu ? buildGPU(kind, srgb, gpu) : buildCPU(kind, srgb));
296
+ };
290
297
  const [map, normalMap, armMap] = await Promise.all([build('diffuse', true), build('nor_gl', false), build('arm', false)]);
291
298
  return { map, normalMap, armMap };
292
299
  }
@@ -5,6 +5,7 @@ import { app } from '../app/runtime';
5
5
  import type * as THREE from 'three';
6
6
  import { Game } from './Game';
7
7
  import { applyLevelTier, TIER } from './tier';
8
+ import { noteDeviceGpu } from '../telemetry/deviceSnapshot';
8
9
  import { readyWebGLContext } from './webglStartup';
9
10
  import { recordBootCheckpoint } from '../boot/bootTrace';
10
11
  import { issueBakedPrograms } from '../boot/earlyPrograms';
@@ -25,7 +26,7 @@ import { setActiveBodies, setActivePhysics } from '../physics/active';
25
26
  import { loadNavmesh } from '../physics/navmeshLoad';
26
27
  import { setRagdollClock } from '../physics/ragdoll';
27
28
  import { Bodies, BODY_CAP } from '../../../shared/engine/physics/bodies';
28
- import { addEdgeWalls, addLevelTerrain } from '../../../shared/engine/physics/terrain';
29
+ import { addLevelTerrain } from '../../../shared/engine/physics/terrain';
29
30
  import { addPiece } from '../../../shared/engine/physics/pieces';
30
31
  import type { WorldRegistry } from '../world/registry';
31
32
  import { installPhysicsDebug } from '../physics/debug';
@@ -74,7 +75,9 @@ export async function bootstrap(step: StepRunner, level: LevelSpec, inputContext
74
75
  progress.detail('Waiting for graphics to recover');
75
76
  recordBootCheckpoint('renderer:waiting', { ...state });
76
77
  });
77
- return new Game(canvas, context, level);
78
+ const made = new Game(canvas, context, level);
79
+ noteDeviceGpu(context); // DEVICE-TELEMETRY DT1: the game's own context names its GPU for the device snapshot
80
+ return made;
78
81
  });
79
82
  game.app.clock.setCapture(harnessPins()?.capture ?? null);
80
83
  issueBakedPrograms(game); // DL10 (Debug 'Early shader compile'): a queued list of the level's entry programs starts linking
@@ -103,7 +106,6 @@ export async function bootstrap(step: StepRunner, level: LevelSpec, inputContext
103
106
  await navmesh;
104
107
  withOwner(game.levelScope, () => {
105
108
  if (needsTerrainCollider(level)) addLevelTerrain(ph, level.ground.collider); // a structure-first shard walks on its built floors only
106
- if (level.boundary?.walls !== false) addEdgeWalls(ph); // a level inside a platform grid: the platform owns its edge
107
109
  });
108
110
  p.detail(`${ph.world.colliders.len()} colliders`);
109
111
  return ph;
@@ -22,7 +22,9 @@ import { pageScope } from '../../../shared/engine/app/resources';
22
22
  import * as THREE from 'three';
23
23
  import { KTX2Loader } from 'three/examples/jsm/loaders/KTX2Loader.js';
24
24
  import type { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
25
- import { texMode, gpuFile, standIn, retireGpuFile } from '../boot/gpuFiles';
25
+ import { texMode, gpuFile, standIn, retireGpuFile, rawAstcVeto, texturePin, type TexMode } from '../boot/gpuFiles';
26
+ import { phoneUrl, versionedUrl } from '../boot/bytes';
27
+ import type { ContentReadError, ContentReadOptions } from '../boot/contentRead';
26
28
  import { emitFault } from '../../../shared/engine/core/faults';
27
29
  import { markGpuOnly } from './gpuOnly';
28
30
  import { type Renderer, probeRenderer } from '../render/renderer';
@@ -33,7 +35,7 @@ import { uploadCompressedTexture } from '../render/compressedUpload';
33
35
  import { installGltfMaterialOrder } from '../render/gltfMaterialOrder';
34
36
  import { registerCompressedMipmaps, compressedMipmapsUploaded } from '../render/compressedMipmaps';
35
37
  import { harnessPins } from '../../../shared/engine/app/identity';
36
- import { applyKtx2Probe, ktx2ProbeResult, linearAstcSurvives } from '../render/ktx2Probe';
38
+ import { applyKtx2Probe, ktx2Probe, ktx2ProbeResult, linearAstcSurvives, type Ktx2Probe } from '../render/ktx2Probe';
37
39
  import { workSlice } from '../../../shared/engine/core/workSlice';
38
40
  import { TIER } from './tier';
39
41
  import { prepareKtx2Zstd, unsupercompressKtx2 } from './ktx2Zstd';
@@ -252,23 +254,33 @@ export function installGltfKtx2(type: typeof GLTFLoader): void {
252
254
  configurable: true, writable: true,
253
255
  value(this: GLTFLoader, ...args: Parameters<GLTFLoader['load']>): void {
254
256
  const [url, onLoad, onProgress, onError] = args;
255
- Reflect.apply(fetchGltf, this, [url, onLoad, onProgress, (error: unknown): void => {
256
- const missing = missingStandIn(error), retired = missing === undefined ? undefined : retireGpuFile(missing);
257
- if (retired === undefined) {
258
- if (onError !== undefined) onError(error); else console.error(error);
259
- return;
260
- }
257
+ const fail = (failure: unknown): void => { if (onError !== undefined) onError(failure); else console.error(failure); };
258
+ const again = (): void => { Reflect.apply(fetchGltf, this, [url, onLoad, onProgress, onError]); };
259
+ Reflect.apply(fetchGltf, this, [url, onLoad, onProgress, (failure: unknown): void => {
260
+ const missing = missingStandIn(failure), retired = missing === undefined ? undefined : retireGpuFile(missing);
261
+ if (retired === undefined) { void heldModelRetry(url, failure, again, fail); return; }
261
262
  if (retired === 'new') {
262
263
  console.warn(`[ktx2] stand-in ${String(missing)} answered 404; loading ${url} instead`);
263
264
  emitFault({ system: 'assets.gpu', error: new Error(`KTX2 stand-in not served: ${String(missing)} (for ${url})`), verdict: 'retry' });
264
265
  }
265
- Reflect.apply(fetchGltf, this, [url, onLoad, onProgress, onError]);
266
+ again();
266
267
  }]);
267
268
  },
268
269
  });
269
270
  }
270
271
  configuredGltfLoaders.add(type);
271
272
  }
273
+ /** OF17: a model whose KTX2 stand-in failed to read while the cache holds the tier's own file: retire the stand-in for the
274
+ * page and load again (the tier's file), else fail as before. */
275
+ async function heldModelRetry(url: string, failure: unknown, again: () => void, fail: (failure: unknown) => void): Promise<void> {
276
+ let file: string | undefined;
277
+ try {
278
+ const served = texMode() === 'ktx2' ? phoneUrl(new URL(url.replace(/[?#].*$/u, ''), location.href).pathname) : undefined;
279
+ file = served === undefined ? undefined : standIn(served, 'ktx2');
280
+ if (served === undefined || file === undefined || await heldForm(served, 'ktx2', cacheHolds) !== 'img') file = undefined;
281
+ } catch { file = undefined; }
282
+ if (file === undefined || retireGpuFile(file) === undefined) fail(failure); else again();
283
+ }
272
284
  /** The URL of a three HttpError's 404 (FileLoader passes the failed Response as `response`), else undefined. */
273
285
  function missingStandIn(error: unknown): string | undefined {
274
286
  if (typeof error !== 'object' || error === null || !('response' in error)) return undefined;
@@ -351,9 +363,11 @@ export function parseKtx2Bytes(input: Uint8Array): Promise<THREE.Texture> {
351
363
  * remain on every returned texture until upload, including after disposal or for a different sampler.
352
364
  * `maxSize` (the tier's texture cap, as loadImage applies it to a decode): a larger file starts at the first mip that fits.
353
365
  */
354
- export async function ktx2Texture(served: string, maxSize: typeof Infinity = Infinity): Promise<THREE.CompressedTexture | null> {
355
- const url = gpuFile(served);
366
+ export async function ktx2Texture(served: string, maxSize: typeof Infinity = Infinity, tex?: TexMode): Promise<THREE.CompressedTexture | null> {
367
+ // `tex` (OF17): a form other than the page's, read because the cache holds it (core/assets.ts loadTexture)
368
+ const url = tex === undefined ? gpuFile(served) : standIn(served, tex);
356
369
  if (url === undefined) return null;
370
+ if (tex === 'ktx2' && texMode() !== 'ktx2') markGpuOnly('KTX2 stand-ins read on the image path because the cache held them (OF17)');
357
371
  const base = await load(url, true);
358
372
  const skip = base.mipmaps.findIndex((m) => Math.max(m.width, m.height) <= maxSize);
359
373
  let t: THREE.CompressedTexture;
@@ -509,3 +523,62 @@ function topRowsFirst(out: Uint8Array, w: number, h: number): Uint8Array {
509
523
  for (let y = 0; y < h; y++) rows.set(out.subarray((h - 1 - y) * stride, (h - y) * stride), y * stride);
510
524
  return rows;
511
525
  }
526
+
527
+ // OF17 (one texture form per device and tier): a texture read in its page's form gives way to the other form when its
528
+ // read fails and the cache holds the other one. Nine Dragon's grid page read `scroll.phone-<h>.ktx2` and its offline one-shard
529
+ // page asked for `scroll.phone.webp`, which nothing had cached, so the read parked LOAD on RETRY for good. A stand-in's read
530
+ // fails at once offline; an image's read fails twice and then, instead of waiting on RETRY (boot/contentRead.ts `instead`),
531
+ // turns to the stand-in. Models (the GLTF load hook above) and terrain arrays (core/assets.ts loadPBRArray) do the same.
532
+
533
+ /**
534
+ * The form of `served` (a path, after tierUrl) to read when its `failed` form could not be read: the other form, when this
535
+ * tier has both, no harness pin holds the page to one form, this GPU may sample the KTX2 one, and `held` (the cache) holds
536
+ * it; else undefined (the read waits on RETRY as before). `held` gets the path of the form it asks about: the stand-in, or
537
+ * `served` itself.
538
+ */
539
+ export async function heldForm(served: string, failed: TexMode, held: (path: string) => Promise<boolean>, probe: () => Ktx2Probe = ktx2Probe): Promise<TexMode | undefined> {
540
+ const ktx2 = standIn(served, 'ktx2');
541
+ if (ktx2 === undefined || texturePin() !== 'auto') return undefined; // a test or capture's pin keeps its one form
542
+ if (failed === 'img') {
543
+ const verdict = probe();
544
+ if ((verdict.veto ?? rawAstcVeto(verdict)) !== null) return undefined;
545
+ }
546
+ const other: TexMode = failed === 'ktx2' ? 'img' : 'ktx2';
547
+ try { return await held(other === 'ktx2' ? ktx2 : served) ? other : undefined; }
548
+ catch { return undefined; } // storage denied: no held form to know of
549
+ }
550
+
551
+ const CONTENT_ADDRESSED = /-[a-f0-9]{8,64}\.[a-z0-9]+$|\/[a-f0-9]{64}\.[a-z0-9]+$/u;
552
+ /** Whether the cache holds `path` as the service worker would answer it: the exact versioned URL, or a content-addressed
553
+ * name under any query (sw.js's own rule). A missing Cache Storage holds nothing. */
554
+ export async function cacheHolds(path: string): Promise<boolean> {
555
+ if (typeof caches === 'undefined') return false;
556
+ const href = new URL(versionedUrl(path), location.href).href;
557
+ return await caches.match(href, { ignoreVary: true, ignoreSearch: CONTENT_ADDRESSED.test(path) }) !== undefined;
558
+ }
559
+ /** failed image reads whose KTX2 stand-in the cache holds: every caller sharing that read turns to the stand-in */
560
+ const heldKtx2 = new WeakSet<Error>();
561
+
562
+ /**
563
+ * `ktx2()` (the page's form: the stand-in in KTX2 mode, else null) or `image(instead)`. `ktx2('ktx2')` reads the stand-in
564
+ * whatever the page's form; `image` passes `instead` to its read (fetchImage).
565
+ */
566
+ export async function readHeldForm<T>(served: string, ktx2: (tex?: TexMode) => Promise<THREE.CompressedTexture | null>,
567
+ image: (instead?: ContentReadOptions['instead']) => Promise<T>, held: (path: string) => Promise<boolean> = cacheHolds): Promise<THREE.CompressedTexture | T> {
568
+ const triedKtx2 = texMode() === 'ktx2';
569
+ let k: THREE.CompressedTexture | null = null;
570
+ try { k = await ktx2(); }
571
+ catch (error) { if (!triedKtx2 || await heldForm(served, 'ktx2', held) !== 'img') throw error; }
572
+ if (k !== null) return k;
573
+ const instead = async (error: ContentReadError): Promise<boolean> => {
574
+ const switched = await heldForm(served, 'img', held) === 'ktx2';
575
+ if (switched) heldKtx2.add(error);
576
+ return switched;
577
+ };
578
+ try { return await image(triedKtx2 ? undefined : instead); }
579
+ catch (error) {
580
+ const stand = error instanceof Error && heldKtx2.has(error) ? await ktx2('ktx2') : null;
581
+ if (stand === null) throw error;
582
+ return stand;
583
+ }
584
+ }
@@ -123,8 +123,22 @@ export interface Fingerprint {
123
123
  facade?: { multiDraw: boolean; batches: number; instances: number };
124
124
  playMs: number; heapMB: number;
125
125
  }
126
+ /** A door or gate panel the area declares: drawn, and whether its colliders stand. */
127
+ export interface ProbeAreaTarget { readonly panel: string; readonly visible: boolean; readonly solid: boolean }
128
+ /** T2E-1b: the area the player is in. On a grid page that is the current cell, not the page shell (`platform.grid`). */
129
+ export interface ProbeArea {
130
+ /** the area's shard slug */
131
+ readonly slug: string;
132
+ /** the grid cell's instance; null on a one-shard page */
133
+ readonly instance: string | null;
134
+ readonly targets: readonly ProbeAreaTarget[];
135
+ /** every quest flag the player holds in this area, sorted */
136
+ readonly flags: readonly string[];
137
+ }
126
138
  export interface ProbeDeps {
127
139
  health: () => number; quest: () => unknown;
140
+ /** The area the player is in; null between areas (a grid page's road). */
141
+ area: () => ProbeArea | null;
128
142
  /** The retained level world used for leak counts when active frame worlds can be replaced and freed. */
129
143
  leakPhysics?: World['physics'];
130
144
  }
@@ -162,6 +176,8 @@ export interface EngineProbe<W extends ProbeWorld = ProbeWorld> {
162
176
  hold: (animal: CombatTarget, on: boolean) => void; hits: { kind: string; amount: number }[]; kills: string[] };
163
177
  arena: () => void;
164
178
  state: () => GameplayState;
179
+ /** T2E-1b: the area the player is in, with its door targets and quest flags; null between areas. */
180
+ area: () => ProbeArea | null;
165
181
  onResume: (fn: () => void) => void;
166
182
  saves: Saves;
167
183
  sounds: () => SoundLog;
@@ -510,6 +526,7 @@ export function installProbe<W extends ProbeWorld>(world: W, deps: ProbeDeps): E
510
526
  creatures: world.animals.animals.map((a, i) => ({ id: `${a.kind}:${i}`, kind: a.kind, pos: point(a.position), hp: a.hp, brain: a.state })).sort((a, b) => a.id.localeCompare(b.id)),
511
527
  quest: { adventure: deps.quest(), level: authoredQuestFlags(world) },
512
528
  }),
529
+ area: () => deps.area(),
513
530
  onResume: (fn) => { requireHarness(); resume = fn; }, saves,
514
531
  sounds: () => { const log = { event: events, ambient: [...ambient].sort() }; events = {}; ambient.clear(); return log; },
515
532
  used: () => labels.splice(0),
@@ -545,7 +562,7 @@ function scopedProbe<W extends ProbeWorld>(source: EngineProbe<W>, scope: Scope)
545
562
  get app() { return read().app; },
546
563
  fingerprint: () => read().fingerprint(), pose: (value) => read().pose(value),
547
564
  walkLeg: (leg) => read().walkLeg(leg), arena: () => { read().arena(); },
548
- state: () => read().state(), onResume: (fn) => { read().onResume(fn); },
565
+ state: () => read().state(), area: () => read().area(), onResume: (fn) => { read().onResume(fn); },
549
566
  sounds: () => read().sounds(), used: () => read().used(), budgets: (poses) => read().budgets(poses),
550
567
  leak: async () => {
551
568
  if (live === undefined) {
@@ -1,4 +1,4 @@
1
- import { listenDom } from '../input/dom';
1
+ import { capturePointer, listenDom } from '../input/dom';
2
2
  import { app } from '../app/runtime';
3
3
  import { LoadProgress } from '../ui/loadProgress';
4
4
  import { engineString } from '../../../shared/engine/strings';
@@ -60,7 +60,7 @@ export class Compare {
60
60
  listenDom(this.uiScope, this.picker.querySelector('.ws-x-picker-close'), 'click', () => { this.picker.classList.remove('show'); this.pickerProgress.clear(); });
61
61
  this.picker.querySelectorAll<HTMLElement>('.ws-x-target').forEach((b) => { listenDom(this.uiScope, b, 'click', () => { const t = this.targets.find((x) => x.id === b.dataset['id']); if (t) this.show(t); }); });
62
62
  listenDom(this.uiScope, this.overlay.querySelector('.ws-x-compare-close'), 'click', () => { this.close(); });
63
- listenDom(this.uiScope, this.divider, 'pointerdown', (e) => { this.divider.setPointerCapture(e.pointerId); this.splitAt(e.clientX); e.preventDefault(); });
63
+ listenDom(this.uiScope, this.divider, 'pointerdown', (e) => { capturePointer(this.divider, e.pointerId); this.splitAt(e.clientX); e.preventDefault(); });
64
64
  listenDom(this.uiScope, this.divider, 'pointermove', (e) => { if (this.divider.hasPointerCapture(e.pointerId)) this.splitAt(e.clientX); });
65
65
  listenDom(this.uiScope, this.divider, 'keydown', (e) => {
66
66
  if (e.key !== 'ArrowLeft' && e.key !== 'ArrowRight') return;
@@ -1,4 +1,4 @@
1
- import { listenDom, listenPage } from '../input/dom';
1
+ import { capturePointer, listenDom, listenPage } from '../input/dom';
2
2
  import { app } from '../app/runtime';
3
3
  import { engineString } from '../../../shared/engine/strings';
4
4
  /**
@@ -28,10 +28,8 @@ const STICK_R = 46; // px — the thumb's travel
28
28
  const TAP_SLOP = 14; // px — a button touch that travels further than this is not a tap
29
29
  const RELAY_SWALLOW_MS = 700; // the browser's own click for a relayed tap, should one still come, lands inside this
30
30
 
31
- /** capture a finger on its control's element (its moves and lift follow it anywhere); a pointer already gone throws */
32
- function capture(el: HTMLElement, id: number): void {
33
- try { el.setPointerCapture(id); } catch { /* lifted before we got here: its pointerup is on its way */ }
34
- }
31
+ /** capture a finger on its control's element (its moves and lift follow it anywhere); a pointer already gone is skipped */
32
+ function capture(el: HTMLElement, id: number): void { capturePointer(el, id); }
35
33
 
36
34
  /**
37
35
  * A held button (the rail's ▲ / ▼): held while any finger that went down on it is still down. It keeps its own pointer
@@ -57,6 +57,8 @@ export class LightPool {
57
57
  private readonly yielding = new Set<THREE.PointLight>();
58
58
  /** A borrowed light and the yielding light whose place in the scene it holds. */
59
59
  private readonly lent = new Map<THREE.PointLight, THREE.PointLight>();
60
+ /** RP4: this nested pool's scene lights taken out of three's count (`adopt`), with the layer mask each gets back */
61
+ private readonly adopted = new Map<THREE.PointLight, number>();
60
62
 
61
63
  private constructor(scene: THREE.Scene) {
62
64
  this.group.name = 'light-pool';
@@ -87,7 +89,31 @@ export class LightPool {
87
89
  if (page === this) throw new Error('A light pool cannot mirror into itself');
88
90
  this.mirroredBy = page; page.sources.add(this);
89
91
  for (const light of this.lights) light.layers.disableAll();
90
- scope.onDispose(() => { page.sources.delete(this); if (this.mirroredBy === page) this.mirroredBy = null; for (const light of this.lights) light.layers.enable(0); });
92
+ scope.onDispose(() => {
93
+ page.sources.delete(this); if (this.mirroredBy === page) this.mirroredBy = null; for (const light of this.lights) light.layers.enable(0);
94
+ for (const [light, mask] of this.adopted) light.layers.mask = mask;
95
+ this.adopted.clear();
96
+ });
97
+ }
98
+
99
+ /** RP4: a mirrored pool also takes the plain point lights its content put under `root` (a region's site and signal
100
+ * lights, `new PointLight` in its own tree): each leaves three's light count and shows through the page's reserved
101
+ * lights as a pooled one does, while it and its ancestors show. Only as many as the reserve can show alongside this
102
+ * pool's own lights; a shadow caster, or one past that, stays counted as before, and so does one that finds the shared
103
+ * reserve full when it shows (another region's lights took it: `showMirrors` gives it back to three's count). Again on the same root takes only new
104
+ * ones. Returns how many it took. Sunscar's two counted whenever its region showed: arriving moved the page from 6 to
105
+ * 7 and 8 point lights and every lit program in view linked again (Chromium, 117 to 216 ms a link). */
106
+ adopt(root: THREE.Object3D): number {
107
+ const page = this.mirroredBy;
108
+ if (page === null) return 0;
109
+ let taken = 0;
110
+ for (const light of this.adopted.keys()) if (light.parent === null) this.adopted.delete(light); // gone with its content
111
+ root.traverse(object => {
112
+ if (!(object instanceof THREE.PointLight) || object.castShadow || object.layers.mask === 0 || this.adopted.has(object)) return;
113
+ if (this.lights.length + this.adopted.size >= page.reserved.length) return;
114
+ this.adopted.set(object, object.layers.mask); object.layers.disableAll(); taken++;
115
+ });
116
+ return taken;
91
117
  }
92
118
 
93
119
  /** Make `count` free dark lights now (counted, never mirrored), for content known to ask after the first render: a
@@ -166,6 +192,20 @@ export class LightPool {
166
192
  // three posed the scene before this hook: the slot's world matrix is set here, from the light's
167
193
  slot.position.setFromMatrixPosition(light.matrixWorld); slot.updateMatrixWorld();
168
194
  }
195
+ for (const [light, mask] of source.adopted) {
196
+ if (light.intensity <= 0 || !shownUnder(light, this.group.parent)) continue;
197
+ const slot = this.reserved[next];
198
+ if (slot === undefined) {
199
+ // the reserve is shared by every shown region: one with no slot left is counted again, as before it was adopted
200
+ // (the count moves, every lit program links again, but it lights), never left dark
201
+ if (!this.warnedMirror) { this.warnedMirror = true; console.warn(`[LightPool] more shown region lights than the ${String(this.reserved.length)} reserved: an adopted light counts again`); }
202
+ light.layers.mask = mask; source.adopted.delete(light);
203
+ continue;
204
+ }
205
+ next++;
206
+ slot.color.copy(light.color); slot.intensity = light.intensity; slot.distance = light.distance; slot.decay = light.decay;
207
+ slot.position.setFromMatrixPosition(light.matrixWorld); slot.updateMatrixWorld();
208
+ }
169
209
  }
170
210
  for (; next < this.reserved.length; next++) { const slot = this.reserved[next]; if (slot !== undefined) slot.intensity = 0; }
171
211
  }
@@ -60,3 +60,15 @@ export function listenPage<K extends PageInputEvent>(scope: Scope, type: K, fn:
60
60
  const { on = 'window', ...rest } = options ?? {};
61
61
  scope.listen(on === 'document' ? document : window, type, fn, rest);
62
62
  }
63
+
64
+ /**
65
+ * Capture a pointer on an element (its moves and lift follow it anywhere). A pointer that is already gone throws:
66
+ * Chrome on Android raises `InvalidStateError` when the touch was handed to the browser (a scroll, a system gesture)
67
+ * before the pointerdown handler ran, and `NotFoundError` for an id it never knew. That touch's pointerup or
68
+ * pointercancel is on its way, so the control runs uncaptured; the throw used to escape the handler, skip the rest of
69
+ * the press and raise "A glitch was reported" (QA-FEEDBACK-2026-11-13 row 6, Sentry WILDSHARD-GAME-2M).
70
+ * Every capture in the client goes through here (test/pointer-capture.test.ts). Returns whether the capture took.
71
+ */
72
+ export function capturePointer(el: Element, pointerId: number): boolean {
73
+ try { el.setPointerCapture(pointerId); return true; } catch { return false; }
74
+ }
@@ -22,6 +22,8 @@ export const PREDICTION_TOLERANCE = 0.02;
22
22
  * phase with nothing wrong: the same spot on the deck. Correcting that would chase the deck for ever.
23
23
  */
24
24
  const DECK_PHASE_TICKS = 3;
25
+ /** NET-LAG NL12 (a): a grounded Y-only gap up to this, on matching XZ, is the same floor (J282: 150 to 200 ms is the design target). */
26
+ export const GROUND_Y_SLACK = 0.05;
25
27
  /** A correction this far is a teleport: it snaps rather than glides. */
26
28
  export const PREDICTION_SNAP = 3;
27
29
  /** Room for a ride's words and its capsule's in a saved move. */
@@ -205,8 +207,10 @@ export class Predictor {
205
207
  }
206
208
  const x = this.value(table.x, owner) - (states[at + CAPTURED.x] ?? 0), y = this.value(table.y, owner) - (states[at + CAPTURED.y] ?? 0), z = this.value(table.z, owner) - (states[at + CAPTURED.z] ?? 0);
207
209
  const reach = PREDICTION_TOLERANCE + DECK_PHASE_TICKS * (states[at + CAPTURED.carried] ?? 0), grounded = this.flag(table.grounded, owner) !== states[at + CAPTURED.grounded];
208
- if (grounded || x * x + y * y + z * z > reach * reach) this.keepMiss(slot, owner);
209
- if (x * x + y * y + z * z > reach * reach) { missed.position++; missed.gap = Math.max(missed.gap, Math.hypot(x, y, z)); return false; }
210
+ // NL12 (a): both on the ground, the ground decides Y; a few cm there alone is the same floor, not a miss
211
+ const floorY = !grounded && this.flag(table.grounded, owner) === 1 && Math.abs(y) <= GROUND_Y_SLACK ? 0 : y, gap = x * x + floorY * floorY + z * z;
212
+ if (grounded || gap > reach * reach) this.keepMiss(slot, owner);
213
+ if (gap > reach * reach) { missed.position++; missed.gap = Math.max(missed.gap, Math.hypot(x, y, z)); return false; }
210
214
  if (grounded) { missed.grounded++; return false; }
211
215
  if (this.flag(table.board, owner) !== states[at + CAPTURED.board]) { missed.board++; return false; }
212
216
  if (this.flag(table.swim, owner) !== states[at + CAPTURED.swim]) { missed.swim++; return false; }