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

package/dist/pick-core.d.ts

@@ -0,0 +1,39 @@
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import { mat4, ray } from '@forgeax/engine-math';
+import { type CameraProjection } from '@forgeax/engine-render';
+/**
+ * Read an entity's resolved world mat4 (16 column-major floats) from the
+ * `Transform.world` column array view (feat-20260601 D-3). Returns a fresh
+ * copy (the view aliases live slot bytes); `undefined` when the entity has no
+ * Transform / world column.
+ */
+export declare function readWorldMatrix(world: World, entity: EntityHandle): Float32Array | undefined;
+/**
+ * The screen-to-world ray plus the camera matrices used to build it.
+ *
+ *   - `ray`            — the unprojected world-space pick ray (origin + direction).
+ *   - `view`           — `invert(camera Transform.world)`.
+ *   - `proj`           — the camera projection matrix (perspective / orthographic).
+ *   - `projectionKind` — the resolved camera projection discriminant.
+ *
+ * `view` and `proj` are returned separately so vertex picking can build its own
+ * `viewProj = proj * view` for `worldToScreen` without recomputing the branch.
+ */
+export interface ScreenRay {
+    readonly ray: ray.Ray;
+    readonly view: mat4.Mat4;
+    readonly proj: mat4.Mat4;
+    readonly projectionKind: CameraProjection;
+}
+/**
+ * Build the screen-to-world ray for `cameraEntity` at the viewport-relative
+ * `(screenX, screenY)` coordinate: validate the camera component, read its world
+ * transform, invert it to a view matrix, branch the projection on the camera
+ * discriminant, and unproject the coordinate into a world-space ray.
+ *
+ * @returns The `ScreenRay`, or `undefined` when the camera entity carries no
+ *   resolvable `Transform.world` (a degenerate miss — no view matrix can be built).
+ * @throws {PickError} `code: 'camera-component-missing'` when `cameraEntity` has no `Camera`.
+ */
+export declare function computeScreenRay(world: World, cameraEntity: EntityHandle, screenX: number, screenY: number, viewportWidth: number, viewportHeight: number): ScreenRay | undefined;
+//# sourceMappingURL=pick-core.d.ts.map

package/dist/pick-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pick-core.d.ts","sourceRoot":"","sources":["../src/pick-core.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAU,KAAK,gBAAgB,EAA2B,MAAM,wBAAwB,CAAC;AAIhG;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,GAAG,YAAY,GAAG,SAAS,CAG5F;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,gBAAgB,CAAC;CAC3C;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE,YAAY,EAC1B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,GACrB,SAAS,GAAG,SAAS,CA6CvB"}

package/dist/pick-errors.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Detail for the `PickError` camera-component-missing code.
+ *
+ * Carries the offending camera entity (packed `Entity` u32) so AI consumers can read
+ * `.detail.cameraEntity` by property access (charter P4) — no string parsing of the
+ * human-facing message.
+ */
+export interface PickCameraMissingDetail {
+    readonly cameraEntity: number;
+}
+/**
+ * Structured error for the picking precondition failure: the supplied `cameraEntity`
+ * does not hold a `Camera` component, so `pick()` cannot build the view / projection
+ * matrices needed to unproject the screen coordinate.
+ *
+ * Three-field structured surface per the AGENTS.md error model + `.detail`:
+ *   - `.code = 'camera-component-missing'` (closed `PickErrorCode`)
+ *   - `.expected` — the expected precondition (camera entity carries a `Camera`)
+ *   - `.hint` — an actionable `world.set` recovery directive
+ *   - `.detail = { cameraEntity }` — the offending entity (charter P4)
+ *
+ * Surfaced (not the normal miss path): a no-hit ray returns `undefined` from `pick()`;
+ * this error is reserved for the unrecoverable precondition (charter P3 explicit failure,
+ * separate channel from the recoverable miss).
+ */
+export declare class PickError extends Error {
+    readonly code = "camera-component-missing";
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: PickCameraMissingDetail;
+    constructor(cameraEntity: number);
+}
+/**
+ * Closed union of picking precondition error codes, derived from the PickError owner.
+ *
+ * AI users perform exhaustive `switch (err.code)` without a default; TS guards completeness.
+ */
+export type PickErrorCode = PickError['code'];
+//# sourceMappingURL=pick-errors.d.ts.map

package/dist/pick-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pick-errors.d.ts","sourceRoot":"","sources":["../src/pick-errors.ts"],"names":[],"mappings":"AAkBA;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,8BAA8B;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;gBAE7B,YAAY,EAAE,MAAM;CAWjC;AAED;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC"}

package/dist/pick-tile.d.ts

@@ -0,0 +1,44 @@
+import { type EntityHandle, type World } from '@forgeax/engine-ecs';
+import { type Result } from '@forgeax/engine-types';
+/**
+ * Closed error union for `pickTile` (charter P3 + P4). Two variants cover the
+ * structural-break paths; "ray hit nothing" is a value (`Result.ok(null)`),
+ * not an error.
+ */
+export type PickTileError = {
+    readonly code: 'tilemap-not-found';
+    readonly tilemapEntity: EntityHandle;
+} | {
+    readonly code: 'tilemap-component-missing';
+    readonly tilemapEntity: EntityHandle;
+};
+/**
+ * Successful picking outcome. Returned through `Result.ok`; a `null` value
+ * means the query landed in-bounds but every layer at that cell was empty
+ * (or the point was outside the tilemap world bounds).
+ */
+export interface PickTileHit {
+    readonly layerEntity: EntityHandle;
+    readonly cellX: number;
+    readonly cellY: number;
+    readonly tileId: number;
+}
+/**
+ * Find the topmost non-zero tile under `(worldX, worldY)` for a given
+ * Tilemap entity, walking child TileLayer entities in DESCENDING
+ * `layerOrder`.
+ *
+ * @returns
+ *   - `Result.ok(PickTileHit)` for a non-zero cell on some layer.
+ *   - `Result.ok(null)` for an empty cell or out-of-bounds query.
+ *   - `Result.err({ code: 'tilemap-not-found' })` for a dead handle.
+ *   - `Result.err({ code: 'tilemap-component-missing' })` for a live entity
+ *     without a Tilemap component.
+ *
+ * The caller must propagate the World so `Transform.world` is current. A
+ * singular world transform follows `mat4.invert`'s deterministic identity
+ * fallback, which keeps this error union structural rather than adding a
+ * third diagnostic arm.
+ */
+export declare function pickTile(world: World, tilemapEntity: EntityHandle, worldX: number, worldY: number): Result<PickTileHit | null, PickTileError>;
+//# sourceMappingURL=pick-tile.d.ts.map

package/dist/pick-tile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pick-tile.d.ts","sourceRoot":"","sources":["../src/pick-tile.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAU,KAAK,YAAY,EAAE,KAAK,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAI5E,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE7D;;;;GAIG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,YAAY,CAAA;CAAE,GAC5E;IAAE,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,YAAY,CAAA;CAAE,CAAC;AAEzF;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,WAAW,EAAE,YAAY,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,KAAK,EACZ,aAAa,EAAE,YAAY,EAC3B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,MAAM,CAAC,WAAW,GAAG,IAAI,EAAE,aAAa,CAAC,CAkF3C"}

package/dist/pick-vertex.d.ts

@@ -0,0 +1,87 @@
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import { type Vec3Like } from '@forgeax/engine-math';
+/**
+ * Result of a successful vertex pick: the mesh vertex nearest to the
+ * supplied screen-space coordinate.
+ *
+ * Field set:
+ *   - `entity`      — the entity this vertex belongs to.
+ *   - `vertexIndex` — index into the vertex position buffer (0-based).
+ *   - `worldPos`    — world-space position of the vertex (Vec3Like; rest-pose when
+ *                     deformed=true). D-7: Vec3Like avoids math brand cast lint in
+ *                     the runtime package.
+ *   - `screenDist`  — screen-space pixel distance from the query coordinate to the
+ *                     projected vertex position (non-negative).
+ *   - `worldDist`   — perpendicular 3D distance from the vertex world position to
+ *                     the pick ray (non-negative). Orthogonal counterpart to screenDist.
+ *   - `deformed`    — true when the mesh is skinned (skinIndex + skinWeight attributes
+ *                     both present), indicating worldPos reflects rest-pose, not GPU
+ *                     skinning output.
+ */
+export interface VertexHit {
+    readonly entity: EntityHandle;
+    readonly vertexIndex: number;
+    readonly worldPos: Vec3Like;
+    readonly screenDist: number;
+    readonly worldDist: number;
+    readonly deformed: boolean;
+}
+/**
+ * Query the nearest vertex on a single entity.
+ *
+ * Without options: returns `VertexHit | undefined` (nearest hit, or `undefined` on miss).
+ *
+ * @param world The ECS world (propagateTransforms must have been called this frame).
+ * @param cameraEntity Entity carrying the Camera component (and Transform).
+ * @param screenX Horizontal pixel coordinate (viewport top-left, y-down).
+ * @param screenY Vertical pixel coordinate.
+ * @param viewportWidth Viewport width in pixels.
+ * @param viewportHeight Viewport height in pixels.
+ * @param entity The mesh entity to query (must carry MeshFilter + MeshRenderer).
+ * @returns The nearest `VertexHit`, or `undefined` when nothing is hit.
+ * @throws {PickError} `code: 'camera-component-missing'` when cameraEntity has no Camera.
+ */
+export declare function pickVertexOnEntity(world: World, cameraEntity: EntityHandle, screenX: number, screenY: number, viewportWidth: number, viewportHeight: number, entity: EntityHandle): VertexHit | undefined;
+/**
+ * Query up to `limit` nearest vertices on a single entity.
+ *
+ * With `{ limit }`: returns `VertexHit[]` sorted by `screenDist` ascending.
+ *
+ * @param options.limit Maximum number of candidates to return (returns all available
+ *   vertices when limit exceeds the hit count).
+ * @returns Sorted array of `VertexHit` (empty on miss).
+ */
+export declare function pickVertexOnEntity(world: World, cameraEntity: EntityHandle, screenX: number, screenY: number, viewportWidth: number, viewportHeight: number, entity: EntityHandle, options: {
+    limit: number;
+}): VertexHit[];
+/**
+ * Query the nearest vertex across all pickable mesh entities in the world.
+ *
+ * Without options: returns `VertexHit | undefined` (globally nearest, or `undefined` on miss).
+ *
+ * Walks all renderable archetypes, does an AABB coarse cull (R-2), then calls
+ * `pickVertexOnEntity` on each ray-intersecting entity. Builtin meshes without AABB
+ * fall through to walk-all-vertices (AC-07).
+ *
+ * @param world The ECS world (propagateTransforms must have been called this frame).
+ * @param cameraEntity Entity carrying the Camera component (and Transform).
+ * @param screenX Horizontal pixel coordinate (viewport top-left, y-down).
+ * @param screenY Vertical pixel coordinate.
+ * @param viewportWidth Viewport width in pixels.
+ * @param viewportHeight Viewport height in pixels.
+ * @returns The globally nearest `VertexHit`, or `undefined` when nothing is hit.
+ * @throws {PickError} `code: 'camera-component-missing'` when cameraEntity has no Camera.
+ */
+export declare function pickVertex(world: World, cameraEntity: EntityHandle, screenX: number, screenY: number, viewportWidth: number, viewportHeight: number): VertexHit | undefined;
+/**
+ * Query up to `limit` nearest vertices across all pickable mesh entities.
+ *
+ * With `{ limit }`: returns `VertexHit[]` globally sorted by `screenDist` ascending.
+ *
+ * @param options.limit Maximum number of candidates to return.
+ * @returns Sorted array of `VertexHit` (empty on miss).
+ */
+export declare function pickVertex(world: World, cameraEntity: EntityHandle, screenX: number, screenY: number, viewportWidth: number, viewportHeight: number, options: {
+    limit: number;
+}): VertexHit[];
+//# sourceMappingURL=pick-vertex.d.ts.map

package/dist/pick-vertex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pick-vertex.d.ts","sourceRoot":"","sources":["../src/pick-vertex.ts"],"names":[],"mappings":"AA8CA,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAa,KAAK,QAAQ,EAAc,MAAM,sBAAsB,CAAC;AAS5E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAqTD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE,YAAY,EAC1B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,YAAY,GACnB,SAAS,GAAG,SAAS,CAAC;AAEzB;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE,YAAY,EAC1B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GACzB,SAAS,EAAE,CAAC;AAmCf;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE,YAAY,EAC1B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,GACrB,SAAS,GAAG,SAAS,CAAC;AAEzB;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE,YAAY,EAC1B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GACzB,SAAS,EAAE,CAAC"}

package/dist/pick.d.ts

@@ -0,0 +1,34 @@
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import { type Vec3Like } from '@forgeax/engine-math';
+/**
+ * Result of a successful screen-to-entity pick.
+ *
+ * Minimal three-field surface (D-6):
+ *   - `entity`   — the picked `Entity` (packed u32 handle, ready for `world.get` / `world.set`)
+ *   - `point`    — the world-space ray/AABB entry point (`Vec3Like`; a 3-element array)
+ *   - `distance` — the entry distance along the ray from the camera (>= 0)
+ *
+ * No `face` / `uv` / `normal` fields: AABB picking has no triangle resolution, so those
+ * would be a lie. A future mesh-precise pick spin-off owns them (requirements OOS).
+ */
+export interface PickHit {
+    readonly entity: EntityHandle;
+    readonly point: Vec3Like;
+    readonly distance: number;
+}
+/**
+ * Raycast from a viewport-relative screen coordinate into the world and return the
+ * nearest pickable mesh entity whose world-space AABB the ray enters.
+ *
+ * @param world The ECS world holding the camera + candidate mesh entities (and the
+ *   per-World SharedRefStore that owns each `MeshAsset` and its local-space `aabb`).
+ * @param cameraEntity The entity carrying the `Camera` component (and a Transform).
+ * @param screenX Horizontal pixel coordinate relative to the viewport top-left (y-down).
+ * @param screenY Vertical pixel coordinate.
+ * @param viewportWidth Viewport width in pixels.
+ * @param viewportHeight Viewport height in pixels.
+ * @returns The nearest `PickHit`, or `undefined` when the ray hits nothing.
+ * @throws {PickError} `code: 'camera-component-missing'` when `cameraEntity` has no `Camera`.
+ */
+export declare function pick(world: World, cameraEntity: EntityHandle, screenX: number, screenY: number, viewportWidth: number, viewportHeight: number): PickHit | undefined;
+//# sourceMappingURL=pick.d.ts.map

package/dist/pick.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pick.d.ts","sourceRoot":"","sources":["../src/pick.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAa,KAAK,QAAQ,EAAQ,MAAM,sBAAsB,CAAC;AAOtE;;;;;;;;;;GAUG;AACH,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,IAAI,CAClB,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE,YAAY,EAC1B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,GACrB,OAAO,GAAG,SAAS,CAkErB"}

package/dist/viewport-to-world.d.ts

@@ -0,0 +1,12 @@
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import type { ray } from '@forgeax/engine-math';
+/**
+ * Unproject a viewport pixel into a world-space ray.
+ *
+ * `screenX`/`screenY` use the canvas convention: top-left origin, y down.
+ * The caller must run `propagateTransforms(world)` for the current frame first.
+ * A camera without a resolvable Transform returns `undefined`; a missing
+ * Camera component throws the package's structured `PickError`.
+ */
+export declare function viewportToWorld(world: World, cameraEntity: EntityHandle, screenX: number, screenY: number, viewportWidth: number, viewportHeight: number): ray.Ray | undefined;
+//# sourceMappingURL=viewport-to-world.d.ts.map

package/dist/viewport-to-world.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewport-to-world.d.ts","sourceRoot":"","sources":["../src/viewport-to-world.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAGhD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE,YAAY,EAC1B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,GACrB,GAAG,CAAC,GAAG,GAAG,SAAS,CAGrB"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@forgeax/engine-picking",
+  "version": "0.0.0-dev.8d955ade1c79",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Screen-to-entity + vertex-level + tile-cell picking free functions for forgeax-engine (Tier 2.2 -- extracted from @forgeax/engine-runtime).",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-assets-runtime": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-ecs": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-math": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-render": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-runtime": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-scene": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-types": "0.0.0-dev.8d955ade1c79"
+  },
+  "devDependencies": {
+    "@forgeax/engine-pack": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-shader": "0.0.0-dev.8d955ade1c79"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "picking is a query library invoked on demand (click / hover), not a per-frame canvas; fps reported by hello-picking that consumes it"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "picking runs at interaction time (ray-AABB / ray-triangle per query), not per-frame; no CI micro-benchmark warranted"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "no package-level binary gate; smoke gate covered by hello-picking dawn smoke that exercises the pick contract"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package; picking cluster extracted from runtime in feat-20260705-runtime-tier2-decomposition"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/glyph-text-pick.test.ts

@@ -0,0 +1,132 @@
+// glyph-text-pick.test.ts — pick() hits a baked GlyphText entity (AC-13).
+//
+// Extracted from packages/runtime/src/__tests__/text.unit.test.ts (the
+// "from glyph-text-pick.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), so this cross-cutting test (glyph text bake + pick)
+// lives in the downstream picking package that depends on runtime.
+
+import { type EntityHandle, World } from '@forgeax/engine-ecs';
+import { CAMERA_PROJECTION_PERSPECTIVE, Camera } from '@forgeax/engine-render';
+import { GlyphText } from '@forgeax/engine-render/authoring';
+import { propagateTransforms, Transform } from '@forgeax/engine-scene';
+import type { FontAsset, GlyphMetric, Handle } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { GpuResidencyCache } from '../../../render/src/device/gpu-residency';
+import {
+  glyphTextLayoutSystem,
+  resetGlyphBakeCache,
+} from '../../../render/src/glyph-text-layout-system';
+import { pick } from '../pick';
+
+describe('glyph-text-pick', () => {
+  // Pick tests do not wire a GPU device; the residency store stays CPU-only.
+  const gpuStore = new GpuResidencyCache();
+
+  const VP = 600;
+
+  function metric(): GlyphMetric {
+    return {
+      advance: 10,
+      bearingX: 0,
+      bearingY: 8,
+      size: { w: 8, h: 8 },
+      region: { x: 0, y: 0, w: 8, h: 8 },
+    };
+  }
+
+  function registerFont(world: World, chars: string): number {
+    const glyphs: Record<number, GlyphMetric> = {};
+    for (const ch of chars) glyphs[ch.codePointAt(0) as number] = metric();
+    const font: FontAsset = {
+      kind: 'font',
+      atlas: 0 as never,
+      sampler: 0 as never,
+      glyphs,
+      common: {
+        lineHeight: 12,
+        base: 8,
+        distanceRange: 4,
+        pxRange: 4,
+        atlasWidth: 64,
+        atlasHeight: 64,
+      },
+    };
+    return world.allocSharedRef('FontAsset', font) as unknown as number;
+  }
+
+  function makeWorld(): World {
+    const world = new World();
+    return world;
+  }
+
+  function spawnCamera(world: World, z: number): EntityHandle {
+    return world
+      .spawn(
+        {
+          component: Transform,
+          data: {
+            pos: [0, 0, z],
+            quat: [0, 0, 0, 1],
+            scale: [1, 1, 1],
+          },
+        },
+        {
+          component: Camera,
+          data: {
+            fov: Math.PI / 4,
+            aspect: 1,
+            near: 0.1,
+            far: 100,
+            projection: CAMERA_PROJECTION_PERSPECTIVE,
+            left: -1,
+            right: 1,
+            bottom: -1,
+            top: 1,
+          },
+        },
+      )
+      .unwrap();
+  }
+
+  function spawnLabel(world: World, fontId: number): EntityHandle {
+    return world
+      .spawn(
+        {
+          component: Transform,
+          data: {
+            pos: [0, 0, 0],
+            quat: [0, 0, 0, 1],
+            scale: [1, 1, 1],
+          },
+        },
+        {
+          component: GlyphText,
+          data: {
+            fontHandle: fontId as unknown as Handle<'FontAsset', 'shared'>,
+            text: 'Hi',
+            fontSize: 1,
+            color: [1, 1, 1, 1],
+          },
+        },
+      )
+      .unwrap();
+  }
+
+  describe('glyph text pick (AC-13, pick.ts unchanged)', () => {
+    it('(d) center-viewport ray hits the baked text entity', () => {
+      resetGlyphBakeCache();
+      const world = makeWorld();
+      const fontId = registerFont(world, 'Hi');
+      const camera = spawnCamera(world, 5);
+      const label = spawnLabel(world, fontId);
+
+      glyphTextLayoutSystem(world, gpuStore); // bake + attach MeshFilter + MeshRenderer
+      propagateTransforms(world);
+
+      const hit = pick(world, camera, VP / 2, VP / 2, VP, VP);
+      expect(hit).toBeDefined();
+      expect(hit?.entity).toBe(label);
+    });
+  });
+});

package/src/__tests__/helpers/mock-shader-registry.ts

@@ -0,0 +1,118 @@
+// Shared test helper: minimal mock ShaderRegistry for AssetRegistry constructor.
+// feat-20260527-material-registration-unification M1 / w4.
+//
+// All tests that create AssetRegistry directly must pass a ShaderRegistry
+// since the constructor parameter became required in w1. This helper
+// provides a zero-config mock that satisfies the constructor signature
+// without requiring a real GPU device.
+
+import { ShaderRegistry, type ShaderRegistryDevice } from '@forgeax/engine-shader';
+
+export function makeMockShaderRegistry(): ShaderRegistry {
+  const mockDevice: ShaderRegistryDevice = {
+    createShaderModule() {
+      return {
+        ok: true,
+        value: undefined,
+        unwrap: () => undefined,
+        unwrapOr: (d: unknown) => d,
+      } as unknown as ReturnType<ShaderRegistryDevice['createShaderModule']>;
+    },
+  };
+  const sr = new ShaderRegistry({
+    device: mockDevice,
+    manifestUrl: undefined,
+  });
+  // Register a default test shader so M2 tests can validate against it.
+  sr.installMaterialArtifact('test::standard', {
+    source: 'fn main() {}',
+    paramSchema: [
+      { name: 'baseColor', type: 'color' },
+      { name: 'metallic', type: 'f32' },
+      { name: 'roughness', type: 'f32' },
+    ],
+  });
+  sr.installMaterialArtifact('test::unlit', {
+    source: 'fn main() {}',
+    paramSchema: [
+      { name: 'baseColor', type: 'color' },
+      { name: 'baseColorTexture', type: 'texture2d' },
+      { name: 'sampler', type: 'sampler', default: null },
+      { name: 'lightIntensity', type: 'f32' }, // required — no default
+    ],
+  });
+  // Register the engine-shipped default-standard-pbr shader so tests
+  // that use it pass the register-time validation gate (M2 / w6).
+  // paramSchema mirrors packages/shader/src/default-standard-pbr.schema.json.
+  sr.installMaterialArtifact('forgeax::default-standard-pbr', {
+    source: 'fn main() {}',
+    paramSchema: [
+      { name: 'baseColor', type: 'color', default: [1.0, 1.0, 1.0, 1.0] },
+      { name: 'metallic', type: 'f32', default: 0.0 },
+      { name: 'roughness', type: 'f32', default: 0.5 },
+      // feat-20260613 fix-issue-1 (D-8): channelMap split into 4 f32 selectors.
+      { name: 'metallicChannel', type: 'f32', default: 2.0 },
+      { name: 'roughnessChannel', type: 'f32', default: 1.0 },
+      { name: 'aoChannel', type: 'f32', default: 0.0 },
+      { name: 'extraChannel', type: 'f32', default: 0.0 },
+      { name: 'emissive', type: 'vec3', default: [0.0, 0.0, 0.0] },
+      { name: 'emissiveIntensity', type: 'f32', default: 0.0 },
+      { name: 'occlusionStrength', type: 'f32', default: 1.0 },
+      { name: 'baseColorTexture', type: 'texture2d' },
+      { name: 'metallicRoughnessTexture', type: 'texture2d' },
+      { name: 'normalTexture', type: 'texture2d' },
+    ],
+  });
+  sr.installMaterialArtifact('forgeax::default-unlit', {
+    source: 'fn main() {}',
+    paramSchema: [
+      { name: 'baseColor', type: 'color' },
+      { name: 'baseColorTexture', type: 'texture2d' },
+      { name: 'sampler', type: 'sampler', default: null },
+    ],
+  });
+  // test::dummy used by M1 test (c)
+  sr.installMaterialArtifact('test::dummy', {
+    source: 'fn main() {}',
+    paramSchema: [],
+  });
+  // forgeax::msdf-text used by the glyph layout system (feat-20260531 F-1).
+  // paramSchema mirrors packages/shader/src/msdf-text.material.json so the
+  // layout system's per-font MaterialAsset register passes validation in the
+  // GPU-less unit tests.
+  sr.installMaterialArtifact('forgeax::msdf-text', {
+    source: 'fn main() {}',
+    paramSchema: [
+      { name: 'tintColor', type: 'color', default: [1.0, 1.0, 1.0, 1.0] },
+      { name: 'distanceRange', type: 'f32', default: 4.0 },
+      { name: 'baseColorTexture', type: 'texture2d' },
+      { name: 'sampler', type: 'sampler', default: null },
+    ],
+  });
+  // feat-20260609-pipeline-driven-pass-selector-shadowcaster-via-mat M3 / T-007:
+  // forgeax::default-shadow-caster — vertex-only depth pass shader for
+  // directional shadow maps. Registered as the 6th built-in material shader.
+  sr.installMaterialArtifact('forgeax::default-shadow-caster', {
+    source: 'fn main() {}',
+    paramSchema: [],
+  });
+  // feat-20260608-tilemap-object-layer-rendering M0 baseline rebuild:
+  // forgeax::sprite registered in the mock so resolveTilesetMaterial inside
+  // tilemap-chunk-extract-system can register a per-tile material in unit
+  // tests (paramSchema mirrors packages/shader/src/sprite.material.json).
+  sr.installMaterialArtifact('forgeax::sprite', {
+    source: 'fn main() {}',
+    paramSchema: [
+      { name: 'baseColor', type: 'color', default: [1.0, 1.0, 1.0, 1.0] },
+      { name: 'texture', type: 'texture2d' },
+      { name: 'sampler', type: 'sampler', default: null },
+      { name: 'region', type: 'vec4', default: [0.0, 0.0, 1.0, 1.0] },
+      { name: 'pivot', type: 'vec2', default: [0.5, 0.5] },
+      { name: 'flipX', type: 'f32', default: 0.0 },
+      { name: 'flipY', type: 'f32', default: 0.0 },
+      { name: 'slices', type: 'vec4', default: [0.0, 0.0, 0.0, 0.0] },
+      { name: 'sliceMode', type: 'f32', default: 0.0 },
+    ],
+  });
+  return sr;
+}