@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
@@ -0,0 +1,55 @@
1
+ // SHARD-AUTHORING SA46 (meta SHARD-AUTHORING-PLAN): the card of a shard the API placed after this page was built. The placement file
2
+ // (`placedCells.ts`) names its cell, but the build bakes no title row for it: a new author's slug uploaded since. Its row comes from
3
+ // the API's catalogue entry (`GET /api/catalogue/shards/<slug>`, which answers the three game origins with CORS), carded plainly by
4
+ // name (`catalogueTitleRow`): the API hosts no uploaded shard's images. Any failure (offline, a 404, no CORS, junk, a name that is
5
+ // not a name) gives no row, and the cell stays out as before.
6
+ import * as v from 'valibot';
7
+ import { Scope } from '@wildshard/engine/app/scope';
8
+ import { apiOrigin } from '@wildshard/engine/core/apiOrigin';
9
+ import { catalogueTitleRow, type TitleManifest } from '../shard/titleList';
10
+
11
+ /** At most this many entries are asked for in one boot: a file rarely adds more than one new slug at a time. */
12
+ export const CARD_LOOKUPS = 4;
13
+ /** The lookups' own deadline, inside the placement file's 3 s: a slow API never costs the cells the build already cards. */
14
+ export const CARD_DEADLINE_MS = 1500;
15
+ const NAME_CHARS = 80;
16
+ /** An entry is about 1.5 KB; anything past this is not one. */
17
+ const ENTRY_BYTES = 64 * 1024;
18
+ const EntrySchema = v.looseObject({ slug: v.string(), name: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(NAME_CHARS)) });
19
+
20
+ export interface CardPorts {
21
+ readonly fetch: typeof fetch;
22
+ /** The API's origin (`VITE_API_ORIGIN`, '' for the page's own). */
23
+ readonly api?: string;
24
+ readonly signal: AbortSignal;
25
+ /** The first new row's `order`: after the build's rows. */
26
+ readonly order: number;
27
+ readonly deadlineMs?: number;
28
+ }
29
+
30
+ /** One slug's catalogue row, or undefined for anything but an entry that names this slug. Never throws. */
31
+ async function catalogueCard(slug: string, order: number, ports: CardPorts): Promise<TitleManifest | undefined> {
32
+ try {
33
+ const url = `${ports.api ?? apiOrigin()}/api/catalogue/shards/${encodeURIComponent(slug)}`;
34
+ // called bare: a browser's `fetch` called as a method of another object throws Illegal invocation
35
+ const read = ports.fetch, response = await read(url, { cache: 'no-store', credentials: 'omit', redirect: 'error', signal: ports.signal });
36
+ if (!response.ok) { await response.body?.cancel(); return undefined; }
37
+ const text = await response.text();
38
+ if (text.length > ENTRY_BYTES) return undefined;
39
+ const entry = v.safeParse(EntrySchema, JSON.parse(text));
40
+ return entry.success && new Set([slug]).has(entry.output.slug) ? catalogueTitleRow(slug, entry.output.name, order) : undefined;
41
+ } catch { return undefined; }
42
+ }
43
+
44
+ /** The plain title rows of `slugs` the API's catalogue names, in their order; slugs it does not know are left out. */
45
+ export async function catalogueCards(slugs: readonly string[], ports: CardPorts): Promise<readonly TitleManifest[]> {
46
+ const asked = [...new Set(slugs)].slice(0, CARD_LOOKUPS);
47
+ const scope = new Scope('grid.placed-cards'), abort = new AbortController(), stop = (): void => { abort.abort(); };
48
+ try {
49
+ scope.timeout(ports.deadlineMs ?? CARD_DEADLINE_MS, stop);
50
+ if (ports.signal.aborted) stop(); else scope.listen(ports.signal, 'abort', stop);
51
+ const own = { ...ports, signal: abort.signal };
52
+ const rows = await Promise.all(asked.map((slug, n) => catalogueCard(slug, ports.order + n, own)));
53
+ return rows.filter(row => row !== undefined);
54
+ } finally { scope.dispose(); }
55
+ }
@@ -0,0 +1,233 @@
1
+ // SHARD-AUTHORING SA33 to SA35, the page half (meta SHARD-AUTHORING-PLAN): a released page (staging, production) learns the cells the API
2
+ // placed after its build, at runtime, from the same signed placement file the MMO reads (`releases/<channel>-placements.json`, SA33a).
3
+ // Its build bakes the pinned grid (`catalogue.json`, C3); the MMO's grid is that plus this file, so without it a placed shard had no
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
+ // SA35's preview bake believe it. A missing, late, unreadable or refused file keeps the build's grid: boot never waits past
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 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.
13
+ import * as v from 'valibot';
14
+ import { Scope } from '@wildshard/engine/app/scope';
15
+ import type { Json, jsonSlot } from '@wildshard/engine/saves/slots';
16
+ import { GRID_RADIUS } from '@wildshard/format/contentBounds';
17
+ import { PLACEMENT_PUBLIC_KEY, PlacementSchema, SignedPlacementSchema, placementsURL, type PlacementFile } from '../../../shared/game/grid/placementRows';
18
+ import { installCatalogue, installedCatalogue, type CatalogueDocument } from '../../../shared/game/grid/catalogueSlot';
19
+ import { findTitleManifest, installTitleManifests, titleManifests } from '../shard/titleList';
20
+ import { catalogueCards } from './placedCards';
21
+ import { installPlacedContent, placedContent, type PlacedContent } from './placedContent';
22
+ import { parseGridCatalogue } from '../../../shared/game/grid/catalogue';
23
+
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. */
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;
30
+
31
+ type Cell = PlacementFile['cells'][number];
32
+ const hexBytes = (hex: string): Uint8Array<ArrayBuffer> => Uint8Array.from(hex.match(/../gu) ?? [], pair => Number.parseInt(pair, 16));
33
+
34
+ /** The file's text as what it says: WebCrypto's Ed25519 under `publicKey` (SPKI DER in hex), then the box's own schema. It throws on a
35
+ * bad signature, before a byte of the body is believed, and where a browser has no Ed25519. */
36
+ export async function readSignedPlacement(text: string, publicKey: string = PLACEMENT_PUBLIC_KEY): Promise<PlacementFile> {
37
+ const signed = v.parse(SignedPlacementSchema, JSON.parse(text));
38
+ const key = await crypto.subtle.importKey('spki', hexBytes(publicKey), { name: 'Ed25519' }, false, ['verify']);
39
+ if (!await crypto.subtle.verify({ name: 'Ed25519' }, key, hexBytes(signed.signature), new TextEncoder().encode(signed.body))) throw new Error('A placement file has a bad signature');
40
+ return v.parse(PlacementSchema, JSON.parse(signed.body));
41
+ }
42
+
43
+ /** Where this page reads its placed cells: its world's channel's placement file, or null for a page with no world (preview bakes
44
+ * staging's cells at deploy, SA35; a solo build has none). `__WS_PLACEMENTS__`, a proof's own address, wins when set. */
45
+ export function placementsOf(scope: { readonly __WS_WORLD__?: unknown; readonly __WS_PLACEMENTS__?: unknown }): string | null {
46
+ if (typeof scope.__WS_PLACEMENTS__ === 'string') return scope.__WS_PLACEMENTS__;
47
+ const world = scope.__WS_WORLD__;
48
+ const release = typeof world === 'object' && world !== null && 'release' in world && typeof world.release === 'string' ? world.release : null;
49
+ return release === null ? null : placementsURL(release);
50
+ }
51
+
52
+ /** What adding a file's cells to a catalogue gave: the catalogue to install, the cells it took, and why any was left out. */
53
+ export interface Placed { readonly document: CatalogueDocument; readonly added: readonly Cell[]; readonly left: readonly string[] }
54
+ /**
55
+ * The catalogue with the file's cells after the build's own. A cell is left out as the MMO's `placeCell` (`gridCells.ts`) refuses it, rule
56
+ * for rule: an instance placed elsewhere, off the 7 × 7, a slug that already has a cell (or names a cell), an instance that is a placed
57
+ * shard's slug, a taken spot. A cell the build already places the same way is kept once. A slug this build has no card or product for
58
+ * (`known` false: an upload after the build the API's catalogue does not card, SA46) is left out too. `placed` names the slugs the file
59
+ * added, which Shard Select cards (`titleDeck.ts`).
60
+ */
61
+ export function addPlacedCells(document: CatalogueDocument, file: PlacementFile, known: (slug: string) => boolean = () => true): Placed {
62
+ const added: Cell[] = [], left: string[] = [];
63
+ const shards = new Map<string, string>(), cells = new Map<string, string>(), spots = new Map<string, string>();
64
+ for (const row of document.grid.cells as readonly Cell[]) { shards.set(row.instance, row.slug); cells.set(row.slug, row.instance); spots.set(row.cell.join(','), row.instance); }
65
+ for (const row of file.cells) {
66
+ const [x, z] = row.cell, spot = `${String(x)},${String(z)}`;
67
+ if (shards.has(row.instance) && cells.get(row.slug) === row.instance && spots.get(spot) === row.instance) continue;
68
+ const refused = shards.has(row.instance) ? `${row.instance} is already placed elsewhere`
69
+ : Math.abs(x) > GRID_RADIUS || Math.abs(z) > GRID_RADIUS ? 'off the 7 × 7'
70
+ : cells.has(row.slug) || shards.has(row.slug) ? `${row.slug} already has a cell`
71
+ : cells.has(row.instance) ? `${row.instance} is a placed shard's name`
72
+ : spots.has(spot) ? `${spot} is ${spots.get(spot) ?? ''}'s`
73
+ : known(row.slug) ? '' : `${row.slug} is not in this build`;
74
+ if (refused !== '') { left.push(`${row.instance} (${row.slug}) at (${spot}): ${refused}`); continue; }
75
+ shards.set(row.instance, row.slug); cells.set(row.slug, row.instance); spots.set(spot, row.instance);
76
+ added.push({ instance: row.instance, slug: row.slug, cell: [x, z] });
77
+ }
78
+ if (added.length === 0) return { document, added, left };
79
+ const grid = { ...document.grid, cells: [...document.grid.cells, ...added] };
80
+ // the grid's own admission (radius, unique spots and instances): a grid it refuses is never installed
81
+ parseGridCatalogue(grid);
82
+ return { document: { ...document, grid, placed: [...document.placed ?? [], ...added.map(row => row.slug)] }, added, left };
83
+ }
84
+
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
86
+ * from the API's catalogue (SA46). */
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
+ }
114
+ export interface PlacedPorts {
115
+ readonly fetch?: typeof fetch;
116
+ readonly publicKey?: string;
117
+ readonly deadlineMs?: number;
118
+ /** The page's own deadline: once it fires the boot has gone on, so a late answer installs nothing (the deck and the one way in read
119
+ * the grid once). */
120
+ readonly signal?: AbortSignal;
121
+ /** Whether this build cards a slug (default: it has a title row, `titleList.ts`). A slug it lacks may be carded from the API's
122
+ * catalogue (SA46); whether its product loads is the product's own question. */
123
+ readonly known?: (slug: string) => boolean;
124
+ /** The API origin a slug the build lacks is carded from (SA46, `placedCards.ts`; default `VITE_API_ORIGIN`). */
125
+ readonly api?: string;
126
+ /** The catalogue lookups' own deadline (`placedCards.ts` `CARD_DEADLINE_MS`). */
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;
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
+ };
144
+ /** After every row's `order`, so a carded shard is last in the deck. */
145
+ const nextOrder = (rows: readonly { readonly order?: number }[]): number => rows.reduce((top, row) => Math.max(top, row.order ?? 0), rows.length) + 1;
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
147
+ * grid and says why (a 404 is a channel the API has placed nothing on). */
148
+ export async function learnPlacedCells(url: string, ports: PlacedPorts = {}): Promise<PlacedRead> {
149
+ const scope = new Scope('grid.placed-cells');
150
+ try {
151
+ const document = installedCatalogue();
152
+ if (document === undefined) return { kept: 'no installed catalogue' };
153
+ // one signal for both deadlines, without `AbortSignal.any` (Safari 17.4): Safari 17's Ed25519 reads this file too
154
+ const abort = new AbortController(), stop = (): void => { abort.abort(); };
155
+ scope.timeout(ports.deadlineMs ?? PLACED_DEADLINE_MS, stop);
156
+ if (ports.signal?.aborted === true) stop(); else if (ports.signal !== undefined) scope.listen(ports.signal, 'abort', stop);
157
+ const channel = /\/releases\/(staging|production)-placements\.json$/u.exec(new URL(url).pathname)?.[1];
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
+ };
163
+ const known = ports.known ?? (slug => findTitleManifest(slug) !== undefined);
164
+ // the page's own deadline, read afresh after each wait: once it fires the boot has gone on
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)); }
200
+ const placed = addPlacedCells(document, file, known);
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);
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
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
213
+ const unknown = addPlacedCells(placed.document, file).added.map(cell => cell.slug);
214
+ const built = { added: placed.added, left: placed.left, serial: file.serial, carded: [] };
215
+ if (unknown.length === 0) return built;
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); });
225
+ if (cards.length === 0 || wentOn()) return built;
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));
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); }
229
+ if (more.added.length > 0) installCatalogue(more.document);
230
+ if (rows.length > 0) installTitleManifests([...titleManifests(), ...rows]);
231
+ return { added: [...placed.added, ...more.added], left: more.left, serial: file.serial, carded: rows.map(row => row.slug) };
232
+ } catch (error) { return { kept: error instanceof Error ? error.message : String(error) }; } finally { scope.dispose(); }
233
+ }
@@ -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 } = {};
@@ -445,6 +445,12 @@ export function createRegionalRuntimeFactory(ports: RegionalRuntimeFactoryPorts)
445
445
  performance.measure(name, { start: stage.endAt - stage.elapsedMs, end: stage.endAt, detail: { units: stage.units } });
446
446
  }
447
447
  restored = true;
448
+ // RP4: this cell's road variants (no PMREM), linked in play before the player can reach its edge
449
+ const warmRoad = async (): Promise<void> => {
450
+ try { await request.page.world.game.warmExteriorRoots(owner, [...view.root.children], () => !owner.disposed && !owner.disposing); }
451
+ catch (error: unknown) { if (!owner.disposed && !owner.disposing) console.warn('[grid] road variant warm-up stopped', error); }
452
+ };
453
+ void warmRoad();
448
454
  // js-heap H6 for a grid region, as the solo page's finish.ts does: the entry has built and warmed everything
449
455
  // its admitted transport fed, so keep none of it (Nalati's 45 MB of product files stayed in a Simulator
450
456
  // interior's JS heap, T10). A later read rechecks the immutable cache or the network, as a released tile does;
@@ -240,6 +240,12 @@ async function slicedTerrainGrid(run: (rows: () => number) => number, left: () =
240
240
 
241
241
  const regionLevel = ({ id, spawn }: LevelSpec): RegionLevel => ({ id, player: { at: { x: spawn.x, y: spawn.y ?? 0, z: spawn.z }, yaw: spawn.yaw } });
242
242
 
243
+ /** PZ22: install the shard's KTX2 table (once per manifest) before its texture policy resolves: Auto reads KTX2 from
244
+ * the registered table (gpuFiles.ts, DL17), so a choice made first stays on images for the resident's whole life. */
245
+ export function registerRegionalTextureTable(manifest: ShardManifest): Promise<void> {
246
+ return prepareShardAssets(manifest, registerGpuFiles);
247
+ }
248
+
243
249
  /** Resolve the existing texture policy once before memory admission. The resident enters this SAME policy for
244
250
  * asynchronous construction and each frame, so a capability-probe image fallback cannot retain a compressed claim. */
245
251
  export function resolveRegionalRuntimeTextures(manifest: Pick<ShardManifest, 'slug' | 'tiers' | 'runtimeCost'>, residents?: Parameters<typeof imagesFirstPlayingBytes>[1]): RegionalRuntimeTextures {
@@ -263,6 +269,8 @@ export function createRegionalWorldFoundation(ports: RegionalWorldPorts): (reque
263
269
  const level = ports.level === undefined ? toLevelSpec(hasDeclaredClientPage(request.admitted.source) ? { ...request.manifest, ground: clientPageGround(request.admitted.source, request.admitted.assets) } : request.manifest, product) : ports.level(request.manifest);
264
270
  const { slug: identity } = request.manifest;
265
271
  if (level.id !== identity) throw new Error('Regional level identity differs from its trusted manifest');
272
+ // PZ22: the table goes in before Auto resolves, and before the resident's scope exists to leak on a refusal
273
+ if (request.textures === undefined) await registerRegionalTextureTable(request.manifest);
266
274
  const resident = request.scope.child(`grid.world:${cell.instance}`), left = (): boolean => resident.disposed;
267
275
  const pausePoint = regionalBuildCheckpoint(resident, ports.pause);
268
276
  let pauses = clientPreparationBatch(identity, 'native.checkpoints', ['pause']);
@@ -280,7 +288,7 @@ export function createRegionalWorldFoundation(ports: RegionalWorldPorts): (reque
280
288
  let rendering: Promise<[PromiseSettledResult<void>]> | undefined;
281
289
  ownSceneTree(scene, resident, app.assets);
282
290
  try {
283
- await timeClientPreparation(identity, 'native.shard-assets', () => prepareShardAssets(request.manifest, registerGpuFiles));
291
+ await timeClientPreparation(identity, 'native.shard-assets', () => registerRegionalTextureTable(request.manifest));
284
292
  if (left()) throw new Error('Regional world left while registering its texture stand-ins');
285
293
  // M3 tiles-swap: the admitted product's reader for the resident runtime (a painter that binds its compiled tiles reads
286
294
  // it), handed over first: the level's declared navigation and a required manifest ground are that product's own files
@@ -534,7 +542,9 @@ export function createRegionalWorldFoundation(ports: RegionalWorldPorts): (reque
534
542
  // The world-only inventory can link while kit/play continue, with the exact destination sky and look.
535
543
  prepareWorldMaterials: async () => {
536
544
  await skyReady;
537
- if (!resident.disposed) regionLook?.sweep();
545
+ if (resident.disposed) return;
546
+ regionLook?.sweep();
547
+ LightPool.for(scene).adopt(scene);
538
548
  },
539
549
  precompileEnvironment: () => scene.environment,
540
550
  // rt3-crossing2: the look's per-frame sweep never ran on what the entered hooks added (no frame draws while they
@@ -543,6 +553,9 @@ export function createRegionalWorldFoundation(ports: RegionalWorldPorts): (reque
543
553
  await skyReady;
544
554
  if (resident.disposed) return;
545
555
  regionLook?.sweep();
556
+ // RP4: its content's own point lights (Sunscar's site and signal lights) show through the page's reserved lights,
557
+ // taken before the warm-up compiles, so showing the region never moves the page's light count
558
+ LightPool.for(scene).adopt(scene);
546
559
  // op-frame21: its own composite, once its world hook has run and before the warm-up compiles the page's passes
547
560
  const place = framePort?.composite;
548
561
  if (cellComposite !== null && place !== undefined && viewRoot !== null && !composited) {