@forgeax/engine-render 0.1.2

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

@@ -0,0 +1,66 @@
+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';
+
+function spawnCamera(world: World): void {
+  world
+    .spawn(
+      { component: Transform, data: { pos: [0, 0, 5] } },
+      { component: Camera, data: { fov: Math.PI / 4, aspect: 1, near: 0.1, far: 100 } },
+    )
+    .unwrap();
+}
+
+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: MeshRenderer, data: {} },
+      { component: Visibility, data: { state: VisibilityStateValue[state] } },
+    )
+    .unwrap();
+}
+
+describe('visibility diagnostics', () => {
+  it('switches from explicit hidden to frustum culling without changing frustum totals', () => {
+    const world = new World();
+    registerPropagateTransforms(world);
+    spawnCamera(world);
+    const entity = spawnCandidate(world, 'hidden');
+    world.update(0).unwrap();
+
+    const hidden = extractFrames([world], 0);
+    expect(hidden.renderables).toHaveLength(0);
+    expect(hidden.visibilityStats).toEqual({ explicitlyHidden: 1 });
+    expect(hidden.frustumStats).toEqual({ culled: 0, total: 0 });
+
+    world.set(entity, Visibility, { state: VisibilityStateValue.visible }).unwrap();
+    const visible = extractFrames([world], 0);
+    expect(visible.renderables).toHaveLength(0);
+    expect(visible.visibilityStats).toEqual({ explicitlyHidden: 0 });
+    expect(visible.frustumStats).toEqual({ culled: 1, total: 1 });
+  });
+
+  it('sums hidden candidate sets per World without counting dispatches or submeshes', () => {
+    const first = new World();
+    const second = new World();
+    spawnCandidate(first, 'hidden');
+    spawnCandidate(second, 'hidden');
+
+    const frame = extractFrames([first, second], 0);
+
+    expect(frame.visibilityStats).toEqual({ explicitlyHidden: 2 });
+    expect(frame.dispatch).toHaveLength(0);
+  });
+});

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

@@ -0,0 +1,89 @@
+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';
+
+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];
+
+    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: [] });
+    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,96 @@
+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';
+
+const ENTITY_COUNT = 10_000;
+const SAMPLE_COUNT = 101;
+const PERF_TEST_TIMEOUT_MS = 600_000;
+
+function buildWorld(inherited: boolean, withHierarchy: boolean): World {
+  const world = new World();
+  const meshHandle = world.internSharedRef('MeshAsset', createPrimitiveMesh('cube').unwrap());
+  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: meshHandle } },
+        { 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);
+      // 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,
+  );
+});

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

@@ -0,0 +1,57 @@
+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 });
+      },
+      prepare: () => ok(undefined),
+      contribute: () => ok(undefined),
+    };
+    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 });
+      },
+      prepare: () => ok(undefined),
+      contribute: () => ok(undefined),
+    };
+    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,37 @@
+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 });
+      },
+      prepare: () => ok(undefined),
+      contribute: () => ok(undefined),
+    };
+    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,50 @@
+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';
+
+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: 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,54 @@
+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';
+
+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');
+  });
+});

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

@@ -0,0 +1,191 @@
+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 { describe, expect, it } from 'vitest';
+import { resolveTilesetRuntime } from '../tilemap/resolve-tileset-runtime';
+
+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 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: MeshRenderer, data: {} },
+      { component: Visibility, data: { state: VisibilityStateValue.hidden } },
+    )
+    .unwrap();
+}
+
+function skinnedMesh(world: World): EntityHandle {
+  const meshHandle = primitiveMesh(world, 'cube');
+  return world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: meshHandle } },
+      { component: MeshRenderer, data: {} },
+      { component: Skin, data: { 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: 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 {
+  const meshHandle = primitiveMesh(world, 'cube');
+  return world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: meshHandle } },
+      { component: MeshRenderer, data: {} },
+      { component: Instances, data: { transforms: IDENTITY } },
+      { component: Visibility, data: { state: VisibilityStateValue.hidden } },
+    )
+    .unwrap();
+}
+
+function explicitInstances(world: World): EntityHandle {
+  const meshHandle = primitiveMesh(world, 'cube');
+  return world
+    .spawn(
+      { component: Transform, data: {} },
+      { component: MeshFilter, data: { assetHandle: meshHandle } },
+      { 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 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 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' } });
+  });
+});