@pixel-point/toolcraft 0.0.15 → 0.0.17

package/templates/runtime/react/orientation-gizmo/orientation-gizmo-math.test.ts

@@ -0,0 +1,217 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  DEFAULT_TOOLCRAFT_ORIENTATION_POSE,
+  TOOLCRAFT_ORIENTATION_AXES,
+  TOOLCRAFT_TURNTABLE_RADIANS_PER_PIXEL,
+  easeToolcraftOrientationSnap,
+  getToolcraftOrientationCameraQuaternion,
+  getToolcraftOrientationPoseFromPointerDelta,
+  getToolcraftOrientationRadius,
+  getToolcraftOrientationSnapDurationMs,
+  interpolateToolcraftOrientationPose,
+  projectToolcraftOrientationAxes,
+  readToolcraftOrientationPose,
+  snapToolcraftOrientationPose,
+  type ToolcraftOrientationAxis,
+} from "./orientation-gizmo-math";
+
+function expectTupleClose(
+  received: readonly [number, number, number],
+  expected: readonly [number, number, number],
+): void {
+  expected.forEach((value, index) => {
+    expect(received[index]).toBeCloseTo(value, 10);
+  });
+}
+
+function normalizeForTest(
+  vector: readonly [number, number, number],
+): [number, number, number] {
+  const length = Math.hypot(...vector);
+
+  return [vector[0] / length, vector[1] / length, vector[2] / length];
+}
+
+function crossForTest(
+  left: readonly [number, number, number],
+  right: readonly [number, number, number],
+): [number, number, number] {
+  return [
+    left[1] * right[2] - left[2] * right[1],
+    left[2] * right[0] - left[0] * right[2],
+    left[0] * right[1] - left[1] * right[0],
+  ];
+}
+
+function distanceForTest(
+  left: readonly [number, number, number],
+  right: readonly [number, number, number],
+): number {
+  return Math.hypot(
+    left[0] - right[0],
+    left[1] - right[1],
+    left[2] - right[2],
+  );
+}
+
+describe("Toolcraft orientation math", () => {
+  it("reads valid poses defensively and rejects malformed state", () => {
+    const source = { position: [1, 2, 3], up: [0, 1, 0] } as const;
+    const read = readToolcraftOrientationPose(source);
+
+    expect(read).toEqual(source);
+    expect(read).not.toBe(source);
+    expect(read.position).not.toBe(source.position);
+    expect(
+      readToolcraftOrientationPose({ position: [1, 2], up: [0, 1, 0] }),
+    ).toEqual(DEFAULT_TOOLCRAFT_ORIENTATION_POSE);
+    expect(
+      readToolcraftOrientationPose({ position: [0, 2, 0], up: [0, 1, 0] }),
+    ).toEqual(DEFAULT_TOOLCRAFT_ORIENTATION_POSE);
+  });
+
+  it("uses Blender factory turntable sensitivity in CSS pixels", () => {
+    expect(TOOLCRAFT_TURNTABLE_RADIANS_PER_PIXEL).toBeCloseTo(
+      (0.4 * Math.PI) / 180,
+      12,
+    );
+    const result = getToolcraftOrientationPoseFromPointerDelta(
+      DEFAULT_TOOLCRAFT_ORIENTATION_POSE,
+      90,
+      0,
+    );
+    const angle = (36 * Math.PI) / 180;
+
+    expectTupleClose(result.position, [
+      -5 * Math.sin(angle),
+      0,
+      5 * Math.cos(angle),
+    ]);
+  });
+
+  it("keeps a level horizon away from the poles", () => {
+    const result = getToolcraftOrientationPoseFromPointerDelta(
+      DEFAULT_TOOLCRAFT_ORIENTATION_POSE,
+      37,
+      24,
+    );
+    const back = normalizeForTest(result.position);
+    const projectedWorldUp = normalizeForTest([
+      -back[1] * back[0],
+      1 - back[1] * back[1],
+      -back[1] * back[2],
+    ]);
+
+    expectTupleClose(result.up, projectedWorldUp);
+    expect(getToolcraftOrientationRadius(result)).toBeCloseTo(5, 10);
+  });
+
+  it.each(["+y", "-y"] as const)(
+    "leaves the %s pole continuously",
+    (axis) => {
+      const pole = snapToolcraftOrientationPose(
+        DEFAULT_TOOLCRAFT_ORIENTATION_POSE,
+        axis,
+      );
+      const first = getToolcraftOrientationPoseFromPointerDelta(pole, 0, 1);
+      const second = getToolcraftOrientationPoseFromPointerDelta(first, 0, 1);
+
+      expect(first).not.toEqual(pole);
+      expect(getToolcraftOrientationRadius(first)).toBeCloseTo(5, 10);
+      expect(getToolcraftOrientationRadius(second)).toBeCloseTo(5, 10);
+      expect(Math.hypot(...crossForTest(first.up, first.position))).toBeGreaterThan(
+        1,
+      );
+      expect(distanceForTest(first.position, second.position)).toBeLessThan(0.1);
+    },
+  );
+
+  it("projects every signed world axis", () => {
+    const projected = projectToolcraftOrientationAxes({
+      position: [0, 0, 10],
+      up: [0, 1, 0],
+    });
+    const byAxis = Object.fromEntries(
+      projected.map((item) => [item.axis, item]),
+    );
+
+    expect(byAxis["+x"]).toMatchObject({ x: 59.5, y: 35, depth: 0 });
+    expect(byAxis["-x"]).toMatchObject({ x: 10.5, y: 35, depth: 0 });
+    expect(byAxis["+y"]).toMatchObject({ x: 35, y: 10.5, depth: 0 });
+    expect(byAxis["-y"]).toMatchObject({ x: 35, y: 59.5, depth: 0 });
+    expect(byAxis["+z"].depth).toBeCloseTo(-1, 12);
+    expect(byAxis["-z"].depth).toBeCloseTo(1, 12);
+  });
+
+  it("snaps every axis while preserving radius", () => {
+    const radius = getToolcraftOrientationRadius(
+      DEFAULT_TOOLCRAFT_ORIENTATION_POSE,
+    );
+    const expectations: Record<
+      ToolcraftOrientationAxis,
+      { position: [number, number, number]; up: [number, number, number] }
+    > = {
+      "+x": { position: [radius, 0, 0], up: [0, 1, 0] },
+      "-x": { position: [-radius, 0, 0], up: [0, 1, 0] },
+      "+y": { position: [0, radius, 0], up: [0, 0, -1] },
+      "-y": { position: [0, -radius, 0], up: [0, 0, 1] },
+      "+z": { position: [0, 0, radius], up: [0, 1, 0] },
+      "-z": { position: [0, 0, -radius], up: [0, 1, 0] },
+    };
+
+    for (const axis of TOOLCRAFT_ORIENTATION_AXES) {
+      const snapped = snapToolcraftOrientationPose(
+        DEFAULT_TOOLCRAFT_ORIENTATION_POSE,
+        axis,
+      );
+
+      expectTupleClose(snapped.position, expectations[axis].position);
+      expectTupleClose(snapped.up, expectations[axis].up);
+      expect(getToolcraftOrientationRadius(snapped)).toBeCloseTo(radius, 10);
+    }
+  });
+
+  it("interpolates orientation without changing radius", () => {
+    const start = DEFAULT_TOOLCRAFT_ORIENTATION_POSE;
+    const end = snapToolcraftOrientationPose(start, "+x");
+    const middle = interpolateToolcraftOrientationPose(start, end, 0.5);
+
+    expect(getToolcraftOrientationRadius(middle)).toBeCloseTo(
+      getToolcraftOrientationRadius(start),
+      10,
+    );
+    expect(
+      getToolcraftOrientationCameraQuaternion(middle).length(),
+    ).toBeCloseTo(1, 10);
+  });
+
+  it("uses Blender cubic smoothstep", () => {
+    expect(easeToolcraftOrientationSnap(-1)).toBe(0);
+    expect(easeToolcraftOrientationSnap(0.25)).toBe(0.15625);
+    expect(easeToolcraftOrientationSnap(0.5)).toBe(0.5);
+    expect(easeToolcraftOrientationSnap(0.75)).toBe(0.84375);
+    expect(easeToolcraftOrientationSnap(2)).toBe(1);
+  });
+
+  it("scales the 200ms Smooth View duration by quaternion angle", () => {
+    const front = DEFAULT_TOOLCRAFT_ORIENTATION_POSE;
+
+    expect(getToolcraftOrientationSnapDurationMs(front, front)).toBeCloseTo(
+      0,
+      8,
+    );
+    expect(
+      getToolcraftOrientationSnapDurationMs(
+        front,
+        snapToolcraftOrientationPose(front, "+x"),
+      ),
+    ).toBeCloseTo(100, 8);
+    expect(
+      getToolcraftOrientationSnapDurationMs(
+        front,
+        snapToolcraftOrientationPose(front, "-z"),
+      ),
+    ).toBeCloseTo(200, 8);
+  });
+});

package/templates/runtime/react/orientation-gizmo/orientation-gizmo-math.ts

@@ -0,0 +1,299 @@
+import {
+  ToolcraftOrientationQuaternion,
+  applyOrientationQuaternion,
+  crossOrientationVectors,
+  dotOrientationVectors,
+  getOrientationQuaternionFromAxisAngle,
+  getOrientationQuaternionFromBasis,
+  getOrientationVectorLength,
+  normalizeOrientationVector,
+  scaleOrientationVector,
+  type ToolcraftOrientationVector,
+} from "./orientation-quaternion";
+
+export { ToolcraftOrientationQuaternion } from "./orientation-quaternion";
+
+export type ToolcraftOrientationPose = Readonly<{
+  position: readonly [number, number, number];
+  up: readonly [number, number, number];
+}>;
+
+export type ToolcraftOrientationAxis = "+x" | "-x" | "+y" | "-y" | "+z" | "-z";
+
+export type ToolcraftOrientationAxisProjection = {
+  axis: ToolcraftOrientationAxis;
+  depth: number;
+  isFrontFacing: boolean;
+  x: number;
+  y: number;
+};
+
+export const DEFAULT_TOOLCRAFT_ORIENTATION_POSE: ToolcraftOrientationPose = {
+  position: [0, 0, 5],
+  up: [0, 1, 0],
+};
+
+export const TOOLCRAFT_ORIENTATION_AXES: readonly ToolcraftOrientationAxis[] = [
+  "+x",
+  "-x",
+  "+y",
+  "-y",
+  "+z",
+  "-z",
+];
+
+export const TOOLCRAFT_TURNTABLE_RADIANS_PER_PIXEL = Math.PI / 450;
+export const TOOLCRAFT_ORIENTATION_SMOOTH_VIEW_MS = 200;
+
+const worldUp: ToolcraftOrientationVector = [0, 1, 0];
+const minimumLengthSquared = 1e-12;
+
+const axisVectors: Record<
+  ToolcraftOrientationAxis,
+  ToolcraftOrientationVector
+> = {
+  "+x": [1, 0, 0],
+  "-x": [-1, 0, 0],
+  "+y": [0, 1, 0],
+  "-y": [0, -1, 0],
+  "+z": [0, 0, 1],
+  "-z": [0, 0, -1],
+};
+
+function clonePose(pose: ToolcraftOrientationPose): ToolcraftOrientationPose {
+  return {
+    position: [...pose.position],
+    up: [...pose.up],
+  };
+}
+
+function readFiniteTuple(value: unknown): [number, number, number] | null {
+  if (
+    !Array.isArray(value) ||
+    value.length !== 3 ||
+    !value.every((entry) => typeof entry === "number" && Number.isFinite(entry))
+  ) {
+    return null;
+  }
+
+  return [value[0], value[1], value[2]];
+}
+
+function isUsablePose(pose: ToolcraftOrientationPose): boolean {
+  const positionLength = getOrientationVectorLength(pose.position);
+  const upLength = getOrientationVectorLength(pose.up);
+  const crossLength = getOrientationVectorLength(
+    crossOrientationVectors(pose.up, pose.position),
+  );
+
+  return (
+    positionLength * positionLength > minimumLengthSquared &&
+    upLength * upLength > minimumLengthSquared &&
+    crossLength * crossLength > minimumLengthSquared
+  );
+}
+
+export function readToolcraftOrientationPose(
+  value: unknown,
+  fallback: ToolcraftOrientationPose = DEFAULT_TOOLCRAFT_ORIENTATION_POSE,
+): ToolcraftOrientationPose {
+  const safeFallback = isUsablePose(fallback)
+    ? fallback
+    : DEFAULT_TOOLCRAFT_ORIENTATION_POSE;
+
+  if (!value || typeof value !== "object") {
+    return clonePose(safeFallback);
+  }
+
+  const record = value as Record<string, unknown>;
+  const position = readFiniteTuple(record.position);
+  const up = readFiniteTuple(record.up);
+
+  if (!position || !up) {
+    return clonePose(safeFallback);
+  }
+
+  const pose = { position, up };
+
+  return isUsablePose(pose) ? clonePose(pose) : clonePose(safeFallback);
+}
+
+export function getToolcraftOrientationRadius(
+  pose: ToolcraftOrientationPose,
+): number {
+  return getOrientationVectorLength(pose.position);
+}
+
+function interpolateOrientationVectors(
+  start: ToolcraftOrientationVector,
+  end: ToolcraftOrientationVector,
+  amount: number,
+): ToolcraftOrientationVector {
+  return [
+    start[0] + (end[0] - start[0]) * amount,
+    start[1] + (end[1] - start[1]) * amount,
+    start[2] + (end[2] - start[2]) * amount,
+  ];
+}
+
+export function getToolcraftOrientationPoseFromPointerDelta(
+  poseValue: ToolcraftOrientationPose,
+  deltaX: number,
+  deltaY: number,
+): ToolcraftOrientationPose {
+  const pose = readToolcraftOrientationPose(poseValue);
+
+  if (!Number.isFinite(deltaX) || !Number.isFinite(deltaY)) {
+    return pose;
+  }
+
+  const cameraQuaternion = getToolcraftOrientationCameraQuaternion(pose);
+  const back = normalizeOrientationVector(pose.position);
+  const cameraRight = normalizeOrientationVector(
+    applyOrientationQuaternion([1, 0, 0], cameraQuaternion),
+  );
+  const rotatedHorizon = crossOrientationVectors(worldUp, back);
+  let pitchAxis = cameraRight;
+
+  if (dotOrientationVectors(rotatedHorizon, rotatedHorizon) > 0.001) {
+    const alignedHorizon =
+      dotOrientationVectors(rotatedHorizon, cameraRight) < 0
+        ? scaleOrientationVector(rotatedHorizon, -1)
+        : rotatedHorizon;
+    let blend =
+      Math.acos(
+        Math.max(-1, Math.min(1, dotOrientationVectors(worldUp, back))),
+      ) / Math.PI;
+    blend = Math.abs(blend - 0.5) * 2;
+    blend *= blend;
+    pitchAxis = normalizeOrientationVector(
+      interpolateOrientationVectors(alignedHorizon, cameraRight, blend),
+    );
+  }
+
+  const pitch = getOrientationQuaternionFromAxisAngle(
+    pitchAxis,
+    -deltaY * TOOLCRAFT_TURNTABLE_RADIANS_PER_PIXEL,
+  );
+  const yaw = getOrientationQuaternionFromAxisAngle(
+    worldUp,
+    -deltaX * TOOLCRAFT_TURNTABLE_RADIANS_PER_PIXEL,
+  );
+  const nextCameraQuaternion = yaw
+    .multiply(pitch)
+    .multiply(cameraQuaternion)
+    .normalize();
+  const radius = getToolcraftOrientationRadius(pose);
+
+  return {
+    position: applyOrientationQuaternion([0, 0, radius], nextCameraQuaternion),
+    up: normalizeOrientationVector(
+      applyOrientationQuaternion([0, 1, 0], nextCameraQuaternion),
+    ),
+  };
+}
+
+export function getToolcraftOrientationCameraQuaternion(
+  poseValue: ToolcraftOrientationPose,
+): ToolcraftOrientationQuaternion {
+  const pose = readToolcraftOrientationPose(poseValue);
+  const back = normalizeOrientationVector(pose.position);
+  const right = normalizeOrientationVector(
+    crossOrientationVectors(pose.up, back),
+  );
+  const cameraUp = normalizeOrientationVector(
+    crossOrientationVectors(back, right),
+  );
+
+  return getOrientationQuaternionFromBasis(right, cameraUp, back);
+}
+
+export function projectToolcraftOrientationAxes(
+  poseValue: ToolcraftOrientationPose,
+  center = 35,
+  reach = 24.5,
+): ToolcraftOrientationAxisProjection[] {
+  const pose = readToolcraftOrientationPose(poseValue);
+  const cameraQuaternion = getToolcraftOrientationCameraQuaternion(pose);
+  const right = applyOrientationQuaternion([1, 0, 0], cameraQuaternion);
+  const up = applyOrientationQuaternion([0, 1, 0], cameraQuaternion);
+  const forward = applyOrientationQuaternion([0, 0, -1], cameraQuaternion);
+
+  return TOOLCRAFT_ORIENTATION_AXES.map((axis) => {
+    const vector = axisVectors[axis];
+    const depth = dotOrientationVectors(vector, forward);
+
+    return {
+      axis,
+      depth,
+      isFrontFacing: depth < 0,
+      x: center + dotOrientationVectors(vector, right) * reach,
+      y: center - dotOrientationVectors(vector, up) * reach,
+    };
+  });
+}
+
+export function snapToolcraftOrientationPose(
+  poseValue: ToolcraftOrientationPose,
+  axis: ToolcraftOrientationAxis,
+): ToolcraftOrientationPose {
+  const radius = getToolcraftOrientationRadius(
+    readToolcraftOrientationPose(poseValue),
+  );
+
+  switch (axis) {
+    case "+x":
+      return { position: [radius, 0, 0], up: [0, 1, 0] };
+    case "-x":
+      return { position: [-radius, 0, 0], up: [0, 1, 0] };
+    case "+y":
+      return { position: [0, radius, 0], up: [0, 0, -1] };
+    case "-y":
+      return { position: [0, -radius, 0], up: [0, 0, 1] };
+    case "+z":
+      return { position: [0, 0, radius], up: [0, 1, 0] };
+    case "-z":
+      return { position: [0, 0, -radius], up: [0, 1, 0] };
+  }
+}
+
+export function easeToolcraftOrientationSnap(progress: number): number {
+  const value = Math.max(0, Math.min(1, progress));
+
+  return value * value * (3 - 2 * value);
+}
+
+export function getToolcraftOrientationSnapDurationMs(
+  startValue: ToolcraftOrientationPose,
+  endValue: ToolcraftOrientationPose,
+): number {
+  const start = getToolcraftOrientationCameraQuaternion(startValue);
+  const end = getToolcraftOrientationCameraQuaternion(endValue);
+  const cosine = Math.abs(
+    start.x * end.x + start.y * end.y + start.z * end.z + start.w * end.w,
+  );
+  const angle = 2 * Math.acos(Math.max(-1, Math.min(1, cosine)));
+
+  return (TOOLCRAFT_ORIENTATION_SMOOTH_VIEW_MS * angle) / Math.PI;
+}
+
+export function interpolateToolcraftOrientationPose(
+  startValue: ToolcraftOrientationPose,
+  endValue: ToolcraftOrientationPose,
+  progress: number,
+): ToolcraftOrientationPose {
+  const start = readToolcraftOrientationPose(startValue);
+  const end = readToolcraftOrientationPose(endValue, start);
+  const radius = getToolcraftOrientationRadius(start);
+  const quaternion = getToolcraftOrientationCameraQuaternion(start).slerp(
+    getToolcraftOrientationCameraQuaternion(end),
+    Math.max(0, Math.min(1, progress)),
+  );
+
+  return {
+    position: applyOrientationQuaternion([0, 0, radius], quaternion),
+    up: normalizeOrientationVector(
+      applyOrientationQuaternion([0, 1, 0], quaternion),
+    ),
+  };
+}

package/templates/runtime/react/orientation-gizmo/orientation-gizmo-public-api.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+
+import * as toolcraftReact from "../index";
+
+describe("Toolcraft orientation public API", () => {
+  it("exports the product integration boundary without exposing runtime visuals or quaternion internals", () => {
+    expect("readToolcraftOrientationPose" in toolcraftReact).toBe(true);
+    expect("useToolcraftModelOrbitInteraction" in toolcraftReact).toBe(true);
+    expect("ToolcraftOrientationGizmo" in toolcraftReact).toBe(false);
+    expect("ToolcraftOrientationQuaternion" in toolcraftReact).toBe(false);
+  });
+});

package/templates/runtime/react/orientation-gizmo/orientation-gizmo-selection.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from "vitest";
+
+import { defineToolcraft } from "../../schema/define-toolcraft";
+import { createToolcraftState } from "../../state/create-template-state";
+import {
+  getToolcraftOrientationControlEntries,
+  resolveToolcraftOrientationControl,
+} from "./orientation-gizmo-selection";
+
+const pose = { position: [0, 0, 5], up: [0, 1, 0] } as const;
+
+describe("Toolcraft orientation gizmo selection", () => {
+  it("selects the one visible declaration from mutually exclusive controls", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                first: {
+                  defaultValue: pose,
+                  keyframeable: false,
+                  label: false,
+                  target: "first.orbit",
+                  type: "orientationGizmo",
+                  visibleWhen: { equals: "first", target: "model.active" },
+                },
+                mode: {
+                  defaultValue: "first",
+                  label: "Model",
+                  options: [
+                    { label: "First", value: "first" },
+                    { label: "Second", value: "second" },
+                  ],
+                  target: "model.active",
+                  type: "select",
+                },
+                second: {
+                  defaultValue: pose,
+                  keyframeable: false,
+                  label: false,
+                  target: "second.orbit",
+                  type: "orientationGizmo",
+                  visibleWhen: { equals: "second", target: "model.active" },
+                },
+              },
+              title: "Model",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+    const entries = getToolcraftOrientationControlEntries(
+      schema.panels.controls?.sections ?? [],
+    );
+
+    expect(
+      resolveToolcraftOrientationControl(createToolcraftState(schema), entries)
+        ?.id,
+    ).toBe("first");
+    expect(
+      resolveToolcraftOrientationControl(
+        createToolcraftState(schema, { values: { "model.active": "second" } }),
+        entries,
+      )?.id,
+    ).toBe("second");
+  });
+
+  it("rejects an ambiguous runtime state instead of choosing declaration order", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                first: {
+                  defaultValue: pose,
+                  keyframeable: false,
+                  label: false,
+                  target: "first.orbit",
+                  type: "orientationGizmo",
+                },
+                modelScale: {
+                  defaultValue: 1,
+                  label: "Scale",
+                  target: "model.scale",
+                  type: "slider",
+                },
+                second: {
+                  defaultValue: pose,
+                  keyframeable: false,
+                  label: false,
+                  target: "second.orbit",
+                  type: "orientationGizmo",
+                },
+              },
+              title: "Model",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+    const entries = getToolcraftOrientationControlEntries(
+      schema.panels.controls?.sections ?? [],
+    );
+
+    expect(() =>
+      resolveToolcraftOrientationControl(createToolcraftState(schema), entries),
+    ).toThrow(/Multiple orientationGizmo controls are visible.*first.*second/);
+  });
+});

package/templates/runtime/react/orientation-gizmo/orientation-gizmo-selection.ts

@@ -0,0 +1,46 @@
+import type {
+  ToolcraftControlSchema,
+  ToolcraftControlSectionSchema,
+} from "../../schema/types";
+import type { ToolcraftState } from "../../state/types";
+import {
+  isToolcraftControlVisible,
+  isToolcraftSectionVisible,
+} from "../controls-panel/conditions/control-conditions";
+
+export type ToolcraftOrientationControlEntry = {
+  control: ToolcraftControlSchema;
+  id: string;
+  section: ToolcraftControlSectionSchema;
+};
+
+export function getToolcraftOrientationControlEntries(
+  sections: readonly ToolcraftControlSectionSchema[],
+): ToolcraftOrientationControlEntry[] {
+  return sections.flatMap((section) =>
+    Object.entries(section.controls).flatMap(([id, control]) =>
+      control.type === "orientationGizmo" ? [{ control, id, section }] : [],
+    ),
+  );
+}
+
+export function resolveToolcraftOrientationControl(
+  state: ToolcraftState,
+  entries: readonly ToolcraftOrientationControlEntry[],
+): ToolcraftOrientationControlEntry | null {
+  const visibleEntries = entries.filter(
+    ({ control, section }) =>
+      isToolcraftSectionVisible(state, section) &&
+      isToolcraftControlVisible(state, control),
+  );
+
+  if (visibleEntries.length > 1) {
+    throw new Error(
+      `Multiple orientationGizmo controls are visible at the same time: ${visibleEntries
+        .map(({ id }) => id)
+        .join(", ")}. Visibility conditions must select at most one canvas handle.`,
+    );
+  }
+
+  return visibleEntries[0] ?? null;
+}