@threenative/core 0.3.3 → 0.3.5

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 (182) hide show
  1. package/capabilities.json +2019 -59
  2. package/dist/{assets-CYKk2WTu.d.ts → assets-CqvE429w.d.ts} +45 -3
  3. package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
  4. package/dist/{canvas-layer-C1SnMoJ-.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
  5. package/dist/{game-D_6r-k4Y.d.ts → game-Bj8G1wmD.d.ts} +242 -17
  6. package/dist/hot.d.ts +5 -5
  7. package/dist/index.d.ts +1131 -105
  8. package/dist/index.js +15201 -4782
  9. package/dist/model-lod-BDAUYgsS.d.ts +197 -0
  10. package/dist/playtest.d.ts +6 -4
  11. package/dist/playtest.js +84 -11
  12. package/dist/react-css.d.ts +62 -0
  13. package/dist/react-css.js +591 -0
  14. package/dist/react.d.ts +2 -2
  15. package/dist/{renderer-Cy4qeBOA.d.ts → renderer-9yEo9hPa.d.ts} +676 -21
  16. package/dist/terrain-jobs-worker.d.ts +2 -0
  17. package/dist/terrain-jobs-worker.js +130 -0
  18. package/dist/ui-layer.d.ts +5 -3
  19. package/dist/ui-layer.js +59 -8
  20. package/dist/world.d.ts +1596 -17
  21. package/dist/world.js +17035 -521
  22. package/gpl/fixtures/make_world_fixture.py +184 -0
  23. package/gpl/recipes/_common.py +11 -0
  24. package/gpl/recipes/decimate.py +11 -5
  25. package/gpl/recipes/export_world.py +699 -0
  26. package/mcp/blender-server.mjs +61 -4
  27. package/mcp/blender.mjs +3 -4
  28. package/mcp/engine-server.mjs +55 -21
  29. package/mcp/servers.mjs +4 -4
  30. package/package.json +15 -9
  31. package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
  32. package/patches/three@0.185.1.patch +8246 -389
  33. package/scripts/apply-three-patch.mjs +123 -41
  34. package/src/animation-blend.ts +264 -0
  35. package/src/animation-composition.ts +362 -0
  36. package/src/animation-layers.ts +260 -0
  37. package/src/animation-root-motion.ts +283 -0
  38. package/src/animation.ts +896 -0
  39. package/src/assets.ts +1303 -0
  40. package/src/atmosphere/index.ts +335 -0
  41. package/src/atmosphere/luts.ts +298 -0
  42. package/src/atmosphere/params.ts +323 -0
  43. package/src/audio.ts +912 -0
  44. package/src/billboard.ts +124 -0
  45. package/src/bone-lengths.ts +157 -0
  46. package/src/camera-shake.ts +116 -0
  47. package/src/canvas-layer.ts +47 -0
  48. package/src/clip-audit.ts +401 -0
  49. package/src/clustered-batch.ts +492 -0
  50. package/src/clustered-mesh.ts +638 -0
  51. package/src/compute-driven.ts +176 -0
  52. package/src/compute-timing.ts +318 -0
  53. package/src/config.ts +593 -0
  54. package/src/debug.ts +82 -0
  55. package/src/engine-render-hook.ts +25 -0
  56. package/src/entities.ts +79 -0
  57. package/src/entity-snapshot.ts +53 -0
  58. package/src/flight.ts +683 -0
  59. package/src/fluid-field.ts +748 -0
  60. package/src/fluid-particles.ts +1253 -0
  61. package/src/frame-budget.ts +1368 -0
  62. package/src/game.ts +2390 -0
  63. package/src/geometry-capture.ts +1098 -0
  64. package/src/gpu-class.ts +160 -0
  65. package/src/gpu-frame-observation.ts +424 -0
  66. package/src/gpu-readback.ts +143 -0
  67. package/src/gpu-scene-bvh.ts +464 -0
  68. package/src/grounding.ts +100 -0
  69. package/src/hot.ts +161 -0
  70. package/src/import-meta.d.ts +13 -0
  71. package/src/index.ts +1536 -0
  72. package/src/input.ts +690 -0
  73. package/src/instanced-batch-lod.ts +283 -0
  74. package/src/instanced-batch.ts +274 -0
  75. package/src/interpolation.ts +129 -0
  76. package/src/launch-diagnostics.ts +161 -0
  77. package/src/loop.ts +564 -0
  78. package/src/matrix-world.ts +245 -0
  79. package/src/merge-parts.ts +812 -0
  80. package/src/model-lod.ts +1315 -0
  81. package/src/net-protocol.ts +333 -0
  82. package/src/net-session.ts +477 -0
  83. package/src/net.ts +80 -0
  84. package/src/ocean/fft.ts +72 -0
  85. package/src/ocean/spectral.ts +728 -0
  86. package/src/particle-significance.ts +102 -0
  87. package/src/particles.ts +648 -0
  88. package/src/path-follow.ts +175 -0
  89. package/src/picking.ts +250 -0
  90. package/src/pipeline-census.ts +1566 -0
  91. package/src/platform.ts +210 -0
  92. package/src/playtest.ts +839 -0
  93. package/src/pointer-events.ts +411 -0
  94. package/src/pose-measure.ts +435 -0
  95. package/src/profiling/FrameCounters.ts +231 -0
  96. package/src/profiling/Spans.ts +548 -0
  97. package/src/profiling/opacity-convention.ts +21 -0
  98. package/src/profiling/render-list-validate.ts +175 -0
  99. package/src/profiling/render-trap-audit.ts +84 -0
  100. package/src/profiling/scene-warning.ts +190 -0
  101. package/src/profiling/span-probes.ts +191 -0
  102. package/src/profiling/unlit-foliage-warning.ts +149 -0
  103. package/src/projection-apply.ts +1529 -0
  104. package/src/projection-marker.ts +142 -0
  105. package/src/projection-plan.ts +1258 -0
  106. package/src/projection-skinned.ts +419 -0
  107. package/src/projection-stability.ts +409 -0
  108. package/src/projection-uniform.ts +328 -0
  109. package/src/random.ts +41 -0
  110. package/src/react-css.ts +604 -0
  111. package/src/react-glyphs.ts +114 -0
  112. package/src/react-host.ts +576 -0
  113. package/src/react-layout.ts +265 -0
  114. package/src/react.ts +60 -0
  115. package/src/render/alpha-antialiasing.ts +159 -0
  116. package/src/render/batched-velocity.ts +126 -0
  117. package/src/render/chain.ts +1021 -0
  118. package/src/render/daylight.ts +189 -0
  119. package/src/render/depth-pyramid.ts +596 -0
  120. package/src/render/foliage-alpha.ts +166 -0
  121. package/src/render/material-key.ts +60 -0
  122. package/src/render/mesh-pool.ts +144 -0
  123. package/src/render/probe-volume.ts +1668 -0
  124. package/src/render/resolution-subrect.ts +253 -0
  125. package/src/render/velocity.ts +442 -0
  126. package/src/render/virtual-shadow-pages.ts +827 -0
  127. package/src/render/virtual-shadow-partial.ts +174 -0
  128. package/src/render/virtual-shadow.ts +3330 -0
  129. package/src/render/world-impostor-surface.ts +722 -0
  130. package/src/render/world-impostor.ts +558 -0
  131. package/src/render-camera-cull.ts +441 -0
  132. package/src/render-pass-budget.ts +501 -0
  133. package/src/renderProjection.ts +758 -0
  134. package/src/renderer-config.ts +127 -0
  135. package/src/renderer.ts +1847 -0
  136. package/src/replay-protocol.ts +85 -0
  137. package/src/replay.ts +205 -0
  138. package/src/resolution-scaler.ts +819 -0
  139. package/src/rig-preparation.ts +271 -0
  140. package/src/ripple-field.ts +432 -0
  141. package/src/scale.ts +109 -0
  142. package/src/scene.ts +239 -0
  143. package/src/schedule.ts +155 -0
  144. package/src/skeletal-mesh.ts +61 -0
  145. package/src/skeleton.ts +100 -0
  146. package/src/snow-field.ts +744 -0
  147. package/src/softbody-topology.ts +269 -0
  148. package/src/softbody.ts +516 -0
  149. package/src/sprite-animator.ts +222 -0
  150. package/src/startup-readiness.ts +386 -0
  151. package/src/state.ts +66 -0
  152. package/src/static-transform.ts +274 -0
  153. package/src/storage-buffer.ts +253 -0
  154. package/src/streaming.ts +308 -0
  155. package/src/target-fps.ts +92 -0
  156. package/src/terrain-jobs-worker.ts +17 -0
  157. package/src/terrain-jobs.ts +353 -0
  158. package/src/textures.ts +39 -0
  159. package/src/tracers.ts +237 -0
  160. package/src/ui-bridge.ts +368 -0
  161. package/src/ui-hit-regions.ts +380 -0
  162. package/src/ui-layer.ts +83 -0
  163. package/src/ui-state.ts +220 -0
  164. package/src/version.ts +2 -0
  165. package/src/viewport.ts +253 -0
  166. package/src/warmup.ts +1357 -0
  167. package/src/water-surface.ts +384 -0
  168. package/src/wave-field.ts +524 -0
  169. package/src/world-capabilities.ts +131 -0
  170. package/src/world-cell-proxy.ts +392 -0
  171. package/src/world-cells.ts +10564 -0
  172. package/src/world-gpu-scene.ts +3354 -0
  173. package/src/world-heightmap.ts +82 -0
  174. package/src/world-package.ts +469 -0
  175. package/src/world-passes.ts +582 -0
  176. package/src/world-region.ts +17 -0
  177. package/src/world-terrain-splat.ts +564 -0
  178. package/src/world-tiles.ts +3826 -0
  179. package/src/world-topology.ts +370 -0
  180. package/src/world-validate.ts +48 -0
  181. package/src/world.ts +805 -0
  182. package/dist/gpu-readback-CMklJs6r.d.ts +0 -112
@@ -0,0 +1,819 @@
1
+ /**
2
+ * The adaptive drawing-buffer scale: PRD-228 Change A's loop.
3
+ *
4
+ * A game reaches its `display.maxFps` target without hand-authoring a resolution constant.
5
+ * Bayview's own constant took an afternoon and three ladder rungs to find on a physical Pixel 8;
6
+ * the next game would have repeated that from scratch, which is what makes the loop framework
7
+ * work rather than game work.
8
+ *
9
+ * Every number below is pre-registered in the PRD before this file existed and is read from one
10
+ * constant block. A controller tuned inside its own implementation until a playtest went green is
11
+ * a controller nobody can argue with afterwards, so the values move by editing the PRD.
12
+ *
13
+ * Nothing here touches the overlay surface, the camera or the aspect ratio: only the 3D drawing
14
+ * buffer moves, which is the arrangement the device ladder measured and accepted.
15
+ */
16
+
17
+ import type { GpuClass } from "./gpu-class.js";
18
+
19
+ /** How the active scale was arrived at, reported beside every fps number. */
20
+ export type ScaleSource = "pinned" | "auto" | "auto-pinned";
21
+
22
+ export const RESOLUTION_SCALER = {
23
+ /**
24
+ * Ratio 0.85 linear, so each step is 0.72x the pixels. Coarse on purpose: every step
25
+ * reallocates render targets on WebGPU, and fine granularity buys smoothness with hitches.
26
+ */
27
+ rungs: [1.0, 0.85, 0.72, 0.61, 0.52, 0.44, 0.38, 0.32, 0.27, 0.23] as const,
28
+ /**
29
+ * The lowest rung a desktop may take while nothing in the render chain reconstructs a
30
+ * full-resolution frame from the smaller one.
31
+ *
32
+ * The ladder above is the device arm's, and it ends at 0.23 because a phone buys the pixels back
33
+ * differently. A desktop has nothing: no temporal stage, no reconstruction, just 5% of the
34
+ * pixels stretched across the panel, which is blocky mush rather than a slow frame — and the
35
+ * report at that point claims the budget was met. 0.61 is where surrendering more pixels stops
36
+ * buying frame time worth what it costs to look at, and it is reported as `atFloor` rather than
37
+ * passed in silence. A host whose chain *does* reconstruct the frame says so, and the deep
38
+ * rungs come back; `renderer-config.ts` decides which floor a platform starts with.
39
+ */
40
+ desktopFloorScale: 0.61,
41
+ /**
42
+ * The rung a class of adapter starts on instead of the ceiling; a class not named here starts at
43
+ * 1.0. Only `mobile-low` moves: one rung down is 0.85, close to the 0.8 content scale Unreal's
44
+ * Low Android bucket sets. A start is a guess the first eligible window corrects — it steps down
45
+ * at once and climbs after `upWindows` clean ones — so a wrong row costs windows, not a stuck
46
+ * look. `unknown` and `discrete` keep the ceiling on purpose: a strong GPU is never capped by a
47
+ * table row.
48
+ */
49
+ startScaleByGpuClass: { "mobile-low": 0.85 } as Partial<Record<GpuClass, number>>,
50
+ /**
51
+ * The signal is **fps against the configured target**, not the presented interval.
52
+ *
53
+ * Amended 2026-08-28 from a device arm, before the second implementation. The original triggers
54
+ * were `presented p95 > 14 ms` down and `< 11.5 ms` up. Under FIFO the presented interval is the
55
+ * *panel's* period, not the game's cost: a game locked at 60 fps on a 60 Hz panel reports
56
+ * presented p95 around 17.5 ms, so `> 14` is true forever. A scaffolded template holding
57
+ * 59.99 fps with a `frame p95` of 7.99 ms out of 16.67 was walked to 552x248 and then told it
58
+ * had run out of room. fps is correct in both regimes: it comes from the mean presented
59
+ * interval, so dropped frames pull it down on their own, and a missed target is missed whether
60
+ * or not a panel caps the top.
61
+ */
62
+ targetFpsFraction: 0.98,
63
+ /**
64
+ * The tail guard on the up-step only. A frame that hits its average target while dropping frames
65
+ * has headroom on paper and none in the hand. A vsync-capped panel's own p95 floor sits near
66
+ * 1.05x the budget, comfortably inside this.
67
+ */
68
+ upTailFraction: 1.15,
69
+ /**
70
+ * A window whose presented p99 is at least this many times its p50 is measuring a **stall**, not
71
+ * a frame rate, and the controller defers on it rather than acting.
72
+ *
73
+ * Amended 2026-08-30 from a browser arm, and this is the second time the fps signal has needed
74
+ * correcting for the same underlying reason: `fps` is `1000 / mean`, and a mean is not robust.
75
+ * `sandbox/lumen-hall` on an NVIDIA Turing at 1600x900 spent its second window building WebGPU
76
+ * pipelines for a five-stage TSL chain. Four of that window's 300 frames took about two seconds
77
+ * each — under `hitchMs`, so they stayed in the window and were averaged. The window reported
78
+ * **22.6 fps** with a **p50 of 9.8 ms**, which is 102 fps. The controller read a 2.6x deficit,
79
+ * took its maximum four-rung jump to 0.52, and the game held 145 fps at 832x468 for the next
80
+ * forty seconds — a third of its pixels surrendered to fix a frame rate that was never missed.
81
+ * The window's own record carried the contradiction the whole time and nothing read it.
82
+ *
83
+ * A down-step is also the wrong medicine specifically here: the resize reallocates every render
84
+ * target, which rebuilds pipelines, which is what stalled in the first place.
85
+ *
86
+ * Ten is chosen to separate the two regimes rather than to tune a result, and the numbers are
87
+ * not close. A vsync-capped panel dropping frames — the case `fps`-from-mean exists to catch —
88
+ * has a p99 of one extra panel period, so a ratio near 2; a game that is simply slow has a ratio
89
+ * near 1. The lumen-hall window's ratio was 200. Nothing real sits between.
90
+ */
91
+ stallP99Multiple: 10,
92
+ /**
93
+ * p99 needs at least three bad samples in a 300-frame window. One profiler or debugger pause can
94
+ * still pull fps-from-mean below the down threshold, so the maximum gets the same stall test.
95
+ * Ordinary missed presents are around 2x p50 and stay far below this boundary.
96
+ */
97
+ stallMaxMultiple: 10,
98
+ /** React to a deficit immediately; climb only on sustained evidence. Asymmetric by design. */
99
+ downWindows: 1,
100
+ upWindows: 4,
101
+ /** Eight frames for the sampled GPU reading plus eight for asynchronous query resolution. */
102
+ maxGpuAgeFrames: 16,
103
+ /** Window GPU samples that make the window's own median fresh evidence; see `IScalerWindow.gpu`. */
104
+ minWindowGpuSamples: 4,
105
+ /** The resize frame is itself a hitch and must never feed the controller. */
106
+ cooldownWindows: 1,
107
+ /** Continuous sub-rectangle changes are separated by this many rendered frames. */
108
+ continuousChangeFrames: 8,
109
+ /** Ignore a continuous estimate that moves less than this fraction of the current scale. */
110
+ continuousChangeThreshold: 0.02,
111
+ /** Move this fraction of the way toward an up-estimate to preserve temporal history. */
112
+ continuousUpFraction: 0.9,
113
+ /**
114
+ * Windows discarded outright at the start. "Window 1 always lies" is already the perf CLI's
115
+ * rule; the controller was the one consumer that believed it. A scaffolded template took its
116
+ * only down-step from a cold-start window reading 51.52 fps while still loading, then spent
117
+ * four windows climbing back to where it started.
118
+ */
119
+ warmupWindows: 1,
120
+ /**
121
+ * The most rungs one down-step may cross. Applies only when fresh GPU timing sizes the
122
+ * jump; without it the fallback below probes a single rung and refunds what earns nothing.
123
+ *
124
+ * Falling one rung per decision costs about twenty seconds per rung at the top of the ladder,
125
+ * and the ladder is ten rungs deep — a game starting at DPR-1 physical spent about three
126
+ * minutes visibly at 29 fps before settling. The jump size comes from the deficit: one window
127
+ * cannot separate the fixed cost from the pixel cost, so it attributes the whole deficit to
128
+ * pixels when GPU timing is unavailable. With fresh GPU timing, the GPU deficit sizes the
129
+ * jump instead: host delay cannot be recovered by surrendering pixels.
130
+ */
131
+ maxDownRungs: 4,
132
+ /**
133
+ * Two down-up-down cycles across one boundary inhibit upward probes for this many windows.
134
+ *
135
+ * The PRD pre-registered this reach as 3 windows. That value cannot fire: a down-then-up leg
136
+ * costs at least `cooldownWindows + upWindows` = 5 windows by the rest of this same table, so a
137
+ * 3-window reach only ever sees the up-then-down leg and the guard is dead code. The reach is
138
+ * therefore derived from the table rather than picked — the tightest a down-up leg can be, plus
139
+ * one — and the correction is recorded in the PRD instead of being tuned in here.
140
+ */
141
+ oscillationCycles: 2,
142
+ oscillationWindows: 1 + 4 + 1,
143
+ /**
144
+ * The insensitivity guard. A downward step is a hypothesis — fewer pixels will buy a faster
145
+ * frame — and it is only paid when the measured GPU cost falls with the pixels. On a scene whose
146
+ * cost is geometry, shadow maps or host work, `gpuMs` stays flat and the controller walks the
147
+ * picture to the floor with the frame exactly as slow: a real browser arm held `GPU p50` of
148
+ * 4-11 ms at scale 0.23 against 6-20 ms at scale 1.
149
+ *
150
+ * After a downward step the scaler compares the GPU time that motivated the step against the GPU
151
+ * time at the new rung. A relative gain below `insensitiveGainFraction`, on a step that cut at
152
+ * least `insensitiveMinPixelDrop` of the pixels, means the cost is not pixel-bound: the step is
153
+ * refunded, the rung it came from becomes the floor, and no further pixels are spent until
154
+ * `insensitiveRiseFraction` of sustained rise shows the workload changed.
155
+ */
156
+ insensitiveGainFraction: 0.1,
157
+ insensitiveMinPixelDrop: 0.2,
158
+ /** A rise of the measured signal over this multiple is a changed workload, not the same one. */
159
+ insensitiveRiseFraction: 1.25,
160
+ /** Consecutive above-`insensitiveRiseFraction` windows needed to clear the memory. */
161
+ insensitiveResetWindows: 2,
162
+ /** A restored rung is held this many windows before any downward probe is reconsidered. */
163
+ insensitiveHoldWindows: 2,
164
+ /**
165
+ * Marker gap: one line per this many windows, so at most one per 5 s at a 120 fps target on the
166
+ * 300-frame report window and longer below it, never shorter.
167
+ */
168
+ insensitiveMarkerWindows: 2,
169
+ } as const;
170
+
171
+ /** Printed when a downward step is refunded because the frame did not respond to the pixels. */
172
+ export const RESOLUTION_SCALE_INSENSITIVE_MARKER = "TN_RESOLUTION_SCALE_INSENSITIVE";
173
+
174
+ /** Pixels retained per rung: 0.85 linear on each axis. */
175
+ const RUNG_PIXEL_RATIO = 0.85 * 0.85;
176
+
177
+ /** One rung value to its index, failing closed on anything the ladder does not contain. */
178
+ function rungIndex(value: number, label: string): number {
179
+ const index = RESOLUTION_SCALER.rungs.indexOf(value as never);
180
+ if (index < 0)
181
+ throw new Error(
182
+ `ResolutionScaler ${label} must be one of the pre-registered rung values, received ${String(value)}.`,
183
+ );
184
+ return index;
185
+ }
186
+
187
+ export interface IResolutionScalerOptions {
188
+ /** The `display.maxFps` the loop is holding the budget against. */
189
+ readonly targetFps: number;
190
+ /** Which rung to start on. Must be one of the rungs; defaults to the ceiling. */
191
+ readonly start?: number;
192
+ /**
193
+ * The lowest rung this platform may take, and the rung `atFloor` is reported at. Must be one of
194
+ * the rungs; defaults to the last one, which is the whole ladder the device arm measured with.
195
+ * A desktop host passes `RESOLUTION_SCALER.desktopFloorScale`.
196
+ */
197
+ readonly minScale?: number;
198
+ /**
199
+ * Read whenever the floor is consulted, so the scaler can see a render chain that arrived or
200
+ * changed under it: a chain that reconstructs a display-resolution frame from these pixels
201
+ * lifts the floor for as long as it is installed.
202
+ */
203
+ readonly temporalUpscale?: () => boolean;
204
+ }
205
+
206
+ /** A closed frame-budget window's presentation distribution and optional GPU observation. */
207
+ export interface IScalerWindow {
208
+ /** The last resolved GPU duration and its age; absent/old observations may only probe. */
209
+ readonly gpuMs?: number;
210
+ readonly gpuAgeFrames?: number;
211
+ /**
212
+ * This window's own GPU samples. When the last resolve is past `maxGpuAgeFrames` but the window
213
+ * holds `minWindowGpuSamples` of them, their median stands in: they were drawn in this window.
214
+ */
215
+ readonly gpu?: { readonly p50: number; readonly samples: number };
216
+ /** Frames per second this window achieved, from the mean presented interval. */
217
+ readonly fps: number;
218
+ /** Loop frames represented by this closed window, used for the sub-rectangle cadence guard. */
219
+ readonly frames?: number;
220
+ /** Current drawing surface, used to quantize a continuous estimate to eight pixels. */
221
+ readonly surface?: {
222
+ readonly drawingBufferWidth: number;
223
+ readonly drawingBufferHeight: number;
224
+ readonly resolutionScale: number;
225
+ readonly resolutionSubrect?: boolean;
226
+ };
227
+ /**
228
+ * `p50` says what an ordinary frame cost; `p99` and `max` expose recurring and isolated stalls.
229
+ * The controller needs them to tell a slow game from a stalled one: `fps` alone cannot, because
230
+ * it comes from a mean.
231
+ */
232
+ readonly presented: {
233
+ readonly max: number;
234
+ readonly p50: number;
235
+ readonly p95: number;
236
+ readonly p99: number;
237
+ };
238
+ }
239
+
240
+ export class ResolutionScaler {
241
+ /** fps at or above this is meeting the target. Mutable only through `retarget`. */
242
+ // The three budget fields are placeholders the constructor overwrites before anything can read
243
+ // them; TypeScript cannot see that through the `retarget` call every constructor makes.
244
+ targetFps = 0;
245
+ /**
246
+ * A presented interval above this is a frame that cost more than the target allows: the same
247
+ * bar `targetFps` is, read as a period instead of a rate. Nothing new is chosen here — it is
248
+ * `targetFpsFraction` again, applied to the statistic a mean cannot speak for.
249
+ */
250
+ budgetMs = 0;
251
+ /** presented p95 above this is dropping frames, whatever the mean says. */
252
+ tailMs = 0;
253
+ #index: number;
254
+ #continuousScale: number;
255
+ /** The lowest rung this platform may take; the whole ladder's last index when it states none. */
256
+ readonly #minIndex: number;
257
+ readonly #temporalUpscale: (() => boolean) | undefined;
258
+ #scaleSource: Exclude<ScaleSource, "pinned"> = "auto";
259
+ #cleanWindows = 0;
260
+ #cooldown = 0;
261
+ #warmup = RESOLUTION_SCALER.warmupWindows;
262
+ #windowIndex = 0;
263
+ // Oscillation state. A "boundary" is the higher of the two rungs a step crossed, so a fall
264
+ // from 1.0 and the climb back to it are recognised as the same boundary.
265
+ #guardBoundary = -1;
266
+ #guardDirection = 0;
267
+ #guardLegs = 0;
268
+ #guardCycles = 0;
269
+ #guardWindow = 0;
270
+ #pinWindows = 0;
271
+ // Unknown-GPU probe state. A down-step taken without fresh GPU timing is a hypothesis —
272
+ // fewer pixels will recover the frame rate — and the next decided window tests it against
273
+ // the fps that motivated it. `#probeBlind` records a failed hypothesis: reprobing the same
274
+ // host-bound workload would only flicker, so unknown-GPU probes stop until fresh timing or
275
+ // a recovered frame rate reopens the question. `#lastHealthyWindow` records the last window
276
+ // whose fresh GPU timing showed headroom, so a single gap after healthy timing holds
277
+ // instead of probing.
278
+ #probeFps: number | undefined = undefined;
279
+ #probeBlind = false;
280
+ #lastHealthyWindow = 0;
281
+ // Insensitivity memory. `#insensitiveProbe` is the outstanding hypothesis of a fresh-GPU
282
+ // downward step; `#insensitiveFloor` is the rung a refunded one proved worth holding (no
283
+ // downward step may cross it while it stands), `#insensitiveSignal` its measured GPU time, and
284
+ // `#insensitiveRise` the consecutive windows of sustained rise that clear both.
285
+ #insensitiveProbe:
286
+ | { fromIndex: number; toIndex: number; fromScale?: number; toScale?: number; signal: number }
287
+ | undefined = undefined;
288
+ #insensitiveFloor = -1;
289
+ #insensitiveSignal = 0;
290
+ #insensitiveRise = 0;
291
+ #insensitiveHold = 0;
292
+ #lastInsensitiveMarker = Number.NEGATIVE_INFINITY;
293
+ #continuousFrames = 0;
294
+ #continuousLastChangeFrame = Number.NEGATIVE_INFINITY;
295
+
296
+ constructor(options: IResolutionScalerOptions) {
297
+ const { minScale, start, targetFps, temporalUpscale } = options;
298
+ this.retarget(targetFps);
299
+ this.#index = start === undefined ? 0 : rungIndex(start, "start");
300
+ this.#continuousScale = RESOLUTION_SCALER.rungs[this.#index] ?? 1;
301
+ this.#minIndex =
302
+ minScale === undefined ? RESOLUTION_SCALER.rungs.length - 1 : rungIndex(minScale, "minScale");
303
+ this.#temporalUpscale = temporalUpscale;
304
+ }
305
+
306
+ /**
307
+ * Re-reads the budget when the engine's resolved display target changes.
308
+ *
309
+ * The web cannot know a panel's rate before it has presented a window's worth of frames, so a
310
+ * 120 Hz display starts on the 60 fallback and moves. The rungs and every decision already made
311
+ * stay: only the bar the next window is judged against changes, and a target that is not a
312
+ * positive rate throws exactly as it does in the constructor.
313
+ */
314
+ retarget(targetFps: number): void {
315
+ if (!Number.isFinite(targetFps) || targetFps <= 0)
316
+ throw new Error(
317
+ `ResolutionScaler targetFps must be a finite number greater than zero, received ${String(targetFps)}.`,
318
+ );
319
+ this.targetFps = targetFps * RESOLUTION_SCALER.targetFpsFraction;
320
+ this.budgetMs = 1000 / this.targetFps;
321
+ this.tailMs = (1000 / targetFps) * RESOLUTION_SCALER.upTailFraction;
322
+ }
323
+
324
+ /** The scale the renderer should be applying right now. */
325
+ get scale(): number {
326
+ return this.#continuousScale;
327
+ }
328
+
329
+ /**
330
+ * The lowest rung the scaler may take right now. The platform's own floor, lifted for as long
331
+ * as the render chain reconstructs the frame from the pixels it is being asked to surrender.
332
+ */
333
+ get #limitIndex(): number {
334
+ return this.#temporalUpscale?.() === true ? RESOLUTION_SCALER.rungs.length - 1 : this.#minIndex;
335
+ }
336
+
337
+ get scaleSource(): Exclude<ScaleSource, "pinned"> {
338
+ return this.#scaleSource;
339
+ }
340
+
341
+ /**
342
+ * True when the floor is reached and the tail is still over budget. The window keeps reporting
343
+ * the true scale: a scaler that ran out of room must say so rather than let the number read as
344
+ * a met budget.
345
+ */
346
+ get atFloor(): boolean {
347
+ return this.#atFloor;
348
+ }
349
+ #atFloor = false;
350
+
351
+ /**
352
+ * Feeds one completed frame-budget window. Returns the new scale when this window caused a
353
+ * step, `undefined` otherwise. Allocation-free: no object is constructed on the steady path.
354
+ */
355
+ observe(window: IScalerWindow): number | undefined {
356
+ this.#windowIndex += 1;
357
+ const frames = window.frames;
358
+ this.#continuousFrames +=
359
+ frames !== undefined && Number.isFinite(frames) && frames > 0 ? Math.floor(frames) : 1;
360
+ if (this.#scaleSource === "auto-pinned" && --this.#pinWindows === 0) {
361
+ this.#scaleSource = "auto";
362
+ this.#guardLegs = this.#guardCycles = this.#cleanWindows = 0;
363
+ // The loop propagates scaleSource only when a scale is returned, including an unchanged one.
364
+ return this.scale;
365
+ }
366
+ if (this.#warmup > 0) {
367
+ this.#warmup -= 1;
368
+ return undefined;
369
+ }
370
+ if (this.#cooldown > 0) {
371
+ this.#cooldown -= 1;
372
+ return undefined;
373
+ }
374
+ // A stalled window is not a measurement of the frame rate, in either direction: acting on the
375
+ // mean would cut resolution the game did not need, and counting it clean would climb on a
376
+ // window that was mostly spent stopped. Deferring means neither — the clean run it interrupts
377
+ // is left standing rather than thrown away. Resetting it made the up-path unreachable for any
378
+ // game that hitches more often than once every `cooldownWindows + upWindows` windows: one
379
+ // 400 ms frame every third window pinned a scaler at 0.44 through seventeen minutes of
380
+ // otherwise perfect 60 fps, which is a forest streaming its next hillside.
381
+ //
382
+ // Unless the stalls are not what makes the frame slow: a weak GPU whose shadow redraws stall
383
+ // every window and whose ordinary frame still misses the budget is judged on that frame,
384
+ // downward only (see `#slowUnderStalls`).
385
+ const stalled = this.#stalled(window);
386
+ if (stalled && !this.#slowUnderStalls(window)) return undefined;
387
+ const gpuMs = this.#freshGpuMs(window);
388
+ this.#noteGpuObservation(window, gpuMs);
389
+ if (this.#insensitiveHold > 0) this.#insensitiveHold -= 1;
390
+ this.#trackInsensitiveRise(gpuMs);
391
+ const refunded = this.#settleInsensitiveProbe(gpuMs);
392
+ if (refunded !== undefined) return refunded;
393
+ if (gpuMs !== undefined && this.#continuousActive(window))
394
+ return this.#observeContinuous(window, gpuMs, stalled);
395
+ if (window.fps < this.targetFps && (gpuMs === undefined || gpuMs > this.budgetMs)) {
396
+ // **Only the mean is under target: hold.** `fps` is `1000 / mean`, and on the one panel
397
+ // arrangement every game actually ships into — `display.maxFps` equal to the refresh rate,
398
+ // vsync on — the mean is the only statistic with any room to move. fps is bounded *above*
399
+ // by the target there, so the whole test lives in the 2% under it, and each present the
400
+ // compositor drops spends a third of a percent. Seven doubled intervals out of 300 crossed
401
+ // the bar on `sandbox/wildwood` while the median and the tail both sat on the panel period,
402
+ // and fewer pixels do not bring a dropped present back: the step won nothing, the next
403
+ // window spent another rung, and the picture walked to 5% of its pixels in 140 seconds.
404
+ // This is `stallP99Multiple`'s lesson at 2x rather than at 10x.
405
+ //
406
+ // Deferred rather than merely not acted on, and the difference is the whole repair. Such a
407
+ // window says nothing about the pixel cost **in either direction**, which is exactly what
408
+ // the stall guard above says about its own case — so it is neither grounds to fall nor a
409
+ // reason to throw away the clean run a climb needs. Counting it against the climb stops the
410
+ // descent and never gives the pixels back: replayed against the state `sandbox/wildwood`'s
411
+ // own record documents — parked at 0.61 while holding 60.0 fps — that reading held 0.61 for
412
+ // five minutes. The picture stops getting worse and never gets sharp again, which is half a
413
+ // fix and the wrong half.
414
+ if (!this.#overBudget(window)) return undefined;
415
+ this.#cleanWindows = 0;
416
+ // Unknown GPU timing is not evidence of a GPU bottleneck: an adapter without timestamp
417
+ // queries reports nothing either way, and neither this window's fps nor its presentation
418
+ // tail can separate fixed host cost from pixel cost. So the fallback may only probe —
419
+ // one rung down, refunded unless fewer pixels earn a better frame rate.
420
+ // The memory holds both kinds of probe: a workload already shown not to answer to pixels
421
+ // does not become pixel-bound just because this window lost its GPU timestamp.
422
+ if (this.#insensitiveHold > 0 || this.#insensitiveFloor >= 0) return undefined;
423
+ if (gpuMs === undefined) return this.#probeUnknown(window);
424
+ if (this.#index >= this.#limitIndex) {
425
+ this.#atFloor = true;
426
+ return undefined;
427
+ }
428
+ const fromIndex = this.#index;
429
+ const stepped = this.#step(this.#rungsToDrop(1000 / gpuMs));
430
+ // Record the hypothesis only for a fresh-GPU step: that is the signal that can separate
431
+ // pixel cost from host cost, and a step the oscillation guard has just pinned is not one
432
+ // the next window will be allowed to test.
433
+ if (this.#scaleSource === "auto") {
434
+ const pixelDrop = 1 - (this.scale / (RESOLUTION_SCALER.rungs[fromIndex] ?? 1)) ** 2;
435
+ if (pixelDrop >= RESOLUTION_SCALER.insensitiveMinPixelDrop)
436
+ this.#insensitiveProbe = { fromIndex, toIndex: this.#index, signal: gpuMs };
437
+ }
438
+ return stepped;
439
+ }
440
+ this.#atFloor = false;
441
+ // A stalled window is never grounds to climb.
442
+ if (stalled) return undefined;
443
+ if (this.#scaleSource === "auto-pinned") return undefined;
444
+ const nextScale = RESOLUTION_SCALER.rungs[Math.max(0, this.#index - 1)] ?? 1;
445
+ const canClimb =
446
+ gpuMs === undefined
447
+ ? window.presented.p95 <= this.tailMs
448
+ : gpuMs * (nextScale / this.scale) ** 2 <= this.budgetMs;
449
+ if (!canClimb) {
450
+ this.#cleanWindows = 0;
451
+ return undefined;
452
+ }
453
+ this.#cleanWindows += 1;
454
+ if (this.#cleanWindows < RESOLUTION_SCALER.upWindows) return undefined;
455
+ this.#cleanWindows = 0;
456
+ if (this.#index === 0) return undefined;
457
+ return this.#step(-1);
458
+ }
459
+
460
+ /**
461
+ * Records what this window's GPU observation settles about earlier inferences. Fresh timing
462
+ * supersedes everything drawn from its absence; a recovered frame rate reopens a question a
463
+ * failed probe closed, because the workload changed.
464
+ */
465
+ #noteGpuObservation(window: IScalerWindow, gpuMs: number | undefined): void {
466
+ if (gpuMs !== undefined) {
467
+ this.#probeFps = undefined;
468
+ this.#probeBlind = false;
469
+ if (gpuMs <= this.budgetMs) this.#lastHealthyWindow = this.#windowIndex;
470
+ } else if (window.fps >= this.targetFps) {
471
+ this.#probeFps = undefined;
472
+ this.#probeBlind = false;
473
+ }
474
+ }
475
+
476
+ /**
477
+ * Settles the outstanding insensitivity hypothesis against this window's fresh GPU time. Returns
478
+ * the restored scale when the step is refunded, `undefined` when it earned its pixels or there is
479
+ * nothing to settle. A window without fresh timing waits rather than guessing.
480
+ */
481
+ #settleInsensitiveProbe(gpuMs: number | undefined): number | undefined {
482
+ const probe = this.#insensitiveProbe;
483
+ if (probe === undefined || gpuMs === undefined) return undefined;
484
+ this.#insensitiveProbe = undefined;
485
+ const gain = (probe.signal - gpuMs) / probe.signal;
486
+ if (gain >= RESOLUTION_SCALER.insensitiveGainFraction) return undefined;
487
+ const restored = probe.fromScale ?? RESOLUTION_SCALER.rungs[probe.fromIndex] ?? 1;
488
+ this.#index = probe.fromIndex;
489
+ this.#continuousScale = restored;
490
+ this.#insensitiveFloor = probe.fromIndex;
491
+ this.#insensitiveSignal = probe.signal;
492
+ this.#insensitiveHold = RESOLUTION_SCALER.insensitiveHoldWindows;
493
+ this.#cleanWindows = 0;
494
+ // The restore is itself a resize and must not feed the controller.
495
+ this.#cooldown = RESOLUTION_SCALER.cooldownWindows;
496
+ this.#emitInsensitive(
497
+ probe.toScale ?? RESOLUTION_SCALER.rungs[probe.toIndex] ?? 1,
498
+ restored,
499
+ gain,
500
+ );
501
+ return restored;
502
+ }
503
+
504
+ /**
505
+ * Clears the memory once the measured signal has risen past `insensitiveRiseFraction` for
506
+ * `insensitiveResetWindows` windows: a heavier workload may be pixel-bound where the old one was
507
+ * not, and the floor it set must not lock the picture soft for the rest of the session.
508
+ */
509
+ #trackInsensitiveRise(gpuMs: number | undefined): void {
510
+ if (this.#insensitiveFloor < 0 || gpuMs === undefined) return;
511
+ if (gpuMs <= this.#insensitiveSignal * RESOLUTION_SCALER.insensitiveRiseFraction) {
512
+ this.#insensitiveRise = 0;
513
+ return;
514
+ }
515
+ this.#insensitiveRise += 1;
516
+ if (this.#insensitiveRise < RESOLUTION_SCALER.insensitiveResetWindows) return;
517
+ this.#insensitiveFloor = -1;
518
+ this.#insensitiveSignal = 0;
519
+ this.#insensitiveRise = 0;
520
+ this.#insensitiveHold = 0;
521
+ }
522
+
523
+ /** One marker per refunded step, no more often than `insensitiveMarkerWindows`. */
524
+ #emitInsensitive(scale: number, restored: number, gain: number): void {
525
+ if (
526
+ this.#windowIndex - this.#lastInsensitiveMarker <
527
+ RESOLUTION_SCALER.insensitiveMarkerWindows
528
+ )
529
+ return;
530
+ this.#lastInsensitiveMarker = this.#windowIndex;
531
+ console.info(
532
+ `${RESOLUTION_SCALE_INSENSITIVE_MARKER} scale=${String(scale)} restored=${String(restored)} gainPct=${String(Math.round(gain * 100))}`,
533
+ );
534
+ }
535
+
536
+ /**
537
+ * One decided over-budget window with no fresh GPU timing. Returns the new scale when this
538
+ * window caused a step, `undefined` otherwise.
539
+ */
540
+ #probeUnknown(window: IScalerWindow): number | undefined {
541
+ // A pending probe is evaluated before the floor guard: parking at the final rung must
542
+ // not strand the hypothesis that fewer pixels would help. Improvement counts only when
543
+ // the new deficit prices fewer rungs than the old one — the same rung table as every
544
+ // sized jump, so timing noise that never crosses a rung boundary refunds instead of
545
+ // ratcheting the ladder down one tremor at a time.
546
+ if (this.#probeFps !== undefined) {
547
+ const earned = this.#rungsToDrop(window.fps) < this.#rungsToDrop(this.#probeFps);
548
+ this.#probeFps = undefined;
549
+ if (!earned) {
550
+ this.#probeBlind = true;
551
+ return this.#step(-1, false);
552
+ }
553
+ if (this.#index >= this.#limitIndex) {
554
+ this.#atFloor = true;
555
+ return undefined;
556
+ }
557
+ this.#probeFps = window.fps;
558
+ return this.#step(1);
559
+ }
560
+ if (this.#index >= this.#limitIndex) {
561
+ this.#atFloor = true;
562
+ return undefined;
563
+ }
564
+ // A gap immediately after fresh-healthy timing is transient, not a new bottleneck.
565
+ if (this.#windowIndex - this.#lastHealthyWindow <= 1) return undefined;
566
+ if (this.#probeBlind) return undefined;
567
+ this.#probeFps = window.fps;
568
+ return this.#step(1);
569
+ }
570
+
571
+ #continuousActive(window: IScalerWindow): boolean {
572
+ return window.surface?.resolutionSubrect === true;
573
+ }
574
+
575
+ #observeContinuous(
576
+ window: IScalerWindow,
577
+ gpuMs: number | undefined,
578
+ stalled: boolean,
579
+ ): number | undefined {
580
+ const overBudget =
581
+ window.fps < this.targetFps && (gpuMs === undefined || gpuMs > this.budgetMs);
582
+ const floor = RESOLUTION_SCALER.rungs[this.#limitIndex] ?? 0.23;
583
+ if (overBudget) {
584
+ this.#cleanWindows = 0;
585
+ if (!this.#overBudget(window) || gpuMs === undefined) {
586
+ this.#atFloor = this.#continuousScale <= floor;
587
+ return undefined;
588
+ }
589
+ if (this.#insensitiveHold > 0 || this.#insensitiveFloor >= 0) return undefined;
590
+ const estimate = this.#continuousScale * Math.sqrt(this.budgetMs / gpuMs);
591
+ const target = this.#quantizeContinuous(Math.max(floor, estimate), window);
592
+ this.#atFloor = target <= floor;
593
+ const fromIndex = this.#index;
594
+ const fromScale = this.#continuousScale;
595
+ const changed = this.#continuousChange(Math.max(floor, target), false);
596
+ if (
597
+ changed !== undefined &&
598
+ this.#scaleSource === "auto" &&
599
+ 1 - (changed / fromScale) ** 2 >= RESOLUTION_SCALER.insensitiveMinPixelDrop
600
+ )
601
+ this.#insensitiveProbe = {
602
+ fromIndex,
603
+ toIndex: this.#index,
604
+ fromScale,
605
+ toScale: changed,
606
+ signal: gpuMs,
607
+ };
608
+ return changed;
609
+ }
610
+ this.#atFloor = false;
611
+ if (stalled || this.#scaleSource === "auto-pinned") return undefined;
612
+ const nextScale = Math.min(1, this.#continuousScale + 0.01);
613
+ const canClimb =
614
+ gpuMs === undefined
615
+ ? window.presented.p95 <= this.tailMs
616
+ : gpuMs * (nextScale / this.#continuousScale) ** 2 <= this.budgetMs;
617
+ if (!canClimb) {
618
+ this.#cleanWindows = 0;
619
+ return undefined;
620
+ }
621
+ this.#cleanWindows += 1;
622
+ if (this.#cleanWindows < RESOLUTION_SCALER.upWindows) return undefined;
623
+ this.#cleanWindows = 0;
624
+ const estimate =
625
+ gpuMs === undefined
626
+ ? 1
627
+ : Math.min(1, this.#continuousScale * Math.sqrt(this.budgetMs / gpuMs));
628
+ const amortized =
629
+ this.#continuousScale +
630
+ RESOLUTION_SCALER.continuousUpFraction *
631
+ (Math.max(this.#continuousScale, estimate) - this.#continuousScale);
632
+ return this.#continuousChange(this.#quantizeContinuous(amortized, window), true);
633
+ }
634
+
635
+ #quantizeContinuous(scale: number, window: IScalerWindow): number {
636
+ const surface = window.surface;
637
+ if (
638
+ surface === undefined ||
639
+ !Number.isFinite(surface.drawingBufferWidth) ||
640
+ !Number.isFinite(surface.drawingBufferHeight) ||
641
+ !Number.isFinite(surface.resolutionScale) ||
642
+ surface.drawingBufferWidth <= 0 ||
643
+ surface.drawingBufferHeight <= 0 ||
644
+ surface.resolutionScale <= 0
645
+ )
646
+ return Math.min(1, Math.max(0, scale));
647
+ const fullWidth =
648
+ surface.resolutionSubrect === true
649
+ ? surface.drawingBufferWidth
650
+ : surface.drawingBufferWidth / surface.resolutionScale;
651
+ const fullHeight =
652
+ surface.resolutionSubrect === true
653
+ ? surface.drawingBufferHeight
654
+ : surface.drawingBufferHeight / surface.resolutionScale;
655
+ const width = Math.max(8, Math.ceil((fullWidth * scale) / 8) * 8);
656
+ const height = Math.max(8, Math.ceil((fullHeight * scale) / 8) * 8);
657
+ return Math.min(1, width / fullWidth, height / fullHeight);
658
+ }
659
+
660
+ #continuousChange(target: number, up: boolean): number | undefined {
661
+ const current = this.#continuousScale;
662
+ const change = Math.abs(target - current) / Math.max(current, Number.EPSILON);
663
+ if (change < RESOLUTION_SCALER.continuousChangeThreshold) return undefined;
664
+ if (
665
+ this.#continuousFrames - this.#continuousLastChangeFrame <
666
+ RESOLUTION_SCALER.continuousChangeFrames
667
+ )
668
+ return undefined;
669
+ const next = Math.min(1, Math.max(RESOLUTION_SCALER.rungs[this.#limitIndex] ?? 0.23, target));
670
+ if (next === current) return undefined;
671
+ const previousIndex = this.#index;
672
+ this.#continuousScale = next;
673
+ this.#syncRungIndex(next);
674
+ this.#continuousLastChangeFrame = this.#continuousFrames;
675
+ this.#cooldown = RESOLUTION_SCALER.cooldownWindows;
676
+ const direction = next < current ? 1 : -1;
677
+ const boundary = direction > 0 ? previousIndex : this.#index;
678
+ this.#noteForOscillationGuard(boundary, direction);
679
+ return this.#continuousScale;
680
+ }
681
+
682
+ #syncRungIndex(scale: number): void {
683
+ let closest = 0;
684
+ let distance = Number.POSITIVE_INFINITY;
685
+ for (const [index, rung] of RESOLUTION_SCALER.rungs.entries()) {
686
+ const nextDistance = Math.abs(rung - scale);
687
+ if (nextDistance >= distance) continue;
688
+ closest = index;
689
+ distance = nextDistance;
690
+ }
691
+ this.#index = closest;
692
+ }
693
+
694
+ /**
695
+ * True when the median or tail corroborates the missed presentation budget. This alone cannot
696
+ * identify a pixel bottleneck; fresh GPU timing takes precedence in observe().
697
+ *
698
+ * Two independent witnesses, each already carrying its own pre-registered bar, and either is
699
+ * enough:
700
+ *
701
+ * - **the median present is over the target's period.** An unlocked renderer holding a steady
702
+ * 17.24 ms against a 16.67 ms budget shows up here and nowhere else: its tail is as tight as
703
+ * its middle, and it is simply doing too much work every frame.
704
+ * - **the tail is past `tailMs`.** Under FIFO an interval is a whole number of panel periods,
705
+ * so a game that misses a real share of its vsyncs moves p95 to two periods in one jump —
706
+ * the 45 fps window the device arm chose the mean signal for. There is nothing in between to
707
+ * fall through: `upTailFraction` sits in the empty gap between one period and two.
708
+ *
709
+ * When neither speaks, the deficit is a handful of doubled intervals in an otherwise on-budget
710
+ * window: jitter from the compositor, a GC, an input burst, an audio callback. None of that is
711
+ * bought back with pixels, and spending a rung on it is how the picture walks to the floor.
712
+ */
713
+ /**
714
+ * Whether a stalled window's ordinary frame misses the budget on its own: the window is under
715
+ * target and fresh GPU timing alone exceeds the budget, so setting the stalls aside still leaves
716
+ * a slow frame that fewer pixels can speed up. A game whose GPU meets the budget keeps the stall
717
+ * deferral; a weak GPU does not stay at full resolution forever because its hitches recur. On an
718
+ * Intel Iris Xe, Machinefall's shadow redraws (120-350 ms) put presented p99 at 15-63x p50 in
719
+ * all but one judged window, p50 sat at 9-12 ms against 8.33, and the scale held 1.0 for the
720
+ * whole walk (PRD-549).
721
+ */
722
+ #slowUnderStalls(window: IScalerWindow): boolean {
723
+ const gpuMs = this.#freshGpuMs(window);
724
+ // Fresh GPU over budget in a window under target. Not the present median: on the Iris Xe it
725
+ // read 7 ms while the main pass took 30 ms and the window ran at 35 fps (PRD-549, live11).
726
+ return window.fps < this.targetFps && gpuMs !== undefined && gpuMs > this.budgetMs;
727
+ }
728
+
729
+ #overBudget(window: IScalerWindow): boolean {
730
+ return window.presented.p50 > this.budgetMs || window.presented.p95 > this.tailMs;
731
+ }
732
+
733
+ #freshGpuMs({ gpu, gpuMs, gpuAgeFrames }: IScalerWindow): number | undefined {
734
+ if (
735
+ gpuMs !== undefined &&
736
+ Number.isFinite(gpuMs) &&
737
+ gpuMs > 0 &&
738
+ gpuAgeFrames !== undefined &&
739
+ Number.isInteger(gpuAgeFrames) &&
740
+ gpuAgeFrames >= 0 &&
741
+ gpuAgeFrames <= RESOLUTION_SCALER.maxGpuAgeFrames
742
+ )
743
+ return gpuMs;
744
+ // An integrated GPU resolves timestamps hundreds of frames late (Iris Xe: 233-593, PRD-549),
745
+ // so the last reading is always old while the window is full of its own samples.
746
+ return gpu !== undefined &&
747
+ gpu.samples >= RESOLUTION_SCALER.minWindowGpuSamples &&
748
+ Number.isFinite(gpu.p50) &&
749
+ gpu.p50 > 0
750
+ ? gpu.p50
751
+ : undefined;
752
+ }
753
+
754
+ /**
755
+ * True when this window's recurring tail or single worst sample is an order of magnitude past
756
+ * its middle, which is a stall rather than a frame rate. A window with no p50 to compare against
757
+ * says nothing either way.
758
+ */
759
+ #stalled(window: IScalerWindow): boolean {
760
+ const { max, p50, p99 } = window.presented;
761
+ if (!(p50 > 0) || !Number.isFinite(p99) || !Number.isFinite(max)) return false;
762
+ return (
763
+ p99 >= p50 * RESOLUTION_SCALER.stallP99Multiple ||
764
+ max >= p50 * RESOLUTION_SCALER.stallMaxMultiple
765
+ );
766
+ }
767
+
768
+ /**
769
+ * How many rungs one down-step should cross, from the fps deficit alone.
770
+ *
771
+ * Each rung is `0.72x` the pixels, so closing a deficit of `target / measured` needs
772
+ * `log(deficit) / log(1 / 0.72)` rungs if the whole frame scaled with pixels. It does not — but
773
+ * a single window cannot say how much of it does, and the up-step is there to give back what
774
+ * this takes too eagerly.
775
+ */
776
+ #rungsToDrop(fps: number): number {
777
+ if (!(fps > 0)) return RESOLUTION_SCALER.maxDownRungs;
778
+ const deficit = this.targetFps / fps;
779
+ if (!(deficit > 1)) return 1;
780
+ const rungs = Math.ceil(Math.log(deficit) / Math.log(1 / RUNG_PIXEL_RATIO));
781
+ return Math.min(Math.max(1, rungs), RESOLUTION_SCALER.maxDownRungs);
782
+ }
783
+
784
+ #step(direction: number, countGuard = true): number {
785
+ // The boundary a fall from rung n crosses is the same one the climb back to n crosses.
786
+ const boundary = direction > 0 ? this.#index : this.#index - 1;
787
+ // The platform's floor is a limit, not a step count: a jump sized on a deficit can ask for
788
+ // more rungs than the floor allows, and it must land on the floor rather than past it.
789
+ const next = this.#index + direction;
790
+ this.#index = direction > 0 ? Math.min(next, this.#limitIndex) : Math.max(0, next);
791
+ this.#cooldown = RESOLUTION_SCALER.cooldownWindows;
792
+ // A refund is a measurement correction, not workload oscillation: counting it would let
793
+ // probe/refund cycles pin the scaler at a rung pixels were just proven not to earn.
794
+ if (countGuard) this.#noteForOscillationGuard(boundary, direction);
795
+ this.#continuousScale = RESOLUTION_SCALER.rungs[this.#index] ?? 1;
796
+ return this.scale;
797
+ }
798
+
799
+ #noteForOscillationGuard(boundary: number, direction: number): void {
800
+ const withinReach =
801
+ this.#windowIndex - this.#guardWindow <= RESOLUTION_SCALER.oscillationWindows;
802
+ const continues =
803
+ boundary === this.#guardBoundary && withinReach && direction !== this.#guardDirection;
804
+ this.#guardLegs = continues ? this.#guardLegs + 1 : 1;
805
+ this.#guardBoundary = boundary;
806
+ this.#guardDirection = direction;
807
+ this.#guardWindow = this.#windowIndex;
808
+ // down, up, down is one cycle. The next cycle reuses this leg as its first.
809
+ if (this.#guardLegs < 3) return;
810
+ this.#guardLegs = 1;
811
+ this.#guardCycles += 1;
812
+ if (this.#guardCycles < RESOLUTION_SCALER.oscillationCycles) return;
813
+ // Suppress upward probes temporarily; neither recovery nor later overload may be locked out
814
+ // for the rest of a session because the workload once sat near a thermal edge.
815
+ this.#index = Math.max(this.#index, boundary + 1);
816
+ this.#scaleSource = "auto-pinned";
817
+ this.#pinWindows = RESOLUTION_SCALER.oscillationWindows;
818
+ }
819
+ }