@forgeax/engine-math 0.1.23 → 0.1.25

package/README.md

@@ -6,7 +6,7 @@ Pure-function SoA-friendly Vec / Mat / Quat / Color / Euler math library for for
 ## 30-second self-introduction
 
 - **ABI**: `Float32Array & { readonly __<dim>: void }` 七件套（`Vec2 / Vec3 / Vec4 / Quat / Mat3 / Mat4 / Color`）+ `Euler` plain-object；branded 维度互斥（编译期）+ TypedArray 即时上传 GPU（运行期）。
-- **Surface**: 18 namespace × 202 函数（vec2:20 / vec3:21 / vec4:18 / mat3:10 / mat4:33 / quat:23 / euler:6 / color:6 / easing:4 / noise:1 / frustum:4 / ray:9 / ray2:11 / box2:13 / box3:7 / circle2:10 / sphere:5 / f32-to-f16-bytes:1）；单 entry `import { Vec3, vec3, ... } from '@forgeax/engine-math'`。
+- **Surface**: 18 namespace × 203 函数（vec2:20 / vec3:21 / vec4:18 / mat3:10 / mat4:33 / quat:23 / euler:6 / color:7 / easing:4 / noise:1 / frustum:4 / ray:9 / ray2:11 / box2:13 / box3:7 / circle2:10 / sphere:5 / f32-to-f16-bytes:1）；单 entry `import { Vec3, vec3, ... } from '@forgeax/engine-math'`。
 - **Style**: gl-matrix / wgpu-matrix 风纯函数 namespace + out-param-first（`func(out, ...args)`）；零分配；aliasing-safe（`add(v, v, v)` 合法）。
 - **Errors**: 全库静默回退（不抛错、不返回 `null`、不返回 `Result`、不 `console.warn`）；退化语义靠 JSDoc `@degrade` + 本 README §退化策略表 + `*.test-d.ts` 三层共担。
 
@@ -33,7 +33,7 @@ vec3.normalize(v, vec3.create(0, 0, 0));          // v = (0, 0, 0)
 
 > 上述代码覆盖 v0.1 PBR 渲染管线 90% 的典型 transform / projection / shader-uniform 准备路径——LLM 一次扫读即可拿到 "概念→签名→典型流程" 完整闭包（charter 命题 1）。
 
-## quick-ref：18 namespace × 202 函数
+## quick-ref：18 namespace × 203 函数
 
 每 namespace 内函数顺序粗略按 "构造 → 比较 → 算术 → 几何 → 高级" 分组。完整签名以 `.d.ts` JSDoc 为 SSOT。
 
@@ -46,7 +46,7 @@ vec3.normalize(v, vec3.create(0, 0, 0));          // v = (0, 0, 0)
 | **`mat4`** (33) | `create / clone / identity / equals / multiply / transpose / invert / scale / translate / rotate / lookAt / compose / decompose / fromQuat / fromTranslation / fromScaling / fromRotation / perspective / perspectiveNO / perspectiveReverseZ / orthographic / orthographicNO / orthographicReverseZ / transformVec3 / transformPoint / transformDirection / getTranslation / getForward / getUp / getRight / unproject / projectPoint / computeViewProj` |
 | **`quat`** (23) | `create / clone / identity / fromAxisAngle / fromEuler / fromRotationMatrix / fromLookAt / fromUnitVectors / multiply / rotateAxis / slerp / nlerp / invert / conjugate / dot / length / lengthSq / normalize / transformVec3 / eulerY / right / up / forward` |
 | **`euler`** (6) | `create / clone / set / toQuat / fromQuat / fromRotationMatrix` |
-| **`color`** (6) | `create / clone / srgbToLinear / linearToSrgb / fromHex / toHex` |
+| **`color`** (7) | `create / clone / srgbToLinear / linearToSrgb / fromHex / fromCss / toHex` |
 | **`easing`** (4) | `cubicInOut / smoothstep / smootherstep / elasticInOut` — scalar time-remaps (clamp t to [0,1]; Bevy `EaseFunction`; slow-in/slow-out with elastic overshoot). Growable home for further ease variants |
 | **`noise`** (1) | `perlin1d` — 1D Perlin noise returning [-1,1]. Deterministic, smooth (nearby inputs → nearby outputs); canonical permutation table matching Bevy's `2d_screen_shake`. Growable home for 2D/3D/Simplex variants |
 | **`frustum`** (4) | `create / fromViewProjection / intersectsBox / intersectsSphere` |
@@ -238,7 +238,8 @@ const projWebGL = mat4.perspectiveNO(mat4.create(), Math.PI / 4, 16 / 9, 0.1, 10
 const projReverseZ = mat4.perspectiveReverseZ(mat4.create(), Math.PI / 4, 16 / 9, 0.1, 100);
 ```
 
-`orthographic / orthographicNO / orthographicReverseZ` 三档同形（`orthographicReverseZ` 为本库自创扩展，详见末尾对照表脚注）。
+`orthographic / orthographicNO / orthographicReverseZ` 三档同形，位置参数统一为
+`(out, left, right, top, bottom, near, far)`（`orthographicReverseZ` 为本库自创扩展，详见末尾对照表脚注）。
 
 ## 非目标（Non-goals）
 
@@ -255,7 +256,7 @@ const projReverseZ = mat4.perspectiveReverseZ(mat4.create(), Math.PI / 4, 16 / 9
 
 | 版本 | 范围 |
 |:--|:--|
-| **v0.0 (本闭环)** | 18 namespace × 202 函数（含 mat4 / quat 反向 surface 跨类型 transform 4 函数、2D bounds/raycast/cast，以及 easing 标量缓动 + noise 1D Perlin）；branded ABI；3 档 NDC 投影；M1-M6 全 19 AC pass |
+| **v0.0 (本闭环)** | 18 namespace × 203 函数（含 mat4 / quat 反向 surface 跨类型 transform 4 函数、2D bounds/raycast/cast，以及 easing 标量缓动 + noise 1D Perlin）；branded ABI；3 档 NDC 投影；M1-M6 全 19 AC pass |
 | v0.1 (PBR 闭环) | `mat3.fromMat4Scale` 法线矩阵优化路径；`Color.linearToSRGB` GPU 上传专用变体；高级 PBR 工具 |
 | v0.2 (动画闭环) | `quat.squad` Catmull-Rom 球面插值；`euler.lookAt` 自然映射；动画系统消费方向定 |
 | v1.0 (稳定 ABI) | 不再 breaking ABI；coverage 阈值不退步；`@forgeax/engine-math` 正式 `npm publish` |

package/dist/color.d.ts

@@ -39,12 +39,21 @@ export declare function linearToSrgb(out: Color, c: ColorLike): Color;
  *
  * @example
  * ```ts
- * color.fromHex(out, '#ff8000');   // → (1, 0.502, 0, 1)
- * color.fromHex(out, '#ff800080'); // → (1, 0.502, 0, 0.502)
+ * color.fromHex(out, '#ff8000');   // → (1, ~0.216, 0, 1)
+ * color.fromHex(out, '#ff800080'); // → (1, ~0.216, 0, 0.502)
  * color.fromHex(out, '#fff');      // → (0, 0, 0, 1) short form unsupported → silent fall-back
  * ```
  */
 export declare function fromHex(out: Color, hex: string): Color;
+/**
+ * Write a Color from a deterministic CSS color string.
+ *
+ * Supports full and short hex, common named colors, rgb()/rgba() channel
+ * numbers or percentages, and hsl()/hsla() with an optional alpha. RGB
+ * channels are decoded to linear-sRGB; alpha is passed through unchanged.
+ * Unsupported or malformed input silently falls back to opaque black.
+ */
+export declare function fromCss(out: Color, css: string): Color;
 /**
  * Serialize as hex string: alpha=1 → `#rrggbb`; alpha<1 → `#rrggbbaa`.
  *
@@ -55,7 +64,7 @@ export declare function fromHex(out: Color, hex: string): Color;
  *
  * @example
  * ```ts
- * color.toHex(color.create(2, -0.1, 0.5, 1));    // → '#ff0080' (HDR/negative clamp)
+ * color.toHex(color.create(2, -0.1, 0.5, 1));    // → '#ff00bc' (linear HDR/negative clamp)
  * color.toHex(color.create(1, 0, 0, 0.5));        // → '#ff000080'
  * color.toHex(color.create(NaN, 0, 0, NaN));      // → '#000000' (NaN→'00', alpha=NaN takes short form)
  * ```

package/dist/color.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"color.d.ts","sourceRoot":"","sources":["../src/color.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEhD,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AAIjC,mEAAmE;AACnE,wBAAgB,MAAM,CAAC,CAAC,SAAI,EAAE,CAAC,SAAI,EAAE,CAAC,SAAI,EAAE,CAAC,SAAI,GAAG,KAAK,CAExD;AAED,iCAAiC;AACjC,wBAAgB,KAAK,CAAC,CAAC,EAAE,SAAS,GAAG,KAAK,CAEzC;AAgCD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,SAAS,GAAG,KAAK,CAM5D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,SAAS,GAAG,KAAK,CAM5D;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,KAAK,CActD;AAUD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,CAU1C"}
+{"version":3,"file":"color.d.ts","sourceRoot":"","sources":["../src/color.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEhD,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AAIjC,mEAAmE;AACnE,wBAAgB,MAAM,CAAC,CAAC,SAAI,EAAE,CAAC,SAAI,EAAE,CAAC,SAAI,EAAE,CAAC,SAAI,GAAG,KAAK,CAExD;AAED,iCAAiC;AACjC,wBAAgB,KAAK,CAAC,CAAC,EAAE,SAAS,GAAG,KAAK,CAEzC;AAgCD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,SAAS,GAAG,KAAK,CAM5D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,KAAK,EAAE,CAAC,EAAE,SAAS,GAAG,KAAK,CAM5D;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,KAAK,CActD;AA8ID;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,KAAK,CAuDtD;AAUD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,SAAS,GAAG,MAAM,CAU1C"}

package/dist/index.mjs

@@ -487,6 +487,7 @@ var color_exports = {};
 __export(color_exports, {
   clone: () => clone,
   create: () => create4,
+  fromCss: () => fromCss,
   fromHex: () => fromHex,
   linearToSrgb: () => linearToSrgb,
   srgbToLinear: () => srgbToLinear,
@@ -534,15 +535,174 @@ function fromHex(out, hex) {
     out[3] = 1;
     return out;
   }
-  out[0] = Number.parseInt(match[1], 16) / 255;
-  out[1] = Number.parseInt(match[2], 16) / 255;
-  out[2] = Number.parseInt(match[3], 16) / 255;
+  out[0] = srgbChannelToLinear(Number.parseInt(match[1], 16) / 255);
+  out[1] = srgbChannelToLinear(Number.parseInt(match[2], 16) / 255);
+  out[2] = srgbChannelToLinear(Number.parseInt(match[3], 16) / 255);
   out[3] = match[4] !== void 0 ? Number.parseInt(match[4], 16) / 255 : 1;
   return out;
 }
-function toHexByte(v) {
+var CSS_HEX_PATTERN = /^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+var CSS_RGB_PATTERN = /^rgba?\(([^()]*)\)$/i;
+var CSS_HSL_PATTERN = /^hsla?\(([^()]*)\)$/i;
+var CSS_DECIMAL_PATTERN = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/;
+var CSS_NAMED_COLORS = {
+  black: "#000000",
+  blue: "#0000ff",
+  cyan: "#00ffff",
+  fuchsia: "#ff00ff",
+  gray: "#808080",
+  green: "#008000",
+  grey: "#808080",
+  lime: "#00ff00",
+  magenta: "#ff00ff",
+  maroon: "#800000",
+  navy: "#000080",
+  olive: "#808000",
+  orange: "#ffa500",
+  purple: "#800080",
+  red: "#ff0000",
+  silver: "#c0c0c0",
+  teal: "#008080",
+  transparent: "#00000000",
+  white: "#ffffff",
+  yellow: "#ffff00"
+};
+function clamp01(v) {
+  return Math.min(1, Math.max(0, v));
+}
+function parseCssChannel(token) {
+  const trimmed = token.trim();
+  if (trimmed.endsWith("%")) {
+    const raw = trimmed.slice(0, -1).trim();
+    if (!CSS_DECIMAL_PATTERN.test(raw)) return void 0;
+    const value2 = Number(raw);
+    return Number.isFinite(value2) ? clamp01(value2 / 100) : void 0;
+  }
+  if (!CSS_DECIMAL_PATTERN.test(trimmed)) return void 0;
+  const value = Number(trimmed);
+  return Number.isFinite(value) ? clamp01(value / 255) : void 0;
+}
+function parseCssAlpha(token) {
+  const trimmed = token.trim();
+  if (trimmed.endsWith("%")) {
+    const raw = trimmed.slice(0, -1).trim();
+    if (!CSS_DECIMAL_PATTERN.test(raw)) return void 0;
+    const value2 = Number(raw);
+    return Number.isFinite(value2) ? clamp01(value2 / 100) : void 0;
+  }
+  if (!CSS_DECIMAL_PATTERN.test(trimmed)) return void 0;
+  const value = Number(trimmed);
+  return Number.isFinite(value) ? clamp01(value) : void 0;
+}
+function parseCssHue(token) {
+  const match = /^([+-]?(?:\d+\.?\d*|\.\d+))(deg|grad|rad|turn)?$/i.exec(token.trim());
+  if (match === null) return void 0;
+  const raw = Number(match[1]);
+  if (!Number.isFinite(raw)) return void 0;
+  const unit = (match[2] ?? "deg").toLowerCase();
+  const degrees = unit === "grad" ? raw * 0.9 : unit === "rad" ? raw * 180 / Math.PI : unit === "turn" ? raw * 360 : raw;
+  return (degrees % 360 + 360) % 360;
+}
+function parseCssPercentage(token) {
+  const trimmed = token.trim();
+  if (!trimmed.endsWith("%")) return void 0;
+  const raw = trimmed.slice(0, -1).trim();
+  if (!CSS_DECIMAL_PATTERN.test(raw)) return void 0;
+  const value = Number(raw);
+  return Number.isFinite(value) ? clamp01(value / 100) : void 0;
+}
+function splitCssColorArgs(body) {
+  const source = body.trim();
+  if (source.length === 0) return void 0;
+  if (source.includes(",")) {
+    if (source.includes("/")) return void 0;
+    const parts = source.split(",").map((part) => part.trim());
+    if (parts.length !== 3 && parts.length !== 4) return void 0;
+    if (parts.some((part) => part.length === 0)) return void 0;
+    return {
+      channels: [parts[0], parts[1], parts[2]],
+      ...parts.length === 4 ? { alpha: parts[3] } : {}
+    };
+  }
+  const tokens = source.replaceAll("/", " / ").split(/\s+/);
+  const slash = tokens.indexOf("/");
+  if (slash === -1) {
+    if (tokens.length !== 3) return void 0;
+    return { channels: [tokens[0], tokens[1], tokens[2]] };
+  }
+  if (slash !== 3 || tokens.length !== 5 || tokens[4] === void 0) return void 0;
+  return {
+    channels: [tokens[0], tokens[1], tokens[2]],
+    alpha: tokens[4]
+  };
+}
+function hslToSrgb(hue, saturation, lightness) {
+  const chroma = (1 - Math.abs(2 * lightness - 1)) * saturation;
+  const h = hue / 60;
+  const x = chroma * (1 - Math.abs(h % 2 - 1));
+  const [r1, g1, b1] = h < 1 ? [chroma, x, 0] : h < 2 ? [x, chroma, 0] : h < 3 ? [0, chroma, x] : h < 4 ? [0, x, chroma] : h < 5 ? [x, 0, chroma] : [chroma, 0, x];
+  const m = lightness - chroma / 2;
+  return [r1 + m, g1 + m, b1 + m];
+}
+function cssFallback(out) {
+  out[0] = 0;
+  out[1] = 0;
+  out[2] = 0;
+  out[3] = 1;
+  return out;
+}
+function fromCss(out, css) {
+  if (typeof css !== "string") return cssFallback(out);
+  const source = css.trim().toLowerCase();
+  const named = CSS_NAMED_COLORS[source];
+  if (named !== void 0) return fromHex(out, named);
+  const fullHex = CSS_HEX_PATTERN.exec(source);
+  if (fullHex !== null) {
+    const digits = fullHex[1];
+    if (digits.length === 3 || digits.length === 4) {
+      const expanded = [...digits].map((channel) => `${channel}${channel}`).join("");
+      return fromHex(out, `#${expanded}`);
+    }
+    return fromHex(out, source);
+  }
+  const rgb = CSS_RGB_PATTERN.exec(source);
+  if (rgb !== null) {
+    const args = splitCssColorArgs(rgb[1]);
+    if (args === void 0) return cssFallback(out);
+    const r = parseCssChannel(args.channels[0]);
+    const g = parseCssChannel(args.channels[1]);
+    const b = parseCssChannel(args.channels[2]);
+    const alpha = args.alpha === void 0 ? 1 : parseCssAlpha(args.alpha);
+    if (r === void 0 || g === void 0 || b === void 0 || alpha === void 0)
+      return cssFallback(out);
+    out[0] = srgbChannelToLinear(r);
+    out[1] = srgbChannelToLinear(g);
+    out[2] = srgbChannelToLinear(b);
+    out[3] = alpha;
+    return out;
+  }
+  const hsl = CSS_HSL_PATTERN.exec(source);
+  if (hsl !== null) {
+    const args = splitCssColorArgs(hsl[1]);
+    if (args === void 0) return cssFallback(out);
+    const hue = parseCssHue(args.channels[0]);
+    const saturation = parseCssPercentage(args.channels[1]);
+    const lightness = parseCssPercentage(args.channels[2]);
+    const alpha = args.alpha === void 0 ? 1 : parseCssAlpha(args.alpha);
+    if (hue === void 0 || saturation === void 0 || lightness === void 0 || alpha === void 0)
+      return cssFallback(out);
+    const [r, g, b] = hslToSrgb(hue, saturation, lightness);
+    out[0] = srgbChannelToLinear(r);
+    out[1] = srgbChannelToLinear(g);
+    out[2] = srgbChannelToLinear(b);
+    out[3] = alpha;
+    return out;
+  }
+  return cssFallback(out);
+}
+function toHexByte(v, encodeLinear = true) {
   if (Number.isNaN(v)) return "00";
-  const clamped = Math.max(0, Math.min(1, v));
+  const clamped = Math.max(0, Math.min(1, encodeLinear ? linearChannelToSrgb(v) : v));
   const byte = Math.round(clamped * 255);
   return byte.toString(16).padStart(2, "0");
 }
@@ -554,7 +714,7 @@ function toHex(c) {
   if (aValue >= 1 || Number.isNaN(aValue)) {
     return `#${r}${g}${b}`;
   }
-  const a = toHexByte(aValue);
+  const a = toHexByte(aValue, false);
   return `#${r}${g}${b}${a}`;
 }
 
@@ -2467,7 +2627,7 @@ function perspectiveReverseZ(out, fovYRadians, aspect, near, far) {
   }
   return out;
 }
-function orthographic(out, left, right2, bottom, top, near, far) {
+function orthographic(out, left, right2, top, bottom, near, far) {
   const lr = 1 / (left - right2);
   const bt = 1 / (bottom - top);
   const nf = 1 / (near - far);
@@ -2489,7 +2649,7 @@ function orthographic(out, left, right2, bottom, top, near, far) {
   out[15] = 1;
   return out;
 }
-function orthographicNO(out, left, right2, bottom, top, near, far) {
+function orthographicNO(out, left, right2, top, bottom, near, far) {
   const lr = 1 / (left - right2);
   const bt = 1 / (bottom - top);
   const nf = 1 / (near - far);
@@ -2511,7 +2671,7 @@ function orthographicNO(out, left, right2, bottom, top, near, far) {
   out[15] = 1;
   return out;
 }
-function orthographicReverseZ(out, left, right2, bottom, top, near, far) {
+function orthographicReverseZ(out, left, right2, top, bottom, near, far) {
   const lr = 1 / (left - right2);
   const bt = 1 / (bottom - top);
   const fn = 1 / (far - near);