@forgeax/engine-render 0.1.28 → 0.1.30

package/src/assembly/dynamic-geometry-host.ts

@@ -2,12 +2,13 @@ import type { EntityHandle, World } from '@forgeax/engine-ecs';
 import { FixedTime } from '@forgeax/engine-ecs';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
 import { Transform } from '@forgeax/engine-scene';
-import { err, type Handle, type Result } from '@forgeax/engine-types';
+import { err, type Handle, ok, type Result } from '@forgeax/engine-types';
 import { MeshFilter } from '../components/mesh-filter';
 import { MeshRenderer } from '../components/mesh-renderer';
 import type { GpuResidencyCache } from '../device/gpu-residency';
 import type { MeshResidencyLease } from '../device/mesh-residency-lifetime';
 import {
+  createDynamicGeometryLifecycle,
   type DynamicGeometryCandidate,
   DynamicGeometryError,
   type DynamicGeometryLifecycle,
@@ -25,6 +26,15 @@ export interface DynamicGeometryHostImplementation {
     candidate: DynamicGeometryCandidate,
     ordering: DynamicGeometryOrdering,
   ): Result<DynamicGeometryCandidate, DynamicGeometryError>;
+  /**
+   * Atomically swap distinct entities in one attached World. Returned failures
+   * retain old bindings; an uncertain rollback throws to require paired rebuild.
+   * Invoke inside PhysicsWorld.admitDerivedShapeCandidates commitGeometry.
+   */
+  acceptDynamicGeometryCandidates(
+    candidates: readonly DynamicGeometryCandidate[],
+    ordering: DynamicGeometryOrdering,
+  ): Result<readonly DynamicGeometryCandidate[], DynamicGeometryError>;
   dynamicGeometryReceipt(candidate: DynamicGeometryCandidate): DynamicGeometryReceipt | undefined;
   cancelDynamicGeometry(candidate: DynamicGeometryCandidate): Result<void, DynamicGeometryError>;
   retireDynamicGeometry(candidate: DynamicGeometryCandidate): Result<void, DynamicGeometryError>;
@@ -269,7 +279,188 @@ export function createDynamicGeometryHost(options: {
     else void completion.then(finish, finish);
     return completion;
   };
-  return {
+  const acceptCandidate = (
+    candidate: DynamicGeometryCandidate,
+    ordering: DynamicGeometryOrdering,
+    deferredSupersession?: Set<HostCandidateRecord>,
+  ): Result<DynamicGeometryCandidate, DynamicGeometryError> => {
+    synchronizeGeneration();
+    const world = candidate.world as World;
+    const hostRecordById = hostCandidates.get(candidate.candidateId);
+    const hostRecord = candidateRecord(candidate);
+    if (hostRecord === undefined && hostRecordById !== undefined)
+      return err(
+        new DynamicGeometryError(
+          'dynamic-geometry-receipt-mismatch',
+          'admission uses the exact host candidate owner and lifecycle credential',
+          'discard the altered credential and use the value returned by preparation',
+          { candidateId: candidate.candidateId },
+        ),
+      );
+    if (hostRecord !== undefined && candidate.state !== 'prepared')
+      return err(
+        new DynamicGeometryError(
+          'dynamic-geometry-candidate-state',
+          'admission consumes a prepared candidate exactly once',
+          'retain the accepted or published candidate receipt instead of admitting it again',
+          { candidateId: candidate.candidateId },
+        ),
+      );
+    if (ordering === undefined || !attachedWorlds.has(world) || ordering.world !== candidate.world)
+      return err(
+        new DynamicGeometryError(
+          'dynamic-geometry-world-not-attached',
+          'candidate and fixed-step ordering belong to the same attached World',
+          'attach the World and submit its PhysicsWorld ordering before accepting geometry',
+          { candidateId: candidate.candidateId },
+        ),
+      );
+    if (!candidate.gpuReady)
+      return err(
+        new DynamicGeometryError(
+          'dynamic-geometry-gpu-not-ready',
+          'candidate has standard GPU residency before acceptance',
+          'prepare with an existing MeshAsset shared handle and repair residency failures',
+          { candidateId: candidate.candidateId },
+        ),
+      );
+    if (
+      hostRecord === undefined ||
+      !hasRenderableBinding(world, candidate.entity) ||
+      !hasMaterialIdentity(world, candidate.entity, candidate.mesh, candidate.materialIdentity)
+    )
+      return err(
+        new DynamicGeometryError(
+          'dynamic-geometry-invalid',
+          'the candidate is bound to a live ECS MeshFilter and MeshRenderer',
+          'keep the candidate MeshFilter binding intact until the consuming draw',
+          { candidateId: candidate.candidateId },
+        ),
+      );
+    if (meshHandleOf(world, candidate.entity) !== hostRecord.previousMeshHandle)
+      return err(
+        new DynamicGeometryError(
+          'dynamic-geometry-invalid',
+          'the old MeshFilter binding remains visible until candidate acceptance',
+          'do not replace the live ECS binding while geometry is prepared',
+          { candidateId: candidate.candidateId },
+        ),
+      );
+    const currentFixedStep = fixedStepOf(world);
+    if (
+      currentFixedStep === undefined ||
+      candidate.fixedStep === undefined ||
+      candidate.fixedStep > currentFixedStep ||
+      ordering.fixedStep !== currentFixedStep
+    )
+      return err(
+        new DynamicGeometryError(
+          'dynamic-geometry-ordering-required',
+          'ordering matches the current World tick, no earlier than preparation',
+          'accept a prepared candidate during the current fixed-step admission',
+          {
+            candidateId: candidate.candidateId,
+            actual: {
+              candidate: candidate.fixedStep,
+              currentFixedStep,
+              ordering: ordering.fixedStep,
+            },
+          },
+        ),
+      );
+    if (candidate.physicsEntity !== undefined) {
+      const publication = physicsPublicationOf(world, candidate.physicsEntity, true);
+      if (
+        publication === undefined ||
+        publication.fixedStep !== currentFixedStep ||
+        publication.revision !== candidate.revision
+      )
+        return err(
+          new DynamicGeometryError(
+            'dynamic-geometry-ordering-required',
+            'candidate physicsEntity has the active paired PhysicsWorld admission',
+            'accept geometry inside admitDerivedShapeCandidate commitGeometry, before physics step',
+            { candidateId: candidate.candidateId, actual: publication },
+          ),
+        );
+    }
+    // One ECS MeshFilter has one visible geometry owner.  Once this
+    // candidate is accepted, any older prepared/accepted candidate for the
+    // same entity can no longer become a receipt-bearing draw. Cancel it
+    // after the new ECS swap so its candidate-only residency is no longer
+    // protected as the live draw owner. Published candidates stay
+    // receipt-bound and are retired independently.
+    const superseded = [...hostCandidates.values()].filter(
+      (record) =>
+        record.candidate.candidateId !== candidate.candidateId &&
+        record.world === world &&
+        record.entity === candidate.entity &&
+        !record.published,
+    );
+    const accepted = lifecycle.accept(candidate, ordering);
+    if (!accepted.ok) return accepted;
+    const swapped = world.set(candidate.entity as EntityHandle, MeshFilter, {
+      assetHandle: hostRecord.meshHandle,
+    });
+    if (!swapped.ok) {
+      lifecycle.cancel(accepted.value);
+      hostCandidates.delete(candidate.candidateId);
+      cleanupCandidateResidency(hostRecord);
+      const released = releaseMeshLeases(hostRecord);
+      if (released !== undefined) return err(released);
+      return err(
+        new DynamicGeometryError(
+          'dynamic-geometry-invalid',
+          'the candidate MeshFilter swap commits through the ECS write barrier',
+          'restore the live entity and retry from a fresh candidate',
+          { candidateId: candidate.candidateId, actual: swapped.error },
+        ),
+      );
+    }
+    hostRecord.candidate = accepted.value;
+    hostRecord.accepted = true;
+    if (deferredSupersession === undefined) options.onTopologyChanged?.();
+    // Keep the World handle leased through the final GPU submission; its slot
+    // must not be reused while a retired frame still references the old mesh.
+    // Cleanup happens only after the new ECS MeshFilter is visible. Before
+    // the swap, hasMeshBinding intentionally protects the older candidate's
+    // GPU copy because it is still the live draw owner.
+    if (deferredSupersession !== undefined) {
+      for (const record of superseded) deferredSupersession.add(record);
+      return accepted;
+    }
+    for (const record of superseded) {
+      const completion = cleanupCandidateResidency(record);
+      const cancelled = lifecycle.cancel(record.candidate, completion);
+      if (!cancelled.ok && cancelled.error.code !== 'dynamic-geometry-candidate-not-found') {
+        const restored = world.set(candidate.entity as EntityHandle, MeshFilter, {
+          assetHandle: hostRecord.previousMeshHandle,
+        });
+        lifecycle.cancel(accepted.value);
+        hostCandidates.delete(candidate.candidateId);
+        cleanupCandidateResidency(hostRecord);
+        releasePreviousMeshLease(hostRecord);
+        return err(
+          new DynamicGeometryError(
+            'dynamic-geometry-invalid',
+            'candidate supersession cancels the prior credential atomically',
+            'keep the prior ECS binding and candidate lifecycle intact when supersession fails',
+            {
+              candidateId: candidate.candidateId,
+              actual: {
+                cancelled: cancelled.error,
+                restored: restored.ok ? undefined : restored.error,
+              },
+            },
+          ),
+        );
+      }
+      hostCandidates.delete(record.candidate.candidateId);
+      scheduleCandidateCleanup(record);
+    }
+    return accepted;
+  };
+  const host: DynamicGeometryHostImplementation = {
     prepareDynamicGeometry(input) {
       const generation = synchronizeGeneration();
       const world = input.world as World;
@@ -463,182 +654,64 @@ export function createDynamicGeometryHost(options: {
       });
       return prepared;
     },
-    acceptDynamicGeometry(candidate, ordering) {
+    acceptDynamicGeometry: (candidate, ordering) => acceptCandidate(candidate, ordering),
+    acceptDynamicGeometryCandidates(candidates, ordering) {
       synchronizeGeneration();
-      const world = candidate.world as World;
-      const hostRecordById = hostCandidates.get(candidate.candidateId);
-      const hostRecord = candidateRecord(candidate);
-      if (hostRecord === undefined && hostRecordById !== undefined)
-        return err(
-          new DynamicGeometryError(
-            'dynamic-geometry-receipt-mismatch',
-            'admission uses the exact host candidate owner and lifecycle credential',
-            'discard the altered credential and use the value returned by preparation',
-            { candidateId: candidate.candidateId },
-          ),
-        );
-      if (hostRecord !== undefined && candidate.state !== 'prepared')
-        return err(
-          new DynamicGeometryError(
-            'dynamic-geometry-candidate-state',
-            'admission consumes a prepared candidate exactly once',
-            'retain the accepted or published candidate receipt instead of admitting it again',
-            { candidateId: candidate.candidateId },
-          ),
-        );
-      if (
-        ordering === undefined ||
-        !attachedWorlds.has(world) ||
-        ordering.world !== candidate.world
-      )
-        return err(
-          new DynamicGeometryError(
-            'dynamic-geometry-world-not-attached',
-            'candidate and fixed-step ordering belong to the same attached World',
-            'attach the World and submit its PhysicsWorld ordering before accepting geometry',
-            { candidateId: candidate.candidateId },
-          ),
-        );
-      if (!candidate.gpuReady)
-        return err(
-          new DynamicGeometryError(
-            'dynamic-geometry-gpu-not-ready',
-            'candidate has standard GPU residency before acceptance',
-            'prepare with an existing MeshAsset shared handle and repair residency failures',
-            { candidateId: candidate.candidateId },
-          ),
-        );
+      // The existing lifecycle's candidate budget bounds this group; there is
+      // no second queue or independently tunable batch allocation limit.
       if (
-        hostRecord === undefined ||
-        !hasRenderableBinding(world, candidate.entity) ||
-        !hasMaterialIdentity(world, candidate.entity, candidate.mesh, candidate.materialIdentity)
+        candidates.length === 0 ||
+        candidates.length > hostCandidates.size ||
+        new Set(candidates.map((candidate) => candidate.entity)).size !== candidates.length ||
+        candidates.some(
+          (candidate) =>
+            candidate.world !== ordering?.world || candidateRecord(candidate) === undefined,
+        )
       )
         return err(
           new DynamicGeometryError(
             'dynamic-geometry-invalid',
-            'the candidate is bound to a live ECS MeshFilter and MeshRenderer',
-            'keep the candidate MeshFilter binding intact until the consuming draw',
-            { candidateId: candidate.candidateId },
+            'a geometry group contains owned candidates for distinct entities in one World',
+            'prepare one candidate per entity and accept the nonempty group in its paired physics admission',
           ),
         );
-      if (meshHandleOf(world, candidate.entity) !== hostRecord.previousMeshHandle)
-        return err(
-          new DynamicGeometryError(
+      const accepted: DynamicGeometryCandidate[] = [];
+      const superseded = new Set<HostCandidateRecord>();
+      const rollback = (): void => {
+        const failures: DynamicGeometryError[] = [];
+        for (const candidate of [...accepted].reverse()) {
+          const result = host.cancelDynamicGeometry(candidate);
+          if (!result.ok) failures.push(result.error);
+        }
+        // A returned failure promises old state. A throw deliberately routes
+        // the paired PhysicsWorld into rebuild-required when that proof fails.
+        if (failures.length > 0)
+          throw new DynamicGeometryError(
             'dynamic-geometry-invalid',
-            'the old MeshFilter binding remains visible until candidate acceptance',
-            'do not replace the live ECS binding while geometry is prepared',
-            { candidateId: candidate.candidateId },
-          ),
-        );
-      const currentFixedStep = fixedStepOf(world);
-      if (
-        currentFixedStep === undefined ||
-        candidate.fixedStep === undefined ||
-        candidate.fixedStep > currentFixedStep ||
-        ordering.fixedStep !== currentFixedStep
-      )
-        return err(
-          new DynamicGeometryError(
-            'dynamic-geometry-ordering-required',
-            'ordering matches the current World tick, no earlier than preparation',
-            'accept a prepared candidate during the current fixed-step admission',
-            {
-              candidateId: candidate.candidateId,
-              actual: {
-                candidate: candidate.fixedStep,
-                currentFixedStep,
-                ordering: ordering.fixedStep,
-              },
-            },
-          ),
-        );
-      if (candidate.physicsEntity !== undefined) {
-        const publication = physicsPublicationOf(world, candidate.physicsEntity, true);
-        if (
-          publication === undefined ||
-          publication.fixedStep !== currentFixedStep ||
-          publication.revision !== candidate.revision
-        )
-          return err(
-            new DynamicGeometryError(
-              'dynamic-geometry-ordering-required',
-              'candidate physicsEntity has the active paired PhysicsWorld admission',
-              'accept geometry inside admitDerivedShapeCandidate commitGeometry, before physics step',
-              { candidateId: candidate.candidateId, actual: publication },
-            ),
+            'a failed geometry group restores every previous ECS binding',
+            'rebuild the paired World and Renderer before rendering or querying physics',
+            { actual: failures },
           );
+      };
+      for (const candidate of candidates) {
+        const result = acceptCandidate(candidate, ordering, superseded);
+        if (!result.ok) {
+          rollback();
+          return err(result.error);
+        }
+        accepted.push(result.value);
       }
-      // One ECS MeshFilter has one visible geometry owner.  Once this
-      // candidate is accepted, any older prepared/accepted candidate for the
-      // same entity can no longer become a receipt-bearing draw. Cancel it
-      // after the new ECS swap so its candidate-only residency is no longer
-      // protected as the live draw owner. Published candidates stay
-      // receipt-bound and are retired independently.
-      const superseded = [...hostCandidates.values()].filter(
-        (record) =>
-          record.candidate.candidateId !== candidate.candidateId &&
-          record.world === world &&
-          record.entity === candidate.entity &&
-          !record.published,
-      );
-      const accepted = lifecycle.accept(candidate, ordering);
-      if (!accepted.ok) return accepted;
-      const swapped = world.set(candidate.entity as EntityHandle, MeshFilter, {
-        assetHandle: hostRecord.meshHandle,
-      });
-      if (!swapped.ok) {
-        lifecycle.cancel(accepted.value);
-        hostCandidates.delete(candidate.candidateId);
-        cleanupCandidateResidency(hostRecord);
-        const released = releaseMeshLeases(hostRecord);
-        if (released !== undefined) return err(released);
-        return err(
-          new DynamicGeometryError(
-            'dynamic-geometry-invalid',
-            'the candidate MeshFilter swap commits through the ECS write barrier',
-            'restore the live entity and retry from a fresh candidate',
-            { candidateId: candidate.candidateId, actual: swapped.error },
-          ),
-        );
-      }
-      hostRecord.candidate = accepted.value;
-      hostRecord.accepted = true;
-      options.onTopologyChanged?.();
-      // Keep the World handle leased through the final GPU submission; its slot
-      // must not be reused while a retired frame still references the old mesh.
-      // Cleanup happens only after the new ECS MeshFilter is visible. Before
-      // the swap, hasMeshBinding intentionally protects the older candidate's
-      // GPU copy because it is still the live draw owner.
+      // Keep all previous unpublished credentials and leases until every ECS
+      // swap succeeds, so a kth-member rejection can still draw the old group.
       for (const record of superseded) {
         const completion = cleanupCandidateResidency(record);
-        const cancelled = lifecycle.cancel(record.candidate, completion);
-        if (!cancelled.ok && cancelled.error.code !== 'dynamic-geometry-candidate-not-found') {
-          const restored = world.set(candidate.entity as EntityHandle, MeshFilter, {
-            assetHandle: hostRecord.previousMeshHandle,
-          });
-          lifecycle.cancel(accepted.value);
-          hostCandidates.delete(candidate.candidateId);
-          cleanupCandidateResidency(hostRecord);
-          releasePreviousMeshLease(hostRecord);
-          return err(
-            new DynamicGeometryError(
-              'dynamic-geometry-invalid',
-              'candidate supersession cancels the prior credential atomically',
-              'keep the prior ECS binding and candidate lifecycle intact when supersession fails',
-              {
-                candidateId: candidate.candidateId,
-                actual: {
-                  cancelled: cancelled.error,
-                  restored: restored.ok ? undefined : restored.error,
-                },
-              },
-            ),
-          );
-        }
-        hostCandidates.delete(record.candidate.candidateId);
+        const result = lifecycle.cancel(record.candidate, completion);
+        if (!result.ok && result.error.code !== 'dynamic-geometry-candidate-not-found')
+          throw result.error;
         scheduleCandidateCleanup(record);
       }
-      return accepted;
+      options.onTopologyChanged?.();
+      return ok(Object.freeze(accepted));
     },
     dynamicGeometryReceipt(candidate) {
       synchronizeGeneration();
@@ -836,4 +909,52 @@ export function createDynamicGeometryHost(options: {
       return receipts;
     },
   };
+  return host;
+}
+
+/**
+ * Renderer assembly adapter for the host's temporal geometry owner.
+ *
+ * Keeping the render-system callback at this boundary prevents the concrete
+ * WebGPU assembly from growing another owner-specific block while preserving
+ * the same lifecycle and residency contracts.
+ */
+export function createRendererDynamicGeometryHost(options: {
+  readonly lifecycle: DynamicGeometryLifecycle;
+  readonly attachedWorlds: ReadonlySet<World>;
+  readonly getGpuStore: () => GpuResidencyCache;
+  readonly currentGeneration: () => number;
+  readonly renderSystem: {
+    readonly invalidateGeometryHistory: () => void;
+    readonly isDynamicGeometryConsumed: (
+      world: World,
+      entity: number,
+      meshHandle: DynamicGeometryCandidate['meshHandle'],
+    ) => boolean;
+  };
+}): DynamicGeometryHostImplementation {
+  const { renderSystem, ...hostOptions } = options;
+  return createDynamicGeometryHost({
+    ...hostOptions,
+    onTopologyChanged: () => renderSystem.invalidateGeometryHistory(),
+    isConsumedByRenderFrame: (candidate) =>
+      renderSystem.isDynamicGeometryConsumed(
+        candidate.world as World,
+        candidate.entity ?? -1,
+        candidate.meshHandle,
+      ),
+  });
+}
+
+export function createRendererDynamicGeometryController(
+  options: Omit<Parameters<typeof createRendererDynamicGeometryHost>[0], 'lifecycle'>,
+): {
+  readonly lifecycle: DynamicGeometryLifecycle;
+  readonly host: DynamicGeometryHostImplementation;
+} {
+  const lifecycle = createDynamicGeometryLifecycle();
+  return {
+    lifecycle,
+    host: createRendererDynamicGeometryHost({ ...options, lifecycle }),
+  };
 }

package/src/assembly/dynamic-geometry-runtime.ts

@@ -0,0 +1,71 @@
+import type { World } from '@forgeax/engine-ecs';
+import type { GpuResidencyCache } from '../device/gpu-residency';
+import {
+  createDynamicGeometryLifecycle,
+  type DynamicGeometryCandidate,
+  type DynamicGeometryLifecycle,
+} from '../dynamic-geometry';
+import { RendererContractFailureError, RendererOperationError } from '../errors/render';
+import type { RenderSystem } from '../render-system';
+import {
+  createDynamicGeometryHost,
+  type DynamicGeometryHostImplementation,
+} from './dynamic-geometry-host';
+
+export interface DynamicGeometryRuntime {
+  readonly lifecycle: DynamicGeometryLifecycle;
+  readonly host: DynamicGeometryHostImplementation;
+}
+
+/** Assemble the renderer-owned candidate lifecycle and its device host. */
+export function createDynamicGeometryRuntime(options: {
+  readonly attachedWorlds: ReadonlySet<World>;
+  readonly getGpuStore: () => GpuResidencyCache;
+  readonly currentGeneration: () => number;
+  readonly renderSystem: Pick<
+    RenderSystem,
+    'invalidateGeometryHistory' | 'isDynamicGeometryConsumed'
+  >;
+}): DynamicGeometryRuntime {
+  const lifecycle = createDynamicGeometryLifecycle();
+  const host = createDynamicGeometryHost({
+    lifecycle,
+    attachedWorlds: options.attachedWorlds,
+    getGpuStore: options.getGpuStore,
+    currentGeneration: options.currentGeneration,
+    onTopologyChanged: () => options.renderSystem.invalidateGeometryHistory(),
+    isConsumedByRenderFrame: (candidate: DynamicGeometryCandidate) =>
+      options.renderSystem.isDynamicGeometryConsumed(
+        candidate.world as World,
+        candidate.entity ?? -1,
+        candidate.meshHandle,
+      ),
+  });
+  return { lifecycle, host };
+}
+
+/** Reject a draw while a derived-physics publication is still unsettled. */
+export function validateDerivedPhysicsFrame(
+  worlds: readonly World[],
+): RendererOperationError<'frame-input-invalid'> | undefined {
+  for (const world of worlds) {
+    if (!world.hasResource('PhysicsWorld')) continue;
+    const physics = world.getResource<{
+      readonly getDerivedAdmission?: () => unknown;
+      readonly getDerivedRecoveryState?: () => string;
+    }>('PhysicsWorld');
+    if (
+      physics?.getDerivedAdmission?.() !== undefined ||
+      physics?.getDerivedRecoveryState?.() === 'rebuild-required'
+    ) {
+      return new RendererOperationError('frame-input-invalid', {
+        operation: 'draw',
+        cause: new RendererContractFailureError(
+          'draw',
+          'paired geometry admission must finish physics step and writeback in a healthy World before draw',
+        ),
+      });
+    }
+  }
+  return undefined;
+}

package/src/assembly/factory.ts

@@ -9,6 +9,9 @@ import type { RendererAssemblyImplementation } from './host-contract';
 import { toError } from './renderer-facade';
 import { tryCreateWebGPURenderer } from './webgpu-renderer';
 
+export { disposeObservationCaptureSet } from './webgpu-renderer';
+export { particleMaterialInputVertexBuffers } from './webgpu-vertex-layouts';
+
 /*
  * Renderer ownership stays explicit even though the implementation is split:
  * the delegated target owner comes from './render-target-host'. The concrete
@@ -69,6 +72,7 @@ export {
   resolveMaterialShaderUvSetCount,
   resolveMaterialShaderVariantSet,
   resolveMaterialShaderVertexInputContract,
+  selectGpuDrivenSceneIndexVariant,
   selectHdrpPbrPrewarmVariants,
   selectNoColorPbrVariant,
   selectPipelineLayoutForVariant,

package/src/assembly/gpu-driven-owner.ts

@@ -0,0 +1,29 @@
+import { err, type RhiDevice, RhiError } from '@forgeax/engine-rhi';
+import { GpuDrivenProduction } from '../gpu-driven/production-raster';
+import type { PipelineBuilderShaderModuleFactory } from '../pipeline-builder';
+
+/**
+ * Renderer-owned GPU-driven frame state boundary. The production object owns
+ * view resources and prepared generations; callers only supply the backend
+ * and shader factory and must not create a parallel frame loop.
+ */
+export function createGpuDrivenOwner(
+  device: RhiDevice,
+  shaderModuleFactory?: PipelineBuilderShaderModuleFactory,
+  recoveryCount = 0,
+): GpuDrivenProduction {
+  return new GpuDrivenProduction(
+    device,
+    shaderModuleFactory ?? {
+      createShaderModule: () =>
+        err(
+          new RhiError({
+            code: 'rhi-not-available',
+            expected: 'the renderer backend exposes shader module creation',
+            hint: 'construct the renderer through the backend pack before activating GPU-driven rendering',
+          }),
+        ),
+    },
+    recoveryCount,
+  );
+}

package/src/assembly/host-contract.ts

@@ -13,6 +13,7 @@ import type { RecoverFailure } from '../errors/recover';
 import type { ObservationUnavailableError, RenderError } from '../errors/render';
 import type { RenderFeature, RenderFeatureDiagnostics } from '../features/types';
 import type { GpuDrivenProductionInspection, LodOcclusionInspection } from '../inspection-types';
+import type { InstanceCollectionStore } from '../instances';
 import type { MeshMaterialBindingObservation } from '../mesh-material-bindings';
 import type { FrameObservation, FrameObservationOptions } from '../record/frame';
 import type { CurrentGraphTarget, GraphTargetCaptureRequest } from '../record/frame-snapshot';
@@ -33,6 +34,7 @@ import type {
   RenderWorldLease,
 } from '../render-contract';
 import type { RenderSceneInspection } from '../render-system';
+import type { RenderSceneBounds } from '../scene/render-scene-types';
 import type {
   RenderTarget,
   RenderTargetDescriptor,
@@ -60,6 +62,8 @@ export type RendererHostEventListener = (event: RendererHostEvent) => void;
  * the public Renderer type.
  */
 export interface RendererHostImplementation {
+  /** Renderer-owned authoring and update path for large instance collections. */
+  readonly instances: InstanceCollectionStore;
   attach(world: World): RenderResult<RenderWorldLease, RenderError>;
   prepareDynamicGeometry(
     input: DynamicGeometryPrepareInput,
@@ -68,6 +72,15 @@ export interface RendererHostImplementation {
     candidate: DynamicGeometryCandidate,
     ordering: DynamicGeometryOrdering,
   ): Result<DynamicGeometryCandidate, DynamicGeometryError>;
+  /**
+   * Atomically swap distinct entities in one attached World. Returned failures
+   * retain old bindings; an uncertain rollback throws to require paired rebuild.
+   * Invoke inside PhysicsWorld.admitDerivedShapeCandidates commitGeometry.
+   */
+  acceptDynamicGeometryCandidates(
+    candidates: readonly DynamicGeometryCandidate[],
+    ordering: DynamicGeometryOrdering,
+  ): Result<readonly DynamicGeometryCandidate[], DynamicGeometryError>;
   dynamicGeometryReceipt(candidate: DynamicGeometryCandidate): DynamicGeometryReceipt | undefined;
   cancelDynamicGeometry(candidate: DynamicGeometryCandidate): Result<void, DynamicGeometryError>;
   retireDynamicGeometry(candidate: DynamicGeometryCandidate): Result<void, DynamicGeometryError>;
@@ -95,6 +108,8 @@ export interface RendererHostImplementation {
   ): RenderResult<RenderTargetReadbackTicket, RenderError>;
   destroyRenderTarget(target: RenderTarget): RenderResult<void, RenderError>;
   setProfile(profile: RenderProfile): RenderResult<void, RenderError>;
+  /** Detached world bounds for one record in the last extracted World; undefined if unavailable. */
+  bounds(world: World, entity: number): RenderSceneBounds | undefined;
   inspect(): RenderInspection;
   /**
    * Internal bounded inspection for high-cardinality producers. The public
@@ -106,6 +121,10 @@ export interface RendererHostImplementation {
     readonly gpuDriven: GpuDrivenProductionInspection;
   };
   drawFrame(request: RenderFrameInput): RenderResult<FrameReceipt, RhiError | RenderError>;
+  /** Arm one upcoming frame for receipt-bound color observations. */
+  requestObservation?: (
+    domains: readonly import('../render-contract').FrameObservationDomain[],
+  ) => RenderResult<void, RenderError>;
   observe(
     receipt: FrameReceipt,
     request: FrameObservationRequest,