@plasius/gpu-renderer 0.2.43 → 0.2.44

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/gpu-renderer",
-  "version": "0.2.43",
+  "version": "0.2.44",
   "description": "Framework-agnostic WebGPU renderer runtime for Plasius projects.",
   "type": "module",
   "sideEffects": false,
@@ -27,7 +27,7 @@
   "scripts": {
     "build": "tsup",
     "demo": "python3 -m http.server --directory ..",
-    "typecheck": "node scripts/check-source-syntax.cjs",
+    "typecheck": "node scripts/check-source-syntax.cjs && tsc -p tsconfig.types.json && node scripts/verify-clean-type-consumer.cjs",
     "audit:eslint": "eslint . --max-warnings=0",
     "audit:deps": "npm ls --all --omit=optional --omit=peer > /dev/null 2>&1 || true",
     "audit:npm": "npm audit --audit-level=high --omit=dev",
@@ -53,14 +53,15 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@plasius/gpu-camera": "^0.1.18",
-    "@plasius/gpu-shared": "^1.0.14",
-    "@plasius/gpu-xr": "^0.1.17"
+    "@plasius/gpu-shared": "^1.1.1",
+    "@plasius/gpu-xr": "^0.1.17",
+    "@types/webxr": "^0.5.24"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "c8": "^11.0.0",
-    "eslint": "^10.6.0",
-    "globals": "^17.7.0",
+    "eslint": "^10.9.1",
+    "globals": "^17.11.0",
     "tsup": "^8.5.1",
     "typescript": "^7.0.2"
   },

package/src/feedback-diagnostics.js

@@ -0,0 +1,190 @@
+import {
+  FEEDBACK_GAME_DIAGNOSTICS_CONTRACT_VERSION,
+  feedbackGameDiagnosticSurfaceRegistrations,
+  parseFeedbackGameDiagnostics,
+} from "@plasius/gpu-shared/feedback-diagnostics";
+
+const inputKeys = Object.freeze([
+  "featureEnabled",
+  "capabilityGranted",
+  "consentConfirmed",
+  "surfaceId",
+  "renderer",
+  "backend",
+  "viewportWidth",
+  "viewportHeight",
+  "frameRate",
+  "frameTimeMs",
+  "featureIds",
+  "counters",
+  "errorCodes",
+]);
+
+export 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 < 1_440
+        ? "medium"
+        : "large";
+  const orientation = width > height ? "landscape" : "portrait";
+  return `${size}-${orientation}`;
+}
+
+export 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";
+}
+
+export 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";
+}
+
+export 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(
+      feedbackGameDiagnosticSurfaceRegistrations,
+      snapshot.surfaceId
+    )
+      ? feedbackGameDiagnosticSurfaceRegistrations[snapshot.surfaceId]
+      : undefined;
+
+  return parseFeedbackGameDiagnostics({
+    type: "feedback-game-diagnostics",
+    version: 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 = Object.create(null);
+  for (const key of gateKeys) {
+    const descriptor = Object.getOwnPropertyDescriptor(input, key);
+    assertValid(
+      descriptor !== undefined &&
+        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((key) => !gateKeys.includes(key))) {
+    const descriptor = Object.getOwnPropertyDescriptor(input, key);
+    assertValid(
+      descriptor !== undefined &&
+        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.");
+  }
+}

package/src/index.d.ts

@@ -1,3 +1,60 @@
+/// <reference types="webxr" />
+
+import type {
+  FeedbackGameDiagnosticBackend,
+  FeedbackGameDiagnosticCounter,
+  FeedbackGameDiagnosticErrorCode,
+  FeedbackGameDiagnosticFeatureId,
+  FeedbackGameDiagnosticFrameRateBucket,
+  FeedbackGameDiagnosticFrameTimeBucket,
+  FeedbackGameDiagnostics,
+  FeedbackGameDiagnosticRenderer,
+  FeedbackGameDiagnosticSurfaceId,
+  FeedbackGameDiagnosticViewportBucket,
+} from "@plasius/gpu-shared/feedback-diagnostics";
+import type { XrStoreState } from "@plasius/gpu-xr";
+
+export interface CreateFeedbackGameDiagnosticSnapshotInput {
+  readonly featureEnabled: boolean;
+  readonly capabilityGranted: boolean;
+  readonly consentConfirmed: boolean;
+  readonly surfaceId: FeedbackGameDiagnosticSurfaceId;
+  readonly renderer: FeedbackGameDiagnosticRenderer;
+  readonly backend: FeedbackGameDiagnosticBackend;
+  /** CSS-pixel viewport width; it is bucketed synchronously and never returned. */
+  readonly viewportWidth: number | null;
+  /** CSS-pixel viewport height; it is bucketed synchronously and never returned. */
+  readonly viewportHeight: number | null;
+  /** Recent coarse FPS observation; it is bucketed synchronously and never returned. */
+  readonly frameRate: number | null;
+  /** Recent coarse frame-time observation; it is bucketed synchronously and never returned. */
+  readonly frameTimeMs: number | null;
+  readonly featureIds: readonly FeedbackGameDiagnosticFeatureId[];
+  readonly counters: readonly FeedbackGameDiagnosticCounter[];
+  readonly errorCodes: readonly FeedbackGameDiagnosticErrorCode[];
+}
+
+export function bucketFeedbackGameViewport(
+  width: unknown,
+  height: unknown,
+): FeedbackGameDiagnosticViewportBucket;
+
+export function bucketFeedbackGameFrameRate(
+  frameRate: unknown,
+): FeedbackGameDiagnosticFrameRateBucket;
+
+export function bucketFeedbackGameFrameTime(
+  frameTimeMs: unknown,
+): FeedbackGameDiagnosticFrameTimeBucket;
+
+export function createFeedbackGameDiagnosticSnapshot<
+  SurfaceId extends FeedbackGameDiagnosticSurfaceId,
+>(
+  input: CreateFeedbackGameDiagnosticSnapshotInput & {
+    readonly surfaceId: SurfaceId;
+  },
+): Extract<FeedbackGameDiagnostics, { readonly surfaceId: SurfaceId }> | null;
+
 export type RendererColor = string | [number, number, number, number?];
 export type AnimatedSceneVector3 = readonly [number, number, number] | readonly number[];
 export type AnimatedScenePropKind =
@@ -509,7 +566,6 @@ export interface WavefrontMeshInput {
   readonly occlusionTexture?: WavefrontTextureSampleInput | null;
   readonly emissiveTexture?: WavefrontTextureSampleInput | null;
   readonly medium?: WavefrontMediumInput | null;
-  readonly extensions?: Record<string, Record<string, unknown>>;
 }
 
 export interface WavefrontTriangleRecord {
@@ -1594,13 +1650,12 @@ export interface GpuRenderer {
   setXrActive(active: boolean): void;
   getSnapshot(): RendererSnapshot;
   bindXrManager(
-    xrManager: {
-      subscribe: (listener: (state: { activeSession: XRSession | null }) => void) => () => void;
-      getState?: () => { activeSession: XRSession | null };
-      store?: { getSnapshot: () => { activeSession: XRSession | null } };
-    },
+    xrManager: RendererXrManager,
     bindOptions?: {
-      onSessionStart?: (session: XRSession, renderer: GpuRenderer) => void;
+      onSessionStart?: (
+        session: NonNullable<XrStoreState["activeSession"]>,
+        renderer: GpuRenderer
+      ) => void;
       onSessionEnd?: (renderer: GpuRenderer) => void;
     }
   ): () => void;
@@ -1636,15 +1691,22 @@ export function createRendererDebugHooks(
   options: RendererDebugHooksOptions
 ): Pick<RendererHooks, "onFrameStart" | "onFrameComplete">;
 
+export type RendererXrState = Pick<XrStoreState, "activeSession">;
+
+export interface RendererXrManager {
+  subscribe(listener: (state: RendererXrState) => void): () => void;
+  getState?(): RendererXrState;
+  store?: { getSnapshot(): RendererXrState };
+}
+
 export function bindRendererToXrManager(
   renderer: Pick<GpuRenderer, "setXrActive">,
-  xrManager: {
-    subscribe: (listener: (state: { activeSession: XRSession | null }) => void) => () => void;
-    getState?: () => { activeSession: XRSession | null };
-    store?: { getSnapshot: () => { activeSession: XRSession | null } };
-  },
+  xrManager: RendererXrManager,
   options?: {
-    onSessionStart?: (session: XRSession, renderer: Pick<GpuRenderer, "setXrActive">) => void;
+    onSessionStart?: (
+      session: NonNullable<XrStoreState["activeSession"]>,
+      renderer: Pick<GpuRenderer, "setXrActive">
+    ) => void;
     onSessionEnd?: (renderer: Pick<GpuRenderer, "setXrActive">) => void;
   }
 ): () => void;

package/src/index.js

@@ -4,6 +4,12 @@ export {
 export {
   createProfessionalAnimatedSceneRenderer,
 } from "./professional-animated-scene-renderer.js";
+export {
+  bucketFeedbackGameFrameRate,
+  bucketFeedbackGameFrameTime,
+  bucketFeedbackGameViewport,
+  createFeedbackGameDiagnosticSnapshot,
+} from "./feedback-diagnostics.js";
 export {
   createDefaultWavefrontSceneObjects,
   createWavefrontBvhBuildLevels,

package/src/wavefront-compute.js

@@ -211,6 +211,10 @@ export async function createWavefrontPathTracingComputeRenderer(options = {}) {
       width: config.width,
       height: config.height,
       tileSize: safeTileSize,
+      tilePixelCapacity: Math.min(
+        config.tilePixelCapacity,
+        safeTileSize * safeTileSize
+      ),
     });
   }
   config = Object.freeze({

package/src/wavefront-gpu-resources.js

@@ -4,6 +4,7 @@ import {
   DEFAULT_BRDF_LUT_SIZE,
   HIT_RECORD_BYTES,
   MEDIUM_TABLE_ROWS,
+  PATH_VERTEX_RECORD_BYTES,
   RAY_RECORD_BYTES,
 } from "./wavefront-core.js";
 import {
@@ -28,7 +29,13 @@ export 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;
   }