@mkbabb/value.js 0.10.0 → 0.11.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Michael Babb
+Copyright (c) 2026 Mike Babb
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -33,15 +33,6 @@ 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
@@ -132,3 +123,12 @@ CSS `matrix()` and `matrix3d()` decomposition per the CSSOM View and CSS Transfo
 - [`@mkbabb/parse-that`](https://github.com/mkbabb/parse-that) — Parser combinators powering the CSS value grammar.
 
 See [`docs/colors/theory.md`](docs/colors/theory.md) for the full bibliography.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). The README shape follows the perimeter-level
+[canonical README shape](https://github.com/mkbabb/glass-ui/blob/master/docs/precepts/canonical-readme-shape.md).
+
+## License
+
+[MIT](./LICENSE) © 2026 Mike Babb.

package/dist/index.d.ts

@@ -3,7 +3,7 @@ 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, 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 { getComputedValue, normalizeNumericUnits, normalizeValueUnits, bumpLayoutEpoch, getLayoutEpoch, } 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';
@@ -12,12 +12,13 @@ export { RGBA_MAX, ALPHA_RANGE, RGB_RANGE, UNIT_RANGE, HUE_RANGE, COLOR_SPACE_RA
 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, color2, gamutMap, interpolateHue, mixColors, CYLINDRICAL_HUE_COMPONENT, computeSafeAccent, safeAccentColor, needsContrastAdjustment, getOklchLightness, } from './units/color/dispatch';
+export { getFormattedColorSpaceRange, color2, gamutMap, interpolateHue, mixColors, CYLINDRICAL_HUE_COMPONENT, } from './units/color/dispatch';
 export type { HueInterpolationMethod } from './units/color/dispatch';
+export { computeSafeAccent, safeAccentColor, needsContrastAdjustment, getOklchLightness, } from './units/color/contrast';
 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, rawOklabToOklch, rawOklchToOklab, oklabToRgb255, } from './units/color/gamut';
-export { clamp, scale, lerp, logerp, deCasteljau, cubicBezier, interpBezier, cubicBezierToSVG, cubicBezierToString, } from './math';
+export { clamp, scale, lerp, lerpArray, 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';

package/dist/math.d.ts

@@ -1,6 +1,22 @@
 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(start: number, end: number, t: number): number;
+/**
+ * SoA (struct-of-arrays) bulk lerp (Wave D2). Interpolates `K` numeric channels
+ * in one flat loop over contiguous `Float64Array`s, writing into a caller-owned
+ * `out` buffer — eliminating the AoS pointer-chase and the per-channel closure
+ * dispatch of K independent `{value}` carriers.
+ *
+ * This is the carrier primitive a numeric-animation SoA substrate adopts; it is
+ * pixel-identical to K independent `lerp()` calls. MEASURE-FIRST (the charter's
+ * land bar): it is SLOWER at K=1 and BITES from K≥2 — measured on this machine
+ * (bench/numeric-soa.mjs) at 1.56× (K=2) → 4.25× (K=64), so callers should use
+ * it only for multi-channel (K≥2) frames. D1 monomorphization is NOT shipped (a
+ * measured non-win, r-interpolation-carrier).
+ *
+ * `start`, `stop`, `out` must share the same length; only `out` is written.
+ */
+export declare function lerpArray(start: Float64Array, stop: Float64Array, t: number, out: Float64Array): Float64Array;
 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/utils.d.ts

@@ -1,6 +1,20 @@
 import { Parser } from '@mkbabb/parse-that';
 /** Case-insensitive string match. Returns the matched portion of the input. */
 export declare const istring: (str: string) => Parser<string>;
+/**
+ * Maximal-munch unit classifier. Consumes the longest identifier-shaped token
+ * and succeeds ONLY when the whole token (case-insensitively) is a member of
+ * `units`; otherwise the parser fails.
+ *
+ * This replaces `any(...units.map(istring))`, which was order-dependent and —
+ * because `istring` compiles a non-anchored RegExp re-flagged sticky `y` by
+ * parse-that — matched a unit as a *prefix* of the continuation: `100vhx`
+ * tokenized `vh` and silently dropped the trailing `x`, and a unit that was a
+ * prefix of a later-declared one would shadow it. Maximal-munch over the full
+ * token removes both hazards (vj-parser-aug §2.2). The canonical declared
+ * spelling is returned so output is byte-identical for every valid unit.
+ */
+export declare const unitParser: (units: readonly string[]) => Parser<string>;
 export declare const identifier: Parser<string>;
 export declare const none: Parser<string>;
 export declare const integer: Parser<number>;

package/dist/units/color/dispatch.d.ts

@@ -3,7 +3,6 @@ import { ColorSpace } from './constants';
 import { hex2rgb, rgb2hex } from './conversions/hex';
 export { hex2rgb, rgb2hex };
 export { deltaEOK, isInSRGBGamut, DELTA_E_OK_JND } from './gamut';
-export { computeSafeAccent, safeAccentColor, needsContrastAdjustment, getOklchLightness, } from './contrast';
 export declare const getFormattedColorSpaceRange: <T extends ColorSpace>(colorSpace: T) => ColorSpaceMap<{
     min: string;
     max: string;

package/dist/units/color/index.d.ts

@@ -271,5 +271,6 @@ export type ColorSpaceMap<T> = {
     "prophoto-rgb": ProPhotoRGBColor<T>;
     rec2020: Rec2020Color<T>;
 };
-export { getFormattedColorSpaceRange, color2, gamutMap, interpolateHue, mixColors, CYLINDRICAL_HUE_COMPONENT, computeSafeAccent, safeAccentColor, needsContrastAdjustment, getOklchLightness, hex2rgb, rgb2hex, } from './dispatch';
+export { getFormattedColorSpaceRange, color2, gamutMap, interpolateHue, mixColors, CYLINDRICAL_HUE_COMPONENT, hex2rgb, rgb2hex, } from './dispatch';
 export type { HueInterpolationMethod } from './dispatch';
+export { computeSafeAccent, safeAccentColor, needsContrastAdjustment, getOklchLightness, } from './contrast';

package/dist/units/index.d.ts

@@ -1,6 +1,7 @@
 import { UNITS } from './constants';
 import { ColorSpace } from './color/constants';
 import { HueInterpolationMethod } from './color/dispatch';
+import { ColorChannelPlan } from './interpolate';
 export { registerColorNames, clearCustomColorNames, getCustomColorNames } from '../parsing/color';
 export declare class ValueUnit<T = any, U extends string = Exclude<(typeof UNITS)[number], undefined> | string> {
     value: T;
@@ -86,4 +87,35 @@ export type InterpolatedVar<T> = {
      * runtime dispatch in `lerpValue` will resolve at call time.
      */
     _lerp?: (t: number, iv: InterpolatedVar<any>) => ValueUnit<any>;
+    /**
+     * Frozen color-channel plan set by `prepareInterpVar` for color ivs (B3).
+     * Drives the closure-free per-frame loop in `lerpColorValue`; absent for
+     * non-color ivs and externally constructed colors (which take the fallback
+     * walk). Typed loosely here to avoid a cycle with `interpolate.ts`.
+     */
+    _colorPlan?: ColorChannelPlan;
+    /**
+     * Resolved computed-endpoint cache set by `lerpComputedValue` for computed
+     * ivs (C1, tranche-F Wave C). A computed leaf (`var`/`calc`) re-resolves
+     * BOTH endpoints against the live box every frame — but the resolved pair
+     * is invariant while the layout epoch is stable, so the first frame after a
+     * (re)resolve stamps `(startN, stopN, unit, target, epoch)` here and every
+     * later frame collapses to a bare `lerp(startN, stopN, t)`. Invalidated
+     * when the target changes or the layout epoch advances (resize). Absent for
+     * non-computed ivs. Typed loosely to avoid a cycle with `interpolate.ts`.
+     */
+    _computedCache?: ComputedEndpointCache;
+};
+/**
+ * The resolved-endpoint cache stamped on a computed `InterpolatedVar` (C1).
+ * `target` and `epoch` are the invalidation keys: a steady frame whose live
+ * target and layout epoch both match the stamp serves `startN`/`stopN`/`unit`
+ * directly; any mismatch re-resolves both endpoints and re-stamps.
+ */
+export type ComputedEndpointCache = {
+    startN: number;
+    stopN: number;
+    unit: string | undefined;
+    target: HTMLElement;
+    epoch: number;
 };

package/dist/units/interpolate.d.ts

@@ -6,9 +6,18 @@ import { ValueUnit, InterpolatedVar } from './index';
  * element's live computed style and lerping the resulting numeric
  * values.
  *
+ * C1 (tranche-F Wave C) — the endpoint cache. The resolved
+ * `(startN, stopN, unit)` pair is invariant while the layout epoch is
+ * stable, so it is cached on the iv (`_computedCache`) the first frame
+ * and every later steady frame collapses to a bare
+ * `lerp(startN, stopN, t)` — no `getComputedValue` memo call, no
+ * `value.toString()`, no forced reflow. The cache busts when the live
+ * target changes or the layout epoch advances (resize → `bumpLayoutEpoch`).
+ * Pixel-identical while the epoch is stable.
+ *
  * Mutates and returns the `value` field of the InterpolatedVar.
  */
-export declare function lerpComputedValue(t: number, { start, stop, value }: InterpolatedVar<any>): ValueUnit<any>;
+export declare function lerpComputedValue(t: number, iv: InterpolatedVar<any>): ValueUnit<any>;
 /**
  * A `Color` at interpolation time: its channels may be raw `number`s (numeric
  * pipeline) or `ValueUnit<number>` wrappers (parser-produced colors). Both
@@ -16,6 +25,20 @@ export declare function lerpComputedValue(t: number, { start, stop, value }: Int
  * branch dispatches between them.
  */
 type InterpColor = Color<ValueUnit<number> | number>;
+/**
+ * Frozen per-frame color-channel plan (B3). Built once at `prepareInterpVar`;
+ * drives `lerpColorValue`'s closure-free hot loop. Parallel arrays (a light SoA)
+ * indexed by channel position: the unwrapped start/stop numbers, the hue
+ * channel index (or -1), the destination ValueUnit ref per channel (or null
+ * when the destination slot is a raw number written via `setChannel`).
+ */
+export type ColorChannelPlan = {
+    keys: readonly string[];
+    startN: Float64Array;
+    stopN: Float64Array;
+    hueIndex: number;
+    dstVU: (ValueUnit<number> | null)[];
+};
 /**
  * Interpolate a colour `ValueUnit` (`unit === "color"`). Walks each
  * channel of the parsed `Color` instance and lerps independently. The

package/dist/units/normalize.d.ts

@@ -2,6 +2,16 @@ import { ValueUnit, InterpolatedVar } from '.';
 import { ColorSpace } from './color/constants';
 import { HueInterpolationMethod } from './color/dispatch';
 import { isColorUnit } from './utils';
+/** The current layout-epoch generation. Bumped on resize. */
+export declare const getLayoutEpoch: () => number;
+/**
+ * Invalidate every layout-epoch-stamped cache (the C1 endpoint cache and the
+ * `getComputedValue` memo) by advancing the generation counter. Call on any
+ * event that changes a computed-unit resolution — a viewport `resize`, a
+ * container `ResizeObserver` callback, a writing-mode flip, etc. Cheap (one
+ * integer increment + one memo clear); the next computed frame re-resolves.
+ */
+export declare const bumpLayoutEpoch: () => number;
 /**
  * Resolve a computed CSS value (`var()`, `calc()`, or other
  * deferred-evaluation unit) against a target element by writing it