@forgeax/engine-runtime 0.1.3 → 0.1.6

package/src/__tests__/extract-frames-graceful-degradation.test.ts

@@ -21,15 +21,11 @@
 //   requirements AC-09
 
 import { World } from '@forgeax/engine-ecs';
-import type { ExtractedFrame } from '@forgeax/engine-render/internal';
-import {
-  Camera,
-  DirectionalLight,
-  extractFrame,
-  prepareExtractContext,
-} from '@forgeax/engine-render/internal';
+import { Camera, DirectionalLight } from '@forgeax/engine-render';
 import { Transform } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
+import type { ExtractedFrame } from '../../../render/src/render-system-extract';
+import { extractFrame, prepareExtractContext } from '../../../render/src/render-system-extract';
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
 

package/src/__tests__/extract-frames-merge.test.ts

@@ -17,29 +17,33 @@
 //   requirements AC-04/AC-05/AC-06
 
 import { World } from '@forgeax/engine-ecs';
+import { Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import {
+  Camera,
+  DirectionalLight,
+  PostProcessParams,
+  SkyboxBackground,
+  Skylight,
+  SpotLight,
+} from '../../../render/src/components';
+import type { CameraSnapshot } from '../../../render/src/render-contract';
 import type {
-  CameraSnapshot,
   DirectionalLightSnapshot,
   DispatchEntry,
   ExtractedFrame,
   ExtractedLights,
   PointLightSnapshot,
   RenderableSnapshot,
+  SkyboxSnapshot,
+  SkylightSnapshot,
   SpotLightSnapshot,
-} from '@forgeax/engine-render/internal';
+} from '../../../render/src/render-system-extract';
 import {
-  Camera,
-  DirectionalLight,
   extractFrame,
   extractFrames,
-  PostProcessParams,
   prepareExtractContext,
-  SkyboxBackground,
-  Skylight,
-  SpotLight,
-} from '@forgeax/engine-render/internal';
-import { Transform } from '@forgeax/engine-scene';
-import { describe, expect, it } from 'vitest';
+} from '../../../render/src/render-system-extract';
 
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -135,7 +139,10 @@ function simulateMerge(
   lights: ExtractedLights;
   renderables: RenderableSnapshot[];
   dispatch: DispatchEntry[];
-  environment: ExtractedFrame['environment'];
+  skylight: SkylightSnapshot | undefined;
+  skylightCount: number;
+  skybox: SkyboxSnapshot | undefined;
+  skyboxCount: number;
   frustumStats: { culled: number; total: number };
   postProcessParams: Map<string, Uint8Array>;
 } {
@@ -215,7 +222,10 @@ function simulateMerge(
   // AC-05: singletons from owner world only
   // biome-ignore lint/style/noNonNullAssertion: ownerIndex is validated, frames is dense
   const ownerFrame = frames[ownerIndex]!;
-  const environment = ownerFrame.environment;
+  const skylight = ownerFrame.skylight;
+  const skylightCount = ownerFrame.skylightCount;
+  const skybox = ownerFrame.skybox;
+  const skyboxCount = ownerFrame.skyboxCount;
 
   // AC-06: cameras only from owner world
   const cameras = [...ownerFrame.cameras];
@@ -247,7 +257,10 @@ function simulateMerge(
     lights,
     renderables,
     dispatch,
-    environment,
+    skylight,
+    skylightCount,
+    skybox,
+    skyboxCount,
     frustumStats,
     postProcessParams,
   };
@@ -431,13 +444,13 @@ describe('extractFrames merge semantics (m2-t1, AC-04/05/06)', () => {
 
     // owner=0 (worldA)
     const merged = simulateMerge([frameA, frameB], 0);
-    expect(merged.environment.kind).toBe('none');
-    expect(merged.environment.skylightCount).toBe(1);
+    expect(merged.skylight).toBeDefined();
+    expect(merged.skylightCount).toBe(1);
 
     // owner=1 (worldB) — worldB has no skylight
     const merged2 = simulateMerge([frameA, frameB], 1);
-    expect(merged2.environment.kind).toBe('none');
-    expect(merged2.environment.skylightCount).toBe(0);
+    expect(merged2.skylight).toBeUndefined();
+    expect(merged2.skylightCount).toBe(0);
   });
 
   it('AC-05: skybox is taken from owner world only, non-owner ignored', () => {
@@ -448,12 +461,12 @@ describe('extractFrames merge semantics (m2-t1, AC-04/05/06)', () => {
     const frameB = extractFrame(worldB as World, prepareExtractContext(worldB as World));
 
     const merged = simulateMerge([frameA, frameB], 0);
-    expect(merged.environment.kind).toBe('none');
-    expect(merged.environment.skyboxCount).toBe(1);
+    expect(merged.skybox).toBeDefined();
+    expect(merged.skyboxCount).toBe(1);
 
     const merged2 = simulateMerge([frameA, frameB], 1);
-    expect(merged2.environment.kind).toBe('none');
-    expect(merged2.environment.skyboxCount).toBe(0);
+    expect(merged2.skybox).toBeUndefined();
+    expect(merged2.skyboxCount).toBe(0);
   });
 
   it('AC-05: postProcessParams from non-owner world are ignored', () => {

package/src/__tests__/extract-record-no-hardcoded-texture-fields.test.ts

@@ -13,14 +13,15 @@
 // through.
 //
 // Scope of the gate — the three USER-REGION texture fields only:
-//   baseColorTexture / metallicRoughnessTexture / normalTexture /
-//   specularTintTexture / emissiveTexture / occlusionTexture
+//   baseColorTexture / metallicRoughnessTexture / normalTexture
 // These are the fields `derive(default-standard-pbr).textureFieldNames`
 // produces and that w7/w8 route through iteration.
 //
 // Deliberately NOT gated (legitimate residual naming):
-//   - engine-owned IBL bindings: these remain outside the material schema and
-//     are assembled by the injection path; material textures are not exempt.
+//   - emissiveTexture / occlusionTexture: these live in the engine-injection
+//     LIGHTMAP region (appendInjection 'lightmap'), are NOT in any paramSchema
+//     textureFieldNames set, and are assembled by the injection path — naming
+//     them there is the engine-managed region, not user-region hardcoding.
 //   - USER_REGION_TEXTURE_FIELDS in derive-paramschema.ts: the 3-field
 //     register-time under-declaration validator (charter P3 safety net from
 //     the 4.3 blending regression). Orthogonal to binding; lives in a
@@ -44,9 +45,6 @@ const USER_REGION_FIELDS = [
   'baseColorTexture',
   'metallicRoughnessTexture',
   'normalTexture',
-  'specularTintTexture',
-  'emissiveTexture',
-  'occlusionTexture',
 ] as const;
 
 /** Strip `//` line comments and block comments so commented prose never trips the gate. */
@@ -70,15 +68,6 @@ describe('extract/record have no per-field hardcoding of the user-region texture
     }
   });
 
-  it('extract derives coordinate fields from the effective schema', () => {
-    const src = stripComments(readFileSync(EXTRACT_SRC, 'utf8'));
-    // The runtime owner may expose the effective schema through either the
-    // admitted projection or the compatibility-derived interface. Keep the
-    // gate about the contract (iterate the projection's texture set), not an
-    // implementation spelling that would reject the owner path.
-    expect(src).toMatch(/(?:derivedMaterialInterface|derivedInterface)\.textureFieldNames/);
-  });
-
   it('record does not bind user-region textures via per-field `submeshMaterial.<field>` reads', () => {
     const src = stripComments(readFileSync(RECORD_SRC, 'utf8'));
     for (const field of USER_REGION_FIELDS) {

package/src/__tests__/extract-skin-mismatch.unit.test.ts

@@ -0,0 +1,322 @@
+// feat-20260611-fox-skinning-vertex-attribute-chain M4 / w19 (AC-07).
+//
+// Asserts the bidirectional Skin <-> pbr-skin material fail-fast added to
+// `render-system-extract.ts` (w17 / D-5):
+//
+//   (a) Skin component on entity + first-pass shader != forgeax::pbr-skin
+//       -> _routeError fires `SkinMaterialMismatchError` (.code
+//       === 'skin-material-mismatch') and the entity is skipped (continue),
+//       leaving sibling entities in the same frame to render normally.
+//
+//   (b) First-pass shader === forgeax::pbr-skin + mesh.attributes missing
+//       skinIndex / skinWeight -> _routeError fires
+//       `MaterialSkinAttrMissingError` (.code === 'material-skin-attr-missing')
+//       and the entity is skipped.
+//
+//   (c) Skin + pbr-skin material + 6-attribute mesh -> NO error routed
+//       (positive control).
+//
+// Plan-strategy D-5: extract uses `_routeError` + `continue` (one entity's
+// misconfiguration must NOT abort the whole frame's draw list); this test
+// also asserts that a sibling unlit entity in the same frame still extracts
+// to a renderable entry alongside the bad-skin one.
+
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { Camera, MeshFilter, MeshRenderer } from '@forgeax/engine-render';
+import { propagateTransforms, Transform } from '@forgeax/engine-scene';
+import type { ShaderRegistry } from '@forgeax/engine-shader';
+import { Skin } from '@forgeax/engine-skinning';
+import type { Handle, MaterialAsset, MeshAsset, SkeletonAsset } from '@forgeax/engine-types';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { extractFrame, prepareExtractContext } from '../../../render/src/render-system-extract';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+// ── helpers ──────────────────────────────────────────────────────────────
+
+const UNIT_AABB = new Float32Array([-1, -1, -1, 1, 1, 1]);
+// Unskinned: 12 floats / vertex × 3 vertices = 36 (position vec3 + normal vec3 + uv vec2 + tangent vec4).
+const TRIANGLE_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,
+]);
+// Skinned: 18 floats / vertex × 3 vertices = 54 (12 base + skinIndex u16x4 packed in 2 floats at slots 12-13 + skinWeight vec4 at slots 14-17).
+// validateMeshPayload (asset-registry feat: validateMeshPayload skin-aware stride) rejects skin meshes at the 12F stride.
+// Trailing 6 floats per vertex are placeholder (extract path reads attributes.skinIndex/Weight directly, not from interleaved buffer).
+const TRIANGLE_VERTICES_SKINNED = new Float32Array([
+  // v0: pos (0,0,0) | normal (0,0,1) | uv (0,0) | tangent (0,0,0,1) | skin (0,0) | weight (0,0,0,0)
+  0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0,
+  // v1: pos (1,0,0) | normal (0,0,1) | uv (1,0) | tangent (0,0,0,1) | skin (0,0) | weight (0,0,0,0)
+  1, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0,
+  // v2: pos (0,1,0) | normal (0,0,1) | uv (0,1) | tangent (0,0,0,1) | skin (0,0) | weight (0,0,0,0)
+  0, 1, 0, 0, 0, 1, 0, 1, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0,
+]);
+const TRIANGLE_POSITIONS = new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]);
+
+function makeAssetRegistry(): AssetRegistry {
+  const shaderRegistry: ShaderRegistry = makeMockShaderRegistry();
+  // The shared mock registry omits forgeax::pbr-skin (it is the
+  // engine-shipped skin shader registered at boot time elsewhere). The
+  // mismatch path under test needs MaterialAsset register-time validation
+  // to accept first-pass shader === 'forgeax::pbr-skin', so we register a
+  // minimal entry here. paramSchema mirrors the standard PBR family head
+  // (baseColor / metallic / roughness) since this test does not exercise
+  // skin-specific param overlay.
+  shaderRegistry.installMaterialArtifact('forgeax::pbr-skin', {
+    source: 'fn main() {}',
+    paramSchema: [
+      { name: 'baseColor', type: 'color', default: [1.0, 1.0, 1.0, 1.0] },
+      { name: 'metallic', type: 'f32', default: 0.0 },
+      { name: 'roughness', type: 'f32', default: 0.5 },
+    ],
+  });
+  return new AssetRegistry(shaderRegistry);
+}
+
+function registerSkinnedMesh(world: World): Handle<'MeshAsset', 'shared'> {
+  return world.allocSharedRef<'MeshAsset', MeshAsset>('MeshAsset', {
+    kind: 'mesh',
+    vertices: TRIANGLE_VERTICES_SKINNED,
+    indices: new Uint16Array([0, 1, 2]),
+    attributes: {
+      position: TRIANGLE_POSITIONS,
+      // pbr-skin requires skinIndex + skinWeight in attributes; values are
+      // irrelevant here -- key presence is what extract reads.
+      skinIndex: new Uint16Array([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]),
+      skinWeight: new Float32Array([1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0]),
+    },
+    aabb: UNIT_AABB,
+    submeshes: [
+      { indexOffset: 0, indexCount: 3, vertexCount: 3, topology: 'triangle-list', materialSlot: 0 },
+    ],
+
+    materialSlots: [{ slotName: 'Default' }],
+  });
+}
+
+function registerUnskinnedMesh(world: World): Handle<'MeshAsset', 'shared'> {
+  return world.allocSharedRef<'MeshAsset', MeshAsset>('MeshAsset', {
+    kind: 'mesh',
+    vertices: TRIANGLE_VERTICES,
+    indices: new Uint16Array([0, 1, 2]),
+    attributes: { position: TRIANGLE_POSITIONS },
+    aabb: UNIT_AABB,
+    submeshes: [
+      { indexOffset: 0, indexCount: 3, vertexCount: 3, topology: 'triangle-list', materialSlot: 0 },
+    ],
+
+    materialSlots: [{ slotName: 'Default' }],
+  });
+}
+
+function registerPbrSkinMaterial(world: World): Handle<'MaterialAsset', 'shared'> {
+  return world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
+    kind: 'material',
+    passes: [
+      {
+        name: 'Forward',
+        program: { module: 'forgeax::pbr-skin' },
+        renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+      },
+    ],
+    values: { baseColor: [1, 1, 1] },
+  });
+}
+
+function registerUnlitMaterial(world: World): Handle<'MaterialAsset', 'shared'> {
+  return world.allocSharedRef<'MaterialAsset', MaterialAsset>('MaterialAsset', {
+    kind: 'material',
+    passes: [
+      {
+        name: 'Forward',
+        program: { module: 'forgeax::default-unlit' },
+        renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+      },
+    ],
+    values: { baseColor: [1, 1, 1] },
+  });
+}
+
+function registerSkeleton(world: World): Handle<'SkeletonAsset', 'shared'> {
+  return world.allocSharedRef<'SkeletonAsset', SkeletonAsset>('SkeletonAsset', {
+    kind: 'skeleton',
+    inverseBindMatrices: new Float32Array(16),
+    jointCount: 1,
+  });
+}
+
+function spawnCamera(world: World): void {
+  world
+    .spawn(
+      {
+        component: Transform,
+        data: {
+          pos: [0, 0, 5],
+          quat: [0, 0, 0, 1],
+          scale: [1, 1, 1],
+        },
+      },
+      {
+        component: Camera,
+        data: {
+          fov: Math.PI / 4,
+          aspect: 1,
+          near: 0.1,
+          far: 100,
+          projection: 0,
+          left: -1,
+          right: 1,
+          bottom: -1,
+          top: 1,
+        },
+      },
+    )
+    .unwrap();
+}
+
+const IDENTITY_TRANSFORM = {
+  pos: [0, 0, 0],
+  quat: [0, 0, 0, 1],
+  scale: [1, 1, 1],
+} as const;
+
+function spawnRenderable(
+  world: World,
+  meshHandle: Handle<'MeshAsset', 'shared'>,
+  matHandle: Handle<'MaterialAsset', 'shared'>,
+): void {
+  world
+    .spawn(
+      { component: Transform, data: IDENTITY_TRANSFORM },
+      { component: MeshFilter, data: { assetHandle: meshHandle } },
+      { component: MeshRenderer, data: { materials: [matHandle] } },
+    )
+    .unwrap();
+}
+
+function spawnSkinnedRenderable(
+  world: World,
+  meshHandle: Handle<'MeshAsset', 'shared'>,
+  matHandle: Handle<'MaterialAsset', 'shared'>,
+  skeletonHandle: Handle<'SkeletonAsset', 'shared'>,
+): void {
+  // feat-20260612 M2 / m2-6: Skin.joints[] now validated against
+  // SkeletonAsset.jointCount (=1 here) at extract time; spawn one joint
+  // Entity bearing Transform so the count matches and the new
+  // `joint-count-mismatch` / `joint-entity-dangling` checks pass for the
+  // bidirectional Skin <-> pbr-skin mismatch happy path (test (c)).
+  const jointEntity = world.spawn({ component: Transform, data: IDENTITY_TRANSFORM }).unwrap();
+  world
+    .spawn(
+      { component: Transform, data: IDENTITY_TRANSFORM },
+      { component: MeshFilter, data: { assetHandle: meshHandle } },
+      { component: MeshRenderer, data: { materials: [matHandle] } },
+      {
+        component: Skin,
+        data: {
+          skeleton: skeletonHandle,
+          joints: new Uint32Array([jointEntity as unknown as number]),
+        },
+      },
+    )
+    .unwrap();
+}
+
+// ── tests ────────────────────────────────────────────────────────────────
+
+describe('render-system-extract Skin / pbr-skin mismatch (AC-07 / w19)', () => {
+  it('(a) Skin + non-pbr-skin material -> SkinMaterialMismatchError routed + entity skipped', () => {
+    const world = new World();
+    const assets = makeAssetRegistry();
+    const meshHandle = registerSkinnedMesh(world);
+    const unlitMatHandle = registerUnlitMaterial(world);
+    const skeletonHandle = registerSkeleton(world);
+    spawnCamera(world);
+    spawnSkinnedRenderable(world, meshHandle, unlitMatHandle, skeletonHandle);
+    propagateTransforms(world);
+
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+
+    const frame = extractFrame(world, prepareExtractContext(world, { assets }));
+
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+    const [, errArg] = errorSpy.mock.calls[0] ?? [];
+    expect((errArg as { code: string }).code).toBe('skin-material-mismatch');
+    expect((errArg as { detail: { actualShader: string | undefined } }).detail.actualShader).toBe(
+      'forgeax::default-unlit',
+    );
+    // entity skipped -> no renderable entry
+    expect(frame.renderables).toHaveLength(0);
+  });
+
+  it('(b) pbr-skin material + non-skin mesh -> MaterialSkinAttrMissingError routed + entity skipped', () => {
+    const world = new World();
+    const assets = makeAssetRegistry();
+    const meshHandle = registerUnskinnedMesh(world);
+    const skinMatHandle = registerPbrSkinMaterial(world);
+    spawnCamera(world);
+    spawnRenderable(world, meshHandle, skinMatHandle);
+    propagateTransforms(world);
+
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+
+    const frame = extractFrame(world, prepareExtractContext(world, { assets }));
+
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+    const [, errArg] = errorSpy.mock.calls[0] ?? [];
+    expect((errArg as { code: string }).code).toBe('material-skin-attr-missing');
+    expect(
+      (errArg as { detail: { missing: 'skinIndex' | 'skinWeight' | 'both' } }).detail.missing,
+    ).toBe('both');
+
+    expect(frame.renderables).toHaveLength(0);
+  });
+
+  it('(c) Skin + pbr-skin material + skinned mesh -> no error routed', () => {
+    const world = new World();
+    const assets = makeAssetRegistry();
+    const meshHandle = registerSkinnedMesh(world);
+    const skinMatHandle = registerPbrSkinMaterial(world);
+    const skeletonHandle = registerSkeleton(world);
+    spawnCamera(world);
+    spawnSkinnedRenderable(world, meshHandle, skinMatHandle, skeletonHandle);
+    propagateTransforms(world);
+
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+
+    extractFrame(world, prepareExtractContext(world, { assets }));
+
+    expect(errorSpy).not.toHaveBeenCalled();
+  });
+
+  it('(d) D-5 continue semantics: bad-skin entity skipped does NOT abort sibling extract', () => {
+    const world = new World();
+    const assets = makeAssetRegistry();
+    const skinnedMesh = registerSkinnedMesh(world);
+    const unskinnedMesh = registerUnskinnedMesh(world);
+    const unlitMat = registerUnlitMaterial(world);
+    const skeletonHandle = registerSkeleton(world);
+    spawnCamera(world);
+    // bad-skin entity (Skin + unlit material) -> mismatch -> skipped
+    spawnSkinnedRenderable(world, skinnedMesh, unlitMat, skeletonHandle);
+    // sibling well-formed entity (no Skin, unlit material, unskinned mesh)
+    spawnRenderable(world, unskinnedMesh, unlitMat);
+    propagateTransforms(world);
+
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+
+    const frame = extractFrame(world, prepareExtractContext(world, { assets }));
+
+    // exactly one mismatch error (the bad-skin entity), and the sibling
+    // emerges as a renderable -- proving `continue` did not turn into
+    // `return Result.err` for the whole frame.
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+    const [, errArg] = errorSpy.mock.calls[0] ?? [];
+    expect((errArg as { code: string }).code).toBe('skin-material-mismatch');
+    expect(frame.renderables.length).toBeGreaterThanOrEqual(1);
+  });
+});