@wildshard/engine 0.1.18 → 0.1.20

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 (334) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/budgets/shard-size-baseline.json +10 -4
  3. package/index.html +6 -4
  4. package/lint/engine-sides.json +18 -0
  5. package/lint/ratchet.json +0 -68
  6. package/lint/ratchet.mjs +1 -4
  7. package/package.json +19 -15
  8. package/scripts/agent-sync.mjs +27 -8
  9. package/scripts/app-build/appCook.ts +8 -2
  10. package/scripts/app-build/catalogue.ts +10 -7
  11. package/scripts/app-build/gen.ts +33 -2
  12. package/scripts/app-build/isolation.d.mts +10 -0
  13. package/scripts/app-build/isolation.mjs +47 -0
  14. package/scripts/app-build/outputProducts.mjs +4 -0
  15. package/scripts/app-build/previousDeploy.d.mts +2 -0
  16. package/scripts/app-build/previousDeploy.mjs +10 -1
  17. package/scripts/app-build/serviceWorker.ts +10 -3
  18. package/scripts/app-build/splitOutput.mjs +4 -2
  19. package/scripts/app-build/standaloneOutput.d.mts +1 -1
  20. package/scripts/app-build/standaloneOutput.mjs +5 -3
  21. package/scripts/app-build/titlePreloads.d.mts +8 -0
  22. package/scripts/app-build/titlePreloads.mjs +69 -0
  23. package/scripts/app-build/worldMapAtlas.ts +10 -6
  24. package/scripts/app-build-pipeline.mjs +31 -3
  25. package/scripts/built-product.mjs +1 -1
  26. package/scripts/cell-mem-bench.mjs +83 -23
  27. package/scripts/check-custom-sections-zero.mjs +1 -1
  28. package/scripts/check-devserver.mjs +2 -0
  29. package/scripts/check-models.mjs +2 -0
  30. package/scripts/check-paths.allow.json +0 -115
  31. package/scripts/check-paths.mjs +2 -2
  32. package/scripts/check-platform-ratchets.mjs +2 -3
  33. package/scripts/chromium-keychain.d.mts +1 -1
  34. package/scripts/ci-static.sh +1 -1
  35. package/scripts/committed-fast-checks.mjs +0 -2
  36. package/scripts/content-sw-proof.mjs +2 -1
  37. package/scripts/cook-worker.mjs +9 -3
  38. package/scripts/cook.mjs +18 -5
  39. package/scripts/docs-inputs-proof.mjs +6 -6
  40. package/scripts/e7-voice-staging-proof.mjs +1 -1
  41. package/scripts/gate-related-tests.mjs +1 -1
  42. package/scripts/git-source-view.mjs +1 -1
  43. package/scripts/goldens/capture.mjs +17 -5
  44. package/scripts/grid-crossing-nightly.mjs +59 -0
  45. package/scripts/grid-crossing-qa.mjs +44 -0
  46. package/scripts/grid-crossing-ratchet.d.mts +6 -0
  47. package/scripts/grid-crossing-ratchet.mjs +52 -0
  48. package/scripts/grid-crossing-report.mjs +122 -0
  49. package/scripts/grid-crossing-stages.mjs +47 -0
  50. package/scripts/grid-crossing-tour.mjs +284 -0
  51. package/scripts/grid-crossing-walk-proof.mjs +126 -17
  52. package/scripts/host-ruler/roots.mjs +2 -2
  53. package/scripts/host-ruler.d.mts +91 -0
  54. package/scripts/host-ruler.mjs +565 -0
  55. package/scripts/land.mjs +2 -1
  56. package/scripts/live-prepush.py +3 -5
  57. package/scripts/loading-flow/benchmax.mjs +37 -12
  58. package/scripts/loading-flow/deskbench.mjs +276 -0
  59. package/scripts/loading-flow/stalls.d.mts +17 -3
  60. package/scripts/loading-flow/stalls.mjs +82 -3
  61. package/scripts/look-loop/test_look_loop.py +1 -38
  62. package/scripts/memory-proof.mjs +61 -6
  63. package/scripts/mmo-bots.mjs +8 -2
  64. package/scripts/net-lag-proof.mjs +219 -0
  65. package/scripts/night-market-kit-budget.mjs +2 -2
  66. package/scripts/nightly-model.ts +9 -6
  67. package/scripts/offline-proof-rules.d.mts +2 -2
  68. package/scripts/offline-proof-rules.mjs +15 -4
  69. package/scripts/offline-proof.mjs +80 -13
  70. package/scripts/{shard-platform-output.mjs → output-reader.mjs} +1 -1
  71. package/scripts/page-release/content.d.mts +9 -1
  72. package/scripts/page-release/content.mjs +131 -17
  73. package/scripts/page-release/flow.mjs +36 -10
  74. package/scripts/page-release/stamp-content.mjs +24 -0
  75. package/scripts/page-release.mjs +28 -6
  76. package/scripts/page-size.mjs +2 -1
  77. package/scripts/parity/boot-smoke.mjs +13 -2
  78. package/scripts/pin-format.ts +5 -2
  79. package/scripts/pin-packs.ts +1 -1
  80. package/scripts/pins-reuse.d.mts +1 -0
  81. package/scripts/pins-reuse.mjs +22 -0
  82. package/scripts/pins.ts +4 -4
  83. package/scripts/precommit-checks.mjs +1 -7
  84. package/scripts/precommit-jobs.mjs +0 -1
  85. package/scripts/precommit-source.py +1 -9
  86. package/scripts/program-discovery.mjs +1 -1
  87. package/scripts/ring-cook.mjs +2 -1
  88. package/scripts/ring-step.ts +1 -1
  89. package/scripts/scratch-dir.mjs +95 -0
  90. package/scripts/scratch-sweep.mjs +182 -0
  91. package/scripts/script-scenario-metrics.mjs +1 -1
  92. package/scripts/shard-output-content.d.mts +1 -1
  93. package/scripts/shard-output-content.mjs +2 -2
  94. package/scripts/shard-outputs.mjs +1 -1
  95. package/scripts/shard-public.mjs +1 -1
  96. package/scripts/shard-wire-meter.mjs +24 -9
  97. package/scripts/side-parity.mjs +4 -2
  98. package/scripts/standalone-smoke.mjs +8 -3
  99. package/scripts/tier-textures.mjs +22 -4
  100. package/scripts/tile-bake-report.mjs +1 -1
  101. package/scripts/tile-bakes.mjs +1 -1
  102. package/scripts/title-assets.generated.json +2 -0
  103. package/scripts/tsconfig.json +2 -14
  104. package/scripts/vendor/basisu/LICENSE +201 -0
  105. package/scripts/vendor/basisu/basis_encoder.cjs +2 -0
  106. package/scripts/vendor/basisu/basis_encoder.wasm +0 -0
  107. package/scripts/vitest-push-guards.config.ts +1 -1
  108. package/scripts/vps/harden-apply.sh +4 -1
  109. package/scripts/vps/harden-prometheus.sh +179 -0
  110. package/scripts/vps/harden.sh +16 -0
  111. package/scripts/vps/rebuild.sh +18 -0
  112. package/scripts/vps/wildshard-config +6 -2
  113. package/scripts/worker-client-play.mjs +6 -2
  114. package/scripts/worktree-reap.mjs +59 -13
  115. package/scripts/worktree.mjs +19 -5
  116. package/src/.oxlintrc.json +3 -182
  117. package/src/client/app/entry.ts +10 -2
  118. package/src/client/engine/anim/rigParser.ts +2 -2
  119. package/src/client/engine/boot/bootCache.ts +2 -2
  120. package/src/client/engine/boot/bootTrace.ts +12 -4
  121. package/src/client/engine/boot/browserChunkRecovery.ts +4 -0
  122. package/src/client/engine/boot/clearDownloads.ts +5 -2
  123. package/src/client/engine/boot/contentRead.ts +11 -0
  124. package/src/client/engine/boot/gpuFiles.ts +4 -2
  125. package/src/client/engine/boot/lastEnd.ts +99 -12
  126. package/src/client/engine/boot/texturePack.ts +2 -2
  127. package/src/client/engine/core/Game.ts +63 -19
  128. package/src/client/engine/core/gpuOnly.ts +10 -0
  129. package/src/client/engine/core/renderBudget.ts +134 -0
  130. package/src/client/engine/net/netPlayer.ts +19 -2
  131. package/src/client/engine/net/otherPlayers.ts +55 -8
  132. package/src/client/engine/net/predictor.ts +33 -9
  133. package/src/client/engine/net/redial.ts +68 -10
  134. package/src/client/engine/pwa/cacheNames.ts +58 -1
  135. package/src/client/engine/pwa/sw.js +41 -11
  136. package/src/client/engine/render/dataLook.ts +219 -44
  137. package/src/client/engine/render/families/detail.ts +89 -0
  138. package/src/client/engine/render/families/pbr.ts +9 -1
  139. package/src/client/engine/render/families/registry.ts +11 -2
  140. package/src/client/engine/render/families/sceneSurface.ts +116 -0
  141. package/src/client/engine/render/look.ts +12 -0
  142. package/src/client/engine/render/lookLight.ts +103 -11
  143. package/src/client/engine/render/lookRender.ts +105 -0
  144. package/src/client/engine/render/precompile.ts +4 -2
  145. package/src/client/engine/render/tiers.ts +4 -1
  146. package/src/client/engine/saves/indexed.ts +2 -2
  147. package/src/client/engine/telemetry/browserErrors.ts +24 -3
  148. package/src/client/engine/telemetry/staleBuildReport.ts +22 -1
  149. package/src/client/engine/ui/debugOptions.ts +1 -1
  150. package/src/client/engine/ui/lookLightOption.ts +10 -6
  151. package/src/client/engine/ui/namePrompt.ts +7 -0
  152. package/src/client/engine/world/declaredProps.ts +5 -1
  153. package/src/client/engine/world/skyRig.ts +4 -1
  154. package/src/client/engine/world/terrainTileView.ts +64 -23
  155. package/src/client/game/boot/audio.generated.ts +114 -114
  156. package/src/client/game/boot/bytes.generated.ts +118 -220
  157. package/src/client/game/boot/placedSpawn.ts +35 -0
  158. package/src/client/game/boot/spawnDownload.ts +25 -6
  159. package/src/client/game/boot/versions.generated.ts +7 -5
  160. package/src/client/game/devScene/hook.ts +428 -0
  161. package/src/client/game/devScene/liveLook.ts +21 -0
  162. package/src/client/game/grid/cellLoading.ts +12 -2
  163. package/src/client/game/grid/live.ts +152 -19
  164. package/src/client/game/grid/liveSession.ts +53 -3
  165. package/src/client/game/grid/mapAtlas.ts +18 -4
  166. package/src/client/game/grid/minimapBlend.ts +15 -5
  167. package/src/client/game/grid/oneWayIn.ts +5 -1
  168. package/src/client/game/grid/pageEntry.ts +12 -1
  169. package/src/client/game/grid/placedCells.ts +114 -12
  170. package/src/client/game/grid/placedContent.ts +85 -0
  171. package/src/client/game/grid/prefetch.ts +9 -1
  172. package/src/client/game/grid/productInputs.ts +23 -10
  173. package/src/client/game/grid/productLeases.ts +4 -1
  174. package/src/client/game/grid/products.ts +8 -4
  175. package/src/client/game/grid/roadLook.ts +24 -15
  176. package/src/client/game/grid/roadLookPlatform.ts +4 -2
  177. package/src/client/game/grid/roadResources.ts +24 -0
  178. package/src/client/game/grid/roadSign.worker.ts +4 -3
  179. package/src/client/game/grid/roadSignPaint.ts +16 -5
  180. package/src/client/game/grid/roadSignPreparation.ts +4 -3
  181. package/src/client/game/grid/roadSignScale.ts +8 -0
  182. package/src/client/game/grid/roadTileCapture.worker.ts +3 -1
  183. package/src/client/game/grid/roadTileCaptureWorker.ts +2 -1
  184. package/src/client/game/grid/roadTileWrite.worker.ts +4 -2
  185. package/src/client/game/grid/roadTileWriter.ts +2 -1
  186. package/src/client/game/grid/screenReports.ts +39 -0
  187. package/src/client/game/grid/session.ts +32 -7
  188. package/src/client/game/grid/softWallLook.ts +25 -8
  189. package/src/client/game/mainMenu.ts +6 -2
  190. package/src/client/game/plugin/context.ts +2 -1
  191. package/src/client/game/plugin/followedMovers.ts +7 -1
  192. package/src/client/game/quest/figures.ts +2 -0
  193. package/src/client/game/session/finish.ts +9 -0
  194. package/src/client/game/shardfile/assetCache.ts +4 -4
  195. package/src/client/game/shardfile/client.ts +28 -8
  196. package/src/client/game/shardfile/clientAssets.ts +9 -5
  197. package/src/client/game/shardfile/clientLibrary.ts +1 -1
  198. package/src/client/game/shardfile/clientPropMaterials.ts +4 -1
  199. package/src/client/game/shardfile/clientViews.ts +36 -8
  200. package/src/client/game/shardfile/clientWater.ts +51 -9
  201. package/src/client/game/shardfile/clientWorker.ts +19 -7
  202. package/src/client/game/shardfile/constructionCheckpoint.ts +2 -2
  203. package/src/client/game/shardfile/groundMerge.ts +57 -5
  204. package/src/client/game/shardfile/hybrid.ts +2 -0
  205. package/src/client/game/shardfile/look.ts +8 -3
  206. package/src/client/game/shardfile/product.ts +34 -7
  207. package/src/client/game/shardfile/productChecks.ts +2 -2
  208. package/src/client/game/shardfile/productCost.ts +2 -2
  209. package/src/client/game/shardfile/readAsset.ts +2 -2
  210. package/src/client/game/shardfile/reflectingWater.ts +73 -0
  211. package/src/client/game/shardfile/seatGrace.ts +9 -0
  212. package/src/client/game/shardfile/skinPlayback.ts +1 -1
  213. package/src/client/game/shardfile/slabLibrary.ts +115 -49
  214. package/src/client/game/shardfile/tileContent.ts +1 -1
  215. package/src/client/game/shardfile/tileDriver.ts +38 -11
  216. package/src/client/game/shardfile/wirePage.ts +7 -3
  217. package/src/client/game/shardfile/worldScenes.ts +17 -10
  218. package/src/client/game/systems/npc/figureRows.ts +9 -0
  219. package/src/client/host/online/doctor.ts +22 -7
  220. package/src/client/host/online/doctorView.ts +2 -0
  221. package/src/client/host/online/linkScreens.ts +109 -5
  222. package/src/client/host/online/shell.ts +13 -4
  223. package/src/client/host/standalone/shell.ts +40 -0
  224. package/src/cook/game/astc6Encode.ts +55 -0
  225. package/src/cook/game/astc6Wasm.ts +176 -0
  226. package/src/cook/game/cookJob.ts +30 -6
  227. package/src/cook/game/cookWorker.ts +38 -11
  228. package/src/cook/game/entryTotals.ts +51 -24
  229. package/src/cook/game/shardCook.ts +35 -7
  230. package/src/cook/game/spawnParts.ts +33 -8
  231. package/src/cook/game/tierTextures.ts +87 -14
  232. package/src/server/engine/ai/bossContenders.ts +27 -3
  233. package/src/server/engine/ai/phases.ts +1 -1
  234. package/src/server/engine/entities/creatureRefill.ts +9 -2
  235. package/src/server/engine/net/ledgerBook.ts +2 -0
  236. package/src/server/engine/net/room.ts +15 -0
  237. package/src/server/engine/sim/respawn.ts +8 -0
  238. package/src/server/game/boss/arenaRoomEntry.ts +5 -1
  239. package/src/server/game/boss/arenaRoomNative.ts +2 -0
  240. package/src/server/game/boss/native.ts +2 -1
  241. package/src/server/game/boss/nativeWake.ts +9 -5
  242. package/src/server/game/boss/openArenaNative.ts +2 -2
  243. package/src/server/game/boss/openArenaRoom.ts +3 -1
  244. package/src/server/game/grid/room.ts +44 -3
  245. package/src/server/game/grid/simulation.ts +23 -0
  246. package/src/server/game/population/mixedRoster.ts +11 -3
  247. package/src/server/game/population/nativeBake.ts +8 -3
  248. package/src/server/game/population/nativeReturns.ts +6 -3
  249. package/src/server/game/population/roster.ts +5 -3
  250. package/src/server/game/quest/eliteDrops.ts +18 -3
  251. package/src/server/game/quest/nativeChapter.ts +1 -1
  252. package/src/server/game/quest/nativeComposition.ts +5 -1
  253. package/src/server/game/riding/nativeTaming.ts +22 -7
  254. package/src/server/game/riding/wildRefill.ts +3 -2
  255. package/src/server/game/shardfile/bossRow.ts +4 -2
  256. package/src/server/game/shardfile/homeKeeper.ts +4 -2
  257. package/src/server/host/bake/headlessWorker.ts +1 -1
  258. package/src/server/host/dedicated/cellHost.ts +112 -18
  259. package/src/server/host/dedicated/cellProtocol.ts +18 -1
  260. package/src/server/host/dedicated/cellWorker.ts +8 -5
  261. package/src/server/host/dedicated/dedicatedRoom.ts +38 -11
  262. package/src/server/host/dedicated/gridCells.ts +15 -6
  263. package/src/server/host/dedicated/loopLag.ts +21 -0
  264. package/src/server/host/dedicated/main.ts +13 -5
  265. package/src/server/host/dedicated/packReader.ts +3 -3
  266. package/src/server/host/dedicated/placementFile.ts +3 -2
  267. package/src/server/host/dedicated/roadRoom.ts +34 -4
  268. package/src/server/host/dedicated/serverMetrics.ts +135 -0
  269. package/src/server/host/dedicated/socketPump.ts +21 -4
  270. package/src/server/host/dedicated/workerTable.ts +32 -14
  271. package/src/server/host/dedicated/world.ts +65 -7
  272. package/src/server/host/headless.ts +1 -1
  273. package/src/server/host/headlessRuntime.ts +1 -1
  274. package/src/server/host/standalone/roadWorld.ts +15 -3
  275. package/src/server/host/standalone/serverHost.ts +57 -8
  276. package/src/server/host/standalone/serverProduct.ts +48 -16
  277. package/src/server/host/standalone/serverRuntime.ts +1 -1
  278. package/src/shared/engine/ai/BossBrain.ts +8 -0
  279. package/src/shared/engine/core/framePacing.ts +12 -1
  280. package/src/shared/engine/physics/terrainTiles.ts +20 -4
  281. package/src/shared/game/boss/wake.ts +6 -0
  282. package/src/shared/game/devColliders.ts +107 -0
  283. package/src/shared/game/devGameplay.ts +41 -0
  284. package/src/shared/game/eliteSystem.ts +8 -0
  285. package/src/shared/game/grid/allocator.ts +3 -0
  286. package/src/shared/game/grid/placementRows.ts +5 -2
  287. package/src/shared/game/plugin/bossRecord.ts +3 -2
  288. package/src/shared/game/shardfile/ktx2Targets.ts +23 -3
  289. package/src/shared/game/shardfile/outputDescriptor.ts +9 -5
  290. package/src/shared/game/shardfile/packReads.ts +28 -3
  291. package/src/shared/game/shardfile/serverPack.ts +9 -0
  292. package/src/shared/game/systems/looks/trampleField.ts +2 -0
  293. package/src/shared/host/formatJsonSchema.ts +2 -2
  294. package/src/tsconfig.json +1 -27
  295. package/lint/host-reviews.json +0 -14
  296. package/lint/listed-view-code.json +0 -13
  297. package/lint/platform-pending-users.json +0 -2520
  298. package/lint/platform-pending-users.md +0 -18
  299. package/scripts/cell-mem/metrics-preload.mjs +0 -65
  300. package/scripts/check-closed-components.d.mts +0 -7
  301. package/scripts/check-closed-components.mjs +0 -87
  302. package/scripts/g571-hosts.d.mts +0 -3
  303. package/scripts/g571-hosts.mjs +0 -54
  304. package/scripts/host-ruler/register-migrate.mjs +0 -242
  305. package/scripts/listed-view-code.d.mts +0 -7
  306. package/scripts/listed-view-code.mjs +0 -93
  307. package/scripts/look-loop/fit-lut.py +0 -142
  308. package/scripts/look-loop/palette-delta.py +0 -183
  309. package/scripts/look-loop/regions/driftwood-isle.json +0 -25
  310. package/scripts/look-loop/regions/far-reach.json +0 -225
  311. package/scripts/look-loop/regions/open-plot-night-market.json +0 -855
  312. package/scripts/look-loop/regions/pine-hollow.json +0 -22
  313. package/scripts/look-loop/regions/sunscar-dunes.json +0 -281
  314. package/scripts/platform-chargebacks.d.mts +0 -9
  315. package/scripts/platform-chargebacks.mjs +0 -135
  316. package/scripts/shard-component-spans.d.mts +0 -15
  317. package/scripts/shard-component-spans.mjs +0 -18
  318. package/scripts/shard-components.d.mts +0 -16
  319. package/scripts/shard-components.mjs +0 -363
  320. package/scripts/shard-platform-hosts.d.mts +0 -2
  321. package/scripts/shard-platform-hosts.mjs +0 -93
  322. package/scripts/shard-platform-sections.d.mts +0 -2
  323. package/scripts/shard-platform-sections.mjs +0 -9
  324. package/scripts/shard-platform.d.mts +0 -76
  325. package/scripts/shard-platform.mjs +0 -1072
  326. package/src/.oxfmtrc.json +0 -48
  327. package/src/scripts/ask-new.sh +0 -29
  328. package/src/scripts/asks.mjs +0 -142
  329. package/src/scripts/herdr-prompt.sh +0 -34
  330. package/src/scripts/herdr-question-open.sh +0 -67
  331. package/src/scripts/md-wrap.mjs +0 -229
  332. /package/scripts/{shard-platform-format.d.mts → node-format.d.mts} +0 -0
  333. /package/scripts/{shard-platform-format.mjs → node-format.mjs} +0 -0
  334. /package/scripts/{shard-platform-output.d.mts → output-reader.d.mts} +0 -0
@@ -13,6 +13,7 @@ import type { ResidencyAllocator, ResidencyLease, ResidencyEviction } from '../.
13
13
  import type { PreparedGridCrossing } from '../../../shared/game/grid/crossing';
14
14
  import type { HomeResidencyClaim } from './pageResidency';
15
15
  import { ApproachInputsDeferredError } from './productInputs';
16
+ import { PRODUCT_DEFERRED } from './productLeases';
16
17
  import { clientPreparationBatch } from '../shardfile/preparationTiming';
17
18
  import { tileOf, type CellTile } from '../../../shared/game/shardfile/tileOrder';
18
19
  import type { RegionShell } from './regionShell';
@@ -88,6 +89,8 @@ export interface LiveGridPorts {
88
89
  /** Crossing telemetry is a production port: the harness verifies real fixed-boundary commits, never a page/debug probe. */
89
90
  export interface LiveGridState {
90
91
  current: string | null; worldFeet: GridPoint; crossings: number;
92
+ /** GC5: the world built ahead of the traveller (on the road or pre-warmed inside the source), and how many pre-warms began */
93
+ ahead?: { readonly instance: string | null; readonly warms: number; readonly refused?: string | null; readonly deferred?: readonly string[]; readonly demanded?: string | null; readonly released?: number };
91
94
  /** Last complete world remains fully charged and pressure-evictable on the road. */
92
95
  retainedCell?: { readonly instance: string; readonly remainingMs: number; readonly playingBytes: number; readonly capBytes: number } | null;
93
96
  transitions: readonly { from: string | null; to: string | null }[];
@@ -115,6 +118,10 @@ interface Resident { region: LiveGridRegion; lease: ResidencyLease; reservations
115
118
  // Contact corrections at a closed readiness wall are not a U-turn. Accumulate real horizontal travel
116
119
  // before selecting another approach, so sub-centimetre capsule recoil cannot evict the world just prepared.
117
120
  const APPROACH_TRAVEL_METRES = 0.1;
121
+ // GC5: the page pre-warms a neighbour's world from inside the source, at the distance the traveller covers at its speed in that
122
+ // world's last measured build time (2 s at least; before it is measured, the slowest build so far or 14 s, capped at 16 s), times a margin. Kept while the traveller stays within
123
+ // WARM_KEEP_METRES of it; the lead is capped below that, so a pre-warm never starts where it would be dropped.
124
+ const DEMAND_METRES = 80, HELD_RETRY_MS = 5000, HEADING_HOLD_MS = 600, FIXED_HZ = 60, WARM_DEFAULT_SECONDS = 14, WARM_MIN_SECONDS = 2, WARM_MAX_SECONDS = 16, WARM_MARGIN = 1.25, WARM_LEAD_METRES = 8, WARM_LEAD_CAP_METRES = 200, WARM_KEEP_METRES = 240;
118
125
  const entryAxes = [['x', 'z'], ['z', 'x']] as const;
119
126
  // Distance can decrease while passing parallel to a cell. Only a ray into its first boundary's midpoint mouth
120
127
  // predicts entry; product downloads remain radial, but an unrelated native world must not block the real turn-in.
@@ -169,6 +176,9 @@ export class LiveGridHost {
169
176
  private readonly productRequests = new Map<string, { work: Promise<LiveGridAdmission>; required: boolean;
170
177
  trigger: 'entry' | 'explicit' | 'radial' | 'boulevard' }>();
171
178
  private readonly deferredProducts = new Map<string, number>();
179
+ /** GC6: a demand read (the neighbour ahead) the budget refused, by allocator revision: kept apart from the radial reads'
180
+ * deferrals, since a radial read deferred for want of headroom must not stop the demand read that may make room */
181
+ private readonly deferredDemand = new Map<string, number>();
172
182
  private readonly issues = new Map<string, string>();
173
183
  private readonly refusals = new Map<string, unknown>();
174
184
  /** One failed cold unload per excursion; quota failures retain their full claim until retry or re-approach. */
@@ -177,7 +187,21 @@ export class LiveGridHost {
177
187
  private frameGeneration = 0;
178
188
  private readonly transitions: { from: string | null; to: string | null }[] = [];
179
189
  private crossings = 0;
190
+ private warms = 0;
191
+ /** QA row 43: when a traveller held at a cell's wall may next retry its failed build */
192
+ private readonly heldRetryAt = new Map<string, number>();
193
+ /** the other mouth the traveller inside the source turned to, and since when (HEADING_HOLD_MS) */
194
+ private turnedSince: { instance: string; at: number } | null = null;
195
+ /** GC5: why the last pre-warm the heading asked for did not start (its product still reading, an exclusive runtime, or the budget) */
196
+ private warmRefusal: string | null = null;
197
+ /** GC6: the neighbour whose product is read as demand (the nearest edge's, or the heading's) and not yet admitted: radial
198
+ * reads of other cells wait while it is missing, so they don't take back the headroom its read needs. */
199
+ private demanded: string | null = null;
180
200
  private previousFeet: GridPoint | undefined;
201
+ /** fixed steps since `previousFeet` moved, for the traveller's speed (GC5) */
202
+ private stepsSincePrevious = 0;
203
+ /** GC5: each cell's last measured world build, in seconds (product to colliders and sim ready) */
204
+ private readonly builtSeconds = new Map<string, number>();
181
205
  private readonly candidateDistances = new Map<GridCell,number>();
182
206
  private readonly approachWork:{candidates:GridCell[];boulevard:GridCell[]}[]=[];
183
207
  /** This host already owns the assembly and its frozen cells for its whole lifetime. */
@@ -243,18 +267,21 @@ export class LiveGridHost {
243
267
  }
244
268
  /** Submit whole-shard requests in stable order. Failed attempts remain closed until an explicit retry. */
245
269
  prefetch(instances: readonly string[], trigger: 'explicit' | 'radial' | 'boulevard' = 'explicit'): Promise<void> { return Promise.all([...new Set(instances)].sort().map((id) => this.residents.has(id) || (!this.disposed && this.constructing.has(id)) || this.deferredProducts.get(id) === this.ports.allocator.revision ? Promise.resolve() : this.prefetchProduct(id, false, trigger))).then(() => undefined); }
246
- private async requireProduct(instance: string, pending: Promise<LiveGridAdmission>): Promise<LiveGridAdmission> {
270
+ private async requireProduct(instance: string, pending: Promise<LiveGridAdmission>, trigger: 'entry' | 'explicit' | 'radial' | 'boulevard' = 'entry', speculative = false): Promise<LiveGridAdmission> {
247
271
  try { return await pending; }
248
272
  catch (error) {
249
- if (!(error instanceof ApproachInputsDeferredError)) throw error;
250
- return this.prefetchProduct(instance, true);
273
+ // the optional read's budget deferral says nothing of a required one: read it again as required
274
+ if (!(error instanceof ApproachInputsDeferredError) && !(error instanceof Error && error.message.includes(PRODUCT_DEFERRED))) throw error;
275
+ return this.prefetchProduct(instance, true, trigger, speculative);
251
276
  }
252
277
  }
253
- private prefetchProduct(instance: string, required = false, trigger: 'entry' | 'explicit' | 'radial' | 'boulevard' = 'entry'): Promise<LiveGridAdmission> {
278
+ /** `speculative`: a demand read nobody waits on yet (GC5's near neighbour and pre-warm). Its budget refusal is deferred
279
+ * until the budget changes, as a radial read's is, not a failed cell that closes the radial read, the pre-warm and the road. */
280
+ private prefetchProduct(instance: string, required = false, trigger: 'entry' | 'explicit' | 'radial' | 'boulevard' = 'entry', speculative = false): Promise<LiveGridAdmission> {
254
281
  this.assertAlive(); const cell = this.assembly.cell(instance);
255
282
  const product = this.products.get(instance); if (product !== undefined) return Promise.resolve(product);
256
283
  const pending = this.productRequests.get(instance);
257
- if (pending !== undefined) return !required || pending.required ? pending.work : this.requireProduct(instance, pending.work);
284
+ if (pending !== undefined) return !required || pending.required ? pending.work : this.requireProduct(instance, pending.work, trigger, speculative);
258
285
  const issue = this.issues.get(instance); if (issue !== undefined) return Promise.reject(new Error(issue));
259
286
  const timing = clientPreparationBatch(cell.slug, `grid.product:${instance}`, ['admission', 'runtime']);
260
287
  const request = (async (): Promise<LiveGridAdmission> => {
@@ -268,11 +295,16 @@ export class LiveGridHost {
268
295
  if ((bundle.hybridWireBytes > 0 || admission.exclusiveRuntime === true) && admission.prepareRuntime === undefined) throw new Error('Hybrid runtime admission is missing');
269
296
  await (timing === undefined ? admission.prepareRuntime?.() : timing.run('runtime', async () => { await admitted.prepareRuntime?.(); }));
270
297
  this.assertAlive();
271
- this.deferredProducts.delete(instance); this.products.set(instance, admission); return admission;
298
+ this.deferredProducts.delete(instance); this.deferredDemand.delete(instance); this.products.set(instance, admission); return admission;
272
299
  } catch (error) {
273
300
  this.tileMetadata.delete(instance);
274
301
  if (this.tileApproach?.instance === instance) { this.tileApproach.controller.abort(); this.tileApproach = null; }
275
- if (!required && error instanceof ApproachInputsDeferredError) this.deferredProducts.set(instance, this.ports.allocator.revision);
302
+ const refused = error instanceof ApproachInputsDeferredError || (error instanceof Error && error.message.includes(PRODUCT_DEFERRED));
303
+ // GC6 (QA 11-14 row 6): inside Driftwood the page held 3 to 5 neighbours' radial products (1199 of 1200 MB), pinned
304
+ // while held, so Nalati's demand read was refused the whole approach and its world was built only on the road. A
305
+ // refused demand read lets the speculative products of other cells go, farthest first, and is read again.
306
+ if (required && speculative && refused) { if (this.releaseSpeculative(instance) > 0) this.deferredDemand.delete(instance); else { this.deferredDemand.set(instance, this.ports.allocator.revision); if (this.demanded === instance) this.demanded = null; } }
307
+ else if (!required && refused) this.deferredProducts.set(instance, this.ports.allocator.revision);
276
308
  else { this.issues.set(instance, error instanceof Error ? error.message : String(error)); this.refusals.set(instance, error); }
277
309
  try { admission?.cancel?.(); }
278
310
  catch (cleanup) { throw new AggregateError([error, cleanup], 'Live product admission and cancellation failed', { cause: cleanup }); }
@@ -281,9 +313,28 @@ export class LiveGridHost {
281
313
  })();
282
314
  this.productRequests.set(instance, { work: request, required, trigger }); return request;
283
315
  }
316
+ /** GC6: let every admitted product nobody builds, enters or reads ahead go except `kept`'s, farthest first (each releases
317
+ * its claim, so the allocator's revision moves and a deferred demand read is tried again). Returns how many went. */
318
+ private releaseSpeculative(kept: string): number {
319
+ const feet = this.worldFeet(), keep = (id: string): boolean => id === kept || id === this.active || id === this.ahead
320
+ || this.constructing.has(id) || this.requests.has(id) || this.residents.has(id)
321
+ || id === this.tileApproach?.instance || id === this.transportApproach?.instance;
322
+ const idle = [...this.products.keys()].filter(id => !keep(id))
323
+ .sort((a, b) => this.distance(this.assembly.cell(b), feet) - this.distance(this.assembly.cell(a), feet));
324
+ for (const id of idle) {
325
+ const admission = this.products.get(id); this.products.delete(id); this.tileMetadata.delete(id);
326
+ try { admission?.cancel?.(); } catch (error) { console.warn(`[grid] ${id}: releasing a speculative product`, error); }
327
+ }
328
+ this.released += idle.length;
329
+ return idle.length;
330
+ }
331
+ /** GC6: how many speculative products a demand read let go (`releaseSpeculative`), for the tour */
332
+ private released = 0;
284
333
  /** GC5 / GC36: the cell whose world the road is building or built ahead of its line (`buildAhead`), kept until the
285
334
  * traveller enters a cell or heads into another's mouth. */
286
335
  private ahead: string | null = null;
336
+ /** GC9: the optional read last raised to demand, so a pending radial read is raised once, not every tick */
337
+ private raised: Promise<LiveGridAdmission> | null = null;
287
338
  private tileApproach: { instance: string; tile: CellTile; controller: AbortController } | null = null;
288
339
  private transportApproach: { instance: string; controller: AbortController; work: Promise<void> } | null = null;
289
340
  private retiredTransport: Promise<void> = Promise.resolve();
@@ -352,6 +403,7 @@ export class LiveGridHost {
352
403
  await (timing === undefined ? previous : timing.run('queue', () => previous));
353
404
  await this.retiredTransport;
354
405
  this.assertAlive();
406
+ const buildStart = diagnosticNow();
355
407
  const admitted = timing === undefined ? await this.prefetchProduct(instance, true) : await timing.run('metadata', () => this.prefetchProduct(instance, true));
356
408
  admission = admitted;
357
409
  this.assertAlive();
@@ -386,6 +438,7 @@ export class LiveGridHost {
386
438
  this.assertAlive();
387
439
  this.residents.set(instance, { region, lease, reservations: 0, evicting: false, retainable: admitted.isolatedPreparation === true });
388
440
  this.readiness.complete(ticket, 'colliders'); this.readiness.complete(ticket, 'sim');
441
+ this.builtSeconds.set(instance, (diagnosticNow() - buildStart) / 1000);
389
442
  lease.update({ needed: false, distance: this.distance(cell) });
390
443
  } catch (error) {
391
444
  try { region?.dispose(); }
@@ -457,6 +510,13 @@ export class LiveGridHost {
457
510
  resident.lease.update({ needed: false, distance: this.distance(this.assembly.cell(instance)) });
458
511
  return this.lastCell === last;
459
512
  }
513
+ /** GC5: how far from a neighbour's square its world starts building at `speed` (m/s): its measured build time, or the
514
+ * slowest measured so far or the default, at least WARM_MIN_SECONDS, with a margin; capped below the keep distance. */
515
+ private warmLead(instance: string, speed: number): number {
516
+ const measured = this.builtSeconds.get(instance) ?? Math.max(WARM_DEFAULT_SECONDS, ...this.builtSeconds.values());
517
+ const seconds = Math.min(WARM_MAX_SECONDS, Math.max(WARM_MIN_SECONDS, measured));
518
+ return Math.min(WARM_LEAD_CAP_METRES, WARM_LEAD_METRES + speed * seconds * WARM_MARGIN);
519
+ }
460
520
  private distance(cell: GridCell, p = this.worldFeet()): number { return Math.hypot(Math.max(0, Math.abs(p.x - cell.origin.x) - CHUNK_HALF), Math.max(0, Math.abs(p.z - cell.origin.z) - CHUNK_HALF)); }
461
521
  /** Only the active/reserved world and one bounded departed world can remain.
462
522
  * A different actual entry retires the departure before any new allocation. */
@@ -474,10 +534,13 @@ export class LiveGridHost {
474
534
  }
475
535
  return released;
476
536
  }
537
+ /** GC6: whether a world is being built (pre-warmed inside the source, built ahead on the road, or entered): every world build
538
+ * is for a cell the traveller heads into, so its slices are urgent (`setBuildUrgent`). */
539
+ building(): boolean { return this.requests.size > 0; }
477
540
  /** Retry after a durability/budget change, instead of fetching the same failed request every tick. */
478
541
  retry(instance: string): void {
479
542
  if (this.requests.has(instance) || this.productRequests.has(instance)) throw new Error('Live admission is still pending');
480
- this.coldUnloadRefused.delete(instance); this.deferredProducts.delete(instance);
543
+ this.coldUnloadRefused.delete(instance); this.deferredProducts.delete(instance); this.deferredDemand.delete(instance);
481
544
  // A quota-refused unload kept a complete native region: retry must not invalidate its valid readiness ticket.
482
545
  if (this.residents.has(instance)) return;
483
546
  this.issues.delete(instance); this.refusals.delete(instance); this.readiness.invalidate(instance);
@@ -500,7 +563,8 @@ export class LiveGridHost {
500
563
  // More than a second of modeled travel between fixed samples is a pose/portal jump.
501
564
  // Establish a new origin instead of spending a constructor on its accidental direction.
502
565
  const travelled = previous !== undefined && travelledDistance >= APPROACH_TRAVEL_METRES && travelledDistance <= this.ports.readiness.link.speed;
503
- if (previous === undefined || travelledDistance >= APPROACH_TRAVEL_METRES) this.previousFeet = feet;
566
+ const steps = ++this.stepsSincePrevious, speed = travelled ? travelledDistance * FIXED_HZ / steps : 0;
567
+ if (previous === undefined || travelledDistance >= APPROACH_TRAVEL_METRES) { this.previousFeet = feet; this.stepsSincePrevious = 0; }
504
568
  // Prefetch the closest cells' products (never their worlds: G663). Unsupported far proxies do not consume the count
505
569
  // before enterable cells inside the cold readiness bound.
506
570
  const candidates=work.candidates,cells=this.assembly.cells;
@@ -513,13 +577,36 @@ export class LiveGridHost {
513
577
  // Immutable products are selected by distance, without a whole-world count cap.
514
578
  const nearby = candidates;
515
579
  // The frame-transfer reservation protects an actual entry; inactive whole worlds retire in steps. A world built ahead
516
- // (`buildAhead`) stays while the traveller is on the road and has not turned into another mouth (below).
517
- if (this.active !== null) this.ahead = null;
580
+ // (`buildAhead`) stays while the traveller is on the road and has not turned into another mouth (below); one pre-warmed
581
+ // from inside the source (GC5) stays while the traveller is within WARM_KEEP_METRES of it.
582
+ if (this.active !== null && this.ahead !== null && (this.ahead === this.active
583
+ || this.distance(this.assembly.cell(this.ahead), feet) > WARM_KEEP_METRES)) this.ahead = null;
518
584
  this.retireInactiveRegions();
585
+ // GC6: the demanded neighbour stays demanded until its product is in, it is entered, or the traveller is far from it
586
+ const demanded = this.demanded;
587
+ if (demanded !== null && (this.products.has(demanded) || this.residents.has(demanded) || demanded === this.active || this.issues.has(demanded)
588
+ || this.distance(this.assembly.cell(demanded), feet) > DEMAND_METRES + WARM_LEAD_METRES * 4)) this.demanded = null;
519
589
  for (const cell of nearby) {
520
590
  const estimate = readinessModel(this.ports.readiness.bundle(cell), this.ports.readiness.link), distance = this.distance(cell, feet);
591
+ if (this.demanded !== null && this.demanded !== cell.instance) continue;
521
592
  if (this.assembly.approaching(distance, estimate.distance) && !this.issues.has(cell.instance) && this.ports.backgroundReady?.() !== false) void background(cell.instance, this.prefetch([cell.instance], 'radial'), () => !this.disposed);
522
593
  }
594
+ // GC5: the neighbour across the source's nearest edge, within DEMAND_METRES, has its product read as demand, standing or
595
+ // moving: a player at a cell's edge reaches it in seconds at a boost, and the radial read above is only a guess the shared
596
+ // budget declines while every neighbour competes for it (Pine's read alone is 6 to 8 s). One at a time, the nearest.
597
+ if (this.active !== null && this.ports.buildAhead === true) {
598
+ const near = candidates[0];
599
+ // GC9: a radial read already pending for it is raised to demand once (the budget declined Pine's radial read again and
600
+ // again while it stood pending, so the demand read never started inside Driftwood and Pine's world was built on the road)
601
+ const pending = near === undefined ? undefined : this.productRequests.get(near.instance);
602
+ if (near !== undefined && this.distance(near, feet) <= DEMAND_METRES && !this.products.has(near.instance) && !this.residents.has(near.instance)
603
+ && (pending === undefined || !pending.required && this.raised !== pending.work) && !this.issues.has(near.instance) && !this.constructing.has(near.instance)
604
+ && this.deferredDemand.get(near.instance) !== this.ports.allocator.revision && this.ports.backgroundReady?.() !== false) {
605
+ if (pending !== undefined) this.raised = pending.work;
606
+ this.demanded = near.instance;
607
+ void background(near.instance, this.prefetchProduct(near.instance, true, 'explicit', true), () => !this.disposed);
608
+ }
609
+ }
523
610
  // Approach preparation owns render tiles only, never a regional world or gameplay hooks.
524
611
  const moving = !travelled ? undefined : candidates.find(cell => headsToEntry(cell, feet, previous)
525
612
  && this.distance(cell, feet) < this.distance(cell, previous) - 0.000001);
@@ -542,11 +629,21 @@ export class LiveGridHost {
542
629
  }
543
630
  // The world built ahead goes once the traveller is a pitch from it, or heads from the road into another mouth (a stop
544
631
  // keeps it). Checked while a build runs too, which the gate below skips.
632
+ const wallReach = 6 + this.ports.player.motor.opts.radius + 0.5 + this.ports.readiness.link.speed / 60;
633
+ const departed = this.transitions.at(-1)?.from;
634
+ // QA 11-13 row 43: on the road within a cell's wall reach the traveller is at that cell's wall, whatever the heading: a
635
+ // jump or a recoil off the wall reads as a heading back into the cell just left, which let the world built ahead go.
636
+ const held = this.ports.buildAhead === true && this.active === null && this.assembly.at(feet.x, feet.z) === undefined
637
+ ? nearby.find(cell => cell.instance !== departed && this.distance(cell, feet) <= wallReach) : undefined;
638
+ // Inside the source a new heading must hold HEADING_HOLD_MS before it retires the world built ahead: steering that
639
+ // wobbles near a corner would otherwise build and dispose a whole world per flip.
640
+ const turned = moving !== undefined && moving.instance !== this.ahead;
641
+ if (!turned || this.active === null) this.turnedSince = null;
642
+ else if (this.turnedSince?.instance !== moving.instance) this.turnedSince = { instance: moving.instance, at: diagnosticNow() };
643
+ const settledTurn = turned && (this.active === null || diagnosticNow() - (this.turnedSince?.at ?? 0) >= HEADING_HOLD_MS);
545
644
  if (this.ahead !== null && (this.distance(this.assembly.cell(this.ahead), feet) >= this.assembly.pitch
546
- || moving !== undefined && moving.instance !== this.ahead && this.assembly.at(feet.x, feet.z) === undefined)) this.ahead = null;
645
+ || held === undefined && settledTurn && (this.assembly.at(feet.x, feet.z) === undefined || this.active !== null))) this.ahead = null;
547
646
  if (this.requests.size === 0) {
548
- const wallReach = 6 + this.ports.player.motor.opts.radius + 0.5 + this.ports.readiness.link.speed / 60;
549
- const departed = this.transitions.at(-1)?.from;
550
647
  const boulevard=work.boulevard;
551
648
  if(travelled&&moving===undefined)for(let i=0,length=candidates.length;i<length;i++){
552
649
  const cell=candidates[i];if(cell!==undefined&&cell.instance!==departed
@@ -579,12 +676,47 @@ export class LiveGridHost {
579
676
  // cell retires first, as the entry would retire it; a U-turn builds it again, as any entry does.
580
677
  // Only from the road itself: past a cell's line (inside its square, before the 6 m entry) the heading names the cell
581
678
  // beyond it, which would retire the world just built for the one underfoot.
582
- if (this.ports.buildAhead === true && moving !== undefined && this.active === null && this.assembly.at(feet.x, feet.z) === undefined
679
+ // QA 11-13 row 43 (Jake on staging: 11 s at Template's wall, "saved state and its systems", no progress): a traveller
680
+ // standing at a neighbour's closed wall makes no heading (under 0.1 m a sample), so a world built ahead and then let go
681
+ // was never asked for again, and online the server crosses only past the line the wall holds them short of. Held at
682
+ // a closed wall on the road, that cell's world is always building.
683
+ // A failed build is tried again while they stand there, at most every HELD_RETRY_MS (never on a cleanup failure).
684
+ if (held !== undefined && this.issues.has(held.instance) && !this.residents.has(held.instance) && !this.requests.has(held.instance) && !this.productRequests.has(held.instance)
685
+ && diagnosticNow() >= (this.heldRetryAt.get(held.instance) ?? 0)) { this.heldRetryAt.set(held.instance, diagnosticNow() + HELD_RETRY_MS); this.retry(held.instance); }
686
+ if (held !== undefined && !this.residents.has(held.instance) && !this.issues.has(held.instance)) {
687
+ this.ahead = held.instance;
688
+ if (this.retireInactiveRegions(held.instance)) void background(held.instance, this.ensure(held.instance), () => !this.disposed);
689
+ }
690
+ else if (held === undefined && this.ports.buildAhead === true && moving !== undefined && this.active === null && this.assembly.at(feet.x, feet.z) === undefined
583
691
  && !this.residents.has(moving.instance) && !this.issues.has(moving.instance)
584
692
  && this.distance(moving, feet) < this.assembly.pitch && this.retireInactiveRegions(moving.instance)) {
585
693
  this.ahead = moving.instance;
586
694
  void background(moving.instance, this.ensure(moving.instance), () => !this.disposed);
587
695
  }
696
+ // GC5 (QA 11-13 row 39: boosts held 4 to 7.6 s at the neighbour's loading wall, the road being under 3 s at 18 m/s):
697
+ // inside the source, heading into a neighbour's mouth, its world is built once the traveller is its measured build
698
+ // time away at this speed. Only beside an isolated source and for an isolated product (opaque runtimes stay exclusive,
699
+ // built only on the road), and only when both fit beside each other (G723); else the road builds it as before.
700
+ if (this.ports.buildAhead === true && moving !== undefined && this.active !== null && this.ahead === null
701
+ && this.residents.get(this.active)?.retainable === true && !this.residents.has(moving.instance) && !this.issues.has(moving.instance)
702
+ && this.distance(moving, feet) <= this.warmLead(moving.instance, speed)) {
703
+ const product = this.products.get(moving.instance);
704
+ // The heading names it: its product is read as demand (it may evict speculative neighbours' products), not as a radial
705
+ // guess, which the shared budget declines while the page's other neighbours compete for the same headroom.
706
+ if (product === undefined) {
707
+ this.warmRefusal = 'product';
708
+ this.demanded = moving.instance;
709
+ if (!this.productRequests.has(moving.instance) && this.deferredDemand.get(moving.instance) !== this.ports.allocator.revision)
710
+ void background(moving.instance, this.prefetchProduct(moving.instance, true, 'explicit', true), () => !this.disposed);
711
+ }
712
+ else if (product.isolatedPreparation !== true) this.warmRefusal = 'exclusive';
713
+ else if (!this.ports.allocator.canPrepareAlongside(this.active, moving.instance, product.bytes,
714
+ { playing: this.ports.allocator.envelope(), loading: CONTENT_CAPS.loading })) this.warmRefusal = 'budget';
715
+ else {
716
+ this.ahead = moving.instance; this.warms++; this.warmRefusal = null;
717
+ void background(moving.instance, this.ensure(moving.instance), () => !this.disposed);
718
+ }
719
+ }
588
720
  if (approach !== undefined && this.ports.prepareNeighbour !== undefined && this.tileMetadata.has(approach.instance)
589
721
  && !this.residents.has(approach.instance) && !this.issues.has(approach.instance)
590
722
  && (this.active === null || moving === approach)
@@ -710,8 +842,9 @@ export class LiveGridHost {
710
842
  /** Prepare disabled replacement controllers while the existing page stays authoritative; no entered runtime hooks run here. */
711
843
  async prepare(from: string | null, to: string | null): Promise<PreparedGridCrossing> {
712
844
  if (this.disposed || this.active !== from || from === to) throw new Error('Stale live frame preparation');
713
- // An entry anywhere but the world built ahead lets that world go, so it retires before this one allocates.
714
- if (this.ahead !== to) this.ahead = null;
845
+ // An entry anywhere but the world built ahead lets that world go, so it retires before this one allocates. Stepping out
846
+ // onto the road keeps one pre-warmed from inside the source (GC5).
847
+ if (to !== null && this.ahead !== to) this.ahead = null;
715
848
  if (from !== null && to !== null) throw new Error('Owned runtime crossing must commit onto the neutral road first');
716
849
  // Protect a ready return before yielding: expiry/pressure cannot free it
717
850
  // between its selection and the final prepared-frame reservation.
@@ -767,7 +900,7 @@ export class LiveGridHost {
767
900
  playingBytes: this.ports.allocator.ownerCost(last.instance).playing, capBytes: Math.min(CONTENT_CAPS.playing, policy.playingBytes) };
768
901
  }
769
902
  /** Read-only crossing evidence and failures for the real grid physics harness. */
770
- state(): LiveGridState { return { current: this.active, worldFeet: this.worldFeet(), crossings: this.crossings, transitions: this.transitions.map((row) => ({ ...row })), residents: [...this.residents.keys()].sort(), pending: [...new Set([...this.requests.keys(), ...this.productRequests.keys()])].sort(), pendingWork: [
903
+ state(): LiveGridState { return { current: this.active, worldFeet: this.worldFeet(), crossings: this.crossings, ahead: { instance: this.ahead, warms: this.warms, refused: this.warmRefusal, deferred: [...new Set([...this.deferredProducts.keys(), ...this.deferredDemand.keys()])], demanded: this.demanded, released: this.released }, transitions: this.transitions.map((row) => ({ ...row })), residents: [...this.residents.keys()].sort(), pending: [...new Set([...this.requests.keys(), ...this.productRequests.keys()])].sort(), pendingWork: [
771
904
  ...[...this.requests.keys()].sort().map(instance => ({ instance, kind: 'world' as const, trigger: 'entry' as const })),
772
905
  ...[...this.productRequests].sort(([a], [b]) => a.localeCompare(b)).map(([instance, request]) => ({ instance, kind: request.required ? 'required-metadata' as const : 'optional-metadata' as const, trigger: request.trigger })),
773
906
  ], issues: Object.fromEntries(this.issues), gameplayReady: this.active === null || this.ports.gameplayReady(this.active), ...(this.ports.lastCell === undefined ? {} : { retainedCell: this.retainedState() }), retirements: this.retirements.map(row => ({ ...row })), retiring: [...this.retiring.keys()], ghosts: { count: this.ghosts.count(), regions: this.ghosts.regions() } }; }
@@ -807,7 +940,7 @@ export class LiveGridHost {
807
940
  try { this.highway.dispose(); this.highwayDisposed = true; this.highwayLease.release(); }
808
941
  catch (error) { failures.push(error); }
809
942
  }
810
- this.deferredProducts.clear();
943
+ this.deferredProducts.clear(); this.deferredDemand.clear();
811
944
  if (failures.length > 0) throw new AggregateError(failures, 'Live grid disposal failed');
812
945
  }
813
946
  }
@@ -241,6 +241,10 @@ export class LiveGridSession {
241
241
  private readonly plotBanks = new Map<string, ReturnType<PlotAudioPorts['bank']>>();
242
242
  private readonly runtimeScope: Scope;
243
243
  private readonly runtimeRegions = new Map<string, PreparedRegionalRuntime>();
244
+ /** GC9: worlds pre-warmed from inside an entered runtime (GC5), whose entry preparation waits for the source to be left:
245
+ * the hybrid session prepares an entry only from the neutral road, so preparing it inside the source threw away the
246
+ * whole world just built ("Entry preparation requires the neutral road") and closed the cell until a retry. */
247
+ private readonly deferredEntries = new Map<string, { readonly prepared: PreparedRegionalRuntime; readonly signal: AbortSignal | undefined }>();
244
248
  private readonly leaveTiming: { instance: string; leaveMs: number }[] = [];
245
249
  private readonly runtimeResidents = new Map<string, HybridResident>();
246
250
  private readonly hybrid: HybridRuntimeSession;
@@ -268,7 +272,7 @@ export class LiveGridSession {
268
272
  // Register the resident parent before the live host disposer: the traveller returns before native children free.
269
273
  this.runtimeScope = scope.child('grid.runtime.residents');
270
274
  this.hybrid = new HybridRuntimeSession(this.runtimeResidents, scope, { pause: yieldGridConstruction });
271
- scope.onDispose(gridCells.onLeave(() => { this.hybrid.leave(); }));
275
+ scope.onDispose(gridCells.onLeave(() => { this.hybrid.leave(); this.prepareDeferredEntries(); }));
272
276
  scope.onDispose(gridCells.onLeave(() => { this.leavePlotAudio(); }));
273
277
  scope.onDispose(gridCells.onEnter(cell => {
274
278
  if (!this.runtimeResidents.has(cell.instance)) { this.enterPlotAudio(cell.instance); ports.lightingSettled?.(); return; }
@@ -394,7 +398,7 @@ export class LiveGridSession {
394
398
 
395
399
  private installCrossing(): GridCrossingSession {
396
400
  return installGridCrossing({ current: () => this.live.current(), prepare: (from, to) => this.prepareCrossing(from, to),
397
- ready: (instance) => this.live.ready(instance), checkpoint: (instance) => {
401
+ ready: (instance) => this.live.ready(instance) && (instance === null || !this.entryPending(instance)), checkpoint: (instance) => {
398
402
  if (this.wire !== null) return true; // the server's saves are the session's
399
403
  const readiness = this.page.crossingSaveReady?.(instance) ?? true;
400
404
  return readiness === true ? this.live.checkpoint(instance) : readiness;
@@ -800,7 +804,8 @@ export class LiveGridSession {
800
804
  this.respawnCells.set(cell.instance, { instance: cell.instance, origin: cell.origin, entryways: retained.admitted.source.entryways });
801
805
  try {
802
806
  await this.hybrid.prepare(cell.instance);
803
- if (!await this.hybrid.prepareEntry(cell.instance, signal)) throw new Error('Admitted entry preparation left its requested cell');
807
+ if (this.hybrid.state().instance === null) { if (!await this.hybrid.prepareEntry(cell.instance, signal)) throw new Error('Admitted entry preparation left its requested cell'); }
808
+ else this.deferredEntries.set(cell.instance, { prepared, signal });
804
809
  prepared.park?.(); // Only actual entry demand reaches here; keep its frame hidden until commit.
805
810
  }
806
811
  catch (error) {
@@ -815,6 +820,7 @@ export class LiveGridSession {
815
820
  const forget = (): void => {
816
821
  if (forgotten) return;
817
822
  forgotten = true;
823
+ if (this.deferredEntries.get(cell.instance)?.prepared === prepared) this.deferredEntries.delete(cell.instance);
818
824
  if (this.runtimeRegions.get(cell.instance) === prepared) {
819
825
  this.startedRuntimes.delete(cell.instance);
820
826
  this.runtimeRegions.delete(cell.instance); this.runtimeResidents.delete(cell.instance); this.transferWalls.delete(cell.instance);
@@ -864,8 +870,52 @@ export class LiveGridSession {
864
870
  const current = this.live.current();
865
871
  return current !== null && this.runtimeRegions.has(current) ? current : null;
866
872
  }
873
+ /** GC6 (QA 11-14 row 6): a world built ahead whose entry still prepares (deferred inside the source, or running on the
874
+ * road). Inside the cell its gameplay gate (`frameReady`) stops the page's frames, and that preparation's warm-up waits on
875
+ * drawn frames: the traveller stood in the cell with no control for good. Its crossing holds on the road instead. */
876
+ entryPending(instance: string): boolean { return this.deferredEntries.has(instance) || this.queuedEntries.has(instance) || this.hybrid.preparing().includes(instance); }
877
+ /** GC6: whether any world built ahead still prepares its entry (the road then builds with the urgent budget) */
878
+ entriesPending(): boolean { return this.deferredEntries.size > 0 || this.queuedEntries.size > 0 || this.hybrid.preparing().length > 0; }
879
+ /** GC6: entries taken from `deferredEntries` and waiting their turn behind another's preparation (`prepareInTurn`) */
880
+ private readonly queuedEntries = new Set<string>();
881
+ /** GC9: once the source is left (the hybrid session is neutral), each world pre-warmed inside it prepares its entry, so the
882
+ * crossing finds it ready; a crossing that arrives first holds on the road until it is (`entryPending`, GC6). */
883
+ private prepareDeferredEntries(): void {
884
+ // one at a time, nearest first: an entry preparation binds the page's one construction environment
885
+ const feet = this.live.worldFeet(), gap = (instance: string): number => {
886
+ const origin = this.ports.assembly.cell(instance).origin; return Math.hypot(origin.x - feet.x, origin.z - feet.z);
887
+ };
888
+ const rows = [...this.deferredEntries].sort(([a], [b]) => gap(a) - gap(b));
889
+ this.deferredEntries.clear();
890
+ for (const [instance] of rows) this.queuedEntries.add(instance);
891
+ this.deferredPreparation = this.prepareInTurn(this.deferredPreparation, rows);
892
+ }
893
+ private async prepareInTurn(previous: Promise<void>, rows: readonly (readonly [string, { readonly prepared: PreparedRegionalRuntime; readonly signal: AbortSignal | undefined }])[]): Promise<void> {
894
+ await previous;
895
+ for (const [instance, row] of rows) await this.prepareEntryOnRoad(instance, row);
896
+ }
897
+ private deferredPreparation: Promise<void> = Promise.resolve();
898
+ private async prepareEntryOnRoad(instance: string, row: { readonly prepared: PreparedRegionalRuntime; readonly signal: AbortSignal | undefined }): Promise<void> {
899
+ const live = (): boolean => this.runtimeRegions.get(instance) === row.prepared && row.signal?.aborted !== true;
900
+ // prepareEntry registers its installation synchronously, so the entry stays pending across this hand-over
901
+ this.queuedEntries.delete(instance);
902
+ const entered = (): boolean => this.hybrid.state().instance === instance;
903
+ if (!live() || this.hybrid.state().instance !== null) { if (live() && !entered()) this.deferredEntries.set(instance, row); return; }
904
+ let prepared = false;
905
+ try { prepared = await this.hybrid.prepareEntry(instance, row.signal); }
906
+ catch (error) { console.warn(`[grid] ${instance}: entry preparation on the road`, error); }
907
+ // a turn back into the source meanwhile (its entry made the session active) waits for the next leave
908
+ if (!prepared && live() && this.hybrid.state().instance !== null && !entered()) this.deferredEntries.set(instance, row);
909
+ }
867
910
  /** G555: the entered runtime hooks' timings (the one running and those finished), for the cell loading screen. */
868
911
  hookTimings(): ReturnType<HybridRuntimeSession['timings']> { return this.hybrid.timings(); }
912
+ /** GC6: the entered runtime, whether its hooks finished, the hook running, the last finished, and the entries preparing */
913
+ hybridState(): { readonly instance: string | null; readonly ready: boolean; readonly hook: string | null; readonly last: string | null; readonly preparing: readonly string[]; readonly deferred: readonly string[]; readonly warm: readonly string[] } {
914
+ const state = this.hybrid.state(), timings = this.hybrid.timings(), last = timings.completed.at(-1);
915
+ return { ...state, hook: timings.current === null ? null : `${timings.current.instance}:${timings.current.hook}`,
916
+ last: last === undefined ? null : `${last.instance}:${last.hook}:${last.outcome}`, preparing: this.hybrid.preparing(), deferred: [...this.deferredEntries.keys()],
917
+ warm: this.hybrid.preparing().map(id => { const w = this.warmPreparation(id); return w === null ? `${id}:-` : `${id}:${w.phase}:${w.completed ? 'done' : w.progress?.detail ?? ''}`; }) };
918
+ }
869
919
  /** GC2: the server still has this client in `instance` (an online cell is still walled, C5). */
870
920
  serverHolds(instance: string): boolean { return this.wire !== null && this.wire.site() === instance; }
871
921
 
@@ -1,4 +1,5 @@
1
1
  import type { Scope } from '@wildshard/engine/app/scope';
2
+ import { captureBrowserError, engineScreenTags } from '@wildshard/engine/telemetry/browserErrors';
2
3
  import type { MapExtraImage } from '@wildshard/engine/ui/Minimap';
3
4
  import type { ResidencyAllocator } from '../../../shared/game/grid/allocator';
4
5
 
@@ -10,9 +11,14 @@ const decode = async (spec: AtlasSpec): Promise<Decoded> => {
10
11
  const image = await createImageBitmap(bytes); return { image, width: image.width, height: image.height, close: () => { image.close(); } };
11
12
  };
12
13
 
13
- /** Load and charge one inert atlas before play. Every cell then reads a crop without product admission or extra decodes. */
14
+ /** A cell's crop of the atlas, or null for a slug the build baked no tile for (QA-FEEDBACK 2026-11-13 row 44). */
15
+ export type AtlasTile = (slug: string) => Pick<MapExtraImage, 'image' | 'crop'> | null;
16
+
17
+ /** Load and charge one inert atlas before play. Every cell then reads a crop without product admission or extra decodes.
18
+ * A slug with no tile (a cell the signed placement file added after the build, placedCells.ts) reads null, never a throw:
19
+ * the full map draws that cell another way, and one Sentry warning a page names the slug. */
14
20
  export async function loadGridMapAtlas(scope: Scope, allocator: Pick<ResidencyAllocator, 'reserve'>, spec: AtlasSpec,
15
- read: (spec: AtlasSpec) => Promise<Decoded> = decode): Promise<(slug: string) => Pick<MapExtraImage, 'image' | 'crop'>> {
21
+ read: (spec: AtlasSpec) => Promise<Decoded> = decode, capture: typeof captureBrowserError = captureBrowserError): Promise<AtlasTile> {
16
22
  if (scope.disposed || scope.disposing) throw new Error('World map owner retired');
17
23
  const lease = allocator.reserve({ id: `library:world-map:${spec.url}`, category: 'library', owner: 'platform', bytes: spec.width * spec.height * 4 + spec.compressed, distance: 0, needed: true });
18
24
  if (lease === null) throw new Error('World map residency deferred');
@@ -23,10 +29,18 @@ export async function loadGridMapAtlas(scope: Scope, allocator: Pick<ResidencyAl
23
29
  if (scope.disposed || scope.disposing) { loaded.close(); throw new Error('World map owner retired'); }
24
30
  if (loaded.width !== spec.width || loaded.height !== spec.height) { loaded.close(); throw new Error('World map dimensions differ'); }
25
31
  image = loaded; lease.shrink(spec.width * spec.height * 4);
26
- const columns = spec.width / spec.tileSize;
32
+ const columns = spec.width / spec.tileSize, missing = new Set<string>();
27
33
  return slug => {
28
34
  if (image === undefined) throw new Error('World map owner retired');
29
- const i = spec.slugs.indexOf(slug); if (i === -1) throw new Error(`Missing world map tile: ${slug}`);
35
+ const i = spec.slugs.indexOf(slug);
36
+ if (i === -1) {
37
+ if (!missing.has(slug)) {
38
+ missing.add(slug);
39
+ try { capture(new Error(`Missing world map tile: ${slug}`), { ...engineScreenTags('map-tile-missing', 'grid', 'playing', { tiles: spec.slugs.length }), shard: slug }); }
40
+ catch { /* a report never blanks the map */ }
41
+ }
42
+ return null;
43
+ }
30
44
  return { image: image.image, crop: [i % columns * spec.tileSize, Math.floor(i / columns) * spec.tileSize, spec.tileSize, spec.tileSize] };
31
45
  };
32
46
  } catch (error) { lease.release(); throw error; }
@@ -30,6 +30,8 @@ const NAME_RANGE = 101 - NAME_ACROSS;
30
30
  /** A neighbour's baked map is kept at this many px a side (0.8 px per metre, 0.64 MB): the minimap shows it ~110 m across */
31
31
  export const CELL_PX = 400;
32
32
  const STRIP = '#3b4038', ROAD = '#2a2e35', LINE = '#c9a640', VOID = '#0b1016', NAME = '#eaf6ff';
33
+ /** A cell the atlas has no tile for, until its own map loads: the build's plain-plot green (scripts/app-build/worldMapAtlas.ts). */
34
+ const PLOT = '#69704f';
33
35
 
34
36
  /** Each shard's baked map, loaded the first time a cell of it is drawn, downscaled once and shared by its copies. */
35
37
  interface MapEntry { image: HTMLCanvasElement | ImageBitmap | null; deferredAt?: number }
@@ -156,21 +158,29 @@ export function minimapOverlay(host: MinimapBlendHost, rects: readonly MapExtraR
156
158
  }
157
159
 
158
160
  /** The grid's full map (SF66): every cell's baked map at its cell, the road network, each shard's name near its cell's north
159
- * edge; the home's own ground is the map's base layer. Home-frame metres. */
160
- type AtlasTile = (slug: string) => Pick<MapExtraImage, 'image' | 'crop'>;
161
+ * edge; the home's own ground is the map's base layer. Home-frame metres. A cell the atlas has no tile for (a placed cell,
162
+ * QA-FEEDBACK 2026-11-13 row 44) draws its own baked map once that loads, and a plain-plot square until then. */
163
+ type AtlasTile = (slug: string) => Pick<MapExtraImage, 'image' | 'crop'> | null;
161
164
  export function fullMapOverlay(host: MinimapBlendHost, rects: readonly MapExtraRect[], atlas?: AtlasTile): MapExtras {
162
165
  const { assembly, home } = host, ox = home.origin.x, oz = home.origin.z, homeImage = atlas === undefined ? host.image(home.instance) : null;
163
- const images: MapExtraImage[] = [], labels: MapExtraLabel[] = [];
166
+ const images: MapExtraImage[] = [], labels: MapExtraLabel[] = [], plots: MapExtraRect[] = [];
164
167
  for (const cell of assembly.cells) {
165
168
  const x = cell.origin.x - ox, z = cell.origin.z - oz;
166
169
  const text = host.name(cell);
167
170
  labels.push({ x, z: z + CHUNK_HALF - 90, text, short: text.split(' · ').at(-1) ?? text, color: NAME, width: CHUNK_HALF * 2 - 32, height: 160 });
168
- if (atlas !== undefined) { images.push({ ...atlas(cell.slug), x, z, size: 2 * CHUNK_HALF, alpha: 1 }); continue; }
171
+ if (atlas !== undefined) {
172
+ const tile = atlas(cell.slug);
173
+ if (tile !== null) { images.push({ ...tile, x, z, size: 2 * CHUNK_HALF, alpha: 1 }); continue; }
174
+ const image = host.image(cell.instance);
175
+ if (image !== null) images.push({ image, x, z, size: 2 * CHUNK_HALF, alpha: 1 });
176
+ else plots.push({ x, z, hx: CHUNK_HALF, hz: CHUNK_HALF, color: PLOT });
177
+ continue;
178
+ }
169
179
  if (cell.instance === home.instance && homeImage === null) continue;
170
180
  const image = host.image(cell.instance);
171
181
  if (image !== null) images.push({ image, x, z, size: 2 * CHUNK_HALF, alpha: 1 });
172
182
  }
173
- return { outside: VOID, baseAlpha: atlas === undefined && homeImage === null ? 1 : 0, rects, images, labels };
183
+ return { outside: VOID, baseAlpha: atlas === undefined && homeImage === null ? 1 : 0, rects: plots.length === 0 ? rects : [...rects, ...plots], images, labels };
174
184
  }
175
185
 
176
186
  interface ExtrasSink { setExtras: (source: (() => MapExtras | null) | null) => void }
@@ -98,7 +98,11 @@ export function deviceRouteMemory(): RouteMemory {
98
98
  shards: release => wordShards(kept(release)),
99
99
  write: (release, grid, shards = null) => {
100
100
  const build = (globalThis as { __WS_BUILD_ID__?: string }).__WS_BUILD_ID__ ?? '';
101
- try { slot().write({ of: release, grid, ...(shards === null ? {} : { shards: [...shards] }), build, at: Date.now() }); } catch { /* a device that keeps nothing falls back to today's page */ }
101
+ try {
102
+ // OF20: the last placement file shares this slot (placedCells.ts `devicePlacedKeep`); a new word keeps it
103
+ const prior = slot().read(), placed = typeof prior === 'object' && prior !== null && !Array.isArray(prior) ? prior['placed'] : undefined;
104
+ slot().write({ of: release, grid, ...(shards === null ? {} : { shards: [...shards] }), build, at: Date.now(), ...(placed === undefined ? {} : { placed }) });
105
+ } catch { /* a device that keeps nothing falls back to today's page */ }
102
106
  },
103
107
  };
104
108
  }
@@ -140,6 +140,17 @@ export function enterGrid(): void {
140
140
 
141
141
 
142
142
 
143
+ /** The grid page's address: its path, and only the harness flags skipintro, mute and nolock, none of which selects a level, and `skipintro` dropped here sent a
144
+ * `?chunk=<slug>&skipintro` link on a world build back under the title (OFFLINE OF18: every Open Plot in the offline proof). */
145
+ export function gridPageUrl(href: string): URL {
146
+ const from = new URL(href).searchParams, to = new URL(new URL(href).pathname, new URL(href).origin);
147
+ const skipintro = from.get('skipintro'), mute = from.get('mute'), nolock = from.get('nolock');
148
+ if (skipintro !== null) to.searchParams.set('skipintro', skipintro);
149
+ if (mute !== null) to.searchParams.set('mute', mute);
150
+ if (nolock !== null) to.searchParams.set('nolock', nolock);
151
+ return to;
152
+ }
153
+
143
154
  /** The boot's one read of the tap intent (used or not), overridden by validated recovery before ordinary admission.
144
155
  * In grid mode the address becomes the bare title URL, preventing an unrecorded automatic restart. */
145
156
  export function bootPageMode(slug: string): PageMode {
@@ -172,7 +183,7 @@ export function bootPageMode(slug: string): PageMode {
172
183
  registerBeforeReload(pageScope, reason => gridRecovery(saves).write(assembly, home, road, reason === 'settings' ? 'reload' : reason)); // SR12: a Settings reload continues play
173
184
  }
174
185
  if (mode === 'grid' && typeof history !== 'undefined') {
175
- try { history.replaceState(history.state, '', new URL(location.pathname, location.origin)); } catch { /* a sandboxed frame: the URL stays */ }
186
+ try { history.replaceState(history.state, '', gridPageUrl(location.href)); } catch { /* a sandboxed frame: the URL stays */ }
176
187
  }
177
188
  return mode;
178
189
  }