@forgeax/engine-render 0.1.4 → 0.1.6

package/src/__tests__/urp-pipeline-targets.unit.test.ts

@@ -3,11 +3,10 @@ import { resolveStandardRenderFeatureTargets } from '../features/targets';
 
 function targets(
   tonemap: 'none' | 'aces-filmic',
-  antialias: 'none' | 'fxaa' | 'msaa' | 'taa',
+  antialias: 'none' | 'fxaa' | 'msaa',
   storageBuffer: boolean,
 ) {
   return resolveStandardRenderFeatureTargets({
-    pipelineId: 'forgeax::urp',
     tonemap,
     antialias,
     colorAttachmentFormat: 'bgra8unorm-srgb',
@@ -40,13 +39,4 @@ describe('urp render feature targets', () => {
       sampleCount: 1,
     });
   });
-
-  it('publishes packed temporal coverage only for TAA', () => {
-    expect(targets('none', 'taa', true)?.[2]).toMatchObject({
-      kind: 'scene-temporal',
-      format: 'rgba16float',
-      sampleCount: 1,
-    });
-    expect(targets('none', 'none', true)).toHaveLength(2);
-  });
 });

package/src/__tests__/urp-pipeline.unit.test.ts

@@ -1,9 +1,9 @@
 import { describe, expect, it } from 'vitest';
 import { resolvePostColorDomainContract } from '../render-pipeline';
 
-describe('URP post color-domain order', () => {
+describe('Standard forward post color-domain order', () => {
   it('declares the required linear-to-encoded stage sequence', () => {
-    expect(resolvePostColorDomainContract('urp')).toEqual([
+    expect(resolvePostColorDomainContract('linear-ldr')).toEqual([
       ['transparent-blend', 'linear-ldr', 'linear-ldr'],
       ['bloom', 'linear-hdr', 'linear-hdr'],
       ['tone', 'linear-hdr', 'linear-ldr'],

package/src/__tests__/vertex-color-pipeline.unit.test.ts

@@ -4,8 +4,12 @@ import {
 } from '@forgeax/engine-geometry';
 import type { VertexAttributeMap } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
-import { variantSetFromVertexLayoutProjection } from '../pipeline';
-import { buildPipelineDescriptor, cacheKeyOf, type PipelineSpec } from '../pipeline-spec';
+import {
+  buildPipelineDescriptor,
+  cacheKeyOf,
+  type PipelineSpec,
+  variantSetFromVertexLayoutProjection,
+} from '../pipeline-spec';
 
 const baseAttributes = (): VertexAttributeMap => ({
   position: new Float32Array([0, 0, 0]),
@@ -93,6 +97,10 @@ describe('render vertex-color projection contract', () => {
         'CLUSTER_FORWARD_AVAILABLE=false+STORAGE_BUFFER_AVAILABLE=true+VERTEX_COLOR_AVAILABLE=true',
     });
     expect(variantSetFromVertexLayoutProjection(colored, '')).toEqual({ ok: true, value: '' });
+    expect(variantSetFromVertexLayoutProjection(plain, '')).toEqual({
+      ok: true,
+      value: 'VERTEX_COLOR_AVAILABLE=false',
+    });
   });
 
   it('does not allocate color stream bytes for a plain mesh', () => {

package/src/__tests__/vertex-layout-consumer.unit.test.ts

@@ -7,7 +7,7 @@ const source = (name: string): string =>
 describe('render consumes geometry layout projection', () => {
   it('does not retain the legacy stride discriminator or uv count as layout authority', () => {
     const renderData = source('render-data.ts');
-    const store = source('gpu-resource-store.ts');
+    const store = source('device/gpu-residency.ts');
     const pipeline = source('pipeline-spec.ts');
 
     expect(renderData).toMatch(/VertexLayoutProjection/);

package/src/__tests__/visibility-diagnostics.integration.test.ts

@@ -1,15 +1,12 @@
+import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
 import { World } from '@forgeax/engine-ecs';
-import { createPrimitiveMesh } from '@forgeax/engine-geometry';
-import {
-  Camera,
-  extractFrames,
-  MeshFilter,
-  MeshRenderer,
-  Visibility,
-  VisibilityStateValue,
-} from '@forgeax/engine-render/internal';
 import { registerPropagateTransforms, Transform } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
+import { Camera } from '../components/camera';
+import { MeshFilter } from '../components/mesh-filter';
+import { MeshRenderer } from '../components/mesh-renderer';
+import { Visibility, VisibilityStateValue } from '../components/visibility';
+import { extractFrames } from '../render-system-extract';
 
 function spawnCamera(world: World): void {
   world
@@ -21,11 +18,10 @@ function spawnCamera(world: World): void {
 }
 
 function spawnCandidate(world: World, state: keyof typeof VisibilityStateValue) {
-  const meshHandle = world.internSharedRef('MeshAsset', createPrimitiveMesh('cube').unwrap());
   return world
     .spawn(
       { component: Transform, data: { pos: [0, 0, 200] } },
-      { component: MeshFilter, data: { assetHandle: meshHandle } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
       { component: MeshRenderer, data: {} },
       { component: Visibility, data: { state: VisibilityStateValue[state] } },
     )

package/src/__tests__/visibility-extract.integration.test.ts

@@ -1,14 +1,8 @@
 import { World } from '@forgeax/engine-ecs';
-import { createWorldProjection } from '@forgeax/engine-ecs/projection';
-import {
-  extractFrame,
-  extractFrames,
-  prepareExtractContext,
-  Visibility,
-  VisibilityStateValue,
-} from '@forgeax/engine-render/internal';
 import { ChildOf, registerPropagateTransforms, Transform } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
+import { Visibility, VisibilityStateValue } from '../components/visibility';
+import { extractFrame, extractFrames, prepareExtractContext } from '../render-system-extract';
 
 function transform(pos: [number, number, number]) {
   return {
@@ -54,14 +48,29 @@ describe('visibility extract orchestration', () => {
     const { world, parent, child } = makeWorld();
     world.update(0).unwrap();
     const before = [...world.get(child, Transform).unwrap().world];
+    const beforeInspection = world.inspect();
+    const beforeShape = {
+      entityCount: beforeInspection.entityCount,
+      archetypeCount: beforeInspection.archetypeCount,
+      tableCount: beforeInspection.tableCount,
+      activeComponents: beforeInspection.activeComponents,
+      systemCount: beforeInspection.systemCount,
+      resourceKeys: beforeInspection.resourceKeys,
+    };
 
     world.set(parent, Transform, { pos: [9, 0, 0] }).unwrap();
-    const projection = createWorldProjection(world, { components: [Transform] });
-    projection.poll();
     extractFrames([world], 0);
 
     expect([...world.get(child, Transform).unwrap().world]).toEqual(before);
-    expect(projection.poll()).toMatchObject({ changes: [] });
+    const afterInspection = world.inspect();
+    expect({
+      entityCount: afterInspection.entityCount,
+      archetypeCount: afterInspection.archetypeCount,
+      tableCount: afterInspection.tableCount,
+      activeComponents: afterInspection.activeComponents,
+      systemCount: afterInspection.systemCount,
+      resourceKeys: afterInspection.resourceKeys,
+    }).toEqual(beforeShape);
     world.update(0).unwrap();
     expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(11);
   });

package/src/__tests__/visibility-extract.perf.test.ts

@@ -1,22 +1,40 @@
+import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
 import { World } from '@forgeax/engine-ecs';
-import { createPrimitiveMesh } from '@forgeax/engine-geometry';
-import {
-  extractFrames,
-  MeshFilter,
-  MeshRenderer,
-  Visibility,
-  VisibilityStateValue,
-} from '@forgeax/engine-render/internal';
 import { ChildOf, Transform } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
+import { MeshFilter } from '../components/mesh-filter';
+import { MeshRenderer } from '../components/mesh-renderer';
+import { Visibility, VisibilityStateValue } from '../components/visibility';
+import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+import { extractFrames } from '../render-system-extract';
+import { RenderScene } from '../scene/render-scene';
 
 const ENTITY_COUNT = 10_000;
 const SAMPLE_COUNT = 101;
-const PERF_TEST_TIMEOUT_MS = 600_000;
+
+const sceneMaterial = {} as MaterialSnapshot;
+
+function sceneSnapshot(entityKey: number): RenderableSnapshot {
+  const world = new Float32Array(16);
+  world[0] = 1;
+  world[5] = 1;
+  world[10] = 1;
+  world[15] = 1;
+  world[12] = entityKey % 1_000;
+  return {
+    assetHandle: 1,
+    transform: { world },
+    localAabb: new Float32Array([-0.5, -0.5, -0.5, 0.5, 0.5, 0.5]),
+    material: { ...sceneMaterial, materialHandle: entityKey % 1_000 },
+    materials: [{ ...sceneMaterial, materialHandle: entityKey % 1_000 }],
+    materialBindingSources: ['engine-default'],
+    worldId: 0,
+    entityKey,
+  };
+}
 
 function buildWorld(inherited: boolean, withHierarchy: boolean): World {
   const world = new World();
-  const meshHandle = world.internSharedRef('MeshAsset', createPrimitiveMesh('cube').unwrap());
   const parent = withHierarchy
     ? world
         .spawn(
@@ -36,7 +54,7 @@ function buildWorld(inherited: boolean, withHierarchy: boolean): World {
         ...(inherited
           ? [{ component: Visibility, data: { state: VisibilityStateValue.inherited } }]
           : []),
-        { component: MeshFilter, data: { assetHandle: meshHandle } },
+        { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
         { component: MeshRenderer, data: {} },
       )
       .unwrap();
@@ -71,26 +89,42 @@ function measureWorlds(worlds: readonly World[]): number[] {
 }
 
 describe('visibility extraction performance (10k)', () => {
-  it(
-    'keeps inherited hierarchy extraction within the 10 percent budget',
-    () => {
-      const flat = buildWorld(false, false);
-      const hierarchy = buildWorld(false, true);
-      const inherited = buildWorld(true, true);
-      const flatMedian = measureWorlds([flat])[0] ?? 0;
-      const [hierarchyMedian = 0, inheritedMedian = 0] = measureWorlds([hierarchy, inherited]);
-      const overhead = inheritedMedian / Math.max(hierarchyMedian, 0.001) - 1;
-      // biome-ignore lint/suspicious/noConsole: retain benchmark profile evidence
-      console.info(
-        `[m3-b-performance] flat=${flatMedian.toFixed(3)}ms hierarchy=${hierarchyMedian.toFixed(3)}ms inherited=${inheritedMedian.toFixed(3)}ms overhead=${(overhead * 100).toFixed(2)}% samples=${SAMPLE_COUNT}`,
-      );
+  it('keeps inherited hierarchy extraction within the 10 percent budget', () => {
+    const flat = buildWorld(false, false);
+    const hierarchy = buildWorld(false, true);
+    const inherited = buildWorld(true, true);
+    const flatMedian = measureWorlds([flat])[0] ?? 0;
+    const [hierarchyMedian = 0, inheritedMedian = 0] = measureWorlds([hierarchy, inherited]);
+    const overhead = inheritedMedian / Math.max(hierarchyMedian, 0.001) - 1;
+    // biome-ignore lint/suspicious/noConsole: retain benchmark profile evidence
+    console.info(
+      `[m3-b-performance] flat=${flatMedian.toFixed(3)}ms hierarchy=${hierarchyMedian.toFixed(3)}ms inherited=${inheritedMedian.toFixed(3)}ms overhead=${(overhead * 100).toFixed(2)}% samples=${SAMPLE_COUNT}`,
+    );
+
+    expect(overhead).toBeLessThanOrEqual(0.1);
+  }, 60_000);
+
+  it('keeps RenderScene delta and no-change evidence on the 100k workload', () => {
+    const scene = new RenderScene();
+    scene.reset(Array.from({ length: 100_000 }, (_, entityKey) => sceneSnapshot(entityKey)));
+    const stable = scene.materialize();
+    const noChange = scene.apply([]);
+    const delta = scene.apply(
+      Array.from({ length: 10_000 }, (_, entityKey) => {
+        const previous = stable[entityKey];
+        const world =
+          previous === undefined
+            ? new Float32Array(16)
+            : new Float32Array(previous.transform.world);
+        world[12] = (world[12] ?? 0) + 1;
+        return { kind: 'update-transform' as const, worldId: 0, entityKey, world };
+      }),
+    );
 
-      expect(overhead).toBeLessThanOrEqual(0.1);
-      // 10k entities x 101 samples is intentionally a large ratio benchmark. The
-      // Linux self-hosted carriers can spend >330s in this uninstrumented test even
-      // though the measured ratio is healthy; keep the benchmark budget intact and
-      // give those carriers an honest wall-clock envelope.
-    },
-    PERF_TEST_TIMEOUT_MS,
-  );
+    expect(noChange).toMatchObject({ updated: 0, resynced: 0 });
+    expect(delta).toMatchObject({ updated: 10_000, resynced: 0 });
+    expect(scene.inspect()).toMatchObject({ renderableScans: 10_000 });
+    expect(scene.materialize()).not.toBe(stable);
+    expect(scene.querySpatial({ min: [-1, -1, -1], max: [1, 1, 1] }).length).toBeGreaterThan(0);
+  }, 60_000);
 });

package/src/__tests__/visibility-feature-dedup.integration.test.ts

@@ -13,8 +13,7 @@ describe('render feature visibility report deduplication', () => {
         context.reportHiddenEntity?.({ world, entity: 3 as never });
         return ok({ count: context.worlds.length });
       },
-      prepare: () => ok(undefined),
-      contribute: () => ok(undefined),
+      plan: () => ok({ resources: [], passes: [] }),
     };
     const host = createRenderFeatureHost([feature]).unwrap();
 
@@ -39,8 +38,7 @@ describe('render feature visibility report deduplication', () => {
         context.reportHiddenEntity?.({ world: second, entity: 1 as never });
         return ok({ count: context.worlds.length });
       },
-      prepare: () => ok(undefined),
-      contribute: () => ok(undefined),
+      plan: () => ok({ resources: [], passes: [] }),
     };
     const host = createRenderFeatureHost([feature]).unwrap();
     const result = runRenderFeatureFrame(host, {

package/src/__tests__/visibility-hidden-report.unit.test.ts

@@ -20,8 +20,7 @@ describe('render feature hidden entity report contract', () => {
         context.reportHiddenEntity?.({ world, entity: 9 as never });
         return ok({ count: context.worlds.length });
       },
-      prepare: () => ok(undefined),
-      contribute: () => ok(undefined),
+      plan: () => ok({ resources: [], passes: [] }),
     };
     const host = createRenderFeatureHost([feature]).unwrap();
     const result = runRenderFeatureFrame(host, {

package/src/__tests__/visibility-instances.integration.test.ts

@@ -1,24 +1,20 @@
+import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
 import { World } from '@forgeax/engine-ecs';
-import { createPrimitiveMesh } from '@forgeax/engine-geometry';
-import {
-  extractFrames,
-  Instances,
-  MeshFilter,
-  MeshRenderer,
-  Visibility,
-  VisibilityStateValue,
-} from '@forgeax/engine-render/internal';
 import { Transform } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
+import { Instances } from '../components/instances';
+import { MeshFilter } from '../components/mesh-filter';
+import { MeshRenderer } from '../components/mesh-renderer';
+import { Visibility, VisibilityStateValue } from '../components/visibility';
+import { extractFrames } from '../render-system-extract';
 
 const IDENTITY = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
 
 function spawnInstance(world: World, state: keyof typeof VisibilityStateValue) {
-  const meshHandle = world.internSharedRef('MeshAsset', createPrimitiveMesh('cube').unwrap());
   return world
     .spawn(
       { component: Transform, data: {} },
-      { component: MeshFilter, data: { assetHandle: meshHandle } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
       { component: MeshRenderer, data: {} },
       { component: Instances, data: { transforms: new Float32Array(IDENTITY) } },
       { component: Visibility, data: { state: VisibilityStateValue[state] } },

package/src/__tests__/visibility-multi-world.integration.test.ts

@@ -1,12 +1,31 @@
 import { World } from '@forgeax/engine-ecs';
-import {
-  extractFrames,
-  resolveVisibility,
-  Visibility,
-  VisibilityStateValue,
-} from '@forgeax/engine-render/internal';
 import { ChildOf } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
+import { Visibility, VisibilityStateValue } from '../components/visibility';
+import { resolveVisibility } from '../extract/visibility';
+import type { MaterialSnapshot, RenderableSnapshot } from '../render-system-extract';
+import { extractFrames } from '../render-system-extract';
+import { RenderScene } from '../scene/render-scene';
+
+const sceneMaterial = {} as MaterialSnapshot;
+
+function sceneSnapshot(worldId: number, entityKey: number, x: number): RenderableSnapshot {
+  const world = new Float32Array(16);
+  world[0] = 1;
+  world[5] = 1;
+  world[10] = 1;
+  world[15] = 1;
+  world[12] = x;
+  return {
+    assetHandle: 1,
+    transform: { world },
+    material: sceneMaterial,
+    materials: [sceneMaterial],
+    materialBindingSources: ['engine-default'],
+    worldId,
+    entityKey,
+  };
+}
 
 describe('visibility World isolation', () => {
   it('does not share intent or effective results for equal entity handles', () => {
@@ -51,4 +70,17 @@ describe('visibility World isolation', () => {
     expect(frame.visibilitySnapshots[0]?.get(firstChild)?.effective).toBe('hidden');
     expect(frame.visibilitySnapshots[1]?.get(secondChild)?.effective).toBe('visible');
   });
+
+  it('keeps equal entity keys isolated when multi-world scene order changes', () => {
+    const scene = new RenderScene();
+    scene.reset([sceneSnapshot(0, 3, 1), sceneSnapshot(1, 3, 2)]);
+    const first = scene.slot(0, 3);
+    const second = scene.slot(1, 3);
+
+    scene.reset([sceneSnapshot(1, 3, 2), sceneSnapshot(0, 3, 1)]);
+
+    expect(scene.slot(0, 3)).toMatchObject({ slot: first?.slot, generation: first?.generation });
+    expect(scene.slot(1, 3)).toMatchObject({ slot: second?.slot, generation: second?.generation });
+    expect(scene.materialize().map((entry) => entry.worldId)).toEqual([1, 0]);
+  });
 });

package/src/__tests__/visibility-producer-matrix.integration.test.ts

@@ -1,22 +1,18 @@
+import { HANDLE_CUBE, HANDLE_QUAD, resolveTilesetRuntime } from '@forgeax/engine-assets-runtime';
 import { type EntityHandle, World } from '@forgeax/engine-ecs';
-import { createPrimitiveMesh, type PrimitiveMeshKind } from '@forgeax/engine-geometry';
-import {
-  extractFrames,
-  Instances,
-  MeshFilter,
-  MeshRenderer,
-  SpriteInstances,
-  TileLayer,
-  Tilemap,
-  tilemapChunkExtractSystem,
-  Visibility,
-  VisibilityStateValue,
-} from '@forgeax/engine-render/internal';
 import { ChildOf, Transform } from '@forgeax/engine-scene';
 import { Skin } from '@forgeax/engine-skinning';
-import type { TextureAsset, TilesetAsset } from '@forgeax/engine-types';
+import { type TilesetAsset, toShared } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
-import { resolveTilesetRuntime } from '../tilemap/resolve-tileset-runtime';
+import { Instances } from '../components/instances';
+import { MeshFilter } from '../components/mesh-filter';
+import { MeshRenderer } from '../components/mesh-renderer';
+import { SpriteInstances } from '../components/sprite-instances';
+import { TileLayer } from '../components/tile-layer';
+import { Tilemap } from '../components/tilemap';
+import { Visibility, VisibilityStateValue } from '../components/visibility';
+import { extractFrames } from '../render-system-extract';
+import { tilemapChunkExtractSystem } from '../tilemap-chunk-extract-system';
 
 const IDENTITY = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
 
@@ -25,16 +21,11 @@ type ProducerCase = {
   readonly setup: (world: World) => EntityHandle;
 };
 
-function primitiveMesh(world: World, kind: PrimitiveMeshKind) {
-  return world.internSharedRef('MeshAsset', createPrimitiveMesh(kind).unwrap());
-}
-
 function staticMesh(world: World): EntityHandle {
-  const meshHandle = primitiveMesh(world, 'cube');
   return world
     .spawn(
       { component: Transform, data: {} },
-      { component: MeshFilter, data: { assetHandle: meshHandle } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
       { component: MeshRenderer, data: {} },
       { component: Visibility, data: { state: VisibilityStateValue.hidden } },
     )
@@ -42,24 +33,22 @@ function staticMesh(world: World): EntityHandle {
 }
 
 function skinnedMesh(world: World): EntityHandle {
-  const meshHandle = primitiveMesh(world, 'cube');
   return world
     .spawn(
       { component: Transform, data: {} },
-      { component: MeshFilter, data: { assetHandle: meshHandle } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
       { component: MeshRenderer, data: {} },
-      { component: Skin, data: { joints: [] } },
+      { component: Skin, data: { skeleton: toShared<'SkeletonAsset'>(999), joints: [] } },
       { component: Visibility, data: { state: VisibilityStateValue.hidden } },
     )
     .unwrap();
 }
 
 function spriteMesh(world: World): EntityHandle {
-  const meshHandle = primitiveMesh(world, 'quad');
   return world
     .spawn(
       { component: Transform, data: {} },
-      { component: MeshFilter, data: { assetHandle: meshHandle } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_QUAD } },
       { component: MeshRenderer, data: {} },
       {
         component: SpriteInstances,
@@ -71,11 +60,10 @@ function spriteMesh(world: World): EntityHandle {
 }
 
 function autoFoldInstances(world: World): EntityHandle {
-  const meshHandle = primitiveMesh(world, 'cube');
   return world
     .spawn(
       { component: Transform, data: {} },
-      { component: MeshFilter, data: { assetHandle: meshHandle } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
       { component: MeshRenderer, data: {} },
       { component: Instances, data: { transforms: IDENTITY } },
       { component: Visibility, data: { state: VisibilityStateValue.hidden } },
@@ -84,11 +72,10 @@ function autoFoldInstances(world: World): EntityHandle {
 }
 
 function explicitInstances(world: World): EntityHandle {
-  const meshHandle = primitiveMesh(world, 'cube');
   return world
     .spawn(
       { component: Transform, data: {} },
-      { component: MeshFilter, data: { assetHandle: meshHandle } },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
       { component: MeshRenderer, data: {} },
       { component: Instances, data: { transforms: IDENTITY } },
       { component: Visibility, data: { state: VisibilityStateValue.hidden } },
@@ -107,17 +94,7 @@ function tilemap(world: World): EntityHandle {
     regions: [{ x: 0, y: 0, width: 16, height: 16 }],
     tiles: [{ regionIndex: 0 }],
   };
-  const atlas: TextureAsset = {
-    kind: 'texture',
-    width: 16,
-    height: 16,
-    format: 'rgba8unorm',
-    data: new Uint8Array(16 * 16 * 4),
-    colorSpace: 'srgb',
-    mipmap: false,
-  };
-  const lookup = (guid: string) =>
-    guid === 'test/tileset' ? tileset : guid === 'visibility/atlas' ? atlas : undefined;
+  const lookup = (guid: string) => (guid === 'test/tileset' ? tileset : undefined);
   const map = world
     .spawn(
       { component: Tilemap, data: { cols: 1, rows: 1, tileset: 'test/tileset' } },

package/src/__tests__/visibility-public-surface.test-d.ts

@@ -1,10 +1,5 @@
 import { World } from '@forgeax/engine-ecs';
-import {
-  Visibility,
-  type VisibilityState,
-  VisibilityStateValue,
-  visibilityStateFromU32,
-} from '@forgeax/engine-render';
+import { Visibility, type VisibilityState, VisibilityStateValue } from '@forgeax/engine-render';
 import { expectTypeOf } from 'vitest';
 
 const world = new World();
@@ -13,14 +8,20 @@ const entity = world.spawn({ component: Visibility, data: {} }).unwrap();
 expectTypeOf(VisibilityStateValue.inherited).toEqualTypeOf<0>();
 expectTypeOf(VisibilityStateValue.hidden).toEqualTypeOf<1>();
 expectTypeOf(VisibilityStateValue.visible).toEqualTypeOf<2>();
-expectTypeOf(visibilityStateFromU32(0)).toEqualTypeOf<VisibilityState | undefined>();
-expectTypeOf(visibilityStateFromU32(99)).toEqualTypeOf<VisibilityState | undefined>();
+expectTypeOf<VisibilityState>().toEqualTypeOf<'inherited' | 'hidden' | 'visible'>();
 
 world.set(entity, Visibility, { state: VisibilityStateValue.visible });
 
 const query = world.query({ read: [Visibility] }).unwrap();
 for (const row of query) {
   const rawState = row.get(Visibility).state;
-  const decodedState = visibilityStateFromU32(rawState ?? VisibilityStateValue.inherited);
+  const decodedState: VisibilityState | undefined =
+    rawState === VisibilityStateValue.hidden
+      ? 'hidden'
+      : rawState === VisibilityStateValue.visible
+        ? 'visible'
+        : rawState === VisibilityStateValue.inherited
+          ? 'inherited'
+          : undefined;
   expectTypeOf(decodedState).toEqualTypeOf<VisibilityState | undefined>();
 }

package/src/__tests__/visibility-resolver.unit.test.ts

@@ -1,7 +1,8 @@
 import { type EntityHandle, World } from '@forgeax/engine-ecs';
 import { ChildOf } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
-import { resolveVisibility, Visibility, VisibilityStateValue } from '../index';
+import { resolveVisibility } from '../extract/visibility';
+import { Visibility, VisibilityStateValue } from '../index';
 
 function spawn(
   world: World,

package/src/__tests__/visibility-resource-short-circuit.unit.test.ts

@@ -0,0 +1,80 @@
+import { AssetRegistry, HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+import { Transform } from '@forgeax/engine-scene';
+import { toShared } from '@forgeax/engine-types';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { MeshFilter } from '../components/mesh-filter';
+import { MeshRenderer } from '../components/mesh-renderer';
+import { Visibility, VisibilityStateValue } from '../components/visibility';
+import { extractFrames } from '../render-system-extract';
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+function captureWorldErrors(): Array<{ readonly code: string }> {
+  const errors: Array<{ readonly code: string }> = [];
+  vi.spyOn(console, 'error').mockImplementation((...args: unknown[]) => {
+    const error = args[args.length - 1];
+    if (typeof error === 'object' && error !== null && 'code' in error) {
+      errors.push(error as { readonly code: string });
+    }
+  });
+  return errors;
+}
+
+function codesForInvalidMaterial(state: number): { hidden: string[]; visible: string[] } {
+  const world = new World();
+  const assets = new AssetRegistry({} as never);
+  const errors = captureWorldErrors();
+  const entity = world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: { materials: [toShared<'MaterialAsset'>(999)] } },
+      { component: Visibility, data: { state } },
+    )
+    .unwrap();
+
+  extractFrames([world], 0, assets);
+  const hiddenCodes = errors.map((error) => error.code);
+  world.set(entity, Visibility, { state: VisibilityStateValue.visible }).unwrap();
+  const beforeVisible = errors.length;
+  extractFrames([world], 0, assets);
+  return { hidden: hiddenCodes, visible: errors.slice(beforeVisible).map((error) => error.code) };
+}
+
+describe('visibility resource short circuit', () => {
+  it('does not resolve a bad override while hidden, then restores the fallback diagnostic', () => {
+    const codes = codesForInvalidMaterial(VisibilityStateValue.hidden);
+
+    expect(codes.hidden).toEqual([]);
+    expect(codes.visible).toContain('mesh-renderer-material-override-invalid');
+  });
+
+  it('does not validate override overflow while hidden', () => {
+    const world = new World();
+    const assets = new AssetRegistry({} as never);
+    const errors = captureWorldErrors();
+    const entity = world
+      .spawn(
+        { component: Transform, data: {} },
+        { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+        {
+          component: MeshRenderer,
+          data: {
+            materials: [toShared<'MaterialAsset'>(998), toShared<'MaterialAsset'>(999)],
+          },
+        },
+        { component: Visibility, data: { state: VisibilityStateValue.hidden } },
+      )
+      .unwrap();
+
+    extractFrames([world], 0, assets);
+    expect(errors).toEqual([]);
+
+    world.set(entity, Visibility, { state: VisibilityStateValue.visible }).unwrap();
+    extractFrames([world], 0, assets);
+    expect(errors.map((error) => error.code)).toContain('mesh-renderer-material-override-overflow');
+  });
+});