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

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

@@ -0,0 +1,98 @@
+import { World } from '@forgeax/engine-ecs';
+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 {
+    pos,
+    quat: [0, 0, 0, 1] as [number, number, number, number],
+    scale: [1, 1, 1] as [number, number, number],
+  };
+}
+
+function makeWorld() {
+  const world = new World();
+  registerPropagateTransforms(world);
+  const parent = world
+    .spawn(
+      { component: Transform, data: transform([1, 0, 0]) },
+      { component: Visibility, data: { state: VisibilityStateValue.hidden } },
+    )
+    .unwrap();
+  const child = world
+    .spawn(
+      { component: Transform, data: transform([2, 0, 0]) },
+      { component: ChildOf, data: { parent } },
+      { component: Visibility, data: { state: VisibilityStateValue.visible } },
+    )
+    .unwrap();
+  return { world, parent, child };
+}
+
+describe('visibility extract orchestration', () => {
+  it('refreshes hierarchy and visibility from the final World state', () => {
+    const { world, parent, child } = makeWorld();
+    world.set(parent, Visibility, { state: VisibilityStateValue.visible }).unwrap();
+    world.update(0).unwrap();
+
+    const frame = extractFrames([world], 0);
+    const snapshot = frame.visibilitySnapshots[0];
+    expect(snapshot?.get(parent)?.effective).toBe('visible');
+    expect(snapshot?.get(child)?.effective).toBe('visible');
+    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(3);
+  });
+
+  it('keeps renderer extraction read-only over derived Transform.world', () => {
+    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();
+    extractFrames([world], 0);
+
+    expect([...world.get(child, Transform).unwrap().world]).toEqual(before);
+    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);
+  });
+
+  it('keeps direct prepared-kernel output aligned with extractFrames output', () => {
+    const { world, child } = makeWorld();
+    const merged = extractFrames([world], 0);
+    const prepared = prepareExtractContext(world);
+    const direct = extractFrame(world, prepared);
+
+    expect(direct.cameras).toEqual(merged.cameras);
+    expect(direct.dispatch).toEqual(merged.dispatch);
+    expect(prepared.visibility.get(child)?.effective).toBe('visible');
+  });
+
+  it('does not reuse a prior visibility result across repeated extracts', () => {
+    const { world, parent } = makeWorld();
+    const first = extractFrames([world], 0);
+    expect(first.visibilitySnapshots[0]?.get(parent)?.effective).toBe('hidden');
+
+    world.set(parent, Visibility, { state: VisibilityStateValue.visible }).unwrap();
+    const second = extractFrames([world], 0);
+    expect(second.visibilitySnapshots[0]?.get(parent)?.effective).toBe('visible');
+  });
+});

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

@@ -0,0 +1,130 @@
+import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+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 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 parent = withHierarchy
+    ? world
+        .spawn(
+          { component: Transform, data: {} },
+          ...(inherited
+            ? [{ component: Visibility, data: { state: VisibilityStateValue.visible } }]
+            : []),
+        )
+        .unwrap()
+    : undefined;
+
+  for (let index = 0; index < ENTITY_COUNT; index++) {
+    world
+      .spawn(
+        { component: Transform, data: {} },
+        ...(parent === undefined ? [] : [{ component: ChildOf, data: { parent } }]),
+        ...(inherited
+          ? [{ component: Visibility, data: { state: VisibilityStateValue.inherited } }]
+          : []),
+        { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+        { component: MeshRenderer, data: {} },
+      )
+      .unwrap();
+  }
+  return world;
+}
+
+function median(values: readonly number[]): number {
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.floor(sorted.length / 2)] ?? 0;
+}
+
+function measureWorldSamples(worlds: readonly World[]): number[][] {
+  for (const world of worlds) extractFrames([world], 0);
+  const samples = worlds.map(() => [] as number[]);
+  for (let sample = 0; sample < SAMPLE_COUNT; sample++) {
+    const firstWorldIndex = sample % worlds.length;
+    for (let offset = 0; offset < worlds.length; offset++) {
+      const worldIndex = (firstWorldIndex + offset) % worlds.length;
+      const world = worlds[worldIndex];
+      if (world === undefined) continue;
+      const start = performance.now();
+      extractFrames([world], 0);
+      samples[worldIndex]?.push(performance.now() - start);
+    }
+  }
+  return samples;
+}
+
+function measureWorlds(worlds: readonly World[]): number[] {
+  return measureWorldSamples(worlds).map((values) => median(values));
+}
+
+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}`,
+    );
+
+    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(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

@@ -0,0 +1,55 @@
+import { World } from '@forgeax/engine-ecs';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createRenderFeatureHost, runRenderFeatureFrame } from '../features/host';
+import type { RenderFeature } from '../features/types';
+
+describe('render feature visibility report deduplication', () => {
+  it('deduplicates a built-in and feature report by World identity and entity', () => {
+    const world = new World();
+    const feature: RenderFeature<{ readonly count: number }> = {
+      identity: 'synthetic.visibility-report',
+      extract: (context) => {
+        context.reportHiddenEntity?.({ world, entity: 3 as never });
+        return ok({ count: context.worlds.length });
+      },
+      plan: () => ok({ resources: [], passes: [] }),
+    };
+    const host = createRenderFeatureHost([feature]).unwrap();
+
+    const result = runRenderFeatureFrame(host, {
+      worlds: [world],
+      owner: 0,
+      frameNumber: 1,
+      caps: {} as never,
+      hiddenEntityReports: [{ world, entity: 3 as never }],
+    });
+
+    expect(result.hiddenEntityReports).toEqual([{ world, entity: 3 }]);
+  });
+
+  it('keeps equal entity handles from different Worlds as separate reports', () => {
+    const first = new World();
+    const second = new World();
+    const feature: RenderFeature<{ readonly count: number }> = {
+      identity: 'synthetic.visibility-worlds',
+      extract: (context) => {
+        context.reportHiddenEntity?.({ world: first, entity: 1 as never });
+        context.reportHiddenEntity?.({ world: second, entity: 1 as never });
+        return ok({ count: context.worlds.length });
+      },
+      plan: () => ok({ resources: [], passes: [] }),
+    };
+    const host = createRenderFeatureHost([feature]).unwrap();
+    const result = runRenderFeatureFrame(host, {
+      worlds: [first, second],
+      owner: 0,
+      frameNumber: 1,
+      caps: {} as never,
+    });
+
+    expect(result.hiddenEntityReports).toHaveLength(2);
+    expect(result.hiddenEntityReports[0]?.world).toBe(first);
+    expect(result.hiddenEntityReports[1]?.world).toBe(second);
+  });
+});

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

@@ -0,0 +1,36 @@
+import { World } from '@forgeax/engine-ecs';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createRenderFeatureHost, runRenderFeatureFrame } from '../features/host';
+import type { RenderFeature, RenderFeatureHiddenEntityReport } from '../features/types';
+
+describe('render feature hidden entity report contract', () => {
+  it('keeps World and entity identity as the only merge keys', () => {
+    const world = new World();
+    const report = { world, entity: 9 as never } satisfies RenderFeatureHiddenEntityReport;
+    expect(Object.keys(report).sort()).toEqual(['entity', 'world']);
+  });
+
+  it('deduplicates reports without changing frustum statistics', () => {
+    const world = new World();
+    const feature: RenderFeature<{ readonly count: number }> = {
+      identity: 'synthetic.hidden-report',
+      extract: (context) => {
+        context.reportHiddenEntity?.({ world, entity: 9 as never });
+        context.reportHiddenEntity?.({ world, entity: 9 as never });
+        return ok({ count: context.worlds.length });
+      },
+      plan: () => ok({ resources: [], passes: [] }),
+    };
+    const host = createRenderFeatureHost([feature]).unwrap();
+    const result = runRenderFeatureFrame(host, {
+      worlds: [world],
+      owner: 0,
+      frameNumber: 1,
+      caps: {} as never,
+    });
+
+    expect(result.hiddenEntityReports).toHaveLength(1);
+    expect(result).not.toHaveProperty('frustumStats');
+  });
+});

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

@@ -0,0 +1,46 @@
+import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
+import { World } from '@forgeax/engine-ecs';
+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) {
+  return world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: {} },
+      { component: Instances, data: { transforms: new Float32Array(IDENTITY) } },
+      { component: Visibility, data: { state: VisibilityStateValue[state] } },
+    )
+    .unwrap();
+}
+
+describe('visibility instance producer gate', () => {
+  it('gates an explicit Instances owner before producing a renderable', () => {
+    const world = new World();
+    const entity = spawnInstance(world, 'hidden');
+
+    const frame = extractFrames([world], 0);
+
+    expect(frame.renderables.some((item) => item.entityKey === entity)).toBe(false);
+    expect(frame.dispatch.some((item) => item.entityIndex === 0)).toBe(false);
+  });
+
+  it('keeps visible members of a mixed batch independent from hidden members', () => {
+    const world = new World();
+    spawnInstance(world, 'hidden');
+    const visible = spawnInstance(world, 'visible');
+
+    const frame = extractFrames([world], 0);
+
+    expect(frame.renderables.map((item) => item.entityKey)).toEqual([visible]);
+    expect(frame.dispatch.length).toBe(2);
+  });
+});

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

@@ -0,0 +1,86 @@
+import { World } from '@forgeax/engine-ecs';
+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', () => {
+    const hiddenWorld = new World();
+    const visibleWorld = new World();
+    const hidden = hiddenWorld
+      .spawn({ component: Visibility, data: { state: VisibilityStateValue.hidden } })
+      .unwrap();
+    const visible = visibleWorld
+      .spawn({ component: Visibility, data: { state: VisibilityStateValue.visible } })
+      .unwrap();
+
+    expect(hidden).toBe(visible);
+    expect(resolveVisibility(hiddenWorld).get(hidden)?.effective).toBe('hidden');
+    expect(resolveVisibility(visibleWorld).get(visible)?.effective).toBe('visible');
+  });
+
+  it('keeps hierarchy parent lookup and snapshots local to each World', () => {
+    const first = new World();
+    const second = new World();
+    const firstParent = first
+      .spawn({ component: Visibility, data: { state: VisibilityStateValue.hidden } })
+      .unwrap();
+    const secondParent = second
+      .spawn({ component: Visibility, data: { state: VisibilityStateValue.visible } })
+      .unwrap();
+    const firstChild = first
+      .spawn(
+        { component: Visibility, data: { state: VisibilityStateValue.inherited } },
+        { component: ChildOf, data: { parent: firstParent } },
+      )
+      .unwrap();
+    const secondChild = second
+      .spawn(
+        { component: Visibility, data: { state: VisibilityStateValue.inherited } },
+        { component: ChildOf, data: { parent: secondParent } },
+      )
+      .unwrap();
+    const frame = extractFrames([first, second], 0);
+
+    expect(frame.visibilitySnapshots).toHaveLength(2);
+    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

@@ -0,0 +1,168 @@
+import { HANDLE_CUBE, HANDLE_QUAD, resolveTilesetRuntime } from '@forgeax/engine-assets-runtime';
+import { type EntityHandle, World } from '@forgeax/engine-ecs';
+import { ChildOf, Transform } from '@forgeax/engine-scene';
+import { Skin } from '@forgeax/engine-skinning';
+import { type TilesetAsset, toShared } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+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]);
+
+type ProducerCase = {
+  readonly name: string;
+  readonly setup: (world: World) => EntityHandle;
+};
+
+function staticMesh(world: World): EntityHandle {
+  return world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: {} },
+      { component: Visibility, data: { state: VisibilityStateValue.hidden } },
+    )
+    .unwrap();
+}
+
+function skinnedMesh(world: World): EntityHandle {
+  return world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: {} },
+      { component: Skin, data: { skeleton: toShared<'SkeletonAsset'>(999), joints: [] } },
+      { component: Visibility, data: { state: VisibilityStateValue.hidden } },
+    )
+    .unwrap();
+}
+
+function spriteMesh(world: World): EntityHandle {
+  return world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: HANDLE_QUAD } },
+      { component: MeshRenderer, data: {} },
+      {
+        component: SpriteInstances,
+        data: { transforms: IDENTITY, regions: new Float32Array([0, 0, 1, 1]) },
+      },
+      { component: Visibility, data: { state: VisibilityStateValue.hidden } },
+    )
+    .unwrap();
+}
+
+function autoFoldInstances(world: World): EntityHandle {
+  return world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: {} },
+      { component: Instances, data: { transforms: IDENTITY } },
+      { component: Visibility, data: { state: VisibilityStateValue.hidden } },
+    )
+    .unwrap();
+}
+
+function explicitInstances(world: World): EntityHandle {
+  return world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
+      { component: MeshRenderer, data: {} },
+      { component: Instances, data: { transforms: IDENTITY } },
+      { component: Visibility, data: { state: VisibilityStateValue.hidden } },
+    )
+    .unwrap();
+}
+
+function tilemap(world: World): EntityHandle {
+  const tileset: TilesetAsset = {
+    kind: 'tileset',
+    atlases: ['visibility/atlas'],
+    tileWidth: 16,
+    tileHeight: 16,
+    columns: 1,
+    rows: 1,
+    regions: [{ x: 0, y: 0, width: 16, height: 16 }],
+    tiles: [{ regionIndex: 0 }],
+  };
+  const lookup = (guid: string) => (guid === 'test/tileset' ? tileset : undefined);
+  const map = world
+    .spawn(
+      { component: Tilemap, data: { cols: 1, rows: 1, tileset: 'test/tileset' } },
+      { component: Transform, data: {} },
+      { component: Visibility, data: { state: VisibilityStateValue.hidden } },
+    )
+    .unwrap();
+  world.spawn(
+    { component: TileLayer, data: { tiles: new Uint32Array([1]), dirty: 0 } },
+    { component: ChildOf, data: { parent: map } },
+  );
+  tilemapChunkExtractSystem(world, lookup);
+  return map;
+}
+
+const PRODUCERS: readonly ProducerCase[] = [
+  { name: 'static mesh', setup: staticMesh },
+  { name: 'skinned mesh', setup: skinnedMesh },
+  { name: 'sprite', setup: spriteMesh },
+  { name: 'auto-fold Instances', setup: autoFoldInstances },
+  { name: 'explicit Instances', setup: explicitInstances },
+  { name: 'tilemap', setup: tilemap },
+];
+
+describe('visibility built-in producer matrix', () => {
+  it.each(PRODUCERS)('$name is hidden, visible, then restorable', ({ setup }) => {
+    const world = new World();
+    const entity = setup(world);
+
+    const hidden = extractFrames([world], 0);
+    expect(hidden.renderables).toHaveLength(0);
+    expect(hidden.dispatch).toHaveLength(0);
+
+    world.set(entity, Visibility, { state: VisibilityStateValue.visible }).unwrap();
+    const visible = extractFrames([world], 0);
+    expect(visible.visibilitySnapshots[0]?.get(entity)?.effective).toBe('visible');
+
+    world.set(entity, Visibility, { state: VisibilityStateValue.hidden }).unwrap();
+    const restored = extractFrames([world], 0);
+    expect(restored.renderables).toHaveLength(0);
+    expect(restored.dispatch).toHaveLength(0);
+  });
+});
+
+describe('tileset durable atlas projection', () => {
+  it('projects the atlas GUID through the current World for the tilemap owner', () => {
+    const world = new World();
+    const atlas = { kind: 'texture', width: 1, height: 1 } as never;
+    const first = resolveTilesetRuntime(world, 'visibility/atlas', (guid) =>
+      guid === 'visibility/atlas' ? atlas : undefined,
+    );
+    const second = resolveTilesetRuntime(world, 'visibility/atlas', () => atlas);
+
+    expect(first.ok).toBe(true);
+    expect(second.ok).toBe(true);
+    if (first.ok && second.ok) expect(first.value.handle).toBe(second.value.handle);
+
+    const otherWorld = new World();
+    const other = resolveTilesetRuntime(otherWorld, 'visibility/atlas', () => atlas);
+    expect(other.ok).toBe(true);
+    if (first.ok && other.ok) {
+      expect(world.sharedRefs.resolve(first.value.handle).ok).toBe(true);
+      expect(otherWorld.sharedRefs.resolve(other.value.handle).ok).toBe(true);
+    }
+  });
+
+  it('fails closed for stale atlas payloads', () => {
+    const result = resolveTilesetRuntime(new World(), 'stale-atlas', () => ({ code: 'stale' }));
+    expect(result).toMatchObject({ ok: false, error: { code: 'tileset-atlas-stale' } });
+  });
+});