@wildshard/engine 0.1.17 → 0.1.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (83) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/lint/engine-sides.json +7 -0
  3. package/lint/host-callback-syntax.mjs +2 -1
  4. package/lint/host-callbacks.mjs +3 -3
  5. package/lint/host-files.mjs +5 -4
  6. package/lint/no-base64.mjs +3 -1
  7. package/lint/shard-imports.mjs +6 -7
  8. package/lint/shard-source.d.mts +9 -0
  9. package/lint/shard-source.mjs +91 -0
  10. package/lint/shardfile-boundaries.mjs +10 -8
  11. package/lint/sim-closure.mjs +6 -3
  12. package/lint/wildshard-plugin.d.ts +4 -0
  13. package/lint/wildshard-plugin.js +22 -23
  14. package/package.json +9 -2
  15. package/scripts/app-build/outputProducts.d.mts +3 -0
  16. package/scripts/app-build/outputProducts.mjs +31 -0
  17. package/scripts/app-build-pipeline.mjs +3 -0
  18. package/scripts/check-devserver.mjs +1 -1
  19. package/scripts/chromium-keychain-check.mjs +4 -2
  20. package/scripts/chromium-keychain.mjs +3 -1
  21. package/scripts/cook.mjs +7 -3
  22. package/scripts/devices.d.mts +4 -0
  23. package/scripts/devices.mjs +39 -0
  24. package/scripts/devserver-client.d.mts +4 -2
  25. package/scripts/devserver-client.mjs +25 -8
  26. package/scripts/doctor-proof.mjs +1 -1
  27. package/scripts/e2e-faults.mjs +159 -0
  28. package/scripts/grid-crossing-walk-proof.mjs +14 -3
  29. package/scripts/memory-proof.mjs +158 -0
  30. package/scripts/offline-proof-rules.d.mts +4 -2
  31. package/scripts/offline-proof-rules.mjs +21 -5
  32. package/scripts/offline-proof.mjs +15 -6
  33. package/scripts/tier-textures-proof.mjs +101 -0
  34. package/scripts/tier-textures.mjs +60 -0
  35. package/scripts/tsconfig.json +1 -0
  36. package/scripts/vps/wildshard-config +79 -23
  37. package/scripts/worker-client-play.mjs +1 -0
  38. package/scripts/worker-client-proof.mjs +1 -1
  39. package/scripts/worker-client-slug.mjs +44 -0
  40. package/src/client/app/entry.ts +37 -10
  41. package/src/client/engine/boot/parsedPages.ts +127 -58
  42. package/src/client/engine/build.d.ts +2 -0
  43. package/src/client/engine/core/Game.ts +18 -0
  44. package/src/client/engine/core/bootstrap.ts +4 -1
  45. package/src/client/engine/debug/probe.ts +18 -1
  46. package/src/client/engine/fx/LightPool.ts +41 -1
  47. package/src/client/engine/pwa/sw.js +12 -3
  48. package/src/client/engine/render/precompile.ts +20 -14
  49. package/src/client/engine/telemetry/browserErrors.ts +4 -1
  50. package/src/client/engine/telemetry/deviceSnapshot.ts +155 -0
  51. package/src/client/game/boot/audio.generated.ts +0 -102
  52. package/src/client/game/boot/bytes.generated.ts +42 -60
  53. package/src/client/game/boot/versions.generated.ts +0 -2
  54. package/src/client/game/grid/area.ts +38 -0
  55. package/src/client/game/grid/live.ts +28 -2
  56. package/src/client/game/grid/liveSession.ts +14 -3
  57. package/src/client/game/grid/menu.ts +4 -0
  58. package/src/client/game/grid/neighbourPanels.ts +10 -1
  59. package/src/client/game/grid/placedCards.ts +55 -0
  60. package/src/client/game/grid/placedCells.ts +131 -0
  61. package/src/client/game/grid/regionalRuntime.ts +6 -0
  62. package/src/client/game/grid/regionalWorld.ts +15 -2
  63. package/src/client/game/grid/roadCull.ts +44 -14
  64. package/src/client/game/grid/roadTileBacking.ts +13 -3
  65. package/src/client/game/grid/session.ts +9 -0
  66. package/src/client/game/grid/shardfileFar.ts +9 -3
  67. package/src/client/game/session/finish.ts +5 -1
  68. package/src/client/game/shard/titleList.ts +6 -2
  69. package/src/client/game/shardfile/clientWorker.ts +2 -1
  70. package/src/client/game/titleDeck.ts +4 -3
  71. package/src/client/host/online/shell.ts +14 -0
  72. package/src/cook/game/shardCook.ts +38 -8
  73. package/src/cook/game/tierTextures.ts +276 -0
  74. package/src/e2e/smoke/game.ts +19 -14
  75. package/src/e2e/smoke/page-globals.d.ts +9 -8
  76. package/src/e2e/smoke/template2.spec.ts +8 -7
  77. package/src/server/host/dedicated/placementFile.ts +1 -17
  78. package/src/server/host/dedicated/socketTransport.ts +2 -1
  79. package/src/server/host/dedicated/world.ts +30 -1
  80. package/src/shared/engine/net/deviceWord.ts +138 -0
  81. package/src/shared/engine/net/socketFrames.ts +7 -4
  82. package/src/shared/game/grid/catalogueSlot.ts +7 -0
  83. package/src/shared/game/grid/placementRows.ts +33 -0
@@ -623,8 +623,6 @@ export const PUBLIC_BYTES = {
623
623
  "/assets/music/ember-forge/music.json": 6930,
624
624
  "/assets/music/ember-forge/take-a-5eb521de9407.m4a": 510990,
625
625
  "/assets/music/ember-forge/take-b-dd466a844ee8.m4a": 510690,
626
- "/assets/music/folk/island-tension-bb05ab64.m4a": 375569,
627
- "/assets/music/folk/pine-tension-180bc197.m4a": 604751,
628
626
  "/assets/music/fossil-badlands/music.json": 7285,
629
627
  "/assets/music/fossil-badlands/take-a-2cd52113f593.m4a": 344211,
630
628
  "/assets/music/fossil-badlands/take-b-16cddecab2a6.m4a": 251265,
@@ -670,41 +668,25 @@ export const PUBLIC_BYTES = {
670
668
  "/assets/music/nine-dragon-stack/sting-death-bf5c76c6.m4a": 55700,
671
669
  "/assets/music/nine-dragon-stack/sting-pickup-8516b7e3.m4a": 25276,
672
670
  "/assets/music/ob7-listening.html": 17104,
673
- "/assets/music/orchestral/island-tension-73116f36.m4a": 454133,
674
- "/assets/music/orchestral/pine-tension-525d8c6d.m4a": 370765,
675
671
  "/assets/music/patchwork-fairground/music.json": 7811,
676
672
  "/assets/music/patchwork-fairground/take-a-9218b66bf0b9.m4a": 588670,
677
673
  "/assets/music/patchwork-fairground/take-b-0e7f6f396f9d.m4a": 225472,
678
- "/assets/music/piano/island-calm-05125ed8.m4a": 710677,
679
- "/assets/music/piano/island-tension-7faf0468.m4a": 480309,
674
+ "/assets/music/piano/island-calm-05125ed8.m4a": 476617,
675
+ "/assets/music/piano/island-tension-7faf0468.m4a": 360423,
680
676
  "/assets/music/piano/music.json": 9500,
681
- "/assets/music/piano/pine-calm-923e0056.m4a": 753131,
682
- "/assets/music/piano/pine-tension-cc014e5b.m4a": 508407,
677
+ "/assets/music/piano/pine-calm-923e0056.m4a": 505088,
678
+ "/assets/music/piano/pine-tension-cc014e5b.m4a": 381939,
683
679
  "/assets/music/piano/sting-chunk-a4f2ffab.m4a": 43558,
684
680
  "/assets/music/piano/sting-death-99b071e0.m4a": 55748,
685
681
  "/assets/music/piano/sting-pickup-6ed91318.m4a": 25148,
686
682
  "/assets/music/piano/title-3d1f713a.m4a": 762019,
687
- "/assets/music/pine-hollow-folk/boss-base-1ad74736.m4a": 738051,
688
- "/assets/music/pine-hollow-folk/boss-bass-2f96accb.m4a": 500499,
689
- "/assets/music/pine-hollow-folk/boss-drums-90b1e7cb.m4a": 509133,
690
- "/assets/music/pine-hollow-folk/music.json": 7556,
691
- "/assets/music/pine-hollow-folk/night-calm-e5eeff22.m4a": 910920,
692
- "/assets/music/pine-hollow-folk/night-tension-0071c7a3.m4a": 615172,
693
- "/assets/music/pine-hollow-folk/sting-dawn-35a7550c.m4a": 98468,
694
- "/assets/music/pine-hollow-orchestral/boss-base-d7203ec0.m4a": 759114,
695
- "/assets/music/pine-hollow-orchestral/boss-bass-c368d6c3.m4a": 512459,
696
- "/assets/music/pine-hollow-orchestral/boss-drums-4c4efeb7.m4a": 512597,
697
- "/assets/music/pine-hollow-orchestral/music.json": 7582,
698
- "/assets/music/pine-hollow-orchestral/night-calm-da54e0eb.m4a": 537709,
699
- "/assets/music/pine-hollow-orchestral/night-tension-ba25e774.m4a": 362382,
700
- "/assets/music/pine-hollow-orchestral/sting-dawn-eafd4a6d.m4a": 98612,
701
- "/assets/music/pine-hollow-piano/boss-base-8b00b5cf.m4a": 662942,
702
- "/assets/music/pine-hollow-piano/boss-bass-0ff27574.m4a": 447388,
703
- "/assets/music/pine-hollow-piano/boss-drums-c4644a0b.m4a": 453178,
683
+ "/assets/music/pine-hollow-piano/boss-base-8b00b5cf.m4a": 444653,
684
+ "/assets/music/pine-hollow-piano/boss-bass-0ff27574.m4a": 336267,
685
+ "/assets/music/pine-hollow-piano/boss-drums-c4644a0b.m4a": 336267,
704
686
  "/assets/music/pine-hollow-piano/music.json": 7632,
705
- "/assets/music/pine-hollow-piano/night-calm-e935c4a1.m4a": 598252,
706
- "/assets/music/pine-hollow-piano/night-tension-48423068.m4a": 403828,
707
- "/assets/music/pine-hollow-piano/sting-dawn-6b0b4004.m4a": 98488,
687
+ "/assets/music/pine-hollow-piano/night-calm-e935c4a1.m4a": 402087,
688
+ "/assets/music/pine-hollow-piano/night-tension-48423068.m4a": 303663,
689
+ "/assets/music/pine-hollow-piano/sting-dawn-6b0b4004.m4a": 66830,
708
690
  "/assets/music/saltwind-lighthouse/music.json": 7271,
709
691
  "/assets/music/saltwind-lighthouse/take-a-d962afb1ace0.m4a": 74123,
710
692
  "/assets/music/saltwind-lighthouse/take-b-6533451204d4.m4a": 292105,
@@ -1089,7 +1071,7 @@ export const PUBLIC_BYTES = {
1089
1071
  "/assets/sfx/best/bear_roar-3-9f1e177e.m4a": 20975,
1090
1072
  "/assets/sfx/best/bed-camp-1-c7570b1a.m4a": 169592,
1091
1073
  "/assets/sfx/best/bed-coldwind-3-2fe1886b.m4a": 107538,
1092
- "/assets/sfx/best/bed-forest-2-0cd11be5.m4a": 340528,
1074
+ "/assets/sfx/best/bed-forest-2-0cd11be5.m4a": 145403,
1093
1075
  "/assets/sfx/best/bed-highwind-1-95937f84.m4a": 111758,
1094
1076
  "/assets/sfx/best/bed-meltwater-2-608d0e3b.m4a": 164196,
1095
1077
  "/assets/sfx/best/bed-rain-1-abadcece.m4a": 150665,
@@ -1252,22 +1234,22 @@ export const PUBLIC_BYTES = {
1252
1234
  "/assets/sfx/desert-ruin/ruins-west-f765ff652fd4.m4a": 79089,
1253
1235
  "/assets/sfx/desert-ruin/sfx.json": 16281,
1254
1236
  "/assets/sfx/desert-ruin/tents-south-66cdbaee8b50.m4a": 89283,
1255
- "/assets/sfx/driftwood-isle/bed-island-1-4611714d.m4a": 199372,
1256
- "/assets/sfx/driftwood-isle/coconut_hit-2-83ed831d.m4a": 1846,
1257
- "/assets/sfx/driftwood-isle/coconut_hit-3-9c8e8fd7.m4a": 4014,
1258
- "/assets/sfx/driftwood-isle/coconut_land-1-42389b0a.m4a": 11074,
1259
- "/assets/sfx/driftwood-isle/crab_click-2-aefbc41d.m4a": 12514,
1260
- "/assets/sfx/driftwood-isle/crab_click-3-f47e95a3.m4a": 10919,
1261
- "/assets/sfx/driftwood-isle/crab_snap-2-bff601ad.m4a": 2458,
1262
- "/assets/sfx/driftwood-isle/crab_snap-3-69ea11c0.m4a": 2356,
1263
- "/assets/sfx/driftwood-isle/gull-1-5fa9130b.m4a": 21764,
1264
- "/assets/sfx/driftwood-isle/hum-shrine-2-d89ed03a.m4a": 119020,
1265
- "/assets/sfx/driftwood-isle/monkey_chatter-3-1c7d7e2d.m4a": 21775,
1266
- "/assets/sfx/driftwood-isle/monkey_shriek-1-1a358b4e.m4a": 13651,
1267
- "/assets/sfx/driftwood-isle/monkey_shriek-2-54acd647.m4a": 10910,
1268
- "/assets/sfx/driftwood-isle/sailor_groan-2-43e2a981.m4a": 17041,
1269
- "/assets/sfx/driftwood-isle/sailor_slash-1-611ba654.m4a": 10429,
1270
- "/assets/sfx/driftwood-isle/sailor_slash-3-5a10eada.m4a": 5832,
1237
+ "/assets/sfx/driftwood-isle/bed-island-1-4611714d.m4a": 85380,
1238
+ "/assets/sfx/driftwood-isle/coconut_hit-2-83ed831d.m4a": 1606,
1239
+ "/assets/sfx/driftwood-isle/coconut_hit-3-9c8e8fd7.m4a": 2934,
1240
+ "/assets/sfx/driftwood-isle/coconut_land-1-42389b0a.m4a": 7360,
1241
+ "/assets/sfx/driftwood-isle/crab_click-2-aefbc41d.m4a": 8515,
1242
+ "/assets/sfx/driftwood-isle/crab_click-3-f47e95a3.m4a": 7520,
1243
+ "/assets/sfx/driftwood-isle/crab_snap-2-bff601ad.m4a": 1938,
1244
+ "/assets/sfx/driftwood-isle/crab_snap-3-69ea11c0.m4a": 1696,
1245
+ "/assets/sfx/driftwood-isle/gull-1-5fa9130b.m4a": 14111,
1246
+ "/assets/sfx/driftwood-isle/hum-shrine-2-d89ed03a.m4a": 51825,
1247
+ "/assets/sfx/driftwood-isle/monkey_chatter-3-1c7d7e2d.m4a": 14111,
1248
+ "/assets/sfx/driftwood-isle/monkey_shriek-1-1a358b4e.m4a": 9020,
1249
+ "/assets/sfx/driftwood-isle/monkey_shriek-2-54acd647.m4a": 7250,
1250
+ "/assets/sfx/driftwood-isle/sailor_groan-2-43e2a981.m4a": 11123,
1251
+ "/assets/sfx/driftwood-isle/sailor_slash-1-611ba654.m4a": 6918,
1252
+ "/assets/sfx/driftwood-isle/sailor_slash-3-5a10eada.m4a": 4064,
1271
1253
  "/assets/sfx/driftwood-isle/sfx.json": 10702,
1272
1254
  "/assets/sfx/ember-forge/ambience-04688340a792.m4a": 223003,
1273
1255
  "/assets/sfx/ember-forge/anvil-strikes-e3381c76f4ab.m4a": 53050,
@@ -1416,21 +1398,21 @@ export const PUBLIC_BYTES = {
1416
1398
  "/assets/sfx/patchwork-fairground/crowd-murmur-38a483e9e64c.m4a": 66451,
1417
1399
  "/assets/sfx/patchwork-fairground/sfx.json": 27500,
1418
1400
  "/assets/sfx/patchwork-fairground/wheel-creak-f120165f01a9.m4a": 50263,
1419
- "/assets/sfx/pine-hollow/bed-cabin-2-c2b7a02b.m4a": 159772,
1420
- "/assets/sfx/pine-hollow/bed-cave-1-9f212e8f.m4a": 148168,
1421
- "/assets/sfx/pine-hollow/bed-creek-1-e1414cd8.m4a": 174815,
1422
- "/assets/sfx/pine-hollow/bed-dawn-2-27bd5ac4.m4a": 156397,
1423
- "/assets/sfx/pine-hollow/bed-hollow-1-17c54253.m4a": 116306,
1424
- "/assets/sfx/pine-hollow/bed-mill-3-a20c4c53.m4a": 123993,
1425
- "/assets/sfx/pine-hollow/bed-night-1-bb291c08.m4a": 167207,
1426
- "/assets/sfx/pine-hollow/bed-nightfog-1-7e88dd54.m4a": 156879,
1427
- "/assets/sfx/pine-hollow/bed-oldgrowth-3-abf1ab68.m4a": 148157,
1428
- "/assets/sfx/pine-hollow/bed-pond-1-d085e52c.m4a": 181874,
1429
- "/assets/sfx/pine-hollow/bed-rain-canopy-3-b1ccc4c3.m4a": 156773,
1430
- "/assets/sfx/pine-hollow/bed-rain-open-1-6035278a.m4a": 130940,
1431
- "/assets/sfx/pine-hollow/bed-ridge-1-6aecf680.m4a": 116306,
1432
- "/assets/sfx/pine-hollow/bed-waterfall-1-02ff171d.m4a": 160955,
1433
- "/assets/sfx/pine-hollow/oneshots-362ce515.m4a": 1163597,
1401
+ "/assets/sfx/pine-hollow/bed-cabin-2-c2b7a02b.m4a": 101227,
1402
+ "/assets/sfx/pine-hollow/bed-cave-1-9f212e8f.m4a": 124335,
1403
+ "/assets/sfx/pine-hollow/bed-creek-1-e1414cd8.m4a": 110353,
1404
+ "/assets/sfx/pine-hollow/bed-dawn-2-27bd5ac4.m4a": 132230,
1405
+ "/assets/sfx/pine-hollow/bed-hollow-1-17c54253.m4a": 95783,
1406
+ "/assets/sfx/pine-hollow/bed-mill-3-a20c4c53.m4a": 79261,
1407
+ "/assets/sfx/pine-hollow/bed-night-1-bb291c08.m4a": 106186,
1408
+ "/assets/sfx/pine-hollow/bed-nightfog-1-7e88dd54.m4a": 99746,
1409
+ "/assets/sfx/pine-hollow/bed-oldgrowth-3-abf1ab68.m4a": 124335,
1410
+ "/assets/sfx/pine-hollow/bed-pond-1-d085e52c.m4a": 115260,
1411
+ "/assets/sfx/pine-hollow/bed-rain-canopy-3-b1ccc4c3.m4a": 99656,
1412
+ "/assets/sfx/pine-hollow/bed-rain-open-1-6035278a.m4a": 104858,
1413
+ "/assets/sfx/pine-hollow/bed-ridge-1-6aecf680.m4a": 95783,
1414
+ "/assets/sfx/pine-hollow/bed-waterfall-1-02ff171d.m4a": 102640,
1415
+ "/assets/sfx/pine-hollow/oneshots-362ce515.m4a": 830278,
1434
1416
  "/assets/sfx/pine-hollow/sfx.json": 79680,
1435
1417
  "/assets/sfx/saltwind-lighthouse/basin-gulls-33a2c0cccece.m4a": 89291,
1436
1418
  "/assets/sfx/saltwind-lighthouse/lighthouse-foghorn-195fbaedb647.m4a": 195955,
@@ -334,8 +334,6 @@ export const ASSET_VERSIONS: Readonly<Record<string, string>> = {
334
334
  "/assets/music/patchwork-fairground/take-a-9218b66bf0b9.m4a": '9218b66b',
335
335
  "/assets/music/patchwork-fairground/take-b-0e7f6f396f9d.m4a": '0e7f6f39',
336
336
  "/assets/music/piano/music.json": '61d975a8',
337
- "/assets/music/pine-hollow-folk/music.json": 'e85dd102',
338
- "/assets/music/pine-hollow-orchestral/music.json": '156fb297',
339
337
  "/assets/music/pine-hollow-piano/music.json": '64a1d36d',
340
338
  "/assets/music/saltwind-lighthouse/music.json": '044784de',
341
339
  "/assets/music/saltwind-lighthouse/take-a-d962afb1ace0.m4a": 'd962afb1',
@@ -0,0 +1,38 @@
1
+ /**
2
+ * T2E-1b (TEMPLATE-E2E): the area the test probe reports. A grid page's own level is the shell (`platform.grid`); the
3
+ * player stands in one of its cells, whose shard, door panels and quest flags are what a smoke asserts on. A one-shard
4
+ * page's area is its shard.
5
+ */
6
+ import type { ProbeArea, ProbeAreaTarget } from '@wildshard/engine/debug/probe';
7
+
8
+ /** What the grid lends the probe: the cell the player is in, the catalogue cells, and per cell its panels and flags. */
9
+ export interface GridAreaPorts {
10
+ /** the cell the page stands in; null on the road between cells */
11
+ readonly current: string | null;
12
+ readonly cells: readonly { readonly instance: string; readonly slug: string }[];
13
+ readonly targets: (instance: string) => readonly ProbeAreaTarget[];
14
+ readonly flags: (instance: string) => readonly string[];
15
+ }
16
+
17
+ /** The current grid cell as the probe's area; null on the road. */
18
+ export function gridArea(ports: GridAreaPorts): ProbeArea | null {
19
+ const cell = ports.cells.find(row => row.instance === ports.current);
20
+ if (cell === undefined) return null;
21
+ return { slug: cell.slug, instance: cell.instance, targets: ports.targets(cell.instance), flags: [...new Set(ports.flags(cell.instance))].sort() };
22
+ }
23
+
24
+ /** A one-shard page's area: its shard, the targets its shardfile client exposes (debug `shardfile`), and its flags. */
25
+ export function shardArea(slug: string, exposed: unknown, flags: readonly string[]): ProbeArea {
26
+ return { slug, instance: null, targets: exposedTargets(exposed), flags: [...new Set(flags)].sort() };
27
+ }
28
+
29
+ function isTarget(value: unknown): value is ProbeAreaTarget {
30
+ return typeof value === 'object' && value !== null && 'panel' in value && typeof value.panel === 'string'
31
+ && 'visible' in value && typeof value.visible === 'boolean' && 'solid' in value && typeof value.solid === 'boolean';
32
+ }
33
+
34
+ function exposedTargets(exposed: unknown): readonly ProbeAreaTarget[] {
35
+ if (typeof exposed !== 'object' || exposed === null || !('targets' in exposed) || typeof exposed.targets !== 'function') return [];
36
+ const rows: unknown = Reflect.apply(exposed.targets, exposed, []);
37
+ return Array.isArray(rows) ? rows.filter(isTarget).map(row => ({ panel: row.panel, visible: row.visible, solid: row.solid })) : [];
38
+ }
@@ -68,6 +68,9 @@ export interface LiveGridPorts {
68
68
  /** Metadata-only prefetch eligibility. Unsupported far proxies do not consume cold request slots; explicit transfers
69
69
  * still run normal admission and readiness. Absent: every cell is a candidate, as in standalone Node drivers. */
70
70
  prefetchable?: (cell: GridCell) => boolean;
71
+ /** GC5 / GC36 (J322: no hold at the line): on the road, build the world of the cell the traveller heads into, ahead of
72
+ * its line, so its entry finds it resident. Absent (standalone drivers): only actual entry builds a world (T7). */
73
+ buildAhead?: boolean;
71
74
  /** Product-only prefetch waits while this is false (T10: the page's spawn settle); required entry never waits. Absent: always. */
72
75
  backgroundReady?: () => boolean;
73
76
  bindFrame: (frame: LiveGridFrame) => void;
@@ -278,6 +281,9 @@ export class LiveGridHost {
278
281
  })();
279
282
  this.productRequests.set(instance, { work: request, required, trigger }); return request;
280
283
  }
284
+ /** GC5 / GC36: the cell whose world the road is building or built ahead of its line (`buildAhead`), kept until the
285
+ * traveller enters a cell or heads into another's mouth. */
286
+ private ahead: string | null = null;
281
287
  private tileApproach: { instance: string; tile: CellTile; controller: AbortController } | null = null;
282
288
  private transportApproach: { instance: string; controller: AbortController; work: Promise<void> } | null = null;
283
289
  private retiredTransport: Promise<void> = Promise.resolve();
@@ -460,7 +466,7 @@ export class LiveGridHost {
460
466
  || this.active !== null || destination !== undefined && destination !== last.instance)) this.forgetLastCell();
461
467
  let released = true;
462
468
  for (const [instance, resident] of this.residents) {
463
- const needed = instance === this.active || instance === destination || this.requests.has(instance) || resident.reservations > 0;
469
+ const needed = instance === this.active || instance === destination || instance === this.ahead || this.requests.has(instance) || resident.reservations > 0;
464
470
  resident.lease.update({ distance: this.distance(this.assembly.cell(instance)), needed: needed || resident.disposalFailed === true });
465
471
  if (needed || this.lastCell?.instance === instance) continue;
466
472
  if (resident.disposalFailed === true || resident.evicting || this.coldUnloadRefused.has(instance)) { released = false; continue; }
@@ -506,7 +512,9 @@ export class LiveGridHost {
506
512
  candidates.sort((a,b) => (this.candidateDistances.get(a) ?? Infinity) - (this.candidateDistances.get(b) ?? Infinity) || a.instance.localeCompare(b.instance));
507
513
  // Immutable products are selected by distance, without a whole-world count cap.
508
514
  const nearby = candidates;
509
- // The frame-transfer reservation protects an actual entry; inactive whole worlds retire in steps.
515
+ // The frame-transfer reservation protects an actual entry; inactive whole worlds retire in steps. A world built ahead
516
+ // (`buildAhead`) stays while the traveller is on the road and has not turned into another mouth (below).
517
+ if (this.active !== null) this.ahead = null;
510
518
  this.retireInactiveRegions();
511
519
  for (const cell of nearby) {
512
520
  const estimate = readinessModel(this.ports.readiness.bundle(cell), this.ports.readiness.link), distance = this.distance(cell, feet);
@@ -532,6 +540,10 @@ export class LiveGridHost {
532
540
  tileApproach.controller.abort(); this.tileApproach = null;
533
541
  }
534
542
  }
543
+ // The world built ahead goes once the traveller is a pitch from it, or heads from the road into another mouth (a stop
544
+ // keeps it). Checked while a build runs too, which the gate below skips.
545
+ if (this.ahead !== null && (this.distance(this.assembly.cell(this.ahead), feet) >= this.assembly.pitch
546
+ || moving !== undefined && moving.instance !== this.ahead && this.assembly.at(feet.x, feet.z) === undefined)) this.ahead = null;
535
547
  if (this.requests.size === 0) {
536
548
  const wallReach = 6 + this.ports.player.motor.opts.radius + 0.5 + this.ports.readiness.link.speed / 60;
537
549
  const departed = this.transitions.at(-1)?.from;
@@ -561,6 +573,18 @@ export class LiveGridHost {
561
573
  const named = moving ?? predicted, outsideSource = sourceDistance >= CHUNK_HALF;
562
574
  if (named !== undefined && outsideSource && !this.residents.has(named.instance) && !this.issues.has(named.instance)
563
575
  && this.distance(named, feet) < this.assembly.pitch) this.prepareApproachTransport(named);
576
+ // GC5 / GC36 (J322: no walls, no hold at the line): on the road, a traveller heading into a cell's mouth builds that
577
+ // cell's world now, not at the line. Built on demand there, the walk stood 2 to 5 s at the neighbour's closed edge
578
+ // while its world was made (2 to 4 s in Chromium). The entry's own preparation then finds it resident. The departed
579
+ // cell retires first, as the entry would retire it; a U-turn builds it again, as any entry does.
580
+ // Only from the road itself: past a cell's line (inside its square, before the 6 m entry) the heading names the cell
581
+ // beyond it, which would retire the world just built for the one underfoot.
582
+ if (this.ports.buildAhead === true && moving !== undefined && this.active === null && this.assembly.at(feet.x, feet.z) === undefined
583
+ && !this.residents.has(moving.instance) && !this.issues.has(moving.instance)
584
+ && this.distance(moving, feet) < this.assembly.pitch && this.retireInactiveRegions(moving.instance)) {
585
+ this.ahead = moving.instance;
586
+ void background(moving.instance, this.ensure(moving.instance), () => !this.disposed);
587
+ }
564
588
  if (approach !== undefined && this.ports.prepareNeighbour !== undefined && this.tileMetadata.has(approach.instance)
565
589
  && !this.residents.has(approach.instance) && !this.issues.has(approach.instance)
566
590
  && (this.active === null || moving === approach)
@@ -686,6 +710,8 @@ export class LiveGridHost {
686
710
  /** Prepare disabled replacement controllers while the existing page stays authoritative; no entered runtime hooks run here. */
687
711
  async prepare(from: string | null, to: string | null): Promise<PreparedGridCrossing> {
688
712
  if (this.disposed || this.active !== from || from === to) throw new Error('Stale live frame preparation');
713
+ // An entry anywhere but the world built ahead lets that world go, so it retires before this one allocates.
714
+ if (this.ahead !== to) this.ahead = null;
689
715
  if (from !== null && to !== null) throw new Error('Owned runtime crossing must commit onto the neutral road first');
690
716
  // Protect a ready return before yielding: expiry/pressure cannot free it
691
717
  // between its selection and the final prepared-frame reservation.
@@ -83,7 +83,7 @@ import { shardProductFromAdmission } from '../shardfile/runtimeProduct';
83
83
  import { createRegionalRuntimeFactory, regionalRuntimeAccountedBytes, type PreparedRegionalRuntime, type RegionalRuntimePage, type RegionalRuntimeTextures } from './regionalRuntime';
84
84
  import { bindHomeBuildCache } from '../shardfile/homeBuildCache';
85
85
  import type { ClientTileRegistration } from '../shardfile/tileContent';
86
- import { createRegionalWorldFoundation, hangCellDataSky, resolveRegionalRuntimeTextures } from './regionalWorld';
86
+ import { createRegionalWorldFoundation, hangCellDataSky, registerRegionalTextureTable, resolveRegionalRuntimeTextures } from './regionalWorld';
87
87
  import { regionalDataCellBytes } from './runtimeCost';
88
88
  import { resolveLevelBounds } from '../../../shared/game/shard/runtime';
89
89
  import { declaredPlayArea, type PlayArea } from '@wildshard/engine/game/shardfile/playArea';
@@ -170,6 +170,8 @@ export interface LiveGridWire {
170
170
  readonly rebound: (physics: Physics) => void;
171
171
  /** The server's creatures in the world the page stands in, for a cell whose creatures no manager holds. */
172
172
  readonly rows: NeighbourRegion;
173
+ /** Every quest flag the server says this player holds in the world the page stands in (T2E-1b, the probe's area). */
174
+ readonly flags?: () => readonly string[];
173
175
  }
174
176
  /** The readout: the live host's crossing telemetry, the crossing coordinator and the safe-zone state. */
175
177
  export interface LiveGridSessionState {
@@ -303,6 +305,7 @@ export class LiveGridSession {
303
305
  return { physics: ports.physics, walls: ports.walls, dispose: () => { highwayScope.dispose(); } };
304
306
  } },
305
307
  admit: (cell, required) => this.admit(cell, required),
308
+ buildAhead: true, // GC5 / GC36: the road builds the world ahead of its line
306
309
  prepareTransport: (cell, signal) => prepareApproachProductInputs(cell.slug, { allocator: ports.allocator, scope }, signal, assembly.local(traveller.position, cell)),
307
310
  ...(ports.prepareNeighbourTiles === undefined ? {} : { prepareNeighbour: ports.prepareNeighbourTiles }),
308
311
  prioritize: (cell) => prioritizeGridProduct(cell.slug, { allocator: ports.allocator, scope }),
@@ -730,7 +733,8 @@ export class LiveGridSession {
730
733
  const region = build();
731
734
  try {
732
735
  const feet = this.live.worldFeet();
733
- await this.ports.prepareDataTiles?.(cell, region.shell.scope, { x: feet.x - cell.origin.x, z: feet.z - cell.origin.z });
736
+ const inside = (offset: number): number => Math.max(-CHUNK_HALF, Math.min(CHUNK_HALF, offset));
737
+ await this.ports.prepareDataTiles?.(cell, region.shell.scope, { x: inside(feet.x - cell.origin.x), z: inside(feet.z - cell.origin.z) });
734
738
  return region;
735
739
  } catch (error) {
736
740
  try { region.dispose(); }
@@ -749,6 +753,9 @@ export class LiveGridSession {
749
753
  if (manifest === undefined || !dataPage && declaration === null) throw new GridCellWaitingError('Missing declared regional page owner');
750
754
  const page = this.page.runtimePage?.();
751
755
  if (page === undefined || page === null) throw new GridCellWaitingError('Regional page services are not ready');
756
+ // PZ22 (WILDSHARD-GAME-8G): Auto picks KTX2 only for a shard whose table is registered (DL17), so the table goes in
757
+ // before the one texture choice is made; resolved first, Driftwood read "no KTX2 set" and drew images on an iPhone.
758
+ if (choice.textures === undefined) await registerRegionalTextureTable(manifest);
752
759
  const textures = choice.textures ??= resolveRegionalRuntimeTextures(manifest, this.ports.allocator.cost().input), bytes = regionalRuntimeAccountedBytes(retained.admitted, manifest, textures.mode);
753
760
  const prepareEntry = async (): Promise<void> => {
754
761
  if (declaration === null) return;
@@ -783,7 +790,9 @@ export class LiveGridSession {
783
790
  try {
784
791
  if (cell.instance === this.ports.home.instance) bindHomeBuildCache(retained.admitted.source);
785
792
  const feet = this.live.worldFeet();
786
- const entryPoint = { x: feet.x - cell.origin.x, z: feet.z - cell.origin.z };
793
+ // A world built from the road (GC36) takes its entry at the cell's edge, the nearest point the feet will arrive at
794
+ const inside = (offset: number): number => Math.max(-CHUNK_HALF, Math.min(CHUNK_HALF, offset));
795
+ const entryPoint = { x: inside(feet.x - cell.origin.x), z: inside(feet.z - cell.origin.z) };
787
796
  prepared = await factory({ cell, admitted: retained.admitted, manifest, page, textures, allocator: this.ports.allocator, claim, scope: this.runtimeScope, entryPoint });
788
797
  }
789
798
  catch (error) { this.transferWalls.delete(cell.instance); throw error; }
@@ -986,6 +995,8 @@ export class LiveGridSession {
986
995
  const region = this.regions.get(instance);
987
996
  return region === undefined ? undefined : { colliders: region.colliders, field: name => this.wire?.site() === instance ? wirePage.row(name) : undefined };
988
997
  }
998
+ /** A cell's quest flags, as the server holds them: only where the wire stands. */
999
+ areaFlags(instance: string): readonly string[] { return this.wire?.site() === instance ? this.wire.flags?.() ?? [] : []; }
989
1000
  /** What draws a cell's life: the server's rows, which exist only where the page stands. */
990
1001
  lifeRegion(instance: string): NeighbourRegion | undefined { return this.wire?.site() === instance ? this.wire.rows : undefined; }
991
1002
 
@@ -2,6 +2,7 @@ import { isDev } from '@wildshard/engine/core/devMode';
2
2
  import type { GridMode } from '../../../shared/game/grid/catalogue';
3
3
 
4
4
  declare const __DEVSERVER__: boolean;
5
+ declare const __PREPARATION_ONLY__: boolean;
5
6
  /**
6
7
  * The main menu's two entries (SHARD-PLATFORM §3.3, G58, G61, SF21a): **Select a shard** (today's one-shard flow) and
7
8
  * **Infinite Wildshard** (the 5 × 5 grid). What each mode lets the player enter is the §3.3 table:
@@ -19,6 +20,9 @@ export const GRID_GATES_PASSED = false;
19
20
 
20
21
  /** The author's build-time switch (`vite build --mode devserver`, SF8c); a unit test's Node has no define, so false */
21
22
  export const DEVSERVER: boolean = typeof __DEVSERVER__ === 'boolean' && __DEVSERVER__;
23
+ /** SHARD-AUTHORING SA43: a production-renderer build made with `WILDSHARD_PREPARATION_ONLY=1` (never released:
24
+ * check-devserver refuses it), the client `wildshard prepare` serves with the author's draft inline */
25
+ export const PREPARATION_ONLY: boolean = typeof __PREPARATION_ONLY__ === 'boolean' && __PREPARATION_ONLY__;
22
26
 
23
27
  /** what the title is allowed to show and enter right now */
24
28
  export interface MenuMode { readonly developer: boolean; readonly devserver: boolean }
@@ -12,9 +12,10 @@ import type { Group, Object3D } from 'three';
12
12
  import type { ClientTileViews } from '../shardfile/clientViews';
13
13
  import type { Shardfile } from '@wildshard/format/shardSchema';
14
14
  import type { GridCell } from '../../../shared/game/grid/assembly';
15
+ import type { ProbeAreaTarget } from '@wildshard/engine/debug/probe';
15
16
 
16
17
  /** What the panels read of a cell the live host has admitted: the solids of its world, and a field's row where this page has one. */
17
- export interface PanelRegion { readonly colliders: ReadonlyMap<string, { readonly setActive: (active: boolean) => void }>; readonly field: (name: string) => number | undefined }
18
+ export interface PanelRegion { readonly colliders: ReadonlyMap<string, { readonly active: () => boolean; readonly setActive: (active: boolean) => void }>; readonly field: (name: string) => number | undefined }
18
19
  /** The page scope the panels live and die with (the views' own scope type). */
19
20
  type PageScope = Parameters<ClientTileViews['panels']>[3];
20
21
  export interface NeighbourPanelPorts {
@@ -73,6 +74,14 @@ export class NeighbourPanels {
73
74
  return new Map([...this.cells].map(([id, cell]) => [id, cell.bindings.map((b) => ({ panel: b.row.panel, visible: b.panel.visible }))]));
74
75
  }
75
76
 
77
+ /** A cell's door panels as the probe reads them (T2E-1b): drawn, and solid while every collider stands in its admitted
78
+ * region (a panel with no colliders reads solid, as `shardfile.targets()` does). */
79
+ targets(instance: string): readonly ProbeAreaTarget[] {
80
+ const cell = this.cells.get(instance), region = this.ports.region(instance);
81
+ return cell?.bindings.map(({ row, panel }) => ({ panel: row.panel, visible: panel.visible,
82
+ solid: region !== undefined && row.colliders.every(id => region.colliders.get(id)?.active() === true) })) ?? [];
83
+ }
84
+
76
85
  private sync(cell: CellPanels): void {
77
86
  const region = this.ports.region(cell.instance);
78
87
  for (const { row, panel, fallback } of cell.bindings) {
@@ -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,131 @@
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 page keeps an old file.
8
+ import * as v from 'valibot';
9
+ import { Scope } from '@wildshard/engine/app/scope';
10
+ import { GRID_RADIUS } from '@wildshard/format/contentBounds';
11
+ import { PLACEMENT_PUBLIC_KEY, PlacementSchema, SignedPlacementSchema, placementsURL, type PlacementFile } from '../../../shared/game/grid/placementRows';
12
+ import { installCatalogue, installedCatalogue, type CatalogueDocument } from '../../../shared/game/grid/catalogueSlot';
13
+ import { findTitleManifest, installTitleManifests, titleManifests } from '../shard/titleList';
14
+ import { catalogueCards } from './placedCards';
15
+ import { parseGridCatalogue } from '../../../shared/game/grid/catalogue';
16
+
17
+ /** 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
+ export const PLACED_DEADLINE_MS = 3000;
19
+
20
+ type Cell = PlacementFile['cells'][number];
21
+ const hexBytes = (hex: string): Uint8Array<ArrayBuffer> => Uint8Array.from(hex.match(/../gu) ?? [], pair => Number.parseInt(pair, 16));
22
+
23
+ /** 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
24
+ * bad signature, before a byte of the body is believed, and where a browser has no Ed25519. */
25
+ export async function readSignedPlacement(text: string, publicKey: string = PLACEMENT_PUBLIC_KEY): Promise<PlacementFile> {
26
+ const signed = v.parse(SignedPlacementSchema, JSON.parse(text));
27
+ const key = await crypto.subtle.importKey('spki', hexBytes(publicKey), { name: 'Ed25519' }, false, ['verify']);
28
+ 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');
29
+ return v.parse(PlacementSchema, JSON.parse(signed.body));
30
+ }
31
+
32
+ /** Where this page reads its placed cells: its world's channel's placement file, or null for a page with no world (preview bakes
33
+ * staging's cells at deploy, SA35; a solo build has none). `__WS_PLACEMENTS__`, a proof's own address, wins when set. */
34
+ export function placementsOf(scope: { readonly __WS_WORLD__?: unknown; readonly __WS_PLACEMENTS__?: unknown }): string | null {
35
+ if (typeof scope.__WS_PLACEMENTS__ === 'string') return scope.__WS_PLACEMENTS__;
36
+ const world = scope.__WS_WORLD__;
37
+ const release = typeof world === 'object' && world !== null && 'release' in world && typeof world.release === 'string' ? world.release : null;
38
+ return release === null ? null : placementsURL(release);
39
+ }
40
+
41
+ /** What adding a file's cells to a catalogue gave: the catalogue to install, the cells it took, and why any was left out. */
42
+ export interface Placed { readonly document: CatalogueDocument; readonly added: readonly Cell[]; readonly left: readonly string[] }
43
+ /**
44
+ * 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
45
+ * 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
46
+ * 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
47
+ * (`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
48
+ * added, which Shard Select cards (`titleDeck.ts`).
49
+ */
50
+ export function addPlacedCells(document: CatalogueDocument, file: PlacementFile, known: (slug: string) => boolean = () => true): Placed {
51
+ const added: Cell[] = [], left: string[] = [];
52
+ const shards = new Map<string, string>(), cells = new Map<string, string>(), spots = new Map<string, string>();
53
+ 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); }
54
+ for (const row of file.cells) {
55
+ const [x, z] = row.cell, spot = `${String(x)},${String(z)}`;
56
+ if (shards.has(row.instance) && cells.get(row.slug) === row.instance && spots.get(spot) === row.instance) continue;
57
+ const refused = shards.has(row.instance) ? `${row.instance} is already placed elsewhere`
58
+ : Math.abs(x) > GRID_RADIUS || Math.abs(z) > GRID_RADIUS ? 'off the 7 × 7'
59
+ : cells.has(row.slug) || shards.has(row.slug) ? `${row.slug} already has a cell`
60
+ : cells.has(row.instance) ? `${row.instance} is a placed shard's name`
61
+ : spots.has(spot) ? `${spot} is ${spots.get(spot) ?? ''}'s`
62
+ : known(row.slug) ? '' : `${row.slug} is not in this build`;
63
+ if (refused !== '') { left.push(`${row.instance} (${row.slug}) at (${spot}): ${refused}`); continue; }
64
+ shards.set(row.instance, row.slug); cells.set(row.slug, row.instance); spots.set(spot, row.instance);
65
+ added.push({ instance: row.instance, slug: row.slug, cell: [x, z] });
66
+ }
67
+ if (added.length === 0) return { document, added, left };
68
+ const grid = { ...document.grid, cells: [...document.grid.cells, ...added] };
69
+ // the grid's own admission (radius, unique spots and instances): a grid it refuses is never installed
70
+ parseGridCatalogue(grid);
71
+ return { document: { ...document, grid, placed: [...document.placed ?? [], ...added.map(row => row.slug)] }, added, left };
72
+ }
73
+
74
+ /** 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
+ * 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 };
77
+ export interface PlacedPorts {
78
+ readonly fetch?: typeof fetch;
79
+ readonly publicKey?: string;
80
+ readonly deadlineMs?: number;
81
+ /** 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
82
+ * the grid once). */
83
+ readonly signal?: AbortSignal;
84
+ /** 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
85
+ * catalogue (SA46); whether its product loads is the product's own question. */
86
+ readonly known?: (slug: string) => boolean;
87
+ /** The API origin a slug the build lacks is carded from (SA46, `placedCards.ts`; default `VITE_API_ORIGIN`). */
88
+ readonly api?: string;
89
+ /** The catalogue lookups' own deadline (`placedCards.ts` `CARD_DEADLINE_MS`). */
90
+ readonly cardDeadlineMs?: number;
91
+ }
92
+ /** After every row's `order`, so a carded shard is last in the deck. */
93
+ const nextOrder = (rows: readonly { readonly order?: number }[]): number => rows.reduce((top, row) => Math.max(top, row.order ?? 0), rows.length) + 1;
94
+ /** 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
95
+ * grid and says why (a 404 is a channel the API has placed nothing on). */
96
+ export async function learnPlacedCells(url: string, ports: PlacedPorts = {}): Promise<PlacedRead> {
97
+ const scope = new Scope('grid.placed-cells');
98
+ try {
99
+ const document = installedCatalogue();
100
+ if (document === undefined) return { kept: 'no installed catalogue' };
101
+ // one signal for both deadlines, without `AbortSignal.any` (Safari 17.4): Safari 17's Ed25519 reads this file too
102
+ const abort = new AbortController(), stop = (): void => { abort.abort(); };
103
+ scope.timeout(ports.deadlineMs ?? PLACED_DEADLINE_MS, stop);
104
+ 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
+ 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` };
111
+ const known = ports.known ?? (slug => findTitleManifest(slug) !== undefined);
112
+ // the page's own deadline, read afresh after each wait: once it fires the boot has gone on
113
+ const wentOn = (): boolean => ports.signal?.aborted === true;
114
+ 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);
117
+ // 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
+ // 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
+ const unknown = addPlacedCells(placed.document, file).added.map(cell => cell.slug);
120
+ const built = { added: placed.added, left: placed.left, serial: file.serial, carded: [] };
121
+ 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 }) });
124
+ 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));
126
+ const opened = new Set(more.added.map(cell => cell.slug)), rows = cards.filter(row => opened.has(row.slug));
127
+ if (more.added.length > 0) installCatalogue(more.document);
128
+ if (rows.length > 0) installTitleManifests([...titleManifests(), ...rows]);
129
+ return { added: [...placed.added, ...more.added], left: more.left, serial: file.serial, carded: rows.map(row => row.slug) };
130
+ } catch (error) { return { kept: error instanceof Error ? error.message : String(error) }; } finally { scope.dispose(); }
131
+ }
@@ -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;