@hyperframes/studio 0.7.7 → 0.7.9

package/src/components/editor/propertyPanel3dTransform.tsx

@@ -1,8 +1,10 @@
+import { useState } from "react";
 import type { DomEditSelection } from "./domEditingTypes";
 import { STUDIO_KEYFRAMES_ENABLED } from "./manualEditingAvailability";
 import { MetricField } from "./propertyPanelPrimitives";
 import { KeyframeNavigation } from "./KeyframeNavigation";
 import { formatPxMetricValue, parsePxMetricValue, RESPONSIVE_GRID } from "./propertyPanelHelpers";
+import { Transform3DCube, type CubePose } from "./Transform3DCube";
 
 type KeyframeEntry = Array<{
   percentage: number;
@@ -24,9 +26,216 @@ interface PropertyPanel3dTransformProps {
     property: string,
     value: number,
   ) => Promise<void>;
+  /** Batched commit — several props into one keyframe (the cube's rotationX/Y/Z). */
+  onCommitAnimatedProperties?: (
+    element: DomEditSelection,
+    props: Record<string, number | string>,
+  ) => Promise<void>;
   onSeekToTime?: (time: number) => void;
   onRemoveKeyframe?: (animId: string, pct: number) => void;
-  onConvertToKeyframes?: (animId: string) => void;
+  onConvertToKeyframes?: (animId: string, duration?: number) => void;
+  /** Live-set props on the preview element during a cube drag (no source write). */
+  onLivePreviewProps?: (element: DomEditSelection, props: Record<string, number>) => void;
+}
+
+type CommitAnimatedProperty = (
+  element: DomEditSelection,
+  property: string,
+  value: number,
+) => Promise<void>;
+
+/** The draggable cube + its commit/recenter/live-preview wiring. */
+function Cube3dControl({
+  element,
+  gsapRuntimeValues,
+  onCommitAnimatedProperty,
+  onCommitAnimatedProperties,
+  onLivePreviewProps,
+  onKeyframe,
+  keyframed,
+}: {
+  element: DomEditSelection;
+  gsapRuntimeValues: Record<string, number>;
+  onCommitAnimatedProperty: CommitAnimatedProperty;
+  onCommitAnimatedProperties?: (
+    element: DomEditSelection,
+    props: Record<string, number | string>,
+  ) => Promise<void>;
+  onLivePreviewProps?: (element: DomEditSelection, props: Record<string, number>) => void;
+  onKeyframe?: () => void;
+  keyframed?: boolean;
+}) {
+  const pose: CubePose = {
+    rotationX: gsapRuntimeValues.rotationX ?? 0,
+    rotationY: gsapRuntimeValues.rotationY ?? 0,
+    rotationZ: gsapRuntimeValues.rotationZ ?? 0,
+  };
+  // Commit only the rotation axes the drag actually changed (each rounded to a
+  // whole degree). Reuses the keyframe-aware animated-property commit, so a drag
+  // at the playhead writes/updates a keyframe just like the numeric fields.
+  const commitPose = (next: CubePose) => {
+    const changedProps: Record<string, number> = {};
+    for (const axis of ["rotationX", "rotationY", "rotationZ"] as const) {
+      const rounded = Math.round(next[axis]);
+      if (rounded !== Math.round(pose[axis])) changedProps[axis] = rounded;
+    }
+    const axes = Object.keys(changedProps);
+    if (axes.length === 0) return;
+    // ONE keyframe for the whole pose change — avoids per-axis commits racing into
+    // adjacent duplicate keyframes. Fall back to per-axis if no batched commit.
+    if (onCommitAnimatedProperties) {
+      void onCommitAnimatedProperties(element, changedProps);
+    } else {
+      for (const [axis, v] of Object.entries(changedProps))
+        onCommitAnimatedProperty(element, axis, v);
+    }
+  };
+  const recenter = () => {
+    // ONE commit for the whole reset — six per-axis commits meant six soft-reloads
+    // (six flashes) for a single click. Batch like commitPose does.
+    const identity = {
+      rotationX: 0,
+      rotationY: 0,
+      rotationZ: 0,
+      z: 0,
+      scale: 1,
+      transformPerspective: 0,
+    };
+    if (onCommitAnimatedProperties) {
+      void onCommitAnimatedProperties(element, identity);
+    } else {
+      for (const [prop, v] of Object.entries(identity))
+        void onCommitAnimatedProperty(element, prop, v);
+    }
+  };
+  // Immediate element feedback while dragging — set the live transform without a
+  // source write; the release commits via onCommitAnimatedProperty.
+  const livePreview = (next: CubePose) =>
+    onLivePreviewProps?.(element, {
+      rotationX: next.rotationX,
+      rotationY: next.rotationY,
+      rotationZ: next.rotationZ,
+    });
+
+  return (
+    <div className="mb-2 px-2">
+      <div className="mx-auto max-w-[184px]">
+        <Transform3DCube
+          pose={pose}
+          perspective={gsapRuntimeValues.transformPerspective ?? 0}
+          onPoseDraft={livePreview}
+          onPoseCommit={commitPose}
+          onPerspectiveDraft={(px) => onLivePreviewProps?.(element, { transformPerspective: px })}
+          onPerspectiveCommit={(px) =>
+            void onCommitAnimatedProperty(element, "transformPerspective", px)
+          }
+          onRecenter={recenter}
+          onKeyframe={onKeyframe}
+          keyframed={keyframed}
+        />
+        <p className="mt-1 text-center text-[9px] leading-snug text-neutral-600">
+          Drag to tilt · Shift-drag to roll
+        </p>
+      </div>
+    </div>
+  );
+}
+
+interface FieldCtx {
+  element: DomEditSelection;
+  gsapRuntimeValues: Record<string, number>;
+  gsapKeyframes: KeyframeEntry;
+  gsapAnimId: string | null;
+  currentPct: number;
+  elStart: number;
+  elDuration: number;
+  resolveAnimIdForProp?: (prop: string) => string | null;
+  onCommitAnimatedProperty?: (
+    element: DomEditSelection,
+    property: string,
+    value: number,
+  ) => Promise<void>;
+  onSeekToTime?: (time: number) => void;
+  onRemoveKeyframe?: (animId: string, pct: number) => void;
+  onConvertToKeyframes?: (animId: string, duration?: number) => void;
+}
+
+const parseDeg = (s: string): number | null => {
+  const n = Number.parseFloat(s.replace("°", ""));
+  return Number.isFinite(n) ? n : null;
+};
+const parseScale = (s: string): number | null => {
+  const n = Number.parseFloat(s);
+  return Number.isFinite(n) ? n : null;
+};
+const parsePxNonNeg = (s: string): number | null => {
+  const v = parsePxMetricValue(s);
+  return v != null && v >= 0 ? v : null;
+};
+
+/**
+ * One 3D-transform field: a number/scrub input plus its keyframe diamond, so
+ * rotation / perspective / Z / scale can each be keyframed just like Layout's
+ * X / Y — the diamond was previously missing on the rotation + perspective rows.
+ */
+function Transform3dField({
+  label,
+  prop,
+  scrub,
+  format,
+  parse,
+  defaultValue,
+  ctx,
+}: {
+  label: string;
+  prop: string;
+  scrub?: boolean;
+  format: (v: number) => string;
+  parse: (s: string) => number | null;
+  defaultValue: number;
+  ctx: FieldCtx;
+}) {
+  const { gsapAnimId, onCommitAnimatedProperty } = ctx;
+  const idFor = (p: string) => ctx.resolveAnimIdForProp?.(p) ?? gsapAnimId;
+  const current = ctx.gsapRuntimeValues[prop] ?? defaultValue;
+  return (
+    <div className="flex items-center gap-1">
+      <div className="flex-1">
+        <MetricField
+          label={label}
+          value={format(current)}
+          scrub={scrub}
+          onCommit={(next) => {
+            const v = parse(next);
+            if (v != null && onCommitAnimatedProperty) {
+              void onCommitAnimatedProperty(ctx.element, prop, v);
+            }
+          }}
+        />
+      </div>
+      {STUDIO_KEYFRAMES_ENABLED && (gsapAnimId || onCommitAnimatedProperty) && (
+        <KeyframeNavigation
+          property={prop}
+          keyframes={ctx.gsapKeyframes}
+          currentPercentage={ctx.currentPct}
+          onSeek={(pct) => ctx.onSeekToTime?.(ctx.elStart + (pct / 100) * ctx.elDuration)}
+          onAddKeyframe={() => {
+            if (onCommitAnimatedProperty) void onCommitAnimatedProperty(ctx.element, prop, current);
+          }}
+          onRemoveKeyframe={(pct) => {
+            const id = idFor(prop);
+            if (id) ctx.onRemoveKeyframe?.(id, pct);
+          }}
+          onConvertToKeyframes={() => {
+            const id = idFor(prop);
+            // Pass the element's clip duration so a converted static 3D `set`
+            // spans the whole clip (keyframes land in range at any playhead).
+            if (id) ctx.onConvertToKeyframes?.(id, ctx.elDuration);
+          }}
+        />
+      )}
+    </div>
+  );
 }
 
 export function PropertyPanel3dTransform({
@@ -39,110 +248,120 @@ export function PropertyPanel3dTransform({
   elDuration,
   element,
   onCommitAnimatedProperty,
+  onCommitAnimatedProperties,
   onSeekToTime,
   onRemoveKeyframe,
   onConvertToKeyframes,
+  onLivePreviewProps,
 }: PropertyPanel3dTransformProps) {
-  const idFor = (prop: string) => resolveAnimIdForProp?.(prop) ?? gsapAnimId;
+  // Expanded by default — the cube gizmo is the headline of this panel, so show
+  // it up front rather than hiding it behind a collapsed header.
+  const [collapsed, setCollapsed] = useState(false);
+  const ctx: FieldCtx = {
+    element,
+    gsapRuntimeValues,
+    gsapKeyframes,
+    gsapAnimId,
+    currentPct,
+    elStart,
+    elDuration,
+    resolveAnimIdForProp,
+    onCommitAnimatedProperty,
+    onSeekToTime,
+    onRemoveKeyframe,
+    onConvertToKeyframes,
+  };
+
   return (
     <div className="mt-3 border-t border-neutral-800/40 pt-3">
-      <div className="mb-2 text-[10px] font-medium uppercase tracking-wider text-neutral-600">
-        3D Transform
-      </div>
-      <div className={RESPONSIVE_GRID}>
-        <div className="flex items-center gap-1">
-          <div className="flex-1">
-            <MetricField
-              label="Z"
-              value={formatPxMetricValue(gsapRuntimeValues.z ?? 0)}
-              scrub
-              onCommit={(next) => {
-                const v = parsePxMetricValue(next);
-                if (v != null && onCommitAnimatedProperty) {
-                  void onCommitAnimatedProperty(element, "z", v);
-                }
-              }}
-            />
-          </div>
-          {STUDIO_KEYFRAMES_ENABLED && (gsapAnimId || onCommitAnimatedProperty) && (
-            <KeyframeNavigation
-              property="z"
-              keyframes={gsapKeyframes}
-              currentPercentage={currentPct}
-              onSeek={(pct) => onSeekToTime?.(elStart + (pct / 100) * elDuration)}
-              onAddKeyframe={() => {
-                if (onCommitAnimatedProperty) {
-                  void onCommitAnimatedProperty(element, "z", gsapRuntimeValues?.z ?? 0);
-                }
-              }}
-              onRemoveKeyframe={(pct) => {
-                const id = idFor("z");
-                if (id) onRemoveKeyframe?.(id, pct);
-              }}
-              onConvertToKeyframes={() => {
-                const id = idFor("z");
-                if (id) onConvertToKeyframes?.(id);
+      <button
+        type="button"
+        onClick={() => setCollapsed((v) => !v)}
+        className="mb-2 flex w-full items-center justify-between text-[10px] font-medium uppercase tracking-wider text-neutral-600 hover:text-neutral-400"
+      >
+        <span>3D Transform</span>
+        <svg width="9" height="9" viewBox="0 0 10 10" fill="currentColor" aria-hidden>
+          {collapsed ? <path d="M3 2l4 3-4 3z" /> : <path d="M2 3l3 4 3-4z" />}
+        </svg>
+      </button>
+      {collapsed ? null : (
+        <>
+          {onCommitAnimatedProperty && (
+            <Cube3dControl
+              element={element}
+              gsapRuntimeValues={gsapRuntimeValues}
+              onCommitAnimatedProperty={onCommitAnimatedProperty}
+              onCommitAnimatedProperties={onCommitAnimatedProperties}
+              onLivePreviewProps={onLivePreviewProps}
+              keyframed={(gsapKeyframes ?? []).some(
+                (kf) =>
+                  "rotationX" in kf.properties ||
+                  "rotationY" in kf.properties ||
+                  "rotationZ" in kf.properties,
+              )}
+              onKeyframe={() => {
+                // Convert the 3D ("other"-group) static set to keyframes so the
+                // cube can animate; spans the element's clip via elDuration.
+                const id = resolveAnimIdForProp?.("rotationX") ?? gsapAnimId;
+                if (id) onConvertToKeyframes?.(id, elDuration);
               }}
             />
           )}
-        </div>
-        <div className="flex items-center gap-1">
-          <div className="flex-1">
-            <MetricField
+          <div className={RESPONSIVE_GRID}>
+            <Transform3dField
+              ctx={ctx}
+              label="Z"
+              prop="z"
+              scrub
+              format={formatPxMetricValue}
+              parse={parsePxMetricValue}
+              defaultValue={0}
+            />
+            <Transform3dField
+              ctx={ctx}
               label="Scale"
-              value={String(gsapRuntimeValues.scale ?? 1)}
+              prop="scale"
               scrub
-              onCommit={(next) => {
-                const v = Number.parseFloat(next);
-                if (Number.isFinite(v) && onCommitAnimatedProperty) {
-                  void onCommitAnimatedProperty(element, "scale", v);
-                }
-              }}
+              format={(v) => String(v)}
+              parse={parseScale}
+              defaultValue={1}
             />
-          </div>
-          {STUDIO_KEYFRAMES_ENABLED && (gsapAnimId || onCommitAnimatedProperty) && (
-            <KeyframeNavigation
-              property="scale"
-              keyframes={gsapKeyframes}
-              currentPercentage={currentPct}
-              onSeek={(pct) => onSeekToTime?.(elStart + (pct / 100) * elDuration)}
-              onAddKeyframe={() => {
-                if (onCommitAnimatedProperty) {
-                  void onCommitAnimatedProperty(element, "scale", gsapRuntimeValues?.scale ?? 1);
-                }
-              }}
-              onRemoveKeyframe={(pct) => {
-                const id = idFor("scale");
-                if (id) onRemoveKeyframe?.(id, pct);
-              }}
-              onConvertToKeyframes={() => {
-                const id = idFor("scale");
-                if (id) onConvertToKeyframes?.(id);
-              }}
+            <Transform3dField
+              ctx={ctx}
+              label="RotX"
+              prop="rotationX"
+              format={(v) => `${v}°`}
+              parse={parseDeg}
+              defaultValue={0}
             />
-          )}
-        </div>
-        <MetricField
-          label="RotX"
-          value={`${gsapRuntimeValues.rotationX ?? 0}°`}
-          onCommit={(next) => {
-            const v = Number.parseFloat(next.replace("°", ""));
-            if (Number.isFinite(v) && onCommitAnimatedProperty) {
-              void onCommitAnimatedProperty(element, "rotationX", v);
-            }
-          }}
-        />
-        <MetricField
-          label="RotY"
-          value={`${gsapRuntimeValues.rotationY ?? 0}°`}
-          onCommit={(next) => {
-            const v = Number.parseFloat(next.replace("°", ""));
-            if (Number.isFinite(v) && onCommitAnimatedProperty) {
-              void onCommitAnimatedProperty(element, "rotationY", v);
-            }
-          }}
-        />
-      </div>
+            <Transform3dField
+              ctx={ctx}
+              label="RotY"
+              prop="rotationY"
+              format={(v) => `${v}°`}
+              parse={parseDeg}
+              defaultValue={0}
+            />
+            <Transform3dField
+              ctx={ctx}
+              label="RotZ"
+              prop="rotationZ"
+              format={(v) => `${v}°`}
+              parse={parseDeg}
+              defaultValue={0}
+            />
+            <Transform3dField
+              ctx={ctx}
+              label="Perspective"
+              prop="transformPerspective"
+              scrub
+              format={formatPxMetricValue}
+              parse={parsePxNonNeg}
+              defaultValue={0}
+            />
+          </div>
+        </>
+      )}
     </div>
   );
 }

package/src/components/editor/propertyPanelHelpers.ts

@@ -68,12 +68,18 @@ export interface PropertyPanelProps {
   onRemoveKeyframe?: (animationId: string, percentage: number) => void;
   onUpdateKeyframeEase?: (animationId: string, percentage: number, ease: string) => void;
   onSetAllKeyframeEases?: (animationId: string, ease: string) => void;
-  onConvertToKeyframes?: (animationId: string) => void;
+  onConvertToKeyframes?: (animationId: string, duration?: number) => void;
   onCommitAnimatedProperty?: (
     selection: DomEditSelection,
     property: string,
     value: number | string,
   ) => Promise<void>;
+  /** Batched variant: commit several props into ONE keyframe (e.g. the 3D cube's
+   * rotationX/Y/Z) so multi-axis edits don't race into adjacent duplicates. */
+  onCommitAnimatedProperties?: (
+    selection: DomEditSelection,
+    props: Record<string, number | string>,
+  ) => Promise<void>;
   onSeekToTime?: (time: number) => void;
   recordingState?: "idle" | "recording" | "preview";
   recordingDuration?: number;
@@ -212,10 +218,8 @@ export const LABEL = "text-[11px] font-medium text-panel-text-3";
 export const RESPONSIVE_GRID = "grid grid-cols-[repeat(auto-fit,minmax(118px,1fr))] gap-3";
 export const EMPTY_STYLES: Record<string, string> = {};
 
-// fallow-ignore-next-line unused-exports -- pre-existing; surfaced in this file's diff by an unrelated line shift
-export const EMPTY_FILTER_VALUE = "none";
-// fallow-ignore-next-line unused-exports -- pre-existing; surfaced in this file's diff by an unrelated line shift
-export const BOX_SHADOW_PRESETS = {
+const EMPTY_FILTER_VALUE = "none";
+const BOX_SHADOW_PRESETS = {
   none: "none",
   soft: "0 12px 36px rgba(0, 0, 0, 0.28)",
   lift: "0 18px 54px rgba(0, 0, 0, 0.38)",
@@ -275,13 +279,7 @@ export function parsePxMetricValue(value: string): number | null {
   return token.value;
 }
 
-// fallow-ignore-next-line unused-exports -- pre-existing; surfaced in this file's diff by an unrelated line shift
-export function clampPanelNumber(
-  value: number,
-  min: number,
-  max: number,
-  fallback: number,
-): number {
+function clampPanelNumber(value: number, min: number, max: number, fallback: number): number {
   if (!Number.isFinite(value)) return fallback;
   return Math.max(min, Math.min(max, value));
 }
@@ -491,6 +489,38 @@ export function extractBackgroundImageUrl(value: string | undefined): string {
 // ── GSAP runtime value readers (used by PropertyPanel) ────────────────────
 
 // fallow-ignore-next-line complexity -- pre-existing; surfaced in this file's diff by an unrelated line shift
+// Core transform channels the panel ALWAYS reads live — even before a just-set
+// value (e.g. rotationX) has re-parsed into `gsapAnimations`. Without this the
+// cube + fields drop the prop and flicker to 0 on every commit; gsap.getProperty
+// reflects the in-place instant patch, so it's the true current value.
+const ALWAYS_READ_CHANNELS = [
+  "x",
+  "y",
+  "rotation",
+  "rotationX",
+  "rotationY",
+  "rotationZ",
+  "z",
+  "scale",
+  "transformPerspective",
+  "opacity",
+];
+
+/** Every property key the panel should read for an element: animated props + the
+ * always-read transform channels. */
+function collectPanelPropKeys(gsapAnimations: GsapAnimation[]): Set<string> {
+  const keys = new Set<string>(ALWAYS_READ_CHANNELS);
+  for (const anim of gsapAnimations) {
+    if (anim.keyframes) {
+      for (const kf of anim.keyframes.keyframes) {
+        for (const p of Object.keys(kf.properties)) keys.add(p);
+      }
+    }
+    for (const p of Object.keys(anim.properties)) keys.add(p);
+  }
+  return keys;
+}
+
 export function readGsapRuntimeValuesForPanel(
   gsapAnimId: string | null,
   gsapAnimations: GsapAnimation[],
@@ -511,15 +541,7 @@ export function readGsapRuntimeValuesForPanel(
     if (!gsap?.getProperty) return null;
     const el = iframe.contentDocument?.querySelector(selector);
     if (!el) return null;
-    const propKeys = new Set<string>();
-    for (const anim of gsapAnimations) {
-      if (anim.keyframes) {
-        for (const kf of anim.keyframes.keyframes) {
-          for (const p of Object.keys(kf.properties)) propKeys.add(p);
-        }
-      }
-      for (const p of Object.keys(anim.properties)) propKeys.add(p);
-    }
+    const propKeys = collectPanelPropKeys(gsapAnimations);
     const result: Record<string, number> = {};
     for (const prop of propKeys) {
       const v = Number(gsap.getProperty(el, prop));

package/src/components/editor/transform3dProjection.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+import { projectAxes, projectCubeFaces, rotate, wrapDeg } from "./transform3dProjection";
+
+const OPTS = { cx: 50, cy: 50, r: 30, persp: 4 };
+
+describe("projectCubeFaces", () => {
+  it("shows the front face (and only front-facing faces) at identity", () => {
+    const faces = projectCubeFaces(0, 0, 0, OPTS);
+    const ids = faces.map((f) => f.id);
+    expect(ids).toContain("front");
+    // Head-on: side/top/bottom normals are edge-on (n.z ≈ 0) → culled.
+    expect(ids).not.toContain("back");
+    expect(faces.length).toBeGreaterThanOrEqual(1);
+    expect(faces.length).toBeLessThanOrEqual(3);
+  });
+
+  it("reveals the top face when tilted forward on X", () => {
+    const ids = projectCubeFaces(45, 0, 0, OPTS).map((f) => f.id);
+    expect(ids).toContain("front");
+    expect(ids).toContain("top");
+    expect(ids).not.toContain("bottom");
+  });
+
+  it("reveals a side face when rotated on Y (CSS rotateY convention)", () => {
+    const ids = projectCubeFaces(0, 45, 0, OPTS).map((f) => f.id);
+    expect(ids).toContain("front");
+    expect(ids).toContain("left");
+    expect(ids).not.toContain("right");
+  });
+
+  it("never returns more than 3 faces (a cube shows at most 3 at once)", () => {
+    for (const [rx, ry, rz] of [
+      [30, 30, 0],
+      [60, 60, 45],
+      [135, 20, 90],
+    ]) {
+      expect(projectCubeFaces(rx, ry, rz, OPTS).length).toBeLessThanOrEqual(3);
+    }
+  });
+
+  it("rotationZ rolls the silhouette without changing which faces are visible", () => {
+    const a = projectCubeFaces(0, 0, 0, OPTS)
+      .map((f) => f.id)
+      .sort();
+    const b = projectCubeFaces(0, 0, 90, OPTS)
+      .map((f) => f.id)
+      .sort();
+    expect(b).toEqual(a);
+    // …but the projected coordinates differ (it rolled).
+    expect(projectCubeFaces(0, 0, 90, OPTS)[0]?.points).not.toEqual(
+      projectCubeFaces(0, 0, 0, OPTS)[0]?.points,
+    );
+  });
+
+  it("paints far faces before near faces (painter's order)", () => {
+    const faces = projectCubeFaces(35, 35, 0, OPTS);
+    for (let i = 1; i < faces.length; i++) {
+      expect(faces[i]!.depth).toBeGreaterThanOrEqual(faces[i - 1]!.depth);
+    }
+  });
+});
+
+describe("projectAxes", () => {
+  it("returns the three X/Y/Z axes with standard colors", () => {
+    const axes = projectAxes(0, 0, 0, OPTS);
+    expect(axes.map((a) => a.id).sort()).toEqual(["x", "y", "z"]);
+    const z = axes.find((a) => a.id === "z")!;
+    expect(z.color).toMatch(/#/);
+  });
+
+  it("flags the toward-viewer axis as front at identity (Z points at the camera)", () => {
+    const z = projectAxes(0, 0, 0, OPTS).find((a) => a.id === "z")!;
+    expect(z.front).toBe(true);
+  });
+
+  it("rotating 180° on Y flips the Z axis away from the viewer", () => {
+    const z = projectAxes(0, 180, 0, OPTS).find((a) => a.id === "z")!;
+    expect(z.front).toBe(false);
+  });
+});
+
+describe("rotate", () => {
+  it("90° on Y maps +x to -z (right edge swings to the back)", () => {
+    const v = rotate({ x: 1, y: 0, z: 0 }, 0, 90, 0);
+    expect(v.x).toBeCloseTo(0, 5);
+    expect(v.z).toBeCloseTo(-1, 5);
+  });
+});
+
+describe("wrapDeg", () => {
+  it("wraps into (-180, 180]", () => {
+    expect(wrapDeg(0)).toBe(0);
+    expect(wrapDeg(180)).toBe(180);
+    expect(wrapDeg(190)).toBe(-170);
+    expect(wrapDeg(-190)).toBe(170);
+    expect(wrapDeg(360)).toBe(0);
+    expect(wrapDeg(540)).toBe(180);
+  });
+});