@weasel-js/geom 1.6.1 → 1.7.1

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+import { a as PolygonPath, b as PathFillRule, R as RectPath, P as Path } from './path-D0CoudGM.js';
+import { P as Point } from './cubicMath-CpCvuEl8.js';
+export { c as cubicPointAt, f as fitCubicThroughDeletion, s as splitCubicAtT } from './cubicMath-CpCvuEl8.js';
 export { P as PORT_REACH } from './portCurve-BBr7eHAL.js';
 
 /**
@@ -34,6 +37,7 @@ declare function sign(n: number): -1 | 0 | 1;
  */
 declare function approxEq(a: number, b: number, eps?: number): boolean;
 
+/** `[a, b, c, d, e, f]`: `x' = a·x + c·y + e`, `y' = b·x + d·y + f`. */
 type Mat3 = readonly [number, number, number, number, number, number];
 /** The transform that leaves a point where it is. */
 declare function identity(): Mat3;
@@ -73,6 +77,9 @@ declare function boundsOfCoords(coords: ArrayLike<number>): Box | null;
 declare function unionBox(a: Box, b: Box): Box;
 /** Inclusive point-in-box test. */
 declare function boxContainsPoint(b: Box, x: number, y: number): boolean;
+/** Whether `outer` wholly holds `inner`, edges inclusive. Two boxes that merely
+ *  overlap answer false. */
+declare function boxContainsBox(outer: Box, inner: Box): boolean;
 /** Interleaved corner ring for a rect at (x,y,w,h), wound clockwise from the
  *  origin corner. The closing edge is implicit — the same unclosed shape
  *  `pointInPolygon` takes, and what a repeated first vertex would leave as a
@@ -81,7 +88,7 @@ declare function rectToContour(x: number, y: number, w: number, h: number): Floa
 
 /**
  * SVG-style command-stream encoding — the kit's single declaration of the path
- * opcodes. `Path` in @weasel-js/core wraps this with `kind` + `fillRule`.
+ * opcodes. `Path` (`./path`) wraps this with `kind` + `fillRule`.
  *
  * The codes index a `Uint8Array` command stream whose coords live in a
  * parallel float array, so a code declared anywhere but `PATH_COMMANDS` makes
@@ -121,10 +128,15 @@ declare const PATH_COMMANDS: {
 type PathCommandName = keyof typeof PATH_COMMANDS;
 /** Numeric code of a declared command. */
 type PathCommandCode = (typeof PATH_COMMANDS)[PathCommandName]['code'];
+/** Command code of `M` (moveTo). */
 declare const PATH_M: 0;
+/** Command code of `L` (lineTo). */
 declare const PATH_L: 1;
+/** Command code of `C` (cubic bezier). */
 declare const PATH_C: 2;
+/** Command code of `Q` (quadratic bezier). */
 declare const PATH_Q: 3;
+/** Command code of `Z` (close subpath). */
 declare const PATH_Z: 4;
 /** Float coords consumed by each command, indexed by command code. */
 declare const PATH_CMD_LENGTHS: readonly number[];
@@ -137,6 +149,9 @@ declare function pathCommandCoordCount(cmd: number): number;
  * `false`. The pen advances to the command's last coord pair afterward; `Z`
  * returns it to the subpath's opening `M`, so a command following a `Z`
  * without an intervening `M` starts where SVG says it does.
+ *
+ * A code `PATH_COMMANDS` does not declare throws once the visitor has seen it,
+ * since the walker cannot tell how many coords it consumes.
  */
 declare function forEachSegment(commands: ArrayLike<number>, coords: ArrayLike<number>, visit: (cmd: number, coordIndex: number, penX: number, penY: number, commandIndex: number) => void | boolean): void;
 
@@ -150,6 +165,58 @@ declare function cubicEvalAt(x0: number, y0: number, x1: number, y1: number, x2:
 declare function elevateQuadraticToCubic(q0x: number, q0y: number, cx: number, cy: number, q1x: number, q1y: number): [number, number, number, number];
 /** Tight AABB of a cubic, evaluating only extrema that lie on the curve. */
 declare function cubicBounds(x0: number, y0: number, x1: number, y1: number, x2: number, y2: number, x3: number, y3: number): Box;
+/** Quadratic Bezier point at parameter t (Bernstein form). */
+declare function quadraticEvalAt(x0: number, y0: number, x1: number, y1: number, x2: number, y2: number, t: number): [number, number];
+/** A line segment's coords: start, end. */
+type LineCoords = [number, number, number, number];
+/** A quadratic Bezier's coords: start, control, end. */
+type QuadraticCoords = [number, number, number, number, number, number];
+/** A cubic Bezier's coords: start, two controls, end. */
+type CubicCoords = [number, number, number, number, number, number, number, number];
+/**
+ * Split a cubic at parameter t (de Casteljau). The two halves share the point
+ * at t and together trace the original exactly. A t outside [0, 1] splits the
+ * curve's polynomial extension.
+ */
+declare function splitCubicAt(x0: number, y0: number, x1: number, y1: number, x2: number, y2: number, x3: number, y3: number, t: number): [CubicCoords, CubicCoords];
+/** Split a quadratic at parameter t (de Casteljau). See {@link splitCubicAt}. */
+declare function splitQuadraticAt(x0: number, y0: number, x1: number, y1: number, x2: number, y2: number, t: number): [QuadraticCoords, QuadraticCoords];
+/** Split a line segment at parameter t. See {@link splitCubicAt}. */
+declare function splitLineAt(x0: number, y0: number, x1: number, y1: number, t: number): [LineCoords, LineCoords];
+
+/** The point on one segment nearest a probe. */
+interface CurveNearest {
+    x: number;
+    y: number;
+    /** Curve parameter of the point, in [0, 1]. */
+    t: number;
+    /** Euclidean distance from the probe. */
+    dist: number;
+}
+/** The point on a path nearest a probe, and the command whose segment holds it. */
+interface PathNearest extends CurveNearest {
+    /** Index of the segment's command in the command stream (`L`, `Q`, `C` or `Z`). */
+    commandIndex: number;
+    /** Offset of that command's first coord; for a `Z`, where its coords would begin. */
+    coordIndex: number;
+}
+/** Nearest point on segment (x0,y0)-(x1,y1) to (px,py). */
+declare function nearestOnLine(px: number, py: number, x0: number, y0: number, x1: number, y1: number): CurveNearest;
+/**
+ * Nearest point on the cubic (x0,y0)…(x3,y3) to (px,py). Samples the curve,
+ * then refines every sampled local minimum with bracketed Newton on the
+ * distance derivative, so a loop or cusp cannot capture it in the wrong basin.
+ */
+declare function nearestOnCubic(px: number, py: number, x0: number, y0: number, x1: number, y1: number, x2: number, y2: number, x3: number, y3: number): CurveNearest;
+/** Nearest point on the quadratic (x0,y0)(x1,y1)(x2,y2) to (px,py). */
+declare function nearestOnQuadratic(px: number, py: number, x0: number, y0: number, x1: number, y1: number, x2: number, y2: number): CurveNearest;
+/**
+ * Nearest point on a command-stream path to (px,py), over every `L`, `Q`, `C`
+ * and the closing edge each `Z` draws. The earliest segment wins a tie.
+ * Returns `null` when the path has no segment, and throws on a command code
+ * `PATH_COMMANDS` does not declare.
+ */
+declare function nearestOnPath(commands: ArrayLike<number>, coords: ArrayLike<number>, px: number, py: number): PathNearest | null;
 
 /**
  * The port-curve rule in the 2D kernel's currency: loose scalars, the way
@@ -228,6 +295,379 @@ declare function segmentsCross(ax: number, ay: number, bx: number, by: number, c
 /** Squared distance from (px,py) to segment (ax,ay)-(bx,by), endpoint-clamped. */
 declare function pointSegmentDist2(px: number, py: number, ax: number, ay: number, bx: number, by: number): number;
 
+/**
+ * Fluent builder for `PolygonPath`. Hides the `Uint8Array` / `Float32Array`
+ * encoding behind move/line/curve/close calls and a final `build()`. Use
+ * this to construct paths in tests and demos; production callers that need
+ * to mutate large paths in place should reach for the raw arrays directly.
+ *
+ * Numeric capacity grows by doubling — typical for amortized O(1) push.
+ *
+ * Also exposes `rectPath` / `polygonFromPoints` shortcuts for the common
+ * cases. `rectPath` returns the lighter `RectPath` subtype, not a polygon.
+ */
+
+/** Fluent builder for `PolygonPath`; hides the `Uint8Array`/`Float32Array` encoding behind move/line/curve/close calls. */
+declare class PathBuilder {
+    private cmds;
+    private xs;
+    private fillRule;
+    /** Seed a builder with an existing `PolygonPath`. Useful for extending
+     *  an in-flight path with another segment (e.g. appending a cubic to
+     *  the end of a curve in response to a user action) without hand-
+     *  reaching into the `commands` / `coords` typed arrays.
+     *
+     *  ```ts
+     *  const next = PathBuilder.fromPath(current).curveTo(...).build();
+     *  ```
+     */
+    static fromPath(path: PolygonPath): PathBuilder;
+    setFillRule(rule: PathFillRule): this;
+    moveTo(x: number, y: number): this;
+    lineTo(x: number, y: number): this;
+    /** Cubic bezier to (x, y) with control points (x1, y1) and (x2, y2). */
+    curveTo(x1: number, y1: number, x2: number, y2: number, x: number, y: number): this;
+    /** Quadratic bezier to (x, y) with control point (x1, y1). */
+    quadTo(x1: number, y1: number, x: number, y: number): this;
+    close(): this;
+    build(): PolygonPath;
+}
+/** Construct a `RectPath` (the fast-path subtype). */
+declare function rectPath(x: number, y: number, width: number, height: number): RectPath;
+/** Build an open polyline from a flat list of points — the same geometry as
+ *  {@link polygonFromPoints} without the closing edge. A freehand stroke and a
+ *  measurement line want this; a region wants the closed one. */
+declare function polylineFromPoints(points: readonly {
+    x: number;
+    y: number;
+}[]): PolygonPath | RectPath;
+/** Build a closed polygon from a flat list of points. */
+declare function polygonFromPoints(points: readonly {
+    x: number;
+    y: number;
+}[], opts?: {
+    fillRule?: PathFillRule;
+}): PolygonPath;
+/** Closed ellipse inscribed in `bounds`, as a 4-cubic-Bezier `PolygonPath`.
+ *  Matches the geometry `useEllipseTool`'s overlay paints. */
+declare function ellipsePath(bounds: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}): PolygonPath;
+/** Closed regular n-gon centered at `center`, circumscribed by `radius`.
+ *  `rotation` is in radians; default 0 puts the first vertex on the +x axis. */
+declare function regularPolygonPath(center: {
+    x: number;
+    y: number;
+}, radius: number, sides: number, rotation?: number): PolygonPath;
+/** Closed n-pointed star centered at `center`, alternating `outerRadius` and
+ *  `innerRadius` (default `outerRadius / 2`). `rotation` is in radians. */
+declare function starPath(center: {
+    x: number;
+    y: number;
+}, outerRadius: number, points?: number, innerRadius?: number, rotation?: number): PolygonPath;
+/** Open 2-vertex polyline from `a` to `b` — strokeable, not fillable. */
+declare function linePath(a: {
+    x: number;
+    y: number;
+}, b: {
+    x: number;
+    y: number;
+}): PolygonPath;
+
+/**
+ * AABB bounds of a `Path`. Returned as `RectPath` for direct reuse with the
+ * rect fast path machinery (selection AABB, area-select intersection).
+ *
+ * `RectPath` is its own bounds — O(1). For `PolygonPath`, walk segment by
+ * segment, computing the tight bound per segment:
+ *
+ *   - `M` / `L`: just the endpoint.
+ *   - `Q`: quadratic Bezier — endpoints plus axis-aligned extrema (one
+ *     possible inflection per axis).
+ *   - `C`: cubic Bezier — endpoints plus axis-aligned extrema (up to two
+ *     possible inflections per axis, found via the quadratic formula on
+ *     the derivative).
+ *
+ * Control points are NOT included directly; they're used only to compute
+ * extrema that actually lie on the curve. This avoids the classic "AABB
+ * extends past where the curve visibly reaches" bug for curved paths whose
+ * control points poke outside the visible extent.
+ *
+ * Empty paths (no commands) return a zero-size rect anchored at the
+ * origin — the convention used elsewhere in the kit for missing geometry.
+ */
+
+/** AABB of a `Path`, returned as a `RectPath` for direct reuse with rect-fast-path machinery. */
+declare function boundsOfPath(path: Path): RectPath;
+
+/**
+ * AABB union over a heterogeneous set of `Path` poses. Returns the
+ * envelope as a `RectPath`, or `null` for empty input — analog of
+ * `unionBounds` for the rect-only model.
+ */
+
+/** AABB envelope over a set of `Path` instances; returns `null` for empty input. */
+declare function unionBoundsPath(paths: Iterable<Path>): RectPath | null;
+
+/**
+ * In-place and copy-out path transforms. Translation is the most common —
+ * called every pointermove during a drag — so the polygon variant mutates
+ * the float buffer directly to keep allocation pressure off the GC.
+ *
+ * `scalePathToBounds` is for the resize interaction: given the path's
+ * current AABB and the desired new AABB, scales every coordinate
+ * proportionally.
+ */
+
+/**
+ * Translate a path by (dx, dy). Returns a new instance — the kit's pose
+ * model treats poses as immutable to keep React state-update semantics
+ * predictable. Polygon coords are copied into a fresh `Float32Array`.
+ */
+declare function translatePath(path: Path, dx: number, dy: number): Path;
+/**
+ * Scale a path's coords so its current AABB maps to `target`. Resize
+ * interactions use this to make a polygon follow a corner-handle drag.
+ *
+ * A degenerate source axis (zero width or height) has no ratio to scale by,
+ * so `boxToBox` translates that axis instead — a zero scale is not
+ * invertible and would discard what is left on it.
+ */
+declare function scalePathToBounds(path: Path, target: RectPath): Path;
+
+/** Apply an affine `Mat3` to a path's geometry.
+ *
+ * Axis-aligned maps (no rotation/shear, i.e. `m[1] === 0 && m[2] === 0`) keep a
+ * `RectPath` a rect — the four corners stay axis-aligned, so we transform the
+ * two diagonal corners and normalize negative extent (mirror). Rotation or
+ * shear promotes the rect's four corners to a `PolygonPath`. Polygon paths map
+ * every coord via the kernel's `transformCoords`, preserving the command stream
+ * and `fillRule`. Never mutates the input.
+ *
+ * `Mat3` here is the 6-tuple `number[]` from `@weasel-js/geom` (DOMMatrix order:
+ * `[a, b, c, d, e, f]` where `x' = a·x + c·y + e`, `y' = b·x + d·y + f`),
+ * not the renderer's 9-element `Float32Array`. */
+declare function transformPath(path: Path, m: Mat3): Path;
+
+/**
+ * Translation-only compose/decompose for `Path` poses, the analog of
+ * `composeRectPose` / `decomposeRectPose` for the rect-only model. Pair
+ * with `composeWorldPose` / `rebaseLocalPose` when an adapter uses `Path`
+ * as its `TPose`.
+ *
+ * Only translation is folded — the kit's hierarchy contract is
+ * translation-only, same as for rects. Parent rotation/scale would require
+ * a richer compose; that's out of scope here.
+ */
+
+/** Express `child` (in `parent`'s local frame) in the next frame up. */
+declare function composePath(parent: Path, child: Path): Path;
+/** Inverse of `composePath` — undo `parent`'s translation from a world pose. */
+declare function decomposePath(parent: Path, world: Path): Path;
+
+/**
+ * Split a `PolygonPath` at each `M` command, returning one `PolygonPath` per
+ * subpath. Inverse-ish of compound-path construction: a multi-region
+ * (compound) path becomes N independent paths.
+ *
+ * `fillRule` is propagated unchanged to every output. Even-odd compound paths
+ * with interior "holes" lose the hole semantics — each subpath becomes its
+ * own filled region. (Same behavior as Illustrator's Release Compound Path.)
+ *
+ * If the input has zero `M` commands (which would already be malformed) the
+ * input is returned wrapped in a single-element array. A path with exactly
+ * one subpath is also returned as a single-element array — a trivial pass.
+ */
+
+/** Split a path into one path per subpath, cutting at each `M`. A path with a
+ *  single subpath comes back as a one-element array. */
+declare function splitSubpaths(path: PolygonPath): PolygonPath[];
+
+/**
+ * Contour orientation: which way a path winds, and the same path wound the
+ * other way. Under `'nonzero'` two overlapping contours fill their overlap
+ * only when they wind the same way, so composing shapes from different
+ * sources into one compound path first needs them to agree.
+ */
+
+/**
+ * Signed area enclosed by `path`, summed over its contours. Positive for a
+ * contour that turns clockwise on a y-down screen (the shoelace sign), so a
+ * hole wound against its outer contour subtracts. An open contour counts as
+ * closed by a straight edge back to its start, the way a fill closes it.
+ * Curved segments are integrated exactly, not through their control polygon.
+ * A `RectPath` has no direction and counts as positive.
+ */
+declare function pathSignedArea(path: Path): number;
+/**
+ * `path` with every contour traversed backwards: same region, same curves,
+ * opposite winding. A closed contour keeps its starting point; an open one
+ * starts from where it used to end.
+ */
+declare function reversePath(path: PolygonPath): PolygonPath;
+
+/**
+ * `pathFromD` — build a weasel `Path` from an **SVG path-data string** (the
+ * value of SVG's `d` attribute, e.g. `"M0 0 L100 0 Z"`).
+ *
+ * This is the terse, declarative composition surface for geometry: a
+ * consumer authors a shape as `d` and hands it straight to a scene/op API,
+ * instead of chaining imperative builder calls. SVG `d` is deliberately the
+ * language — it's a standard every consumer already knows, so the kit gets
+ * path-language expressiveness without minting a new one. See
+ * `docs/conventions.md` ("Compose scenes in a terse path language").
+ *
+ * Lowers every supported command (M/m L/l H/h V/v C/c S/s Q/q T/t A/a Z/z)
+ * into weasel's `PathBuilder` primitives (move, line, cubic, quadratic,
+ * close). Smooth (`S`/`s`/`T`/`t`) commands resolve their implicit reflected
+ * control point from the previous cubic / quadratic. Arc commands (`A`/`a`)
+ * convert to a series of cubic Bezier curves using the standard
+ * endpoint-parameterization formulas (F.6.5 in the SVG spec): we reconstruct
+ * the center, sweep angle, and a fixed number of (≤ 90°) cubic segments per
+ * arc.
+ *
+ * No runtime dependency — a small hand-rolled parser. `@weasel-js/svg`'s
+ * document parser (`parseSvg`) calls this for `<path d=…>` elements, so the
+ * `d` grammar coverage is shared between the two entry points.
+ */
+
+/**
+ * Build a weasel `PolygonPath` from an SVG path-data (`d`) string. Unknown
+ * command letters are skipped (and reported via `onWarn` when provided); the
+ * builder still returns whatever valid commands preceded them.
+ */
+declare function pathFromD(d: string, onWarn?: (message: string) => void): ReturnType<PathBuilder['build']>;
+
+/**
+ * A station along a path: where it is at a fraction of its length, and which
+ * way it is heading there.
+ *
+ * For anything positioned *along* geometry rather than beside it — a label on a
+ * routed edge, a tick on a curve, a badge near an arrowhead. Curves are
+ * flattened first, so the fraction is arc length along the drawn shape rather
+ * than a curve parameter, which is what makes 0.5 look like the middle.
+ */
+
+/** The answer `pointAlongPath` gives: a point on the path and its heading there. */
+interface PathStation {
+    point: Point;
+    /** Unit vector along the path at `point`, pointing toward the end. */
+    tangent: Point;
+}
+/** Options for `pointAlongPath`. */
+interface PointAlongPathOptions {
+    /** Curve flattening tolerance, in world units. Default 0.5. */
+    flattenTolerance?: number;
+}
+/**
+ * Where `path` is at `t` of its total length, and its heading there.
+ *
+ * `t` is clamped to 0..1. Subpaths are measured in order and treated as one
+ * run, the way a browser measures a whole `<path>`. Returns `null` for a path
+ * with no points at all; a path of zero length answers at its single point,
+ * heading along +X.
+ */
+declare function pointAlongPath(path: Path, t: number, opts?: PointAlongPathOptions): PathStation | null;
+
+/**
+ * Pure-geometry distance from a point to a path's boundary (stroke), with
+ * no fill-side logic. Used by pickers that want to know "how close is this
+ * click to the visible edge of the shape?" Callers combine this with
+ * `pathContainsPoint` from `pathHitTest.ts` to get a closed-region
+ * pick distance (0 inside, stroke-distance outside).
+ *
+ * A polygon path defers to geom's `nearestOnPath`; a RectPath short-circuits
+ * to AABB-perimeter math.
+ */
+
+/** Closest Euclidean distance from (px, py) to the boundary of `path`.
+ *  Pure stroke distance — does *not* consult fill rule or interior. For
+ *  closed-region pick distance ("0 inside, stroke-distance outside"),
+ *  combine with `pathContainsPoint` at the call site. */
+declare function pathDistanceToPoint(path: Path, px: number, py: number): number;
+
+/**
+ * Schneider (1990, Graphics Gems I) adaptive cubic-Bezier fitter.
+ * Given a sequence of sample points, returns a `PolygonPath` whose `C`
+ * segments approximate the samples within `errorTolerance` world units.
+ *
+ * Output shape: an initial `M` to the first sample, followed by N
+ * `C` cubic segments. For colinear / two-point inputs, returns a single
+ * degenerate cubic. For empty input, returns an empty polygon path.
+ */
+declare function schneiderFit(samples: ReadonlyArray<Point>, errorTolerance: number): PolygonPath;
+
+/**
+ * Path hit-testing: path-vs-point (filled region and stroke distance),
+ * path-vs-rect, and path-vs-polygon in both directions.
+ *
+ * A `rect` path short-circuits to AABB arithmetic. A `polygon` path is its
+ * filled region: beziers are flattened, `fillRule` is honored (default
+ * `nonzero`), and every closed subpath counts — the hole of a donut is not
+ * part of the shape under `evenodd`. Open subpaths enclose no area, so the
+ * filled-region tests ignore them.
+ */
+
+type XY = {
+    x: number;
+    y: number;
+};
+/** Options for the path hit-tests. */
+interface PointInPathOptions {
+    /** Bezier flattening tolerance in world units. Default 0.5. */
+    tolerance?: number;
+}
+/** Options for {@link strokeHitTest}. */
+interface StrokeHitTestOptions {
+    /** Bezier flattening tolerance in world units. Default 0.5. */
+    tolerance?: number;
+    /** Extra reach past the band measured in screen pixels rather than world
+     *  units: `px` pixels, after `transform` carries the path's frame to the
+     *  screen (only its linear part matters). A pointer's forgiveness is a
+     *  screen distance, and under a non-uniform or rotated-then-squished
+     *  transform no world distance equals it. */
+    slop?: {
+        px: number;
+        transform: Mat3;
+    };
+}
+/** Filled-region hit-test for a path. Rect short-circuits to AABB; polygons run ray-cast / winding per `fillRule`. */
+declare function pointInPath(path: Path, x: number, y: number, opts?: PointInPathOptions): boolean;
+/**
+ * Stroke-distance hit-test. True when (x, y) lies within `threshold` world
+ * units of the path's outline — when a stroke of total width `2 * threshold`
+ * drawn along the path would cover the point. Works for open and closed
+ * subpaths alike; OR it with {@link pointInPath} for fill-plus-stroke picking.
+ * Every flattened segment is treated as a capsule of radius `threshold`.
+ */
+declare function strokeHitTest(path: Path, x: number, y: number, threshold: number, opts?: StrokeHitTestOptions): boolean;
+/** Returns true if (x, y) lies within the filled region of `path`. */
+declare function pathContainsPoint(path: Path, x: number, y: number, opts?: PointInPathOptions): boolean;
+/** Returns true if `rect` is entirely contained within `path`. */
+declare function pathContainsRect(path: Path, rect: Rect, opts?: PointInPathOptions): boolean;
+/** Returns true if `rect` overlaps (intersects or contains) `path`. */
+declare function pathIntersectsRect(path: Path, rect: Rect, opts?: PointInPathOptions): boolean;
+/** Returns true if every vertex of `polygon` lies inside `path`. */
+declare function pathContainsPolygon(path: Path, polygon: readonly XY[], opts?: PointInPathOptions): boolean;
+/** Returns true if `polygon` overlaps (intersects or is contained by) `path`. */
+declare function pathIntersectsPolygon(path: Path, polygon: readonly XY[], opts?: PointInPathOptions): boolean;
+/**
+ * Returns true if all of `path` — every subpath, open ones included, beziers
+ * flattened — lies inside the closed `polygon`: the inverse of
+ * {@link pathContainsPolygon}. A lasso enclosing a shape asks this.
+ */
+declare function polygonContainsPath(polygon: readonly XY[], path: Path, opts?: PointInPathOptions): boolean;
+/**
+ * Returns true if any of `path` meets the closed `polygon`: its filled region,
+ * or the line of an open subpath, which encloses nothing. Beziers are
+ * flattened, so a control point off the curve never counts. The companion of
+ * {@link polygonContainsPath}; a lasso touching a shape asks this.
+ */
+declare function polygonIntersectsPath(polygon: readonly XY[], path: Path, opts?: PointInPathOptions): boolean;
+
 /**
  * Apply an affine to an interleaved coord stream, returning a fresh f64
  * buffer. Command codes are unaffected — for a Bezier the transformed control
@@ -273,6 +713,158 @@ interface PlacedRect {
  * size. A rect too big to fit pins to the boundary's leading edge.
  */
 declare function clampRectWithin(rect: Rect, boundary: Rect, padding?: number): Rect;
+/**
+ * Position an overlay beside `anchor` at the requested placement. With `flip`,
+ * a side that overflows the boundary is swapped for the opposite one when that
+ * fits. The result then slides along the alignment axis to stay inside the
+ * boundary; along the side axis it is left where it is, even if it overflows.
+ */
 declare function placeRect(options: PlaceRectOptions): PlacedRect;
 
-export { type Box, DEFAULT_FLATTEN_TOLERANCE, EPS, type Mat3, PATH_C, PATH_CMD_LENGTHS, PATH_COMMANDS, PATH_L, PATH_M, PATH_Q, PATH_Z, type PathCommandCode, type PathCommandName, type PlaceRectOptions, type PlacedRect, type Placement, type PlacementAlign, type PlacementSide, type Rect, applyToPoint, approxEq, boundsOfCoords, boxContainsPoint, boxToBox, clampRectWithin, cross, cubicBounds, cubicEvalAt, dot, elevateQuadraticToCubic, flattenCubic, flattenCubicWithArcLen, flattenQuadratic, flattenQuadraticWithArcLen, forEachSegment, identity, invert, len2, multiply, pathCommandCoordCount, placeRect, pointInPolygon, pointSegmentDist2, portControls, portCurvePoints, rectToContour, rotate, rotateAboutPoint, scale, segmentsCross, sign, sub, transformCoords, translate, unionBox };
+/** An easing curve: maps normalized progress `t ∈ [0, 1]` to eased progress.
+ *  Curves may leave the 0–1 range in the middle (back, elastic) but should
+ *  pass through 0 at 0 and 1 at 1. */
+type EasingFn = (t: number) => number;
+/** A spring's physical parameters. Higher stiffness settles faster, higher
+ *  damping overshoots less, higher mass makes both sluggish. */
+interface SpringPreset {
+    stiffness: number;
+    damping: number;
+    mass: number;
+}
+/** One of the tunings in `SPRING_PRESETS`. */
+type SpringPresetName = 'gentle' | 'wobbly' | 'stiff' | 'slow';
+/** No easing: constant rate from start to finish. */
+declare const linear: EasingFn;
+/** Accelerates from a standstill, gently. */
+declare const easeInQuad: EasingFn;
+/** Decelerates to a stop, gently. The safe default for UI motion. */
+declare const easeOutQuad: EasingFn;
+/** Accelerates then decelerates, gently. */
+declare const easeInOutQuad: EasingFn;
+/** Accelerates from a standstill, moderately. */
+declare const easeInCubic: EasingFn;
+/** Decelerates to a stop, moderately. */
+declare const easeOutCubic: EasingFn;
+/** Accelerates then decelerates, moderately. */
+declare const easeInOutCubic: EasingFn;
+/** Accelerates from a standstill, sharply. */
+declare const easeInQuart: EasingFn;
+/** Decelerates to a stop, sharply. */
+declare const easeOutQuart: EasingFn;
+/** Accelerates then decelerates, sharply. */
+declare const easeInOutQuart: EasingFn;
+/** Accelerates from a standstill, very sharply. */
+declare const easeInQuint: EasingFn;
+/** Decelerates to a stop, very sharply. */
+declare const easeOutQuint: EasingFn;
+/** Accelerates then decelerates, very sharply. */
+declare const easeInOutQuint: EasingFn;
+/** Accelerates from a standstill along a sine curve — the mildest
+ *  acceleration of the built-ins. */
+declare const easeInSine: EasingFn;
+/** Decelerates to a stop along a sine curve — the mildest
+ *  deceleration of the built-ins. */
+declare const easeOutSine: EasingFn;
+/** Accelerates then decelerates along a sine curve. */
+declare const easeInOutSine: EasingFn;
+/** Accelerates exponentially: barely moves at first, then rushes. */
+declare const easeInExpo: EasingFn;
+/** Decelerates exponentially: leaps away, then creeps in. */
+declare const easeOutExpo: EasingFn;
+/** Exponential at both ends — a very fast middle between two
+ *  near-still extremes. */
+declare const easeInOutExpo: EasingFn;
+/** Accelerates along a circular arc: slow start, abrupt arrival. */
+declare const easeInCirc: EasingFn;
+/** Decelerates along a circular arc: abrupt start, slow arrival. */
+declare const easeOutCirc: EasingFn;
+/** Circular arcs at both ends. */
+declare const easeInOutCirc: EasingFn;
+/** Pulls back past the start before moving forward. Overshoots below 0. */
+declare const easeInBack: EasingFn;
+/** Overshoots the target, then settles back onto it. Exceeds 1. */
+declare const easeOutBack: EasingFn;
+/** Overshoots at both ends. Leaves the 0–1 range on each side. */
+declare const easeInOutBack: EasingFn;
+/** Oscillates around the start with growing amplitude, then snaps away. */
+declare const easeInElastic: EasingFn;
+/** Springs past the target and wobbles into it. Exceeds 1. */
+declare const easeOutElastic: EasingFn;
+/** Wobbles at both ends. Leaves the 0–1 range on each side. */
+declare const easeInOutElastic: EasingFn;
+/** Lands on the target and bounces, in hops of decreasing height. */
+declare const easeOutBounce: EasingFn;
+/** Bounces up to the start before departing — `easeOutBounce` reversed. */
+declare const easeInBounce: EasingFn;
+/** Bounces at both ends. */
+declare const easeInOutBounce: EasingFn;
+/** Alias for `easeInQuad`, kept for call sites that predate the
+ *  named-curve library. */
+declare const easeIn: EasingFn;
+/** Alias for `easeOutQuad`, kept for call sites that predate the
+ *  named-curve library. */
+declare const easeOut: EasingFn;
+/** Alias for `easeInOutQuad`, kept for call sites that predate the
+ *  named-curve library. */
+declare const easeInOut: EasingFn;
+/** All easings in one bag — useful for demos / pickers. */
+declare const EASINGS: {
+    readonly linear: EasingFn;
+    readonly easeInQuad: EasingFn;
+    readonly easeOutQuad: EasingFn;
+    readonly easeInOutQuad: EasingFn;
+    readonly easeInCubic: EasingFn;
+    readonly easeOutCubic: EasingFn;
+    readonly easeInOutCubic: EasingFn;
+    readonly easeInQuart: EasingFn;
+    readonly easeOutQuart: EasingFn;
+    readonly easeInOutQuart: EasingFn;
+    readonly easeInQuint: EasingFn;
+    readonly easeOutQuint: EasingFn;
+    readonly easeInOutQuint: EasingFn;
+    readonly easeInSine: EasingFn;
+    readonly easeOutSine: EasingFn;
+    readonly easeInOutSine: EasingFn;
+    readonly easeInExpo: EasingFn;
+    readonly easeOutExpo: EasingFn;
+    readonly easeInOutExpo: EasingFn;
+    readonly easeInCirc: EasingFn;
+    readonly easeOutCirc: EasingFn;
+    readonly easeInOutCirc: EasingFn;
+    readonly easeInBack: EasingFn;
+    readonly easeOutBack: EasingFn;
+    readonly easeInOutBack: EasingFn;
+    readonly easeInElastic: EasingFn;
+    readonly easeOutElastic: EasingFn;
+    readonly easeInOutElastic: EasingFn;
+    readonly easeInBounce: EasingFn;
+    readonly easeOutBounce: EasingFn;
+    readonly easeInOutBounce: EasingFn;
+};
+/** The name of one of the built-in easing curves. */
+type EasingName = keyof typeof EASINGS;
+/** Named spring tunings, from softest to firmest. Springs settle on a target
+ *  rather than running for a fixed duration, so these are an alternative to an
+ *  easing curve, not a modifier on one. */
+declare const SPRING_PRESETS: Record<SpringPresetName, SpringPreset>;
+
+/** Cubic-bezier control points, CSS `cubic-bezier()` order. The curve's two
+ *  endpoints are implicit at (0,0) and (1,1). */
+interface BezierEasing {
+    /** `readonly` so an `as const` preset is assignable; nothing ever writes it. */
+    bezier: readonly [number, number, number, number];
+}
+/** An easing curve as a value: a function, the name of a built-in, or control
+ *  points. Anything an editor has to name, show or serialize must not be a bare
+ *  function, which is why the union exists. */
+type EasingSpec = EasingFn | EasingName | BezierEasing;
+/** Build the easing curve for four cubic-bezier control points. `x1`/`x2` are
+ *  clamped to [0,1] — CSS `cubic-bezier()`'s constraint for a monotone x(t),
+ *  which both `solveForX` root-finders assume. `y1`/`y2` are unclamped: an
+ *  overshoot easing (back, elastic) needs them outside 0..1. */
+declare function cubicBezierEasing(x1: number, y1: number, x2: number, y2: number): EasingFn;
+/** Resolve a spec to the function that shapes progress. `undefined` is linear. */
+declare function resolveEasing(spec?: EasingSpec): EasingFn;
+
+export { type BezierEasing, type Box, type CubicCoords, type CurveNearest, DEFAULT_FLATTEN_TOLERANCE, EASINGS, EPS, type EasingFn, type EasingName, type EasingSpec, type LineCoords, type Mat3, PATH_C, PATH_CMD_LENGTHS, PATH_COMMANDS, PATH_L, PATH_M, PATH_Q, PATH_Z, Path, PathBuilder, type PathCommandCode, type PathCommandName, PathFillRule, type PathNearest, type PathStation, type PlaceRectOptions, type PlacedRect, type Placement, type PlacementAlign, type PlacementSide, Point, type PointAlongPathOptions, type PointInPathOptions, PolygonPath, type QuadraticCoords, type Rect, RectPath, SPRING_PRESETS, type SpringPreset, type SpringPresetName, type StrokeHitTestOptions, applyToPoint, approxEq, boundsOfCoords, boundsOfPath, boxContainsBox, boxContainsPoint, boxToBox, clampRectWithin, composePath, cross, cubicBezierEasing, cubicBounds, cubicEvalAt, decomposePath, dot, easeIn, easeInBack, easeInBounce, easeInCirc, easeInCubic, easeInElastic, easeInExpo, easeInOut, easeInOutBack, easeInOutBounce, easeInOutCirc, easeInOutCubic, easeInOutElastic, easeInOutExpo, easeInOutQuad, easeInOutQuart, easeInOutQuint, easeInOutSine, easeInQuad, easeInQuart, easeInQuint, easeInSine, easeOut, easeOutBack, easeOutBounce, easeOutCirc, easeOutCubic, easeOutElastic, easeOutExpo, easeOutQuad, easeOutQuart, easeOutQuint, easeOutSine, elevateQuadraticToCubic, ellipsePath, flattenCubic, flattenCubicWithArcLen, flattenQuadratic, flattenQuadraticWithArcLen, forEachSegment, identity, invert, len2, linePath, linear, multiply, nearestOnCubic, nearestOnLine, nearestOnPath, nearestOnQuadratic, pathCommandCoordCount, pathContainsPoint, pathContainsPolygon, pathContainsRect, pathDistanceToPoint, pathFromD, pathIntersectsPolygon, pathIntersectsRect, pathSignedArea, placeRect, pointAlongPath, pointInPath, pointInPolygon, pointSegmentDist2, polygonContainsPath, polygonFromPoints, polygonIntersectsPath, polylineFromPoints, portControls, portCurvePoints, quadraticEvalAt, rectPath, rectToContour, regularPolygonPath, resolveEasing, reversePath, rotate, rotateAboutPoint, scale, scalePathToBounds, schneiderFit, segmentsCross, sign, splitCubicAt, splitLineAt, splitQuadraticAt, splitSubpaths, starPath, strokeHitTest, sub, transformCoords, transformPath, translate, translatePath, unionBoundsPath, unionBox };