@forgeax/engine-app 0.1.4 → 0.1.7

package/src/create-app.ts

@@ -23,40 +23,31 @@
 // inherits .tagName from HTMLElement, so the property test cleanly
 // separates the canvas argument from the AppAssembleArgs plain object.
 
-import {
-  type AssetRegistry,
-  type CatalogSource,
-  createAssetRegistry,
-  createCatalogSource,
-} from '@forgeax/engine-assets-runtime';
-import { getAssetRegistryResolver } from '@forgeax/engine-assets-runtime/internal';
+import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import type { AudioBackend } from '@forgeax/engine-audio';
 import type { DebugDraw } from '@forgeax/engine-debug-draw';
 import { createWorldContext, Update, World } from '@forgeax/engine-ecs';
 import type { InputBackend } from '@forgeax/engine-input';
 import type { Context, Plugin } from '@forgeax/engine-plugin';
-import type { Renderer, RendererError } from '@forgeax/engine-render';
-import { loadRhiPack } from '@forgeax/engine-render/internal';
+import type { RenderError } from '@forgeax/engine-render';
+import { CAMERA_PROJECTION_PERSPECTIVE, Camera, type Renderer } from '@forgeax/engine-render';
+import type { RendererHostAssembly } from '@forgeax/engine-render/internal/construct-renderer';
 import { RhiError } from '@forgeax/engine-rhi';
-import type {
-  CaptureFrameOptions,
-  CreateShaderModuleFn,
-  RecorderAttachment,
+import {
+  attachRecorder,
+  type CaptureFrameOptions,
+  type RecorderAttachment,
 } from '@forgeax/engine-rhi-debug';
 import * as engineRuntimeModule from '@forgeax/engine-runtime';
-import { createRenderer, EngineEnvironmentError } from '@forgeax/engine-runtime';
-import { type AssetDecoderContributionRef, err, ok, type Result } from '@forgeax/engine-types';
+import { EngineEnvironmentError } from '@forgeax/engine-runtime';
+import {
+  constructRuntimeRendererHost,
+  loadRhiPack,
+} from '@forgeax/engine-runtime/internal/renderer-host';
+import { err, ok, type Result } from '@forgeax/engine-types';
 
 import { createAnimationPayloadLookup } from './animation-asset-lookup';
-
-export { syncCameraAspect } from './canvas-policy';
-
-import {
-  type AssetRuntimeAssembly,
-  type AssetRuntimeAssemblyError,
-  assembleAssetRuntime,
-} from './assets-runtime-assembly';
-import { syncCameraAspect } from './canvas-policy';
+import { publishBrowserFrameSubmitted, resetBrowserFrameSubmitted } from './browser-frame-signal';
 import type { AppErrorCode, AppErrorDetailFor } from './errors';
 import { APP_ERROR_HINTS, APP_EXPECTED, AppError } from './errors';
 import {
@@ -69,6 +60,7 @@ import {
   selectExecutionTier,
   unavailableExecutionCapabilities,
 } from './execution';
+import { normalizeExecutionBootstrapUrl } from './execution/bootstrap-url';
 import { createLocalExecutionControl } from './execution/control';
 import { createWorkerExecutionApp } from './execution/host-controller';
 import { assembledEngineProfile } from './internal/assembled-engine-profile';
@@ -86,6 +78,7 @@ import {
   type RhiCapture,
 } from './internal/rhi-capture';
 import { resolveRhiDebugFlag } from './internal/rhi-debug-flag';
+import { createRenderFeatureHost, type RenderFeatureHost } from './renderer-plugin';
 import type {
   App,
   AppAssembleArgs,
@@ -93,35 +86,10 @@ import type {
   AssembleAppError,
   BundlerOptions,
   CanvasAppError,
-  CanvasDrawingBufferSize,
   CreateAppOptions,
   ExecutionApp,
 } from './types';
 
-const DEFAULT_ASSET_CATALOG_PATH = 'pack-index.json';
-
-function defaultAssetCatalogUrl(): string {
-  const base =
-    typeof document !== 'undefined'
-      ? document.baseURI
-      : (globalThis as { location?: { href?: string } }).location?.href;
-  return base === undefined
-    ? DEFAULT_ASSET_CATALOG_PATH
-    : new URL(DEFAULT_ASSET_CATALOG_PATH, base).href;
-}
-
-function assembleAppAssetRuntime(
-  catalog: CatalogSource | undefined,
-  contributions: readonly AssetDecoderContributionRef[] | undefined,
-): Result<AssetRuntimeAssembly, AssetRuntimeAssemblyError> {
-  const registry = createAssetRegistry({
-    catalog: catalog ?? createCatalogSource({ url: defaultAssetCatalogUrl() }),
-  });
-  const assembled = assembleAssetRuntime(registry, contributions ?? []);
-  if (!assembled.ok) registry.dispose();
-  return assembled;
-}
-
 function makeAppError<C extends AppErrorCode>(
   code: C,
   expected: string,
@@ -131,23 +99,7 @@ function makeAppError<C extends AppErrorCode>(
   return new AppError({ code, expected, hint, detail }) as AppError;
 }
 
-function normalizeExecutionBootstrapUrl(bootstrap: string | URL): Result<string, AppError> {
-  const moduleUrl = typeof bootstrap === 'string' ? bootstrap : bootstrap.href;
-  try {
-    return ok(new URL(bootstrap, globalThis.location?.href).href);
-  } catch (cause) {
-    return err(
-      makeAppError(
-        'app-execution-bootstrap-failed',
-        APP_EXPECTED['app-execution-bootstrap-failed'],
-        APP_ERROR_HINTS['app-execution-bootstrap-failed'],
-        { phase: 'prepare', moduleUrl, cause },
-      ),
-    );
-  }
-}
-
-function canvasAspectPlugin(canvas: HTMLCanvasElement, maxCanvasPixelRatio?: number): Plugin {
+function canvasAspectPlugin(canvas: HTMLCanvasElement): Plugin {
   return {
     name: 'canvas-aspect',
     inject: ['world'],
@@ -157,7 +109,7 @@ function canvasAspectPlugin(canvas: HTMLCanvasElement, maxCanvasPixelRatio?: num
           name: 'app-sync-camera-aspect',
           queries: [],
           fn: () => {
-            syncCanvasDrawingBuffer(canvas, maxCanvasPixelRatio);
+            syncCanvasDrawingBuffer(canvas);
             syncCameraAspect(ctx.world, canvas.width, canvas.height);
           },
         };
@@ -210,7 +162,8 @@ export function createApp(
 ): Promise<Result<App, CanvasAppError>>;
 
 /**
- * createApp({ renderer, world, input?, schedule?, ... }) -- assemble-form
+ * Create the browser host for the single RenderScene -> FrameReceipt path.
+ * `createApp({ renderer, world, input?, schedule?, ... })` is the assemble form
  * SSOT (per plan-strategy D-5). Host already owns renderer / world; the
  * returned App holds them by reference equality (per AC-02).
  *
@@ -251,20 +204,6 @@ async function createAppFromCanvas(
   //   document.createElement('canvas') without appendChild. Returning
   //   Result.err here short-circuits before createRenderer fires off any
   //   async adapter / device / shader work that would only fail later.
-  const maxCanvasPixelRatio = opts?.maxCanvasPixelRatio;
-  if (
-    maxCanvasPixelRatio !== undefined &&
-    (!Number.isFinite(maxCanvasPixelRatio) || maxCanvasPixelRatio <= 0)
-  ) {
-    return err(
-      makeAppError(
-        'app-invalid-canvas-pixel-ratio',
-        APP_EXPECTED['app-invalid-canvas-pixel-ratio'],
-        APP_ERROR_HINTS['app-invalid-canvas-pixel-ratio'],
-        { value: maxCanvasPixelRatio },
-      ),
-    );
-  }
   if (!canvas.isConnected) {
     return err(
       makeAppError(
@@ -276,31 +215,23 @@ async function createAppFromCanvas(
     );
   }
 
-  const executionOptions = opts?.execution;
-  const normalizedExecutionBootstrap =
-    executionOptions === undefined
-      ? undefined
-      : normalizeExecutionBootstrapUrl(executionOptions.bootstrap);
-  if (normalizedExecutionBootstrap?.ok === false) {
-    return err(normalizedExecutionBootstrap.error);
-  }
-
   // The DOM canvas starts with a 300x150 drawing buffer even when CSS lays it
   // out at a different size. Set the physical buffer before the renderer
   // configures its swap chain; the same helper runs before each frame so a CSS
   // resize remains visible to both rendering and camera policy.
-  syncCanvasDrawingBuffer(canvas, maxCanvasPixelRatio);
+  syncCanvasDrawingBuffer(canvas);
 
-  if (opts?.execution !== undefined && normalizedExecutionBootstrap?.ok === true) {
+  let executionBootstrapUrl: string | undefined;
+  if (opts?.execution !== undefined) {
+    const normalizedBootstrap = normalizeExecutionBootstrapUrl(opts.execution.bootstrap);
+    if (!normalizedBootstrap.ok) return err(normalizedBootstrap.error);
+    executionBootstrapUrl = normalizedBootstrap.value;
     const realmBoundOption = [
       ['features', opts.features],
       ['plugins', opts.plugins],
       ['rhi', opts.rhi],
-      ['rawDeviceForContextConfigure', opts.rawDeviceForContextConfigure],
+      ['rhiInstrumentation', opts.rhiInstrumentation],
       ['drawSource', opts.drawSource],
-      ['membershipTiming', opts.membershipTiming],
-      ['assetCatalog', opts.assetCatalog],
-      ['assetDecoders', opts.assetDecoders],
       ['bundler.importTransport', bundler?.importTransport],
     ].find(([, value]) => value !== undefined)?.[0];
     if (realmBoundOption !== undefined) {
@@ -311,7 +242,7 @@ async function createAppFromCanvas(
           APP_ERROR_HINTS['app-execution-bootstrap-failed'],
           {
             phase: 'prepare',
-            moduleUrl: normalizedExecutionBootstrap.value,
+            moduleUrl: executionBootstrapUrl,
             cause: new TypeError(
               `${realmBoundOption} must be constructed by the execution bootstrap module`,
             ),
@@ -328,11 +259,10 @@ async function createAppFromCanvas(
       }
     | undefined;
   let preparedExecutionBootstrap: PreparedExecutionBootstrap | undefined;
-  if (opts?.execution !== undefined && normalizedExecutionBootstrap?.ok === true) {
-    const executionOptions = opts.execution;
+  if (opts?.execution !== undefined) {
     const capabilities = await probeExecutionCapabilities(canvas);
     const selected = selectExecutionTier({
-      requestedTier: executionOptions.tier ?? 'auto',
+      requestedTier: opts.execution.tier ?? 'auto',
       capabilities,
       sharedEvidencePassed: true,
     });
@@ -342,15 +272,18 @@ async function createAppFromCanvas(
       return createWorkerExecutionApp({
         canvas,
         appOptions: opts,
-        syncCanvas: () => measureCanvasDrawingBuffer(canvas, maxCanvasPixelRatio),
+        syncCanvas: () => measureCanvasDrawingBuffer(canvas),
         ...(bundler !== undefined ? { bundler } : {}),
         capabilities,
         selection: selected.value,
       });
     }
+    if (executionBootstrapUrl === undefined) {
+      throw new Error('execution bootstrap URL was not normalized');
+    }
     const prepared = await prepareBootstrapEntry(
-      normalizedExecutionBootstrap.value,
-      executionOptions.bootstrapData,
+      executionBootstrapUrl,
+      opts.execution.bootstrapData,
     );
     if (!prepared.ok) return err(prepared.error);
     preparedExecutionBootstrap = prepared.value;
@@ -367,40 +300,34 @@ async function createAppFromCanvas(
   //   forwarded to keep the contract honest (AI users walk the union
   //   discriminant rather than parse error.message strings).
   // feat-20260608 / M2 / D-3: CreateAppOptions stops `extends RendererOptions`,
-  // so the two RHI escape hatches (rhi / rawDeviceForContextConfigure) are
+  // so the RHI escape hatch (rhi) is
   // forwarded explicitly. Build a RendererOptions object out of just those
   // fields when present; an empty {} keeps createRenderer on its default path.
   const rendererOpts: import('@forgeax/engine-render').RendererOptions = {};
   if (opts?.rhi !== undefined) {
     Object.assign(rendererOpts, { rhi: opts.rhi });
   }
-  if (opts?.rhiInstrumentation !== undefined) {
-    Object.assign(rendererOpts, { rhiInstrumentation: opts.rhiInstrumentation });
-  }
-  if (opts?.rawDeviceForContextConfigure !== undefined) {
-    Object.assign(rendererOpts, {
-      rawDeviceForContextConfigure: opts.rawDeviceForContextConfigure,
-    });
-  }
   if (opts?.profiler !== undefined) {
     Object.assign(rendererOpts, { profiler: opts.profiler });
   }
-  if (opts?.membershipTiming !== undefined) {
-    Object.assign(rendererOpts, { membershipTiming: opts.membershipTiming });
-  }
   const rendererFeatures = preparedExecutionBootstrap?.features ?? opts?.features;
   if (rendererFeatures !== undefined) {
     Object.assign(rendererOpts, { features: rendererFeatures });
   }
+  if (opts?.standardProfile !== undefined) {
+    Object.assign(rendererOpts, { standardProfile: opts.standardProfile });
+  }
+  if (opts?.rhiInstrumentation !== undefined) {
+    Object.assign(rendererOpts, { rhiInstrumentation: opts.rhiInstrumentation });
+  }
 
-  // Optional RHI instrumentation is assembled once and forwarded through the
-  // typed Runtime -> Render seam. App keeps only the capture capability.
+  // FORGEAX_ENGINE_RHI_DEBUG=1 attaches the recorder at the Runtime backend
+  // seam. Render remains the owner of device/surface lifecycle; App only owns
+  // the optional capture capability and its frame transaction.
   let rhiAttachment: RecorderAttachment | undefined;
   let rhiCapture: RhiCapture | undefined;
   let rhiDebugGlobal:
-    | {
-        captureFrame(options?: CaptureFrameOptions): ReturnType<RhiCapture['captureFrame']>;
-      }
+    | { captureFrame(options?: CaptureFrameOptions): ReturnType<RhiCapture['captureFrame']> }
     | undefined;
   const cleanupRhiDebugHost = (): void => {
     const host = globalThis as { __forgeax?: typeof rhiDebugGlobal };
@@ -445,65 +372,55 @@ async function createAppFromCanvas(
       : undefined;
   const hasWebGPU = nav !== undefined && 'gpu' in nav && nav.gpu !== undefined;
   if (
-    opts?.rhi === undefined &&
     (browserBuildRhiDebugFlag === undefined || browserBuildRhiDebugFlag === '1') &&
     rhiDebugFlag === '1'
   ) {
-    const backend = hasWebGPU
+    const realBackend = (hasWebGPU
       ? await import('@forgeax/engine-rhi-webgpu')
-      : await import('@forgeax/engine-rhi-wgpu');
-    if (!hasWebGPU && 'ensureReady' in backend) await backend.ensureReady();
-    const pack = loadRhiPack(backend);
-    const debugModule = await import(/* @vite-ignore */ '@forgeax/engine-rhi-debug');
+      : await import('@forgeax/engine-rhi-wgpu')) as unknown as Record<string, unknown>;
+    if (!hasWebGPU && 'ensureReady' in realBackend) {
+      await (realBackend.ensureReady as () => Promise<unknown>)();
+    }
+    const pack = loadRhiPack(realBackend);
     if (pack.createShaderModule === undefined) {
-      throw new Error('RHI debug capture requires the backend shader-module entry');
+      throw new Error('RHI-debug requires a backend createShaderModule capability');
     }
-    const createShaderModule: CreateShaderModuleFn = pack.createShaderModule;
-    const attached = debugModule.attachRecorder({
+    const attached = attachRecorder({
       rhi: pack.rhi,
-      createShaderModule,
+      createShaderModule: pack.createShaderModule,
     });
     if (!attached.ok) throw new Error(attached.error.hint);
-    const attachment = attached.value;
-    rhiAttachment = attachment;
-    const capture = createRhiCapture(attachment);
-    rhiCapture = capture;
-
+    rhiAttachment = attached.value;
+    rhiCapture = createRhiCapture(attached.value);
+    const capture = rhiCapture;
+    rhiDebugGlobal = { captureFrame: (options) => capture.captureFrame(options) };
     Object.assign(rendererOpts, {
-      rhi: attachment.backend.rhi,
-      rhiInstrumentation: createRhiInstrumentation(attachment),
+      rhi: attached.value.backend.rhi,
+      rhiInstrumentation: createRhiInstrumentation(attached.value),
     });
-
-    rhiDebugGlobal = {
-      captureFrame: (options) => capture.captureFrame(options),
-    };
     (globalThis as { __forgeax?: typeof rhiDebugGlobal }).__forgeax = rhiDebugGlobal;
   }
 
-  const assetAssemblyResult = assembleAppAssetRuntime(opts?.assetCatalog, opts?.assetDecoders);
-  if (!assetAssemblyResult.ok) {
-    cleanupRhiDebugHost();
-    return err(assetAssemblyResult.error);
-  }
-  const assetAssembly = assetAssemblyResult.value;
   let renderer: Renderer;
+  let rendererDebugDrawHost: RendererHostAssembly['debugDrawHost'];
+  let rendererFeatureHost: RenderFeatureHost;
+  let assets: AssetRegistry;
   try {
-    renderer = await createRenderer(canvas, rendererOpts, {
-      ...bundler,
-      assetResolver: getAssetRegistryResolver(assetAssembly.registry),
-    });
+    const constructed = await constructRuntimeRendererHost(canvas, rendererOpts, bundler);
+    if (!constructed.ok) throw constructed.error;
+    renderer = constructed.value.renderer;
+    rendererDebugDrawHost = constructed.value.debugDrawHost;
+    rendererFeatureHost = createRenderFeatureHost(constructed.value.featureHost);
+    assets = constructed.value.assets;
   } catch (e: unknown) {
     cleanupRhiDebugHost();
-    assetAssembly.dispose();
-    assetAssembly.registry.dispose();
-    if (e instanceof EngineEnvironmentError) {
-      return err(e);
-    }
-    // Unknown throw shapes (RhiError surfaced as throw, raw Error, ...).
-    // Re-raise to preserve fail-fast: the contract pins
-    // EngineEnvironmentError as the only construction-time failure
-    // shape; anything else is an engine bug, not an app-shell concern.
-    throw e;
+    if (e instanceof EngineEnvironmentError) return err(e);
+    const detail = e instanceof Error ? e : new Error(String(e));
+    return err(
+      new EngineEnvironmentError('renderer construction failed', {
+        webgpuError: detail,
+      }),
+    );
   }
 
   // Step 2.4 decision: resolve whether the remote eval server should start
@@ -516,7 +433,6 @@ async function createAppFromCanvas(
       ? (import.meta as { env?: { DEV?: boolean } }).env?.DEV
       : undefined,
     (globalThis as { process?: { env?: { FORGEAX_ENGINE_REMOTE_SERVE?: string } } }).process?.env,
-    typeof window !== 'undefined',
   );
 
   let debugDraw: DebugDraw | undefined;
@@ -564,8 +480,10 @@ async function createAppFromCanvas(
       world,
       mainEngineProfile({
         renderer,
-        assetAssembly,
-        animationPayloads: createAnimationPayloadLookup(renderer.assets),
+        rendererDebugDrawHost,
+        rendererFeatureHost,
+        assets,
+        animationPayloads: createAnimationPayloadLookup(assets),
         ...(inputBackend === undefined ? {} : { input: inputBackend }),
         ...(inputHandle === undefined ? {} : { inputDispose: inputHandle.cleanup }),
         ...(opts?.inputMap === undefined ? {} : { inputMap: opts.inputMap }),
@@ -575,14 +493,12 @@ async function createAppFromCanvas(
         extensions: [
           rhiDebugHostPlugin(cleanupRhiDebugHost),
           ...userPlugins,
-          canvasAspectPlugin(canvas, maxCanvasPixelRatio),
+          canvasAspectPlugin(canvas),
         ],
       }),
     );
   } catch (cause) {
     cleanupRhiDebugHost();
-    assetAssembly.dispose();
-    assetAssembly.registry.dispose();
     return err(
       makeAppError(
         'app-plugin-activation-failed',
@@ -639,23 +555,17 @@ async function createAppFromCanvas(
   // of static dep on @forgeax/engine-remote. Component reflection crosses
   // this boundary as JSON-safe host data; app does not own any component.
   const remoteHandle = shouldStartRemote
-    ? await startRemoteServer(
-        world,
-        renderer,
-        assetAssembly.registry,
-        rhiCapture,
-        opts?.profiler,
-        executionControl,
-      )
+    ? await startRemoteServer(world, renderer, assets, rhiCapture, opts?.profiler, executionControl)
     : undefined;
   if (remoteHandle !== undefined) await pluginContext.plugin(remoteServerPlugin(remoteHandle));
 
   const buildArgs: BuildAppArgs = {
     renderer,
-    assets: assetAssembly.registry,
+    assets,
     world,
     pluginContext,
     executionControl,
+    onFrameSubmitted: (event) => publishBrowserFrameSubmitted(canvas, event),
     ...(inputBackend !== undefined ? { inputBackend } : {}),
     ...(inputHandle === undefined
       ? {}
@@ -681,10 +591,7 @@ async function createAppFromCanvas(
     Object.assign(buildArgs, { profiler: opts.profiler });
   }
   if (rhiCapture !== undefined) {
-    Object.assign(buildArgs, {
-      rhiCapture,
-      ...(rhiAttachment === undefined ? {} : { rhiAttachment }),
-    });
+    Object.assign(buildArgs, { rhiCapture });
   }
   if (debugDraw !== undefined) {
     Object.assign(buildArgs, { debugDraw });
@@ -695,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();
@@ -727,17 +635,17 @@ async function createAppFromCanvas(
           ?.VITE_FORGEAX_ENGINE_BRIDGE_PORT ?? '5733';
       await pluginContext.plugin({
         name: 'browser-remote-bridge',
-        inject: ['world', 'renderer', 'assetRegistry'],
+        inject: ['world', 'renderer', 'assets'],
         async apply(ctx) {
-          if (ctx.renderer === undefined || ctx.assetRegistry === undefined) {
-            throw new Error('browser remote bridge requires renderer and assetRegistry services');
+          if (ctx.renderer === undefined || ctx.assets === undefined) {
+            throw new Error('browser remote bridge requires renderer and assets services');
           }
           try {
             const bridge = await import('./internal/browser-remote-bridge');
             const teardown = await bridge.installBrowserRemoteBridge({
               world: ctx.world,
               renderer: ctx.renderer,
-              assets: ctx.assetRegistry,
+              assets: ctx.assets,
               runtimeModule: engineRuntimeModule,
               ...(rhiCapture !== undefined ? { rhiCapture } : {}),
               ...(opts?.profiler !== undefined ? { profiler: opts.profiler } : {}),
@@ -764,47 +672,14 @@ export function syncCanvasDrawingBuffer(
   canvas: Pick<HTMLCanvasElement, 'clientWidth' | 'clientHeight' | 'width' | 'height'> & {
     readonly style?: Pick<CSSStyleDeclaration, 'width' | 'height'>;
   },
-  maxCanvasPixelRatio?: number,
-): CanvasDrawingBufferSize {
-  const size = resolveCanvasDrawingBufferSize(canvas, maxCanvasPixelRatio);
-  if (size === undefined) return { width: canvas.width, height: canvas.height };
-  if (canvas.width !== size.width) canvas.width = size.width;
-  if (canvas.height !== size.height) canvas.height = size.height;
-  return size;
-}
-
-/**
- * Measure the next effective drawing buffer without writing the DOM canvas.
- * This is the Worker host path because transferControlToOffscreen makes the
- * HTML canvas dimensions immutable; the Worker owns the transferred surface.
- */
-export function measureCanvasDrawingBuffer(
-  canvas: Pick<HTMLCanvasElement, 'clientWidth' | 'clientHeight' | 'width' | 'height'> & {
-    readonly style?: Pick<CSSStyleDeclaration, 'width' | 'height'>;
-  },
-  maxCanvasPixelRatio?: number,
-): CanvasDrawingBufferSize {
-  return (
-    resolveCanvasDrawingBufferSize(canvas, maxCanvasPixelRatio) ?? {
-      width: canvas.width,
-      height: canvas.height,
-    }
-  );
-}
-
-function resolveCanvasDrawingBufferSize(
-  canvas: Pick<HTMLCanvasElement, 'clientWidth' | 'clientHeight' | 'width' | 'height'> & {
-    readonly style?: Pick<CSSStyleDeclaration, 'width' | 'height'>;
-  },
-  maxCanvasPixelRatio?: number,
-): CanvasDrawingBufferSize | undefined {
+): void {
   if (
     !Number.isFinite(canvas.clientWidth) ||
     !Number.isFinite(canvas.clientHeight) ||
     canvas.clientWidth <= 0 ||
     canvas.clientHeight <= 0
   )
-    return undefined;
+    return;
   // An intrinsic canvas with no CSS dimensions already has an explicit
   // drawing-buffer contract. `clientWidth` mirrors `width` for this shape;
   // multiplying it by DPR would change the caller's requested pixel size and
@@ -818,15 +693,9 @@ function resolveCanvasDrawingBufferSize(
     canvas.clientWidth === canvas.width &&
     canvas.clientHeight === canvas.height
   ) {
-    return { width: canvas.width, height: canvas.height };
+    return;
   }
-  const devicePixelRatio = Math.max(1, globalThis.devicePixelRatio || 1);
-  const dpr =
-    maxCanvasPixelRatio === undefined ||
-    !Number.isFinite(maxCanvasPixelRatio) ||
-    maxCanvasPixelRatio <= 0
-      ? devicePixelRatio
-      : Math.min(devicePixelRatio, maxCanvasPixelRatio);
+  const dpr = Math.max(1, globalThis.devicePixelRatio || 1);
   const previous = syncedCanvasSizes.get(canvas);
   const drawingBufferIsTheLayoutMeasurement =
     previous !== undefined &&
@@ -838,13 +707,60 @@ function resolveCanvasDrawingBufferSize(
   const cssHeight = drawingBufferIsTheLayoutMeasurement ? previous.cssHeight : canvas.clientHeight;
   const width = Math.max(1, Math.round(cssWidth * dpr));
   const height = Math.max(1, Math.round(cssHeight * dpr));
+  if (canvas.width !== width) canvas.width = width;
+  if (canvas.height !== height) canvas.height = height;
   syncedCanvasSizes.set(canvas, {
     cssWidth,
     cssHeight,
     drawingWidth: width,
     drawingHeight: height,
   });
-  return { width, height };
+}
+
+/** Measure a CSS-sized canvas without mutating its drawing buffer. */
+export function measureCanvasDrawingBuffer(
+  canvas: Pick<HTMLCanvasElement, 'clientWidth' | 'clientHeight' | 'width' | 'height'> & {
+    readonly style?: Pick<CSSStyleDeclaration, 'width' | 'height'>;
+  },
+  maxCanvasPixelRatio?: number,
+): { readonly width: number; readonly height: number } {
+  if (
+    !Number.isFinite(canvas.clientWidth) ||
+    !Number.isFinite(canvas.clientHeight) ||
+    canvas.clientWidth <= 0 ||
+    canvas.clientHeight <= 0
+  ) {
+    return { width: canvas.width, height: canvas.height };
+  }
+  const hasExplicitCssSize =
+    (canvas.style?.width ?? '') !== '' || (canvas.style?.height ?? '') !== '';
+  if (
+    !hasExplicitCssSize &&
+    canvas.clientWidth === canvas.width &&
+    canvas.clientHeight === canvas.height
+  ) {
+    return { width: canvas.width, height: canvas.height };
+  }
+  const devicePixelRatio = Math.max(1, globalThis.devicePixelRatio || 1);
+  const dpr =
+    maxCanvasPixelRatio === undefined ||
+    !Number.isFinite(maxCanvasPixelRatio) ||
+    maxCanvasPixelRatio <= 0
+      ? devicePixelRatio
+      : Math.min(devicePixelRatio, maxCanvasPixelRatio);
+  const previous = syncedCanvasSizes.get(canvas);
+  const drawingBufferIsTheLayoutMeasurement =
+    previous !== undefined &&
+    canvas.width === previous.drawingWidth &&
+    canvas.height === previous.drawingHeight &&
+    canvas.clientWidth === previous.drawingWidth &&
+    canvas.clientHeight === previous.drawingHeight;
+  const cssWidth = drawingBufferIsTheLayoutMeasurement ? previous.cssWidth : canvas.clientWidth;
+  const cssHeight = drawingBufferIsTheLayoutMeasurement ? previous.cssHeight : canvas.clientHeight;
+  return {
+    width: Math.max(1, Math.round(cssWidth * dpr)),
+    height: Math.max(1, Math.round(cssHeight * dpr)),
+  };
 }
 
 const syncedCanvasSizes = new WeakMap<
@@ -857,10 +773,49 @@ const syncedCanvasSizes = new WeakMap<
   }
 >();
 
+/**
+ * Per-frame aspect-sync body for the createApp(canvas) path (feat-20260617
+ * M3 / w13). Walks every Camera entity and, for perspective cameras with
+ * `autoAspect === true`, writes `canvasW / canvasH` into `Camera.aspect`.
+ *
+ * Read discipline (D-5 / research Finding 2): `autoAspect` is read through
+ * `world.get` (the readRow path narrows the bool column to a JS boolean).
+ * The query bundle is used only to enumerate the entity handles -- reading
+ * the bool column off the bundle would return a raw 0/1 number, so a
+ * `!== 0` test is always true (the
+ * bool-field-compared-with-not-equal-zero-always-true trap).
+ *
+ * Best-effort + side-effect-isolated:
+ *   - canvas size 0 (detached / display:none) -> skip entirely so `aspect`
+ *     never becomes NaN / 0.
+ *   - orthographic cameras and `autoAspect === false` cameras are left
+ *     untouched.
+ *
+ * @see {@link https://github.com/Ubpa/forgeax-engine/blob/main/docs/how-to/2026-06-18-host-engine-contract.md | Host-engine contract SSOT}
+ */
+export function syncCameraAspect(world: World, canvasW: number, canvasH: number): void {
+  // Guard against detached / zero-sized canvases: a 0 width or height would
+  // write NaN (0 / 0) or 0 into aspect and corrupt the projection matrix.
+  if (canvasW <= 0 || canvasH <= 0) return;
+  const aspect = canvasW / canvasH;
+
+  const query = world.query({ with: [Camera] }).unwrap();
+  for (const row of query) {
+    const entity = row.entity;
+    const r = world.get(entity, Camera);
+    if (!r.ok) continue;
+    // world.get narrows the bool column to a real boolean (D-5); the
+    // perspective discriminator is the numeric column value.
+    if (r.value.autoAspect !== true) continue;
+    if (r.value.projection !== CAMERA_PROJECTION_PERSPECTIVE) continue;
+    world.set(entity, Camera, { aspect });
+  }
+}
+
 async function startRemoteServer(
   world: World,
   renderer: Renderer,
-  assets: AssetRegistry,
+  assets: AssetRegistry | undefined,
   rhiCapture: RhiCapture | undefined,
   profiler: import('@forgeax/engine-profiler').Profiler | undefined,
   execution: ExecutionControl,
@@ -907,22 +862,17 @@ async function startRemoteServer(
 async function createAppFromAssemble(
   args: AppAssembleArgs,
 ): Promise<Result<App, AssembleAppError>> {
-  const assetAssemblyResult = assembleAppAssetRuntime(args.assetCatalog, args.assetDecoders);
-  if (!assetAssemblyResult.ok) return err(assetAssemblyResult.error);
-  const assetAssembly = assetAssemblyResult.value;
   let pluginContext: Context;
   try {
     pluginContext = await createWorldContext(
       args.world,
       assembledEngineProfile({
         renderer: args.renderer,
-        assetAssembly,
+        ...(args.assets === undefined ? {} : { assets: args.assets }),
         extensions: args.plugins ?? [],
       }),
     );
   } catch (cause) {
-    assetAssembly.dispose();
-    assetAssembly.registry.dispose();
     return err(
       makeAppError(
         'app-plugin-activation-failed',
@@ -968,7 +918,7 @@ async function createAppFromAssemble(
     ? await startRemoteServer(
         args.world,
         args.renderer,
-        assetAssembly.registry,
+        args.assets,
         undefined,
         args.profiler,
         executionControl,
@@ -978,7 +928,6 @@ async function createAppFromAssemble(
 
   const buildArgs: BuildAppArgs = {
     renderer: args.renderer,
-    assets: assetAssembly.registry,
     world: args.world,
     pluginContext,
     executionControl,
@@ -1013,7 +962,7 @@ async function createAppFromAssemble(
 
 interface BuildAppArgs {
   readonly renderer: Renderer;
-  readonly assets: AssetRegistry;
+  readonly assets?: AssetRegistry;
   readonly world: World;
   readonly pluginContext: Context;
   readonly inputBackend?: InputBackend;
@@ -1027,10 +976,8 @@ interface BuildAppArgs {
   readonly wireOnLockErrorDispatch?: (dispatch: (err: AppError) => void) => void;
   readonly audioBackend?: AudioBackend;
   readonly silenceUnhandledErrors?: boolean;
-  /** M4: host-owned RHI capture capability attached to the app surface. */
+  /** Optional App-owned RHI capture capability. */
   readonly rhiCapture?: RhiCapture;
-  /** Internal attachment used to bind capture to this App's frame authority. */
-  readonly rhiAttachment?: RecorderAttachment;
   /** feat-20260615 debug-draw M5: DebugDraw instance created by createDebugDrawOnReady. */
   readonly debugDraw?: DebugDraw;
   /** feat-20260629 M4 / w20: remote eval server handle from createAppFromCanvas. */
@@ -1050,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;
 }
 
 /**
@@ -1060,14 +1012,12 @@ interface BuildAppArgs {
 async function buildApp(args: BuildAppArgs): Promise<Result<App, AppError | RhiError>> {
   const {
     renderer,
-    assets,
     world,
     pluginContext,
     inputBackend,
     audioBackend,
     silenceUnhandledErrors,
     rhiCapture,
-    rhiAttachment,
     debugDraw,
     remoteHandle,
     profiler,
@@ -1088,6 +1038,7 @@ async function buildApp(args: BuildAppArgs): Promise<Result<App, AppError | RhiE
   const fanout = new ErrorFanoutRegistry(
     silenceUnhandledErrors !== undefined ? { silenceUnhandledErrors } : {},
   );
+  let lastError: AppDispatchError | undefined;
   const execution =
     args.executionControl ??
     createLocalExecutionControl(
@@ -1116,6 +1067,7 @@ async function buildApp(args: BuildAppArgs): Promise<Result<App, AppError | RhiE
     );
 
   function dispatch(e: AppDispatchError): void {
+    lastError = e;
     fanout.fire(e);
   }
 
@@ -1141,8 +1093,7 @@ async function buildApp(args: BuildAppArgs): Promise<Result<App, AppError | RhiE
     Object.assign(loopOpts, { profiler });
   }
   const loop = createFrameLoop(loopOpts);
-
-  if (rhiCapture !== undefined && rhiAttachment !== undefined) {
+  if (rhiCapture !== undefined) {
     bindRhiCaptureFrameDriver(rhiCapture, {
       getState: () => loop.getState(),
       pause: () => {
@@ -1158,9 +1109,6 @@ async function buildApp(args: BuildAppArgs): Promise<Result<App, AppError | RhiE
       stepFrame: (deltaSeconds) => loop.stepFrame(deltaSeconds),
     });
   }
-
-  let lastError: AppDispatchError | undefined;
-
   // M4 (w13) device-lost internal subscription. R-1 timing contract:
   // app.start() arms the rAF handle BEFORE this listener subscribes, so
   // a synchronous late-attach replay of a persisted device-lost event
@@ -1177,32 +1125,13 @@ async function buildApp(args: BuildAppArgs): Promise<Result<App, AppError | RhiE
     if (rendererUnsubscribe !== undefined) {
       return;
     }
-    rendererUnsubscribe = renderer.onError((e: RendererError) => {
-      // D-3: device-lost stays in RhiError 18-member union; AppError does
-      // NOT add 'app-device-lost'. The host onError listener receives the
-      // error verbatim through the fanout dispatch below.
-      //
-      // feat-20260531-skybox-env-background F-1: the renderer onError channel
-      // now fans out RhiError | RuntimeError (e.g. 'equirect-projection-failed').
-      // Device loss is recoverable at the Renderer boundary: the frame-loop
-      // heartbeat remains armed and freezes World/update work until the host
-      // explicitly calls `renderer.recover()`. Stopping the loop here would
-      // leave a successful recovery
-      // with no frame submitter.
-      //
-      // Note: we discriminate by .code rather than instanceof RhiError
-      // because the listener may be invoked across module boundaries
-      // (re-export from @forgeax/engine-runtime vs direct
-      // @forgeax/engine-rhi/errors import). Bundler dedup is not
-      // guaranteed on subpath exports, so an instanceof check is a
-      // false-negative trap. The union .code type still provides static
-      // safety on .code access.
-      if (e?.code === 'device-lost') {
-        lastError = e;
+    rendererUnsubscribe = renderer.subscribe((event) => {
+      if (event.kind === 'frame-submitted') {
+        args.onFrameSubmitted?.(event);
+        return;
       }
-      // Always fan out to host listeners (D-2 last bullet: device-lost
-      // error is forwarded as-is to host onError listener so the host
-      // can decide whether to rebuild the renderer).
+      if (event.kind !== 'error') return;
+      const e: RenderError = event.error;
       dispatch(e);
     });
   }
@@ -1216,10 +1145,10 @@ async function buildApp(args: BuildAppArgs): Promise<Result<App, AppError | RhiE
 
   const stub: App = {
     renderer,
-    assets,
+    ...(args.assets === undefined ? {} : { assets: args.assets }),
     world,
     execution,
-    async releaseSurfacePreserveWorld(): Promise<Result<void, RhiError>> {
+    async releaseSurfacePreserveWorld(): Promise<Result<void, RhiError | RenderError>> {
       if (loop.getState() === 'running') {
         const paused = loop.pause();
         if (!paused.ok) {
@@ -1246,7 +1175,7 @@ async function buildApp(args: BuildAppArgs): Promise<Result<App, AppError | RhiE
       }
       return released.ok ? ok(undefined) : err(released.error);
     },
-    async restoreSurface(): Promise<Result<void, RhiError>> {
+    async restoreSurface(): Promise<Result<void, RhiError | RenderError>> {
       const restored = renderer.restoreSurface();
       if (!restored.ok) return err(restored.error);
       if (resumeAfterSurfaceRestore) {
@@ -1276,7 +1205,7 @@ async function buildApp(args: BuildAppArgs): Promise<Result<App, AppError | RhiE
     },
     start(): Result<void, AppError> {
       // R-1: arm the rAF handle FIRST (loop.start schedules raf(tick))
-      // and only THEN subscribe to renderer.onError. If the renderer
+      // and only THEN subscribe to renderer events. If the renderer
       // late-attach replays a persisted device-lost event during the
       // subscribe call, the loop is already armed and can retain the error.
       const r = loop.start();
@@ -1321,7 +1250,7 @@ async function buildApp(args: BuildAppArgs): Promise<Result<App, AppError | RhiE
       loop.setDrawSource(drawSource);
     },
     /**
-     * Most recent device-loss error retained for host self-inspection.
+     * Most recent dispatched error retained for host self-inspection.
      */
     get lastError(): AppDispatchError | undefined {
       return lastError;
@@ -1331,21 +1260,5 @@ async function buildApp(args: BuildAppArgs): Promise<Result<App, AppError | RhiE
     ...(remoteHandle !== undefined ? { remote: remoteHandle } : {}),
   };
 
-  // Readiness barrier (charter Fail Fast). createRenderer resolves before
-  // its `ready` Promise (manifest -> pipeline -> asset upload three-step
-  // chain) settles, so a host that calls app.start() immediately would arm
-  // the rAF loop while renderer.draw(world) still returns 'rhi-not-available'
-  // every frame -- a startup race that surfaces as intermittent console.error
-  // spam on cold loads. Awaiting ready here makes "App ready" mean "renderer
-  // ready": start() never observes a pre-ready frame, and a genuine pipeline
-  // build failure fail-fasts as Result.err(rhiError) (caught by the canonical
-  // `if (!app.ok) reportError(app.error)` takeoff) instead of per-frame noise.
-  // The audio tick system is registered by audioPlugin before buildApp as the 'audio-tick'
-  // world system, so there is no buildApp-side Update system anymore.
-  const readyResult = await renderer.ready;
-  if (!readyResult.ok) {
-    return err(readyResult.error);
-  }
-
   return ok(stub);
 }