curvy 2.0.0-alpha.18 → 2.0.0-alpha.19

package/dist/arc/arc.d.ts

@@ -1,32 +1,44 @@
 import type { Closed } from '../interval/interval.ts';
 import type { Interval2d } from '../interval/interval2d.ts';
 import type { RationalCubicPath2d } from '../path/rationalCubic2d.ts';
-import type { Pipeable } from '../utils.ts';
+import type { Value } from '../utils/value.ts';
 import type { Vector2 } from '../vector/vector2.ts';
-import type { ArcTypeId } from './arc.internal.ts';
 /**
- * A circular arc: the points `center + radius * (cos(a), sin(a))` for `a`
- * running from `startAngle` to `startAngle + sweep`.
+ * An arc described by its geometry rather than its curve coefficients:
+ * `Circular` for a piece of a circle, `Elliptical` for a piece of a
+ * possibly rotated ellipse.
  *
  * An authoring representation, like the spline modules: describe the arc
- * here, query its closed-form geometry (`solve`, `length`, `boundingBox`),
- * and lower it with `toPath` for curve math or `toPathData` for SVG. The
- * description keeps answers the lowered form loses — arc length and
- * point-at-parameter are exact one-liners here and numeric iterations
- * there.
+ * here, query its geometry (`solve`, `length`, `boundingBox`), and lower it
+ * with `toPath` for curve math or `toPathData` for SVG. The description
+ * keeps answers the lowered form loses. Point-at-parameter is one
+ * `cos`/`sin` here and a rational evaluation there, and length is a closed
+ * form or a fixed-cost elliptic integral rather than a tolerance-driven
+ * iteration.
  *
- * Angles are in radians, measured from the `+x` direction, positive
- * rotating `+x` toward `+y` — clockwise in an SVG viewport's y-down
- * coordinates. Direction and multiplicity live in the sweep's sign and
- * magnitude: a negative sweep runs the other way, and a magnitude past
- * `2 * pi` keeps going around the circle.
+ * Every operation in this module accepts both kinds. Angles are in
+ * radians, positive rotating `+x` toward `+y` — clockwise in an SVG
+ * viewport's y-down coordinates. Direction and multiplicity live in the
+ * sweep's sign and magnitude: a negative sweep runs the other way, and a
+ * magnitude past `2 * pi` keeps going around.
  *
  * All fields are readonly. No operation mutates an arc.
  *
  * @since 2.0.0
  */
-export interface Circular extends Pipeable {
-    readonly [ArcTypeId]: ArcTypeId;
+export type Arc = Circular | Elliptical;
+/**
+ * A circular arc: the points `center + radius * (cos(a), sin(a))` for `a`
+ * running from `startAngle` to `startAngle + sweep`.
+ *
+ * Angles are in radians, measured from the `+x` direction, positive
+ * rotating `+x` toward `+y` — clockwise in an SVG viewport's y-down
+ * coordinates.
+ *
+ * @since 2.0.0
+ */
+export interface Circular extends Value.Instance {
+    readonly '~curvy/Arc': '~curvy/Arc';
     readonly kind: 'circular';
     /**
      * The cartesian center of the circle the arc lies on.
@@ -75,6 +87,102 @@ export interface CircularConfig {
      */
     readonly sweep?: number;
 }
+/**
+ * An elliptical arc: the points of an ellipse with semi-axes `radiusX` and
+ * `radiusY`, rotated by `rotation` around `center`, for parametric angles
+ * running from `startAngle` to `startAngle + sweep`.
+ *
+ * The point at parametric angle `a` is
+ * `center + R(rotation) * (radiusX * cos(a), radiusY * sin(a))`, where
+ * `R` rotates `+x` toward `+y`. This is SVG's own arc parametrization.
+ *
+ * The parametric angle is not the direction from the center to the
+ * point. It is the angle on the circle that the radii stretch into the
+ * ellipse, so the two agree only on the axes, or everywhere when the radii
+ * are equal. Equal steps in it also cover unequal distances along the
+ * curve, unlike a circle's.
+ *
+ * @since 2.0.0
+ */
+export interface Elliptical extends Value.Instance {
+    readonly '~curvy/Arc': '~curvy/Arc';
+    readonly kind: 'elliptical';
+    /**
+     * The cartesian center of the ellipse the arc lies on.
+     */
+    readonly center: Vector2;
+    /**
+     * The semi-axis along the ellipse's own x axis, before rotation.
+     * Non-negative. `0` flattens the ellipse to a segment along its y axis.
+     */
+    readonly radiusX: number;
+    /**
+     * The semi-axis along the ellipse's own y axis, before rotation.
+     * Non-negative. `0` flattens the ellipse to a segment along its x axis.
+     */
+    readonly radiusY: number;
+    /**
+     * The angle from the `+x` direction to the ellipse's own x axis, in
+     * radians, positive rotating `+x` toward `+y`.
+     */
+    readonly rotation: number;
+    /**
+     * The parametric angle where the arc starts, in radians. `0` is the end
+     * of the ellipse's own x axis.
+     */
+    readonly startAngle: number;
+    /**
+     * The signed parametric extent, in radians. Positive runs `+x` toward
+     * `+y` in the ellipse's own frame. A magnitude past `2 * pi` traces the
+     * ellipse more than once.
+     */
+    readonly sweep: number;
+}
+/**
+ * Configuration for `elliptical`. Only the two radii are required. The
+ * defaults give a full, unrotated ellipse around the origin.
+ *
+ * @since 2.0.0
+ */
+export interface EllipticalConfig {
+    /**
+     * The cartesian center of the ellipse. Defaults to the origin.
+     */
+    readonly center?: Vector2;
+    /**
+     * The semi-axis along the ellipse's own x axis. Must be finite and
+     * non-negative.
+     */
+    readonly radiusX: number;
+    /**
+     * The semi-axis along the ellipse's own y axis. Must be finite and
+     * non-negative.
+     */
+    readonly radiusY: number;
+    /**
+     * The angle from `+x` to the ellipse's own x axis, in radians. Defaults
+     * to `0`, an axis-aligned ellipse.
+     */
+    readonly rotation?: number;
+    /**
+     * The parametric angle where the arc starts, in radians. Defaults to
+     * `0`, the end of the ellipse's own x axis.
+     */
+    readonly startAngle?: number;
+    /**
+     * The signed parametric extent, in radians. Defaults to `2 * pi`, the
+     * whole ellipse.
+     */
+    readonly sweep?: number;
+}
+/**
+ * Checks if a value is an `Arc` of either kind.
+ *
+ * @param v - The value to check.
+ * @returns `true` if the value is an `Arc`, `false` otherwise.
+ * @since 2.0.0
+ */
+export declare const isArc: (v: unknown) => v is Arc;
 /**
  * Checks if a value is a `Circular` arc.
  *
@@ -102,41 +210,78 @@ export declare const isCircular: (v: unknown) => v is Circular;
  * ```
  */
 export declare const circular: (config: CircularConfig) => Circular;
+/**
+ * Checks if a value is an `Elliptical` arc.
+ *
+ * @param v - The value to check.
+ * @returns `true` if the value is an `Elliptical` arc, `false` otherwise.
+ * @since 2.0.0
+ */
+export declare const isElliptical: (v: unknown) => v is Elliptical;
+/**
+ * Creates an `Elliptical` arc.
+ *
+ * Equal radii give an ellipse that is geometrically a circle, but the
+ * value stays `Elliptical`. Build a `Circular` arc with `circular` to get
+ * its closed-form length.
+ *
+ * @param config - Center, radii, rotation, start angle, and sweep. Only
+ *   `radiusX` and `radiusY` are required. See `EllipticalConfig` for the
+ *   defaults.
+ * @returns A new `Elliptical` arc.
+ * @throws `Error` when either radius is negative, or when a radius,
+ *   `rotation`, `startAngle`, or `sweep` is not finite.
+ * @since 2.0.0
+ * @example
+ * ```ts
+ * // The ellipse inscribed in a 200 x 100 box at the origin:
+ * const oval = Arc.elliptical({
+ *   center: Vector2.make(100, 50),
+ *   radiusX: 100,
+ *   radiusY: 50,
+ * })
+ *
+ * // Its lower half, from 3 o'clock through 6 o'clock to 9 o'clock:
+ * const lower = Arc.elliptical({ radiusX: 100, radiusY: 50, sweep: Math.PI })
+ * ```
+ */
+export declare const elliptical: (config: EllipticalConfig) => Elliptical;
 export declare const equals: {
     /**
-     * Checks two `Circular` arcs for equality, field by field. Numeric
-     * fields compare within the tolerance of `coincident` from
-     * `curvy/number`.
+     * Checks two arcs for equality, field by field. Numeric fields compare
+     * within the tolerance of `coincident` from `curvy/number`.
      *
-     * Comparison is structural, not geometric: two arcs tracing the same
-     * points from different descriptions — a start angle shifted by
-     * `2 * pi`, or the reverse direction — compare unequal.
+     * Comparison is structural, not geometric. Arcs of different kinds
+     * always compare unequal, even an `Elliptical` arc with equal radii
+     * against the `Circular` arc it traces. So do two arcs tracing the same
+     * points from different descriptions, like a start angle shifted by
+     * `2 * pi` or the reverse direction.
      *
      * @param a - The first arc.
      * @param b - The second arc.
      * @returns `true` if the arcs are equal, `false` otherwise.
      * @since 2.0.0
      */
-    (a: Circular, b: Circular): boolean;
+    (a: Arc, b: Arc): boolean;
     /**
-     * Checks two `Circular` arcs for equality.
+     * Checks two arcs for equality, field by field.
      *
      * @param b - The arc to compare against.
      * @returns A function that takes an arc and returns whether the two are
      *   equal.
      * @since 2.0.0
      */
-    (b: Circular): (a: Circular) => boolean;
+    (b: Arc): (a: Arc) => boolean;
 };
 /**
- * Computes the point where the arc starts,
- * `center + radius * (cos(startAngle), sin(startAngle))`.
+ * Computes the point where the arc starts, at angle `startAngle`. For a
+ * circular arc that is `center + radius * (cos(startAngle), sin(startAngle))`.
  *
  * @param a - The arc.
  * @returns The arc's first point.
  * @since 2.0.0
  */
-export declare const startPoint: (a: Circular) => Vector2;
+export declare const startPoint: (a: Arc) => Vector2;
 /**
  * Computes the point where the arc ends, evaluated at
  * `startAngle + sweep`.
@@ -149,16 +294,19 @@ export declare const startPoint: (a: Circular) => Vector2;
  * @returns The arc's last point.
  * @since 2.0.0
  */
-export declare const endPoint: (a: Circular) => Vector2;
+export declare const endPoint: (a: Arc) => Vector2;
 export declare const solve: {
     /**
      * Evaluates the arc at parameter `t`, the point at angle
      * `startAngle + t * sweep`.
      *
-     * The uniform parameter is also the arc-length parameter: equal steps
-     * in `t` cover equal distance along the arc, a property polynomial
-     * curves lack. `t` is not clamped — values outside `[0, 1]` continue
-     * around the circle.
+     * On a circular arc the uniform parameter is also the arc-length
+     * parameter. Equal steps in `t` cover equal distance along the arc, a
+     * property polynomial curves lack. An elliptical arc's angle is
+     * parametric, so equal steps cover more distance near the ends of the
+     * longer axis.
+     *
+     * `t` is not clamped. Values outside `[0, 1]` continue around the curve.
      *
      * @param a - The arc to evaluate.
      * @param t - The parameter. `0` is the start of the arc, `1` the end.
@@ -169,62 +317,83 @@ export declare const solve: {
      * // The midpoint of a quarter arc sits at 45 degrees:
      * Arc.solve(Arc.circular({ radius: 1, sweep: Math.PI / 2 }), 0.5)
      * // (cos(pi / 4), sin(pi / 4))
+     *
+     * // On an ellipse the same parameter lands at (100 * cos(pi / 4), 50 * sin(pi / 4)),
+     * // which lies at about 26.6 degrees from the center, not 45:
+     * Arc.solve(Arc.elliptical({ radiusX: 100, radiusY: 50, sweep: Math.PI / 2 }), 0.5)
      * ```
      */
-    (a: Circular, t: number): Vector2;
+    (a: Arc, t: number): Vector2;
     /**
-     * Evaluates the arc at parameter `t`.
+     * Evaluates the arc at parameter `t`, the point at angle
+     * `startAngle + t * sweep`.
      *
      * @param t - The parameter. `0` is the start of the arc, `1` the end.
      * @returns A function that takes an arc and returns the point at `t`.
      * @since 2.0.0
      */
-    (t: number): (a: Circular) => Vector2;
+    (t: number): (a: Arc) => Vector2;
 };
 /**
- * Computes the arc's length, `radius * abs(sweep)`. Exact, in closed form
- * — no tolerance parameter and no iteration, unlike arc length on a
- * lowered path. A sweep past one full turn counts every traversal.
+ * Computes the arc's length. A sweep past one full turn counts every
+ * traversal.
+ *
+ * Neither kind takes a tolerance parameter or iterates to one, unlike arc
+ * length on a lowered path:
+ * - circular: `radius * abs(sweep)`, exact in closed form
+ * - elliptical: an incomplete elliptic integral of the second kind,
+ *   evaluated through Carlson's symmetric forms in a fixed number of
+ *   steps. The relative error stays near `1e-15`. Equal radii take the
+ *   closed form, and so does a flat ellipse.
  *
  * @param a - The arc.
  * @returns The length of the arc.
  * @since 2.0.0
+ * @example
+ * ```ts
+ * // The perimeter of a 2:1 ellipse:
+ * Arc.length(Arc.elliptical({ radiusX: 2, radiusY: 1 })) // 9.688448220547677
+ * ```
  */
-export declare const length: (a: Circular) => number;
+export declare const length: (a: Arc) => number;
 /**
- * Reverses the arc's direction: the same points traced the other way.
+ * Reverses the arc's direction, tracing the same points the other way.
  * The start angle moves to the far end and the sweep negates, so
  * `solve(reverse(a), t)` is `solve(a, 1 - t)`.
  *
  * @param a - The arc.
- * @returns A new `Circular` arc tracing the input backward.
+ * @returns A new arc of the same kind, tracing the input backward.
  * @since 2.0.0
  */
-export declare const reverse: (a: Circular) => Circular;
+export declare const reverse: <A extends Arc>(a: A) => A;
 /**
  * Computes the exact axis-aligned bounding box of the arc.
  *
- * Extremes occur only at the endpoints or where the arc crosses an axis
- * direction (a multiple of `pi / 2`), so every side is evaluated in
- * closed form — exact up to IEEE 754 rounding, with no tolerance
- * parameter. Contrast `RationalCubicPath2d.boundingBox`, which is tight
- * only to a tolerance you choose. A zero-radius arc's box collapses to
- * `center`.
+ * Extremes occur only at the endpoints or at the angles where the curve
+ * runs parallel to an axis, and both are known in closed form. Every side
+ * is therefore exact up to IEEE 754 rounding, with no tolerance parameter.
+ * Contrast `RationalCubicPath2d.boundingBox`, which is tight only to a
+ * tolerance you choose. An arc whose radii are all `0` has a box that
+ * collapses to `center`.
  *
  * @param a - The arc.
  * @returns A closed `Interval2d` enclosing exactly the arc's points.
  * @since 2.0.0
  */
-export declare const boundingBox: (a: Circular) => Interval2d<Closed, Closed>;
+export declare const boundingBox: (a: Arc) => Interval2d<Closed, Closed>;
 /**
  * Constructs the arc as a `RationalCubicPath2d`, exact up to IEEE 754
- * rounding — the same construction `CoordinateSystem.arc` uses: rational
- * cubic segments of at most a quarter turn each, uniform in angle, with a
- * sweep past one full turn tracing the circle more than once.
+ * rounding. The path is made of rational cubic segments of at most a
+ * quarter turn each, uniform in angle, and a sweep past one full turn
+ * traces the curve more than once. Circular arcs use the same
+ * construction as `CoordinateSystem.arc`, and elliptical arcs carry it
+ * through the ellipse's stretch and rotation.
  *
- * The path is the form to transform: circles are not closed under affine
- * maps, but rational cubics are, so lower first and apply
- * `RationalCubicPath2d.transform` to the result.
+ * The path is the form to transform, since circles and ellipses are not
+ * closed under every affine map but rational cubics are. Lower first and
+ * apply `RationalCubicPath2d.transform` to the result. It is also the form
+ * `CoordinateSystem.image` takes, to carry an arc drawn in chart space
+ * into a polar system.
  *
  * @param a - The arc.
  * @returns The arc as a `RationalCubicPath2d`.
@@ -242,21 +411,27 @@ export declare const boundingBox: (a: Circular) => Interval2d<Closed, Closed>;
  * )
  * ```
  */
-export declare const toPath: (a: Circular) => RationalCubicPath2d;
+export declare const toPath: (a: Arc) => RationalCubicPath2d;
 /**
  * Emits exact SVG path data for the arc, using `A` commands computed from
  * the arc's description rather than recovered from curve coefficients.
+ * An elliptical arc's commands carry both radii and its rotation in
+ * degrees, which is how SVG draws ellipses natively.
+ *
  * Pieces stay at or under a half turn, so the large-arc flag is always
- * `0`; the sweep flag is `1` for a positive sweep, which renders
+ * `0`. The sweep flag is `1` for a positive sweep, which renders
  * clockwise in an SVG viewport's y-down coordinates.
  *
  * Degenerate contracts:
- * - zero sweep, or radius `0`: an `M` command alone, which renders
+ * - zero sweep, or every radius `0`: an `M` command alone, which renders
  *   nothing
- * - a full-turn sweep: the circle as two half-turn `A` commands, closing
- *   on the exact starting coordinates
- * - a sweep past one full turn: clamped to one circle, where `toPath`
- *   keeps going around — SVG path data cannot express multiple laps
+ * - an elliptical arc with one radius `0`: `L` commands tracing the flat
+ *   ellipse back and forth, since SVG would draw an `A` with a zero radius
+ *   as a single line between its endpoints
+ * - a full-turn sweep: two half-turn `A` commands, closing on the exact
+ *   starting coordinates
+ * - a sweep past one full turn: clamped to one lap, where `toPath` keeps
+ *   going around. SVG path data cannot express multiple laps.
  *
  * @param a - The arc.
  * @returns The SVG path data string.
@@ -274,4 +449,4 @@ export declare const toPath: (a: Circular) => RationalCubicPath2d;
  * )
  * ```
  */
-export declare const toPathData: (a: Circular) => string;
+export declare const toPathData: (a: Arc) => string;

package/dist/arc/index.d.ts

@@ -1,2 +1,3 @@
 import * as ArcNs from './arc.ts';
+export type Arc = ArcNs.Arc;
 export { ArcNs as Arc };

package/dist/arc/index.mjs

@@ -1,12 +1,15 @@
 import { t as __exportAll } from "../shared/chunk-25Hzd3z8.mjs";
-import { _ as toPathData$1, c as equals$1, d as length$1, g as toPath$1, h as startPoint$1, i as circular$1, l as isCircular$1, m as solve$1, p as reverse$1, r as boundingBox$1, s as endPoint$1 } from "../shared/arc.internal-DBLPlj56.mjs";
+import { _ as solve$1, b as toPathData$1, c as endPoint$1, d as isCircular$1, f as isElliptical$1, g as reverse$1, i as circular$1, l as equals$1, m as length$1, r as boundingBox$1, s as elliptical$1, u as isArc$1, v as startPoint$1, y as toPath$1 } from "../shared/arc-D4Q75qss.mjs";
 //#region src/arc/arc.ts
 var arc_exports = /* @__PURE__ */ __exportAll({
 	boundingBox: () => boundingBox,
 	circular: () => circular,
+	elliptical: () => elliptical,
 	endPoint: () => endPoint,
 	equals: () => equals,
+	isArc: () => isArc,
 	isCircular: () => isCircular,
+	isElliptical: () => isElliptical,
 	length: () => length,
 	reverse: () => reverse,
 	solve: () => solve,
@@ -15,6 +18,14 @@ var arc_exports = /* @__PURE__ */ __exportAll({
 	toPathData: () => toPathData
 });
 /**
+* Checks if a value is an `Arc` of either kind.
+*
+* @param v - The value to check.
+* @returns `true` if the value is an `Arc`, `false` otherwise.
+* @since 2.0.0
+*/
+const isArc = isArc$1;
+/**
 * Checks if a value is a `Circular` arc.
 *
 * @param v - The value to check.
@@ -41,10 +52,46 @@ const isCircular = isCircular$1;
 * ```
 */
 const circular = circular$1;
+/**
+* Checks if a value is an `Elliptical` arc.
+*
+* @param v - The value to check.
+* @returns `true` if the value is an `Elliptical` arc, `false` otherwise.
+* @since 2.0.0
+*/
+const isElliptical = isElliptical$1;
+/**
+* Creates an `Elliptical` arc.
+*
+* Equal radii give an ellipse that is geometrically a circle, but the
+* value stays `Elliptical`. Build a `Circular` arc with `circular` to get
+* its closed-form length.
+*
+* @param config - Center, radii, rotation, start angle, and sweep. Only
+*   `radiusX` and `radiusY` are required. See `EllipticalConfig` for the
+*   defaults.
+* @returns A new `Elliptical` arc.
+* @throws `Error` when either radius is negative, or when a radius,
+*   `rotation`, `startAngle`, or `sweep` is not finite.
+* @since 2.0.0
+* @example
+* ```ts
+* // The ellipse inscribed in a 200 x 100 box at the origin:
+* const oval = Arc.elliptical({
+*   center: Vector2.make(100, 50),
+*   radiusX: 100,
+*   radiusY: 50,
+* })
+*
+* // Its lower half, from 3 o'clock through 6 o'clock to 9 o'clock:
+* const lower = Arc.elliptical({ radiusX: 100, radiusY: 50, sweep: Math.PI })
+* ```
+*/
+const elliptical = elliptical$1;
 const equals = equals$1;
 /**
-* Computes the point where the arc starts,
-* `center + radius * (cos(startAngle), sin(startAngle))`.
+* Computes the point where the arc starts, at angle `startAngle`. For a
+* circular arc that is `center + radius * (cos(startAngle), sin(startAngle))`.
 *
 * @param a - The arc.
 * @returns The arc's first point.
@@ -66,34 +113,46 @@ const startPoint = startPoint$1;
 const endPoint = endPoint$1;
 const solve = solve$1;
 /**
-* Computes the arc's length, `radius * abs(sweep)`. Exact, in closed form
-* — no tolerance parameter and no iteration, unlike arc length on a
-* lowered path. A sweep past one full turn counts every traversal.
+* Computes the arc's length. A sweep past one full turn counts every
+* traversal.
+*
+* Neither kind takes a tolerance parameter or iterates to one, unlike arc
+* length on a lowered path:
+* - circular: `radius * abs(sweep)`, exact in closed form
+* - elliptical: an incomplete elliptic integral of the second kind,
+*   evaluated through Carlson's symmetric forms in a fixed number of
+*   steps. The relative error stays near `1e-15`. Equal radii take the
+*   closed form, and so does a flat ellipse.
 *
 * @param a - The arc.
 * @returns The length of the arc.
 * @since 2.0.0
+* @example
+* ```ts
+* // The perimeter of a 2:1 ellipse:
+* Arc.length(Arc.elliptical({ radiusX: 2, radiusY: 1 })) // 9.688448220547677
+* ```
 */
 const length = length$1;
 /**
-* Reverses the arc's direction: the same points traced the other way.
+* Reverses the arc's direction, tracing the same points the other way.
 * The start angle moves to the far end and the sweep negates, so
 * `solve(reverse(a), t)` is `solve(a, 1 - t)`.
 *
 * @param a - The arc.
-* @returns A new `Circular` arc tracing the input backward.
+* @returns A new arc of the same kind, tracing the input backward.
 * @since 2.0.0
 */
 const reverse = reverse$1;
 /**
 * Computes the exact axis-aligned bounding box of the arc.
 *
-* Extremes occur only at the endpoints or where the arc crosses an axis
-* direction (a multiple of `pi / 2`), so every side is evaluated in
-* closed form — exact up to IEEE 754 rounding, with no tolerance
-* parameter. Contrast `RationalCubicPath2d.boundingBox`, which is tight
-* only to a tolerance you choose. A zero-radius arc's box collapses to
-* `center`.
+* Extremes occur only at the endpoints or at the angles where the curve
+* runs parallel to an axis, and both are known in closed form. Every side
+* is therefore exact up to IEEE 754 rounding, with no tolerance parameter.
+* Contrast `RationalCubicPath2d.boundingBox`, which is tight only to a
+* tolerance you choose. An arc whose radii are all `0` has a box that
+* collapses to `center`.
 *
 * @param a - The arc.
 * @returns A closed `Interval2d` enclosing exactly the arc's points.
@@ -102,13 +161,17 @@ const reverse = reverse$1;
 const boundingBox = boundingBox$1;
 /**
 * Constructs the arc as a `RationalCubicPath2d`, exact up to IEEE 754
-* rounding — the same construction `CoordinateSystem.arc` uses: rational
-* cubic segments of at most a quarter turn each, uniform in angle, with a
-* sweep past one full turn tracing the circle more than once.
+* rounding. The path is made of rational cubic segments of at most a
+* quarter turn each, uniform in angle, and a sweep past one full turn
+* traces the curve more than once. Circular arcs use the same
+* construction as `CoordinateSystem.arc`, and elliptical arcs carry it
+* through the ellipse's stretch and rotation.
 *
-* The path is the form to transform: circles are not closed under affine
-* maps, but rational cubics are, so lower first and apply
-* `RationalCubicPath2d.transform` to the result.
+* The path is the form to transform, since circles and ellipses are not
+* closed under every affine map but rational cubics are. Lower first and
+* apply `RationalCubicPath2d.transform` to the result. It is also the form
+* `CoordinateSystem.image` takes, to carry an arc drawn in chart space
+* into a polar system.
 *
 * @param a - The arc.
 * @returns The arc as a `RationalCubicPath2d`.
@@ -130,17 +193,23 @@ const toPath = toPath$1;
 /**
 * Emits exact SVG path data for the arc, using `A` commands computed from
 * the arc's description rather than recovered from curve coefficients.
+* An elliptical arc's commands carry both radii and its rotation in
+* degrees, which is how SVG draws ellipses natively.
+*
 * Pieces stay at or under a half turn, so the large-arc flag is always
-* `0`; the sweep flag is `1` for a positive sweep, which renders
+* `0`. The sweep flag is `1` for a positive sweep, which renders
 * clockwise in an SVG viewport's y-down coordinates.
 *
 * Degenerate contracts:
-* - zero sweep, or radius `0`: an `M` command alone, which renders
+* - zero sweep, or every radius `0`: an `M` command alone, which renders
 *   nothing
-* - a full-turn sweep: the circle as two half-turn `A` commands, closing
-*   on the exact starting coordinates
-* - a sweep past one full turn: clamped to one circle, where `toPath`
-*   keeps going around — SVG path data cannot express multiple laps
+* - an elliptical arc with one radius `0`: `L` commands tracing the flat
+*   ellipse back and forth, since SVG would draw an `A` with a zero radius
+*   as a single line between its endpoints
+* - a full-turn sweep: two half-turn `A` commands, closing on the exact
+*   starting coordinates
+* - a sweep past one full turn: clamped to one lap, where `toPath` keeps
+*   going around. SVG path data cannot express multiple laps.
 *
 * @param a - The arc.
 * @returns The SVG path data string.