@wildshard/engine 0.1.15 → 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 (262) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/index.html +157 -11
  3. package/lint/engine-sides.json +23 -0
  4. package/lint/host-callback-syntax.mjs +2 -1
  5. package/lint/host-callbacks.mjs +3 -3
  6. package/lint/host-files.mjs +5 -4
  7. package/lint/host-register.json +496 -0
  8. package/lint/no-base64.mjs +3 -1
  9. package/lint/ratchet.json +2 -2
  10. package/lint/shard-imports.d.mts +1 -0
  11. package/lint/shard-imports.mjs +60 -13
  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 +44 -27
  18. package/package.json +24 -6
  19. package/scripts/app-build/buildIdentity.d.mts +3 -1
  20. package/scripts/app-build/buildIdentity.mjs +25 -5
  21. package/scripts/app-build/builtAt.d.mts +4 -0
  22. package/scripts/app-build/builtAt.mjs +21 -0
  23. package/scripts/app-build/outputProducts.d.mts +3 -0
  24. package/scripts/app-build/outputProducts.mjs +31 -0
  25. package/scripts/app-build/serviceWorker.ts +16 -2
  26. package/scripts/app-build/versionFiles.ts +2 -1
  27. package/scripts/app-build-pipeline.mjs +7 -1
  28. package/scripts/audio-download-proof.mjs +843 -0
  29. package/scripts/build-app.mjs +4 -0
  30. package/scripts/build-mirror.d.mts +2 -0
  31. package/scripts/build-mirror.mjs +5 -4
  32. package/scripts/built-product.mjs +3 -3
  33. package/scripts/cell-mem/metrics-preload.mjs +65 -0
  34. package/scripts/cell-mem-bench.mjs +130 -0
  35. package/scripts/check-chunks.mjs +2 -1
  36. package/scripts/check-devserver.mjs +1 -1
  37. package/scripts/chromium-keychain-check.mjs +4 -2
  38. package/scripts/chromium-keychain.mjs +3 -1
  39. package/scripts/cook.mjs +7 -3
  40. package/scripts/devices.d.mts +4 -0
  41. package/scripts/devices.mjs +39 -0
  42. package/scripts/devserver-client.d.mts +7 -0
  43. package/scripts/devserver-client.mjs +85 -0
  44. package/scripts/doctor-proof.mjs +1 -1
  45. package/scripts/e2e-faults.mjs +159 -0
  46. package/scripts/engine-ci-budget.ts +7 -1
  47. package/scripts/format-lock.mjs +20 -11
  48. package/scripts/generate-title-launch.mjs +3 -2
  49. package/scripts/grid-crossing-walk-proof.mjs +30 -11
  50. package/scripts/heavy-lane.py +25 -1
  51. package/scripts/host-ruler/register-migrate.mjs +242 -0
  52. package/scripts/host-ruler/register.d.mts +36 -0
  53. package/scripts/host-ruler/register.mjs +116 -0
  54. package/scripts/host-ruler/roots.d.mts +29 -0
  55. package/scripts/host-ruler/roots.mjs +333 -0
  56. package/scripts/host-ruler/server-roots.d.mts +23 -0
  57. package/scripts/host-ruler/server-roots.mjs +272 -0
  58. package/scripts/main-watch.d.mts +1 -1
  59. package/scripts/main-watch.mjs +10 -6
  60. package/scripts/map-hash.mjs +3 -6
  61. package/scripts/memory-proof.mjs +158 -0
  62. package/scripts/mmo-bots.mjs +2 -2
  63. package/scripts/offline-proof-rules.d.mts +5 -2
  64. package/scripts/offline-proof-rules.mjs +43 -6
  65. package/scripts/offline-proof.mjs +15 -6
  66. package/scripts/online-rig.mjs +4 -4
  67. package/scripts/page-release/flow.d.mts +1 -0
  68. package/scripts/page-release/flow.mjs +6 -2
  69. package/scripts/page-release.mjs +5 -1
  70. package/scripts/physics-route.json +0 -71
  71. package/scripts/pins-catalogue.ts +103 -0
  72. package/scripts/pins-reuse.mjs +3 -1
  73. package/scripts/pins.ts +22 -14
  74. package/scripts/preview-grid.ts +203 -0
  75. package/scripts/road-preload-proof.mjs +167 -0
  76. package/scripts/server-release/publish.mjs +2 -2
  77. package/scripts/server-release/served-slug.d.mts +2 -0
  78. package/scripts/server-release/served-slug.mjs +10 -0
  79. package/scripts/server-release/sign.d.mts +1 -0
  80. package/scripts/server-release/sign.mjs +3 -7
  81. package/scripts/shard-components.mjs +0 -2
  82. package/scripts/shard-outputs.d.mts +8 -0
  83. package/scripts/shard-outputs.mjs +45 -11
  84. package/scripts/side-parity.d.mts +2 -1
  85. package/scripts/side-parity.mjs +25 -4
  86. package/scripts/test-amber.d.mts +1 -0
  87. package/scripts/test-amber.mjs +10 -0
  88. package/scripts/test-products.json +3 -3
  89. package/scripts/tier-textures-proof.mjs +101 -0
  90. package/scripts/tier-textures.mjs +60 -0
  91. package/scripts/tracked-public.d.mts +1 -0
  92. package/scripts/tracked-public.mjs +17 -0
  93. package/scripts/tsconfig.json +1 -0
  94. package/scripts/vps/wildshard-config +79 -23
  95. package/scripts/worker-client-play.mjs +1 -0
  96. package/scripts/worker-client-proof.mjs +1 -1
  97. package/scripts/worker-client-slug.mjs +44 -0
  98. package/src/cli/engine.mjs +8 -0
  99. package/src/client/app/bootRoute.ts +4 -1
  100. package/src/client/app/dropModal.ts +15 -2
  101. package/src/client/app/entry.ts +96 -13
  102. package/src/client/app/slugPath.ts +5 -0
  103. package/src/client/engine/audio/Audio.ts +20 -2
  104. package/src/client/engine/boot/bakedTextures.ts +3 -2
  105. package/src/client/engine/boot/bootTrace.ts +6 -1
  106. package/src/client/engine/boot/bytes.ts +4 -3
  107. package/src/client/engine/boot/clearDownloads.ts +1 -1
  108. package/src/client/engine/boot/contentRead.ts +4 -0
  109. package/src/client/engine/boot/dropNotice.ts +20 -6
  110. package/src/client/engine/boot/gpuFiles.ts +25 -2
  111. package/src/client/engine/boot/lastEnd.ts +8 -2
  112. package/src/client/engine/boot/parsedPages.ts +127 -58
  113. package/src/client/engine/boot/shardPrefetch.ts +7 -1
  114. package/src/client/engine/boot/sw.ts +19 -0
  115. package/src/client/engine/build.d.ts +2 -0
  116. package/src/client/engine/core/Game.ts +29 -3
  117. package/src/client/engine/core/GpuRecovery.ts +7 -0
  118. package/src/client/engine/core/Volumetrics.ts +5 -0
  119. package/src/client/engine/core/assets.ts +27 -20
  120. package/src/client/engine/core/bootstrap.ts +5 -3
  121. package/src/client/engine/core/ktx2.ts +84 -11
  122. package/src/client/engine/debug/probe.ts +18 -1
  123. package/src/client/engine/explore/Compare.ts +2 -2
  124. package/src/client/engine/explore/TouchFly.ts +3 -5
  125. package/src/client/engine/fx/LightPool.ts +41 -1
  126. package/src/client/engine/input/dom.ts +12 -0
  127. package/src/client/engine/net/predictor.ts +6 -2
  128. package/src/client/engine/player/Player.ts +10 -2
  129. package/src/client/engine/player/TouchControls.ts +12 -4
  130. package/src/client/engine/pwa/sw.js +59 -11
  131. package/src/client/engine/render/drawCheck.ts +96 -0
  132. package/src/client/engine/render/precompile.ts +20 -14
  133. package/src/client/engine/saves/staleBuildNote.ts +46 -0
  134. package/src/client/engine/telemetry/browserErrors.ts +161 -21
  135. package/src/client/engine/telemetry/deviceSnapshot.ts +155 -0
  136. package/src/client/engine/telemetry/screenOutbox.ts +61 -0
  137. package/src/client/engine/telemetry/staleBuildReport.ts +12 -0
  138. package/src/client/engine/ui/DeathFade.ts +99 -11
  139. package/src/client/engine/ui/ErrorModal.ts +13 -6
  140. package/src/client/engine/ui/Feedback.ts +2 -1
  141. package/src/client/engine/ui/Loading.ts +10 -6
  142. package/src/client/engine/ui/Map.ts +2 -1
  143. package/src/client/engine/ui/WeaponStrip.ts +2 -1
  144. package/src/client/engine/ui/backGuard.ts +104 -0
  145. package/src/client/engine/ui/hudAdapters.ts +30 -4
  146. package/src/client/engine/ui/loading.css +17 -0
  147. package/src/client/engine/ui/namePrompt.ts +6 -5
  148. package/src/client/engine/ui/styles/combat.css +12 -0
  149. package/src/client/engine/ui/styles/namePrompt.css +4 -2
  150. package/src/client/game/boot/audio.generated.ts +0 -396
  151. package/src/client/game/boot/bytes.generated.ts +42 -71
  152. package/src/client/game/boot/versions.generated.ts +0 -13
  153. package/src/client/game/compendium/keepsakes.ts +16 -6
  154. package/src/client/game/grapple/tool.ts +10 -7
  155. package/src/client/game/grid/area.ts +38 -0
  156. package/src/client/game/grid/cellLoading.ts +23 -12
  157. package/src/client/game/grid/cellScreens.ts +39 -74
  158. package/src/client/game/grid/live.ts +28 -2
  159. package/src/client/game/grid/liveSession.ts +54 -10
  160. package/src/client/game/grid/menu.ts +4 -0
  161. package/src/client/game/grid/nearPlaceholderPlan.ts +8 -0
  162. package/src/client/game/grid/nearPlaceholderView.ts +9 -3
  163. package/src/client/game/grid/neighbourPanels.ts +10 -1
  164. package/src/client/game/grid/oneWayIn.ts +92 -27
  165. package/src/client/game/grid/pageEntry.ts +19 -0
  166. package/src/client/game/grid/pageShell.ts +1 -1
  167. package/src/client/game/grid/placedCards.ts +55 -0
  168. package/src/client/game/grid/placedCells.ts +131 -0
  169. package/src/client/game/grid/plotAudio.ts +114 -0
  170. package/src/client/game/grid/products.ts +55 -5
  171. package/src/client/game/grid/regionalRuntime.ts +6 -0
  172. package/src/client/game/grid/regionalWorld.ts +15 -2
  173. package/src/client/game/grid/roadCull.ts +44 -14
  174. package/src/client/game/grid/roadLookPlatform.ts +2 -2
  175. package/src/client/game/grid/roadTileBacking.ts +13 -3
  176. package/src/client/game/grid/session.ts +47 -22
  177. package/src/client/game/grid/shardfileFar.ts +9 -3
  178. package/src/client/game/grid/spawnGround.ts +68 -0
  179. package/src/client/game/grid/voidLook.ts +29 -23
  180. package/src/client/game/loot/runtime.ts +3 -1
  181. package/src/client/game/mainMenu.ts +14 -6
  182. package/src/client/game/riding/hud.ts +6 -4
  183. package/src/client/game/session/finish.ts +22 -4
  184. package/src/client/game/session/play.ts +8 -2
  185. package/src/client/game/session/session.ts +4 -1
  186. package/src/client/game/shard/titleList.ts +6 -2
  187. package/src/client/game/shardfile/clientWorker.ts +43 -13
  188. package/src/client/game/shardfile/serverRoute.ts +10 -22
  189. package/src/client/game/slugPage.css +11 -0
  190. package/src/client/game/slugPage.ts +84 -0
  191. package/src/client/game/systems/viewmodel/heldView.ts +6 -3
  192. package/src/client/game/titleDeck.ts +56 -32
  193. package/src/client/host/online/doctor.ts +7 -6
  194. package/src/client/host/online/linkScreens.ts +16 -0
  195. package/src/client/host/online/release.ts +51 -5
  196. package/src/client/host/online/shell.ts +62 -27
  197. package/src/client/host/standalone/shell.ts +7 -3
  198. package/src/cook/game/audioReport.ts +57 -0
  199. package/src/cook/game/entryTotals.ts +26 -6
  200. package/src/cook/game/installedRuntimeReads.ts +3 -0
  201. package/src/cook/game/shardCook.ts +38 -8
  202. package/src/cook/game/tierTextures.ts +276 -0
  203. package/src/e2e/smoke/game.ts +19 -14
  204. package/src/e2e/smoke/page-globals.d.ts +9 -8
  205. package/src/e2e/smoke/template2.spec.ts +8 -7
  206. package/src/server/engine/sim/respawn.ts +6 -1
  207. package/src/server/engine/sim.ts +3 -0
  208. package/src/server/game/grid/simulation.ts +35 -0
  209. package/src/server/game/loot/harvest.ts +2 -0
  210. package/src/server/game/loot/keepsakeProgression.ts +40 -0
  211. package/src/server/game/loot/playerOwned.ts +5 -1
  212. package/src/server/game/plugin/simulation.ts +4 -0
  213. package/src/server/game/population/nativeBake.ts +2 -1
  214. package/src/server/game/quest/chapterRecords.ts +2 -0
  215. package/src/server/game/quest/serverChapters.ts +4 -0
  216. package/src/server/game/quest/serverDoors.ts +11 -5
  217. package/src/server/game/roomRespawn.ts +4 -0
  218. package/src/server/game/shardfile/installedSides.ts +18 -0
  219. package/src/server/game/shardfile/nativeAssemblyHosts.ts +19 -10
  220. package/src/server/game/shardfile/nativeAssemblyInput.ts +1 -4
  221. package/src/server/host/bake/headlessWorker.ts +5 -1
  222. package/src/server/host/dedicated/cellHost.ts +98 -29
  223. package/src/server/host/dedicated/cellProtocol.ts +11 -1
  224. package/src/server/host/dedicated/cellWorker.ts +9 -3
  225. package/src/server/host/dedicated/crossing.ts +6 -2
  226. package/src/server/host/dedicated/dedicatedRoom.ts +21 -8
  227. package/src/server/host/dedicated/gridCells.ts +52 -9
  228. package/src/server/host/dedicated/main.ts +31 -12
  229. package/src/server/host/dedicated/placementFile.ts +56 -0
  230. package/src/server/host/dedicated/releaseFile.ts +17 -10
  231. package/src/server/host/dedicated/roadRoom.ts +21 -5
  232. package/src/server/host/dedicated/socketTransport.ts +2 -1
  233. package/src/server/host/dedicated/workerTable.ts +13 -1
  234. package/src/server/host/dedicated/world.ts +111 -10
  235. package/src/server/host/headlessRuntime.ts +10 -5
  236. package/src/server/host/installers.ts +62 -0
  237. package/src/server/host/openWorld.ts +59 -0
  238. package/src/server/host/ropeDecks.ts +2 -0
  239. package/src/server/host/standalone/cellWorld.ts +25 -19
  240. package/src/server/host/standalone/fallFloor.ts +2 -2
  241. package/src/server/host/standalone/gridServer.ts +7 -4
  242. package/src/server/host/standalone/roadWorld.ts +41 -4
  243. package/src/shared/engine/audio/bootAudio.ts +33 -0
  244. package/src/shared/engine/level/spec.ts +3 -3
  245. package/src/shared/engine/net/acts.ts +3 -0
  246. package/src/shared/engine/net/deviceWord.ts +138 -0
  247. package/src/shared/engine/net/socketFrames.ts +7 -4
  248. package/src/shared/engine/physics/query.ts +27 -0
  249. package/src/shared/engine/physics/terrain.ts +19 -28
  250. package/src/shared/engine/saves/saves.lock.json +15 -0
  251. package/src/shared/engine/sim/actRoutes.ts +2 -0
  252. package/src/shared/game/compendium/keepsakeProgression.ts +24 -0
  253. package/src/shared/game/grid/catalogue.ts +12 -5
  254. package/src/shared/game/grid/catalogueSlot.ts +18 -0
  255. package/src/shared/game/grid/farProxy.ts +6 -5
  256. package/src/shared/game/grid/pageMode.ts +1 -1
  257. package/src/shared/game/grid/placementRows.ts +33 -0
  258. package/src/shared/game/grid/roadLayout.ts +26 -3
  259. package/src/shared/game/grid/singleplayer.json +0 -13
  260. package/src/shared/game/grid/voidFloor.ts +122 -0
  261. package/src/shared/game/strings.ts +15 -0
  262. package/src/shared/host/standalone/netInput.ts +2 -1
@@ -17,6 +17,8 @@ import { isOwnedId, isCosmetic, type Owned } from '../../../shared/game/loot/Own
17
17
  import { wirePage } from '../shardfile/wirePage';
18
18
  import { rollLoot } from '../loot/tables';
19
19
  import { onCreatureDeath } from '../../../shared/game/loot/deaths';
20
+ import { progressionState, takeKeepsake, type KeepsakeRoom } from '../../../shared/game/compendium/keepsakeProgression';
21
+ import { OWNED_ROW, WORN_LINE } from '../../../shared/game/loot/ownedRows';
20
22
  import type { DeclaredLootEconomy } from '../../../shared/game/shard/declaredRows';
21
23
  import type { ShardContext } from '../plugin/context';
22
24
  import type { CollectionCatalogue, CollectionDisplay, CollectionParams } from '../models/collectionDisplay';
@@ -54,13 +56,19 @@ export function installCollectionKeepsakes<A extends { kind: string; variant?: s
54
56
  } {
55
57
  const { owned, progression, flags, rows } = h, scope = h.owner?.scope, view = keepsakeView(h);
56
58
  const pending: { text: string; at: number }[] = [];
59
+ // SERVER-PARITY HS4: in a room the server's book holds the keepsakes (SS3b pays the charms off the same flags, personal loot
60
+ // files the trophies), and this page only mirrors it: it grants nothing, and tells each reward once, past the world's first frame.
61
+ const room = (): KeepsakeRoom | null => wirePage.client === null ? null
62
+ : { worn: id => wirePage.line(`${OWNED_ROW.owned}${id}`) === WORN_LINE, wear: id => { wirePage.wear(id); } };
63
+ const told = new Set<string>();
57
64
  let clock = 0;
58
65
  const sync = (announce: boolean): void => {
59
- const state = progression.states[progression.flags.filter(flag => flags.has(flag)).length];
60
- if (state === undefined) throw new Error('Missing admitted reward state');
66
+ const state = progressionState(progression, flag => flags.has(flag)), online = room() !== null;
61
67
  view.chime?.setCount(state.displayCount);
62
68
  for (const reward of state.earned) {
63
- if (!owned.grant(reward.id) || !announce) continue;
69
+ const fresh = online ? !told.has(reward.id) : owned.grant(reward.id);
70
+ told.add(reward.id);
71
+ if (!fresh || !announce || online && !wirePage.settled) continue;
64
72
  const last = pending[pending.length - 1]?.at ?? -Infinity;
65
73
  pending.push({ text: reward.text, at: Math.max(clock + rows.delay, last + rows.spacing) });
66
74
  }
@@ -78,7 +86,7 @@ export function installCollectionKeepsakes<A extends { kind: string; variant?: s
78
86
  }));
79
87
  };
80
88
  apply(); const offOwned = owned.onChange(apply); scope?.onDispose(offOwned);
81
- const awarded = new Set<string>();
89
+ const awarded = new Set<string>(), restored = new Set<string>();
82
90
  const roster = new ClaimedPickupRoster<string>(h.pickups, {
83
91
  scene: h.game.scene, has: id => !awarded.has(id) && isOwnedId(id) && owned.has(id),
84
92
  model: id => { const row = rows.drops[id]; if (row === undefined) throw new Error(`Missing collection drop: ${id}`); return view.loose(row.model, row.trophy); },
@@ -86,7 +94,9 @@ export function installCollectionKeepsakes<A extends { kind: string; variant?: s
86
94
  take: id => {
87
95
  const text = h.pickups[id]?.toast, row = rows.drops[id];
88
96
  if (!isOwnedId(id) || text === undefined || row === undefined) throw new Error(`Unknown collection pickup: ${id}`);
89
- awarded.delete(id); owned.grant(id); if (row.wear && isCosmetic(id)) owned.wear(id);
97
+ // a restore is the page's own save's: in a room (now, whenever the wire bound) the server's book keeps the reward
98
+ awarded.delete(id); if (restored.delete(id) && room() !== null) return;
99
+ takeKeepsake(owned, id, row.wear, room());
90
100
  view.announce(text, 0.8);
91
101
  },
92
102
  });
@@ -107,7 +117,7 @@ export function installCollectionKeepsakes<A extends { kind: string; variant?: s
107
117
  });
108
118
  for (const row of rows.restore) {
109
119
  const at = h.rewardAt();
110
- if (flags.has(row.flag) && isOwnedId(row.item) && !owned.has(row.item) && at !== undefined) roster.spawn(row.item, at, false);
120
+ if (flags.has(row.flag) && isOwnedId(row.item) && !owned.has(row.item) && at !== undefined) { restored.add(row.item); roster.spawn(row.item, at, false); }
111
121
  }
112
122
  h.game.onUpdate((dt, t) => {
113
123
  clock += dt;
@@ -16,6 +16,7 @@ import type { EquipmentHost } from '@wildshard/engine/combat/view/EquipmentHost'
16
16
  import type { InputContextDef } from '@wildshard/engine/level/context';
17
17
  import { playerModes } from '@wildshard/engine/player/modes';
18
18
  import type { DiscSpot, TouchRelabel } from '@wildshard/engine/ui/hudSlots';
19
+ import { frameEye, framedPoint } from '@wildshard/engine/ui/hudAdapters';
19
20
  import type { ShardContext } from '@wildshard/engine/game/plugin/context';
20
21
  import { Filament, Rope } from './ribbon';
21
22
  import { effectField } from '@wildshard/engine/fx/effectField';
@@ -125,11 +126,13 @@ function installGrappleAim(ctx: EquipmentHost, shard: ShardContext, scope: Scope
125
126
  const MARKS = row.marks, H = v.parse(hints, row.hints);
126
127
  prepareGrappleFonts(row);
127
128
  let hooks = fragment.hooks;
128
- // the camera as the aim (read live, as the Tool always did)
129
+ // the camera as the aim (read live, as the Tool always did). Hooks, colliders and the feet are frame-local; in a grid frame
130
+ // the camera stands at the frame's render offset, so the eye takes it off and a projection adds it (QA 2026-11-13 row 28)
131
+ const viewEye = new Vector3();
129
132
  const view: GrappleView = {
130
- get eye() { return ctx.game.camera.position; },
133
+ get eye() { return frameEye(ctx.game.camera, viewEye); },
131
134
  update: () => { ctx.game.camera.updateMatrixWorld(true); },
132
- project: (point, out) => out.copy(point).project(ctx.game.camera),
135
+ project: (point, out) => framedPoint(point, out).project(ctx.game.camera),
133
136
  forward: (out) => ctx.game.camera.getWorldDirection(out),
134
137
  };
135
138
  const tracer = makeTracer(ctx, row, profile, scope);
@@ -248,7 +251,7 @@ function installGrappleAim(ctx: EquipmentHost, shard: ShardContext, scope: Scope
248
251
  const pickCandidate = (): GrappleTarget | null => {
249
252
  if (candidate < 0) return null;
250
253
  const hook = hooks[candidate];
251
- if (hook === undefined || !rules.visible(sim.course, ctx.game.camera.position, hook)) return null;
254
+ if (hook === undefined || !rules.visible(sim.course, view.eye, hook)) return null;
252
255
  const landing = new Vector3();
253
256
  const side = rules.landing(ctx.player.position, hook, landing);
254
257
  return side === rules.none ? null : rules.target(sim.course, hook, landing, side);
@@ -313,7 +316,7 @@ function installGrappleAim(ctx: EquipmentHost, shard: ShardContext, scope: Scope
313
316
  const scan = (): number => {
314
317
  const camera = ctx.game.camera;
315
318
  camera.updateMatrixWorld(true);
316
- const eye = camera.position;
319
+ const eye = view.eye;
317
320
  for (let i = 0; i < n; i++) {
318
321
  const hook = hooks[i];
319
322
  if (hook === undefined) continue;
@@ -321,7 +324,7 @@ function installGrappleAim(ctx: EquipmentHost, shard: ShardContext, scope: Scope
321
324
  dist[i] = d;
322
325
  let on = 0;
323
326
  if (d >= MIN_RANGE && d <= MAX_RANGE) {
324
- ndc.copy(hook).project(camera);
327
+ framedPoint(hook, ndc).project(camera);
325
328
  if (ndc.z >= -1 && ndc.z <= 1 && Math.abs(ndc.x) <= 1.05 && Math.abs(ndc.y) <= 1.05) { on = 1; ndcX[i] = ndc.x; ndcY[i] = ndc.y; }
326
329
  }
327
330
  inView[i] = on;
@@ -388,7 +391,7 @@ function installGrappleAim(ctx: EquipmentHost, shard: ShardContext, scope: Scope
388
391
  for (const m of marks) m.show(false);
389
392
  if (target === null) chip.show(false);
390
393
  else {
391
- ndc.copy(target.hook).project(ctx.game.camera);
394
+ framedPoint(target.hook, ndc).project(ctx.game.camera);
392
395
  chip.show(ndc.z >= -1 && ndc.z <= 1);
393
396
  chip.label(touchUi ? row.chip.lockedTouch : row.chip.lockedDesk, 'locked', row.chip.lockedColor);
394
397
  chip.at(target.hook);
@@ -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
+ }
@@ -7,9 +7,10 @@
7
7
  * `cellLoadingStep` is the pure part: a cell's live state to its current step and detail, a refusal's reason, or done.
8
8
  * `CellLoading` owns the one scoped screen: it opens on the cell the traveller waits at (or has entered before it is
9
9
  * gameplay-ready), steps it at most a few times a second, and fades it out when the cell is ready or left.
10
+ *
11
+ * QA 2026-11-13 (Jake: "make it look the same as the one for Shard Select"): G578's in-world canvas panel is gone; the
12
+ * screen is SHARD SELECT's own card again, drawn as a screen-space inset over the live world (`cellScreens.ts`).
10
13
  */
11
- import type { CellScreen, CellScreenView } from './cellScreens';
12
- import type { SoftWallEdge } from './softWallLook';
13
14
  import { loadingPath } from '../boot/loadingPaths';
14
15
 
15
16
  /** One waiting cell's live admission, read through the grid session's read-only port. */
@@ -57,33 +58,43 @@ export function cellLoadingStep(input: CellLoadingInput): CellLoadingStep {
57
58
  return { kind: 'step', key: input.hook === 'activate' ? 'enter' : 'warm', detail: `preparing its first frame${running}` };
58
59
  }
59
60
 
60
- /** Where the waiting cell's screen stands: the edge the traveller meets, the cell's centre and the ground there (home frame). */
61
- export interface CellScreenPlace { readonly edge: SoftWallEdge; readonly cell: { readonly x: number; readonly z: number }; readonly ground: number }
62
- /** G578: the waiting cell's steps on its in-world screen (`CellScreen`); the 3D world, the road and the other cells stay live. */
61
+ /** One row of the screen: its label and whether it is done, running now (with the detail) or still to come. */
62
+ export interface CellLoadingRow { readonly label: string; readonly state: 'done' | 'now' | 'next' }
63
+ /** What the screen shows: whose cell, the step running now (a key of the `cell` path), its rows and detail, or the refusal. */
64
+ export interface CellLoadingView { readonly instance: string; readonly name: string; readonly step: string; readonly rows: readonly CellLoadingRow[];
65
+ readonly detail: string; readonly failed: string | null }
66
+ /** The screen a waiting cell's steps draw on: shown (or stepped) per poll, hidden when the cell is entered or left. */
67
+ export interface CellLoadingScreen { readonly show: (view: CellLoadingView) => void; readonly hide: (entered: boolean) => void }
68
+ /** The waiting cell's steps on the loading card (`CellLoadingScreen`); the 3D world, the road and the other cells stay live. */
63
69
  export class CellLoading {
64
70
  private instance: string | null = null;
65
71
  /** the step shown: a running hook's own step, else the furthest reached (a region learns it has hooks only when they
66
72
  * start, so between hooks a row never goes back) */
67
73
  private reached = -1;
68
- constructor(private readonly screen: Pick<CellScreen, 'show' | 'hide'>, private readonly place: (instance: string) => CellScreenPlace | null) {}
74
+ /** `known`: whether the waiting cell is one of this session's neighbours (no screen for one that is not) */
75
+ constructor(private readonly screen: CellLoadingScreen, private readonly known: (instance: string) => boolean) {}
69
76
  /** Show, step or hide the screen from this cell's live state (null: no cell is waiting). */
70
77
  step(input: CellLoadingInput | null): void {
71
78
  if (input === null || input.instance !== this.instance) this.close();
72
79
  if (input === null) return;
73
- const step = cellLoadingStep(input), at = this.place(input.instance);
74
- if (step.kind === 'done' || at === null) { this.close(); return; }
80
+ const step = cellLoadingStep(input);
81
+ if (step.kind === 'done' || !this.known(input.instance)) { this.close(step.kind === 'done'); return; }
75
82
  this.instance = input.instance;
76
83
  const path = loadingPath('cell').steps;
77
84
  if (step.kind === 'step') {
78
85
  const index = path.findIndex(row => row.key === step.key);
79
86
  this.reached = input.hook === null ? Math.max(this.reached, index) : index;
80
87
  }
81
- const rows = path.map((row, i): CellScreenView['rows'][number] => ({ label: row.label, state: i < this.reached ? 'done' : i === this.reached ? 'now' : 'next' }));
88
+ const rows = path.map((row, i): CellLoadingRow => ({ label: row.label, state: i < this.reached ? 'done' : i === this.reached ? 'now' : 'next' }));
82
89
  const detail = step.kind === 'step' ? step.detail : '';
83
- this.screen.show(at.edge, at.cell, at.ground, { name: input.name, rows, detail, failed: step.kind === 'failed' ? step.reason : null });
90
+ this.screen.show({ instance: input.instance, name: input.name, step: path[Math.max(0, this.reached)]?.key ?? '', rows, detail,
91
+ failed: step.kind === 'failed' ? step.reason : null });
84
92
  }
85
93
  /** The screen's cell (null: none shown). */
86
94
  get open(): string | null { return this.instance; }
87
- /** Hide the screen. */
88
- close(): void { this.instance = null; this.reached = -1; this.screen.hide(); }
95
+ /** Hide the screen: `entered`, the cell is ready (the card completes and fades); else it was left or cancelled. */
96
+ close(entered = false): void {
97
+ const was = this.instance; this.instance = null; this.reached = -1;
98
+ if (was !== null) this.screen.hide(entered);
99
+ }
89
100
  }
@@ -1,83 +1,48 @@
1
1
  /**
2
- * G578 (Jake, 2026-10-21: on the grid a cell load never leaves the 3D world): the waiting cell's loading steps on an
3
- * in-world screen at its edge, the same rows as the loading screen (`loadingPath('cell')`): each step done, the one now with
4
- * its detail, the rest to come, or why it refused. It stands over the road where the traveller meets the closed wall (the
5
- * soft wall's edge midpoint), 12 m beyond the wall and facing out, so a traveller held at the wall reads all of it (closer,
6
- * the 9 m panel overflows a portrait view; on the traveller's side it stood behind the camera). It draws over the cell's
7
- * ground (no depth test): the road and the other cells stay live around it while the cell's boundary holds. Presentation
8
- * only: it reads the session's step, and owns one canvas.
2
+ * QA 2026-11-13 (Jake: "This loading screen here, I have no idea why this loading screen in the 3D world is completely
3
+ * different from the new one ... make it look the same as the one for Shard Select"): a waiting cell's steps on SHARD
4
+ * SELECT's own loading card (`Loading`, scoped, in its `inset` mode), a crisp screen-space card over the live world. It
5
+ * replaced G578's blurry canvas panel standing in 3D beyond the cell's wall (`CellScreen`, removed). The card opens when
6
+ * a cell's preparation shows, steps with it, completes and fades when the cell is entered, and goes at once when the
7
+ * traveller leaves or the session ends. Presentation only: `CellLoading` decides what it shows.
9
8
  */
10
- import { CanvasTexture, Mesh, MeshBasicMaterial, type Object3D, PlaneGeometry, SRGBColorSpace } from 'three';
11
- import type { Scope } from '@wildshard/engine/app/scope';
12
- import type { SoftWallEdge } from './softWallLook';
9
+ import { Loading } from '@wildshard/engine/ui/Loading';
10
+ import { loadingPath } from '../boot/loadingPaths';
11
+ import type { CellLoadingScreen, CellLoadingView } from './cellLoading';
13
12
 
14
- /** One row of the screen: its label and whether it is done, running now (with the detail) or still to come. */
15
- export interface CellScreenRow { readonly label: string; readonly state: 'done' | 'now' | 'next' }
16
- /** What the screen shows: whose cell, its rows, the running step's detail, or the refusal instead of the rows. */
17
- export interface CellScreenView { readonly name: string; readonly rows: readonly CellScreenRow[]; readonly detail: string; readonly failed: string | null }
13
+ export class CellLoadingCard implements CellLoadingScreen {
14
+ private card: { readonly instance: string; readonly loading: Loading; failed: string | null } | null = null;
15
+ /** an entered cell's card while it completes and fades: a new card or a leave ends it at once */
16
+ private fading: Loading | null = null;
18
17
 
19
- /** The side of a cell (`sides`, its four edges around `centre`) the traveller faces from `dx`, `dz` (their offset from the
20
- * cell's centre): the axis they are further along, on their side; one standing at the very centre gets the +x side. */
21
- export function facingEdge<E extends { readonly x: number; readonly z: number; readonly axis: 'x' | 'z' }>(sides: readonly E[],
22
- centre: { readonly x: number; readonly z: number }, dx: number, dz: number): E | undefined {
23
- const sx = dx < 0 ? -1 : 1, sz = dz < 0 ? -1 : 1;
24
- return Math.abs(dx) >= Math.abs(dz) ? sides.find(row => row.axis === 'x' && Math.sign(row.x - centre.x) === sx)
25
- : sides.find(row => row.axis === 'z' && Math.sign(row.z - centre.z) === sz);
26
- }
27
-
28
- const W = 1024, H = 576, WIDTH = 9, HEIGHT = WIDTH * H / W, LIFT = 1, IN = 12;
29
- const CYAN = '#38e6ff', DIM = 'rgba(205, 240, 255, 0.55)', FONT = 'system-ui, -apple-system, sans-serif';
30
-
31
- /** The one in-world loading screen, moved to whichever cell the traveller waits at. */
32
- export class CellScreen {
33
- private readonly canvas: HTMLCanvasElement | OffscreenCanvas;
34
- private readonly texture: CanvasTexture<HTMLCanvasElement | OffscreenCanvas>;
35
- private readonly mesh: Mesh<PlaneGeometry, MeshBasicMaterial>;
36
- private drawn = '';
37
- constructor(parent: Object3D, scope: Scope) {
38
- this.canvas = typeof document === 'undefined' ? new OffscreenCanvas(W, H) : Object.assign(document.createElement('canvas'), { width: W, height: H });
39
- this.texture = scope.own(new CanvasTexture(this.canvas)); this.texture.colorSpace = SRGBColorSpace;
40
- const material = scope.own(new MeshBasicMaterial({ map: this.texture, transparent: true, depthTest: false, depthWrite: false, toneMapped: false, fog: false }));
41
- this.mesh = new Mesh(scope.own(new PlaneGeometry(WIDTH, HEIGHT)), material);
42
- this.mesh.name = 'cell-loading-screen'; this.mesh.visible = false; this.mesh.renderOrder = 20; this.mesh.frustumCulled = false;
43
- parent.add(this.mesh); scope.onDispose(() => { this.mesh.removeFromParent(); });
18
+ show(view: CellLoadingView): void {
19
+ // a cleared refusal starts a fresh card: a failed card keeps its reason until it is disposed
20
+ if (this.card !== null && (this.card.instance !== view.instance || this.card.failed !== null && view.failed === null)) this.hide(false);
21
+ let card = this.card;
22
+ if (card === null) {
23
+ this.fading?.scope.dispose(); this.fading = null;
24
+ const loading = new Loading({ id: view.instance, name: view.name }, { scoped: true, inset: true });
25
+ loading.setPath(loadingPath('cell'));
26
+ card = this.card = { instance: view.instance, loading, failed: null };
27
+ }
28
+ if (view.failed !== null) {
29
+ if (card.failed !== view.failed) { card.failed = view.failed; card.loading.scopedFail(view.failed); }
30
+ return;
31
+ }
32
+ card.loading.scopedStep(view.step, view.detail);
44
33
  }
45
34
 
46
- /** Stand beyond `edge` (the waiting cell's closed wall in the home frame), facing the traveller outside it, and draw `view`. */
47
- show(edge: SoftWallEdge, cell: { readonly x: number; readonly z: number }, ground: number, view: CellScreenView): void {
48
- const outward = edge.axis === 'x' ? Math.sign(edge.x - cell.x) : Math.sign(edge.z - cell.z);
49
- const x = edge.axis === 'x' ? edge.x - outward * IN : edge.x, z = edge.axis === 'z' ? edge.z - outward * IN : edge.z;
50
- this.mesh.position.set(x, ground + LIFT + HEIGHT / 2, z);
51
- // the (front) face looks out of the cell, toward the traveller on the road
52
- this.mesh.rotation.set(0, edge.axis === 'x' ? (outward > 0 ? Math.PI / 2 : -Math.PI / 2) : (outward > 0 ? 0 : Math.PI), 0);
53
- this.mesh.updateMatrixWorld();
54
- this.mesh.visible = true;
55
- const key = JSON.stringify(view);
56
- if (key !== this.drawn) { this.drawn = key; this.draw(view); }
35
+ hide(entered: boolean): void {
36
+ const card = this.card;
37
+ if (!entered) { this.fading?.scope.dispose(); this.fading = null; }
38
+ if (card === null) return;
39
+ this.card = null;
40
+ if (entered && card.failed === null) {
41
+ const fading = this.fading = card.loading;
42
+ void fading.done().then(() => { if (this.fading === fading) this.fading = null; return undefined; }, () => undefined);
43
+ } else card.loading.scope.dispose();
57
44
  }
58
- /** Hide it (the cell is ready, or no cell is waiting). */
59
- hide(): void { this.mesh.visible = false; }
60
- get visible(): boolean { return this.mesh.visible; }
61
45
 
62
- private draw(view: CellScreenView): void {
63
- const g = this.canvas.getContext('2d');
64
- if (g === null) throw new Error('Cell screen has no 2D context');
65
- g.clearRect(0, 0, W, H);
66
- g.fillStyle = 'rgba(4, 18, 28, 0.82)'; g.fillRect(0, 0, W, H);
67
- g.strokeStyle = CYAN; g.lineWidth = 6; g.strokeRect(3, 3, W - 6, H - 6);
68
- g.fillStyle = CYAN; g.font = `700 54px ${FONT}`; g.textBaseline = 'top';
69
- g.fillText(view.name.toUpperCase(), 44, 34);
70
- if (view.failed !== null) {
71
- g.fillStyle = '#ff9a7a'; g.font = `600 36px ${FONT}`; g.fillText(view.failed.slice(0, 48), 44, 130);
72
- } else {
73
- g.font = `500 32px ${FONT}`;
74
- view.rows.forEach((row, i) => {
75
- const y = 118 + i * 52;
76
- g.fillStyle = row.state === 'next' ? DIM : row.state === 'now' ? CYAN : '#ffffff';
77
- g.fillText(`${row.state === 'done' ? '✓' : row.state === 'now' ? '▶' : '·'} ${row.label}`, 44, y);
78
- });
79
- g.fillStyle = DIM; g.font = `400 28px ${FONT}`; g.fillText(view.detail.slice(0, 60), 44, H - 64);
80
- }
81
- this.texture.needsUpdate = true;
82
- }
46
+ /** The card's root while one is up (tests and proofs read it). */
47
+ get root(): HTMLElement | null { return this.card?.loading.root ?? null; }
83
48
  }
@@ -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.
@@ -78,15 +78,18 @@ import { copyPrompts, enteredCopy } from './copyPrompts';
78
78
  import { yieldGridAdmission, yieldGridConstruction } from './admissionYield';
79
79
  import { HybridRuntimeSession, type HybridResident } from '../shardfile/hybrid';
80
80
 
81
+ import { enterPlotAudio, pagePlotAudioPorts, plotAudioScene, type PlotAudioPorts, type PlotAudioScene } from './plotAudio';
82
+ import { shardProductFromAdmission } from '../shardfile/runtimeProduct';
81
83
  import { createRegionalRuntimeFactory, regionalRuntimeAccountedBytes, type PreparedRegionalRuntime, type RegionalRuntimePage, type RegionalRuntimeTextures } from './regionalRuntime';
82
84
  import { bindHomeBuildCache } from '../shardfile/homeBuildCache';
83
85
  import type { ClientTileRegistration } from '../shardfile/tileContent';
84
- import { createRegionalWorldFoundation, hangCellDataSky, resolveRegionalRuntimeTextures } from './regionalWorld';
86
+ import { createRegionalWorldFoundation, hangCellDataSky, registerRegionalTextureTable, resolveRegionalRuntimeTextures } from './regionalWorld';
85
87
  import { regionalDataCellBytes } from './runtimeCost';
86
88
  import { resolveLevelBounds } from '../../../shared/game/shard/runtime';
87
89
  import { declaredPlayArea, type PlayArea } from '@wildshard/engine/game/shardfile/playArea';
88
90
  import type { ShardProduct } from '@wildshard/engine/game/shardfile/shardProduct';
89
91
  import type { Bounds } from '@wildshard/engine/level/spec';
92
+ import { pinFrameOffset } from '@wildshard/engine/ui/hudAdapters';
90
93
 
91
94
  /** The cached metadata claim and its later constructor enter the same immutable
92
95
  * texture policy. Fresh inputs remain borrowed only by actual construction. */
@@ -167,6 +170,8 @@ export interface LiveGridWire {
167
170
  readonly rebound: (physics: Physics) => void;
168
171
  /** The server's creatures in the world the page stands in, for a cell whose creatures no manager holds. */
169
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[];
170
175
  }
171
176
  /** The readout: the live host's crossing telemetry, the crossing coordinator and the safe-zone state. */
172
177
  export interface LiveGridSessionState {
@@ -230,7 +235,10 @@ export class LiveGridSession {
230
235
  private readonly applied = new Vector3();
231
236
  private readonly roadWallet: GridWallet;
232
237
  /** each admitted region's authored spawn (its level's player start) and its ground / water queries, local */
233
- private readonly regions = new Map<string, { readonly spawn: LiveGridSpawn; readonly items: Shardfile['items']['rows']; readonly queries: PlayerFrameQueries; readonly colliders: PanelRegion['colliders']; readonly prompts: ReturnType<typeof copyPrompts> }>();
238
+ private readonly regions = new Map<string, { readonly spawn: LiveGridSpawn; readonly items: Shardfile['items']['rows']; readonly queries: PlayerFrameQueries; readonly colliders: PanelRegion['colliders']; readonly prompts: ReturnType<typeof copyPrompts>; readonly audio: PlotAudioScene | null }>();
239
+ /** AU20: the entered data cell's own audio scene (an Open Plot's score, bed and loops), live while the feet are in it. */
240
+ private plotAudio: { readonly instance: string; readonly scope: Scope } | null = null;
241
+ private readonly plotBanks = new Map<string, ReturnType<PlotAudioPorts['bank']>>();
234
242
  private readonly runtimeScope: Scope;
235
243
  private readonly runtimeRegions = new Map<string, PreparedRegionalRuntime>();
236
244
  private readonly leaveTiming: { instance: string; leaveMs: number }[] = [];
@@ -261,8 +269,9 @@ export class LiveGridSession {
261
269
  this.runtimeScope = scope.child('grid.runtime.residents');
262
270
  this.hybrid = new HybridRuntimeSession(this.runtimeResidents, scope, { pause: yieldGridConstruction });
263
271
  scope.onDispose(gridCells.onLeave(() => { this.hybrid.leave(); }));
272
+ scope.onDispose(gridCells.onLeave(() => { this.leavePlotAudio(); }));
264
273
  scope.onDispose(gridCells.onEnter(cell => {
265
- if (!this.runtimeResidents.has(cell.instance)) { ports.lightingSettled?.(); return; }
274
+ if (!this.runtimeResidents.has(cell.instance)) { this.enterPlotAudio(cell.instance); ports.lightingSettled?.(); return; }
266
275
  this.startedRuntimes.add(cell.instance);
267
276
  const activation = this.hybrid.enter(cell);
268
277
  this.activation = activation;
@@ -296,6 +305,7 @@ export class LiveGridSession {
296
305
  return { physics: ports.physics, walls: ports.walls, dispose: () => { highwayScope.dispose(); } };
297
306
  } },
298
307
  admit: (cell, required) => this.admit(cell, required),
308
+ buildAhead: true, // GC5 / GC36: the road builds the world ahead of its line
299
309
  prepareTransport: (cell, signal) => prepareApproachProductInputs(cell.slug, { allocator: ports.allocator, scope }, signal, assembly.local(traveller.position, cell)),
300
310
  ...(ports.prepareNeighbourTiles === undefined ? {} : { prepareNeighbour: ports.prepareNeighbourTiles }),
301
311
  prioritize: (cell) => prioritizeGridProduct(cell.slug, { allocator: ports.allocator, scope }),
@@ -367,15 +377,16 @@ export class LiveGridSession {
367
377
  // done in one go it froze a template cell 1.0–1.6 s every ~6.2 s on the phone.
368
378
  if (++saveTicks >= 300) { saveTicks = 0; this.captureAutosave(); }
369
379
  });
370
- page.onInput(() => { traveller.camera.position.sub(this.applied); this.applied.set(0, 0, 0); });
380
+ page.onInput(() => { traveller.camera.position.sub(this.applied); this.applied.set(0, 0, 0); pinFrameOffset.set(0, 0, 0); });
371
381
  scope.onDispose(() => { this.autosave?.return(false); this.autosave = null; });
372
382
  page.onUpdate(() => { // the page has one update slot (game.grid.origin): the camera offset, then one autosave stage
373
- if (this.offset.lengthSq() !== 0) { traveller.camera.position.add(this.offset); this.applied.copy(this.offset); }
383
+ // the HUD's world pins stand in the same frame: their points move with the camera (hudAdapters.ts pinFrameOffset)
384
+ if (this.offset.lengthSq() !== 0) { traveller.camera.position.add(this.offset); this.applied.copy(this.offset); pinFrameOffset.copy(this.offset); }
374
385
  // The capture's own frame encodes nothing more: the next stage waits for the next frame's update.
375
386
  if (scope.disposed) return;
376
387
  if (this.autosaveCaptured) this.autosaveCaptured = false; else this.stepAutosave();
377
388
  });
378
- scope.onDispose(() => { traveller.camera.position.sub(this.applied); this.applied.set(0, 0, 0); });
389
+ scope.onDispose(() => { traveller.camera.position.sub(this.applied); this.applied.set(0, 0, 0); pinFrameOffset.set(0, 0, 0); });
379
390
  scope.listen(window, 'pagehide', () => { this.checkpoint(); });
380
391
  scope.listen(document, 'visibilitychange', () => { if (document.visibilityState === 'hidden') this.checkpoint(); });
381
392
  scope.onDispose(() => { this.checkpoint(); });
@@ -696,7 +707,9 @@ export class LiveGridSession {
696
707
  transfer.sync(); this.transferWalls.set(cell.instance, transfer);
697
708
  this.regions.set(cell.instance, { spawn: { x: start.at.x, y: undefined, z: start.at.z, yaw: start.yaw },
698
709
  // the admitted terrain inside the cell (one source of truth); its strips are road level (the terrain tile ends at the cell edge)
699
- queries: { heightAt: (x, z) => (Math.max(Math.abs(x), Math.abs(z)) <= CHUNK_HALF ? heightAt(x, z) : 0), waterSurfaceAt: (x, z) => water.restAt(x, z), platforms: [] }, colliders, items: copySource.items.rows, prompts: copyPrompts(copySource) });
710
+ queries: { heightAt: (x, z) => (Math.max(Math.abs(x), Math.abs(z)) <= CHUNK_HALF ? heightAt(x, z) : 0), waterSurfaceAt: (x, z) => water.restAt(x, z), platforms: [] }, colliders, items: copySource.items.rows, prompts: copyPrompts(copySource),
711
+ // AU20: the cell's declared audio scene, bound only while the feet stand in it (no entered hooks run here)
712
+ audio: source.runtime === null && source.audio.scene !== undefined ? plotAudioScene(source, ((plot) => plot.has('client/plan') ? plot.section('client/plan') : undefined)(shardProductFromAdmission(retained.admitted, shell.scope))) : null });
700
713
  this.respawnCells.set(cell.instance, { instance: cell.instance, origin: cell.origin, entryways: source.entryways });
701
714
  // G321: its own sky inside its cell (its data look's dome and light), laid while it is resident
702
715
  {
@@ -705,7 +718,7 @@ export class LiveGridSession {
705
718
  try { await hangCellDataSky(request); } catch (error) { console.warn(`[region sky] ${cell.instance}`, error); }
706
719
  })();
707
720
  }
708
- const unlist = (): void => { this.regions.delete(cell.instance); this.transferWalls.delete(cell.instance); };
721
+ const unlist = (): void => { if (this.plotAudio?.instance === cell.instance) this.leavePlotAudio(); this.plotBanks.delete(cell.instance); this.regions.delete(cell.instance); this.transferWalls.delete(cell.instance); };
709
722
  return { host: shell, shell, dispose: () => {
710
723
  unlist();
711
724
  try { shell.dispose(); } finally { retained.release(); }
@@ -720,7 +733,8 @@ export class LiveGridSession {
720
733
  const region = build();
721
734
  try {
722
735
  const feet = this.live.worldFeet();
723
- 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) });
724
738
  return region;
725
739
  } catch (error) {
726
740
  try { region.dispose(); }
@@ -739,6 +753,9 @@ export class LiveGridSession {
739
753
  if (manifest === undefined || !dataPage && declaration === null) throw new GridCellWaitingError('Missing declared regional page owner');
740
754
  const page = this.page.runtimePage?.();
741
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);
742
759
  const textures = choice.textures ??= resolveRegionalRuntimeTextures(manifest, this.ports.allocator.cost().input), bytes = regionalRuntimeAccountedBytes(retained.admitted, manifest, textures.mode);
743
760
  const prepareEntry = async (): Promise<void> => {
744
761
  if (declaration === null) return;
@@ -773,7 +790,9 @@ export class LiveGridSession {
773
790
  try {
774
791
  if (cell.instance === this.ports.home.instance) bindHomeBuildCache(retained.admitted.source);
775
792
  const feet = this.live.worldFeet();
776
- 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) };
777
796
  prepared = await factory({ cell, admitted: retained.admitted, manifest, page, textures, allocator: this.ports.allocator, claim, scope: this.runtimeScope, entryPoint });
778
797
  }
779
798
  catch (error) { this.transferWalls.delete(cell.instance); throw error; }
@@ -813,6 +832,29 @@ export class LiveGridSession {
813
832
  } };
814
833
  }
815
834
 
835
+ /** AU20: the feet entered a data cell; bind its declared audio scene to the page's mixer until they leave. */
836
+ private enterPlotAudio(instance: string): void {
837
+ this.leavePlotAudio();
838
+ const scene = this.regions.get(instance)?.audio ?? null, page = this.page.runtimePage?.() ?? null;
839
+ if (scene === null || page === null) return;
840
+ const own = pagePlotAudioPorts(page.context.app, page.world.player, instance);
841
+ if (own === null) return;
842
+ // one bank read per resident cell: dropped with the region (unlist), so a re-entry lends the bank it already decoded
843
+ const ports: PlotAudioPorts = { ...own, bank: (data) => {
844
+ let read = this.plotBanks.get(instance);
845
+ if (read === undefined) { read = own.bank(data); this.plotBanks.set(instance, read); void read.catch(() => { if (this.plotBanks.get(instance) === read) this.plotBanks.delete(instance); }); }
846
+ return read;
847
+ } };
848
+ const owner = this.ports.scope.child(`grid.plot-audio.${instance}`);
849
+ this.plotAudio = { instance, scope: owner };
850
+ try { enterPlotAudio(scene, owner, ports); }
851
+ catch (error) { this.leavePlotAudio(); ports.fault(error); }
852
+ }
853
+ private leavePlotAudio(): void {
854
+ const entered = this.plotAudio; this.plotAudio = null;
855
+ entered?.scope.dispose();
856
+ }
857
+
816
858
  /** Live scalar warm-up progress for this destination, never the last trace of a different region. */
817
859
  warmPreparation(instance: string): NonNullable<PreparedRegionalRuntime['warmPreparation']> | null {
818
860
  return this.runtimeRegions.get(instance)?.warmPreparation ?? null;
@@ -953,6 +995,8 @@ export class LiveGridSession {
953
995
  const region = this.regions.get(instance);
954
996
  return region === undefined ? undefined : { colliders: region.colliders, field: name => this.wire?.site() === instance ? wirePage.row(name) : undefined };
955
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?.() ?? [] : []; }
956
1000
  /** What draws a cell's life: the server's rows, which exist only where the page stands. */
957
1001
  lifeRegion(instance: string): NeighbourRegion | undefined { return this.wire?.site() === instance ? this.wire.rows : undefined; }
958
1002