@plasius/gpu-renderer 0.2.43 → 0.2.45

package/CHANGELOG.md

@@ -23,6 +23,46 @@ All notable changes to this project will be documented in this file.
 - **Security**
   - (placeholder)
 
+## [0.2.45] - 2026-09-07
+
+- **Added**
+  - (placeholder)
+
+- **Changed**
+  - Refreshed compatible @plasius/* lockfile resolutions to the latest published releases.
+ - (placeholder)
+
+- **Fixed**
+  - Documented verified locked-branch runner admission for trusted push checks,
+    including exact-commit verification and removal before branch updates.
+  - Restored trusted-push-only CI on explicit self-hosted runners, preserving
+    required check names and excluding external fork execution; bounded scheduled
+    dependency validation to self-hosted main runs.
+  - Preserved hosted pull-request isolation, bounded validation runtime, and
+    disabled package-manager cache finalization on self-hosted main validation.
+  - (placeholder)
+
+- **Security**
+  - (placeholder)
+
+## [0.2.44] - 2026-08-31
+
+- **Added**
+  - Added an explicit consent-, flag-, and capability-gated helper that converts
+    coarse renderer health observations into the closed shared feedback
+    diagnostics packet for approved generator and GPU demo surfaces.
+
+- **Changed**
+  - Updated `@plasius/gpu-shared` to the protected-CD-published 1.1.1 release
+    that exposes the focused feedback-diagnostics contract, and revalidated
+    the renderer against the registry artifact.
+
+- **Fixed**
+  - (placeholder)
+
+- **Security**
+  - (placeholder)
+
 ## [0.2.43] - 2026-08-31
 
 - **Added**
@@ -90,11 +130,21 @@ All notable changes to this project will be documented in this file.
 
 - **Changed**
   - Updated internal GPU dependencies to their surviving clean lines and refreshed the esbuild resolution.
+  - Bound diagnostics to the focused shared-package subpath and canonical
+    contract-version export, and enabled complete declaration checking with the
+    published WebXR type definitions.
 
 - **Fixed**
-  - (placeholder)
+  - Removed a duplicate public mesh `extensions` declaration and replaced
+    unresolved ambient XR session references with the `@plasius/gpu-xr` state
+    contract.
 
 - **Security**
+  - Updated the development-tool dependency graph to the patched
+    `brace-expansion` release after the feedback release audit.
+  - Kept feedback diagnostics separate from general renderer snapshots and
+    excluded user-captured pixels, DOM, player data, URLs, filenames, exact
+    measurements, adapter identity and raw warnings from the output contract.
   - Added permanent fail-closed Zero-Three validation for manifests, source,
     locks, installed dependency graphs, declarations, bundles, npm tarballs,
     CycloneDX SBOMs, and active documentation, with digest-bound evidence
@@ -657,6 +707,9 @@ All notable changes to this project will be documented in this file.
     contract used by the wavefront display-quality renderer.
 
 - **Fixed**
+  - Clamped wavefront tile capacity against the depth-scaled path-vertex
+    storage binding so supported high-depth reference renders stay within
+    `maxStorageBufferBindingSize`.
   - Raised the bounded wavefront `maxDepth` ceiling to 32 so offline/reference
     renders can request 20-bounce paths without being clamped by renderer
     configuration.
@@ -684,6 +737,9 @@ All notable changes to this project will be documented in this file.
     corruption and stalled validation captures on higher-SPP frames.
 
 - **Changed**
+  - Raised the bounded wavefront `maxDepth` ceiling to 32 so offline/reference
+    renders can request 20-bounce paths without being clamped by renderer
+    configuration.
   - Changed internal wavefront frame batching and dispatch-diagnostics plumbing
     to live in a dedicated runtime helper module so scheduling concerns stay
     separated from shader and pipeline assembly.
@@ -1069,3 +1125,5 @@ All notable changes to this project will be documented in this file.
 [0.2.41]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.41
 [0.2.42]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.42
 [0.2.43]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.43
+[0.2.44]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.44
+[0.2.45]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.45

package/README.md

@@ -8,19 +8,56 @@
 [![Security Policy](https://img.shields.io/badge/security%20policy-yes-orange.svg)](./SECURITY.md)
 [![Changelog](https://img.shields.io/badge/changelog-md-blue.svg)](./CHANGELOG.md)
 
-[![license](https://img.shields.io/github/license/Plasius-LTD/gpu-renderer)](./LICENSE)
-
 Framework-agnostic WebGPU renderer runtime for Plasius projects.
 This package is intended to replace Three.js-dependent render orchestration with
 an explicit WebGPU-first runtime that can be consumed from React, vanilla, or
 worker-driven app surfaces.
 
 The package targets Node.js 24, consumes the stable `@plasius/gpu-shared` 1.x
-runtime line (`^1.0.12`), and validates its development tooling against the
+runtime line (`^1.1.1`), and validates its development tooling against the
 current ESLint 10 and TypeScript 7 baselines.
 
 Apache-2.0. ESM + CJS builds.
 
+## Privacy-Safe Feedback Diagnostics
+
+Approved in-game viewers can explicitly convert a small set of current renderer
+health observations into the closed
+`@plasius/gpu-shared/feedback-diagnostics` packet:
+
+```js
+import { createFeedbackGameDiagnosticSnapshot } from "@plasius/gpu-renderer";
+
+const diagnostics = createFeedbackGameDiagnosticSnapshot({
+  featureEnabled,
+  capabilityGranted,
+  consentConfirmed: true,
+  surfaceId: "site.gpu-demo",
+  renderer: "webgpu",
+  backend: "worker",
+  viewportWidth: 1920,
+  viewportHeight: 1080,
+  frameRate: 59.9,
+  frameTimeMs: 16.7,
+  featureIds: ["renderer.frame-loop"],
+  counters: [{ code: "frame-drop", count: 2 }],
+  errorCodes: [],
+});
+```
+
+The helper returns `null` before reading renderer observations unless the
+remotely evaluated `feedback.game-diagnostics.enabled` flag, the
+`feedback.game-diagnostics.attach` capability, and explicit consent are all
+present. It derives trusted provenance and returns only coarse buckets and
+closed codes.
+
+This API is deliberately separate from general renderer snapshots. It accepts
+no canvas, user-captured pixels, DOM, player object, URL, filename,
+adapter/device detail, coordinate or raw warning, performs no automatic
+diagnostic capture or network/storage operation, and never registers
+`/player-system`. Disabling the flag preserves ordinary structured-only bug
+reporting.
+
 ## Install
 
 ```sh
@@ -654,9 +691,23 @@ npm run pack:check
 ## Release integrity
 
 CI keeps the administrative contributor registry outside Git and npm package
-artifacts using exact, case-normalised path checks. External fork heads are
-rejected; same-repository pull requests validate on GitHub-hosted runners and
-main pushes validate on approved self-hosted runners. Release preparation and
+artifacts using exact, case-normalised path checks. CI runs only for pushes to
+repository-owned branches on explicit `[self-hosted, Linux, X64]` runners.
+External fork pull requests trigger no CI execution; a maintainer must review
+and move a contribution to a repository-owned branch to produce required checks.
+Before branch CI starts, an authorised maintainer reviews the exact commit and
+locks its repository branch as read-only, enforcing the lock for administrators
+and disabling force pushes, deletion, and fork syncing. After reading back the
+lock and commit SHA, admit only that branch's fully qualified workflow ref for
+`gpu-renderer/.github/workflows/ci.yml` in `Public CI - Quarantined`. Top-level
+push jobs identify their workflow by branch ref; SHA-only admission did not
+schedule the reviewed job. Remove the temporary workflow entry and verify its
+removal before unlocking or updating the branch, and after delivery. Preserve all
+other group restrictions. Never admit mutable branch or PR refs. See
+[ADR-0028](docs/adrs/adr-0028-locked-branch-runner-admission.md) for the procedure.
+The trusted admission, build-test, and artifact-integrity checks keep their
+existing names for branch protection. Scheduled dependency validation also uses
+bounded self-hosted capacity and accepts only `main`. Release preparation and
 publication use a two-run exact-main protocol on GitHub-hosted Node.js 24.18.0
 LTS. A read-only job seals the package tarball and SBOM before a dependency-free
 production job publishes that exact artifact through npm OIDC with provenance;

package/dist/index.cjs

@@ -24,8 +24,12 @@ __export(index_exports, {
   applyMediumTransmittance: () => applyMediumTransmittance,
   beerLambertTransmittance: () => beerLambertTransmittance,
   bindRendererToXrManager: () => bindRendererToXrManager,
+  bucketFeedbackGameFrameRate: () => bucketFeedbackGameFrameRate,
+  bucketFeedbackGameFrameTime: () => bucketFeedbackGameFrameTime,
+  bucketFeedbackGameViewport: () => bucketFeedbackGameViewport,
   createAnimatedSceneRenderer: () => createAnimatedSceneRenderer,
   createDefaultWavefrontSceneObjects: () => createDefaultWavefrontSceneObjects,
+  createFeedbackGameDiagnosticSnapshot: () => createFeedbackGameDiagnosticSnapshot,
   createGpuRenderer: () => createGpuRenderer,
   createMediumStack: () => createMediumStack,
   createProfessionalAnimatedSceneRenderer: () => createProfessionalAnimatedSceneRenderer,
@@ -2294,6 +2298,140 @@ async function createProfessionalAnimatedSceneRenderer(options = {}) {
   };
 }
 
+// src/feedback-diagnostics.js
+var import_feedback_diagnostics = require("@plasius/gpu-shared/feedback-diagnostics");
+var inputKeys = Object.freeze([
+  "featureEnabled",
+  "capabilityGranted",
+  "consentConfirmed",
+  "surfaceId",
+  "renderer",
+  "backend",
+  "viewportWidth",
+  "viewportHeight",
+  "frameRate",
+  "frameTimeMs",
+  "featureIds",
+  "counters",
+  "errorCodes"
+]);
+function bucketFeedbackGameViewport(width, height) {
+  if (typeof width !== "number" || typeof height !== "number" || !Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+    return "unknown";
+  }
+  const shorterEdge = Math.min(width, height);
+  const longerEdge = Math.max(width, height);
+  const size = shorterEdge < 600 ? "small" : shorterEdge < 900 || longerEdge < 1440 ? "medium" : "large";
+  const orientation = width > height ? "landscape" : "portrait";
+  return `${size}-${orientation}`;
+}
+function bucketFeedbackGameFrameRate(frameRate) {
+  if (typeof frameRate !== "number" || !Number.isFinite(frameRate) || frameRate < 0) {
+    return "unknown";
+  }
+  if (frameRate < 15) {
+    return "under-15";
+  }
+  if (frameRate < 30) {
+    return "15-29";
+  }
+  if (frameRate < 60) {
+    return "30-59";
+  }
+  return "60-plus";
+}
+function bucketFeedbackGameFrameTime(frameTimeMs) {
+  if (typeof frameTimeMs !== "number" || !Number.isFinite(frameTimeMs) || frameTimeMs < 0) {
+    return "unknown";
+  }
+  if (frameTimeMs < 17) {
+    return "under-17ms";
+  }
+  if (frameTimeMs < 34) {
+    return "17-33ms";
+  }
+  if (frameTimeMs < 67) {
+    return "34-66ms";
+  }
+  return "over-66ms";
+}
+function createFeedbackGameDiagnosticSnapshot(input) {
+  try {
+    return createFeedbackGameDiagnosticSnapshotInternal(input);
+  } catch {
+    throw new TypeError("Invalid privacy-safe renderer diagnostics input.");
+  }
+}
+function createFeedbackGameDiagnosticSnapshotInternal(input) {
+  const snapshot = snapshotInputIfEnabled(input);
+  if (snapshot === null) {
+    return null;
+  }
+  const registration = typeof snapshot.surfaceId === "string" && Object.hasOwn(
+    import_feedback_diagnostics.feedbackGameDiagnosticSurfaceRegistrations,
+    snapshot.surfaceId
+  ) ? import_feedback_diagnostics.feedbackGameDiagnosticSurfaceRegistrations[snapshot.surfaceId] : void 0;
+  return (0, import_feedback_diagnostics.parseFeedbackGameDiagnostics)({
+    type: "feedback-game-diagnostics",
+    version: import_feedback_diagnostics.FEEDBACK_GAME_DIAGNOSTICS_CONTRACT_VERSION,
+    surfaceId: snapshot.surfaceId,
+    consentConfirmed: true,
+    provenanceContractId: registration?.provenanceContractId,
+    renderer: snapshot.renderer,
+    backend: snapshot.backend,
+    viewportBucket: bucketFeedbackGameViewport(
+      snapshot.viewportWidth,
+      snapshot.viewportHeight
+    ),
+    frameRateBucket: bucketFeedbackGameFrameRate(snapshot.frameRate),
+    frameTimeBucket: bucketFeedbackGameFrameTime(snapshot.frameTimeMs),
+    featureIds: snapshot.featureIds,
+    counters: snapshot.counters,
+    errorCodes: snapshot.errorCodes
+  });
+}
+function snapshotInputIfEnabled(input) {
+  assertValid(
+    input !== null && typeof input === "object" && !Array.isArray(input) && (Object.getPrototypeOf(input) === Object.prototype || Object.getPrototypeOf(input) === null)
+  );
+  const gateKeys = [
+    "featureEnabled",
+    "capabilityGranted",
+    "consentConfirmed"
+  ];
+  const snapshot = /* @__PURE__ */ Object.create(null);
+  for (const key of gateKeys) {
+    const descriptor = Object.getOwnPropertyDescriptor(input, key);
+    assertValid(
+      descriptor !== void 0 && descriptor.enumerable === true && Object.hasOwn(descriptor, "value") && typeof descriptor.value === "boolean"
+    );
+    snapshot[key] = descriptor.value;
+  }
+  const { featureEnabled, capabilityGranted, consentConfirmed } = snapshot;
+  if (!featureEnabled || !capabilityGranted || !consentConfirmed) {
+    return null;
+  }
+  const actualKeys = Reflect.ownKeys(input);
+  assertValid(
+    actualKeys.length === inputKeys.length && inputKeys.every((key) => actualKeys.includes(key)) && actualKeys.every(
+      (key) => typeof key === "string" && inputKeys.includes(key)
+    )
+  );
+  for (const key of inputKeys.filter((key2) => !gateKeys.includes(key2))) {
+    const descriptor = Object.getOwnPropertyDescriptor(input, key);
+    assertValid(
+      descriptor !== void 0 && descriptor.enumerable === true && Object.hasOwn(descriptor, "value")
+    );
+    snapshot[key] = descriptor.value;
+  }
+  return Object.freeze(snapshot);
+}
+function assertValid(condition) {
+  if (!condition) {
+    throw new TypeError("Invalid privacy-safe renderer diagnostics input.");
+  }
+}
+
 // src/wavefront-frame-runtime.js
 function createGpuParallelismCounters() {
   return {
@@ -5139,7 +5277,13 @@ function clampTileSizeForDevice(config, device) {
   }
   const maxPixelsByRay = Math.floor(limit / RAY_RECORD_BYTES);
   const maxPixelsByHit = Math.floor(limit / HIT_RECORD_BYTES);
-  const maxPixels = Math.max(256, Math.min(maxPixelsByRay, maxPixelsByHit));
+  const maxPixelsByPathVertex = Math.floor(
+    limit / ((config.maxDepth + 1) * PATH_VERTEX_RECORD_BYTES)
+  );
+  const maxPixels = Math.max(
+    256,
+    Math.min(maxPixelsByRay, maxPixelsByHit, maxPixelsByPathVertex)
+  );
   if (config.tilePixelCapacity <= maxPixels) {
     return config.tileSize;
   }
@@ -11447,7 +11591,11 @@ async function createWavefrontPathTracingComputeRenderer(options = {}) {
       canvas,
       width: config.width,
       height: config.height,
-      tileSize: safeTileSize
+      tileSize: safeTileSize,
+      tilePixelCapacity: Math.min(
+        config.tilePixelCapacity,
+        safeTileSize * safeTileSize
+      )
     });
   }
   config = Object.freeze({
@@ -13265,8 +13413,12 @@ function createRayTracingRenderPlan(options = {}) {
   applyMediumTransmittance,
   beerLambertTransmittance,
   bindRendererToXrManager,
+  bucketFeedbackGameFrameRate,
+  bucketFeedbackGameFrameTime,
+  bucketFeedbackGameViewport,
   createAnimatedSceneRenderer,
   createDefaultWavefrontSceneObjects,
+  createFeedbackGameDiagnosticSnapshot,
   createGpuRenderer,
   createMediumStack,
   createProfessionalAnimatedSceneRenderer,