@forgeax/engine-app 0.1.6 → 0.1.19

package/dist/index.mjs

@@ -3,7 +3,7 @@ export { Context } from '@forgeax/engine-plugin';
 export { createFullscreenRenderFeature } from '@forgeax/engine-render/authoring';
 import { Camera, perspective, renderComponentsPlugin, CAMERA_PROJECTION_PERSPECTIVE } from '@forgeax/engine-render';
 import { RhiError } from '@forgeax/engine-rhi';
-import { attachRecorder, decodeTape, openReplay, decodeToRgba8, buildTapeIndex, createRhiDebugError } from '@forgeax/engine-rhi-debug';
+import { attachRecorder, decodeTape, openReplay, decodeToRgba8, buildTapeIndex, replayDeviceRequest, createRhiDebugError } from '@forgeax/engine-rhi-debug';
 import * as engineRuntimeModule from '@forgeax/engine-runtime';
 import { EngineEnvironmentError } from '@forgeax/engine-runtime';
 import { loadRhiPack, constructRuntimeRendererHost } from '@forgeax/engine-runtime/internal/renderer-host';
@@ -217,6 +217,29 @@ var init_browser_remote_bridge = __esm({
   }
 });
 
+// src/browser-frame-signal.ts
+var FORGEAX_FRAME_SUBMITTED_DATASET = "forgeaxFrameSubmitted";
+var FORGEAX_FRAME_SUBMITTED_EVENT = "forgeax:frame-submitted";
+function resetBrowserFrameSubmitted(canvas) {
+  const documentElement = canvas.ownerDocument?.documentElement;
+  if (documentElement !== void 0) {
+    delete documentElement.dataset[FORGEAX_FRAME_SUBMITTED_DATASET];
+  }
+}
+function publishBrowserFrameSubmitted(canvas, event) {
+  const documentElement = canvas.ownerDocument?.documentElement;
+  if (documentElement !== void 0) {
+    documentElement.dataset[FORGEAX_FRAME_SUBMITTED_DATASET] = String(event.frameId);
+  }
+  if (typeof CustomEvent === "function" && typeof canvas.dispatchEvent === "function") {
+    canvas.dispatchEvent(
+      new CustomEvent(FORGEAX_FRAME_SUBMITTED_EVENT, {
+        detail: Object.freeze({ ...event })
+      })
+    );
+  }
+}
+
 // src/animation-asset-lookup.ts
 function createAnimationPayloadLookup(source) {
   return (guid) => source?.lookup(guid);
@@ -330,8 +353,8 @@ var APP_EXPECTED = Object.fromEntries(
 var APP_ERROR_HINTS = Object.fromEntries(
   Object.entries(appErrorPolicy).map(([code, policy]) => [code, policy.hint])
 );
-function isAppError(err13) {
-  return err13 instanceof AppErrorClass;
+function isAppError(err14) {
+  return err14 instanceof AppErrorClass;
 }
 function executionBootstrapHostPlugin(host) {
   return {
@@ -809,16 +832,16 @@ var ErrorFanoutRegistry = class {
    * console.error(err) so the unhandled error is visible in devtools
    * (charter P3 explicit failure: silent drop is a footgun).
    */
-  fire(err13) {
+  fire(err14) {
     if (this.listeners.size === 0) {
       if (!this.silenceUnhandledErrors) {
-        console.error(err13);
+        console.error(err14);
       }
       return;
     }
     const snapshot = Array.from(this.listeners);
     for (const cb of snapshot) {
-      cb(err13);
+      cb(err14);
     }
   }
   /**
@@ -2000,13 +2023,13 @@ function attachInputAuto(canvas, options = {}) {
     ...options.lockProvider ? { lockProvider: options.lockProvider } : {},
     onLockError: (detail) => {
       if (onLockErrorDispatch) {
-        const err13 = new AppError({
+        const err14 = new AppError({
           code: "app-pointer-lock-failed",
           expected: APP_EXPECTED["app-pointer-lock-failed"],
           hint: APP_ERROR_HINTS["app-pointer-lock-failed"],
           detail
         });
-        onLockErrorDispatch(err13);
+        onLockErrorDispatch(err14);
       }
     }
   };
@@ -2065,21 +2088,27 @@ function inputPlugin() {
     }
   };
 }
-
-// ../render/src/record/render-context.ts
-function selectSwapChainFormat(storageBufferCapable) {
-  if (!storageBufferCapable) return { storage: "rgba8unorm", view: "rgba8unorm-srgb" };
+function selectSwapChainFormat(storageBufferCapable, surfaceViewFormats = true) {
+  if (!storageBufferCapable) {
+    return {
+      storage: "rgba8unorm",
+      view: surfaceViewFormats ? "rgba8unorm-srgb" : "rgba8unorm"
+    };
+  }
   const nav = globalThis.navigator;
   const gpu = nav?.gpu;
   const getPreferred = gpu?.getPreferredCanvasFormat;
   if (gpu !== void 0 && typeof getPreferred === "function") {
     const storage = getPreferred.call(gpu);
     const view = storage === "rgba8unorm" ? "rgba8unorm-srgb" : storage === "bgra8unorm" ? "bgra8unorm-srgb" : storage;
-    return { storage, view };
+    return {
+      storage,
+      view: surfaceViewFormats ? view : storage
+    };
   }
   return {
     storage: "rgba8unorm",
-    view: "rgba8unorm-srgb",
+    view: surfaceViewFormats ? "rgba8unorm-srgb" : "rgba8unorm",
     fallbackReason: "preferred-canvas-format-missing"
   };
 }
@@ -2616,6 +2645,7 @@ async function createAppFromCanvas(canvas, opts, bundler) {
     world,
     pluginContext,
     executionControl,
+    onFrameSubmitted: (event) => publishBrowserFrameSubmitted(canvas, event),
     ...inputBackend !== void 0 ? { inputBackend } : {},
     ...inputHandle === void 0 ? {} : {
       wireOnLockErrorDispatch: (dispatch) => {
@@ -2646,6 +2676,7 @@ async function createAppFromCanvas(canvas, opts, bundler) {
   if (remoteHandle !== void 0) {
     Object.assign(buildArgs, { remoteHandle });
   }
+  resetBrowserFrameSubmitted(canvas);
   const built = await buildApp(buildArgs);
   if (!built.ok) {
     await pluginContext.fiber.dispose();
@@ -2735,6 +2766,7 @@ function syncCameraAspect(world, canvasW, canvasH) {
     if (!r.ok) continue;
     if (r.value.autoAspect !== true) continue;
     if (r.value.projection !== CAMERA_PROJECTION_PERSPECTIVE) continue;
+    if (r.value.aspect === Math.fround(aspect)) continue;
     world.set(entity, Camera, { aspect });
   }
 }
@@ -2938,6 +2970,10 @@ async function buildApp(args) {
       return;
     }
     rendererUnsubscribe = renderer.subscribe((event) => {
+      if (event.kind === "frame-submitted") {
+        args.onFrameSubmitted?.(event);
+        return;
+      }
       if (event.kind !== "error") return;
       const e = event.error;
       dispatch(e);
@@ -3113,8 +3149,8 @@ var LOAD_GAME_EXPECTED = Object.fromEntries(
 var LOAD_GAME_ERROR_HINTS = Object.fromEntries(
   Object.entries(loadGameErrorPolicy).map(([code, policy]) => [code, policy.hint])
 );
-function isLoadGameError(err13) {
-  return err13 instanceof LoadGameErrorClass;
+function isLoadGameError(err14) {
+  return err14 instanceof LoadGameErrorClass;
 }
 function isPlugin(value) {
   return typeof value === "function" || typeof value === "object" && value !== null && "apply" in value && typeof value.apply === "function";
@@ -3175,10 +3211,12 @@ async function createBrowserRhiDebugRuntime() {
     attachment,
     createShaderModule: backend.createShaderModule,
     rhiInstrumentation: createRhiInstrumentation(attachment),
-    createReplayDevice: async () => {
+    createReplayDevice: async (tape) => {
       const adapter = await backend.rhi.requestAdapter();
       if (!adapter.ok) return adapter;
-      return adapter.value.requestDevice();
+      return adapter.value.requestDevice(
+        replayDeviceRequest(tape, adapter.value.features, adapter.value.limits)
+      );
     },
     attachRenderer(_renderer) {
       return () => {
@@ -3316,6 +3354,11 @@ function resourceSubjectDigest(resource) {
   ];
   return candidates.find((value) => typeof value === "string" && value.length > 0);
 }
+function resourceSubjectDrawn(resource, drawCalls) {
+  if (resource.kind === "texture") return drawCalls > 0;
+  if (resource.kind === "material" || resource.kind === "mesh") return drawCalls > 2;
+  return resource.observation !== void 0;
+}
 async function replayToolPreviewCapture(capture) {
   const analyzeStartedAtMs = performance.now();
   const tapeBytes = dataUriBytes(capture.tape.jsonUri);
@@ -3328,13 +3371,23 @@ async function replayToolPreviewCapture(capture) {
       detail: { phase: "tape-parse", cause: parsed.error }
     });
   }
-  const subjectDigest = resourceSubjectDigest(capture.resource);
-  if (capture.resource !== void 0 && subjectDigest === void 0) {
+  const drawCalls = countDrawCalls(parsed.value);
+  const resource = capture.resource !== void 0 && capture.resource.observation === void 0 && capture.resource.ownerFacts !== void 0 && resourceSubjectDrawn(capture.resource, drawCalls) ? { ...capture.resource, observation: capture.resource.ownerFacts } : capture.resource;
+  const subjectDigest = resourceSubjectDigest(resource);
+  if (resource !== void 0 && subjectDigest === void 0) {
     return err({
       code: "tool-preview-bootstrap-failed",
       expected: "the resource owner to publish a subject identity before evidence publication",
       hint: "repair AssetRegistry owner facts or post-frame observation; recipe and trace are not subject identity",
-      detail: { phase: "resource-identity" }
+      detail: {
+        phase: "resource-identity",
+        cause: {
+          kind: resource.kind,
+          drawCalls,
+          ownerFactsPublished: resource.ownerFacts !== void 0,
+          observationPublished: resource.observation !== void 0
+        }
+      }
     });
   }
   let runtime;
@@ -3348,7 +3401,7 @@ async function replayToolPreviewCapture(capture) {
       detail: { phase: "replay-runtime", cause }
     });
   }
-  const replayDevice = await runtime.createReplayDevice();
+  const replayDevice = await runtime.createReplayDevice(parsed.value);
   if (!replayDevice.ok) {
     return err({
       code: "tool-preview-capability-unavailable",
@@ -3370,7 +3423,6 @@ async function replayToolPreviewCapture(capture) {
     });
   }
   const replay = replayResult.value;
-  const drawCalls = countDrawCalls(parsed.value);
   if (drawCalls === 0) {
     await replay.dispose();
     return err({
@@ -3590,7 +3642,7 @@ async function replayToolPreviewCapture(capture) {
         }
       }
     },
-    ...capture.resource === void 0 ? {} : { resource: capture.resource }
+    ...resource === void 0 ? {} : { resource }
   });
 }
 async function createToolPreviewHost(options) {
@@ -3743,7 +3795,7 @@ async function createToolPreviewHost(options) {
       });
     const executeStartedAtMs = performance.now();
     const actionTrace = [];
-    const encodedCapture = runtime.attachment.captureFrame();
+    let encodedCapture;
     for (let frame = 0; frame < recipe.frames; frame += 1) {
       for (const action of recipe.actions.filter((candidate) => candidate.frame === frame)) {
         let accepted = false;
@@ -3767,6 +3819,17 @@ async function createToolPreviewHost(options) {
         }
         actionTrace.push(action);
       }
+      if (frame === recipe.frames - 1) {
+        encodedCapture = runtime.attachment.captureFrame();
+        const snapshot = await runtime.attachment.frameBoundary();
+        if (!snapshot.ok)
+          return err({
+            code: "tool-preview-bootstrap-failed",
+            expected: "RHI-debug snapshots live resources before the captured frame",
+            hint: snapshot.error.hint,
+            detail: { phase: "rhi-snapshot", cause: snapshot.error }
+          });
+      }
       const stepped = app.stepFrame(recipe.deltaSeconds);
       if (!stepped.ok)
         return err({
@@ -3776,9 +3839,14 @@ async function createToolPreviewHost(options) {
         });
       await new Promise((resolve) => setTimeout(resolve, 0));
     }
-    await runtime.attachment.frameBoundary();
-    await new Promise((resolve) => setTimeout(resolve, 0));
-    await runtime.attachment.frameBoundary();
+    const finalized = await runtime.attachment.frameBoundary();
+    if (!finalized.ok)
+      return err({
+        code: "tool-preview-bootstrap-failed",
+        expected: "RHI-debug finalizes the captured frame",
+        hint: finalized.error.hint,
+        detail: { phase: "rhi-finalize", cause: finalized.error }
+      });
     if (options.collectResourceFacts !== void 0) {
       try {
         const collected = await options.collectResourceFacts(app, resourceFacts);
@@ -3807,6 +3875,14 @@ async function createToolPreviewHost(options) {
         detail: { phase: "profiler-finish", cause: profile.error }
       });
     }
+    if (encodedCapture === void 0) {
+      return err({
+        code: "tool-preview-bootstrap-failed",
+        expected: "a positive-frame recipe to arm one captured frame",
+        hint: "validate the recipe before running the preview host",
+        detail: { phase: "rhi-capture" }
+      });
+    }
     const tape = await encodedCapture;
     if (!tape.ok)
       return err({
@@ -3946,6 +4022,6 @@ function fitToolPreviewCameraToAabb(aabb, options) {
   };
 }
 
-export { APP_ERROR_HINTS, APP_EXPECTED, APP_PHASE_CATALOG, AppError, EXECUTION_CAPABILITY_NAMES, EXECUTION_REPORT_SCHEMA_VERSION, EXECUTION_REQUESTED_TIERS, EXECUTION_TIERS, LOAD_GAME_ERROR_HINTS, LOAD_GAME_EXPECTED, LoadGameError, createApp, createExecutionReport, createToolPreviewEvidence, createToolPreviewHost, createToolPreviewRecipe, ensureFallbackCamera, executionBootstrapHostPlugin, fitToolPreviewCameraToAabb, gameHostPlugin, inputPlugin, isAppError, isExecutionReport, isLoadGameError, joinResourcePreviewEvidence, joinToolPreviewEvidence, loadBootstrapEntry, loadGame, measureCanvasDrawingBuffer, missingExecutionCapabilities, ownedRendererPlugin, prepareBootstrapEntry, probeExecutionCapabilities, renderFeatureHostPlugin, renderFeaturePlugin, rendererPlugin, replayToolPreviewCapture, selectExecutionTier, syncCanvasDrawingBuffer, unavailableExecutionCapabilities, validateExecutionBootstrapData, validateToolPreviewTrace };
+export { APP_ERROR_HINTS, APP_EXPECTED, APP_PHASE_CATALOG, AppError, EXECUTION_CAPABILITY_NAMES, EXECUTION_REPORT_SCHEMA_VERSION, EXECUTION_REQUESTED_TIERS, EXECUTION_TIERS, FORGEAX_FRAME_SUBMITTED_DATASET, FORGEAX_FRAME_SUBMITTED_EVENT, LOAD_GAME_ERROR_HINTS, LOAD_GAME_EXPECTED, LoadGameError, createApp, createExecutionReport, createToolPreviewEvidence, createToolPreviewHost, createToolPreviewRecipe, ensureFallbackCamera, executionBootstrapHostPlugin, fitToolPreviewCameraToAabb, gameHostPlugin, inputPlugin, isAppError, isExecutionReport, isLoadGameError, joinResourcePreviewEvidence, joinToolPreviewEvidence, loadBootstrapEntry, loadGame, measureCanvasDrawingBuffer, missingExecutionCapabilities, ownedRendererPlugin, prepareBootstrapEntry, probeExecutionCapabilities, publishBrowserFrameSubmitted, renderFeatureHostPlugin, renderFeaturePlugin, rendererPlugin, replayToolPreviewCapture, resetBrowserFrameSubmitted, selectExecutionTier, syncCanvasDrawingBuffer, unavailableExecutionCapabilities, validateExecutionBootstrapData, validateToolPreviewTrace };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map