@plasius/gpu-renderer 0.1.6 → 0.1.8

package/dist/index.cjs

@@ -21,12 +21,660 @@ var index_exports = {};
 __export(index_exports, {
   bindRendererToXrManager: () => bindRendererToXrManager,
   createGpuRenderer: () => createGpuRenderer,
+  createRayTracingRenderPlan: () => createRayTracingRenderPlan,
+  createRendererDebugHooks: () => createRendererDebugHooks,
   defaultRendererClearColor: () => defaultRendererClearColor,
+  defaultRendererWorkerProfile: () => defaultRendererWorkerProfile,
+  getRendererWorkerManifest: () => getRendererWorkerManifest,
+  getRendererWorkerProfile: () => getRendererWorkerProfile,
+  rendererAccelerationStructureUpdateClasses: () => rendererAccelerationStructureUpdateClasses,
+  rendererDebugOwner: () => rendererDebugOwner,
+  rendererRayTracingStageOrder: () => rendererRayTracingStageOrder,
+  rendererRepresentationBands: () => rendererRepresentationBands,
+  rendererWorkerManifests: () => rendererWorkerManifests,
+  rendererWorkerProfileNames: () => rendererWorkerProfileNames,
+  rendererWorkerProfiles: () => rendererWorkerProfiles,
+  rendererWorkerQueueClass: () => rendererWorkerQueueClass,
   supportsWebGpu: () => supportsWebGpu
 });
 module.exports = __toCommonJS(index_exports);
 var DEFAULT_CLEAR_COLOR = Object.freeze([0.07, 0.11, 0.18, 1]);
 var DEFAULT_CANVAS_SELECTOR = "canvas[data-plasius-gpu-renderer]";
+var rendererDebugOwner = "renderer";
+var rendererWorkerQueueClass = "render";
+var defaultRendererWorkerProfile = "realtime";
+var rendererRepresentationBands = Object.freeze([
+  "near",
+  "mid",
+  "far",
+  "horizon"
+]);
+var rendererAccelerationStructureUpdateClasses = Object.freeze([
+  "static",
+  "rigid-dynamic",
+  "deforming",
+  "proxy"
+]);
+var rendererRayTracingStageOrder = Object.freeze([
+  "primaryVisibility",
+  "shadowAssist",
+  "opaqueFoundation",
+  "rtDirectLighting",
+  "rtReflections",
+  "rtGlobalIllumination",
+  "denoiseTemporal",
+  "transparents",
+  "composition",
+  "present"
+]);
+var rendererRayTracingStageDefinitions = Object.freeze(
+  rendererRayTracingStageOrder.map(
+    (key, index) => Object.freeze({
+      key,
+      order: index + 1,
+      required: true,
+      description: {
+        primaryVisibility: "Primary visibility and depth preparation.",
+        shadowAssist: "Shadow assist passes and regional shadow preparation.",
+        opaqueFoundation: "Main opaque foundation for shading and tracing inputs.",
+        rtDirectLighting: "Ray-traced direct lighting and premium shadows.",
+        rtReflections: "Ray-traced reflections for important surfaces.",
+        rtGlobalIllumination: "Selective ray-traced indirect lighting and GI.",
+        denoiseTemporal: "Required denoise and temporal accumulation stage.",
+        transparents: "Transparents, particles, and volumetrics composition.",
+        composition: "Final world composition and color resolve.",
+        present: "Presentation to the active surface."
+      }[key]
+    })
+  )
+);
+var rendererRepresentationBandPolicies = Object.freeze({
+  near: Object.freeze({
+    band: "near",
+    rasterMode: "full-live",
+    rtParticipation: "premium",
+    shadowSource: "ray-traced-primary",
+    temporalReuse: "balanced",
+    updateCadenceDivisor: 1
+  }),
+  mid: Object.freeze({
+    band: "mid",
+    rasterMode: "simplified-live",
+    rtParticipation: "selective",
+    shadowSource: "regional-raster-and-proxy",
+    temporalReuse: "aggressive",
+    updateCadenceDivisor: 2
+  }),
+  far: Object.freeze({
+    band: "far",
+    rasterMode: "proxy-or-cached",
+    rtParticipation: "proxy",
+    shadowSource: "merged-proxy-casters",
+    temporalReuse: "high",
+    updateCadenceDivisor: 8
+  }),
+  horizon: Object.freeze({
+    band: "horizon",
+    rasterMode: "horizon-shell",
+    rtParticipation: "disabled",
+    shadowSource: "baked-impression",
+    temporalReuse: "cached",
+    updateCadenceDivisor: 60
+  })
+});
+var rendererAccelerationStructurePolicies = Object.freeze(
+  rendererAccelerationStructureUpdateClasses.map(
+    (updateClass) => Object.freeze({
+      updateClass,
+      description: {
+        static: "Stable static world geometry with infrequent rebuilds.",
+        "rigid-dynamic": "Rigid transforms that can be refit or relinked without full deformation updates.",
+        deforming: "Skinned or vertex-deforming content treated as a managed RT cost center.",
+        proxy: "Low-cost RT proxy or distant representation updates."
+      }[updateClass]
+    })
+  )
+);
+function buildRendererWorkerBudgetLevels(jobType, queueClass, levels) {
+  return Object.freeze(
+    levels.map(
+      (level) => Object.freeze({
+        id: level.id,
+        estimatedCostMs: level.estimatedCostMs,
+        config: Object.freeze({
+          maxDispatchesPerFrame: level.config.maxDispatchesPerFrame,
+          maxJobsPerDispatch: level.config.maxJobsPerDispatch,
+          cadenceDivisor: level.config.cadenceDivisor,
+          workgroupScale: level.config.workgroupScale,
+          maxQueueDepth: level.config.maxQueueDepth,
+          metadata: Object.freeze({
+            owner: rendererDebugOwner,
+            queueClass,
+            jobType,
+            quality: level.id
+          })
+        })
+      })
+    )
+  );
+}
+var rendererWorkerProfileSpecs = {
+  realtime: {
+    description: "Frame-stage DAG for flat rendering with visibility, main encode, post-processing, and submit.",
+    suggestedAllocationIds: [
+      "renderer.surface.current",
+      "renderer.visibility.worklist",
+      "renderer.post-process.history"
+    ],
+    jobs: {
+      acquire: {
+        priority: 5,
+        dependencies: [],
+        domain: "resolution",
+        importance: "critical",
+        levels: [
+          {
+            id: "fixed",
+            estimatedCostMs: 0.2,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 1
+            }
+          }
+        ],
+        suggestedAllocationIds: ["renderer.surface.current"]
+      },
+      visibility: {
+        priority: 4,
+        dependencies: [],
+        domain: "geometry",
+        importance: "high",
+        levels: [
+          {
+            id: "low",
+            estimatedCostMs: 0.4,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 128,
+              cadenceDivisor: 2,
+              workgroupScale: 0.5,
+              maxQueueDepth: 256
+            }
+          },
+          {
+            id: "medium",
+            estimatedCostMs: 0.8,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 256,
+              cadenceDivisor: 1,
+              workgroupScale: 0.75,
+              maxQueueDepth: 384
+            }
+          },
+          {
+            id: "high",
+            estimatedCostMs: 1.2,
+            config: {
+              maxDispatchesPerFrame: 2,
+              maxJobsPerDispatch: 512,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 512
+            }
+          }
+        ],
+        suggestedAllocationIds: ["renderer.visibility.worklist"]
+      },
+      mainEncode: {
+        priority: 4,
+        dependencies: ["acquire", "visibility"],
+        domain: "geometry",
+        importance: "critical",
+        levels: [
+          {
+            id: "low",
+            estimatedCostMs: 1.2,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 128,
+              cadenceDivisor: 1,
+              workgroupScale: 0.6,
+              maxQueueDepth: 192
+            }
+          },
+          {
+            id: "medium",
+            estimatedCostMs: 2.1,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 256,
+              cadenceDivisor: 1,
+              workgroupScale: 0.8,
+              maxQueueDepth: 256
+            }
+          },
+          {
+            id: "high",
+            estimatedCostMs: 3,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 384,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 384
+            }
+          }
+        ],
+        suggestedAllocationIds: ["renderer.surface.current"]
+      },
+      postProcess: {
+        priority: 3,
+        dependencies: ["mainEncode"],
+        domain: "post-processing",
+        importance: "high",
+        levels: [
+          {
+            id: "low",
+            estimatedCostMs: 0.5,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 64,
+              cadenceDivisor: 2,
+              workgroupScale: 0.5,
+              maxQueueDepth: 96
+            }
+          },
+          {
+            id: "medium",
+            estimatedCostMs: 0.9,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 128,
+              cadenceDivisor: 1,
+              workgroupScale: 0.75,
+              maxQueueDepth: 128
+            }
+          },
+          {
+            id: "high",
+            estimatedCostMs: 1.4,
+            config: {
+              maxDispatchesPerFrame: 2,
+              maxJobsPerDispatch: 192,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 192
+            }
+          }
+        ],
+        suggestedAllocationIds: ["renderer.post-process.history"]
+      },
+      submit: {
+        priority: 2,
+        dependencies: ["postProcess"],
+        domain: "resolution",
+        importance: "critical",
+        levels: [
+          {
+            id: "fixed",
+            estimatedCostMs: 0.2,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 1
+            }
+          }
+        ],
+        suggestedAllocationIds: ["renderer.surface.current"]
+      }
+    }
+  },
+  xr: {
+    description: "Frame-stage DAG for XR rendering with late-latch coordination before main encode and submit.",
+    suggestedAllocationIds: [
+      "renderer.xr.surface.current",
+      "renderer.xr.visibility.worklist"
+    ],
+    jobs: {
+      acquire: {
+        priority: 5,
+        dependencies: [],
+        domain: "xr",
+        importance: "critical",
+        levels: [
+          {
+            id: "fixed",
+            estimatedCostMs: 0.2,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 1
+            }
+          }
+        ],
+        suggestedAllocationIds: ["renderer.xr.surface.current"]
+      },
+      visibility: {
+        priority: 4,
+        dependencies: [],
+        domain: "geometry",
+        importance: "high",
+        levels: [
+          {
+            id: "low",
+            estimatedCostMs: 0.5,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 96,
+              cadenceDivisor: 2,
+              workgroupScale: 0.5,
+              maxQueueDepth: 192
+            }
+          },
+          {
+            id: "medium",
+            estimatedCostMs: 0.9,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 192,
+              cadenceDivisor: 1,
+              workgroupScale: 0.75,
+              maxQueueDepth: 256
+            }
+          },
+          {
+            id: "high",
+            estimatedCostMs: 1.3,
+            config: {
+              maxDispatchesPerFrame: 2,
+              maxJobsPerDispatch: 320,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 320
+            }
+          }
+        ],
+        suggestedAllocationIds: ["renderer.xr.visibility.worklist"]
+      },
+      lateLatch: {
+        priority: 5,
+        dependencies: ["acquire"],
+        domain: "xr",
+        importance: "critical",
+        levels: [
+          {
+            id: "fixed",
+            estimatedCostMs: 0.15,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 1
+            }
+          }
+        ],
+        suggestedAllocationIds: ["renderer.xr.surface.current"]
+      },
+      mainEncode: {
+        priority: 4,
+        dependencies: ["visibility", "lateLatch"],
+        domain: "xr",
+        importance: "critical",
+        levels: [
+          {
+            id: "low",
+            estimatedCostMs: 1.1,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 96,
+              cadenceDivisor: 1,
+              workgroupScale: 0.6,
+              maxQueueDepth: 128
+            }
+          },
+          {
+            id: "medium",
+            estimatedCostMs: 1.8,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 192,
+              cadenceDivisor: 1,
+              workgroupScale: 0.8,
+              maxQueueDepth: 192
+            }
+          },
+          {
+            id: "high",
+            estimatedCostMs: 2.6,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 256,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 256
+            }
+          }
+        ],
+        suggestedAllocationIds: ["renderer.xr.surface.current"]
+      },
+      submit: {
+        priority: 2,
+        dependencies: ["mainEncode"],
+        domain: "xr",
+        importance: "critical",
+        levels: [
+          {
+            id: "fixed",
+            estimatedCostMs: 0.2,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 1
+            }
+          }
+        ],
+        suggestedAllocationIds: ["renderer.xr.surface.current"]
+      }
+    }
+  }
+};
+function buildRendererInputBoundary(profile) {
+  return Object.freeze({
+    type: "stable-visual-snapshot",
+    owner: rendererDebugOwner,
+    profile,
+    authority: "visual",
+    source: "scene-preparation",
+    stable: true
+  });
+}
+function buildRendererRenderStages(profile) {
+  return Object.freeze(
+    rendererRayTracingStageDefinitions.map(
+      (stage) => Object.freeze({
+        ...stage,
+        profile,
+        workerJobKeys: profile === "xr" && stage.key === "primaryVisibility" ? Object.freeze(["lateLatch", "visibility"]) : stage.key === "present" ? Object.freeze(["submit"]) : stage.key === "denoiseTemporal" || stage.key === "transparents" || stage.key === "composition" ? Object.freeze(["postProcess"]) : stage.key === "primaryVisibility" ? Object.freeze(["visibility"]) : stage.key === "shadowAssist" || stage.key === "opaqueFoundation" || stage.key === "rtDirectLighting" || stage.key === "rtReflections" || stage.key === "rtGlobalIllumination" ? Object.freeze(["mainEncode"]) : Object.freeze(["mainEncode"])
+      })
+    )
+  );
+}
+function buildRendererRepresentationBands(profile) {
+  return Object.freeze(
+    rendererRepresentationBands.map(
+      (band) => Object.freeze({
+        ...rendererRepresentationBandPolicies[band],
+        profile
+      })
+    )
+  );
+}
+function buildRendererAccelerationStructureUpdates(profile) {
+  return Object.freeze(
+    rendererAccelerationStructurePolicies.map(
+      (policy) => Object.freeze({
+        ...policy,
+        profile
+      })
+    )
+  );
+}
+function assertRendererIdentifier(name, value) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${name} must be a non-empty string.`);
+  }
+  return value.trim();
+}
+function buildRendererWorkerProfile(name, spec) {
+  return Object.freeze({
+    name,
+    description: spec.description,
+    jobs: Object.freeze(Object.keys(spec.jobs))
+  });
+}
+function buildRendererWorkerManifestJob(profileName, jobName, spec) {
+  const label = `renderer.${profileName}.${jobName}`;
+  return Object.freeze({
+    key: jobName,
+    label,
+    worker: Object.freeze({
+      jobType: label,
+      queueClass: rendererWorkerQueueClass,
+      priority: spec.priority,
+      dependencies: Object.freeze(
+        spec.dependencies.map((dependency) => `renderer.${profileName}.${dependency}`)
+      ),
+      schedulerMode: "dag"
+    }),
+    performance: Object.freeze({
+      id: label,
+      jobType: label,
+      queueClass: rendererWorkerQueueClass,
+      domain: spec.domain,
+      authority: "visual",
+      importance: spec.importance,
+      levels: buildRendererWorkerBudgetLevels(
+        label,
+        rendererWorkerQueueClass,
+        spec.levels
+      )
+    }),
+    debug: Object.freeze({
+      owner: rendererDebugOwner,
+      queueClass: rendererWorkerQueueClass,
+      jobType: label,
+      tags: Object.freeze(["renderer", profileName, jobName, spec.domain]),
+      suggestedAllocationIds: Object.freeze([...spec.suggestedAllocationIds])
+    })
+  });
+}
+function buildRendererWorkerManifest(name, spec) {
+  return Object.freeze({
+    schemaVersion: 1,
+    owner: rendererDebugOwner,
+    profile: name,
+    description: spec.description,
+    queueClass: rendererWorkerQueueClass,
+    schedulerMode: "dag",
+    inputBoundary: buildRendererInputBoundary(name),
+    renderStages: buildRendererRenderStages(name),
+    representationBands: buildRendererRepresentationBands(name),
+    accelerationStructureUpdates: buildRendererAccelerationStructureUpdates(name),
+    suggestedAllocationIds: Object.freeze([...spec.suggestedAllocationIds]),
+    jobs: Object.freeze(
+      Object.entries(spec.jobs).map(
+        ([jobName, jobSpec]) => buildRendererWorkerManifestJob(name, jobName, jobSpec)
+      )
+    )
+  });
+}
+var rendererWorkerProfiles = Object.freeze(
+  Object.fromEntries(
+    Object.entries(rendererWorkerProfileSpecs).map(([name, spec]) => [
+      name,
+      buildRendererWorkerProfile(name, spec)
+    ])
+  )
+);
+var rendererWorkerProfileNames = Object.freeze(
+  Object.keys(rendererWorkerProfiles)
+);
+var rendererWorkerManifests = Object.freeze(
+  Object.fromEntries(
+    Object.entries(rendererWorkerProfileSpecs).map(([name, spec]) => [
+      name,
+      buildRendererWorkerManifest(name, spec)
+    ])
+  )
+);
+function getRendererWorkerProfile(name = defaultRendererWorkerProfile) {
+  const profile = rendererWorkerProfiles[name];
+  if (!profile) {
+    const available = rendererWorkerProfileNames.join(", ");
+    throw new Error(`Unknown renderer worker profile "${name}". Available: ${available}.`);
+  }
+  return profile;
+}
+function getRendererWorkerManifest(name = defaultRendererWorkerProfile) {
+  const manifest = rendererWorkerManifests[name];
+  if (!manifest) {
+    const available = rendererWorkerProfileNames.join(", ");
+    throw new Error(`Unknown renderer worker profile "${name}". Available: ${available}.`);
+  }
+  return manifest;
+}
+function createRayTracingRenderPlan(options = {}) {
+  const profile = options.profile ?? defaultRendererWorkerProfile;
+  const snapshotId = assertRendererIdentifier(
+    "snapshotId",
+    options.snapshotId
+  );
+  const workerManifest = getRendererWorkerManifest(profile);
+  const representations = Array.isArray(options.representations) ? Object.freeze(
+    options.representations.map((representation, index) => {
+      if (!representation || typeof representation !== "object") {
+        throw new Error(`representations[${index}] must be an object.`);
+      }
+      const band = assertRendererIdentifier(
+        `representations[${index}].band`,
+        representation.band
+      );
+      if (!rendererRepresentationBands.includes(band)) {
+        throw new Error(
+          `representations[${index}].band must be one of: ${rendererRepresentationBands.join(", ")}.`
+        );
+      }
+      return Object.freeze({
+        ...representation,
+        band
+      });
+    })
+  ) : workerManifest.representationBands;
+  return Object.freeze({
+    schemaVersion: 1,
+    owner: rendererDebugOwner,
+    profile,
+    inputBoundary: Object.freeze({
+      ...workerManifest.inputBoundary,
+      snapshotId
+    }),
+    renderStages: workerManifest.renderStages,
+    representationBands: representations,
+    accelerationStructureUpdates: workerManifest.accelerationStructureUpdates,
+    workerManifest
+  });
+}
 function clamp01(value) {
   return Math.min(1, Math.max(0, value));
 }
@@ -62,12 +710,111 @@ function normalizeColor(value) {
   }
   return [...DEFAULT_CLEAR_COLOR];
 }
+function readPositiveNumber(name, value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    throw new Error(`${name} must be a finite number greater than zero.`);
+  }
+  return value;
+}
 function now() {
   if (typeof performance !== "undefined" && typeof performance.now === "function") {
     return performance.now();
   }
   return Date.now();
 }
+function normalizeFrameId(value) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error("frameIdFactory must return a non-empty string.");
+  }
+  return value.trim();
+}
+function resolveTargetFrameTimeMs(options, event) {
+  const {
+    targetFrameTimeMs: fixedTargetFrameTimeMs,
+    targetFrameRate,
+    getTargetFrameTimeMs
+  } = options;
+  if (typeof getTargetFrameTimeMs === "function") {
+    const resolved = getTargetFrameTimeMs(event);
+    return readPositiveNumber("getTargetFrameTimeMs()", resolved);
+  }
+  if (fixedTargetFrameTimeMs !== void 0) {
+    return fixedTargetFrameTimeMs;
+  }
+  if (targetFrameRate !== void 0) {
+    return 1e3 / targetFrameRate;
+  }
+  return void 0;
+}
+function createRendererDebugHooks(options = {}) {
+  const {
+    debugSession,
+    targetFrameTimeMs,
+    targetFrameRate,
+    getTargetFrameTimeMs,
+    onFrameStart,
+    onFrameComplete
+  } = options;
+  if (!debugSession || typeof debugSession.recordFrame !== "function") {
+    throw new Error(
+      "debugSession must expose recordFrame(sample). Use @plasius/gpu-debug createGpuDebugSession()."
+    );
+  }
+  const fixedTargetFrameTimeMs = readPositiveNumber(
+    "targetFrameTimeMs",
+    targetFrameTimeMs
+  );
+  const fixedTargetFrameRate = readPositiveNumber(
+    "targetFrameRate",
+    targetFrameRate
+  );
+  if (fixedTargetFrameTimeMs !== void 0 && fixedTargetFrameRate !== void 0) {
+    throw new Error(
+      "Provide either targetFrameTimeMs or targetFrameRate, not both."
+    );
+  }
+  if (getTargetFrameTimeMs !== void 0 && typeof getTargetFrameTimeMs !== "function") {
+    throw new Error("getTargetFrameTimeMs must be a function when provided.");
+  }
+  const resolvedOptions = {
+    targetFrameTimeMs: fixedTargetFrameTimeMs,
+    targetFrameRate: fixedTargetFrameRate,
+    getTargetFrameTimeMs
+  };
+  return {
+    onFrameStart(event) {
+      if (typeof onFrameStart === "function") {
+        onFrameStart({
+          ...event,
+          owner: rendererDebugOwner
+        });
+      }
+    },
+    onFrameComplete(event) {
+      const resolvedTargetFrameTimeMs = resolveTargetFrameTimeMs(
+        resolvedOptions,
+        event
+      );
+      if (typeof event.frameTimeMs === "number" && Number.isFinite(event.frameTimeMs) && event.frameTimeMs > 0) {
+        debugSession.recordFrame({
+          frameId: event.frameId,
+          frameTimeMs: event.frameTimeMs,
+          targetFrameTimeMs: resolvedTargetFrameTimeMs
+        });
+      }
+      if (typeof onFrameComplete === "function") {
+        onFrameComplete({
+          ...event,
+          owner: rendererDebugOwner,
+          targetFrameTimeMs: resolvedTargetFrameTimeMs
+        });
+      }
+    }
+  };
+}
 function readNavigator(navigatorOverride) {
   const currentNavigator = navigatorOverride ?? globalThis.navigator;
   if (!currentNavigator || typeof currentNavigator !== "object") {
@@ -148,8 +895,11 @@ async function createGpuRenderer(options = {}) {
     clearColor = DEFAULT_CLEAR_COLOR,
     requestAnimationFrame = globalThis.requestAnimationFrame?.bind(globalThis),
     cancelAnimationFrame = globalThis.cancelAnimationFrame?.bind(globalThis),
+    frameIdFactory,
+    onFrameStart,
     onBeforeEncode,
-    onAfterSubmit
+    onAfterSubmit,
+    onFrameComplete
   } = options;
   const gpu = readGpu(navigatorOverride);
   const adapter = await gpu.requestAdapter({ powerPreference });
@@ -176,6 +926,28 @@ async function createGpuRenderer(options = {}) {
     if (destroyed) {
       throw new Error("Renderer was destroyed.");
     }
+    const frameNumber = frame + 1;
+    const frameId = normalizeFrameId(
+      typeof frameIdFactory === "function" ? frameIdFactory({
+        frame: frameNumber,
+        timestamp,
+        canvas: targetCanvas,
+        xrActive
+      }) : `renderer.frame.${frameNumber}`
+    );
+    const frameTimeMs = lastTimestamp > 0 ? Math.max(0, timestamp - lastTimestamp) : void 0;
+    if (typeof onFrameStart === "function") {
+      onFrameStart({
+        frame: frameNumber,
+        frameId,
+        frameTimeMs,
+        timestamp,
+        device,
+        context,
+        canvas: targetCanvas,
+        xrActive
+      });
+    }
     const texture = context.getCurrentTexture?.();
     if (!texture || typeof texture.createView !== "function") {
       throw new Error("WebGPU context returned an invalid current texture.");
@@ -188,12 +960,16 @@ async function createGpuRenderer(options = {}) {
     if (typeof onBeforeEncode === "function") {
       onBeforeEncode({
         frame,
+        frameNumber,
+        frameId,
+        frameTimeMs,
         timestamp,
         device,
         context,
         encoder,
         pass,
-        canvas: targetCanvas
+        canvas: targetCanvas,
+        xrActive
       });
     }
     if (typeof pass.end === "function") {
@@ -201,19 +977,37 @@ async function createGpuRenderer(options = {}) {
     }
     const commandBuffer = encoder.finish();
     device.queue.submit([commandBuffer]);
-    frame += 1;
+    frame = frameNumber;
     lastTimestamp = timestamp;
     if (typeof onAfterSubmit === "function") {
       onAfterSubmit({
-        frame,
+        frame: frameNumber,
+        frameNumber,
+        frameId,
+        frameTimeMs,
+        timestamp,
+        device,
+        context,
+        canvas: targetCanvas,
+        xrActive
+      });
+    }
+    if (typeof onFrameComplete === "function") {
+      onFrameComplete({
+        frame: frameNumber,
+        frameId,
+        frameTimeMs,
         timestamp,
         device,
         context,
-        canvas: targetCanvas
+        canvas: targetCanvas,
+        xrActive
       });
     }
     return {
-      frame,
+      frame: frameNumber,
+      frameId,
+      frameTimeMs,
       timestamp
     };
   };
@@ -355,7 +1149,20 @@ var defaultRendererClearColor = DEFAULT_CLEAR_COLOR;
 0 && (module.exports = {
   bindRendererToXrManager,
   createGpuRenderer,
+  createRayTracingRenderPlan,
+  createRendererDebugHooks,
   defaultRendererClearColor,
+  defaultRendererWorkerProfile,
+  getRendererWorkerManifest,
+  getRendererWorkerProfile,
+  rendererAccelerationStructureUpdateClasses,
+  rendererDebugOwner,
+  rendererRayTracingStageOrder,
+  rendererRepresentationBands,
+  rendererWorkerManifests,
+  rendererWorkerProfileNames,
+  rendererWorkerProfiles,
+  rendererWorkerQueueClass,
   supportsWebGpu
 });
 //# sourceMappingURL=index.cjs.map