curvy 2.0.0-alpha.11 → 2.0.0-alpha.13

package/dist/characteristic/index.mjs

@@ -1,2 +1,2 @@
-import { n as characteristic_exports } from "../shared/characteristic-Hb7F8SBw.mjs";
+import { n as characteristic_exports } from "../shared/characteristic-BkEr-rr8.mjs";
 export { characteristic_exports as Characteristic };

package/dist/curve/index.mjs

@@ -1,2 +1,2 @@
-import { S as linear2d_exports, g as quadratic2d_exports, o as cubic2d_exports, r as rationalCubic2d_exports } from "../shared/rationalCubic2d-IroMR6AA.mjs";
+import { _ as quadratic2d_exports, i as rationalCubic2d_exports, s as cubic2d_exports, w as linear2d_exports } from "../shared/rationalCubic2d-CeHgpNht.mjs";
 export { cubic2d_exports as CubicCurve2d, linear2d_exports as LinearCurve2d, quadratic2d_exports as QuadraticCurve2d, rationalCubic2d_exports as RationalCubicCurve2d };

package/dist/curve/rationalCubic2d.d.ts

@@ -1,8 +1,9 @@
 import type { Closed } from '../interval/interval.ts';
 import type { Interval2d } from '../interval/interval2d.ts';
+import type { Monotonicity } from '../monotonicity/monotonicity.ts';
 import type { Pipeable } from '../utils.ts';
 import type { CubicPolynomial } from '../polynomial/cubic.ts';
-import type { Increasing, Monotonic } from '../polynomial/traits.ts';
+import type { Decreasing, Increasing, Monotonic } from '../polynomial/traits.ts';
 import type * as Solution from '../solution/solution.ts';
 import type { Vector2, Weighted } from '../vector/vector2.ts';
 import type { CubicCurve2d } from './cubic2d.ts';
@@ -191,22 +192,205 @@ export declare const subdivide: {
      */
     (t: number): (c: RationalCubicCurve2d) => [RationalCubicCurve2d, RationalCubicCurve2d];
 };
+export declare const boundingBox: {
+    /**
+     * Computes a closed axis-aligned bounding box for a rational cubic curve,
+     * tight to within `tolerance` per side.
+     *
+     * Implemented as recursive subdivision: at each leaf the curve segment's
+     * loose hull AABB (cheap, always valid) is compared against the segment's
+     * endpoint AABB (which the curve provably visits). When the per-side gap
+     * between them is ≤ `tolerance`, the leaf returns its hull; otherwise the
+     * segment is split at `t = 0.5` and the procedure recurses, unioning the
+     * halves.
+     *
+     * The returned box is provably within `tolerance` of the true tight box on
+     * every side, and contains the curve since each leaf hull does. The
+     * polynomial cubic case (uniform weights) is handled by a fast path that
+     * computes the exact box from per-axis cubic extrema, with no subdivision.
+     *
+     * @param c - The rational cubic curve.
+     * @param tolerance - Maximum allowed slack per side; must be positive.
+     * @returns A closed `Interval2d` enclosing the curve, tight to within `tolerance`.
+     * @since 2.0.0
+     */
+    (c: RationalCubicCurve2d, tolerance: number): Interval2d<Closed, Closed>;
+    /**
+     * Computes a closed axis-aligned bounding box for a rational cubic curve.
+     *
+     * @param tolerance - Maximum allowed slack per side; must be positive.
+     * @returns A function that takes a curve and returns its bounding box.
+     * @since 2.0.0
+     */
+    (tolerance: number): (c: RationalCubicCurve2d) => Interval2d<Closed, Closed>;
+};
+/**
+ * Classifies the monotonicity of the curve's `x(t) = X(t)/W(t)` projection on
+ * the unit interval `[0, 1]`.
+ *
+ * Decided via Bernstein sign convexity on the derivative-numerator polynomial
+ * `q(t) = X'·W − X·W'`. Since `W² > 0` wherever the curve is well-defined,
+ * the sign of `dx/dt` equals the sign of `q`. Although `q` is a difference of
+ * degree-5 products, the leading terms cancel and `q` is in fact a quartic —
+ * its 5 Bernstein coefficients on `[0, 1]` are evaluated for uniform sign,
+ * with de Casteljau subdivision to resolve mixed-sign cases. The procedure is
+ * exact except at tangential zeros, where it conservatively reports `None`.
+ *
+ * Returning `Increasing` or `Decreasing` is the trigger for
+ * {@link asMonotonic} / {@link asIncreasing} / {@link asDecreasing}.
+ *
+ * @param c - The rational cubic curve.
+ * @returns The monotonicity of the curve's x projection on `[0, 1]`.
+ * @since 2.0.0
+ */
+export declare const xMonotonicity: (c: RationalCubicCurve2d) => Monotonicity;
+/**
+ * Classifies the monotonicity of the curve's `y(t) = Y(t)/W(t)` projection on
+ * the unit interval `[0, 1]`. See {@link xMonotonicity} for the method.
+ *
+ * @param c - The rational cubic curve.
+ * @returns The monotonicity of the curve's y projection on `[0, 1]`.
+ * @since 2.0.0
+ */
+export declare const yMonotonicity: (c: RationalCubicCurve2d) => Monotonicity;
+/**
+ * Type-narrowing predicate: refines the curve's x-axis trait to include
+ * `Monotonic` when `x(t)/w(t)` is strictly monotonic on `[0, 1]`. The y-axis
+ * trait is unchanged.
+ *
+ * Use this when only x-axis monotonicity is required (e.g. to make {@link solveAtX}
+ * narrow to `AtMostOne` without also asserting y-axis monotonicity).
+ *
+ * @param c - The rational cubic curve.
+ * @returns `true` when the x projection is strictly monotonic on `[0, 1]`.
+ * @since 2.0.0
+ */
+export declare const isMonotonicX: <XT, YT>(c: RationalCubicCurve2d<XT, YT>) => c is RationalCubicCurve2d<XT & Monotonic, YT>;
+/**
+ * Type-narrowing predicate: refines the curve's x-axis trait to include
+ * `Increasing`.
+ *
+ * @since 2.0.0
+ */
+export declare const isIncreasingX: <XT, YT>(c: RationalCubicCurve2d<XT, YT>) => c is RationalCubicCurve2d<XT & Increasing, YT>;
+/**
+ * Type-narrowing predicate: refines the curve's x-axis trait to include
+ * `Decreasing`.
+ *
+ * @since 2.0.0
+ */
+export declare const isDecreasingX: <XT, YT>(c: RationalCubicCurve2d<XT, YT>) => c is RationalCubicCurve2d<XT & Decreasing, YT>;
+/**
+ * Type-narrowing predicate: refines the curve's y-axis trait to include
+ * `Monotonic`. The x-axis trait is unchanged. y analog of {@link isMonotonicX}.
+ *
+ * @since 2.0.0
+ */
+export declare const isMonotonicY: <XT, YT>(c: RationalCubicCurve2d<XT, YT>) => c is RationalCubicCurve2d<XT, YT & Monotonic>;
+/**
+ * Type-narrowing predicate: refines the curve's y-axis trait to include
+ * `Increasing`.
+ *
+ * @since 2.0.0
+ */
+export declare const isIncreasingY: <XT, YT>(c: RationalCubicCurve2d<XT, YT>) => c is RationalCubicCurve2d<XT, YT & Increasing>;
+/**
+ * Type-narrowing predicate: refines the curve's y-axis trait to include
+ * `Decreasing`.
+ *
+ * @since 2.0.0
+ */
+export declare const isDecreasingY: <XT, YT>(c: RationalCubicCurve2d<XT, YT>) => c is RationalCubicCurve2d<XT, YT & Decreasing>;
+/**
+ * Type-narrowing predicate: refines both axes' traits to include `Monotonic`
+ * when both `x(t)/w(t)` and `y(t)/w(t)` are strictly monotonic on `[0, 1]`.
+ *
+ * The constant case is excluded — `Monotonic` is the *strict* brand.
+ *
+ * @param c - The rational cubic curve.
+ * @returns `true` when both axes are strictly monotonic on `[0, 1]`.
+ * @since 2.0.0
+ */
+export declare const isMonotonic: <XT, YT>(c: RationalCubicCurve2d<XT, YT>) => c is RationalCubicCurve2d<XT & Monotonic, YT & Monotonic>;
+/**
+ * Type-narrowing predicate: refines both axes' traits to include `Increasing`
+ * when both `x(t)/w(t)` and `y(t)/w(t)` are strictly increasing on `[0, 1]`.
+ *
+ * @since 2.0.0
+ */
+export declare const isIncreasing: <XT, YT>(c: RationalCubicCurve2d<XT, YT>) => c is RationalCubicCurve2d<XT & Increasing, YT & Increasing>;
+/**
+ * Type-narrowing predicate: refines both axes' traits to include `Decreasing`
+ * when both `x(t)/w(t)` and `y(t)/w(t)` are strictly decreasing on `[0, 1]`.
+ *
+ * @since 2.0.0
+ */
+export declare const isDecreasing: <XT, YT>(c: RationalCubicCurve2d<XT, YT>) => c is RationalCubicCurve2d<XT & Decreasing, YT & Decreasing>;
+/**
+ * Asserts that the curve is strictly monotonic in x on `[0, 1]`, returning
+ * the same curve with the x-axis trait branded `Monotonic`.
+ *
+ * @param c - The rational cubic curve.
+ * @returns The same curve, refined with the `Monotonic` brand on x.
+ * @throws When the x projection is not strictly monotonic on `[0, 1]`.
+ * @since 2.0.0
+ */
+export declare const asMonotonicX: <XT, YT>(c: RationalCubicCurve2d<XT, YT>) => RationalCubicCurve2d<XT & Monotonic, YT>;
+/**
+ * Asserts that the curve is strictly increasing in x on `[0, 1]`.
+ *
+ * @since 2.0.0
+ */
+export declare const asIncreasingX: <XT, YT>(c: RationalCubicCurve2d<XT, YT>) => RationalCubicCurve2d<XT & Increasing, YT>;
+/**
+ * Asserts that the curve is strictly decreasing in x on `[0, 1]`.
+ *
+ * @since 2.0.0
+ */
+export declare const asDecreasingX: <XT, YT>(c: RationalCubicCurve2d<XT, YT>) => RationalCubicCurve2d<XT & Decreasing, YT>;
+/**
+ * Asserts that the curve is strictly monotonic in y on `[0, 1]`. y analog of
+ * {@link asMonotonicX}.
+ *
+ * @since 2.0.0
+ */
+export declare const asMonotonicY: <XT, YT>(c: RationalCubicCurve2d<XT, YT>) => RationalCubicCurve2d<XT, YT & Monotonic>;
+/**
+ * Asserts that the curve is strictly increasing in y on `[0, 1]`.
+ *
+ * @since 2.0.0
+ */
+export declare const asIncreasingY: <XT, YT>(c: RationalCubicCurve2d<XT, YT>) => RationalCubicCurve2d<XT, YT & Increasing>;
 /**
- * Computes a closed axis-aligned bounding box for a rational cubic curve from
- * its projected control polygon. Looser than the tight extrema-based box used
- * by `CubicCurve2d.boundingBox` — finding tight extrema of `x(t)/w(t)` and
- * `y(t)/w(t)` requires solving degree-5 polynomials — but always valid: a
- * positive-weight rational Bézier curve lies inside the convex hull of its
- * projected control points, so the AABB of those points contains the curve.
+ * Asserts that the curve is strictly decreasing in y on `[0, 1]`.
  *
- * Suitable for subdivision-based geometric queries, where bound looseness is
- * compensated by recursion depth.
+ * @since 2.0.0
+ */
+export declare const asDecreasingY: <XT, YT>(c: RationalCubicCurve2d<XT, YT>) => RationalCubicCurve2d<XT, YT & Decreasing>;
+/**
+ * Asserts that the curve is strictly monotonic in both axes on `[0, 1]`,
+ * returning the same curve with both axes branded `Monotonic`.
  *
  * @param c - The rational cubic curve.
- * @returns A closed `Interval2d` enclosing the curve.
+ * @returns The same curve, refined with the `Monotonic` brand on both axes.
+ * @throws When either axis is not strictly monotonic on `[0, 1]`.
+ * @since 2.0.0
+ */
+export declare const asMonotonic: <XT, YT>(c: RationalCubicCurve2d<XT, YT>) => RationalCubicCurve2d<XT & Monotonic, YT & Monotonic>;
+/**
+ * Asserts that the curve is strictly increasing in both axes on `[0, 1]`,
+ * returning the same curve with both axes branded `Increasing`.
+ *
+ * @since 2.0.0
+ */
+export declare const asIncreasing: <XT, YT>(c: RationalCubicCurve2d<XT, YT>) => RationalCubicCurve2d<XT & Increasing, YT & Increasing>;
+/**
+ * Asserts that the curve is strictly decreasing in both axes on `[0, 1]`,
+ * returning the same curve with both axes branded `Decreasing`.
+ *
  * @since 2.0.0
  */
-export declare const boundingBox: (c: RationalCubicCurve2d) => Interval2d<Closed, Closed>;
+export declare const asDecreasing: <XT, YT>(c: RationalCubicCurve2d<XT, YT>) => RationalCubicCurve2d<XT & Decreasing, YT & Decreasing>;
 export declare const approximateAsCubicCurves: {
     /**
      * Approximates the rational cubic as a sequence of polynomial cubic curves

package/dist/interval/index.mjs

@@ -1,3 +1,3 @@
 import { s as interval_exports } from "../shared/interval-Dm35Xhy4.mjs";
-import { n as interval2d_exports } from "../shared/interval2d-DPmvk_Qe.mjs";
+import { n as interval2d_exports } from "../shared/interval2d-AtneyI45.mjs";
 export { interval_exports as Interval, interval2d_exports as Interval2d };

package/dist/monotonicity/index.d.ts

@@ -0,0 +1,4 @@
+import * as MonotonicityNs from './monotonicity.ts';
+export type Monotonicity = MonotonicityNs.Monotonicity;
+export type GuaranteedMonotonicity = MonotonicityNs.GuaranteedMonotonicity;
+export { MonotonicityNs as Monotonicity };

package/dist/monotonicity/index.mjs

@@ -0,0 +1,2 @@
+import { r as monotonicity_exports } from "../shared/monotonicity-BdebFOtv.mjs";
+export { monotonicity_exports as Monotonicity };

package/dist/monotonicity/monotonicity.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Classification of a function's monotonicity on an interval.
+ *
+ * Encoded as a 2-bit sign-coverage bitmask of the function's derivative:
+ *   - bit 0 (`Increasing`) — derivative takes positive values
+ *   - bit 1 (`Decreasing`) — derivative takes negative values
+ *
+ * The four states fall out of the encoding:
+ *
+ *   | value | name         | derivative on the interval        |
+ *   |-------|--------------|-----------------------------------|
+ *   |   `0` | `Constant`   | ≡ 0                               |
+ *   |   `1` | `Increasing` | ≥ 0, with at least one `> 0`      |
+ *   |   `2` | `Decreasing` | ≤ 0, with at least one `< 0`      |
+ *   |   `3` | `None`       | crosses zero                      |
+ *
+ * The numeric encoding is principled, not arbitrary: the bitwise OR of two
+ * adjacent subintervals' classifications gives the classification of their
+ * union, which lets monotonicity be computed by recursive subdivision
+ * without any custom combine logic.
+ *
+ * @since 2.0.0
+ */
+export type Monotonicity = 0 | 1 | 2 | 3;
+/**
+ * Subset of {@link Monotonicity} excluding the indeterminate `None` state.
+ * Returned by classifiers operating on functions whose derivative cannot
+ * change sign on the interval (e.g. linear polynomials, whose derivative is
+ * constant).
+ *
+ * @since 2.0.0
+ */
+export type GuaranteedMonotonicity = 0 | 1 | 2;
+/**
+ * Derivative is identically zero on the interval. The function is constant.
+ *
+ * @since 2.0.0
+ */
+export declare const Constant: 0;
+/**
+ * Derivative is non-negative on the interval with at least one strictly
+ * positive sample. The function is strictly increasing.
+ *
+ * @since 2.0.0
+ */
+export declare const Increasing: 1;
+/**
+ * Derivative is non-positive on the interval with at least one strictly
+ * negative sample. The function is strictly decreasing.
+ *
+ * @since 2.0.0
+ */
+export declare const Decreasing: 2;
+/**
+ * Derivative crosses zero on the interval. The function has at least one
+ * interior extremum and is not monotonic in either direction.
+ *
+ * @since 2.0.0
+ */
+export declare const None: 3;
+/**
+ * Type-narrowing predicate: refines a `Monotonicity` to `Increasing |
+ * Decreasing` — the strict cases that admit a unique inverse.
+ *
+ * @param m - The monotonicity classification.
+ * @returns `true` when `m` is `Increasing` or `Decreasing`.
+ * @since 2.0.0
+ */
+export declare const isStrict: (m: Monotonicity) => m is 1 | 2;
+/**
+ * Classifies the monotonicity of a function given its values at two interval
+ * endpoints, when the function is known a priori to be monotonic on the
+ * spanning interval (e.g. a linear polynomial).
+ *
+ * @param s0 - The function value at the start of the interval.
+ * @param s1 - The function value at the end of the interval.
+ * @returns The classification — `Increasing`, `Decreasing`, or `Constant`.
+ * @since 2.0.0
+ */
+export declare const fromComparison: (s0: number, s1: number) => GuaranteedMonotonicity;