@forgeax/engine-debug-draw 0.1.2

package/src/errors.ts

@@ -0,0 +1,142 @@
+// @forgeax/engine-debug-draw -- error model SSOT (feat-20260615-debug-draw M1 / w2)
+//
+// Closed union DebugDrawErrorCode, discriminated detail union,
+// and structured DebugDrawError carrying .code / .expected / .hint / .detail.
+//
+// Decision anchors:
+// - plan-strategy D-11: destroy-then-flush returns Result.err, shape calls no-op + warn once
+// - requirements sec 3.6: error code closed union 4 members
+// - AGENTS.md Error model: structured errors with .expected / .hint, never throw
+// - architecture-principles #5 Fail Fast: validate at entry, non-conforming data never flows downstream
+
+import { err, type Result } from '@forgeax/engine-types';
+
+/** {@link pipeline-create-failed} payload: carries the RHI-level error detail. */
+export interface PipelineCreateFailedDetail {
+  readonly code: 'pipeline-create-failed';
+  readonly rhiError: string;
+}
+
+/** {@link buffer-allocation-failed} payload: carries the RHI-level error detail. */
+export interface BufferAllocationFailedDetail {
+  readonly code: 'buffer-allocation-failed';
+  readonly rhiError: string;
+}
+
+/** {@link flushed-after-destroy} payload: carries the instance identifier. */
+export interface FlushedAfterDestroyDetail {
+  readonly code: 'flushed-after-destroy';
+}
+
+/** {@link viewProj-required} payload: carries the missing parameter name. */
+export interface ViewProjRequiredDetail {
+  readonly code: 'viewProj-required';
+}
+
+interface DebugDrawErrorDetailByCode {
+  'pipeline-create-failed': PipelineCreateFailedDetail;
+  'buffer-allocation-failed': BufferAllocationFailedDetail;
+  'flushed-after-destroy': FlushedAfterDestroyDetail;
+  'viewProj-required': ViewProjRequiredDetail;
+}
+
+/**
+ * Closed {@link DebugDrawErrorCode} union.
+ * Exhaustive `switch (err.code)` needs no default fallback.
+ *
+ * | code | trigger |
+ * |:--|:--|
+ * | `'pipeline-create-failed'` | `device.createRenderPipeline(...)` rejected or threw |
+ * | `'buffer-allocation-failed'` | `device.createBuffer(...)` for GPU vbo allocation failed |
+ * | `'flushed-after-destroy'` | `flush()` called on an already-destroyed DebugDraw instance |
+ * | `'viewProj-required'` | `flush()` called with `undefined` or missing `viewProj` |
+ */
+export type DebugDrawErrorCode = keyof DebugDrawErrorDetailByCode;
+
+/**
+ * Discriminated detail union for {@link DebugDrawError}, narrowed per
+ * `DebugDrawError.code`. AI users obtain the concrete shape via
+ * `switch (err.code)` without a fallback `as` cast.
+ */
+export type DebugDrawErrorDetail = DebugDrawErrorDetailByCode[DebugDrawErrorCode];
+
+/**
+ * Structured debug-draw error -- four-field surface
+ * (`.code` / `.expected` / `.hint` / `.detail`).
+ *
+ * AI users consume the structured triple by fields, not by parsing `.message`.
+ */
+type DebugDrawErrorVariant<C extends DebugDrawErrorCode> = {
+  readonly code: C;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: DebugDrawErrorDetailByCode[C];
+};
+
+export type DebugDrawError = {
+  [C in DebugDrawErrorCode]: DebugDrawErrorVariant<C>;
+}[DebugDrawErrorCode];
+
+function makeError<C extends DebugDrawErrorCode>(
+  code: C,
+  expected: string,
+  hint: string,
+  detail: DebugDrawErrorDetailByCode[C],
+): DebugDrawErrorVariant<C> {
+  const error = {
+    code,
+    expected,
+    hint,
+    detail,
+    get message(): string {
+      return `[${code}] ${hint}`;
+    },
+  };
+  return error;
+}
+
+/** Result-returning helpers consuming engine-types `Result<T, E>` + `err()`. */
+
+export function pipelineCreateFailed(rhiError: string): Result<never, DebugDrawError> {
+  return err(
+    makeError(
+      'pipeline-create-failed',
+      'PSO creation should succeed with valid WGSL + layout',
+      `Pipeline creation failed: ${rhiError}. Check WGSL syntax, vertex layout, and depth-stencil state.`,
+      { code: 'pipeline-create-failed', rhiError },
+    ),
+  );
+}
+
+export function bufferAllocationFailed(rhiError: string): Result<never, DebugDrawError> {
+  return err(
+    makeError(
+      'buffer-allocation-failed',
+      'GPU vertex buffer allocation should succeed for the requested byte size',
+      `Buffer allocation failed: ${rhiError}. Check available device memory and buffer usage flags.`,
+      { code: 'buffer-allocation-failed', rhiError },
+    ),
+  );
+}
+
+export function flushedAfterDestroy(): Result<never, DebugDrawError> {
+  return err(
+    makeError(
+      'flushed-after-destroy',
+      'DebugDraw instance is alive and not yet destroyed',
+      'DebugDraw was destroyed; create a new instance via createDebugDraw().',
+      { code: 'flushed-after-destroy' },
+    ),
+  );
+}
+
+export function viewProjRequired(): Result<never, DebugDrawError> {
+  return err(
+    makeError(
+      'viewProj-required',
+      'viewProj must be provided as a Mat4 for flush to transform vertices',
+      'Pass a viewProj Mat4 to flush(encoder, view, viewProj).',
+      { code: 'viewProj-required' },
+    ),
+  );
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+// @forgeax/engine-debug-draw -- public barrel (feat-20260615-debug-draw-immediate-mode M1/M2)
+//
+// Single-entry surface: createDebugDraw factory + DebugDraw class + DebugDrawErrorCode
+// closed union. Shape API (line / sphere / aabb / frustum) + flush are available
+// on the returned DebugDraw instance.
+
+export { INITIAL_VERTEX_CAPACITY, MAX_VERTEX_CAPACITY, VERTEX_STRIDE_BYTES } from './constants';
+export { createDebugDraw, DebugDraw } from './debug-draw';
+export type {
+  DebugDrawError,
+  DebugDrawErrorCode,
+  DebugDrawErrorDetail,
+} from './errors';
+export type { CreateShaderModule, DebugDrawOptions, DepthMode } from './types';

package/src/shapes/aabb.ts

@@ -0,0 +1,57 @@
+// @forgeax/engine-debug-draw -- aabb shape geometry (M3 / w20)
+//
+// Pure geometry decomposition: 12 edges (24 vertices) from 8 corners.
+// No staging / GPU concerns; consumed by DebugDraw class.
+
+import type { Vec3 } from '@forgeax/engine-math';
+
+function a(v: { readonly [index: number]: number }, i: number): number {
+  return v[i] as number;
+}
+
+/** 24 vertices forming a wireframe axis-aligned bounding box (12 edges). */
+export function aabbVertices(min: Vec3, max: Vec3): [number, number, number][] {
+  const mnx = a(min, 0);
+  const mny = a(min, 1);
+  const mnz = a(min, 2);
+  const mxx = a(max, 0);
+  const mxy = a(max, 1);
+  const mxz = a(max, 2);
+
+  // 8 corners: x in {mnx, mxx}, y in {mny, mxy}, z in {mnz, mxz}
+  const c: [number, number, number][] = [
+    [mnx, mny, mnz], // 0
+    [mxx, mny, mnz], // 1
+    [mnx, mxy, mnz], // 2
+    [mxx, mxy, mnz], // 3
+    [mnx, mny, mxz], // 4
+    [mxx, mny, mxz], // 5
+    [mnx, mxy, mxz], // 6
+    [mxx, mxy, mxz], // 7
+  ];
+
+  // 12 edges
+  const edges: [number, number][] = [
+    [0, 1],
+    [0, 2],
+    [1, 3],
+    [2, 3],
+    [4, 5],
+    [4, 6],
+    [5, 7],
+    [6, 7],
+    [0, 4],
+    [1, 5],
+    [2, 6],
+    [3, 7],
+  ];
+
+  const result: [number, number, number][] = [];
+  for (const [ai, bi] of edges) {
+    const ac = c[ai] as [number, number, number];
+    const bc = c[bi] as [number, number, number];
+    result.push([ac[0], ac[1], ac[2]]);
+    result.push([bc[0], bc[1], bc[2]]);
+  }
+  return result;
+}

package/src/shapes/arrow.ts

@@ -0,0 +1,75 @@
+// @forgeax/engine-debug-draw -- arrow shape geometry (solo round 20260713-222551)
+//
+// Pure geometry decomposition: an arrow = 1 body segment (start->end) + 4 arrowhead
+// segments from `end` back toward 4 canonical tip vectors, rotated so local +X aligns
+// with the arrow's direction. Mirrors Bevy `bevy_gizmos::arrows` ArrowBuilder::drop.
+// No staging / GPU concerns; consumed by the DebugDraw class.
+
+import type { Vec3Like } from '@forgeax/engine-math';
+import { quat, vec3 } from '@forgeax/engine-math';
+
+// The 4 arrowhead tip directions in the arrow's local frame (arrow points toward +X),
+// matching Bevy's tips array. Normalized when scaled to tipLength.
+const TIP_DIRS: ReadonlyArray<readonly [number, number, number]> = [
+  [-1, 1, 0],
+  [-1, 0, 1],
+  [-1, -1, 0],
+  [-1, 0, -1],
+];
+
+// Plain Vec3Like (not a branded Vec3) — `quat.fromUnitVectors` accepts Vec3Like, so no
+// cross-boundary brand cast is needed (brand-cast lint: casts live only in math factories).
+const UNIT_X: Vec3Like = [1, 0, 0];
+
+/**
+ * Line-segment vertices for an arrow from `start` to `end`.
+ * Returns 10 vertices = 5 segments (1 body + 4 arrowhead), each a [x,y,z] pair
+ * consumed pairwise by the line-list renderer.
+ *
+ * `tipLength` defaults to `|end - start| / 10` (Bevy's default arrowhead length).
+ * A degenerate (zero-length) arrow emits only the body segment (no orientable head).
+ */
+export function arrowVertices(
+  start: Vec3Like,
+  end: Vec3Like,
+  tipLength?: number,
+): [number, number, number][] {
+  const sx = start[0] as number;
+  const sy = start[1] as number;
+  const sz = start[2] as number;
+  const ex = end[0] as number;
+  const ey = end[1] as number;
+  const ez = end[2] as number;
+
+  const verts: [number, number, number][] = [
+    [sx, sy, sz],
+    [ex, ey, ez],
+  ];
+
+  const dir = vec3.create();
+  vec3.set(dir, ex - sx, ey - sy, ez - sz);
+  const len = vec3.length(dir);
+  if (len < 1e-6) return verts; // degenerate: no orientable head
+
+  const headLen = tipLength ?? len / 10;
+  vec3.normalize(dir, dir);
+
+  // Rotate the local-frame tip vectors so +X faces the arrow direction.
+  const rot = quat.fromUnitVectors(quat.create(), UNIT_X, dir);
+  const tipLocal = vec3.create();
+  const tipWorld = vec3.create();
+  for (const [tx, ty, tz] of TIP_DIRS) {
+    vec3.set(tipLocal, tx, ty, tz);
+    vec3.normalize(tipLocal, tipLocal);
+    vec3.scale(tipLocal, tipLocal, headLen);
+    quat.transformVec3(tipWorld, rot, tipLocal);
+    // Head segment: from the arrow tip (end) back out to the rotated tip vector.
+    verts.push([ex, ey, ez]);
+    verts.push([
+      ex + (tipWorld[0] as number),
+      ey + (tipWorld[1] as number),
+      ez + (tipWorld[2] as number),
+    ]);
+  }
+  return verts;
+}

package/src/shapes/axes.ts

@@ -0,0 +1,60 @@
+// @forgeax/engine-debug-draw -- axes gizmo geometry (solo round 20260713-222551)
+//
+// Draws a transform's local coordinate frame as three arrows (X / Y / Z), matching
+// Bevy `gizmos.axes(transform, base_length)`. Each axis endpoint is
+// `translation + base_length * column_i` of the world matrix — i.e. Bevy's
+// `transform.transform_point(base_length * Vec3::AXIS)` (the world-space direction the
+// local axis points, scale included). Colors follow the universal convention:
+// X = red, Y = green, Z = blue. No staging / GPU concerns; consumed by the DebugDraw class.
+
+import type { Mat4, Vec3Like } from '@forgeax/engine-math';
+import { arrowVertices } from './arrow';
+
+/** X=red, Y=green, Z=blue RGBA (Bevy's axes convention). */
+export const AXES_COLORS: readonly [
+  readonly [number, number, number, number],
+  readonly [number, number, number, number],
+  readonly [number, number, number, number],
+] = [
+  [1, 0, 0, 1],
+  [0, 1, 0, 1],
+  [0, 0, 1, 1],
+];
+
+/**
+ * The three axis arrows for a world transform, as `{ vertices, color }` per axis
+ * (X, Y, Z). The caller (DebugDraw.axes) pushes each with its color. `worldMat` is a
+ * 16-float column-major mat4; the arrows originate at its translation (col 3) and point
+ * `length` along its local X / Y / Z (columns 0 / 1 / 2, scale included, matching Bevy).
+ */
+export function axesArrowSets(
+  worldMat: Mat4,
+  length: number,
+): { vertices: [number, number, number][]; color: readonly [number, number, number, number] }[] {
+  const m = worldMat as unknown as ArrayLike<number>;
+  const ox = m[12] as number;
+  const oy = m[13] as number;
+  const oz = m[14] as number;
+  // Plain Vec3Like tuples (not branded Vec3) — arrowVertices accepts Vec3Like, so no
+  // cross-boundary brand cast is needed (brand-cast lint: casts live only in math factories).
+  const origin: Vec3Like = [ox, oy, oz];
+
+  // Columns 0/1/2 are the local X/Y/Z basis in world space (rotation * scale).
+  const cols: ReadonlyArray<readonly [number, number, number]> = [
+    [m[0] as number, m[1] as number, m[2] as number],
+    [m[4] as number, m[5] as number, m[6] as number],
+    [m[8] as number, m[9] as number, m[10] as number],
+  ];
+
+  const sets: {
+    vertices: [number, number, number][];
+    color: readonly [number, number, number, number];
+  }[] = [];
+  for (let i = 0; i < 3; i++) {
+    const c = cols[i] as readonly [number, number, number];
+    const color = AXES_COLORS[i] as readonly [number, number, number, number];
+    const end: Vec3Like = [ox + c[0] * length, oy + c[1] * length, oz + c[2] * length];
+    sets.push({ vertices: arrowVertices(origin, end), color });
+  }
+  return sets;
+}

package/src/shapes/frustum.ts

@@ -0,0 +1,182 @@
+// @forgeax/engine-debug-draw -- frustum shape geometry (M3 / w21)
+//
+// Pure geometry decomposition: invert viewProj matrix, transform 8 NDC
+// corners to world space, draw 12 edges (24 vertices).
+// Returns null when the viewProj is near-singular (determinant ~ 0).
+// No staging / GPU concerns; consumed by DebugDraw class.
+
+import { type Mat4, mat4 } from '@forgeax/engine-math';
+
+function at(m: { readonly [index: number]: number }, i: number): number {
+  return m[i] as number;
+}
+
+/**
+ * Generate 24 vertices (12 edges) for a frustum wireframe from a view-projection matrix.
+ * Returns null if the matrix is near-singular (|det| < 1e-10).
+ */
+export function frustumVertices(viewProj: Mat4): [number, number, number][] | null {
+  const m = viewProj;
+
+  // 4x4 determinant
+  const det =
+    at(m, 0) *
+      (at(m, 5) * (at(m, 10) * at(m, 15) - at(m, 14) * at(m, 11)) -
+        at(m, 9) * (at(m, 6) * at(m, 15) - at(m, 14) * at(m, 7)) +
+        at(m, 13) * (at(m, 6) * at(m, 11) - at(m, 10) * at(m, 7))) -
+    at(m, 4) *
+      (at(m, 1) * (at(m, 10) * at(m, 15) - at(m, 14) * at(m, 11)) -
+        at(m, 9) * (at(m, 2) * at(m, 15) - at(m, 14) * at(m, 3)) +
+        at(m, 13) * (at(m, 2) * at(m, 11) - at(m, 10) * at(m, 3))) +
+    at(m, 8) *
+      (at(m, 1) * (at(m, 6) * at(m, 15) - at(m, 14) * at(m, 7)) -
+        at(m, 5) * (at(m, 2) * at(m, 15) - at(m, 14) * at(m, 3)) +
+        at(m, 13) * (at(m, 2) * at(m, 7) - at(m, 6) * at(m, 3))) -
+    at(m, 12) *
+      (at(m, 1) * (at(m, 6) * at(m, 11) - at(m, 10) * at(m, 7)) -
+        at(m, 5) * (at(m, 2) * at(m, 11) - at(m, 10) * at(m, 3)) +
+        at(m, 9) * (at(m, 2) * at(m, 7) - at(m, 6) * at(m, 3)));
+
+  if (Math.abs(det) < 1e-10) {
+    return null;
+  }
+
+  // 4x4 inverse via cofactor expansion
+  const invDet = 1.0 / det;
+  const inv = mat4.create();
+  inv[0] =
+    (at(m, 5) * (at(m, 10) * at(m, 15) - at(m, 14) * at(m, 11)) -
+      at(m, 9) * (at(m, 6) * at(m, 15) - at(m, 14) * at(m, 7)) +
+      at(m, 13) * (at(m, 6) * at(m, 11) - at(m, 10) * at(m, 7))) *
+    invDet;
+  inv[1] =
+    -(
+      at(m, 1) * (at(m, 10) * at(m, 15) - at(m, 14) * at(m, 11)) -
+      at(m, 9) * (at(m, 2) * at(m, 15) - at(m, 14) * at(m, 3)) +
+      at(m, 13) * (at(m, 2) * at(m, 11) - at(m, 10) * at(m, 3))
+    ) * invDet;
+  inv[2] =
+    (at(m, 1) * (at(m, 6) * at(m, 15) - at(m, 14) * at(m, 7)) -
+      at(m, 5) * (at(m, 2) * at(m, 15) - at(m, 14) * at(m, 3)) +
+      at(m, 13) * (at(m, 2) * at(m, 7) - at(m, 6) * at(m, 3))) *
+    invDet;
+  inv[3] =
+    -(
+      at(m, 1) * (at(m, 6) * at(m, 11) - at(m, 10) * at(m, 7)) -
+      at(m, 5) * (at(m, 2) * at(m, 11) - at(m, 10) * at(m, 3)) +
+      at(m, 9) * (at(m, 2) * at(m, 7) - at(m, 6) * at(m, 3))
+    ) * invDet;
+  inv[4] =
+    -(
+      at(m, 4) * (at(m, 10) * at(m, 15) - at(m, 14) * at(m, 11)) -
+      at(m, 8) * (at(m, 6) * at(m, 15) - at(m, 14) * at(m, 7)) +
+      at(m, 12) * (at(m, 6) * at(m, 11) - at(m, 10) * at(m, 7))
+    ) * invDet;
+  inv[5] =
+    (at(m, 0) * (at(m, 10) * at(m, 15) - at(m, 14) * at(m, 11)) -
+      at(m, 8) * (at(m, 2) * at(m, 15) - at(m, 14) * at(m, 3)) +
+      at(m, 12) * (at(m, 2) * at(m, 11) - at(m, 10) * at(m, 3))) *
+    invDet;
+  inv[6] =
+    -(
+      at(m, 0) * (at(m, 6) * at(m, 15) - at(m, 14) * at(m, 7)) -
+      at(m, 4) * (at(m, 2) * at(m, 15) - at(m, 14) * at(m, 3)) +
+      at(m, 12) * (at(m, 2) * at(m, 7) - at(m, 6) * at(m, 3))
+    ) * invDet;
+  inv[7] =
+    (at(m, 0) * (at(m, 6) * at(m, 11) - at(m, 10) * at(m, 7)) -
+      at(m, 4) * (at(m, 2) * at(m, 11) - at(m, 10) * at(m, 3)) +
+      at(m, 8) * (at(m, 2) * at(m, 7) - at(m, 6) * at(m, 3))) *
+    invDet;
+  inv[8] =
+    (at(m, 4) * (at(m, 9) * at(m, 15) - at(m, 13) * at(m, 11)) -
+      at(m, 8) * (at(m, 5) * at(m, 15) - at(m, 13) * at(m, 7)) +
+      at(m, 12) * (at(m, 5) * at(m, 11) - at(m, 9) * at(m, 7))) *
+    invDet;
+  inv[9] =
+    -(
+      at(m, 0) * (at(m, 9) * at(m, 15) - at(m, 13) * at(m, 11)) -
+      at(m, 8) * (at(m, 1) * at(m, 15) - at(m, 13) * at(m, 3)) +
+      at(m, 12) * (at(m, 1) * at(m, 11) - at(m, 9) * at(m, 3))
+    ) * invDet;
+  inv[10] =
+    (at(m, 0) * (at(m, 5) * at(m, 15) - at(m, 13) * at(m, 7)) -
+      at(m, 4) * (at(m, 1) * at(m, 15) - at(m, 13) * at(m, 3)) +
+      at(m, 12) * (at(m, 1) * at(m, 7) - at(m, 5) * at(m, 3))) *
+    invDet;
+  inv[11] =
+    -(
+      at(m, 0) * (at(m, 5) * at(m, 11) - at(m, 9) * at(m, 7)) -
+      at(m, 4) * (at(m, 1) * at(m, 11) - at(m, 9) * at(m, 3)) +
+      at(m, 8) * (at(m, 1) * at(m, 7) - at(m, 5) * at(m, 3))
+    ) * invDet;
+  inv[12] =
+    -(
+      at(m, 4) * (at(m, 9) * at(m, 14) - at(m, 13) * at(m, 10)) -
+      at(m, 8) * (at(m, 5) * at(m, 14) - at(m, 13) * at(m, 6)) +
+      at(m, 12) * (at(m, 5) * at(m, 10) - at(m, 9) * at(m, 6))
+    ) * invDet;
+  inv[13] =
+    (at(m, 0) * (at(m, 9) * at(m, 14) - at(m, 13) * at(m, 10)) -
+      at(m, 8) * (at(m, 1) * at(m, 14) - at(m, 13) * at(m, 2)) +
+      at(m, 12) * (at(m, 1) * at(m, 10) - at(m, 9) * at(m, 2))) *
+    invDet;
+  inv[14] =
+    -(
+      at(m, 0) * (at(m, 5) * at(m, 14) - at(m, 13) * at(m, 6)) -
+      at(m, 4) * (at(m, 1) * at(m, 14) - at(m, 13) * at(m, 2)) +
+      at(m, 12) * (at(m, 1) * at(m, 6) - at(m, 5) * at(m, 2))
+    ) * invDet;
+  inv[15] =
+    (at(m, 0) * (at(m, 5) * at(m, 10) - at(m, 9) * at(m, 6)) -
+      at(m, 4) * (at(m, 1) * at(m, 10) - at(m, 9) * at(m, 2)) +
+      at(m, 8) * (at(m, 1) * at(m, 6) - at(m, 5) * at(m, 2))) *
+    invDet;
+
+  // 8 NDC corners: x,y in {-1,1}, z in [0,1] (WebGPU NDC, matches mat4.perspective).
+  // Near plane = z=0, far plane = z=1.
+  const ndc: [number, number, number, number][] = [
+    [-1, -1, 0, 1],
+    [1, -1, 0, 1],
+    [-1, 1, 0, 1],
+    [1, 1, 0, 1],
+    [-1, -1, 1, 1],
+    [1, -1, 1, 1],
+    [-1, 1, 1, 1],
+    [1, 1, 1, 1],
+  ];
+
+  const corners: [number, number, number][] = ndc.map(([nx, ny, nz, nw]) => {
+    const cx = at(inv, 0) * nx + at(inv, 4) * ny + at(inv, 8) * nz + at(inv, 12) * nw;
+    const cy = at(inv, 1) * nx + at(inv, 5) * ny + at(inv, 9) * nz + at(inv, 13) * nw;
+    const cz = at(inv, 2) * nx + at(inv, 6) * ny + at(inv, 10) * nz + at(inv, 14) * nw;
+    const cw = at(inv, 3) * nx + at(inv, 7) * ny + at(inv, 11) * nz + at(inv, 15) * nw;
+    const iw = 1.0 / cw;
+    return [cx * iw, cy * iw, cz * iw] as [number, number, number];
+  });
+
+  // 12 edges
+  const edges: [number, number][] = [
+    [0, 1],
+    [0, 2],
+    [1, 3],
+    [2, 3],
+    [4, 5],
+    [4, 6],
+    [5, 7],
+    [6, 7],
+    [0, 4],
+    [1, 5],
+    [2, 6],
+    [3, 7],
+  ];
+
+  const result: [number, number, number][] = [];
+  for (const [ai, bi] of edges) {
+    const ac = corners[ai] as [number, number, number];
+    const bc = corners[bi] as [number, number, number];
+    result.push([ac[0], ac[1], ac[2]]);
+    result.push([bc[0], bc[1], bc[2]]);
+  }
+  return result;
+}

package/src/shapes/line.ts

@@ -0,0 +1,14 @@
+// @forgeax/engine-debug-draw -- line shape geometry (M3 / w20)
+//
+// Pure geometry decomposition: 1 segment = 2 vertices.
+// No staging / GPU concerns; consumed by DebugDraw class.
+
+import type { Vec3 } from '@forgeax/engine-math';
+
+/** 2 vertices forming a line segment from `a` to `b`. */
+export function lineVertices(a: Vec3, b: Vec3): [number, number, number][] {
+  return [
+    [a[0] as number, a[1] as number, a[2] as number],
+    [b[0] as number, b[1] as number, b[2] as number],
+  ];
+}

package/src/shapes/sphere.ts

@@ -0,0 +1,74 @@
+// @forgeax/engine-debug-draw -- sphere shape geometry (M3 / w21)
+//
+// Pure geometry decomposition: 3 orthogonal great-circle rings
+// (XY, XZ, YZ planes). Each ring has `segments` segments producing
+// 2 vertices each. Default segments=16 gives 96 vertices (3 * 2 * 16).
+// No staging / GPU concerns; consumed by DebugDraw class.
+
+import type { Vec3 } from '@forgeax/engine-math';
+
+function a(v: { readonly [index: number]: number }, i: number): number {
+  return v[i] as number;
+}
+
+/**
+ * Generate vertices for a wireframe sphere.
+ * Returns 3 * 2 * segments vertices (pairs forming line segments).
+ */
+export function sphereVertices(
+  center: Vec3,
+  radius: number,
+  segments: number,
+): [number, number, number][] {
+  const cx = a(center, 0);
+  const cy = a(center, 1);
+  const cz = a(center, 2);
+  const step = (2 * Math.PI) / segments;
+
+  const result: [number, number, number][] = [];
+
+  for (let plane = 0; plane < 3; plane++) {
+    for (let i = 0; i < segments; i++) {
+      const angle0 = i * step;
+      const angle1 = (i + 1) % segments;
+
+      let p0x: number;
+      let p0y: number;
+      let p0z: number;
+      let p1x: number;
+      let p1y: number;
+      let p1z: number;
+
+      if (plane === 0) {
+        // XY plane
+        p0x = cx + radius * Math.cos(angle0);
+        p0y = cy + radius * Math.sin(angle0);
+        p0z = cz;
+        p1x = cx + radius * Math.cos(angle1);
+        p1y = cy + radius * Math.sin(angle1);
+        p1z = cz;
+      } else if (plane === 1) {
+        // XZ plane
+        p0x = cx + radius * Math.cos(angle0);
+        p0y = cy;
+        p0z = cz + radius * Math.sin(angle0);
+        p1x = cx + radius * Math.cos(angle1);
+        p1y = cy;
+        p1z = cz + radius * Math.sin(angle1);
+      } else {
+        // YZ plane
+        p0x = cx;
+        p0y = cy + radius * Math.cos(angle0);
+        p0z = cz + radius * Math.sin(angle0);
+        p1x = cx;
+        p1y = cy + radius * Math.cos(angle1);
+        p1z = cz + radius * Math.sin(angle1);
+      }
+
+      result.push([p0x, p0y, p0z]);
+      result.push([p1x, p1y, p1z]);
+    }
+  }
+
+  return result;
+}