@tscircuit/core 0.0.2115 → 0.0.2117

package/dist/index.js

@@ -27,6 +27,7 @@ __export(components_exports, {
   AssemblyMotor: () => AssemblyMotor,
   AssemblyPart: () => AssemblyPart,
   AssemblyPrintedPart: () => AssemblyPrintedPart,
+  AssemblyReferenceSurface: () => AssemblyReferenceSurface,
   AssemblyScreen: () => AssemblyScreen,
   AssemblySubassembly: () => AssemblySubassembly,
   AutoroutingPhase: () => AutoroutingPhase,
@@ -14772,6 +14773,30 @@ var matchesAssemblyIdentity = (component, path) => {
   return true;
 };
 
+// lib/components/primitive-components/get-part-reference-surfaces.ts
+import {
+  resolveReferencePlanes
+} from "jscad-planner";
+var getPartReferenceSurfaces = (part) => {
+  const model = part._parsedProps.cadModel;
+  const authored = part.componentName === "AssemblyPrintedPart" ? part.printedPartPlan?.referencePlanes ?? (model && typeof model === "object" && "jscad" in model ? resolveReferencePlanes(model.jscad).referencePlanes : []) : [];
+  const surfaces = [
+    ...authored,
+    ...part.children.filter(
+      (child) => child.componentName === "AssemblyReferenceSurface"
+    ).map((child) => child.referenceFrame)
+  ];
+  const names = /* @__PURE__ */ new Set();
+  for (const surface of surfaces) {
+    if (names.has(surface.name))
+      throw new Error(
+        `Part "${part.name}" has duplicate reference surface "${surface.name}"`
+      );
+    names.add(surface.name);
+  }
+  return surfaces;
+};
+
 // lib/components/primitive-components/get-assembly-scope-components.ts
 var getAssemblyScope = (component) => {
   let ancestor = component.parent;
@@ -14789,9 +14814,19 @@ var getComponentsInAssemblyScope = (component) => {
 };
 
 // lib/components/primitive-components/resolve-printed-part-mounts.ts
-var isMountablePart = (part) => part.componentName === "AssemblyMotor" || part.componentName === "AssemblyPrintedPart";
+var isMountablePart = (part) => part.componentName === "AssemblyMotor" || part.componentName === "AssemblyPart" || part.componentName === "AssemblyPrintedPart";
 var isPrintedPart = (part) => part.componentName === "AssemblyPrintedPart";
+var isMotor = (part) => part.componentName === "AssemblyMotor";
 var identity7 = () => [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+var getMountTransformPlacement = (world) => {
+  const bottom = world[10] < 0;
+  const sign = bottom ? -1 : 1;
+  return {
+    position: { x: world[12], y: world[13], z: world[14] },
+    pcbRotation: Math.atan2(sign * world[1], sign * world[0]) * 180 / Math.PI,
+    layer: bottom ? "bottom" : "top"
+  };
+};
 var faceMatrix = ({
   origin,
   normal,
@@ -14806,14 +14841,12 @@ var faceMatrix = ({
   );
 };
 var getFace = (part, faceName) => {
-  if (isPrintedPart(part)) {
-    const face = part.printedPartPlan?.referencePlanes.find(
+  if (!isMotor(part)) {
+    const face = getPartReferenceSurfaces(part).find(
       (face2) => face2.name === faceName
     );
     if (!face)
-      throw new Error(
-        `Printed part "${part.name}" has no reference face "${faceName}"`
-      );
+      throw new Error(`Part "${part.name}" has no reference face "${faceName}"`);
     return face;
   }
   if (faceName !== "backface" && faceName !== "frontface")
@@ -14845,9 +14878,21 @@ var findTarget = (owner, selector, parts) => {
   const part = matches[0];
   return { part, face: getFace(part, faceName) };
 };
-var rootOrientation = (part) => {
+var rootOrientation = (part, placement) => {
   const result = identity7();
   if (isPrintedPart(part)) return result;
+  if (!isMotor(part)) {
+    if (!placement)
+      throw new Error(`Part "${part.name}" has no inherited placement`);
+    mat4.translate(result, result, [
+      placement.position.x,
+      placement.position.y,
+      placement.position.z
+    ]);
+    mat4.rotateZ(result, result, placement.pcbRotation * Math.PI / 180);
+    if (placement.layer === "bottom") mat4.rotateY(result, result, Math.PI);
+    return result;
+  }
   switch (part._parsedProps.shaftFacingDirection) {
     case "x+":
       return mat4.rotateY(result, result, Math.PI / 2);
@@ -14877,9 +14922,25 @@ var resolvePrintedPartMounts = (component) => {
       );
     const existing = transforms.get(part);
     if (existing) return existing;
-    let world = rootOrientation(part);
+    let world;
     let root = part;
-    if (part._parsedProps.mountedTo) {
+    const parent = part.componentName === "AssemblyPart" ? findParentAssembly(part) : void 0;
+    if (parent && isMountablePart(parent)) {
+      world = [...resolvePart(parent, [...path, part])];
+      root = roots.get(parent);
+    } else {
+      const placement = part.componentName === "AssemblyPart" ? resolveInheritedAssemblyPlacement(
+        part,
+        [],
+        (target) => {
+          const targetWorld = resolvePart(target, [...path, part]);
+          root = roots.get(target);
+          return getMountTransformPlacement(targetWorld);
+        }
+      ) : void 0;
+      world = rootOrientation(part, placement);
+    }
+    if ((isMotor(part) || isPrintedPart(part)) && part._parsedProps.mountedTo) {
       const { part: target, face } = findTarget(
         part,
         part._parsedProps.mountedTo,
@@ -14904,7 +14965,7 @@ var resolvePrintedPartMounts = (component) => {
   };
   for (const part of parts) resolvePart(part);
   const motorMountRoots = new Set(
-    parts.filter((part) => !isPrintedPart(part) && part._parsedProps.mountedTo).map((part) => roots.get(part))
+    parts.filter((part) => isMotor(part) && part._parsedProps.mountedTo).map((part) => roots.get(part))
   );
   const anchoredRoots = /* @__PURE__ */ new Set();
   for (const board of scoped.filter(
@@ -14922,7 +14983,7 @@ var resolvePrintedPartMounts = (component) => {
         `Assembly "${root.name}" has multiple mounted boards; only one board may determine its placement`
       );
     anchoredRoots.add(root);
-    if (!isPrintedPart(root) && !["z+", "z-"].includes(root._parsedProps.shaftFacingDirection ?? "z+"))
+    if (isMotor(root) && !["z+", "z-"].includes(root._parsedProps.shaftFacingDirection ?? "z+"))
       throw new Error(
         `Board "${board.name}" cannot mount to motor "${root.name}" facing ${root._parsedProps.shaftFacingDirection}: rotated PCB boards are not yet supported`
       );
@@ -14995,7 +15056,7 @@ var boardMountsToPrintedPart = (board) => {
   if (!selector) return false;
   const partName = selector.slice(0, selector.lastIndexOf("."));
   return getComponentsInAssemblyScope(board).some(
-    (part) => part.componentName === "AssemblyPrintedPart" && matchesAssemblyIdentity(part, partName)
+    (part) => (part.componentName === "AssemblyPrintedPart" || part.componentName === "AssemblyPart") && matchesAssemblyIdentity(part, partName)
   );
 };
 
@@ -15050,17 +15111,32 @@ var findParentAssembly = (component) => {
   return void 0;
 };
 var resolveAssemblyPlacement = (component, path = []) => {
-  if (component.componentName === "AssemblyPrintedPart") {
+  if (path.includes(component)) {
+    throw new Error(
+      `Assembly attachment cycle: ${[...path, component].map((item) => item.name).join(" -> ")}`
+    );
+  }
+  if (component.componentName === "AssemblyPrintedPart" || component.componentName === "AssemblyPart") {
     const part = component;
     const { transforms, subcircuitId } = resolvePrintedPartMounts(part);
     const transform = transforms.get(part);
+    if (part.componentName === "AssemblyPart")
+      return {
+        ...getMountTransformPlacement(transform),
+        worldTransform: Math.abs(Math.abs(transform[10]) - 1) > 1e-6 ? transform : void 0,
+        subcircuit_id: subcircuitId
+      };
     return {
+      worldTransform: transform,
       position: { x: transform[12], y: transform[13], z: transform[14] },
       pcbRotation: 0,
       layer: "top",
       subcircuit_id: subcircuitId
     };
   }
+  return resolveInheritedAssemblyPlacement(component, path);
+};
+var resolveInheritedAssemblyPlacement = (component, path = [], resolvePartPlacement) => {
   if (path.includes(component)) {
     throw new Error(
       `Assembly attachment cycle: ${[...path, component].map((item) => item.name).join(" -> ")}`
@@ -15073,6 +15149,14 @@ var resolveAssemblyPlacement = (component, path = []) => {
   ) : findParentAssembly(component);
   if (!target)
     return { position: { x: 0, y: 0, z: 0 }, pcbRotation: 0, layer: "top" };
+  if (resolvePartPlacement && (target.componentName === "AssemblyPart" || target.componentName === "AssemblyPrintedPart"))
+    return resolvePartPlacement(target);
+  if (resolvePartPlacement && isPositionedAssembly(target))
+    return resolveInheritedAssemblyPlacement(
+      target,
+      nextPath,
+      resolvePartPlacement
+    );
   if (isPositionedAssembly(target))
     return resolveAssemblyPlacement(target, nextPath);
   const db2 = component.root.db;
@@ -15201,6 +15285,20 @@ var resolveAssemblyModelUrl = (modelUrl) => {
 import { normalizeDegrees as normalizeDegrees4 } from "@tscircuit/math-utils";
 import { cadModelBase, point3 } from "@tscircuit/props";
 import { rotation } from "circuit-json";
+import { mat4 as mat42, vec3 as vec32 } from "gl-matrix";
+
+// lib/components/primitive-components/get-assembly-euler-angles.ts
+var getAssemblyEulerAngles = (transform) => {
+  const y2 = Math.asin(Math.max(-1, Math.min(1, -transform[2])));
+  const angles = Math.abs(Math.cos(y2)) > 1e-8 ? [
+    Math.atan2(transform[6], transform[10]),
+    y2,
+    Math.atan2(transform[1], transform[0])
+  ] : [0, y2, Math.atan2(-transform[4], transform[5])];
+  return angles.map((angle) => angle === 0 ? 0 : angle);
+};
+
+// lib/components/primitive-components/render-assembly-cad-model.ts
 import {
   applyToPoint as applyToPoint29,
   compose as compose8,
@@ -15226,6 +15324,28 @@ var renderAssemblyCadModel = (owner, model, placement) => {
     z: rotation.parse(authoredRotation.z)
   };
   const assetUrl = (url) => constructAssetUrl(url, owner.root?.platform?.projectBaseUrl);
+  let mountedPosition;
+  let mountedRotation;
+  if (placement.worldTransform) {
+    const point6 = vec32.transformMat4(
+      [0, 0, 0],
+      [offset.x, offset.y, offset.z + (base.zOffsetFromSurface ?? 0)],
+      placement.worldTransform
+    );
+    mountedPosition = { x: point6[0], y: point6[1], z: point6[2] };
+    const frame = [...placement.worldTransform];
+    mat42.rotateZ(frame, frame, rotationOffset.z * Math.PI / 180);
+    mat42.rotateY(frame, frame, rotationOffset.y * Math.PI / 180);
+    mat42.rotateX(frame, frame, rotationOffset.x * Math.PI / 180);
+    const angles = getAssemblyEulerAngles(frame).map(
+      (angle) => angle * 180 / Math.PI
+    );
+    mountedRotation = {
+      x: angles[0],
+      y: angles[1],
+      z: normalizeDegrees4(angles[2])
+    };
+  }
   const urls = typeof model === "string" ? { footprinter_string: model } : {
     model_stl_url: "stlUrl" in model ? assetUrl(model.stlUrl) : void 0,
     model_obj_url: "objUrl" in model ? assetUrl(model.objUrl) : void 0,
@@ -15238,13 +15358,13 @@ var renderAssemblyCadModel = (owner, model, placement) => {
   };
   const cad = owner.root.db.cad_component.insert({
     ...urls,
-    position: {
+    position: mountedPosition ?? {
       ...xy2,
       z: placement.position.z + (bottom ? -1 : 1) * (offset.z + (base.zOffsetFromSurface ?? 0))
     },
     // Same CAD Euler convention as NormalComponent.doInitialCadModelRender:
     // bottom flips Y and negates the board-plane Z angle.
-    rotation: {
+    rotation: mountedRotation ?? {
       x: rotationOffset.x,
       y: (bottom ? 180 : 0) + rotationOffset.y,
       z: normalizeDegrees4(
@@ -15253,6 +15373,7 @@ var renderAssemblyCadModel = (owner, model, placement) => {
     },
     layer: placement.layer,
     source_component_id: owner.source_component_id,
+    color: owner.componentName === "AssemblyPrintedPart" ? owner._parsedProps.color : void 0,
     subcircuit_id: placement.subcircuit_id,
     model_origin_position: base.modelOriginPosition ?? { x: 0, y: 0, z: 0 },
     model_unit_to_mm_scale_factor: base.modelUnitToMmScale ?? 1,
@@ -102101,9 +102222,36 @@ var getAlignedSharedEndpointRailPath = ({
   if (donorPath.length < 3 || branchPath.length < 4) return null;
   const donorDepartureAxis = getSegmentAxis4(donorPath[0], donorPath[1]);
   const branchDepartureAxis = getSegmentAxis4(branchPath[0], branchPath[1]);
-  if (!donorDepartureAxis || donorDepartureAxis !== branchDepartureAxis) {
+  if (!donorDepartureAxis || !branchDepartureAxis) {
     return null;
   }
+  if (donorDepartureAxis !== branchDepartureAxis) {
+    if (!nearlyEqual(donorPath[0].x, branchPath[0].x) || !nearlyEqual(donorPath[0].y, branchPath[0].y)) {
+      return null;
+    }
+    const branchRailAxis2 = getSegmentAxis4(branchPath[1], branchPath[2]);
+    const donorRailAxis2 = getSegmentAxis4(donorPath[1], donorPath[2]);
+    if (branchRailAxis2 !== donorDepartureAxis || donorRailAxis2 !== branchDepartureAxis || getPinFacingAxis(sharedPin) !== branchDepartureAxis || !isCoordinateOnPinFacingSide({
+      coordinate: branchPath[1][branchDepartureAxis],
+      axis: branchDepartureAxis,
+      pin: sharedPin
+    })) {
+      return null;
+    }
+    const donorDirection = donorPath[1][donorDepartureAxis] - donorPath[0][donorDepartureAxis];
+    const branchDirection = branchPath[2][branchRailAxis2] - branchPath[1][branchRailAxis2];
+    if (Math.sign(donorDirection) === Math.sign(branchDirection)) return null;
+    const railCoordinateAxis2 = branchRailAxis2 === "x" ? "y" : "x";
+    const candidateFromShared2 = simplifyPath([
+      branchPath[0],
+      {
+        ...branchPath[2],
+        [railCoordinateAxis2]: donorPath[0][railCoordinateAxis2]
+      },
+      ...branchPath.slice(3)
+    ]);
+    return branchTrace.pins[0].pinId === sharedPin.pinId ? candidateFromShared2 : candidateFromShared2.reverse();
+  }
   const donorDeparture = donorPath[1][donorDepartureAxis] - donorPath[0][donorDepartureAxis];
   const branchDeparture = branchPath[1][branchDepartureAxis] - branchPath[0][branchDepartureAxis];
   if (Math.sign(donorDeparture) !== Math.sign(branchDeparture)) return null;
@@ -102425,6 +102573,48 @@ var getAlignedPerpendicularEndpointBusPath = ({
   ]);
   return branchStartsAtSharedPin ? candidate : candidate.reverse();
 };
+var traceCollidesWithObstacles = ({
+  trace,
+  obstacles
+}) => findFirstCollision(trace.tracePath, obstacles, {
+  excludeRectsForSegment: (segmentIndex) => new Set(
+    obstacles.filter(
+      (obstacle) => obstacle.kind === "chip" && trace.pins.some(
+        (pin) => obstacle.chipId === pin.chipId && [
+          trace.tracePath[segmentIndex],
+          trace.tracePath[segmentIndex + 1]
+        ].some(
+          (point6) => nearlyEqual(point6.x, pin.x) && nearlyEqual(point6.y, pin.y)
+        )
+      ) && segmentOverlapsRectBoundary(
+        trace.tracePath[segmentIndex],
+        trace.tracePath[segmentIndex + 1],
+        obstacle
+      )
+    )
+  )
+}) !== null;
+var getPathLengthInsideRect = ({
+  path,
+  rect
+}) => path.slice(1).reduce((length8, point6, index2) => {
+  const previous = path[index2];
+  if (nearlyEqual(previous.x, point6.x)) {
+    if (previous.x < rect.minX || previous.x > rect.maxX) return length8;
+    return length8 + Math.max(
+      0,
+      Math.min(Math.max(previous.y, point6.y), rect.maxY) - Math.max(Math.min(previous.y, point6.y), rect.minY)
+    );
+  }
+  if (nearlyEqual(previous.y, point6.y)) {
+    if (previous.y < rect.minY || previous.y > rect.maxY) return length8;
+    return length8 + Math.max(
+      0,
+      Math.min(Math.max(previous.x, point6.x), rect.maxX) - Math.max(Math.min(previous.x, point6.x), rect.minX)
+    );
+  }
+  return length8;
+}, 0);
 var candidateIsClear = ({
   candidateTrace,
   originalTrace,
@@ -102436,30 +102626,24 @@ var candidateIsClear = ({
   preserveExistingObstacleContact = false
 }) => {
   const obstacles = getObstacleRects(inputProblem);
-  if (!preserveExistingObstacleContact && isPathCollidingWithObstacles(candidateTrace.tracePath, obstacles))
+  if (!preserveExistingObstacleContact && traceCollidesWithObstacles({ trace: candidateTrace, obstacles }))
     return false;
-  const pathLengthInsideRect = (path, rect) => path.slice(1).reduce((length8, point6, index2) => {
-    const previous = path[index2];
-    if (nearlyEqual(previous.x, point6.x)) {
-      if (previous.x < rect.minX || previous.x > rect.maxX) return length8;
-      return length8 + Math.max(
-        0,
-        Math.min(Math.max(previous.y, point6.y), rect.maxY) - Math.max(Math.min(previous.y, point6.y), rect.minY)
-      );
-    }
-    if (nearlyEqual(previous.y, point6.y)) {
-      if (previous.y < rect.minY || previous.y > rect.maxY) return length8;
-      return length8 + Math.max(
-        0,
-        Math.min(Math.max(previous.x, point6.x), rect.maxX) - Math.max(Math.min(previous.x, point6.x), rect.minX)
-      );
-    }
-    return length8;
-  }, 0);
   for (const obstacle of preserveExistingObstacleContact ? obstacles : []) {
-    if (!isPathCollidingWithObstacles(candidateTrace.tracePath, [obstacle]))
+    if (!traceCollidesWithObstacles({
+      trace: candidateTrace,
+      obstacles: [obstacle]
+    }))
       continue;
-    if (!isPathCollidingWithObstacles(originalTrace.tracePath, [obstacle]) || pathLengthInsideRect(candidateTrace.tracePath, obstacle) > pathLengthInsideRect(originalTrace.tracePath, obstacle) + 1e-6)
+    if (!traceCollidesWithObstacles({
+      trace: originalTrace,
+      obstacles: [obstacle]
+    }) || getPathLengthInsideRect({
+      path: candidateTrace.tracePath,
+      rect: obstacle
+    }) > getPathLengthInsideRect({
+      path: originalTrace.tracePath,
+      rect: obstacle
+    }) + 1e-6)
       return false;
   }
   const otherNetTraces = traces.filter(
@@ -118103,7 +118287,7 @@ function Group_getRoutingPhasePlans(group) {
 var package_default = {
   name: "@tscircuit/core",
   type: "module",
-  version: "0.0.2114",
+  version: "0.0.2116",
   types: "dist/index.d.ts",
   main: "dist/index.js",
   module: "dist/index.js",
@@ -118162,9 +118346,9 @@ var package_default = {
     "@tscircuit/miniflex": "^0.0.4",
     "@tscircuit/modelprinter": "^0.0.18",
     "@tscircuit/ngspice-spice-engine": "^0.0.20",
-    "@tscircuit/props": "^0.0.696",
+    "@tscircuit/props": "^0.0.697",
     "@tscircuit/schematic-match-adapt": "^0.0.18",
-    "@tscircuit/schematic-trace-solver": "https://jscdn.tscircuit.com/@tscircuit/schematic-trace-solver/0.0.228.tgz",
+    "@tscircuit/schematic-trace-solver": "https://jscdn.tscircuit.com/@tscircuit/schematic-trace-solver/0.0.229.tgz",
     "@tscircuit/solver-utils": "^0.0.16",
     "@tscircuit/soup-util": "^0.0.41",
     "@tscircuit/via-stitch-solver": "github:tscircuit/via-stitch-solver#64f2ac7781b795bdc0d74ba411988e60767fa653",
@@ -118178,10 +118362,10 @@ var package_default = {
     "bun-match-svg": "0.0.12",
     "calculate-elbow": "^0.0.12",
     "chokidar-cli": "^3.0.0",
-    "circuit-json": "^0.0.521",
+    "circuit-json": "^0.0.525",
     "circuit-json-to-bpc": "^0.0.13",
     "circuit-json-to-connectivity-map": "^0.0.33",
-    "circuit-json-to-gltf": "^0.0.148",
+    "circuit-json-to-gltf": "^0.0.151",
     "circuit-json-to-spice": "^0.0.45",
     "circuit-to-svg": "^0.0.445",
     concurrently: "^9.1.2",
@@ -118246,8 +118430,8 @@ var package_default = {
   },
   overrides: {
     "@tscircuit/circuit-json-util": "^0.0.119",
-    "@tscircuit/props": "^0.0.696",
-    "circuit-json": "^0.0.521",
+    "@tscircuit/props": "^0.0.697",
+    "circuit-json": "^0.0.525",
     "@tscircuit/cableprinter": "^0.0.6"
   }
 };
@@ -130360,7 +130544,7 @@ import { assemblyMotorProps } from "@tscircuit/props";
 
 // lib/components/primitive-components/resolve-assembly-motor-rotation.ts
 import { normalizeDegrees as normalizeDegrees10 } from "@tscircuit/math-utils";
-import { mat4 as mat42, vec3 as vec32 } from "gl-matrix";
+import { mat4 as mat43, vec3 as vec33 } from "gl-matrix";
 
 // lib/components/primitive-components/resolve-board-mount-rotation-anchor.ts
 var resolveBoardMountRotationAnchor = (board) => {
@@ -130421,14 +130605,14 @@ var resolveAssemblyMotorRotation = (motor, placement) => {
   if (!board || !input) return alignment;
   const bottom = placement.layer === "bottom";
   const sign = bottom ? -1 : 1;
-  const orientation2 = mat42.create();
-  mat42.rotateX(orientation2, orientation2, radians(alignment.x));
-  mat42.rotateY(
+  const orientation2 = mat43.create();
+  mat43.rotateX(orientation2, orientation2, radians(alignment.x));
+  mat43.rotateY(
     orientation2,
     orientation2,
     radians(alignment.y + (bottom ? 180 : 0))
   );
-  mat42.rotateZ(orientation2, orientation2, radians(sign * placement.pcbRotation));
+  mat43.rotateZ(orientation2, orientation2, radians(sign * placement.pcbRotation));
   const expression = input.startsWith("calc(") ? input.match(
     /^calc\(\s*(.*?)\s*(?:([+-])\s*((?:\d+(?:\.\d*)?|\.\d+))\s*(degcw|degccw))?\s*\)$/
   ) : [input, input];
@@ -130454,23 +130638,23 @@ var resolveAssemblyMotorRotation = (motor, placement) => {
   const clockwiseAngle = radians(
     (expression[2] === "-" ? -1 : 1) * Number(expression[3] ?? 0) * (expression[4] === "degccw" ? -1 : 1)
   );
-  const anchor = vec32.normalize(
-    vec32.create(),
+  const anchor = vec33.normalize(
+    vec33.create(),
     resolveBoardMountRotationAnchor(board)
   );
-  const shaft = vec32.transformMat4(vec32.create(), [0, 0, 1], orientation2);
-  const turn = mat42.fromRotation(mat42.create(), -clockwiseAngle, shaft);
-  const target = vec32.transformMat4(vec32.create(), anchor, turn);
-  const motorDirection = vec32.transformMat4(
-    vec32.create(),
+  const shaft = vec33.transformMat4(vec33.create(), [0, 0, 1], orientation2);
+  const turn = mat43.fromRotation(mat43.create(), -clockwiseAngle, shaft);
+  const target = vec33.transformMat4(vec33.create(), anchor, turn);
+  const motorDirection = vec33.transformMat4(
+    vec33.create(),
     [direction.direction.x, direction.direction.y, direction.direction.z],
     orientation2
   );
   const spin = Math.atan2(
-    vec32.dot(shaft, vec32.cross(vec32.create(), motorDirection, target)),
-    vec32.dot(motorDirection, target)
+    vec33.dot(shaft, vec33.cross(vec33.create(), motorDirection, target)),
+    vec33.dot(motorDirection, target)
   );
-  mat42.rotateZ(orientation2, orientation2, spin);
+  mat43.rotateZ(orientation2, orientation2, spin);
   const pitch = Math.asin(Math.max(-1, Math.min(1, orientation2[8])));
   const nonsingular = Math.abs(orientation2[8]) < 0.999999;
   const roll = nonsingular ? Math.atan2(-orientation2[9], orientation2[10]) : Math.atan2(orientation2[6], orientation2[5]);
@@ -130684,6 +130868,49 @@ var AssemblySubassembly = class extends PrimitiveComponent2 {
 // lib/components/primitive-components/AssemblyPart.ts
 import { assemblyPartProps } from "@tscircuit/props";
 import { isValidElement as isValidElement5 } from "react";
+
+// lib/components/primitive-components/render-part-reference-surfaces.ts
+import { mat3, vec3 as vec34 } from "gl-matrix";
+var renderPartReferenceSurfaces = (part) => {
+  const surfaces = getPartReferenceSurfaces(part);
+  if (!surfaces.length) return;
+  const { transforms, subcircuitId } = resolvePrintedPartMounts(part);
+  const world = transforms.get(part);
+  const rotation5 = mat3.fromMat4(mat3.create(), world);
+  const toPoint = (vector3) => ({
+    x: vector3[0],
+    y: vector3[1],
+    z: vector3[2]
+  });
+  for (const surface of surfaces) {
+    const child = part.children.find(
+      (child2) => child2.componentName === "AssemblyReferenceSurface" && child2.name === surface.name
+    );
+    part.root.db.cad_reference_surface.insert({
+      source_component_id: part.source_component_id,
+      name: surface.name,
+      shape: "rect",
+      center: toPoint(vec34.transformMat4(vec34.create(), surface.origin, world)),
+      normal: toPoint(
+        vec34.normalize(
+          vec34.create(),
+          vec34.transformMat3(vec34.create(), surface.normal, rotation5)
+        )
+      ),
+      x_axis: toPoint(
+        vec34.normalize(
+          vec34.create(),
+          vec34.transformMat3(vec34.create(), surface.xAxis, rotation5)
+        )
+      ),
+      width: child?._parsedProps.width,
+      height: child?._parsedProps.height,
+      subcircuit_id: subcircuitId
+    });
+  }
+};
+
+// lib/components/primitive-components/AssemblyPart.ts
 var AssemblyPart = class extends PrimitiveComponent2 {
   isAssemblyDeviceContainer = true;
   get config() {
@@ -130697,6 +130924,7 @@ var AssemblyPart = class extends PrimitiveComponent2 {
       this.add(createInstanceFromReactElement(this.props.cadModel));
   }
   doInitialSourceRender() {
+    getPartReferenceSurfaces(this);
     this.source_component_id = this.root.db.source_component.insert({
       // Circuit JSON currently represents generic assembly geometry as subassembly.
       ftype: "subassembly",
@@ -130706,6 +130934,7 @@ var AssemblyPart = class extends PrimitiveComponent2 {
   }
   doInitialCadModelRender() {
     if (!this.root || this.root.pcbDisabled || !this.source_component_id) return;
+    renderPartReferenceSurfaces(this);
     const model = resolveAssemblyModel(this._parsedProps) ?? this._parsedProps.cadModel;
     if (model && !(typeof model === "object" && "type" in model)) {
       this.cad_component_id = renderAssemblyCadModel(
@@ -130717,6 +130946,46 @@ var AssemblyPart = class extends PrimitiveComponent2 {
   }
 };
 
+// lib/components/primitive-components/AssemblyReferenceSurface.ts
+import { assemblyReferenceSurfaceProps } from "@tscircuit/props";
+var AssemblyReferenceSurface = class extends PrimitiveComponent2 {
+  get config() {
+    return {
+      componentName: "AssemblyReferenceSurface",
+      zodProps: assemblyReferenceSurfaceProps
+    };
+  }
+  doInitialSourceRender() {
+    if (this.parent?.componentName !== "AssemblyPart" && this.parent?.componentName !== "AssemblyPrintedPart")
+      throw new Error(
+        `Reference surface "${this.name}" must be a child of assembly.part or assembly.printedpart`
+      );
+  }
+  /** Part-local frame, right-handed XYZ in mm: origin is a point, normal and
+   * xAxis are unit directions. XY faces +Z, XZ faces +Y, YZ faces +X.
+   * XZ's second tangent is -Z so its tangent basis remains right-handed.
+   */
+  get referenceFrame() {
+    const {
+      name,
+      plane,
+      normalDirection,
+      centerXOffset,
+      centerYOffset,
+      centerZOffset
+    } = this._parsedProps;
+    const sign = normalDirection.endsWith("-") ? -1 : 1;
+    const normal = plane === "xy" ? [0, 0, sign] : plane === "xz" ? [0, sign, 0] : [sign, 0, 0];
+    const xAxis = plane === "yz" ? [0, 1, 0] : [1, 0, 0];
+    return {
+      name,
+      origin: [centerXOffset, centerYOffset, centerZOffset],
+      normal,
+      xAxis
+    };
+  }
+};
+
 // lib/components/primitive-components/EnclosureCutoutAperture/EnclosureCutoutAperture.ts
 import { enclosureCutoutApertureProps } from "@tscircuit/props";
 
@@ -133266,7 +133535,7 @@ import { isValidElement as isValidElement6 } from "react";
 import { assemblyPrintedPartProps } from "@tscircuit/props";
 import { renderToJscadPlan } from "jscad-fiber/headless";
 import {
-  resolveReferencePlanes
+  resolveReferencePlanes as resolveReferencePlanes2
 } from "jscad-planner";
 var AssemblyPrintedPart = class extends PrimitiveComponent2 {
   isAssemblyDeviceContainer = true;
@@ -133284,7 +133553,7 @@ var AssemblyPrintedPart = class extends PrimitiveComponent2 {
   get printedPartPlan() {
     if (!this._parsedProps.jscad) return void 0;
     if (!this.compiledJscad || this.compiledJscadInput !== this._parsedProps.jscad) {
-      const { geometry, referencePlanes } = resolveReferencePlanes(
+      const { geometry, referencePlanes } = resolveReferencePlanes2(
         renderToJscadPlan(this._parsedProps.jscad)
       );
       if (!geometry)
@@ -133302,20 +133571,24 @@ var AssemblyPrintedPart = class extends PrimitiveComponent2 {
   }
   doInitialSourceRender() {
     this.printedPartPlan;
+    getPartReferenceSurfaces(this);
     this.source_component_id = this.root.db.source_component.insert({
       ftype: "printedpart",
-      name: this.name
+      name: this.name,
+      color: this._parsedProps.color,
+      material: this._parsedProps.material
     }).source_component_id;
   }
   doInitialCadModelRender() {
     if (!this.root || this.root.pcbDisabled || !this.source_component_id) return;
+    renderPartReferenceSurfaces(this);
     const plan = this.printedPartPlan;
     if (!plan) {
       let model = resolveAssemblyModel(this._parsedProps) ?? this._parsedProps.cadModel;
       const placement = resolveAssemblyPlacement(this);
       if (!model || typeof model === "object" && "type" in model) return;
       if (typeof model === "object" && "jscad" in model) {
-        const { geometry } = resolveReferencePlanes(
+        const { geometry } = resolveReferencePlanes2(
           model.jscad
         );
         if (!geometry)
@@ -133329,12 +133602,7 @@ var AssemblyPrintedPart = class extends PrimitiveComponent2 {
     }
     const { transforms, subcircuitId } = resolvePrintedPartMounts(this);
     const transform = transforms.get(this);
-    const y2 = Math.asin(Math.max(-1, Math.min(1, -transform[2])));
-    const angles = Math.abs(Math.cos(y2)) > 1e-8 ? [
-      Math.atan2(transform[6], transform[10]),
-      y2,
-      Math.atan2(transform[1], transform[0])
-    ] : [0, y2, Math.atan2(-transform[4], transform[5])];
+    const angles = getAssemblyEulerAngles(transform);
     this.cad_component_id = renderAssemblyCadModel(
       this,
       {
@@ -133843,15 +134111,15 @@ function parseCableString(cableString) {
 }
 
 // lib/components/primitive-components/resolve-assembly-cable.ts
-import { vec3 as vec36 } from "gl-matrix";
+import { vec3 as vec38 } from "gl-matrix";
 
 // lib/components/primitive-components/resolve-assembly-cable-endpoint.ts
 import { getJstMotorConnector } from "@tscircuit/modelprinter";
-import { mat4 as mat43, vec3 as vec34 } from "gl-matrix";
+import { mat4 as mat44, vec3 as vec36 } from "gl-matrix";
 import { selectAll as selectAll3 } from "css-select";
 
 // lib/components/primitive-components/resolve-assembly-cable-pin1-position.ts
-import { vec3 as vec33 } from "gl-matrix";
+import { vec3 as vec35 } from "gl-matrix";
 function resolveAssemblyCablePin1Position(cable, connector, matingCenter, outward) {
   const db2 = cable.root.db;
   const pins = db2.source_port.list().flatMap((sourcePort) => {
@@ -133876,10 +134144,10 @@ function resolveAssemblyCablePin1Position(cable, connector, matingCenter, outwar
     }),
     { x: 0, y: 0 }
   );
-  const offset = vec33.fromValues(pin1.x - center.x, pin1.y - center.y, 0);
-  const axis = vec33.normalize(vec33.create(), [outward.x, outward.y, outward.z]);
-  vec33.scaleAndAdd(offset, offset, axis, -vec33.dot(offset, axis));
-  if (vec33.length(offset) < 1e-6) return void 0;
+  const offset = vec35.fromValues(pin1.x - center.x, pin1.y - center.y, 0);
+  const axis = vec35.normalize(vec35.create(), [outward.x, outward.y, outward.z]);
+  vec35.scaleAndAdd(offset, offset, axis, -vec35.dot(offset, axis));
+  if (vec35.length(offset) < 1e-6) return void 0;
   return {
     x: matingCenter.x + offset[0],
     y: matingCenter.y + offset[1],
@@ -133908,33 +134176,33 @@ function resolveAssemblyCableEndpoint(cable, selector, cableConnector) {
     const faceMount = resolveMotorFaceMount(motor);
     const placement = faceMount ? { position: faceMount.position, pcbRotation: 0, layer: "top" } : resolveAssemblyMotorPlacement(motor);
     const offset = faceMount?.rotation ?? resolveAssemblyMotorRotation(motor, placement);
-    const orientation2 = mat43.create();
+    const orientation2 = mat44.create();
     const bottom = placement.layer === "bottom";
-    mat43.rotateX(orientation2, orientation2, offset.x * Math.PI / 180);
-    mat43.rotateY(
+    mat44.rotateX(orientation2, orientation2, offset.x * Math.PI / 180);
+    mat44.rotateY(
       orientation2,
       orientation2,
       (offset.y + (bottom ? 180 : 0)) * Math.PI / 180
     );
-    mat43.rotateZ(
+    mat44.rotateZ(
       orientation2,
       orientation2,
       (bottom ? -1 : 1) * (placement.pcbRotation + offset.z) * Math.PI / 180
     );
     const reference = motor.motorReferencePoints.wireside;
-    const direction2 = vec34.transformMat4(
-      vec34.create(),
+    const direction2 = vec36.transformMat4(
+      vec36.create(),
       [reference.direction.x, reference.direction.y, reference.direction.z],
       orientation2
     );
-    const point6 = vec34.transformMat4(
-      vec34.create(),
+    const point6 = vec36.transformMat4(
+      vec36.create(),
       [reference.position.x, reference.position.y, reference.position.z],
       orientation2
     );
     const halfPinSpan = (motorConnector.pinCount - 1) * motorConnector.pitch / 2;
-    const pin1Offset = vec34.transformMat4(
-      vec34.create(),
+    const pin1Offset = vec36.transformMat4(
+      vec36.create(),
       [
         reference.direction.y * halfPinSpan,
         -reference.direction.x * halfPinSpan,
@@ -133983,12 +134251,12 @@ function resolveAssemblyCableEndpoint(cable, selector, cableConnector) {
   const board = connector._getBoard();
   const layer = pcb.layer === "bottom" ? "bottom" : "top";
   const inferredCenter = pcb.cable_insertion_center ?? pcb.center;
-  const inferredDirection = vec34.normalize(vec34.create(), [
+  const inferredDirection = vec36.normalize(vec36.create(), [
     inferredCenter.x - pcb.center.x,
     inferredCenter.y - pcb.center.y,
     0
   ]);
-  const direction = connector._getPcbComponentInsertionAxisDirection(layer, pcb.rotation) ?? (props.standard === "usb_c" && vec34.length(inferredDirection) > 0 ? { x: inferredDirection[0], y: inferredDirection[1], z: 0 } : { x: 0, y: 0, z: layer === "bottom" ? -1 : 1 });
+  const direction = connector._getPcbComponentInsertionAxisDirection(layer, pcb.rotation) ?? (props.standard === "usb_c" && vec36.length(inferredDirection) > 0 ? { x: inferredDirection[0], y: inferredDirection[1], z: 0 } : { x: 0, y: 0, z: layer === "bottom" ? -1 : 1 });
   const center = Math.abs(direction.z) > 0.5 ? pcb.center : inferredCenter;
   const sign = layer === "bottom" ? -1 : 1;
   const height = !props.standard && cableConnector ? Math.abs(direction.z) > 0.5 ? cableConnector.bodyDepth : cableConnector.bodyHeight / 2 : Math.abs(direction.z) > 0.5 ? props.standard === "jst_ph" ? 6 : props.standard === "jst_sh" ? 4.25 : 1.5 : props.standard === "usb_c" ? 1.5 : props.standard === "jst_sh" ? 1.4 : 2.25;
@@ -134012,7 +134280,7 @@ function resolveAssemblyCableEndpoint(cable, selector, cableConnector) {
 }
 
 // lib/components/primitive-components/infer-assembly-cable-path.ts
-import { vec3 as vec35 } from "gl-matrix";
+import { vec3 as vec37 } from "gl-matrix";
 function inferAssemblyCablePath({
   from,
   to,
@@ -134022,26 +134290,26 @@ function inferAssemblyCablePath({
   const distance27 = Math.hypot(to.x - from.x, to.y - from.y, to.z - from.z);
   if (distance27 < 1e-6)
     throw new Error("Cable wire exits must be at different positions");
-  const chord = vec35.fromValues(to.x - from.x, to.y - from.y, to.z - from.z);
-  const routeNormal = vec35.cross(vec35.create(), chord, [
+  const chord = vec37.fromValues(to.x - from.x, to.y - from.y, to.z - from.z);
+  const routeNormal = vec37.cross(vec37.create(), chord, [
     fromDirection.x,
     fromDirection.y,
     fromDirection.z
   ]);
-  if (vec35.length(routeNormal) < 1e-6) {
-    vec35.cross(
+  if (vec37.length(routeNormal) < 1e-6) {
+    vec37.cross(
       routeNormal,
       chord,
       Math.abs(chord[2]) / distance27 > 0.95 ? [0, 1, 0] : [0, 0, 1]
     );
   }
-  const archDirection = vec35.normalize(
-    vec35.create(),
-    vec35.cross(vec35.create(), routeNormal, chord)
+  const archDirection = vec37.normalize(
+    vec37.create(),
+    vec37.cross(vec37.create(), routeNormal, chord)
   );
   const archSide = from.z < 0 && to.z < 0 ? -1 : 1;
   if (archDirection[2] * archSide < 0)
-    vec35.scale(archDirection, archDirection, -1);
+    vec37.scale(archDirection, archDirection, -1);
   const clearance = Math.min(25, Math.max(8, distance27 / 3));
   const controlA = {
     x: from.x + fromDirection.x * clearance,
@@ -134112,8 +134380,8 @@ function resolveAssemblyCable(cable) {
     );
   const definition = fromDefinition;
   const endpointExit = (position, direction, depth) => {
-    const exit = vec36.scaleAndAdd(
-      vec36.create(),
+    const exit = vec38.scaleAndAdd(
+      vec38.create(),
       [position.x, position.y, position.z],
       [direction.x, direction.y, direction.z],
       depth
@@ -134192,6 +134460,9 @@ var analog = {
 
 // lib/namespaced-elements/assembly.ts
 var assembly = {
+  referencesurface: createNamespacedElement(
+    "assembly.referencesurface"
+  ),
   part: createNamespacedElement("assembly.part"),
   cable: createNamespacedElement("assembly.cable"),
   printedpart: createNamespacedElement(
@@ -134448,6 +134719,7 @@ extendCatalogue({
   "assembly.device": AssemblyDevice,
   "assembly.motor": AssemblyMotor,
   "assembly.part": AssemblyPart,
+  "assembly.referencesurface": AssemblyReferenceSurface,
   "assembly.printedpart": AssemblyPrintedPart,
   "assembly.screen": AssemblyScreen,
   "assembly.subassembly": AssemblySubassembly,
@@ -134477,6 +134749,7 @@ export {
   AssemblyMotor,
   AssemblyPart,
   AssemblyPrintedPart,
+  AssemblyReferenceSurface,
   AssemblyScreen,
   AssemblySubassembly,
   AutoroutingPhase,