@forgeax/engine-picking 0.1.2

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":"AA6CA,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAa,KAAK,QAAQ,EAAc,MAAM,sBAAsB,CAAC;AAU5E;;;;;;;;;;;;;;;;;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":"AAkCA,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAa,KAAK,QAAQ,EAAQ,MAAM,sBAAsB,CAAC;AAQtE;;;;;;;;;;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.1.2",
+  "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-ecs": "0.1.2",
+    "@forgeax/engine-math": "0.1.2",
+    "@forgeax/engine-render": "0.1.2",
+    "@forgeax/engine-runtime": "0.1.2",
+    "@forgeax/engine-scene": "0.1.2",
+    "@forgeax/engine-types": "0.1.2"
+  },
+  "devDependencies": {
+    "@forgeax/engine-geometry": "0.1.2",
+    "@forgeax/engine-pack": "0.1.2",
+    "@forgeax/engine-shader": "0.1.2"
+  },
+  "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,131 @@
+// 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,
+  glyphTextLayoutSystem,
+  resetGlyphBakeCache,
+} from '@forgeax/engine-render/authoring';
+import { GpuResourceStore } from '@forgeax/engine-render/internal';
+import { Transform } from '@forgeax/engine-scene';
+import type { FontAsset, GlyphMetric, Handle } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+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 GpuResourceStore();
+
+  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
+
+      const hit = pick(world, camera, VP / 2, VP / 2, VP, VP);
+      expect(hit).toBeDefined();
+      expect(hit?.entity).toBe(label);
+    });
+  });
+});

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 });
+    });
+  });
+});