@forgeax/engine-picking 0.1.33 → 0.1.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-picking",
-  "version": "0.1.33",
+  "version": "0.1.34",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -22,17 +22,17 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-assets-runtime": "0.1.33",
-    "@forgeax/engine-ecs": "0.1.33",
-    "@forgeax/engine-math": "0.1.33",
-    "@forgeax/engine-render": "0.1.33",
-    "@forgeax/engine-runtime": "0.1.33",
-    "@forgeax/engine-scene": "0.1.33",
-    "@forgeax/engine-types": "0.1.33"
+    "@forgeax/engine-assets-runtime": "0.1.34",
+    "@forgeax/engine-ecs": "0.1.34",
+    "@forgeax/engine-math": "0.1.34",
+    "@forgeax/engine-render": "0.1.34",
+    "@forgeax/engine-runtime": "0.1.34",
+    "@forgeax/engine-scene": "0.1.34",
+    "@forgeax/engine-types": "0.1.34"
   },
   "devDependencies": {
-    "@forgeax/engine-pack": "0.1.33",
-    "@forgeax/engine-shader": "0.1.33"
+    "@forgeax/engine-pack": "0.1.34",
+    "@forgeax/engine-shader": "0.1.34"
   },
   "forgeax": {
     "metrics": {

package/src/__tests__/display-picking.unit.test.ts

@@ -0,0 +1,163 @@
+import type { World } from '@forgeax/engine-ecs';
+import { mat4 } from '@forgeax/engine-math';
+import {
+  attachBarrelDistortionCameraFrame,
+  createBarrelDistortionMapping,
+} from '@forgeax/engine-render';
+import { describe, expect, it } from 'vitest';
+import {
+  computeDisplayScreenRay,
+  displayToScenePixel,
+  pickDisplay,
+  pickVertexDisplay,
+  pickVertexOnEntityDisplay,
+} from '../display-picking';
+
+describe('display picking frame authority', () => {
+  it('uses the accepted identity frame after an unrendered camera mutation', () => {
+    const mapping = attachBarrelDistortionCameraFrame(
+      createBarrelDistortionMapping(640, 360, undefined).unwrap(),
+      {
+        projection: 'perspective',
+        far: 100,
+        viewMatrix: mat4.create(),
+        projectionMatrix: mat4.create(),
+      },
+    );
+    // A live World fallback would throw here. The submitted camera matrices
+    // remain the sole source for the displayed frame after a later mutation.
+    const mutatedWorld = {
+      get: () => {
+        throw new Error('unrendered camera state must not be read');
+      },
+    } as unknown as World;
+    const ray = computeDisplayScreenRay(mutatedWorld, 17 as never, 320, 180, mapping, 640, 360);
+    expect(ray).toBeDefined();
+  });
+
+  it('uses the submitted camera matrices for the display ray', () => {
+    const viewMatrix = mat4.create();
+    viewMatrix[12] = -0.5;
+    const projectionMatrix = mat4.create();
+    projectionMatrix[0] = 0.75;
+    const mapping = attachBarrelDistortionCameraFrame(
+      createBarrelDistortionMapping(64, 64, undefined).unwrap(),
+      {
+        projection: 'orthographic',
+        far: 100,
+        viewMatrix,
+        projectionMatrix,
+      },
+    );
+    const world = {
+      get: () => {
+        throw new Error('display picking must use the accepted mapping');
+      },
+    } as unknown as World;
+    const ray = computeDisplayScreenRay(world, 17 as never, 32, 32, mapping, 64, 64);
+    expect(ray).toMatchObject({ projectionKind: 'orthographic' });
+    expect(ray).toBeDefined();
+    if (ray === undefined) return;
+    expect(Array.from(ray.view)).toEqual(Array.from(viewMatrix));
+    expect(Array.from(ray.proj)).toEqual(Array.from(projectionMatrix));
+  });
+
+  it('rejects a display query without an accepted frame context', () => {
+    const world = {
+      get: () => {
+        throw new Error('missing frame context must not consult World');
+      },
+    } as unknown as World;
+    expect(
+      computeDisplayScreenRay(world, 17 as never, 10, 10, undefined, 640, 360),
+    ).toBeUndefined();
+  });
+
+  it('rejects a viewport that disagrees with the submitted mapping extent', () => {
+    const mapping = attachBarrelDistortionCameraFrame(
+      createBarrelDistortionMapping(640, 360, undefined).unwrap(),
+      {
+        projection: 'perspective',
+        far: 100,
+        viewMatrix: mat4.create(),
+        projectionMatrix: mat4.create(),
+      },
+    );
+    const world = {} as World;
+    expect(
+      computeDisplayScreenRay(world, 17 as never, 640, 360, mapping, 1280, 720),
+    ).toBeUndefined();
+    const out = { x: 0, y: 0 };
+    expect(displayToScenePixel(out, undefined, 10, 10)).toBe(false);
+  });
+
+  it('uses caller-normalized DPR and embedded offsets while rejecting crop misses', () => {
+    const mapping = attachBarrelDistortionCameraFrame(
+      createBarrelDistortionMapping(640, 360, undefined).unwrap(),
+      {
+        projection: 'perspective',
+        far: 100,
+        viewMatrix: mat4.create(),
+        projectionMatrix: mat4.create(),
+      },
+    );
+    const world = {} as World;
+    const embeddedOffset = { left: 37, top: 19 };
+    const devicePixelRatio = 2;
+    const cssPoint = { x: embeddedOffset.left + 160, y: embeddedOffset.top + 90 };
+    const submittedPixel = {
+      x: (cssPoint.x - embeddedOffset.left) * devicePixelRatio,
+      y: (cssPoint.y - embeddedOffset.top) * devicePixelRatio,
+    };
+
+    // Offset/DPR normalization belongs to the host display adapter. The
+    // public picking API consumes the resulting physical pixel against the
+    // accepted submitted extent.
+    expect(
+      computeDisplayScreenRay(
+        world,
+        17 as never,
+        submittedPixel.x,
+        submittedPixel.y,
+        mapping,
+        640,
+        360,
+      ),
+    ).toBeDefined();
+    expect(
+      computeDisplayScreenRay(world, 17 as never, -1, submittedPixel.y, mapping, 640, 360),
+    ).toBeUndefined();
+    expect(
+      computeDisplayScreenRay(world, 17 as never, 640, submittedPixel.y, mapping, 640, 360),
+    ).toBeDefined();
+    expect(
+      computeDisplayScreenRay(world, 17 as never, 641, submittedPixel.y, mapping, 640, 360),
+    ).toBeUndefined();
+    // A DPR-sized viewport is a different submitted extent and must fail
+    // closed instead of silently selecting a second display mapping.
+    expect(
+      computeDisplayScreenRay(
+        world,
+        17 as never,
+        submittedPixel.x,
+        submittedPixel.y,
+        mapping,
+        1280,
+        720,
+      ),
+    ).toBeUndefined();
+  });
+
+  it('fails closed for omitted display context across every display entrypoint', () => {
+    const world = {
+      get: () => {
+        throw new Error('missing frame context must not consult World');
+      },
+    } as unknown as World;
+    expect(pickDisplay(world, 17 as never, 10, 10, undefined, 640, 360)).toBeUndefined();
+    expect(pickVertexDisplay(world, 17 as never, 10, 10, undefined, 640, 360)).toBeUndefined();
+    expect(
+      pickVertexOnEntityDisplay(world, 17 as never, 10, 10, undefined, 640, 360, 18 as never),
+    ).toBeUndefined();
+  });
+});

package/src/__tests__/pick-triangle.unit.test.ts

@@ -4,7 +4,6 @@ import { AssetGuid } from '@forgeax/engine-pack/guid';
 import {
   CAMERA_PROJECTION_PERSPECTIVE,
   Camera,
-  InstanceCollectionStore,
   Instances,
   MeshFilter,
   MeshRenderer,
@@ -48,7 +47,6 @@ function registerMesh(
 function makeScene() {
   const world = new World();
   const assets = new AssetRegistry(makeMockShaderRegistry());
-  const instanceCollections = new InstanceCollectionStore();
   const material = assets.catalog(AssetGuid.format(AssetGuid.random()), {
     kind: 'material',
     passes: [
@@ -81,7 +79,7 @@ function makeScene() {
       },
     )
     .unwrap();
-  return { world, assets, materialHandle, camera, instanceCollections };
+  return { world, assets, materialHandle, camera };
 }
 
 function spawnMesh(
@@ -119,7 +117,6 @@ function spawnInstancedMesh(
     transforms[offset + 15] = 1;
     transforms[offset + 12] = translations[index] as number;
   }
-  const collection = scene.instanceCollections.create({ transforms }).unwrap();
   return scene.world
     .spawn(
       {
@@ -128,7 +125,7 @@ function spawnInstancedMesh(
       },
       { component: MeshFilter, data: { assetHandle: mesh } },
       { component: MeshRenderer, data: { materials: [scene.materialHandle] } },
-      { component: Instances, data: { collectionId: collection.collectionId } },
+      { component: Instances, data: { transforms } },
     )
     .unwrap();
 }
@@ -239,14 +236,14 @@ describe('pickTriangle', () => {
     );
     const entity = spawnInstancedMesh(scene, mesh, [5, 0]);
 
-    const result = query(scene, VP / 2, VP / 2, { instances: scene.instanceCollections });
+    const result = query(scene, VP / 2, VP / 2);
     expect(result.status).toBe('hit');
     if (result.status !== 'hit') return;
     expect(result.hit.entity).toBe(entity);
     expect(result.hit.instanceIndex).toBe(1);
   });
 
-  it('fails closed when an explicit Instances resolver is absent', () => {
+  it('fails closed when authored Instances contain an incomplete matrix', () => {
     const scene = makeScene();
     const mesh = registerMesh(
       scene.world,
@@ -254,9 +251,9 @@ describe('pickTriangle', () => {
       [-0.5, -0.5, 0, 0.5, -0.5, 0, 0, 0.5, 0],
       [0, 1, 2],
     );
-    spawnInstancedMesh(scene, mesh, [0]);
+    const entity = spawnInstancedMesh(scene, mesh, [0]);
+    scene.world.set(entity, Instances, { transforms: new Float32Array(15) }).unwrap();
 
-    expect(query(scene).status).toBe('unavailable');
     const result = query(scene);
     expect(result.status).toBe('unavailable');
     if (result.status === 'unavailable') {

package/src/__tests__/voxel-display-consumer.test-d.ts

@@ -0,0 +1,57 @@
+// Public Voxel L1/L6 consumer contract.
+//
+// Voxel owns grab/split and target succession. Engine owns the submitted
+// display mapping; this fixture keeps both routes typechecked without importing
+// a private renderer or creating a second spatial transform.
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import type { FrameReceipt } from '@forgeax/engine-render';
+import { mapSceneToDisplay } from '@forgeax/engine-render';
+import { computeDisplayScreenRay, pickDisplay, pickVertexDisplay } from '../index';
+
+declare const world: World;
+declare const camera: EntityHandle;
+declare const target: EntityHandle;
+declare const receipt: FrameReceipt;
+declare const outputWidth: number;
+declare const outputHeight: number;
+declare const pointerX: number;
+declare const pointerY: number;
+
+const mapping = receipt.barrelDistortion;
+if (mapping !== undefined) {
+  const ray = computeDisplayScreenRay(
+    world,
+    camera,
+    pointerX,
+    pointerY,
+    mapping,
+    outputWidth,
+    outputHeight,
+  );
+  const entityHit = pickDisplay(
+    world,
+    camera,
+    pointerX,
+    pointerY,
+    mapping,
+    outputWidth,
+    outputHeight,
+  );
+  const vertexHits = pickVertexDisplay(
+    world,
+    camera,
+    pointerX,
+    pointerY,
+    mapping,
+    outputWidth,
+    outputHeight,
+    { limit: 8, radius: 6 },
+  );
+  const label = { x: 0, y: 0 };
+  const labelVisible = mapSceneToDisplay(label, mapping, pointerX, pointerY);
+  void ray;
+  void entityHit;
+  void vertexHits;
+  void target;
+  void labelVisible;
+}

package/src/display-picking.ts

@@ -0,0 +1,302 @@
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import { mat4, ray, type Vec3Like, vec2 } from '@forgeax/engine-math';
+import {
+  type BarrelDistortionMapping,
+  type DisplayPoint,
+  mapDisplayToScene,
+  mapSceneToDisplay,
+} from '@forgeax/engine-render';
+import { type PickHit, pickWithScreenRay } from './pick';
+import { computeScreenRayFromMatrices, type ScreenRay } from './pick-core';
+import {
+  pickVertexOnEntityWithScreenRay,
+  pickVertexWithScreenRay,
+  type VertexHit,
+} from './pick-vertex';
+
+export interface DisplayVertexPickOptions {
+  readonly limit?: number;
+  /** Maximum distance in displayed physical pixels; omitted keeps all ray hits. */
+  readonly radius?: number;
+}
+
+/**
+ * Convert a displayed output pixel to the matching unwarped scene pixel.
+ *
+ * `undefined` is the fail-closed signal that no accepted submitted frame is
+ * available. It is not an identity mapping; callers must wait for a new
+ * submitted frame (including an explicit zero-strength mapping).
+ */
+export function displayToScenePixel(
+  out: DisplayPoint,
+  mapping: BarrelDistortionMapping | undefined,
+  displayX: number,
+  displayY: number,
+): boolean {
+  if (mapping === undefined) return false;
+  return mapDisplayToScene(out, mapping, displayX, displayY);
+}
+
+/**
+ * Display coordinates are meaningful only against the accepted submitted
+ * output extent. Keep the legacy viewport arguments as an explicit boundary
+ * check for callers migrating from unwarped picking; never let them select a
+ * second ray viewport or manufacture an identity mapping. An omitted mapping
+ * therefore rejects the query before any World or camera access.
+ */
+function submittedExtent(
+  mapping: BarrelDistortionMapping | undefined,
+  viewportWidth: number,
+  viewportHeight: number,
+): { readonly width: number; readonly height: number } | undefined {
+  if (mapping === undefined) return undefined;
+  if (
+    !Number.isFinite(mapping.width) ||
+    !Number.isFinite(mapping.height) ||
+    mapping.width <= 0 ||
+    mapping.height <= 0 ||
+    !Number.isFinite(viewportWidth) ||
+    !Number.isFinite(viewportHeight) ||
+    viewportWidth !== mapping.width ||
+    viewportHeight !== mapping.height
+  ) {
+    return undefined;
+  }
+  return { width: mapping.width, height: mapping.height };
+}
+
+/** Build a world ray from the physical pixel currently visible on screen. */
+export function computeDisplayScreenRay(
+  world: World,
+  cameraEntity: EntityHandle,
+  displayX: number,
+  displayY: number,
+  mapping: BarrelDistortionMapping | undefined,
+  viewportWidth: number,
+  viewportHeight: number,
+): ScreenRay | undefined {
+  // The signature retains the world/entity pair for the shared picking
+  // surface, but an accepted frame context is mandatory for display rays.
+  void world;
+  void cameraEntity;
+  const extent = submittedExtent(mapping, viewportWidth, viewportHeight);
+  if (
+    extent === undefined ||
+    !Number.isFinite(displayX) ||
+    !Number.isFinite(displayY) ||
+    displayX < 0 ||
+    displayX > extent.width ||
+    displayY < 0 ||
+    displayY > extent.height
+  ) {
+    return undefined;
+  }
+  const scene = { x: 0, y: 0 };
+  if (!displayToScenePixel(scene, mapping, displayX, displayY)) return undefined;
+  return computeSceneScreenRay(scene.x, scene.y, mapping);
+}
+
+function computeSceneScreenRay(
+  sceneX: number,
+  sceneY: number,
+  mapping: BarrelDistortionMapping | undefined,
+): ScreenRay | undefined {
+  if (mapping === undefined || mapping.camera === undefined) return undefined;
+  const camera = mapping.camera;
+  const submitted = mapping;
+  return computeScreenRayFromMatrices(
+    sceneX,
+    sceneY,
+    submitted.width,
+    submitted.height,
+    camera.viewMatrix,
+    camera.projectionMatrix,
+    camera.projection,
+  );
+}
+
+/** Explicit display-space entity pick; legacy `pick` remains unwarped. */
+export function pickDisplay(
+  world: World,
+  _cameraEntity: EntityHandle,
+  displayX: number,
+  displayY: number,
+  mapping: BarrelDistortionMapping | undefined,
+  viewportWidth: number,
+  viewportHeight: number,
+): PickHit | undefined {
+  const extent = submittedExtent(mapping, viewportWidth, viewportHeight);
+  if (
+    extent === undefined ||
+    !Number.isFinite(displayX) ||
+    !Number.isFinite(displayY) ||
+    displayX < 0 ||
+    displayX > extent.width ||
+    displayY < 0 ||
+    displayY > extent.height
+  ) {
+    return undefined;
+  }
+  const scene = { x: 0, y: 0 };
+  if (!displayToScenePixel(scene, mapping, displayX, displayY)) return undefined;
+  const screenRay = computeSceneScreenRay(scene.x, scene.y, mapping);
+  if (screenRay === undefined) return undefined;
+  return pickWithScreenRay(world, screenRay);
+}
+
+function remapVertexHits(
+  hits: readonly VertexHit[],
+  displayX: number,
+  displayY: number,
+  mapping: BarrelDistortionMapping | undefined,
+  screenRay: ScreenRay,
+  viewportWidth: number,
+  viewportHeight: number,
+  radius: number | undefined,
+): VertexHit[] {
+  const viewProj = mat4.create();
+  mat4.multiply(viewProj, screenRay.proj, screenRay.view);
+  const scenePoint = vec2.create();
+  const displayPoint: DisplayPoint = { x: 0, y: 0 };
+  const remapped: VertexHit[] = [];
+  for (const hit of hits) {
+    const projected = ray.worldToScreen(
+      scenePoint,
+      hit.worldPos as unknown as Vec3Like,
+      viewProj,
+      viewportWidth,
+      viewportHeight,
+    );
+    if (projected.behind) continue;
+    if (
+      mapping === undefined ||
+      !mapSceneToDisplay(displayPoint, mapping, scenePoint[0] as number, scenePoint[1] as number)
+    )
+      continue;
+    const dx = displayPoint.x - displayX;
+    const dy = displayPoint.y - displayY;
+    const screenDist = Math.hypot(dx, dy);
+    if (radius !== undefined && (!Number.isFinite(radius) || screenDist > radius)) continue;
+    remapped.push({ ...hit, screenDist });
+  }
+  remapped.sort((left, right) => left.screenDist - right.screenDist);
+  return remapped;
+}
+
+function displayVertexQuery(
+  displayX: number,
+  displayY: number,
+  mapping: BarrelDistortionMapping | undefined,
+  viewportWidth: number,
+  viewportHeight: number,
+): DisplayPoint | undefined {
+  const extent = submittedExtent(mapping, viewportWidth, viewportHeight);
+  if (
+    extent === undefined ||
+    !Number.isFinite(displayX) ||
+    !Number.isFinite(displayY) ||
+    displayX < 0 ||
+    displayX > extent.width ||
+    displayY < 0 ||
+    displayY > extent.height
+  ) {
+    return undefined;
+  }
+  const scene = { x: 0, y: 0 };
+  if (!displayToScenePixel(scene, mapping, displayX, displayY)) return undefined;
+  return scene;
+}
+
+/** Pick vertices using displayed-pixel radius and ordering under the same mapping. */
+export function pickVertexDisplay(
+  world: World,
+  _cameraEntity: EntityHandle,
+  displayX: number,
+  displayY: number,
+  mapping: BarrelDistortionMapping | undefined,
+  viewportWidth: number,
+  viewportHeight: number,
+  options?: DisplayVertexPickOptions,
+): VertexHit | VertexHit[] | undefined {
+  const scene = displayVertexQuery(displayX, displayY, mapping, viewportWidth, viewportHeight);
+  if (scene === undefined) return options === undefined ? undefined : [];
+  const screenRay = computeSceneScreenRay(scene.x, scene.y, mapping);
+  if (screenRay === undefined) return options === undefined ? undefined : [];
+  const extent =
+    mapping === undefined ? undefined : { width: mapping.width, height: mapping.height };
+  if (extent === undefined) return options === undefined ? undefined : [];
+  const hitResult = pickVertexWithScreenRay(
+    world,
+    screenRay,
+    scene.x,
+    scene.y,
+    extent.width,
+    extent.height,
+    {
+      limit: Number.MAX_SAFE_INTEGER,
+    },
+  );
+  const hits = Array.isArray(hitResult) ? hitResult : [];
+  const remapped = remapVertexHits(
+    hits,
+    displayX,
+    displayY,
+    mapping,
+    screenRay,
+    extent.width,
+    extent.height,
+    options?.radius,
+  );
+  return options === undefined
+    ? remapped[0]
+    : options.limit === undefined
+      ? remapped
+      : remapped.slice(0, options.limit);
+}
+
+/** Pick vertices on one entity using displayed-pixel radius and ordering. */
+export function pickVertexOnEntityDisplay(
+  world: World,
+  _cameraEntity: EntityHandle,
+  displayX: number,
+  displayY: number,
+  mapping: BarrelDistortionMapping | undefined,
+  viewportWidth: number,
+  viewportHeight: number,
+  entity: EntityHandle,
+  options?: DisplayVertexPickOptions,
+): VertexHit | VertexHit[] | undefined {
+  const scene = displayVertexQuery(displayX, displayY, mapping, viewportWidth, viewportHeight);
+  if (scene === undefined) return options === undefined ? undefined : [];
+  const screenRay = computeSceneScreenRay(scene.x, scene.y, mapping);
+  if (screenRay === undefined) return options === undefined ? undefined : [];
+  const extent =
+    mapping === undefined ? undefined : { width: mapping.width, height: mapping.height };
+  if (extent === undefined) return options === undefined ? undefined : [];
+  const hitResult = pickVertexOnEntityWithScreenRay(
+    world,
+    screenRay,
+    scene.x,
+    scene.y,
+    extent.width,
+    extent.height,
+    entity,
+    { limit: Number.MAX_SAFE_INTEGER },
+  );
+  const hits = Array.isArray(hitResult) ? hitResult : [];
+  const remapped = remapVertexHits(
+    hits,
+    displayX,
+    displayY,
+    mapping,
+    screenRay,
+    extent.width,
+    extent.height,
+    options?.radius,
+  );
+  return options === undefined
+    ? remapped[0]
+    : options.limit === undefined
+      ? remapped
+      : remapped.slice(0, options.limit);
+}

package/src/index.ts

@@ -6,6 +6,15 @@
 // (camera validation -> view=invert -> projection -> screenToRay -> GlobalTransform.world)
 // lives once in pick-core.ts (AC-201).
 
+export type { DisplayVertexPickOptions } from './display-picking';
+export {
+  computeDisplayScreenRay,
+  displayToScenePixel,
+  pickDisplay,
+  pickVertexDisplay,
+  pickVertexOnEntityDisplay,
+} from './display-picking';
+
 // --- screen-to-entity ray-AABB pick (nearest pickable mesh) ---
 export type { PickHit } from './pick';
 export { pick } from './pick';

package/src/pick-core.ts

@@ -48,6 +48,39 @@ export interface ScreenRay {
   readonly projectionKind: CameraProjection;
 }
 
+/** Build a screen ray from matrices captured with the accepted render frame. */
+export function computeScreenRayFromMatrices(
+  screenX: number,
+  screenY: number,
+  viewportWidth: number,
+  viewportHeight: number,
+  viewMatrix: ArrayLike<number>,
+  projectionMatrix: ArrayLike<number>,
+  projectionKind: CameraProjection,
+): ScreenRay | undefined {
+  if (
+    !Number.isFinite(screenX) ||
+    !Number.isFinite(screenY) ||
+    !Number.isFinite(viewportWidth) ||
+    !Number.isFinite(viewportHeight) ||
+    viewportWidth <= 0 ||
+    viewportHeight <= 0 ||
+    viewMatrix.length !== 16 ||
+    projectionMatrix.length !== 16 ||
+    !Array.from(viewMatrix).every((value) => Number.isFinite(value)) ||
+    !Array.from(projectionMatrix).every((value) => Number.isFinite(value))
+  ) {
+    return undefined;
+  }
+  const view = mat4.create();
+  const proj = mat4.create();
+  view.set(viewMatrix);
+  proj.set(projectionMatrix);
+  const r = ray.create();
+  ray.screenToRay(r, screenX, screenY, viewportWidth, viewportHeight, view, proj, projectionKind);
+  return { ray: r, view, proj, projectionKind };
+}
+
 /**
  * Build the screen-to-world ray for `cameraEntity` at the viewport-relative
  * `(screenX, screenY)` coordinate: validate the camera component, read its world