import { BivectorN, VecN } from '@holotope/core';
import type { RigidMotion4 } from './contact-kinematics4.js';
import { RigidBody4 } from './rigid-body4.js';
/** Dynamic body, prescribed rigid motion, or an immovable world participant. */
export type ConstraintParticipant4 = RigidBody4 | RigidMotion4 | null;
/** One participant's linear and six-plane angular coefficients in an R4 row. */
export interface RigidJacobian4 {
    readonly linear: VecN;
    readonly angular: BivectorN;
}
/**
 * Scalar rigid-Jacobian row `J_A v_A + J_B v_B = targetSpeed`.
 *
 * `positionError` must use the same orientation as the Jacobian: positive
 * error is reduced by negative coordinate speed. Persistent rows must retain
 * a coherent ID and Jacobian orientation for warm starting.
 */
export interface ConstraintRow4 {
    /** Stable identity, so a solver can warm-start this row's impulse. */
    readonly id: string;
    /** First body or anchor the row couples. */
    readonly participantA: ConstraintParticipant4;
    /** How `participantA`'s motion enters the coordinate, in its own frame. */
    readonly jacobianA: RigidJacobian4;
    /** Second body or anchor the row couples. */
    readonly participantB: ConstraintParticipant4;
    /** How `participantB`'s motion enters the coordinate, in its own frame. */
    readonly jacobianB: RigidJacobian4;
    /** Signed coordinate violation to be stabilized away. Default 0. */
    readonly positionError?: number;
    /** Authored coordinate speed before position stabilization. Default 0. */
    readonly velocityTarget?: number;
    /** Lower generalized-force bound. Default negative infinity. */
    readonly minForce?: number;
    /** Upper generalized-force bound. Default positive infinity. */
    readonly maxForce?: number;
}
export interface ConstraintRowSolver4Options {
    /** Projected Gauss-Seidel passes. Default 8. */
    readonly iterations?: number;
    /** Fraction of signed position error corrected per step. Default 0.2. */
    readonly baumgarte?: number;
    /** Absolute position error ignored by velocity-level bias. Default 0.001. */
    readonly positionSlop?: number;
    /** Upper bound on the stabilization coordinate speed. Default 2. */
    readonly maxBiasSpeed?: number;
    /** Apply coherent impulses retained from the previous solve. Default true. */
    readonly warmStart?: boolean;
}
export type ConstraintImpulseState4 = 'unbounded' | 'within-bounds' | 'at-minimum' | 'at-maximum' | 'fixed';
export interface ConstraintRowResult4 {
    readonly id: string;
    readonly positionError: number;
    /** Scalar `J M^-1 J^T`. */
    readonly response: number;
    readonly effectiveMass: number;
    readonly initialSpeed: number;
    readonly velocityTarget: number;
    readonly biasSpeed: number;
    readonly targetSpeed: number;
    readonly minForce: number;
    readonly maxForce: number;
    readonly minImpulse: number;
    readonly maxImpulse: number;
    readonly warmStartedImpulse: number;
    readonly accumulatedImpulse: number;
    readonly impulseState: ConstraintImpulseState4;
    readonly finalSpeed: number;
    /** Raw equality residual; may remain nonzero at a valid active bound. */
    readonly residualSpeed: number;
    /** Projected fixed-point residual; zero is the bounded-row KKT condition. */
    readonly projectedResidualSpeed: number;
}
export interface ConstraintRowSolveResult4 {
    readonly rows: readonly ConstraintRowResult4[];
    readonly retiredIds: readonly string[];
    readonly iterations: number;
    /** Sum of absolute scalar row impulses; coordinate-scale diagnostic only. */
    readonly sumAbsoluteCoordinateImpulse: number;
    readonly maxResidualSpeed: number;
    readonly maxProjectedResidualSpeed: number;
    /** Maximum absolute authored row error; units depend on row coordinates. */
    readonly maxAbsoluteCoordinateError: number;
}
export interface PointConstraintPair4 {
    readonly participantA: ConstraintParticipant4;
    readonly participantB: ConstraintParticipant4;
    readonly anchorA: VecN;
    readonly anchorB: VecN;
}
export interface PointConstraintRow4Options {
    readonly id: string;
    readonly participantA: ConstraintParticipant4;
    readonly participantB: ConstraintParticipant4;
    readonly anchorA: VecN | ArrayLike<number>;
    readonly anchorB: VecN | ArrayLike<number>;
    /** Finite nonzero world direction; normalized by the adapter. */
    readonly direction: VecN | ArrayLike<number>;
    readonly positionError?: number;
    readonly velocityTarget?: number;
    readonly minForce?: number;
    readonly maxForce?: number;
}
/** Warm-started projected solver for scalar rigid-Jacobian rows in R4. */
export declare class ConstraintRowSolver4 {
    readonly iterations: number;
    readonly baumgarte: number;
    readonly positionSlop: number;
    readonly maxBiasSpeed: number;
    readonly warmStart: boolean;
    private cache;
    constructor(options?: ConstraintRowSolver4Options);
    solve(constraints: readonly ConstraintRow4[], dt: number): ConstraintRowSolveResult4;
    reset(): void;
    private prepare;
    private applyWarmStart;
    private solveRow;
}
/** Builds a normalized point-direction equality row with exact R4 lever arms. */
export declare function pointConstraintRow4(options: PointConstraintRow4Options): ConstraintRow4;
/** Scalar generalized speed `J_A v_A + J_B v_B`. */
export declare function constraintRowSpeed4(constraint: ConstraintRow4): number;
/** Scalar response `J M^-1 J^T`. */
export declare function constraintRowResponse4(constraint: ConstraintRow4): number;
/** Cross-response `J_left M^-1 J_right^T` for coherent row blocks. */
export declare function constraintRowCoupling4(left: ConstraintRow4, right: ConstraintRow4): number;
/** Applies the generalized impulse `M^-1 J^T lambda` to dynamic participants. */
export declare function applyConstraintRowImpulse4(constraint: ConstraintRow4, impulse: number): void;
/** Relative world velocity `velocityA(anchorA) - velocityB(anchorB)`. */
export declare function pointPairRelativeVelocity4(pair: PointConstraintPair4): VecN;
/** Applies equal and opposite R4 point impulses to a participant pair. */
export declare function applyPointPairImpulse4(pair: PointConstraintPair4, impulseWorld: VecN | ArrayLike<number>): void;
/** World velocity of a dynamic, prescribed, or fixed participant at a point. */
export declare function participantVelocityAtPoint4(participant: ConstraintParticipant4, anchor: VecN): VecN;
//# sourceMappingURL=constraint-row4.d.ts.map