@wildshard/engine 0.1.15 → 0.1.17

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 (207) hide show
  1. package/CHANGELOG.md +15 -0
  2. package/index.html +157 -11
  3. package/lint/engine-sides.json +16 -0
  4. package/lint/host-register.json +496 -0
  5. package/lint/ratchet.json +2 -2
  6. package/lint/shard-imports.d.mts +1 -0
  7. package/lint/shard-imports.mjs +56 -8
  8. package/lint/wildshard-plugin.js +22 -4
  9. package/package.json +16 -5
  10. package/scripts/app-build/buildIdentity.d.mts +3 -1
  11. package/scripts/app-build/buildIdentity.mjs +25 -5
  12. package/scripts/app-build/builtAt.d.mts +4 -0
  13. package/scripts/app-build/builtAt.mjs +21 -0
  14. package/scripts/app-build/serviceWorker.ts +16 -2
  15. package/scripts/app-build/versionFiles.ts +2 -1
  16. package/scripts/app-build-pipeline.mjs +4 -1
  17. package/scripts/audio-download-proof.mjs +843 -0
  18. package/scripts/build-app.mjs +4 -0
  19. package/scripts/build-mirror.d.mts +2 -0
  20. package/scripts/build-mirror.mjs +5 -4
  21. package/scripts/built-product.mjs +3 -3
  22. package/scripts/cell-mem/metrics-preload.mjs +65 -0
  23. package/scripts/cell-mem-bench.mjs +130 -0
  24. package/scripts/check-chunks.mjs +2 -1
  25. package/scripts/devserver-client.d.mts +5 -0
  26. package/scripts/devserver-client.mjs +68 -0
  27. package/scripts/engine-ci-budget.ts +7 -1
  28. package/scripts/format-lock.mjs +20 -11
  29. package/scripts/generate-title-launch.mjs +3 -2
  30. package/scripts/grid-crossing-walk-proof.mjs +16 -8
  31. package/scripts/heavy-lane.py +25 -1
  32. package/scripts/host-ruler/register-migrate.mjs +242 -0
  33. package/scripts/host-ruler/register.d.mts +36 -0
  34. package/scripts/host-ruler/register.mjs +116 -0
  35. package/scripts/host-ruler/roots.d.mts +29 -0
  36. package/scripts/host-ruler/roots.mjs +333 -0
  37. package/scripts/host-ruler/server-roots.d.mts +23 -0
  38. package/scripts/host-ruler/server-roots.mjs +272 -0
  39. package/scripts/main-watch.d.mts +1 -1
  40. package/scripts/main-watch.mjs +10 -6
  41. package/scripts/map-hash.mjs +3 -6
  42. package/scripts/mmo-bots.mjs +2 -2
  43. package/scripts/offline-proof-rules.d.mts +1 -0
  44. package/scripts/offline-proof-rules.mjs +22 -1
  45. package/scripts/online-rig.mjs +4 -4
  46. package/scripts/page-release/flow.d.mts +1 -0
  47. package/scripts/page-release/flow.mjs +6 -2
  48. package/scripts/page-release.mjs +5 -1
  49. package/scripts/physics-route.json +0 -71
  50. package/scripts/pins-catalogue.ts +103 -0
  51. package/scripts/pins-reuse.mjs +3 -1
  52. package/scripts/pins.ts +22 -14
  53. package/scripts/preview-grid.ts +203 -0
  54. package/scripts/road-preload-proof.mjs +167 -0
  55. package/scripts/server-release/publish.mjs +2 -2
  56. package/scripts/server-release/served-slug.d.mts +2 -0
  57. package/scripts/server-release/served-slug.mjs +10 -0
  58. package/scripts/server-release/sign.d.mts +1 -0
  59. package/scripts/server-release/sign.mjs +3 -7
  60. package/scripts/shard-components.mjs +0 -2
  61. package/scripts/shard-outputs.d.mts +8 -0
  62. package/scripts/shard-outputs.mjs +45 -11
  63. package/scripts/side-parity.d.mts +2 -1
  64. package/scripts/side-parity.mjs +25 -4
  65. package/scripts/test-amber.d.mts +1 -0
  66. package/scripts/test-amber.mjs +10 -0
  67. package/scripts/test-products.json +3 -3
  68. package/scripts/tracked-public.d.mts +1 -0
  69. package/scripts/tracked-public.mjs +17 -0
  70. package/src/cli/engine.mjs +8 -0
  71. package/src/client/app/bootRoute.ts +4 -1
  72. package/src/client/app/dropModal.ts +15 -2
  73. package/src/client/app/entry.ts +67 -11
  74. package/src/client/app/slugPath.ts +5 -0
  75. package/src/client/engine/audio/Audio.ts +20 -2
  76. package/src/client/engine/boot/bakedTextures.ts +3 -2
  77. package/src/client/engine/boot/bootTrace.ts +6 -1
  78. package/src/client/engine/boot/bytes.ts +4 -3
  79. package/src/client/engine/boot/clearDownloads.ts +1 -1
  80. package/src/client/engine/boot/contentRead.ts +4 -0
  81. package/src/client/engine/boot/dropNotice.ts +20 -6
  82. package/src/client/engine/boot/gpuFiles.ts +25 -2
  83. package/src/client/engine/boot/lastEnd.ts +8 -2
  84. package/src/client/engine/boot/shardPrefetch.ts +7 -1
  85. package/src/client/engine/boot/sw.ts +19 -0
  86. package/src/client/engine/core/Game.ts +11 -3
  87. package/src/client/engine/core/GpuRecovery.ts +7 -0
  88. package/src/client/engine/core/Volumetrics.ts +5 -0
  89. package/src/client/engine/core/assets.ts +27 -20
  90. package/src/client/engine/core/bootstrap.ts +1 -2
  91. package/src/client/engine/core/ktx2.ts +84 -11
  92. package/src/client/engine/explore/Compare.ts +2 -2
  93. package/src/client/engine/explore/TouchFly.ts +3 -5
  94. package/src/client/engine/input/dom.ts +12 -0
  95. package/src/client/engine/net/predictor.ts +6 -2
  96. package/src/client/engine/player/Player.ts +10 -2
  97. package/src/client/engine/player/TouchControls.ts +12 -4
  98. package/src/client/engine/pwa/sw.js +47 -8
  99. package/src/client/engine/render/drawCheck.ts +96 -0
  100. package/src/client/engine/saves/staleBuildNote.ts +46 -0
  101. package/src/client/engine/telemetry/browserErrors.ts +157 -20
  102. package/src/client/engine/telemetry/screenOutbox.ts +61 -0
  103. package/src/client/engine/telemetry/staleBuildReport.ts +12 -0
  104. package/src/client/engine/ui/DeathFade.ts +99 -11
  105. package/src/client/engine/ui/ErrorModal.ts +13 -6
  106. package/src/client/engine/ui/Feedback.ts +2 -1
  107. package/src/client/engine/ui/Loading.ts +10 -6
  108. package/src/client/engine/ui/Map.ts +2 -1
  109. package/src/client/engine/ui/WeaponStrip.ts +2 -1
  110. package/src/client/engine/ui/backGuard.ts +104 -0
  111. package/src/client/engine/ui/hudAdapters.ts +30 -4
  112. package/src/client/engine/ui/loading.css +17 -0
  113. package/src/client/engine/ui/namePrompt.ts +6 -5
  114. package/src/client/engine/ui/styles/combat.css +12 -0
  115. package/src/client/engine/ui/styles/namePrompt.css +4 -2
  116. package/src/client/game/boot/audio.generated.ts +0 -294
  117. package/src/client/game/boot/bytes.generated.ts +0 -11
  118. package/src/client/game/boot/versions.generated.ts +0 -11
  119. package/src/client/game/compendium/keepsakes.ts +16 -6
  120. package/src/client/game/grapple/tool.ts +10 -7
  121. package/src/client/game/grid/cellLoading.ts +23 -12
  122. package/src/client/game/grid/cellScreens.ts +39 -74
  123. package/src/client/game/grid/liveSession.ts +40 -7
  124. package/src/client/game/grid/nearPlaceholderPlan.ts +8 -0
  125. package/src/client/game/grid/nearPlaceholderView.ts +9 -3
  126. package/src/client/game/grid/oneWayIn.ts +92 -27
  127. package/src/client/game/grid/pageEntry.ts +19 -0
  128. package/src/client/game/grid/pageShell.ts +1 -1
  129. package/src/client/game/grid/plotAudio.ts +114 -0
  130. package/src/client/game/grid/products.ts +55 -5
  131. package/src/client/game/grid/roadLookPlatform.ts +2 -2
  132. package/src/client/game/grid/session.ts +38 -22
  133. package/src/client/game/grid/spawnGround.ts +68 -0
  134. package/src/client/game/grid/voidLook.ts +29 -23
  135. package/src/client/game/loot/runtime.ts +3 -1
  136. package/src/client/game/mainMenu.ts +14 -6
  137. package/src/client/game/riding/hud.ts +6 -4
  138. package/src/client/game/session/finish.ts +17 -3
  139. package/src/client/game/session/play.ts +8 -2
  140. package/src/client/game/session/session.ts +4 -1
  141. package/src/client/game/shardfile/clientWorker.ts +41 -12
  142. package/src/client/game/shardfile/serverRoute.ts +10 -22
  143. package/src/client/game/slugPage.css +11 -0
  144. package/src/client/game/slugPage.ts +84 -0
  145. package/src/client/game/systems/viewmodel/heldView.ts +6 -3
  146. package/src/client/game/titleDeck.ts +55 -32
  147. package/src/client/host/online/doctor.ts +7 -6
  148. package/src/client/host/online/linkScreens.ts +16 -0
  149. package/src/client/host/online/release.ts +51 -5
  150. package/src/client/host/online/shell.ts +48 -27
  151. package/src/client/host/standalone/shell.ts +7 -3
  152. package/src/cook/game/audioReport.ts +57 -0
  153. package/src/cook/game/entryTotals.ts +26 -6
  154. package/src/cook/game/installedRuntimeReads.ts +3 -0
  155. package/src/server/engine/sim/respawn.ts +6 -1
  156. package/src/server/engine/sim.ts +3 -0
  157. package/src/server/game/grid/simulation.ts +35 -0
  158. package/src/server/game/loot/harvest.ts +2 -0
  159. package/src/server/game/loot/keepsakeProgression.ts +40 -0
  160. package/src/server/game/loot/playerOwned.ts +5 -1
  161. package/src/server/game/plugin/simulation.ts +4 -0
  162. package/src/server/game/population/nativeBake.ts +2 -1
  163. package/src/server/game/quest/chapterRecords.ts +2 -0
  164. package/src/server/game/quest/serverChapters.ts +4 -0
  165. package/src/server/game/quest/serverDoors.ts +11 -5
  166. package/src/server/game/roomRespawn.ts +4 -0
  167. package/src/server/game/shardfile/installedSides.ts +18 -0
  168. package/src/server/game/shardfile/nativeAssemblyHosts.ts +19 -10
  169. package/src/server/game/shardfile/nativeAssemblyInput.ts +1 -4
  170. package/src/server/host/bake/headlessWorker.ts +5 -1
  171. package/src/server/host/dedicated/cellHost.ts +98 -29
  172. package/src/server/host/dedicated/cellProtocol.ts +11 -1
  173. package/src/server/host/dedicated/cellWorker.ts +9 -3
  174. package/src/server/host/dedicated/crossing.ts +6 -2
  175. package/src/server/host/dedicated/dedicatedRoom.ts +21 -8
  176. package/src/server/host/dedicated/gridCells.ts +52 -9
  177. package/src/server/host/dedicated/main.ts +31 -12
  178. package/src/server/host/dedicated/placementFile.ts +72 -0
  179. package/src/server/host/dedicated/releaseFile.ts +17 -10
  180. package/src/server/host/dedicated/roadRoom.ts +21 -5
  181. package/src/server/host/dedicated/workerTable.ts +13 -1
  182. package/src/server/host/dedicated/world.ts +81 -9
  183. package/src/server/host/headlessRuntime.ts +10 -5
  184. package/src/server/host/installers.ts +62 -0
  185. package/src/server/host/openWorld.ts +59 -0
  186. package/src/server/host/ropeDecks.ts +2 -0
  187. package/src/server/host/standalone/cellWorld.ts +25 -19
  188. package/src/server/host/standalone/fallFloor.ts +2 -2
  189. package/src/server/host/standalone/gridServer.ts +7 -4
  190. package/src/server/host/standalone/roadWorld.ts +41 -4
  191. package/src/shared/engine/audio/bootAudio.ts +33 -0
  192. package/src/shared/engine/level/spec.ts +3 -3
  193. package/src/shared/engine/net/acts.ts +3 -0
  194. package/src/shared/engine/physics/query.ts +27 -0
  195. package/src/shared/engine/physics/terrain.ts +19 -28
  196. package/src/shared/engine/saves/saves.lock.json +15 -0
  197. package/src/shared/engine/sim/actRoutes.ts +2 -0
  198. package/src/shared/game/compendium/keepsakeProgression.ts +24 -0
  199. package/src/shared/game/grid/catalogue.ts +12 -5
  200. package/src/shared/game/grid/catalogueSlot.ts +11 -0
  201. package/src/shared/game/grid/farProxy.ts +6 -5
  202. package/src/shared/game/grid/pageMode.ts +1 -1
  203. package/src/shared/game/grid/roadLayout.ts +26 -3
  204. package/src/shared/game/grid/singleplayer.json +0 -13
  205. package/src/shared/game/grid/voidFloor.ts +122 -0
  206. package/src/shared/game/strings.ts +15 -0
  207. package/src/shared/host/standalone/netInput.ts +2 -1
@@ -0,0 +1,114 @@
1
+ import type { AudioData } from '@wildshard/format/audio';
2
+ import type { ClientPlan } from '@wildshard/format/clientPlan';
3
+ import type { Scope } from '@wildshard/engine/app/scope';
4
+ import type { LevelAudioBank } from '@wildshard/engine/audio/levelAudio';
5
+ import type { App } from '@wildshard/engine/app/app';
6
+ import type { Player } from '@wildshard/engine/player/Player';
7
+ import { wind } from '@wildshard/engine/world/steppeWind';
8
+ import { ENGINE_MUSIC_STYLE } from '@wildshard/engine/audio/bootAudio';
9
+ import { AudioSceneDirector } from '../audio/sceneDirector';
10
+
11
+ /**
12
+ * AUDIO AU20: an Open Plot on the grid page is a bodyless data cell (no runtime, no declared client page), so no entered
13
+ * hooks run there and its client plan's `audio.scene` never installed: crossing in from a deck shard left the music and
14
+ * ambience buses silent. While the feet stand in such a cell, the grid binds the plot's declared audio scene (its score,
15
+ * bed and loops) to the page's mixer, and drops it on leaving.
16
+ *
17
+ * Where its takes come from: a play-time read (the page cache, else the network) when the feet enter the cell, never in
18
+ * LOAD, so the neighbour the player entered from keeps a DOWNLOAD of only its own audio.
19
+ */
20
+
21
+ /** One wind observation the plot's `world.updates` audio-scene row feeds its director each frame. */
22
+ export interface PlotAudioInput { readonly name: string; readonly field: 'speed' | 'gust' }
23
+ /** What an Open Plot's cell plays while the feet stand in it. */
24
+ export interface PlotAudioScene { readonly data: AudioData; readonly inputs: readonly PlotAudioInput[] }
25
+
26
+ /** The plot's declared audio scene, or null when its cell has none the grid can play without an entered runtime: a runtime
27
+ * shard (its hooks own its audio), no `audio.scene` client feature, a scene in a separate file, or a frame input whose owner
28
+ * (an arena, the weather rig) exists only inside an entered runtime. */
29
+ export function plotAudioScene(source: { readonly runtime: unknown; readonly audio: AudioData }, plan: ClientPlan | undefined): PlotAudioScene | null {
30
+ if (source.runtime !== null || plan === undefined || source.audio.scene === undefined) return null;
31
+ if (!plan.features.some(feature => feature.kind === 'audio.scene')) return null;
32
+ const inputs: PlotAudioInput[] = [];
33
+ for (const feature of plan.features) {
34
+ if (feature.kind !== 'world.updates') continue;
35
+ for (const row of feature.rows) {
36
+ if (row.kind !== 'audio-scene') continue;
37
+ for (const input of row.inputs) {
38
+ if (input.source.kind !== 'wind') return null;
39
+ inputs.push({ name: input.name, field: input.source.field });
40
+ }
41
+ }
42
+ }
43
+ return { data: source.audio, inputs };
44
+ }
45
+
46
+ /** The page owners a plot's scene borrows; tests pass their own. */
47
+ export interface PlotAudioPorts {
48
+ /** Bind the declared director to the page's mixer and music for `scope`; returns its frame update. */
49
+ readonly bind: (data: AudioData, scope: Scope) => (dt: number, inputs: Readonly<Record<string, number>>) => void;
50
+ /** Read and decode the plot's level bank (its loops, the score set's stings, the engine title) at play time; the grid
51
+ * keeps one read per resident cell, so walking its edge back and forth decodes it once. */
52
+ readonly bank: (data: AudioData) => Promise<LevelAudioBank>;
53
+ /** Lend the bank to the page's mixer while `scope` lives; the bank it replaced comes back after. */
54
+ readonly lend: (bank: LevelAudioBank, scope: Scope) => void;
55
+ /** Run `run` every frame while `scope` lives. */
56
+ readonly frame: (run: (dt: number) => void, scope: Scope) => void;
57
+ readonly wind: (field: PlotAudioInput['field']) => number;
58
+ readonly fault: (error: unknown) => void;
59
+ }
60
+
61
+ /** Enter the plot's scene for the life of `scope` (the feet in its cell). The score switches at once; its bank arrives
62
+ * when read, and a bank read after the feet left is never lent. */
63
+ export function enterPlotAudio(scene: PlotAudioScene, scope: Scope, ports: PlotAudioPorts): void {
64
+ if (scope.disposed) return;
65
+ // made before the director binds, so it ends after the director unbinds: the replaced bank returns to the page's own
66
+ // listeners, never to the plot's score and cue player
67
+ const lent = scope.child('plot-audio.bank');
68
+ const update = ports.bind(scene.data, scope);
69
+ ports.frame((dt) => {
70
+ const values: Record<string, number> = {};
71
+ for (const input of scene.inputs) values[input.name] = ports.wind(input.field);
72
+ update(dt, values);
73
+ }, scope);
74
+ const lend = async (): Promise<void> => {
75
+ try {
76
+ const bank = await ports.bank(scene.data);
77
+ if (!lent.disposed) ports.lend(bank, lent);
78
+ } catch (error) { if (!lent.disposed) ports.fault(error); }
79
+ };
80
+ void lend();
81
+ }
82
+
83
+ /** One decode at a time, as the boot's decoder does (WebKit holds no pile of native PCM outputs at once). */
84
+ function serialDecode(decode: (bytes: ArrayBuffer) => Promise<AudioBuffer>): (bytes: ArrayBuffer) => Promise<AudioBuffer> {
85
+ let tail: Promise<unknown> = Promise.resolve();
86
+ return (bytes) => {
87
+ const next = tail.then(() => decode(bytes));
88
+ tail = next.catch(() => undefined);
89
+ return next;
90
+ };
91
+ }
92
+
93
+ /** The page's real owners: its mixer and music, the page player, the steppe wind. */
94
+ export function pagePlotAudioPorts(app: App, player: Player, instance: string): PlotAudioPorts | null {
95
+ const audio = app.audio;
96
+ if (audio === null) return null;
97
+ return {
98
+ bind: (data, scope) => {
99
+ const director = new AudioSceneDirector(data, player);
100
+ if (director.fieldFiles.length > 0) throw new Error('Plot audio fields need their product reads');
101
+ director.bind(audio, audio.music ?? undefined, undefined, scope);
102
+ return (dt, inputs) => { director.update(dt, inputs); };
103
+ },
104
+ bank: async (data) => {
105
+ const [{ createCatalogueAudio }, { cachedBytes, decodeBytes }] = await Promise.all([import('@wildshard/engine/audio/levelAudio'), import('@wildshard/engine/audio/preload')]);
106
+ const profile = await createCatalogueAudio(data);
107
+ return profile.decode(ENGINE_MUSIC_STYLE, cachedBytes, serialDecode(decodeBytes));
108
+ },
109
+ lend: (bank, scope) => { audio.lendLevelBank(bank, scope); },
110
+ frame: (run, scope) => { app.addContentSystem({ id: `grid.plot-audio.${instance}`, phase: 'update', after: ['engine.player.update'], run }, scope); },
111
+ wind: field => field === 'speed' ? wind.speed : wind.gustAt(player.position.x, player.position.z),
112
+ fault: (error) => { console.warn(`[grid] ${instance} plays no score`, error); },
113
+ };
114
+ }
@@ -75,10 +75,11 @@ async function readGridProductIndex(url: string, identity: string, options: Prod
75
75
  return { index, url, options, packed };
76
76
  }
77
77
  /** One immutable file the index declares (a section or a blob), from the content cache or the product URL, size and hash
78
- * checked; a network read is kept in the content cache like an admission's. */
79
- async function readGridProductFile(at: GridProductIndex, path: string, hash: string, size: number): Promise<Uint8Array> {
80
- const { options } = at, base = new URL('.', at.url).href, address = new URL(path, at.url).href;
81
- if(options.firstParty&&options.firstPartyRead!==undefined)return options.firstPartyRead(address,size,undefined,hash);
78
+ * checked; a network read is kept in the content cache like an admission's. `address` is the file's URL (a versioned
79
+ * section's carries its `?v=`). */
80
+ async function readGridProductFile(at: GridProductIndex, path: string, hash: string, size: number, address = new URL(path, at.url).href): Promise<Uint8Array> {
81
+ const { options } = at, base = new URL('.', at.url).href, native = nativeRead(options);
82
+ if(native!==undefined)return native(address,size,undefined,hash);
82
83
  const held = await options.cache?.asset(base, hash) ?? await options.cachedResponse?.(address, hash, size);
83
84
  if ((held === null || held === undefined) && options.offline) throw new Error(`Missing cached grid product file ${path}`);
84
85
  const bytes = held ?? (at.packed.has(hash) ? await at.packed.read(hash) : await boundedResponse(await options.fetch(address), size));
@@ -93,11 +94,60 @@ async function readGridProductFile(at: GridProductIndex, path: string, hash: str
93
94
  }
94
95
  return bytes;
95
96
  }
97
+ /** OFFLINE OF8: one read per section URL in a load. The far ring's byte charge, the far proxy and the near proxy each read a
98
+ * neighbour's world/tiles (and both proxies its look), at once or a few hundred ms apart, and the audit saw one section URL
99
+ * read up to 5 times in a load. A read in flight is shared; each caller parses its own copy. */
100
+ const sectionReads = new Map<string, Promise<Uint8Array>>();
101
+ /** A first-party section's verified bytes, kept after the read settles so the next caller in the same load reads none. Its
102
+ * URL names its hash, so a kept copy is never stale. Least recently used leaves first past `SECTION_BYTES` (one load's
103
+ * neighbour sections are about 0.3-1 MB; the largest seen is 73 KB). */
104
+ const settledSections = new Map<string, Uint8Array>();
105
+ const SECTION_BYTES = 2 * 1024 * 1024;
106
+ let settledBytes = 0;
107
+ function keepSection(key: string, bytes: Uint8Array): void {
108
+ if (bytes.length > SECTION_BYTES || settledSections.has(key)) return;
109
+ settledSections.set(key, bytes); settledBytes += bytes.length;
110
+ for (const [oldest, held] of settledSections) {
111
+ if (settledBytes <= SECTION_BYTES) break;
112
+ settledSections.delete(oldest); settledBytes -= held.length;
113
+ }
114
+ }
115
+ /** A first-party section's URL carries `?v=` and the first 8 hex of the hash its index declares, as the cook names it in a
116
+ * spawn manifest (`shardCook.ts` productFile), so the service worker's `immutable()` keeps it and a spawn download's copy
117
+ * answers it. A third-party product's file keeps its bare URL. */
118
+ function gridSectionAddress(at: GridProductIndex, path: string, hash: string): string {
119
+ const address = new URL(path, at.url);
120
+ if (nativeRead(at.options) !== undefined) address.searchParams.set('v', hash.slice(0, 8));
121
+ return address.href;
122
+ }
123
+ /** The build-owned reader a first-party product reads through (undefined: the checked network and content-cache path). */
124
+ function nativeRead(options: ProductOptions): ProductOptions['firstPartyRead'] {
125
+ return options.firstParty ? options.firstPartyRead : undefined;
126
+ }
96
127
  /** One hash-verified section of the index, parsed (null when the index has none). */
97
128
  async function readGridSection(at: GridProductIndex, name: string): Promise<unknown> {
98
129
  const section = at.index.sections.find(row => row.name === name);
99
130
  if (section === undefined) return null;
100
- return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(await readGridProductFile(at, section.path, section.hash, section.bytes)));
131
+ const address = gridSectionAddress(at, section.path, section.hash), versioned = nativeRead(at.options) !== undefined;
132
+ const decode = (bytes: Uint8Array): unknown => JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
133
+ // Only a first-party section is kept once settled: the checked path has its own content cache and revalidation.
134
+ const held = versioned ? settledSections.get(`${address} ${section.hash}`) : undefined;
135
+ if (held !== undefined) {
136
+ const kept = `${address} ${section.hash}`;
137
+ settledSections.delete(kept); settledSections.set(kept, held);
138
+ return decode(held);
139
+ }
140
+ // an offline caller on the checked path refuses what an online one would fetch, so they never share a read
141
+ const key = `${address} ${section.hash} ${String(at.options.offline)}`;
142
+ let reading = sectionReads.get(key);
143
+ if (reading === undefined) {
144
+ const read = readGridProductFile(at, section.path, section.hash, section.bytes, address);
145
+ reading = read;
146
+ sectionReads.set(key, read);
147
+ const forget = (): void => { if (sectionReads.get(key) === read) sectionReads.delete(key); };
148
+ void read.then(bytes => { forget(); if (versioned) keepSection(`${address} ${section.hash}`, bytes); return bytes; }, forget);
149
+ }
150
+ return decode(await reading);
101
151
  }
102
152
  /** One hash-verified section of a product's bounded index (null when the index has none). No runtime or asset is admitted. */
103
153
  async function readGridProductSection(url: string, identity: string, name: string, options: ProductOptions): Promise<unknown> {
@@ -110,7 +110,7 @@ export async function installPlatformRoadSliced(input: PlatformRoadInput, pause:
110
110
  /** the layout's pieces standing at points `within` accepts (the rail stays: it belongs to the void floor) */
111
111
  function layoutWithin(layout: RoadLayout, within: (x: number, z: number) => boolean): RoadLayout {
112
112
  return { segments: layout.segments.filter(s => within(s.centre.x, s.centre.z)), junctions: layout.junctions.filter(j => within(j.centre.x, j.centre.z)),
113
- signs: layout.signs.filter(s => within(s.at.x, s.at.z)), lights: layout.lights.filter(l => within(l.at.x, l.at.z)), rail: layout.rail };
113
+ signs: layout.signs.filter(s => within(s.at.x, s.at.z)), lights: layout.lights.filter(l => within(l.at.x, l.at.z)), rail: layout.rail, edge: layout.edge, holes: layout.holes };
114
114
  }
115
115
 
116
116
  /** Two builds of one road system (A1's ring-first halves) as one: their readouts summed, roots joined, hooks shared. */
@@ -153,7 +153,7 @@ function* platformRoadSteps(input: PlatformRoadInput): Generator<void, PlatformR
153
153
  const road = yield* installRoadLookSteps({ layout, home, scene, scope, solid, cull: culler, admission, overlayLight, retireGeometry,
154
154
  ...(input.grain === undefined ? {} : { grain: input.grain }),
155
155
  ...(input.signs === undefined ? {} : { signs: input.signs }) });
156
- const voidLook = input.voidFloor === false ? null : installVoidLook({ rail: layout.rail, home, scene, scope, solid, admission });
156
+ const voidLook = input.voidFloor === false ? null : installVoidLook({ rail: layout.rail, edge: layout.edge, holes: layout.holes, home, scene, scope, solid, admission });
157
157
  // this build's own boulevard group (a split road adds one per build)
158
158
  let boulevard: Object3D | undefined;
159
159
  for (const child of scene.children) if (child.name === 'grid-boulevard') boulevard = child;
@@ -55,7 +55,8 @@ import { neighbourEdges } from '../../../shared/game/grid/readinessEdges';
55
55
  import { DEVSERVER, gridMode } from './menu';
56
56
  import { gridCells, pageGridInstance } from '../plugin/context';
57
57
  import { prepareHomeMetadata, withInitialHomeMetadata } from './homeMetadata';
58
- import { bootSteppedTiles } from './loadingRings';
58
+ import { bootSteppedTiles, stepRingsUntil } from './loadingRings';
59
+ import { holdSpawnGround, spawnGroundCell, type SpawnGround } from './spawnGround';
59
60
  import type { ResidencyAllocator } from '../../../shared/game/grid/allocator';
60
61
  import type { PageResidency } from './pageResidency';
61
62
  import { PlatformRenderResidency } from './renderResidency';
@@ -67,7 +68,7 @@ import { FarImpostorSchema, type FarImpostor } from '@wildshard/format/shardSect
67
68
  import { bindCellCover, cellCoverPort } from './cellCover';
68
69
  import { FAR_RING, type FarLookRuntime } from '../../../shared/game/grid/farProxy';
69
70
  import { bakedNearFiles, NearPlaceholders, type NearPlaceholderState } from './nearPlaceholderView';
70
- import { PHONE_NEAR_CELLS, placeholderBlocksTiles } from './nearPlaceholderPlan';
71
+ import { PHONE_NEAR_CELLS, admitsCellTiles, placeholderBlocksTiles } from './nearPlaceholderPlan';
71
72
  import { TIER } from '@wildshard/engine/core/tier';
72
73
  import { GridFrame, type GridFrameHost, type GridFrameState } from './frame';
73
74
  import { installHazeBand } from './hazeBand';
@@ -77,7 +78,9 @@ import { ApproachInputsDeferredError } from './productInputs';
77
78
  import { GridViewAdmissions } from './viewAdmissions';
78
79
  import { loadShardfileFar, loadShardfileNear } from './shardfileFar';
79
80
  import { jsonResidentBytes } from '../shardfile/productCost';
80
- import { RAIL_OFFSET, roadLayout } from '../../../shared/game/grid/roadLayout';
81
+ import { withOwner } from '@wildshard/engine/app/ownership';
82
+ import { roadLayout } from '../../../shared/game/grid/roadLayout';
83
+ import { installVoidFloor, rimWalls } from '../../../shared/game/grid/voidFloor';
81
84
  import type { RoadLookState } from './roadLook';
82
85
  import { combinePlatformRoads, installPlatformRoad, installPlatformRoadSliced, type PlatformRoad } from './roadLookPlatform';
83
86
  import { collisionStrips, type CollisionStrip } from '../../../shared/game/grid/collisionStrips';
@@ -105,7 +108,7 @@ import { GAME_STRINGS } from '../../../shared/game/strings';
105
108
  import { GridCellWaitingError, classifyRefusal, pageShardRefusals, refusalReason, type ShardRefusal } from './refusal';
106
109
  import { tileRing } from '../shardfile/tileDriver';
107
110
  import { CellLoading, type CellLoadingInput } from './cellLoading';
108
- import { CellScreen, facingEdge } from './cellScreens';
111
+ import { CellLoadingCard } from './cellScreens';
109
112
  import { readGridSeamData, type GridSeamAddress } from '../../../shared/game/grid/seamData';
110
113
  import { readCompiledGridStrips } from '../../../shared/game/grid/compiledStrips';
111
114
  import { startRoadGrain } from './roadGrainPreparation';
@@ -287,15 +290,9 @@ function farLook(row: unknown): FarLookRuntime { return v.parse(FarRow, row).loo
287
290
  function farImpostorRow(row: unknown): FarImpostor | undefined { return v.parse(FarRow, row).far.impostor; }
288
291
  function farBytes(row: unknown): number { const { far } = v.parse(FarRow, row); return Math.round(far.gpu + far.decoded); }
289
292
 
290
- /** The closed outer rim on the outer road's shoulder: the void's rail (G89; the empty neighbour has no sim to wait for). */
293
+ /** The closed outer rim on the 7 × 7's outer road shoulder (SA34): the void's rail (G89; the empty neighbour has no sim to wait for). */
291
294
  function rimEdges(assembly: GridAssembly, home: Readonly<{ origin: Readonly<{ x: number; z: number }> }>): ReadinessEdge[] {
292
- const xs = assembly.cells.map((c) => c.cell[0]), zs = assembly.cells.map((c) => c.cell[1]), p = assembly.pitch;
293
- const minX = Math.min(...xs) * p - p / 2 - RAIL_OFFSET, maxX = Math.max(...xs) * p + p / 2 + RAIL_OFFSET, minZ = Math.min(...zs) * p - p / 2 - RAIL_OFFSET, maxZ = Math.max(...zs) * p + p / 2 + RAIL_OFFSET;
294
- const cx = (minX + maxX) / 2 - home.origin.x, cz = (minZ + maxZ) / 2 - home.origin.z, hx = (maxX - minX) / 2, hz = (maxZ - minZ) / 2;
295
- return [
296
- { instance: null, x: minX - home.origin.x, z: cz, axis: 'x', halfLength: hz, floor: 0 }, { instance: null, x: maxX - home.origin.x, z: cz, axis: 'x', halfLength: hz, floor: 0 },
297
- { instance: null, x: cx, z: minZ - home.origin.z, axis: 'z', halfLength: hx, floor: 0 }, { instance: null, x: cx, z: maxZ - home.origin.z, axis: 'z', halfLength: hx, floor: 0 },
298
- ];
295
+ return rimWalls(assembly.pitch).map(wall => ({ instance: null, x: wall.x - home.origin.x, z: wall.z - home.origin.z, axis: wall.axis, halfLength: wall.halfLength, floor: 0 }));
299
296
  }
300
297
 
301
298
  type ConstructorPhase = 'fields' | 'lights' | 'home' | 'frame' | 'road' | 'presentation' | 'physics' | 'roots' | 'streaming';
@@ -676,14 +673,8 @@ export class GridSession {
676
673
  return cell.edgeLook === undefined ? look : Object.assign(look, { height: cell.edgeLook.height });
677
674
  })),
678
675
  ports: { closed: (id) => this.live === null || !this.live.live.ready(id) } });
679
- // G578: a waiting cell's loading steps on an in-world screen at the edge the traveller faces; the world stays live
680
- const screen = new CellScreen(host.scene, host.scope);
681
- this.cellLoading = new CellLoading(screen, (waiting) => {
682
- const cell = this.neighbours.find(row => row.instance === waiting); if (cell === undefined) return null;
683
- const centre = { x: cell.origin.x - home.origin.x, z: cell.origin.z - home.origin.z }, world = this.world();
684
- const edge = facingEdge(neighbourEdges(cell, home), centre, world.x - cell.origin.x, world.z - cell.origin.z);
685
- return edge === undefined ? null : { edge: { instance: waiting, x: edge.x, z: edge.z, axis: edge.axis, halfLength: edge.halfLength }, cell: centre, ground: edge.floor };
686
- });
676
+ // QA 2026-11-13: a waiting cell's loading steps on SHARD SELECT's loading card, inset over the live world
677
+ this.cellLoading = new CellLoading(new CellLoadingCard(), (waiting) => this.neighbours.some(row => row.instance === waiting));
687
678
  setParkedMatricesFrozen(true); // G580 T2: a hidden parked world skips matrix updates during its warm-up
688
679
  host.scope.onDispose(() => { this.cellLoading.close(); if (host.heldFrame !== undefined) host.heldFrame.enabled = false; setWarmUpHeld(false); setParkedMatricesFrozen(false); setBuildHeldTimed(false); });
689
680
  // G78: a shimmer line at every shard border on its real ground; G119: SAVING… / SAVE FAILED, RETRY while a crossing waits
@@ -697,6 +688,8 @@ export class GridSession {
697
688
  this.constructorTiming?.('presentation');
698
689
  const nativeOrigin = { origin: { x: 0, z: 0 } };
699
690
  if (preparedRoad?.collidersInstalled !== true) for (const { mesh } of this.strips) installStripCollider(host.physics, mesh, host.scope);
691
+ // SA34: the 7 × 7's empty cells and the band to the rail are walkable void floor at road level, never a fall
692
+ withOwner(host.scope, () => installVoidFloor(host.physics, this.assembly.cells, this.assembly.pitch, false));
700
693
  // The normal world stage owns the home's sockets; this scope adds only rebased neighbours.
701
694
  installEntrySockets(host.physics, host.scope, this.neighbours.map((cell) => ({ x: cell.origin.x - nativeOrigin.origin.x, z: cell.origin.z - nativeOrigin.origin.z })));
702
695
  this.walls = new ReadinessWalls(host.physics, [...this.neighbours.flatMap((cell) => neighbourEdges(cell, nativeOrigin)), ...rimEdges(this.assembly, nativeOrigin)], host.scope);
@@ -1110,10 +1103,11 @@ export class GridSession {
1110
1103
  // cells keep their baked proxy without admitting their full product at boot.
1111
1104
  if (this.startOuterRoad !== null && this.roadSettled && this.host.backgroundReady?.() !== false) { const start = this.startOuterRoad; this.startOuterRoad = null; start(); }
1112
1105
  // DL17 (G872): the cell the player is in, drawn by its regional runtime, admits no second tile copy of itself (the
1113
- // home re-read ~225 of its files after control for it); leaving starts it while the runtime is still resident
1106
+ // home re-read ~225 of its files after control for it); leaving starts it while the runtime is still resident. A
1107
+ // runtime whose ground is those tiles (D189: Pine) still admits them, or its far proxy stays over the spawn
1114
1108
  const drawn = this.live?.runtimeDrawnCell() ?? null;
1115
1109
  if (this.initialFarReady && this.host.backgroundReady?.() !== false) for (const cell of this.neighbours) {
1116
- if (cell.instance === drawn) continue;
1110
+ if (cell.instance === drawn && !admitsCellTiles(cell.instance, drawn, this.clientTiles.owns(cell.instance), findShard(cell.slug)?.cellGround === 'world')) continue;
1117
1111
  const distance = Math.hypot(Math.max(0, Math.abs(at.x - cell.origin.x) - CHUNK_HALF), Math.max(0, Math.abs(at.z - cell.origin.z) - CHUNK_HALF));
1118
1112
  if (this.assembly.approaching(distance, 400 + Math.min(speed, 60) * 4)) void this.admitNeighbour?.(cell).catch(() => undefined);
1119
1113
  }
@@ -1178,6 +1172,28 @@ export class GridSession {
1178
1172
  /** Settles once the road system has landed (or failed): the entry's shader warm-up waits for it, so its programs are warmed. */
1179
1173
  roadLanded(): Promise<void> { return this.roadLanding; }
1180
1174
 
1175
+ /** PINE-FLASH (spawnGround.ts): the loader's `spawnDetail` step holds until the entered cell's ground covers its far
1176
+ * proxy (Pine: its ring tiles, admitted now rather than after T10's background opens), or the ceiling. A cell that
1177
+ * draws its own ground, or none drawn by a runtime, holds nothing. */
1178
+ async prepareSpawnGround(limitMs?: number): Promise<SpawnGround> {
1179
+ const live = this.live, render = this.admitNeighbourRender, drawn = live?.runtimeDrawnCell() ?? null;
1180
+ if (live === null || render === undefined || drawn === null) return 'none';
1181
+ const cell = this.assembly.cell(drawn);
1182
+ const instance = spawnGroundCell(drawn, this.clientTiles.owns(drawn), findShard(cell.slug)?.cellGround === 'world');
1183
+ if (instance === null) return 'none';
1184
+ const feet = live.worldFeet(), start = { x: feet.x - cell.origin.x, z: feet.z - cell.origin.z };
1185
+ const owner = this.host.scope.child(`grid.spawn-ground.${instance}`), prepareOffered = this.clientTiles.prepareOffered;
1186
+ try {
1187
+ return await holdSpawnGround({ instance, admit: () => render(cell), require: (id, keys, level) => this.rings.require(id, keys, level),
1188
+ ...(prepareOffered === undefined ? {} : { spawn: () => prepareOffered(instance, owner, start) }),
1189
+ pump: entry => stepRingsUntil(entry, { frames: () => this.lateFrames,
1190
+ step: () => { if (!this.host.scope.disposed) { const at = this.world(); this.rings.step({ x: at.x, z: at.z, vx: 0, vz: 0 }); } },
1191
+ wait: () => new Promise<void>(resolve => { if (!this.host.scope.disposed) this.host.scope.timeout(16, resolve); }) }),
1192
+ after: ms => new Promise<void>(resolve => { owner.timeout(ms, resolve); }), ...(limitMs === undefined ? {} : { limitMs }) },
1193
+ requirement => { owner.onDispose(requirement.release); });
1194
+ } finally { owner.dispose(); }
1195
+ }
1196
+
1181
1197
  /** Hold the loading screen until every visible neighbour is drawn (or the time limit: the soft walls hold anyway). */
1182
1198
  async ready(limitMs = 20_000): Promise<boolean> {
1183
1199
  for (let waited = 0; ; waited += 16) {
@@ -0,0 +1,68 @@
1
+ /**
2
+ * PINE-FLASH (opus-pineflash, 2026-11-13): control never arrives over the entered cell's coarse far proxy.
3
+ *
4
+ * Pine's runtime draws its pines, grass and road, but its ground is the cell's own L1 / L0 ring tiles (D189). Since engine
5
+ * 93e50340 the entered cell admits them, but only once the grid's background opens (T10: 3 s of play after control), so the
6
+ * first seconds of control showed the far proxy's tan canyon walls around the spawn (opus-rel16's GC spawn shots, v0.1.16).
7
+ *
8
+ * The loader's `spawnDetail` step now holds for that ground: the cell's tile views are admitted at once, every L1 quadrant
9
+ * (the far proxy hides region by region as each uploads) and the spawn's L0 ring are pinned, and the step ends when they
10
+ * are published or after `SPAWN_GROUND_LIMIT_MS`, so a slow tile never hangs the load (the rings keep masking the proxy as
11
+ * the rest arrives in play). A cell whose runtime draws its own ground (Nalati's `cellGround: 'world'`, a runtime holding the
12
+ * tile registration) or a page with no runtime-drawn cell holds nothing: today's path. Driftwood's ground is its ring tiles
13
+ * too (its hill showed the proxy's smooth mound, no stairs, at control), so it holds as well: 0.4 s headless, Pine 0.6 s.
14
+ */
15
+ import type { TileRequirement } from '@wildshard/engine/world/tileStreamer';
16
+
17
+ /** The hold's ceiling (ms). Pine's whole wait measured 0.6 s in a headless preview; past this the loader goes on and the rings finish
18
+ * the ground in play, as they did before the hold. */
19
+ export const SPAWN_GROUND_LIMIT_MS = 8000;
20
+ /** The far proxy's 4 x 4 L1 quadrants (`z * 4 + x`), each hiding one far region when it uploads. */
21
+ export const L1_QUADRANTS: readonly number[] = Array.from({ length: 16 }, (_, key) => key);
22
+
23
+ /** How the hold ended: nothing to hold, ground published, the ceiling, or an admission that failed (the proxy stays). */
24
+ export type SpawnGround = 'none' | 'ready' | 'timeout' | 'failed';
25
+
26
+ /** The entered cell to hold for: drawn by its regional runtime, whose ground is its ring tiles. Null: nothing to hold. */
27
+ export function spawnGroundCell(drawn: string | null, registered: boolean, ownGround: boolean): string | null {
28
+ return drawn !== null && !registered && !ownGround ? drawn : null;
29
+ }
30
+
31
+ /** What one hold needs from the grid session. */
32
+ export interface SpawnGroundPorts {
33
+ readonly instance: string;
34
+ /** offer the cell's tile views to the rings (false: its inputs are deferred, so no tile can come) */
35
+ readonly admit: () => Promise<boolean>;
36
+ /** pin tiles on the page's one streamer (`TileStreamer.require`) */
37
+ readonly require: (instance: string, keys: Iterable<number>, level: 'l1') => TileRequirement;
38
+ /** pin the spawn's L0 ring until `release` (the registration's `prepareOffered`), if the page has one */
39
+ readonly spawn?: () => Promise<void>;
40
+ /** step the rings while `entry` waits and no page frame steps them (`stepRingsUntil`) */
41
+ readonly pump: (entry: Promise<unknown>) => Promise<unknown>;
42
+ /** resolve after `ms` on the page's scope */
43
+ readonly after: (ms: number) => Promise<void>;
44
+ readonly limitMs?: number;
45
+ }
46
+
47
+ /** Hold until the entered cell's ground covers its far proxy and its spawn ring is published, or the ceiling. The caller
48
+ * releases what the hold pinned (its scope) once this settles. */
49
+ export async function holdSpawnGround(ports: SpawnGroundPorts, held: (requirement: TileRequirement) => void): Promise<SpawnGround> {
50
+ let over = false;
51
+ const ground = (async (): Promise<SpawnGround> => {
52
+ try {
53
+ if (!await ports.admit()) return 'none';
54
+ if (over) return 'timeout'; // admitted after the ceiling: the caller has released its pins, so pin nothing new
55
+ const coarse = ports.require(ports.instance, L1_QUADRANTS, 'l1'); held(coarse);
56
+ await Promise.all([coarse.ready, ports.spawn?.()]);
57
+ return 'ready';
58
+ } catch (error: unknown) {
59
+ // past the ceiling the caller's release rejects the pins: that is the hold ending, not a failure
60
+ if (!over) console.warn(`[grid] ${ports.instance} spawn ground not held`, error);
61
+ return 'failed';
62
+ }
63
+ })();
64
+ const ceiling = (async (): Promise<SpawnGround> => { await ports.after(ports.limitMs ?? SPAWN_GROUND_LIMIT_MS); return 'timeout'; })();
65
+ const ended = Promise.race([ground, ceiling]);
66
+ void ports.pump(ended);
67
+ try { return await ended; } finally { over = true; }
68
+ }
@@ -1,20 +1,21 @@
1
1
  /**
2
2
  * The VR void past the outer road (SHARD-PLATFORM SF17b look, G77 / G89 "A: Tron grid + rail"): a black unlit floor with
3
- * cyan grid lines to the horizon, starting at the rail on the outer road's shoulder, and the thin glowing cyan rail itself
4
- * on short posts. The rail is where the grid's closed rim walls stand (`session.ts` `rimEdges`), so the wall you bump is
5
- * the rail you see.
3
+ * cyan grid lines to the horizon, starting on the outer road's shoulder, and the thin glowing cyan rail itself on short
4
+ * posts. SA34: the floor is walkable out to the rail on the 7 × 7's outer shoulder (`voidFloor.ts`), and an empty cell inside
5
+ * the placed rectangle is a square of the same floor. The rail is where the grid's closed rim walls stand (`session.ts`
6
+ * `rimEdges`), so the wall you bump is the rail you see.
6
7
  *
7
- * Cheap by construction: the floor is one square annulus (8 triangles) with a grid shader (no textures, no lights, no fog);
8
+ * Cheap by construction: the floor is one square annulus (8 triangles) plus two per empty-cell square, with a grid shader (no textures, no lights, no fog);
8
9
  * the rail and posts are part of the road system's one solid material (`roadSolid.ts`). Lines are anti-aliased with screen derivatives and fade
9
10
  * as they shrink under a pixel, so the horizon stays clean instead of shimmering.
10
11
  */
11
12
  import { BufferAttribute, BufferGeometry, Color, Group, Mesh, type Object3D, ShaderMaterial } from 'three';
12
13
  import { uniformPart, type SolidPart } from './roadSolid';
13
14
  import type { GridCell } from '../../../shared/game/grid/assembly';
14
- import type { LookScope, RailBox } from '../../../shared/game/grid/roadLayout';
15
+ import type { CellSquare, LookScope, RailBox } from '../../../shared/game/grid/roadLayout';
15
16
  import type { PlatformRenderAdmission, PlatformRenderBytePlan } from './renderResidency';
16
17
 
17
- /** The void floor's reach past the rail (well beyond the camera's 2.6 km far plane). */
18
+ /** The void floor's reach past its edge (to the grid camera's 6 km far plane, `FAR_RING.drawDistance`). */
18
19
  const REACH = 6000;
19
20
  /** The floor sits a hair above road level so it covers the outer strip beyond the rail. */
20
21
  const FLOOR_Y = 0.04;
@@ -75,28 +76,33 @@ function voidFloorMaterial(home: GridCell, rail: readonly [number, number, numbe
75
76
  return material;
76
77
  }
77
78
 
78
- /** The void floor: a square annulus from the rail box out to REACH, in the home frame. */
79
- function floorGeometry(box: RailBox, home: GridCell): BufferGeometry {
79
+ /** The void floor: a square annulus from the floor's edge box out to REACH, and one square per empty cell (SA34), in the home frame. */
80
+ function floorGeometry(box: RailBox, holes: readonly CellSquare[], home: GridCell): BufferGeometry {
80
81
  const x0 = box.minX - home.origin.x, x1 = box.maxX - home.origin.x, z0 = box.minZ - home.origin.z, z1 = box.maxZ - home.origin.z;
81
82
  const X0 = x0 - REACH, X1 = x1 + REACH, Z0 = z0 - REACH, Z1 = z1 + REACH;
82
- // inner ring 0..3 (sw, se, ne, nw), outer ring 4..7
83
+ // inner ring 0..3 (sw, se, ne, nw), outer ring 4..7, then four corners per hole
83
84
  const p = [x0, z0, x1, z0, x1, z1, x0, z1, X0, Z0, X1, Z0, X1, Z1, X0, Z1];
84
- const position = new Float32Array(24);
85
- for (let k = 0; k < 8; k++) { position[k * 3] = p[k * 2] ?? 0; position[k * 3 + 1] = FLOOR_Y; position[k * 3 + 2] = p[k * 2 + 1] ?? 0; }
85
+ for (const hole of holes) {
86
+ const hx0 = hole.x - hole.hx - home.origin.x, hx1 = hole.x + hole.hx - home.origin.x, hz0 = hole.z - hole.hz - home.origin.z, hz1 = hole.z + hole.hz - home.origin.z;
87
+ p.push(hx0, hz0, hx1, hz0, hx1, hz1, hx0, hz1);
88
+ }
89
+ const count = p.length / 2, position = new Float32Array(count * 3);
90
+ for (let k = 0; k < count; k++) { position[k * 3] = p[k * 2] ?? 0; position[k * 3 + 1] = FLOOR_Y; position[k * 3 + 2] = p[k * 2 + 1] ?? 0; }
86
91
  // each side a quad between inner edge (a, b) and outer edge (A, B), wound to face up
87
- const index = new Uint16Array([0, 4, 5, 0, 5, 1, 1, 5, 6, 1, 6, 2, 2, 6, 7, 2, 7, 3, 3, 7, 4, 3, 4, 0].map((n) => n));
88
- for (let k = 0; k < index.length; k += 3) { const b = index[k + 1] ?? 0; index[k + 1] = index[k + 2] ?? 0; index[k + 2] = b; }
92
+ const ring = [0, 4, 5, 0, 5, 1, 1, 5, 6, 1, 6, 2, 2, 6, 7, 2, 7, 3, 3, 7, 4, 3, 4, 0];
93
+ for (let k = 0; k < ring.length; k += 3) { const b = ring[k + 1] ?? 0; ring[k + 1] = ring[k + 2] ?? 0; ring[k + 2] = b; }
94
+ // a hole's square (sw, se, ne, nw), wound to face up
95
+ for (let h = 0; h < holes.length; h++) { const o = 8 + h * 4; ring.push(o, o + 2, o + 1, o, o + 3, o + 2); }
96
+ const index = new Uint16Array(ring);
89
97
  const g = new BufferGeometry().setAttribute('position', new BufferAttribute(position, 3)).setIndex(new BufferAttribute(index, 1));
90
98
  g.computeBoundingSphere();
91
99
  return g;
92
100
  }
93
101
 
94
- /** The floor's vertices and Uint16 indices (`floorGeometry`: a square annulus, 8 corners, 4 quads). */
95
- const FLOOR_VERTICES = 8, FLOOR_INDICES = 24;
96
- /** G144's preflight for the void: the floor's retained position and index buffers (CPU + GPU; no texture). The rail and its
97
- * posts belong to the deck's plan. */
98
- export function voidFloorPlan(): PlatformRenderBytePlan {
99
- const bytes = FLOOR_VERTICES * 3 * Float32Array.BYTES_PER_ELEMENT + FLOOR_INDICES * Uint16Array.BYTES_PER_ELEMENT;
102
+ /** G144's preflight for the void: the floor's retained position and index buffers (CPU + GPU; no texture): the annulus's 8
103
+ * corners and 24 indices, and 4 corners and 6 indices per empty-cell square. The rail and its posts belong to the deck's plan. */
104
+ export function voidFloorPlan(holes = 0): PlatformRenderBytePlan {
105
+ const bytes = (8 + 4 * holes) * 3 * Float32Array.BYTES_PER_ELEMENT + (24 + 6 * holes) * Uint16Array.BYTES_PER_ELEMENT;
100
106
  return { id: 'road.void', jsBytes: bytes, gpuBytes: bytes };
101
107
  }
102
108
 
@@ -140,21 +146,21 @@ class SolidMesher {
140
146
  * (unlit cyan, in ≤ 50 m beams so the per-view cull can drop what is out of view) and its posts go to `solid`, the road
141
147
  * system's one solid material (SF17b per-view budget).
142
148
  */
143
- export function installVoidLook(input: { readonly rail: RailBox; readonly home: GridCell; readonly scene: Object3D; readonly scope: LookScope; readonly solid: (part: SolidPart) => void; readonly admission?: PlatformRenderAdmission }): VoidLookState {
144
- const { rail: box, home, scene, scope } = input, group = new Group();
149
+ export function installVoidLook(input: { readonly rail: RailBox; readonly edge: RailBox; readonly holes: readonly CellSquare[]; readonly home: GridCell; readonly scene: Object3D; readonly scope: LookScope; readonly solid: (part: SolidPart) => void; readonly admission?: PlatformRenderAdmission }): VoidLookState {
150
+ const { rail: box, edge, holes, home, scene, scope } = input, group = new Group();
145
151
  group.name = 'grid-void';
146
152
  const x0 = box.minX - home.origin.x, x1 = box.maxX - home.origin.x, z0 = box.minZ - home.origin.z, z1 = box.maxZ - home.origin.z;
147
153
  const owned = { value: 0 };
148
154
  let drawn: Mesh | null = null;
149
155
  const build = (owner: LookScope): void => {
150
156
  const floorMaterial = voidFloorMaterial(home, [x0, x1, z0, z1], owned);
151
- const floor = new Mesh(floorGeometry(box, home), floorMaterial);
157
+ const floor = new Mesh(floorGeometry(edge, holes, home), floorMaterial);
152
158
  floor.visible = owned.value < 1; drawn = floor;
153
159
  floor.name = 'grid-void-floor'; floor.frustumCulled = false;
154
160
  floor.castShadow = false; floor.receiveShadow = false; floor.matrixAutoUpdate = false; floor.updateMatrix(); group.add(floor);
155
161
  owner.onDispose(() => { if (drawn === floor) drawn = null; floor.removeFromParent(); floor.geometry.dispose(); floorMaterial.dispose(); });
156
162
  };
157
- if (input.admission === undefined) build(scope); else input.admission.allocate(voidFloorPlan(), build);
163
+ if (input.admission === undefined) build(scope); else input.admission.allocate(voidFloorPlan(holes.length), build);
158
164
  // the rail: thin beams along the four sides (unlit, the HUD's cyan); short dark posts carry it
159
165
  const sides: readonly [number, number, number, number][] = [[x0, z0, x1, z0], [x1, z0, x1, z1], [x1, z1, x0, z1], [x0, z1, x0, z0]];
160
166
  const rail = new SolidMesher(), posts = new SolidMesher(), cyan = CYAN.clone().multiplyScalar(1.6), dark = new Color(0x2b3036);
@@ -22,6 +22,7 @@ import type { CreatureDeathSource } from '../../../shared/game/loot/deaths';
22
22
  import type { ShardContext } from "../plugin/context";
23
23
  import { installEnteredRuntimeService } from '../shard/retainedHooks';
24
24
  import { DynamicBodySlots } from '@wildshard/engine/physics/bodies';
25
+ import { framedPoint } from '@wildshard/engine/ui/hudAdapters';
25
26
 
26
27
  export interface LootShop { readonly isOpen: boolean; render: () => void; dispose: () => void }
27
28
  export interface LootPresentation {
@@ -78,7 +79,8 @@ export function installLoot<A extends LootBody>(h: ScopedLootHost<A>): ScopedLoo
78
79
  const offPayouts = feed.onPayout(({ at, coins: n }) => {
79
80
  if (!live) return;
80
81
  burst.spawn(fell.set(at.x, at.y, at.z), n, () => undefined, () => { flush(); view.chime(); });
81
- projected.set(at.x, at.y + 1.5, at.z).project(h.camera);
82
+ // the payout point is frame-local: at the grid frame's offset like the HUD pins (QA 2026-11-13 row 28)
83
+ framedPoint(projected.set(at.x, at.y + 1.5, at.z), projected).project(h.camera);
82
84
  if (chip !== null && projected.z < 1 && Math.abs(projected.x) < 1.1 && Math.abs(projected.y) < 1.1) chip.pop((projected.x + 1) * 0.5 * window.innerWidth, (1 - projected.y) * 0.5 * window.innerHeight, n);
83
85
  });
84
86
  lifetime.onDispose(offPayouts);
@@ -17,7 +17,7 @@ import { mobileDevice } from '@wildshard/engine/boot/titleArrival';
17
17
  import { dropFirstPlay, firstPlayDone, startFirstPlay } from '@wildshard/engine/boot/firstPlayMark';
18
18
  import { lowPowerOn } from '@wildshard/engine/core/graphicsMode';
19
19
  import { askNameOnce, nameAskDue } from '@wildshard/engine/ui/namePrompt';
20
- import { lastEnd } from '@wildshard/engine/boot/lastEnd';
20
+ import { lastEnd, type LastEnd } from '@wildshard/engine/boot/lastEnd';
21
21
  import { setDev } from '@wildshard/engine/core/devMode';
22
22
  import { buildTitleDeck, titleCards, type TitleDeck, type TitleDeckOptions } from './titleDeck';
23
23
  import { gridEntryShown, menuMode, gridMode } from './grid/menu';
@@ -204,6 +204,9 @@ export function buildTitleMenu(opts: TitleMenuOptions): TitleMenu {
204
204
  const startPrefetch = (): void => {
205
205
  if (started || opts.active !== null) return;
206
206
  started = true;
207
+ // OFFLINE OF5a: a title that stays 10 s asks the worker to hold this build's code, so an update seen only here still
208
+ // launches offline; the worker does it only on a device that held an older build (a first visit reads nothing, S2)
209
+ owner.timeout(10_000, () => { if (!leavingTitle) { document.documentElement.dataset['wsTitleSettled'] = '1'; document.dispatchEvent(new Event('ws:title-settled')); } });
207
210
  owner.raf(() => {
208
211
  const choice = titlePrefetchChoice(saves), selectedMode = gridMode(mode().devserver, mode());
209
212
  const target = titlePrefetchTarget(choice.read(), titleManifests(), mode().developer);
@@ -258,11 +261,16 @@ export interface GridTitle { readonly onGrid: () => void; readonly note: string;
258
261
  /** Return the installed title action and note for the grid entry. */
259
262
  export function installGridTitle(): GridTitle {
260
263
  dropGridIntent();
261
- const end = lastEnd();
262
264
  const loop = gridRecoveryLoop();
263
- // QB6: a standalone world's unexpected end gets the same one line, by the world's name
265
+ return { onGrid: enterGrid, note: endedNote(lastEnd(), loop), ...(loop ? { screen: 'select' } : {}) };
266
+ }
267
+
268
+ /** The title's one line about the previous page's unexpected end: the grid's, or a standalone world's by its name (QB6).
269
+ * OF14: the world's name wins over the grid's recovery loop, which a one-shard page's crash inside the grid's 10-minute
270
+ * recovery guard trips too (Signal Dunes' offline failure said "Infinite Wildshard ended unexpectedly last time"). */
271
+ export function endedNote(end: Pick<LastEnd, 'kind' | 'mode' | 'slug'>, loop: boolean, find: (slug: string) => { readonly name: string } | undefined = findTitleManifest): string {
264
272
  const world = end.kind === 'unexpected' && end.mode !== 'grid' ? end.slug : '';
265
- const name = world.length === 0 ? '' : findTitleManifest(world)?.name ?? world;
266
- return { onGrid: enterGrid, note: loop || (end.kind === 'unexpected' && end.mode === 'grid') ? GAME_STRINGS.grid.ended : name !== '' ? GAME_STRINGS.grid.shardEnded(name) : '',
267
- ...(loop ? { screen: 'select' } : {}) };
273
+ const name = world.length === 0 ? '' : find(world)?.name ?? world;
274
+ if (name !== '') return GAME_STRINGS.grid.shardEnded(name);
275
+ return loop || (end.kind === 'unexpected' && end.mode === 'grid') ? GAME_STRINGS.grid.ended : '';
268
276
  }
@@ -2,6 +2,7 @@ import { diagnosticNow } from '@wildshard/engine/core/clock';
2
2
  import type { TouchVerbSpec } from '@wildshard/engine/input/InputService';
3
3
  import type { LevelContext } from '@wildshard/engine/level/context';
4
4
  import { hudSlots, type DiscOpts } from '@wildshard/engine/ui/hudSlots';
5
+ import { frameEye, framedPoint } from '@wildshard/engine/ui/hudAdapters';
5
6
  import { uiScope } from '@wildshard/engine/ui/ownership';
6
7
  import * as THREE from 'three';
7
8
  import './ride.css';
@@ -36,7 +37,7 @@ const arcPath = (cx: number, cy: number, r: number, a0: number, a1: number): str
36
37
  return `M${p0x.toFixed(1)} ${p0y.toFixed(1)} A${r} ${r} 0 0 1 ${p1x.toFixed(1)} ${p1y.toFixed(1)}`;
37
38
  };
38
39
 
39
- const _p = new THREE.Vector3();
40
+ const _p = new THREE.Vector3(), _eye = new THREE.Vector3();
40
41
 
41
42
  export class RideHUD {
42
43
  readonly scope: ReturnType<typeof uiScope> = uiScope('RideHUD');
@@ -236,7 +237,8 @@ export class RideHUD {
236
237
  }
237
238
  if (tg.name.textContent !== mt.name) tg.name.textContent = mt.name;
238
239
  const tag = tg.el;
239
- const d = _p.fromArray(mt.position).distanceTo(this.camera.position);
240
+ // a horse stands in the frame's own coordinates; the eye there is the camera less the grid frame's offset (QA 11-13 row 28)
241
+ const d = _p.fromArray(mt.position).distanceTo(frameEye(this.camera, _eye));
240
242
  _p.fromArray(mt.position); _p.y += this.profile.tagHeight * mt.scale;
241
243
  const vis = m.horse !== mt.id && !mt.hidden && d < this.profile.tagRange && d > 2 && this.project(_p);
242
244
  if (vis) tag.style.transform = `translate(${_p.x.toFixed(1)}px, ${_p.y.toFixed(1)}px) translate(-50%, -100%)`;
@@ -244,9 +246,9 @@ export class RideHUD {
244
246
  }
245
247
  }
246
248
 
247
- /** world → CSS px in `_p` (in place); false when behind the camera */
249
+ /** a frame-local point → CSS px in `_p` (in place), at the grid frame's offset like the HUD pins; false when behind the camera */
248
250
  private project(w: THREE.Vector3): boolean {
249
- _p.copy(w).project(this.camera);
251
+ framedPoint(w, _p).project(this.camera);
250
252
  if (_p.z > 1 || _p.z < -1) return false;
251
253
  const r = this.root.getBoundingClientRect();
252
254
  _p.set((_p.x * 0.5 + 0.5) * r.width, (-_p.y * 0.5 + 0.5) * r.height, 0);