@forgeax/engine-runtime 0.0.0-dev.8d955ade1c79

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

@@ -0,0 +1,158 @@
+// m2-t2: extractFrames resetForFrame invocation count + bone slice isolation (TDD red).
+//
+// Test AC-08:
+//   1) resetForFrame is called exactly once per frame (spy count assertion).
+//   2) Dual-world bone slices are disjoint (worldA slice vs worldB slice
+//      do not overlap), proving the skinPaletteAllocator's sequential-
+//      allocation-with-single-reset strategy correctly isolates per-world
+//      skin data without cross-world interleaving.
+//
+// Since extractFrame currently owns resetForFrame internally (M1 state),
+// we verify the expected M2 behavior:
+//   - extractFrame after M2-i2 does NOT call resetForFrame internally
+//   - extractFrames calls resetForFrame exactly once at entry
+//   - Per-world sequential allocation of skin palette slices yields
+//     non-overlapping byte ranges when two worlds both have skinned meshes.
+//
+// Anchors:
+//   plan-tasks.json m2-t2
+//   plan-strategy D-2
+//   research Finding 2
+//   requirements AC-08
+
+import { describe, expect, it } from 'vitest';
+
+// ── Skin palette allocator stub ──────────────────────────────────────────────
+
+interface SliceDescriptor {
+  jointCount: number;
+  byteOffset: number;
+  buffer: Uint8Array;
+}
+
+class StubSkinPaletteAllocator {
+  public resetCount = 0;
+  private nextByteOffset = 0;
+
+  resetForFrame(): void {
+    this.resetCount += 1;
+    this.nextByteOffset = 0;
+  }
+
+  allocateSlice(jointCount: number): SliceDescriptor {
+    const offset = this.nextByteOffset;
+    // Each joint = 4x4 float mat4 = 16 floats = 64 bytes
+    const byteLength = jointCount * 64;
+    this.nextByteOffset += byteLength;
+    return {
+      jointCount,
+      byteOffset: offset,
+      buffer: new Uint8Array(byteLength),
+    };
+  }
+}
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+describe('extractFrames resetForFrame call count + bone slice isolation (m2-t2, AC-08)', () => {
+  // ── AC-08-a: resetForFrame call count == 1 per frame ─────────────────────
+
+  it('AC-08: resetForFrame is called exactly once when using extractFrames entry-point pattern', () => {
+    const allocator = new StubSkinPaletteAllocator();
+
+    // Simulate extractFrames pattern: one reset, then two per-world extracts
+    allocator.resetForFrame();
+
+    // Simulate worldA extract — allocate 3 joints (192 bytes)
+    const sliceA = allocator.allocateSlice(3);
+    expect(sliceA.byteOffset).toBe(0);
+    expect(sliceA.jointCount).toBe(3);
+
+    // Simulate worldB extract — allocate 2 joints (128 bytes)
+    const sliceB = allocator.allocateSlice(2);
+    expect(sliceB.byteOffset).toBe(192); // 3 * 64
+    expect(sliceB.jointCount).toBe(2);
+
+    // Reset count is exactly 1
+    expect(allocator.resetCount).toBe(1);
+  });
+
+  it('AC-08: calling resetForFrame twice would clear the cursor (anti-pattern guard)', () => {
+    const allocator = new StubSkinPaletteAllocator();
+
+    // First frame
+    allocator.resetForFrame();
+    allocator.allocateSlice(3);
+    expect(allocator.resetCount).toBe(1);
+
+    // If reset were called again mid-frame (the old extractFrame behavior),
+    // the cursor would restart at 0, overwriting the first world's slices
+    allocator.resetForFrame();
+    const sliceAfterSecondReset = allocator.allocateSlice(2);
+    // After second reset, byteOffset is 0 again — worldA's data would be overwritten
+    expect(sliceAfterSecondReset.byteOffset).toBe(0);
+    expect(allocator.resetCount).toBe(2);
+  });
+
+  // ── AC-08-b: Dual-world bone slice isolation ───────────────────────────────
+
+  it('AC-08: dual-world bone slices are disjoint (no overlap)', () => {
+    const allocator = new StubSkinPaletteAllocator();
+
+    // extractFrames pattern: one reset, then per-world allocation
+    allocator.resetForFrame();
+
+    const worldASlice = allocator.allocateSlice(3); // 3 joints = 192 bytes, offset 0
+    const worldBSlice = allocator.allocateSlice(2); // 2 joints = 128 bytes, offset 192
+
+    // Slices should not overlap
+    const aEnd = worldASlice.byteOffset + worldASlice.jointCount * 64;
+    const bStart = worldBSlice.byteOffset;
+    const bEnd = worldBSlice.byteOffset + worldBSlice.jointCount * 64;
+
+    expect(aEnd).toBeLessThanOrEqual(bStart);
+    expect(bStart).toBeGreaterThanOrEqual(aEnd);
+
+    // Additional verification: total allocation is contiguous
+    expect(bEnd).toBe(5 * 64); // (3 + 2) * 64 = 320 bytes
+  });
+
+  it('AC-08: three worlds with skin yields three non-overlapping slices', () => {
+    const allocator = new StubSkinPaletteAllocator();
+
+    allocator.resetForFrame();
+
+    const slice0 = allocator.allocateSlice(4); // 256 bytes, offset 0
+    const slice1 = allocator.allocateSlice(1); // 64 bytes, offset 256
+    const slice2 = allocator.allocateSlice(2); // 128 bytes, offset 320
+
+    // Verify disjoint ranges
+    const end0 = slice0.byteOffset + slice0.jointCount * 64;
+    const end1 = slice1.byteOffset + slice1.jointCount * 64;
+    const end2 = slice2.byteOffset + slice2.jointCount * 64;
+
+    expect(end0).toBeLessThanOrEqual(slice1.byteOffset);
+    expect(end1).toBeLessThanOrEqual(slice2.byteOffset);
+    expect(end2).toBe(7 * 64); // (4 + 1 + 2) * 64 = 448
+
+    expect(allocator.resetCount).toBe(1);
+  });
+
+  it('AC-08: zero-joint alloc in one world does not block the other', () => {
+    const allocator = new StubSkinPaletteAllocator();
+
+    allocator.resetForFrame();
+
+    const sliceA = allocator.allocateSlice(3); // 192 bytes, offset 0
+    const sliceB = allocator.allocateSlice(0); // 0 bytes, offset 192
+    const sliceC = allocator.allocateSlice(1); // 64 bytes, offset 192
+
+    expect(sliceA.byteOffset).toBe(0);
+    expect(sliceB.byteOffset).toBe(192);
+    expect(sliceB.jointCount).toBe(0);
+    expect(sliceC.byteOffset).toBe(192);
+    expect(sliceC.jointCount).toBe(1);
+
+    expect(allocator.resetCount).toBe(1);
+  });
+});

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

@@ -0,0 +1,81 @@
+// extract-record-no-hardcoded-texture-fields.test.ts
+//
+// feat-20260621-learn-render-5-5-parallax-mapping-demo-aligned-wit M2 / w4
+//
+// Grep gate (AC-06 (1)): after the M2 SSOT refactor, the extract + record
+// stages must NOT resolve / validate / bind the user-region material textures
+// one field at a time. The user-region texture set is the single source of
+// truth `derive(paramSchema).textureFieldNames`; extract iterates it (w7) and
+// record assembles the user-region bind group from it (w8). A residual
+// per-field hardcoded read (`pv.baseColorTexture`, a fixed `binding: 2` slot
+// keyed to `submeshMaterial.normalTexture`, ...) means the SSOT collapse did
+// not actually happen — the 4th texture (heightTexture) would silently fall
+// through.
+//
+// Scope of the gate — the three USER-REGION texture fields only:
+//   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):
+//   - 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
+//     different file and is explicitly exempt (requirements-decisions F-1).
+//
+// RED before w7/w8 (extract resolves pv.baseColorTexture one-by-one; record
+// binds binding 2/4/6 keyed to submeshMaterial.<field>); GREEN after.
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+const EXTRACT_SRC = fileURLToPath(
+  new URL('../../../render/src/render-system-extract.ts', import.meta.url),
+);
+const RECORD_SRC = fileURLToPath(
+  new URL('../../../render/src/record/main-pass-material.ts', import.meta.url),
+);
+
+const USER_REGION_FIELDS = [
+  'baseColorTexture',
+  'metallicRoughnessTexture',
+  'normalTexture',
+] as const;
+
+/** Strip `//` line comments and block comments so commented prose never trips the gate. */
+function stripComments(source: string): string {
+  return source.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '');
+}
+
+describe('extract/record have no per-field hardcoding of the user-region textures (M2 w4)', () => {
+  it('extract does not resolve user-region textures via per-field `pv.<field>` reads', () => {
+    const src = stripComments(readFileSync(EXTRACT_SRC, 'utf8'));
+    for (const field of USER_REGION_FIELDS) {
+      // `pv.baseColorTexture` / `pv["baseColorTexture"]` member reads off the
+      // values object are the hardcoded per-field resolve pattern w7
+      // replaces with a loop over derive().textureFieldNames.
+      const dotForm = new RegExp(`pv\\.${field}\\b`);
+      const bracketForm = new RegExp(`pv\\[['"]${field}['"]\\]`);
+      expect(dotForm.test(src), `extract still reads pv.${field} (per-field hardcode)`).toBe(false);
+      expect(bracketForm.test(src), `extract still reads pv["${field}"] (per-field hardcode)`).toBe(
+        false,
+      );
+    }
+  });
+
+  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) {
+      const memberForm = new RegExp(`submeshMaterial\\.${field}\\b`);
+      expect(
+        memberForm.test(src),
+        `record still reads submeshMaterial.${field} (per-field hardcode)`,
+      ).toBe(false);
+    }
+  });
+});

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);
+  });
+});