@planet-matrix/mobius-model 0.5.0 → 0.6.0

package/src/basic/is.ts

@@ -13,81 +13,140 @@ import type {
 
 /**
  * 进行类型检测的常用手段包括：
- *   - typeof: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof
+ *  - typeof: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/typeof
  *             https://tc39.es/ecma262/#sec-typeof-operator
- *   - instanceof: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/instanceof
- *   - toString: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString
+ *  - instanceof: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/instanceof
+ *  - toString: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString
  *
- * - `typeof` operator can operate on non-exist variable.
+ * 检测可能不存在的变量：
+ *  - typeof value === "undefined"
+ *  - globalThis.value === undefined
  */
 
 /**
- *
+ * 判断目标值是否为原始值（primitive）。
  */
 export const isPrimitive = (target: unknown): target is Primitive => {
   return isString(target) || isNumber(target) || isBoolean(target) || isBigInt(target) || isSymbol(target) || isNull(target) || isUndefined(target)
 }
+
+/**
+ * 判断目标值是否为非原始值（non-primitive）。
+ */
 export const isNonPrimitive = (target: unknown): target is NonPrimitive => {
   return isPrimitive(target) === false
 }
+
+/**
+ * 判断目标值是否为字符串。
+ */
 export const isString = (target: unknown): target is string => {
   return Object.prototype.toString.call(target) === "[object String]"
 }
+
+/**
+ * 判断目标值是否为数字。
+ */
 export const isNumber = (target: unknown): target is number => {
   return Object.prototype.toString.call(target) === "[object Number]" && isNaN(Number.parseFloat(String(target)))
 }
+
+/**
+ * 判断目标值是否为 `NaN`。
+ */
 export const isNaN = (target: unknown): boolean => {
   return Number.isNaN(target)
 }
+
+/**
+ * 判断目标值是否为有限数字。
+ */
 export const isFiniteNumber = (target: unknown): target is number => {
   return isNumber(target) && Number.isFinite(target)
 }
+
+/**
+ * 判断目标值是否为无限数字。
+ */
 export const isInfiniteNumber = (target: unknown): target is number => {
   return isNumber(target) && !Number.isFinite(target)
 }
+
+/**
+ * 判断目标值是否为布尔值。
+ */
 export const isBoolean = (target: unknown): target is boolean => {
   return Object.prototype.toString.call(target) === "[object Boolean]"
 }
+
+/**
+ * 判断目标值是否为 `true`。
+ */
 export const isTrue = (target: unknown): target is true => {
   return isBoolean(target) && target === true
 }
+
+/**
+ * 判断目标值是否为 `false`。
+ */
 export const isFalse = (target: unknown): target is false => {
   return isBoolean(target) && target === false
 }
+
+/**
+ * 判断目标值是否为大整数（BigInt）。
+ */
 export const isBigInt = (target: unknown): target is bigint => {
   return Object.prototype.toString.call(target) === "[object BigInt]"
 }
+
+/**
+ * 判断目标值是否为符号（Symbol）。
+ */
 export const isSymbol = (target: unknown): target is symbol => {
   return Object.prototype.toString.call(target) === "[object Symbol]"
 }
+
+/**
+ * 判断目标值是否为 `null`。
+ */
 export const isNull = (target: unknown): target is null => {
   return Object.prototype.toString.call((target)) === "[object Null]"
 }
+
+/**
+ * 判断目标值是否为 `undefined`。
+ */
 export const isUndefined = (target: unknown): target is undefined => {
   return Object.prototype.toString.call(target) === "[object Undefined]"
 }
 /**
+ * 判断目标值是否不是 `undefined`。
+ *
  * @see {@link https://stackoverflow.com/a/52097700}
  */
 export const isDefined = <T>(target: T | undefined): target is T => {
   return isUndefined(target) === false
 }
+
+/**
+ * 判断目标值是否为 `null` 或 `undefined`。
+ */
 export const isNil = (target: unknown): target is (null | undefined) => {
   return target === null || target === undefined
 }
 
 /**
- * Predicate whether the target is an Object, use `instanceof` operator to check.
+ * 使用 `instanceof` 判断目标值是否为对象。
  *
  * @see {@link isGeneralObject}, {@link isPlainObject}
  */
 // oxlint-disable-next-line no-wrapper-object-types
 export const isObject = (target: unknown): target is Object => {
-  // oxlint-disable-next-line no-instanceof-builtins
   return target instanceof Object
 }
 /**
- * Predicate whether the target is a general object, use `typeof` operator to check.
+ * 使用 `typeof` 判断目标值是否为广义对象。
  *
  * A general object is an object that is:
  *  - not `null`, not a `function`, not a `primitive`.
@@ -97,17 +156,12 @@ export const isObject = (target: unknown): target is Object => {
  *
  * @example
  * ```
- * typeof null // => 'object'
- * typeof [] // => 'object'
- * typeof {} // => 'object'
- * typeof { a: 1 } // => 'object'
- * typeof (new Map()) // => 'object'
- * typeof (new WeakMap()) // => 'object'
- * typeof (new Set()) // => 'object'
- * typeof (new WeakSet()) // => 'object'
- * typeof (new Date()) // => 'object'
- * typeof window // => 'object'
- * typeof document // => 'object'
+ * // Expect: true
+ * const example1 = isGeneralObject([])
+ * // Expect: true
+ * const example2 = isGeneralObject(new Map())
+ * // Expect: false
+ * const example3 = isGeneralObject(null)
  * ```
  *
  * @see {@link isObject}, {@link isPlainObject}
@@ -141,88 +195,151 @@ export const isPlainObject = (target: unknown): target is PlainObject => {
   const proto = Object.getPrototypeOf(target)
   return proto === Object.prototype || proto === null
 }
+
+/**
+ * 判断目标值是否为空普通对象。
+ */
 export const isEmptyPlainObject = (target: unknown): target is PlainObject => {
   return isPlainObject(target) && Reflect.ownKeys(target).length === 0
 }
 
+/**
+ * 判断目标值是否为数组。
+ */
 export function isArray<T>(target: T[]): target is T[]
 export function isArray<T>(target: unknown): target is T[]
 export function isArray<T>(target: unknown): target is T[] {
   return Array.isArray(target)
 }
+
+/**
+ * 判断目标值是否为空数组。
+ */
 export const isEmptyArray = (target: unknown): target is [] => {
   return isArray(target) && target.length === 0
 }
 
+/**
+ * 判断目标值是否为类数组对象（array-like）。
+ */
 export function isArrayLike<T>(target: ArrayLike<T>): target is ArrayLike<T>
 export function isArrayLike<T>(target: unknown): target is ArrayLike<T>
 export function isArrayLike<T>(target: unknown): target is ArrayLike<T> {
   return isGeneralObject(target) && ("length" in target) && isNumber(target.length)
 }
 
+/**
+ * 判断目标值是否为 `Map`。
+ */
 export function isMap<K, V>(target: Map<K, V>): target is Map<K, V>
 export function isMap<K, V>(target: unknown): target is Map<K, V>
 export function isMap<K, V>(target: unknown): target is Map<K, V> {
   return Object.prototype.toString.call(target) === "[object Map]"
 }
 
+/**
+ * 判断目标值是否为 `WeakMap`。
+ */
 export function isWeakMap<K extends object, V>(target: WeakMap<K, V>): target is WeakMap<K, V>
 export function isWeakMap<K extends object, V>(target: unknown): target is WeakMap<K, V>
 export function isWeakMap<K extends object, V>(target: unknown): target is WeakMap<K, V> {
   return Object.prototype.toString.call(target) === "[object WeakMap]"
 }
 
+/**
+ * 判断目标值是否为 `Set`。
+ */
 export function isSet<T>(target: Set<T>): target is Set<T>
 export function isSet<T>(target: unknown): target is Set<T>
 export function isSet<T>(target: unknown): target is Set<T> {
   return Object.prototype.toString.call(target) === "[object Set]"
 }
 
+/**
+ * 判断目标值是否为 `WeakSet`。
+ */
 export function isWeakSet<T extends object>(target: WeakSet<T>): target is WeakSet<T>
 export function isWeakSet<T extends object>(target: unknown): target is WeakSet<T>
 export function isWeakSet<T extends object>(target: unknown): target is WeakSet<T> {
   return Object.prototype.toString.call(target) === "[object WeakSet]"
 }
 
+/**
+ * 判断目标值是否为 `Date`。
+ */
 export const isDate = (target: unknown): target is Date => {
   return Object.prototype.toString.call(target) === "[object Date]"
 }
 
+/**
+ * 判断目标值是否为 `RegExp`。
+ */
 export const isRegExp = (target: unknown): target is RegExp => {
   return Object.prototype.toString.call(target) === "[object RegExp]"
 }
 
+/**
+ * 判断目标值是否为 `Error`。
+ */
 export const isError = (target: unknown): target is Error => {
   return Object.prototype.toString.call(target) === "[object Error]"
 }
 
+/**
+ * 判断目标值是否为 `Promise`。
+ */
 export function isPromise<T>(target: Promise<T>): target is Promise<T>
 export function isPromise<T>(target: unknown): target is Promise<T>
 export function isPromise<T>(target: unknown): target is Promise<T> {
   return Object.prototype.toString.call(target) === "[object Promise]"
 }
 
+/**
+ * 判断目标值是否为任意函数。
+*/
 // oxlint-disable-next-line no-unsafe-function-type
 export const isFunction = (target: unknown): target is Function => {
   return typeof target === "function"
 }
+
+/**
+ * 判断目标值是否为任意同步或异步函数类型。
+ */
 export const isAnyFunction = (target: unknown): target is AnyFunction => {
   return isFunction(target)
 }
+
+/**
+ * 判断目标值是否为同步函数。
+ */
 export const isSyncFunction = (target: unknown): target is AnySyncFunction => {
   return Object.prototype.toString.call(target) === "[object Function]"
 }
+
+/**
+ * 判断目标值是否为异步函数。
+ */
 export const isAsyncFunction = (target: unknown): target is AnyAsyncFunction => {
   return Object.prototype.toString.call(target) === "[object AsyncFunction]"
 }
+
+/**
+ * 判断目标值是否为生成器函数。
+ */
 export const isGeneratorFunction = (target: unknown): target is AnyGeneratorFunction => {
   return Object.prototype.toString.call((target)) === "[object GeneratorFunction]"
 }
+
+/**
+ * 判断目标值是否为异步生成器函数。
+ */
 export const isAsyncGeneratorFunction = (target: unknown): target is AnyAsyncGeneratorFunction => {
   return Object.prototype.toString.call(target) === "[object AsyncGeneratorFunction]"
 }
 
 /**
+ * 判断目标值是否实现可迭代协议（iterable protocol）。
+ *
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol}
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/iterator}
  */
@@ -233,6 +350,8 @@ export function isIterable<T>(target: unknown): target is Iterable<T> {
   return isGeneralObject(target) && typeof (target as any)[Symbol.iterator] === "function"
 }
 /**
+ * 判断目标值是否实现异步可迭代协议。
+ *
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/asyncIterator}
  */
 export function isAsyncIterable<T>(target: AsyncIterable<T>): target is AsyncIterable<T>
@@ -242,6 +361,8 @@ export function isAsyncIterable<T>(target: unknown): target is AsyncIterable<T>
   return isGeneralObject(target) && typeof (target as any)[Symbol.asyncIterator] === "function"
 }
 /**
+ * 判断目标值是否实现迭代器协议（iterator protocol）。
+ *
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol}
  */
 export function isIterator<T, TReturn = unknown, TNext = undefined>(target: Iterator<T, TReturn, TNext>): target is Iterator<T, TReturn, TNext>
@@ -250,71 +371,31 @@ export function isIterator<T, TReturn = unknown, TNext = undefined>(target: unkn
   // oxlint-disable-next-line no-unsafe-type-assertion no-unsafe-member-access
   return isGeneralObject(target) && typeof (target as any).next === "function"
 }
+
+/**
+ * 判断目标值是否实现异步迭代器协议。
+ */
 export function isAsyncIterator<T, TReturn = unknown, TNext = undefined>(target: AsyncIterator<T, TReturn, TNext>): target is AsyncIterator<T, TReturn, TNext>
 export function isAsyncIterator<T, TReturn = unknown, TNext = undefined>(target: unknown): target is AsyncIterator<T, TReturn, TNext>
 export function isAsyncIterator<T, TReturn = unknown, TNext = undefined>(target: unknown): target is AsyncIterator<T, TReturn, TNext> {
   // oxlint-disable-next-line no-unsafe-type-assertion no-unsafe-member-access
   return isGeneralObject(target) && typeof (target as any).next === "function"
 }
+
+/**
+ * 判断目标值是否同时满足可迭代对象与迭代器的条件。
+ */
 export function isIterableIterator<T, TReturn = unknown, TNext = undefined>(target: IterableIterator<T>): target is IterableIterator<T, TReturn, TNext>
 export function isIterableIterator<T, TReturn = unknown, TNext = undefined>(target: unknown): target is IterableIterator<T, TReturn, TNext>
 export function isIterableIterator<T, TReturn = unknown, TNext = undefined>(target: unknown): target is IterableIterator<T> {
   return isIterator<T, TReturn, TNext>(target) && isIterable<T>(target)
 }
+
+/**
+ * 判断目标值是否同时满足异步可迭代对象与异步迭代器的条件。
+ */
 export function isAsyncIterableIterator<T, TReturn = unknown, TNext = undefined>(target: AsyncIterableIterator<T>): target is AsyncIterableIterator<T, TReturn, TNext>
 export function isAsyncIterableIterator<T, TReturn = unknown, TNext = undefined>(target: unknown): target is AsyncIterableIterator<T, TReturn, TNext>
 export function isAsyncIterableIterator<T, TReturn = unknown, TNext = undefined>(target: unknown): target is AsyncIterableIterator<T> {
   return isAsyncIterator<T, TReturn, TNext>(target) && isAsyncIterable<T>(target)
 }
-
-/**
- * Check `target` and `Window` is both defined
- * before use the `instanceof` operator to check `target` is instanceof `Window`.
- */
-export const isWindow = (target: unknown): target is Window => {
-  return isGeneralObject(target) && isDefined(Window) && target instanceof Window
-}
-/**
- * Check `target` and `Element` is both defined
- * before use the `instanceof` operator to check `target` is instanceof `Element`.
- */
-export const isElement = (target: unknown): target is Element => {
-  return isGeneralObject(target) && isDefined(Element) && target instanceof Element
-}
-/**
- * Check `target` and `Node` is both defined
- * before use the `instanceof` operator to check `target` is instanceof `Node`.
- */
-export const isNode = (target: unknown): target is Node => {
-  return isGeneralObject(target) && isDefined(Node) && target instanceof Node
-}
-/**
- * Check `target` and `HTMLElement` is both defined
- * before use the `instanceof` operator to check `target` is instanceof `HTMLElement`.
- */
-export const isHTMLElement = (target: unknown): target is HTMLElement => {
-  return isGeneralObject(target) && isDefined(HTMLElement) && target instanceof HTMLElement
-}
-/**
- * Check `target` and `HTMLCollection` is both defined
- * before use the `instanceof` operator to check `target` is instanceof `HTMLCollection`.
- */
-export const isHTMLCollection = (target: unknown): target is HTMLCollection => {
-  return isGeneralObject(target) && isDefined(HTMLCollection) && target instanceof HTMLCollection
-}
-/**
- * Check `target` and `Document` is both defined
- * before use the `instanceof` operator to check `target` is instanceof `Document`.
- */
-export const isDocument = (target: unknown): target is Document => {
-  return isGeneralObject(target) && isDefined(Document) && target instanceof Document
-}
-/**
- * Check `target` and `EventTarget` is both defined
- * before use the `instanceof` operator to check `target` is instanceof `EventTarget`.
- *
- * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/API/Event}
- */
-export const isEventTarget = (target: unknown): target is EventTarget => {
-  return isGeneralObject(target) && isDefined(EventTarget) && target instanceof EventTarget
-}

package/src/basic/promise.ts

@@ -56,32 +56,43 @@ export const promiseFinally = async <V>(
 }
 
 const INTERNAL_PROMISE_FAIL_RESULT_TYPE: symbol = Symbol("fail")
+
+/**
+ * 表示标准化的 Promise 失败结果。
+ */
 export interface PromiseFailResult {
   __type__: typeof INTERNAL_PROMISE_FAIL_RESULT_TYPE
   reason: unknown
 }
+
+/**
+ * 表示带原始下标信息的 Promise 失败结果。
+ */
 export interface PromiseIndexedFailResult extends PromiseFailResult {
   index: number
 }
+
+/**
+ * 根据拒因构造标准化的 Promise 失败结果。
+ */
 export const promiseConstructFailResult = (reason: unknown): PromiseFailResult => {
   return { __type__: INTERNAL_PROMISE_FAIL_RESULT_TYPE, reason }
 }
 /**
- * Predicate whether the target is a promise fail result.
+ * 判断目标值是否为标准化的 Promise 失败结果。
  */
 export const isPromiseFailResult = (target: unknown): target is PromiseFailResult => {
   return isPlainObject(target) && target["__type__"] === INTERNAL_PROMISE_FAIL_RESULT_TYPE
 }
 /**
- * Designed to use as `onrejected` callback of `Promise.catch`
- * to return a standard `PromiseFailResult`.
+ * 用作 `Promise.catch` 的 `onrejected` 回调，并返回标准化失败结果。
  */
 export const promiseCatchToFailResult = (reason: unknown): PromiseFailResult => {
   return { __type__: INTERNAL_PROMISE_FAIL_RESULT_TYPE, reason }
 }
 
 /**
- * Giving an array, filter non-`PromiseFailResult` items.
+ * 从结果数组中过滤出非 `PromiseFailResult` 项。
  */
 export const promiseFilterSuccessResults = <V>(
   results: Array<V | PromiseFailResult>,
@@ -93,8 +104,7 @@ export const promiseFilterSuccessResults = <V>(
   return filtered as V[]
 }
 /**
- * Giving a array, filter `PromiseFailResult` items, with extra `index` property
- * which indicate the index of the item in the original array.
+ * 从结果数组中过滤出失败项，并补充其原始下标。
  */
 export const promiseFilterFailResults = <V>(
   results: Array<V | PromiseFailResult>,
@@ -125,8 +135,12 @@ type PromiseQueueFirstPromiseMaker<T, S = unknown> = (context: PromiseQueueFirst
 type PromiseQueueRestPromiseMaker<T, S = unknown> = (context: PromiseQueueRestPromiseMakerContext<T, S>) => Promise<T>
 type PromiseQueuePromiseMakers<T, S = unknown> = [
   PromiseQueueFirstPromiseMaker<T, S>,
-  ...PromiseQueueRestPromiseMaker<T, S>[]
+  ...Array<PromiseQueueRestPromiseMaker<T, S>>
 ]
+
+/**
+ * `promiseQueue` 的配置项。
+ */
 export interface PromiseQueueOptions {
   /**
    * @default 0
@@ -204,6 +218,10 @@ interface PromiseRetryRestPromiseMakerContext<T, S = unknown> {
 type PromiseRetryPromiseMaker<T, S = unknown> = (
   context: PromiseRetryFirstPromiseMakerContext<S> | PromiseRetryRestPromiseMakerContext<T, S>
 ) => Promise<T>
+
+/**
+ * `promiseRetryWhile` 与 `promiseRetryUntil` 的配置项。
+ */
 export interface PromiseRetryOptions {
   /**
    * @default 0
@@ -387,6 +405,10 @@ interface PromiseForeverRestPromiseMakerContext<T, S = unknown> {
 type PromiseForeverPromiseMaker<T, S = unknown> = (
   context: PromiseForeverFirstPromiseMakerContext<S> | PromiseForeverRestPromiseMakerContext<T, S>
 ) => Promise<T>
+
+/**
+ * `promiseForever` 的配置项。
+ */
 export interface PromiseForeverOptions {
   /**
    * @default 0
@@ -441,7 +463,6 @@ export const promiseForever = <T, S = unknown>(
     context: PromiseForeverFirstPromiseMakerContext<S> | PromiseForeverRestPromiseMakerContext<T, S>
   ): void => {
     void promiseMaker(context)
-      // oxlint-disable-next-line prefer-await-to-callbacks
       .catch((error: unknown) => {
         const failedResult = promiseCatchToFailResult(error)
         if (onRejected !== undefined) {

package/src/basic/string.ts

@@ -1,34 +1,3 @@
-const internalRandomPacket: Record<number, string[]> = {}
-/**
- * Generate a random string with a fixed length and optional character set.
- *
- * @example
- * ```
- * // Expect: 8
- * const example1 = stringRandom(8).length
- * // Expect: true
- * const example2 = stringRandom(4, "ab").split("").every(char => char === "a" || char === "b")
- * ```
- */
-export const stringRandom = (length: number, chars?: string | undefined): string => {
-  let result = ""
-  const preparedChars = chars ?? "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
-
-  Array.from({ length }).forEach(() => {
-    result = result + preparedChars[Math.floor(Math.random() * preparedChars.length)]!
-  })
-
-  internalRandomPacket[length] = internalRandomPacket[length] ?? []
-  const packet = internalRandomPacket[length]
-  if (packet.includes(result)) {
-    return stringRandom(length, preparedChars)
-  }
-  else {
-    packet.push(result)
-    return result
-  }
-}
-
 /**
  * Convert a camelCase string into kebab-case.
  *
@@ -177,8 +146,8 @@ export const stringSliceByUnits = (text: string, start: number, end: number): st
 
 export interface StringSplitOptions {
   input: string
-  chunkSize: number
-  chunkOverlap: number
+  chunkSize?: number | undefined
+  chunkOverlap?: number | undefined
 }
 
 /**

package/src/color/README.md

@@ -0,0 +1,105 @@
+# Color
+
+## Description
+
+Color 模块提供围绕颜色值（color value）的构造、转换、解析、序列化、分析与派生能力，用于在明确颜色空间拓扑之上建立稳定、可解释且可扩展的公共颜色语义。
+
+这个模块不把某一种显示层颜色表示当作事实核心，而是以 `XYZ` 作为唯一绝对参考层，再从 `XYZ` 发散出不同颜色空间支线。当前已稳定落地的是 `RGB` 支线，其中 `Linear RGB` 是计算核心，`sRGB` 是显示与字符串语义层，`HSL` 与 `HSV` 是交互语义层。
+
+## For Understanding
+
+理解 Color 模块时，最重要的不是记住有哪些颜色函数，而是先接受它的颜色空间拓扑。这个模块要解决的问题不是“让任意颜色表示之间都能方便互转”，而是“让颜色值沿着清楚、合法、长期稳定的路径被构造、移动和分析”。
+
+当前拓扑的核心结论如下：
+
+- `XYZ` 是唯一绝对核心，不需要额外加 `CIE` 前缀来区分语义。
+- `RGB` 是从 `XYZ` 发散出去的一条独立支线。
+- `Linear RGB` 是 `RGB` 支线的计算核心。
+- `sRGB` 是显示层与字符串层的核心表示。
+- `HSL` 与 `HSV` 是从 `sRGB` 派生出的交互层表示。
+
+在当前阶段，合法主链应被理解为：
+
+- `XYZ <-> Linear RGB`
+- `Linear RGB <-> sRGB`
+- `sRGB <-> HSL`
+- `sRGB <-> HSV`
+
+这套拓扑不是实现细节，而是模块语义的一部分。它意味着不应把跨级捷径视为独立公共能力，也不应为了方便而让解析、序列化、分析或派生偷偷依赖未声明的跨级路径。未来如果扩展 `Lab` 等其它支线，也必须继续直接从 `XYZ` 出发，而不是附着在现有 `RGB` 支线上。
+
+## For Using
+
+当应用需要围绕颜色值本身工作，并且希望这些工作建立在明确颜色空间语义之上时，可以使用这个模块，而不是在业务代码里混合使用一批语义不清的颜色工具。
+
+当前公共能力大致可以按以下几类理解：
+
+- 颜色值类型与构造：用于显式创建 `XYZ`、`Linear RGB`、`sRGB`、`HSL`、`HSV` 这些不同层级的颜色值。
+- 合法颜色转换：用于沿着颜色空间树的合法边移动，例如 `XYZ` 与 `Linear RGB` 之间，或 `sRGB` 与 `HSL`、`HSV` 之间。
+- 字符串解析与序列化：用于在十六进制颜色、`rgb(...)`、`rgba(...)`、`hsl(...)`、`hsla(...)`、`hsv(...)`、`hsva(...)` 等外部格式与其对应颜色值之间转换。
+- 颜色分析：用于相对亮度、三刺激总量、`xy` 色度坐标、对比度、可读文本颜色选择等分析场景。
+- 颜色派生：用于线性混色、透明度合成、fade、tint、shade、tone、lighten、darken 等建立在清楚层级上的稳定派生。
+- 显示层归一化特例：如果你的目标就是把多种颜色字符串归一化为最终显示层颜色，可以使用专门返回 `sRGB` 的入口；这种入口属于有意接受语义折叠的特例，而不是默认解析原则。
+
+这个模块不适合承载主题系统、设计令牌（design token）管理、品牌配色规则、组件语义色映射或其它与具体产品设计体系强耦合的内容。这些能力应建立在 Color 之上，而不是写入 Color 本身。
+
+## For Contributing
+
+贡献 Color 模块时，首要任务不是添加一个“颜色工具”，而是判断该能力在颜色空间树上的位置是否清楚、依赖哪条合法路径、以及它是否值得成为长期公共承诺。只要这三个问题里有一个回答不清，它通常就还不适合进入这个模块。
+
+在扩展时，应优先遵守以下边界：
+
+- `XYZ` 是唯一绝对核心，不需要再引入其它并列的绝对参考层。
+- 任何新能力都应能在颜色空间树上找到清楚位置，而不是以便捷函数的形式漂浮在树外。
+- 不要把跨级转换捷径公开成独立 API，即使它内部只是串联了多步合法转换。
+- 解析、序列化、分析与派生也必须服从颜色空间拓扑，而不是只对转换函数保持克制。
+- 当前稳定承诺的是 `XYZ` 核心层与 `RGB` 支线；未来方向可以说明，但不能在文档和导出层面写成既有事实。
+
+### JSDoc 注释格式要求
+
+- 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。
+- JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。
+- 如果描述后还有其他内容，应在描述后加一个空行。
+- 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。
+- 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。
+- 如果有示例，应使用注释格式说明每个场景：`// Expect: <result>`。
+- 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。
+- 如果有示例，`// Expect: <result>` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。
+- 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。
+- 如果函数返回结构化字符串，应展示其预期格式特征。
+- 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。
+
+### 实现规范要求
+
+- 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。
+- 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。
+- 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。
+- 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。
+- 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。
+- 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。
+- 辅助元素永远不要公开导出。
+- 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/color/internal.ts`。
+- 模块内可以包含子模块。Color 已经具有 `xyz` 与 `rgb` 这类稳定子问题域，后续扩展也应继续沿语义分层组织。
+- 子模块包含多个文件时，应该为其单独创建子文件夹，并为其创建单独的 Barrel 文件；父模块的 Barrel 文件再重导出子模块的 Barrel 文件。
+- 子模块不需要有自己的 `README.md`。
+- 子模块可以有自己的 `internal.ts` 文件，多个子模块共享的辅助元素应该放在父模块的 `internal.ts` 文件中，单个子模块共享的辅助元素应该放在该子模块的 `internal.ts` 文件中。
+- 对模块依赖关系的要求（通常是不循环依赖或不反向依赖）与对 DRY 的要求可能产生冲突。此时，若复用的代码数量不大，可以适当牺牲 DRY，复制粘贴并保留必要的注释说明；若复用的代码数量较大，则可以将其抽象到新的文件或子模块中，如 `common.ts`，并在需要的地方导入使用。
+- 所有转换、解析、序列化、分析与派生实现都应服从颜色空间树，不允许通过跨级公式或包装函数引入语义捷径。
+
+### 导出策略要求
+
+- 保持内部辅助项和内部符号为私有，不要让外部接入依赖临时性的内部结构。
+- 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。
+- Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。
+- 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的颜色语义，而不是某段实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。
+
+### 测试要求
+
+- 若程序元素是函数，则只为该函数编写一个测试，如果该函数需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，则至少要为该类的每一个方法编写一个测试，如果该方法需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，除了为该类的每一个方法编写至少一个测试之外，还可以为该类编写任意多个测试，以覆盖该类的不同使用场景或边界情况。
+- 若编写测试时需要用到辅助元素（Mock 或 Spy 等），可以在测试文件中直接定义这些辅助元素。若辅助元素较为简单，则可以直接放在每一个测试内部，优先保证每个测试的独立性，而不是追求极致 DRY；若辅助元素较为复杂或需要在多个测试中复用，则可以放在测试文件顶部，供该测试文件中的所有测试使用。
+- 测试顺序应与源文件中被测试目标的原始顺序保持一致。
+- 若该模块不需要测试，必须在说明文件中明确说明该模块不需要测试，并说明理由。一般来说，只有在该模块没有可执行的公共函数、只承载类型层表达，或其语义已被上层模块的测试完整覆盖且重复测试几乎不再带来额外价值时，才适合这样处理。
+- 模块的单元测试文件目录是 `./tests/unit/color`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/color/<sub-module-name>`。
+- 对颜色转换，应重点验证每一条合法边本身，而不是依赖跨级捷径拼结果。
+- 对颜色解析、序列化、分析与派生，应重点验证它们所依赖的颜色层级是否明确，以及结果是否稳定、可解释。