danceflow-geometry 1.0.0

package/dist/lineArrangement.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Line Arrangement Mathematical Operations
+ *
+ * Distributes dancers evenly along a line (horizontal, vertical, or diagonal)
+ *
+ * Math: Linear Interpolation (LERP)
+ *   P_i = P_start + (i / (n-1)) * (P_end - P_start)
+ *
+ * Where:
+ *   P_i = Position of dancer i
+ *   P_start = Start point of line
+ *   P_end = End point of line
+ *   n = Total number of dancers
+ *   i = Index of current dancer (0 to n-1)
+ *
+ * CRITICAL: All coordinates in Stage space (0-1000 units)
+ * Performance: O(n) - Must complete in <5ms for 50 dancers
+ */
+import type { DancerPosition, Point, LineOrientation, LineArrangementOptions } from './types';
+/**
+ * Arrange dancers in a line formation
+ *
+ * Math: P_i = P_start + (i / (n-1)) * (P_end - P_start)
+ *
+ * Handles edge cases:
+ * - 1 dancer: Places at centroid of line
+ * - 2 dancers: Places at start and end
+ * - 3+ dancers: Evenly distributes along line
+ *
+ * @param positions - Current dancer positions (used for determining line placement)
+ * @param options - Line arrangement configuration
+ * @returns New positions arranged in a line
+ *
+ * @example
+ * // Horizontal line
+ * const newPositions = arrangeInLine(currentPositions, {
+ *   orientation: 'horizontal',
+ *   faceDirection: 'forward'
+ * });
+ *
+ * // Diagonal line with custom endpoints
+ * const diagonalPositions = arrangeInLine(currentPositions, {
+ *   orientation: 'diagonal-45',
+ *   startPoint: { x: 100, y: 100 },
+ *   endPoint: { x: 900, y: 900 },
+ *   faceDirection: 'center'
+ * });
+ *
+ * // Fixed spacing (overrides endpoints)
+ * const spacedPositions = arrangeInLine(currentPositions, {
+ *   orientation: 'vertical',
+ *   spacing: 50, // 50 Stage units between each dancer
+ *   faceDirection: 90 // Face East
+ * });
+ */
+export declare function arrangeInLine(positions: readonly DancerPosition[], options: LineArrangementOptions): DancerPosition[];
+/**
+ * Calculate line endpoints from two dancer positions
+ * Useful for UI where user drags to define line
+ *
+ * @param point1 - First point (drag start)
+ * @param point2 - Second point (drag end)
+ * @param snapToOrientation - Optionally snap to nearest orientation
+ * @returns Orientation and adjusted endpoints
+ *
+ * @example
+ * // User drags from (100,100) to (500,150)
+ * const result = calculateLineFromDrag(
+ *   { x: 100, y: 100 },
+ *   { x: 500, y: 150 },
+ *   true // Snap to nearest orientation
+ * );
+ * // result.orientation = 'horizontal' (nearly horizontal)
+ * // result.start = { x: 100, y: 125 }
+ * // result.end = { x: 500, y: 125 }
+ */
+export declare function calculateLineFromDrag(point1: Point, point2: Point, snapToOrientation?: boolean): {
+    orientation: LineOrientation;
+    start: Point;
+    end: Point;
+};
+/**
+ * Validate that line arrangement won't exceed stage bounds
+ *
+ * @param positions - Positions to arrange
+ * @param options - Line arrangement options
+ * @param stageWidth - Stage width (default: 1000)
+ * @param stageHeight - Stage height (default: 1000)
+ * @param margin - Safety margin from edges (default: 20)
+ * @returns True if arrangement is safe
+ */
+export declare function isLineArrangementSafe(positions: readonly DancerPosition[], options: LineArrangementOptions, stageWidth?: number, stageHeight?: number, margin?: number): boolean;

package/dist/mirrorFlip.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Mirror/Flip Formation Mathematical Operations
+ *
+ * Reflects dancer positions across horizontal or vertical axis
+ *
+ * Math: Reflection Formulas
+ *   Horizontal (across Y-axis): P'_x = 2*cx - P_x, P'_y = P_y
+ *   Vertical (across X-axis):   P'_x = P_x, P'_y = 2*cy - P_y
+ *
+ * Where:
+ *   (cx, cy) = Reflection axis center (typically centroid)
+ *   P = Original position
+ *   P' = Reflected position
+ *
+ * Facing Direction:
+ *   Horizontal flip: facing' = (360 - facing) % 360  [mirrors left/right]
+ *   Vertical flip:   facing' = (180 - facing + 360) % 360  [mirrors up/down]
+ *
+ * CRITICAL: All coordinates in Stage space (0-1000 units)
+ * Performance: O(n) - Must complete in <5ms for 50 dancers
+ */
+import type { DancerPosition, Point, MirrorOptions } from './types';
+/**
+ * Mirror/flip dancer positions across an axis
+ *
+ * Math:
+ *   Horizontal: x' = 2*cx - x
+ *   Vertical:   y' = 2*cy - y
+ *
+ * Handles edge cases:
+ * - 0 dancers: Returns empty array
+ * - 1 dancer: Mirrors across centroid (results in same position if at center)
+ * - Custom axis position: Mirrors across specified line
+ *
+ * @param positions - Current dancer positions
+ * @param options - Mirror configuration
+ * @returns Mirrored positions
+ *
+ * @example
+ * // Mirror horizontally (flip left/right)
+ * const mirrored = mirrorFormation(currentPositions, {
+ *   axis: 'horizontal'
+ * });
+ *
+ * // Mirror vertically (flip up/down)
+ * const flipped = mirrorFormation(currentPositions, {
+ *   axis: 'vertical'
+ * });
+ *
+ * // Mirror across custom axis (center line at x=500)
+ * const custom = mirrorFormation(currentPositions, {
+ *   axis: 'horizontal',
+ *   axisPosition: 500
+ * });
+ *
+ * // Mirror positions but not facing
+ * const positionsOnly = mirrorFormation(currentPositions, {
+ *   axis: 'horizontal',
+ *   mirrorFacing: false
+ * });
+ */
+export declare function mirrorFormation(positions: readonly DancerPosition[], options: MirrorOptions): DancerPosition[];
+/**
+ * Create a mirrored duplicate of the formation
+ * Combines original and mirrored positions
+ *
+ * Useful for creating symmetric formations
+ *
+ * @param positions - Original positions
+ * @param options - Mirror configuration
+ * @returns Combined array of original + mirrored positions
+ *
+ * @example
+ * // Create symmetric formation (double the dancers)
+ * const symmetric = mirrorAndDuplicate(halfFormation, {
+ *   axis: 'horizontal'
+ * });
+ * // Result: original dancers + mirrored copies
+ */
+export declare function mirrorAndDuplicate(positions: readonly DancerPosition[], options: MirrorOptions): DancerPosition[];
+/**
+ * Mirror formation across both axes (180° rotation effect)
+ * Equivalent to rotating 180° around center point
+ *
+ * Math:
+ *   x' = 2*cx - x
+ *   y' = 2*cy - y
+ *   facing' = (facing + 180) % 360
+ *
+ * @param positions - Current positions
+ * @param center - Center point (auto-calculated if not provided)
+ * @param mirrorFacing - Whether to rotate facing 180° (default: true)
+ * @returns Double-mirrored positions
+ *
+ * @example
+ * // Flip formation upside down
+ * const upsideDown = mirrorBothAxes(currentPositions);
+ */
+export declare function mirrorBothAxes(positions: readonly DancerPosition[], center?: Point, mirrorFacing?: boolean): DancerPosition[];
+/**
+ * Create kaleidoscope effect by mirroring across both axes
+ * Creates 4 mirrored copies (quadrants)
+ *
+ * @param positions - Original positions (should be in one quadrant)
+ * @param center - Center point for kaleidoscope
+ * @returns Array with 4x dancers (original + 3 mirrored copies)
+ *
+ * @example
+ * // Create kaleidoscope pattern from quarter formation
+ * const kaleidoscope = createKaleidoscope(quarterFormation, { x: 500, y: 500 });
+ * // Result: 4 symmetric quadrants
+ */
+export declare function createKaleidoscope(positions: readonly DancerPosition[], center?: Point): DancerPosition[];
+/**
+ * Validate that mirrored formation won't exceed stage bounds
+ *
+ * @param positions - Positions to mirror
+ * @param options - Mirror options
+ * @param stageWidth - Stage width (default: 1000)
+ * @param stageHeight - Stage height (default: 1000)
+ * @param margin - Safety margin from edges (default: 20)
+ * @returns True if mirrored formation is safe
+ */
+export declare function isMirrorSafe(positions: readonly DancerPosition[], options: MirrorOptions, stageWidth?: number, stageHeight?: number, margin?: number): boolean;
+/**
+ * Calculate mirror axis from two points (for UI interaction)
+ * User drags a line to define mirror axis
+ *
+ * @param point1 - First point on mirror line
+ * @param point2 - Second point on mirror line
+ * @returns Axis type and position
+ *
+ * @example
+ * // User drags vertical line
+ * const mirror = calculateMirrorAxisFromDrag(
+ *   { x: 500, y: 100 },
+ *   { x: 500, y: 900 }
+ * );
+ * // mirror.axis = 'horizontal', mirror.axisPosition = 500
+ */
+export declare function calculateMirrorAxisFromDrag(point1: Point, point2: Point): {
+    axis: 'horizontal' | 'vertical';
+    axisPosition: number;
+};
+/**
+ * Find pairs of dancers that are symmetric across an axis
+ * Useful for highlighting symmetric relationships
+ *
+ * @param positions - All dancer positions
+ * @param options - Mirror configuration
+ * @param tolerance - Position tolerance for matching (Stage units, default: 10)
+ * @returns Array of [index1, index2] pairs that are symmetric
+ *
+ * @example
+ * // Find symmetric pairs
+ * const pairs = findSymmetricPairs(allPositions, { axis: 'horizontal' });
+ * // pairs = [[0, 5], [1, 6], ...] (dancers 0&5 are symmetric, etc.)
+ */
+export declare function findSymmetricPairs(positions: readonly DancerPosition[], options: MirrorOptions, tolerance?: number): Array<[number, number]>;

package/dist/polygon.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Polygon geometry utilities
+ * For lasso selection and point-in-polygon detection
+ * Optimized based on Proof 4 in math_scratchpad.md
+ */
+import type { Point } from './types';
+/**
+ * Polygon bounding box
+ */
+export interface PolygonBoundingBox {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+}
+/**
+ * Compute bounding box for a polygon
+ * O(n) operation - should be cached when possible
+ *
+ * @param polygon - Array of points [x1, y1, x2, y2, ...]
+ * @returns Bounding box
+ */
+export declare function computeBoundingBox(polygon: readonly number[]): PolygonBoundingBox;
+/**
+ * Check if a point is inside a polygon using ray casting algorithm
+ *
+ * @param point - Point to test
+ * @param polygon - Array of points forming polygon [x1, y1, x2, y2, ...]
+ * @returns true if point is inside polygon
+ */
+export declare function isPointInPolygon(point: Point, polygon: readonly number[]): boolean;
+/**
+ * Optimized point-in-polygon test with bounding box pre-check
+ * Based on Proof 4: Optimized Point-in-Polygon in math_scratchpad.md
+ *
+ * Use this for large polygons (1000+ points) and/or many point queries
+ *
+ * @param point - Point to test
+ * @param polygon - Array of points [x1, y1, x2, y2, ...]
+ * @param bbox - Pre-computed bounding box (optional, will compute if not provided)
+ * @returns true if point is inside polygon
+ */
+export declare function isPointInPolygonOptimized(point: Point, polygon: readonly number[], bbox?: PolygonBoundingBox): boolean;
+/**
+ * Batch point-in-polygon test for multiple points
+ * Computes bounding box once and reuses it
+ *
+ * @param points - Array of points to test
+ * @param polygon - Array of points [x1, y1, x2, y2, ...]
+ * @returns Array of booleans indicating if each point is inside
+ */
+export declare function batchPointInPolygon(points: readonly Point[], polygon: readonly number[]): boolean[];
+/**
+ * Calculate the area of a polygon
+ * Uses the shoelace formula
+ *
+ * @param polygon - Array of points [x1, y1, x2, y2, ...]
+ * @returns Signed area (positive for counter-clockwise, negative for clockwise)
+ */
+export declare function polygonArea(polygon: readonly number[]): number;
+/**
+ * Calculate the centroid of a polygon
+ *
+ * @param polygon - Array of points [x1, y1, x2, y2, ...]
+ * @returns Centroid point
+ */
+export declare function polygonCentroid(polygon: readonly number[]): Point;
+/**
+ * Simplify a polygon by removing points closer than a threshold
+ * Useful for reducing the complexity of lasso selections
+ *
+ * @param polygon - Array of points [x1, y1, x2, y2, ...]
+ * @param threshold - Minimum distance between consecutive points
+ * @returns Simplified polygon
+ */
+export declare function simplifyPolygon(polygon: readonly number[], threshold: number): number[];

package/dist/rotateFormation.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Rotate Formation Mathematical Operations
+ *
+ * Rotates dancer positions around a center point using rotation matrix
+ *
+ * Math: 2D Rotation Matrix (adapted for Stage coordinates with Y-down)
+ *   x' = cx + (x - cx) * cos(θ) - (y - cy) * sin(θ)
+ *   y' = cy + (x - cx) * sin(θ) + (y - cy) * cos(θ)
+ *
+ * CRITICAL: Stage coordinates have Y-axis pointing DOWN (not up like math)
+ * This means we need to negate the Y component in rotation calculations
+ * to achieve counterclockwise rotation visually.
+ *
+ * Where:
+ *   (cx, cy) = Center of rotation (typically centroid)
+ *   θ = Rotation angle in radians (positive = counterclockwise)
+ *   (x, y) = Original position
+ *   (x', y') = Rotated position
+ *
+ * Facing Direction:
+ *   facing' = (facing + rotationDegrees) % 360
+ *
+ * Common Rotations:
+ *   90° (π/2):   Quarter turn counterclockwise
+ *   180° (π):    Half turn
+ *   270° (3π/2): Quarter turn clockwise (or -90°)
+ *   -90° (-π/2): Quarter turn clockwise
+ *
+ * CRITICAL: All coordinates in Stage space (0-1000 units)
+ * Performance: O(n) - Must complete in <5ms for 50 dancers
+ */
+import type { Point, DancerPosition } from './types';
+/**
+ * Preset rotation angles (in degrees)
+ */
+export type RotationPreset = 90 | 180 | 270 | -90 | -180 | -270;
+/**
+ * Options for rotation transformation
+ */
+export interface RotateOptions {
+    /** Rotation angle in degrees (positive = counterclockwise) */
+    angle: number;
+    /** Center of rotation (auto-calculated if not provided) */
+    center?: Point;
+    /** Whether to rotate facing direction (default: true) */
+    rotateFacing?: boolean;
+}
+/**
+ * Rotate formation around a center point
+ *
+ * Math: Uses 2D rotation matrix transformation (adapted for Stage Y-down coords)
+ *
+ * Handles edge cases:
+ * - 0 dancers: Returns empty array
+ * - 1 dancer: Rotates around center (may stay in place if at center)
+ * - 0° rotation: Returns original positions
+ * - 360° rotation: Returns to original positions
+ *
+ * Positive angles rotate counterclockwise (standard mathematical convention)
+ * Negative angles rotate clockwise
+ *
+ * @example
+ * // Rotate 90° counterclockwise
+ * const rotated = rotateFormation(currentPositions, {
+ *   angle: 90
+ * });
+ *
+ * @example
+ * // Rotate 90° clockwise (negative angle)
+ * const clockwise = rotateFormation(currentPositions, {
+ *   angle: -90
+ * });
+ *
+ * @example
+ * // Rotate 180° (flip)
+ * const flipped = rotateFormation(currentPositions, {
+ *   angle: 180
+ * });
+ *
+ * @example
+ * // Rotate around custom center
+ * const custom = rotateFormation(currentPositions, {
+ *   angle: 45,
+ *   center: { x: 500, y: 500 }
+ * });
+ *
+ * @example
+ * // Rotate positions but not facing
+ * const positionsOnly = rotateFormation(currentPositions, {
+ *   angle: 90,
+ *   rotateFacing: false
+ * });
+ */
+export declare function rotateFormation(positions: readonly DancerPosition[], options: RotateOptions): DancerPosition[];
+/**
+ * Rotate formation by preset angle (90°, 180°, 270°)
+ * Convenience wrapper with common rotation values
+ *
+ * @example
+ * // Quarter turn counterclockwise
+ * const rotated = rotateFormationPreset(positions, 90);
+ *
+ * @example
+ * // Half turn
+ * const half = rotateFormationPreset(positions, 180);
+ *
+ * @example
+ * // Quarter turn clockwise
+ * const clockwise = rotateFormationPreset(positions, -90);
+ */
+export declare function rotateFormationPreset(positions: readonly DancerPosition[], preset: RotationPreset, center?: Point): DancerPosition[];
+/**
+ * Create rotational copies of a formation
+ * Useful for creating symmetric radial patterns
+ *
+ * @example
+ * // Create 4-way rotational symmetry
+ * const pattern = createRotationalCopies(wedgeFormation, 4, { x: 500, y: 500 });
+ * // Result: 4 copies rotated 0°, 90°, 180°, 270°
+ *
+ * @example
+ * // Create 6-way star pattern
+ * const star = createRotationalCopies(rayFormation, 6);
+ * // Result: 6 copies rotated 0°, 60°, 120°, 180°, 240°, 300°
+ */
+export declare function createRotationalCopies(positions: readonly DancerPosition[], copies: number, center?: Point): DancerPosition[];
+/**
+ * Animate smooth rotation between two angles
+ * Generates intermediate positions for rotation animation
+ *
+ * @example
+ * // Animate 90° rotation in 10 steps
+ * const frames = animateRotation(positions, 0, 90, 10);
+ * // frames[0] = positions at 0°
+ * // frames[5] = positions at 45°
+ * // frames[9] = positions at 90°
+ */
+export declare function animateRotation(positions: readonly DancerPosition[], startAngle: number, endAngle: number, steps: number, center?: Point): DancerPosition[][];
+/**
+ * Calculate rotation angle from two points (for UI interaction)
+ * User drags from center to define rotation
+ *
+ * CRITICAL: Adapted for Stage coordinates with Y-down
+ * We negate the Y components to get correct angle direction
+ *
+ * @example
+ * // User drags from right to top (90° counterclockwise)
+ * const angle = calculateRotationFromDrag(
+ *   { x: 500, y: 500 },
+ *   { x: 600, y: 500 }, // Start: right of center
+ *   { x: 500, y: 400 }  // End: top of center
+ * );
+ * // angle ≈ 90
+ */
+export declare function calculateRotationFromDrag(center: Point, startPoint: Point, endPoint: Point): number;
+/**
+ * Snap rotation angle to nearest preset (45° increments)
+ *
+ * @example
+ * snapRotationAngle(47) // → 45
+ * snapRotationAngle(92) // → 90
+ * snapRotationAngle(178) // → 180
+ */
+export declare function snapRotationAngle(angle: number, snapIncrement?: number): number;
+/**
+ * Validate that rotated formation won't exceed stage bounds
+ */
+export declare function isRotationSafe(positions: readonly DancerPosition[], options: RotateOptions, stageWidth?: number, stageHeight?: number, margin?: number): boolean;
+/**
+ * Calculate bounding box diagonal length
+ * Useful for determining safe rotation radius
+ */
+export declare function getBoundingBoxDiagonal(positions: readonly DancerPosition[]): number;
+/**
+ * Calculate maximum safe rotation radius for formation to stay on stage
+ */
+export declare function getMaxRotationRadius(center: Point, stageWidth?: number, stageHeight?: number, margin?: number): number;

package/dist/spline.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Catmull-Rom spline interpolation for smooth path generation
+ * Implements proof from math_scratchpad.md
+ */
+import type { Point } from './types';
+/**
+ * Bezier control points for a cubic Bezier curve
+ */
+export interface BezierControlPoints {
+    start: Point;
+    control1: Point;
+    control2: Point;
+    end: Point;
+}
+/**
+ * Interpolate a point on a Catmull-Rom spline segment
+ * Based on Proof 3: Catmull-Rom Spline Interpolation in math_scratchpad.md
+ *
+ * @param p0 - Point before start (for tangent calculation)
+ * @param p1 - Segment start point
+ * @param p2 - Segment end point
+ * @param p3 - Point after end (for tangent calculation)
+ * @param t - Parameter in [0, 1]
+ * @returns Interpolated point
+ */
+export declare function catmullRomPoint(p0: Point, p1: Point, p2: Point, p3: Point, t: number): Point;
+/**
+ * Generate a smooth Catmull-Rom spline through control points
+ *
+ * @param controlPoints - Array of points to interpolate through
+ * @param segmentsPerCurve - Number of points to generate per curve segment (default: 20)
+ * @returns Array of interpolated points forming the smooth path
+ */
+export declare function catmullRomSpline(controlPoints: readonly Point[], segmentsPerCurve?: number): Point[];
+/**
+ * Convert a Catmull-Rom segment to cubic Bezier control points
+ * Based on conversion formula from math_scratchpad.md
+ *
+ * @param p0 - Point before start
+ * @param p1 - Segment start
+ * @param p2 - Segment end
+ * @param p3 - Point after end
+ * @returns Cubic Bezier control points
+ */
+export declare function catmullRomToBezier(p0: Point, p1: Point, p2: Point, p3: Point): BezierControlPoints;
+/**
+ * Convert entire Catmull-Rom spline to Bezier curves
+ * Useful for rendering with Canvas/SVG bezierCurveTo
+ *
+ * @param controlPoints - Array of control points
+ * @returns Array of Bezier curve segments
+ */
+export declare function catmullRomSplineToBezier(controlPoints: readonly Point[]): BezierControlPoints[];
+/**
+ * Calculate the tangent (derivative) at a point on the Catmull-Rom spline
+ * Useful for orienting dancers along a path
+ *
+ * @param p0 - Point before start
+ * @param p1 - Segment start
+ * @param p2 - Segment end
+ * @param p3 - Point after end
+ * @param t - Parameter in [0, 1]
+ * @returns Tangent vector (not normalized)
+ */
+export declare function catmullRomTangent(p0: Point, p1: Point, p2: Point, p3: Point, t: number): Point;
+/**
+ * Calculate the angle (in degrees) of the tangent at a point
+ * Useful for setting dancer facing direction along a path
+ *
+ * @param p0 - Point before start
+ * @param p1 - Segment start
+ * @param p2 - Segment end
+ * @param p3 - Point after end
+ * @param t - Parameter in [0, 1]
+ * @returns Angle in degrees (0 = right, 90 = down)
+ */
+export declare function catmullRomAngle(p0: Point, p1: Point, p2: Point, p3: Point, t: number): number;
+/**
+ * Calculate arc length of a Catmull-Rom segment
+ * Uses numerical integration (Simpson's rule)
+ *
+ * @param p0 - Point before start
+ * @param p1 - Segment start
+ * @param p2 - Segment end
+ * @param p3 - Point after end
+ * @param samples - Number of samples for integration (default: 100)
+ * @returns Arc length
+ */
+export declare function catmullRomArcLength(p0: Point, p1: Point, p2: Point, p3: Point, samples?: number): number;
+/**
+ * Sample a Catmull-Rom spline at uniform distances (arc-length parameterization)
+ * Useful for placing dancers at equal spacing along a curved path
+ *
+ * @param controlPoints - Array of control points
+ * @param spacing - Desired spacing between samples
+ * @returns Array of evenly spaced points along the curve
+ */
+export declare function catmullRomUniformSample(controlPoints: readonly Point[], spacing: number): Point[];

package/dist/spreader.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Enhanced spreader tool with directional and elliptical scaling
+ * Implements mathematical proofs from math_scratchpad.md
+ */
+import type { DancerPosition, Point, SpreadOptions } from './types';
+/**
+ * Apply elliptical scaling to positions around a center point
+ * Based on Proof 1: Elliptical Spreading Transform in math_scratchpad.md
+ *
+ * @param positions - Array of positions to transform
+ * @param scaleX - Horizontal scale factor
+ * @param scaleY - Vertical scale factor
+ * @param center - Center point (optional, will calculate if not provided)
+ * @param rotationDegrees - Rotation angle in degrees (default: 0)
+ * @returns Transformed positions
+ */
+export declare function ellipticalScale(positions: readonly DancerPosition[], scaleX: number, scaleY: number, center?: Point, rotationDegrees?: number): DancerPosition[];
+/**
+ * Apply directional spreading to positions
+ * Convenience wrapper around ellipticalScale for common spread patterns
+ *
+ * @param positions - Array of positions to spread
+ * @param options - Spread configuration options
+ * @returns Spread positions
+ */
+export declare function directionalSpread(positions: readonly DancerPosition[], options: SpreadOptions): DancerPosition[];
+/**
+ * Calculate the spread factor needed to achieve a target distance
+ * Useful for UI controls that want to spread by absolute distance rather than scale factor
+ *
+ * @param positions - Current positions
+ * @param targetDistance - Desired average distance from center
+ * @param center - Center point (optional)
+ * @returns Scale factor to achieve target distance
+ */
+export declare function calculateSpreadFactorForDistance(positions: readonly DancerPosition[], targetDistance: number, center?: Point): number;
+/**
+ * Get bounding box dimensions of positions
+ * Useful for determining appropriate spread limits
+ *
+ * @param positions - Array of positions
+ * @returns Bounding box with dimensions
+ */
+export declare function getBoundingBox(positions: readonly DancerPosition[]): {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+    width: number;
+    height: number;
+};
+/**
+ * Check if spreading would cause positions to exceed stage bounds
+ *
+ * @param positions - Positions to check
+ * @param scaleFactor - Proposed scale factor
+ * @param stageWidth - Stage width in units
+ * @param stageHeight - Stage height in units
+ * @param center - Center point (optional)
+ * @returns True if spread is safe, false if it would exceed bounds
+ */
+export declare function isSpreadSafe(positions: readonly DancerPosition[], scaleFactor: number, stageWidth: number, stageHeight: number, center?: Point): boolean;