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

package/src/__tests__/pick-errors.test-d.ts

@@ -0,0 +1,66 @@
+// pick-errors.test-d.ts — PickError code-owner and closed-union declaration guard.
+//
+// The guard proves the package barrel keeps the public PickErrorCode projection
+// equal to the PickError.code owner, rejects an invalid literal, and remains
+// exhaustively switchable without a `default` arm. Adding a member later without
+// extending the switch breaks the declaration typecheck.
+//
+// Both closed unions the picking barrel exports are covered:
+//   - PickErrorCode  — single member ('camera-component-missing'), thrown by pick().
+//   - PickTileError  — two-member discriminated union (code), returned by pickTile().
+//
+// Charter P3 (tension): closed unions must retain zero-loss exhaustive-switch
+// capability across the package boundary — this file is the compile-time proof.
+
+// (b) external-consumer import path: the type resolves from the package barrel.
+import type { PickError, PickErrorCode, PickTileError } from '@forgeax/engine-picking';
+import { expectTypeOf, test } from 'vitest';
+
+function assertNever(_x: never): never {
+  throw new Error('exhaustive');
+}
+
+// PickErrorCode exhaustive switch, no default — assertNever traps a future
+// member that is added without extending this switch.
+function describePickErrorCode(code: PickErrorCode): string {
+  switch (code) {
+    case 'camera-component-missing':
+      return 'camera missing';
+    default:
+      return assertNever(code);
+  }
+}
+
+// (c) PickTileError exhaustive switch over the discriminant, no default.
+function describePickTileError(err: PickTileError): string {
+  switch (err.code) {
+    case 'tilemap-not-found':
+      return 'tilemap not found';
+    case 'tilemap-component-missing':
+      return 'tilemap component missing';
+    default:
+      return assertNever(err);
+  }
+}
+
+test('PickErrorCode derives the exact closed surface from PickError', () => {
+  expectTypeOf<PickErrorCode>().toEqualTypeOf<PickError['code']>();
+  expectTypeOf<PickErrorCode>().toEqualTypeOf<'camera-component-missing'>();
+
+  const acceptPickErrorCode = (code: PickErrorCode): void => {
+    void code;
+  };
+  acceptPickErrorCode('camera-component-missing');
+  // @ts-expect-error invalid codes must not be accepted.
+  acceptPickErrorCode('not-a-pick-error');
+
+  // Compile-time exhaustiveness (run-time noop).
+  void describePickErrorCode;
+});
+
+test('PickTileError is the closed two-member discriminated union', () => {
+  expectTypeOf<PickTileError['code']>().toEqualTypeOf<
+    'tilemap-not-found' | 'tilemap-component-missing'
+  >();
+  void describePickTileError;
+});

package/src/__tests__/pick-errors.test.ts

@@ -0,0 +1,71 @@
+// pick-errors.test.ts — PickErrorCode closed union + PickError structured surface.
+//
+// Extracted from packages/runtime/src/__tests__/errors.unit.test.ts (the
+// "from pick-errors.test.ts" block) in feat-20260705 M2 / w25 when the pick
+// cluster moved to @forgeax/engine-picking. Runtime can no longer import the
+// picking package (AC-203: no runtime -> picking edge), so these unit tests
+// live alongside the code they exercise.
+
+import { describe, expect, it } from 'vitest';
+import { PickError, type PickErrorCode } from '../pick-errors';
+
+describe('pick-errors', () => {
+  const KEBAB_REGEX = /^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)*$/;
+
+  describe('w8 — PickErrorCode closed union (AC-13)', () => {
+    it('camera-component-missing is a valid PickErrorCode literal', () => {
+      const code: PickErrorCode = 'camera-component-missing';
+      expect(code).toBe('camera-component-missing');
+    });
+
+    it('camera-component-missing is valid kebab-case', () => {
+      const code: PickErrorCode = 'camera-component-missing';
+      expect(code).toMatch(KEBAB_REGEX);
+    });
+
+    it('exhaustive switch over PickErrorCode compiles without default', () => {
+      function exhaustive(code: PickErrorCode): string {
+        switch (code) {
+          case 'camera-component-missing':
+            return 'camera missing';
+        }
+      }
+      expect(exhaustive('camera-component-missing')).toBe('camera missing');
+    });
+  });
+
+  describe('w8 — PickError structured 3-field surface (AC-11)', () => {
+    it('PickError has .code === camera-component-missing', () => {
+      const e = new PickError(7);
+      expect(e.code).toBe('camera-component-missing');
+    });
+
+    it('PickError .expected is a non-empty string', () => {
+      const e = new PickError(7);
+      expect(typeof e.expected).toBe('string');
+      expect(e.expected.length).toBeGreaterThan(0);
+    });
+
+    it('PickError .hint contains a world.set recovery directive', () => {
+      const e = new PickError(7);
+      expect(e.hint.length).toBeGreaterThan(0);
+      expect(e.hint).toContain('world.set');
+    });
+
+    it('PickError super message (Error.message) is non-empty', () => {
+      const e = new PickError(7);
+      expect(e.message.length).toBeGreaterThan(0);
+    });
+
+    it('PickError is an instanceof Error and carries .name', () => {
+      const e = new PickError(7);
+      expect(e).toBeInstanceOf(Error);
+      expect(e.name).toBe('PickError');
+    });
+
+    it('PickError .detail records the offending camera entity', () => {
+      const e = new PickError(42);
+      expect(e.detail).toEqual({ cameraEntity: 42 });
+    });
+  });
+});

package/src/__tests__/pick-tile.test.ts

@@ -0,0 +1,239 @@
+// pick-tile.test - pickTile cell-level query (worldX/Y -> tileId)
+// (feat-20260608 M0 baseline rebuild).
+//
+// Anchors: plan-tasks m0-t7 / m0-t8; plan-strategy §D-5 / §M0 targetFiles
+// (pickTile); feat-20260604 baseline; charter P3 explicit failure.
+
+import { World } from '@forgeax/engine-ecs';
+import { TileLayer, Tilemap } from '@forgeax/engine-render/authoring';
+import { ChildOf, propagateTransforms, Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { pickTile } from '../pick-tile';
+
+function makeFixture(opts: {
+  cols: number;
+  rows: number;
+  layers: ReadonlyArray<{ layerOrder: number; tiles: readonly number[] }>;
+}) {
+  const world = new World();
+  const tilemap = world
+    .spawn(
+      { component: Tilemap, data: { cols: opts.cols, rows: opts.rows, tileset: 'test/tileset' } },
+      { component: Transform, data: {} },
+    )
+    .unwrap();
+  const layerEntities = opts.layers.map((spec) => {
+    const tilesArr = new Uint32Array(opts.cols * opts.rows);
+    for (let i = 0; i < spec.tiles.length; i++) tilesArr[i] = spec.tiles[i] ?? 0;
+    return world
+      .spawn(
+        { component: TileLayer, data: { tiles: tilesArr, layerOrder: spec.layerOrder } },
+        { component: ChildOf, data: { parent: tilemap } },
+      )
+      .unwrap();
+  });
+  return { world, tilemap, layerEntities };
+}
+
+describe('pickTile (M0 baseline)', () => {
+  it('hits the cell containing worldX/Y on a single-layer tilemap', () => {
+    const { world, tilemap } = makeFixture({
+      cols: 4,
+      rows: 4,
+      layers: [{ layerOrder: 0, tiles: [0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0] }],
+    });
+    const r = pickTile(world, tilemap, 1.5, 1.5);
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.value).not.toBeNull();
+      if (r.value !== null) {
+        expect(r.value.cellX).toBe(1);
+        expect(r.value.cellY).toBe(1);
+        expect(r.value.tileId).toBe(1);
+      }
+    }
+  });
+
+  it('returns Result.ok(null) when worldX/Y is out of bounds', () => {
+    const { world, tilemap } = makeFixture({
+      cols: 2,
+      rows: 2,
+      layers: [{ layerOrder: 0, tiles: [1, 0, 0, 0] }],
+    });
+    const r = pickTile(world, tilemap, 100, 100);
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.value).toBeNull();
+  });
+
+  it('returns Result.ok(null) when no non-zero tile occupies the cell', () => {
+    const { world, tilemap } = makeFixture({
+      cols: 2,
+      rows: 2,
+      layers: [{ layerOrder: 0, tiles: [1, 0, 0, 0] }],
+    });
+    const r = pickTile(world, tilemap, 1.5, 1.5);
+    expect(r.ok).toBe(true);
+    if (r.ok) expect(r.value).toBeNull();
+  });
+
+  it('walks layers in layerOrder-descending order (high layer wins)', () => {
+    // layer 0: cell (0,0) has tile 1
+    // layer 5: cell (0,0) has tile 7
+    const { world, tilemap } = makeFixture({
+      cols: 2,
+      rows: 2,
+      layers: [
+        { layerOrder: 0, tiles: [1, 0, 0, 0] },
+        { layerOrder: 5, tiles: [7, 0, 0, 0] },
+      ],
+    });
+    const r = pickTile(world, tilemap, 0.5, 0.5);
+    expect(r.ok).toBe(true);
+    if (r.ok && r.value !== null) {
+      expect(r.value.tileId).toBe(7);
+    } else {
+      expect.fail('expected a hit');
+    }
+  });
+
+  it('uses the propagated inverse affine transform for translated rotated scaled maps', () => {
+    const world = new World();
+    const tilemap = world
+      .spawn(
+        {
+          component: Tilemap,
+          data: { cols: 3, rows: 2, tileSize: [1, 1], tileset: 'test/tileset' },
+        },
+        {
+          component: Transform,
+          data: {
+            pos: [10, 20, 0],
+            // +90 degrees around Z: local cell (1.5, 0.5) maps to world (8.5, 23).
+            quat: [0, 0, Math.SQRT1_2, Math.SQRT1_2],
+            scale: [2, 3, 1],
+          },
+        },
+      )
+      .unwrap();
+    const lowerLayer = world
+      .spawn(
+        {
+          component: TileLayer,
+          data: { tiles: new Uint32Array([0, 3, 0, 0, 0, 0]), layerOrder: 0 },
+        },
+        { component: ChildOf, data: { parent: tilemap } },
+      )
+      .unwrap();
+    const upperLayer = world
+      .spawn(
+        {
+          component: TileLayer,
+          data: { tiles: new Uint32Array([0, 9, 0, 0, 0, 0]), layerOrder: 7 },
+        },
+        { component: ChildOf, data: { parent: tilemap } },
+      )
+      .unwrap();
+
+    propagateTransforms(world).unwrap();
+    const r = pickTile(world, tilemap, 8.5, 23);
+
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      expect(r.value).toEqual({ layerEntity: upperLayer, cellX: 1, cellY: 0, tileId: 9 });
+    }
+    expect(lowerLayer).not.toBe(upperLayer);
+  });
+
+  it('falls through to lower layer when higher layer has 0 at the cell', () => {
+    const { world, tilemap } = makeFixture({
+      cols: 2,
+      rows: 2,
+      layers: [
+        { layerOrder: 0, tiles: [3, 0, 0, 0] },
+        { layerOrder: 5, tiles: [0, 0, 0, 0] },
+      ],
+    });
+    const r = pickTile(world, tilemap, 0.5, 0.5);
+    expect(r.ok).toBe(true);
+    if (r.ok && r.value !== null) {
+      expect(r.value.tileId).toBe(3);
+    } else {
+      expect.fail('expected a hit');
+    }
+  });
+
+  it('returns tilemap-not-found for a dead handle', () => {
+    const { world } = makeFixture({
+      cols: 1,
+      rows: 1,
+      layers: [{ layerOrder: 0, tiles: [1] }],
+    });
+    const dead = world.spawn({ component: Transform, data: {} }).unwrap();
+    world.despawn(dead).unwrap();
+    const r = pickTile(world, dead, 1, 1);
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.error.code).toBe('tilemap-not-found');
+  });
+
+  it('returns Result.err when the entity does not carry Tilemap', () => {
+    const { world } = makeFixture({
+      cols: 1,
+      rows: 1,
+      layers: [{ layerOrder: 0, tiles: [1] }],
+    });
+    const e = world.spawn({ component: Transform, data: {} }).unwrap();
+    const r = pickTile(world, e, 1, 1);
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.error.code).toBe('tilemap-component-missing');
+    }
+  });
+
+  it('repairs a missing Tilemap on the same World and retries successfully', () => {
+    const world = new World();
+    const entity = world.spawn({ component: Transform, data: {} }).unwrap();
+
+    const missing = pickTile(world, entity, 0.5, 0.5);
+    expect(missing.ok).toBe(false);
+    if (!missing.ok) expect(missing.error.code).toBe('tilemap-component-missing');
+
+    world
+      .addComponent(entity, {
+        component: Tilemap,
+        data: { cols: 1, rows: 1, tileSize: [1, 1], tileset: 'test/tileset' },
+      })
+      .unwrap();
+    const layer = world
+      .spawn(
+        { component: TileLayer, data: { tiles: new Uint32Array([11]), layerOrder: 0 } },
+        { component: ChildOf, data: { parent: entity } },
+      )
+      .unwrap();
+
+    const repaired = pickTile(world, entity, 0.5, 0.5);
+    expect(repaired.ok).toBe(true);
+    if (repaired.ok) {
+      expect(repaired.value).toEqual({ layerEntity: layer, cellX: 0, cellY: 0, tileId: 11 });
+    }
+  });
+
+  it('keeps the documented mat4 singular fallback deterministic', () => {
+    const { world, tilemap } = makeFixture({
+      cols: 1,
+      rows: 1,
+      layers: [{ layerOrder: 0, tiles: [5] }],
+    });
+    world.set(tilemap, Transform, { pos: [7, 9, 0], scale: [0, 2, 1] }).unwrap();
+    propagateTransforms(world).unwrap();
+
+    // mat4.invert defines singular input as identity; pickTile keeps that
+    // central math fallback instead of inventing another error arm.
+    const first = pickTile(world, tilemap, 0.5, 0.5);
+    const second = pickTile(world, tilemap, 0.5, 0.5);
+    expect(first).toEqual(second);
+    expect(first.ok).toBe(true);
+    if (first.ok) {
+      expect(first.value).toMatchObject({ cellX: 0, cellY: 0, tileId: 5 });
+    }
+  });
+});