@forgeax/engine-picking 0.1.3 → 0.1.6

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

@@ -13,24 +13,25 @@
 // TDD red phase (w7): pickVertex full-scene tests covering AC-02 (three-state
 // return) + R-2 (AABB coarse cull multi-entity) + limit > available vertices.
 
+import { AssetRegistry, resolveAssetHandle } from '@forgeax/engine-assets-runtime';
 import { type EntityHandle, World } from '@forgeax/engine-ecs';
-import { createPrimitiveMesh } from '@forgeax/engine-geometry';
 import { mat4, ray, type Vec3Like, vec2, vec3 } from '@forgeax/engine-math';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
 import {
   CAMERA_PROJECTION_PERSPECTIVE,
   Camera,
   cameraProjectionFromF32,
-  Materials,
   MeshFilter,
   MeshRenderer,
 } from '@forgeax/engine-render';
 import { propagateTransforms, Transform } from '@forgeax/engine-scene';
 
-import type { Handle, MeshAsset, VertexAttributeMap } from '@forgeax/engine-types';
+import type { Handle, MaterialAsset, MeshAsset, VertexAttributeMap } from '@forgeax/engine-types';
+import { toShared } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
-import { resolvePickingAsset } from '../asset-port';
 import { PickError } from '../pick-errors';
 import { pickVertex, pickVertexOnEntity, type VertexHit } from '../pick-vertex';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
 
 // ── shared constants ─────────────────────────────────────────────────────
 
@@ -52,42 +53,29 @@ function translateTransform(x: number, y: number, z: number) {
   };
 }
 
-function aabbFromPositions(positions: ArrayLike<number>): Float32Array {
-  let minX = Number.POSITIVE_INFINITY;
-  let minY = Number.POSITIVE_INFINITY;
-  let minZ = Number.POSITIVE_INFINITY;
-  let maxX = Number.NEGATIVE_INFINITY;
-  let maxY = Number.NEGATIVE_INFINITY;
-  let maxZ = Number.NEGATIVE_INFINITY;
-  for (let i = 0; i < positions.length; i += 3) {
-    minX = Math.min(minX, positions[i] as number);
-    minY = Math.min(minY, positions[i + 1] as number);
-    minZ = Math.min(minZ, positions[i + 2] as number);
-    maxX = Math.max(maxX, positions[i] as number);
-    maxY = Math.max(maxY, positions[i + 1] as number);
-    maxZ = Math.max(maxZ, positions[i + 2] as number);
-  }
-  return new Float32Array([minX, minY, minZ, maxX, maxY, maxZ]);
-}
-
 interface Scene {
   world: World;
+  assets: AssetRegistry;
   material: Handle<'MaterialAsset', 'shared'>;
 }
 
 function makeScene(): Scene {
   const world = new World();
-  const material = world.internSharedRef('MaterialAsset', Materials.unlit([1, 1, 1, 1]));
-  return { world, material };
-}
-
-function registerPrimitiveWithoutAabb(
-  scene: Scene,
-  kind: 'cube' | 'triangle',
-): Handle<'MeshAsset', 'shared'> {
-  const primitive = createPrimitiveMesh(kind).unwrap();
-  const { aabb: _aabb, ...meshWithoutAabb } = primitive;
-  return scene.world.internSharedRef('MeshAsset', meshWithoutAabb);
+  const assets = new AssetRegistry(makeMockShaderRegistry());
+  const matResult = assets.catalog<MaterialAsset>(AssetGuid.format(AssetGuid.random()), {
+    kind: 'material',
+    passes: [
+      {
+        name: 'Forward',
+        program: { module: 'forgeax::default-unlit' },
+        renderState: { tags: { LightMode: 'Forward' }, queue: 2000 },
+      },
+    ],
+    values: { baseColor: [1, 1, 1] },
+  });
+  if (!matResult.ok) throw new Error('material catalog failed');
+  const material = world.allocSharedRef('MaterialAsset', matResult.value);
+  return { world, assets, material };
 }
 
 function spawnPerspectiveCamera(world: World, z: number): EntityHandle {
@@ -126,18 +114,19 @@ function registerTriangle(scene: Scene): Handle<'MeshAsset', 'shared'> {
     v[i * 12 + 1] = positions[i * 3 + 1] as number;
     v[i * 12 + 2] = positions[i * 3 + 2] as number;
   }
-  return scene.world.allocSharedRef('MeshAsset', {
+  const result = scene.assets.catalog<MeshAsset>(AssetGuid.format(AssetGuid.random()), {
     kind: 'mesh',
     vertices: v,
     indices: new Uint16Array([0, 1, 2]),
     attributes: { position: positions },
-    aabb: aabbFromPositions(positions),
     submeshes: [
       { indexOffset: 0, indexCount: 3, vertexCount: 3, topology: 'triangle-list', materialSlot: 0 },
     ],
 
     materialSlots: [{ slotName: 'Default' }],
   });
+  if (!result.ok) throw new Error(`triangle mesh catalog failed: ${result.error.message}`);
+  return scene.world.allocSharedRef('MeshAsset', result.value);
 }
 
 /**
@@ -215,12 +204,11 @@ function registerCube(scene: Scene): Handle<'MeshAsset', 'shared'> {
     7,
     4, // left
   ]);
-  return scene.world.allocSharedRef('MeshAsset', {
+  const result = scene.assets.catalog<MeshAsset>(AssetGuid.format(AssetGuid.random()), {
     kind: 'mesh',
     vertices: v,
     indices,
     attributes: { position: positions },
-    aabb: aabbFromPositions(positions),
     submeshes: [
       {
         indexOffset: 0,
@@ -233,6 +221,8 @@ function registerCube(scene: Scene): Handle<'MeshAsset', 'shared'> {
 
     materialSlots: [{ slotName: 'Default' }],
   });
+  if (!result.ok) throw new Error(`cube mesh catalog failed: ${result.error.message}`);
+  return scene.world.allocSharedRef('MeshAsset', result.value);
 }
 
 /**
@@ -262,18 +252,19 @@ function registerSkinnedTriangle(scene: Scene): Handle<'MeshAsset', 'shared'> {
     skinIndex,
     skinWeight,
   };
-  return scene.world.allocSharedRef('MeshAsset', {
+  const result = scene.assets.catalog<MeshAsset>(AssetGuid.format(AssetGuid.random()), {
     kind: 'mesh',
     vertices: v,
     indices: new Uint16Array([0, 1, 2]),
     attributes: attrs,
-    aabb: aabbFromPositions(positions),
     submeshes: [
       { indexOffset: 0, indexCount: 3, vertexCount: 3, topology: 'triangle-list', materialSlot: 0 },
     ],
 
     materialSlots: [{ slotName: 'Default' }],
   });
+  if (!result.ok) throw new Error(`skinned mesh catalog failed: ${result.error.message}`);
+  return scene.world.allocSharedRef('MeshAsset', result.value);
 }
 
 function spawnMeshEntity(
@@ -498,7 +489,10 @@ describe('pickVertexOnEntity', () => {
       const entity = spawnMeshEntity(scene, mesh, 0, 0, 0);
       propagateTransforms(scene.world);
 
-      const meshRes = resolvePickingAsset<MeshAsset>(scene.world, mesh);
+      const meshRes = resolveAssetHandle<MeshAsset>(
+        scene.world,
+        toShared<'MeshAsset'>(mesh as unknown as number),
+      );
       if (!meshRes.ok) throw new Error('resolve failed');
       const position = meshRes.value.attributes.position as Float32Array;
       const wm = readWorldMatrix(scene.world, entity)!;
@@ -535,7 +529,10 @@ describe('pickVertexOnEntity', () => {
       const entity = spawnMeshEntity(scene, mesh, 0.1, 0.2, 0);
       propagateTransforms(scene.world);
 
-      const meshRes = resolvePickingAsset<MeshAsset>(scene.world, mesh);
+      const meshRes = resolveAssetHandle<MeshAsset>(
+        scene.world,
+        toShared<'MeshAsset'>(mesh as unknown as number),
+      );
       if (!meshRes.ok) throw new Error('resolve failed');
       const position = meshRes.value.attributes.position as Float32Array;
       const wm = readWorldMatrix(scene.world, entity)!;
@@ -726,7 +723,10 @@ describe('pickVertexOnEntity', () => {
       propagateTransforms(scene.world);
 
       // Verify mesh is skinned
-      const meshRes = resolvePickingAsset<MeshAsset>(scene.world, mesh);
+      const meshRes = resolveAssetHandle<MeshAsset>(
+        scene.world,
+        toShared<'MeshAsset'>(mesh as unknown as number),
+      );
       expect(meshRes.ok).toBe(true);
       if (!meshRes.ok) throw new Error('resolve failed');
       const attrs = meshRes.value.attributes;
@@ -750,7 +750,10 @@ describe('pickVertexOnEntity', () => {
       const entity = spawnMeshEntity(scene, mesh, 0.1, 0.2, 0);
       propagateTransforms(scene.world);
 
-      const meshRes = resolvePickingAsset<MeshAsset>(scene.world, mesh);
+      const meshRes = resolveAssetHandle<MeshAsset>(
+        scene.world,
+        toShared<'MeshAsset'>(mesh as unknown as number),
+      );
       if (!meshRes.ok) throw new Error('resolve failed');
       const position = meshRes.value.attributes.position as Float32Array;
       const wm = readWorldMatrix(scene.world, entity)!;
@@ -872,7 +875,10 @@ describe('pickVertexOnEntity', () => {
       // propagate must be called before pickVertexOnEntity
       propagateTransforms(scene.world);
 
-      const meshRes = resolvePickingAsset<MeshAsset>(scene.world, mesh);
+      const meshRes = resolveAssetHandle<MeshAsset>(
+        scene.world,
+        toShared<'MeshAsset'>(mesh as unknown as number),
+      );
       if (!meshRes.ok) throw new Error('resolve failed');
       const position = meshRes.value.attributes.position as Float32Array;
       const wm = readWorldMatrix(scene.world, entity)!;
@@ -1014,7 +1020,7 @@ describe('w6: degradation input + builtin fallback', () => {
         v[i * 12 + 1] = positions[i * 3 + 1] as number;
         v[i * 12 + 2] = positions[i * 3 + 2] as number;
       }
-      return scene.world.allocSharedRef('MeshAsset', {
+      const result = scene.assets.catalog<MeshAsset>(AssetGuid.format(AssetGuid.random()), {
         kind: 'mesh',
         vertices: v,
         indices: new Uint16Array([0, 1, 2, 3]),
@@ -1031,6 +1037,8 @@ describe('w6: degradation input + builtin fallback', () => {
 
         materialSlots: [{ slotName: 'Default' }],
       });
+      if (!result.ok) throw new Error(`strip mesh catalog failed: ${result.error.message}`);
+      return scene.world.allocSharedRef('MeshAsset', result.value);
     }
 
     it('strip submesh returns undefined (no crash, no approximate hit)', () => {
@@ -1062,7 +1070,7 @@ describe('w6: degradation input + builtin fallback', () => {
     function registerUint16Position(scene: Scene): Handle<'MeshAsset', 'shared'> {
       const positions = new Uint16Array([0, 0, 0, 1, 0, 0, 0, 1, 0]);
       const v = new Float32Array(3 * 12);
-      return scene.world.allocSharedRef('MeshAsset', {
+      const result = scene.assets.catalog<MeshAsset>(AssetGuid.format(AssetGuid.random()), {
         kind: 'mesh',
         vertices: v,
         indices: new Uint16Array([0, 1, 2]),
@@ -1079,11 +1087,13 @@ describe('w6: degradation input + builtin fallback', () => {
 
         materialSlots: [{ slotName: 'Default' }],
       });
+      if (!result.ok) throw new Error(`u16 mesh catalog failed: ${result.error.message}`);
+      return scene.world.allocSharedRef('MeshAsset', result.value);
     }
 
     function registerUndefinedPosition(scene: Scene): Handle<'MeshAsset', 'shared'> {
       const v = new Float32Array(3 * 12);
-      return scene.world.allocSharedRef('MeshAsset', {
+      const result = scene.assets.catalog<MeshAsset>(AssetGuid.format(AssetGuid.random()), {
         kind: 'mesh',
         vertices: v,
         indices: new Uint16Array([0, 1, 2]),
@@ -1100,6 +1110,8 @@ describe('w6: degradation input + builtin fallback', () => {
 
         materialSlots: [{ slotName: 'Default' }],
       });
+      if (!result.ok) throw new Error(`no-position mesh catalog failed: ${result.error.message}`);
+      return scene.world.allocSharedRef('MeshAsset', result.value);
     }
 
     it('Uint16Array position returns undefined (skip, no crash)', () => {
@@ -1136,7 +1148,7 @@ describe('w6: degradation input + builtin fallback', () => {
         v[i * 12 + 1] = positions[i * 3 + 1] as number;
         v[i * 12 + 2] = positions[i * 3 + 2] as number;
       }
-      return scene.world.allocSharedRef('MeshAsset', {
+      const result = scene.assets.catalog<MeshAsset>(AssetGuid.format(AssetGuid.random()), {
         kind: 'mesh',
         vertices: v,
         attributes: { position: positions },
@@ -1152,6 +1164,8 @@ describe('w6: degradation input + builtin fallback', () => {
 
         materialSlots: [{ slotName: 'Default' }],
       });
+      if (!result.ok) throw new Error(`indexless mesh catalog failed: ${result.error.message}`);
+      return scene.world.allocSharedRef('MeshAsset', result.value);
     }
 
     it('non-indexed mesh hits vertices (every consecutive 3 vertices = one face)', () => {
@@ -1177,7 +1191,7 @@ describe('w6: degradation input + builtin fallback', () => {
     function registerEmptyMesh(scene: Scene): Handle<'MeshAsset', 'shared'> {
       const positions = new Float32Array(0);
       const v = new Float32Array(0);
-      return scene.world.allocSharedRef('MeshAsset', {
+      const result = scene.assets.catalog<MeshAsset>(AssetGuid.format(AssetGuid.random()), {
         kind: 'mesh',
         vertices: v,
         attributes: { position: positions },
@@ -1193,6 +1207,8 @@ describe('w6: degradation input + builtin fallback', () => {
 
         materialSlots: [{ slotName: 'Default' }],
       });
+      if (!result.ok) throw new Error(`empty mesh catalog failed: ${result.error.message}`);
+      return scene.world.allocSharedRef('MeshAsset', result.value);
     }
 
     it('0 vertices returns undefined (no crash)', () => {
@@ -1229,7 +1245,7 @@ describe('w6: degradation input + builtin fallback', () => {
         v[i * 12 + 1] = positions[i * 3 + 1] as number;
         v[i * 12 + 2] = positions[i * 3 + 2] as number;
       }
-      return scene.world.allocSharedRef('MeshAsset', {
+      const result = scene.assets.catalog<MeshAsset>(AssetGuid.format(AssetGuid.random()), {
         kind: 'mesh',
         vertices: v,
         indices: new Uint16Array([0, 1, 2]),
@@ -1246,6 +1262,8 @@ describe('w6: degradation input + builtin fallback', () => {
 
         materialSlots: [{ slotName: 'Default' }],
       });
+      if (!result.ok) throw new Error(`NaN mesh catalog failed: ${result.error.message}`);
+      return scene.world.allocSharedRef('MeshAsset', result.value);
     }
 
     it('NaN vertex coordinates excluded, valid vertices still hit (no NaN propagation)', () => {
@@ -1276,7 +1294,7 @@ describe('w6: degradation input + builtin fallback', () => {
         v[i * 12 + 1] = positions[i * 3 + 1] as number;
         v[i * 12 + 2] = positions[i * 3 + 2] as number;
       }
-      const mesh = scene.world.allocSharedRef('MeshAsset', {
+      const result = scene.assets.catalog<MeshAsset>(AssetGuid.format(AssetGuid.random()), {
         kind: 'mesh',
         vertices: v,
         indices: new Uint16Array([0, 1, 2]),
@@ -1293,6 +1311,8 @@ describe('w6: degradation input + builtin fallback', () => {
 
         materialSlots: [{ slotName: 'Default' }],
       });
+      if (!result.ok) throw new Error('all-NaN mesh catalog failed');
+      const mesh = scene.world.allocSharedRef('MeshAsset', result.value);
       const entity = spawnMeshEntity(scene, mesh, 0, 0, 0);
       const hit = runPickVertexOnEntity(scene.world, camera, VP / 2, VP / 2, VP, VP, entity) as
         | VertexHit
@@ -1301,17 +1321,16 @@ describe('w6: degradation input + builtin fallback', () => {
     });
   });
 
-  // ── AC-07: World-owned primitive mesh without AABB → walk-all-vertices fallback ──
+  // ── AC-07: builtin mesh without AABB → walk-all-vertices fallback ──
 
-  describe('AC-07: primitive mesh without AABB — walk-all-vertices fallback', () => {
-    it('triangle (no AABB) returns a valid hit via full vertex walk', () => {
+  describe('AC-07: builtin mesh without AABB — walk-all-vertices fallback', () => {
+    it('BUILTIN_TRIANGLE (no AABB) returns a valid hit via full vertex walk', () => {
       const scene = makeScene();
       const camera = spawnPerspectiveCamera(scene.world, 5);
-      const mesh = registerPrimitiveWithoutAabb(scene, 'triangle');
       const entity = scene.world
         .spawn(
           { component: Transform, data: translateTransform(0, 0, 0) },
-          { component: MeshFilter, data: { assetHandle: mesh } },
+          { component: MeshFilter, data: { assetHandle: toShared<'MeshAsset'>(1) } },
           { component: MeshRenderer, data: { materials: [scene.material] } },
         )
         .unwrap();
@@ -1327,14 +1346,13 @@ describe('w6: degradation input + builtin fallback', () => {
       }
     });
 
-    it('cube (no AABB) returns valid vertex hits', () => {
+    it('BUILTIN_CUBE (no AABB) returns valid vertex hits', () => {
       const scene = makeScene();
       const camera = spawnPerspectiveCamera(scene.world, 5);
-      const mesh = registerPrimitiveWithoutAabb(scene, 'cube');
       const entity = scene.world
         .spawn(
           { component: Transform, data: translateTransform(0, 0, 0) },
-          { component: MeshFilter, data: { assetHandle: mesh } },
+          { component: MeshFilter, data: { assetHandle: toShared<'MeshAsset'>(2) } },
           { component: MeshRenderer, data: { materials: [scene.material] } },
         )
         .unwrap();
@@ -1517,12 +1535,11 @@ describe('w7: pickVertex full-scene', () => {
         v[i * 12 + 1] = positions[i * 3 + 1] as number;
         v[i * 12 + 2] = positions[i * 3 + 2] as number;
       }
-      return scene.world.allocSharedRef('MeshAsset', {
+      const result = scene.assets.catalog<MeshAsset>(AssetGuid.format(AssetGuid.random()), {
         kind: 'mesh',
         vertices: v,
         indices: new Uint16Array([0, 1, 2]),
         attributes: { position: positions },
-        aabb: aabbFromPositions(positions),
         submeshes: [
           {
             indexOffset: 0,
@@ -1535,6 +1552,8 @@ describe('w7: pickVertex full-scene', () => {
 
         materialSlots: [{ slotName: 'Default' }],
       });
+      if (!result.ok) throw new Error(`small triangle catalog failed: ${result.error.message}`);
+      return scene.world.allocSharedRef('MeshAsset', result.value);
     }
 
     it('entity far from ray is excluded by AABB coarse cull', () => {

package/src/__tests__/pick.test.ts

@@ -6,7 +6,9 @@
 // package (AC-203), so these integration tests live in the downstream picking
 // package that depends on runtime.
 
+import { AssetRegistry } from '@forgeax/engine-assets-runtime';
 import { type EntityHandle, World } from '@forgeax/engine-ecs';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
 import {
   CAMERA_PROJECTION_ORTHOGRAPHIC,
   CAMERA_PROJECTION_PERSPECTIVE,
@@ -15,13 +17,13 @@ import {
   MeshRenderer,
 } from '@forgeax/engine-render';
 import { ChildOf, propagateTransforms, Transform } from '@forgeax/engine-scene';
-import type { Handle } from '@forgeax/engine-types';
-
+import type { Handle, MaterialAsset, MeshAsset } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { type PickHit, pick } from '../pick';
 import { PickError } from '../pick-errors';
 import { pickVertex, pickVertexOnEntity } from '../pick-vertex';
 import { viewportToWorld } from '../viewport-to-world';
+import { makeMockShaderRegistry } from './helpers/mock-shader-registry';
 
 // --- from pick.test.ts ---
 // pick.test.ts — feat-20260529-picking-raycasting-screen-to-entity M3 / w12 (TDD red).
@@ -30,10 +32,14 @@ import { viewportToWorld } from '../viewport-to-world';
 //   pick(world, cameraEntity, screenX, screenY, viewportWidth, viewportHeight)
 //     -> PickHit | undefined
 //
-// The deterministic scene is built with a bare `new World()` and direct owner
-// payloads. A full `createRenderer` is intentionally NOT used —
+// The deterministic scene is built with a bare `new World()` + a real
+// `AssetRegistry` (the `assets` param introduced by the 2026-05-29 replan: the
+// ray-AABB test needs `MeshAsset.aabb`, which lives ONLY in the AssetRegistry,
+// never on a world column). A full `createRenderer` is intentionally NOT used —
 // it requires a live WebGPU device unavailable in the `pnpm test:unit` project,
-// and `pick` only consumes World shared references, not the renderer.
+// and `pick` only consumes an `AssetRegistry`, not the renderer. The registry
+// instance IS `renderer.assets` at the demo call site (w16), so the surface
+// under test is identical.
 //
 // Coverage (all pick acceptance criteria):
 //   (AC-06) nearest hit wins — two boxes along the ray, the closer one returns
@@ -97,7 +103,7 @@ function translateTransform(
  * `vertices` must be a multiple of the 12-float interleaved stride; a single 3-vertex
  * triangle (36 floats) satisfies the gate while the position attribute drives the AABB.
  */
-function registerBox(world: World): Handle<'MeshAsset', 'shared'> {
+function registerBox(world: World, assets: AssetRegistry): Handle<'MeshAsset', 'shared'> {
   const vertices = new Float32Array([
     0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 1, 0, 1,
     0, 0, 0, 0,
@@ -107,7 +113,9 @@ function registerBox(world: World): Handle<'MeshAsset', 'shared'> {
     -0.5, -0.5, -0.5, 0.5, -0.5, -0.5, 0.5, 0.5, -0.5, -0.5, 0.5, -0.5, -0.5, -0.5, 0.5, 0.5, -0.5,
     0.5, 0.5, 0.5, 0.5, -0.5, 0.5, 0.5,
   ]);
-  return world.allocSharedRef('MeshAsset', {
+  // catalog computes the local-space AABB (withMeshAabb); mint the augmented
+  // payload on the world so resolveAssetHandle (used by pick) reads .aabb.
+  const result = assets.catalog<MeshAsset>(AssetGuid.format(AssetGuid.random()), {
     kind: 'mesh',
     vertices,
     indices: new Uint16Array([0, 1, 2]),
@@ -123,12 +131,13 @@ function registerBox(world: World): Handle<'MeshAsset', 'shared'> {
     ],
 
     materialSlots: [{ slotName: 'Default' }],
-    aabb: new Float32Array([-0.5, -0.5, -0.5, 0.5, 0.5, 0.5]),
   });
+  if (!result.ok) throw new Error('mesh catalog failed');
+  return world.allocSharedRef('MeshAsset', result.value);
 }
 
-function registerMaterial(world: World): Handle<'MaterialAsset', 'shared'> {
-  return world.allocSharedRef('MaterialAsset', {
+function registerMaterial(world: World, assets: AssetRegistry): Handle<'MaterialAsset', 'shared'> {
+  const result = assets.catalog<MaterialAsset>(AssetGuid.format(AssetGuid.random()), {
     kind: 'material',
     passes: [
       {
@@ -139,19 +148,23 @@ function registerMaterial(world: World): Handle<'MaterialAsset', 'shared'> {
     ],
     values: { baseColor: [1, 1, 1] },
   });
+  if (!result.ok) throw new Error('material catalog failed');
+  return world.allocSharedRef('MaterialAsset', result.value);
 }
 
 interface Scene {
   world: World;
+  assets: AssetRegistry;
   mesh: Handle<'MeshAsset', 'shared'>;
   material: Handle<'MaterialAsset', 'shared'>;
 }
 
 function makeScene(): Scene {
   const world = new World();
-  const mesh = registerBox(world);
-  const material = registerMaterial(world);
-  return { world, mesh, material };
+  const assets = new AssetRegistry(makeMockShaderRegistry());
+  const mesh = registerBox(world, assets);
+  const material = registerMaterial(world, assets);
+  return { world, assets, mesh, material };
 }
 
 /** Spawn a perspective camera at (x,y,z) looking down -Z (identity rotation). */

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

@@ -1,5 +1,5 @@
+import { HANDLE_CUBE } from '@forgeax/engine-assets-runtime';
 import { type EntityHandle, World } from '@forgeax/engine-ecs';
-import { createPrimitiveMesh } from '@forgeax/engine-geometry';
 import {
   CAMERA_PROJECTION_PERSPECTIVE,
   Camera,
@@ -8,9 +8,9 @@ import {
   Visibility,
   VisibilityStateValue,
 } from '@forgeax/engine-render';
-import { extractFrames } from '@forgeax/engine-render/internal';
 import { propagateTransforms, Transform } from '@forgeax/engine-scene';
 import { describe, expect, it } from 'vitest';
+import { extractFrames } from '../../../render/src/render-system-extract';
 import { pick } from '../pick';
 
 const VIEWPORT = 600;
@@ -49,11 +49,10 @@ describe('visibility picking boundary', () => {
   it('keeps pick results unchanged when the render candidate is hidden', () => {
     const world = new World();
     const camera = spawnCamera(world);
-    const mesh = world.internSharedRef('MeshAsset', createPrimitiveMesh('cube').unwrap());
     const entity = world
       .spawn(
         { component: Transform, data: transform([0, 0, 0]) },
-        { component: MeshFilter, data: { assetHandle: mesh } },
+        { component: MeshFilter, data: { assetHandle: HANDLE_CUBE } },
         { component: MeshRenderer, data: {} },
         { component: Visibility, data: { state: VisibilityStateValue.visible } },
       )

package/src/pick-vertex.ts

@@ -15,7 +15,7 @@
 //   - { limit: N }       → VertexHit[]
 //
 // Reuses pick()'s full skeleton (camera validation / view=invert(world) / projection branch /
-// screenToRay / world.sharedRefs.resolve / Transform.world / AABB coarse cull), then for each
+// screenToRay / resolveAssetHandle / Transform.world / AABB coarse cull), then for each
 // triangle-list submesh that passes the AABB test, iterates every triangle and collects
 // vertex candidates via rayTriangleIntersects.
 //
@@ -43,13 +43,13 @@
 //          Finding 9 (behind flag) / Finding 10 (isSkinned);
 //          plan-tasks.json w5/w8 acceptanceCheck.
 
+import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
 import type { EntityHandle, World } from '@forgeax/engine-ecs';
 import { mat4, ray, type Vec3Like, vec2, vec3 } from '@forgeax/engine-math';
 import { MeshFilter, MeshRenderer } from '@forgeax/engine-render';
 import { Transform } from '@forgeax/engine-scene';
 import type { MeshAsset } from '@forgeax/engine-types';
 import { toShared } from '@forgeax/engine-types';
-import { resolvePickingAsset } from './asset-port';
 import { computeScreenRay, readWorldMatrix } from './pick-core';
 
 // ── types ────────────────────────────────────────────────────────────────
@@ -236,7 +236,7 @@ function collectVertexHits(
   if (!mfRes.ok) {
     return [];
   }
-  const meshRes = resolvePickingAsset<MeshAsset>(
+  const meshRes = resolveAssetHandle<MeshAsset>(
     world,
     toShared<'MeshAsset'>(mfRes.value.assetHandle as unknown as number),
   );
@@ -546,7 +546,7 @@ export function pickVertex(
   for (const row of query) {
     const assetHandleRaw = Math.round(row.get(MeshFilter).assetHandle as number);
     if (assetHandleRaw === 0) continue;
-    const meshRes = resolvePickingAsset<MeshAsset>(world, toShared<'MeshAsset'>(assetHandleRaw));
+    const meshRes = resolveAssetHandle<MeshAsset>(world, toShared<'MeshAsset'>(assetHandleRaw));
     if (!meshRes.ok) continue;
 
     // read entity (mirrors pick.ts:190)

package/src/pick.ts

@@ -8,7 +8,7 @@
 //
 // Mesh AABB source (feat-20260614 M8, D-15/D-18): the ray-AABB test needs each
 // mesh's local-space `MeshAsset.aabb`, resolved from the entity's `MeshFilter`
-// handle via `world.sharedRefs.resolve<MeshAsset>(handle)` (two-tier builtin /
+// handle via `resolveAssetHandle<MeshAsset>(world, handle)` (two-tier builtin /
 // world.sharedRefs dispatch). The registry no longer holds handles, so `pick`
 // takes no `AssetRegistry` -- it resolves entirely World-side. Keeping `pick` a
 // free function (rather than a `World` method) preserves the layering: `World`
@@ -32,13 +32,13 @@
 // Related: requirements in-scope #5/#6/#7 + AC-05..AC-11; plan-strategy D-3 / D-6 / 5.3;
 //          research Finding 4 (local->world AABB) + Finding 5 (entity-id via query rows).
 
+import { resolveAssetHandle } from '@forgeax/engine-assets-runtime';
 import type { EntityHandle, World } from '@forgeax/engine-ecs';
 import { box3, ray, type Vec3Like, vec3 } from '@forgeax/engine-math';
 import { MeshFilter, MeshRenderer } from '@forgeax/engine-render';
 import { Transform } from '@forgeax/engine-scene';
 import type { MeshAsset } from '@forgeax/engine-types';
 import { toShared } from '@forgeax/engine-types';
-import { resolvePickingAsset } from './asset-port';
 import { computeScreenRay, readWorldMatrix } from './pick-core';
 
 /**
@@ -103,7 +103,7 @@ export function pick(
   for (const row of query) {
     const assetHandleRaw = Math.round(row.get(MeshFilter).assetHandle as number);
     if (assetHandleRaw === 0) continue;
-    const meshRes = resolvePickingAsset<MeshAsset>(world, toShared<'MeshAsset'>(assetHandleRaw));
+    const meshRes = resolveAssetHandle<MeshAsset>(world, toShared<'MeshAsset'>(assetHandleRaw));
     if (!meshRes.ok) continue;
     const localAabb = meshRes.value.aabb;
     if (localAabb === undefined) continue;

package/dist/asset-port.d.ts

@@ -1,6 +0,0 @@
-import type { World } from '@forgeax/engine-ecs';
-import type { Asset, Handle, Result } from '@forgeax/engine-types';
-export type PickingAssetResolutionError = ReturnType<World['sharedRefs']['resolve']> extends Result<unknown, infer E> ? E : never;
-/** Resolve a picking payload through the World shared-ref owner. */
-export declare function resolvePickingAsset<T extends Asset>(world: World, handle: Handle<string, 'shared'>): Result<T, PickingAssetResolutionError>;
-//# sourceMappingURL=asset-port.d.ts.map

package/dist/asset-port.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"asset-port.d.ts","sourceRoot":"","sources":["../src/asset-port.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAEnE,MAAM,MAAM,2BAA2B,GACrC,UAAU,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE1F,oEAAoE;AACpE,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,KAAK,EACjD,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAC/B,MAAM,CAAC,CAAC,EAAE,2BAA2B,CAAC,CAExC"}

package/src/asset-port.ts

@@ -1,13 +0,0 @@
-import type { World } from '@forgeax/engine-ecs';
-import type { Asset, Handle, Result } from '@forgeax/engine-types';
-
-export type PickingAssetResolutionError =
-  ReturnType<World['sharedRefs']['resolve']> extends Result<unknown, infer E> ? E : never;
-
-/** Resolve a picking payload through the World shared-ref owner. */
-export function resolvePickingAsset<T extends Asset>(
-  world: World,
-  handle: Handle<string, 'shared'>,
-): Result<T, PickingAssetResolutionError> {
-  return world.sharedRefs.resolve<string, T>(handle) as Result<T, PickingAssetResolutionError>;
-}