@wildshard/engine 0.1.18 → 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 (293) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/budgets/shard-size-baseline.json +10 -4
  3. package/index.html +6 -4
  4. package/lint/engine-sides.json +14 -0
  5. package/lint/ratchet.json +0 -68
  6. package/lint/ratchet.mjs +1 -4
  7. package/package.json +17 -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 +22 -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 +81 -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 +277 -0
  51. package/scripts/grid-crossing-walk-proof.mjs +124 -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/live-prepush.py +3 -5
  56. package/scripts/loading-flow/benchmax.mjs +3 -1
  57. package/scripts/look-loop/test_look_loop.py +1 -38
  58. package/scripts/memory-proof.mjs +61 -6
  59. package/scripts/mmo-bots.mjs +8 -2
  60. package/scripts/net-lag-proof.mjs +219 -0
  61. package/scripts/night-market-kit-budget.mjs +2 -2
  62. package/scripts/offline-proof-rules.d.mts +2 -2
  63. package/scripts/offline-proof-rules.mjs +15 -4
  64. package/scripts/offline-proof.mjs +74 -13
  65. package/scripts/{shard-platform-output.mjs → output-reader.mjs} +1 -1
  66. package/scripts/page-release/content.d.mts +9 -1
  67. package/scripts/page-release/content.mjs +131 -17
  68. package/scripts/page-release/flow.mjs +36 -10
  69. package/scripts/page-release/stamp-content.mjs +24 -0
  70. package/scripts/page-release.mjs +28 -6
  71. package/scripts/page-size.mjs +2 -1
  72. package/scripts/pin-packs.ts +1 -1
  73. package/scripts/pins.ts +4 -4
  74. package/scripts/precommit-checks.mjs +1 -7
  75. package/scripts/precommit-jobs.mjs +0 -1
  76. package/scripts/precommit-source.py +1 -9
  77. package/scripts/program-discovery.mjs +1 -1
  78. package/scripts/ring-cook.mjs +2 -1
  79. package/scripts/ring-step.ts +1 -1
  80. package/scripts/script-scenario-metrics.mjs +1 -1
  81. package/scripts/shard-output-content.d.mts +1 -1
  82. package/scripts/shard-output-content.mjs +2 -2
  83. package/scripts/shard-outputs.mjs +1 -1
  84. package/scripts/shard-public.mjs +1 -1
  85. package/scripts/shard-wire-meter.mjs +24 -9
  86. package/scripts/side-parity.mjs +4 -2
  87. package/scripts/standalone-smoke.mjs +8 -3
  88. package/scripts/tier-textures.mjs +22 -4
  89. package/scripts/tile-bake-report.mjs +1 -1
  90. package/scripts/tile-bakes.mjs +1 -1
  91. package/scripts/title-assets.generated.json +2 -0
  92. package/scripts/tsconfig.json +0 -2
  93. package/scripts/vendor/basisu/LICENSE +201 -0
  94. package/scripts/vendor/basisu/basis_encoder.cjs +2 -0
  95. package/scripts/vendor/basisu/basis_encoder.wasm +0 -0
  96. package/scripts/vitest-push-guards.config.ts +1 -1
  97. package/scripts/vps/harden-apply.sh +4 -1
  98. package/scripts/vps/harden-prometheus.sh +176 -0
  99. package/scripts/vps/harden.sh +16 -0
  100. package/scripts/vps/rebuild.sh +18 -0
  101. package/scripts/vps/wildshard-config +6 -2
  102. package/scripts/worker-client-play.mjs +6 -2
  103. package/scripts/worktree-reap.mjs +5 -5
  104. package/src/.oxlintrc.json +3 -182
  105. package/src/client/app/entry.ts +10 -2
  106. package/src/client/engine/boot/bootCache.ts +2 -2
  107. package/src/client/engine/boot/bootTrace.ts +12 -4
  108. package/src/client/engine/boot/browserChunkRecovery.ts +4 -0
  109. package/src/client/engine/boot/clearDownloads.ts +5 -2
  110. package/src/client/engine/boot/contentRead.ts +11 -0
  111. package/src/client/engine/boot/gpuFiles.ts +4 -2
  112. package/src/client/engine/boot/lastEnd.ts +99 -12
  113. package/src/client/engine/boot/texturePack.ts +2 -2
  114. package/src/client/engine/net/netPlayer.ts +19 -2
  115. package/src/client/engine/net/otherPlayers.ts +55 -8
  116. package/src/client/engine/net/predictor.ts +33 -9
  117. package/src/client/engine/net/redial.ts +29 -6
  118. package/src/client/engine/pwa/cacheNames.ts +58 -1
  119. package/src/client/engine/pwa/sw.js +41 -11
  120. package/src/client/engine/render/dataLook.ts +152 -40
  121. package/src/client/engine/render/families/detail.ts +89 -0
  122. package/src/client/engine/render/families/pbr.ts +7 -1
  123. package/src/client/engine/render/look.ts +6 -0
  124. package/src/client/engine/render/lookLight.ts +103 -11
  125. package/src/client/engine/render/lookRender.ts +105 -0
  126. package/src/client/engine/saves/indexed.ts +2 -2
  127. package/src/client/engine/telemetry/browserErrors.ts +24 -3
  128. package/src/client/engine/telemetry/staleBuildReport.ts +22 -1
  129. package/src/client/engine/ui/debugOptions.ts +1 -1
  130. package/src/client/engine/ui/lookLightOption.ts +10 -6
  131. package/src/client/engine/ui/namePrompt.ts +7 -0
  132. package/src/client/game/boot/audio.generated.ts +114 -114
  133. package/src/client/game/boot/bytes.generated.ts +118 -220
  134. package/src/client/game/boot/placedSpawn.ts +35 -0
  135. package/src/client/game/boot/spawnDownload.ts +25 -6
  136. package/src/client/game/boot/versions.generated.ts +7 -5
  137. package/src/client/game/devScene/hook.ts +291 -0
  138. package/src/client/game/grid/cellLoading.ts +12 -2
  139. package/src/client/game/grid/live.ts +112 -16
  140. package/src/client/game/grid/liveSession.ts +33 -2
  141. package/src/client/game/grid/mapAtlas.ts +18 -4
  142. package/src/client/game/grid/minimapBlend.ts +15 -5
  143. package/src/client/game/grid/oneWayIn.ts +5 -1
  144. package/src/client/game/grid/placedCells.ts +114 -12
  145. package/src/client/game/grid/placedContent.ts +85 -0
  146. package/src/client/game/grid/prefetch.ts +9 -1
  147. package/src/client/game/grid/productInputs.ts +3 -1
  148. package/src/client/game/grid/productLeases.ts +4 -1
  149. package/src/client/game/grid/products.ts +8 -4
  150. package/src/client/game/grid/roadLook.ts +24 -15
  151. package/src/client/game/grid/roadLookPlatform.ts +4 -2
  152. package/src/client/game/grid/roadResources.ts +24 -0
  153. package/src/client/game/grid/roadSign.worker.ts +4 -3
  154. package/src/client/game/grid/roadSignPaint.ts +16 -5
  155. package/src/client/game/grid/roadSignPreparation.ts +4 -3
  156. package/src/client/game/grid/roadSignScale.ts +8 -0
  157. package/src/client/game/grid/roadTileCapture.worker.ts +3 -1
  158. package/src/client/game/grid/roadTileCaptureWorker.ts +2 -1
  159. package/src/client/game/grid/roadTileWrite.worker.ts +4 -2
  160. package/src/client/game/grid/roadTileWriter.ts +2 -1
  161. package/src/client/game/grid/screenReports.ts +39 -0
  162. package/src/client/game/grid/session.ts +20 -4
  163. package/src/client/game/grid/softWallLook.ts +25 -8
  164. package/src/client/game/mainMenu.ts +6 -2
  165. package/src/client/game/plugin/context.ts +2 -1
  166. package/src/client/game/plugin/followedMovers.ts +7 -1
  167. package/src/client/game/quest/figures.ts +2 -0
  168. package/src/client/game/session/finish.ts +6 -0
  169. package/src/client/game/shardfile/assetCache.ts +4 -4
  170. package/src/client/game/shardfile/client.ts +4 -1
  171. package/src/client/game/shardfile/clientAssets.ts +9 -5
  172. package/src/client/game/shardfile/clientLibrary.ts +1 -1
  173. package/src/client/game/shardfile/clientWater.ts +51 -9
  174. package/src/client/game/shardfile/clientWorker.ts +19 -7
  175. package/src/client/game/shardfile/look.ts +8 -3
  176. package/src/client/game/shardfile/product.ts +34 -7
  177. package/src/client/game/shardfile/productChecks.ts +2 -2
  178. package/src/client/game/shardfile/productCost.ts +2 -2
  179. package/src/client/game/shardfile/readAsset.ts +2 -2
  180. package/src/client/game/shardfile/reflectingWater.ts +73 -0
  181. package/src/client/game/shardfile/seatGrace.ts +9 -0
  182. package/src/client/game/shardfile/skinPlayback.ts +1 -1
  183. package/src/client/game/systems/npc/figureRows.ts +9 -0
  184. package/src/client/host/online/doctor.ts +2 -0
  185. package/src/client/host/online/linkScreens.ts +30 -4
  186. package/src/client/host/standalone/shell.ts +4 -0
  187. package/src/cook/game/astc6Encode.ts +55 -0
  188. package/src/cook/game/astc6Wasm.ts +176 -0
  189. package/src/cook/game/cookJob.ts +30 -6
  190. package/src/cook/game/cookWorker.ts +38 -11
  191. package/src/cook/game/entryTotals.ts +51 -24
  192. package/src/cook/game/shardCook.ts +35 -7
  193. package/src/cook/game/spawnParts.ts +33 -8
  194. package/src/cook/game/tierTextures.ts +87 -14
  195. package/src/server/engine/ai/bossContenders.ts +27 -3
  196. package/src/server/engine/ai/phases.ts +1 -1
  197. package/src/server/engine/entities/creatureRefill.ts +9 -2
  198. package/src/server/engine/net/ledgerBook.ts +2 -0
  199. package/src/server/engine/net/room.ts +15 -0
  200. package/src/server/engine/sim/respawn.ts +8 -0
  201. package/src/server/game/boss/arenaRoomEntry.ts +5 -1
  202. package/src/server/game/boss/arenaRoomNative.ts +2 -0
  203. package/src/server/game/boss/native.ts +2 -1
  204. package/src/server/game/boss/nativeWake.ts +9 -5
  205. package/src/server/game/boss/openArenaNative.ts +2 -2
  206. package/src/server/game/boss/openArenaRoom.ts +3 -1
  207. package/src/server/game/grid/room.ts +44 -3
  208. package/src/server/game/grid/simulation.ts +23 -0
  209. package/src/server/game/population/mixedRoster.ts +11 -3
  210. package/src/server/game/population/nativeBake.ts +8 -3
  211. package/src/server/game/population/nativeReturns.ts +6 -3
  212. package/src/server/game/population/roster.ts +5 -3
  213. package/src/server/game/quest/eliteDrops.ts +15 -4
  214. package/src/server/game/quest/nativeChapter.ts +1 -1
  215. package/src/server/game/quest/nativeComposition.ts +5 -1
  216. package/src/server/game/riding/nativeTaming.ts +10 -6
  217. package/src/server/game/riding/wildRefill.ts +3 -2
  218. package/src/server/game/shardfile/bossRow.ts +4 -2
  219. package/src/server/game/shardfile/homeKeeper.ts +4 -2
  220. package/src/server/host/bake/headlessWorker.ts +1 -1
  221. package/src/server/host/dedicated/cellHost.ts +98 -16
  222. package/src/server/host/dedicated/cellProtocol.ts +16 -1
  223. package/src/server/host/dedicated/cellWorker.ts +8 -5
  224. package/src/server/host/dedicated/dedicatedRoom.ts +16 -6
  225. package/src/server/host/dedicated/gridCells.ts +15 -6
  226. package/src/server/host/dedicated/loopLag.ts +21 -0
  227. package/src/server/host/dedicated/main.ts +13 -5
  228. package/src/server/host/dedicated/packReader.ts +3 -3
  229. package/src/server/host/dedicated/placementFile.ts +3 -2
  230. package/src/server/host/dedicated/roadRoom.ts +34 -4
  231. package/src/server/host/dedicated/serverMetrics.ts +126 -0
  232. package/src/server/host/dedicated/socketPump.ts +21 -4
  233. package/src/server/host/dedicated/workerTable.ts +15 -4
  234. package/src/server/host/dedicated/world.ts +65 -7
  235. package/src/server/host/headless.ts +1 -1
  236. package/src/server/host/headlessRuntime.ts +1 -1
  237. package/src/server/host/standalone/roadWorld.ts +15 -3
  238. package/src/server/host/standalone/serverHost.ts +4 -1
  239. package/src/server/host/standalone/serverProduct.ts +41 -11
  240. package/src/shared/engine/ai/BossBrain.ts +8 -0
  241. package/src/shared/game/boss/wake.ts +6 -0
  242. package/src/shared/game/devColliders.ts +47 -0
  243. package/src/shared/game/eliteSystem.ts +8 -0
  244. package/src/shared/game/grid/allocator.ts +3 -0
  245. package/src/shared/game/grid/placementRows.ts +5 -2
  246. package/src/shared/game/plugin/bossRecord.ts +3 -2
  247. package/src/shared/game/shardfile/ktx2Targets.ts +23 -3
  248. package/src/shared/game/shardfile/outputDescriptor.ts +9 -5
  249. package/src/shared/game/shardfile/packReads.ts +28 -3
  250. package/src/shared/game/shardfile/serverPack.ts +9 -0
  251. package/src/shared/game/systems/looks/trampleField.ts +2 -0
  252. package/src/shared/host/formatJsonSchema.ts +2 -2
  253. package/src/tsconfig.json +1 -27
  254. package/lint/host-reviews.json +0 -14
  255. package/lint/listed-view-code.json +0 -13
  256. package/lint/platform-pending-users.json +0 -2520
  257. package/lint/platform-pending-users.md +0 -18
  258. package/scripts/cell-mem/metrics-preload.mjs +0 -65
  259. package/scripts/check-closed-components.d.mts +0 -7
  260. package/scripts/check-closed-components.mjs +0 -87
  261. package/scripts/g571-hosts.d.mts +0 -3
  262. package/scripts/g571-hosts.mjs +0 -54
  263. package/scripts/host-ruler/register-migrate.mjs +0 -242
  264. package/scripts/listed-view-code.d.mts +0 -7
  265. package/scripts/listed-view-code.mjs +0 -93
  266. package/scripts/look-loop/fit-lut.py +0 -142
  267. package/scripts/look-loop/palette-delta.py +0 -183
  268. package/scripts/look-loop/regions/driftwood-isle.json +0 -25
  269. package/scripts/look-loop/regions/far-reach.json +0 -225
  270. package/scripts/look-loop/regions/open-plot-night-market.json +0 -855
  271. package/scripts/look-loop/regions/pine-hollow.json +0 -22
  272. package/scripts/look-loop/regions/sunscar-dunes.json +0 -281
  273. package/scripts/platform-chargebacks.d.mts +0 -9
  274. package/scripts/platform-chargebacks.mjs +0 -135
  275. package/scripts/shard-component-spans.d.mts +0 -15
  276. package/scripts/shard-component-spans.mjs +0 -18
  277. package/scripts/shard-components.d.mts +0 -16
  278. package/scripts/shard-components.mjs +0 -363
  279. package/scripts/shard-platform-hosts.d.mts +0 -2
  280. package/scripts/shard-platform-hosts.mjs +0 -93
  281. package/scripts/shard-platform-sections.d.mts +0 -2
  282. package/scripts/shard-platform-sections.mjs +0 -9
  283. package/scripts/shard-platform.d.mts +0 -76
  284. package/scripts/shard-platform.mjs +0 -1072
  285. package/src/.oxfmtrc.json +0 -48
  286. package/src/scripts/ask-new.sh +0 -29
  287. package/src/scripts/asks.mjs +0 -142
  288. package/src/scripts/herdr-prompt.sh +0 -34
  289. package/src/scripts/herdr-question-open.sh +0 -67
  290. package/src/scripts/md-wrap.mjs +0 -229
  291. /package/scripts/{shard-platform-format.d.mts → node-format.d.mts} +0 -0
  292. /package/scripts/{shard-platform-format.mjs → node-format.mjs} +0 -0
  293. /package/scripts/{shard-platform-output.d.mts → output-reader.d.mts} +0 -0
@@ -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; }
@@ -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,6 +870,31 @@ export class LiveGridSession {
864
870
  const current = this.live.current();
865
871
  return current !== null && this.runtimeRegions.has(current) ? current : null;
866
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
+ }
867
898
  /** G555: the entered runtime hooks' timings (the one running and those finished), for the cell loading screen. */
868
899
  hookTimings(): ReturnType<HybridRuntimeSession['timings']> { return this.hybrid.timings(); }
869
900
  /** GC2: the server still has this client in `instance` (an online cell is still walled, C5). */
@@ -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
  }
@@ -4,18 +4,29 @@
4
4
  // Shard Select card and `?chunk=<slug>` landed on the deck. The file is believed only under the API's placement key, as the box and
5
5
  // SA35's preview bake believe it. A missing, late, unreadable or refused file keeps the build's grid: boot never waits past
6
6
  // `PLACED_DEADLINE_MS` and never fails here. The bucket sends it `no-store`, the read asks `no-store`, and the service worker leaves
7
- // `/releases/` to the network (sw.js `isContentRead`), so no page keeps an old file.
7
+ // `/releases/` to the network (sw.js `isContentRead`), so no cache serves an old file.
8
+ // OFFLINE OF20: the device keeps the last file it believed (its text, in OF0's `gridRoute` slot, beside the world's kept word), and
9
+ // the next page installs it at once, its signature checked again: offline, or on a link that hangs past the deadline, Shard Select
10
+ // still has the cells this device last saw. A fresh file read in time replaces it, from the build's own catalogue; a 404 drops it.
11
+ // PAGE-SIZE (time to the title): the device keep imports the saves slots (about 1.2 MB of chunks) only when it is read or written,
12
+ // never on the title's path: online it is read only once the fresh read is slow (`KEPT_AFTER_MS`) or fails, and written a while after.
8
13
  import * as v from 'valibot';
9
14
  import { Scope } from '@wildshard/engine/app/scope';
15
+ import type { Json, jsonSlot } from '@wildshard/engine/saves/slots';
10
16
  import { GRID_RADIUS } from '@wildshard/format/contentBounds';
11
17
  import { PLACEMENT_PUBLIC_KEY, PlacementSchema, SignedPlacementSchema, placementsURL, type PlacementFile } from '../../../shared/game/grid/placementRows';
12
18
  import { installCatalogue, installedCatalogue, type CatalogueDocument } from '../../../shared/game/grid/catalogueSlot';
13
19
  import { findTitleManifest, installTitleManifests, titleManifests } from '../shard/titleList';
14
20
  import { catalogueCards } from './placedCards';
21
+ import { installPlacedContent, placedContent, type PlacedContent } from './placedContent';
15
22
  import { parseGridCatalogue } from '../../../shared/game/grid/catalogue';
16
23
 
17
24
  /** How long a page's boot waits for the file: GO4's 3 s, the world word's own deadline. A slower answer leaves the build's grid. */
18
25
  export const PLACED_DEADLINE_MS = 3000;
26
+ /** OF20 with the title's time: an online page reads its kept file only once the fresh read has taken this long (or failed). */
27
+ export const KEPT_AFTER_MS = 600;
28
+ /** How long after the fresh file is believed the device keep writes it (its slots chunks load then, off the title's path). */
29
+ export const KEEP_WRITE_AFTER_MS = 5000;
19
30
 
20
31
  type Cell = PlacementFile['cells'][number];
21
32
  const hexBytes = (hex: string): Uint8Array<ArrayBuffer> => Uint8Array.from(hex.match(/../gu) ?? [], pair => Number.parseInt(pair, 16));
@@ -73,7 +84,33 @@ export function addPlacedCells(document: CatalogueDocument, file: PlacementFile,
73
84
 
74
85
  /** What a page's read of its placement file did, for the console and the tests: `carded` names the added slugs whose card came
75
86
  * from the API's catalogue (SA46). */
76
- export type PlacedRead = { readonly added: readonly Cell[]; readonly left: readonly string[]; readonly serial: number; readonly carded: readonly string[] } | { readonly kept: string };
87
+ export type PlacedRead = { readonly added: readonly Cell[]; readonly left: readonly string[]; readonly serial: number; readonly carded: readonly string[];
88
+ /** OF20: the device's kept file, because the fresh one did not come (why) */ readonly cached?: string } | { readonly kept: string };
89
+ /** OF20: the last placement file this device believed, by its address. */
90
+ export interface PlacedKeep {
91
+ readonly read: (url: string) => string | null | Promise<string | null>;
92
+ readonly write: (url: string, text: string | null) => void | Promise<void>;
93
+ }
94
+ /** OF20: in OF0's device slot `gridRoute` (oneWayIn.ts `deviceRouteMemory`), as `placed: { url, text }`: one store for the world's
95
+ * last word and its last layout. The slots module is imported on the first read or write, never with this file (PAGE-SIZE: it is
96
+ * about 1.2 MB of chunks the title would wait for). */
97
+ export function devicePlacedKeep(): PlacedKeep {
98
+ const slot = async (): Promise<ReturnType<typeof jsonSlot>> =>
99
+ (await import('@wildshard/engine/saves/slots')).jsonSlot('gridRoute', 'device');
100
+ const row = async (): Promise<Record<string, Json>> => { const value = (await slot()).read(); return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : {}; };
101
+ return {
102
+ read: async url => {
103
+ try {
104
+ const placed = (await row())['placed'];
105
+ return typeof placed === 'object' && placed !== null && !Array.isArray(placed) && placed['url'] === url && typeof placed['text'] === 'string' ? placed['text'] : null;
106
+ } catch { return null; }
107
+ },
108
+ write: async (url, text) => {
109
+ try { const { placed: _old, ...rest } = await row(); (await slot()).write(text === null ? rest : { ...rest, placed: { url, text } }); }
110
+ catch { /* a device that keeps nothing reads the network only, as before */ }
111
+ },
112
+ };
113
+ }
77
114
  export interface PlacedPorts {
78
115
  readonly fetch?: typeof fetch;
79
116
  readonly publicKey?: string;
@@ -88,7 +125,22 @@ export interface PlacedPorts {
88
125
  readonly api?: string;
89
126
  /** The catalogue lookups' own deadline (`placedCards.ts` `CARD_DEADLINE_MS`). */
90
127
  readonly cardDeadlineMs?: number;
128
+ /** SA48: a carded slug's content from the cook (`placedContent.ts`), by the hash its cell names; default: this page's build's index in
129
+ * the store at the placement file's origin. A slug with none stays out. */
130
+ readonly content?: (slug: string, hash: string | undefined, signal: AbortSignal) => Promise<PlacedContent | undefined>;
131
+ /** OF20: where the last believed file is kept (default: the device, `devicePlacedKeep`) */
132
+ readonly keep?: PlacedKeep;
133
+ /** An online page reads its kept file once the fresh read has taken this long (default `KEPT_AFTER_MS`); offline at once. */
134
+ readonly keptAfterMs?: number;
135
+ /** The fresh file is kept this long after it is believed (default `KEEP_WRITE_AFTER_MS`; the default keep only). */
136
+ readonly keepWriteAfterMs?: number;
91
137
  }
138
+ /** The cook's content for a placed slug, from the store the placement file is in, for this page's build under its own validator. */
139
+ const cookContent = (url: string, read: typeof fetch): NonNullable<PlacedPorts['content']> => (slug, hash, signal) => {
140
+ const build: unknown = Reflect.get(globalThis, '__WS_BUILD_ID__'), validator: unknown = Reflect.get(globalThis, '__WS_SHARDFILE_VALIDATOR__');
141
+ return hash === undefined || typeof build !== 'string' ? Promise.resolve(undefined)
142
+ : placedContent(slug, hash, { fetch: read, signal, packs: new URL('/', url).href, build, validator: typeof validator === 'string' ? validator : null });
143
+ };
92
144
  /** After every row's `order`, so a carded shard is last in the deck. */
93
145
  const nextOrder = (rows: readonly { readonly order?: number }[]): number => rows.reduce((top, row) => Math.max(top, row.order ?? 0), rows.length) + 1;
94
146
  /** Read the file at `url` and install the build's catalogue with its cells. Never throws: anything but a believed file keeps the build's
@@ -102,28 +154,78 @@ export async function learnPlacedCells(url: string, ports: PlacedPorts = {}): Pr
102
154
  const abort = new AbortController(), stop = (): void => { abort.abort(); };
103
155
  scope.timeout(ports.deadlineMs ?? PLACED_DEADLINE_MS, stop);
104
156
  if (ports.signal?.aborted === true) stop(); else if (ports.signal !== undefined) scope.listen(ports.signal, 'abort', stop);
105
- const response = await (ports.fetch ?? fetch)(url, { cache: 'no-store', credentials: 'omit', redirect: 'error', signal: abort.signal });
106
- if (response.status === 404) return { kept: 'no placement file (404): nothing placed on this channel' };
107
- if (!response.ok) return { kept: `placement file ${String(response.status)}` };
108
- const file = await readSignedPlacement(await response.text(), ports.publicKey);
109
157
  const channel = /\/releases\/(staging|production)-placements\.json$/u.exec(new URL(url).pathname)?.[1];
110
- if (channel !== undefined && file.channel !== channel) return { kept: `a ${file.channel} placement file at the ${channel} address` };
158
+ const believe = async (text: string): Promise<PlacementFile> => {
159
+ const read = await readSignedPlacement(text, ports.publicKey);
160
+ if (channel !== undefined && read.channel !== channel) throw new Error(`a ${read.channel} placement file at the ${channel} address`);
161
+ return read;
162
+ };
111
163
  const known = ports.known ?? (slug => findTitleManifest(slug) !== undefined);
112
164
  // the page's own deadline, read afresh after each wait: once it fires the boot has gone on
113
165
  const wentOn = (): boolean => ports.signal?.aborted === true;
166
+ // OF20: the kept file, so a page whose read never comes still has the layout this device last saw. Offline it is read at once;
167
+ // online only once the fresh read is slow or fails, so the title never waits for the keep's chunks (PAGE-SIZE). A fresh file
168
+ // installed first wins: the kept one never replaces it.
169
+ const keep = ports.keep ?? devicePlacedKeep();
170
+ let cached: { readonly added: readonly Cell[]; readonly left: readonly string[]; readonly serial: number } | undefined, fresh = false;
171
+ let keptRead: Promise<void> | undefined;
172
+ const readKept = (): Promise<void> => (keptRead ??= (async () => {
173
+ const held = await keep.read(url);
174
+ if (held === null || fresh) return;
175
+ try {
176
+ const file = await believe(held), kept = addPlacedCells(document, file, known);
177
+ if (!fresh && !wentOn() && kept.added.length > 0) { installCatalogue(kept.document); cached = { added: kept.added, left: kept.left, serial: file.serial }; }
178
+ } catch { await keep.write(url, null); } // a kept file this build no longer believes is dropped
179
+ })().catch(() => undefined));
180
+ if (typeof navigator !== 'undefined' && !navigator.onLine) void readKept();
181
+ else scope.timeout(ports.keptAfterMs ?? KEPT_AFTER_MS, () => { void readKept(); });
182
+ const fallBack = async (why: string): Promise<PlacedRead> => {
183
+ await readKept();
184
+ return cached === undefined ? { kept: why } : { ...cached, carded: [], cached: why };
185
+ };
186
+ let response: Response;
187
+ try { response = await (ports.fetch ?? fetch)(url, { cache: 'no-store', credentials: 'omit', redirect: 'error', signal: abort.signal }); }
188
+ catch (error) { return await fallBack(error instanceof Error ? error.message : String(error)); }
189
+ if (response.status === 404) {
190
+ // nothing placed on this channel now: the kept cells leave too
191
+ fresh = true;
192
+ await keep.write(url, null);
193
+ if (cached !== undefined && !wentOn()) installCatalogue(document);
194
+ return { kept: 'no placement file (404): nothing placed on this channel' };
195
+ }
196
+ if (!response.ok) return await fallBack(`placement file ${String(response.status)}`);
197
+ let text: string, file: PlacementFile;
198
+ try { text = await response.text(); file = await believe(text); }
199
+ catch (error) { return await fallBack(error instanceof Error ? error.message : String(error)); }
114
200
  const placed = addPlacedCells(document, file, known);
115
- if (wentOn()) return { kept: 'the page went on before the placement file was read' };
116
- if (placed.added.length > 0) installCatalogue(placed.document);
201
+ // only a file that places cleanly is kept; the device keep writes it a while later, off the title's path
202
+ if (ports.keep === undefined) {
203
+ const believed = text, later = new Scope('grid.placed-keep');
204
+ later.timeout(ports.keepWriteAfterMs ?? KEEP_WRITE_AFTER_MS, () => { void keep.write(url, believed); later.dispose(); });
205
+ }
206
+ else await keep.write(url, text);
207
+ if (wentOn()) return await fallBack('the page went on before the placement file was read');
208
+ fresh = true;
209
+ // from the build's own catalogue, so the fresh file replaces the kept one's cells
210
+ if (placed.added.length > 0 || cached !== undefined) installCatalogue(placed.document);
117
211
  // SA46: a cell the box would open whose slug this build has no card for (an upload after the build) is carded from its catalogue
118
212
  // entry, after the build's own cells are in, so a slow or absent API costs them nothing; a slug it does not card stays out
119
213
  const unknown = addPlacedCells(placed.document, file).added.map(cell => cell.slug);
120
214
  const built = { added: placed.added, left: placed.left, serial: file.serial, carded: [] };
121
215
  if (unknown.length === 0) return built;
122
- const cards = await catalogueCards(unknown, { fetch: ports.fetch ?? fetch, signal: abort.signal, order: nextOrder(titleManifests()), ...(ports.api === undefined ? {} : { api: ports.api }),
123
- ...(ports.cardDeadlineMs === undefined ? {} : { deadlineMs: ports.cardDeadlineMs }) });
216
+ // SA48: its content from the cook beside its card, so ENTER WORLD loads it; a card with no content would only fail at the door
217
+ const hashes = new Map(file.cells.map(cell => [cell.slug, cell.hash])), content = ports.content ?? cookContent(url, ports.fetch ?? fetch);
218
+ const [cards, contents] = await Promise.all([
219
+ catalogueCards(unknown, { fetch: ports.fetch ?? fetch, signal: abort.signal, order: nextOrder(titleManifests()), ...(ports.api === undefined ? {} : { api: ports.api }),
220
+ ...(ports.cardDeadlineMs === undefined ? {} : { deadlineMs: ports.cardDeadlineMs }) }),
221
+ Promise.all(unknown.map(slug => content(slug, hashes.get(slug), abort.signal).catch(() => undefined))),
222
+ ]);
223
+ const cooked = new Map<string, PlacedContent>();
224
+ unknown.forEach((slug, n) => { const found = contents[n]; if (found !== undefined) cooked.set(slug, found); });
124
225
  if (cards.length === 0 || wentOn()) return built;
125
- const carded = new Set(cards.map(row => row.slug)), more = addPlacedCells(placed.document, file, slug => carded.has(slug));
226
+ const carded = new Set(cards.filter(row => cooked.has(row.slug)).map(row => row.slug)), more = addPlacedCells(placed.document, file, slug => carded.has(slug));
126
227
  const opened = new Set(more.added.map(cell => cell.slug)), rows = cards.filter(row => opened.has(row.slug));
228
+ for (const slug of opened) { const found = cooked.get(slug); if (found !== undefined) installPlacedContent(found); }
127
229
  if (more.added.length > 0) installCatalogue(more.document);
128
230
  if (rows.length > 0) installTitleManifests([...titleManifests(), ...rows]);
129
231
  return { added: [...placed.added, ...more.added], left: more.left, serial: file.serial, carded: rows.map(row => row.slug) };
@@ -0,0 +1,85 @@
1
+ // SHARD-AUTHORING SA48 (meta SHARD-AUTHORING-PLAN): the content of a shard the API placed after this page was built. SA46 cards it, but
2
+ // entering reads its client product from the build's spawn rows, which no build has for a new author's upload. The cook does (MMO-SERVER
3
+ // MS2.4): for this build and the bytes the signed placement file names (`hash`, SA47 (1)) it writes `index/<build>/<hash>.json` beside
4
+ // its manifests, parts and header in the packs store. This reads that index and each manifest it names, and gives the rows a bake's
5
+ // `addCookedShards` would have written (the entry and whole-level addresses, the store as their home, whether it recorded programs),
6
+ // with the page's admission row for its header (`productVerdict`'s, believed only under this page's own validator revision). Any
7
+ // failure (no index yet, a 404, junk, another build's or slug's index, another validator) gives nothing, and the slug stays out.
8
+ import * as v from 'valibot';
9
+ import { bareSlug } from '../../../shared/game/grid/catalogueSlot';
10
+ import { readSpawnManifest, readSpawnManifestAddress, type SpawnManifestAddress } from '../../../shared/game/shardfile/spawnManifest';
11
+ import { cookIndexPath } from '../../../shared/game/shardfile/serverPack';
12
+ import { installPlacedSpawn, type PlacedSpawn } from '../boot/placedSpawn';
13
+
14
+ /** An index is a few KB; a manifest is at most `readSpawnManifestAddress`'s 2 MB. */
15
+ const INDEX_BYTES = 256 * 1024, MANIFEST_BYTES = 2_000_000;
16
+ const size = v.pipe(v.number(), v.safeInteger(), v.minValue(0));
17
+ const hex = v.pipe(v.string(), v.regex(/^[a-f0-9]{64}$/u));
18
+ const ManifestRow = v.object({ url: v.pipe(v.string(), v.regex(/^\/assets\/spawn\/[a-z0-9_-]+-(?:entry|whole)-(?:phone|desktop)-[a-f0-9]{16}\.json$/u)),
19
+ tier: v.picklist(['phone', 'desktop']), set: v.picklist(['entry', 'whole']), files: size, totalBytes: size, wireBytes: size });
20
+ const IndexSchema = v.object({ version: v.literal(1), build: v.string(), slug: v.pipe(v.string(), v.regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/u)), hash: hex, header: v.string(),
21
+ manifests: v.pipe(v.array(ManifestRow), v.maxLength(8)), keys: v.pipe(v.array(v.string()), v.maxLength(100_000)), loose: v.string(),
22
+ verdict: v.optional(v.looseObject({ revision: hex, sourceHash: v.string(), indexHash: hex, residentBytes: v.pipe(v.number(), v.safeInteger(), v.minValue(1)),
23
+ postCost: v.looseObject({}), worst: v.optional(v.unknown()) })) });
24
+
25
+ /** What a placed slug needs to enter: its spawn rows and its header's admission row. */
26
+ export interface PlacedContent { readonly spawn: PlacedSpawn; readonly verdict: Readonly<Record<string, unknown>> | null }
27
+ export interface PlacedContentPorts {
28
+ readonly fetch: typeof fetch;
29
+ readonly signal: AbortSignal;
30
+ /** The store's root: the placement file's origin (`https://packs.wildshard.io/`), where the cook writes. */
31
+ readonly packs: string;
32
+ /** This page's build (`__BUILD_ID__`), the cook's folder. */
33
+ readonly build: string;
34
+ /** This page's validator revision (`__WS_SHARDFILE_VALIDATOR__`); null on a page with none (the dev server), which admits by no row. */
35
+ readonly validator: string | null;
36
+ }
37
+
38
+ async function bounded(response: Response, cap: number): Promise<Uint8Array<ArrayBuffer>> {
39
+ if (!response.ok) { await response.body?.cancel(); throw new Error(`HTTP ${String(response.status)}`); }
40
+ const body = new Uint8Array(await response.arrayBuffer());
41
+ if (body.byteLength > cap) throw new Error('Too large');
42
+ return body;
43
+ }
44
+ const decode = (bytes: Uint8Array): unknown => JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
45
+
46
+ /** The cook's content for `slug` at `hash`, or undefined for anything but this build's index of these bytes. Never throws. */
47
+ export async function placedContent(slug: string, hash: string, ports: PlacedContentPorts): Promise<PlacedContent | undefined> {
48
+ try {
49
+ if (!/^[a-f0-9]{64}$/u.test(hash) || !/^[\w.-]{1,64}$/u.test(ports.build) || !ports.packs.endsWith('/')) return undefined;
50
+ const read = ports.fetch, at = (path: string): string => new URL(path.replace(/^\//u, ''), ports.packs).href;
51
+ // past the CDN's cached 404 (a query of its own, as the box reads it, SA47): an index missing now may be written a minute later
52
+ // (to the minute, so the edge still takes a busy page's repeats)
53
+ const indexAt = `${at(cookIndexPath(ports.build, hash))}?t=${String(Math.floor(Date.now() / 60_000))}`;
54
+ const index = v.parse(IndexSchema, decode(await bounded(await read(indexAt, { cache: 'no-store', credentials: 'omit', redirect: 'error', signal: ports.signal }), INDEX_BYTES)));
55
+ const product = index.slug;
56
+ if (index.build !== ports.build || index.hash !== hash || product !== bareSlug(slug) || index.header !== `shardfiles/${product}/shard.json`
57
+ || index.loose !== `loose/${hash}/`) return undefined;
58
+ // a page that checks admission admits only a header its own validator's revision passed; a page with none asks nothing
59
+ if (ports.validator !== null && index.verdict?.revision !== ports.validator) return undefined;
60
+ // each manifest's own length is its address's (`readSpawnManifestAddress`); it is content-named, so this read is the download's
61
+ const addresses = await Promise.all(index.manifests.map(async row => {
62
+ const body = await bounded(await read(at(row.url), { credentials: 'omit', redirect: 'error', signal: ports.signal }), MANIFEST_BYTES);
63
+ const manifest = readSpawnManifest(decode(body));
64
+ if (manifest.shard !== product || manifest.tier !== row.tier || manifest.files.length !== row.files || manifest.totalBytes !== row.totalBytes) throw new Error(`${row.url} is not its row`);
65
+ return { row, address: readSpawnManifestAddress({ url: row.url, bytes: body.byteLength, totalBytes: row.totalBytes, files: row.files, wireBytes: row.wireBytes }) };
66
+ }));
67
+ const pick = (set: 'entry' | 'whole'): Partial<Record<'phone' | 'desktop', SpawnManifestAddress>> =>
68
+ Object.fromEntries(addresses.filter(({ row }) => row.set === set).map(({ row, address }) => [row.tier, address]));
69
+ const entry = pick('entry');
70
+ if (entry.phone === undefined || entry.desktop === undefined) return undefined;
71
+ const verdict = index.verdict === undefined ? null : { ...index.verdict, path: `/${index.header}` };
72
+ return { spawn: { slug: product, entry, whole: pick('whole'), base: ports.packs, loose: at(index.loose),
73
+ programs: index.keys.includes(`${index.loose}programs/${product}.json`) }, verdict };
74
+ } catch { return undefined; }
75
+ }
76
+
77
+ /** Make a placed slug's content this page's: its spawn rows for the download, and its admission row beside the build's own. */
78
+ export function installPlacedContent(content: PlacedContent): void {
79
+ installPlacedSpawn(content.spawn);
80
+ const verdicts: unknown = Reflect.get(globalThis, '__WS_SHARDFILE_VERDICTS__');
81
+ if (content.verdict === null || !Array.isArray(verdicts)) return;
82
+ // one row a path: a later learn of another upload replaces this page's earlier one (the build's own paths are never placed slugs)
83
+ const at = verdicts.findIndex((row: unknown) => typeof row === 'object' && row !== null && Reflect.get(row, 'path') === content.verdict?.['path']);
84
+ if (at === -1) verdicts.push(content.verdict); else verdicts.splice(at, 1, content.verdict);
85
+ }
@@ -25,6 +25,7 @@ import type { OfflineDownloadEnd } from '@wildshard/engine/ui/offlineDownload';
25
25
  import { hasCachedAsset, cacheAsset } from '../shardfile/assetCache';
26
26
  import { builtIndexHash, builtIndexHashes } from '@wildshard/format/builtIndexes';
27
27
  import { readPrefetchIndex } from './prefetchIndex';
28
+ import { markPackMissing, packGone, packMissing } from '../../../shared/game/shardfile/packReads';
28
29
  import type { GridAssembly } from '../../../shared/game/grid/assembly';
29
30
  import {TIER, MOBILE_DEVICE, type Tier} from '@wildshard/engine/core/tier';
30
31
  import { prefetchRing } from './titleOrder';
@@ -181,7 +182,14 @@ class GridPrefetch {
181
182
  }
182
183
  for (const pack of index.packs ?? []) {
183
184
  const members = byPack.get(pack.hash);
184
- if (members !== undefined && this.status.reason === null) await this.pack(pack, members, base, { holds, keepAsset }, quota);
185
+ if (members === undefined || this.status.reason !== null) continue;
186
+ // PZ7: a pack that is not published (or fails) leaves its members to their loose URLs
187
+ if (packMissing(pack)) { loose.push(...members); continue; }
188
+ try { await this.pack(pack, members, base, { holds, keepAsset }, quota); }
189
+ catch (error: unknown) {
190
+ if (!packGone(error)) throw error; // an abort, or a pack refused for its bytes
191
+ markPackMissing(pack, error); loose.push(...members);
192
+ }
185
193
  }
186
194
  rows.splice(0, rows.length, ...loose);
187
195
  let next = 0;
@@ -72,7 +72,9 @@ export class ProductInputs {
72
72
  const bytes = missing.reduce((sum, ref) => sum + (source.files.find(file => file.hash === ref)?.compressed ?? source.requires.commonsWire[ref.replace(/^commons:/u, '')] ?? 0), 0);
73
73
  const lease = this.reserve(bytes, signal !== undefined), loaded = new Map<string, Uint8Array>();
74
74
  try {
75
- const width = signal === undefined ? 1 : 4;
75
+ // GC9: a cell's world reads its inputs back from the cache before it builds (Pine: about 1,500 files); one at a time
76
+ // that read was most of the build behind a moving player's loading wall. Eight in flight; a cancellable approach four.
77
+ const width = signal === undefined ? 8 : 4;
76
78
  for (let i = 0; i < missing.length; i += width) {
77
79
  active(); const batch = missing.slice(i, i + width);
78
80
  const results = await Promise.allSettled(batch.map(ref => this.reader.read(ref)));
@@ -4,6 +4,9 @@ import { ApproachInputsDeferredError } from './productInputs';
4
4
  import { productResidentBytesSteps } from '../shardfile/productCost';
5
5
  import { workSlice } from '@wildshard/engine/core/workSlice';
6
6
 
7
+ /** A required product read the shared budget refused for now (not a broken product). */
8
+ export const PRODUCT_DEFERRED = 'Product residency admission deferred';
9
+
7
10
  /** A caller holds the product while any admitted source or immutable transport bytes are still in use. */
8
11
  export interface ProductLease<T> { readonly value: T; release: () => void }
9
12
  interface Entry<T> { promise: Promise<T>; claim: ResidencyLease | undefined; bytes: number; users: number; settled: boolean; failed: boolean; optional: boolean }
@@ -37,7 +40,7 @@ export class ProductLeases<T> {
37
40
  const request = { id: `product:${this.owner}:${key}`, category: 'product' as const, owner: this.owner,
38
41
  bytes: fresh.bytes, distance: 0, needed: true, evictSync: () => { this.entries.delete(key); fresh.claim = undefined; } };
39
42
  const claim = fresh.optional ? this.allocator.reserveIfFits(request) : this.allocator.reserve(request);
40
- if (claim === null) { if (fresh.optional) throw new ApproachInputsDeferredError(); throw new Error('Product residency admission deferred'); } fresh.claim = claim;
43
+ if (claim === null) { if (fresh.optional) throw new ApproachInputsDeferredError(); throw new Error(PRODUCT_DEFERRED); } fresh.claim = claim;
41
44
  }, bytes => {
42
45
  if (this.closed) return; // A decoder completing after page disposal has no live claim to reduce.
43
46
  if (fresh.claim === undefined) throw new Error('Transport release needs a product claim');
@@ -27,7 +27,7 @@ import * as v from 'valibot';
27
27
  import { GridAdmissionPriority } from './admissionPriority';
28
28
  import { timeClientPreparation } from '../shardfile/preparationTiming';
29
29
  import { readCheckedOutputIndex } from '../../../shared/game/shardfile/outputIndexChecks';
30
- import { packReads, type PackReads } from '../../../shared/game/shardfile/packReads';
30
+ import { packOrLoose, packReads, type PackReads } from '../../../shared/game/shardfile/packReads';
31
31
 
32
32
  const edgeRows = v.strictObject({ edge: EdgeProfilesSchema, entryways: EntrywaysSchema });
33
33
  const farRow = v.looseObject({ far: v.nullable(v.looseObject({ decoded: v.number(), gpu: v.number() })) });
@@ -82,7 +82,9 @@ async function readGridProductFile(at: GridProductIndex, path: string, hash: str
82
82
  if(native!==undefined)return native(address,size,undefined,hash);
83
83
  const held = await options.cache?.asset(base, hash) ?? await options.cachedResponse?.(address, hash, size);
84
84
  if ((held === null || held === undefined) && options.offline) throw new Error(`Missing cached grid product file ${path}`);
85
- const bytes = held ?? (at.packed.has(hash) ? await at.packed.read(hash) : await boundedResponse(await options.fetch(address), size));
85
+ const loose = async (): Promise<Uint8Array> => boundedResponse(await options.fetch(address), size);
86
+ // PZ7: a pack that is not published (or fails) falls back to the file's own URL
87
+ const bytes = held ?? (at.packed.has(hash) ? await packOrLoose(() => at.packed.read(hash), loose) : await loose());
86
88
  if (bytes.length !== size || await options.hash(bytes) !== hash) throw new Error(`Grid product file ${path} hash or size mismatch`);
87
89
  if (held === null || held === undefined) {
88
90
  const cache = options.cache;
@@ -343,8 +345,10 @@ export function gridShardfileProduct(slug: string, owner: GridProductOwner, mode
343
345
  const input = options.firstPartyRead===undefined
344
346
  ? await readIndexBytes(await boundedResponse(await options.fetch(url.href), limits.sourceBytes), options)
345
347
  : await readProductDescriptor(options,url);
346
- const admitted = await timeClientPreparation(slug, 'product.read', () => admitProduct(input, { ...options, reserve }));
347
- const selectedInputs = [...admitted.assets.keys()];
348
+ // GC9: the runtime-only wires released below are never read here (Pine's read fetched and hashed ~1,500 files twice)
349
+ const admitted = await timeClientPreparation(slug, 'product.read', () => admitProduct(input, { ...options, reserve, deferred: source => neighbourProductFilesPaced(source, options.pause) }));
350
+ // GC9: the files admission left unread stay selected inputs (approach and tile admissions read them back by name)
351
+ const selectedInputs = [...admitted.assets.keys(), ...admitted.unread ?? []];
348
352
  // admission already refused a stack past the budget on its own; the cost is what placement sums per adjacent pair
349
353
  gridPostCosts(owner.allocator).record(slug, productPostCost(admitted.source, (hash) => admitted.assets.get(hash)));
350
354
  const preparation: { inputs?: ProductInputs } = {};