@emasoft/svg-matrix 1.0.28 → 1.0.30

package/src/use-symbol-resolver.js

@@ -14,16 +14,15 @@
  * @module use-symbol-resolver
  */
 
-import Decimal from 'decimal.js';
-import { Matrix } from './matrix.js';
-import * as Transforms2D from './transforms2d.js';
-import * as PolygonClip from './polygon-clip.js';
-import * as ClipPathResolver from './clip-path-resolver.js';
+import Decimal from "decimal.js";
+import { Matrix } from "./matrix.js";
+import * as Transforms2D from "./transforms2d.js";
+import * as PolygonClip from "./polygon-clip.js";
+import * as ClipPathResolver from "./clip-path-resolver.js";
+import { parseTransformAttribute } from "./svg-flatten.js";
 
 Decimal.set({ precision: 80 });
 
-const D = x => (x instanceof Decimal ? x : new Decimal(x));
-
 /**
  * Detect circular references when resolving use/symbol references.
  * Prevents infinite loops when SVG contains circular reference chains like:
@@ -87,19 +86,23 @@ function hasCircularReference(startId, getNextId, maxDepth = 100) {
  * // }
  */
 export function parseUseElement(useElement) {
-  const href = useElement.getAttribute('href') ||
-               useElement.getAttribute('xlink:href') || '';
+  const href =
+    useElement.getAttribute("href") ||
+    useElement.getAttribute("xlink:href") ||
+    "";
 
   return {
-    href: href.startsWith('#') ? href.slice(1) : href,
-    x: parseFloat(useElement.getAttribute('x') || '0'),
-    y: parseFloat(useElement.getAttribute('y') || '0'),
-    width: useElement.getAttribute('width') ?
-           parseFloat(useElement.getAttribute('width')) : null,
-    height: useElement.getAttribute('height') ?
-            parseFloat(useElement.getAttribute('height')) : null,
-    transform: useElement.getAttribute('transform') || null,
-    style: extractStyleAttributes(useElement)
+    href: href.startsWith("#") ? href.slice(1) : href,
+    x: parseFloat(useElement.getAttribute("x") || "0"),
+    y: parseFloat(useElement.getAttribute("y") || "0"),
+    width: useElement.getAttribute("width")
+      ? parseFloat(useElement.getAttribute("width"))
+      : null,
+    height: useElement.getAttribute("height")
+      ? parseFloat(useElement.getAttribute("height"))
+      : null,
+    transform: useElement.getAttribute("transform") || null,
+    style: extractStyleAttributes(useElement),
   };
 }
 
@@ -144,23 +147,27 @@ export function parseUseElement(useElement) {
  */
 export function parseSymbolElement(symbolElement) {
   const data = {
-    id: symbolElement.getAttribute('id') || '',
-    viewBox: symbolElement.getAttribute('viewBox') || null,
-    preserveAspectRatio: symbolElement.getAttribute('preserveAspectRatio') || 'xMidYMid meet',
+    id: symbolElement.getAttribute("id") || "",
+    viewBox: symbolElement.getAttribute("viewBox") || null,
+    preserveAspectRatio:
+      symbolElement.getAttribute("preserveAspectRatio") || "xMidYMid meet",
     children: [],
-    refX: parseFloat(symbolElement.getAttribute('refX') || '0'),
-    refY: parseFloat(symbolElement.getAttribute('refY') || '0')
+    refX: parseFloat(symbolElement.getAttribute("refX") || "0"),
+    refY: parseFloat(symbolElement.getAttribute("refY") || "0"),
   };
 
   // Parse viewBox
   if (data.viewBox) {
-    const parts = data.viewBox.trim().split(/[\s,]+/).map(Number);
+    const parts = data.viewBox
+      .trim()
+      .split(/[\s,]+/)
+      .map(Number);
     if (parts.length === 4) {
       data.viewBoxParsed = {
         x: parts[0],
         y: parts[1],
         width: parts[2],
-        height: parts[3]
+        height: parts[3],
       };
     }
   }
@@ -239,61 +246,66 @@ export function parseChildElement(element) {
 
   const data = {
     type: tagName,
-    id: element.getAttribute('id') || null,
-    transform: element.getAttribute('transform') || null,
-    style: extractStyleAttributes(element)
+    id: element.getAttribute("id") || null,
+    transform: element.getAttribute("transform") || null,
+    style: extractStyleAttributes(element),
   };
 
   switch (tagName) {
-    case 'rect':
-      data.x = parseFloat(element.getAttribute('x') || '0');
-      data.y = parseFloat(element.getAttribute('y') || '0');
-      data.width = parseFloat(element.getAttribute('width') || '0');
-      data.height = parseFloat(element.getAttribute('height') || '0');
-      data.rx = parseFloat(element.getAttribute('rx') || '0');
-      data.ry = parseFloat(element.getAttribute('ry') || '0');
+    case "rect":
+      data.x = parseFloat(element.getAttribute("x") || "0");
+      data.y = parseFloat(element.getAttribute("y") || "0");
+      data.width = parseFloat(element.getAttribute("width") || "0");
+      data.height = parseFloat(element.getAttribute("height") || "0");
+      data.rx = parseFloat(element.getAttribute("rx") || "0");
+      data.ry = parseFloat(element.getAttribute("ry") || "0");
       break;
-    case 'circle':
-      data.cx = parseFloat(element.getAttribute('cx') || '0');
-      data.cy = parseFloat(element.getAttribute('cy') || '0');
-      data.r = parseFloat(element.getAttribute('r') || '0');
+    case "circle":
+      data.cx = parseFloat(element.getAttribute("cx") || "0");
+      data.cy = parseFloat(element.getAttribute("cy") || "0");
+      data.r = parseFloat(element.getAttribute("r") || "0");
       break;
-    case 'ellipse':
-      data.cx = parseFloat(element.getAttribute('cx') || '0');
-      data.cy = parseFloat(element.getAttribute('cy') || '0');
-      data.rx = parseFloat(element.getAttribute('rx') || '0');
-      data.ry = parseFloat(element.getAttribute('ry') || '0');
+    case "ellipse":
+      data.cx = parseFloat(element.getAttribute("cx") || "0");
+      data.cy = parseFloat(element.getAttribute("cy") || "0");
+      data.rx = parseFloat(element.getAttribute("rx") || "0");
+      data.ry = parseFloat(element.getAttribute("ry") || "0");
       break;
-    case 'path':
-      data.d = element.getAttribute('d') || '';
+    case "path":
+      data.d = element.getAttribute("d") || "";
       break;
-    case 'polygon':
-      data.points = element.getAttribute('points') || '';
+    case "polygon":
+      data.points = element.getAttribute("points") || "";
       break;
-    case 'polyline':
-      data.points = element.getAttribute('points') || '';
+    case "polyline":
+      data.points = element.getAttribute("points") || "";
       break;
-    case 'line':
-      data.x1 = parseFloat(element.getAttribute('x1') || '0');
-      data.y1 = parseFloat(element.getAttribute('y1') || '0');
-      data.x2 = parseFloat(element.getAttribute('x2') || '0');
-      data.y2 = parseFloat(element.getAttribute('y2') || '0');
+    case "line":
+      data.x1 = parseFloat(element.getAttribute("x1") || "0");
+      data.y1 = parseFloat(element.getAttribute("y1") || "0");
+      data.x2 = parseFloat(element.getAttribute("x2") || "0");
+      data.y2 = parseFloat(element.getAttribute("y2") || "0");
       break;
-    case 'g':
+    case "g":
       data.children = [];
       for (const child of element.children) {
         data.children.push(parseChildElement(child));
       }
       break;
-    case 'use':
-      data.href = (element.getAttribute('href') ||
-                   element.getAttribute('xlink:href') || '').replace('#', '');
-      data.x = parseFloat(element.getAttribute('x') || '0');
-      data.y = parseFloat(element.getAttribute('y') || '0');
-      data.width = element.getAttribute('width') ?
-                   parseFloat(element.getAttribute('width')) : null;
-      data.height = element.getAttribute('height') ?
-                    parseFloat(element.getAttribute('height')) : null;
+    case "use":
+      data.href = (
+        element.getAttribute("href") ||
+        element.getAttribute("xlink:href") ||
+        ""
+      ).replace("#", "");
+      data.x = parseFloat(element.getAttribute("x") || "0");
+      data.y = parseFloat(element.getAttribute("y") || "0");
+      data.width = element.getAttribute("width")
+        ? parseFloat(element.getAttribute("width"))
+        : null;
+      data.height = element.getAttribute("height")
+        ? parseFloat(element.getAttribute("height"))
+        : null;
       break;
   }
 
@@ -340,14 +352,14 @@ export function parseChildElement(element) {
  */
 export function extractStyleAttributes(element) {
   return {
-    fill: element.getAttribute('fill'),
-    stroke: element.getAttribute('stroke'),
-    strokeWidth: element.getAttribute('stroke-width'),
-    opacity: element.getAttribute('opacity'),
-    fillOpacity: element.getAttribute('fill-opacity'),
-    strokeOpacity: element.getAttribute('stroke-opacity'),
-    visibility: element.getAttribute('visibility'),
-    display: element.getAttribute('display')
+    fill: element.getAttribute("fill"),
+    stroke: element.getAttribute("stroke"),
+    strokeWidth: element.getAttribute("stroke-width"),
+    opacity: element.getAttribute("opacity"),
+    fillOpacity: element.getAttribute("fill-opacity"),
+    strokeOpacity: element.getAttribute("stroke-opacity"),
+    visibility: element.getAttribute("visibility"),
+    display: element.getAttribute("display"),
   };
 }
 
@@ -398,7 +410,12 @@ export function extractStyleAttributes(element) {
  * // Result: uniform scale of 2.0 (max of 200/100, 150/100)
  * // Centered: translate(0, -25) then scale(2, 2) - height extends beyond viewport
  */
-export function calculateViewBoxTransform(viewBox, targetWidth, targetHeight, preserveAspectRatio = 'xMidYMid meet') {
+export function calculateViewBoxTransform(
+  viewBox,
+  targetWidth,
+  targetHeight,
+  preserveAspectRatio = "xMidYMid meet",
+) {
   if (!viewBox || !targetWidth || !targetHeight) {
     return Matrix.identity(3);
   }
@@ -414,15 +431,16 @@ export function calculateViewBoxTransform(viewBox, targetWidth, targetHeight, pr
 
   // Parse preserveAspectRatio
   const parts = preserveAspectRatio.trim().split(/\s+/);
-  const align = parts[0] || 'xMidYMid';
-  const meetOrSlice = parts[1] || 'meet';
+  const align = parts[0] || "xMidYMid";
+  const meetOrSlice = parts[1] || "meet";
 
-  if (align === 'none') {
+  if (align === "none") {
     // Non-uniform scaling
     const scaleX = targetWidth / vbW;
     const scaleY = targetHeight / vbH;
-    return Transforms2D.translation(-vbX * scaleX, -vbY * scaleY)
-      .mul(Transforms2D.scale(scaleX, scaleY));
+    return Transforms2D.translation(-vbX * scaleX, -vbY * scaleY).mul(
+      Transforms2D.scale(scaleX, scaleY),
+    );
   }
 
   // Uniform scaling
@@ -430,7 +448,7 @@ export function calculateViewBoxTransform(viewBox, targetWidth, targetHeight, pr
   const scaleY = targetHeight / vbH;
   let scale;
 
-  if (meetOrSlice === 'slice') {
+  if (meetOrSlice === "slice") {
     scale = Math.max(scaleX, scaleY);
   } else {
     scale = Math.min(scaleX, scaleY);
@@ -444,21 +462,20 @@ export function calculateViewBoxTransform(viewBox, targetWidth, targetHeight, pr
   const scaledHeight = vbH * scale;
 
   // X alignment
-  if (align.includes('xMid')) {
+  if (align.includes("xMid")) {
     tx += (targetWidth - scaledWidth) / 2;
-  } else if (align.includes('xMax')) {
+  } else if (align.includes("xMax")) {
     tx += targetWidth - scaledWidth;
   }
 
   // Y alignment
-  if (align.includes('YMid')) {
+  if (align.includes("YMid")) {
     ty += (targetHeight - scaledHeight) / 2;
-  } else if (align.includes('YMax')) {
+  } else if (align.includes("YMax")) {
     ty += targetHeight - scaledHeight;
   }
 
-  return Transforms2D.translation(tx, ty)
-    .mul(Transforms2D.scale(scale, scale));
+  return Transforms2D.translation(tx, ty).mul(Transforms2D.scale(scale, scale));
 }
 
 /**
@@ -557,13 +574,13 @@ export function resolveUse(useData, defs, options = {}) {
   // Pre-multiply by use element's transform if present (step 1)
   // This makes useTransform apply FIRST, then translation
   if (useData.transform) {
-    const useTransform = ClipPathResolver.parseTransform(useData.transform);
+    const useTransform = parseTransformAttribute(useData.transform);
     transform = transform.mul(useTransform);
   }
 
   // Handle symbol with viewBox (step 3)
   // ViewBox transform applies LAST (after translation and useTransform)
-  if (target.type === 'symbol' && target.viewBoxParsed) {
+  if (target.type === "symbol" && target.viewBoxParsed) {
     const width = useData.width || target.viewBoxParsed.width;
     const height = useData.height || target.viewBoxParsed.height;
 
@@ -571,7 +588,7 @@ export function resolveUse(useData, defs, options = {}) {
       target.viewBoxParsed,
       width,
       height,
-      target.preserveAspectRatio
+      target.preserveAspectRatio,
     );
 
     // ViewBox transform is applied LAST, so it's the leftmost in multiplication
@@ -583,7 +600,7 @@ export function resolveUse(useData, defs, options = {}) {
   const children = target.children || [target];
 
   for (const child of children) {
-    if (child.type === 'use') {
+    if (child.type === "use") {
       // Recursive resolution
       const resolved = resolveUse(child, defs, { maxDepth: maxDepth - 1 });
       if (resolved) {
@@ -592,7 +609,7 @@ export function resolveUse(useData, defs, options = {}) {
     } else {
       resolvedChildren.push({
         element: child,
-        transform: Matrix.identity(3)
+        transform: Matrix.identity(3),
       });
     }
   }
@@ -601,7 +618,7 @@ export function resolveUse(useData, defs, options = {}) {
     element: target,
     transform,
     children: resolvedChildren,
-    inheritedStyle: useData.style
+    inheritedStyle: useData.style,
   };
 }
 
@@ -670,8 +687,12 @@ export function flattenResolvedUse(resolved, samples = 20) {
       // Recursive flattening
       const nested = flattenResolvedUse(child, samples);
       for (const n of nested) {
-        n.polygon = n.polygon.map(p => {
-          const [x, y] = Transforms2D.applyTransform(resolved.transform, p.x, p.y);
+        n.polygon = n.polygon.map((p) => {
+          const [x, y] = Transforms2D.applyTransform(
+            resolved.transform,
+            p.x,
+            p.y,
+          );
           return { x, y };
         });
         results.push(n);
@@ -682,7 +703,7 @@ export function flattenResolvedUse(resolved, samples = 20) {
       if (polygon.length >= 3) {
         results.push({
           polygon,
-          style: mergeStyles(resolved.inheritedStyle, element.style)
+          style: mergeStyles(resolved.inheritedStyle, element.style),
         });
       }
     }
@@ -731,7 +752,7 @@ export function elementToPolygon(element, transform, samples = 20) {
 
   // Apply transform
   if (transform && polygon.length > 0) {
-    polygon = polygon.map(p => {
+    polygon = polygon.map((p) => {
       const [x, y] = Transforms2D.applyTransform(transform, p.x, p.y);
       return { x, y };
     });
@@ -867,7 +888,7 @@ export function getResolvedBBox(resolved, samples = 20) {
     x: minX,
     y: minY,
     width: maxX - minX,
-    height: maxY - minY
+    height: maxY - minY,
   };
 }
 
@@ -929,7 +950,7 @@ export function clipResolvedUse(resolved, clipPolygon, samples = 20) {
       if (clippedPoly.length >= 3) {
         result.push({
           polygon: clippedPoly,
-          style
+          style,
         });
       }
     }
@@ -993,19 +1014,19 @@ export function resolvedUseToPathData(resolved, samples = 20) {
 
   for (const { polygon } of polygons) {
     if (polygon.length >= 3) {
-      let d = '';
+      let d = "";
       for (let i = 0; i < polygon.length; i++) {
         const p = polygon[i];
         const x = Number(p.x).toFixed(6);
         const y = Number(p.y).toFixed(6);
         d += i === 0 ? `M ${x} ${y}` : ` L ${x} ${y}`;
       }
-      d += ' Z';
+      d += " Z";
       paths.push(d);
     }
   }
 
-  return paths.join(' ');
+  return paths.join(" ");
 }
 
 /**
@@ -1063,15 +1084,15 @@ export function buildDefsMap(svgRoot) {
   const defs = {};
 
   // Find all elements with id
-  const elementsWithId = svgRoot.querySelectorAll('[id]');
+  const elementsWithId = svgRoot.querySelectorAll("[id]");
 
   for (const element of elementsWithId) {
-    const id = element.getAttribute('id');
+    const id = element.getAttribute("id");
     const tagName = element.tagName.toLowerCase();
 
-    if (tagName === 'symbol') {
+    if (tagName === "symbol") {
       defs[id] = parseSymbolElement(element);
-      defs[id].type = 'symbol';
+      defs[id].type = "symbol";
     } else {
       defs[id] = parseChildElement(element);
     }
@@ -1146,7 +1167,7 @@ export function buildDefsMap(svgRoot) {
  */
 export function resolveAllUses(svgRoot, options = {}) {
   const defs = buildDefsMap(svgRoot);
-  const useElements = svgRoot.querySelectorAll('use');
+  const useElements = svgRoot.querySelectorAll("use");
   const resolved = [];
 
   // Helper to get the next use reference from a definition
@@ -1155,14 +1176,14 @@ export function resolveAllUses(svgRoot, options = {}) {
     if (!target) return null;
 
     // Check if target is itself a use element
-    if (target.type === 'use') {
+    if (target.type === "use") {
       return target.href;
     }
 
     // Check if target contains use elements in its children
     if (target.children && target.children.length > 0) {
       for (const child of target.children) {
-        if (child.type === 'use') {
+        if (child.type === "use") {
           return child.href;
         }
       }
@@ -1176,7 +1197,9 @@ export function resolveAllUses(svgRoot, options = {}) {
 
     // Check for circular reference before attempting to resolve
     if (hasCircularReference(useData.href, getUseRef)) {
-      console.warn(`Circular use reference detected: #${useData.href}, skipping resolution`);
+      console.warn(
+        `Circular use reference detected: #${useData.href}, skipping resolution`,
+      );
       continue;
     }
 
@@ -1185,10 +1208,27 @@ export function resolveAllUses(svgRoot, options = {}) {
       resolved.push({
         original: useEl,
         useData,
-        resolved: result
+        resolved: result,
       });
     }
   }
 
   return resolved;
 }
+
+export default {
+  parseUseElement,
+  parseSymbolElement,
+  parseChildElement,
+  extractStyleAttributes,
+  calculateViewBoxTransform,
+  resolveUse,
+  flattenResolvedUse,
+  elementToPolygon,
+  mergeStyles,
+  getResolvedBBox,
+  clipResolvedUse,
+  resolvedUseToPathData,
+  buildDefsMap,
+  resolveAllUses,
+};

package/src/vector.js

@@ -15,6 +15,10 @@ const D = x => (x instanceof Decimal ? x : new Decimal(x));
  * Supports basic operations (add, sub, scale), products (dot, cross, outer),
  * and geometric operations (norm, normalize, angle, projection).
  *
+ * @class
+ * @property {Array<Decimal>} data - Array of Decimal vector components
+ * @property {number} length - Number of components in the vector
+ *
  * @example
  * const v = Vector.from([1, 2, 3]);
  * const w = Vector.from(['1.5', '2.5', '3.5']);
@@ -83,8 +87,12 @@ export class Vector {
    * @throws {Error} If other is not a Vector or dimensions mismatch
    */
   add(other) {
-    if (!(other instanceof Vector)) throw new Error('add expects Vector');
-    if (other.length !== this.length) throw new Error('shape mismatch: vectors must have same length');
+    if (!other || !(other instanceof Vector)) {
+      throw new Error('add: argument must be a Vector');
+    }
+    if (this.length !== other.length) {
+      throw new Error(`add: dimension mismatch (${this.length} vs ${other.length})`);
+    }
     return new Vector(this.data.map((v, i) => v.plus(other.data[i])));
   }
 
@@ -95,8 +103,12 @@ export class Vector {
    * @throws {Error} If other is not a Vector or dimensions mismatch
    */
   sub(other) {
-    if (!(other instanceof Vector)) throw new Error('sub expects Vector');
-    if (other.length !== this.length) throw new Error('shape mismatch: vectors must have same length');
+    if (!other || !(other instanceof Vector)) {
+      throw new Error('sub: argument must be a Vector');
+    }
+    if (this.length !== other.length) {
+      throw new Error(`sub: dimension mismatch (${this.length} vs ${other.length})`);
+    }
     return new Vector(this.data.map((v, i) => v.minus(other.data[i])));
   }
 
@@ -125,8 +137,12 @@ export class Vector {
    * @throws {Error} If other is not a Vector or dimensions mismatch
    */
   dot(other) {
-    if (!(other instanceof Vector)) throw new Error('dot expects Vector');
-    if (other.length !== this.length) throw new Error('shape mismatch: vectors must have same length');
+    if (!other || !(other instanceof Vector)) {
+      throw new Error('dot: argument must be a Vector');
+    }
+    if (this.length !== other.length) {
+      throw new Error(`dot: dimension mismatch (${this.length} vs ${other.length})`);
+    }
     return this.data.reduce((acc, v, i) => acc.plus(v.mul(other.data[i])), new Decimal(0));
   }
 
@@ -143,7 +159,9 @@ export class Vector {
    * @throws {Error} If other is not a Vector
    */
   outer(other) {
-    if (!(other instanceof Vector)) throw new Error('outer expects Vector');
+    if (!other || !(other instanceof Vector)) {
+      throw new Error('outer: argument must be a Vector');
+    }
     const rows = this.length, cols = other.length;
     const out = Array.from({ length: rows }, (_, i) =>
       Array.from({ length: cols }, (_, j) => this.data[i].mul(other.data[j]))
@@ -155,10 +173,15 @@ export class Vector {
    * Cross product for 3D vectors only.
    * @param {Vector} other - 3D Vector to compute cross product with
    * @returns {Vector} New 3D Vector perpendicular to both inputs
-   * @throws {Error} If either vector is not 3D
+   * @throws {Error} If other is not a Vector or either vector is not 3D
    */
   cross(other) {
-    if (this.length !== 3 || other.length !== 3) throw new Error('cross product requires 3D vectors');
+    if (!other || !(other instanceof Vector)) {
+      throw new Error('cross: argument must be a Vector');
+    }
+    if (this.length !== 3 || other.length !== 3) {
+      throw new Error(`cross: requires 3D vectors (got ${this.length}D and ${other.length}D)`);
+    }
     const [a1, a2, a3] = this.data;
     const [b1, b2, b3] = other.data;
     return new Vector([
@@ -193,15 +216,23 @@ export class Vector {
    * Angle between this vector and another (in radians).
    * @param {Vector} other - Vector to compute angle with
    * @returns {Decimal} Angle in radians as a Decimal
-   * @throws {Error} If either vector is zero
+   * @throws {Error} If other is not a Vector, dimensions mismatch, or either vector is zero
    */
   angleBetween(other) {
+    if (!other || !(other instanceof Vector)) {
+      throw new Error('angleBetween: argument must be a Vector');
+    }
+    if (this.length !== other.length) {
+      throw new Error(`angleBetween: dimension mismatch (${this.length} vs ${other.length})`);
+    }
     const dotProduct = this.dot(other);
     const n1 = this.norm();
     const n2 = other.norm();
-    if (n1.isZero() || n2.isZero()) throw new Error('Angle with zero vector is undefined');
+    if (n1.isZero() || n2.isZero()) {
+      throw new Error('angleBetween: angle with zero vector is undefined');
+    }
     // Clamp cosine to [-1, 1] for numerical safety
-    let cosv = dotProduct.div(n1.mul(n2));
+    const cosv = dotProduct.div(n1.mul(n2));
     const cosNum = cosv.toNumber();
     const clamped = Math.min(1, Math.max(-1, cosNum));
     return new Decimal(Math.acos(clamped));
@@ -211,11 +242,19 @@ export class Vector {
    * Project this vector onto another vector.
    * @param {Vector} other - Vector to project onto
    * @returns {Vector} The projection of this onto other
-   * @throws {Error} If other is zero vector
+   * @throws {Error} If other is not a Vector, dimensions mismatch, or other is zero vector
    */
   projectOnto(other) {
+    if (!other || !(other instanceof Vector)) {
+      throw new Error('projectOnto: argument must be a Vector');
+    }
+    if (this.length !== other.length) {
+      throw new Error(`projectOnto: dimension mismatch (${this.length} vs ${other.length})`);
+    }
     const denom = other.dot(other);
-    if (denom.isZero()) throw new Error('Cannot project onto zero vector');
+    if (denom.isZero()) {
+      throw new Error('projectOnto: cannot project onto zero vector');
+    }
     const coef = this.dot(other).div(denom);
     return other.scale(coef);
   }
@@ -250,8 +289,15 @@ export class Vector {
    * Check if this vector is orthogonal to another.
    * @param {Vector} other - Vector to check orthogonality with
    * @returns {boolean} True if vectors are orthogonal (dot product is zero)
+   * @throws {Error} If other is not a Vector or dimensions mismatch
    */
   isOrthogonalTo(other) {
+    if (!other || !(other instanceof Vector)) {
+      throw new Error('isOrthogonalTo: argument must be a Vector');
+    }
+    if (this.length !== other.length) {
+      throw new Error(`isOrthogonalTo: dimension mismatch (${this.length} vs ${other.length})`);
+    }
     return this.dot(other).isZero();
   }
 
@@ -259,9 +305,15 @@ export class Vector {
    * Euclidean distance to another vector.
    * @param {Vector} other - Vector to compute distance to
    * @returns {Decimal} The Euclidean distance
-   * @throws {Error} If dimensions mismatch
+   * @throws {Error} If other is not a Vector or dimensions mismatch
    */
   distance(other) {
+    if (!other || !(other instanceof Vector)) {
+      throw new Error('distance: argument must be a Vector');
+    }
+    if (this.length !== other.length) {
+      throw new Error(`distance: dimension mismatch (${this.length} vs ${other.length})`);
+    }
     return this.sub(other).norm();
   }