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

package/src/components/__tests__/points-lines-admission.unit.test.ts

@@ -0,0 +1,219 @@
+import type { MeshAsset, PrimitiveTopology } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  PointsLinesBudgetExceededError,
+  PointsLinesInvalidStyleError,
+  PointsLinesMaterialUnsupportedError,
+  PointsLinesPrepareFailedError,
+  PointsLinesStyleUnsupportedError,
+  PointsLinesTopologyMismatchError,
+} from '../../errors/render';
+import { Materials } from '../../materials';
+import { admitPointsLines, type PointsLinesAdmissionInput } from '../../points-lines/admission';
+
+const unlitMaterial = Materials.unlit([1, 0.5, 0.25, 1], { castShadow: false });
+
+function mesh(topology: PrimitiveTopology, count = 4, indexed = false): MeshAsset {
+  const vertices = new Float32Array(count * 3);
+  return {
+    kind: 'mesh',
+    vertices,
+    ...(indexed ? { indices: new Uint16Array(count) } : {}),
+    attributes: { position: vertices },
+    aabb: new Float32Array([-1, -1, -1, 1, 1, 1]),
+    submeshes: [
+      {
+        indexOffset: 0,
+        indexCount: indexed ? count : 0,
+        vertexCount: count,
+        topology,
+        materialSlot: 0,
+      },
+    ],
+    materialSlots: [{ slotName: 'default' }],
+  };
+}
+
+function pointsInput(
+  overrides: Partial<PointsLinesAdmissionInput> = {},
+): PointsLinesAdmissionInput {
+  return {
+    entity: 7,
+    points: { sizePx: 4, shape: 0 },
+    mesh: mesh('point-list', 3),
+    material: unlitMaterial,
+    ...overrides,
+  };
+}
+
+function linesInput(overrides: Partial<PointsLinesAdmissionInput> = {}): PointsLinesAdmissionInput {
+  return {
+    entity: 8,
+    lines: { widthPx: 1 },
+    mesh: mesh('line-list', 4),
+    material: unlitMaterial,
+    ...overrides,
+  };
+}
+
+function expectRefusal(
+  result: ReturnType<typeof admitPointsLines>,
+  code: string,
+  detail: Record<string, unknown>,
+): void {
+  expect(result.ok).toBe(false);
+  if (result.ok) return;
+  if (!('detail' in result.error)) throw new Error('expected a detailed Points/Lines refusal');
+  expect(result.error.code).toBe(code);
+  expect(result.error.expected).toEqual(expect.any(String));
+  expect(result.error.hint).toEqual(expect.any(String));
+  expect(result.error.detail).toMatchObject(detail);
+}
+
+describe('Points and Lines admission', () => {
+  it('accepts indexed and non-indexed point and line-list geometry', () => {
+    const indexedPoints = admitPointsLines(pointsInput({ mesh: mesh('point-list', 3, true) }));
+    const nonIndexedLines = admitPointsLines(linesInput());
+
+    expect(indexedPoints.ok).toBe(true);
+    expect(nonIndexedLines.ok).toBe(true);
+    if (indexedPoints.ok) expect(indexedPoints.value.pointCount).toBe(3);
+    if (nonIndexedLines.ok) expect(nonIndexedLines.value.segmentCount).toBe(2);
+  });
+
+  it('rejects component conflicts and invalid numeric styles before topology', () => {
+    const conflict = admitPointsLines(pointsInput({ lines: { widthPx: 1 } }));
+    const invalidSize = admitPointsLines(pointsInput({ points: { sizePx: Number.NaN, shape: 0 } }));
+    const invalidWidth = admitPointsLines(linesInput({ lines: { widthPx: 0 } }));
+
+    expectRefusal(conflict, 'points-lines-invalid-style', {
+      entity: 7,
+      component: 'Points/Lines',
+      field: 'components',
+    });
+    expectRefusal(invalidSize, 'points-lines-invalid-style', {
+      entity: 7,
+      component: 'Points',
+      field: 'sizePx',
+      value: Number.NaN,
+    });
+    expectRefusal(invalidWidth, 'points-lines-invalid-style', {
+      entity: 8,
+      component: 'Lines',
+      field: 'widthPx',
+      value: 0,
+    });
+  });
+
+  it('rejects unsupported topologies, odd line tails, and mixed candidates atomically', () => {
+    const strip = admitPointsLines(linesInput({ mesh: mesh('line-strip', 4) }));
+    const triangles = admitPointsLines(pointsInput({ mesh: mesh('triangle-list', 3) }));
+    const odd = admitPointsLines(linesInput({ mesh: mesh('line-list', 3) }));
+    const baseMixedMesh = mesh('line-list', 2);
+    const mixedMesh: MeshAsset = {
+      ...baseMixedMesh,
+      submeshes: [
+        ...baseMixedMesh.submeshes,
+        {
+          indexOffset: 0,
+          indexCount: 0,
+          vertexCount: 3,
+          topology: 'triangle-list',
+          materialSlot: 0,
+        },
+      ],
+    };
+    const mixed = admitPointsLines(linesInput({ mesh: mixedMesh }));
+
+    expectRefusal(strip, 'points-lines-style-unsupported', {
+      lane: 'admission',
+      field: 'topology',
+      member: 'line-strip',
+    });
+    expectRefusal(triangles, 'points-lines-topology-mismatch', {
+      entity: 7,
+      expected: 'point-list',
+      actual: 'triangle-list',
+      submesh: 0,
+    });
+    expectRefusal(odd, 'points-lines-topology-mismatch', {
+      entity: 8,
+      expected: 'line-list pairs',
+      actual: 'line-list odd tail',
+      submesh: 0,
+    });
+    expectRefusal(mixed, 'points-lines-topology-mismatch', {
+      entity: 8,
+      submesh: 1,
+    });
+  });
+
+  it('rejects non-unlit materials and explicit resource budgets', () => {
+    const lit = Materials.standard({ baseColor: [1, 1, 1, 1] });
+    const material = admitPointsLines(linesInput({ material: lit }));
+    const budget = admitPointsLines(pointsInput({ limits: { maxPoints: 2 } }));
+
+    expectRefusal(material, 'points-lines-material-unsupported', {
+      entity: 8,
+      pass: 'deferred',
+      reason: expect.any(String),
+    });
+    expectRefusal(budget, 'points-lines-budget-exceeded', {
+      lane: 'admission',
+      requested: 3,
+      limit: 2,
+      unit: 'points',
+    });
+  });
+
+  it('keeps every closed refusal detail constructible and code-correlated', () => {
+    const errors = [
+      new PointsLinesInvalidStyleError({
+        entity: 1,
+        component: 'Points',
+        field: 'sizePx',
+        value: -1,
+        expected: 'finite sizePx > 0',
+      }),
+      new PointsLinesTopologyMismatchError({
+        entity: 1,
+        submesh: 0,
+        expected: 'point-list',
+        actual: 'triangle-list',
+      }),
+      new PointsLinesStyleUnsupportedError({
+        lane: 'admission',
+        field: 'topology',
+        member: 'line-strip',
+        supported: ['line-list'],
+      }),
+      new PointsLinesMaterialUnsupportedError({
+        entity: 1,
+        material: 'mat-1',
+        pass: 'forward',
+        module: 'forgeax_material::standard',
+        reason: 'surface lighting is not supported',
+      }),
+      new PointsLinesBudgetExceededError({
+        lane: 'admission',
+        requested: 5,
+        limit: 4,
+        unit: 'points',
+      }),
+      new PointsLinesPrepareFailedError({
+        owner: 'points-lines',
+        generation: 2,
+        stage: 'prepare',
+        cause: 'candidate validation failed',
+        lastKnownGood: false,
+      }),
+    ];
+
+    for (const error of errors) {
+      expect(error.code).toMatch(/^points-lines-/);
+      expect(error.expected).toEqual(expect.any(String));
+      expect(error.hint).toEqual(expect.any(String));
+      expect(error.detail).toBeDefined();
+    }
+  });
+});

package/src/components/__tests__/points-lines-schema.unit.test.ts

@@ -0,0 +1,56 @@
+import { World } from '@forgeax/engine-ecs';
+import type { PointShape } from '@forgeax/engine-render';
+import { Lines, PointShapeValue, Points, pointShapeFromU32 } from '@forgeax/engine-render';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+describe('Points and Lines public schema', () => {
+  it('creates both components through the public import and inserts them in World', () => {
+    const world = new World();
+    const pointEntity = world
+      .spawn({
+        component: Points,
+        data: { sizePx: 8, shape: PointShapeValue.circle },
+      })
+      .unwrap();
+    const lineEntity = world.spawn({ component: Lines, data: { widthPx: 4 } }).unwrap();
+
+    expect(world.get(pointEntity, Points).unwrap()).toMatchObject({
+      sizePx: 8,
+      shape: PointShapeValue.circle,
+    });
+    expect(world.get(lineEntity, Lines).unwrap()).toMatchObject({ widthPx: 4 });
+  });
+
+  it('keeps the frozen defaults and closed point shape decoder', () => {
+    const world = new World();
+    const pointEntity = world.spawn({ component: Points, data: {} }).unwrap();
+    const lineEntity = world.spawn({ component: Lines, data: {} }).unwrap();
+
+    expect(world.get(pointEntity, Points).unwrap()).toMatchObject({
+      sizePx: 4,
+      shape: PointShapeValue.square,
+    });
+    expect(world.get(lineEntity, Lines).unwrap().widthPx).toBe(1);
+    expect(Points.fields).toEqual({
+      sizePx: expect.objectContaining({ type: 'f32', default: 4 }),
+      shape: expect.objectContaining({
+        type: 'enum',
+        default: PointShapeValue.square,
+        labels: PointShapeValue,
+      }),
+    });
+    expect(Lines.fields).toEqual({
+      widthPx: expect.objectContaining({ type: 'f32', default: 1 }),
+    });
+    expect(pointShapeFromU32(PointShapeValue.square)).toBe('square');
+    expect(pointShapeFromU32(PointShapeValue.circle)).toBe('circle');
+    expect(pointShapeFromU32(99)).toBeUndefined();
+  });
+
+  it('exposes only the three first-release style fields', () => {
+    type PublicPointShape = PointShape;
+    expectTypeOf<PublicPointShape>().toEqualTypeOf<'square' | 'circle'>();
+    expectTypeOf<keyof typeof Points.fields>().toEqualTypeOf<'sizePx' | 'shape'>();
+    expectTypeOf<keyof typeof Lines.fields>().toEqualTypeOf<'widthPx'>();
+  });
+});

package/src/components/__tests__/schema-contract.unit.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from 'vitest';
+import { Camera, DirectionalLight, MeshFilter } from '../index';
+
+describe('canonical render schema owners', () => {
+  it('keeps mesh, light, and camera facts on their component owners', () => {
+    expect(MeshFilter.fields.assetHandle.type).toBe('shared<MeshAsset>');
+    expect(DirectionalLight.fields.direction.type).toBe('array<f32, 3>');
+    expect(Camera.fields.projection.default).toBe(0);
+  });
+});

package/src/components/__tests__/schema-parity.unit.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import {
+  Camera,
+  DirectionalLight,
+  MeshFilter,
+  MeshRenderer,
+  orthographic,
+  perspective,
+} from '../index';
+
+describe('render schema parity', () => {
+  it('keeps branded mesh and merged light fields in the canonical schema', () => {
+    expect(MeshFilter.fields.assetHandle.type).toBe('shared<MeshAsset>');
+    expect(DirectionalLight.fields.direction.type).toBe('array<f32, 3>');
+    expect(DirectionalLight.fields.castShadow.default).toBe(true);
+    expect(MeshRenderer.fields.materials.type).toBe('array<shared<MaterialAsset>>');
+  });
+
+  it('exposes both camera projection variants and helpers', () => {
+    expect(Camera.fields.projection.default).toBe(0);
+    expect(Camera.fields.left.default).toBe(-1);
+    expect(perspective({ fov: 1, aspect: 2 }).projection).toBe(0);
+    expect(orthographic({ left: -2, right: 2, bottom: -1, top: 1 }).projection).toBe(1);
+  });
+});

package/src/components/__tests__/visibility-schema.unit.test.ts

@@ -0,0 +1,35 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { Visibility, VisibilityStateValue, visibilityStateFromU32 } from '../visibility';
+
+describe('M1 Visibility schema', () => {
+  it('uses inherited as the default and decodes the closed three-state set', () => {
+    const world = new World();
+    const entity = world.spawn({ component: Visibility, data: {} }).unwrap();
+
+    expect(world.get(entity, Visibility).unwrap().state).toBe(VisibilityStateValue.inherited);
+    expect(Visibility.fields.state.labels).toEqual(VisibilityStateValue);
+    expect(Object.isFrozen(Visibility.fields.state.labels)).toBe(true);
+    expect(JSON.parse(JSON.stringify(Visibility.fields.state.labels))).toEqual(
+      VisibilityStateValue,
+    );
+    expect(Visibility.fields.state.default).toBe(VisibilityStateValue.inherited);
+    expect(visibilityStateFromU32(VisibilityStateValue.inherited)).toBe('inherited');
+    expect(visibilityStateFromU32(VisibilityStateValue.hidden)).toBe('hidden');
+    expect(visibilityStateFromU32(VisibilityStateValue.visible)).toBe('visible');
+    expect(visibilityStateFromU32(3)).toBeUndefined();
+  });
+
+  it('supports real World.set and Query consumption without a cast', () => {
+    const world = new World();
+    const entity = world.spawn({ component: Visibility, data: {} }).unwrap();
+
+    expect(world.set(entity, Visibility, { state: VisibilityStateValue.hidden }).ok).toBe(true);
+
+    const query = world.query({ read: [Visibility] }).unwrap();
+    let stateFromQuery: number | undefined;
+    for (const row of query) stateFromQuery = row.get(Visibility).state;
+
+    expect(stateFromQuery).toBe(VisibilityStateValue.hidden);
+  });
+});