@plasius/gpu-performance 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.
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.17] - 2026-11-22
24
+
25
+ - Refresh supported npm dependency and security tooling baselines; preserve runtime API contracts (weekly maintenance, 2026-11-22).
26
+
27
+ - **Added**
28
+ - (placeholder)
29
+
30
+ - **Changed**
31
+ - (placeholder)
32
+
33
+ - **Fixed**
34
+ - (placeholder)
35
+
36
+ - **Security**
37
+ - (placeholder)
38
+
39
+ ## [0.1.16] - 2026-11-16
40
+
41
+ - **Added**
42
+ - Opt-in recovery from conservative initial quality levels, with host-provided adjacent cost ratios for unmeasured upgrades.
43
+
44
+ - **Changed**
45
+ - (placeholder)
46
+
47
+ - **Fixed**
48
+ - (placeholder)
49
+
50
+ - **Security**
51
+ - (placeholder)
52
+
23
53
  ## [0.1.15] - 2026-11-05
24
54
 
25
55
  - **Added**
@@ -329,3 +359,5 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
329
359
  [0.1.13]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.13
330
360
  [0.1.14]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.14
331
361
  [0.1.15]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.15
362
+ [0.1.16]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.16
363
+ [0.1.17]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.17
package/README.md CHANGED
@@ -172,6 +172,22 @@ Custom adapters may implement `canStepUp(context)`; refusal retains pending
172
172
  recovery and lets other eligible modules recover. Without this option or hook,
173
173
  existing recovery behaviour remains unchanged.
174
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
+
175
191
  Hosts can reserve execution headroom without changing their cadence target using
176
192
  `target.frameBudgetRatio` (greater than zero and at most one). For a negotiated
177
193
  24 FPS target, `0.9` starts reduction above 37.5 ms and admits recovery below
package/dist/index.cjs CHANGED
@@ -405,8 +405,12 @@ function createMeasuredQualityRecovery(levelCount, options) {
405
405
  if (headroom === void 0 || headroom > 1) {
406
406
  throw new Error("recoveryBudget.headroomRatio must be in (0, 1].");
407
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
+ }
408
412
  const lastTimes = new Array(levelCount);
409
- const recoveryRatios = new Array(levelCount);
413
+ const recoveryRatios = initialRatios ? [...initialRatios] : new Array(levelCount);
410
414
  let pending;
411
415
  return {
412
416
  record(index, frameTimeMs) {
@@ -1050,6 +1054,9 @@ function createGpuPerformanceGovernor(options) {
1050
1054
  throw new Error("createGpuPerformanceGovernor requires an options object.");
1051
1055
  }
1052
1056
  validateTelemetryHooks(options.telemetry);
1057
+ if (options.recoverInitialLevels !== void 0 && typeof options.recoverInitialLevels !== "boolean") {
1058
+ throw new Error("recoverInitialLevels must be a boolean.");
1059
+ }
1053
1060
  const device = createDeviceProfile(options.device);
1054
1061
  if (!device.supportsWebGpu) {
1055
1062
  throw new Error(
@@ -1086,6 +1093,7 @@ function createGpuPerformanceGovernor(options) {
1086
1093
  let lastDownCycle = Number.NEGATIVE_INFINITY;
1087
1094
  let lastUpCycle = Number.NEGATIVE_INFINITY;
1088
1095
  let recoveryStack = [];
1096
+ const initialRecovery = new Set(options.recoverInitialLevels ? modules.keys() : []);
1089
1097
  let recentErrors = [];
1090
1098
  let recentFrameIds = /* @__PURE__ */ new Set();
1091
1099
  let recentFrameIdQueue = [];
@@ -1254,26 +1262,41 @@ function createGpuPerformanceGovernor(options) {
1254
1262
  };
1255
1263
  const attemptRecovery = (metrics, workerGraph, decisionErrors, correlationId) => {
1256
1264
  const context = createContext("recover", "recovering", metrics, workerGraph);
1257
- for (let index = recoveryStack.length - 1; index >= 0; index -= 1) {
1258
- const moduleId = recoveryStack[index];
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
+ };
1259
1275
  if (!moduleId) {
1260
- recoveryStack.splice(index, 1);
1276
+ remove();
1261
1277
  continue;
1262
1278
  }
1263
1279
  const module2 = modules.get(moduleId);
1264
1280
  if (!module2) {
1265
- recoveryStack.splice(index, 1);
1281
+ remove();
1266
1282
  continue;
1267
1283
  }
1268
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
+ }
1269
1292
  if (module2.canStepUp?.(context) === false) continue;
1270
1293
  const adjustment = module2.stepUp(context);
1271
- recoveryStack.splice(index, 1);
1294
+ if (index >= 0 || !adjustment) remove();
1272
1295
  if (adjustment) {
1273
1296
  return [adjustment];
1274
1297
  }
1275
1298
  } catch {
1276
- recoveryStack.splice(index, 1);
1299
+ remove();
1277
1300
  appendError(
1278
1301
  createErrorRecord({
1279
1302
  cycle,
@@ -1385,9 +1408,11 @@ function createGpuPerformanceGovernor(options) {
1385
1408
  throw new Error(`Module "${module2.id}" is already registered.`);
1386
1409
  }
1387
1410
  modules.set(module2.id, module2);
1411
+ if (options.recoverInitialLevels) initialRecovery.add(module2.id);
1388
1412
  return () => {
1389
1413
  modules.delete(module2.id);
1390
1414
  recoveryStack = recoveryStack.filter((id) => id !== module2.id);
1415
+ initialRecovery.delete(module2.id);
1391
1416
  };
1392
1417
  },
1393
1418
  getTarget() {
@@ -1416,6 +1441,8 @@ function createGpuPerformanceGovernor(options) {
1416
1441
  lastDownCycle = Number.NEGATIVE_INFINITY;
1417
1442
  lastUpCycle = Number.NEGATIVE_INFINITY;
1418
1443
  recoveryStack = [];
1444
+ initialRecovery.clear();
1445
+ if (options.recoverInitialLevels) for (const id of modules.keys()) initialRecovery.add(id);
1419
1446
  recentErrors = [];
1420
1447
  recentFrameIds = /* @__PURE__ */ new Set();
1421
1448
  recentFrameIdQueue = [];