@plasius/gpu-performance 0.1.14 → 0.1.16

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.
package/CHANGELOG.md CHANGED
@@ -20,6 +20,36 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
20
20
  - **Security**
21
21
  - (placeholder)
22
22
 
23
+ ## [0.1.16] - 2026-11-16
24
+
25
+ - **Added**
26
+ - Opt-in recovery from conservative initial quality levels, with host-provided adjacent cost ratios for unmeasured upgrades.
27
+
28
+ - **Changed**
29
+ - (placeholder)
30
+
31
+ - **Fixed**
32
+ - (placeholder)
33
+
34
+ - **Security**
35
+ - (placeholder)
36
+
37
+ ## [0.1.15] - 2026-11-05
38
+
39
+ - **Added**
40
+ - Opt-in measured quality recovery, completed-frame cost recording and retryable adapter recovery admission.
41
+ - Optional frame-budget headroom for earlier adaptation under changing workloads, preserving the negotiated cadence and default thresholds.
42
+
43
+ - **Changed**
44
+ - Refreshed compatible @plasius/* lockfile resolutions to the latest published releases.
45
+ - (placeholder)
46
+
47
+ - **Fixed**
48
+ - (placeholder)
49
+
50
+ - **Security**
51
+ - Resolve demonstrated build/test advisories in Vitest, Vite, glob matching, brace expansion and source-map parsing; production dependencies remain unchanged.
52
+
23
53
  ## [0.1.14] - 2026-08-31
24
54
 
25
55
  - **Added**
@@ -312,3 +342,5 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
312
342
  [0.1.12]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.12
313
343
  [0.1.13]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.13
314
344
  [0.1.14]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.14
345
+ [0.1.15]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.15
346
+ [0.1.16]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.16
package/README.md CHANGED
@@ -144,6 +144,58 @@ for (const [index, frameTimeMs] of [12.8, 13.1, 18.4, 18.9, 19.2, 18.8, 18.1, 17
144
144
  }
145
145
  ```
146
146
 
147
+ For a ladder whose quality levels have measured frame costs, opt into recovery
148
+ admission to avoid repeatedly retrying an over-budget level:
149
+
150
+ ```ts
151
+ const quality = createQualityLadderAdapter({
152
+ id: "interactive-quality",
153
+ domain: "resolution",
154
+ levels: [
155
+ { id: "preview", config: { scale: 0.5 } },
156
+ { id: "full", config: { scale: 1 } },
157
+ ],
158
+ recoveryBudget: { headroomRatio: 0.9 },
159
+ });
160
+ // Register quality with your governor. After each awaited frame, record its
161
+ // execution duration before governor.recordFrame({ frameTimeMs }).
162
+ quality.recordFrameTime(30);
163
+ ```
164
+
165
+ The adapter pairs timings across downgrades, then admits a known higher level
166
+ when its projected cost fits the chosen fraction of the negotiated frame budget.
167
+ Unknown levels can still be explored. Faster execution reopens recovery without
168
+ changing the product's target. Recreate the adapter when the workload or device
169
+ changes. Keep input queue age separate from frame execution time. Cost estimates
170
+ cannot guarantee a deadline when even minimum work exceeds the device budget.
171
+ Custom adapters may implement `canStepUp(context)`; refusal retains pending
172
+ recovery and lets other eligible modules recover. Without this option or hook,
173
+ existing recovery behaviour remains unchanged.
174
+
175
+ For latency-sensitive startup, select a conservative `initialLevel` and set
176
+ `recoverInitialLevels: true` on the governor. This opt-in adds pending recovery
177
+ for registered modules without inventing frame samples. Normal cooldowns,
178
+ measured admission, thermal pressure and authoritative-system protection still
179
+ apply. Historical downgrades recover first. Removing a module removes its pending
180
+ startup recovery; resetting the governor starts admission again from its current
181
+ level. The default remains recovery of governor-issued downgrades only.
182
+
183
+ Set `recoveryBudget.initialCostRatios` to one positive finite cost ratio per
184
+ adjacent upward step when the host can estimate unmeasured work. For example,
185
+ scales 0.5 and 1 at equal samples use `[4]`, while 1 and 2 SPP at equal scale use
186
+ `[2]`. Ratios are copied and constrain the first upgrade; paired completed-frame
187
+ measurements replace them after a downgrade. They are estimates, not guaranteed
188
+ frame times. Engine improvements automatically reopen admission through measured
189
+ execution times, without changing the host's frame-rate target.
190
+
191
+ Hosts can reserve execution headroom without changing their cadence target using
192
+ `target.frameBudgetRatio` (greater than zero and at most one). For a negotiated
193
+ 24 FPS target, `0.9` starts reduction above 37.5 ms and admits recovery below
194
+ 34.5 ms. Omit it to retain the existing thresholds. Supply the supported/preferred
195
+ frame-rate buckets for a non-default cadence. Shorter existing sample windows and
196
+ cooldowns let rapidly changing camera workloads respond earlier; they remain host
197
+ policy. Keep the ladder's recovery reserve consistent with this execution reserve.
198
+
147
199
  Ray-tracing-first budget metadata is part of the public contract:
148
200
 
149
201
  - `representationBands`: `near`, `mid`, `far`, `horizon`
package/dist/index.cjs CHANGED
@@ -209,6 +209,10 @@ function createDeviceProfile(input = {}) {
209
209
  });
210
210
  }
211
211
  function negotiateFrameTarget(options = {}) {
212
+ const frameBudgetRatio = readPositiveNumber("frameBudgetRatio", options.frameBudgetRatio);
213
+ if (frameBudgetRatio !== void 0 && frameBudgetRatio > 1) {
214
+ throw new Error("frameBudgetRatio must be at most one.");
215
+ }
212
216
  const mode = options.mode === void 0 ? "flat" : assertEnumValue("mode", options.mode, runtimeModes);
213
217
  const minimumFrameRate = Math.round(
214
218
  readPositiveNumber("minimumFrameRate", options.minimumFrameRate) ?? 60
@@ -265,8 +269,8 @@ function negotiateFrameTarget(options = {}) {
265
269
  rationale.push("Immersive modes prefer headset-native cadence when the session supports it.");
266
270
  }
267
271
  const targetFrameTimeMs = 1e3 / targetFrameRate;
268
- const downgradeMultiplier = mode === "flat" ? 1.05 : 1.03;
269
- const upgradeMultiplier = mode === "flat" ? 0.92 : 0.95;
272
+ const downgradeMultiplier = frameBudgetRatio ?? (mode === "flat" ? 1.05 : 1.03);
273
+ const upgradeMultiplier = (frameBudgetRatio ?? 1) * (mode === "flat" ? 0.92 : 0.95);
270
274
  return Object.freeze({
271
275
  mode,
272
276
  minimumFrameRate,
@@ -394,6 +398,42 @@ function normalizePerformanceBudgetMetadata(name, value) {
394
398
  });
395
399
  }
396
400
 
401
+ // src/quality-recovery.ts
402
+ function createMeasuredQualityRecovery(levelCount, options) {
403
+ const enabled = options !== void 0;
404
+ const headroom = enabled ? readPositiveNumber("recoveryBudget.headroomRatio", options?.headroomRatio) : 1;
405
+ if (headroom === void 0 || headroom > 1) {
406
+ throw new Error("recoveryBudget.headroomRatio must be in (0, 1].");
407
+ }
408
+ const initialRatios = options?.initialCostRatios;
409
+ if (initialRatios !== void 0 && (!Array.isArray(initialRatios) || initialRatios.length !== levelCount - 1 || Array.from(initialRatios).some((value) => typeof value !== "number" || !Number.isFinite(value) || value <= 0))) {
410
+ throw new Error("recoveryBudget.initialCostRatios must contain one finite positive ratio per upward step.");
411
+ }
412
+ const lastTimes = new Array(levelCount);
413
+ const recoveryRatios = initialRatios ? [...initialRatios] : new Array(levelCount);
414
+ let pending;
415
+ return {
416
+ record(index, frameTimeMs) {
417
+ const value = readNonNegativeNumber("frameTimeMs", frameTimeMs);
418
+ if (value === void 0) throw new Error("frameTimeMs is required.");
419
+ if (!enabled || value === 0) return;
420
+ lastTimes[index] = value;
421
+ if (pending?.index === index) {
422
+ recoveryRatios[index] = pending.upperTime / value;
423
+ pending = void 0;
424
+ }
425
+ },
426
+ reduced(from, to) {
427
+ const upperTime = lastTimes[from];
428
+ pending = enabled && upperTime !== void 0 ? { index: to, upperTime } : void 0;
429
+ },
430
+ canRecover(index, context) {
431
+ const ratio = recoveryRatios[index];
432
+ return !enabled || ratio === void 0 || context.metrics.latestFrameTimeMs * ratio <= context.target.targetFrameTimeMs * headroom;
433
+ }
434
+ };
435
+ }
436
+
397
437
  // src/ladder.ts
398
438
  function resolveLevelIndex(levels, initialLevel) {
399
439
  if (typeof initialLevel === "number") {
@@ -473,6 +513,7 @@ function createQualityLadderAdapter(options) {
473
513
  const levels = [...options.levels];
474
514
  const metadata = normalizePerformanceBudgetMetadata("budget metadata", options);
475
515
  let currentLevelIndex = resolveLevelIndex(levels, options.initialLevel);
516
+ const recovery = createMeasuredQualityRecovery(levels.length, options.recoveryBudget);
476
517
  const emitChange = (context, adjustment, previousLevelIndex) => {
477
518
  if (typeof options.onLevelChange !== "function") {
478
519
  return;
@@ -493,7 +534,9 @@ function createQualityLadderAdapter(options) {
493
534
  return null;
494
535
  }
495
536
  const previousLevelIndex = currentLevelIndex;
537
+ if (direction === "up" && !recovery.canRecover(currentLevelIndex, context)) return null;
496
538
  currentLevelIndex = nextLevelIndex;
539
+ if (direction === "down") recovery.reduced(previousLevelIndex, currentLevelIndex);
497
540
  const adjustment = buildAdjustment(
498
541
  direction,
499
542
  id,
@@ -519,6 +562,12 @@ function createQualityLadderAdapter(options) {
519
562
  getCurrentLevel() {
520
563
  return levels[currentLevelIndex];
521
564
  },
565
+ recordFrameTime(frameTimeMs) {
566
+ recovery.record(currentLevelIndex, frameTimeMs);
567
+ },
568
+ canStepUp(context) {
569
+ return recovery.canRecover(currentLevelIndex, context);
570
+ },
522
571
  getSnapshot() {
523
572
  return buildSnapshot(
524
573
  id,
@@ -1005,6 +1054,9 @@ function createGpuPerformanceGovernor(options) {
1005
1054
  throw new Error("createGpuPerformanceGovernor requires an options object.");
1006
1055
  }
1007
1056
  validateTelemetryHooks(options.telemetry);
1057
+ if (options.recoverInitialLevels !== void 0 && typeof options.recoverInitialLevels !== "boolean") {
1058
+ throw new Error("recoverInitialLevels must be a boolean.");
1059
+ }
1008
1060
  const device = createDeviceProfile(options.device);
1009
1061
  if (!device.supportsWebGpu) {
1010
1062
  throw new Error(
@@ -1018,7 +1070,8 @@ function createGpuPerformanceGovernor(options) {
1018
1070
  supportedFrameRates: options.target?.supportedFrameRates ?? device.supportedFrameRates,
1019
1071
  preferredFrameRates: options.target?.preferredFrameRates,
1020
1072
  minimumFrameRate: options.target?.minimumFrameRate,
1021
- maximumFrameRate: options.target?.maximumFrameRate
1073
+ maximumFrameRate: options.target?.maximumFrameRate,
1074
+ frameBudgetRatio: options.target?.frameBudgetRatio
1022
1075
  });
1023
1076
  const modules = /* @__PURE__ */ new Map();
1024
1077
  if ((options.modules?.length ?? 0) > MAX_MODULE_COUNT) {
@@ -1040,6 +1093,7 @@ function createGpuPerformanceGovernor(options) {
1040
1093
  let lastDownCycle = Number.NEGATIVE_INFINITY;
1041
1094
  let lastUpCycle = Number.NEGATIVE_INFINITY;
1042
1095
  let recoveryStack = [];
1096
+ const initialRecovery = new Set(options.recoverInitialLevels ? modules.keys() : []);
1043
1097
  let recentErrors = [];
1044
1098
  let recentFrameIds = /* @__PURE__ */ new Set();
1045
1099
  let recentFrameIdQueue = [];
@@ -1208,25 +1262,41 @@ function createGpuPerformanceGovernor(options) {
1208
1262
  };
1209
1263
  const attemptRecovery = (metrics, workerGraph, decisionErrors, correlationId) => {
1210
1264
  const context = createContext("recover", "recovering", metrics, workerGraph);
1211
- while (recoveryStack.length > 0) {
1212
- const moduleId = recoveryStack[recoveryStack.length - 1];
1265
+ const pending = recoveryStack.map((moduleId, index) => ({ moduleId, index })).reverse();
1266
+ const reduced = new Set(recoveryStack);
1267
+ for (const moduleId of initialRecovery) {
1268
+ if (!reduced.has(moduleId)) pending.push({ moduleId, index: -1 });
1269
+ }
1270
+ for (const { moduleId, index } of pending) {
1271
+ const remove = () => {
1272
+ if (index >= 0) recoveryStack.splice(index, 1);
1273
+ else initialRecovery.delete(moduleId);
1274
+ };
1213
1275
  if (!moduleId) {
1214
- recoveryStack.pop();
1276
+ remove();
1215
1277
  continue;
1216
1278
  }
1217
1279
  const module2 = modules.get(moduleId);
1218
1280
  if (!module2) {
1219
- recoveryStack.pop();
1281
+ remove();
1220
1282
  continue;
1221
1283
  }
1222
1284
  try {
1285
+ if (index < 0) {
1286
+ const snapshot = module2.getSnapshot();
1287
+ if (snapshot.isAtMaximum || snapshot.authority === "authoritative" && !adaptation.allowAuthoritativeScaling) {
1288
+ remove();
1289
+ continue;
1290
+ }
1291
+ }
1292
+ if (module2.canStepUp?.(context) === false) continue;
1223
1293
  const adjustment = module2.stepUp(context);
1224
- recoveryStack.pop();
1294
+ if (index >= 0 || !adjustment) remove();
1225
1295
  if (adjustment) {
1226
1296
  return [adjustment];
1227
1297
  }
1228
1298
  } catch {
1229
- recoveryStack.pop();
1299
+ remove();
1230
1300
  appendError(
1231
1301
  createErrorRecord({
1232
1302
  cycle,
@@ -1338,9 +1408,11 @@ function createGpuPerformanceGovernor(options) {
1338
1408
  throw new Error(`Module "${module2.id}" is already registered.`);
1339
1409
  }
1340
1410
  modules.set(module2.id, module2);
1411
+ if (options.recoverInitialLevels) initialRecovery.add(module2.id);
1341
1412
  return () => {
1342
1413
  modules.delete(module2.id);
1343
1414
  recoveryStack = recoveryStack.filter((id) => id !== module2.id);
1415
+ initialRecovery.delete(module2.id);
1344
1416
  };
1345
1417
  },
1346
1418
  getTarget() {
@@ -1369,6 +1441,8 @@ function createGpuPerformanceGovernor(options) {
1369
1441
  lastDownCycle = Number.NEGATIVE_INFINITY;
1370
1442
  lastUpCycle = Number.NEGATIVE_INFINITY;
1371
1443
  recoveryStack = [];
1444
+ initialRecovery.clear();
1445
+ if (options.recoverInitialLevels) for (const id of modules.keys()) initialRecovery.add(id);
1372
1446
  recentErrors = [];
1373
1447
  recentFrameIds = /* @__PURE__ */ new Set();
1374
1448
  recentFrameIdQueue = [];