@flare-engine/math 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Grzegorz Otto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @flare-engine/math
+
+2D math primitives for the Flare engine — `Vec2`, `Rect`, `Circle`, `Transform2D`, `Mat3`, `Color`, 32 easing functions, seeded RNG, and intersection tests. Plain-object types with static method namespaces; zero-alloc forms take an `out` parameter to avoid GC pressure in game loops.
+
+## Install
+
+```sh
+bun add @flare-engine/math
+```
+
+## Usage
+
+```ts
+import { vec2, Vec2, Rect, easeOutQuad, SeededRNG } from '@flare-engine/math';
+
+const a = vec2(0, 0);
+const b = vec2(10, 0);
+const out = vec2(0, 0);
+Vec2.lerp(a, b, 0.5, out);
+
+const rng = new SeededRNG(42);
+const t = easeOutQuad(rng.float());
+```
+
+See [API spec](../../docs/design/api-specs.md#flare-enginemath--5kb-gzip) and [skill reference](../../.github/skills/flare-math/SKILL.md).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,308 @@
+/** Clamps value between min and max. */
+declare function clamp(value: number, min: number, max: number): number;
+/** Linearly interpolates between a and b by t (unclamped). */
+declare function lerp(a: number, b: number, t: number): number;
+/** Returns the interpolation factor of value between a and b. */
+declare function inverseLerp(a: number, b: number, value: number): number;
+/** Maps value from [inMin, inMax] to [outMin, outMax]. */
+declare function map(value: number, inMin: number, inMax: number, outMin: number, outMax: number): number;
+/** Converts degrees to radians. */
+declare function degToRad(degrees: number): number;
+/** Converts radians to degrees. */
+declare function radToDeg(radians: number): number;
+/** Returns true if a and b are approximately equal within epsilon. */
+declare function approxEquals(a: number, b: number, epsilon?: number): boolean;
+/** Wraps value into [min, max) range. */
+declare function wrap(value: number, min: number, max: number): number;
+/** PingPong — bounces value back and forth in [0, length]. */
+declare function pingPong(t: number, length: number): number;
+/** Hermite smooth interpolation (0→1) with zero first-derivative at edges. */
+declare function smoothStep(edge0: number, edge1: number, x: number): number;
+/** Returns -1, 0, or 1. Unlike Math.sign, returns 0 for NaN. */
+declare function sign(value: number): number;
+
+/** Creates a Vec2 plain object. */
+declare function vec2(x?: number, y?: number): Vec2;
+/** Vec2 plain object type — no class, no GC pressure. */
+type Vec2 = {
+    x: number;
+    y: number;
+};
+declare const Vec2: {
+    /** Returns { 0, 0 }. */
+    readonly zero: () => Vec2;
+    /** Returns { 1, 1 }. */
+    readonly one: () => Vec2;
+    /** Returns { 0, -1 }. */
+    readonly up: () => Vec2;
+    /** Returns { 0, 1 }. */
+    readonly down: () => Vec2;
+    /** Returns { -1, 0 }. */
+    readonly left: () => Vec2;
+    /** Returns { 1, 0 }. */
+    readonly right: () => Vec2;
+    /** Component-wise addition. Writes into out if provided. */
+    readonly add: (a: Vec2, b: Vec2, out?: Vec2) => Vec2;
+    /** Component-wise subtraction a - b. */
+    readonly sub: (a: Vec2, b: Vec2, out?: Vec2) => Vec2;
+    /** Scales a vector by a scalar. */
+    readonly scale: (v: Vec2, s: number, out?: Vec2) => Vec2;
+    /** Returns a unit vector. Returns zero vector if length is 0. */
+    readonly normalize: (v: Vec2, out?: Vec2) => Vec2;
+    /** Zero-alloc; writes into `out`. Mandatory `out` so callers avoid temporaries in hot paths. */
+    readonly normalizeOut: (dx: number, dy: number, speed: number, out: Vec2) => Vec2;
+    /** Dot product. */
+    readonly dot: (a: Vec2, b: Vec2) => number;
+    /** 2D cross product (z-component of the 3D cross). */
+    readonly cross: (a: Vec2, b: Vec2) => number;
+    /** Linearly interpolates between a and b (unclamped). */
+    readonly lerp: (a: Vec2, b: Vec2, t: number, out?: Vec2) => Vec2;
+    /** Spherical linear interpolation for unit vectors. */
+    readonly slerp: (a: Vec2, b: Vec2, t: number, out?: Vec2) => Vec2;
+    /** Euclidean distance between two points. */
+    readonly distance: (a: Vec2, b: Vec2) => number;
+    /** Squared distance (avoids sqrt). */
+    readonly distanceSq: (a: Vec2, b: Vec2) => number;
+    /** Length of a vector. */
+    readonly length: (v: Vec2) => number;
+    /** Squared length (avoids sqrt). */
+    readonly lengthSq: (v: Vec2) => number;
+    /** Angle of vector in radians (atan2). */
+    readonly angle: (v: Vec2) => number;
+    /** Rotates a vector by angle (radians) around origin. */
+    readonly rotate: (v: Vec2, angle: number, out?: Vec2) => Vec2;
+    /** Component-wise approximate equality. */
+    readonly equals: (a: Vec2, b: Vec2, epsilon?: number) => boolean;
+    /** Returns a copy of the vector. */
+    readonly clone: (v: Vec2) => Vec2;
+    /** Clamps the length of a vector to maxLength. */
+    readonly clampLength: (v: Vec2, maxLength: number, out?: Vec2) => Vec2;
+};
+
+/** Axis-aligned bounding box. */
+type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+declare const Rect: {
+    /** Returns true if point is inside rect (inclusive). */
+    readonly contains: (r: Rect, p: Vec2) => boolean;
+    /** Returns true if two rects overlap (share area). */
+    readonly intersects: (a: Rect, b: Rect) => boolean;
+    /** Returns the overlapping rect, or null if no overlap. */
+    readonly intersection: (a: Rect, b: Rect) => Rect | null;
+    /** Returns the smallest rect containing both rects. */
+    readonly union: (a: Rect, b: Rect) => Rect;
+    /** Creates a rect from an array of points (bounding box). */
+    readonly fromPoints: (points: readonly Vec2[]) => Rect;
+    /** Returns the center point of the rect. */
+    readonly center: (r: Rect) => Vec2;
+    /** Returns a new rect expanded by amount on each side. */
+    readonly expand: (r: Rect, amount: number) => Rect;
+};
+
+/** Circle shape: center position + radius. */
+type Circle = {
+    x: number;
+    y: number;
+    radius: number;
+};
+declare const Circle: {
+    /** Returns true if point is inside or on the circle. */
+    readonly contains: (c: Circle, p: Vec2) => boolean;
+    /** Returns true if two circles overlap (share area). */
+    readonly intersects: (a: Circle, b: Circle) => boolean;
+    /** Returns true if a circle and rect overlap. */
+    readonly intersectsRect: (c: Circle, r: Rect) => boolean;
+};
+
+/** 2D transform: position, rotation (radians), and scale. */
+type Transform2D = {
+    position: Vec2;
+    rotation: number;
+    scale: Vec2;
+};
+declare const Transform2D: {
+    /** Creates an identity transform. */
+    readonly identity: () => Transform2D;
+    /** Creates a transform from components. */
+    readonly create: (x?: number, y?: number, rotation?: number, scaleX?: number, scaleY?: number) => Transform2D;
+    /** Transforms a local-space point to world-space. */
+    readonly localToWorld: (t: Transform2D, point: Vec2) => Vec2;
+    /** Transforms a world-space point to local-space. */
+    readonly worldToLocal: (t: Transform2D, point: Vec2) => Vec2;
+    /** Returns a copy of the transform. */
+    readonly clone: (t: Transform2D) => Transform2D;
+};
+
+/**
+ * 3x3 matrix stored in column-major order on Float32Array.
+ * Layout: [m00, m10, m20, m01, m11, m21, m02, m12, m22]
+ *
+ * | m00 m01 m02 |     indices: | 0 3 6 |
+ * | m10 m11 m12 |              | 1 4 7 |
+ * | m20 m21 m22 |              | 2 5 8 |
+ */
+type Mat3 = Float32Array;
+declare const Mat3: {
+    /** Creates a new identity matrix. */
+    readonly create: () => Mat3;
+    /** Sets m to identity. */
+    readonly identity: (m: Mat3) => Mat3;
+    /** Multiplies a * b, writes into out (or allocates). */
+    readonly multiply: (a: Mat3, b: Mat3, out?: Mat3) => Mat3;
+    /** Creates a translation matrix. */
+    readonly translate: (tx: number, ty: number, out?: Mat3) => Mat3;
+    /** Creates a rotation matrix (radians). */
+    readonly rotate: (angle: number, out?: Mat3) => Mat3;
+    /** Creates a scale matrix. */
+    readonly scale: (sx: number, sy: number, out?: Mat3) => Mat3;
+    /** Inverts the matrix. Returns null if singular. */
+    readonly invert: (m: Mat3, out?: Mat3) => Mat3 | null;
+    /** Builds a matrix from a Transform2D (TRS order: translate * rotate * scale). */
+    readonly fromTransform: (t: Transform2D, out?: Mat3) => Mat3;
+};
+
+/** OKLab perceptual color space (L 0-1, a and b unbounded in practice ±0.5). */
+type Oklab = {
+    L: number;
+    a: number;
+    b: number;
+};
+/** OKLCH polar form of OKLab (L 0-1, C >= 0, h degrees [0,360)). */
+type Oklch = {
+    L: number;
+    C: number;
+    h: number;
+};
+/** RGBA color with components normalized to 0-1. */
+type Color = {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
+declare const Color: {
+    readonly WHITE: Color;
+    readonly BLACK: Color;
+    readonly TRANSPARENT: Color;
+    /** Creates a Color from normalized 0-1 components. */
+    readonly create: (r?: number, g?: number, b?: number, a?: number) => Color;
+    /** Parses a hex string (#RGB, #RGBA, #RRGGBB, #RRGGBBAA). */
+    readonly fromHex: (hex: string) => Color;
+    /** Converts to hex string #RRGGBB or #RRGGBBAA if alpha < 1. */
+    readonly toHex: (c: Color) => string;
+    /** Linearly interpolates between two colors. */
+    readonly lerp: (a: Color, b: Color, t: number) => Color;
+    /** Component-wise multiplication. */
+    readonly multiply: (a: Color, b: Color) => Color;
+    /**
+     * Converts to a Skia-compatible color number (0xAARRGGBB).
+     * Compatible with @shopify/react-native-skia Skia.Color() format.
+     */
+    readonly toSkColor: (c: Color) => number;
+    /** Converts sRGB Color to OKLab. Alpha is dropped. */
+    readonly toOklab: (c: Color) => Oklab;
+    /**
+     * Converts OKLab to sRGB Color. Out-of-gamut results are clamped to [0,1];
+     * round-trips are exact only for in-gamut colors.
+     */
+    readonly fromOklab: (lab: Oklab, alpha?: number) => Color;
+    /** Converts sRGB Color to OKLCH (polar OKLab). Achromatic colors get h = 0. */
+    readonly toOklch: (c: Color) => Oklch;
+    /**
+     * Converts OKLCH to sRGB Color. Hue is wrapped via ((h%360)+360)%360.
+     * Out-of-gamut results are clamped; round-trips exact only in-gamut.
+     */
+    readonly fromOklch: (lch: Oklch, alpha?: number) => Color;
+    /** Euclidean distance in OKLab space between two sRGB colors. */
+    readonly deltaEOk: (a: Color, b: Color) => number;
+    /** Euclidean distance between two OKLab values. */
+    readonly deltaEOkLab: (a: Oklab, b: Oklab) => number;
+    /** WCAG 2.x relative luminance. White = 1, black = 0. */
+    readonly relativeLuminance: (c: Color) => number;
+    /** WCAG 2.x contrast ratio. Order-independent; range [1, 21]. */
+    readonly contrastRatio: (fg: Color, bg: Color) => number;
+};
+
+declare function linear(t: number): number;
+declare function step(t: number): number;
+declare function easeInQuad(t: number): number;
+declare function easeOutQuad(t: number): number;
+declare function easeInOutQuad(t: number): number;
+declare function easeInCubic(t: number): number;
+declare function easeOutCubic(t: number): number;
+declare function easeInOutCubic(t: number): number;
+declare function easeInQuart(t: number): number;
+declare function easeOutQuart(t: number): number;
+declare function easeInOutQuart(t: number): number;
+declare function easeInQuint(t: number): number;
+declare function easeOutQuint(t: number): number;
+declare function easeInOutQuint(t: number): number;
+declare function easeInSine(t: number): number;
+declare function easeOutSine(t: number): number;
+declare function easeInOutSine(t: number): number;
+declare function easeInExpo(t: number): number;
+declare function easeOutExpo(t: number): number;
+declare function easeInOutExpo(t: number): number;
+declare function easeInCirc(t: number): number;
+declare function easeOutCirc(t: number): number;
+declare function easeInOutCirc(t: number): number;
+declare function easeInBack(t: number): number;
+declare function easeOutBack(t: number): number;
+declare function easeInOutBack(t: number): number;
+declare function easeInElastic(t: number): number;
+declare function easeOutElastic(t: number): number;
+declare function easeInOutElastic(t: number): number;
+declare function easeOutBounce(t: number): number;
+declare function easeInBounce(t: number): number;
+declare function easeInOutBounce(t: number): number;
+declare function springIn(t: number): number;
+declare function springOut(t: number): number;
+declare function springInOut(t: number): number;
+type EasingFn = (t: number) => number;
+
+/** Seeded PRNG using mulberry32 algorithm. */
+declare class SeededRNG {
+    private state;
+    constructor(seed: number);
+    /** Returns a float in [0, 1). */
+    next(): number;
+    /** Returns a float in [min, max). */
+    float(min: number, max: number): number;
+    /** Returns an integer in [min, max] (inclusive). */
+    int(min: number, max: number): number;
+}
+/** Returns a random float in [min, max). */
+declare function randomFloat(min: number, max: number): number;
+/** Returns a random integer in [min, max] (inclusive). */
+declare function randomInt(min: number, max: number): number;
+/** Returns a random Vec2 within a rect. */
+declare function randomVec2InRect(r: Rect): Vec2;
+/** Returns a random point inside a circle (uniform distribution). */
+declare function randomPointInCircle(cx: number, cy: number, radius: number): Vec2;
+/** Fisher-Yates shuffle (in-place). Returns the array. */
+declare function shuffle<T>(array: T[]): T[];
+/** Returns a random element from the array. */
+declare function choose<T>(array: readonly T[]): T | undefined;
+
+/** Returns true if point is inside rect (inclusive). */
+declare function pointInRect(p: Vec2, r: Rect): boolean;
+/** Returns true if point is inside circle (inclusive). */
+declare function pointInCircle(p: Vec2, c: Circle): boolean;
+/** Returns true if two rects overlap. */
+declare function rectVsRect(a: Rect, b: Rect): boolean;
+/** Returns true if rect and circle overlap. */
+declare function rectVsCircle(r: Rect, c: Circle): boolean;
+/** Returns true if two circles overlap. */
+declare function circleVsCircle(a: Circle, b: Circle): boolean;
+/** Line segment intersection with AABB. Uses Liang-Barsky algorithm. */
+declare function lineVsRect(x1: number, y1: number, x2: number, y2: number, r: Rect): boolean;
+/** Line segment intersection with circle. */
+declare function lineVsCircle(x1: number, y1: number, x2: number, y2: number, c: Circle): boolean;
+/** Ray intersection with AABB. Returns t (distance) or null if no hit. */
+declare function rayVsRect(originX: number, originY: number, dirX: number, dirY: number, r: Rect): number | null;
+
+export { Circle, Color, type EasingFn, Mat3, type Oklab, type Oklch, Rect, SeededRNG, Transform2D, Vec2, approxEquals, choose, circleVsCircle, clamp, degToRad, easeInBack, easeInBounce, easeInCirc, easeInCubic, easeInElastic, easeInExpo, easeInOutBack, easeInOutBounce, easeInOutCirc, easeInOutCubic, easeInOutElastic, easeInOutExpo, easeInOutQuad, easeInOutQuart, easeInOutQuint, easeInOutSine, easeInQuad, easeInQuart, easeInQuint, easeInSine, easeOutBack, easeOutBounce, easeOutCirc, easeOutCubic, easeOutElastic, easeOutExpo, easeOutQuad, easeOutQuart, easeOutQuint, easeOutSine, inverseLerp, lerp, lineVsCircle, lineVsRect, linear, map, pingPong, pointInCircle, pointInRect, radToDeg, randomFloat, randomInt, randomPointInCircle, randomVec2InRect, rayVsRect, rectVsCircle, rectVsRect, shuffle, sign, smoothStep, springIn, springInOut, springOut, step, vec2, wrap };

package/dist/index.d.ts

@@ -0,0 +1,308 @@
+/** Clamps value between min and max. */
+declare function clamp(value: number, min: number, max: number): number;
+/** Linearly interpolates between a and b by t (unclamped). */
+declare function lerp(a: number, b: number, t: number): number;
+/** Returns the interpolation factor of value between a and b. */
+declare function inverseLerp(a: number, b: number, value: number): number;
+/** Maps value from [inMin, inMax] to [outMin, outMax]. */
+declare function map(value: number, inMin: number, inMax: number, outMin: number, outMax: number): number;
+/** Converts degrees to radians. */
+declare function degToRad(degrees: number): number;
+/** Converts radians to degrees. */
+declare function radToDeg(radians: number): number;
+/** Returns true if a and b are approximately equal within epsilon. */
+declare function approxEquals(a: number, b: number, epsilon?: number): boolean;
+/** Wraps value into [min, max) range. */
+declare function wrap(value: number, min: number, max: number): number;
+/** PingPong — bounces value back and forth in [0, length]. */
+declare function pingPong(t: number, length: number): number;
+/** Hermite smooth interpolation (0→1) with zero first-derivative at edges. */
+declare function smoothStep(edge0: number, edge1: number, x: number): number;
+/** Returns -1, 0, or 1. Unlike Math.sign, returns 0 for NaN. */
+declare function sign(value: number): number;
+
+/** Creates a Vec2 plain object. */
+declare function vec2(x?: number, y?: number): Vec2;
+/** Vec2 plain object type — no class, no GC pressure. */
+type Vec2 = {
+    x: number;
+    y: number;
+};
+declare const Vec2: {
+    /** Returns { 0, 0 }. */
+    readonly zero: () => Vec2;
+    /** Returns { 1, 1 }. */
+    readonly one: () => Vec2;
+    /** Returns { 0, -1 }. */
+    readonly up: () => Vec2;
+    /** Returns { 0, 1 }. */
+    readonly down: () => Vec2;
+    /** Returns { -1, 0 }. */
+    readonly left: () => Vec2;
+    /** Returns { 1, 0 }. */
+    readonly right: () => Vec2;
+    /** Component-wise addition. Writes into out if provided. */
+    readonly add: (a: Vec2, b: Vec2, out?: Vec2) => Vec2;
+    /** Component-wise subtraction a - b. */
+    readonly sub: (a: Vec2, b: Vec2, out?: Vec2) => Vec2;
+    /** Scales a vector by a scalar. */
+    readonly scale: (v: Vec2, s: number, out?: Vec2) => Vec2;
+    /** Returns a unit vector. Returns zero vector if length is 0. */
+    readonly normalize: (v: Vec2, out?: Vec2) => Vec2;
+    /** Zero-alloc; writes into `out`. Mandatory `out` so callers avoid temporaries in hot paths. */
+    readonly normalizeOut: (dx: number, dy: number, speed: number, out: Vec2) => Vec2;
+    /** Dot product. */
+    readonly dot: (a: Vec2, b: Vec2) => number;
+    /** 2D cross product (z-component of the 3D cross). */
+    readonly cross: (a: Vec2, b: Vec2) => number;
+    /** Linearly interpolates between a and b (unclamped). */
+    readonly lerp: (a: Vec2, b: Vec2, t: number, out?: Vec2) => Vec2;
+    /** Spherical linear interpolation for unit vectors. */
+    readonly slerp: (a: Vec2, b: Vec2, t: number, out?: Vec2) => Vec2;
+    /** Euclidean distance between two points. */
+    readonly distance: (a: Vec2, b: Vec2) => number;
+    /** Squared distance (avoids sqrt). */
+    readonly distanceSq: (a: Vec2, b: Vec2) => number;
+    /** Length of a vector. */
+    readonly length: (v: Vec2) => number;
+    /** Squared length (avoids sqrt). */
+    readonly lengthSq: (v: Vec2) => number;
+    /** Angle of vector in radians (atan2). */
+    readonly angle: (v: Vec2) => number;
+    /** Rotates a vector by angle (radians) around origin. */
+    readonly rotate: (v: Vec2, angle: number, out?: Vec2) => Vec2;
+    /** Component-wise approximate equality. */
+    readonly equals: (a: Vec2, b: Vec2, epsilon?: number) => boolean;
+    /** Returns a copy of the vector. */
+    readonly clone: (v: Vec2) => Vec2;
+    /** Clamps the length of a vector to maxLength. */
+    readonly clampLength: (v: Vec2, maxLength: number, out?: Vec2) => Vec2;
+};
+
+/** Axis-aligned bounding box. */
+type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+declare const Rect: {
+    /** Returns true if point is inside rect (inclusive). */
+    readonly contains: (r: Rect, p: Vec2) => boolean;
+    /** Returns true if two rects overlap (share area). */
+    readonly intersects: (a: Rect, b: Rect) => boolean;
+    /** Returns the overlapping rect, or null if no overlap. */
+    readonly intersection: (a: Rect, b: Rect) => Rect | null;
+    /** Returns the smallest rect containing both rects. */
+    readonly union: (a: Rect, b: Rect) => Rect;
+    /** Creates a rect from an array of points (bounding box). */
+    readonly fromPoints: (points: readonly Vec2[]) => Rect;
+    /** Returns the center point of the rect. */
+    readonly center: (r: Rect) => Vec2;
+    /** Returns a new rect expanded by amount on each side. */
+    readonly expand: (r: Rect, amount: number) => Rect;
+};
+
+/** Circle shape: center position + radius. */
+type Circle = {
+    x: number;
+    y: number;
+    radius: number;
+};
+declare const Circle: {
+    /** Returns true if point is inside or on the circle. */
+    readonly contains: (c: Circle, p: Vec2) => boolean;
+    /** Returns true if two circles overlap (share area). */
+    readonly intersects: (a: Circle, b: Circle) => boolean;
+    /** Returns true if a circle and rect overlap. */
+    readonly intersectsRect: (c: Circle, r: Rect) => boolean;
+};
+
+/** 2D transform: position, rotation (radians), and scale. */
+type Transform2D = {
+    position: Vec2;
+    rotation: number;
+    scale: Vec2;
+};
+declare const Transform2D: {
+    /** Creates an identity transform. */
+    readonly identity: () => Transform2D;
+    /** Creates a transform from components. */
+    readonly create: (x?: number, y?: number, rotation?: number, scaleX?: number, scaleY?: number) => Transform2D;
+    /** Transforms a local-space point to world-space. */
+    readonly localToWorld: (t: Transform2D, point: Vec2) => Vec2;
+    /** Transforms a world-space point to local-space. */
+    readonly worldToLocal: (t: Transform2D, point: Vec2) => Vec2;
+    /** Returns a copy of the transform. */
+    readonly clone: (t: Transform2D) => Transform2D;
+};
+
+/**
+ * 3x3 matrix stored in column-major order on Float32Array.
+ * Layout: [m00, m10, m20, m01, m11, m21, m02, m12, m22]
+ *
+ * | m00 m01 m02 |     indices: | 0 3 6 |
+ * | m10 m11 m12 |              | 1 4 7 |
+ * | m20 m21 m22 |              | 2 5 8 |
+ */
+type Mat3 = Float32Array;
+declare const Mat3: {
+    /** Creates a new identity matrix. */
+    readonly create: () => Mat3;
+    /** Sets m to identity. */
+    readonly identity: (m: Mat3) => Mat3;
+    /** Multiplies a * b, writes into out (or allocates). */
+    readonly multiply: (a: Mat3, b: Mat3, out?: Mat3) => Mat3;
+    /** Creates a translation matrix. */
+    readonly translate: (tx: number, ty: number, out?: Mat3) => Mat3;
+    /** Creates a rotation matrix (radians). */
+    readonly rotate: (angle: number, out?: Mat3) => Mat3;
+    /** Creates a scale matrix. */
+    readonly scale: (sx: number, sy: number, out?: Mat3) => Mat3;
+    /** Inverts the matrix. Returns null if singular. */
+    readonly invert: (m: Mat3, out?: Mat3) => Mat3 | null;
+    /** Builds a matrix from a Transform2D (TRS order: translate * rotate * scale). */
+    readonly fromTransform: (t: Transform2D, out?: Mat3) => Mat3;
+};
+
+/** OKLab perceptual color space (L 0-1, a and b unbounded in practice ±0.5). */
+type Oklab = {
+    L: number;
+    a: number;
+    b: number;
+};
+/** OKLCH polar form of OKLab (L 0-1, C >= 0, h degrees [0,360)). */
+type Oklch = {
+    L: number;
+    C: number;
+    h: number;
+};
+/** RGBA color with components normalized to 0-1. */
+type Color = {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
+declare const Color: {
+    readonly WHITE: Color;
+    readonly BLACK: Color;
+    readonly TRANSPARENT: Color;
+    /** Creates a Color from normalized 0-1 components. */
+    readonly create: (r?: number, g?: number, b?: number, a?: number) => Color;
+    /** Parses a hex string (#RGB, #RGBA, #RRGGBB, #RRGGBBAA). */
+    readonly fromHex: (hex: string) => Color;
+    /** Converts to hex string #RRGGBB or #RRGGBBAA if alpha < 1. */
+    readonly toHex: (c: Color) => string;
+    /** Linearly interpolates between two colors. */
+    readonly lerp: (a: Color, b: Color, t: number) => Color;
+    /** Component-wise multiplication. */
+    readonly multiply: (a: Color, b: Color) => Color;
+    /**
+     * Converts to a Skia-compatible color number (0xAARRGGBB).
+     * Compatible with @shopify/react-native-skia Skia.Color() format.
+     */
+    readonly toSkColor: (c: Color) => number;
+    /** Converts sRGB Color to OKLab. Alpha is dropped. */
+    readonly toOklab: (c: Color) => Oklab;
+    /**
+     * Converts OKLab to sRGB Color. Out-of-gamut results are clamped to [0,1];
+     * round-trips are exact only for in-gamut colors.
+     */
+    readonly fromOklab: (lab: Oklab, alpha?: number) => Color;
+    /** Converts sRGB Color to OKLCH (polar OKLab). Achromatic colors get h = 0. */
+    readonly toOklch: (c: Color) => Oklch;
+    /**
+     * Converts OKLCH to sRGB Color. Hue is wrapped via ((h%360)+360)%360.
+     * Out-of-gamut results are clamped; round-trips exact only in-gamut.
+     */
+    readonly fromOklch: (lch: Oklch, alpha?: number) => Color;
+    /** Euclidean distance in OKLab space between two sRGB colors. */
+    readonly deltaEOk: (a: Color, b: Color) => number;
+    /** Euclidean distance between two OKLab values. */
+    readonly deltaEOkLab: (a: Oklab, b: Oklab) => number;
+    /** WCAG 2.x relative luminance. White = 1, black = 0. */
+    readonly relativeLuminance: (c: Color) => number;
+    /** WCAG 2.x contrast ratio. Order-independent; range [1, 21]. */
+    readonly contrastRatio: (fg: Color, bg: Color) => number;
+};
+
+declare function linear(t: number): number;
+declare function step(t: number): number;
+declare function easeInQuad(t: number): number;
+declare function easeOutQuad(t: number): number;
+declare function easeInOutQuad(t: number): number;
+declare function easeInCubic(t: number): number;
+declare function easeOutCubic(t: number): number;
+declare function easeInOutCubic(t: number): number;
+declare function easeInQuart(t: number): number;
+declare function easeOutQuart(t: number): number;
+declare function easeInOutQuart(t: number): number;
+declare function easeInQuint(t: number): number;
+declare function easeOutQuint(t: number): number;
+declare function easeInOutQuint(t: number): number;
+declare function easeInSine(t: number): number;
+declare function easeOutSine(t: number): number;
+declare function easeInOutSine(t: number): number;
+declare function easeInExpo(t: number): number;
+declare function easeOutExpo(t: number): number;
+declare function easeInOutExpo(t: number): number;
+declare function easeInCirc(t: number): number;
+declare function easeOutCirc(t: number): number;
+declare function easeInOutCirc(t: number): number;
+declare function easeInBack(t: number): number;
+declare function easeOutBack(t: number): number;
+declare function easeInOutBack(t: number): number;
+declare function easeInElastic(t: number): number;
+declare function easeOutElastic(t: number): number;
+declare function easeInOutElastic(t: number): number;
+declare function easeOutBounce(t: number): number;
+declare function easeInBounce(t: number): number;
+declare function easeInOutBounce(t: number): number;
+declare function springIn(t: number): number;
+declare function springOut(t: number): number;
+declare function springInOut(t: number): number;
+type EasingFn = (t: number) => number;
+
+/** Seeded PRNG using mulberry32 algorithm. */
+declare class SeededRNG {
+    private state;
+    constructor(seed: number);
+    /** Returns a float in [0, 1). */
+    next(): number;
+    /** Returns a float in [min, max). */
+    float(min: number, max: number): number;
+    /** Returns an integer in [min, max] (inclusive). */
+    int(min: number, max: number): number;
+}
+/** Returns a random float in [min, max). */
+declare function randomFloat(min: number, max: number): number;
+/** Returns a random integer in [min, max] (inclusive). */
+declare function randomInt(min: number, max: number): number;
+/** Returns a random Vec2 within a rect. */
+declare function randomVec2InRect(r: Rect): Vec2;
+/** Returns a random point inside a circle (uniform distribution). */
+declare function randomPointInCircle(cx: number, cy: number, radius: number): Vec2;
+/** Fisher-Yates shuffle (in-place). Returns the array. */
+declare function shuffle<T>(array: T[]): T[];
+/** Returns a random element from the array. */
+declare function choose<T>(array: readonly T[]): T | undefined;
+
+/** Returns true if point is inside rect (inclusive). */
+declare function pointInRect(p: Vec2, r: Rect): boolean;
+/** Returns true if point is inside circle (inclusive). */
+declare function pointInCircle(p: Vec2, c: Circle): boolean;
+/** Returns true if two rects overlap. */
+declare function rectVsRect(a: Rect, b: Rect): boolean;
+/** Returns true if rect and circle overlap. */
+declare function rectVsCircle(r: Rect, c: Circle): boolean;
+/** Returns true if two circles overlap. */
+declare function circleVsCircle(a: Circle, b: Circle): boolean;
+/** Line segment intersection with AABB. Uses Liang-Barsky algorithm. */
+declare function lineVsRect(x1: number, y1: number, x2: number, y2: number, r: Rect): boolean;
+/** Line segment intersection with circle. */
+declare function lineVsCircle(x1: number, y1: number, x2: number, y2: number, c: Circle): boolean;
+/** Ray intersection with AABB. Returns t (distance) or null if no hit. */
+declare function rayVsRect(originX: number, originY: number, dirX: number, dirY: number, r: Rect): number | null;
+
+export { Circle, Color, type EasingFn, Mat3, type Oklab, type Oklch, Rect, SeededRNG, Transform2D, Vec2, approxEquals, choose, circleVsCircle, clamp, degToRad, easeInBack, easeInBounce, easeInCirc, easeInCubic, easeInElastic, easeInExpo, easeInOutBack, easeInOutBounce, easeInOutCirc, easeInOutCubic, easeInOutElastic, easeInOutExpo, easeInOutQuad, easeInOutQuart, easeInOutQuint, easeInOutSine, easeInQuad, easeInQuart, easeInQuint, easeInSine, easeOutBack, easeOutBounce, easeOutCirc, easeOutCubic, easeOutElastic, easeOutExpo, easeOutQuad, easeOutQuart, easeOutQuint, easeOutSine, inverseLerp, lerp, lineVsCircle, lineVsRect, linear, map, pingPong, pointInCircle, pointInRect, radToDeg, randomFloat, randomInt, randomPointInCircle, randomVec2InRect, rayVsRect, rectVsCircle, rectVsRect, shuffle, sign, smoothStep, springIn, springInOut, springOut, step, vec2, wrap };