@forgeax/engine-runtime 0.1.2

package/src/__tests__/render-system-cross-world-overlay-queue.test.ts

@@ -0,0 +1,172 @@
+// feat-20260709-editor-world-partition-editorworld-super-composite / M1 / w2
+// (RED — impl lands in w4/w5/w6). Contract test for cross-world Overlay queue
+// merge ordering.
+//
+// AC-03 (gizmo overlays correctly): an editor gizmo lives in a SEPARATE world
+// from the scene, drawn with an Overlay material pass (queue=4000, depthCompare
+// 'always', depthWriteEnabled=false). When the editorWorld and sceneWorld are
+// composited through `extractFrames(worlds, { cameraOwner, resourceOwner })`,
+// the merged dispatch list must remain queue-sorted ACROSS worlds — so the
+// Overlay (queue=4000) entity from the editorWorld is submitted AFTER the
+// opaque (queue=2000) entity from the sceneWorld. If the merge sorted per-world
+// instead of globally, the gizmo could be recorded before scene geometry and
+// the topmost-overlay guarantee would break.
+//
+// This test asserts the ordering on the MERGED `frame.dispatch` (a single
+// queue-sorted list, plan-strategy D-3). It calls the future two-index owner
+// form so it is RED until w4 changes the extractFrames signature.
+//
+// Scope: queue-merge SEMANTICS only. Pixel-level gizmo visual correctness is
+// M4's job (orchestrator Read(image) of a browser PNG, plan-strategy §5.4);
+// this headless test carries no GPU dependency.
+//
+// Anchors:
+//   requirements AC-03 (gizmo visually overlaid — here: queue merge semantics)
+//   research F3 (gizmo Overlay queue=4000 + depthCompare 'always' +
+//     depthWriteEnabled=false existing mechanism)
+//   plan-strategy §4 risk "cross-world Overlay sort fails" countermeasure
+
+import { World } from '@forgeax/engine-ecs';
+import type { RenderAssetPort } from '@forgeax/engine-render/internal';
+import { Camera, extractFrames, MeshFilter, MeshRenderer } from '@forgeax/engine-render/internal';
+import { Transform } from '@forgeax/engine-scene';
+import { ShaderRegistry, type ShaderRegistryDevice } from '@forgeax/engine-shader';
+import type { Handle, MaterialAsset, MaterialPass, MeshAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createTestRenderAssetOwner } from './helpers/render-asset-port';
+
+// Two-index owner shape w4-w6 introduces (see w1 for rationale).
+interface OwnerSplit {
+  readonly cameraOwner: number;
+  readonly resourceOwner: number;
+}
+type ExtractFramesOwnerSplit = (
+  worlds: readonly World[],
+  owner: OwnerSplit,
+  assets?: RenderAssetPort | null,
+) => ReturnType<typeof extractFrames>;
+const extractFramesSplit = extractFrames as unknown as ExtractFramesOwnerSplit;
+
+const QUEUE_OPAQUE = 2000;
+const QUEUE_OVERLAY = 4000; // research F3: gizmo Overlay queue.
+
+function identityTransform(): {
+  pos: number[];
+  quat: number[];
+  scale: number[];
+} {
+  return { pos: [0, 0, 0], quat: [0, 0, 0, 1], scale: [1, 1, 1] };
+}
+
+function makeShaderRegistry(): ShaderRegistry {
+  const mockDevice: ShaderRegistryDevice = {
+    createShaderModule() {
+      return {
+        ok: true,
+        value: undefined,
+        unwrap: () => undefined,
+        unwrapOr: (d: unknown) => d,
+      } as unknown as ReturnType<ShaderRegistryDevice['createShaderModule']>;
+    },
+  };
+  const sr = new ShaderRegistry({ device: mockDevice, manifestUrl: undefined });
+  sr.installMaterialArtifact('forgeax::default-unlit', {
+    source: 'fn main() {}',
+    paramSchema: [{ name: 'baseColor', type: 'color', default: [1.0, 1.0, 1.0, 1.0] }],
+  });
+  return sr;
+}
+
+// Minimal triangle mesh so the entity is renderable and produces a dispatch.
+// No `aabb` field: the extract-stage frustum cull treats an AABB-less mesh as
+// always-visible (conservative pass-through), so the entity survives extract
+// regardless of camera frustum (headless robustness).
+function registerMesh(world: World): Handle<'MeshAsset', 'shared'> {
+  return world.allocSharedRef<'MeshAsset', MeshAsset>('MeshAsset', {
+    kind: 'mesh',
+    vertices: new Float32Array([
+      0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0,
+      1, 0, 0, 0, 0,
+    ]),
+    indices: new Uint16Array([0, 1, 2]),
+    attributes: { position: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]) },
+    submeshes: [
+      { indexOffset: 0, indexCount: 3, vertexCount: 3, topology: 'triangle-list', materialSlot: 0 },
+    ],
+
+    materialSlots: [{ slotName: 'Default' }],
+  });
+}
+
+function registerMaterial(world: World, queue: number): Handle<'MaterialAsset', 'shared'> {
+  const pass: MaterialPass = {
+    name: queue === QUEUE_OVERLAY ? 'Overlay' : 'Forward',
+    program: { module: 'forgeax::default-unlit' },
+    renderState: { queue },
+  };
+  return world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
+    kind: 'material',
+    passes: [pass],
+    values: {},
+  } as MaterialAsset);
+}
+
+// A world holding a single renderable at the given queue. The mesh carries no
+// AABB, so the entity survives extract regardless of camera frustum (headless
+// robustness — see registerMesh).
+function makeRenderableWorld(queue: number): World {
+  const world = new World();
+  const mesh = registerMesh(world);
+  const mat = registerMaterial(world, queue);
+  world
+    .spawn(
+      { component: Transform, data: identityTransform() },
+      { component: MeshFilter, data: { assetHandle: mesh } },
+      { component: MeshRenderer, data: { materials: [mat] } },
+    )
+    .unwrap();
+  return world;
+}
+
+describe('cross-world Overlay queue merge (w2, AC-03)', () => {
+  it('Overlay(queue=4000) from editorWorld is dispatched AFTER opaque(queue=2000) from sceneWorld', () => {
+    // sceneWorld (index 0): a camera + one opaque renderable. It is the
+    // resourceOwner (supplies singleton resources) and cameraOwner in this
+    // composite; the editorWorld carries only the gizmo overlay.
+    const sceneWorld = makeRenderableWorld(QUEUE_OPAQUE);
+    sceneWorld
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+      )
+      .unwrap();
+
+    // editorWorld (index 1): the gizmo overlay renderable at queue=4000.
+    const editorWorld = makeRenderableWorld(QUEUE_OVERLAY);
+
+    const assets = createTestRenderAssetOwner(makeShaderRegistry());
+    // cameraOwner=0 (scene camera), resourceOwner=0 (scene singletons); the
+    // editorWorld contributes renderables that must merge into the global queue.
+    const frame = extractFramesSplit(
+      [sceneWorld, editorWorld],
+      {
+        cameraOwner: 0,
+        resourceOwner: 0,
+      },
+      assets,
+    );
+
+    // Locate the opaque + overlay dispatch entries in the MERGED list.
+    const opaqueIdx = frame.dispatch.findIndex((d) => d.queue === QUEUE_OPAQUE);
+    const overlayIdx = frame.dispatch.findIndex((d) => d.queue === QUEUE_OVERLAY);
+
+    // Both worlds contributed a dispatch entry (cross-world merge happened).
+    expect(opaqueIdx).toBeGreaterThanOrEqual(0);
+    expect(overlayIdx).toBeGreaterThanOrEqual(0);
+
+    // The core AC-03 guarantee: the Overlay entity (from the editorWorld) is
+    // submitted AFTER the opaque entity (from the sceneWorld) in the single
+    // queue-sorted dispatch list. Per-world sorting would not guarantee this.
+    expect(overlayIdx).toBeGreaterThan(opaqueIdx);
+  });
+});

package/src/__tests__/render-system-extract-dispatch-ordering.test.ts

@@ -0,0 +1,322 @@
+// bug-20260709-builtin-quad-withoutaabb-disables-sprite-frustum-cu M2 / AC-06.
+//
+// Regression lock for the M2.5 `pendingDispatch` + `flushPendingDispatch`
+// pairing that ships with the Stage 1 aabb restore. After M1 restored
+// The quad primitive's local-space aabb lets builtin quads enter the frustum-cull
+// three-gate branch at `render-system-extract.ts` like any user asset.
+// Before M2.5 the three `dispatch.push` sites ran BEFORE the cull `continue`
+// so a culled entity left dangling dispatch entries whose `renderableIndex`
+// aliased the slot a LATER visible entity's renderable occupied. The record
+// stage then read the wrong `materialHandle` and picked the wrong pipeline
+// layout — the `pbr-mesh-array-bgl` (URP) vs `hdrp-unified-bgl-group2` (HDRP)
+// mismatch that showed up 168x on PR #598 CI's deferred-shading smoke.
+//
+// M2.5 stages each entity's dispatch entries into a per-entity
+// `pendingDispatch` array, then flushes them into the shared `dispatch[]`
+// only at the three renderable-push sites (all inside the cull-passed
+// branch). A culled entity `continue`s without flushing, so its pending
+// entries are naturally discarded. Each pending entry captures the current
+// `renderables.length`; no other entity can push before this entity survives
+// culling and takes that slot, so flush can publish the original entry without
+// allocating a second descriptor.
+//
+// Coverage matrix — this file exercises every push × flush combination the
+// runtime unit-test surface can reach:
+//
+//   push A: resolved-material matched-passes loop      (extract.ts ~L3125)
+//   push B: default-material shadow-caster pass         (extract.ts ~L3176)
+//   push C: default-material forward pass               (extract.ts ~L3194)
+//   flush 1: hasInstances && instRes not-ok             (extract.ts ~L3522)
+//   flush 2: hasInstances && instRes ok                 (extract.ts ~L3537)
+//   flush 3: !hasInstances (plain single entity)        (extract.ts ~L3551)
+//
+//   test 1  — push A + flush 3     (main branch, non-instances)
+//   test 2  — push B + push C + flush 3  (default material, non-instances)
+//   test 3  — push A + flush 2     (main branch, instances-success)
+//   test 4  — push A + flush 3     (all-culled scene: zero dispatch)
+//
+// Flush site 1 (hasInstances && !instRes.ok) is unreachable from a healthy
+// spawn — the Instances archetype bundle key implies the component row is
+// live. It shares the exact `renderables.push({ ...baseRenderable, entityKey })`
+// shape with flush 3 by mechanical inspection (extract.ts L3521-3523 vs
+// L3550-3552); no unit-test path drives it without mocking World internals,
+// so it is covered by the shared-shape argument, not by a separate case.
+//
+// Topology-only assertions: this file checks dispatch/renderable slot
+// alignment (`renderableIndex < renderables.length`, count parity, per-entry
+// paramSnapshot equality with the target renderable). It does NOT assert
+// record-stage material handle re-resolution or GPU behaviour — those
+// cross-stage checks live in the hello-shadow-opt-out / deferred-shading
+// dawn smokes (per plan-strategy §5.5).
+
+import { World } from '@forgeax/engine-ecs';
+import { createPrimitiveMesh } from '@forgeax/engine-geometry';
+import {
+  Camera,
+  extractFrame,
+  Instances,
+  MeshFilter,
+  MeshRenderer,
+  prepareExtractContext,
+} from '@forgeax/engine-render/internal';
+import { propagateTransforms, Transform } from '@forgeax/engine-scene';
+import type { MaterialAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+import { createTestRenderAssetOwner } from './helpers/render-asset-port';
+
+function identityTransform() {
+  return {
+    pos: [0, 0, 0] as [number, number, number],
+    quat: [0, 0, 0, 1] as [number, number, number, number],
+    scale: [1, 1, 1] as [number, number, number],
+  };
+}
+
+// Helper for `{...identityTransform(), posZ: N}` migration — build a fresh pos
+// vec with only Z overridden (PR #656 array-schema requires atomic pos writes).
+function transformAtZ(z: number) {
+  return {
+    pos: [0, 0, z] as [number, number, number],
+    quat: [0, 0, 0, 1] as [number, number, number, number],
+    scale: [1, 1, 1] as [number, number, number],
+  };
+}
+
+function perspectiveCameraData() {
+  return {
+    fov: Math.PI / 4,
+    aspect: 1,
+    near: 0.1,
+    far: 100,
+    projection: 0,
+    left: -1,
+    right: 1,
+    bottom: -1,
+    top: 1,
+  };
+}
+
+function spawnFrontFacingCamera(world: World): void {
+  // Camera at posZ=5 looking down -Z (default). With far=100 the far plane
+  // sits near posZ=-95; an entity at posZ=100 is behind the camera and
+  // outside the frustum, so its aabb-carrying renderable is culled.
+  world
+    .spawn(
+      { component: Transform, data: transformAtZ(5) },
+      { component: Camera, data: perspectiveCameraData() },
+    )
+    .unwrap();
+}
+
+function registerUnlitMaterial(world: World, rgb: readonly [number, number, number]) {
+  return world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
+    kind: 'material',
+    passes: [
+      {
+        name: 'Forward',
+        program: { module: 'forgeax::default-unlit' },
+        renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+      },
+    ],
+    values: { baseColor: [rgb[0], rgb[1], rgb[2]] },
+  });
+}
+
+function createQuadHandle(world: World) {
+  return world.internSharedRef('MeshAsset', createPrimitiveMesh('quad').unwrap());
+}
+
+function expectSlotAlignment(
+  frame: ReturnType<typeof extractFrame>,
+  { requireBaseColorEquality }: { requireBaseColorEquality: boolean },
+): void {
+  // Every dispatch entry's renderableIndex must land inside [0, renderables.length).
+  for (const de of frame.dispatch) {
+    expect(de.renderableIndex).toBeGreaterThanOrEqual(0);
+    expect(de.renderableIndex).toBeLessThan(frame.renderables.length);
+    const target = frame.renderables[de.renderableIndex];
+    expect(target).toBeDefined();
+    if (requireBaseColorEquality) {
+      // paramSnapshot.baseColor is the closest AI-user-observable proxy for
+      // "does this dispatch entry belong to this renderable" without crossing
+      // into the record stage's materialHandle resolution.
+      const deColor = (de.paramSnapshot?.baseColor ?? []) as readonly number[];
+      const targetColor = (target?.material.paramSnapshot?.baseColor ?? []) as readonly number[];
+      expect(deColor).toEqual(targetColor);
+    }
+  }
+}
+
+describe('render-system-extract M2.5 dispatch/renderable slot pairing (AC-06)', () => {
+  it("push A + flush 3 (resolved material, non-instances): culled entity does not alias the surviving entity's renderable slot", () => {
+    // Scenario mirrors the PR #598 CI failure signature: entity B (culled)
+    // is spawned FIRST so pre-M2.5 its dispatch push would capture
+    // renderableIndex = 0; entity A (visible) is spawned second and its
+    // renderable pushes into slot 0. Distinct materials make the aliasing
+    // observable via paramSnapshot.baseColor equality.
+    const world = new World();
+    const quadHandle = createQuadHandle(world);
+    const assets = createTestRenderAssetOwner(makeMockShaderRegistry());
+    spawnFrontFacingCamera(world);
+
+    const matGreen = registerUnlitMaterial(world, [0, 1, 0]);
+    const matRed = registerUnlitMaterial(world, [1, 0, 0]);
+
+    world
+      .spawn(
+        { component: Transform, data: transformAtZ(100) },
+        { component: MeshFilter, data: { assetHandle: quadHandle } },
+        { component: MeshRenderer, data: { materials: [matGreen] } },
+      )
+      .unwrap();
+    world
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        { component: MeshFilter, data: { assetHandle: quadHandle } },
+        { component: MeshRenderer, data: { materials: [matRed] } },
+      )
+      .unwrap();
+
+    expect(propagateTransforms(world).ok).toBe(true);
+    const frame = extractFrame(world, prepareExtractContext(world, { assets }));
+
+    expect(frame.renderables).toHaveLength(1);
+    // One matched Forward pass per surviving entity — pre-M2.5 this would be 2
+    // (the culled green entity's dispatch push at push-site A already ran).
+    expect(frame.dispatch).toHaveLength(1);
+    expect(frame.dispatch[0]?.renderableIndex).toBe(0);
+    expect(frame.dispatch[0]?.tags).toEqual({ LightMode: 'Forward' });
+    expect(frame.dispatch[0]?.renderState).toBeUndefined();
+    expect(frame.renderables[0]?.material.renderState).toBeUndefined();
+    expectSlotAlignment(frame, { requireBaseColorEquality: true });
+    // Frustum-stat sanity: cull loop actually ran (Stage 1 aabb restore).
+    expect(frame.frustumStats.total).toBeGreaterThanOrEqual(2);
+    expect(frame.frustumStats.culled).toBeGreaterThanOrEqual(1);
+  });
+
+  it('push B + push C + flush 3 (default material shadow+forward, non-instances): culled entity leaves no dangling dispatch', () => {
+    // MeshRenderer without a materials array drives handleRaw===0 which
+    // fires the default-material two-push block (shadow-caster + forward)
+    // at push-sites B and C. plan-strategy §D-7 explicitly names this branch
+    // as part of the M2.5 fix scope (shadow-opt-out AC-13 depends on it).
+    const world = new World();
+    const quadHandle = createQuadHandle(world);
+    spawnFrontFacingCamera(world);
+
+    world
+      .spawn(
+        { component: Transform, data: transformAtZ(100) },
+        { component: MeshFilter, data: { assetHandle: quadHandle } },
+        { component: MeshRenderer, data: {} as never },
+      )
+      .unwrap();
+    world
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        { component: MeshFilter, data: { assetHandle: quadHandle } },
+        { component: MeshRenderer, data: {} as never },
+      )
+      .unwrap();
+
+    expect(propagateTransforms(world).ok).toBe(true);
+    const frame = extractFrame(world, prepareExtractContext(world));
+
+    expect(frame.renderables).toHaveLength(1);
+    // Two entries per surviving entity (shadow-caster + forward) — pre-M2.5
+    // this would be 4 because both entities pushed the pair before cull.
+    expect(frame.dispatch).toHaveLength(2);
+    // Both entries point at the single surviving renderable's slot.
+    for (const de of frame.dispatch) {
+      expect(de.renderableIndex).toBe(0);
+    }
+    // Both LightMode tags present (shadow + forward) — confirms push B and
+    // push C both flushed through the same flush site (flush 3).
+    const lightModes = frame.dispatch.map((de) => de.tags.LightMode).sort();
+    expect(lightModes).toEqual(['Forward', 'ShadowCaster']);
+    expectSlotAlignment(frame, { requireBaseColorEquality: false });
+  });
+
+  it('push A + flush 2 (resolved material, instances-success): culled instances entity does not leave dangling dispatch', () => {
+    // Instances component drives the hasInstances && instRes.ok branch
+    // (flush site 2). Frustum cull still operates on the entity's own
+    // Transform + local aabb (pre-instance transforms), so an Instances
+    // entity at posZ=100 is culled the same way a plain entity is.
+    const world = new World();
+    const quadHandle = createQuadHandle(world);
+    const assets = createTestRenderAssetOwner(makeMockShaderRegistry());
+    spawnFrontFacingCamera(world);
+
+    const matBlue = registerUnlitMaterial(world, [0, 0, 1]);
+    const matYellow = registerUnlitMaterial(world, [1, 1, 0]);
+
+    // 4 instances, identity mat4 columns each (16 floats per instance).
+    const instanceTransforms = new Float32Array(4 * 16);
+    for (let n = 0; n < 4; n++) {
+      // col-major identity
+      instanceTransforms[n * 16 + 0] = 1;
+      instanceTransforms[n * 16 + 5] = 1;
+      instanceTransforms[n * 16 + 10] = 1;
+      instanceTransforms[n * 16 + 15] = 1;
+    }
+
+    world
+      .spawn(
+        { component: Transform, data: transformAtZ(100) },
+        { component: MeshFilter, data: { assetHandle: quadHandle } },
+        { component: MeshRenderer, data: { materials: [matBlue] } },
+        { component: Instances, data: { transforms: instanceTransforms } },
+      )
+      .unwrap();
+    world
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        { component: MeshFilter, data: { assetHandle: quadHandle } },
+        { component: MeshRenderer, data: { materials: [matYellow] } },
+        { component: Instances, data: { transforms: instanceTransforms } },
+      )
+      .unwrap();
+
+    expect(propagateTransforms(world).ok).toBe(true);
+    const frame = extractFrame(world, prepareExtractContext(world, { assets }));
+
+    expect(frame.renderables).toHaveLength(1);
+    expect(frame.renderables[0]?.instances).toBeDefined();
+    expect(frame.renderables[0]?.instances?.instanceCount).toBe(4);
+    // One resolved-material Forward pass per surviving instances entity.
+    expect(frame.dispatch).toHaveLength(1);
+    expect(frame.dispatch[0]?.renderableIndex).toBe(0);
+    expectSlotAlignment(frame, { requireBaseColorEquality: true });
+  });
+
+  it('push A + flush 3 negative path (all quad entities out of view): zero renderables and zero dispatch', () => {
+    // Edge case from requirements §edge-cases row 4: with all quad
+    // entities off-frustum, `renderables` and `dispatch` both empty; the
+    // per-entity `pendingDispatch` is dropped on every cull `continue` so
+    // no dangling entries leak into the shared `dispatch[]`.
+    const world = new World();
+    const quadHandle = createQuadHandle(world);
+    const assets = createTestRenderAssetOwner(makeMockShaderRegistry());
+    spawnFrontFacingCamera(world);
+
+    const matGrey = registerUnlitMaterial(world, [0.5, 0.5, 0.5]);
+    for (let n = 0; n < 3; n++) {
+      world
+        .spawn(
+          { component: Transform, data: transformAtZ(100 + n) },
+          { component: MeshFilter, data: { assetHandle: quadHandle } },
+          { component: MeshRenderer, data: { materials: [matGrey] } },
+        )
+        .unwrap();
+    }
+
+    expect(propagateTransforms(world).ok).toBe(true);
+    const frame = extractFrame(world, prepareExtractContext(world, { assets }));
+
+    expect(frame.renderables).toHaveLength(0);
+    expect(frame.dispatch).toHaveLength(0);
+    // Cull loop actually visited each entity (Stage 1 aabb restore held).
+    expect(frame.frustumStats.total).toBeGreaterThanOrEqual(3);
+    expect(frame.frustumStats.culled).toBe(frame.frustumStats.total);
+  });
+});