Builder workbench + dock primitives + FPV refinements

.gitignore

@@ -21,3 +21,6 @@ packages/vue/tsconfig.tsbuildinfo
 
 # Agent-tool internal state — worktree refs, scheduled-task locks, etc.
 /.claude/
+log.md
+log-texture.md
+website/.baseline-shots/

packages/core/src/helpers/arrowPolygons.ts

@@ -25,6 +25,11 @@ export interface ArrowPolygonsOptions {
   headHalfThickness?: number;
   /** Fill color. */
   color?: string;
+  /** Emit the rectangular shaft polygons. Default `true`. Set `false` to
+   *  render just the pyramid head — used by transform-control gizmos to
+   *  declutter back-facing axes (only the head still identifies direction
+   *  while the shaft would visually overlap the front-facing arrow). */
+  shaft?: boolean;
 }
 
 function makeAxisVec(axis: 0 | 1 | 2, along: number, sideA: number, sideB: number): Vec3 {
@@ -106,6 +111,7 @@ export function arrowPolygons(options: ArrowPolygonsOptions): Polygon[] {
   const headLength = options.headLength ?? 0.8;
   const headHalf = options.headHalfThickness ?? 0.2;
   const color = options.color ?? "#ffffff";
+  const includeShaft = options.shaft ?? true;
 
   // Shaft spans from origin to ±shaftLength along the axis. Use min/max
   // so the cuboid is built with from < to (axisBox convention) — the
@@ -118,8 +124,10 @@ export function arrowPolygons(options: ArrowPolygonsOptions): Polygon[] {
   const headApex = (shaftLength + headLength) * sign;
 
   const head = pyramidPolygons(axis, headBase, headApex, headHalf, color);
+  const headPolys = sign === -1 ? reverseWinding(head) : head;
+  if (!includeShaft) return headPolys;
   return [
     ...shaftPolygons(axis, shaftMin, shaftMax, shaftHalf, color),
-    ...(sign === -1 ? reverseWinding(head) : head),
+    ...headPolys,
   ];
 }

packages/core/src/helpers/index.ts

@@ -4,5 +4,9 @@ export { arrowPolygons } from "./arrowPolygons";
 export type { ArrowPolygonsOptions } from "./arrowPolygons";
 export { ringPolygons } from "./ringPolygons";
 export type { RingPolygonsOptions } from "./ringPolygons";
+export { ringQuadPolygons } from "./ringQuadPolygons";
+export type { RingQuadPolygonsOptions } from "./ringQuadPolygons";
+export { planePolygons } from "./planePolygons";
+export type { PlanePolygonsOptions } from "./planePolygons";
 export { octahedronPolygons } from "./octahedronPolygons";
 export type { OctahedronPolygonsOptions } from "./octahedronPolygons";

packages/core/src/helpers/planePolygons.ts

@@ -0,0 +1,64 @@
+/**
+ * A flat quad on one of the three axis-aligned planes, offset diagonally
+ * along the two in-plane axes. Used as a planar drag handle in
+ * `<PolyTransformControls>` — clicking and dragging this handle moves the
+ * attached mesh along two axes simultaneously (XY, XZ, or YZ), instead of
+ * the single-axis motion the arrow shafts provide.
+ *
+ * The polygon lives in standard polycss world space; wrap it in the
+ * framework's PolyMesh equivalent for rendering.
+ */
+import type { Polygon, Vec3 } from "../types";
+
+export interface PlanePolygonsOptions {
+  /** Axis perpendicular to the plane: 0 = YZ plane, 1 = XZ plane,
+   *  2 = XY plane. The quad lies on the OTHER two axes. */
+  axis: 0 | 1 | 2;
+  /** Half-extent of the quad along each in-plane axis. Default `0.4`. */
+  size?: number;
+  /** Center of the quad along the two in-plane axes. Pass a single number
+   *  to use the same offset on both (positive places the handle in the
+   *  +A/+B corner). Pass `[offsetA, offsetB]` to control each
+   *  independently — sign flips move the handle to a different octant.
+   *  `A = (axis+1)%3`, `B = (axis+2)%3`. Default `size * 2`. */
+  offset?: number | [number, number];
+  /** Position along the perpendicular axis. Default `0` (on the plane). */
+  along?: number;
+  /** Fill color. */
+  color?: string;
+}
+
+/** Build the polygons for one axis-aligned planar drag handle. */
+export function planePolygons(options: PlanePolygonsOptions): Polygon[] {
+  const axis = options.axis;
+  const size = options.size ?? 0.4;
+  const offsetIn = options.offset ?? size * 2;
+  const offsetA = typeof offsetIn === "number" ? offsetIn : offsetIn[0];
+  const offsetB = typeof offsetIn === "number" ? offsetIn : offsetIn[1];
+  const along = options.along ?? 0;
+  const color = options.color ?? "#ffffff";
+
+  const a = (axis + 1) % 3;
+  const b = (axis + 2) % 3;
+  const make = (sideA: number, sideB: number): Vec3 => {
+    const v: Vec3 = [0, 0, 0];
+    v[axis] = along;
+    v[a] = offsetA + sideA;
+    v[b] = offsetB + sideB;
+    return v;
+  };
+  // CCW when viewed from the +axis side. The quad is double-sided in CSS
+  // (no back-face cull when rendered through .polycss-mesh), so winding is
+  // primarily a documentation aid here.
+  return [
+    {
+      vertices: [
+        make(-size, -size),
+        make( size, -size),
+        make( size,  size),
+        make(-size,  size),
+      ],
+      color,
+    },
+  ];
+}

packages/core/src/helpers/ringQuadPolygons.ts

@@ -0,0 +1,49 @@
+/**
+ * One square quad covering the bounding box of a ring (annulus) in the
+ * plane perpendicular to a chosen axis. Used by `<PolyTransformControls
+ * mode="rotate">` together with a CSS `mask: radial-gradient(...)` to
+ * render the visible donut, replacing the segmented quad-strip approach
+ * of `ringPolygons` with a single DOM element per ring.
+ *
+ * The caller is responsible for applying the mask CSS and using a donut-
+ * shaped hit-test (the quad's bounding rect alone would over-hit the
+ * inner hole). The recommended setup is to set the CSS custom property
+ * `--ring-inner-ratio` on the mesh element so the mask scales with the
+ * caller's chosen thickness ratio.
+ */
+import type { Polygon, Vec3 } from "../types";
+
+export interface RingQuadPolygonsOptions {
+  /** World axis the ring is perpendicular to: 0=X, 1=Y, 2=Z. The quad
+   *  lies in the plane spanned by the other two axes. */
+  axis: 0 | 1 | 2;
+  /** Outer radius of the ring. The quad spans ±outerRadius in both
+   *  in-plane axes. */
+  outerRadius: number;
+  /** Fill color. */
+  color?: string;
+}
+
+/** Build a single 4-vertex polygon (a square) bounding the ring's outer
+ *  circle. CSS `mask` is expected to clip this to the donut shape at
+ *  render time. */
+export function ringQuadPolygons(options: RingQuadPolygonsOptions): Polygon[] {
+  const axis = options.axis;
+  const r = options.outerRadius;
+  const color = options.color ?? "#ffffff";
+  const a = (axis + 1) % 3;
+  const b = (axis + 2) % 3;
+  const make = (sa: number, sb: number): Vec3 => {
+    const v: Vec3 = [0, 0, 0];
+    v[axis] = 0;
+    v[a] = sa;
+    v[b] = sb;
+    return v;
+  };
+  return [
+    {
+      vertices: [make(-r, -r), make(r, -r), make(r, r), make(-r, r)],
+      color,
+    },
+  ];
+}

packages/core/src/index.ts

@@ -41,6 +41,14 @@ export type {
 
 // ── Rotation math ────────────────────────────────────────────────
 export { rotateVec3, inverseRotateVec3 } from "./math/rotation";
+export {
+  quatFromAxisAngle,
+  quatFromEulerXYZ,
+  quatMultiply,
+  eulerXYZFromQuat,
+  QUAT_IDENTITY,
+} from "./math/quaternion";
+export type { Quat } from "./math/quaternion";
 
 // ── Camera ────────────────────────────────────────────────────────
 export {
@@ -110,8 +118,8 @@ export type {
 } from "./cull/cameraBackfaceCulling";
 
 // ── Helper-gizmo geometry (axes, light marker, transform arrows / rings) ─
-export { axesHelperPolygons, arrowPolygons, ringPolygons, octahedronPolygons } from "./helpers";
-export type { AxesHelperOptions, ArrowPolygonsOptions, RingPolygonsOptions, OctahedronPolygonsOptions } from "./helpers";
+export { axesHelperPolygons, arrowPolygons, ringPolygons, ringQuadPolygons, planePolygons, octahedronPolygons } from "./helpers";
+export type { AxesHelperOptions, ArrowPolygonsOptions, RingPolygonsOptions, RingQuadPolygonsOptions, PlanePolygonsOptions, OctahedronPolygonsOptions } from "./helpers";
 
 // ── Animation ─────────────────────────────────────────────────────
 export {

packages/core/src/math/quaternion.test.ts

@@ -0,0 +1,99 @@
+import { describe, it, expect } from "vitest";
+import {
+  QUAT_IDENTITY,
+  eulerXYZFromQuat,
+  quatFromAxisAngle,
+  quatFromEulerXYZ,
+  quatMultiply,
+} from "./quaternion";
+
+const TAU = Math.PI * 2;
+
+function expectVec3Close(actual: readonly [number, number, number], expected: readonly [number, number, number], tol = 1e-6): void {
+  expect(actual[0]).toBeCloseTo(expected[0], tol < 1 ? 5 : 0);
+  expect(actual[1]).toBeCloseTo(expected[1], tol < 1 ? 5 : 0);
+  expect(actual[2]).toBeCloseTo(expected[2], tol < 1 ? 5 : 0);
+}
+
+describe("quaternion helpers", () => {
+  it("identity round-trips through eulerXYZFromQuat", () => {
+    const e = eulerXYZFromQuat(QUAT_IDENTITY);
+    expectVec3Close(e, [0, 0, 0]);
+  });
+
+  it("quatFromEulerXYZ([0,0,0]) is identity", () => {
+    const q = quatFromEulerXYZ([0, 0, 0]);
+    expect(q).toEqual([1, 0, 0, 0]);
+  });
+
+  it("quatFromAxisAngle(X, 0) is identity", () => {
+    const q = quatFromAxisAngle([1, 0, 0], 0);
+    expect(q).toEqual([1, 0, 0, 0]);
+  });
+
+  it("Euler round-trips for pure single-axis rotations", () => {
+    for (const axis of [0, 1, 2] as const) {
+      const eIn: [number, number, number] = [0, 0, 0];
+      eIn[axis] = 30;
+      const q = quatFromEulerXYZ(eIn);
+      const eOut = eulerXYZFromQuat(q);
+      expectVec3Close(eOut, eIn);
+    }
+  });
+
+  it("Euler round-trips for combined rotations away from gimbal lock", () => {
+    const eIn: [number, number, number] = [20, 35, 45];
+    const eOut = eulerXYZFromQuat(quatFromEulerXYZ(eIn));
+    expectVec3Close(eOut, eIn);
+  });
+
+  it("quatMultiply with identity is a no-op", () => {
+    const q = quatFromEulerXYZ([15, 25, 35]);
+    expect(quatMultiply(q, QUAT_IDENTITY)).toEqual(q);
+    expect(quatMultiply(QUAT_IDENTITY, q)).toEqual(q);
+  });
+
+  it("local-axis compose ≠ Euler-add when an axis is repeated after another", () => {
+    // Bug scenario: mesh has rotation [90, 45, 0] (rotated X=90 then Y=45).
+    // User drags the X ring again. Euler-add would set rotation[0] =
+    // 90 + 45 = 135, producing matrix X(135)*Y(45). Local-compose multiplies
+    // on the right: X(90)*Y(45)*X(45) ≠ X(135)*Y(45). The composed Euler is
+    // therefore different from the naïve add.
+    const qBase = quatFromEulerXYZ([90, 45, 0]);
+    const qDelta = quatFromAxisAngle([1, 0, 0], (Math.PI * 45) / 180);
+    const qLocal = quatMultiply(qBase, qDelta);
+    const localEuler = eulerXYZFromQuat(qLocal);
+    const naiveAddEuler: [number, number, number] = [135, 45, 0];
+    const diff =
+      Math.abs(localEuler[0] - naiveAddEuler[0]) +
+      Math.abs(localEuler[1] - naiveAddEuler[1]) +
+      Math.abs(localEuler[2] - naiveAddEuler[2]);
+    expect(diff).toBeGreaterThan(1);
+  });
+
+  it("local-axis compose IS commutative with Euler-add for X-then-Y-once (XYZ order quirk)", () => {
+    // Sanity: when the user only ever rotates each axis at most once and in
+    // X-then-Y-then-Z order, local-compose collapses to Euler-add (because
+    // that's the very definition of Euler XYZ). Verifies the helpers are
+    // self-consistent — bugs in other tests above would also fail here.
+    const qStart = quatFromEulerXYZ([90, 0, 0]);
+    const qDelta = quatFromAxisAngle([0, 1, 0], (Math.PI * 45) / 180);
+    const qNew = quatMultiply(qStart, qDelta);
+    const e = eulerXYZFromQuat(qNew);
+    expectVec3Close(e, [90, 45, 0]);
+  });
+
+  it("composing a full TAU rotation around any axis returns to identity orientation", () => {
+    for (const axis of [
+      [1, 0, 0] as const,
+      [0, 1, 0] as const,
+      [0, 0, 1] as const,
+    ]) {
+      const q = quatFromAxisAngle([axis[0], axis[1], axis[2]], TAU);
+      // 2π rotation = identity OR -identity (same orientation, opposite hemisphere).
+      const same = Math.abs(q[0] - 1) < 1e-6;
+      const flipped = Math.abs(q[0] + 1) < 1e-6;
+      expect(same || flipped).toBe(true);
+    }
+  });
+});