@bug-on/m3-expressive 1.0.0

package/dist/shapes.d.ts

@@ -0,0 +1,1119 @@
+import { ReactNode, CSSProperties } from 'react';
+
+/**
+ * Corner rounding parameters for polygon vertices.
+ * Ported from androidx.graphics.shapes.CornerRounding.kt
+ *
+ * @see https://m3.material.io/styles/shape/corner-radius-scale
+ */
+/**
+ * Defines how a polygon corner is rounded.
+ *
+ * @example
+ * // Fully rounded corner with radius 16
+ * const rounding: CornerRounding = { radius: 16, smoothing: 0 };
+ *
+ * @example
+ * // Rounded corner with iOS-style squircle smoothing
+ * const smoothRounding: CornerRounding = { radius: 16, smoothing: 0.6 };
+ */
+interface CornerRounding {
+    /**
+     * The radius of the rounding. A value of 0 means no rounding (sharp corner).
+     * @default 0
+     */
+    readonly radius: number;
+    /**
+     * Smoothing factor in [0, 1]. Controls how the rounding curve transitions from
+     * the straight edge to the circular arc (squircle-like effect).
+     * 0 = pure circular arc, 1 = maximum smoothing.
+     * @default 0
+     */
+    readonly smoothing: number;
+}
+/**
+ * Creates a CornerRounding.
+ * @param radius - Rounding radius (default: 0)
+ * @param smoothing - Smoothing factor 0–1 (default: 0)
+ */
+declare function cornerRounding(radius?: number, smoothing?: number): CornerRounding;
+/** No rounding: straight/sharp corners. */
+declare const UNROUNDED: CornerRounding;
+
+/**
+ * Shared utility constants and functions for the MD3 Expressive Shape Engine.
+ * Ported from androidx.graphics.shapes.Utils.kt
+ *
+ * @see https://m3.material.io/styles/shape/overview-principles
+ */
+/** Epsilon for floating-point distance comparisons */
+declare const DISTANCE_EPSILON = 0.0001;
+/** Epsilon for angle comparisons */
+declare const ANGLE_EPSILON = 0.0001;
+/** Pi as a float constant */
+declare const FLOAT_PI: number;
+/**
+ * Calculates the Euclidean distance between two coordinate offsets.
+ * @param dx - Difference in x coordinates
+ * @param dy - Difference in y coordinates
+ * @returns The distance
+ */
+declare function distance(dx: number, dy: number): number;
+/**
+ * Calculates the squared Euclidean distance (cheaper than distance).
+ * @param dx - Difference in x coordinates
+ * @param dy - Difference in y coordinates
+ * @returns The squared distance
+ */
+declare function distanceSquared(dx: number, dy: number): number;
+/**
+ * Converts polar coordinates to Cartesian (x, y).
+ * @param radius - The radial distance
+ * @param angle - The angle in radians
+ * @returns A tuple [x, y]
+ */
+declare function radialToCartesian(radius: number, angle: number): [number, number];
+/**
+ * Returns value modulo divisor, always positive.
+ * @param value - The value
+ * @param divisor - The divisor
+ * @returns Positive modulo result
+ */
+declare function positiveModulo(value: number, divisor: number): number;
+/**
+ * Linearly interpolates between start and stop.
+ * @param start - Start value (at fraction=0)
+ * @param stop - End value (at fraction=1)
+ * @param fraction - Interpolation factor [0,1]
+ * @returns Interpolated value
+ */
+declare function interpolate(start: number, stop: number, fraction: number): number;
+/**
+ * Returns the square of a value.
+ * @param value - The value to square
+ */
+declare function square(value: number): number;
+/**
+ * Returns a unit direction vector from (0,0) toward (dx, dy).
+ * @param dx - X component
+ * @param dy - Y component
+ * @returns [nx, ny] normalized direction
+ */
+declare function directionVector(dx: number, dy: number): [number, number];
+/**
+ * Checks if the turn from prev→curr→next is convex (clockwise in screen coords).
+ * @param prevX - Previous vertex x
+ * @param prevY - Previous vertex y
+ * @param currX - Current vertex x
+ * @param currY - Current vertex y
+ * @param nextX - Next vertex x
+ * @param nextY - Next vertex y
+ * @returns true if convex
+ */
+declare function convex(prevX: number, prevY: number, currX: number, currY: number, nextX: number, nextY: number): boolean;
+/**
+ * Type for a function that transforms a point (x, y) → (x', y').
+ */
+type PointTransformer = (x: number, y: number) => [number, number];
+
+/**
+ * Point type and operations for the MD3 Expressive Shape Engine.
+ * Ported from androidx.graphics.shapes.Point.kt
+ *
+ * In Kotlin, Point is a type alias for FloatFloatPair. Here we use a plain object
+ * for zero-overhead structural typing in TypeScript.
+ */
+
+/** A 2D point or vector. */
+interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * Creates a new Point.
+ * @param x - X coordinate
+ * @param y - Y coordinate
+ */
+declare function point(x: number, y: number): Point;
+/**
+ * Returns the magnitude (distance from origin) of the point.
+ * @param p - The point
+ */
+declare function getDistance(p: Point): number;
+/**
+ * Returns the squared magnitude of the point (cheaper than getDistance).
+ * @param p - The point
+ */
+declare function getDistanceSquared(p: Point): number;
+/**
+ * Dot product of two points (treated as vectors).
+ * @param a - First point
+ * @param b - Second point
+ */
+declare function dotProduct(a: Point, b: Point): number;
+/**
+ * Rotates the point 90 degrees counter-clockwise.
+ * @param p - The point
+ * @returns New rotated point
+ */
+declare function rotate90(p: Point): Point;
+/**
+ * Returns the unit vector in the direction of the point from (0,0).
+ * @param p - The point
+ * @throws Error if the point is at the origin
+ */
+declare function getDirection(p: Point): Point;
+/**
+ * Checks if p0→p1→p2 turn is clockwise (positive cross product in screen coords).
+ * @param p0 - Previous point
+ * @param p1 - Current point
+ * @param p2 - Next point
+ */
+declare function clockwise(p0: Point, p1: Point, p2: Point): boolean;
+/** Point addition. */
+declare function addPoints(a: Point, b: Point): Point;
+/** Point subtraction. */
+declare function subtractPoints(a: Point, b: Point): Point;
+/** Scalar multiplication. */
+declare function scalePoint(p: Point, scalar: number): Point;
+/** Scalar division. */
+declare function dividePoint(p: Point, scalar: number): Point;
+/**
+ * Linearly interpolates between two points.
+ * @param start - Start point (at fraction=0)
+ * @param stop - End point (at fraction=1)
+ * @param fraction - Interpolation factor [0,1]
+ */
+declare function lerpPoint(start: Point, stop: Point, fraction: number): Point;
+/**
+ * Applies a PointTransformer to a point.
+ * @param p - The original point
+ * @param fn - The transform function
+ */
+declare function transformPoint(p: Point, fn: PointTransformer): Point;
+
+/**
+ * Cubic Bézier curve type for the MD3 Expressive Shape Engine.
+ * Ported from androidx.graphics.shapes.Cubic.kt
+ *
+ * A cubic holds 8 floats: [anchor0X, anchor0Y, control0X, control0Y, control1X, control1Y, anchor1X, anchor1Y]
+ */
+
+/**
+ * A single cubic Bézier curve segment.
+ *
+ * The curve goes from anchor0 → (via control0, control1) → anchor1.
+ *
+ * @example
+ * const line = Cubic.straightLine(0, 0, 1, 0);
+ * const arc  = Cubic.circularArc(0, 0, 1, 0, 0, 1);
+ */
+declare class Cubic {
+    /** Internal storage: [a0x, a0y, c0x, c0y, c1x, c1y, a1x, a1y] */
+    readonly points: number[];
+    constructor(points: number[]);
+    /** First anchor point X */
+    get anchor0X(): number;
+    /** First anchor point Y */
+    get anchor0Y(): number;
+    /** First control point X */
+    get control0X(): number;
+    /** First control point Y */
+    get control0Y(): number;
+    /** Second control point X */
+    get control1X(): number;
+    /** Second control point Y */
+    get control1Y(): number;
+    /** Second anchor point X */
+    get anchor1X(): number;
+    /** Second anchor point Y */
+    get anchor1Y(): number;
+    /**
+     * Returns a point on the curve at parameter t (0=start, 1=end).
+     * Uses the standard cubic Bézier formula.
+     * @param t - Parameter in [0, 1]
+     */
+    pointOnCurve(t: number): Point;
+    /**
+     * Returns true if this curve has (near) zero length.
+     */
+    zeroLength(): boolean;
+    /**
+     * Splits this cubic at parameter t, returning two cubics.
+     * Uses De Casteljau's algorithm.
+     * @param t - Split parameter in [0, 1]
+     * @returns [left, right] pair
+     */
+    split(t: number): [Cubic, Cubic];
+    /**
+     * Returns a reversed copy of this cubic (anchor0 ↔ anchor1, controls swapped).
+     */
+    reverse(): Cubic;
+    /**
+     * Calculates the axis-aligned bounding box.
+     * @param approximate - If true, uses control point hull (faster). Default: false.
+     * @returns [minX, minY, maxX, maxY]
+     */
+    calculateBounds(approximate?: boolean): [number, number, number, number];
+    /**
+     * Interpolates between this cubic and another at fraction t.
+     * @param other - Target cubic
+     * @param t - Fraction [0, 1]
+     */
+    interpolateTo(other: Cubic, t: number): Cubic;
+    /**
+     * Applies a PointTransformer to all anchor and control points.
+     * @param fn - The transform function
+     */
+    transformed(fn: PointTransformer): Cubic;
+    toString(): string;
+    /**
+     * Creates a cubic representing a straight line.
+     * Control points lie at 1/3 and 2/3 of the line.
+     * @param x0 - Start anchor X
+     * @param y0 - Start anchor Y
+     * @param x1 - End anchor X
+     * @param y1 - End anchor Y
+     */
+    static straightLine(x0: number, y0: number, x1: number, y1: number): Cubic;
+    /**
+     * Creates a cubic approximating a circular arc.
+     * p0 and p1 must be equidistant from the center.
+     * For arcs > 180°, use multiple cubics.
+     *
+     * @param centerX - Arc center X
+     * @param centerY - Arc center Y
+     * @param x0 - Start point X (on circle)
+     * @param y0 - Start point Y (on circle)
+     * @param x1 - End point X (on circle)
+     * @param y1 - End point Y (on circle)
+     */
+    static circularArc(centerX: number, centerY: number, x0: number, y0: number, x1: number, y1: number): Cubic;
+    /**
+     * Creates a zero-length cubic at the given point.
+     * @param x - X coordinate
+     * @param y - Y coordinate
+     */
+    static empty(x: number, y: number): Cubic;
+}
+/**
+ * A mutable version of Cubic used in performance-critical paths (Morph.forEachCubic).
+ * Reuses the same instance to avoid allocations.
+ */
+declare class MutableCubic extends Cubic {
+    constructor();
+    /**
+     * Mutably interpolates between c1 and c2 at the given progress.
+     * @param c1 - Start cubic
+     * @param c2 - End cubic
+     * @param progress - Interpolation factor [0, 1]
+     */
+    interpolate(c1: Cubic, c2: Cubic, progress: number): void;
+    /**
+     * Mutably applies a PointTransformer to all points.
+     * @param fn - The transform function
+     */
+    transform(fn: PointTransformer): void;
+}
+
+/**
+ * Feature types for the MD3 Expressive Shape Engine.
+ * Ported from androidx.graphics.shapes.Features.kt
+ *
+ * Features describe the outline segments of a RoundedPolygon:
+ * - Corner: a (potentially rounded) vertex
+ * - Edge: a straight or curved segment between two corners
+ */
+
+/**
+ * A discriminated union representing one outline segment of a polygon.
+ *
+ * @example
+ * const corner: Feature = { type: "corner", cubics: [...], convex: true };
+ * const edge: Feature   = { type: "edge",   cubics: [...] };
+ */
+type Feature = CornerFeature | EdgeFeature;
+/** A (potentially rounded) corner vertex. */
+interface CornerFeature {
+    readonly type: "corner";
+    /**
+     * Cubic curves making up this corner.
+     * Unrounded corner = 1 zero-length cubic. Rounded = 1–3 cubics (flanking + arc + flanking).
+     */
+    readonly cubics: Cubic[];
+    /** True if this corner is convex (pointing outward). */
+    readonly convex: boolean;
+}
+/** A straight or curved edge segment between two corners. */
+interface EdgeFeature {
+    readonly type: "edge";
+    /** Cubic curves making up this edge (usually a single straight-line cubic). */
+    readonly cubics: Cubic[];
+}
+/**
+ * Creates a corner feature.
+ * @param cubics - Cubic curves defining the corner shape
+ * @param convex - Whether the corner is convex
+ */
+declare function cornerFeature(cubics: Cubic[], convex: boolean): CornerFeature;
+/**
+ * Creates an edge feature.
+ * @param cubics - Cubic curves defining the edge
+ */
+declare function edgeFeature(cubics: Cubic[]): EdgeFeature;
+/**
+ * Returns a transformed copy of a feature.
+ * @param feature - The feature to transform
+ * @param fn - Point transformer function
+ */
+declare function transformFeature(feature: Feature, fn: PointTransformer): Feature;
+
+/**
+ * RoundedPolygon — core shape class for the MD3 Expressive Shape Engine.
+ * Ported from androidx.graphics.shapes.RoundedPolygon.kt
+ *
+ * A RoundedPolygon is defined by a list of Feature (Corner + Edge) objects.
+ * Its geometry is stored as a flat list of Cubic Bézier curves that form
+ * a closed, contiguous outline.
+ */
+
+/**
+ * The core shape class. Represents a closed polygon outline as a list of Cubic
+ * Bézier curves, optionally rounded at the vertices.
+ *
+ * All shapes in MD3 Expressive are represented as RoundedPolygon instances.
+ *
+ * @example
+ * // Create a circle (8-vertex polygon, fully rounded)
+ * const circle = RoundedPolygon.circle();
+ *
+ * @example
+ * // Create a rounded rectangle
+ * const rect = RoundedPolygon.rectangle(2, 1, { radius: 0.25, smoothing: 0 });
+ */
+declare class RoundedPolygon {
+    /** Flat list of cubic Bézier curves forming the closed outline. */
+    readonly cubics: Cubic[];
+    /** Feature list (corners + edges). */
+    readonly features: Feature[];
+    /** Center point of the polygon. */
+    readonly center: Point;
+    /** @internal Use static factory methods instead */
+    private constructor();
+    get centerX(): number;
+    get centerY(): number;
+    /**
+     * Creates a polygon from a vertex count (regular polygon).
+     * @param numVertices - Number of vertices (≥ 3)
+     * @param radius - Circumradius (default: 1)
+     * @param centerX - Center X (default: 0)
+     * @param centerY - Center Y (default: 0)
+     * @param rounding - Corner rounding for all vertices
+     * @param perVertexRounding - Per-vertex rounding overrides
+     */
+    static fromNumVertices(numVertices: number, radius?: number, centerX?: number, centerY?: number, rounding?: CornerRounding, perVertexRounding?: CornerRounding[]): RoundedPolygon;
+    /**
+     * Creates a polygon from a flat vertex array [x0, y0, x1, y1, ...].
+     * @param vertices - Flat array of x,y pairs (length must be even and ≥ 6)
+     * @param rounding - Corner rounding for all vertices
+     * @param perVertexRounding - Per-vertex rounding overrides
+     * @param centerX - Center X (auto-calculated if not provided)
+     * @param centerY - Center Y (auto-calculated if not provided)
+     */
+    static fromVertices(vertices: number[], rounding?: CornerRounding, perVertexRounding?: CornerRounding[], centerX?: number, centerY?: number): RoundedPolygon;
+    /**
+     * Creates a polygon from a pre-built Feature list.
+     * @param features - Feature list (≥ 2 features)
+     * @param centerX - Center X (auto-calculated if NaN)
+     * @param centerY - Center Y (auto-calculated if NaN)
+     */
+    static fromFeatures(features: Feature[], centerX?: number, centerY?: number): RoundedPolygon;
+    /**
+     * Returns a new RoundedPolygon with all points transformed.
+     * @param fn - Transform function: (x, y) => [x', y']
+     */
+    transformed(fn: PointTransformer): RoundedPolygon;
+    /**
+     * Returns a normalized copy: scaled and centered to fit in [0,1] × [0,1].
+     * Maintains aspect ratio by using the larger dimension.
+     */
+    normalized(): RoundedPolygon;
+    /**
+     * Calculates the axis-aligned bounding box.
+     * @param approximate - If true, uses control point hull (faster). Default: true.
+     * @returns [minX, minY, maxX, maxY]
+     */
+    calculateBounds(approximate?: boolean): [number, number, number, number];
+    /**
+     * Calculates the maximum bounding square (useful for shapes that rotate).
+     * @returns [minX, minY, maxX, maxY] of the max-bounds square
+     */
+    calculateMaxBounds(): [number, number, number, number];
+}
+
+/**
+ * MD3 Expressive Shape Catalog — auto-generated from SVGs.
+ *
+ * Each shape is a pre-normalized RoundedPolygon (fits in [0,1]×[0,1], centered at (0.5, 0.5)).
+ * Regenerated via scratch/generate-shapes.ts.
+ */
+
+declare const MD3Shapes: {
+    readonly arch: RoundedPolygon;
+    readonly arrow: RoundedPolygon;
+    readonly boom: RoundedPolygon;
+    readonly bun: RoundedPolygon;
+    readonly burst: RoundedPolygon;
+    readonly circle: RoundedPolygon;
+    readonly clamshell: RoundedPolygon;
+    readonly diamond: RoundedPolygon;
+    readonly fan: RoundedPolygon;
+    readonly flower: RoundedPolygon;
+    readonly gem: RoundedPolygon;
+    readonly ghostish: RoundedPolygon;
+    readonly heart: RoundedPolygon;
+    readonly clover4Leaf: RoundedPolygon;
+    readonly clover8Leaf: RoundedPolygon;
+    readonly oval: RoundedPolygon;
+    readonly pentagon: RoundedPolygon;
+    readonly pill: RoundedPolygon;
+    readonly pixelCircle: RoundedPolygon;
+    readonly pixelTriangle: RoundedPolygon;
+    readonly puffyDiamond: RoundedPolygon;
+    readonly puffy: RoundedPolygon;
+    readonly semiCircle: RoundedPolygon;
+    readonly cookie12Sided: RoundedPolygon;
+    readonly cookie4Sided: RoundedPolygon;
+    readonly cookie6Sided: RoundedPolygon;
+    readonly cookie7Sided: RoundedPolygon;
+    readonly cookie9Sided: RoundedPolygon;
+    readonly slanted: RoundedPolygon;
+    readonly softBoom: RoundedPolygon;
+    readonly softBurst: RoundedPolygon;
+    readonly square: RoundedPolygon;
+    readonly sunny: RoundedPolygon;
+    readonly triangle: RoundedPolygon;
+    readonly verySunny: RoundedPolygon;
+};
+type MD3ShapeName = keyof typeof MD3Shapes;
+
+/**
+ * MD3 Corner Radius Token Scale.
+ * Ported from MD3 spec: https://m3.material.io/styles/shape/corner-radius-scale
+ *
+ * The Material 3 shape system uses a 10-step size-based scale.
+ * All values are in density-independent pixels (dp).
+ *
+ * @example
+ * import { MD3CornerRadius } from "@bug-on/m3-expressive";
+ *
+ * // Use a token name
+ * const rounding = { radius: MD3CornerRadius.large, smoothing: 0 };
+ *
+ * // Use with ShapeMedia
+ * <ShapeMedia shape="pill" cornerRadius="extraLarge" ... />
+ */
+declare const MD3CornerRadius: {
+    /** 0dp — Sharp corners */
+    readonly none: 0;
+    /** 4dp */
+    readonly extraSmall: 4;
+    /** 8dp */
+    readonly small: 8;
+    /** 12dp */
+    readonly medium: 12;
+    /** 16dp */
+    readonly large: 16;
+    /** 20dp (new in M3 Expressive) */
+    readonly largeIncreased: 20;
+    /** 28dp */
+    readonly extraLarge: 28;
+    /** 32dp (new in M3 Expressive) */
+    readonly extraLargeIncreased: 32;
+    /** 48dp (new in M3 Expressive) */
+    readonly extraExtraLarge: 48;
+    /** 9999dp — Fully rounded (pill/circle) */
+    readonly full: 9999;
+};
+/** Token name for MD3 corner radius scale. */
+type MD3CornerRadiusToken = keyof typeof MD3CornerRadius;
+
+/**
+ * Shape factory functions for the MD3 Expressive Shape Engine.
+ * Ported from androidx.graphics.shapes.Shapes.kt
+ *
+ * These functions create basic geometric shapes as RoundedPolygon instances.
+ * All shapes default to being centered at (0,0) with radius 1.
+ */
+
+/**
+ * Creates a circular shape approximated by a rounded polygon.
+ *
+ * @param numVertices - Number of polygon vertices (≥ 3, default: 8)
+ * @param radius - Circle radius (default: 1)
+ * @param centerX - Center X (default: 0)
+ * @param centerY - Center Y (default: 0)
+ * @returns A RoundedPolygon approximating a circle
+ *
+ * @example
+ * const myCircle = circle(8, 100, 0, 0);
+ */
+declare function circle(numVertices?: number, radius?: number, centerX?: number, centerY?: number): RoundedPolygon;
+/**
+ * Creates a rectangular shape with optional rounding.
+ *
+ * @param width - Rectangle width (default: 2)
+ * @param height - Rectangle height (default: 2)
+ * @param rounding - Corner rounding for all corners (default: none)
+ * @param perVertexRounding - Per-corner rounding overrides (length must be 4)
+ * @param centerX - Center X (default: 0)
+ * @param centerY - Center Y (default: 0)
+ *
+ * @example
+ * // Rounded rectangle
+ * const roundedRect = rectangle(2, 1, { radius: 0.25, smoothing: 0 });
+ */
+declare function rectangle(width?: number, height?: number, rounding?: CornerRounding, perVertexRounding?: CornerRounding[], centerX?: number, centerY?: number): RoundedPolygon;
+/**
+ * Creates a star-shaped polygon with inner and outer radii.
+ *
+ * If innerRadius equals radius, the result is a regular polygon with
+ * 2 × numVerticesPerRadius vertices.
+ *
+ * @param numVerticesPerRadius - Vertices per radius (outer + inner)
+ * @param radius - Outer radius (default: 1)
+ * @param innerRadius - Inner radius (default: 0.5)
+ * @param rounding - Corner rounding for outer vertices (default: none)
+ * @param innerRounding - Corner rounding for inner vertices (default: uses rounding)
+ * @param perVertexRounding - Full per-vertex rounding list
+ * @param centerX - Center X (default: 0)
+ * @param centerY - Center Y (default: 0)
+ *
+ * @example
+ * // 8-pointed star
+ * const star8 = star(8, 1, 0.4);
+ *
+ * @example
+ * // Rounded sunny shape
+ * const sunny = star(8, 1, 0.75, { radius: 0.15, smoothing: 0 }, { radius: 0.05, smoothing: 0 });
+ */
+declare function star(numVerticesPerRadius: number, radius?: number, innerRadius?: number, rounding?: CornerRounding, innerRounding?: CornerRounding, perVertexRounding?: CornerRounding[], centerX?: number, centerY?: number): RoundedPolygon;
+/**
+ * Creates a pill shape: rectangle with fully-rounded short ends.
+ *
+ * @param width - Width of the pill (default: 2)
+ * @param height - Height of the pill (default: 1)
+ * @param smoothing - Corner smoothing factor [0,1] (default: 0)
+ * @param centerX - Center X (default: 0)
+ * @param centerY - Center Y (default: 0)
+ *
+ * @example
+ * const pillShape = pill(3, 1);
+ */
+declare function pill(width?: number, height?: number, smoothing?: number, centerX?: number, centerY?: number): RoundedPolygon;
+/**
+ * Creates a pill-star shape: like a pill but with star-like inner/outer vertices.
+ *
+ * @param width - Width (default: 2)
+ * @param height - Height (default: 1)
+ * @param numVerticesPerRadius - Number of point pairs per radius
+ * @param innerRadiusRatio - Inner radius as fraction of outer (default: 0.5)
+ * @param rounding - Outer vertex rounding (default: none)
+ * @param innerRounding - Inner vertex rounding (default: uses rounding)
+ * @param perVertexRounding - Full per-vertex rounding list
+ * @param vertexSpacing - Spacing factor [0,1] (default: 0.5)
+ * @param centerX - Center X (default: 0)
+ * @param centerY - Center Y (default: 0)
+ */
+declare function pillStar(width?: number, height?: number, numVerticesPerRadius?: number, innerRadiusRatio?: number, rounding?: CornerRounding, innerRounding?: CornerRounding, perVertexRounding?: CornerRounding[], vertexSpacing?: number, centerX?: number, centerY?: number): RoundedPolygon;
+
+/**
+ * DoubleMapper: bidirectional mapper used in the Morph matching algorithm.
+ * Maps progress values from polygon1 space → polygon2 space and vice versa.
+ */
+interface DoubleMapper {
+    /** Maps a progress value from the start polygon to the end polygon. */
+    map(progress: number): number;
+    /** Maps a progress value from the end polygon back to the start polygon. */
+    mapBack(progress: number): number;
+}
+/**
+ * Creates a DoubleMapper from two parallel arrays of mapped progress values.
+ * Used internally by featureMapper.
+ *
+ * @param fromValues - Progress values in polygon1 space [0..1]
+ * @param toValues - Corresponding progress values in polygon2 space [0..1]
+ */
+declare function createDoubleMapper(fromValues: number[], toValues: number[]): DoubleMapper;
+
+/**
+ * Polygon measurement utilities for the Morph engine.
+ * Ported from androidx.graphics.shapes.PolygonMeasure.kt
+ *
+ * Measures the outline of a RoundedPolygon by arc length, normalizing
+ * progress values to [0, 1]. Used by Morph to match curves between polygons.
+ */
+
+/** A Cubic with its start/end outline progress values normalized to [0, 1]. */
+interface MeasuredCubic {
+    readonly cubic: Cubic;
+    readonly startOutlineProgress: number;
+    readonly endOutlineProgress: number;
+}
+/** Feature info extracted from a measured polygon (for featureMapper). */
+interface MeasuredFeature {
+    /** Progress at the midpoint of this feature's central arc */
+    readonly progress: number;
+    /** Whether this corner is convex */
+    readonly convex: boolean;
+}
+/**
+ * A list of MeasuredCubics covering the full outline of a polygon.
+ * Provides methods to cut and shift the polygon at a given progress point.
+ */
+declare class MeasuredPolygon {
+    readonly measuredCubics: MeasuredCubic[];
+    readonly features: MeasuredFeature[];
+    private constructor();
+    get size(): number;
+    getOrNull(index: number): MeasuredCubic | null;
+    /**
+     * Cuts the polygon at cutPoint and rotates so that cutPoint becomes progress=0.
+     * Returns a new MeasuredPolygon with adjusted progress values.
+     * @param cutPoint - Progress value [0, 1] at which to cut
+     */
+    cutAndShift(cutPoint: number): MeasuredPolygon;
+    /**
+     * Cuts a MeasuredCubic at a given outline progress, returning [segment, rest].
+     */
+    cutAtProgress(measuredCubic: MeasuredCubic, progress: number): [MeasuredCubic, MeasuredCubic];
+    /**
+     * Measures a RoundedPolygon's outline by arc length.
+     * Returns a MeasuredPolygon with normalized progress in [0, 1].
+     */
+    static measurePolygon(polygon: RoundedPolygon): MeasuredPolygon;
+}
+
+/**
+ * Feature mapping for the Morph engine.
+ * Ported from androidx.graphics.shapes.FeatureMapping.kt
+ *
+ * Maps corners between two polygons by proximity, enabling the Morph engine
+ * to create smooth transitions between shapes with different vertex counts.
+ */
+
+/**
+ * Creates a DoubleMapper that maps progress values between two polygons
+ * based on matching their convex corners by proximity.
+ *
+ * The algorithm:
+ * 1. Extract convex corner progress values from both polygons
+ * 2. Match each corner in polygon1 to the closest corner of the same type in polygon2
+ * 3. Build a piecewise-linear bidirectional mapper
+ *
+ * @param features1 - Measured features from polygon 1
+ * @param features2 - Measured features from polygon 2
+ * @returns A DoubleMapper for bidirectional progress mapping
+ */
+declare function featureMapper(features1: MeasuredFeature[], features2: MeasuredFeature[]): DoubleMapper;
+
+/**
+ * Morph — animates between two RoundedPolygon shapes.
+ * Ported from androidx.graphics.shapes.Morph.kt
+ *
+ * The Morph class pre-computes a list of matched cubic pairs at construction time.
+ * Animating between shapes is then a simple per-pair linear interpolation.
+ *
+ * @example
+ * const morph = new Morph(MD3Shapes.circle, MD3Shapes.flower);
+ * const cubics = morph.asCubics(0.5); // halfway between circle and flower
+ *
+ * @example
+ * // Zero-allocation iteration (for animation loops)
+ * morph.forEachCubic(progress, (c) => {
+ *   ctx.bezierCurveTo(c.control0X, c.control0Y, c.control1X, c.control1Y, c.anchor1X, c.anchor1Y);
+ * });
+ */
+
+/** A matched pair of cubics (start shape, end shape). */
+type CubicPair = readonly [Cubic, Cubic];
+/**
+ * Animates between two RoundedPolygon shapes.
+ *
+ * At construction time, Morph matches the cubic curves of both shapes using
+ * the featureMapper algorithm. This produces a list of CubicPairs, which can
+ * then be interpolated at any progress value.
+ */
+declare class Morph {
+    private readonly start;
+    private readonly end;
+    /** Pre-computed list of matched cubic pairs. @internal */
+    private readonly morphMatch;
+    /**
+     * Creates a Morph between two shapes.
+     * @param start - Starting shape
+     * @param end - Ending shape
+     */
+    constructor(start: RoundedPolygon, end: RoundedPolygon);
+    /**
+     * Returns the interpolated shape at the given progress as a list of Cubics.
+     *
+     * Note: This allocates a new list. For performance-critical animation loops,
+     * use {@link forEachCubic} instead.
+     *
+     * @param progress - Value in [0, 1]. 0 = start shape, 1 = end shape.
+     *   Values outside [0, 1] produce exaggerated shapes (useful for bounce/overshoot).
+     * @returns List of interpolated Cubic curves forming the morphed shape
+     */
+    asCubics(progress: number): Cubic[];
+    /**
+     * Iterates over the morphed cubics without allocating new Cubic instances.
+     * Reuses a single MutableCubic for each callback invocation.
+     *
+     * @param progress - Value in [0, 1]
+     * @param callback - Called for each interpolated cubic
+     *
+     * @example
+     * const mutable = new MutableCubic();
+     * morph.forEachCubic(progress, mutable, (c) => {
+     *   path.bezierCurveTo(c.control0X, c.control0Y, c.control1X, c.control1Y, c.anchor1X, c.anchor1Y);
+     * });
+     */
+    forEachCubic(progress: number, mutableOrCallback: MutableCubic | ((c: MutableCubic) => void), callback?: (c: MutableCubic) => void): void;
+    /**
+     * Calculates the axis-aligned bounding box of the morph (union of start + end bounds).
+     * @param approximate - Use faster approximate bounds (default: true)
+     */
+    calculateBounds(approximate?: boolean): [number, number, number, number];
+    /**
+     * Calculates the max bounding square (union of start + end max bounds).
+     */
+    calculateMaxBounds(): [number, number, number, number];
+    /**
+     * Matches cubic curves between two polygons.
+     *
+     * Algorithm:
+     * 1. Measure both polygons (arc-length normalized progress)
+     * 2. Use featureMapper to determine correspondence between features
+     * 3. Cut and shift polygon2 so both start at the same logical point
+     * 4. Walk both lists together, splitting curves when one extends past the other
+     *
+     * @internal
+     */
+    private static match;
+}
+
+/**
+ * Rendering utilities: convert RoundedPolygon / Cubic[] to SVG paths and CSS clip-paths.
+ *
+ * All output paths use absolute coordinates relative to the shape's natural
+ * normalized space ([0,1]×[0,1]) or scaled to pixel dimensions.
+ */
+
+/**
+ * Converts a list of Cubic Bézier curves to an SVG path string.
+ *
+ * @param cubics - Array of Cubic curves (must be contiguous, closed)
+ * @param width - Width in pixels to scale x coordinates (default: 1 = normalized)
+ * @param height - Height in pixels to scale y coordinates (default: 1 = normalized)
+ * @returns SVG path data string, e.g. "M 0.5 0 C 1 0 1 1 0.5 1 Z"
+ *
+ * @example
+ * const path = toSvgPath(MD3Shapes.circle.cubics, 200, 200);
+ * // Use in <path d={path} />
+ */
+declare function toSvgPath(cubics: Cubic[], width?: number, height?: number): string;
+/**
+ * Converts a RoundedPolygon to a CSS `clip-path: path(...)` value.
+ *
+ * @param polygon - Normalized RoundedPolygon (values in [0,1])
+ * @param width - Element width in pixels
+ * @param height - Element height in pixels
+ * @returns CSS clip-path value, e.g. "path('M ...')"
+ *
+ * @example
+ * const clipPath = toClipPath(MD3Shapes.sunny, 200, 200);
+ * element.style.clipPath = clipPath;
+ */
+declare function toClipPath(polygon: RoundedPolygon, width: number, height: number): string;
+/**
+ * Returns a CSS clip-path for a morphed shape at the given progress.
+ *
+ * @param morph - A pre-constructed Morph instance
+ * @param progress - Interpolation factor in [0, 1]
+ * @param width - Element width in pixels
+ * @param height - Element height in pixels
+ * @returns CSS clip-path value
+ *
+ * @example
+ * const morph = new Morph(MD3Shapes.circle, MD3Shapes.flower);
+ * element.style.clipPath = interpolatePath(morph, 0.5, 200, 200);
+ */
+declare function interpolatePath(morph: Morph, progress: number, width: number, height: number): string;
+
+/**
+ * Types for ShapeMedia React components.
+ */
+
+/** A shape reference: either a named MD3 shape or a custom RoundedPolygon. */
+type ShapeRef = MD3ShapeName | RoundedPolygon;
+/**
+ * Trigger for morphing animation.
+ * - "hover"  — morph on mouse enter/leave
+ * - "click"  — morph on click (toggle)
+ * - "focus"  — morph on focus/blur
+ * - "scroll" — morph driven by scroll progress (requires scrollProgress prop)
+ * - "none"   — no automatic morphing (use controlled mode)
+ */
+type MorphTrigger = "hover" | "click" | "focus" | "scroll" | "none";
+/** Options for the morph animation. */
+interface ShapeMorphOptions {
+    /** Duration in seconds (default: 0.3) */
+    duration?: number;
+    /** Easing: any CSS easing string or Framer Motion easing (default: "ease-in-out") */
+    easing?: string | number[];
+}
+/** Return value of the useShapeMorph hook. */
+interface UseShapeMorphResult {
+    /**
+     * CSS clip-path value for the current morphed shape.
+     * Apply to an element's style.clipPath.
+     */
+    clipPath: string;
+    /** Whether the morph is currently at the end shape (progress=1). */
+    isActive: boolean;
+    /** Programmatically trigger morph to end shape. */
+    activate: () => void;
+    /** Programmatically reverse morph to start shape. */
+    deactivate: () => void;
+    /** Set an exact progress value (0=start, 1=end). */
+    setProgress: (progress: number) => void;
+    /** Event handlers for auto-wiring to DOM elements. */
+    handlers: {
+        onMouseEnter?: () => void;
+        onMouseLeave?: () => void;
+        onClick?: () => void;
+        onFocus?: () => void;
+        onBlur?: () => void;
+    };
+}
+/** Props for the ShapeMedia component. */
+interface ShapeMediaProps {
+    /** The base shape (at rest). */
+    shape: ShapeRef;
+    /**
+     * The target shape to morph to (optional).
+     * When not provided, no morphing animation occurs.
+     */
+    morphTo?: ShapeRef;
+    /** Which interaction triggers the morph (default: "hover"). */
+    morphOn?: MorphTrigger;
+    /** Animation options. */
+    morphOptions?: ShapeMorphOptions;
+    /**
+     * External scroll progress in [0, 1], used when morphOn="scroll".
+     * Connect to useScroll / scrollYProgress from Framer Motion.
+     */
+    scrollProgress?: number;
+    /** Width in pixels. If not provided, uses element's natural width. */
+    width?: number;
+    /** Height in pixels. If not provided, uses element's natural height. */
+    height?: number;
+    /** Children to render inside the clipped shape. */
+    children?: ReactNode;
+    /** Additional CSS class names. */
+    className?: string;
+    /** Inline styles (merged with shape clip-path). */
+    style?: CSSProperties;
+    /** ARIA label for accessibility. */
+    "aria-label"?: string;
+    /** ARIA role (default: "presentation" if no aria-label, else "img"). */
+    role?: string;
+    /** Whether the component is disabled (disables morphing). */
+    disabled?: boolean;
+}
+/** Props for ShapeIcon — simplified fixed-size shape wrapper. */
+interface ShapeIconProps {
+    /** The base shape. */
+    shape: ShapeRef;
+    /** Shape to morph to on hover. */
+    morphTo?: ShapeRef;
+    /** Size in pixels (width = height). Default: 48. */
+    size?: number;
+    /** Icon content. */
+    children?: ReactNode;
+    /** CSS class names. */
+    className?: string;
+    /** Inline styles. */
+    style?: CSSProperties;
+    /** Background color. Default: "currentColor". */
+    color?: string;
+    /** ARIA label. */
+    "aria-label"?: string;
+}
+/** Props for ShapeSvg — renders the shape as an SVG path. */
+interface ShapeSvgProps {
+    /** The shape to render. */
+    shape: ShapeRef;
+    /** SVG viewport width (default: 100). */
+    width?: number;
+    /** SVG viewport height (default: 100). */
+    height?: number;
+    /** Path fill color (default: "currentColor"). */
+    fill?: string;
+    /** Path stroke color (default: "none"). */
+    stroke?: string;
+    /** Path stroke width (default: 0). */
+    strokeWidth?: number;
+    /** CSS class names. */
+    className?: string;
+    /** Inline styles. */
+    style?: CSSProperties;
+    /** ARIA label. */
+    "aria-label"?: string;
+    /** Morph progress [0, 1] — set to animate between shape and morphTo. */
+    progress?: number;
+    /** Target shape for morphed SVG rendering. */
+    morphTo?: ShapeRef;
+}
+
+/**
+ * ShapeIcon — simplified fixed-size shape wrapper for icons and small elements.
+ * Morphs to a circle on hover by default.
+ *
+ * @example
+ * <ShapeIcon shape="sunny" size={48}>
+ *   <StarIcon />
+ * </ShapeIcon>
+ */
+
+/**
+ * ShapeIcon renders a fixed-size shape with icon content inside.
+ */
+declare function ShapeIcon({ shape, morphTo, size, children, className, style, color, "aria-label": ariaLabel, }: ShapeIconProps): React.JSX.Element;
+
+/**
+ * ShapeMedia — wraps any UI element (image, video, button, div) with an MD3
+ * Expressive shape clip-path, with optional shape morphing animation.
+ *
+ * @example
+ * // Static shape
+ * <ShapeMedia shape="sunny" width={200} height={200}>
+ *   <img src="/photo.jpg" alt="A sunny photo" />
+ * </ShapeMedia>
+ *
+ * @example
+ * // Shape morph on hover
+ * <ShapeMedia shape="circle" morphTo="flower" morphOn="hover" width={200} height={200}>
+ *   <img src="/avatar.jpg" alt="Avatar" />
+ * </ShapeMedia>
+ */
+
+/**
+ * ShapeMedia wraps children in a shape clip-path with optional morphing animation.
+ *
+ * @remarks
+ * - Requires "use client" (uses ResizeObserver, animation APIs).
+ * - Use ShapeMediaServer for SSR-only static rendering.
+ * - Automatically handles `prefers-reduced-motion`.
+ *
+ * @param props - {@link ShapeMediaProps}
+ */
+declare function ShapeMedia({ shape, morphTo, morphOn, morphOptions, scrollProgress, width: widthProp, height: heightProp, children, className, style, "aria-label": ariaLabel, role, disabled, }: ShapeMediaProps): React.JSX.Element;
+
+/**
+ * ShapeMediaServer — SSR-safe static variant of ShapeMedia.
+ *
+ * Renders a static clip-path without any client-side JavaScript or hydration.
+ * Use this in Next.js Server Components or any SSR context where you don't
+ * need morphing animation.
+ *
+ * @example
+ * // In a Next.js Server Component
+ * import { ShapeMediaServer } from "@bug-on/m3-expressive";
+ *
+ * export default function ProfileCard() {
+ *   return (
+ *     <ShapeMediaServer shape="sunny" width={200} height={200}>
+ *       <img src="/avatar.jpg" alt="Profile" />
+ *     </ShapeMediaServer>
+ *   );
+ * }
+ */
+
+interface ShapeMediaServerProps {
+    /** The shape to render. */
+    shape: ShapeRef;
+    /** Width in pixels. */
+    width: number;
+    /** Height in pixels. */
+    height: number;
+    /** Children to render inside the clipped area. */
+    children?: ReactNode;
+    /** Additional CSS class names. */
+    className?: string;
+    /** Inline styles. */
+    style?: CSSProperties;
+    /** ARIA label. */
+    "aria-label"?: string;
+    /** ARIA role. */
+    role?: string;
+}
+/**
+ * SSR-safe shape clip-path wrapper. No animations, no JS required.
+ */
+declare function ShapeMediaServer({ shape, width, height, children, className, style, "aria-label": ariaLabel, role, }: ShapeMediaServerProps): React.JSX.Element;
+
+/**
+ * ShapeSvg — renders a shape as an inline SVG path element.
+ * Useful for decorative shapes, loading skeletons, and outlines.
+ * Supports morphed rendering via a `progress` prop.
+ *
+ * @example
+ * // Static shape
+ * <ShapeSvg shape="sunny" width={200} height={200} fill="#6750A4" />
+ *
+ * @example
+ * // Morphed shape (controlled externally)
+ * <ShapeSvg shape="circle" morphTo="flower" progress={0.5} width={200} height={200} />
+ */
+
+/**
+ * ShapeSvg renders a shape or morphed shape as a plain SVG path.
+ */
+declare function ShapeSvg({ shape, morphTo, progress, width, height, fill, stroke, strokeWidth, className, style, "aria-label": ariaLabel, }: ShapeSvgProps): React.JSX.Element;
+
+/**
+ * useShapeMorph — React hook for shape morphing animations.
+ *
+ * Manages the Morph instance and animated progress value, returning a
+ * CSS clip-path string that updates with every animation frame.
+ *
+ * @example
+ * const { clipPath, handlers } = useShapeMorph({
+ *   shape: "circle",
+ *   morphTo: "flower",
+ *   morphOn: "hover",
+ *   width: 200,
+ *   height: 200,
+ * });
+ *
+ * return <div style={{ clipPath }} {...handlers}>{children}</div>;
+ */
+
+interface UseShapeMorphOptions {
+    shape: ShapeRef;
+    morphTo?: ShapeRef;
+    morphOn?: MorphTrigger;
+    morphOptions?: ShapeMorphOptions;
+    scrollProgress?: number;
+    width: number;
+    height: number;
+    disabled?: boolean;
+}
+/**
+ * Hook for shape morphing with animated clip-path output.
+ */
+declare function useShapeMorph({ shape, morphTo, morphOn, morphOptions, scrollProgress, width, height, disabled, }: UseShapeMorphOptions): UseShapeMorphResult;
+
+export { ANGLE_EPSILON, type CornerFeature, type CornerRounding, Cubic, type CubicPair, DISTANCE_EPSILON, type DoubleMapper, type EdgeFeature, FLOAT_PI, type Feature, MD3CornerRadius, type MD3CornerRadiusToken, type MD3ShapeName, MD3Shapes, type MeasuredCubic, type MeasuredFeature, MeasuredPolygon, Morph, type MorphTrigger, MutableCubic, type Point, type PointTransformer, RoundedPolygon, ShapeIcon, type ShapeIconProps, ShapeMedia, type ShapeMediaProps, ShapeMediaServer, type ShapeMorphOptions, type ShapeRef, ShapeSvg, type ShapeSvgProps, UNROUNDED, type UseShapeMorphResult, addPoints, circle, clockwise, convex, cornerFeature, cornerRounding, createDoubleMapper, directionVector, distance, distanceSquared, dividePoint, dotProduct, edgeFeature, featureMapper, getDirection, getDistance, getDistanceSquared, interpolate, interpolatePath, lerpPoint, pill, pillStar, point, positiveModulo, radialToCartesian, rectangle, rotate90, scalePoint, square, star, subtractPoints, toClipPath, toSvgPath, transformFeature, transformPoint, useShapeMorph };