@mkbabb/value.js 0.5.0 → 0.10.0

package/README.md

@@ -1,15 +1,16 @@
-# value.js ![image](demo/color-picker/cube.png)
+# `value.js` <img src="demo/color-picker/favicon.svg" style="vertical-align: middle" width="48">
 
-CSS value parsing, color theory, and unit conversion. Typed values with units—`deg`, `px`, `rem`, `oklch()`—the core CSS value vocabulary.
+CSS value parsing, color theory, and unit conversion. Typed values with units—`deg`, `px`, `rem`, `oklch()`—the CSS value vocabulary.
 
-[demo](https://color.babb.dev)
+[demo](https://color.babb.dev) & [app guide](docs/colors/app.md)
 
 ## Features
 
 - Parse any CSS value: lengths, angles, times, colors, `calc()`, `var()`, gradients, transforms
+- CSS Color Level 4 support: `color()`, `color-mix()`, relative color syntax
 - **15 color spaces**: RGB, HSL, HSV, HWB, Lab, LCh, OKLab, OKLCh, XYZ, Kelvin, sRGB-linear, Display P3, Adobe RGB, ProPhoto RGB, Rec. 2020
 - Color space conversion via **XYZ hub** with analytical gamut mapping (Ottosson's algorithm)
-- CSS Color Level 4 support: `color()`, `color-mix()`, relative color syntax
+- **Color quantization**: OKLab-native palette extraction (MMCQ + k-means++) with chroma-weighted clustering and JND deduplication
 - CSS math functions: `calc()`, `min()`, `max()`, `clamp()`, trig, exponential
 - 30+ easing functions: cubic-bezier, stepped, linear(), bounce, sine, expo
 - 2D/3D matrix decomposition with quaternion slerp interpolation
@@ -32,14 +33,23 @@ import {
 } from "@mkbabb/value.js";
 ```
 
+## Upgrading
+
+If you are upgrading across a major-feature bump, see [`CHANGELOG.md`](CHANGELOG.md) for the full per-version breaking-change list. The two migrations to be aware of:
+
+- **v0.7.0** — the 51 individual `<from>2<to>` color-conversion functions were removed from the barrel. Replace `import { rgb2hsl } from "@mkbabb/value.js"` with the unified `color2(rgb, "rgb", "hsl")`.
+- **v0.8.0** — `lerpLegacy` was removed; `lerp` takes canonical `(a, b, t)` ordering. The published codemod `scripts/migrate-keyframes-js-lerp.mjs` rewrites the legacy call shape automatically; manual migration is a straightforward argument swap (first argument moves to last).
+
+v0.9.0 carries no breaking changes.
+
 ## Build
 
 ```bash
 npm run build        # library → dist/value.js + value.cjs + value.d.ts
 npm run gh-pages     # demo → dist/
 npm run dev          # dev server (Vite default port)
-npm test             # vitest (1372 tests)
-npm run test:e2e     # playwright (desktop + mobile)
+npm test             # vitest unit suite
+npm run test:e2e     # playwright smoke suite (5 projects)
 ```
 
 ## Structure
@@ -66,77 +76,53 @@ src/
 │       ├── index.ts      # Color<T> base + space classes
 │       ├── constants.ts  # ranges, matrices, white points, named colors
 │       ├── matrix.ts     # Vec3/Mat3 (row-major, replaces gl-matrix)
-│       ├── utils.ts      # conversions via XYZ, mixColors, gamutMap
+│       ├── conversions/  # focused per-family converters (hex, kelvin, lab, …)
+│       ├── dispatch.ts   # color2(), DIRECT_PATHS, gamutMap dispatch
 │       ├── normalize.ts  # color normalization to [0,1], space conversion
 │       ├── gamut.ts      # Ottosson analytical sRGB gamut mapping
 │       └── colorFilter.ts # CSS filter solver (SPSA)
+├── quantize/             # image color quantization
+│   ├── index.ts          # quantizePixels, dominantColor (public API)
+│   ├── cluster.ts        # MMCQ median cut, k-means++, JND dedup
+│   └── types.ts          # QuantizeOptions, QuantizedColor
 └── transform/
     └── decompose.ts      # 2D/3D matrix decomposition, quaternion slerp
-
-test/                     # vitest unit tests (24 files)
-e2e/                      # playwright E2E (14 specs)
-demo/                     # Vue 3.5 color picker (reka-ui, Tailwind)
-api/                      # Hono + MongoDB palette API (Docker)
-docs/                     # color-theory.md, gamut-mapping.md
-assets/docs/              # 10 color space reference pages
 ```
 
 ## Color Spaces
 
 All conversions route through the **XYZ D65** hub, enabling any-to-any conversion. Perceptual spaces (OKLab, Lab) use D50 natively with Bradford chromatic adaptation where needed.
 
-Each color space is documented in [`assets/docs/`](assets/docs/)—historical context, component ranges, conversion functions, and practical applications.
+Each color space is documented in [`assets/docs/`](assets/docs/), therein with historical context, component ranges, conversion functions, and practical applications.
 
 ### Gamut Mapping
 
 Out-of-gamut colors are mapped using Björn Ottosson's analytical sRGB algorithm: a polynomial initial guess refined by a single Halley's method step (cubic convergence). Significantly faster than CSS Color 4's iterative binary search. Hue is preserved exactly; an adaptive `L0` formula blends between chroma reduction and mid-gray anchoring.
 
-See [`docs/gamut-mapping.md`](docs/gamut-mapping.md) for the full treatment.
-
-## Easing
-
-30+ timing functions covering the CSS `<easing-function>` grammar plus bounce and back. `CSSCubicBezier` solves via Newton-Raphson with bisection fallback; `cssLinear()` implements CSS Easing Level 2 piecewise-linear with gap filling per spec; stepped easings support all four jump terms.
-
-## Transforms
-
-CSS `matrix()` and `matrix3d()` decomposition per the CSSOM View and CSS Transforms specs. 3D uses Gram-Schmidt orthogonalization + quaternion extraction. `slerp` for rotation interpolation. `interpolateDecomposed()` for full transform blending.
-
-## Palette API
+See [`docs/colors/gamut-mapping.md`](docs/colors/gamut-mapping.md) for the full treatment.
 
-The [demo](https://color.babb.dev) is backed by a palette API for saving, sharing, and voting on color palettes. Users register via `POST /sessions`, which mints a UUID token and a four-word slug—no accounts required. Palettes are slug-addressed, votable (atomic toggle), and sortable by popularity or recency. A color name registry lets users propose names for CSS colors; admins approve or reject through a moderation queue.
+### Color Quantization
 
-Hono + MongoDB, Dockerized. See [`api/README.md`](api/README.md) for endpoints, schema, and deployment.
+`quantizePixels()` extracts a perceptual palette from raw image data. The pipeline operates natively in OKLab—MMCQ pre-clustering, k-means++ with chroma-weighted distance, JND deduplication.
 
-| Feature           | Mechanism                                                                                                    |
-| ----------------- | ------------------------------------------------------------------------------------------------------------ |
-| **Sessions**      | `POST /sessions` → UUID token + user slug; stored with hashed IP; 30-day TTL                                  |
-| **Palettes**      | CRUD by slug; 1–50 color stops with CSS string + optional name + position                                    |
-| **Voting**        | `POST /palettes/:slug/vote` — idempotent toggle; unique composite index on `{userSlug, paletteSlug}`         |
-| **Color names**   | `POST /colors/propose` → admin approval queue → `GET /colors/approved` feeds the demo's custom name registry |
-| **Rate limiting** | 60 reads/min, 10 writes/min per IP (in-memory, rightmost X-Forwarded-For)                                    |
+```ts
+import { quantizePixels, dominantColor } from "@mkbabb/value.js";
 
-### Palette System Flow (Frontend + API)
+const palette = quantizePixels(pixels, width, height, { k: 6 });
+const dominant = dominantColor(pixels, width, height);
+```
 
-1. **Save locally** (`PaletteForm` / `usePaletteStore`): stores palettes in browser storage (`color-palettes`) for instant local recall.
-2. **Publish** (`PaletteDialog`): ensures a session (`POST /sessions`), then publishes via `POST /palettes` with `X-Session-Token`.
-3. **Browse + vote** (`Browse` tab): fetches `GET /palettes` and toggles votes with `POST /palettes/:slug/vote` (server maintains atomic vote counts).
-4. **Suggest color names** (`ColorInput` propose form): ensures session, then submits `POST /colors/propose` for moderation.
-5. **Admin moderation** (`AdminPanel`): token login (`Authorization: Bearer ...`), queue from `GET /admin/queue`, actions for approve/reject + feature/delete.
+See [`docs/colors/quantization.md`](docs/colors/quantization.md) for the full pipeline.
 
-### Validation
+## Easing
 
-- **API smoke (live backend)**: session creation, publish/list/get, vote toggle, rename, propose, admin queue, approve, feature, delete.
-- **Playwright live integration**: [`e2e/palette-api-live.spec.ts`](e2e/palette-api-live.spec.ts) validates save/publish/vote/propose/admin end-to-end against a real API.
+30+ timing functions covering the CSS `<easing-function>` grammar plus bounce and back. `CSSCubicBezier` solves via Newton-Raphson with bisection fallback; `cssLinear()` implements CSS Easing Level 2 piecewise-linear with gap filling per spec; stepped easings support all four jump terms.
 
-```bash
-# 1) Start API (example)
-MONGODB_URI=mongodb://127.0.0.1:27019/palette-e2e ADMIN_TOKEN=test-admin-token PORT=3100 npm --prefix api run dev
+## Transforms
 
-# 2) Run live frontend + backend integration
-PALETTE_API_E2E=1 VITE_API_URL=http://127.0.0.1:3100 npx playwright test e2e/palette-api-live.spec.ts --project=desktop
-```
+CSS `matrix()` and `matrix3d()` decomposition per the CSSOM View and CSS Transforms specs. 3D uses Gram-Schmidt orthogonalization + quaternion extraction. `slerp` for rotation interpolation. `interpolateDecomposed()` for full transform blending.
 
-## Sources, acknowledgements, &c.
+## Sources, acknowledgements, & c.
 
 - Ottosson, B. (2020). [A perceptual color space for image processing](https://bottosson.github.io/posts/oklab/). — OKLab: the perceptual color space used for `color-mix()` and gamut mapping.
 - Ottosson, B. (2021). [sRGB gamut clipping](https://bottosson.github.io/posts/gamutclipping/). — Analytical gamut mapping algorithm (cubic boundary + Halley's method).
@@ -145,8 +131,4 @@ PALETTE_API_E2E=1 VITE_API_URL=http://127.0.0.1:3100 npx playwright test e2e/pal
 - Lindbloom, B. [XYZ to Correlated Color Temperature](http://www.brucelindbloom.com/index.html?Eqn_XYZ_to_T.html). — CCT conversion reference.
 - [`@mkbabb/parse-that`](https://github.com/mkbabb/parse-that) — Parser combinators powering the CSS value grammar.
 
-See [`docs/color-theory.md`](docs/color-theory.md) for the full bibliography.
-
-## License
-
-GPL-3.0-only
+See [`docs/colors/theory.md`](docs/colors/theory.md) for the full bibliography.

package/dist/easing.d.ts

@@ -1,3 +1,10 @@
+/**
+ * A timing function (a.k.a. easing function): maps progress
+ * `t ∈ [0, 1]` to an eased output (typically `∈ [0, 1]`, but easings
+ * such as `bounceInEase` overshoot). Canonical home for the type
+ * (keyframes.js parallel-declares the same shape — keep parity here).
+ */
+export type TimingFunction = (t: number) => number;
 export declare function linear(t: number): number;
 /**
  * CSS Easing Level 2 `linear()` — piecewise-linear timing function.
@@ -24,6 +31,11 @@ export declare function easeInCubic(t: number): number;
 export declare function easeOutCubic(t: number): number;
 export declare function easeInOutCubic(t: number): number;
 export declare function smoothStep3(t: number): number;
+/**
+ * Solve X(t) = x for t using Newton-Raphson with bisection fallback.
+ * X(t) = 3(1-t)^2*t*x1 + 3(1-t)*t^2*x2 + t^3
+ */
+export declare function solveCubicBezierX(x: number, x1: number, x2: number, epsilon?: number): number;
 export declare const CSSCubicBezier: (x1: number, y1: number, x2: number, y2: number) => (x: number) => number;
 export declare function easeInBounce(t: number): number;
 export declare function bounceInEase(t: number): number;
@@ -44,15 +56,52 @@ export declare const jumpTerms: readonly ["jump-start", "jump-end", "jump-none",
 export declare function steppedEase(steps: number, jumpTerm?: (typeof jumpTerms)[number]): (t: number) => number;
 export declare function stepStart(): (t: number) => number;
 export declare function stepEnd(): (t: number) => number;
+/**
+ * Canonical cubic-bezier control-point tables for every CSS timing
+ * function expressible as a bezier curve. The CSS spec only defines the
+ * four "standard" keywords (ease, ease-in, ease-out, ease-in-out), but
+ * the sine/quad/cubic/expo/circ/back families used throughout the
+ * animation ecosystem have well-known bezier approximations — these are
+ * the values popularised by Robert Penner and shipped by libraries like
+ * GSAP, anime.js, and the Material Design curves.
+ *
+ * Keeping all of these in value.js means every consumer (keyframes.js,
+ * bbnf-buddy, future editors) can ask "is this name a bezier curve?"
+ * and "what are its control points?" from one source of truth, rather
+ * than hand-rolling parallel tables.
+ */
 export declare const bezierPresets: {
+    readonly linear: readonly [0, 0, 1, 1];
     readonly ease: readonly [0.25, 0.1, 0.25, 1];
     readonly "ease-in": readonly [0.42, 0, 1, 1];
     readonly "ease-out": readonly [0, 0, 0.58, 1];
     readonly "ease-in-out": readonly [0.42, 0, 0.58, 1];
+    readonly "ease-in-sine": readonly [0.47, 0, 0.745, 0.715];
+    readonly "ease-out-sine": readonly [0.39, 0.575, 0.565, 1];
+    readonly "ease-in-out-sine": readonly [0.445, 0.05, 0.55, 0.95];
+    readonly "ease-in-quad": readonly [0.55, 0.085, 0.68, 0.53];
+    readonly "ease-out-quad": readonly [0.25, 0.46, 0.45, 0.94];
+    readonly "ease-in-out-quad": readonly [0.455, 0.03, 0.515, 0.955];
+    readonly "ease-in-cubic": readonly [0.55, 0.055, 0.675, 0.19];
+    readonly "ease-out-cubic": readonly [0.215, 0.61, 0.355, 1];
+    readonly "ease-in-out-cubic": readonly [0.645, 0.045, 0.355, 1];
+    readonly "ease-in-expo": readonly [0.95, 0.05, 0.795, 0.035];
+    readonly "ease-out-expo": readonly [0.19, 1, 0.22, 1];
+    readonly "ease-in-out-expo": readonly [1, 0, 0, 1];
+    readonly "ease-in-circ": readonly [0.6, 0.04, 0.98, 0.335];
+    readonly "ease-out-circ": readonly [0.075, 0.82, 0.165, 1];
+    readonly "ease-in-out-circ": readonly [0.785, 0.135, 0.15, 0.86];
     readonly "ease-in-back": readonly [0.6, -0.28, 0.735, 0.045];
     readonly "ease-out-back": readonly [0.175, 0.885, 0.32, 1.275];
     readonly "ease-in-out-back": readonly [0.68, -0.55, 0.265, 1.55];
 };
+/**
+ * Short human descriptions for every timing-function name value.js knows
+ * about — bezier presets, analytic functions, and step variants. Editors
+ * and demos can surface these as tooltip copy without hand-maintaining a
+ * parallel map.
+ */
+export declare const timingFunctionDescriptions: Record<string, string>;
 export declare const timingFunctions: {
     readonly linear: typeof linear;
     readonly easeInQuad: typeof easeInQuad;

package/dist/index.d.ts

@@ -1,29 +1,40 @@
 export { ValueUnit, FunctionValue, ValueArray } from './units';
 export type { InterpolatedVar } from './units';
-export { ABSOLUTE_LENGTH_UNITS, RELATIVE_LENGTH_UNITS, LENGTH_UNITS, TIME_UNITS, ANGLE_UNITS, PERCENTAGE_UNITS, FREQUENCY_UNITS, RESOLUTION_UNITS, FLEX_UNITS, COMPUTED_UNITS, STRING_UNITS, COLOR_UNITS, UNITS, BLACKLISTED_COALESCE_UNITS, STYLE_NAMES, } from './units/constants';
+export { ABSOLUTE_LENGTH_UNITS, RELATIVE_LENGTH_UNITS, LENGTH_UNITS, TIME_UNITS, ANGLE_UNITS, PERCENTAGE_UNITS, FREQUENCY_UNITS, RESOLUTION_UNITS, FLEX_UNITS, COMPUTED_UNITS, UNITS, STYLE_NAMES, } from './units/constants';
 export type { MatrixValues } from './units/constants';
 export { isColorUnit, flattenObject, unflattenObject, unflattenObjectToString, isCSSStyleName, unpackMatrixValues, convertAbsoluteUnitToPixels, convertToPixels, convertToMs, convertToDegrees, convertToHz, convertToDPI, convert2, } from './units/utils';
 export { getComputedValue, normalizeNumericUnits, normalizeValueUnits, } from './units/normalize';
+export type { NormalizeValueUnitsOptions } from './units/normalize';
+export { lerpValue, lerpComputedValue, lerpColorValue, lerpNumericValue, prepareInterpVar, } from './units/interpolate';
 export { Color, RGBColor, HSLColor, HSVColor, HWBColor, LABColor, LCHColor, OKLABColor, OKLCHColor, XYZColor, KelvinColor, LinearSRGBColor, DisplayP3Color, AdobeRGBColor, ProPhotoRGBColor, Rec2020Color, } from './units/color';
 export type { ColorSpaceMap } from './units/color';
 export { RGBA_MAX, ALPHA_RANGE, RGB_RANGE, UNIT_RANGE, HUE_RANGE, COLOR_SPACE_RANGES, ALPHA_DENORM_UNIT, COLOR_SPACE_DENORM_UNITS, COLOR_SPACE_NAMES, WHITE_POINT_D65, WHITE_POINT_D50, WHITE_POINT_D65_D50, WHITE_POINT_D50_D65, WHITE_POINTS, XYZ_TO_LMS_MATRIX, LMS_TO_XYZ_MATRIX, LMS_TO_OKLAB_MATRIX, OKLAB_TO_LMS_MATRIX, LMS_TO_LINEAR_SRGB, LINEAR_SRGB_TO_LMS, OKLAB_TO_LMS_COEFF, GAMUT_SECTOR_COEFFICIENTS, COLOR_NAMES, } from './units/color/constants';
 export type { ColorSpace, WhitePoint } from './units/color/constants';
 export { transformMat3, transposeMat3, multiplyMat3, invertMat3, } from './units/color/matrix';
 export type { Vec3, Mat3 } from './units/color/matrix';
-export { getFormattedColorSpaceRange, hex2rgb, rgb2hex, kelvin2rgb, rgb2kelvin, hsv2hsl, hsl2hsv, hwb2hsl, hsl2hwb, rgb2hsl, hsl2rgb, xyz2lab, lab2xyz, srgbToLinear, linearToSrgb, rgb2xyz, xyz2rgb, lch2lab, lab2lch, oklab2xyz, xyz2oklab, oklab2lab, lab2oklab, oklab2oklch, oklch2oklab, oklch2lab, lab2oklch, hsl2xyz, xyz2hsl, hsv2xyz, xyz2hsv, hwb2xyz, xyz2hwb, lch2xyz, xyz2lch, oklch2xyz, xyz2oklch, kelvin2xyz, xyz2kelvin, adobeRgbToLinear, linearToAdobeRgb, proPhotoToLinear, linearToProPhoto, rec2020ToLinear, linearToRec2020, linearSrgb2xyz, xyz2linearSrgb, displayP32xyz, xyz2displayP3, adobeRgb2xyz, xyz2adobeRgb, proPhoto2xyz, xyz2proPhoto, rec20202xyz, xyz2rec2020, color2, gamutMap, interpolateHue, mixColors, CYLINDRICAL_HUE_COMPONENT, } from './units/color/utils';
-export type { HueInterpolationMethod } from './units/color/utils';
+export { getFormattedColorSpaceRange, color2, gamutMap, interpolateHue, mixColors, CYLINDRICAL_HUE_COMPONENT, computeSafeAccent, safeAccentColor, needsContrastAdjustment, getOklchLightness, } from './units/color/dispatch';
+export type { HueInterpolationMethod } from './units/color/dispatch';
+export { mixColorsN } from './units/color/mix';
 export { normalizeColorUnitComponent, normalizeColor, normalizeColorUnit, colorUnit2, normalizeColorUnits, } from './units/color/normalize';
-export { DELTA_E_OK_JND, deltaEOK, oklabToLinearSRGB, isInSRGBGamut, computeMaxSaturation, findCusp, findGamutIntersection, gamutMapOKLab, srgbToOKLab, gamutMapSRGB, } from './units/color/gamut';
+export { DELTA_E_OK_JND, deltaEOK, oklabToLinearSRGB, isInSRGBGamut, computeMaxSaturation, findCusp, findGamutIntersection, gamutMapOKLab, srgbToOKLab, gamutMapSRGB, rawOklabToOklch, rawOklchToOklab, oklabToRgb255, } from './units/color/gamut';
 export { clamp, scale, lerp, logerp, deCasteljau, cubicBezier, interpBezier, cubicBezierToSVG, cubicBezierToString, } from './math';
 export { FRAME_RATE, isObject, clone, arrayEquals, sleep, waitUntil, debounce, createHash, memoize, hyphenToCamelCase, camelCaseToHyphen, seekPreviousValue, requestAnimationFrame, cancelAnimationFrame, } from './utils';
 export type { MemoizeOptions } from './utils';
 export { rgb2ColorFilter, cssFiltersToString } from './units/color/colorFilter';
-export { linear, easeInQuad, easeOutQuad, easeInOutQuad, easeInCubic, easeOutCubic, easeInOutCubic, smoothStep3, CSSCubicBezier, easeInBounce, bounceInEase, bounceInEaseHalf, bounceOutEase, bounceOutEaseHalf, bounceInOutEase, easeInSine, easeOutSine, easeInOutSine, easeInCirc, easeOutCirc, easeInOutCirc, easeInExpo, easeOutExpo, easeInOutExpo, jumpTerms, steppedEase, stepStart, stepEnd, cssLinear, bezierPresets, timingFunctions, } from './easing';
-export type { LinearStop } from './easing';
+export { linear, easeInQuad, easeOutQuad, easeInOutQuad, easeInCubic, easeOutCubic, easeInOutCubic, smoothStep3, CSSCubicBezier, solveCubicBezierX, easeInBounce, bounceInEase, bounceInEaseHalf, bounceOutEase, bounceOutEaseHalf, bounceInOutEase, easeInSine, easeOutSine, easeInOutSine, easeInCirc, easeOutCirc, easeInOutCirc, easeInExpo, easeOutExpo, easeInOutExpo, jumpTerms, steppedEase, stepStart, stepEnd, cssLinear, bezierPresets, timingFunctions, timingFunctionDescriptions, } from './easing';
+export type { LinearStop, TimingFunction } from './easing';
 export { CSS_WIDE_KEYWORDS, CSSString, CSSFunction, CSSJSON, CSSValues, parseCSSValue, parseCSSPercent, parseCSSTime, } from './parsing';
-export { CSSValueUnit, parseCSSValueUnit } from './parsing/units';
+export { parseCSSStylesheet } from './parsing/stylesheet';
+export type { Stylesheet, StylesheetItem, KeyframeRule, KeyframeSelector, Declaration, PropertyDescriptor, } from './parsing/stylesheet';
+export { extractKeyframes, extractProperties, extractStyleRules, extractAnimationOptions, } from './parsing/extract';
+export type { CSSAnimationOptions } from './parsing/extract';
+export { parseAnimationShorthand, reverseAnimationShorthand, } from './parsing/animation-shorthand';
+export { serializeStylesheet, serializeStylesheetItem, serializeDeclaration, serializeKeyframeSelector, formatCSS, stylesheetToString, } from './parsing/serialize';
+export { CSSValueUnit, parseCSSValueUnit, reverseCSSTime, reverseCSSIterationCount, } from './parsing/units';
 export { evaluateMathFunction } from './parsing/math';
-export { CSSColor, parseCSSColor } from './parsing/color';
+export { CSSColor, parseCSSColor, registerColorNames, clearCustomColorNames, getCustomColorNames, } from './parsing/color';
 export { istring, identifier, none, integer, number, succeed, fail, tryParse, parseResult, } from './parsing/utils';
+export { quantizePixels, dominantColor } from './quantize';
+export type { QuantizeOptions, QuantizedColor } from './quantize';
 export { decomposeMatrix2D, decomposeMatrix3D, recomposeMatrix3D, slerp, interpolateDecomposed, } from './transform/decompose';
 export type { DecomposedMatrix2D, DecomposedMatrix3D, Vec4, Mat4, } from './transform/decompose';

package/dist/math.d.ts

@@ -1,6 +1,6 @@
 export declare function clamp(value: number, min: number, max: number): number;
 export declare function scale(value: number, fromMin: number, fromMax: number, toMin?: number, toMax?: number): number;
-export declare function lerp(t: number, start: number, end: number): number;
+export declare function lerp(start: number, end: number, t: number): number;
 export declare function logerp(t: number, start: number, end: number): number;
 export declare function deCasteljau(t: number, points: number[]): number;
 export declare function cubicBezier(t: number, x1: number, y1: number, x2: number, y2: number): number[];

package/dist/parsing/animation-shorthand.d.ts

@@ -0,0 +1,19 @@
+import { CSSAnimationOptions } from './extract';
+/**
+ * Parse the value of an `animation` shorthand declaration into one
+ * options object per comma-segment.
+ *
+ * Per CSS Animations spec, `animation: 1s ease-in, 500ms linear`
+ * declares two animations. This function returns both; callers that
+ * only support a single animation should take `[0]`.
+ */
+export declare const parseAnimationShorthand: import('../utils').Memoized<(input: string) => CSSAnimationOptions[]>;
+/**
+ * Reverse: emit a single `animation` shorthand string from an options
+ * object. Always emits in canonical order:
+ * `<duration> <timing-function> <delay> <iteration-count>
+ *  <direction> <fill-mode> <composition> <name>`.
+ *
+ * Fields that are unset are omitted entirely (no `0s` placeholders).
+ */
+export declare const reverseAnimationShorthand: (opts: CSSAnimationOptions) => string;

package/dist/parsing/color.d.ts

@@ -13,8 +13,8 @@ type ComponentExpr = {
     type: "none";
 };
 export declare const CSSColor: {
-    Value: Parser<ValueUnit<any, string | undefined>>;
-    colorValue: Parser<ValueUnit<any, string | undefined>>;
+    Value: Parser<ValueUnit<any, string>>;
+    colorValue: Parser<ValueUnit<any, string>>;
     componentExpr: Parser<ComponentExpr>;
     sep: Parser<string>;
     alphaSep: Parser<string>;
@@ -23,5 +23,12 @@ export declare const CSSColor: {
 export declare function registerColorNames(names: Record<string, string>): void;
 export declare function clearCustomColorNames(): void;
 export declare function getCustomColorNames(): ReadonlyMap<string, string>;
-export declare function parseCSSColor(input: string): ValueUnit;
+/**
+ * Parse a CSS color string into a `ValueUnit<Color>`. Memoised — the returned
+ * ValueUnit is shared across callers, so callers MUST NOT mutate it. Clone
+ * before mutating if a per-call instance is needed.
+ *
+ * The cache is invalidated by `registerColorNames` and `clearCustomColorNames`.
+ */
+export declare const parseCSSColor: import('../utils').Memoized<(input: string) => ValueUnit>;
 export {};

package/dist/parsing/extract.d.ts

@@ -0,0 +1,48 @@
+import { Declaration, KeyframeRule, PropertyDescriptor, Stylesheet } from './stylesheet';
+/**
+ * Animation options as expressed in CSS — a CSS-spec subset shared by
+ * `animation` shorthand and the individual `animation-*` longhand
+ * properties. Renderer-specific options (WAAPI, color space, hue
+ * method) are not represented here; consumers extend this type.
+ */
+export type CSSAnimationOptions = {
+    name?: string;
+    duration?: number;
+    delay?: number;
+    iterationCount?: number;
+    direction?: "normal" | "reverse" | "alternate" | "alternate-reverse";
+    fillMode?: "none" | "forwards" | "backwards" | "both";
+    timingFunction?: string;
+    composition?: "replace" | "add" | "accumulate";
+};
+/**
+ * Group every `@keyframes` block in the stylesheet by name. Unnamed
+ * blocks are keyed by the empty string. When two `@keyframes` rules
+ * share a name, their rule lists are concatenated (CSS cascade order).
+ */
+export declare const extractKeyframes: (s: Stylesheet) => Map<string, KeyframeRule[]>;
+/**
+ * Index every `@property` registration by its custom property name.
+ * Later registrations override earlier ones.
+ */
+export declare const extractProperties: (s: Stylesheet) => Map<string, PropertyDescriptor>;
+/** Return every top-level qualified rule (`.foo { ... }`). */
+export declare const extractStyleRules: (s: Stylesheet) => {
+    selectors: string[];
+    declarations: Declaration[];
+}[];
+/**
+ * Walk the stylesheet's top-level style rules and merge every
+ * recognised `animation-*` longhand into a single options object.
+ *
+ * Shorthand `animation: ...` is handled by `parseAnimationShorthand`
+ * (a separate entry) — we don't re-tokenise it here. If a style rule
+ * has both shorthand and longhand declarations, the consumer is
+ * expected to call `parseAnimationShorthand` itself and merge.
+ *
+ * Longhand declarations later in the stylesheet override earlier ones
+ * (CSS cascade). Cross-rule merging is intentional — most stylesheets
+ * keep all `animation-*` for one animation in a single rule, but the
+ * extractor stays robust either way.
+ */
+export declare const extractAnimationOptions: (s: Stylesheet) => CSSAnimationOptions;

package/dist/parsing/index.d.ts

@@ -1,32 +1,17 @@
 import { Parser } from '@mkbabb/parse-that';
 import { FunctionValue, ValueArray, ValueUnit } from '../units';
 export declare const CSS_WIDE_KEYWORDS: readonly ["inherit", "initial", "unset", "revert", "revert-layer"];
-export declare const CSSString: Parser<ValueUnit<string, string | undefined>>;
+export declare const CSSString: Parser<ValueUnit<string, string>>;
 export declare const CSSFunction: {
     Function: Parser<any>;
     Value: Parser<any>;
     FunctionArgs: Parser<ValueArray<any>>;
 };
-export declare const CSSJSON: Parser<ValueUnit<any, string>>;
+export declare const CSSJSON: Parser<ValueUnit<any, "json">>;
 export declare const CSSValues: {
     Value: Parser<any>;
     Values: Parser<any[]>;
 };
-export declare const parseCSSValue: ((input: string) => ValueUnit | FunctionValue) & {
-    cache: Map<string, {
-        value: ValueUnit<any, string | undefined> | FunctionValue<any, string>;
-        timestamp: number;
-    }>;
-};
-export declare const parseCSSPercent: ((input: string | number) => number) & {
-    cache: Map<string, {
-        value: number;
-        timestamp: number;
-    }>;
-};
-export declare const parseCSSTime: ((input: string) => number) & {
-    cache: Map<string, {
-        value: number;
-        timestamp: number;
-    }>;
-};
+export declare const parseCSSValue: import('../utils').Memoized<(input: string) => ValueUnit | FunctionValue>;
+export declare const parseCSSPercent: import('../utils').Memoized<(input: string | number) => number>;
+export declare const parseCSSTime: import('../utils').Memoized<(input: string) => number>;

package/dist/parsing/serialize.d.ts

@@ -0,0 +1,24 @@
+import { Declaration, KeyframeSelector, Stylesheet, StylesheetItem } from './stylesheet';
+export declare const serializeKeyframeSelector: (s: KeyframeSelector) => string;
+export declare const serializeDeclaration: (d: Declaration) => string;
+export declare const serializeStylesheetItem: (item: StylesheetItem) => string;
+/**
+ * Emit a `Stylesheet` AST as a CSS string. Items are separated by a
+ * single blank line. The output is structurally equivalent to the
+ * input (modulo whitespace) when round-tripped through
+ * `parseCSSStylesheet`.
+ */
+export declare const serializeStylesheet: (s: Stylesheet) => string;
+/**
+ * Format a CSS string via Prettier's PostCSS parser. Prettier and its
+ * PostCSS plugin are loaded lazily via dynamic `import()` — calling
+ * code that never invokes `formatCSS` doesn't pay the bundle cost.
+ *
+ * Use this for human-readable output (editors, file dumps). Programs
+ * that read the AST directly should not need it.
+ */
+export declare function formatCSS(css: string, printWidth?: number): Promise<string>;
+/**
+ * Convenience: serialise + format in one call.
+ */
+export declare function stylesheetToString(s: Stylesheet, printWidth?: number): Promise<string>;

package/dist/parsing/stylesheet.d.ts

@@ -0,0 +1,44 @@
+import { ValueArray } from '../units';
+export type Declaration = {
+    name: string;
+    value: ValueArray;
+    important: boolean;
+};
+export type KeyframeSelector = {
+    kind: "percent";
+    value: number;
+} | {
+    kind: "named";
+    name: "entry" | "exit" | "cover" | "contain";
+};
+export type KeyframeRule = {
+    selectors: KeyframeSelector[];
+    declarations: Declaration[];
+    timingFunction?: string;
+    composition?: "replace" | "add" | "accumulate";
+};
+export type PropertyDescriptor = {
+    syntax?: string;
+    inherits?: boolean;
+    initialValue?: ValueArray;
+};
+export type StylesheetItem = {
+    kind: "keyframes";
+    name?: string;
+    rules: KeyframeRule[];
+} | {
+    kind: "property";
+    name: string;
+    descriptor: PropertyDescriptor;
+} | {
+    kind: "style";
+    selectors: string[];
+    declarations: Declaration[];
+} | {
+    kind: "unknown";
+    atName: string;
+    prelude: string;
+    body: string | null;
+};
+export type Stylesheet = StylesheetItem[];
+export declare const parseCSSStylesheet: import('../utils').Memoized<(input: string) => Stylesheet>;

package/dist/parsing/units.d.ts

@@ -6,14 +6,32 @@ export declare const CSSValueUnit: {
     Length: Parser<ValueUnit<number, string>>;
     Angle: Parser<ValueUnit<number, string>>;
     Time: Parser<ValueUnit<number, string>>;
-    TimePercentage: Parser<ValueUnit<any, string | undefined>>;
+    TimePercentage: Parser<ValueUnit<any, string>>;
     Frequency: Parser<ValueUnit<number, string>>;
     Resolution: Parser<ValueUnit<number, string>>;
     Flex: Parser<ValueUnit<number, string>>;
-    Percentage: Parser<ValueUnit<any, string | undefined>>;
-    Color: Parser<ValueUnit<any, string | undefined>>;
-    Slash: Parser<ValueUnit<string, string>>;
-    Value: Parser<ValueUnit<any, string | undefined>>;
+    Percentage: Parser<ValueUnit<any, string>>;
+    Color: Parser<ValueUnit<any, string>>;
+    Slash: Parser<ValueUnit<string, "string">>;
+    Value: Parser<ValueUnit<any, string>>;
     sep: Parser<string>;
 };
-export declare function parseCSSValueUnit(input: string): ValueUnit;
+/**
+ * Parse a CSS dimension/value string into a `ValueUnit`. Memoised — the
+ * returned `ValueUnit` is shared across callers, so callers MUST NOT mutate it.
+ * Mirrors the memo contract of the sibling `parseCSSValue`/`parseCSSColor`.
+ */
+export declare const parseCSSValueUnit: import('../utils').Memoized<(input: string) => ValueUnit>;
+/**
+ * Format a millisecond duration as a CSS time string. Emits `<n>s`
+ * for durations ≥ 5 s (where seconds become more readable than
+ * milliseconds); otherwise `<n>ms`. Threshold matches the historical
+ * keyframes.js convention so round-trips don't drift.
+ */
+export declare function reverseCSSTime(time: number): string;
+/**
+ * Format an iteration count for the `animation-iteration-count`
+ * property. `Infinity` becomes the keyword `infinite`; finite values
+ * render as their decimal representation.
+ */
+export declare function reverseCSSIterationCount(count: number): string;

package/dist/parsing/utils.d.ts

@@ -12,6 +12,11 @@ export declare function fail(message: string): Parser<never>;
 /**
  * Try to parse; return the result or throw on failure.
  * Equivalent to Parsimmon's `.tryParse()`.
+ *
+ * The thrown error includes a 16-char context window (8 before / 8 after
+ * the failure offset) so callers — particularly the demo's color-picker
+ * error toasts — can pinpoint where the parse derailed. (E.W1 Lane D /
+ * E-AUDIT-5 §9 item 11.)
  */
 export declare function tryParse<T>(parser: Parser<T>, input: string): T;
 /**