Expand renderer vocabulary and annotation fallback

Co-authored-by: OpenAI Codex <codex@openai.com>

AGENTS.md

@@ -284,6 +284,22 @@ technical cutaway animation.
   movement, and the server clamps/coerces the threshold before selecting
   `render_mode`. The browser now trusts the server's `render_mode` and only
   downgrades when geometry or annotation data is missing.
+- Implemented the `FEATURE2.md` annotated-photo fallback pass: fixed portrait
+  and landscape image containment by giving the annotation frame a definite
+  viewport-bounded box, added numbered marker dots, leader lines, and optional
+  annotation bounding boxes, and kept all annotation text rendered through
+  `textContent`.
+- Implemented the `FEATURE3.md` renderer/prompt vocabulary pass: added
+  deterministic `cone`, `capsule`, `torus`, and `spring` shapes; added `screw`,
+  `orbit`, and `pulse` motions; raised the usable part cap to 6 across prompt,
+  schema, coercion, and browser renderability; and updated the sample analysis
+  to exercise all four new primitives.
+- Local verification after the `FEATURE2.md` / `FEATURE3.md` pass: schema and
+  coercion checks passed, FastAPI `TestClient` confirmed `/`, `/analyze_image`,
+  and `/generate_scene`, browser verification confirmed contained portrait and
+  landscape annotated-photo fallbacks with labels in bounds and no mobile
+  horizontal overflow, and the deterministic Three.js path reached
+  `CUTAWAY READY` with a nonblank six-part scene.
 
 ## Next Work
 

README.md

@@ -144,6 +144,13 @@ play/pause control. The confidence slider defaults to 50%, matching the
 server's fallback threshold, and the generation route is authoritative for the
 visible render mode.
 
+The deterministic renderer supports `box`, `cylinder`, `sphere`, `gear`, `rod`,
+`cone`, `capsule`, `torus`, and `spring` primitives, plus `static`, `rotate`,
+`oscillate`, `translate`, `screw`, `orbit`, and `pulse` motions. The
+annotated-photo fallback keeps the uploaded image contained in the viewport and
+draws marker dots, leader lines, and optional normalized bounding boxes from
+validated annotation data.
+
 The browser no longer injects model-authored HTML into the DOM. The model's
 job is limited to the structured analysis JSON contract in `snap2sim/schema.py`.
 

index.html

@@ -488,30 +488,59 @@
     }
 
     .annotated-stage {
-      display: grid;
-      place-items: center;
-      padding: 58px 18px 44px;
       background: rgba(15, 19, 24, 0.72);
     }
 
     .annotation-frame {
-      position: relative;
-      width: 100%;
-      height: 100%;
-      display: grid;
-      place-items: center;
+      position: absolute;
+      inset: 58px 18px 44px;
     }
 
     .annotation-image {
+      position: absolute;
+      inset: 0;
       width: 100%;
       height: 100%;
       object-fit: contain;
-      border: 1px solid rgba(122, 84, 32, 0.72);
+      outline: 1px solid rgba(122, 84, 32, 0.72);
       background: var(--bg);
     }
 
+    .photo-marker {
+      position: absolute;
+      width: 22px;
+      height: 22px;
+      transform: translate(-50%, -50%);
+      border: 1px solid var(--cyan);
+      border-radius: 50%;
+      color: var(--bg);
+      background: var(--cyan);
+      box-shadow: 0 0 16px rgba(95, 212, 208, 0.45);
+      display: grid;
+      place-items: center;
+      font: 0.68rem/1 "Fira Code", monospace;
+      pointer-events: none;
+    }
+
+    .photo-leader {
+      position: absolute;
+      height: 1px;
+      transform-origin: 0 50%;
+      background: rgba(95, 212, 208, 0.72);
+      pointer-events: none;
+    }
+
+    .photo-box {
+      position: absolute;
+      border: 1px solid rgba(95, 212, 208, 0.86);
+      background: rgba(95, 212, 208, 0.08);
+      box-shadow: inset 0 0 0 1px rgba(15, 19, 24, 0.45);
+      pointer-events: none;
+    }
+
     .photo-label {
       max-width: min(220px, 42vw);
+      transform: none;
       white-space: normal;
       text-transform: none;
     }
@@ -839,7 +868,7 @@
       return Boolean(analysis && Array.isArray(analysis.parts) && analysis.parts.some((part) => {
         const geometry = part && part.geometry;
         return geometry
-          && ["box", "cylinder", "sphere", "gear", "rod"].includes(geometry.shape)
+          && ["box", "cylinder", "sphere", "gear", "rod", "cone", "capsule", "torus", "spring"].includes(geometry.shape)
           && isNumberList(geometry.size, 3)
           && isNumberList(geometry.position, 3);
       }));
@@ -936,6 +965,10 @@
         mesh.userData.basePosition = mesh.position.clone();
         mesh.userData.baseRotation = mesh.rotation.clone();
         mesh.userData.part = part;
+        const pivot = part.motion && isNumberList(part.motion.pivot, 3)
+          ? part.motion.pivot
+          : [0, 0, 0];
+        mesh.userData.pivot = new THREE.Vector3(pivot[0], pivot[1], pivot[2]);
         mesh.scale.setScalar(0.001);
         scene.add(mesh);
         return mesh;
@@ -1032,19 +1065,48 @@
         if (disposed) return;
         const imageRect = containedImageRect(image);
         const layerRect = labelLayer.getBoundingClientRect();
-        labelLayer.replaceChildren(...annotatedParts.map((part, index) => {
+        if (imageRect.width < 1 || imageRect.height < 1 || layerRect.width < 1 || layerRect.height < 1) return;
+        const nodes = [];
+        for (const [index, part] of annotatedParts.entries()) {
           const annotation = part.annotation || {};
           const point = annotation.point || [0.5, 0.5];
+          const pointX = imageRect.left - layerRect.left + clamp01(point[0]) * imageRect.width;
+          const pointY = imageRect.top - layerRect.top + clamp01(point[1]) * imageRect.height;
+          if (isNumberList(annotation.box, 4)) {
+            const [boxX, boxY, boxW, boxH] = annotation.box.map(clamp01);
+            const box = document.createElement("div");
+            box.className = "photo-box";
+            box.style.left = (imageRect.left - layerRect.left + boxX * imageRect.width) + "px";
+            box.style.top = (imageRect.top - layerRect.top + boxY * imageRect.height) + "px";
+            box.style.width = (Math.min(boxW, 1 - boxX) * imageRect.width) + "px";
+            box.style.height = (Math.min(boxH, 1 - boxY) * imageRect.height) + "px";
+            nodes.push(box);
+          }
+
+          const marker = document.createElement("div");
+          marker.className = "photo-marker";
+          marker.style.left = pointX + "px";
+          marker.style.top = pointY + "px";
+          marker.textContent = String(index + 1);
+          nodes.push(marker);
+
+          const labelWidth = Math.min(220, Math.max(120, layerRect.width * 0.42), Math.max(80, layerRect.width - 24));
+          const preferLeft = pointX > layerRect.width * 0.62;
+          const maxLabelX = Math.max(12, layerRect.width - labelWidth - 12);
+          const maxLabelY = Math.max(12, layerRect.height - 82);
+          const labelX = Math.min(
+            maxLabelX,
+            Math.max(12, pointX + (preferLeft ? -labelWidth - 28 : 28))
+          );
+          const labelY = Math.min(
+            maxLabelY,
+            Math.max(12, pointY - 42)
+          );
           const label = document.createElement("div");
           label.className = "scene-label photo-label";
-          label.style.left = Math.min(
-            layerRect.width - 72,
-            Math.max(72, imageRect.left - layerRect.left + clamp01(point[0]) * imageRect.width)
-          ) + "px";
-          label.style.top = Math.min(
-            layerRect.height - 36,
-            Math.max(56, imageRect.top - layerRect.top + clamp01(point[1]) * imageRect.height)
-          ) + "px";
+          label.style.left = labelX + "px";
+          label.style.top = labelY + "px";
+          label.style.width = labelWidth + "px";
 
           const title = document.createElement("span");
           title.className = "label-title";
@@ -1057,8 +1119,19 @@
             note.textContent = noteText;
             label.append(note);
           }
-          return label;
-        }));
+          const labelAnchorX = preferLeft ? labelX + labelWidth : labelX;
+          const labelAnchorY = labelY + 24;
+          const dx = labelAnchorX - pointX;
+          const dy = labelAnchorY - pointY;
+          const leader = document.createElement("div");
+          leader.className = "photo-leader";
+          leader.style.left = pointX + "px";
+          leader.style.top = pointY + "px";
+          leader.style.width = Math.max(0, Math.hypot(dx, dy) - 13) + "px";
+          leader.style.transform = "rotate(" + Math.atan2(dy, dx) + "rad)";
+          nodes.push(leader, label);
+        }
+        labelLayer.replaceChildren(...nodes);
       }
 
       image.addEventListener("load", updatePhotoLabels, { once: true });
@@ -1141,18 +1214,34 @@
     function buildPartMesh(part, index) {
       const geometryData = part.geometry || {};
       const size = Array.isArray(geometryData.size) ? geometryData.size : [1, 1, 1];
+      const x = Math.max(0.05, Number(size[0]) || 1);
+      const y = Math.max(0.05, Number(size[1]) || 1);
+      const z = Math.max(0.05, Number(size[2]) || 1);
       let geometry;
       if (geometryData.shape === "cylinder") {
-        geometry = new THREE.CylinderGeometry(size[0] / 2, size[2] / 2, size[1], 48);
+        const radius = Math.max(x, z) / 2;
+        geometry = new THREE.CylinderGeometry(radius, radius, y, 48);
+      } else if (geometryData.shape === "cone") {
+        geometry = new THREE.ConeGeometry(Math.max(x, z) / 2, y, 48);
       } else if (geometryData.shape === "sphere") {
-        geometry = new THREE.SphereGeometry(Math.max(size[0], size[1], size[2]) / 2, 36, 18);
+        geometry = new THREE.SphereGeometry(Math.max(x, y, z) / 2, 36, 18);
+      } else if (geometryData.shape === "capsule") {
+        const radius = Math.min(Math.max(x, z) / 2, y / 2);
+        geometry = new THREE.CapsuleGeometry(radius, Math.max(0.05, y - radius * 2), 8, 24);
       } else if (geometryData.shape === "rod") {
-        geometry = new THREE.CylinderGeometry(Math.max(size[0], size[1]) / 2, Math.max(size[0], size[1]) / 2, size[2], 24);
+        geometry = new THREE.CylinderGeometry(Math.max(x, y) / 2, Math.max(x, y) / 2, z, 24);
         geometry.rotateX(Math.PI / 2);
       } else if (geometryData.shape === "gear") {
-        geometry = gearGeometry(Math.max(size[0], size[2]) / 2, size[1], geometryData.teeth || 18);
+        geometry = gearGeometry(Math.max(x, z) / 2, y, geometryData.teeth || 18);
+      } else if (geometryData.shape === "torus") {
+        const outerRadius = Math.max(x, z) / 2;
+        const tube = Math.min(y / 2, outerRadius * 0.36);
+        geometry = new THREE.TorusGeometry(Math.max(0.05, outerRadius - tube), Math.max(0.025, tube), 16, 64);
+        geometry.rotateX(Math.PI / 2);
+      } else if (geometryData.shape === "spring") {
+        geometry = springGeometry(Math.max(x, z) / 2, y, geometryData.coils || 5, geometryData.wire);
       } else {
-        geometry = new THREE.BoxGeometry(size[0], size[1], size[2]);
+        geometry = new THREE.BoxGeometry(x, y, z);
       }
 
       const color = colorFor(geometryData.color, index);
@@ -1186,6 +1275,25 @@
       return geometry;
     }
 
+    function springGeometry(outerRadius, height, coils, wire) {
+      const safeCoils = Math.max(2, Math.min(12, Number(coils) || 5));
+      const radius = Math.max(0.08, outerRadius * 0.72);
+      const wireRadius = Math.max(0.018, Math.min(Number(wire) || outerRadius * 0.08, outerRadius * 0.18));
+      const points = [];
+      const steps = Math.ceil(safeCoils * 28);
+      for (let i = 0; i <= steps; i += 1) {
+        const t = i / steps;
+        const angle = t * safeCoils * Math.PI * 2;
+        points.push(new THREE.Vector3(
+          Math.cos(angle) * radius,
+          (t - 0.5) * height,
+          Math.sin(angle) * radius
+        ));
+      }
+      const curve = new THREE.CatmullRomCurve3(points);
+      return new THREE.TubeGeometry(curve, steps, wireRadius, 8, false);
+    }
+
     function revealMesh(mesh, elapsed, index) {
       const local = Math.max(0, Math.min(1, (elapsed - index * 0.1) / 0.55));
       const eased = 1 - Math.pow(1 - local, 3);
@@ -1207,6 +1315,22 @@
         const range = motion.range || [-0.25, 0.25];
         const offset = range[0] + (range[1] - range[0]) * ((Math.sin(elapsed * speed + phase) + 1) / 2);
         mesh.position.add(axis.multiplyScalar(offset));
+      } else if (motion.type === "screw") {
+        const range = motion.range || [-0.18, 0.18];
+        const pitch = Number(motion.pitch || 0.18);
+        const turn = elapsed * speed + phase;
+        mesh.rotateOnAxis(axis, turn);
+        const offset = range[0] + (range[1] - range[0]) * ((Math.sin(turn) + 1) / 2) + Math.sin(turn) * pitch;
+        mesh.position.add(axis.multiplyScalar(offset));
+      } else if (motion.type === "orbit") {
+        const pivot = mesh.userData.pivot || new THREE.Vector3(0, 0, 0);
+        const offset = mesh.userData.basePosition.clone().sub(pivot).applyAxisAngle(axis, elapsed * speed + phase);
+        mesh.position.copy(pivot).add(offset);
+        mesh.rotateOnAxis(axis, elapsed * speed + phase);
+      } else if (motion.type === "pulse") {
+        const amplitude = Number(motion.amplitude || 0.18);
+        const scalar = Math.max(0.2, 1 + Math.sin(elapsed * speed + phase) * amplitude);
+        mesh.scale.multiplyScalar(scalar);
       }
     }
 

snap2sim/model_io.py

@@ -114,7 +114,7 @@ def _coerce_analysis_payload(payload: dict[str, Any], fallback_component: str) -
     parts = payload.get("parts")
     if not isinstance(parts, list):
         parts = []
-    coerced_parts = [_coerce_part(part, index) for index, part in enumerate(parts[:4]) if isinstance(part, dict)]
+    coerced_parts = [_coerce_part(part, index) for index, part in enumerate(parts[:6]) if isinstance(part, dict)]
     coerced_parts = [part for part in coerced_parts if part is not None]
     if not coerced_parts:
         coerced_parts = _generic_analysis(fallback_component)["parts"]
@@ -163,22 +163,25 @@ def _coerce_part(part: dict[str, Any], index: int) -> dict[str, Any] | None:
         return base_part
 
     shape = geometry.get("shape")
-    if shape not in {"box", "cylinder", "sphere", "gear", "rod"}:
+    if shape not in {"box", "cylinder", "sphere", "gear", "rod", "cone", "capsule", "torus", "spring"}:
         shape = "box"
     motion_type = motion.get("type")
-    if motion_type not in {"rotate", "translate", "oscillate", "static"}:
+    if motion_type not in {"rotate", "translate", "oscillate", "static", "screw", "orbit", "pulse"}:
         motion_type = "static"
 
     coerced_motion: dict[str, Any] = {"type": motion_type}
     axis = _axis_vector(motion.get("axis"))
     if axis:
         coerced_motion["axis"] = axis
-    for key in ["speed", "amplitude", "phase"]:
+    for key in ["speed", "amplitude", "phase", "pitch"]:
         if isinstance(motion.get(key), (int, float)) and not isinstance(motion.get(key), bool):
             coerced_motion[key] = float(motion[key])
     values = _number_list(motion.get("range"), 2)
     if values:
         coerced_motion["range"] = values
+    values = _number_list(motion.get("pivot"), 3)
+    if values:
+        coerced_motion["pivot"] = values
 
     coerced_geometry: dict[str, Any] = {
         "shape": shape,
@@ -190,6 +193,10 @@ def _coerce_part(part: dict[str, Any], index: int) -> dict[str, Any] | None:
         coerced_geometry["rotation"] = values
     if isinstance(geometry.get("teeth"), int):
         coerced_geometry["teeth"] = geometry["teeth"]
+    if isinstance(geometry.get("coils"), int):
+        coerced_geometry["coils"] = geometry["coils"]
+    if isinstance(geometry.get("wire"), (int, float)) and not isinstance(geometry.get("wire"), bool):
+        coerced_geometry["wire"] = float(geometry["wire"])
     if isinstance(geometry.get("color"), str) and geometry["color"].strip():
         coerced_geometry["color"] = geometry["color"].strip()
 
@@ -276,7 +283,7 @@ def _geometry_size(geometry: dict[str, Any], shape: str) -> list[float]:
     length = _number_value(geometry.get("length"))
     width = _number_value(geometry.get("width"))
     depth = _number_value(geometry.get("depth"))
-    if shape in {"cylinder", "gear"} and radius and height:
+    if shape in {"cylinder", "gear", "cone", "capsule", "torus", "spring"} and radius and height:
         diameter = radius * 2
         return [diameter, height, diameter]
     if shape == "rod" and (length or height) and radius:
@@ -310,9 +317,9 @@ def _number_value(value: Any) -> float | None:
 
 def _unit_number_list(value: Any, length: int) -> list[float] | None:
     values = _number_list(value, length)
-    if not values or not all(0 <= item <= 1 for item in values):
+    if not values:
         return None
-    return values
+    return [max(0.0, min(1.0, item)) for item in values]
 
 
 def _coerce_annotation(value: Any) -> dict[str, Any] | None:

snap2sim/prompts.py

@@ -2,37 +2,51 @@
 
 from __future__ import annotations
 
-VISION_SYSTEM_PROMPT = """You are a mechanical teardown analyst.
-Given an image of a hardware component, infer the most likely internal
-mechanism and return only JSON matching the provided schema. Prefer clear,
-physically plausible primitive geometry over speculative detail. If the photo is
-ambiguous, state lower confidence and identify visible components with photo
-annotations instead of forcing a speculative 3D mechanism."""
+VISION_SYSTEM_PROMPT = """You are a mechanical teardown analyst for an annotated
+technical cutaway demo. Reason briefly if useful, then emit exactly one JSON
+object matching the schema. Prefer the simplest truthful primitive mechanism.
+If the photo is ambiguous, lower confidence and use visible photo annotations
+instead of forcing speculative 3D geometry."""
 
 
 def build_vision_prompt() -> str:
     return (
         "Analyze the uploaded hardware component as a cutaway mechanism. "
-        "You may reason first if needed, but the final answer must be one JSON "
-        "object. Do not include markdown. Keep the final payload compact and "
-        "physically plausible for primitive Three.js rendering.\n\n"
+        "Final answer must be one JSON object with no markdown.\n\n"
         "Required top-level keys: component, confidence, summary, trigger, "
         "motion_sequence, parts. Optional top-level render_mode is three, "
         "annotate, or unavailable.\n"
         "Each part requires: id, name, role, and either geometry plus motion, "
         "or annotation when the visible component can be located but 3D "
         "geometry is uncertain.\n"
-        "Allowed geometry.shape values: box, cylinder, sphere, gear, rod.\n"
-        "Allowed motion.type values: rotate, translate, oscillate, static.\n"
+        "Shapes, with size always [x, y, z] extents:\n"
+        "- box: plates, housings, blocks, levers, selectors\n"
+        "- cylinder: shafts, sleeves, bushings, drums, pins\n"
+        "- cone: valve cones, tips, nozzles, tapers\n"
+        "- capsule: pistons, rollers, dowel pins, plungers, bearings\n"
+        "- sphere: balls, detents, ball bearings, nodes\n"
+        "- rod: links, tie rods, thin axles, connecting rods\n"
+        "- gear: toothed wheels, ratchets, cogs; set teeth when useful\n"
+        "- torus: o-rings, snap rings, seals, washers, single coils\n"
+        "- spring: helical springs and coils; set coils when useful\n\n"
+        "Motions, with axis as a numeric vector like [0, 1, 0]:\n"
+        "- static: fixed structure or housing\n"
+        "- rotate: continuous spin; use speed\n"
+        "- oscillate: sinusoidal twist; use amplitude and speed\n"
+        "- translate: slide along axis; use range [min, max]\n"
+        "- screw: spin plus advance along axis; use pitch for helical action\n"
+        "- orbit: revolve around pivot [x, y, z]\n"
+        "- pulse: scale breathing for diaphragms, springs, valves, pumps\n\n"
         "Every geometry must use size: [x, y, z] and position: [x, y, z]. "
         "Do not use radius, height, length, width, or depth fields. Every "
         "motion axis must be a numeric vector such as [0, 1, 0], never a string "
         "like x, y, or z.\n\n"
-        "Use 2 to 4 parts. Keep names and descriptions short. When possible, "
+        "Use 2 to 6 parts; prefer the fewest that explain the mechanism. "
+        "Keep names and descriptions short. When possible, "
         "include annotation.point in normalized image coordinates [x, y] with "
         "origin at top-left, plus a short annotation.note. Optional "
         "annotation.box is [x, y, width, height], also normalized from 0 to 1.\n\n"
-        "Use this shape:\n"
+        "Use this compact shape:\n"
         "{\n"
         '  "component": "short component name",\n'
         '  "confidence": 0.7,\n'
@@ -44,13 +58,13 @@ def build_vision_prompt() -> str:
         '      "id": "part_id",\n'
         '      "name": "part name",\n'
         '      "role": "mechanical role",\n'
-        '      "geometry": {"shape": "box", "size": [1, 1, 1], "position": [0, 0, 0]},\n'
-        '      "motion": {"type": "static"},\n'
+        '      "geometry": {"shape": "spring", "size": [0.4, 1.2, 0.4], "position": [0, 0, 0], "coils": 6},\n'
+        '      "motion": {"type": "pulse", "speed": 2, "amplitude": 0.08},\n'
         '      "annotation": {"point": [0.5, 0.5], "label": "visible label", "note": "short visible clue"}\n'
         "    }\n"
         "  ]\n"
         "}\n\n"
-        "Optional geometry fields: rotation, teeth, color. Optional motion "
-        "fields: axis, speed, amplitude, phase, range. Include optional fields "
-        "only when useful."
+        "Optional geometry fields: rotation, teeth, coils, wire, color. Optional "
+        "motion fields: axis, speed, amplitude, phase, range, pitch, pivot. "
+        "Include optional fields only when useful."
     )

snap2sim/schema.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import math
 from typing import Any, Literal
 
-MotionType = Literal["rotate", "translate", "oscillate", "static"]
+MotionType = Literal["rotate", "translate", "oscillate", "static", "screw", "orbit", "pulse"]
 
 
 EXAMPLE_ANALYSIS: dict[str, Any] = {
@@ -19,7 +19,7 @@ EXAMPLE_ANALYSIS: dict[str, Any] = {
     "trigger": "handle swings clockwise and counterclockwise",
     "motion_sequence": [
         "handle applies torque to the outer head",
-        "pawl tooth locks into the ratchet gear",
+        "spring-loaded pawl locks into the ratchet gear",
         "gear and socket rotate on the drive stroke",
         "pawl rides over gear teeth on the return stroke",
     ],
@@ -70,10 +70,10 @@ EXAMPLE_ANALYSIS: dict[str, Any] = {
             "name": "spring pawl",
             "role": "locks and releases against gear teeth",
             "geometry": {
-                "shape": "box",
-                "size": [0.32, 0.35, 1.1],
+                "shape": "cone",
+                "size": [0.34, 0.62, 0.34],
                 "position": [1.25, 0.3, 0.18],
-                "rotation": [0, 0.35, 0],
+                "rotation": [0.55, 0, -0.75],
                 "color": "amber",
             },
             "motion": {
@@ -90,20 +90,63 @@ EXAMPLE_ANALYSIS: dict[str, Any] = {
             },
         },
         {
-            "id": "selector",
-            "name": "direction selector",
-            "role": "flips the pawl angle for reverse drive",
+            "id": "pawl_spring",
+            "name": "pawl return spring",
+            "role": "pushes the pawl back into the gear teeth",
             "geometry": {
-                "shape": "box",
-                "size": [0.9, 0.2, 0.32],
-                "position": [0, 0.68, -1.05],
+                "shape": "spring",
+                "coils": 6,
+                "wire": 0.035,
+                "size": [0.34, 0.9, 0.34],
+                "position": [1.55, 0.32, -0.2],
+                "rotation": [0.2, 0, 0.45],
                 "color": "orange",
             },
+            "motion": {"type": "pulse", "speed": 2.4, "amplitude": 0.08},
+            "annotation": {
+                "point": [0.72, 0.5],
+                "label": "return spring",
+                "note": "small spring biasing the locking pawl",
+            },
+        },
+        {
+            "id": "selector_pin",
+            "name": "selector pin",
+            "role": "slides the selector and changes pawl bias direction",
+            "geometry": {
+                "shape": "capsule",
+                "size": [0.22, 0.85, 0.22],
+                "position": [-0.95, 0.56, -0.95],
+                "rotation": [1.5708, 0, 0.25],
+                "color": "steel",
+            },
+            "motion": {
+                "type": "translate",
+                "axis": [1, 0, 0],
+                "range": [-0.08, 0.08],
+                "speed": 1.3,
+            },
+            "annotation": {
+                "point": [0.38, 0.3],
+                "label": "selector pin",
+                "note": "rounded pin under the direction selector",
+            },
+        },
+        {
+            "id": "retaining_ring",
+            "name": "retaining ring",
+            "role": "keeps the socket gear captured in the head",
+            "geometry": {
+                "shape": "torus",
+                "size": [1.9, 0.18, 1.9],
+                "position": [0, 0.43, 0],
+                "color": "cyan",
+            },
             "motion": {"type": "static"},
             "annotation": {
-                "point": [0.5, 0.28],
-                "label": "selector",
-                "note": "external control that reverses drive direction",
+                "point": [0.5, 0.36],
+                "label": "retaining ring",
+                "note": "circular clip around the socket drive",
             },
         },
     ],
@@ -122,6 +165,7 @@ ANALYSIS_SCHEMA: dict[str, Any] = {
         "motion_sequence": {"type": "array", "items": {"type": "string"}},
         "parts": {
             "type": "array",
+            "maxItems": 6,
             "items": {
                 "type": "object",
                 "required": ["id", "name", "role"],
@@ -135,7 +179,17 @@ ANALYSIS_SCHEMA: dict[str, Any] = {
                         "properties": {
                             "shape": {
                                 "type": "string",
-                                "enum": ["box", "cylinder", "sphere", "gear", "rod"],
+                                "enum": [
+                                    "box",
+                                    "cylinder",
+                                    "sphere",
+                                    "gear",
+                                    "rod",
+                                    "cone",
+                                    "capsule",
+                                    "torus",
+                                    "spring",
+                                ],
                             },
                             "size": {
                                 "type": "array",
@@ -156,6 +210,8 @@ ANALYSIS_SCHEMA: dict[str, Any] = {
                                 "maxItems": 3,
                             },
                             "teeth": {"type": "integer", "minimum": 6, "maximum": 80},
+                            "coils": {"type": "integer", "minimum": 2, "maximum": 12},
+                            "wire": {"type": "number"},
                             "color": {"type": "string"},
                         },
                     },
@@ -165,7 +221,15 @@ ANALYSIS_SCHEMA: dict[str, Any] = {
                         "properties": {
                             "type": {
                                 "type": "string",
-                                "enum": ["rotate", "translate", "oscillate", "static"],
+                                "enum": [
+                                    "rotate",
+                                    "translate",
+                                    "oscillate",
+                                    "static",
+                                    "screw",
+                                    "orbit",
+                                    "pulse",
+                                ],
                             },
                             "axis": {
                                 "type": "array",
@@ -182,6 +246,13 @@ ANALYSIS_SCHEMA: dict[str, Any] = {
                                 "minItems": 2,
                                 "maxItems": 2,
                             },
+                            "pitch": {"type": "number"},
+                            "pivot": {
+                                "type": "array",
+                                "items": {"type": "number"},
+                                "minItems": 3,
+                                "maxItems": 3,
+                            },
                         },
                     },
                     "annotation": {
@@ -211,8 +282,8 @@ ANALYSIS_SCHEMA: dict[str, Any] = {
 }
 
 
-_SHAPES = {"box", "cylinder", "sphere", "gear", "rod"}
-_MOTIONS = {"rotate", "translate", "oscillate", "static"}
+_SHAPES = {"box", "cylinder", "sphere", "gear", "rod", "cone", "capsule", "torus", "spring"}
+_MOTIONS = {"rotate", "translate", "oscillate", "static", "screw", "orbit", "pulse"}
 _RENDER_MODES = {"three", "annotate", "unavailable"}
 DEFAULT_CONFIDENCE_THRESHOLD = 0.5
 
@@ -274,6 +345,8 @@ def validate_analysis(payload: dict[str, Any]) -> dict[str, Any]:
     parts = payload.get("parts")
     if not isinstance(parts, list) or not parts:
         raise ValueError("Invalid analysis payload at parts: expected a non-empty list")
+    if len(parts) > 6:
+        raise ValueError("Invalid analysis payload at parts: expected no more than 6 items")
 
     for index, part in enumerate(parts):
         path = f"parts.{index}"
@@ -296,6 +369,10 @@ def validate_analysis(payload: dict[str, Any]) -> dict[str, Any]:
                 _require_number_list(geometry, "rotation", f"{path}.geometry.rotation", 3)
             if "teeth" in geometry and not isinstance(geometry["teeth"], int):
                 raise ValueError(f"Invalid analysis payload at {path}.geometry.teeth: expected an integer")
+            if "coils" in geometry and not isinstance(geometry["coils"], int):
+                raise ValueError(f"Invalid analysis payload at {path}.geometry.coils: expected an integer")
+            if "wire" in geometry and not _is_number(geometry["wire"]):
+                raise ValueError(f"Invalid analysis payload at {path}.geometry.wire: expected a number")
             has_geometry = True
 
         has_annotation = False
@@ -327,7 +404,9 @@ def validate_analysis(payload: dict[str, Any]) -> dict[str, Any]:
                 _require_number_list(motion, "axis", f"{path}.motion.axis", 3)
             if "range" in motion:
                 _require_number_list(motion, "range", f"{path}.motion.range", 2)
-            for key in ["speed", "amplitude", "phase"]:
+            if "pivot" in motion:
+                _require_number_list(motion, "pivot", f"{path}.motion.pivot", 3)
+            for key in ["speed", "amplitude", "phase", "pitch"]:
                 if key in motion and not _is_number(motion[key]):
                     raise ValueError(f"Invalid analysis payload at {path}.motion.{key}: expected a number")
         elif has_geometry: