@wildshard/engine 0.1.17 → 0.1.19

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 (343) 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 +21 -0
  5. package/lint/host-callback-syntax.mjs +2 -1
  6. package/lint/host-callbacks.mjs +3 -3
  7. package/lint/host-files.mjs +5 -4
  8. package/lint/no-base64.mjs +3 -1
  9. package/lint/ratchet.json +0 -68
  10. package/lint/ratchet.mjs +1 -4
  11. package/lint/shard-imports.mjs +6 -7
  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 +22 -23
  18. package/package.json +25 -16
  19. package/scripts/agent-sync.mjs +27 -8
  20. package/scripts/app-build/appCook.ts +8 -2
  21. package/scripts/app-build/catalogue.ts +10 -7
  22. package/scripts/app-build/gen.ts +22 -2
  23. package/scripts/app-build/isolation.d.mts +10 -0
  24. package/scripts/app-build/isolation.mjs +47 -0
  25. package/scripts/app-build/outputProducts.d.mts +3 -0
  26. package/scripts/app-build/outputProducts.mjs +35 -0
  27. package/scripts/app-build/previousDeploy.d.mts +2 -0
  28. package/scripts/app-build/previousDeploy.mjs +10 -1
  29. package/scripts/app-build/serviceWorker.ts +10 -3
  30. package/scripts/app-build/splitOutput.mjs +4 -2
  31. package/scripts/app-build/standaloneOutput.d.mts +1 -1
  32. package/scripts/app-build/standaloneOutput.mjs +5 -3
  33. package/scripts/app-build/titlePreloads.d.mts +8 -0
  34. package/scripts/app-build/titlePreloads.mjs +69 -0
  35. package/scripts/app-build/worldMapAtlas.ts +10 -6
  36. package/scripts/app-build-pipeline.mjs +34 -3
  37. package/scripts/built-product.mjs +1 -1
  38. package/scripts/cell-mem-bench.mjs +81 -23
  39. package/scripts/check-custom-sections-zero.mjs +1 -1
  40. package/scripts/check-devserver.mjs +3 -1
  41. package/scripts/check-models.mjs +2 -0
  42. package/scripts/check-paths.allow.json +0 -115
  43. package/scripts/check-paths.mjs +2 -2
  44. package/scripts/check-platform-ratchets.mjs +2 -3
  45. package/scripts/chromium-keychain-check.mjs +4 -2
  46. package/scripts/chromium-keychain.d.mts +1 -1
  47. package/scripts/chromium-keychain.mjs +3 -1
  48. package/scripts/ci-static.sh +1 -1
  49. package/scripts/committed-fast-checks.mjs +0 -2
  50. package/scripts/content-sw-proof.mjs +2 -1
  51. package/scripts/cook-worker.mjs +9 -3
  52. package/scripts/cook.mjs +20 -3
  53. package/scripts/devices.d.mts +4 -0
  54. package/scripts/devices.mjs +39 -0
  55. package/scripts/devserver-client.d.mts +4 -2
  56. package/scripts/devserver-client.mjs +25 -8
  57. package/scripts/docs-inputs-proof.mjs +6 -6
  58. package/scripts/doctor-proof.mjs +1 -1
  59. package/scripts/e2e-faults.mjs +159 -0
  60. package/scripts/e7-voice-staging-proof.mjs +1 -1
  61. package/scripts/gate-related-tests.mjs +1 -1
  62. package/scripts/git-source-view.mjs +1 -1
  63. package/scripts/goldens/capture.mjs +17 -5
  64. package/scripts/grid-crossing-nightly.mjs +59 -0
  65. package/scripts/grid-crossing-qa.mjs +44 -0
  66. package/scripts/grid-crossing-ratchet.d.mts +6 -0
  67. package/scripts/grid-crossing-ratchet.mjs +52 -0
  68. package/scripts/grid-crossing-report.mjs +122 -0
  69. package/scripts/grid-crossing-stages.mjs +47 -0
  70. package/scripts/grid-crossing-tour.mjs +277 -0
  71. package/scripts/grid-crossing-walk-proof.mjs +136 -18
  72. package/scripts/host-ruler/roots.mjs +2 -2
  73. package/scripts/host-ruler.d.mts +91 -0
  74. package/scripts/host-ruler.mjs +565 -0
  75. package/scripts/live-prepush.py +3 -5
  76. package/scripts/loading-flow/benchmax.mjs +3 -1
  77. package/scripts/look-loop/test_look_loop.py +1 -38
  78. package/scripts/memory-proof.mjs +213 -0
  79. package/scripts/mmo-bots.mjs +8 -2
  80. package/scripts/net-lag-proof.mjs +219 -0
  81. package/scripts/night-market-kit-budget.mjs +2 -2
  82. package/scripts/offline-proof-rules.d.mts +5 -3
  83. package/scripts/offline-proof-rules.mjs +34 -7
  84. package/scripts/offline-proof.mjs +88 -18
  85. package/scripts/{shard-platform-output.mjs → output-reader.mjs} +1 -1
  86. package/scripts/page-release/content.d.mts +9 -1
  87. package/scripts/page-release/content.mjs +131 -17
  88. package/scripts/page-release/flow.mjs +36 -10
  89. package/scripts/page-release/stamp-content.mjs +24 -0
  90. package/scripts/page-release.mjs +28 -6
  91. package/scripts/page-size.mjs +2 -1
  92. package/scripts/pin-packs.ts +1 -1
  93. package/scripts/pins.ts +4 -4
  94. package/scripts/precommit-checks.mjs +1 -7
  95. package/scripts/precommit-jobs.mjs +0 -1
  96. package/scripts/precommit-source.py +1 -9
  97. package/scripts/program-discovery.mjs +1 -1
  98. package/scripts/ring-cook.mjs +2 -1
  99. package/scripts/ring-step.ts +1 -1
  100. package/scripts/script-scenario-metrics.mjs +1 -1
  101. package/scripts/shard-output-content.d.mts +1 -1
  102. package/scripts/shard-output-content.mjs +2 -2
  103. package/scripts/shard-outputs.mjs +1 -1
  104. package/scripts/shard-public.mjs +1 -1
  105. package/scripts/shard-wire-meter.mjs +24 -9
  106. package/scripts/side-parity.mjs +4 -2
  107. package/scripts/standalone-smoke.mjs +8 -3
  108. package/scripts/tier-textures-proof.mjs +101 -0
  109. package/scripts/tier-textures.mjs +78 -0
  110. package/scripts/tile-bake-report.mjs +1 -1
  111. package/scripts/tile-bakes.mjs +1 -1
  112. package/scripts/title-assets.generated.json +2 -0
  113. package/scripts/tsconfig.json +1 -2
  114. package/scripts/vendor/basisu/LICENSE +201 -0
  115. package/scripts/vendor/basisu/basis_encoder.cjs +2 -0
  116. package/scripts/vendor/basisu/basis_encoder.wasm +0 -0
  117. package/scripts/vitest-push-guards.config.ts +1 -1
  118. package/scripts/vps/harden-apply.sh +4 -1
  119. package/scripts/vps/harden-prometheus.sh +176 -0
  120. package/scripts/vps/harden.sh +16 -0
  121. package/scripts/vps/rebuild.sh +18 -0
  122. package/scripts/vps/wildshard-config +84 -24
  123. package/scripts/worker-client-play.mjs +7 -2
  124. package/scripts/worker-client-proof.mjs +1 -1
  125. package/scripts/worker-client-slug.mjs +44 -0
  126. package/scripts/worktree-reap.mjs +5 -5
  127. package/src/.oxlintrc.json +3 -182
  128. package/src/client/app/entry.ts +47 -12
  129. package/src/client/engine/boot/bootCache.ts +2 -2
  130. package/src/client/engine/boot/bootTrace.ts +12 -4
  131. package/src/client/engine/boot/browserChunkRecovery.ts +4 -0
  132. package/src/client/engine/boot/clearDownloads.ts +5 -2
  133. package/src/client/engine/boot/contentRead.ts +11 -0
  134. package/src/client/engine/boot/gpuFiles.ts +4 -2
  135. package/src/client/engine/boot/lastEnd.ts +99 -12
  136. package/src/client/engine/boot/parsedPages.ts +127 -58
  137. package/src/client/engine/boot/texturePack.ts +2 -2
  138. package/src/client/engine/build.d.ts +2 -0
  139. package/src/client/engine/core/Game.ts +18 -0
  140. package/src/client/engine/core/bootstrap.ts +4 -1
  141. package/src/client/engine/debug/probe.ts +18 -1
  142. package/src/client/engine/fx/LightPool.ts +41 -1
  143. package/src/client/engine/net/netPlayer.ts +19 -2
  144. package/src/client/engine/net/otherPlayers.ts +55 -8
  145. package/src/client/engine/net/predictor.ts +33 -9
  146. package/src/client/engine/net/redial.ts +29 -6
  147. package/src/client/engine/pwa/cacheNames.ts +58 -1
  148. package/src/client/engine/pwa/sw.js +53 -14
  149. package/src/client/engine/render/dataLook.ts +152 -40
  150. package/src/client/engine/render/families/detail.ts +89 -0
  151. package/src/client/engine/render/families/pbr.ts +7 -1
  152. package/src/client/engine/render/look.ts +6 -0
  153. package/src/client/engine/render/lookLight.ts +103 -11
  154. package/src/client/engine/render/lookRender.ts +105 -0
  155. package/src/client/engine/render/precompile.ts +20 -14
  156. package/src/client/engine/saves/indexed.ts +2 -2
  157. package/src/client/engine/telemetry/browserErrors.ts +28 -4
  158. package/src/client/engine/telemetry/deviceSnapshot.ts +155 -0
  159. package/src/client/engine/telemetry/staleBuildReport.ts +22 -1
  160. package/src/client/engine/ui/debugOptions.ts +1 -1
  161. package/src/client/engine/ui/lookLightOption.ts +10 -6
  162. package/src/client/engine/ui/namePrompt.ts +7 -0
  163. package/src/client/game/boot/audio.generated.ts +114 -216
  164. package/src/client/game/boot/bytes.generated.ts +118 -238
  165. package/src/client/game/boot/placedSpawn.ts +35 -0
  166. package/src/client/game/boot/spawnDownload.ts +25 -6
  167. package/src/client/game/boot/versions.generated.ts +7 -7
  168. package/src/client/game/devScene/hook.ts +291 -0
  169. package/src/client/game/grid/area.ts +38 -0
  170. package/src/client/game/grid/cellLoading.ts +12 -2
  171. package/src/client/game/grid/live.ts +134 -12
  172. package/src/client/game/grid/liveSession.ts +47 -5
  173. package/src/client/game/grid/mapAtlas.ts +18 -4
  174. package/src/client/game/grid/menu.ts +4 -0
  175. package/src/client/game/grid/minimapBlend.ts +15 -5
  176. package/src/client/game/grid/neighbourPanels.ts +10 -1
  177. package/src/client/game/grid/oneWayIn.ts +5 -1
  178. package/src/client/game/grid/placedCards.ts +55 -0
  179. package/src/client/game/grid/placedCells.ts +233 -0
  180. package/src/client/game/grid/placedContent.ts +85 -0
  181. package/src/client/game/grid/prefetch.ts +9 -1
  182. package/src/client/game/grid/productInputs.ts +3 -1
  183. package/src/client/game/grid/productLeases.ts +4 -1
  184. package/src/client/game/grid/products.ts +8 -4
  185. package/src/client/game/grid/regionalRuntime.ts +6 -0
  186. package/src/client/game/grid/regionalWorld.ts +15 -2
  187. package/src/client/game/grid/roadCull.ts +44 -14
  188. package/src/client/game/grid/roadLook.ts +24 -15
  189. package/src/client/game/grid/roadLookPlatform.ts +4 -2
  190. package/src/client/game/grid/roadResources.ts +24 -0
  191. package/src/client/game/grid/roadSign.worker.ts +4 -3
  192. package/src/client/game/grid/roadSignPaint.ts +16 -5
  193. package/src/client/game/grid/roadSignPreparation.ts +4 -3
  194. package/src/client/game/grid/roadSignScale.ts +8 -0
  195. package/src/client/game/grid/roadTileBacking.ts +13 -3
  196. package/src/client/game/grid/roadTileCapture.worker.ts +3 -1
  197. package/src/client/game/grid/roadTileCaptureWorker.ts +2 -1
  198. package/src/client/game/grid/roadTileWrite.worker.ts +4 -2
  199. package/src/client/game/grid/roadTileWriter.ts +2 -1
  200. package/src/client/game/grid/screenReports.ts +39 -0
  201. package/src/client/game/grid/session.ts +29 -4
  202. package/src/client/game/grid/shardfileFar.ts +9 -3
  203. package/src/client/game/grid/softWallLook.ts +25 -8
  204. package/src/client/game/mainMenu.ts +6 -2
  205. package/src/client/game/plugin/context.ts +2 -1
  206. package/src/client/game/plugin/followedMovers.ts +7 -1
  207. package/src/client/game/quest/figures.ts +2 -0
  208. package/src/client/game/session/finish.ts +11 -1
  209. package/src/client/game/shard/titleList.ts +6 -2
  210. package/src/client/game/shardfile/assetCache.ts +4 -4
  211. package/src/client/game/shardfile/client.ts +4 -1
  212. package/src/client/game/shardfile/clientAssets.ts +9 -5
  213. package/src/client/game/shardfile/clientLibrary.ts +1 -1
  214. package/src/client/game/shardfile/clientWater.ts +51 -9
  215. package/src/client/game/shardfile/clientWorker.ts +21 -8
  216. package/src/client/game/shardfile/look.ts +8 -3
  217. package/src/client/game/shardfile/product.ts +34 -7
  218. package/src/client/game/shardfile/productChecks.ts +2 -2
  219. package/src/client/game/shardfile/productCost.ts +2 -2
  220. package/src/client/game/shardfile/readAsset.ts +2 -2
  221. package/src/client/game/shardfile/reflectingWater.ts +73 -0
  222. package/src/client/game/shardfile/seatGrace.ts +9 -0
  223. package/src/client/game/shardfile/skinPlayback.ts +1 -1
  224. package/src/client/game/systems/npc/figureRows.ts +9 -0
  225. package/src/client/game/titleDeck.ts +4 -3
  226. package/src/client/host/online/doctor.ts +2 -0
  227. package/src/client/host/online/linkScreens.ts +30 -4
  228. package/src/client/host/online/shell.ts +14 -0
  229. package/src/client/host/standalone/shell.ts +4 -0
  230. package/src/cook/game/astc6Encode.ts +55 -0
  231. package/src/cook/game/astc6Wasm.ts +176 -0
  232. package/src/cook/game/cookJob.ts +30 -6
  233. package/src/cook/game/cookWorker.ts +38 -11
  234. package/src/cook/game/entryTotals.ts +51 -24
  235. package/src/cook/game/shardCook.ts +67 -9
  236. package/src/cook/game/spawnParts.ts +33 -8
  237. package/src/cook/game/tierTextures.ts +349 -0
  238. package/src/e2e/smoke/game.ts +19 -14
  239. package/src/e2e/smoke/page-globals.d.ts +9 -8
  240. package/src/e2e/smoke/template2.spec.ts +8 -7
  241. package/src/server/engine/ai/bossContenders.ts +27 -3
  242. package/src/server/engine/ai/phases.ts +1 -1
  243. package/src/server/engine/entities/creatureRefill.ts +9 -2
  244. package/src/server/engine/net/ledgerBook.ts +2 -0
  245. package/src/server/engine/net/room.ts +15 -0
  246. package/src/server/engine/sim/respawn.ts +8 -0
  247. package/src/server/game/boss/arenaRoomEntry.ts +5 -1
  248. package/src/server/game/boss/arenaRoomNative.ts +2 -0
  249. package/src/server/game/boss/native.ts +2 -1
  250. package/src/server/game/boss/nativeWake.ts +9 -5
  251. package/src/server/game/boss/openArenaNative.ts +2 -2
  252. package/src/server/game/boss/openArenaRoom.ts +3 -1
  253. package/src/server/game/grid/room.ts +44 -3
  254. package/src/server/game/grid/simulation.ts +23 -0
  255. package/src/server/game/population/mixedRoster.ts +11 -3
  256. package/src/server/game/population/nativeBake.ts +8 -3
  257. package/src/server/game/population/nativeReturns.ts +6 -3
  258. package/src/server/game/population/roster.ts +5 -3
  259. package/src/server/game/quest/eliteDrops.ts +15 -4
  260. package/src/server/game/quest/nativeChapter.ts +1 -1
  261. package/src/server/game/quest/nativeComposition.ts +5 -1
  262. package/src/server/game/riding/nativeTaming.ts +10 -6
  263. package/src/server/game/riding/wildRefill.ts +3 -2
  264. package/src/server/game/shardfile/bossRow.ts +4 -2
  265. package/src/server/game/shardfile/homeKeeper.ts +4 -2
  266. package/src/server/host/bake/headlessWorker.ts +1 -1
  267. package/src/server/host/dedicated/cellHost.ts +98 -16
  268. package/src/server/host/dedicated/cellProtocol.ts +16 -1
  269. package/src/server/host/dedicated/cellWorker.ts +8 -5
  270. package/src/server/host/dedicated/dedicatedRoom.ts +16 -6
  271. package/src/server/host/dedicated/gridCells.ts +15 -6
  272. package/src/server/host/dedicated/loopLag.ts +21 -0
  273. package/src/server/host/dedicated/main.ts +13 -5
  274. package/src/server/host/dedicated/packReader.ts +3 -3
  275. package/src/server/host/dedicated/placementFile.ts +4 -19
  276. package/src/server/host/dedicated/roadRoom.ts +34 -4
  277. package/src/server/host/dedicated/serverMetrics.ts +126 -0
  278. package/src/server/host/dedicated/socketPump.ts +21 -4
  279. package/src/server/host/dedicated/socketTransport.ts +2 -1
  280. package/src/server/host/dedicated/workerTable.ts +15 -4
  281. package/src/server/host/dedicated/world.ts +95 -8
  282. package/src/server/host/headless.ts +1 -1
  283. package/src/server/host/headlessRuntime.ts +1 -1
  284. package/src/server/host/standalone/roadWorld.ts +15 -3
  285. package/src/server/host/standalone/serverHost.ts +4 -1
  286. package/src/server/host/standalone/serverProduct.ts +41 -11
  287. package/src/shared/engine/ai/BossBrain.ts +8 -0
  288. package/src/shared/engine/net/deviceWord.ts +138 -0
  289. package/src/shared/engine/net/socketFrames.ts +7 -4
  290. package/src/shared/game/boss/wake.ts +6 -0
  291. package/src/shared/game/devColliders.ts +47 -0
  292. package/src/shared/game/eliteSystem.ts +8 -0
  293. package/src/shared/game/grid/allocator.ts +3 -0
  294. package/src/shared/game/grid/catalogueSlot.ts +7 -0
  295. package/src/shared/game/grid/placementRows.ts +36 -0
  296. package/src/shared/game/plugin/bossRecord.ts +3 -2
  297. package/src/shared/game/shardfile/ktx2Targets.ts +23 -3
  298. package/src/shared/game/shardfile/outputDescriptor.ts +9 -5
  299. package/src/shared/game/shardfile/packReads.ts +28 -3
  300. package/src/shared/game/shardfile/serverPack.ts +9 -0
  301. package/src/shared/game/systems/looks/trampleField.ts +2 -0
  302. package/src/shared/host/formatJsonSchema.ts +2 -2
  303. package/src/tsconfig.json +1 -27
  304. package/lint/host-reviews.json +0 -14
  305. package/lint/listed-view-code.json +0 -13
  306. package/lint/platform-pending-users.json +0 -2520
  307. package/lint/platform-pending-users.md +0 -18
  308. package/scripts/cell-mem/metrics-preload.mjs +0 -65
  309. package/scripts/check-closed-components.d.mts +0 -7
  310. package/scripts/check-closed-components.mjs +0 -87
  311. package/scripts/g571-hosts.d.mts +0 -3
  312. package/scripts/g571-hosts.mjs +0 -54
  313. package/scripts/host-ruler/register-migrate.mjs +0 -242
  314. package/scripts/listed-view-code.d.mts +0 -7
  315. package/scripts/listed-view-code.mjs +0 -93
  316. package/scripts/look-loop/fit-lut.py +0 -142
  317. package/scripts/look-loop/palette-delta.py +0 -183
  318. package/scripts/look-loop/regions/driftwood-isle.json +0 -25
  319. package/scripts/look-loop/regions/far-reach.json +0 -225
  320. package/scripts/look-loop/regions/open-plot-night-market.json +0 -855
  321. package/scripts/look-loop/regions/pine-hollow.json +0 -22
  322. package/scripts/look-loop/regions/sunscar-dunes.json +0 -281
  323. package/scripts/platform-chargebacks.d.mts +0 -9
  324. package/scripts/platform-chargebacks.mjs +0 -135
  325. package/scripts/shard-component-spans.d.mts +0 -15
  326. package/scripts/shard-component-spans.mjs +0 -18
  327. package/scripts/shard-components.d.mts +0 -16
  328. package/scripts/shard-components.mjs +0 -363
  329. package/scripts/shard-platform-hosts.d.mts +0 -2
  330. package/scripts/shard-platform-hosts.mjs +0 -93
  331. package/scripts/shard-platform-sections.d.mts +0 -2
  332. package/scripts/shard-platform-sections.mjs +0 -9
  333. package/scripts/shard-platform.d.mts +0 -76
  334. package/scripts/shard-platform.mjs +0 -1072
  335. package/src/.oxfmtrc.json +0 -48
  336. package/src/scripts/ask-new.sh +0 -29
  337. package/src/scripts/asks.mjs +0 -142
  338. package/src/scripts/herdr-prompt.sh +0 -34
  339. package/src/scripts/herdr-question-open.sh +0 -67
  340. package/src/scripts/md-wrap.mjs +0 -229
  341. /package/scripts/{shard-platform-format.d.mts → node-format.d.mts} +0 -0
  342. /package/scripts/{shard-platform-format.mjs → node-format.mjs} +0 -0
  343. /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';
@@ -68,6 +69,9 @@ export interface LiveGridPorts {
68
69
  /** Metadata-only prefetch eligibility. Unsupported far proxies do not consume cold request slots; explicit transfers
69
70
  * still run normal admission and readiness. Absent: every cell is a candidate, as in standalone Node drivers. */
70
71
  prefetchable?: (cell: GridCell) => boolean;
72
+ /** GC5 / GC36 (J322: no hold at the line): on the road, build the world of the cell the traveller heads into, ahead of
73
+ * its line, so its entry finds it resident. Absent (standalone drivers): only actual entry builds a world (T7). */
74
+ buildAhead?: boolean;
71
75
  /** Product-only prefetch waits while this is false (T10: the page's spawn settle); required entry never waits. Absent: always. */
72
76
  backgroundReady?: () => boolean;
73
77
  bindFrame: (frame: LiveGridFrame) => void;
@@ -85,6 +89,8 @@ export interface LiveGridPorts {
85
89
  /** Crossing telemetry is a production port: the harness verifies real fixed-boundary commits, never a page/debug probe. */
86
90
  export interface LiveGridState {
87
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 };
88
94
  /** Last complete world remains fully charged and pressure-evictable on the road. */
89
95
  retainedCell?: { readonly instance: string; readonly remainingMs: number; readonly playingBytes: number; readonly capBytes: number } | null;
90
96
  transitions: readonly { from: string | null; to: string | null }[];
@@ -112,6 +118,10 @@ interface Resident { region: LiveGridRegion; lease: ResidencyLease; reservations
112
118
  // Contact corrections at a closed readiness wall are not a U-turn. Accumulate real horizontal travel
113
119
  // before selecting another approach, so sub-centimetre capsule recoil cannot evict the world just prepared.
114
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;
115
125
  const entryAxes = [['x', 'z'], ['z', 'x']] as const;
116
126
  // Distance can decrease while passing parallel to a cell. Only a ray into its first boundary's midpoint mouth
117
127
  // predicts entry; product downloads remain radial, but an unrelated native world must not block the real turn-in.
@@ -174,7 +184,18 @@ export class LiveGridHost {
174
184
  private frameGeneration = 0;
175
185
  private readonly transitions: { from: string | null; to: string | null }[] = [];
176
186
  private crossings = 0;
187
+ private warms = 0;
188
+ /** QA row 43: when a traveller held at a cell's wall may next retry its failed build */
189
+ private readonly heldRetryAt = new Map<string, number>();
190
+ /** the other mouth the traveller inside the source turned to, and since when (HEADING_HOLD_MS) */
191
+ private turnedSince: { instance: string; at: number } | null = null;
192
+ /** GC5: why the last pre-warm the heading asked for did not start (its product still reading, an exclusive runtime, or the budget) */
193
+ private warmRefusal: string | null = null;
177
194
  private previousFeet: GridPoint | undefined;
195
+ /** fixed steps since `previousFeet` moved, for the traveller's speed (GC5) */
196
+ private stepsSincePrevious = 0;
197
+ /** GC5: each cell's last measured world build, in seconds (product to colliders and sim ready) */
198
+ private readonly builtSeconds = new Map<string, number>();
178
199
  private readonly candidateDistances = new Map<GridCell,number>();
179
200
  private readonly approachWork:{candidates:GridCell[];boulevard:GridCell[]}[]=[];
180
201
  /** This host already owns the assembly and its frozen cells for its whole lifetime. */
@@ -240,18 +261,21 @@ export class LiveGridHost {
240
261
  }
241
262
  /** Submit whole-shard requests in stable order. Failed attempts remain closed until an explicit retry. */
242
263
  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); }
243
- private async requireProduct(instance: string, pending: Promise<LiveGridAdmission>): Promise<LiveGridAdmission> {
264
+ private async requireProduct(instance: string, pending: Promise<LiveGridAdmission>, trigger: 'entry' | 'explicit' | 'radial' | 'boulevard' = 'entry', speculative = false): Promise<LiveGridAdmission> {
244
265
  try { return await pending; }
245
266
  catch (error) {
246
- if (!(error instanceof ApproachInputsDeferredError)) throw error;
247
- return this.prefetchProduct(instance, true);
267
+ // the optional read's budget deferral says nothing of a required one: read it again as required
268
+ if (!(error instanceof ApproachInputsDeferredError) && !(error instanceof Error && error.message.includes(PRODUCT_DEFERRED))) throw error;
269
+ return this.prefetchProduct(instance, true, trigger, speculative);
248
270
  }
249
271
  }
250
- private prefetchProduct(instance: string, required = false, trigger: 'entry' | 'explicit' | 'radial' | 'boulevard' = 'entry'): Promise<LiveGridAdmission> {
272
+ /** `speculative`: a demand read nobody waits on yet (GC5's near neighbour and pre-warm). Its budget refusal is deferred
273
+ * 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. */
274
+ private prefetchProduct(instance: string, required = false, trigger: 'entry' | 'explicit' | 'radial' | 'boulevard' = 'entry', speculative = false): Promise<LiveGridAdmission> {
251
275
  this.assertAlive(); const cell = this.assembly.cell(instance);
252
276
  const product = this.products.get(instance); if (product !== undefined) return Promise.resolve(product);
253
277
  const pending = this.productRequests.get(instance);
254
- if (pending !== undefined) return !required || pending.required ? pending.work : this.requireProduct(instance, pending.work);
278
+ if (pending !== undefined) return !required || pending.required ? pending.work : this.requireProduct(instance, pending.work, trigger, speculative);
255
279
  const issue = this.issues.get(instance); if (issue !== undefined) return Promise.reject(new Error(issue));
256
280
  const timing = clientPreparationBatch(cell.slug, `grid.product:${instance}`, ['admission', 'runtime']);
257
281
  const request = (async (): Promise<LiveGridAdmission> => {
@@ -269,7 +293,8 @@ export class LiveGridHost {
269
293
  } catch (error) {
270
294
  this.tileMetadata.delete(instance);
271
295
  if (this.tileApproach?.instance === instance) { this.tileApproach.controller.abort(); this.tileApproach = null; }
272
- if (!required && error instanceof ApproachInputsDeferredError) this.deferredProducts.set(instance, this.ports.allocator.revision);
296
+ const refused = error instanceof ApproachInputsDeferredError || (error instanceof Error && error.message.includes(PRODUCT_DEFERRED));
297
+ if ((!required || speculative) && refused) this.deferredProducts.set(instance, this.ports.allocator.revision);
273
298
  else { this.issues.set(instance, error instanceof Error ? error.message : String(error)); this.refusals.set(instance, error); }
274
299
  try { admission?.cancel?.(); }
275
300
  catch (cleanup) { throw new AggregateError([error, cleanup], 'Live product admission and cancellation failed', { cause: cleanup }); }
@@ -278,6 +303,11 @@ export class LiveGridHost {
278
303
  })();
279
304
  this.productRequests.set(instance, { work: request, required, trigger }); return request;
280
305
  }
306
+ /** GC5 / GC36: the cell whose world the road is building or built ahead of its line (`buildAhead`), kept until the
307
+ * traveller enters a cell or heads into another's mouth. */
308
+ private ahead: string | null = null;
309
+ /** GC9: the optional read last raised to demand, so a pending radial read is raised once, not every tick */
310
+ private raised: Promise<LiveGridAdmission> | null = null;
281
311
  private tileApproach: { instance: string; tile: CellTile; controller: AbortController } | null = null;
282
312
  private transportApproach: { instance: string; controller: AbortController; work: Promise<void> } | null = null;
283
313
  private retiredTransport: Promise<void> = Promise.resolve();
@@ -346,6 +376,7 @@ export class LiveGridHost {
346
376
  await (timing === undefined ? previous : timing.run('queue', () => previous));
347
377
  await this.retiredTransport;
348
378
  this.assertAlive();
379
+ const buildStart = diagnosticNow();
349
380
  const admitted = timing === undefined ? await this.prefetchProduct(instance, true) : await timing.run('metadata', () => this.prefetchProduct(instance, true));
350
381
  admission = admitted;
351
382
  this.assertAlive();
@@ -380,6 +411,7 @@ export class LiveGridHost {
380
411
  this.assertAlive();
381
412
  this.residents.set(instance, { region, lease, reservations: 0, evicting: false, retainable: admitted.isolatedPreparation === true });
382
413
  this.readiness.complete(ticket, 'colliders'); this.readiness.complete(ticket, 'sim');
414
+ this.builtSeconds.set(instance, (diagnosticNow() - buildStart) / 1000);
383
415
  lease.update({ needed: false, distance: this.distance(cell) });
384
416
  } catch (error) {
385
417
  try { region?.dispose(); }
@@ -451,6 +483,13 @@ export class LiveGridHost {
451
483
  resident.lease.update({ needed: false, distance: this.distance(this.assembly.cell(instance)) });
452
484
  return this.lastCell === last;
453
485
  }
486
+ /** GC5: how far from a neighbour's square its world starts building at `speed` (m/s): its measured build time, or the
487
+ * slowest measured so far or the default, at least WARM_MIN_SECONDS, with a margin; capped below the keep distance. */
488
+ private warmLead(instance: string, speed: number): number {
489
+ const measured = this.builtSeconds.get(instance) ?? Math.max(WARM_DEFAULT_SECONDS, ...this.builtSeconds.values());
490
+ const seconds = Math.min(WARM_MAX_SECONDS, Math.max(WARM_MIN_SECONDS, measured));
491
+ return Math.min(WARM_LEAD_CAP_METRES, WARM_LEAD_METRES + speed * seconds * WARM_MARGIN);
492
+ }
454
493
  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)); }
455
494
  /** Only the active/reserved world and one bounded departed world can remain.
456
495
  * A different actual entry retires the departure before any new allocation. */
@@ -460,7 +499,7 @@ export class LiveGridHost {
460
499
  || this.active !== null || destination !== undefined && destination !== last.instance)) this.forgetLastCell();
461
500
  let released = true;
462
501
  for (const [instance, resident] of this.residents) {
463
- const needed = instance === this.active || instance === destination || this.requests.has(instance) || resident.reservations > 0;
502
+ const needed = instance === this.active || instance === destination || instance === this.ahead || this.requests.has(instance) || resident.reservations > 0;
464
503
  resident.lease.update({ distance: this.distance(this.assembly.cell(instance)), needed: needed || resident.disposalFailed === true });
465
504
  if (needed || this.lastCell?.instance === instance) continue;
466
505
  if (resident.disposalFailed === true || resident.evicting || this.coldUnloadRefused.has(instance)) { released = false; continue; }
@@ -494,7 +533,8 @@ export class LiveGridHost {
494
533
  // More than a second of modeled travel between fixed samples is a pose/portal jump.
495
534
  // Establish a new origin instead of spending a constructor on its accidental direction.
496
535
  const travelled = previous !== undefined && travelledDistance >= APPROACH_TRAVEL_METRES && travelledDistance <= this.ports.readiness.link.speed;
497
- if (previous === undefined || travelledDistance >= APPROACH_TRAVEL_METRES) this.previousFeet = feet;
536
+ const steps = ++this.stepsSincePrevious, speed = travelled ? travelledDistance * FIXED_HZ / steps : 0;
537
+ if (previous === undefined || travelledDistance >= APPROACH_TRAVEL_METRES) { this.previousFeet = feet; this.stepsSincePrevious = 0; }
498
538
  // Prefetch the closest cells' products (never their worlds: G663). Unsupported far proxies do not consume the count
499
539
  // before enterable cells inside the cold readiness bound.
500
540
  const candidates=work.candidates,cells=this.assembly.cells;
@@ -506,12 +546,31 @@ export class LiveGridHost {
506
546
  candidates.sort((a,b) => (this.candidateDistances.get(a) ?? Infinity) - (this.candidateDistances.get(b) ?? Infinity) || a.instance.localeCompare(b.instance));
507
547
  // Immutable products are selected by distance, without a whole-world count cap.
508
548
  const nearby = candidates;
509
- // The frame-transfer reservation protects an actual entry; inactive whole worlds retire in steps.
549
+ // The frame-transfer reservation protects an actual entry; inactive whole worlds retire in steps. A world built ahead
550
+ // (`buildAhead`) stays while the traveller is on the road and has not turned into another mouth (below); one pre-warmed
551
+ // from inside the source (GC5) stays while the traveller is within WARM_KEEP_METRES of it.
552
+ if (this.active !== null && this.ahead !== null && (this.ahead === this.active
553
+ || this.distance(this.assembly.cell(this.ahead), feet) > WARM_KEEP_METRES)) this.ahead = null;
510
554
  this.retireInactiveRegions();
511
555
  for (const cell of nearby) {
512
556
  const estimate = readinessModel(this.ports.readiness.bundle(cell), this.ports.readiness.link), distance = this.distance(cell, feet);
513
557
  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);
514
558
  }
559
+ // GC5: the neighbour across the source's nearest edge, within DEMAND_METRES, has its product read as demand, standing or
560
+ // 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
561
+ // budget declines while every neighbour competes for it (Pine's read alone is 6 to 8 s). One at a time, the nearest.
562
+ if (this.active !== null && this.ports.buildAhead === true) {
563
+ const near = candidates[0];
564
+ // GC9: a radial read already pending for it is raised to demand once (the budget declined Pine's radial read again and
565
+ // again while it stood pending, so the demand read never started inside Driftwood and Pine's world was built on the road)
566
+ const pending = near === undefined ? undefined : this.productRequests.get(near.instance);
567
+ if (near !== undefined && this.distance(near, feet) <= DEMAND_METRES && !this.products.has(near.instance) && !this.residents.has(near.instance)
568
+ && (pending === undefined || !pending.required && this.raised !== pending.work) && !this.issues.has(near.instance) && !this.constructing.has(near.instance)
569
+ && this.deferredProducts.get(near.instance) !== this.ports.allocator.revision && this.ports.backgroundReady?.() !== false) {
570
+ if (pending !== undefined) this.raised = pending.work;
571
+ void background(near.instance, this.prefetchProduct(near.instance, true, 'explicit', true), () => !this.disposed);
572
+ }
573
+ }
515
574
  // Approach preparation owns render tiles only, never a regional world or gameplay hooks.
516
575
  const moving = !travelled ? undefined : candidates.find(cell => headsToEntry(cell, feet, previous)
517
576
  && this.distance(cell, feet) < this.distance(cell, previous) - 0.000001);
@@ -532,9 +591,23 @@ export class LiveGridHost {
532
591
  tileApproach.controller.abort(); this.tileApproach = null;
533
592
  }
534
593
  }
594
+ // The world built ahead goes once the traveller is a pitch from it, or heads from the road into another mouth (a stop
595
+ // keeps it). Checked while a build runs too, which the gate below skips.
596
+ const wallReach = 6 + this.ports.player.motor.opts.radius + 0.5 + this.ports.readiness.link.speed / 60;
597
+ const departed = this.transitions.at(-1)?.from;
598
+ // 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
599
+ // jump or a recoil off the wall reads as a heading back into the cell just left, which let the world built ahead go.
600
+ const held = this.ports.buildAhead === true && this.active === null && this.assembly.at(feet.x, feet.z) === undefined
601
+ ? nearby.find(cell => cell.instance !== departed && this.distance(cell, feet) <= wallReach) : undefined;
602
+ // Inside the source a new heading must hold HEADING_HOLD_MS before it retires the world built ahead: steering that
603
+ // wobbles near a corner would otherwise build and dispose a whole world per flip.
604
+ const turned = moving !== undefined && moving.instance !== this.ahead;
605
+ if (!turned || this.active === null) this.turnedSince = null;
606
+ else if (this.turnedSince?.instance !== moving.instance) this.turnedSince = { instance: moving.instance, at: diagnosticNow() };
607
+ const settledTurn = turned && (this.active === null || diagnosticNow() - (this.turnedSince?.at ?? 0) >= HEADING_HOLD_MS);
608
+ if (this.ahead !== null && (this.distance(this.assembly.cell(this.ahead), feet) >= this.assembly.pitch
609
+ || held === undefined && settledTurn && (this.assembly.at(feet.x, feet.z) === undefined || this.active !== null))) this.ahead = null;
535
610
  if (this.requests.size === 0) {
536
- const wallReach = 6 + this.ports.player.motor.opts.radius + 0.5 + this.ports.readiness.link.speed / 60;
537
- const departed = this.transitions.at(-1)?.from;
538
611
  const boulevard=work.boulevard;
539
612
  if(travelled&&moving===undefined)for(let i=0,length=candidates.length;i<length;i++){
540
613
  const cell=candidates[i];if(cell!==undefined&&cell.instance!==departed
@@ -561,6 +634,52 @@ export class LiveGridHost {
561
634
  const named = moving ?? predicted, outsideSource = sourceDistance >= CHUNK_HALF;
562
635
  if (named !== undefined && outsideSource && !this.residents.has(named.instance) && !this.issues.has(named.instance)
563
636
  && this.distance(named, feet) < this.assembly.pitch) this.prepareApproachTransport(named);
637
+ // GC5 / GC36 (J322: no walls, no hold at the line): on the road, a traveller heading into a cell's mouth builds that
638
+ // cell's world now, not at the line. Built on demand there, the walk stood 2 to 5 s at the neighbour's closed edge
639
+ // while its world was made (2 to 4 s in Chromium). The entry's own preparation then finds it resident. The departed
640
+ // cell retires first, as the entry would retire it; a U-turn builds it again, as any entry does.
641
+ // Only from the road itself: past a cell's line (inside its square, before the 6 m entry) the heading names the cell
642
+ // beyond it, which would retire the world just built for the one underfoot.
643
+ // QA 11-13 row 43 (Jake on staging: 11 s at Template's wall, "saved state and its systems", no progress): a traveller
644
+ // 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
645
+ // was never asked for again, and online the server crosses only past the line the wall holds them short of. Held at
646
+ // a closed wall on the road, that cell's world is always building.
647
+ // A failed build is tried again while they stand there, at most every HELD_RETRY_MS (never on a cleanup failure).
648
+ if (held !== undefined && this.issues.has(held.instance) && !this.residents.has(held.instance) && !this.requests.has(held.instance) && !this.productRequests.has(held.instance)
649
+ && diagnosticNow() >= (this.heldRetryAt.get(held.instance) ?? 0)) { this.heldRetryAt.set(held.instance, diagnosticNow() + HELD_RETRY_MS); this.retry(held.instance); }
650
+ if (held !== undefined && !this.residents.has(held.instance) && !this.issues.has(held.instance)) {
651
+ this.ahead = held.instance;
652
+ if (this.retireInactiveRegions(held.instance)) void background(held.instance, this.ensure(held.instance), () => !this.disposed);
653
+ }
654
+ else if (held === undefined && this.ports.buildAhead === true && moving !== undefined && this.active === null && this.assembly.at(feet.x, feet.z) === undefined
655
+ && !this.residents.has(moving.instance) && !this.issues.has(moving.instance)
656
+ && this.distance(moving, feet) < this.assembly.pitch && this.retireInactiveRegions(moving.instance)) {
657
+ this.ahead = moving.instance;
658
+ void background(moving.instance, this.ensure(moving.instance), () => !this.disposed);
659
+ }
660
+ // 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):
661
+ // inside the source, heading into a neighbour's mouth, its world is built once the traveller is its measured build
662
+ // time away at this speed. Only beside an isolated source and for an isolated product (opaque runtimes stay exclusive,
663
+ // built only on the road), and only when both fit beside each other (G723); else the road builds it as before.
664
+ if (this.ports.buildAhead === true && moving !== undefined && this.active !== null && this.ahead === null
665
+ && this.residents.get(this.active)?.retainable === true && !this.residents.has(moving.instance) && !this.issues.has(moving.instance)
666
+ && this.distance(moving, feet) <= this.warmLead(moving.instance, speed)) {
667
+ const product = this.products.get(moving.instance);
668
+ // The heading names it: its product is read as demand (it may evict speculative neighbours' products), not as a radial
669
+ // guess, which the shared budget declines while the page's other neighbours compete for the same headroom.
670
+ if (product === undefined) {
671
+ this.warmRefusal = 'product';
672
+ if (!this.productRequests.has(moving.instance) && this.deferredProducts.get(moving.instance) !== this.ports.allocator.revision)
673
+ void background(moving.instance, this.prefetchProduct(moving.instance, true, 'explicit', true), () => !this.disposed);
674
+ }
675
+ else if (product.isolatedPreparation !== true) this.warmRefusal = 'exclusive';
676
+ else if (!this.ports.allocator.canPrepareAlongside(this.active, moving.instance, product.bytes,
677
+ { playing: this.ports.allocator.envelope(), loading: CONTENT_CAPS.loading })) this.warmRefusal = 'budget';
678
+ else {
679
+ this.ahead = moving.instance; this.warms++; this.warmRefusal = null;
680
+ void background(moving.instance, this.ensure(moving.instance), () => !this.disposed);
681
+ }
682
+ }
564
683
  if (approach !== undefined && this.ports.prepareNeighbour !== undefined && this.tileMetadata.has(approach.instance)
565
684
  && !this.residents.has(approach.instance) && !this.issues.has(approach.instance)
566
685
  && (this.active === null || moving === approach)
@@ -686,6 +805,9 @@ export class LiveGridHost {
686
805
  /** Prepare disabled replacement controllers while the existing page stays authoritative; no entered runtime hooks run here. */
687
806
  async prepare(from: string | null, to: string | null): Promise<PreparedGridCrossing> {
688
807
  if (this.disposed || this.active !== from || from === to) throw new Error('Stale live frame preparation');
808
+ // An entry anywhere but the world built ahead lets that world go, so it retires before this one allocates. Stepping out
809
+ // onto the road keeps one pre-warmed from inside the source (GC5).
810
+ if (to !== null && this.ahead !== to) this.ahead = null;
689
811
  if (from !== null && to !== null) throw new Error('Owned runtime crossing must commit onto the neutral road first');
690
812
  // Protect a ready return before yielding: expiry/pressure cannot free it
691
813
  // between its selection and the final prepared-frame reservation.
@@ -741,7 +863,7 @@ export class LiveGridHost {
741
863
  playingBytes: this.ports.allocator.ownerCost(last.instance).playing, capBytes: Math.min(CONTENT_CAPS.playing, policy.playingBytes) };
742
864
  }
743
865
  /** Read-only crossing evidence and failures for the real grid physics harness. */
744
- 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: [
866
+ state(): LiveGridState { return { current: this.active, worldFeet: this.worldFeet(), crossings: this.crossings, ahead: { instance: this.ahead, warms: this.warms, refused: this.warmRefusal }, transitions: this.transitions.map((row) => ({ ...row })), residents: [...this.residents.keys()].sort(), pending: [...new Set([...this.requests.keys(), ...this.productRequests.keys()])].sort(), pendingWork: [
745
867
  ...[...this.requests.keys()].sort().map(instance => ({ instance, kind: 'world' as const, trigger: 'entry' as const })),
746
868
  ...[...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 })),
747
869
  ], 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() } }; }
@@ -83,7 +83,7 @@ import { shardProductFromAdmission } from '../shardfile/runtimeProduct';
83
83
  import { createRegionalRuntimeFactory, regionalRuntimeAccountedBytes, type PreparedRegionalRuntime, type RegionalRuntimePage, type RegionalRuntimeTextures } from './regionalRuntime';
84
84
  import { bindHomeBuildCache } from '../shardfile/homeBuildCache';
85
85
  import type { ClientTileRegistration } from '../shardfile/tileContent';
86
- import { createRegionalWorldFoundation, hangCellDataSky, resolveRegionalRuntimeTextures } from './regionalWorld';
86
+ import { createRegionalWorldFoundation, hangCellDataSky, registerRegionalTextureTable, resolveRegionalRuntimeTextures } from './regionalWorld';
87
87
  import { regionalDataCellBytes } from './runtimeCost';
88
88
  import { resolveLevelBounds } from '../../../shared/game/shard/runtime';
89
89
  import { declaredPlayArea, type PlayArea } from '@wildshard/engine/game/shardfile/playArea';
@@ -170,6 +170,8 @@ export interface LiveGridWire {
170
170
  readonly rebound: (physics: Physics) => void;
171
171
  /** The server's creatures in the world the page stands in, for a cell whose creatures no manager holds. */
172
172
  readonly rows: NeighbourRegion;
173
+ /** Every quest flag the server says this player holds in the world the page stands in (T2E-1b, the probe's area). */
174
+ readonly flags?: () => readonly string[];
173
175
  }
174
176
  /** The readout: the live host's crossing telemetry, the crossing coordinator and the safe-zone state. */
175
177
  export interface LiveGridSessionState {
@@ -239,6 +241,10 @@ export class LiveGridSession {
239
241
  private readonly plotBanks = new Map<string, ReturnType<PlotAudioPorts['bank']>>();
240
242
  private readonly runtimeScope: Scope;
241
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 }>();
242
248
  private readonly leaveTiming: { instance: string; leaveMs: number }[] = [];
243
249
  private readonly runtimeResidents = new Map<string, HybridResident>();
244
250
  private readonly hybrid: HybridRuntimeSession;
@@ -266,7 +272,7 @@ export class LiveGridSession {
266
272
  // Register the resident parent before the live host disposer: the traveller returns before native children free.
267
273
  this.runtimeScope = scope.child('grid.runtime.residents');
268
274
  this.hybrid = new HybridRuntimeSession(this.runtimeResidents, scope, { pause: yieldGridConstruction });
269
- scope.onDispose(gridCells.onLeave(() => { this.hybrid.leave(); }));
275
+ scope.onDispose(gridCells.onLeave(() => { this.hybrid.leave(); this.prepareDeferredEntries(); }));
270
276
  scope.onDispose(gridCells.onLeave(() => { this.leavePlotAudio(); }));
271
277
  scope.onDispose(gridCells.onEnter(cell => {
272
278
  if (!this.runtimeResidents.has(cell.instance)) { this.enterPlotAudio(cell.instance); ports.lightingSettled?.(); return; }
@@ -303,6 +309,7 @@ export class LiveGridSession {
303
309
  return { physics: ports.physics, walls: ports.walls, dispose: () => { highwayScope.dispose(); } };
304
310
  } },
305
311
  admit: (cell, required) => this.admit(cell, required),
312
+ buildAhead: true, // GC5 / GC36: the road builds the world ahead of its line
306
313
  prepareTransport: (cell, signal) => prepareApproachProductInputs(cell.slug, { allocator: ports.allocator, scope }, signal, assembly.local(traveller.position, cell)),
307
314
  ...(ports.prepareNeighbourTiles === undefined ? {} : { prepareNeighbour: ports.prepareNeighbourTiles }),
308
315
  prioritize: (cell) => prioritizeGridProduct(cell.slug, { allocator: ports.allocator, scope }),
@@ -730,7 +737,8 @@ export class LiveGridSession {
730
737
  const region = build();
731
738
  try {
732
739
  const feet = this.live.worldFeet();
733
- await this.ports.prepareDataTiles?.(cell, region.shell.scope, { x: feet.x - cell.origin.x, z: feet.z - cell.origin.z });
740
+ const inside = (offset: number): number => Math.max(-CHUNK_HALF, Math.min(CHUNK_HALF, offset));
741
+ await this.ports.prepareDataTiles?.(cell, region.shell.scope, { x: inside(feet.x - cell.origin.x), z: inside(feet.z - cell.origin.z) });
734
742
  return region;
735
743
  } catch (error) {
736
744
  try { region.dispose(); }
@@ -749,6 +757,9 @@ export class LiveGridSession {
749
757
  if (manifest === undefined || !dataPage && declaration === null) throw new GridCellWaitingError('Missing declared regional page owner');
750
758
  const page = this.page.runtimePage?.();
751
759
  if (page === undefined || page === null) throw new GridCellWaitingError('Regional page services are not ready');
760
+ // PZ22 (WILDSHARD-GAME-8G): Auto picks KTX2 only for a shard whose table is registered (DL17), so the table goes in
761
+ // before the one texture choice is made; resolved first, Driftwood read "no KTX2 set" and drew images on an iPhone.
762
+ if (choice.textures === undefined) await registerRegionalTextureTable(manifest);
752
763
  const textures = choice.textures ??= resolveRegionalRuntimeTextures(manifest, this.ports.allocator.cost().input), bytes = regionalRuntimeAccountedBytes(retained.admitted, manifest, textures.mode);
753
764
  const prepareEntry = async (): Promise<void> => {
754
765
  if (declaration === null) return;
@@ -783,7 +794,9 @@ export class LiveGridSession {
783
794
  try {
784
795
  if (cell.instance === this.ports.home.instance) bindHomeBuildCache(retained.admitted.source);
785
796
  const feet = this.live.worldFeet();
786
- const entryPoint = { x: feet.x - cell.origin.x, z: feet.z - cell.origin.z };
797
+ // A world built from the road (GC36) takes its entry at the cell's edge, the nearest point the feet will arrive at
798
+ const inside = (offset: number): number => Math.max(-CHUNK_HALF, Math.min(CHUNK_HALF, offset));
799
+ const entryPoint = { x: inside(feet.x - cell.origin.x), z: inside(feet.z - cell.origin.z) };
787
800
  prepared = await factory({ cell, admitted: retained.admitted, manifest, page, textures, allocator: this.ports.allocator, claim, scope: this.runtimeScope, entryPoint });
788
801
  }
789
802
  catch (error) { this.transferWalls.delete(cell.instance); throw error; }
@@ -791,7 +804,8 @@ export class LiveGridSession {
791
804
  this.respawnCells.set(cell.instance, { instance: cell.instance, origin: cell.origin, entryways: retained.admitted.source.entryways });
792
805
  try {
793
806
  await this.hybrid.prepare(cell.instance);
794
- 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 });
795
809
  prepared.park?.(); // Only actual entry demand reaches here; keep its frame hidden until commit.
796
810
  }
797
811
  catch (error) {
@@ -806,6 +820,7 @@ export class LiveGridSession {
806
820
  const forget = (): void => {
807
821
  if (forgotten) return;
808
822
  forgotten = true;
823
+ if (this.deferredEntries.get(cell.instance)?.prepared === prepared) this.deferredEntries.delete(cell.instance);
809
824
  if (this.runtimeRegions.get(cell.instance) === prepared) {
810
825
  this.startedRuntimes.delete(cell.instance);
811
826
  this.runtimeRegions.delete(cell.instance); this.runtimeResidents.delete(cell.instance); this.transferWalls.delete(cell.instance);
@@ -855,6 +870,31 @@ export class LiveGridSession {
855
870
  const current = this.live.current();
856
871
  return current !== null && this.runtimeRegions.has(current) ? current : null;
857
872
  }
873
+ /** GC9: once the source is left (the hybrid session is neutral), each world pre-warmed inside it prepares its entry, so the
874
+ * crossing finds it ready; an entry that arrives first waits for that preparation (`HybridRuntimeSession.enter`). */
875
+ private prepareDeferredEntries(): void {
876
+ // one at a time, nearest first: an entry preparation binds the page's one construction environment
877
+ const feet = this.live.worldFeet(), gap = (instance: string): number => {
878
+ const origin = this.ports.assembly.cell(instance).origin; return Math.hypot(origin.x - feet.x, origin.z - feet.z);
879
+ };
880
+ const rows = [...this.deferredEntries].sort(([a], [b]) => gap(a) - gap(b));
881
+ this.deferredEntries.clear();
882
+ this.deferredPreparation = this.prepareInTurn(this.deferredPreparation, rows);
883
+ }
884
+ private async prepareInTurn(previous: Promise<void>, rows: readonly (readonly [string, { readonly prepared: PreparedRegionalRuntime; readonly signal: AbortSignal | undefined }])[]): Promise<void> {
885
+ await previous;
886
+ for (const [instance, row] of rows) await this.prepareEntryOnRoad(instance, row);
887
+ }
888
+ private deferredPreparation: Promise<void> = Promise.resolve();
889
+ private async prepareEntryOnRoad(instance: string, row: { readonly prepared: PreparedRegionalRuntime; readonly signal: AbortSignal | undefined }): Promise<void> {
890
+ const live = (): boolean => this.runtimeRegions.get(instance) === row.prepared && row.signal?.aborted !== true;
891
+ if (!live() || this.hybrid.state().instance !== null) { if (live()) this.deferredEntries.set(instance, row); return; }
892
+ let prepared = false;
893
+ try { prepared = await this.hybrid.prepareEntry(instance, row.signal); }
894
+ catch (error) { console.warn(`[grid] ${instance}: entry preparation on the road`, error); }
895
+ // a turn back into the source meanwhile (its entry made the session active) waits for the next leave
896
+ if (!prepared && live() && this.hybrid.state().instance !== null) this.deferredEntries.set(instance, row);
897
+ }
858
898
  /** G555: the entered runtime hooks' timings (the one running and those finished), for the cell loading screen. */
859
899
  hookTimings(): ReturnType<HybridRuntimeSession['timings']> { return this.hybrid.timings(); }
860
900
  /** GC2: the server still has this client in `instance` (an online cell is still walled, C5). */
@@ -986,6 +1026,8 @@ export class LiveGridSession {
986
1026
  const region = this.regions.get(instance);
987
1027
  return region === undefined ? undefined : { colliders: region.colliders, field: name => this.wire?.site() === instance ? wirePage.row(name) : undefined };
988
1028
  }
1029
+ /** A cell's quest flags, as the server holds them: only where the wire stands. */
1030
+ areaFlags(instance: string): readonly string[] { return this.wire?.site() === instance ? this.wire.flags?.() ?? [] : []; }
989
1031
  /** What draws a cell's life: the server's rows, which exist only where the page stands. */
990
1032
  lifeRegion(instance: string): NeighbourRegion | undefined { return this.wire?.site() === instance ? this.wire.rows : undefined; }
991
1033
 
@@ -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; }
@@ -2,6 +2,7 @@ import { isDev } from '@wildshard/engine/core/devMode';
2
2
  import type { GridMode } from '../../../shared/game/grid/catalogue';
3
3
 
4
4
  declare const __DEVSERVER__: boolean;
5
+ declare const __PREPARATION_ONLY__: boolean;
5
6
  /**
6
7
  * The main menu's two entries (SHARD-PLATFORM §3.3, G58, G61, SF21a): **Select a shard** (today's one-shard flow) and
7
8
  * **Infinite Wildshard** (the 5 × 5 grid). What each mode lets the player enter is the §3.3 table:
@@ -19,6 +20,9 @@ export const GRID_GATES_PASSED = false;
19
20
 
20
21
  /** The author's build-time switch (`vite build --mode devserver`, SF8c); a unit test's Node has no define, so false */
21
22
  export const DEVSERVER: boolean = typeof __DEVSERVER__ === 'boolean' && __DEVSERVER__;
23
+ /** SHARD-AUTHORING SA43: a production-renderer build made with `WILDSHARD_PREPARATION_ONLY=1` (never released:
24
+ * check-devserver refuses it), the client `wildshard prepare` serves with the author's draft inline */
25
+ export const PREPARATION_ONLY: boolean = typeof __PREPARATION_ONLY__ === 'boolean' && __PREPARATION_ONLY__;
22
26
 
23
27
  /** what the title is allowed to show and enter right now */
24
28
  export interface MenuMode { readonly developer: boolean; readonly devserver: boolean }
@@ -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 }
@@ -12,9 +12,10 @@ import type { Group, Object3D } from 'three';
12
12
  import type { ClientTileViews } from '../shardfile/clientViews';
13
13
  import type { Shardfile } from '@wildshard/format/shardSchema';
14
14
  import type { GridCell } from '../../../shared/game/grid/assembly';
15
+ import type { ProbeAreaTarget } from '@wildshard/engine/debug/probe';
15
16
 
16
17
  /** What the panels read of a cell the live host has admitted: the solids of its world, and a field's row where this page has one. */
17
- export interface PanelRegion { readonly colliders: ReadonlyMap<string, { readonly setActive: (active: boolean) => void }>; readonly field: (name: string) => number | undefined }
18
+ export interface PanelRegion { readonly colliders: ReadonlyMap<string, { readonly active: () => boolean; readonly setActive: (active: boolean) => void }>; readonly field: (name: string) => number | undefined }
18
19
  /** The page scope the panels live and die with (the views' own scope type). */
19
20
  type PageScope = Parameters<ClientTileViews['panels']>[3];
20
21
  export interface NeighbourPanelPorts {
@@ -73,6 +74,14 @@ export class NeighbourPanels {
73
74
  return new Map([...this.cells].map(([id, cell]) => [id, cell.bindings.map((b) => ({ panel: b.row.panel, visible: b.panel.visible }))]));
74
75
  }
75
76
 
77
+ /** A cell's door panels as the probe reads them (T2E-1b): drawn, and solid while every collider stands in its admitted
78
+ * region (a panel with no colliders reads solid, as `shardfile.targets()` does). */
79
+ targets(instance: string): readonly ProbeAreaTarget[] {
80
+ const cell = this.cells.get(instance), region = this.ports.region(instance);
81
+ return cell?.bindings.map(({ row, panel }) => ({ panel: row.panel, visible: panel.visible,
82
+ solid: region !== undefined && row.colliders.every(id => region.colliders.get(id)?.active() === true) })) ?? [];
83
+ }
84
+
76
85
  private sync(cell: CellPanels): void {
77
86
  const region = this.ports.region(cell.instance);
78
87
  for (const { row, panel, fallback } of cell.bindings) {
@@ -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
  }