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

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

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest';
+
+type ProducerAudit = {
+  readonly producer: string;
+  readonly owner: 'built-in' | 'vfx-render';
+  readonly visible: string;
+  readonly hidden: string;
+  readonly restored: string;
+  readonly shadow: 'required' | 'N/A: baseline has no shadow contribution';
+};
+
+const PRODUCER_MATRIX: readonly ProducerAudit[] = [
+  {
+    producer: 'static-mesh',
+    owner: 'built-in',
+    visible: 'main dispatch exists',
+    hidden: 'main and shadow dispatch are empty',
+    restored: 'the same entity dispatches again',
+    shadow: 'required',
+  },
+  {
+    producer: 'skinned-mesh',
+    owner: 'built-in',
+    visible: 'main dispatch exists',
+    hidden: 'main and shadow dispatch are empty',
+    restored: 'the same entity dispatches again',
+    shadow: 'required',
+  },
+  {
+    producer: 'auto-fold-instances',
+    owner: 'built-in',
+    visible: 'visible members remain in the batch',
+    hidden: 'hidden members leave the batch',
+    restored: 'the same members return',
+    shadow: 'required',
+  },
+  {
+    producer: 'explicit-instances',
+    owner: 'built-in',
+    visible: 'the owner dispatches',
+    hidden: 'the owner dispatch is empty',
+    restored: 'the owner dispatches again',
+    shadow: 'required',
+  },
+  {
+    producer: 'sprite',
+    owner: 'built-in',
+    visible: 'main dispatch exists',
+    hidden: 'main and shadow dispatch are empty',
+    restored: 'the same entity dispatches again',
+    shadow: 'required',
+  },
+  {
+    producer: 'tilemap',
+    owner: 'built-in',
+    visible: 'derived render entities dispatch',
+    hidden: 'derived render entities dispatch nothing',
+    restored: 'derived render entities dispatch again',
+    shadow: 'required',
+  },
+  {
+    producer: 'vfx-particles',
+    owner: 'vfx-render',
+    visible: 'main-color contribution exists',
+    hidden: 'main-color contribution is empty',
+    restored: 'the same player contributes again',
+    shadow: 'N/A: baseline has no shadow contribution',
+  },
+];
+
+describe('visibility producer matrix audit', () => {
+  it('contains every producer and three explicit state criteria', () => {
+    expect(PRODUCER_MATRIX.map(({ producer }) => producer)).toEqual([
+      'static-mesh',
+      'skinned-mesh',
+      'auto-fold-instances',
+      'explicit-instances',
+      'sprite',
+      'tilemap',
+      'vfx-particles',
+    ]);
+    for (const row of PRODUCER_MATRIX) {
+      expect(row.visible).not.toBe('');
+      expect(row.hidden).not.toBe('');
+      expect(row.restored).not.toBe('');
+    }
+  });
+
+  it('requires real shadow evidence only from producers with a shadow path', () => {
+    const builtIn = PRODUCER_MATRIX.filter((row) => row.owner === 'built-in');
+    expect(builtIn.every((row) => row.shadow === 'required')).toBe(true);
+    expect(PRODUCER_MATRIX.find((row) => row.producer === 'vfx-particles')?.shadow).toBe(
+      'N/A: baseline has no shadow contribution',
+    );
+  });
+});

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

@@ -0,0 +1,27 @@
+import { World } from '@forgeax/engine-ecs';
+import { Visibility, type VisibilityState, VisibilityStateValue } from '@forgeax/engine-render';
+import { expectTypeOf } from 'vitest';
+
+const world = new World();
+const entity = world.spawn({ component: Visibility, data: {} }).unwrap();
+
+expectTypeOf(VisibilityStateValue.inherited).toEqualTypeOf<0>();
+expectTypeOf(VisibilityStateValue.hidden).toEqualTypeOf<1>();
+expectTypeOf(VisibilityStateValue.visible).toEqualTypeOf<2>();
+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: 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

@@ -0,0 +1,85 @@
+import { type EntityHandle, World } from '@forgeax/engine-ecs';
+import { ChildOf } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { resolveVisibility } from '../extract/visibility';
+import { Visibility, VisibilityStateValue } from '../index';
+
+function spawn(
+  world: World,
+  state: keyof typeof VisibilityStateValue,
+  parent?: EntityHandle,
+): EntityHandle {
+  const parentData = parent === undefined ? [] : [{ component: ChildOf, data: { parent } }];
+  return world
+    .spawn({ component: Visibility, data: { state: VisibilityStateValue[state] } }, ...parentData)
+    .unwrap();
+}
+
+describe('visibility resolver truth table', () => {
+  it('defaults root inherited to visible and preserves explicit states', () => {
+    const world = new World();
+    const inherited = spawn(world, 'inherited');
+    const hidden = spawn(world, 'hidden');
+    const visible = spawn(world, 'visible');
+
+    const snapshot = resolveVisibility(world);
+
+    expect(snapshot.get(inherited)).toMatchObject({
+      intent: 'inherited',
+      effective: 'visible',
+      source: 'default',
+    });
+    expect(snapshot.get(hidden)).toMatchObject({
+      intent: 'hidden',
+      effective: 'hidden',
+      source: 'self',
+    });
+    expect(snapshot.get(visible)).toMatchObject({
+      intent: 'visible',
+      effective: 'visible',
+      source: 'self',
+    });
+  });
+
+  it.each([
+    ['visible', 'inherited', 'visible'],
+    ['visible', 'hidden', 'hidden'],
+    ['visible', 'visible', 'visible'],
+    ['hidden', 'inherited', 'hidden'],
+    ['hidden', 'hidden', 'hidden'],
+    ['hidden', 'visible', 'visible'],
+  ] as const)('resolves parent %s and child %s as %s', (parentState, childState, expected) => {
+    const world = new World();
+    const parent = spawn(world, parentState);
+    const child = spawn(world, childState, parent);
+
+    const result = resolveVisibility(world);
+
+    expect(result.get(child)?.effective).toBe(expected);
+  });
+
+  it('lets explicit visible establish a new inherited baseline below a hidden ancestor', () => {
+    const world = new World();
+    const hiddenParent = spawn(world, 'hidden');
+    const visibleChild = spawn(world, 'visible', hiddenParent);
+    const inheritedGrandchild = spawn(world, 'inherited', visibleChild);
+
+    const snapshot = resolveVisibility(world);
+
+    expect(snapshot.get(hiddenParent)?.effective).toBe('hidden');
+    expect(snapshot.get(visibleChild)?.effective).toBe('visible');
+    expect(snapshot.get(inheritedGrandchild)?.effective).toBe('visible');
+    expect(snapshot.get(inheritedGrandchild)?.source).toBe('parent');
+  });
+
+  it('keeps the author intent queryable for a non-render hierarchy node', () => {
+    const world = new World();
+    const parent = world.spawn().unwrap();
+    const child = spawn(world, 'inherited', parent);
+
+    const result = resolveVisibility(world);
+
+    expect(result.get(parent)?.intent).toBeUndefined();
+    expect(result.get(child)?.effective).toBe('visible');
+  });
+});

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

package/src/__tests__/visibility-snapshot-contract.unit.test.ts

@@ -0,0 +1,60 @@
+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';
+
+describe('visibility snapshot contract', () => {
+  it('projects intent and effective state without writing a derived component', () => {
+    const world = new World();
+    const parent = world
+      .spawn({ component: Visibility, data: { state: VisibilityStateValue.hidden } })
+      .unwrap();
+    const child = world
+      .spawn(
+        { component: Visibility, data: { state: VisibilityStateValue.inherited } },
+        { component: ChildOf, data: { parent } },
+      )
+      .unwrap();
+
+    const snapshot = resolveVisibility(world);
+    const childResult = snapshot.get(child);
+
+    expect(childResult).toMatchObject({ intent: 'inherited', effective: 'hidden' });
+    expect(snapshot.diagnostics).toEqual([]);
+    expect(world.components.resolve('EffectiveVisibility')).toBeUndefined();
+  });
+
+  it('is read-only and does not retain a previous World result', () => {
+    const first = new World();
+    const firstEntity = first
+      .spawn({ component: Visibility, data: { state: VisibilityStateValue.hidden } })
+      .unwrap();
+    const firstSnapshot = resolveVisibility(first);
+    expect(firstSnapshot.get(firstEntity)?.effective).toBe('hidden');
+
+    const second = new World();
+    second.spawn().unwrap();
+    const secondEntity = second
+      .spawn({ component: Visibility, data: { state: VisibilityStateValue.visible } })
+      .unwrap();
+    const secondSnapshot = resolveVisibility(second);
+
+    expect(secondSnapshot).not.toBe(firstSnapshot);
+    expect(secondSnapshot.get(secondEntity)?.effective).toBe('visible');
+    // The first numeric handle is occupied by a non-visibility entity in the
+    // second World, so a prior World snapshot cannot leak a result into it.
+    expect(secondSnapshot.get(firstEntity)).toBeUndefined();
+  });
+
+  it('exposes diagnostics alongside entity queries for a broken parent edge', () => {
+    const world = new World();
+    const child = world
+      .spawn({ component: Visibility, data: { state: VisibilityStateValue.inherited } })
+      .unwrap();
+    const snapshot = resolveVisibility(world);
+
+    expect(snapshot.get(child)?.intent).toBe('inherited');
+    expect(snapshot.diagnostics).toBeDefined();
+  });
+});

package/src/__tests__/vocabulary.unit.test.ts

@@ -0,0 +1,21 @@
+// @perf-budget-skip: intentional public render-barrel vocabulary smoke gate.
+
+import { describe, expect, it } from 'vitest';
+
+describe('render vocabulary', () => {
+  it('exposes the core render roster from the render package', async () => {
+    const render = await import('../index');
+    expect(render.Camera).toBeDefined();
+    expect(render.MeshFilter).toBeDefined();
+    expect(render.MeshRenderer).toBeDefined();
+    expect(render.DirectionalLight).toBeDefined();
+    expect(render.PointLight).toBeDefined();
+    expect(render.SpotLight).toBeDefined();
+    expect(render.Layer).toBeDefined();
+    expect(render.SortKey).toBeDefined();
+    expect(render.Instances).toBeDefined();
+    expect(render.PostProcessParams).toBeDefined();
+    expect(render.TONEMAP_REINHARD).toBeDefined();
+    expect('tonemapToU32' in render).toBe(false);
+  }, 15_000);
+});

package/src/assembly/backend-contract.ts

@@ -0,0 +1,57 @@
+import type {
+  Result,
+  RhiCanvasContext,
+  RhiDevice,
+  RhiError,
+  RhiInstance,
+  ShaderModule,
+} from '@forgeax/engine-rhi';
+
+/** Optional host hooks for recorder and device-lifecycle capabilities. */
+export interface RhiBackendInstrumentation {
+  readonly resolveSurfaceDevice?: (device: RhiDevice) => Result<RhiDevice, RhiError>;
+  readonly onFrameBoundary?: () => void;
+  readonly onDeviceLost?: () => void;
+}
+
+/** Runtime-owned backend services injected into the render assembly. */
+export interface RhiBackendPack {
+  readonly rhi: RhiInstance & {
+    readonly acquireCanvasContext: (
+      canvas: HTMLCanvasElement | OffscreenCanvas,
+    ) => Result<RhiCanvasContext, RhiError>;
+  };
+  readonly createShaderModule?: (
+    device: RhiDevice,
+    desc: { code: string; label?: string | undefined },
+  ) => Promise<Result<ShaderModule, RhiError>>;
+  readonly translateErrorEventToRhiError?: (event: unknown) => {
+    readonly ok: false;
+    readonly error: RhiError;
+  };
+  /** @internal */
+  readonly _internal_getRawDevice?: (device: RhiDevice) => unknown | undefined;
+  /** Optional lifecycle hooks owned by the host capability being injected. */
+  readonly instrumentation?: RhiBackendInstrumentation;
+}
+
+export interface EngineEnvironmentErrorDetail {
+  readonly webgpuError?: RhiError | Error | undefined;
+  readonly wgpuError?: RhiError | Error | undefined;
+}
+
+export class EngineEnvironmentError extends Error {
+  readonly reason: string;
+  readonly webgpuError?: RhiError | Error | undefined;
+  readonly wgpuError?: RhiError | Error | undefined;
+  readonly detail: EngineEnvironmentErrorDetail;
+
+  constructor(reason: string, detail: EngineEnvironmentErrorDetail = {}) {
+    super(`forgeax-engine: no usable backend (${reason})`);
+    this.name = 'EngineEnvironmentError';
+    this.reason = reason;
+    this.webgpuError = detail.webgpuError;
+    this.wgpuError = detail.wgpuError;
+    this.detail = detail;
+  }
+}