@plasius/gpu-performance 0.1.13 → 0.1.15

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,40 @@ 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.15] - 2026-11-05
24
+
25
+ - **Added**
26
+ - Opt-in measured quality recovery, completed-frame cost recording and retryable adapter recovery admission.
27
+ - Optional frame-budget headroom for earlier adaptation under changing workloads, preserving the negotiated cadence and default thresholds.
28
+
29
+ - **Changed**
30
+ - Refreshed compatible @plasius/* lockfile resolutions to the latest published releases.
31
+ - (placeholder)
32
+
33
+ - **Fixed**
34
+ - (placeholder)
35
+
36
+ - **Security**
37
+ - Resolve demonstrated build/test advisories in Vitest, Vite, glob matching, brace expansion and source-map parsing; production dependencies remain unchanged.
38
+
39
+ ## [0.1.14] - 2026-08-31
40
+
41
+ - **Added**
42
+ - (placeholder)
43
+
44
+ - **Changed**
45
+ - (placeholder)
46
+
47
+ - **Fixed**
48
+ - Added exact-commit CI dispatch and disabled package-manager cache
49
+ finalization in both hosted validation jobs.
50
+ - (placeholder)
51
+
52
+ - **Security**
53
+ - Pinned the npm OIDC release client to 11.6.2 and revalidate the exact
54
+ checked-out and remote `main` commit immediately before publication.
55
+ - (placeholder)
56
+
23
57
  ## [0.1.13] - 2026-08-30
24
58
 
25
59
  - **Added**
@@ -293,3 +327,5 @@ The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/
293
327
  [0.1.11]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.11
294
328
  [0.1.12]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.12
295
329
  [0.1.13]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.13
330
+ [0.1.14]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.14
331
+ [0.1.15]: https://github.com/Plasius-LTD/gpu-performance/releases/tag/v0.1.15
package/README.md CHANGED
@@ -144,6 +144,42 @@ 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
+ Hosts can reserve execution headroom without changing their cadence target using
176
+ `target.frameBudgetRatio` (greater than zero and at most one). For a negotiated
177
+ 24 FPS target, `0.9` starts reduction above 37.5 ms and admits recovery below
178
+ 34.5 ms. Omit it to retain the existing thresholds. Supply the supported/preferred
179
+ frame-rate buckets for a non-default cadence. Shorter existing sample windows and
180
+ cooldowns let rapidly changing camera workloads respond earlier; they remain host
181
+ policy. Keep the ladder's recovery reserve consistent with this execution reserve.
182
+
147
183
  Ray-tracing-first budget metadata is part of the public contract:
148
184
 
149
185
  - `representationBands`: `near`, `mid`, `far`, `horizon`
@@ -487,9 +523,10 @@ GitHub Actions now carries the package delivery path:
487
523
 
488
524
  CI keeps the administrative contributor registry outside Git and npm package
489
525
  artifacts using exact, case-normalised path checks. Repository-owned pull
490
- requests and `main` execute on GitHub-hosted runners with Node.js 24.18.0 LTS.
526
+ requests and `main` execute on GitHub-hosted runners with Node.js 24.18.0 LTS
527
+ and explicit cache finalization disabled.
491
528
  Release preparation lands metadata through the protected branch, waits for
492
529
  successful exact-commit CI, and then publishes the sealed package through npm
493
- OIDC from the `production` environment. The release retains and attests the
530
+ OIDC from the `production` environment with a pinned npm 11.6.2 client. The release retains and attests the
494
531
  SBOM and complete Zero-Three evidence; there is no legacy npm token fallback.
495
532
  <!-- END PLASIUS RELEASE INTEGRITY -->
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,38 @@ 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 lastTimes = new Array(levelCount);
409
+ const recoveryRatios = new Array(levelCount);
410
+ let pending;
411
+ return {
412
+ record(index, frameTimeMs) {
413
+ const value = readNonNegativeNumber("frameTimeMs", frameTimeMs);
414
+ if (value === void 0) throw new Error("frameTimeMs is required.");
415
+ if (!enabled || value === 0) return;
416
+ lastTimes[index] = value;
417
+ if (pending?.index === index) {
418
+ recoveryRatios[index] = pending.upperTime / value;
419
+ pending = void 0;
420
+ }
421
+ },
422
+ reduced(from, to) {
423
+ const upperTime = lastTimes[from];
424
+ pending = enabled && upperTime !== void 0 ? { index: to, upperTime } : void 0;
425
+ },
426
+ canRecover(index, context) {
427
+ const ratio = recoveryRatios[index];
428
+ return !enabled || ratio === void 0 || context.metrics.latestFrameTimeMs * ratio <= context.target.targetFrameTimeMs * headroom;
429
+ }
430
+ };
431
+ }
432
+
397
433
  // src/ladder.ts
398
434
  function resolveLevelIndex(levels, initialLevel) {
399
435
  if (typeof initialLevel === "number") {
@@ -473,6 +509,7 @@ function createQualityLadderAdapter(options) {
473
509
  const levels = [...options.levels];
474
510
  const metadata = normalizePerformanceBudgetMetadata("budget metadata", options);
475
511
  let currentLevelIndex = resolveLevelIndex(levels, options.initialLevel);
512
+ const recovery = createMeasuredQualityRecovery(levels.length, options.recoveryBudget);
476
513
  const emitChange = (context, adjustment, previousLevelIndex) => {
477
514
  if (typeof options.onLevelChange !== "function") {
478
515
  return;
@@ -493,7 +530,9 @@ function createQualityLadderAdapter(options) {
493
530
  return null;
494
531
  }
495
532
  const previousLevelIndex = currentLevelIndex;
533
+ if (direction === "up" && !recovery.canRecover(currentLevelIndex, context)) return null;
496
534
  currentLevelIndex = nextLevelIndex;
535
+ if (direction === "down") recovery.reduced(previousLevelIndex, currentLevelIndex);
497
536
  const adjustment = buildAdjustment(
498
537
  direction,
499
538
  id,
@@ -519,6 +558,12 @@ function createQualityLadderAdapter(options) {
519
558
  getCurrentLevel() {
520
559
  return levels[currentLevelIndex];
521
560
  },
561
+ recordFrameTime(frameTimeMs) {
562
+ recovery.record(currentLevelIndex, frameTimeMs);
563
+ },
564
+ canStepUp(context) {
565
+ return recovery.canRecover(currentLevelIndex, context);
566
+ },
522
567
  getSnapshot() {
523
568
  return buildSnapshot(
524
569
  id,
@@ -1018,7 +1063,8 @@ function createGpuPerformanceGovernor(options) {
1018
1063
  supportedFrameRates: options.target?.supportedFrameRates ?? device.supportedFrameRates,
1019
1064
  preferredFrameRates: options.target?.preferredFrameRates,
1020
1065
  minimumFrameRate: options.target?.minimumFrameRate,
1021
- maximumFrameRate: options.target?.maximumFrameRate
1066
+ maximumFrameRate: options.target?.maximumFrameRate,
1067
+ frameBudgetRatio: options.target?.frameBudgetRatio
1022
1068
  });
1023
1069
  const modules = /* @__PURE__ */ new Map();
1024
1070
  if ((options.modules?.length ?? 0) > MAX_MODULE_COUNT) {
@@ -1208,25 +1254,26 @@ function createGpuPerformanceGovernor(options) {
1208
1254
  };
1209
1255
  const attemptRecovery = (metrics, workerGraph, decisionErrors, correlationId) => {
1210
1256
  const context = createContext("recover", "recovering", metrics, workerGraph);
1211
- while (recoveryStack.length > 0) {
1212
- const moduleId = recoveryStack[recoveryStack.length - 1];
1257
+ for (let index = recoveryStack.length - 1; index >= 0; index -= 1) {
1258
+ const moduleId = recoveryStack[index];
1213
1259
  if (!moduleId) {
1214
- recoveryStack.pop();
1260
+ recoveryStack.splice(index, 1);
1215
1261
  continue;
1216
1262
  }
1217
1263
  const module2 = modules.get(moduleId);
1218
1264
  if (!module2) {
1219
- recoveryStack.pop();
1265
+ recoveryStack.splice(index, 1);
1220
1266
  continue;
1221
1267
  }
1222
1268
  try {
1269
+ if (module2.canStepUp?.(context) === false) continue;
1223
1270
  const adjustment = module2.stepUp(context);
1224
- recoveryStack.pop();
1271
+ recoveryStack.splice(index, 1);
1225
1272
  if (adjustment) {
1226
1273
  return [adjustment];
1227
1274
  }
1228
1275
  } catch {
1229
- recoveryStack.pop();
1276
+ recoveryStack.splice(index, 1);
1230
1277
  appendError(
1231
1278
  createErrorRecord({
1232
1279
  cycle,