@forgeax/engine-app 0.1.6 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-app",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -23,32 +23,32 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-animation": "0.1.6",
-    "@forgeax/engine-assets-runtime": "0.1.6",
-    "@forgeax/engine-audio": "0.1.6",
-    "@forgeax/engine-audio-webaudio": "0.1.6",
-    "@forgeax/engine-debug-draw": "0.1.6",
-    "@forgeax/engine-ecs": "0.1.6",
-    "@forgeax/engine-input": "0.1.6",
-    "@forgeax/engine-physics": "0.1.6",
-    "@forgeax/engine-physics-rapier2d": "0.1.6",
-    "@forgeax/engine-physics-rapier3d": "0.1.6",
-    "@forgeax/engine-plugin": "0.1.6",
-    "@forgeax/engine-profiler": "0.1.6",
-    "@forgeax/engine-render": "0.1.6",
-    "@forgeax/engine-rhi": "0.1.6",
-    "@forgeax/engine-runtime": "0.1.6",
-    "@forgeax/engine-scene": "0.1.6",
-    "@forgeax/engine-state": "0.1.6",
-    "@forgeax/engine-tool-runtime": "0.1.6",
-    "@forgeax/engine-types": "0.1.6"
+    "@forgeax/engine-animation": "0.1.7",
+    "@forgeax/engine-assets-runtime": "0.1.7",
+    "@forgeax/engine-audio": "0.1.7",
+    "@forgeax/engine-audio-webaudio": "0.1.7",
+    "@forgeax/engine-debug-draw": "0.1.7",
+    "@forgeax/engine-ecs": "0.1.7",
+    "@forgeax/engine-input": "0.1.7",
+    "@forgeax/engine-physics": "0.1.7",
+    "@forgeax/engine-physics-rapier2d": "0.1.7",
+    "@forgeax/engine-physics-rapier3d": "0.1.7",
+    "@forgeax/engine-plugin": "0.1.7",
+    "@forgeax/engine-profiler": "0.1.7",
+    "@forgeax/engine-render": "0.1.7",
+    "@forgeax/engine-rhi": "0.1.7",
+    "@forgeax/engine-runtime": "0.1.7",
+    "@forgeax/engine-scene": "0.1.7",
+    "@forgeax/engine-state": "0.1.7",
+    "@forgeax/engine-tool-runtime": "0.1.7",
+    "@forgeax/engine-types": "0.1.7"
   },
   "devDependencies": {
-    "@forgeax/engine-remote": "0.1.6",
-    "@forgeax/engine-rhi-debug": "0.1.6",
-    "@forgeax/engine-rhi-null": "0.1.6",
-    "@forgeax/engine-rhi-webgpu": "0.1.6",
-    "@forgeax/engine-rhi-wgpu": "0.1.6",
+    "@forgeax/engine-remote": "0.1.7",
+    "@forgeax/engine-rhi-debug": "0.1.7",
+    "@forgeax/engine-rhi-null": "0.1.7",
+    "@forgeax/engine-rhi-webgpu": "0.1.7",
+    "@forgeax/engine-rhi-wgpu": "0.1.7",
     "@types/ws": "^8.5.10",
     "@webgpu/types": "^0.1.71",
     "ws": "^8.20.0"

package/src/browser-frame-signal.ts

@@ -0,0 +1,44 @@
+/**
+ * Browser-visible render progress owned by the App frame loop.
+ *
+ * The Renderer already emits `frame-submitted` after its sole queue-submit
+ * boundary. This adapter projects that event onto the document without
+ * exposing a renderer handle or creating a second readiness registry. DevKit
+ * capture waits on the same projection, then verifies compositor pixels.
+ */
+
+export const FORGEAX_FRAME_SUBMITTED_DATASET = 'forgeaxFrameSubmitted';
+export const FORGEAX_FRAME_SUBMITTED_EVENT = 'forgeax:frame-submitted';
+
+export interface BrowserFrameSubmitted {
+  readonly frameId: number;
+  readonly deviceGeneration: number;
+}
+
+export function resetBrowserFrameSubmitted(canvas: HTMLCanvasElement): void {
+  const documentElement = canvas.ownerDocument?.documentElement;
+  if (documentElement !== undefined) {
+    delete documentElement.dataset[FORGEAX_FRAME_SUBMITTED_DATASET];
+  }
+}
+
+export function publishBrowserFrameSubmitted(
+  canvas: HTMLCanvasElement,
+  event: BrowserFrameSubmitted,
+): void {
+  const documentElement = canvas.ownerDocument?.documentElement;
+  if (documentElement !== undefined) {
+    documentElement.dataset[FORGEAX_FRAME_SUBMITTED_DATASET] = String(event.frameId);
+  }
+  // Native/Web test canvases may be structural objects without DOM event
+  // methods. The dataset projection above remains optional as well, so the
+  // signal must stay a no-op outside a browser host instead of poisoning the
+  // frame loop with a listener exception.
+  if (typeof CustomEvent === 'function' && typeof canvas.dispatchEvent === 'function') {
+    canvas.dispatchEvent(
+      new CustomEvent(FORGEAX_FRAME_SUBMITTED_EVENT, {
+        detail: Object.freeze({ ...event }),
+      }),
+    );
+  }
+}

package/src/create-app.ts

@@ -47,6 +47,7 @@ import {
 import { err, ok, type Result } from '@forgeax/engine-types';
 
 import { createAnimationPayloadLookup } from './animation-asset-lookup';
+import { publishBrowserFrameSubmitted, resetBrowserFrameSubmitted } from './browser-frame-signal';
 import type { AppErrorCode, AppErrorDetailFor } from './errors';
 import { APP_ERROR_HINTS, APP_EXPECTED, AppError } from './errors';
 import {
@@ -564,6 +565,7 @@ async function createAppFromCanvas(
     world,
     pluginContext,
     executionControl,
+    onFrameSubmitted: (event) => publishBrowserFrameSubmitted(canvas, event),
     ...(inputBackend !== undefined ? { inputBackend } : {}),
     ...(inputHandle === undefined
       ? {}
@@ -600,6 +602,7 @@ async function createAppFromCanvas(
 
   // The aspect-sync sidecar belongs to the canvas path because it owns the DOM
   // canvas. It runs as an Update system so it shares World scheduling semantics.
+  resetBrowserFrameSubmitted(canvas);
   const built = await buildApp(buildArgs);
   if (!built.ok) {
     await pluginContext.fiber.dispose();
@@ -994,6 +997,11 @@ interface BuildAppArgs {
     | undefined;
   readonly profiler?: import('@forgeax/engine-profiler').Profiler;
   readonly executionControl?: import('./execution/control').LocalExecutionControl;
+  /** Canvas-form projection of the Renderer frame-submitted event. */
+  readonly onFrameSubmitted?: (event: {
+    readonly frameId: number;
+    readonly deviceGeneration: number;
+  }) => void;
 }
 
 /**
@@ -1118,6 +1126,10 @@ async function buildApp(args: BuildAppArgs): Promise<Result<App, AppError | RhiE
       return;
     }
     rendererUnsubscribe = renderer.subscribe((event) => {
+      if (event.kind === 'frame-submitted') {
+        args.onFrameSubmitted?.(event);
+        return;
+      }
       if (event.kind !== 'error') return;
       const e: RenderError = event.error;
       dispatch(e);

package/src/index.ts

@@ -39,6 +39,13 @@ export {
   createFullscreenRenderFeature,
   type FullscreenRenderFeatureOptions,
 } from '@forgeax/engine-render/authoring';
+export {
+  type BrowserFrameSubmitted,
+  FORGEAX_FRAME_SUBMITTED_DATASET,
+  FORGEAX_FRAME_SUBMITTED_EVENT,
+  publishBrowserFrameSubmitted,
+  resetBrowserFrameSubmitted,
+} from './browser-frame-signal';
 export { createApp, measureCanvasDrawingBuffer, syncCanvasDrawingBuffer } from './create-app';
 export type {
   AppDetailCanvasDetached,